Appendix A. Query Reply Data Structures Supported by EHLLAPI

This appendix lists and defines the query reply structures supported by the EHLLAPI structured field interface for PC/3270. Refer to IBM 3270 Information Display System Data Stream Programmer's Reference or, in the case of an IBM licensed program, the documentation for the specific licensed program.

Notes:
  1. EHLLAPI must scan the query reply buffers to locate the destination/origin ID (DOID) self-defining parameter (SDP) for the structured field support to work and be reliable. The DOID field is then filled in with the assigned ID.
  2. The application should build the query reply data structures in the application's private memory.
  3. Only cursory checking is performed on the query reply data. Only the ID and the length of the structure are checked for validity.
  4. The 2-byte length field at the beginning of each query reply is not byte reversed.
  5. Only one distributed data management (DDM) base-type connection is allowed per host session. If the DDM connection supports the SDP for the DOID, multiple connections are allowed.
  6. If a nonzero return code is received indicating that an application is already connected to the selected session (RC 32 or 39), use that presentation space with caution. Conflicts with File Transfer, and other EHLLAPI applications might result.

The DDM Query Reply

Several DDM query reply formats are supported. Here are some of them:

Table 15. DDM Query Reply Base Format
Offset Length Content Meaning
0 1 word Length Length of structure
2 1 byte X'81' Query reply ID
3 1 byte X'95' Query reply type
4-5 2 bytes FLAGS Reserved
6-7 2 bytes LIMIN Maximum DDM bytes allowed in inbound transmission
8-9 2 bytes LIMOUT Maximum DDM bytes allowed in outbound transmission
10 1 byte NSS Number of subsets identifier
11 1 byte DDMSS DDM subset identifier

DDM Application Name Self-Defining Parameter

The DDM application name self-defining parameter provides the host application with the name of the application containing control of the DDM auxiliary device. The controlling application is identified by the DOID in the Direct Access self-defining parameter.

This self-defining parameter is optional, but it is necessary if a host application is to identify a distinct DDM auxiliary device when more than one application is in existence at a remote workstation.

Table 16. DDM Application Name Self-Defining Parameter
Offset Length Content Meaning
0 1 byte Length Parameter length
1 1 byte X'02' DDM application name
2-n n-2 bytes NAME Name of the remote application program
NAME
The name consists of 8 characters or less and is the means by which a host application can relate to an application in a remote workstation. It is the responsibility of the host and remote application users to ensure that the name is understood by the application at each end.

PCLK Protocol Controls Self-Defining Parameter

The PCLK Protocol Controls self-defining parameter indicates that the PCLK Protocol Controls structured field, ID = X'1013', can be used for both inbound and outbound in data streams destined to or from the DDM auxiliary device processor.

Table 17. DDM PCLK Auxiliary Device Self-Defining Parameter
Offset Length Content Meaning
0 1 byte X'04' Parameter length
1 1 byte X'03' PCLK protocol controls
2-3 2 bytes VERS Protocol version
VERS
The value given in VERS is used to indicate the versions of PCLK installed in the terminal at the time the query reply is returned. For example, X'0001' indicates PCLK Version 1.1.

Refer to IBM 3270 Information Display System Data Stream Programmer's Reference for the field definitions for this query reply.

Base DDM Query Reply Formats

The following query reply formats are examples of some of the Base + SDP (self-defining parameter) combinations possible. Not all of the combinations are shown.

Table 18. Base DDM Query Reply Format with Name and Direct Access Self-Defining Parameters
Offset Length Content Meaning
0 1 word Length Length of structure (includes self-defining parameters)
2 1 byte X'81' Query reply ID
3 1 byte X'95' Query Reply type
4-5 2 bytes FLAGS Reserved
6-7 2 bytes LIMIN Maximum DDM bytes allowed in inbound transmission
8-9 2 bytes LIMOUT Maximum DDM bytes allowed in outbound transmission
10 1 byte NSS Number of subsets supported
11 1 byte DDMSS DDM subset identifier
12 1 byte Length (n+2) Parameter length
13 1 byte X'02' DDM application name
14- (13+n) n bytes Name Name of the remote application program
14+n 1 byte X'04' Parameter length
15+n 1 byte X'01' Direct access ID
16+n - 17+n 2 bytes DOID Destination/origin ID assigned by the subsystem

The self-defining parameters begin at offsets 12 and (14 + n) where n is the length of the application name supplied at offset 14.

Refer to IBM 3270 Information Display System Data Stream Programmer's Reference for the field definitions for this query reply.

Table 19. Base DDM Query Reply Format with Direct Access and Name Self-Defining Parameters
Offset Length Content Meaning
0 1 word Length Length of structure (includes self-defining parameters)
2 1 byte X'81' Query reply ID
3 1 byte X'95' Query reply type
4-5 2 bytes FLAGS Reserved
6-7 2 bytes LIMIN Maximum DDM bytes allowed in inbound transmission
8-9 2 bytes LIMOUT Maximum DDM bytes allowed in outbound transmission
10 1 byte NSS Number of subsets supported
11 1 byte DDMSS DDM subset identifier
12 1 byte X'04' Parameter length
13 1 byte X'01' Direct access ID
14-15 2 bytes DOID Destination/origin ID assigned by the subsystem
16 1 byte Length (n+2) Parameter length
17 1 byte X'02' DDM application name
16+n - 17+n n bytes Name Name of the remote application program

The self-defining parameters begin at offsets 12 and 16.

Refer to IBM 3270 Information Display System Data Stream Programmer's Reference for the field definitions for this query reply.

The IBM Auxiliary Device Query Reply

The Auxiliary Device Query Reply is used to indicate to the host application the support of an IBM auxiliary device that uses a data stream defined by IBM, refer to IBM 3270 Information Display System Data Stream Programmer's Reference for more details.

When the function is supported, the query reply is transmitted inbound in reply to a Read Partition structured field specifying Query or Query List (QCODE List = X'9E', Equivalent, or All).

When a workstation supports multiple auxiliary devices, the IBM auxiliary devices query reply must be sent for each device.

Optional Parameters

All parameters shown in the base part of the query reply must be present. Parameters not used are set to X'00'.

At least one self-defining parameter must be present.

Table 20. IBM Auxiliary Device Base Format with Direct Access Self-Defining Parameter
Offset Length Content Meaning
0-1 1 word Length Length of structure (includes self-defining parameters)
2 1 byte X'81' Query reply ID
3 1 byte X'9E' IBM auxiliary device reply
4
1 byte
 
BIT 0
 
 
1-7
FLAGS
 
QUERY
B'1'
 
RES
Reserved
 
Read Part (Query, Query List)
Auxiliary device supports Query
 
Reserved, must be B'0's
5 1 byte FLAGS Reserved
6-7 2 bytes LIMIN Maximum DDM bytes allowed in inbound transmission
8-9 2 bytes LIMOUT Maximum DDM bytes allowed in outbound transmission
10 1 byte
TYPE
X'01'
X'02'
Others
Type of auxiliary device supported
IBM auxiliary device display
IBM auxiliary device printer
Reserved
11 1 byte X'04' Parameter length
12 1 byte X'01' Direct access
13-14 1 word DOID Destination/origin ID assigned by the subsystem

QUERY This bit must be set to B'1' for all IBM auxiliary devices to indicate that it supports receiving a Read Partition (Query, Query List). The host applications can then use a Read Partition directed to the auxiliary device to determine its characteristics. The destination/origin structured field is used to direct the Read Partition structured field to the auxiliary device.

The minimum support level for the IBM auxiliary device is to return the Null query reply in response to the Read Partition.

LIMIN States the maximum number of bytes that can be sent in an inbound transmission. A LIMIN value of X'0000' indicates no implementation limit on the number of bytes transmitted inbound.
LIMOUT States the maximum number of bytes that can be sent to an IBM auxiliary device in an outbound transmission. A LIMOUT value of X'0000' indicates no implementation limit on the number of bytes transmitted outbound.
TYPE Identifies the auxiliary device being supported. Two values are valid. One identifies an auxiliary display and the other identifies an auxiliary printer. All other values are reserved.

The IBM auxiliary device processor supports two self-defining parameters, 01 and 03. These are defined in Table 21.

Direct Access Self-Defining Parameter

The direct access self-defining parameter provides the ID for use in the destination/origin structured field in the direct access of the IBM auxiliary device.

This SDP is always required to accompany the base query reply.

Table 21. IBM Auxiliary Device Direct Access Self-Defining Parameter
Offset Length Content Meaning
0 1 byte X'04' Parameter length
1 1 byte X'01' Direct access ID
2-3 2 bytes DOID Destination/origin ID
DOID
The value in these bytes is used in the ID field of the destination/origin structured field to identify the auxiliary device as the destination or origin of the data that follows.

PCLK Protocol Controls Self-Defining Parameter

The presence of the PCLK protocol controls self-defining parameter indicates that the PCLK protocol controls structured field, ID = X'1013', can be used for both inbound and outbound in data streams destined to or from the IBM auxiliary device processor.

Table 22. IBM Auxiliary Device PCLK Self-Defining Parameter
Offset Length Content Meaning
0 1 byte X'04' Parameter length
1 1 byte X'03' PCLK protocol controls
2-3 2 bytes VERS Protocol version
VERS
The value given in VERS is used to indicate the versions of PCLK installed in the terminal at the time the query reply is returned. For example, X'0001' indicates PCLK version 1.1.

Refer to IBM 3270 Information Display System Data Stream Programmer's Reference for the field definitions for this query reply.

The Product-Defined Query Reply

This query reply is used by IBM products using registered subidentifiers within the X'9C' data structure. The Product-Defined Data Stream query reply indicates support of a 3270DS workstation auxiliary device that uses an IBM product-defined data stream. The data stream is not defined by a format architecture document having an identifiable control point such as an architecture review board.

When an auxiliary device supports an IBM product-defined data stream, this query reply is transmitted inbound in reply to a Query List (QCODE List = X'9C' or All).

Optional Parameters

All parameters shown in the base part of the query reply and the direct access self-defining parameter must be present.

The format of the Product-Defined query reply is as follows:

Table 23. IBM Product-Defined Query Reply Base Format
Offset Length Content Meaning
0-1 1 word Length Length of structure (includes self-defining parameters)
2 1 byte X'81' Query reply ID
3 1 byte X'9C' IBM product-defined data stream
4-5 2 bytes FLAGS Reserved
6 1 byte REFID Reference identifier
7 1 byte SSID Subset identifier
8 1 byte X'04' Parameter length
9 1 byte X'01' Direct access
10-11 1 word DOID Destination/origin ID assigned by the subsystem

Valid values for REFID (offset 6) and SSID (offset 7) of the Product-Defined query reply are as follows:

Table 24. Valid REFID and SSID Values for the IBM Product-Defined Query Reply
REFID SSID Product and Data Stream Documentation
X'01'   5080 Graphics System:

This reference ID indicates the 5080 Graphics System data stream is supported by the auxiliary device. Descriptions of the 5080 Graphics Architecture, structured field, subset ID, DOID, and associated function sets are defined in IBM 5080 Graphics System Principles of Operation

  X'01' X'02' 5080 HGFD Graphics Subset 5080 RS232 Ports Subset
X'02'   WHIP API (replaced by SRL name when written)

This reference ID indicates that the WHIP API data stream is supported by the auxiliary device. A description of the WHIP API architecture is defined in IBM RT PC Workstation Host Interface Program Version 1.1 User's Guide and Reference Manual

  X'01' WHIP Subset 1
X'03' to X'FF'   All other values are reserved.

The IBM product-defined processor supports only the direct access self-defining parameter. It is defined in Table 25.

Direct Access Self-Defining Parameter

The presence of the Direct Access ID self-defining parameter indicates that the auxiliary device can be accessed directly by using the destination/origin structured field. When multiple auxiliary devices are supported that use a product-defined data stream, separate Product-Defined Data Stream query replies must be provided, each of which has a unique DOID.

Table 25. IBM Product-Defined Direct Access Self-Defining Parameter
Offset Length Content Meaning
0 1 byte X'04' Parameter length
1 1 byte X'01' Direct access ID
2-3 2 bytes DOID Destination/origin ID
DOID
The value in these bytes is used in the ID field of the destination/origin structured field to identify the auxiliary device as the destination or origin of the data that follows.

The Document Interchange Architecture Query Reply

This query reply indicates the Document Interchange Architecture (DIA) function set supported. The format of the DIA Query Reply is as follows:

Table 26. IBM DIA Base Format
Offset Length Content Meaning
0 1 word Length Length of structure (includes self-defining parameters)
2 1 byte X'81' Query reply ID
3 1 byte X'97' IBM DIA
4-5 2 bytes FLAGS Reserved
6-7 2 bytes LIMIN Maximum DDM bytes allowed in inbound transmission
8-9 2 bytes LIMOUT Maximum DDM bytes allowed in outbound transmission
10 1 byte NFS Number of 3-byte function set IDs that follow
11-13 3 bytes DIAFS DIA function set identifier
14- (13+(N*3)) N*3 bytes DIAFSs Additional DIA function set IDs
14+(N*3) 1 byte X'04' Parameter length
15+(N*3) 1 byte X'01' Direct access
16+(N*3) 1 word DOID Destination/origin ID assigned by the subsystem

The DIA auxiliary device processor supports only the direct access self-defining parameter. It is defined in Table 27.

The presence of the direct access ID self-defining parameter indicates that the auxiliary device can be accessed directly by using the destination/origin structured field.

Table 27. IBM Product-Defined Direct Access Self-Defining Parameter
Offset Length Content Meaning
0 1 byte X'04' Parameter length
1 1 byte X'01' Direct access ID
2-3 2 bytes DOID Destination/origin ID
DOID
The value in these bytes is used in the ID field of the destination/origin structured field to identify the auxiliary device as the destination or origin of the data that follows.

Refer to IBM 3270 Information Display System Data Stream Programmer's Reference for the field definitions for this query reply.