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:
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.
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 | *)]
This command is threadsafe.
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.
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.
RESPONSE | REASON |
---|---|
OK | None |
EXCEPTION | INSUFFICIENT_STORAGE |
DISASTER | None |
INVALID | None |
KERNERROR | None |
PURGED | None |
FREEMAIN releases an area of storage that is currently allocated to your exit program.
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 | *)]
This command is threadsafe.
The explanation of the options is the same as that given above for the GETMAIN function.
RESPONSE | REASON |
---|---|
OK | None |
EXCEPTIONNone | None |
DISASTER | None |
INVALID | None |
KERNERROR | None |
PURGED | None |
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.
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 | *)]
This command is threadsafe.
RESPONSE | REASON |
---|---|
OK | None |
EXCEPTION | INVALID_ELEMENT |
DISASTER | None |
INVALID | None |
KERNERROR | None |
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.
DFHSMMCX [CALL,]
[CLEAR,]
[IN,
FUNCTION (INQUIRE_ELEMENT_LENGTH),
ADDRESS (name4 | (Rn) | *),]
[OUT,
ELEMENT_ADDRESS(name4 | (Rn) | *),
ELEMENT_LENGTH(name4 | (Rn) | *),
RESPONSE (name1 | *),
REASON (name1 | *)]
This command is threadsafe.
CICS accepts addresses that reference the leading or trailing check zones as being valid addresses for the element of storage you are inquiring upon.
RESPONSE | REASON |
---|---|
OK | None |
EXCEPTION | INVALID_ADDRESS |
DISASTER | None |
INVALID | None |
KERNERROR | None |
PURGED | None |
INQUIRE_SHORT_ON_STORAGE enables you to determine whether CICS is short on storage either above or below the 16MB line.
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 | *)]
This command is threadsafe.
RESPONSE | REASON |
---|---|
OK | None |
DISASTER | None |
KERNERROR | None |
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.
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 | *)]
This command is threadsafe.
The start addresses returned do not include the leading check zone. For a description of a buffer descriptor, see buffer-descriptor.
For a description of a buffer descriptor, see buffer-descriptor.
If you omit the transaction (task) number, CICS assumes the current task.
RESPONSE | REASON |
---|---|
OK | None |
EXCEPTION | INSUFFICIENT_STORAGE |
NO_TRANSACTION_ENVIRONMENT | |
DISASTER | None |
INVALID | None |
KERNERROR | None |
PURGED | None |
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.
DFHSMSRX [CALL,]
[CLEAR,]
[IN,
FUNCTION(SWITCH_SUBSPACE),
SPACE(BASESPACE),]
[OUT,
RESPONSE (name1 | *),
REASON (name1 | *)]
This command is threadsafe.
RESPONSE | REASON |
---|---|
OK | None |
DISASTER | None |
KERNERROR | None |