Receive Data (QOLRECV) API
Required Parameter Group:
| 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.
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:
| '0'B |
Either there is no message in the QSYSOPR message queue, or
there is a message and it does not have the capability to run problem analysis
report (PAR) to determine the cause of the error. |
| '1'B |
There is a message in the QSYSOPR message queue for this
error, and it does have the capability to run problem analysis report (PAR) to
determine the cause of the error. |
The valid values for bit 1 are as follows:
| '0'B |
The line error can be retried. |
| '1'B |
The line error is not able to be restarted. |
The valid values for bit 2 are as follows:
| '0'B |
The cause and diagnostic codes fields are not valid. |
| '1'B |
The cause and diagnostic codes fields are valid. |
The valid values for bit 3 are as follows:
| '0'B |
The error has not been reported to the system operator message
queue. |
| '1'B |
The error has been reported to the system operator message
queue. |
The valid values for bit 4 are as follows:
| '0'B |
A reset request packet was transmitted on the network |
| '1'B |
A reset confirmation packet was transmitted on the network
instead of a reset request packet.
The content of bit 4 is only valid for operation X'BF01' with 00/0000
return/reason codes.
|
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  book
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 book
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. |
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
iSeries server 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. |
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:
| X'00' |
The remaining amount of user data from a complete X.25 packet
sequence fit into the corresponding data unit. |
| X'01' |
The remaining amount of user data from a complete X.25 packet
sequence could not all fit into the corresponding data unit. The next data unit
will be used. |
|
| 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:
| X'00' |
The Q-bit was set off in all X.25 packets reassembled into the
corresponding data unit. |
| X'01' |
The Q-bit was set on in all X.25 packets reassembled into the
corresponding data unit. |
|
| 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:
| X'00' |
The user data in the corresponding data unit was received in
one or more data packets. |
| X'01' |
The user data in the corresponding data unit was received in
an X.25 interrupt packet. |
|
| 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:
| X'00' |
The D-bit was set off in all X.25 packets reassembled into the
corresponding data unit. |
| X'01' |
The D-bit was set on in all X.25 packets reassembled into the
corresponding data unit.
Note: A packet-level confirmation is sent by the
input/output processor (IOP) when a packet is received with the X.25 D-bit set
on.
|
|
| 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:
| X'00' |
The D-bit was set off in the call connected packet. D-bit will
be supported for sending data but not for receiving data.
Note: When this value is returned and an X.25 packet is
received with the D-bit set on, the input/output processor (IOP) will send a
reset packet.
|
| X'01' |
The D-bit was set on in the call connected packet. D-bit will
be supported for sending data and for receiving data. |
|
| 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. |
| 1 |
The content of this field is only valid for a 0/0 return and reason
code. |
|
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:
| X'0001' |
Clear confirmation data included. |
| X'0002' |
Clear indication data included. |
|
| 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:
| X'00' |
The D-bit was set off in the incoming call packet. |
| X'01' |
The D-bit was set on in the incoming call packet. |
|
| Reserved |
CHAR(9) |
Reserved for extension. |
| Reverse charging indicator |
CHAR(1) |
Specifies reverse charging options.
The valid values are as follows:
| X'00' |
Reverse charging not requested. |
| X'01' |
Reverse charging requested. |
|
| Fast select indicator |
CHAR(1) |
Specifies fast select options. The
valid values are as follows:
| X'00' |
Fast select not requested. |
| X'01' |
Fast select with restriction requested. |
| X'02' |
Fast select without restriction requested. |
|
| 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 iSeries server 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.
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