Send Data (QOLSEND) API

The Send Data (QOLSEND) API performs output on a link that is currently enabled in the job in which the application program is running. The operation parameter allows you to specify the type of output operation to perform. The application program must provide the data associated with the output operation in the output buffer that was created when the link was enabled. For X'0000' operations, the application program must also provide a description of that data in the output buffer descriptor that was created when the link was enabled.

The types of output operations that can be performed on a link depend on the type of communications line that the link is using. See LAN Output Operations for more information on output operations that are supported on links using a token-ring, Ethernet, wireless, or FDDI communications line. See X.25 SVC and PVC Output Operations for more information on output operations that are supported on links using an X.25 communications line.

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.

Diagnostic data

OUTPUT; CHAR(40)

Additional diagnostic data. See Diagnostic Data Parameter Format for more information.

The content of this parameter is only valid when the operation parameter is set to X'0000' or X'B400'.

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 set to X'B000'.

New user connection end point ID

INPUT; BINARY(4)

The user connection end point (UCEP) ID for the connection that is to be established. This is the identifier on which all incoming data for this connection will be received. Any numeric value except zero should be used. See Receive Data (QOLRECV) API for more information.

The content of this parameter is only valid for links using an X.25 communications line and when the operation parameter is set to X'B000' or X'B400'.

Existing provider connection end point ID

INPUT; BINARY(4)

The PCEP ID for the connection on which this operation will be performed. For links using a token-ring, Ethernet, or wireless communications line, the content of this parameter must always be set to 1.

For links using an X.25 communications line, the content of this parameter is only valid when the operation parameter is set to X'0000', X'B100', X'B400', or X'BF00'. It must contain the PCEP ID that was returned in the new provider connection end point ID parameter from the call to the QOLSEND API with operation X'B000', or the PCEP ID that was returned in the new provider connection end point ID parameter from the call to the QOLRECV API with operation X'B201' (incoming call). See Receive Data (QOLRECV) API for more information on receiving X.25 calls.

Communications handle

INPUT; CHAR(10)

The name of the link on which to perform the output operation.

Operation

INPUT; CHAR(2)

The type of output operation to perform. With the exception of X'0000', all values are only valid for links using an X.25 communications line. The valid values are as follows:

X'0000'	Send data.
X'B000'	Send call request packet (SVC) or open PVC connection.
X'B100'	Send clear packet (SVC) or close PVC connection.
X'B110'	Initiate final cleanup of all connections that were closed by the system. This operation is only valid when the application receives an X'B311' operation to receive connection failure data.
X'B400'	Send call accept packet (SVC).
X'BF00'	Send reset request packet or reset confirmation packet (SVC or PVC).

Number of data units

INPUT; BINARY(4)

The number of data units in the output buffer that contain data. Any value between 1 and the number of data units created in the output buffer may be used.

The content of this parameter is only valid when the operation parameter is set to X'0000'.

Note: The number of data units created in the output buffer was returned in the data units created parameter on the call to the QOLELINK API. See Enable Link (QOLELINK) API for more information.

Diagnostic Data Parameter Format

The format of the diagnostic data parameter is shown below. The contents of the fields within this parameter are only valid on X'0000' and X'B400' 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. See Error Codes for more information. The content of this field is only valid for 83/4001, 83/4002, and 83/4003 return/reason codes.
Time stamp	CHAR(8)	The time the error occurred. The content of this field is only valid for 83/4001, 83/4002, and 83/4003 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, 83/4002, and 83/4003 return/reason codes.
Reserved	CHAR(10)	Reserved for extension.
Indicators	CHAR(1)	Specifies indicators the user-defined communications application program can use for diagnosing 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 cannot be retried. 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. For example, consider the following values for the indicators field: X'20' A condition has caused X.25 cause and diagnostic codes to be passed to the application. This information can determine the cause of the condition. X'50' An error has occurred and been reported to the QSYSOPR message queue. The error cannot be retried. X'F0' An error has occurred and been reported to the QSYSOPR message queue. The error cannot be retried, and has X.25 cause and diagnostic codes associated with it. Also a problem analysis report can be generated to determine the probable cause. The content of this field is valid only for 83/4001, 83/4002, 83/3202 and 83/4003 return/reason codes.
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 output buffer to the incorrect data in the output buffer. The content of this field is only valid for a 83/1999 return/reason code.
Reserved	CHAR(4)	Reserved for extension.

LAN Output Operations

The only output operation supported on links using a token-ring, Ethernet, wireless, or FDDI communications line is X'0000' (send user data). For each data frame to be sent on the network, the application program must provide the following information:

• General LAN information, optional routing information, and user data in the next data unit of the output buffer, starting with the first data unit
  
  
• A description, in the corresponding element of the output buffer descriptor, of the information in that data unit.

For example, suppose a user-defined communications application program wants to send two data frames. The information for the first frame would be placed in first data unit of the output buffer and described in the first element of the output buffer descriptor. The information for the second frame would be placed in the second data unit of the output buffer and described in the second element of the output buffer descriptor. The number of data units parameter on the call to the QOLSEND API would be set to 2.

Note: The X'0000' operation is synchronous. Control will not return from the QOLSEND API until the operation completes.

Data Unit Format-LAN Operation X'0000'

Each data frame to be sent on the network corresponds to a data unit in the output buffer. The information in each of these data units is made up of general LAN information, optional routing data, and user data.

Field	Type	Description
Length of general LAN information	BINARY(2)	The length of the general LAN information in the data unit. This must be set to 16.
Destination adapter address	CHAR(6)	Specifies, in packed form, the adapter address to which this data frame will be sent. Note: Because user-defined communications support only allows connectionless service over LANs, it is not necessary for all frames being sent on a single output operation to have the same destination adapter address.
DSAP address	CHAR(1)	The service access point on which the destination system will receive this frame. Any value may be used. Note: The Ethernet Version 2 standard does not use logical link control, which utilizes SAPs. Therefore, to send Ethernet Version 2 frames, a null DSAP address (X'00') must be specified in the DSAP address field. Also, the Ethernet Standard (ETHSTD) parameter in the Ethernet line description must be configured as either *ETHV2 or *ALL.
SSAP address	CHAR(1)	The service access point on which the system will send this frame. Any service access point configured in the token-ring, Ethernet, wireless, or FDDI line description may be used. Note: The Ethernet Version 2 standard does not use logical link control, which utilizes SAPs. Therefore, to send Ethernet Version 2 frames, a null SSAP address (X'00') must be specified in the SSAP address field. Also, the Ethernet Standard (ETHSTD) parameter in the Ethernet line description must be configured as either *ETHV2 or *ALL.
Access control	CHAR(1)	Specifies outbound frame priority and is mapped to the access priority bits in the access control field of 802.5 frames. For links using a token-ring communications line, any value between X'00' and X'07' may be used, where X'00' is the lowest priority and X'07' is the highest priority. For links using an Ethernet or wireless communications line, the content of this field is not applicable and must be set to X'00'.
Priority control	CHAR(1)	Specifies how to interpret the value set in the access control field. For links using a token-ring communications line, the valid values are as follows: X'00' Use any priority less than or equal to the value set in the access control field. X'01' Use the priority exactly equal to the value set in the access control field. X'FF' Use the system default priority. For links using an Ethernet or wireless communications line, the content of this field is not applicable and must be set to X'00'.
Length of 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 used, where 0 indicates that there is no routing information. For links using an Ethernet or wireless communications line, the content of this field is not applicable and must 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 must be less than or equal to the maximum frame size allowed on the service access point specified in the SSAP address field. See Query Line Description (QOLQLIND) API to determine the maximum frame size allowed on the service access point specified in the SSAP address field. For Ethernet Version 2 frames, this must 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.

Output Buffer Descriptor Element Format-LAN Operation X'0000'

The information specified in each data unit of the output buffer must be described in the corresponding element of the output buffer descriptor.

Field	Type	Description
Length	BINARY(2)	The number of bytes of information in the corresponding data unit of the output buffer. This must be equal to the length of the general LAN information plus the length of the routing information plus the length of the user data. See Format of the General LAN Information in the Receive Data (QOLRECV) API for more information on the format of the general LAN information.
Reserved	CHAR(30)	Reserved for extension.

X.25 SVC and PVC Output Operations

The following table shows the output operations that are supported on links using an X.25 communications line.

Operation	Meaning
X'0000'	Send user data (SVC or PVC). Note: This is a synchronous operation. Control will not return from the QOLSEND API until the operation completes.
X'B000'	Send a call request packet (SVC) or open the PVC connection. Note: This is an asynchronous operation. Notification of the completion of this operation will be returned from the QOLRECV API with operation X'B001' only after control returns from the QOLSEND API with a 0/0 return and reason code. See Receive Data (QOLRECV) API for more information.
X'B100'	Send a clear packet (SVC) or close the PVC connection. Note: This is an asynchronous operation. Notification of the completion of this operation will be returned from the QOLRECV API with operation X'B101' only after control returns from the QOLSEND API with a 0/0 return and reason code. See Receive Data (QOLRECV) API for more information.
X'B110'	Close all connections which were cleared by the reason given in the connection failure date received on X 'B311'. Note: This is an asynchronous operation. Notification of the completion of this operation will be returned from the QOLRECV API with operation X'B111' only after control returns from the QOLSEND API with a 0/0 return and reason code. See Receive Data (QOLRECV) API for more information.
X'B400'	Send a call accept packet (SVC only). Note: This is a synchronous operation. Control will not return from the QOLSEND API until the operation completes.
X'BF00'	Send a reset request or reset confirmation packet (SVC or PVC). Note: This is an asynchronous operation. Notification of the completion of this operation will be returned from the QOLRECV API with operation X'BF01' only after control returns from the QOLSEND API with a 0/0 return and reason code. See Receive Data (QOLRECV) API for more information.
Note: The maximum number of outstanding asynchronous operations (notification of completion not yet received from the QOLRECV API) is five. All calls made to the QOLSEND API or QOLSETF API under this condition will be rejected with a return and reason code of 83/3200.

X.25 Operation X'0000'

This operation allows the application program to send user data on an SVC or PVC X.25 connection. The application must provide the following information:

• User data in the next data unit of the output buffer, starting with the first data unit
  
  
• A description, in the corresponding element of the output buffer descriptor, of the user data in that data unit.

For example, suppose a user-defined communications application program wants to send two data units of user data. The first portion of the user data would be placed in first data unit of the output buffer and described in the first element of the output buffer descriptor. The second portion of the user data would be placed in the second data unit of the output buffer and described in the second element of the output buffer descriptor. The number of data units parameter on the call to the QOLSEND API would be set to 2.

User-defined communications support automatically fragments the user data in each data unit into one or more appropriately sized X.25 packets based on the negotiated transmit packet size for the connection. All packets constructed for a data unit, except for the last (or only) packet, will always have the X.25 more data bit (M-bit) set on. See Output Buffer Descriptor Element Format-X.25 Operation X'0000' for more information on how to set the X.25 M-bit on or off in the last (or only) packet constructed for a data unit.

Data Unit Format-X.25 Operation X'000'

Each data unit in the output buffer consists solely of user data and starts offset 0 from the top of the data unit.

Output Buffer Descriptor Element Format-X.25 Operation X'0000'

The user data specified in each data unit of the output buffer must be described in the corresponding element of the output buffer descriptor.

Field	Type	Description
Length	BINARY(2)	The number of bytes of user data in the corresponding data unit of the output buffer. This must 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.
More data indicator	CHAR(1)	Specifies whether the X.25 more data bit (M-bit) should be set on or off in the last (or only) X.25 packet constructed for the corresponding data unit. The valid values are as follows: X'00' Set the M-bit off in the last (or only) X.25 packet constructed for the corresponding data unit. X'01' Set the M-bit on in the last (or only) X.25 packet constructed for the corresponding data unit. Note: When this value is selected, the length field must be set to a multiple of the negotiated transmit packet size for the connection.
Qualified data indicator	CHAR(1)	Specifies whether the X.25 qualifier bit (Q-bit) should be set on or off in all X.25 packets constructed for the corresponding data unit. The valid values are as follows: X'00' Set the Q-bit off in all X.25 packets constructed for the corresponding data unit. X'01' Set the Q-bit on in all X.25 packets constructed for the corresponding data unit.
Interrupt packet indicator	CHAR(1)	Specifies whether the user data in the corresponding data unit should be sent in an X.25 interrupt packet. The valid values are as follows: X'00' Send the user data in the corresponding data unit in one or more X.25 data packets. X'01' Send the user data in the corresponding data unit in an X.25 interrupt packet. An interrupt packet causes the data to be expedited. Note: When this value is selected, the length field must be set to a value between 1 and 32, and the number of data units parameter on the call to the QOLSEND API must be set to 1. Also, the contents of the more data indicator, qualified data indicator, and delivery confirmation indicator fields are ignored.
Delivery confirmation indicator	CHAR(1)	Specifies whether the X.25 delivery confirmation bit (D-bit) should be set on or off in all X.25 packets constructed for the corresponding data unit. The valid values are as follows: X'00' Set the D-bit off in all X.25 packets constructed for the corresponding data unit. X'01' Set the D-bit on in all X.25 packets constructed for the corresponding data unit. Note: The system does not fully support delivery confirmation when sending user data. Confirmation is from the local data circuit equipment (DCE).
Reserved	CHAR(26)	Reserved for extension.

X.25 Operation X'B000'

This operation allows the application program to either initiate an SVC call or to open a PVC connection. The application must provide the data for this operation in the first data unit of the output buffer. The output buffer descriptor is not used.

The format of the data required for the X'B000' operation depends on whether it is used to initiate an SVC call or to open a PVC connection. Each format is explained in the following table.

Note: When initiating an SVC call, the system chooses an available SVC to use. The logical channel identifier of the SVC that was chosen will be returned when notification of the completion of X'B000' is received from the QOLRECV API (operation X'B001'). See Receive Data (QOLRECV) API for more information.

Data Unit Format-X.25 Operation X'B000' (Initiate an SVC Call)

The data for this operation starts at offset 0 from the top of the first data unit in the output buffer. The following table shows the format of the data required for the X'B000' operation when initiating an SVC call.

Field	Type	Description
Reserved	CHAR(1)	This field must be set to X'02'.
Reserved	CHAR(3)	This field must be set to hexadecimal zeros.
Transmit packet size	BINARY(2)	The requested transmit packet size for this connection. The valid values are 64, 128, 256, 512, 1024, 2048, and 4096. The value specified must be less than or equal to the transmit maximum packet size configured for this line. The special value of X'FFFF' may be specified to use the transmit default packet size configured for this line. See Query Line Description (QOLQLIND) API for information on determining the transmit maximum packet size and the transmit default packet size configured for this line.
Transmit window size	BINARY(2)	The requested transmit window size for this connection. The valid values are as follows: 1-7 When modulus 8 is configured for this line. 1-15 When modulus 128 is configured for this line. X'FFFF' Use the transmit default window size configured for this line. See Query Line Description (QOLQLIND) API for information on determining the modulus value and the transmit default window size configured for this line.
Receive packet size	BINARY(2)	The requested receive packet size for this connection. The valid values are 64, 128, 256, 512, 1024, 2048, and 4096. The value specified must be less than or equal to the receive maximum packet size configured for this line. The special value of X'FFFF' may be specified to use the receive default packet size configured for this line. See Query Line Description (QOLQLIND) API for information on determining the receive maximum packet size and the receive default packet size configured for this line.
Receive window size	BINARY(2)	The requested receive window size for this connection. The valid values are as follows: 1-7 When modulus 8 is configured for this line. 1-15 When modulus 128 is configured for this line. X'FFFF' Use the receive default window size configured for this line. See Query Line Description (QOLQLIND) API for information on determining the modulus value and the receive default window size configured for this line.
Reserved	CHAR(7)	This field must be set to hexadecimal zeros.
DTE address length	BINARY(1)	The number of binary coded decimal (BCD) digits in the DTE address to call. The valid values are as follows: 1-15 When extended network addressing is not configured for this line. 1-17 When extended network addressing is configured in the line description. See Query Line Description (QOLQLIND) API to determine if extended network addressing is configured for this line.
DTE address	CHAR(16)	Specifies, in binary coded decimal (BCD), the DTE address to call. The address must be left justified and padded on the right with BCD zeros.
Reserved	CHAR(8)	This field must be set to hexadecimal zeros.
Delivery confirmation support	CHAR(1)	Specifies whether the X.25 delivery confirmation bit (D-bit) should be set on or off in the call request packet. The valid values are as follows: X'00' Set the D-bit off in the call request packet. X'01' Set the D-bit on in the call request packet.
Reserved	CHAR(7)	This field must be set to hexadecimal zeros.
Closed user group indicator	CHAR(1)	Specifies whether the closed user group (CUG) identifier should be included in the call packet. The valid values are as follows: X'00' Do not include the CUG identifier in the call packet. X'01' Include the CUG identifier in the call packet.
Closed user group identifier	CHAR(1)	The CUG identifier to be included in the call packet. The valid values are as follows: X'00' When the closed user group indicator field is set to X'00' X'00'-X'99' When the closed user group indicator field is set to X'01'
Reverse charging indicator	CHAR(1)	Specifies reverse charging options. The valid values are as follows: X'00' Do not request reverse charging. X'01' Request reverse charging.
Fast select indicator	CHAR(1)	Specifies fast select options. The valid values are as follows: X'00' Do not request fast select. X'01' Request fast select with restriction. X'02' Request fast select without restriction.
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 used. Note: The system codes the closed user group, reverse charging, and fast select facilities in the X.25 facilities field, if the user requested them in the above fields. Additionally, if the network user identification parameter (NETUSRID) is specified in the line description, the network user identification (NUI) facility is coded in the field, following the other additional facilities, if present. Finally, if the packet and window size values specified are different than the network default, the facilities containing these values are coded in the field as well. The system will update the X.25 facilities length field appropriately for each facility to which the system adds the X.25 facilities field. This length cannot exceed 109 bytes.
X.25 facilities	CHAR(109)	Specifies additional X.25 facilities data requested. Note: The application programmer should not code the facilities for NUI, fast select, reverse charging, closed user group, packet size, or window size in this field. By doing so, this field could contain duplicate facilities, which may not be consistently supported by all X.25 networks.
Reserved	CHAR(48)	This field must be set to hexadecimal zeros.
Call user data length	BINARY(2)	The number of bytes of data in the call user data field. The valid values are as follows: 0-16 When the fast select indicator field is set to X'00'. 0-128 When the fast select indicator field is set to X'01' or X'02'.
Call user data	CHAR(128)	The call user data.
Reserved	CHAR(128)	This field must be set to hexadecimal zeros.
Control information	CHAR(1)	Specifies control information for this connection. This is a bit-sensitive field with bit 0 (leftmost bit) defined for reset support. The remaining bits are undefined and should be set off ('0'B). The valid values for bit 0 are as follows: '0'B Resets are not supported on this connection. When this value is selected, the X'BF00' output operation will not be valid on this connection. Also, a reset indication packet received on this connection will cause the connection to be ended. '1'B Resets are supported on this connection. When this value is selected, the X'BF00' output operation will be valid on this connection. Also, the user-defined communications application program will be required to handle reset indications received on this connection. For example, consider the following values for the control information field: X'00' Resets are not supported on this connection. X'80' Resets are supported on this connection.
Reserved	CHAR(3)	This field must be set to hexadecimal zeros.
Maximum data unit assembly size	BINARY(4)	The maximum number of bytes of user data that is received in a complete X.25 packet sequence before passing the user data to the application. Any value between 1024 and 32767 may be used, and should be set to the largest value that the application will support. Notes: The system attempts to assemble the entire packet sequence before passing the data to the application. The only exception to this is when the size of the packet sequence exceeds the value the user specified for this field. If the number of bytes of user data received in a complete X.25 packet sequence is more than can fit into one data unit of the input buffer, the more data indicator field in the corresponding element of the input buffer descriptor will be set to X'01' and the remaining user data will be filled in the next data unit. See Receive Data (QOLRECV) API for more information. There is no limitation on the number of bytes of user data that can be sent in a complete X.25 packet sequence. However, the QOLSEND API may need to called more than once.
Automatic flow control	BINARY(2)	Relates to the amount of data that will be held by user-defined communications support before sending a receive not ready (RNR) packet to the sending system. The recommended value for this field is 32, but any value between 1 and 128 may be used. Note: A receive ready (RR) packet will be sent when the user-defined communications application program receives some of the data.
Reserved	CHAR(30)	This field must be set to hexadecimal zeros.

Data Unit Format-X.25 Operation X'B000' (Open a PVC Connection)

The data for this operation starts at offset 0 from the top of the first data unit in the output buffer. The following table shows the format of the data required for the X'B000' operation when opening a PVC connection.

Field	Type	Description
Reserved	CHAR(1)	This field must be set to hexadecimal zeros.
Reserved	CHAR(1)	This field must be set to hexadecimal zeros.
Logical channel identifier	CHAR(2)	The logical channel identifier of the PVC to open. Any PVC configured for this line that is eligible to be used by the network controller that the link is using may be specified and must be in the range of X'0001'-X'0FFF'. See Query Line Description (QOLQLIND) API for information on determining the PVCs configured for this line that are eligible to be used by the network controller the link is using.
Transmit packet size	BINARY(2)	The requested transmit packet size for this connection. The valid values are 64, 128, 256, 512, 1024, 2048, and 4096. The value specified must be less than or equal to the transmit maximum packet size configured for this line. The special value of X'FFFF' may be specified to use the transmit default packet size configured for this line. See Query Line Description (QOLQLIND) API for information on determining the transmit maximum packet size and the transmit default packet size configured for this line.
Transmit window size	BINARY(2)	The requested transmit window size for this connection. The valid values are as follows: 1-7 When modulus 8 is configured for this line. 1-15 When modulus 128 is configured for this line. X'FFFF' Use the transmit default window size configured for this line. See Query Line Description (QOLQLIND) API for information on determining the modulus value and the transmit default window size configured for this line.
Receive packet size	BINARY(2)	The requested receive packet size for this connection. The valid values are 64, 128, 256, 512, 1024, 2048, and 4096. The value specified must be less than or equal to the receive maximum packet size configured for this line. The special value of X'FFFF' may be specified to use the receive default packet size configured for this line. See Query Line Description (QOLQLIND) API for information on determining the receive maximum packet size and the receive default packet size configured for this line.
Receive window size	BINARY(2)	The requested receive window size for this connection. The valid values are as follows: 1-7 When modulus 8 is configured for this line. 1-15 When modulus 128 is configured for this line. X'FFFF' Use the receive default window size configured for this line. See Query Line Description (QOLQLIND) API for information on determining the modulus value and the receive default window size configured for this line.
Reserved	CHAR(32)	This field must be set to hexadecimal zeros.
Delivery confirmation support	CHAR(1)	The X.25 delivery confirmation bit (D-bit) support for this connection. The valid values are as follows: X'00' D-bit will be supported for sending data but not for receiving data. Note: When this value is selected 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' D-bit will be supported for sending data and for receiving data.
Reserved	CHAR(427)	This field must be set to hexadecimal zeros.
Control information	CHAR(1)	Specifies control information for this connection. This is a bit-sensitive field with bit 0 (leftmost bit) defined for reset support. The remaining bits are undefined and should be set off ('0'B). The valid values for bit 0 are as follows: '0'B Resets are not supported on this connection. When this value is selected, the X'BF00' output operation will not be valid on this connection. Also, a reset indication packet received on this connection will cause the connection to be ended. '1'B Resets are supported on this connection. When this value is selected, the X'BF00' output operation will be valid on this connection. Also, the user-defined communications application program will be required to handle reset indications received on this connection. For example, consider the following values for the control information field: X'00' Resets are not supported on this connection. X'80' Resets are supported on this connection.
Reserved	CHAR(3)	This field must be set to hexadecimal zeros.
Maximum data unit assembly size	BINARY(4)	The maximum number of bytes of user data that is received in a complete X.25 packet sequence before passing the user data to the application. Any value between 1024 and 32767 may be used, and should be set to the largest value that the application will support. Notes: The system attempts to assemble the entire packet sequence before passing the data to the application. The only exception to this is when the size of the packet sequence exceeds the value the user specified for this field. If the number of bytes of user data received in a complete X.25 packet sequence is more than can fit into one data unit of the input buffer, the more data indicator field in the corresponding element of the input buffer descriptor will be set to X'01' and the remaining user data will be filled in the next data unit. See Receive Data (QOLRECV) API for more information. There is no limit of the number of bytes of user data that can be sent in a complete X.25 packet sequence. However, the QOLSEND API may need to called more than once.
Automatic flow control	BINARY(2)	Relates to the amount of data that will be held by user-defined communications support before sending a receive not ready (RNR) packet to the sending system. The recommended value for this field is 32, but any value between 1 and 128 may be used. Note: A receive ready (RR) packet will be sent when the user-defined communications application program receives some of the data.
Reserved	CHAR(30)	This field must be set to hexadecimal zeros.

X.25 Operation X'B100'

This operation allows the application program to either send a clear packet on an SVC, close an SVC connection that was cleared by the remote system, or to close a PVC connection. The application must provide the data for this operation in the first data unit of the output buffer. The output buffer descriptor is not used.

The format of the data required for the X'B100' operation is the same whether or not it is used to send a clear packet on an SVC or to close a PVC connection. The format of the data required for the X'B100' operation should be set to hexadecimal zeros if it is used to close an SVC connection that was previously cleared by the remote system.

Notes:

1. The system provides the confirmation of the clear indication, however, the local user-defined communications application must issue the X'B100' operation to free the PCEP for the connection.
   
   
2. Closing a PVC connection will cause a reset packet to be sent to the remote system.

Data Unit Format-X.25 Operation X'B100'

The data for this operation starts at offset 0 from the top of the first data unit in the output buffer. The following table shows the format of the data required for the X'B100' operation.

Field	Type	Description
Reserved	CHAR(2)	This field must be set to hexadecimal zeros.
Cause code	CHAR(1)	The X.25 cause code.
Diagnostic code	CHAR(1)	The X.25 diagnostic code.
Reserved	CHAR(4)	This field must be set to hexadecimal zeros.
X.25 facilities length1	BINARY(1)	The number of bytes of data in the X.25 facilities field. Any value between 0 and 109 may be used.
X.25 facilities1	CHAR(109)	The X.25 facilities data.
Reserved	CHAR(48)	This field must be set to hexadecimal zeros.
Clear user data length1	BINARY(2)	The number of bytes of data in the clear user data field. Any value between 0 and 128 may be used.
Clear user data1	CHAR(128)	The clear user data. Note: The CCITT standard recommends that this field only be present in conjunction with the fast select or call deflection selection facility. The system does not enforce this restriction, however.
Reserved	CHAR(216)	This field must be set to hexadecimal zeros.
1 This field is not used for PVC connections and should be set to hexadecimal zeros.

X.25 Operation X'B110'

This operation allows the application program to clean up all internal control information on all the connections over the link and free up all PCEPs and UCEPs. This operation is only valid following the receipt of the X'B311' operation that reports the connection failure data to the application. There is no data associated with this operation.

X.25 Operation X'B400'

This operation allows the application program to accept an incoming SVC call. The application must provide the data for this operation in the first data unit of the output buffer. The output buffer descriptor is not used.

Note: Notification of incoming calls are received from the QOLRECV API with operation X'B201'. See Receive Data (QOLRECV) API for more information.

Data Unit Format-X.25 Operation X'B400'

The data for this operation starts at offset 0 from the top of the first data unit in the output buffer. The following table shows the format of the data required for the X'B400' operation.

Field	Type	Description
Reserved	CHAR(1)	This field must be set to hexadecimal zeros.
Reserved	CHAR(3)	This field must be set to hexadecimal zeros.
Transmit packet size	BINARY(2)	The transmit packet size for this connection. The valid values are 64, 128, 256, 512, 1024, 2048, and 4096. The value specified must be less than or equal to the transmit maximum packet size configured for this line. The special value of X'FFFF' may be specified to use the transmit default packet size configured for this line. See Query Line Description (QOLQLIND) API for information on determining the transmit maximum packet size and the transmit default packet size configured for this line.
Transmit window size	BINARY(2)	The transmit window size for this connection. The valid values are as follows: 1-7 When modulus 8 is configured for this line. 1-15 When modulus 128 is configured for this line. X'FFFF' Use the transmit default window size configured for this line. See Query Line Description (QOLQLIND) API for information on determining the modulus value and the transmit default window size configured for this line.
Receive packet size	BINARY(2)	The receive packet size for this connection. The valid values are 64, 128, 256, 512, 1024, 2048, and 4096. The value specified must be less than or equal to the receive maximum packet size configured for this line. The special value of X'FFFF' may be specified to use the receive default packet size configured for this line. See Query Line Description (QOLQLIND) API for information on determining the receive maximum packet size and the receive default packet size configured for this line.
Receive window size	BINARY(2)	The receive window size for this connection. The valid values are as follows: 1-7 When modulus 8 is configured for this line. 1-15 When modulus 128 is configured for this line. X'FFFF' Use the receive default window size configured for this line. See Query Line Description (QOLQLIND) API for information on determining the modulus value and the receive default window size configured for this line.
Reserved	CHAR(32)	This field must be set to hexadecimal zeros.
Delivery confirmation support	CHAR(1)	Specifies whether the X.25 delivery confirmation bit (D-bit) should be set on or off in the call accept packet. This also specifies the D-bit support for this connection. The valid values are as follows: X'00' Set the D-bit off in the call accept packet. D-bit will be supported for sending data but not for receiving data. Note: When this value is selected 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' Set the D-bit on in the call accept packet. D-bit will be supported for sending data and for receiving data.
Reserved	CHAR(11)	This field must be set to hexadecimal zeros.
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 used. Note: The system codes the packet and window size facilities in this field, if necessary. The total length of all facilities cannot exceed 109 bytes.
X.25 facilities	CHAR(109)	The X.25 facilities data. Note: The application programmer should not code the facilities for packet or window sizes in this field. By doing so, this field could contain duplicate facilities, which may not be consistently supported by all X.25 networks.
Reserved	CHAR(306)	This field must be set to hexadecimal zeros.
Control information	CHAR(1)	Specifies control information for this connection. This is a bit-sensitive field with bit 0 (leftmost bit) defined for reset support. The remaining bits are undefined and should be set off ('0'B). The valid values for bit 0 are as follows: '0'B Resets are not supported on this connection. When this value is selected, the X'BF00' output operation will not be valid on this connection. Also, a reset indication packet received on this connection will cause the connection to be ended. '1'B Resets are supported on this connection. When this value is selected, the X'BF00' output operation will be valid on this connection. Also, the user-defined communications application program will be required to handle reset indications received on this connection. For example, consider the following values for the control information field: X'00' Resets are not supported on this connection. X'80' Resets are supported on this connection.
Reserved	CHAR(3)	This field must be set to hexadecimal zeros.
Maximum data unit assembly size	BINARY(4)	The maximum number of bytes of user data that can be received in a complete X.25 packet sequence on this connection. If this limit is exceeded, the connection will be ended. Any value between 1024 and 32767 may be used. Notes: If the number of bytes of user data received in a complete X.25 packet sequence is more than can fit into one data unit of the input buffer, the more data indicator field in the corresponding element of the input buffer descriptor will be set to X'01' and the remaining user data will be filled in the next data unit. See Receive Data (QOLRECV) API for more information. There is no limitation on the number of bytes of user data that can be sent in a complete X.25 packet sequence. However, the QOLSEND API may need to called more than once.
Automatic flow control	BINARY(2)	Relates to the amount of data that will be held by user-defined communications support before sending a receive not ready (RNR) packet to the sending system. The recommended value for this field is 32, but any value between 1 and 128 may be used. Note: A receive ready (RR) packet will be sent when the user-defined communications application program receives some of the data.
Reserved	CHAR(30)	This field must be set to hexadecimal zeros.

X.25 Operation X'BF00'

This operation allows an application program to send a reset request packet or a reset confirmation packet on an X.25 SVC or PVC connection. The application must provide the X.25 cause and diagnostic codes required for this operation in the first data unit of the output buffer. The output buffer descriptor is not used.

Information indicating whether a reset request or reset confirmation packet was sent is returned when notification of the completion of the X'BF00' operation is received from the QOLRECV API (operation X'BF01'). This information will be in the diagnostic data parameter of the QOLRECV API. See Receive Data (QOLRECV) API for more information.

A reset confirmation packet will be sent under the following conditions:

• After a reset indication packet has been received on the connection and the application has received it from the QOLRECV API (X'B301' operation, 83/3202 return and reason code)
  
  
• After a reset indication packet has been received on the connection but before the application has received it from the QOLRECV API
  
  
• When a reset indication packet is received on the connection at the same time the X'BF00' output operation is issued

  This is known as a reset collision. In this case, user-defined communications support will discard the reset indication and, therefore, the application program will not receive it from the QOLRECV API. However, the cause and diagnostic codes from the reset indication are returned in the diagnostic data parameter of the QOLRECV program when the application receives notification of the completion of the X'BF00' operation. See Receive Data (QOLRECV) API for more information.

A reset request packet will be sent when none of the above conditions are true.

Notes:

1. Data not yet received by the application program on a connection will not be deleted when a X'BF00' operation is issued on that connection. This data will be received before the notification of the completion of the X'BF00' operation is received from the QOLRECV API (operation X'BF01'). Data received after the notification of the completion of the X'BF00' operation is received should be treated as new data.
   
   
2. The X'BF00' operation is only valid on connections that support resets. See X.25 Operation X'B000' and X.25 Operation X'B400' for more information on specifying reset support.

Data Unit Format-X.25 Operation X'BF00'

The first 2 bytes of the data unit in the output buffer are used for this operation. The first byte contains the X.25 cause code. The second byte contains the X.25 diagnostic code.

Return and Reason Codes

The return and reason codes that can be returned from the QOLSEND API depend on the type of communications line the link is using and on the operation that was requested.

Return and Reason Codes for LAN Operation X'0000'

Return / Reason Code	Meaning	Recovery
0/0	Operation successful.	Continue processing.
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. Then correct the error, enable the link, and try the request again.
80/2401	Output buffer or output 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. Then 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/8000	The amount of user data in a data unit of the output buffer is greater than the maximum frame size allowed on the communications line the link is using. Escape message CPF91F1 will be sent to the application program when this return and reason code is received.	Ensure the link is disabled. Correct the error, 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/1006	Output operation not valid.	Correct the operation parameter. Try the request again.
83/1007	Connection identifier not valid.	Correct the existing provider connection end point ID parameter. Try the request again.
83/1008	Number of data units not valid.	Correct the number of data units parameter. Try the request again.
83/1998	The amount of data in a data unit of the output buffer is not correct.	Correct the amount of user data, or the total amount of generalLAN information, routing information, and user data in the offending data unit. Try the request again.
83/1999	Incorrect data in a data unit of the output buffer. The error offset field in the diagnostic data parameter will point to the incorrect data.	Correct the incorrect data. Try the request again.
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.
83/4001	Link failure, system starting error recovery for this link.	Wait for the link to recover. Try the request again.
83/4003	Error detected by the input/output processor (IOP). The diagnostic data parameter will contain more information on this error.	Correct the error, and try the request again.

General X.25 Return and Reason Codes

The following table shows the return and reason codes that can be received from the QOLSEND API for any requested operation.

Return / Reason Code	Meaning	Recovery
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	Output buffer or output 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 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, 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/1006	Output operation not valid.	Correct the operation parameter. Try the request again.
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.
83/3200	All resources are currently in use by asynchronous operations that have not yet completed.	Wait for at least one of the asynchronous operations to complete. Notification of completion of these operations will be received from the QOLRECV API. Try the request again.

Return and Reason Codes for X.25 Operation X'0000'

Return / Reason Code	Meaning	Recovery
0/0	Operation successful.	Continue processing.
83/1007	Connection identifier not valid.	Correct the existing provider connection end point ID parameter. Try the request again.
83/1008	Number of data units not valid.	Correct the number of data units parameter. Try the request again.
83/1997	The amount of user data in a data unit of the output buffer is not a multiple of the negotiated transmit packet size, and the more data indicator in the corresponding element of the output buffer descriptor is set to X'01'.	Correct the amount of user data in the offending data unit. Try the request again.
83/1998	The amount of user data in a data unit of the output buffer is not correct.	Correct the amount of user data in the offending data unit. Try the request again.
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). 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.	Wait to receive notification from the QOLRECV API indicating this condition (X'B301' operation, 83/3202 return and reason code). Issue the X'BF00' output operation to send a reset confirmation packet.
83/3205	Connection not in a valid state.	Ensure the connection is in a valid state for this operation. Try the request again.
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' or X'B311' operation, 83/4001 return and reason code). 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). Issue the X'B100' output operation to end the connection.
83/4003	Data not sent. Error detected by input/output processor.	Try the request again. If the error persists, use the ANZPRB command to analyze and report the problem.

Return and Reason Codes for X.25 Operation X'B000'

Return / Reason Code	Meaning	Recovery
0/0	Operation initiated.	Wait for notification of the completion of the X'B000' operation from the QOLRECV API (X'B001' operation).
83/4005	All connections are currently in use.	Wait for a connection to become available and try the request again.

Return and Reason Codes for X.25 Operation X'B100'

Return / Reason Code	Meaning	Recovery
0/0	Operation initiated.	Wait for notification of the completion of the X'B100' operation from the QOLRECV API (X'B101' operation).
83/1007	Connection identifier not valid.	Correct the existing provider connection end point ID parameter. Try the request again.
83/3205	Connection not in a valid state.	Ensure the connection is in a valid state for this operation. Try the request again.

Return and Reason Codes for X.25 Operation X'B110'

Return / Reason Code	Meaning	Recovery
0/0	Operation initiated.	Wait for notification of the completion of the X'B110' operation from the QOLRECV API (X'B111' operation).

Return and Reason Codes for X.25 Operation X'B400'

Return / Reason Code	Meaning	Recovery
0/0	Operation successful.	Continue processing.
83/1007	Connection identifier not valid.	Correct the existing provider connection end point ID parameter. Try the request again.
83/1999	Incorrect data in a data unit of the output buffer. The error offset field in the diagnostic data parameter will point to the incorrect data.	Correct the incorrect data. Try the request again.
83/3205	Connection not in a valid state.	Ensure the connection is in a valid state for this operation. Try the request again.
83/4001	Link failure, system starting error recovery for this link.	Issue the X'B100' output operation to end the connection.
83/4004	Inbound call timed out.	Issue the X'B100' output operation to end the connection.

Return and Reason Codes for X.25 Operation X'BF00'

Return / Reason Code	Meaning	Recovery
0/0	Operation initiated.	Wait for notification of the completion of the X'BF00' operation from the QOLRECV API (X'BF01' operation).
83/1007	Connection identifier not valid.	Correct the existing provider connection end point ID parameter. Try the request again.
83/3205	Connection not in a valid state.	Ensure the connection is in a valid state for this operation. Try the request again.

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

---

[ Back to top | Communications APIs | APIs by category ]