Description
The
INT1 DataPort is an AccessServer port type that supports multiplexing of
numerous host connections to one user program connection.
The
user program connection is via TCP/IP, known as a Client connection, Data
messages sent over the Client connection are in Uniscope data format with a
header that identifies the individual multiplexed user connection.
The
job of the INT1 DataPort is to create and manage a full INT1 session over TCP/IP
to the 2200/Clearpath host system for each of the multiplexed connections.
For a list of error codes see the faq page.
Operation
The
graphical interface is used to display configured information and the real time
status of running objects. When
running the AccessServer as a service this visual information is not available
but can be viewed with the QMC management console program.
The
user interface is principally point and click.
You can add new configurable items, such as ports and hosts, and stop and
start running entities. You can
delete configured items and dynamically created items, such as Clients and
users.
To
redisplay current information, click on the refresh button on the toolbar.
Each INT1 DataPort is a listening port has one or more destination hosts.
A listening port is configured to accept connections from user programs and
then process messages sent over the tcp connection.
Each user program connection is referred to as a Client.
Each message level connection is referred to as a user.
Therefore we can have many user connections over each Client connection.
Add
To
add an item, select the parent, such as INT1 DataPorts and click on the Add
button on the toolbar or use a right mouse click to display a popup menu with
the add command.
Delete
To
delete an item select the item, such as port, and click on the Delete button on
the toolbar or use a right mouse click to display a popup menu with the delete
command. Note that you can delete
dynamic items such as a client or a user. Deleting
any item also deletes all child
items, both configured and dynamic. For
example, deleting a port deletes all hosts, all clients and all users, deleting
a client deletes all child users.
Stop
and Start
Stopping
a Port simply stops it from listening for new connections.
It does not stop any messages on existing client/user connections.
Stopping
a Client prevents messages from all
users of that client being processed, but any messages received from the host
will still be sent back to the client. Starting
a Client allows messages from the client’s users to be processed.
Stopping
a User discards all messages received
from the particular client and sends a reject back to the client for each
message. Messages from the host will
still be sent back to the user. The
reason that the input is discarded is that a message has to be read before it
can be decided which user sent the message, only then can it be determined that
the user has been stopped.
Message
Counts
Message counts are
displayed for users, clients and ports. The
counts are held as 32 bit integers so they can get very large but, at some time,
they will wrap around to zero. Therefore,
there may be some apparent disparity between input and output message counts.
The port status also displays message
rates, as messages per second. The
calculations are performed over the interval between clicking the refresh
button.
Message
Level Interface
Description
The
message level interface describes a message format that is used to pass all
messages to and from the dataport client. Each
message comprises a buffer header and data area, both of which are contiguous.
See the FAQ page on the Quickware web site (www.qw.com)
for definitions of error codes.
Buffer
Header
The
buffer header is a fixed length, fixed format header that is at the beginning of
each message. The function
descriptions show only the required buffer header fields for each function.
Other fields may be filled in for debug/trace purposes but are not used
by the interface. For example, the
m_user1 and m_user2 fields could be filled in for each data message to assist in
tracing.
The
identifier fields are very important:
·
m_connectionID
·
m_user1
·
m_user2
These fields are used to identify the connection in both directions, from the
client to QAS and from QAS to the client.
The
client provides the m_user1 and m_user2 identifiers in the connect packet when
instigating a user connection. These
values are remembered by the data port and returned on every subsequent message
for that user.
Similarly,
the m_connectionId is returned from the data port in the buffer header in a
connect confirm message. The client
should use this value in every subsequent message for that user.
Field |
Type |
Description |
m_link
|
int
|
Used internally in queuing operations
|
m_function
|
byte
|
Function code (see Commands and Responses)
|
m_control
|
byte
|
Sub information for selected functions
|
m_info
|
word
|
Sub information for selected functions
|
m_connectionId
|
int
|
Connection id, as returned on fncConConf
|
m_user1
|
int
|
User information
|
m_user2
|
int
|
User information
|
m_result
|
word
|
Result code
|
m_result2
|
word
|
Extended result
|
m_holdFlags
|
byte
|
Private flags
|
m_userFlags
|
byte
|
Flags
|
m_offset
|
word
|
Offset to data, from start of header
|
m_size
|
word
|
Size of data, in bytes
|
m_flags
|
word
|
Private flags
|
Data….
|
Note: int=32
bits, word=16 bits, byte=8 bits. All
non-byte fields are big-endian except for m_link and m_flags.
Function Descriptions (commands)
Command |
m_function |
Description |
fncConnectStr
|
22 |
Connect to host, with parameters in a string
|
fncDiscAbort
|
19 |
Disconnect from host, no acknowledgment required
|
fncDisconnect
|
06 |
Disconnect from host
|
fncParams |
12 |
Send list of parameters |
fncRegister |
14 |
Register client with ‘host’ name |
fncSend
|
08 |
Send data
|
fncSendFKey
|
1E |
Send
function key to host
|
fncSendMsgWait
|
1F |
Send
MsgWait to host
|
fncStatus
|
03 |
Completion status
|
|
|
|
fncTraceOn |
60 |
Turn on tracing of all connections |
fncTraceOff |
61 |
Turn off tracing of all connections |
fncTraceConnectionOn |
62 |
Turn on tracing of a specific connection |
fncTraceConnectionOff |
63 |
Turn off tracing of a specific connection |
fncLoggingOn |
64 |
Turn on general logging |
fncLoggingOff |
65 |
Turn off general logging |
fncLoggingFolder |
66 |
Set the path of the logging files folder |
Function:
fncConnectStr
Description:
Request connect to the host. The host and terminal details are
provided in a null-terminated connect request string which begins at the
data offset. The following connect flags are defined:
- If the
BF_SENT_WANTED flag is true then a fncSentmessage
will be returned for every message sent to the host.
- If the BF_TRANSPARENT flag is true then the text content
received from the host is forwarded without any extra internal processing.
- If the BF_NO_STX_ETX flag is true then the data part of the message will not be
bracketed by stx/etx bytes.
- If the BF_IGNORE_DC2 flag is true then print invocation
indicated by DC2 characters will be ignored.
- If the BF_STRIP_NULLS flag is true then null characters
(binary zero) will be stripped from the data. Note that
this flag can be used in conjunction with BF_TRANSPARENT so that
all data will be passed transparently except that nulls will be
stripped.
If the terminal name is already in use on a socket then the connect request will
be rejected with an erDuplicate error and the current socket for that terminal
name will be closed.
The host may be specified by name only, in which case the configured host list
will be searched for a match. Otherwise,
host details are passed in the string, and the first 5 host parameters must all
be provided.
A relative terminal number may be provided in the m_info field.
If a non-zero value is passed then it is assumed to be a consistent
terminal number for the connecting terminal.
This number is then used to form a local tcp port number.
If zero, then a dynamically assigned tcp local port number is used.
The benefit of setting the relative terminal number is that the AccessServer
will always attempt to use the same source tcp port number for that
terminal. Then, if there is a network problem and a reconnect is required,
the host can recognize a new request from the same device.
Buffer
Header:
m_function
|
fncConnectStr
|
m_info
|
Relative
terminal number
|
m_user1
|
User
info (returned in responses)
|
m_user2
|
User
info (returned in responses)
|
m_userFlags
|
0x01
|
BF_SENT_WANTED
|
|
0x02
|
BF_TRANSPARENT
|
|
0x04
|
BF_NO_STX_ETX
|
|
0x08
|
BF_IGNORE_DC2
|
|
0x10
|
BF_STRIP_NULLS
|
m_offset
|
Offset
to data (connection string)
|
m_size
|
Data
size
|
Connect
String:
termName,termType,rows,cols,hostname[,appName,IPadr,port,transport,csuName[,conTimeout,localIPadr]]
e.g.
TERM01,4,24,80,ResHost
TERM02,0,0,0,ResHost
TERM03,0,0,0,ResHost,TIP,1.2.3.4,102,T,tipcsu,30,1.2.3.4
termName
|
Up to 8 byte
terminal name
|
termType
|
termU20
= 0 termU40
= 1 termU200
= 2 termU300
= 3 termU60
= 4
|
rows
|
Number of screen
rows (0-default)
|
cols
|
Number of screen
columns (0=default)
|
hostName
|
Host name;
details are looked up in internal configuration if the following fields
are not provided.
|
appName
|
Up to 8 byte
application name
|
IPadr
|
IP address in
dot notation or as a domain name
|
port
|
TCP port number
|
transport
|
‘T’ for TCP
end-to-end or ‘D’ for the TCP-to-DTP session relay
|
csuName
|
Up to 8 byte csu
name
|
conTimeout
|
Connection
timeout in seconds (default=30)
|
localIPadr |
Local IP address in
dot notation or as a domain name; only specify this parameter if you have
a multi-homed server and need to bind to a specific local IP address
|
Function:
fncDiscAbort
Description:
Disconnect but do not return a disconnect confirm
Buffer
Header:
m_function
|
fncDiscAbort |
m_connectionId
|
Connection id
|
Function:
fncDisconnect
Description:
Disconnect and return a disconnect confirm.
Buffer Header:
m_function
|
fncDisconnect |
m_connectionId
|
Connection
id
|
Function: fncParams
Description: A message
sent from the client to specify global parameter settings.
Buffer Header:
m_function |
fncParams |
m_offset |
Offset to data (parameter string) |
m_size |
Data size |
Parameter String:
String of
parameter values separated by commas
Parameter List
Signature checking
|
Non-zero to check
signature in messages from client |
Function:
fncRegister
Description:
A message sent from the client to
register the associated application name. The message payload contains a
string that identifies the registered client name which is subsequently used
to match the host application on a connect request.
Buffer Header:
m_function |
fncRegister |
m_offset |
Offset to data (registration string) |
m_size |
Data size |
Connect String:
appName
e.g.ResHost
Function:
fncSend
Description:
Send a data message to the host.
Buffer
Header:
m_function
|
fncSend |
m_connectionId
|
Connection id
|
m_offset
|
Offset to data
|
m_size
|
Data size
|
Function:
fncSendFKey
Description:
Send a function key to the host.
Buffer Header:
m_function
|
fncSendFKey |
m_connectionId
|
Connection
id
|
m_info
|
1
to 22 for function keys F1 to F22
|
Function:
fncSendMsgWait
Description:
Send MessageWait to the host.
Buffer Header:
m_function
|
fncSendMsgWait |
m_connectionId
|
Connection
id
|
Function:
fncStatus
Description:
Provides completion status for the last message, which required
acknowledgment, either because it contained a print invocation or the host
required an Assurance Unit. If the
status indicates an error condition an Assurance Unit is outstanding then an
Assurance Unit Fail is sent to the host, else a device status is sent, if the
host has indicated that it wants to receive device status messages.
Buffer Header:
m_function
|
fncStatus |
m_connectionId
|
Connection
id
|
m_info
|
00
|
OK
(same as DEVICE_STATUS_READY)
|
02
|
DEVICE_STATUS_NOT_CONFIGURED
|
03
|
DEVICE_STATUS_NOT_AVAILABLE
|
04
|
DEVICE_STATUS_NO_MEDIA
|
05
|
DEVICE_STATUS_READY
|
06
|
DEVICE_STATUS_INPUT_DATA_ERROR
|
07
|
DEVICE_STATUS_OUPUT_ERROR
|
08
|
DEVICE_STATUS_END_OF_MEDIA
|
09
|
DEVICE_STATUS_DEVICE_DOWN
|
0a
|
DEVICE_STATUS_OUTPUT_ERROR_CLEAR
|
0b
|
DEVICE_STATUS_POC
|
Function:
fncTraceOn
Description: Request to turn on tracing of input/output messages, for
all connections.
Buffer
Header:
Function:
fncTraceOff
Description: Turn off tracing, for all
connections.
Buffer Header:
Function:
fncTraceConnectionOn
Description: Turn on tracing of a specific
connection
Buffer Header:
m_function |
fncTraceConnectionOn |
m_connectionId |
Connection id |
Function:
fncTraceConnectionOff
Description: Turn off tracing of a specific
connection
Buffer Header:
m_function |
fncTraceConnectionOff |
m_connectionId |
Connection id |
Function:
fncLoggingOn
Description: Turn on logging
Buffer Header:
Function:
fncLoggingOff
Description: Turn off logging
Buffer Header:
Function:
fncLoggingFolder
Description: Set the
path to the folder to be used for log files, provided in a null-terminated
string beginning at the data offset.
Buffer Header:
m_function |
fncLoggingFolder |
m_offset |
Offset to data (folder path) |
Function
Descriptions (responses)
fncConnect |
05 |
Connect request |
|
fncConConf
|
0A
|
Connect confirm
|
|
fncConRej
|
0B
|
Connect reject
|
Reason in m_result |
fncDisconnected
|
17
|
Disconnected from host
|
Reason in m_result |
fncRcv |
0C
|
Input data
|
|
fncRcvAttention
|
20
|
Input attention (msg
wait)
|
|
fncRcvFKey |
23 |
Input function key
|
|
fncReject
|
21
|
Request rejected
|
Reason in m_result
|
fncSent
|
0F
|
Message sent
|
|
Function:
fncConnect
Description: A message sent
to the client requesting a connection. The message
payload contains a connect string that identifies the device name and the
requested host application name. The response from the client is to be either a fncConConf
with the m_user1/m_user2 fields or a fncConRej. This gives the client
application the opportunity to accept or reject the connect request.
Buffer Header:
m_function |
fncConnect |
m_connectionId |
Connection id (to
be sent on all messages) |
m_offset |
Offset to data (connect string) |
m_size |
Data size |
Connect String:
termName,appName
e.g. TERM01,ResHost
termName
|
terminal name
|
appName
|
application name
|
Function:
fncConConf
Description:
Indicates that the host connection has completed successfully.
Note that the Connection id is being provided for the first time on this
connection and must be included on every subsequent message from the client for
this user.
Buffer Header:
m_function
|
fncConConf |
m_info
|
Local
tcp port number
|
m_connectionId
|
Connection
id (send on all messages)
|
m_user1
|
User
info
|
m_user2
|
User
info
|
m_userFlags |
0x0001 BF_SENT_WANTED (only from Client) |
Function:
fncConRej
Description:
Indicates that the connect to the host failed.
Buffer Header:
m_function
|
fncConRej |
m_user1
|
User
info
|
m_user2
|
User
info
|
m_result
|
Reject
reason
|
m_offset |
Offset to optional text reason
(only from Client) |
m_size |
Text size |
Function:
fncDisconnected
Description:
Indicates that the current connection to the host has been terminated, by
the host or due to a network failure etc.
Buffer
Header:
m_function
|
fncDisconnected |
m_connectionId
|
Connection id
|
m_user1
|
User info
|
m_user2
|
User info
|
m_result
|
Disconnect reason
|
Function:
fncRcv
Description:
A message has been received from the host.
If either of the print or AU flags is set, then the user program must
subsequently send a Status message to indicate that the message processing has
completed. This enables the
corresponding indication to be sent to the host.
The message from the host maybe required to be printed.
If so, the BF_PRINT
flag is set and the printer id is indicated in one of two ways, by the
BF_DEVICE
flag.
Buffer
Header:
m_function
|
fncRcv |
m_info
|
Printer DID or device number
|
m_connectionId
|
Connection id
|
m_user1
|
User info
|
m_user2
|
User info
|
m_ userFlags
|
0x0002
|
BF_PRINT |
contains print
data
|
0x0004
|
BF_AU |
require status
for AU
|
|
0x0008
|
BF_DEVICE |
0 = m_info field
contains the printer device id
1 = m_info
contains the printer relative device number
|
m_offset
|
Offset to data
|
m_size
|
Data size
|
Function:
fncRcvAttention
Description:
A message wait has been received from the host.
Buffer
Header:
m_function
|
fncRcvAttention |
m_connectionId
|
Connection id
|
m_user1
|
User info
|
m_user2
|
User info
|
Function:
fncRcvFKey
Description: A
function key has been received.
Buffer
Header:
m_function
|
fncRcvFKey |
m_info
|
1
to 22 for function keys F1 to F22
|
m_user1
|
User info
|
m_user2
|
User info
|
Function:
fncReject
Description:
A requested command from the user program is being rejected.
The reason for the rejection is indicated in the result field.
Buffer
Header:
m_function
|
fncReject |
m_connectionId
|
Connection id
|
m_info
|
Original command being rejected
|
m_user1
|
User info
|
m_user2
|
User info
|
m_result
|
Reject reason
|
Function:
fncSent
Description:
A data, function key or MsgWait message has been sent to the host.
These messages are only sent if requested when the session is opened (see
fncConnectPkt).
Buffer
Header:
m_function
|
fncSent |
m_connectionId
|
Connection id
|
m_user1
|
User info
|
m_user2
|
User info
|
Reject Codes
Please see the list of codes in the FAQ page.
Exception
Conditions
In
a TCP/IP environment flow control is exercised by the open and closing of tcp
send and receive windows. It is to
be expected at random times that a tcp window will close, due to traffic load
and/or network congestion. This and
other events, means exception conditions must be considered:
Condition
|
Exception
|
Action
|
Received
request with any function other than Connect Request
|
Connection
id is invalid
|
Return
a Reject indication
|
Connect
Request
|
Terminal
name in use
|
Return
a Connect Reject indication and
terminate the current connection
|
Send
message to host
|
Waiting
for session status (printer or AU)
|
Return
a Reject indication
|
Send
message to host
|
Host
output blocked
|
Return
a Reject indication
|
Send
message to host
|
User
input has been stopped
|
Return
a Reject indication
|
AccessServer
Automation
Description
AccessServer
supports the COM compliant Automation interface by which properties and methods
of an individual object are exposed for programmatic control and enquiry.
Where multiple objects of the same type are implemented, they are
maintained as collections of objects. Conventional
methods are used to access theses collections (Add, Remove, Item Count).
Property |
Description |
Type |
AccessPorts
|
Handle
to the Passthru AccessPorts collection (read only) |
IDispatch |
AccessPorts2200
|
Handle
to the 2200 AccessPorts collection (read only) |
IDispatch |
AccessPortsINT1
|
Handle
to the INT1 DataPorts collection (read only) |
IDispatch |
Logging
|
Set
logging on/off |
long |
RootDirectory
|
The
start directory (read only) |
String |
StartTime
|
Time
program was started (read only)
|
String
|
Tracing
|
Set
tracing on/off
|
long
|
Version
|
Program
version (read only)
|
String
|
Method |
Description |
Return |
Save
|
Saves
config information
|
long |
INT1
DataPorts Collection
Property |
Description |
Type |
Count
|
Returns
the count of items |
long |
Method |
Description |
Return |
Add(long
index) |
Add
a new item to the collection |
IDispatch |
Item(long)
|
Returns
a handle for the requested item (the first is index 0) |
IDispatch |
Remove(long
index)
|
Delete
the requested item at index |
long |
INT1
DataPort Object
Property |
Description |
Type |
AutoStart
|
Non
zero if to be auto started |
long |
Clients
|
Handle
to the Clients collection (read only) |
IDispatch |
Comment
|
Descriptive
comment |
String |
Hosts
|
Handle
to the Hosts collection (read only) |
IDispatch |
InMsgs
|
Input
message count, from host |
long |
MaxConnections
|
Maximum
client connections
|
long
|
Name
|
Port
name
|
String
|
OutMsgs
|
Output
message count, to host
|
long
|
PortNumber
|
Listening
tcp port
|
long
|
StartedTime
|
Time
the port was started
|
String
|
Status
|
Port
status
|
long
|
Method |
Description |
Return |
LoadProperties(String
fileName)
|
Loads
properties
|
void |
SaveProperties(String
fileName)
|
Saves
properties
|
void |
Start
|
Start
listening
|
word
|
Stop
|
Stop
listening
|
word
|
Clients
Collection
Property |
Description |
Type |
Count
|
Returns the count of
items |
long |
Method |
Description |
Return |
Item(long)
|
Returns a handle for the
requested item (the first is index 0) |
IDispatch
|
Remove(long
index)
|
Delete the requested item
at index |
long |
Client
Object
Property |
Description |
Type |
Address
|
Client
IP address
|
String
|
InMsgs
|
Input
message count
|
long
|
LastInputTime
|
Time
of last input of LastUser
|
String
|
LastOutputTime
|
Time
of last output of LastUser
|
String
|
LastUser
|
Name
of last user to input
|
String
|
Name
|
Client
name
|
String
|
OutMsgs
|
Output
message count
|
long
|
SourcePort
|
Client
tcp port
|
long
|
StartedTime
|
Time
client session started
|
String
|
Status
|
Status
(0=stopped)
|
long
|
Users
|
Handle
to the Users collection (read only)
|
IDispatch
|
Method |
Description |
Return |
Start
|
Resume
receiving user messages
|
void
|
Stop
|
Stop
receiving user messages
|
void
|
Users
Collection
Property |
Description |
Type |
Count
|
Returns
the count of items |
long |
Method |
Description |
Return |
Item(long)
|
Returns
a handle for the requested item (the first is index 0) |
IDispatch |
Remove(long
index)
|
Delete
the requested item at index |
long |
User
Object
Property |
Description |
Type |
FromName
|
Source name
|
String
|
Host
|
Host name
|
String
|
InMsgs
|
Input message count, from
host |
long |
LastInputTime
|
Time
of last input
|
String
|
LastOutputTime
|
Time
of last output
|
String
|
Name
|
User name
|
String
|
OutMsgs
|
Output message count, to
host
|
long
|
SessionStatus
|
0=idle, 1=waiting for
Print status, 2=waiting for AU status |
long |
StartedTime
|
Time the port was started
|
String
|
Status
|
Status (0=stopped)
|
long |
UserAddress
|
User IP address
|
String
|
UserPort
|
User tcp port
|
long |
Method |
Description |
Return |
Start
|
Resume
receiving messages
|
void
|
Stop
|
Stop
receiving messages
|
void
|
Hosts
Collection
Property |
Description |
Type |
Count
|
Returns
the count of items |
long |
Method |
Description |
Return |
Add()
|
Creates
a new host object and returns a handle to the created item
|
IDispatch |
Item(long)
|
Returns
a handle for the requested item (the first is index 0) |
IDispatch |
Remove(long
index)
|
Delete
the requested item at index |
long |
Host
Object
Property |
Description |
Type |
AccessList
|
|
IDispatch
|
Address
|
IP address or domain name
|
String
|
AppName
|
Host app name
|
String
|
CSUname
|
CSU name
|
String
|
Comment
|
Text comment
|
long |
ConnectionTimeout
|
Timeout
in seconds when connecting
|
long
|
InMsgs
|
Input
message count, from host
|
long
|
MaxUsers
|
Maximum number of active
users
|
long |
Name
|
User name
|
String
|
OutMsgs
|
Output message count, to
host
|
long
|
Port
|
TCP/IP port numbert
|
long |
Priority
|
|
long
|
Security
|
|
long |
Transport
|
1=TCP-DTP, 2=TCPTP0
|
long |
UserCount
|
Number of active users
|
long |
|