Retrieve Request Message (QMHRTVRQ) API

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.

Message key

INPUT; CHAR(4)

A value must be specified for this parameter when the message type parameter is *NEXT or *PRV 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 or *LAST.

Error code

I/O; CHAR(*)

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

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.

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.

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:

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