Clear Data Queue (QCLRDTAQ) API
Required Parameter Group:
| 1 | Data queue name | Input | Char(10) |
| 2 | Library name | Input | Char(10) |
Optional Parameter Group:
| 3 | Key order | Input | Char(2) |
| 4 | Length of key data | Input | Packed(3,0) |
| 5 | Key data | Input | Char(*) |
| 6 | Error code | I/O | Char(*) |
Default Public Authority: *USE
Threadsafe: Conditional; see Usage Notes.
The Clear Data Queue (QCLRDTAQ) API clears all data from the specified data queue, or clears messages that match the key specification from a keyed data queue.
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 clear a data queue that exists on a remote system. Clearing messages by key 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.
Required Parameter Group
- Data queue name
- INPUT; CHAR(10)
The name of the data queue being cleared.
- 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.
Optional Parameter Group
- Key order
- INPUT; CHAR(2)
The comparison criteria between the keys of messages on the data queue and the key data parameter.
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 If a key order of LT is specified with key data of XXX, entries 1 and 3 would be removed. If a key order of EQ is specified with key data of XXX, entry 2 would be removed.
- 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 either zero or equal to the length specified on the KEYLEN parameter on the Create Data Queue (CRTDTAQ) command. If this parameter is not specified or is zero, all messages will be cleared from the data queue.
- Key data
- INPUT; CHAR(*)
The data to be used for selecting messages to be removed from the data queue.
- 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 clear messages from a local data queue. It cannot be used in a job that allows multiple threads to clear messages from a DDM data queue.
Error Messages
| Message ID | Error Message Text |
|---|---|
| CPF24B4 E | Severe error while addressing parameter list. |
| CPF3C36 E | Number of parameters, &1, entered for this API was not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| 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. |
| CPF9506 E | Key length must be &3 for data queue &1 in &2. |
| CPF9507 E | Invalid key length specified. |
| CPF9510 E | Operation on DDM data queue &1 in &2 failed. |
| CPF9511 E | Function not supported for DDM data queue &1. |
| 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. |
| 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: V1R3
[ Back to top | Object APIs | APIs by category ]