| 1 | Qualified data queue name | Input | Char(20) |
| 2 | Requested Changes | Input | Char(*) |
| 3 | Error code | I/O | Char(*) |
The Change Data Queue (QMHQCDQ) API changes the value of one or more attributes of an existing data queue. All attributes of a data queue cannot be changed. This API can only be used with standard data queues, not DDM data queues.
When changing a data queue, a shared update lock will be used. If the lock cannot be obtained, CPF9803 (Cannot allocate object in library) is generated. If any job is using the dequeue (DEQ) MI instruction with a wait value or the Receive Data Queue (QRCVDTAQ) API with a wait value while removing the entry, CPF9503 (Cannot lock data queue) is generated and the request would need to be tried again when the queue is available. After the attribute is changed, the new value will be used for subsequent data queue operations. For example, if the Allocate Object (ALCOBJ) CL command was used to lock a data queue while locks are being enforced, when the data queue is changed to ignore locks, no exception is issued. All data queue operations waiting for a lock on the queue at the time of the change will remain waiting until they get the lock or until they timeout with the CPF9503. Any subsequent data queue operations will no longer perform locking for the queue, so the lock via ALCOBJ is ignored by data queue operations.
The data queue whose description is to be changed. 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 current library for the thread |
| *LIBL | The library list |
The changes to be made to the specified data queue. The information must be in the following format:
The structure in which to return error information. For the format of the structure, see Error code parameter.
The following table shows the format for the variable length record. For a detailed description of each field, see Field Descriptions.
| Offset | Type | Field | |
|---|---|---|---|
| Dec | Hex | ||
| 0 | 0 | BINARY(4) | Key |
| 4 | 4 | BINARY(4) | Length of new value |
| 8 | 8 | CHAR(*) | New value |
If the length of the new value is longer than the allowed length of the key field, the data is truncated to the right. No message is issued.
If the length of the new value is shorter than the allowed length of the key field, the data is padded with blanks to the right. No message is issued.
It is not an error to specify a key more than once. If duplicate keys are specified, the last specified value for that key is used.
Key. Identifies the data queue attribute to be changed. Only certain data queue attributes can be changed. The following table lists the valid key for the data queue attributes that can be changed. It also specifies the type and allowed length for the attribute. For a description of each attribute along with their possible values, see Attribute Descriptions.
| Key | Type | Attribute to change |
|---|---|---|
| 100 | CHAR(1) | Automatic reclaim |
| 200 | CHAR(1) | Enforce data queue locks |
Length of new value. The length of the new value for the attribute to be changed.
New value. The value used for changing the specified data queue attribute.
Automatic reclaim. Whether the data queue resets the amount of storage allocated for the queue when the queue is empty. If the data queue has been extended beyond the initial size specified on the Create Data Queue (CRTDTAQ) command, it is reset back to the initial size on the next and any subsequent receive/dequeue operations that obtain the last remaining entry on the queue.
Possible values are:
| 0 | Storage is not reclaimed. |
| 1 | Storage is reclaimed on subsequent receive/dequeue operations that cause the queue to become empty. The amount of storage allocated will be set to the initial number of entries. |
Enforce data queue locks. Identifies whether 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. Locks can be viewed with the Work with Object Locks (WRKOBJLCK) CL command. When locks are enforced, performance can be impacted due to the additional locking performed by all data queue operations. When data queue locks are being observed, the following lock will be used for each data queue operation:
Possible values 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 value can impact performance due to the additional locking performed for all data queue operations. |
This API can be used in a multithreaded job to change a local data queue, but cannot be used to change a DDM data queue.
There is a possibility of a permanent deadlock when you use this API to change the data queue attributes to enforce data queue locking. If the enforce data queue locking option is turned on, and a thread gets an exclusive thread scoped lock on the queue with the Allocate Object (ALCOBJ) CL command, and then it performs a receive (or dequeue) with a wait and there are no messages that satisfy the receive (or dequeue), then the thread will enter a permanent deadlock waiting for a message. This is a permanent deadlock because no other thread or job will be able to get in to perform a send (or enqueue) because the receive (or dequeue) thread that is waiting is holding the thread scoped exclusive lock that was obtained via ALCOBJ. To recover from the deadlock, cancel the job.
A new failure might occur when using the Change Data Queue (QMHQCDQ) API to change the data queue attributes to enforce data queue locking. This situation can occur when the following is true in thread 1: 1) The Enforce data queue locking option is turned on, 2) the data queue is journaled, and 3) thread 1 performs a send (or enqueue) operation that results in an extend of the data queue (and an internal seize during the extend operation). Meanwhile, thread 2 tries to perform a receive (or dequeue) operation. With this scenario, thread 2 will fail because the data queue lock will conflict with the seize held by thread 1. This failure is a correctable problem. Thread 2 would need to try again the receive (or dequeue) which will no longer conflict with thread 1 when the extend operation completes.
| 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. |
| CPF3C4D E | Length &1 for key &2 not valid. |
| CPF3C81 E | Value for key &1 not valid. |
| CPF3C82 E | Key &1 not valid for API &2. |
| CPF3C88 E | Number of variable length records &1 is not valid. |
| CPF3C90 E | Literal value cannot be changed. |
| CPF3CF1 E | Error code parameter not valid. |
| CPF9503 E | Cannot lock data queue &1 in &2. |
| 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. |
| 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 ]