INQUIRE TSQUEUE / TSQNAME

Description

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

Browsing

You can browse 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 want. For example, to see the queues with names that begin with ABC, start your browse with an AT value of ABC, padded on the right to eight characters with nulls (X'00').

To browse temporary storage queues that are in a shared temporary storage pool, you must specify the POOLNAME or the SYSID option on the browse START request only. You must specify an explicit SYSID for a queue that is defined by a TYPE=SHARED entry in a temporary storage table (TST) and that maps to a shared TS pool.

In a browse, CICS® returns all queues, and you might see queues created by CICS for internal use as well as queues created by user applications. Queues with names that start with the following 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

EXPIRYINT(data-area)

Returns a fullword binary field that gives the expiry interval, in hours, that is defined for the temporary storage queue in its TSMODEL resource definition.

The value returned is derived from the EXPIRYINTMIN value rounded up to the next hour, or, if minutes are not specified, from any EXPIRYINT value defined in the model from a previous release.

If the temporary storage queue is not referenced during the expiry interval, it becomes eligible to be deleted automatically by CICS.

A value of zero means that no expiry interval applies to the temporary storage queue, so it is never eligible for automatic deletion. In addition, the following types of temporary storage queues are never deleted automatically by CICS, even if a nonzero expiry interval is set in the matching TSMODEL resource definition:

• Queues in auxiliary temporary storage that are defined as recoverable.
• Queues in a remote CICS region.
• Queues that CICS creates for its own use.

From CICS TS 5.2, the expiry interval also applies to shared temporary storage queues.

EXPIRYINTMIN(data-area)

Returns a fullword binary field that gives the expiry interval, in minutes, that is defined for the temporary storage queue in its TSMODEL resource definition. CICS uses the value rounded up to the nearest multiple of 10 minutes. If the temporary storage queue is not referenced during the expiry interval, it becomes eligible to be deleted automatically by CICS.

A value of zero means that no expiry interval applies to the temporary storage queue, so it is never eligible for automatic deletion. In addition, the following types of temporary storage queues are never deleted automatically by CICS, even if a nonzero expiry interval is set in the matching TSMODEL resource definition:

• Queues in auxiliary temporary storage that are defined as recoverable.
• Queues in a remote CICS region.
• Queues that CICS creates for its own use.

From CICS TS 5.2, the expiry interval also applies to shared temporary storage queues.

FLENGTH(data-area)

Returns a fullword binary field that gives 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 is stored in a single entry in the coupling facility, FLENGTH is the total size of all items including their control information. In this situation, the returned value for FLENGTH is less than 32K (32768).

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

LASTUSEDINT(data-area)

Returns a fullword binary field that gives 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 Defining TS server regions .

LOCATION(cvda)

Returns a CVDA value indicating where the temporary storage queue resides. CVDA values are as follows:

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 that gives 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 temporary storage, 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. The control interval size of the temporary storage data set determines which is chosen. See Control interval size for auxiliary temporary storage.
• For shared queues, the lengths returned in MINITEMLEN, MAXITEMLEN, and FLENGTH, reflect the data length stored in the coupling facility. The data length includes any item control information, which consists of a 2-byte length prefix for each item.

For all types of queue, the maximum value returned is capped at 32767 (X'7FFF').

MINITEMLEN(data-area)

Returns a halfword binary field that gives the length in bytes of the smallest 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 temporary storage, 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. The control interval size of the temporary storage data set determines which is chosen. See Control interval size for auxiliary temporary storage.
• For shared queues, the lengths returned in MINITEMLEN, MAXITEMLEN, and FLENGTH, reflect the data length stored in the coupling facility. The data length includes any item control information, which consists of a 2-byte length prefix for each item.

For all types of queue, the maximum value returned is capped at 32767 (X'7FFF').

NUMITEMS(data-area)

Returns a halfword binary field that gives 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 as follows:

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. If CICS does not find the system name in a TST, an INVREQ response is issued.

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

TRANSID(data-value)

Returns the identifier of the transaction that created the temporary storage queue.

TSMODEL(data-value)

Returns the 8-character name of the temporary storage model which was used when the temporary storage queue was created. Note that the model may have been altered or deleted since the queue was created.

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 eight significant characters. The queue name is truncated, and some significant characters are lost.

4

This temporary storage queue name cannot be deleted because 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.