| 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) |
| 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(*) |
| 11 | Remove message | Input | Char(10) |
| 12 | Size of data receiver | Input | Packed(5,0) |
| 13 | Error code | I/O | Char(*) |
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 using this API. This means that you can use this API to receive a message from a data queue that exists on a remote iSeries. However, using this API to receive messages without removing them from the data queue is not supported for DDM data queues.
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.
The name of the data queue to receive the data from.
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 on creating DDM data queues and on DDM target jobs, see Distributed Data Management in the iSeries Information Center.
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.
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.
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.
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:
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:
| Physical Entry | 3-Character Key |
|---|---|
| 1 | GGG |
| 2 | XXX |
| 3 | AAA |
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.
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.
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. |
The sender ID information associated with the received message.
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. | |||
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.
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. |
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.
The structure in which to return error information. For the format of the structure, see Error Code Parameter.
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.
| 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. |
| Top | Object API categories | API by category |