Retrieve Request Message (QMHRTVRQ) API
Required Parameter Group:
| 1 | Message information | Output | Char(*) |
| 2 | Length of message information | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Message type | Input | Char(10) |
| 5 | Message key | Input | Char(4) |
| 6 | Error code | I/0 | Char(*) |
Optional Parameter Group 1:
| 7 | Text string to match | Input | Char(*) |
| 8 | Length of text string to match | Input | Binary(4) |
Default Public Authority: *USE
Threadsafe: Yes
The Retrieve Request Message (QMHRTVRQ) API retrieves request messages from the current job's job message queue. Only request messages (commands) that have been received are retrieved; new request messages and all other types of messages are bypassed. One use for this API is in programs that support a retrieve key on a command line to retrieve commands previously run.
Authorities and Locks
None.
Required Parameter Group
- Message information
- OUTPUT; CHAR(*)
The variable that is to receive information about the request message. The minimum size for this area is 8 bytes. If the size of this area is smaller than the available message information, the API returns only the data that the area can hold. If no request message could be retrieved from the job message queue, no error is returned. (For example, there are no request messages prior to or after the one identified by the message key passed in.) Instead, bytes available is set to 0 to indicate no message was found.
- Length of message information
- INPUT; BINARY(4)
The size of the area to contain the message information, in bytes. The minimum size is 8. If this value is larger than the actual size of the storage allocated for the message information parameter, the result may not be predictable.
- Format name
- INPUT; CHAR(8)
The format of the message information to be returned.
Valid formats are:
RTVQ0100 Basic request message information. RTVQ0200 All request message information.
- Message type
- INPUT; CHAR(10)
The message to be retrieved.
The valid values follow:
*FIRST Retrieve the first request message in the current job. *LAST Retrieve the last request message in the current job. *NEXT Retrieve the request message after the message indicated by the message key parameter. Message key is required when *NEXT is used. *PRV Retrieve the request message before the message indicated by the message key parameter. Message key is required when *PRV is used. *MATCH Retrieve the most recent request message that begins with the text specified in the text string to match parameter. Text string to match is required when *MATCH is used. *MATCHPRV Retrieve the request message that begins with the text specified in the text string to match parameter and is before the message indicated by the message key parameter. Message key and text string to match are required when *MATCHPRV is used.
- Message key
- INPUT; CHAR(4)
A value must be specified for this parameter when the message type parameter is *NEXT, *PRV or *MATCHPRV and is used to retrieve the request message after or before the message with this key. This message key need not refer to a message on the job message queue. The search begins with the message on the queue that has the key closest to this value. This value must be blank when the message type parameter is *FIRST, *LAST or *MATCH.
- Error code
- I/O; CHAR(*)
The structure in which to return error information. For the format of the structure, see Error code parameter.
Optional Parameter Group 1
- Text string to match
- INPUT; CHAR(*)
Specifies a text string to be used to find a request that begins with the specified text. Before the specified text is compared to the requests in the job, both the specified text and the request in the job will be converted to uppercase.
- Length of text string to match
- INPUT; BINARY(4)
The size of the text string to match, in bytes. If this value is larger than the actual size of the storage allocated for the text string to match parameter, the result may not be predictable.
RTVQ0100 Format
The following table describes the information that is returned in the message information parameter for the RTVQ0100 format. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(4) | Message key |
| 12 | C | CHAR(20) | Reserved |
| 32 | 20 | BINARY(4) | Length of request message text returned |
| 36 | 24 | BINARY(4) | Length of request message text available |
| 40 | 28 | CHAR(*) | Request message text |
RTVQ0200 Format
The following table describes the information that is returned in the message information parameter for the RTVQ0200 format. For detailed descriptions of the fields, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(4) | Message key |
| 12 | C | CHAR(10) | Program name or ILE service program name |
| 22 | 16 | CHAR(1) | Call stack entry type |
| 23 | 17 | CHAR(10) | Module name |
| 33 | 21 | CHAR(256) | Procedure name |
| 289 | 121 | CHAR(11) | Reserved |
| 300 | 12C | BINARY(4) | Offset to long procedure name |
| 304 | 130 | BINARY(4) | Length of long procedure name |
| 308 | 134 | BINARY(4) | Length of request message text returned |
| 312 | 138 | BINARY(4) | Length of request message text available |
| 316 | 13C | CHAR(*) | Request message text |
| CHAR(*) | Long procedure name | ||
Field Descriptions
Bytes available. The length of all data available to return. All available data is returned if enough space is provided.
Bytes returned. The length of all data actually returned. If the data is truncated because the length of message information parameter did not specify an area large enough to hold the data, this value is less than bytes available. When no request messages could be retrieved from the job message queue, the following occurs:
- The value of the bytes returned field is set to 8.
- The value of the bytes available field is set to 0.
- The remaining fields are unchanged.
Call stack entry type. The type of call stack entry receiving the message.
The possible values follow:
| 0 | The receiving call stack entry is an original program model (OPM) program. |
| 1 | The receiving call stack entry is a procedure within an ILE program, and the procedure name is up to and including 256 characters in length. |
| 2 | The receiving call stack entry is a procedure within an ILE program, and the procedure name is 257 through 4096 characters in length. For this type, the procedure name field is blank and the name can be obtained from the long procedure name. |
Length of long procedure name. The length of the procedure name, in bytes. If the message was sent to an original program model (OPM) program, this field is zero.
Length of request message text available. The length of all available request message text, in bytes.
Length of request message text returned. The actual length of data in the request message text field. If the returned length is equal to the available length, all request message text was returned. If the message information parameter is not sufficiently large to hold all the text, the returned length is less than the available length and the text is truncated.
Long procedure name. The complete procedure name that received the message. A nested procedure name has each procedure name separated by a colon. The outermost procedure name is identified first followed by the procedures it contains. The innermost procedure is identified last in the string.
If the message was sent to an OPM program, this field is not used. The offset to long procedure name field and the length of long procedure name field are zero.
Message key. The key to the request message retrieved. This value can be used on subsequent calls to this API using *NEXT or *PRV in the message type parameter. This retrieves the next or previous request message on the job message queue. It can also be used on the Receive Program Message (QMHRCVPM) API to get more information about the request message.
Module name. The name of the module that contains the ILE procedure receiving the message. If the message was sent to an OPM program, this field is blank.
Offset to long procedure name. The offset to the procedure name, in bytes. If the message was sent to an OPM program, this field is zero. If the message information parameter is not large enough to contain any of the long procedure name field, this offset is set to zero.
Procedure name. The name of the ILE procedure receiving the message. When the call stack entry type is 0 or 2, this field is blank. A nested procedure name has each procedure name separated by a colon. The outermost procedure name is identified first followed by the procedures it contains. The innermost procedure is identified last in the string.
Program name or ILE service program name. The name of the program receiving the request message, or the name of the ILE program that contains the procedure receiving the message.
Request message text. The text of the request message. If you are retrieving CL commands, the maximum length of a CL command is 6000 bytes.
Reserved. An ignored field.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24AF E | Message key not allowed with message type specified. |
| CPF24A7 E | Value for the length of message information not valid. |
| CPF24B3 E | Message type &1 not valid. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF24DC E | Text string to match required with specified message type. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V2R2