Start of change

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.

Authorization: The caller must have:
  • *EXECUTE authority for the library, and
  • *OBJOPR and *READ authority for the *DTAQ
Read syntax diagramSkip visual syntax diagramRECEIVE_DATA_QUEUE( DATA_QUEUE => data-queue,DATA_QUEUE_LIBRARY => data-queue-library,REMOVE => remove,WAIT_TIME => wait-time,KEY_DATA => key-data,KEY_ORDER => key-order )

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 negative value 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'));
End of change