INQUIRE MVSTCB

Description

The INQUIRE MVSTCB command can be used only in browse mode. It returns addresses and storage information for the MVS TCBs in the CICS® address space. The information for each TCB shows the addresses, lengths and MVS subpools for the storage elements owned by the TCB, the storage key for each element, and the number of bytes in use (obtained by the task by using a getmain request) for each element.

The syntax shown is the correct syntax for this command for all new applications. In the following list of options, the ELEMENTLIST, LENGTHLIST and SUBPOOLLIST options are obsolete, but are supported for compatibility with applications developed in releases before CICS Transaction Server for z/OS®, Version 3 Release 2. Do not use these options in combination with the SET option.

The NUMELEMENTS option has a role in both the old syntax and the new syntax. Where the ELEMENTLIST, LENGTHLIST and SUBPOOLLIST options are used, the NUMELEMENTS option specifies the number of entries in each of these lists (which is the same for each list). NUMELEMENTS is also used in combination with the SET option, to give the number of addresses in the pointer list that the SET option returns.

Browsing

This command can be used only in browse mode. Browse through all of the MVS TCBs in the CICS address space by using the browse options (START, NEXT, and END) on the command. For general information about browsing, including syntax, exception conditions, and examples, see Browsing resource definitions.

Options

ELEMENTLIST(ptr-ref)

Returns the address of a list of the addresses of all areas of private storage allocated to this TCB. This option is obsolete, but it is supported for compatibility with applications developed in earlier CICS releases.

LENGTHLIST(ptr-ref)

Returns the address of a list of fullword binary lengths of the storage areas listed in the ELEMENTLIST list. This option is obsolete, but it is supported for compatibility with applications developed in earlier CICS releases.

NUMELEMENTS(data-area)

A fullword binary field that is set to the number of storage elements owned by this TCB. This value is the number of addresses listed in the pointer list returned by the SET option, where each address indicates one storage element.

MVSTCB(ptr-ref)

Returns the address of the MVS TCB in the CICS address space. The TCB address that is returned can be used as input to the COLLECT STATISTICS MVSTCB command to retrieve storage and CPU time statistics for the TCB.

SET(ptr-ref)

Returns the address of a list of four-byte addresses. Each address points to a descriptor that contains details of one storage element owned by this TCB. The number of addresses in the list is the value returned by the NUMELEMENTS option.

CICS obtains the storage for the list and descriptors. It is freed when the inquiring task ends, or issues another INQUIRE MVSTCB command with one of the command options. The task cannot free the storage itself.

The format of the descriptor for each storage element is shown in Table 1:

Table 1. INQUIRE MVSTCB, SET option: Descriptor for each storage element

Offset (decimal)	Length	Contents
0	4	Address of the storage
4	4	Length
8	4	MVS subpool number
12	4	MVS storage key (for example, 8)
16	4	Number of bytes in use

Note: Number of bytes in use is the amount of storage obtained by the task by using a getmain request. This might be less than the amount of storage allocated to the TCB, because storage is always allocated to a TCB in page multiples (4096 bytes).

SUBPOOLLIST(ptr-ref)

Returns the address of a list of fullword binary subpool numbers of the MVS subpools for the storage areas listed in the ELEMENTLIST list. This option is obsolete, but it is supported for compatibility with applications developed in earlier CICS releases.

Conditions

END

RESP2 values:

2

All authorized resources have been retrieved. All data areas specified on this command are left unchanged.

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.

NOTAUTH

RESP2 values:

100

The user associated with the issuing task is not authorized to use this command.

NOTFND

RESP2 values:

1

The TCB specified on the command was not found.