Clear Data Queue (QCLRDTAQ) API

  Required Parameter Group:

  Optional Parameter Group:

  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.

The QSYS2.CLEAR_DATA_QUEUE procedure can be used as an alternative to this API. See CLEAR_DATA_QUEUE procedure for more information.

Authorities and Locks

Data Queue Authority
Data Queue Library Authority
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

The name of the data queue being cleared.

Library name

The name of the library where the data queue resides.

You can use these special values for the library name:

Optional Parameter Group

Key order

The comparison criteria between the keys of messages on the data queue and the key data parameter.

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 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

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

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

API introduced: V1R3

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