INQUIRE TDQUEUE

Description

The INQUIRE TDQUEUE command retrieves information about a particular transient data queue.

You define transient data queues to CICS using transient data resource definitions. There are two basic types: intrapartition and extrapartition. Intrapartition queues are managed and stored entirely by CICS, and are subject to automatic task initiation (ATI). ATI means that when the number of items on the queue reaches the value in the TRIGGERLEVEL option, CICS automatically creates a task to process the queue.

An extrapartition queue is an MVS™ sequential data set or a spool file. Extrapartition queues are not subject to ATI, and consequently the associated options produce null values. Furthermore, if the data set is not open, CICS might not be able to determine some of the values, such as BLOCKFORMAT and RECORDFORMAT. Null values, explained in Null values, are returned in such cases.

Two other types of queue exist: indirect and remote, both of which point, eventually, to one of the basic types.

An indirect queue points to another queue on the same CICS system, and is essentially an alias for the other queue. When you name an indirect queue in an INQUIRE TDQUEUE command, CICS returns only the TYPE value, which is INDIRECT, and the name of the queue to which the indirect definition points (the INDIRECTNAME value). You need a second INQUIRE TDQUEUE against the INDIRECTNAME value to determine the characteristics of the underlying queue.

Browsing

You can also browse through the transient data queues defined in your system by using the browse options, START, NEXT, and END, on INQUIRE TDQUEUE commands. See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.

The resource signature

You can use this command to retrieve the resource signature fields. You can use these fields to manage resources by capturing details of when the resource was defined, installed, and last changed. For more information, see Auditing resources. The resource signature fields are BUNDLE, CHANGEAGENT, CHANGEAGREL, CHANGETIME, CHANGEUSRID, DEFINESOURCE, DEFINETIME, INSTALLAGENT, INSTALLTIME, and INSTALLUSRID. See Summary of the resource signature field values for detailed information about the content of the resource signature fields.

Options

ATIFACILITY(cvda) (intrapartition queues only)

Returns a CVDA value indicating whether the queue has a terminal (or session) associated with it. If it does, and CICS creates a task to process the queue because its trigger level has been reached, the terminal is assigned as the principal facility of the task. See also the ATITERMID and ATITRANID options. CVDA values are as follows:

NOTAPPLIC

The queue is not intrapartition.

NOTERMINAL

No terminal is associated with the queue.

TERMINAL

A terminal is associated with the queue.

ATITERMID(data-area) (intrapartition queues only)

Returns the 4-character name of the terminal or session associated with the queue, if any. (See the ATIFACILITY option.) Otherwise, blanks are returned.

ATITRANID(data-area) (intrapartition queues only)

Returns the 4-character identifier of the transaction to be run when CICS initiates a task automatically to process the queue. This option applies only to intrapartition queues intended for ATI; for other types of queues, and for intrapartition queues where no transaction has been specified in the queue definition, the value returned is blanks.

ATIUSERID(data-area) (intrapartition queues only)

Returns the 8-byte user identifier associated with the queue. CICS assigns this value to a task that it creates to process the queue if no terminal is associated with the queue. If the queue is not intrapartition, or no transaction is defined for it with the ATITRANID option, blanks are returned.

If the security manager is not active, the value returned is that of the default user ID and not any value that has been included in the installed definition.

BLOCKFORMAT(cvda) (extrapartition queues only)

Returns a CVDA value indicating whether the data set associated with the queue is in blocked record format or not. It applies only to extrapartition queues. CVDA values are as follows:

BLOCKED

The records are blocked.

NOTAPPLIC

The data set is not open or the queue is not an extrapartition queue.

UNBLOCKED

The records are not blocked.

BLOCKSIZE(data-area)

Returns the length of the block in bytes, in the range 1 - 32767.

CHANGEAGENT(cvda)

Returns a CVDA value that identifies the agent that made the last change to the resource definition. The possible values are as follows:

CREATESPI

The resource definition was last changed by an EXEC CICS CREATE command.

CSDAPI

The resource definition was last changed by a CEDA transaction or the programmable interface to DFHEDAP.

CSDBATCH

The resource definition was last changed by a DFHCSDUP job.

DREPAPI

The resource definition was last changed by a CICSPlex SM BAS API command.

SYSTEM

The resource definition was last changed by the CICS or CICSPlex system.

CHANGEAGREL(data-area)

Returns a 4-digit number of the CICS release that was running when the resource definition was last changed.

CHANGETIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource definition was last changed. For more information about the format of the ABSTIME value, see FORMATTIME.

CHANGEUSRID(data-area)

Returns the 8-character user ID that ran the change agent.

DATABUFFERS(data-area) (extrapartition queues only)

Returns the number of buffers, in the range 1 - 255, to be used by the transient data queue.

DDNAME(data-area) (extrapartition queues only)

Returns an 8-character identifier, padded with blanks if necessary, that can refer to a data set name used in the startup JCL.

DEFINESOURCE(data-area)

Returns the 8-character source of the resource definition. The DEFINESOURCE value depends on the CHANGEAGENT value. For more information, see Summary of the resource signature field values.

DEFINETIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource definition was created.

DISPOSITION(cvda) (extrapartition queues only)

Returns a CVDA value indicating the status of the associated data set. CVDA values are as follows:

MOD

The system first assumes that the data set exists. For an existing data set, MOD causes the read/write mechanism to be positioned after the last record in the data set. The read/write mechanism is positioned after the last record each time the data set is opened for output.

If the system cannot find volume information for the data set on the DD statement, in the catalog, or passed with the data set from a previous step, the system assumes that the data set is being created in this job step. For a new data set, MOD causes the read/write mechanism to be positioned at the beginning of the data set.

NOTAPPLIC

The option does not apply because the queue is not open or is not an extrapartition queue.

OLD

The data set existed before this job step.

SHARE

The data set existed before this job step and can be read by other concurrent jobs.

Note: You can use the abbreviation SHR when using CEDA to define this parameter.

DSNAME(data-area) (extrapartition queues only)

Returns a 1- to 44-character name that indicates an associated QSAM data set or DUMMY data set. This data area is blank if SYSOUTCLASS is used.

EMPTYSTATUS(cvda) (extrapartition queues only)

Returns a CVDA value indicating the state of the queue with regard to space. CICS detects a FULL condition only when a task attempts to add a record and there is no space, and detects EMPTY only when a task attempts to read and there are no records. Consequently, a value of NOTEMPTY is returned unless one of these conditions has been detected. EMPTYSTATUS applies only to extrapartition queues. CVDA values are as follows:

EMPTY

The queue is empty.

FULL

The queue is full.

NOTAPPLIC

The option does not apply because the queue is not open or is not extrapartition.

NOTEMPTY

No operation against the queue has indicated that it is either empty or full.

ENABLESTATUS(cvda) (all except indirect queues)

Returns a CVDA value indicating whether the queue can be accessed by applications. For remote queues, this value reflects whether the local CICS will forward commands to access the queue to the remote system or reject them with a DISABLED exception condition; it does not necessarily reflect the state of the queue on the remote system. CVDA values are as follows:

DISABLED

The queue cannot be accessed by applications. For extrapartition queues, this value does not necessarily mean that the associated data set is closed.

DISABLING

The queue is currently being disabled.

ENABLED

The queue can be accessed by applications.

NOTAPPLIC

The queue is indirect.

ERROROPTION(cvda) (extrapartition queues only)

Returns a CVDA value indicating the action that CICS takes if an I/O error is encountered. CVDA values are as follows:

IGNORERR

The block that caused the error is accepted.

SKIP

The block that caused the error is skipped.

INDIRECTNAME(data-area) (indirect queues only)

Returns the 4-character name of the queue to which this indirect queue points. This option applies only to queues defined as indirect; for other types of queues, blanks are returned.

INDOUBT(cvda) (intrapartition queues only)

Returns a CVDA value indicating the action that CICS is to take for an indoubt unit of work (UOW) if the definition for this queue specifies WAIT(YES). CVDA values are as follows:

QUEUE

The UOW is indoubt and waiting; any locks held by the UOW for this queue remain active until the final state of the UOW is known. Tasks are suspended rather than receiving the LOCKED response. When the final state of the UOW is known, any changes that it has made are committed or backed out. Until then, any further requests of the following types that need one of the active locks must wait:

• READQ if the indoubt UOW had issued READQ or DELETEQ requests
• WRITEQ if the indoubt UOW had issued WRITEQ or DELETEQ requests
• DELETEQ if the indoubt UOW had issued READQ, WRITEQ, or DELETEQ requests

REJECT

The UOW is indoubt and waiting, and any locks held by the UOW for this queue are retained until the final state of the UOW is known. When the final state is known, any changes it has made are committed or backed out. Until then, any further requests that need one of the retained locks are rejected, and a LOCKED condition is returned. REJECT causes LOCKED to be raised in exactly the same circumstances as those in which QUEUE causes a transaction to wait.

INDOUBTWAIT(cvda) (intrapartition queues only)

Returns a CVDA value indicating whether an indoubt unit of work (UOW), which has modified a recoverable queue, will wait for resynchronization with its coordinator to determine whether to commit or back out the changes. CVDA values are as follows:

NOWAIT

The UOW is not to wait, and any changes made to recoverable resources are to be backed out or committed, as specified by the ACTION attribute on the transaction resource definition.

WAIT

The UOW is to wait and any action required while waiting is determined by the WAITACTION option.

This parameter overrides the WAIT option defined on the transaction definition of the UOW. See TRANSACTION definition attributes for an explanation of the interactions of indoubt attributes on the TDQUEUE and TRANSACTION definitions.

INSTALLAGENT(cvda)

Returns a CVDA value that identifies the agent that installed the resource. The possible values are as follows:

CREATESPI

The resource was installed by an EXEC CICS CREATE command.

CSDAPI

The resource was installed by a CEDA transaction or the programmable interface to DFHEDAP.

GRPLIST

The resource was installed by GRPLIST INSTALL.

SYSTEM

The resource was installed by the CICS or CICSPlex SM system.

INSTALLTIME(data-area)

Returns an ABSTIME value that represents the time stamp when the resource was installed.

INSTALLUSRID(data-area)

Returns the 8-character user ID that installed the resource.

IOTYPE(cvda) (extrapartition queues only)

Returns a CVDA value indicating whether the queue was defined for INPUT, OUTPUT, or RDBACK. CVDA values are as follows:

INPUT

The queue is defined for input and is read forward.

NOTAPPLIC

The queue is not open or is not an extrapartition queue.

OUTPUT

The queue is defined for output.

RDBACK

The queue is defined for input and is read backward.

MEMBER(data-area) (extrapartition queues only)

Returns the 8-character member name if the queue is a member of a partitioned data set. If not, blanks are returned.

NUMITEMS(data-area) (intrapartition queues only)

Returns a fullword binary field giving the number of items in the queue. A value of -1 is returned if the queue is not intrapartition.

OPENSTATUS(cvda) (extrapartition queues only)

Returns a CVDA value indicating whether the queue is open, closed, or in an intermediate state. CVDA values are as follows:

CLOSED

The queue is closed.

CLOSING

The queue is closing.

NOTAPPLIC

The queue is not extrapartition.

OPEN

The queue is open.

OPENING

The queue is opening.

PRINTCONTROL(cvda) (extrapartition queues only)

Returns a CVDA value indicating the type of print control, if any, defined for the queue. Printer control characters appear in the first position of every record when used. However, CICS does not check this character when records are written to the queue, or remove the character when records are read from the queue; use and enforcement of the printer control conventions are up to the applications using the queue. CVDA values are as follows:

ASACTL

ASA control characters are used.

MCHCTL

Machine control characters are used.

NOCTL

No print control characters are used.

NOTAPPLIC

The queue is not open or is not extrapartition.

RECORDFORMAT(cvda) (extrapartition queues only)

Returns a CVDA value indicating whether the queue has fixed- or variable-length records. CVDA values are as follows:

FIXED

The queue has fixed-length records.

NOTAPPLIC

The queue is not open or is not extrapartition.

VARIABLE

The queue has variable-length records.

RECORDLENGTH(data-area) (extrapartition queues only)

Returns a fullword binary field giving the record length in bytes for queues having fixed-length records, or the maximum record length for queues having variable-length records. The RECORDLENGTH option applies only to extrapartition queues; for others, -1 is returned.

RECOVSTATUS(cvda) (intrapartition queues only)

Returns a CVDA value indicating the type of recovery defined for the queue. Recovery is available only for intrapartition queues. CVDA values are as follows:

LOGICAL

The queue is logically recoverable.

NOTAPPLIC

The queue is not intrapartition.

NOTRECOVABLE

The queue is not recoverable.

PHYSICAL

The queue is physically recoverable.

REMOTENAME(data-area) (remote queues only)

Returns the 4-character name of this queue in the remote CICS region in which the queue is defined (from the RMTNAME option in its definition). The REMOTENAME option applies only to queues defined as remote; for other queues the value returned is blanks.

REMOTESYSTEM(data-area) (remote queues only)

Returns the 4-character name of the CICS region in which the queue is defined (from the SYSIDNT value in its definition). The REMOTESYSTEM option applies only to queues defined as remote; for other queues the value returned is blanks.

REWIND(cvda) (extrapartition queues only)

Returns a CVDA value indicating the disposition of a tape data set. CVDA values are as follows:

LEAVE

The current tape is positioned to the logical end of the data set.

REREAD

The current tape is positioned to reprocess the data set.

SYSOUTCLASS(data-area)

Returns a single character indicating the class attribute of the associated SYSOUT data set or blank if DSNAME is used.

TDQUEUE(data-value)

Specifies the 4-character name of the transient data queue about which you are inquiring.

TRIGGERLEVEL(data-area) (intrapartition only)

Returns a fullword binary field giving the number of items that the queue must reach before automatic transaction initiation (ATI) occurs. When the queue reaches this depth, CICS calls a task to process it automatically. A value of zero means that the queue is not subject to ATI; a value of -1 is returned if the queue is not intrapartition.

TYPE(cvda)

Returns a CVDA value identifying the type of queue. CVDA values are as follows:

EXTRA

The queue is extrapartition.

INDIRECT

The queue is indirect.

INTRA

The queue is intrapartition.

REMOTE

The queue is remote.

Conditions

END

RESP2 values:

2

There are no more resource definitions of this type.

ILLOGIC

RESP2 values:

1

Browse sequence error

NORMAL

RESP2 values:

0

No errors

NOTAUTH

RESP2 values:

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.

QIDERR

RESP2 values:

1

The named queue cannot be found.