Receive Data Queue (QRCVDTAQ) API
Required Parameter Group:
| 1 | Data queue name | Input | Char(10) |
| 2 | Library name | Input | Char(10) |
| 3 | Length of data | Output | Packed(5,0) |
| 4 | Data | Output | Char(*) |
| 5 | Wait time | Input | Packed(5,0) |
Optional Parameter Group 1:
| 6 | Key order | Input | Char(2) |
| 7 | Length of key data | Input | Packed(3,0) |
| 8 | Key data | I/O | Char(*) |
| 9 | Length of sender information | Input | Packed(3,0) |
| 10 | Sender information | Output | Char(*) |
Optional Parameter Group 2:
| 11 | Remove message | Input | Char(10) |
| 12 | Size of data receiver | Input | Packed(5,0) |
| 13 | Error code | I/O | Char(*) |
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. The next entry sent to the queue is given to the job with the next highest priority.
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.
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:
*LIBL The library list *CURLIB The job's current library. 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.
When no entries are on the data queue, the wait time parameter (in seconds) specifies the following:
< 0 Waits forever. 0 Continue processing immediately. If no entry exists, the call completes immediately with the length of data parameter set to zero. > 0 The number of seconds to wait. The maximum is 99999 which allows a wait time of approximately 28 hours. Notes: If the wait time value is less than or equal to 2, 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:
GT Greater than LT Less than NE Not equal EQ Equal GE Greater than or equal LE Less than or equal 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.Physical Entry 3-Character Key 1 GGG 2 XXX 3 AAA 4 GGG
- 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:
0 No sender information is returned. 8 Returns only the bytes returned and bytes available fields of the sender information. > 8 Return as much sender information as the length allows.
- 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.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | PACKED(7,0) | Bytes returned |
| 4 | 4 | PACKED(7,0) | Bytes available |
| 8 | 8 | CHAR(10) | Job name |
| 18 | 12 | CHAR(10) | User profile name |
| 28 | 1C | CHAR(6) | Job number |
| 34 | 22 | CHAR(10) | Senders current user profile name. |
| Note: The last four fields, together, combine to make up the sender ID. | |||
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:
*YES The message is removed from the data queue. This is the default value if this parameter is not specified. *NO The message is not removed from the data queue.
- 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.
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.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF2207 E | Not authorized to use object &1 in library &3 type *&2. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF2472 E | Invalid wait time specified. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9501 E | Data queue &1 in &2 requires a key value. |
| CPF9502 E | Key length must be zero for data queue &1 in &2. |
| CPF9503 E | Cannot lock data queue &1 in &2. |
| CPF9504 E | An invalid search order was specified. |
| CPF9505 E | Sender ID length value is not valid. |
| CPF9506 E | Key length must be &3 for data queue &1 in &2. |
| CPF9507 E | Invalid key length specified. |
| CPF9508 E | Invalid sender ID length specified. |
| CPF9509 E | Space access error. |
| CPF9510 E | Operation on DDM data queue &1 in &2 failed. |
| CPF9511 E | Function not supported for DDM data queue &1. |
| CPF9514 E | Value for data length parameter not valid. |
| CPF9515 E | Value for remove message parameter not valid. |
| CPF9523 E | Data queue function not successful. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 D | Cannot allocate object &2 in library &3. |
| CPF9805 E | Object &2 in library &3 destroyed. |
| CPF9807 E | One or more libraries in library list deleted. |
| CPF9808 E | Cannot allocate one or more libraries on library list. |
| CPF9810 E | Library &1 not found. |
| CPF9820 E | Not authorized to use library &1. |
| CPF9830 E | Cannot assign library &1. |
| CPF9872 E | Program or service program &1 in library &2 ended. Reason code &3. |
API introduced: V1R1
[ Back to top | Object APIs | APIs by category ]