| 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(*) |
| 7 | Text string to match | Input | Char(*) |
| 8 | Length of text string to match | Input | Binary(4) |
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.
None.
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.
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.
The format of the message information to be returned.
Valid formats are:
| RTVQ0100 | Basic request message information. |
| RTVQ0200 | All request message information. |
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. |
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.
The structure in which to return error information. For the format of the structure, see Error code parameter.
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.
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.
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 |
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 | ||
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:
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.
| 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. |