The GETMAIN call

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

Storage that is acquired by using a GETMAIN call and that is in the following classes is released by CICS® when the TCA being used at the time of the acquisition terminates:
  • CICS
  • CICS24
  • USER
  • USER24.
In contrast, storage in the following classes is not released automatically at task-end. You must use the FREEMAIN call to release it.
  • SHARED_CICS
  • SHARED_CICS24
  • SHARED_USER
  • SHARED_USER24
  • TERMINAL.

Also, some user exits can be invoked from system tasks. In these circumstances, storage is not released until the next CICS shutdown. Therefore, use the FREEMAIN call to release all storage areas acquired by a GETMAIN call as soon as you finish 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 | *)]

This command is threadsafe.

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 example, a number, a symbolic expression, or a combination of the two.

If you request TERMINAL storage, the length you specify does 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 1.
Table 1. CICS storage classes
STORAGE_CLASS Type of storage
CICS Task-lifetime CICS-key storage above 16 MB but below 2 GB
CICS24 Task-lifetime CICS-key storage below 16 MB
SHARED_CICS Shared CICS-key storage above 16 MB but below 2 GB
SHARED_CICS24 Shared CICS-key storage below 16 MB
SHARED_USER Shared user-key storage above 16 MB but below 2 GB
SHARED_USER24 Shared user-key storage below 16 MB
TERMINAL This class of storage has an 8-byte SAA.
USER Task-lifetime user-key storage above 16 MB but below 2 GB
USER24 Task-lifetime user-key storage below 16 MB

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 requested in 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 you specify a class of TERMINAL on the STORAGE_CLASS option. On FREEMAIN requests, you must code this option if you release TERMINAL-class storage.
Note: Before you obtain 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
Note:
  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.