Storage control XPI functions

There are seven XPI storage control functions. These are the DFHSMMCX macro calls GETMAIN, FREEMAIN, INQUIRE_ELEMENT_LENGTH, and INQUIRE_TASK_STORAGE, and the DFHSMSRX calls INQUIRE_ACCESS, INQUIRE_SHORT_ON_STORAGE, and SWITCH_SUBSPACE.

DFHSMMCX calls cannot be used in any exit program invoked from any global user exit point in the:

The GETMAIN call

GETMAIN acquires an element of storage for use by your exit program. You can ask for a particular CLASS of storage, and you can request that it be initialized to a single-byte value.

Storage in the following classes, acquired by a GETMAIN call, is released by CICS® when the TCA being used at the time of the acquisition terminates:

In contrast, storage in the following classes is not released automatically at task-end: you should use the FREEMAIN call to release it:

In addition, some user exits may be invoked from system tasks, and in these circumstances storage is not released until the next CICS shutdown. Therefore you should use FREEMAIN to release all storage areas acquired by GETMAIN as soon as you have finished using them.

GETMAIN

DFHSMMCX [CALL,]
      [CLEAR,]
      [IN,
      FUNCTION(GETMAIN),
      GET_LENGTH(name4 | (Rn) | expression),
      STORAGE_CLASS(CICS|CICS24|SHARED_CICS|SHARED_CICS24|
                  SHARED_USER|SHARED_USER24|USER|USER24|TERMINAL),
      SUSPEND(NO|YES),
      [INITIAL_IMAGE(name1 | literalconst),]
      [TCTTE_ADDRESS(name4 | (Ra)),]]
      [OUT,
      ADDRESS(name4 | (Rn) | *),
      RESPONSE(name1 | *),
      REASON(name1 | *)]

Start of changeThis command is threadsafe.End of change

ADDRESS(name4 | (Rn) | *)
returns the address of the storage obtained by the call.
name4
The name of a fullword where the obtained storage address is saved
(Rn)
A register that is set to point to the obtained storage
*
The parameter list itself, name SMMC_ADDRESS, is used to keep the address.
GET_LENGTH(name4 | (Rn) | expression)
specifies the number of bytes of storage you want, expressed in any of the following ways:
name4
The name of a fullword specifying, in binary, the number of bytes
(Rn)
A register containing, in binary, the number of bytes
expression
A valid assembler-language expression; for instance, a number, a symbolic expression, or a combination of the two.

If you request TERMINAL storage, the length you specify should not include the length of the storage accounting area (SAA). The maximum length you can specify is 65 515 bytes. CICS storage management adds an 8-byte SAA, and the address returned by the XPI call is that of the start of the SAA.

If you request CICS24, CICS, USER24, USER, SHARED_CICS24, SHARED_CICS, SHARED_USER24, or SHARED_USER storage, you need only specify the length needed by your program. The address returned is that of the start of your data storage. The maximum size of storage for these storage classes is the same as the size of the DSA from which they are allocated.

INITIAL_IMAGE(name1 | literalconst)
specifies the initializing pattern. For example, you might want to set the acquired storage to binary zeros.
name1
The name of a location where the one-byte initializing pattern is stored
literalconst
A number in the form of a literal, for example B'00000000', X'FF', X'FC', "0", or an equate symbol with a similar value.
STORAGE_CLASS(CICS|CICS24|SHARED_CICS|SHARED_CICS24| SHARED_USER|SHARED_USER24|USER|USER24|TERMINAL)
specifies the class of the storage that is the subject of the call. The values you can assign to this option, and the type of storage each represents, are listed in Table 20.
Table 20. CICS storage classes
STORAGE_CLASS Type of storage
CICS Task-lifetime CICS-key storage above 16MB
CICS24 Task-lifetime CICS-key storage below 16MB
SHARED_CICS Shared CICS-key storage above 16MB
SHARED_CICS24 Shared CICS-key storage below 16MB
SHARED_USER Shared user-key storage above 16MB
SHARED_USER24 Shared user-key storage below 16MB
TERMINAL This class of storage has an 8-byte SAA.
USER Task-lifetime user-key storage above 16MB
USER24 Task-lifetime user-key storage below 16MB

You must specify a storage class on a GETMAIN request. On a FREEMAIN request it is an optional parameter, and any value that you specify is not checked by CICS.

SUSPEND(YES|NO)
specifies whether to suspend your request if there is less storage available than you have asked for on the GET_LENGTH option.
TCTTE_ADDRESS(name4 | (Ra))
specifies the address of the terminal control table terminal entry (TCTTE). On GETMAIN requests, you must code this option if, on the STORAGE_CLASS option, you specify a class of TERMINAL. On FREEMAIN requests, you must code it if you are freeing TERMINAL-class storage.
Note:
Before obtaining TERMINAL class storage, check TCAFCI bit 7 to ensure that the TCA is running under a terminal.
name4
The name of a fullword containing the address
(Ra)
A register that points to the TCTTE.

RESPONSE and REASON values for GETMAIN:

RESPONSE REASON
OK None
EXCEPTION INSUFFICIENT_STORAGE
DISASTER None
INVALID None
KERNERROR None
PURGED None
Notes:
  1. For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.
  2. ‘INSUFFICIENT_STORAGE’ is returned if the GETMAIN request was specified with SUSPEND(NO), and there was not enough storage available to satisfy the request.
  3. ‘PURGED’ is returned if the GETMAIN request was specified with SUSPEND (YES), there was not enough storage to satisfy the request, and the task was purged.

The FREEMAIN call

FREEMAIN releases an area of storage that is currently allocated to your exit program.

FREEMAIN

DFHSMMCX [CALL,]
      [CLEAR,]
      [IN,
      FUNCTION(FREEMAIN),
      ADDRESS(name4 | (Rn) | *),
      [STORAGE_CLASS(CICS|CICS24|SHARED_CICS|SHARED_CICS24|
                  SHARED_USER|SHARED_USER24|USER|USER24|TERMINAL),]
      [TCTTE_ADDRESS(pointer),]]
      [OUT,
      RESPONSE(name1 | *),
      REASON(name1 | *)]

Start of changeThis command is threadsafe.End of change

The explanation of the options is the same as that given above for the GETMAIN function.

RESPONSE and REASON values for FREEMAIN:

RESPONSE REASON
OK None
EXCEPTIONNone None
DISASTER None
INVALID None
KERNERROR None
PURGED None
Note:
For more detail, refer to the explanation of RESPONSE and REASON in Making an XPI call.

The INQUIRE_ACCESS call

INQUIRE_ACCESS returns the access-key of an element of storage specified by start address and length. If the element is not wholly contained within one of the CICS dynamic storage areas (DSAs), CICS returns an exception response.

INQUIRE_ACCESS

DFHSMSRX [CALL,]
      [CLEAR,]
      [IN,
      FUNCTION(INQUIRE_ACCESS),
      ELEMENT_ADDRESS(name4 | (Rn) | *),
      ELEMENT_LENGTH(name4 | (Rn) | *),]
      [OUT,
      ACCESS(CICS | READ_ONLY | USER),
      RESPONSE(name1 | *),
      REASON(name1 | *)]

Start of changeThis command is threadsafe.End of change

ACCESS(CICS|READ_ONLY|USER)
returns the access-key of the storage element.
CICS
CICS-key
READ_ONLY
Readonly storage
USER
User-key.
ELEMENT_ADDRESS(name4 | (Rn) | *)
specifies the address of the storage element.
ELEMENT_LENGTH(name4 | (Rn) | *)
specifies the length of the storage element, in bytes. A length of zero is treated as a length of one.

RESPONSE and REASON values for INQUIRE_ACCESS:

RESPONSE REASON
OK None
EXCEPTION INVALID_ELEMENT
DISASTER None
INVALID None
KERNERROR None

The INQUIRE_ELEMENT_LENGTH call

INQUIRE_ELEMENT_LENGTH enables you to pass the address of any part of an element of task-lifetime storage, and to obtain from CICS the start address and the length of the storage element that contains the passed address.

INQUIRE_ELEMENT_LENGTH

DFHSMMCX  [CALL,]
       [CLEAR,]
       [IN,
       FUNCTION (INQUIRE_ELEMENT_LENGTH),
       ADDRESS (name4 | (Rn) | *),]
       [OUT,
       ELEMENT_ADDRESS(name4 | (Rn) | *),
       ELEMENT_LENGTH(name4 | (Rn) | *),
       RESPONSE (name1 | *),
       REASON (name1 | *)]

Start of changeThis command is threadsafe.End of change

ADDRESS(name4 | (Rn) | *)
specifies an address that lies within an element of task-lifetime storage of the current task.

CICS accepts addresses that reference the leading or trailing check zones as being valid addresses for the element of storage you are inquiring upon.

ELEMENT_ADDRESS(name4 | (Rn) | *)
returns the start address of the element of task-lifetime storage referenced by the ADDRESS parameter. The start address returned does not include the leading check zone.
ELEMENT_LENGTH(name4 | (Rn) | *)
returns the length of the element of task-lifetime storage referenced by the ADDRESS parameter. The length returned does not include the leading or trailing check zones.

RESPONSE and REASON values for INQUIRE_ELEMENT_LENGTH:

RESPONSE REASON
OK None
EXCEPTION INVALID_ADDRESS
DISASTER None
INVALID None
KERNERROR None
PURGED None

The INQUIRE_SHORT_ON_STORAGE call

INQUIRE_SHORT_ON_STORAGE enables you to determine whether CICS is short on storage either above or below the 16MB line.

INQUIRE_SHORT_ON_STORAGE

DFHSMSRX  [CALL,]
       [CLEAR,]
       [IN,
       FUNCTION(INQUIRE_SHORT_ON_STORAGE),]
       [OUT,
       SOS_ABOVE_THE_LINE(NO|YES),
       SOS_BELOW_THE_LINE(NO|YES),
       RESPONSE (name1 | *),
       REASON (name1 | *)]

Start of changeThis command is threadsafe.End of change

SOS_ABOVE_THE_LINE(NO|YES),
returns YES if CICS is currently short-on-storage in any of the DSAs above the 16MB line, and NO if not.
SOS_BELOW_THE_LINE(NO|YES),
returns YES if CICS is currently short-on-storage in any of the DSAs below the 16MB line, and NO if not.

RESPONSE and REASON values for INQUIRE_SHORT_ON_STORAGE:

RESPONSE REASON
OK None
DISASTER None
KERNERROR None

The INQUIRE_TASK_STORAGE call

INQUIRE_TASK_STORAGE enables you to request details of all elements of task-lifetime storage belonging to a task. You can specify the transaction number of the task explicitly on the call, or let it default to the current task.

INQUIRE_TASK_STORAGE

DFHSMMCX  [CALL,]
       [CLEAR,]
       [IN,
       FUNCTION (INQUIRE_TASK_STORAGE),
       [TRANSACTION_NUMBER(name4 | (Rn) | *),]
       ELEMENT_BUFFER(buffer-descriptor),
       LENGTH_BUFFER(buffer-descriptor),]
       [OUT,
       NUMBER_OF_ELEMENTS(name4 | (Rn) | *),
       RESPONSE (name1 | *),
       REASON (name1 | *)]

Start of changeThis command is threadsafe.End of change

ELEMENT_BUFFER(buffer-descriptor)
defines the address and length of a buffer into which CICS returns a list of start addresses of all the elements of task-lifetime storage belonging to either the specified task or, by default, the current task.

The start addresses returned do not include the leading check zone. For a description of a buffer descriptor, see buffer-descriptor.

LENGTH_BUFFER(buffer-descriptor)
defines the address and length of a buffer into which CICS returns a list of the lengths of the elements of task-lifetime storage belonging to either the specified task or, by default, the current task. The lengths returned do not include the leading or trailing check zones.

For a description of a buffer descriptor, see buffer-descriptor.

NUMBER_OF_ELEMENTS(name4 | (Rn) | *)
returns the number of entries in each of the two buffers, ELEMENT_BUFFER and LENGTH_BUFFER, as a full-word binary value.
TRANSACTION_NUMBER(name4 | (Rn) | *)
specifies, as a 4 byte packed decimal value, the transaction number of the task to whom the storage belongs.

If you omit the transaction (task) number, CICS assumes the current task.

RESPONSE and REASON values for INQUIRE_TASK_STORAGE:

RESPONSE REASON
OK None
EXCEPTION INSUFFICIENT_STORAGE
NO_TRANSACTION_ENVIRONMENT
DISASTER None
INVALID None
KERNERROR None
PURGED None

The SWITCH_SUBSPACE call

SWITCH_SUBSPACE causes CICS to switch from a subspace to base space, if the task is not already executing in the base space. If the task is already in the base space, storage manager ignores the call.

This function can be used by global user exit programs that receive control in subspace and for some reason need to switch into basespace.

SWITCH_SUBSPACE

DFHSMSRX  [CALL,]
       [CLEAR,]
       [IN,
       FUNCTION(SWITCH_SUBSPACE),
       SPACE(BASESPACE),]
       [OUT,
       RESPONSE (name1 | *),
       REASON (name1 | *)]

Start of changeThis command is threadsafe.End of change

SPACE(BASESPACE)
specifies that CICS is to switch the task issuing the call to the basespace, if it is currently executing within a subspace. This enables the task to read and write to another task’s user-key task-lifetime storage.

RESPONSE and REASON values for SWITCH_SUBSPACE:

RESPONSE REASON
OK None
DISASTER None
KERNERROR None

Related concepts
Overview of the XPI
Global user exit XPI examples, showing the use of storage
Related tasks
Making an XPI call
Writing global user exit programs
Writing a task-related user exit program
Related reference
The XPI functions
[[ Contents Previous Page | Next Page Index ]]