DATA_QUEUE_ENTRIES table function

Edit online

The DATA_QUEUE_ENTRIES table function returns one or more messages from the specified data queue. The messages are not removed from the data queue. The message data is returned as character, UTF-8, and binary data.

Distributed data management (DDM) data queues are not supported.

The MESSAGE_DATA, MESSAGE_DATA_UTF8, and MESSAGE_DATA_BINARY columns contain identical values. It is up to the user to determine which data type is most appropriate for working with the result data.

The values returned for the result columns of the table function are closely related to the values returned by the Retrieve Data Queue Message (QMHRDQM) API.

Authorization: The caller must have:

*EXECUTE authority to the library containing the data queue, and
*OBJOPR and *READ authority to the data queue.

The schema is QSYS2.

data-queue

A character or graphic string containing the name of the data queue.

data-queue-library

A character or graphic string containing the name of the library containing the data queue. Can be one of the following special values:

*CURLIB: The job's current library is used.
*LIBL: The library list is used. This is the default.

selection-type

A character string indicating how the messages are to be returned. If this parameter is omitted, ALL is used.

ALL: All messages are to be returned in the order based on the type of data queue. FIFO queues are returned in FIFO order, LIFO queues are returned in LIFO order, and keyed queues are returned in ascending key order.
FIRST: The first message is to be returned. This option is not allowed for a keyed data queue.
KEY: Messages meeting the key criteria are to be returned. This option is only valid for a keyed data queue.; When this value is specified, key-data and key-order must also be specified.
LAST: The last message is to be returned. This option is not allowed for a keyed data queue.
REVERSE: All messages are to be returned in reverse order of the type of data queue. For example, LIFO queues are returned in FIFO order. This option is not allowed for a keyed data queue.

key-data

A character string containing the data to use as the key for receiving a message from the data queue. This parameter is required for a keyed data queue. It must not be specified for a non-keyed data queue.

The length of key-data must be the length specified on the KEYLEN parameter on the Create Data Queue (CRTDTAQ) command. The KEY_LENGTH column of the QSYS2.DATA_QUEUE_INFO view contains this value.

When this parameter is specified, key-order must also be specified.

key-order

The comparison criteria between the keys of messages on the data queue and the key-data parameter. Valid values are:

EQ: All messages with a key equal to key-data are to be returned.
GE: All messages with a key greater than or equal to key-data are to be returned.
GT: All messages with a key greater than key-data are to be returned.
LE: All messages with a key less than or equal to key-data are to be returned.
LT: All messages with a key less than key-data are to be returned.
NE: All messages with a key not equal to key-data are to be returned.

This parameter is ignored if key-data is not specified.

The result of the function is a table containing one or more rows with the format shown in the following table. If no messages are selected, no rows are returned. All the columns are nullable.

Table 1. DATA_QUEUE_ENTRIES table function
Column Name	Data Type	Description
ORDINAL_POSITION	INTEGER	The relative position of this row in the result data set.
DATA_QUEUE_LIBRARY	VARCHAR(10)	The library in which the data queue was found.
DATA_QUEUE	VARCHAR(10)	The name of the data queue.
MESSAGE_DATA	CLOB(64512)	The message received from the data queue as character data.
MESSAGE_DATA_UTF8	CLOB(64512) CCSID 1208	The message received from the data queue represented as character data in CCSID 1208.
MESSAGE_DATA_BINARY	BLOB(64512)	The message received from the data queue in binary form. This is the raw form of the data.
KEY_DATA	VARCHAR(256)	For a keyed data queue. the key value of the returned message. This is the actual key value, which could be different than the key-data parameter value. Contains the null value if this is not a keyed data queue.
MESSAGE_ENQUEUE_TIMESTAMP	TIMESTAMP(0)	The date and time that the message was placed on the data queue.
SENDER_JOB_NAME	VARCHAR(28)	The qualified job name of the sender. Contains the null value if no sender information is available for the message.
SENDER_CURRENT_USER	VARCHAR(10)	The current user profile of the sender. Contains the null value if no sender information is available for the message.

Example

Look at all the messages in data queue DQ1 in TESTLIB.

SELECT * FROM TABLE(QSYS2.DATA_QUEUE_ENTRIES(
                                             DATA_QUEUE => 'DQ1', 
                                             DATA_QUEUE_LIBRARY => 'TESTLIB'))
  ORDER BY ORDINAL_POSITION;