Retrieve Data Queue Message (QMHRDQM) API

The Retrieve Data Queue Message (QMHRDQM) API retrieves one or more messages from a data queue.

The QMHRDQM API allows the retrieval of multiple messages per call. The message selection information parameter allows you to have some control over which messages are returned. The QMHRDQM API can be used to retrieve the following:

• The first or last message of a data queue
• All messages of a data queue
• Selected messages from a keyed data queue

The QMHRDQM API is similar in function to the QRCVDTAQ API. However, the QRCVDTAQ API can remove the received message from the data queue; QMHRDQM API does not remove received messages.

Distributed data management (DDM) data queues are not supported using this API.

Authorities and Locks

Data Queue Authority

*OBJOPR and *READ

Data Queue Library Authority

*EXECUTE

Data Queue Lock

*EXCLRD

Internally, when a job uses API QSNDDTAQ (Send Data Queue), QRCVDTAQ (Receive Data Queue), QMHQRDQD (Retrieve Data Queue Description), or QMHRDQM (Retrieve Data Queue Message), a cache is created to allow faster access to the data queue. An entry in the cache means a user is authorized to the data queue. An entry is added to the cache when a user calling one of the APIs has the required authority to the data queue. An entry is also added to the cache when QSNDDTAQ is called to handle a journal entry for a data queue created with the sender ID attribute set to *YES, and the user requesting the the send function has the required authority to the current profile name in the sender ID information of the journal entry. The data in the cache is used until the job ends, so if you need to immediately change a user's authority to one of these objects, you may need to end that user's jobs.

Required Parameter Group

Receiver variable

OUTPUT; CHAR(*)

The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.

Length of receiver variable

INPUT; BINARY(4)

The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes

Format name

INPUT; CHAR(8)

The format of the data to be placed in the receiver variable.

The valid format names are:

RDQM0100	Retrieved data queue message(s) information.
RDQM0200	Retrieved data queue message(s) information.

The RDQM0200 format differs from RDQM0100 in that when the user requests to retrieve the number of bytes equal to the maximum message entry size specified, this returns the length and data of the message entry that was enqueued instead of the maximum length and data contained in the data queue entry. Therefore, the repeating fields at the end of format RDQM0200 could require less space than format RDQM0100, which uses the same amount of space for each entry retrieved from the queue.

Qualified data queue name

INPUT; CHAR(20)

The data queue whose description is to be returned. The first 10 characters contain the data queue name, and the second 10 characters contain the data queue library name.

You can use these special values for the library name:

*CURLIB	The job's current library
*LIBL	The library list

Note: To improve data queue performance, the data queue APIs remember addressing information for the last data queues used. When this occurs, a specific (not *LIBL or *CURLIB) value is provided for the library name, and the data queue is located in the system auxiliary storage pool (ASP number 1) or a basic user ASP (ASP numbers 2-32). The addressing information for data queues located in independent ASPs is not saved.

Because the addressing information is saved, users of this API should be aware of the following scenario:

If, a job references a data queue, the data queue is moved using the Move Object (MOVOBJ) command or renamed using the Rename Object (RNMOBJ) command, and a new data queue is created with the same name and library as the data queue that was renamed or moved, then, the job continues to reference the original data queue, not the newly created data queue.

Message selection information

INPUT; CHAR(*)

Identifies which message (or messages) you want to retrieve. The layout of this parameter is determined by the value of the message selection information format name.

Length of message selection information

INPUT; BINARY(4)

The length of the message selection information parameter. This must be 8 bytes for RDQS0100 and 16 bytes plus the size of the key for RDQS0200.

Message selection information format name

INPUT; CHAR(8)

The format of the message selection information parameter.

The following format names can be used:

RDQS0100	Format to select messages when using nonkeyed data queues.
RDQS0200	Format to select messages when using keyed data queues.

Error code

I/O; CHAR(*)

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

RDQM0100 Format

The following table lists the fields returned in the RDQM0100 format of the receiver variable parameter. For a detailed description of each field, see Field Descriptions.

RDQM0200 Format

The following table lists the fields returned in the RDQM0200 format of the receiver variable parameter. For a detailed description of each field, see Field Descriptions.

RDQS0100 Format

The following table describes the RDQS0100 format of the Message selection information parameter. This format is used with data queues when selection with keys is not necessary. This format cannot be used with keyed data queues. To retrieve messages using keys and key search order, use format RDQS0200. For a detailed description of each field, see Field Descriptions.

For example, to retrieve the first 10 bytes of the last entry in a data queue specify the following: Parameter seven would contain a format name of 'RDQS0100' and parameter five would consist of a Selection type of 'L', the Reserved field would be blanks, and Number of message text bytes to retrieve would be 10.

RDQS0200 Format

The following table describes the RDQS0200 format of the Message selection information parameter. This format is used to retrieve messages from data queues when selection with keys is necessary. When using this format, all messages satisfying the key search order are returned. For a detailed description of each field, see Field Descriptions.

Note: This format is valid only if the queue was created as a keyed data queue.

Field Descriptions

Actual data queue library name. The library in which the data queue was found. This name is found by searching the library list (*LIBL) or the current library (*CURLIB). If the data queue is in a library other than your current library or library list, it will not be found.

Bytes available. The number of bytes of data available to be returned. All available data is returned if enough space is provided.

Bytes returned. The number of bytes of data returned.

Enqueued message entry length. The number of bytes specified for the message entry length when the entry was placed on the data queue. For a data queue created with SENDERID(*YES), this length is the message entry length specified plus 36 bytes for the sender ID. This is the number of bytes returned in the message text field unless the number of message text bytes to retrieve field is less than this value. In that case, the maximum message text length requested is returned in the message text field.

Entry length available. The total number of bytes available to be retrieved for each message entry.

Entry length returned. The number of bytes retrieved for each message entry.

Key. The key field to be compared with the actual keys of the messages on the data queue.

Key search order. A relational operator specifying the comparison criteria between the message key specified in the RDQS0200 format and the actual keys of messages in the data queue.

Valid values are:

Length of key. The length of the data provided in the key field. This must be a value from 1 through 256.

Maximum message text length available. The maximum message entry size (in bytes) specified when the data queue was created. For a data queue created with SENDERID(*YES), this length is the maximum entry size plus 36 bytes for the sender ID.

Maximum message text length requested. The value specified in the message selection format (RDQS0100 or RDQS0200) for the number of message text bytes to retrieve.

Message enqueue date and time. The date and time that the message was placed on the data queue. Its format is a system time stamp (*DTS). The Convert Date and Time Format (QWCCVTDT) API can be used to convert this time stamp to a character format.

Message key. The key of the message.

Message key length available. The size (in bytes) of the key at the creation time of the data queue.

Message key length returned. The number of bytes retrieved in the message key field.

Message text. The text of the message. For the RDQM0100 format, the number of bytes of message text returned is the maximum message text length requested. For the RDQM0200 format, the number of bytes of message text returned is the minimum of the maximum message text length requested field or the enqueued message entry length field. For example, with RDQM0200, if the maximum message text length requested is less than the enqueued message entry length, some text of the data queue entry would not be returned.

Number of message key bytes to retrieve. The number of message key bytes to return for each data queue entry. The maximum value allowed is 256. If the number of bytes requested exceeds the actual message key length, the key is padded with binary zeros. If the number of message key bytes requested is less than the actual key, the key is truncated.

Number of message text bytes to retrieve. The number of message text bytes to return for each data queue entry. The maximum value allowed is 65536. The maximum message text length returned field is equal to this value. If the number of bytes requested exceeds the actual message text length, the text is padded with binary zeros if the RDQM0100 format is used. If the RQDM0200 format is used, and the actual message text length is less than the number of bytes requested, the number of bytes returned is the actual message length, and no padding is done. If the number of message text bytes is less than the actual text, the message text is truncated.

Number of messages available. The number of messages on the data queue that satisfy the search criteria specified in the Message selection information parameter.

Number of messages returned. The number of messages retrieved.

Offset to first message entry. The offset at which the first message entry begins. If this value is 0, there is no message available.

Offset to next message entry. The offset to the next message entry. If this value is 0, there are no more messages returned.

Reserved. An unused field.

Selection type. Selection type depends on the format used.

For the RDQS0100 format, valid values are:

For the RDQS0200 format, valid values are:

Error Messages