Receive Request (QzdmReceiveRequest) API

The Receive Request (QzdmReceiveRequest) API is used to receive a request or a message over an OptiConnect path. A maximum of 32KB of data may be transferred in a single receive request.

Restrictions

The following restrictions apply:

• The OptiConnect QSOC subsystem must be started on both the local and remote systems prior to calling this API.
  
  
• A stream must be opened to the OptiConnect device driver on the local system by using the Open Stream (QzdmOpenStream) API prior to calling this API.
  
  
• A path must be opened to the remote system by using the Open Path (QzdmOpenPath) API prior to calling this API.
  
  
• If the receiving system does not provide a large enough data buffer to receive all of the data, the data that will fit into the data buffer is moved, but the remaining data is truncated. The user must then increase the size of the data buffer and then retry the entire transaction.
  
  
• A maximum of 16 transactions may be in progress for a stream-identifier and path-identifier pair.

Authorities and Locks

Service Program Authority

*EXECUTE

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The receiver variable that is to receive the output control information from the Receive Request (QzdmReceiveRequest) API.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable, in bytes. The length of the receiver variable must be at least equal to or greater than the length of the output format.

Format name of receiver variable

INPUT; CHAR(8)

The format of the information that is returned from the Receive Request (QzdmReceiveRequest) API. The RQRC0100 format is used by this API for the receiver variable. See RQRC0100 Format for more information on the RQRC0100 format.

Request variable

INPUT; CHAR(*)

The request variable structure that describes the input for the Receive Request (QzdmReceiveRequest) API.

Length of request variable

INPUT; BINARY(4)

The length of the request variable, in bytes. The length of the request variable must be at least equal to the length of the input format, and less than or equal to the maximum length of 4KB.

Format name of request variable

INPUT; CHAR(8)

The format of the information that is provided as input for the Receive Request (QzdmReceiveRequest) API. The RQRQ0100 format is used by this API for the request variable. See RQRQ0100 Format for more information on the RQRQ0100 format.

Error code

I/O; CHAR(*)

The structure in which to return error information. For the format of the structure, see Error Code Parameter.

RQRC0100 Format

The following table defines the information returned for Format RQRC0100.

RQRQ0100 Format

The following table defines the information required for Format RQRQ0100.

Field Descriptions

Current output data length. The total data length of the request that was moved to the user's data buffer area. If the current output data length is less than the total request data length, then this indicates that not all of the data was received. It is the responsibility of the user's application program to retry the entire transaction by using a larger data buffer size for the Receive Request (QzdmReceiveRequest) API to receive all of the data.

Data buffer length. The length of the data buffer that is used for receiving data.

Data buffer pointer. The pointer to the data buffer that is used for receiving data.

Maximum response data length. The maximum length that is allowed for the response data. This field is provided by the user as input on the Send Request (QzdmSendRequest) API and indicates the maximum response data length allowed for the Send Response (QzdmSendResponse) API.

Number of output descriptors. The number of output descriptors that are used. An output descriptor describes where the output data may be found. The output descriptor consists of a space pointer to a data buffer and the length of the data buffer. A maximum of three output descriptors may be specified.

Offset to output descriptors. The offset to the output descriptors.

Path identifier. The OptiConnect path that is to be used for communications. This field is provided as output on the Receive Request (QzdmReceiveRequest) API.

Reserved. A reserved space for the purpose of aligning pointer values on a 16-byte boundary. This field must be initialized to binary 0.

Stream identifier. The OptiConnect stream that is used for communications. This field is provided as output on the Open Stream (QzdmOpenStream) API.

Time-out value. A length of time, in milliseconds, to wait for the Receive Request (QzdmReceiveRequest) API to complete. If the Receive Request (QzdmReceiveRequest) API does not complete before the specified time-out value, then the exception CPFADFE is returned. The user should then re-issue the Receive Request (QzdmReceiveRequest) API and specify the same time-out value or an increased time-out value.

The Receive Request (QzdmReceiveRequest) API remains outstanding, and control is not returned to the user application until either of the following occurs:

• The request either completes successfully or unsuccessfully.
• The time-out value has been exceeded.

A value of -1 may be specified, which indicates to wait forever for the Receive Request (QzdmReceiveRequest) API to complete.

Total request data length. The total data length of the request that is available to be received. This field is provided as output on the Receive Request (QzdmReceiveRequest) API.

Transaction identifier. The specific transaction associated with this Receive Request (QzdmReceiveRequest) API. This field is provided as output on the Receive Request (QzdmReceiveRequest) API. This field must then be provided as input on the corresponding Send Response (QzdmSendResponse) API.

Error Messages