RECEIVE_DATA_QUEUE table function
The RECEIVE_DATA_QUEUE table function returns a message from the specified 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.
- *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.
- 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.
- 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
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.
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'));