Receive Response (QzdmReceiveResponse) API

Required Parameter Group:

1	Receiver variable	Output	Char(*)
2	Length of receiver variable	Input	Binary(4)
3	Format name of receiver variable	Input	Char(8)
4	Request variable	Input	Char(*)
5	Length of request variable	Input	Binary(4)
6	Format name of request variable	Input	Char(8)
7	Error code	I/O	Char(*)

  Library Name / Service Program: QSOC/QZDMMDTA

  Default Public Authority: *EXECUTE

  Threadsafe: No

The Receive Response (QzdmReceiveResponse) API is used to receive an acknowledgement and the response data over an OptiConnect path. A maximum of 32KB of data may be received in a single receive response.

The response data is received into the output buffers, which were previously defined in the output descriptors on the Send Request (QzdmSendRequest) API.

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 Response (QzdmReceiveResponse) 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 Response (QzdmReceiveResponse) API. The RSRC0100 format is used by this API for the receiver variable. See RSRC0100 Format for more information on the RSRC0100 format.
Request variable: INPUT; CHAR(*)
The request variable structure that describes the input for the Receive Response (QzdmReceiveResponse) 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 Response (QzdmReceiveResponse) API. The RSRQ0100 format is used by this API for the request variable. See RSRQ0100 Format for more information on the RSRQ0100 format.
Error code: I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.

RSRC0100 Format

The following table defines the information returned for Format RSRC0100.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(4)	Acknowledgement data
4	4	BINARY(4)	Actual response data length

RSRQ0100 Format

The following table defines the information required for Format RSRQ0100.

Offset		Type	Field
Dec	Hex	Type	Field
0	0	CHAR(16)	Stream identifier
16	10	CHAR(8)	Path identifier
24	18	BINARY(4)	Time-out value
28	1C	CHAR(8)	Transaction identifier

Field Descriptions

Acknowledgement data. The acknowledgement data for the request. This field is provided as input on the Send Response (QzdmSendResponse) API.

Actual response data length. The actual length that was received for the response data. If the response data that was sent from the Send Response (QzdmSendResponse) API is larger than the buffer that was provided with the Send Request (QzdmSendRequest) API, 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 Send Request (QzdmSendRequest) API to receive all of the data with the Receive Response (QzdmReceiveResponse) API.

Path identifier. The OptiConnect path that is used for communications. This field is provided as output on the Open Path (QzdmOpenPath) API.

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 Response (QzdmReceiveResponse) API to complete. If the Receive Response (QzdmReceiveResponse) API does not complete before the specified time-out value, the exception CPFADFE is returned. The user should then re-issue the Receive Response (QzdmReceiveResponse) API and specify the same time-out value or an increased time-out value.

The Receive Response (QzdmReceiveResponse) 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 Response (QzdmReceiveResponse) API to complete.

Transaction identifier. The specific transaction associated with this Receive Response (QzdmReceiveResponse) API. This field is provided as output on the Send Request (QzdmSendRequest) API.

Error Messages

Message ID	Error Message Text
CPF24B4 E	Severe error while addressing parameter list.
CPF3C1D E	Length specified in parameter &1 not valid.
CPF3C21 E	Format name &1 is not valid.
CPF3C90 E	Literal value cannot be changed.
CPF3CF1 E	Error code parameter not valid.
CPF9872 E	Program or service program &1 in library &2 ended. Reason code &3.
CPFADF0 E	The OptiConnect QSOC subsystem must be active.
CPFADF1 E	OptiConnect communication error.
CPFADF3 E	OptiConnect path not valid or closed.
CPFADF5 E	OptiConnect API internal error, function code &1, return code &2.
CPFADF6 E	Request variable not valid, reason code &1.
CPFADFE E	Time-out occurred.
CPFADFF E	Transaction was terminated.

API introduced: V3R7

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