Receive Data Queue (QRCVDTAQ) API


  Required Parameter Group:


  Optional Parameter Group 1:


  Optional Parameter Group 2:


  Optional Parameter Group 3:


  Default Public Authority: *USE

  Threadsafe: Conditional; see Usage Notes.

The Receive Data Queue (QRCVDTAQ) API receives data from the specified data queue.

When more than one program has a receive pending on a data queue at one time, a data entry sent to the data queue is received by only one of the programs. The program with the highest run priority receives the entry.

If the data queue was created with the AUTORCL keyword on the Create Data Queue (CRTDTAQ) command set to *YES, when the queue is empty the storage allocated to the data queue will be reduced to the storage needed for the initial number of entries defined for the data queue.

Distributed data management (DDM) data queues are supported by this API. This means that you can use this API to receive a message from a data queue that exists on a remote system. However, using this API to receive messages without removing them from the data queue is not supported for DDM data queues.

The QSYS2.RECEIVE_DATA_QUEUE table function can be used as an alternative to this API. See RECEIVE_DATA_QUEUE table function for more information.


Authorities and Locks

Data Queue Authority
*OBJOPR and *READ
Data Queue Library Authority
*EXECUTE
Data Queue Lock
*SHRUPD, after the data queue is changed to enforce data queue locks via the Change Data Queue (QMHQCDQ) API.

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

Data queue name
INPUT; CHAR(10)

The name of the data queue to receive the data from.

Library name
INPUT; CHAR(10)

The name of the library where the data queue resides.

You can use these special values for the library name:

Note: To improve data queue performance, the data queue APIs remember addressing information for the last data queues used. This occurs when 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 scenarios.

Scenario 1

If, a job references a library-specific 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.

Scenario 2

If, a job references a library-specific distributed data management (DDM) data queue, the DDM 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 DDM data queue that was renamed or moved, the job continues to reference the original DDM data queue, not the newly created data queue.

Scenario 3

If, a job references a DDM data queue, which starts a DDM target job (DDM conversation) on a remote system that references a library-specific data queue, the data queue on the remote system is moved using the Move Object (MOVOBJ) command or renamed using the Rename Object (RNMOBJ) command, and on the remote system, a new data queue is created with the same name and library as the data queue that was renamed or moved, then, the DDM target job continues to reference the original data queue on the remote system, not the newly created data queue, only when the same DDM target job is used for the subsequent data queue operation. If a new DDM target job is used for the subsequent data queue operation, then the newly created data queue will be used on the remote system.

Note: For more information about creating DDM data queues and about DDM target jobs, see the Distributed database programming topic collection.

Length of data
OUTPUT; PACKED(5,0)

The number of characters received from the data queue. If a time out occurs and no data is received from the data queue, this field is set to zero. The value of this field will never exceed the value specified for the MAXLEN parameter on the Create Data Queue (CRTDTAQ) command.

If the size of the data receiver variable is specified, the data received from the data queue will be truncated if the message is longer than the size of the data receiver variable. The value of this field will be set to the actual length of the data received before it is truncated.

Data
OUTPUT; CHAR(*)

A field of at least the length of the value specified for the MAXLEN parameter on the Create Data Queue (CRTDTAQ) command. This field contains the data received from the data queue.

Note: If the length of this field is larger than the size of the message received, only the number of characters (beginning from the left) as defined by the message received from the data queue are changed. If the length of this field is smaller than the value specified for the MAXLEN parameter on the Create Data Queue (CRTDTAQ) command, and the actual length of this field is not specified in the size of data receiver parameter, unexpected results can occur.

If the length of this field is specified in the size of data receiver parameter, the data received will be truncated if it is longer than the size specified.

Wait time
INPUT; PACKED(5,0)

The amount of time to wait if no entries exist on the data queue. The wait time is in seconds if the wait time units parameter is not specified.

When no entries are on the data queue, the wait time parameter specifies the following:

Notes: If the wait time value is less than or equal to 2 seconds, the job does not leave the activity level (for 2 seconds). This is described as a short wait. For more details on activity levels and implementation applications, see the Work management topic collection.

If a wait time is specified when receiving an entry from a data queue located in an independent auxiliary storage pool (ASP), and the independent ASP is varied off:

  • If *YES is specified or defaulted for the remove message parameter, QRCVDTAQ will end with an exception, and no data will be returned.
  • If *NO is specified for the remove message parameter, QRCVDTAQ will wait for the specified wait time, and no data will be received, even if the independent ASP is varied on again and a message is sent to the data queue.

Optional Parameter Group 1

Key order
INPUT; CHAR(2)

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:

This parameter is ignored if the length of key data is zero. A value of blanks is recommended if the length of key data is zero.

For example, assume a keyed data queue contains these three entries:

If a key order of LE is specified with key data of XXX, entry 3 would be received. If the same values were specified on a subsequent request, entry 1 would be received. Subsequent receives with the same values would receive entry 4 and then entry 2.

Length of key data
INPUT; PACKED(3,0)

The length of the key data parameter. If this parameter is specified, it must be zero for nonkeyed data queues. For keyed data queues it must be equal to the length specified on the KEYLEN parameter on the Create Data Queue (CRTDTAQ) command.

Key data
I/O; CHAR(*)

The data to be used for receiving a message from the data queue. The key of the received message is also returned in this field. It may be different than the key specified to search for. For example, if the key data parameter is set to AA on input with the key order parameter set to GE (greater than or equal to), the key of the record that is actually received could be AB or anything else greater than or equal to AA. The key data parameter is set to the actual key of the received data when the API returns.

Length of sender information
INPUT; PACKED(3,0)

The length of the sender identification parameter.

Valid values are:


Sender information
OUTPUT; CHAR(*)

The sender ID information associated with the received message.


Format of Sender Information

The format and content of the sender information returned is shown in the following table. For a detailed description of each field, see Field Descriptions.

Note: On the CRTDTAQ command, the SENDERID parameter defaults to *NO. To include the sender ID for each data queue entry, the SENDERID parameter must be *YES when the data queue is created.



Field Descriptions

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.

Job name. The name of the job that sent the message.

Job number. The job number of the job that sent the message.

Senders current user profile name. The current user profile name of the job that sent the message.

User profile name. The user profile name of the job that sent the message.


Optional Parameter Group 2

Remove message
INPUT; CHAR(10)

Whether the message is to be removed from the data queue when it is received.

Valid values are:


Size of data receiver
INPUT; PACKED(5,0)

The size of the area to contain the data received from the data queue. If a value of 0 is specified for this parameter, no data will be returned. If a size greater than 0 is specified, the data will be copied into the receiver up to the specified length. If the available data is longer than the length specified, it will be truncated.

If this parameter is not specified, the entire message will be copied into the receiver variable.

Error code
I/O; CHAR(*)

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


Optional Parameter Group 3

Wait time units
INPUT; CHAR(10)

The units of time for the wait time parameter.

Valid values are:


Usage Notes

This API can be used in a multithreaded job to receive messages from a local data queue. It cannot be used in a job that allows multiple threads to receive messages from a DDM data queue.

Application queueing time and resource usage time for data queue usage are recorded only for messages that are received in the initial thread of a job.

Start of changeThis API is not threadsafe for data queues that are replicated with Db2 Mirror.End of change


Error Messages



API introduced: V1R1

[ Back to top | Object APIs | APIs by category ]