INQUIRE STORAGE64

Retrieve information about 64-bit task storage.

Syntax

INQUIRE STORAGE64

Conditions: INVREQ, NOTAUTH, TASKIDERR

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations.

This command is threadsafe.

Description

Use INQUIRE STORAGE64 to perform these operations:

Get a list of the task storage areas associated with a particular task (by using the NUMELEMENTS option).
Find the length and starting address of a particular area of 64-bit storage (by using the ADDRESS64 option).

INQUIRE STORAGE64 returns either the 64-bit element address or a list of 64-bit addresses associated with the task. The storage is only accessible to Assembly language programs running in AMODE 64.

INQUIRE STORAGE64 applies only to storage allocated to user tasks, which are tasks that execute user-defined transactions or the CICS transactions.

Options

ADDRESS64(ptr-value): Specifies that you are inquiring about a single area of 64-bit storage and identifies the area. The address that you specify can be anywhere within the area about which you are inquiring; it does not have to be the start of it. CICS® returns the length of the area (in FLENGTH) and its starting address (in ELEMENT64) if it is a valid element of user task storage.
DSANAME(data-value): Specifies the name of the DSA for which storage elements are to be returned.
Possible values are GCDSA and GUDSA. See CICS dynamic storage areas (DSAs). If you omit this option, storage elements are returned for both DSAs.
ELEMENT64(ptr-ref): Returns the starting address of the storage area that contains the address that you provide on the ADDRESS64 option, if the area is user task storage. This is the first byte of the area available for task data, not the preceding storage management control information, if any. If the area is not user task storage, the address that is returned is nulls.
ELEMENTLIST(ptr-ref): Returns the address of a list of doubleword addresses of all areas of task storage for the task that you specify on the TASK option. Each address points to the first byte available for data storage, not to preceding storage management control information, if any. The number of addresses in this list is the NUMELEMENTS option value. (Addresses are 8 bytes long, so the length of the list in bytes is eight times NUMELEMENTS.)
CICS obtains the storage for this list and frees it when the inquiring task ends, or issues another INQUIRE STORAGE or INQUIRE STORAGE64 command with ELEMENTLIST or LENGTHLIST, or issues an INQUIRE TASK LIST command; the task cannot free the storage itself.
FLENGTH(data-area): Returns a fullword binary field that gives the length of the storage area that contains the address that you specify on the ADDRESS64 option. This is the length of the part that is available for task data. It does not include storage management control information at the beginning or end of the area, if any. If the area is not user task storage, the length that is returned is -1.
LENGTHLIST(ptr-ref): Returns the address of a list of doubleword binary lengths. Each entry in this list is the length of the storage area to which the corresponding entry in the ELEMENTLIST list points. These lengths are the amounts available for data storage and do not include storage management control information, if any.
CICS obtains the storage for this list and frees it when the inquiring task ends, or issues another INQUIRE STORAGE or INQUIRE STORAGE64 command with ELEMENTLIST or LENGTHLIST, or issues an INQUIRE TASK LIST command; the task cannot free the storage itself.
NUMELEMENTS(data-area): Indicates that you are requesting a list of the task storage areas for the task that you specify on the TASK option. CICS returns the number of areas, in fullword binary form, in the data area you provide. If you request an ELEMENTLIST or LENGTHLIST, this value is the number of entries in the list.
TASK(data-value): Specifies, as a 4 byte packed decimal value, the task number for which you are requesting a storage list. If you omit this option but include NUMELEMENTS, CICS assumes that the inquiry is for the task that issues the INQUIRE STORAGE64 command.

Conditions

INVREQ

RESP2 values:

1: Invalid DSANAME specified.

NOTAUTH

RESP2 values:

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

TASKIDERR

RESP2 values:

1: The task number does not exist.
2: The task number designates a system task, not a user task.