INQUIRE TDQUEUE
Retrieve information about a transient data queue.
Conditions: END, ILLOGIC, NORMAL, NOTAUTH, QIDERR
This command is threadsafe.
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 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.
- The TYPE (REMOTE).
- The system on which it is defined (the REMOTESYSTEM value).
- Its name there (REMOTENAME).
- 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.
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 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.