| 1 | Receiver variable | Output | Char(*) |
| 2 | Length of receiver variable | Input | Binary(4) |
| 3 | Format name | Input | Char(8) |
| 4 | Qualified data queue name | Input | Char(20) |
The Retrieve Data Queue Description (QMHQRDQD) API retrieves the description and attributes of a data queue. Examples include the number of entries currently on the data queue, the text description of the data queue, whether the queue includes sender ID information, and whether the data queue is keyed.
The attributes of a distributed data management (DDM) data queue can be retrieved with this 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.
The receiver variable that receives the information requested. You can specify the size of the area to be smaller than the format requested as long as you specify the length parameter correctly. As a result, the API returns only the data that the area can hold.
The length of the receiver variable provided. The length of receiver variable parameter may be specified up to the size of the receiver variable specified in the user program. If the length of receiver variable parameter specified is larger than the allocated size of the receiver variable specified in the user program, the results are not predictable. The minimum length is 8 bytes.
The format of the data queue description to be returned.
The valid format names are:
| RDQD0100 | Basic data queue description. |
| RDQD0200 | DDM data queue description. This is valid for DDM data queues only. |
The data queue whose description is to be returned. The first 10 characters contain the data queue name, and the second 10 characters contain the data queue library name.
You can use these special values for the library name:
| *CURLIB | The job's current library |
| *LIBL | The library list |
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 scenario:
If, a job references a 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.
The actual name of the data queue and the library in which it is found are returned by this API.
The following table shows the information placed in the receiver variable parameter for the RDQD0100 format. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | BINARY(4) | Message length |
| 12 | C | BINARY(4) | Key length |
| 16 | 10 | CHAR(1) | Sequence |
| 17 | 11 | CHAR(1) | Include sender ID |
| 18 | 12 | CHAR(1) | Force indicator |
| 19 | 13 | CHAR(50) | Text description |
| 69 | 45 | CHAR(1) | Type of data queue |
| 70 | 46 | CHAR(1) | Automatic Reclaim |
| 71 | 47 | CHAR(1) | Enforce data queue locks |
| 72 | 48 | BINARY(4) | Number of messages |
| 76 | 4C | BINARY(4) | Number of entries currently allocated |
| 80 | 50 | CHAR(10) | Data queue name used |
| 90 | 5A | CHAR(10) | Data queue library used |
| 100 | 64 | BINARY(4) | Maximum number of entries allowed |
| 104 | 68 | BINARY(4) | Initial number of entries |
| 108 | 6C | BINARY(4) | Maximum number of entries specified |
| 112 | 70 | CHAR(8) | Last reclaim date and time |
The following table shows the information placed in the receiver variable parameter for the RDQD0200 format. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Bytes returned |
| 4 | 4 | BINARY(4) | Bytes available |
| 8 | 8 | CHAR(10) | APPC device description |
| 18 | 12 | CHAR(8) | Mode |
| 26 | 1A | CHAR(8) | Remote location name |
| 34 | 22 | CHAR(8) | Local location name |
| 42 | 2A | CHAR(8) | Remote network identifier |
| 50 | 32 | CHAR(10) | Remote data queue name |
| 60 | 3C | CHAR(10) | Remote data queue library name |
| 70 | 46 | CHAR(10) | Data queue name used |
| 80 | 50 | CHAR(10) | Data queue library used |
| 90 | 5A | CHAR(18) | Relational database name |
APPC device description. The name of the APPC device description on the source system that is used with this DDM data queue. The special value *LOC can be returned. This is the name that was specified on the DEV parameter of the CRTDTAQ command. This will be blank for RDB type DDM data queues.
Automatic reclaim. Whether or not the data queue has the amount of storage allocated for the queue reclaimed when the queue is empty.
Possible values returned are:
| 0 | Storage is not reclaimed. |
| 1 | Storage is reclaimed when the queue is empty. The amount of storage allocated will be set to the initial number of entries. |
This will be blank for a DDM data queue.
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.
Data queue library used. The library in which the data queue is found. If *LIBL or *CURLIB is specified for the library name, this field is the actual name of the library in which the data queue was found. If a specific library (not *LIBL or *CURLIB) is specified, and the data queue is moved from that library to a different library after this job first accessed the data queue, this will be set to the name of the library in which the data queue currently exists.
Data queue name used. The name of the data queue. This will be the same as the name specified unless the data queue was renamed after this job first accessed the data queue.
Enforce data queue locks. Identifies whether or not IBM-supplied data queue operations will enforce a lock on the data queue. This attribute cannot be specified on the Create Data Queue (CRTDTAQ) CL Command. The default when a data queue is created is for locks to be ignored. A data queue can be locked with the Allocate Object (ALCOBJ) CL Command. When locks are enforced, performance can be degraded due to the additional locking performed by all data queue operations.
Possible values returned are:
| 0 | Locks on the data queue are ignored by IBM-supplied data queue operations. |
| 1 | Locks on the data queue are enforced by IBM-supplied data queue operations. |
This will be blank for a DDM data queue.
Force indicator. Whether or not the data queue is forced to auxiliary storage when entries are sent or received for the specified data queue.
Possible values returned are:
| Y | The data queue is forced to auxiliary storage after entries are sent or received. |
| N | The data queue is not forced to auxiliary storage after entries are sent or received. |
This will be blank for a DDM data queue.
Include sender ID. If the queue was created to include the sender ID with sent messages.
Possible values returned are:
| Y | The sender ID is included when data is sent to the data queue. |
| N | The sender ID is not included when data is sent to the data queue. |
This will be blank for a DDM data queue.
Initial number of entries. The number of messages that will fit into the storage allocated for the data queue when it is created or when it is automatically reclaimed. This will be 0 for a DDM data queue.
Key length. If the specified data queue was created as a keyed type, this field contains the length, in bytes, of the message reference key. Values range from 1 to 256. If the specified queue is not a keyed queue or is a DDM data queue, the value is 0.
Last reclaim date and time. The date and time that the last automatic reclaim was done. Its format is a system time stamp (*DTS). The Convert Date and Time Format (QWCCVTDT) API can be used to convert this time stamp to a character format. This will be hex zeroes for a DDM data queue or when no reclaim has occurred for a standard data queue.
Local location name. The name of the local location. The special values *LOC and *NETATR can be returned. This is the name that was specified on the LCLLOCNAME parameter of the CRTDTAQ command. This will be blank for RDB type DDM data queues.
Maximum number of entries allowed. The maximum number of messages that will fit into the data queue when it is full. This will be 0 for a DDM data queue.
Maximum number of entries specified. The maximum number of messages that was specified on the SIZE keyword of the CRTDTAQ command. This will be 0 for a DDM data queue. This will be set to -1 for data queues created prior to release V4R5M0, when support for the SIZE keyword was added to the CRTDTAQ command.
The number of entries specified or one of the following special values will be returned:
| -1 | *MAX16MB was specified for the data queue size. |
| -2 | *MAX2GB was specified for the data queue size. |
Message length. The maximum length allowed for messages. The is the value that was specified with the MAXLEN keyword on the CRTDTAQ command. This will be 0 for a DDM data queue.
Mode. The mode name used with the remote location name to communicate with the target system. The special value *NETATR can be returned. This is the name that was specified on the MODE parameter of the CRTDTAQ command. This will be blank for RDB type DDM data queues.
Number of entries currently allocated. The number of entries that will fit into the data queue before it is extended. When the queue is extended, additional storage is allocated for the queue. The data queue can be extended until it reaches the value for the maximum number of entries allowed. This will be 0 for a DDM data queue.
Number of messages. The number of messages currently on the data queue. This will be 0 for a DDM data queue.
Relational database name. The name of the relational database entry that identifies the target system or target ASP group. This field will be set to blanks unless the data queue is an RDB type DDM data queue. This is the name that was specifed on the RDB parameter of the CRTDTAQ command.
Remote data queue library name. The name of the library for the remote data queue on the target system. The special values *LIBL and *CURLIB can be returned. This is the data queue name that was specified on the RMTDTAQ parameter of the CRTDTAQ command.
Remote data queue name. The name of the remote data queue on the target system. This is the data queue name that was specified on the RMTDTAQ parameter of the CRTDTAQ command.
Remote location name. The name of the remote location that is used with this object. This is the name that was specified on the RMTLOCNAME parameter of the CRTDTAQ command. A special value of *RDB indicates that the remote location information from the relational database entry returned in the relational database entry name field is used to determine the remote system.
Remote network identifier. The remote network identifier in which the remote location used to communcate with the target system. The special values *LOC, *NETATR, and *NONE can be returned. This is the name that was specified on the RMTNETID parameter of the CRTDTAQ command. This will be blank for RDB type DDM data queues.
Sequence. The sequence in which messages can be removed from the queue.
Possible values returned are:
| F | First-in first-out |
| K | Keyed |
| L | Last-in first-out |
This will be blank for a DDM data queue.
Text description. The text description of the data queue. The field contains blanks if no text description was specified when the data queue was created.
Type of data queue. This will be set to one of the following values:
| 0 | The data queue is a standard data queue. |
| 1 | The data queue is a DDM data queue. |
| Message ID | Error Message Text |
|---|---|
| CPF2150 E | Object information function failed. |
| CPF2151 E | Operation failed for &2 in &1 type *&3. |
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C21 E | Format name &1 is not valid. |
| CPF3C24 E | Length of the receiver variable is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF9503 E | Cannot lock data queue &1 in &2. |
| CPF9509 E | Space access error. |
| CPF9516 E | Format &1 not allowed for data queue. |
| CPF9801 E | Object &2 in library &3 not found. |
| CPF9802 E | Not authorized to object &2 in &3. |
| CPF9803 E | Cannot allocate object &2 in library &3. |
| 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. |
[ Back to top | Object APIs | APIs by category ]