QTerm 7.0

The 7.0 version of QTerm brings a new look and easily accessible function panels which can be permanently displayed (pinned) or can be automatically hidden and only displayed when moused over. Mutiple frame windows are also supported with one or more terminal windows in each frame. This allows you to easily take advantage of multiple monitors.

If you are interested in trying out the new version please click here to download the software

Click New to close.

New

 

AccessServer Int1Dataport

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  

appName

application name

 

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:  

m_function

fncTraceOn

 

   Function:               fncTraceOff

Description:            Turn off tracing, for all connections.

Buffer Header:       

m_function fncTraceOff

 

 

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:       

m_function

fncLoggingOn

 

 

Function:                  fncLoggingOff

Description:            Turn off logging

Buffer Header:       

m_function fncLoggingOff

 

 

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