RECEIVE_DATA_QUEUE table function

Edit online

The RECEIVE_DATA_QUEUE table function returns a message from the specified data queue, including a DDM data queue. The message data is returned as character, UTF-8, and binary data.

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 of the receive data queue operation.

The values returned for the result columns of the table function are closely related to the values returned by the Receive Data Queue (QRCVDTAQ) 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.

remove

A character or graphic string indicating whether the message is to be removed from the data queue after it is received. For a DDM data queue, YES must be specified.

NO: The message is not removed from the data queue.
YES: The message is removed from the data queue. This is the default.

wait-time

The amount of time to wait, in seconds and milliseconds, if no entries exist on the data queue. The value can be from -99999 to 99999.000.

Any value less than zero indicates to wait forever.
A value of zero means to continue processing immediately. This is the default.
A positive value indicates the length of time to wait. The milliseconds part of the time is ignored for any value over 100 and for DDM data queues.

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. When the system searches for the requested key, the entries are searched in ascending order from the lowest value key to the highest value key until a match is found. If there are entries with duplicate keys, the entry that was put on the queue first is received. Valid values are:

EQ: Equal
GE: Greater than or equal
GT: Greater than
LE: Less than or equal
LT: Less than
NE: Not equal

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

The result of the function is a table containing one row or no rows with the format shown in the following table. All the columns are nullable.

Table 1. RECEIVE_DATA_QUEUE table function
Column Name	Data Type	Description
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.
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

Get the message from data queue DQ1 in TESTLIB with key 456.

SELECT * FROM TABLE(QSYS2.RECEIVE_DATA_QUEUE(
                                        DATA_QUEUE => 'DQ1', 
                                        DATA_QUEUE_LIBRARY => 'TESTLIB',
                                        KEY_DATA => '456', 
                                        KEY_ORDER => 'EQ'));