INQUIRE TDQUEUE

Retrieve information about a transient data queue.

Read syntax diagramSkip visual syntax diagramINQUIRE TDQUEUE
 
>>-INQUIRE TDQUEUE(data-value)---------------------------------->
 
   .-----------------------------.
   V                             |
>----+-------------------------+-+-----------------------------><
     +-ATIFACILITY(cvda)-------+
     +-ATITERMID(data-area)----+
     +-ATITRANID(data-area)----+
     +-ATIUSERID(data-area)----+
     +-BLOCKFORMAT(cvda)-------+
     +-BLOCKSIZE(data-area)----+
     +-DATABUFFERS(data-area)--+
     +-DDNAME(data-area)-------+
     +-DISPOSITION(cvda)-------+
     +-DSNAME(data-area)-------+
     +-EMPTYSTATUS(cvda)-------+
     +-ENABLESTATUS(cvda)------+
     +-ERROROPTION(cvda)-------+
     +-INDIRECTNAME(data-area)-+
     +-INDOUBT(cvda)-----------+
     +-INDOUBTWAIT(cvda)-------+
     +-IOTYPE(cvda)------------+
     +-MEMBER(data-area)-------+
     +-NUMITEMS(data-area)-----+
     +-OPENSTATUS(cvda)--------+
     +-PRINTCONTROL(cvda)------+
     +-RECORDFORMAT(cvda)------+
     +-RECORDLENGTH(data-area)-+
     +-RECOVSTATUS(cvda)-------+
     +-REMOTENAME(data-area)---+
     +-REMOTESYSTEM(data-area)-+
     +-REWIND(cvda)------------+
     +-SYSOUTCLASS(cvda)-------+
     +-TRIGGERLEVEL(data-area)-+
     '-TYPE(cvda)--------------'
 

Conditions: ENDCOND, ILLOGIC, NORMAL, NOTAUTH, QIDERR

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

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

A remote queue is one defined on another CICS system. When you inquire about such a queue, the local CICS system returns only the information it maintains locally about the queue: the TYPE (REMOTE), the system on which it is defined (the REMOTESYSTEM value), its name there (REMOTENAME), and whether it is available to applications on the local system (its ENABLESTATUS).

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.

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:
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 executed 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 associated with the queue. If the queue is not intrapartition, or no transaction is defined for it (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:
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 through 32767).
DATABUFFERS(data-area) (extrapartition queues only)
returns the number of buffers (in the range 1 through 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 may refer to a data set name used in the startup JCL.
DISPOSITION(cvda) (extrapartition queues only)
returns a CVDA value indicating the status of the associated data set. CVDA values are:
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.
Start of changeSHAREEnd of change
Start of changeThe 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.
End of change
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 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:
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:
DISABLE PENDING
The queue is currently being disabled.
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 should take if an I/O error is encountered. CVDA values are:
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 that this indirect queue points to. 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 CICS is to take for an in-doubt unit of work (UOW) if the definition for this queue specifies WAIT(YES). CVDA values are:
QUEUE
The UOW is in-doubt and waiting; any locks held by the UOW for this queue remain active until the final state of the UOW is known. This means that 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 in-doubt UOW had issued READQ or DELETEQ requests.
  • WRITEQ if the in-doubt UOW had issued WRITEQ or DELETEQ requests.
  • DELETEQ if the in-doubt UOW had issued READQ, WRITEQ, or DELETEQ requests.
REJECT
The UOW is in-doubt 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 in-doubt unit of work (UOW), which has modified a recoverable queue, should wait for resynchronization with its coordinator to determine whether to commit or backout the changes. CVDA values are:
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 UOW’s transaction definition. See the CICS® Resource Definition Guide for an explanation of the interactions of in-doubt attributes on the TDQUEUE and TRANSACTION definitions.

IOTYPE(cvda) (extrapartition queues only)
returns a CVDA value indicating whether the queue was defined for INPUT, OUTPUT, or RDBACK. CVDA values are:
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:
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 the 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:
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:
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. RECORDLENGTH 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:
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). REMOTENAME 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). REMOTESYSTEM 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:
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 the queue must reach before automatic transaction initiation (ATI) occurs. When the queue reaches this depth, CICS invokes a task to process it automatically. A value of zero means 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:
EXTRA
The queue is extrapartition.
INDIRECT
The queue is indirect.
INTRA
The queue is intrapartition.
REMOTE
The queue is remote.

Conditions

ENDCOND
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.
[[ Contents Previous Page | Next Page Index ]]