SET TDQUEUE

Change the attributes of a transient data queue.

SET TDQUEUE

Conditions: INVREQ, IOERR, NOTAUTH, QIDERR, USERIDERR

This command is threadsafe.

For more information about the use of CVDAs, see CICS-value data areas (CVDAs).

Description

The SET TDQUEUE command allows you to change some attributes of a transient data queue.

Transient data queues, also called destinations, are defined in TDQUEUE resource definitions. There are two basic types: intrapartition and extrapartition. Intrapartition queues are managed and stored entirely by CICS, and are eligible for automatic task initiation (ATI), the facility that CICS provides for scheduling tasks automatically. For a transient data queue, ATI is governed by the value specified on the TRIGGERLEVEL option. If the value is nonzero, CICS automatically creates a task to process the queue when the number of items on the queue reaches this trigger level. A value of zero exempts the queue from ATI.

An extrapartition queue is an MVS™ sequential data set (or a spool file). Extrapartition queues are not subject to ATI.

There are two other types of queue: indirect and remote, both of which point to one of the basic types. You cannot modify the definition of either with a SET TDQUEUE command, however. (See the INQUIRE TDQUEUE command for more information about these queues.)

You cannot alter the following parameters unless the queue is fully disabled:

ATIFACILITY
ATITERMID
ATITRANID.
ATIUSERID

To disable a transient data destination, the queue must not currently be in use. If it is in use, the queue enters a “disable pending” state. The last unit of work (UOW) to use the queue fully disables it. The parameters TRIGGERLEVEL, OPENSTATUS, and ENABLESTATUS can be altered regardless of whether the queue is enabled or disabled. The value of the ENABLESTATUS parameter cannot be altered while a queue is in a “disable pending” state.

A transient data queue cannot be disabled while it is in use, or while tasks are waiting to use it.

Indirect and remote queues can be disabled at any time because they have no concept of being “in use”.

If tasks are waiting to use an extrapartition queue, a physically recoverable queue, or a non-recoverable intrapartition queue, and an attempt is made to disable the queue, the queue enters a “disable pending” state. The last task to use the extrapartition queue fully disables it.

If an attempt is made to disable a logically recoverable intrapartition TD queue when there are UOWs enqueued upon it, the queue enters a “disable pending” state. The last UOW to obtain the enqueue fully disables the queue. If a UOW has updated a logically recoverable queue and suffers an indoubt failure, the queue cannot be disabled until the indoubt failure has been resolved.

If a UOW owns an enqueue on a queue that is in a “disable pending” state, it is allowed to continue making updates.

When a queue is in a “disable pending” state, no new tasks can alter the queue’s state or its contents. A disabled response is returned when a READQ, WRITEQ, or DELETEQ request is issued against a destination that is in a “disable pending” state.

Note: If a task updates a logically recoverable transient data queue, and attempts to disable the queue and alter an attribute of the queue (for example, ATITRANID) within the same UOW, the call fails. This is because the UOW is a user of the queue, and the queue enters a “disable pending” state. The SET operation on the queue attribute, in this case, ATITRANID, fails. The queue does not become fully disabled until the UOW commits or backs out at syncpoint. You are recommended to issue an EXEC CICS SYNCPOINT command before attempting to update the queue attribute (ATITRANID) using SET TDQUEUE.

Options

ATIFACILITY(cvda) (intrapartition queues only)

specifies whether the queue has a terminal (or session) associated with it. When ATI occurs, this option determines whether the task that CICS creates to process the queue has a principal facility or not. CVDA values are:

NOTERMINAL: ATI tasks are to execute without a principal facility.
TERMINAL: ATI tasks require the terminal specified in ATITERMID as the principal facility.

ATITERMID(data-value) (intrapartition queues only)

specifies the 4-character name of the terminal or session associated with the queue, if any. When CICS creates a task to process the queue, this terminal is the principal facility if the ATIFACILITY value is TERMINAL.

You can set this value at any time, but it is used only during ATI, and only when ATI tasks are to have a principal facility. When ATIFACILITY is NOTERMINAL, CICS retains but does not use the ATITERMID value, and does not display it in an INQUIRE TDQUEUE command.

ATITRANID(data-value) (intrapartition queues only)

specifies the 4-character identifier of the transaction to be executed when CICS initiates a task automatically to process the queue. This value is used only during ATI. CICS does not check the ATITRANID value when you set it but, when ATI occurs, the created task abends unless the ATITRANID value names a transaction defined at the time. Furthermore, this transaction must not be defined as remote.

ATIUSERID(data-value) (intrapartition queues only)

specifies the 8-byte user identifier associated with the queue, if any. If there is no terminal associated with the queue when ATI occurs, CICS assigns this user to the task it creates to process the queue.

You can set this value at any time, but it is used only during ATI, and only when the ATIFACILITY value is NOTERMINAL. When ATIFACILITY is TERMINAL, CICS retains but does not use the ATIUSERID value, and does not display it in an INQUIRE TDQUEUE command.

In addition to the authority checks made for any SET TDQUEUE command, when ATIUSERID is specified, CICS invokes the external security manager to ensure that the user associated with the task issuing the command has authority to act for the user named in ATIUSERID. When the ESM is RACF®, this means that the user associated with the task must be defined as a RACF surrogate for the user in ATIUSERID.

ENABLESTATUS(cvda)

specifies whether the queue can be accessed by applications. CVDA values are:

DISABLED: The queue cannot be accessed by applications. You cannot disable a queue that has suffered an indoubt failure.
ENABLED: The queue can be accessed by applications.

For extrapartition queues, changing the ENABLESTATUS value affects only the availability of the queue; CICS does not open or close the associated data set.

OPENSTATUS(cvda) (extrapartition queues only)

specifies whether the data set associated with the queue is to be open or closed. CVDA values are:

CLOSED: The data set is to be closed.
OPEN: The data set is to be opened.

TDQUEUE(data-value)

specifies the 4-character name of the transient data queue whose attributes you are changing.

TRIGGERLEVEL(data-value) (intrapartition only)

specifies, as a fullword binary value, the number of items that must be on the queue for ATI to occur, or, alternatively, that ATI is not to occur. The number must be in the range 0–32767. If it is zero, ATI does not occur. If it is not zero, when the queue reaches the TRIGGERLEVEL depth CICS creates a task to process it automatically. See also the ATIFACILITY, ATITERMINAL, ATITRANSID, and ATIUSERID options.

Conditions

INVREQ

RESP2 values:

2: TRIGGERLEVEL was specified for an extrapartition queue.
3: The TRIGGERLEVEL value is not in the range 0–32767.
4: ATITERMID was specified for an extrapartition queue.
5: ATITRANID was specified for an extrapartition queue.
6: ATIFACILITY was specified for an extrapartition queue.
7: ATIFACILITY has an invalid CVDA value.
8: OPENSTATUS has an invalid CVDA value.
9: OPENSTATUS was specified for an intrapartition queue.
10: ENABLESTATUS has an invalid CVDA value.
12: The queue is remote.
13: The queue is indirect.
16: OPENSTATUS was specified, but the JCL DDNAME to which the queue definition points was not found.
18: SET not possible because the queue was not closed.
19: ATIUSERID was specified for an extrapartition queue.
20: The ESM interface is not initialized.
21: CICS has received an unknown response from the ESM.
22: The ESM did not respond.
30: Disabled pending condition.
31: SET not possible because the queue was not disabled.
35: SET not possible because the queue is indoubt.
40: SET not possible because the queue is CXRF.

IOERR

RESP2 values:

14: An error occurred opening or closing the data set associated with the queue.
17: The queue cannot be set CLOSED because there is no space in the associated data set.

NOTAUTH

RESP2 values:

23: The user named on the ATIUSERID option is not authorized.
24: The user named in ATIUSERID has been revoked.
25: During SECLABEL processing by the external security manager, an error occurred. For information about security labels, see the RACF Security Administrator's Guide
27: The user named in the ATIUSERID option is not allowed to access the queue.
100: The user associated with the issuing task is not authorized to use this command.
101: The user associated with the issuing task is not authorized to access this particular resource in the way required by this command.
102: The user associated with the issuing task is not an authorized surrogate for the user specified in ATIUSERID.

QIDERR

RESP2 values:

1: The queue cannot be found.

USERIDERR

RESP2 values:

28: The user named in ATIUSERID is not known to the ESM.