Wait Message (QzdmWaitMessage) API
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 Wait Message (QzdmWaitMessage) API is used to wait for a message on an OptiConnect stream. The message may be a request message, a response message, or a control message.
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.
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 Wait Message (QzdmWaitMessage) 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 Wait Message (QzdmWaitMessage) API. The WMRC0100 format is used by this API for the receiver variable. See WMRC0100 Format for more information on the WMRC0100 format.
- Request variable
- INPUT; CHAR(*)
The request variable structure that describes the input for the Wait Message (QzdmWaitMessage) 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 Wait Message (QzdmWaitMessage) API. The WMRQ0100 format is used by this API for the request variable. See WMRQ0100 Format for more information on the WMRQ0100 format.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
WMRC0100 Format
The following table defines the information returned for Format WMRC0100.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | CHAR(1) | Message type |
WMRQ0100 Format
The following table defines the information required for Format WMRQ0100.
Offset | Type | Field | |
---|---|---|---|
Dec | Hex | ||
0 | 0 | CHAR(16) | Stream identifier |
16 | 10 | BINARY(4) | Time-out value |
Field Descriptions
Message type. The type of message that is received. This field is provided as output on the Wait Message (QzdmWaitMessage) API.
Possible values follow:
1 | Request message |
2 | Response message |
3 | Control message |
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 Wait Message (QzdmWaitMessage) API to complete. If the Wait Message (QzdmWaitMessage) API does not complete before the specified time-out value, the exception CPFADFE is returned. The user should then re-issue the Wait Message (QzdmWaitMessage) API and specify the same time-out value or an increased time-out value.
The Wait Message (QzdmWaitMessage) 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 Wait Message (QzdmWaitMessage) API to complete.
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. |
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. |
API introduced: V3R7