Receive Data (QOLRECV) API
| 1 | Return code | Output | Binary(4) |
| 2 | Reason code | Output | Binary(4) |
| 3 | Existing user connection end point ID | Output | Binary(4) |
| 4 | New provider connection end point ID | Output | Binary(4) |
| 5 | Operation | Output | Char(2) |
| 6 | Number of data units | Output | Binary(4) |
| 7 | Data available | Output | Char(1) |
| 8 | Diagnostic data | Output | Char(40) |
| 9 | Communications handle | Input | Char(10) |
Default Public Authority: *USE
Threadsafe: No
The Receive Data (QOLRECV) API performs an input operation on a link that is currently enabled in the job in which the application program is running. The type of data received is returned in the operation parameter. The data itself, is returned in the input buffer that was created when the link was enabled. For X'0001' operations, a description of that data is also be returned in the input buffer descriptor that is created when the link was enabled.
The QOLRECV API can receive different types of data depending on the type of communications line the link is using. See LAN Input Operations for more information on the types of data that can be received on links using a token-ring, Ethernet, wireless, or FDDI communications line. See X.25 SVC and PVC Input Operations for more information on the types of data that can be received on links using an X.25 communications line.
Note: The QOLRECV API should only be called when the user-defined communications support has data available to be received. This is indicated either by an incoming-data entry on the data queue or user queue, or by the data available parameter on the QOLRECV API.
Authorities and Locks
None.
Required Parameter Group
- Return code
- OUTPUT; BINARY(4)
The recovery action to take. See Return and Reason Codes.
- Reason code
- OUTPUT; BINARY(4)
The error that occurred. See Return and Reason Codes.
- Existing user connection end point ID
- OUTPUT; BINARY(4)
The user connection end point (UCEP) ID that the data was received on. For links using a token-ring, Ethernet, wireless, or FDDI communications line, the content of this parameter will always be 1.
For links using an X.25 communications line, the content of this parameter is only valid when the operation parameter is X'0001', X'B001', X'B101', X'B301', or X'BF01'. It will contain the UCEP ID that was provided in the new user connection end point ID parameter on the call to the QOLSEND API with operation X'B000' or X'B400'.
Note: If an incoming X.25 SVC call is rejected by the user-defined communications application program by calling the QOLSEND API with operation X'B100', the content of this parameter will be set to zero when notification of the completion of the X'B100' operation is received from the QOLRECV API (operation X'B101').
- New provider connection end point ID
- OUTPUT; BINARY(4)
The provider connection end point (PCEP) ID for the connection that is to be established. This identifier must be used on all subsequent calls to the QOLSEND API for this connection.
The content of this parameter is only valid for links using an X.25 communications line and when the operation parameter is X'B201'.
- Operation
- OUTPUT; CHAR(2)
The type of data received by the application program. With the exception of X'0001', all values are only valid for links using an X.25 communications line. The valid values are as follows:
X'0001' User data. X'B001' Completion of the X'B000' output operation. X'B101' Completion of the X'B100' output operation. X'B111' Completion of the X'B110' output operation. Cleanup of all connections complete. No data is associated with this operation.
X'B201' Incoming X.25 switched virtual circuit (SVC) call. X'B301' Connection failure or reset indication received. X'B311' Connection failure applying to all connections for this link. This operation is only received when the extended operations parameter for the QOLELINK API is set to operations supported.
X'BF01' Completion of the reset (X'BF00') output operation. Note: The special value of X'0000' will be returned in the operation parameter to indicate no data was received from the QOLRECV API. See Return and Reason Codes for more information.
- Number of data units
- OUTPUT; BINARY(4)
The number of data units in the input buffer that contain data. Any value between 1 and the number of data units created in the input buffer may be returned when the operation parameter is X'0001'. Otherwise, any value between 0 and 1 may be returned.
Note: The number of data units created in the input buffer was returned in the data units created parameter on the call to the QOLELINK API. See Enable Link (QOLELINK) API for more information.
- Data available
- OUTPUT; CHAR(1)
Specifies whether more data is available for the user-defined communications application program to receive. The valid values are as follows:
X'00' No more data is available for the user-defined communications application program to receive. X'01' More data is available for the user-defined communications application program to receive. The QOLRECV API must be called again prior to any other operations. Note: An incoming-data entry will be sent to the data queue or user queue only when the content of this parameter is X'00' and then more data is subsequently available to be received. See Incoming-data entry for more information.
- Diagnostic data
- OUTPUT; CHAR(40)
Specifies additional diagnostic data. See Format of Diagnostic Data Parameter for more information.
The content of this parameter is only valid when the operation parameter is X'B001', X'B101', X'B301', X'B311', or X'BF01'.
- Communications handle
- INPUT; CHAR(10)
The name of the link on which to receive the data.
Format of Diagnostic Data Parameter
The format of the diagnostic data parameter is shown below. The contents of the fields within this parameter are only valid on X'B001', X'B101', X'B301', X'B311', and X'BF01' operations for the indicated return and reason codes.
| Field | Type | Description | ||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Reserved | CHAR(2) | Reserved for extension. | ||||||||||||||||||||
| Error code | CHAR(4) | Specifies hexadecimal diagnostic
information that can be used to determine recovery actions.
The content of this field is only valid for 83/4001 and 83/4002 return/reason codes. |
||||||||||||||||||||
| Time stamp | CHAR(8) | The time the error occurred.
The content of this field is only valid for 83/4001 and 83/4002 return/reason codes. |
||||||||||||||||||||
| Error log identifier | CHAR(4) | The hexadecimal identifier that can
be used for locating error information in the error log.
The content of this field is only valid for 83/4001 and 83/4002 return/reason codes. |
||||||||||||||||||||
| Reserved | CHAR(10) | Reserved for extension. | ||||||||||||||||||||
| Indicators | CHAR(1) | The indicators that the user-defined
communications application program can use to diagnose a potential error
condition. This is a bit-sensitive field.
The valid values for bit 0 (leftmost bit) are as follows:
The valid values for bit 1 are as follows:
The valid values for bit 2 are as follows:
The valid values for bit 3 are as follows:
The valid values for bit 4 are as follows:
The content of the indicators field is only valid for 83/4001, 83/4002, and 83/3202 return/reason codes, and 00/0000 return/reason codes for operation X'BF01'. |
||||||||||||||||||||
| X.25 cause code | CHAR(1) | Specifies additional information on
the condition reported. See the
X.25 Network Support
 manual
for interpreting the values of this field.
The content of this field is only valid for 83/4001, 83/4002 and 83/3202 return/reason codes. |
||||||||||||||||||||
| X.25 diagnostic code | CHAR(1) | Specifies additional information on
the condition reported. See the
X.25 Network Support
manual
for interpreting the values of this field.
The content of this field is only valid for 83/4001, 83/4002 and 83/3202 return/reason codes. |
||||||||||||||||||||
| Reserved | CHAR(1) | Reserved for extension. | ||||||||||||||||||||
| Error offset | BINARY(4) | The offset from the top of the input
buffer to the incorrect data in the input buffer.
The content of this field is only valid for a 83/1999 return/reason code. |
||||||||||||||||||||
| Reserved | CHAR(4) | Reserved for extension. |
LAN Input Operations
The only type of data that an application program can receive from the QOLRECV API on links using a token-ring, Ethernet, wireless, or FDDI communications line is user data (operation X'0001'). User-defined communications support returns the following information for each data frame received from the QOLRECV API:
- One or more data units. The first data unit contains a general LAN header,
routing information if a token ring is used, and user data.
- Total length of the data unit. This information is reported in the corresponding input buffer descriptor element.
For example, suppose two data frames came in from the network and the user-defined communications application program was notified of this by an incoming-data entry on the data queue or user queue. On return from the QOLRECV API, the information for the first frame would be in the first data unit of the input buffer and described in the first element of the input buffer descriptor. The information for the second frame would be in the second data unit of the input buffer and described in the second element of the input buffer descriptor. The number of data units parameter would be set to 2.
Data Unit Format-LAN Operation X'0001'
Each data frame received from the QOLRECV API corresponds to a data unit in the input buffer. The information in each of these data units is made up of a general LAN header, routing information (for token-ring links only), followed by user data.
The general LAN header is used to pass information about the frame to the communications support. The fields in the general LAN header are used for all LAN link types, although some of them are link specific. For example, routing information is only for token-ring links, and the length of routing information is X'00' to X'18'. For non-token-ring links, the length of the routing information is always X'00'. Also, DSAP and SSAP are defined for protocols that use the 802.2 logical link control interface and do not apply to Ethernet Version 2. A DSAP and SSAP of X'00' tells the communications support that the data frame is an Ethernet Version 2 frame.
Format of the General LAN Information
| Field | Type | Description |
|---|---|---|
| Length of general LAN information | BINARY(2) | The length of the general LAN information in the data unit, including this field. This field is always set to 16. |
| Sending adapter address | CHAR(6) | Specifies, in packed form, the
adapter address from which this frame was sent. The possible values returned in
this field depend on the filters activated for this link. See Set Filter (QOLSETF) API for more information.
Note: Because user-defined communications support only allows connectionless service over LANs, all frames received on a single call to the QOLRECV API may not have the same source adapter address. |
| DSAP address | CHAR(1) | The service access point on which the
system received this frame. The possible values returned in this field
depend on the filters activated for this link. See Set Filter (QOLSETF) API for more information.
Note: The Ethernet Version 2 standard does not define a DSAP address in an Ethernet Version 2 frame. Therefore, when receiving Ethernet Version 2 frames, the DSAP address will be null (X'00'). |
| SSAP address | CHAR(1) | The service access point on which the
source system sent this frame. The possible values returned in this field
depend on the filters activated for this link. See Set Filter (QOLSETF) API for more information.
Note: The Ethernet Version 2 standard does not define a SSAP address in an Ethernet Version 2 frame. Therefore, when receiving Ethernet Version 2 frames, the SSAP address will be null (X'00'). |
| Reserved | CHAR(2) | Reserved for extension. |
| Length of token-ring routing information | BINARY(2) | The length of the routing information
in the data unit. For links using a token-ring communications line, any value
between 0 and 18 may be returned, where 0 indicates that there is no routing
information.
For links using an Ethernet, wireless, or FDDI communications line, the content of this field is not applicable and will be set to 0 indicating that there is no routing information. |
| Length of user data | BINARY(2) | The length of the user data in the
data unit. This will be less than or equal to the maximum frame size allowed on
the service access point returned in the DSAP address field. See Query Line Description (QOLQLIND) API to
determine the maximum frame size allowed on the service access point returned
in the DSAP address field.
For Ethernet Version 2 frames, this will be at least 48 and not more than 1502 (including 2 bytes for the Ethernet type field). Note: Ethernet 802.3 frames will be padded when the user data is less than 46 bytes. |
Token-ring routing information follows the general LAN header. The length of this field is specified by the length of token-ring routing information field found in the general LAN header. If the length of the routing information is nonzero, the user data follows the routing information header.
The following table shows the fields and offsets used for Ethernet 802.3, wireless, and token-ring frames without routing information.
| General LAN Header | User Data |
|---|---|
| 0 | 16 |
The length of the user data is described in the length of user data field in the general LAN header. For Ethernet Version 2 frames, the first 2 bytes of user data are used for the frame type. The type field is a 2-byte field that specifies the upper layer protocol of the frame.
The adapter address, DSAP, SSAP, and frame type fields are all used to define inbound routing information used by the QOLSETF API. Refer to Set Filter (QOLSETF) API for information on the QOLSETF API and how inbound routing information is used to route inbound data to the application program.
Note: Inbound routing information is not related to the token-ring routing information described in the general LAN header.
The following table shows the fields and offsets used for token-ring frames with routing information.
| General LAN Header | Routing Information | User Data |
|---|---|---|
| 0 | 16 | 16 + Length of Routing Information |
The following table shows the fields and offsets used for Ethernet Version 2 frames.
Note: For Ethernet Version 2, the frame type field is the first 2 bytes of user data, following the general LAN information, with user data starting at offset 18.
| General LAN Header | User Data | |
|---|---|---|
| Frame Type | Data | |
| 0 | 16 | 18 |
Input Buffer Descriptor Element Format-LAN Operation X'0001'
The information returned in each data unit of the input buffer will be described in the corresponding element of the input buffer descriptor. The following table shows the format of each element in the input buffer descriptor.
| Field | Type | Description |
|---|---|---|
| Length | BINARY(2) | The number of bytes of information in the corresponding data unit of the input buffer. This will be equal to the length of the general LAN information with the length of the routing information and the length of the user data. See Format of the General LAN Information for general LAN information fields and descriptions. |
| Reserved | CHAR(30) | Reserved for extension. |
X.25 SVC and PVC Input Operations
The following table shows the types of data that can be received from the QOLRECV API on links using an X.25 communications line.
| Operation | Meaning |
|---|---|
| X'0001' | User data (SVC or PVC). |
| X'B001' | Completion of the X'B000' output operation (SVC or PVC). |
| X'B101' | Completion of the X'B100' output operation (SVC or PVC). |
| X'B201' | Incoming X.25 call (SVC). |
| X'B301' | Connection failure or reset indication (SVC or PVC). |
| X'B311' | Connection failure applying to all connections for this link. |
| X'BF01' | Completion of the X'BF00' output operation (SVC or PVC). |
X.25 Operation X'0001'
This operation indicates that user data was received on an X.25 SVC or PVC connection. User-defined communications support will return the following information:
- User data in the next data unit of the input buffer, starting with the
first data unit
- A description, in the corresponding element of the input buffer descriptor, of the user data in that data unit
For example, suppose two data units of user data came in from the network and the application program was notified of this by an incoming-data entry on the data queue or user queue. On return from the QOLRECV API, the first portion of the user data would be in the first data unit of the input buffer and described in the first element of the input buffer descriptor. The second portion of the user data would be in the second data unit of the input buffer and described in the second element of the input buffer descriptor. The number of data units parameter would be set to 2.
User-defined communications support will automatically reassemble the X.25 data packet(s) from a complete packet sequence into the next data unit of the input buffer. If the amount of user data in a complete packet sequence is more than what can fit into a data unit, the more data indicator field in the corresponding element of the input buffer descriptor will be set to X'01' and the next data unit will be used for the remaining user data, and so on.
Data Unit Format-X.25 Operation X'0001'
Each data unit in the input buffer consists solely of user data and starts offset 0 from the top of the data unit.
Input Buffer Descriptor Element Format-X.25 Operation X'0001'
The user data returned in each data unit of the input buffer will be described in the corresponding element of the input buffer descriptor.
| Field | Type | Description | ||||
|---|---|---|---|---|---|---|
| Length | BINARY(2) | The number of bytes of user data in
the corresponding data unit of the input buffer. This will always be less than
or equal to the X.25 user data size parameter that was specified on the call to
the QOLELINK API when the link was enabled. See Enable Link (QOLELINK) API for more information.
Note: The maximum amount of user data in a data unit of the input buffer may be further limited by the maximum data unit assembly size for a connection. See Send Data (QOLSEND) API for more information. |
||||
| More data indicator | CHAR(1) | Specifies whether the remaining
amount of user data from a complete X.25 packet sequence is more than can fit
into the corresponding data unit. The valid values are as follows:
|
||||
| Qualified data indicator | CHAR(1) | Specifies whether the X.25 qualifier
bit (Q-bit) was set on or off in all X.25 packets reassembled into the
corresponding data unit. The valid values are as follows:
|
||||
| Interrupt packet indicator | CHAR(1) | Specifies whether the user data in
the corresponding data unit was received in an X.25 interrupt packet. The valid
values are as follows:
|
||||
| Delivery confirmation indicator | CHAR(1) | Specifies whether the X.25 delivery
confirmation bit (D-bit) was set on or off in all X.25 packets reassembled into
the corresponding data unit. The valid values are as follows:
|
||||
| Reserved | CHAR(26) | Reserved for extension. |
X.25 Operation X'B001'
This operation indicates that a X'B000' output operation has completed. User-defined communications support will return the data for this operation (if any) in the first data unit of the input buffer. The input buffer descriptor is not used.
Data will be returned in the input buffer for the following return and reason codes:
- 0/0
- 83/1999
- 83/4002 (only when the number of data units parameter is set to one)
The format of the data returned in the input buffer for the X'B001' operation depends on whether the X'B000' output operation was used to initiate an SVC call or to open a PVC connection. Each format will be explained below.
Note: The formats below only apply to 0/0 and 83/4002 return and reason codes. When the X'B001' operation is received with a 83/1999 return and reason code, the data returned starts at offset 0 from the top of the first data unit in the input buffer and contains the data specified in the output buffer on the X'B000' output operation. See Send Data (QOLSEND) API for more information.
Data Unit Format-X.25 Operation X'B001' (Completion of SVC Call)
The data returned starts at offset 0 from the top of the first data unit in the input buffer.
| Field | Type | Description | ||||
|---|---|---|---|---|---|---|
| Reserved | CHAR(2) | Reserved for extension. | ||||
| Logical channel identifier | CHAR(2) | The logical channel identifier assigned to the SVC connection.1 | ||||
| Transmit packet size | BINARY(2) | The negotiated transmit packet size for this connection.1 | ||||
| Transmit window size | BINARY(2) | The negotiated transmit window size for this connection.1 | ||||
| Receive packet size | BINARY(2) | The negotiated receive packet size for this connection.1 | ||||
| Receive window size | BINARY(2) | The negotiated receive window size for this connection.1 | ||||
| Reserved | CHAR(32) | Reserved for extension. | ||||
| Delivery confirmation support | CHAR(1) | Specifies whether the X.25 delivery
confirmation bit (D-bit) was set on or off in the call connected packet. This
also specifies the D-bit support for this connection.1 The valid
values are as follows:
|
||||
| Reserved | CHAR(11) | Reserved for extension. | ||||
| X.25 facilities length | BINARY(1) | The number of bytes of data in the X.25 facilities field. Any value between 0 and 109 may be returned. | ||||
| X.25 facilities | CHAR(109) | The X.25 facilities data. | ||||
| Reserved | CHAR(48) | Reserved for extension. | ||||
| Call/clear user data length | BINARY(2) | The number of bytes of data in the call/clear user data field. Any value between 0 and 128 may be returned. | ||||
| Call/clear user data | CHAR(128) | For a 0/0 return and reason code, this specifies the call user data. For an 83/4002 return and reason code, this specifies the clear user data. | ||||
| Reserved | CHAR(168) | Reserved for extension. | ||||
|
||||||
Data Unit Format-X.25 Operation X'B001' (Completion of Open PVC)
The data returned starts at offset 0 from the top of the first data unit in the input buffer.
| Field | Type | Description |
|---|---|---|
| Reserved | CHAR(4) | Reserved for extension. |
| Transmit packet size | BINARY(2) | The negotiated transmit packet size
for this connection.
Note: This will be the same as the requested transmit packet size specified on the X'B000' output operation. |
| Transmit window size | BINARY(2) | The negotiated transmit window size
for this connection.
Note: This will be the same as the requested transmit window size specified on the X'B000' output operation. |
| Receive packet size | BINARY(2) | The negotiated receive packet size
for this connection.
Note: This will be the same as the requested receive packet size specified on the X'B000' output operation. |
| Receive window size | BINARY(2) | The negotiated receive window size
for this connection.
Note: This will be the same as the requested receive window size specified on the X'B000' output operation. |
| Reserved | CHAR(500) | Reserved for extension. |
X.25 Operation X'B101'
This operation indicates that a X'B100' output operation has completed. User-defined communications support will return the data for this operation (if any) in the first data unit of the input buffer. The input buffer descriptor is not used.
Data will be returned in the input buffer for the following return and reason codes:
- 0/0 (only when the number of data units parameter is set to one)
- 83/1999
Note: The format below only applies for a 0/0 return and reason code. When the X'B101' operation is received with an 83/1999 return and reason code, the data returned starts at offset 0 from the top of the first data unit in the input buffer and contains the data specified in the output buffer on the X'B100' output operation. See Send Data (QOLSEND) API for more information.
Data Unit Format-X.25 Operation X'B101'
The data returned starts at offset 0 from the top of the first data unit in the input buffer.
| Field | Type | Description | ||||
|---|---|---|---|---|---|---|
| Clear type | CHAR(2) | The type of clear user data returned.
The valid values are as follows:
|
||||
| Cause code | CHAR(1) | The X.25 cause code. | ||||
| Diagnostic code | CHAR(1) | The X.25 diagnostic code. | ||||
| Reserved | CHAR(4) | Reserved for extension. | ||||
| X.25 facilities length | BINARY(1) | The number of bytes of data in the X.25 facilities field. Any value between 0 and 109 may be returned. | ||||
| X.25 facilities | CHAR(109) | The X.25 facilities data. | ||||
| Reserved | CHAR(48) | Reserved for extension. | ||||
| Clear user data length | BINARY(2) | The number of bytes of data in the clear user data field. Any value between 0 and 128 may be returned. | ||||
| Clear user data | CHAR(128) | The clear user data. | ||||
| Reserved | CHAR(216) | Reserved for extension. |
X.25 Operation X'B111'
This operation indicates a X'B110' output operation has completed. All connections have been closed and the clean up of connection control information is complete. All UCEPs and PCEPs are freed. There is no data associated with this operation.
X.25 Operation X'B201'
This operation indicates that an incoming X.25 SVC call was received. User-defined communications support returns the data for this operation in the first data unit of the input buffer. The input buffer descriptor is not used.
Note: It is the responsibility of the application program to either accept or reject the incoming call. This is done by calling the QOLSEND API with operation X'B400' or X'B100', respectively.
Data Unit Format-X.25 Operation X'B201'
The data returned starts at offset 0 from the top of the first data unit in the input buffer.
| Field | Type | Description | ||||||
|---|---|---|---|---|---|---|---|---|
| Reserved | CHAR(2) | Reserved for extension. | ||||||
| Logical channel identifier | CHAR(2) | The logical channel identifier assigned to the incoming SVC call. | ||||||
| Transmit packet size | BINARY(2) | The requested transmit packet size for this connection. | ||||||
| Transmit window size | BINARY(2) | The requested transmit window size for this connection. | ||||||
| Receive packet size | BINARY(2) | The requested receive packet size for this connection. | ||||||
| Receive window size | BINARY(2) | The requested receive window size for this connection. | ||||||
| Reserved | CHAR(7) | Reserved for extension. | ||||||
| Calling DTE address length | BINARY(1) | The number of binary coded decimal (BCD) digits in the calling DTE address. | ||||||
| Calling DTE address | CHAR(16) | Specifies, in binary coded decimal (BCD), the calling DTE address. The address will be left justified and padded on the right with BCD zeros. | ||||||
| Reserved | CHAR(8) | Reserved for extension. | ||||||
| Delivery confirmation support | CHAR(1) | Specifies whether the X.25 delivery
confirmation bit (D-bit) was set on or off in the incoming call packet. The
valid values are as follows:
|
||||||
| Reserved | CHAR(9) | Reserved for extension. | ||||||
| Reverse charging indicator | CHAR(1) | Specifies reverse charging options.
The valid values are as follows:
|
||||||
| Fast select indicator | CHAR(1) | Specifies fast select options. The
valid values are as follows:
|
||||||
| X.25 facilities length | BINARY(1) | The number of bytes of data in the X.25 facilities field. Any value between 0 and 109 may be returned. | ||||||
| X.25 facilities | CHAR(109) | The X.25 facilities data. | ||||||
| Reserved | CHAR(48) | Reserved for extension. | ||||||
| Call user data length | BINARY(2) | The number of bytes of data in the call user data field. Any value between 0 and 128 may be returned. | ||||||
| Call user data | CHAR(128) | The call user data.
Note:The system treats the first byte of call user data as the protocol identifier (PID). |
||||||
| Called DTE address length | BINARY(1) | The number of binary coded decimal (BCD) digits in the called DTE address. | ||||||
| Called DTE address | CHAR(16) | Specifies, in binary coded decimal (BCD), the called DTE address. The address will be left-justified and padded on the right with BCD zeros. | ||||||
| Reserved | CHAR(111) | Reserved for extension. |
X.25 Operation X'B301'
This operation indicates that a failure has occurred, or a reset indication has been received, on an X.25 SVC or PVC connection. User-defined communications support will return data for this operation in the first data unit of the input buffer only on a 83/4002 return and reason code when the number of data units parameter is set to one. The input buffer descriptor is not used.
Note: The diagnostic data parameter will contain the X.25 cause and diagnostic codes when a reset indication is received.
Data Unit Format-X.25 Operation X'B301'
The data returned starts at offset 0 from the top of the first data unit in the input buffer.
| Field | Type | Description |
|---|---|---|
| Reserved | CHAR(8) | Reserved for extension. |
| X.25 facilities length | BINARY(1) | The number of bytes of data in the X.25 facilities field. Any value between 0 and 109 may be returned. |
| X.25 facilities | CHAR(109) | The X.25 facilities data. |
| Reserved | CHAR(48) | Reserved for extension. |
| Clear user data length | BINARY(2) | The number of bytes of data in the clear user data field. Any value between 0 and 128 may be returned. |
| Clear user data | CHAR(128) | The clear user data. |
| Reserved | CHAR(216) | Reserved for extension. |
X.25 Operation X'B311'
This operation indicates that an error has occurred that has caused the system to close all connections on the link. The error may be a system error or a network error. The error information is returned in the diagnostic data and no additional data is provided.
Note: This operation is only received when the extended operation parameter on the QOLELINK API is set to operation supported. If the extended operations are not supported and an error occurs that will close all connections, X'B301' is received for each connection.
X.25 Operation X'BF01'
This operation indicates that a X'BF00' output operation has been completed. Neither the input buffer nor the input buffer descriptor is used for this operation.
Note: When the X'BF01' operation is received with a 0/0 return and reason code, the diagnostic data parameter will contain information indicating if a reset request or reset confirmation packet was sent.
Return and Reason Codes
The return and reason codes that can be returned from the QOLRECV API depend on the type of communications line the link is using and on the type of data (operation) that was received.
LAN Return and Reason Codes
The following table shows the return and reason codes that indicate data could not be received from the QOLRECV API.
Note: When these return and reason codes are returned, all output parameters except the return and reason codes will contain hexadecimal zeros.
| Return / Reason Code | Meaning | Recovery |
|---|---|---|
| 0/3203 | No data available to be received. | Ensure that user-defined communications support has data available to be received before calling the QOLRECV API. Try the request again. |
| 80/2200 | Queue error detected. Escape message CPF91F1 will be sent to the application program when this return and reason code is received. | Ensure the link is disabled and see messages in the job log for further information. Correct the error, enable the link, and try the request again. |
| 80/2401 | Input buffer or input buffer descriptor error detected. Escape message CPF91F1 will be sent to the application program when this return and reason code is received. | Ensure the link is disabled and see messages in the job log for further information. Correct the error, enable the link, and try the request again. |
| 80/3002 | A previous error occurred on this link that was reported to the application program by escape message CPF91F0 or CPF91F1. However, the application program has attempted another operation. | Ensure the link is disabled and see messages in the job log for further information. If escape message CPF91F0 was sent to the application program, then report the problem using the ANZPRB command. Otherwise, correct the error, enable the link, and try the request again. |
| 80/4000 | Error recovery has been canceled for this link. | Ensure the link is disabled and see messages in the job log for further information. Correct the condition, enable the link, and try the request again. |
| 80/9999 | Internal system error detected. Escape message CPF91F0 will be sent to the application program when this return and reason code is received. | See messages in the job log for further information. Report the problem using the ANZPRB command. |
| 83/3001 | Link not enabled. | Correct the communications handle parameter. Try the request again. |
| 83/3004 | Link is enabling. | Wait for the enable-complete entry to be sent to the data queue or user queue. If the link was successfully enabled, try the request again. |
Return and Reason Codes for LAN Operation X'0001'
| Return / Reason Code | Meaning | Recovery |
|---|---|---|
| 0/0 | User data received successfully. | Continue processing. |
X.25 Return and Reason Codes
The following table shows the return and reason codes that indicate data could not be received from the QOLRECV API.
Note: When these return and reason codes are returned, all output parameters except the return and reason codes will contain hexadecimal zeros.
| Return / Reason Code | Meaning | Recovery |
|---|---|---|
| 0/3203 | No data available to be received. | Ensure that user-defined communications support has data available to be received before calling the QOLRECV API. Try the request again. |
| 80/2200 | Queue error detected. Escape message CPF91F1 will be sent to the application program when this return and reason code is received. | Ensure the link is disabled and see messages in the job log for further information. Correct the error, enable the link, and try the request again. |
| 80/2401 | Input buffer or input buffer descriptor error detected. Escape message CPF91F1 will be sent to the application program when this return and reason code is received. | Ensure the link is disabled and see messages in the job log for further information. Correct the error, enable the link, and try the request again. |
| 80/3002 | A previous error occurred on this link that was reported to the application program by escape message CPF91F0 or CPF91F1. However, the application program has attempted another operation. | Ensure the link is disabled and see messages in the job log for further information. If escape message CPF91F0 was sent to the application program, then report the problem using the ANZPRB command. Otherwise, correct the error, enable the link, and try the request again. |
| 80/4000 | Error recovery has been canceled for this link. | Ensure the link is disabled and see messages in the job log for further information. Correct the condition, enable the link, and try the request again. |
| 80/9999 | Internal system error detected. Escape message CPF91F0 will be sent to the application program when this return and reason code is received. | See messages in the job log for further information. Report the problem using the ANZPRB command. |
| 83/3001 | Link not enabled. | Correct the communications handle parameter. Try the request again. |
| 83/3004 | Link is enabling. | Wait for the enable-complete entry to be sent to the data queue or user queue. If the link was successfully enabled, try the request again. |
Return and Reason Codes for X.25 Operation X'0001'
| Return / Reason Code | Meaning | Recovery |
|---|---|---|
| 0/0 | User data received successfully. | Continue processing. |
Return and Reason Codes for X.25 Operation X'B001'
| Return / Reason Code | Meaning | Recovery |
|---|---|---|
| 0/0 | The X'B000' output operation was successful. | Continue processing. |
| 83/1999 | Incorrect data was specified in
output buffer when the X'B000' output operation was issued.
Note: The data specified in the output buffer will be copied into the input buffer and the error offset field in the diagnostic data parameter will point to the incorrect data. |
Correct the incorrect data. Then, try the X'B000' output operation again. |
| 83/3204 | Connection ending because a X'B100' output operation was issued. | Wait for notification of the completion of the X'B100' output operation from the QOLRECV API (X'B101' operation). |
| 83/4001 | Link failure, system starting error recovery for this link. The connection has ended. | Wait for the link to recover. Then, try the X'B000' output operation again. |
| 83/4002 | Connection failure. The connection has ended. The diagnostic data parameter will contain more information on this error. | Correct any errors and try the X'B000' output operation again. |
| 83/4005 | All SVC channels are currently in use, or the requested PVC channel is already in use. | Wait for a virtual circuit to become available. Then, try the X'B000' output operation again. |
Return and Reason Codes for X.25 Operation X'B101'
| Return / Reason Code | Meaning | Recovery |
|---|---|---|
| 0/0 | The X'B100' output operation was successful. The connection has ended. | Continue processing. |
| 83/1007 | Connection identifier not valid because connection has already ended. | Continue processing. |
| 83/1999 | Incorrect data was specified in
output buffer when the X'B100' output operation was issued.
Note: The data specified in the output buffer will be copied into the input buffer and the error offset field in the diagnostic data parameter will point to the incorrect data. |
Correct the incorrect data. Then, try the X'B100' output operation again. |
Return and Reason Codes for X.25 Operation X'B111'
| Return / Reason Code | Meaning | Recovery |
|---|---|---|
| 0/0 | The X'B100' output operation was successful. The connection has ended. | Continue processing. |
| 83/1007 | Connection identifier not valid because connection has already ended. | Continue processing. |
| 83/3205 | The X'B110' operation is rejected because the application has not received the X'B311' operation prior to requesting the X'B110' operation. | Correct the application. |
Return and Reason Codes for X.25 Operation X'B201'
| Return / Reason Code | Meaning | Recovery |
|---|---|---|
| 0/0 | Incoming X.25 SVC call received successfully. | Continue processing. |
Return and Reason Codes for X.25 Operation X'B301'
| Return / Reason Code | Meaning | Recovery |
|---|---|---|
| 83/3201 | The maximum amount of incoming user data that can be held by user-defined communications support for the application program on this connection has been exceeded. | Issue the X'B100' output operation to end the connection. |
| 83/3202 | A reset indication has been received on this connection. The X.25 cause and diagnostic code fields in the diagnostic data parameter will contain the cause and diagnostic codes of the reset indication. | Issue the X'BF00' output operation to send a reset confirmation packet. |
| 83/4001 | Link failure, system starting error recovery for this link. | Issue the X'B100' output operation to end the connection. |
| 83/4002 | Connection failure. The diagnostic data parameter will contain more information on this error. | Issue the X'B100' output operation to end the connection. |
Return and Reason Codes for X.25 Operation X'B311'
| Return / Reason Code | Meaning | Recovery |
|---|---|---|
| 83/4001 | Link failure, system starting error recovery for this link. All connections that were active on this link are closed or cleared. | Issue the X'B110' operation to free the connections. |
| 83/4002 | A network error has occurred that affects all connections on this link. All connections that were active on this link are closed or cleared. The diagnostic data contains more information on this error. | Issue the X'B110' operation to free the connections. |
Return and Reason Codes for X.25 Operation X'BF01'
| Return / Reason Code | Meaning | Recovery |
|---|---|---|
| 0/0 | The X'BF00' output operation was successful. The diagnostic data parameter will contain information indicating if a reset request or reset confirmation packet was sent. | Continue processing. |
| 83/1006 | Operation not valid. | Do not issue the X'BF00' output operation on connections that do not support resets. |
| 83/3201 | The maximum amount of incoming user data that can be held by user-defined communications support for the application program on this connection has been exceeded. | Wait to receive a failure notification from the QOLRECV API indicating this condition (X'B301' operation, 83/3201 return and reason code). Then issue the X'B100' output operation to end the connection. |
| 83/3204 | Connection ending because a X'B100' output operation was issued. | Wait for notification of the completion of the X'B100' output operation from the QOLRECV API (X'B101' operation). |
| 83/4001 | Link failure, system starting error recovery for this link. | Wait to receive a failure notification from the QOLRECV API indicating this condition (X'B301' operation, 83/4001 return and reason code). Then, issue the X'B100' output operation to end the connection. |
| 83/4002 | Connection failure. | Wait to receive a failure notification from the QOLRECV API indicating this condition (X'B301' operation, 83/4002 return and reason code). Then, issue the X'B100' output operation to end the connection. |
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF3C90 E | Literal value cannot be changed. |
| CPF91F0 E | Internal system error. |
| CPF91F1 E | User-defined communications application error. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R1