INQUIRE TSQUEUE / TSQNAME

Retrieve information about a temporary storage queue.

This section applies also to the alternative command, INQUIRE TSQNAME Use either to Inquire about names up to 8 characters long, use INQUIRE TSQNAME to Inquire about names up to 16 characters long.

Read syntax diagramSkip visual syntax diagramINQUIRE TSQUEUE
 
>>-INQUIRE --+-TSQUEUE(data-value)-+---------------------------->
             '-TSQNAME(data-value)-'
 
                             .----------------------------.
                             V                            |
>--+----------------------+----+------------------------+-+----><
   +-POOLNAME(data-value)-+    +-FLENGTH(data-area)-----+
   '-SYSID(data-value)----'    +-LASTUSEDINT(data-area)-+
                               +-LOCATION(cvda)---------+
                               +-MAXITEMLEN(data-area)--+
                               +-MINITEMLEN(data-area)--+
                               +-NUMITEMS(data-area)----+
                               +-RECOVSTATUS(cvda)------+
                               '-TRANSID(data-area)-----'
 

Conditions: END, ILLOGIC, INVREQ, NOTAUTH, POOLERR, QIDERR, SYSIDERR

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

Description

The INQUIRE TSQUEUE command returns information about a particular temporary storage queue.

Browsing

You can also browse through all of the temporary storage queues in your system by using the browse options (START, AT, NEXT, and END) on INQUIRE TSQUEUE commands. In browse mode, the definitions are returned in alphabetic order, and you can specify a starting point with the AT option if you wish. If you want to see all the queues with names beginning with a certain string of letters, for example, you can start your browse with an AT value of those letters, padded on the right to eight characters with nulls (X'00'). If you want to browse TS queues that are in a shared temporary storage pool managed by a TS server, you must specify the POOLNAME or the SYSID option on the browse START request only. If CICS cannot find the specified SYSID in any temporary storage table (TST) TYPE=SHARED entry, CICS returns the INVREQ condition.

Note:
If you do a WRITEQ, for example, to queue, which maps to a shared TS pool because of a TST definition, be aware that to inquire on this queue you need to specify the explicit SYSID on the INQUIRE command.

In a browse, CICS returns all queues, and you may see queues created by CICS for internal use as well as those created by user applications. In particular, queues with names that start with these characters are CICS queues: ‘**’, ‘$$’, X'FA' through X'FF', ‘CEBR’ and ‘DF’.

See Browsing resource definitions for general information about browsing, including syntax, exception conditions, and examples.

Options

FLENGTH(data-area)
returns a fullword binary field giving the total length in bytes of all the items in the temporary storage queue. For more information about queue lengths, see the MAXITEMLEN option.

For shared queues only: When the whole shared queue has been stored in a single entry in the coupling facility (in which case the returned value for FLENGTH is less than 32K (32768)), this is the total size of all items including their control information.

When the shared queue has been stored as a separate list in the coupling facility, the total size is estimated as MAXITEMLEN times NUMITEMS.

LASTUSEDINT(data-area)
returns a fullword binary field specifying the interval in seconds since the temporary storage queue was last referenced.

The value returned for ‘large’ shared temporary storage queues is governed by the value of the LASTUSEDINTERVAL parameter specified for the associated TS queue manager (see the CICS® System Definition Guide for further information).

LOCATION(cvda)
returns a CVDA value indicating where the temporary storage queue resides. CVDA values are:
AUXILIARY
The temporary storage queue is held in the CICS temporary storage VSAM data set (or in the coupling facility).
MAIN
The temporary storage queue is held in main storage.
MAXITEMLEN(data-area)
returns a halfword binary field giving the length in bytes of the largest item in the temporary storage queue.

The length of a queue item is the sum of the length of the user data plus 8 bytes for header information, rounded up. For main storage queues, the length is rounded up to the boundary of the MVS storage subpool used to store it.

For auxiliary temporary storage, the length is rounded to the next highest multiple of either 64 or 128 (depending on the control interval size of the temporary storage data set). (For background information about CI sizes, see the CICS System Definition Guide.)

For shared queues, the lengths returned in MINITEMLEN, MAXITEMLEN, and FLENGTH, reflect the data length stored in the coupling facility. This includes any item control information, which consists of a 2-byte length prefix for each item.

Start of changeFor all types of queue the maximum value returned will be capped at 32767 (Hex '7FFF').End of change

MINITEMLEN(data-area)
returns a halfword binary field giving the length in bytes of the smallest item in the temporary storage queue. For information about how CICS calculates the length of items, and for information about shared TS queues, see the MAXITEMLEN option.
NUMITEMS(data-area)
returns a halfword binary field giving the number of items in the temporary storage queue.
POOLNAME(data-value) (TS data sharing only)
specifies the name of a temporary storage pool. CICS ships the command to the temporary storage server that manages the pool.

For browse operations, specify POOLNAME on the browse START request only, not on the NEXT or END requests.

RECOVSTATUS(cvda)
returns a CVDA value indicating the recovery status of the queue. CVDA values are:
RECOVERABLE
The queue is recoverable.
NOTRECOVERABLE
The queue is not recoverable.
SYSID(data-value) (TS data sharing only)
specifies the system name that corresponds to a temporary storage pool name. If CICS finds the specified system name in a TST TYPE=SHARED entry, it ships the command to the temporary storage server that manages the pool.

For browse operations, specify SYSID on the browse START request only, not on the NEXT or END requests.

TRANSID(data-value)
specifies the identifier of the transaction which created the temporary storage queue.
TSQUEUE(data-value)
specifies the 8-character name of the temporary storage queue about which you are inquiring.
TSQNAME(data-value)
is an alternative to TSQUEUE and specifies the 16-character name of the temporary storage queue about which you are inquiring.

Conditions

END
RESP2 values:
2
There are no more resource definitions of this type.
ILLOGIC
RESP2 values:
1
You have issued a START command when a browse of this resource type is already in progress, or you have issued a NEXT or an END command when a browse of this resource type is not in progress.
INVREQ
RESP2 values:
1
The specified SYSID does not exist in any TYPE=SHARED entry in the temporary storage table.
2
When INQUIRE TSQUEUE NEXT is specified, the NEXT queue to be browsed has a queue name of more than 8 significant characters. The queue name is truncated, some significant characters are lost.
4
This temporary storage queue name cannot be deleted as it was written by CICS using the PUTQ macro.
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.
POOLERR
RESP2 values:
3
The POOLNAME does not exist.
QIDERR
RESP2 values:
1
The temporary storage queue cannot be found.
SYSIDERR
RESP2 values:
3
The SYSID does not map to a shared pool.
4
Server error.
5
I/O error on coupling facility.
[[ Contents Previous Page | Next Page Index ]]