GETMAIN

Get main storage.

Read syntax diagramSkip visual syntax diagram
GETMAIN

>>-GETMAIN--SET(ptr-ref)--+-FLENGTH(data-value)--+-------+-+---->
                          |                      '-BELOW-' |   
                          '-LENGTH(data-value)-------------'   

>--+---------------------+--+--------+--+-----------+----------->
   '-INITIMG(data-value)-'  '-SHARED-'  '-NOSUSPEND-'   

>--+-------------+---------------------------------------------><
   +-USERDATAKEY-+   
   '-CICSDATAKEY-'   

Conditions: LENGERR, NOSTG

This command is threadsafe.

Note for dynamic transaction routing: Using GETMAIN with SHARED could create inter-transaction affinities that adversely affect the use of dynamic transaction routing. See the CICS® Application Programming Guide for more information about transaction affinities.

Description

GETMAIN gets a main storage area of the size indicated by the FLENGTH option. (You can also use the LENGTH option, but this is supported for compatibility purposes and you are strongly recommended to use FLENGTH.) The address of the area is returned in the pointer reference supplied in the SET option.

CICS always allocates on double-word boundaries and rounds the requested length up to the nearest double-word multiple. Because there is no default initialization, you must use the INITIMG option if you require the storage to be initialized to a specific bit configuration.

CICS allocates storage from one of six different dynamic storage areas (DSAs):
  • The CICS dynamic storage area (CDSA), below the 16MB line
  • The user dynamic storage area (UDSA), below the 16MB line
  • The shared dynamic storage area (SDSA), below the 16MB line
  • The extended CICS dynamic storage area (ECDSA), above the 16MB line
  • The extended user dynamic storage area (EUDSA), above the 16MB line
  • The extended shared dynamic storage area (ESDSA), above the 16MB line
Note: There are two other dynamic storage areas—the read-only DSA (RDSA) and the extended read-only DSA (ERDSA)—but you cannot GETMAIN storage from these DSAs.
CICS determines whether to obtain the requested storage above or below the 16MB line, from one of the CICS- or user-key DSAs, or from one of the shared DSAs, according to the following options:
  • The FLENGTH option with BELOW also specified
  • The FLENGTH option alone, in conjunction with the addressing mode of the requesting program
  • The LENGTH option
  • The SHARED option
In most cases, CICS obtains the storage from a DSA. If the FLENGTH option is specified alone, and the addressing mode of the requesting program is 31-bit, CICS obtains the storage from an EDSA.
CICS decides whether to allocate storage from a CICS-key or user-key DSA, or from a shared DSA, according to the following options:
  • The USERDATAKEY option on the GETMAIN command
  • The CICSDATAKEY option on the GETMAIN command
  • The TASKDATAKEY option on the RDO TRANSACTION resource definition under which the requesting program is running if the USERDATAKEY or CICSDATAKEY option is omitted
  • The SHARED option on the GETMAIN command

The data-key option on the GETMAIN command overrides the TASKDATAKEY option on the RDO TRANSACTION resource definition. The effect of the data-key options is summarized in the following table:

Table 1. Data-key options on GETMAIN command
No data-key option USERDATAKEY specified CICSDATAKEY specified
Determined by TASKDATAKEY on transaction definition User-key storage. From UDSA or EUDSA if SHARED option is not specified, or from SDSA or ESDSA if SHARED option is specified. CICS-key storage. From CDSA or ECDSA.

The storage that a task gets is available until it is released with a FREEMAIN command. For an area obtained without the SHARED option, only the task that acquired the storage may release it, and at task end CICS automatically releases such storage not already released. Note that any storage acquired with the SHARED option is accessible by all tasks, including those that are running with transaction isolation.

A SHARED area, on the other hand, is not released at task end and remains until explicitly freed; any task may issue the FREEMAIN. This means that you can use SHARED storage in task-to-task communication.

You cannot, however, use the storage obtained as a TIOA for subsequent terminal operations, because this could cause storage violations.

Specifying CICSDATAKEY ensures that the requesting program obtains CICS-key storage from a CICS DSA, even if TASKDATAKEY(USER) is specified on the RDO TRANSACTION resource definition.

Options

BELOW
specifies that storage is to be obtained below the 16MB line, that is, from the CICS DSA.
CICSDATAKEY
specifies that CICS is to allocate storage from one of the CICS-key DSAs (the CDSA or ECDSA), overriding the TASKDATAKEY option specified on the transaction resource definition. If you do not specify the data key, CICS determines the type of storage (CICS-key or user-key) according to the TASKDATAKEY option on the transaction resource definition.
Note: If the program is running under a task defined with TASKDATAKEY(USER) on the transaction resource definition, do not explicitly use FREEMAIN but allow the storage to be freed as part of the task termination.
FLENGTH(data-value)
specifies the number of bytes of storage required, in fullword binary format.

The maximum length that you can specify is the value of the corresponding DSA limit parameter, either DSALIMIT or EDSALIMIT. These are the system initialization parameters that define the overall storage limit within which CICS can allocate and manage the individual DSAs.

If the length requested is bigger than the DSALIMIT or EDSALIMIT value, the LENGERR condition occurs. If it is not bigger than these limits, but is more than is available, NOSTG occurs.

INITIMG(data-value)
specifies an optional 1-byte initialization value. If you specify INITIMG, CICS sets every byte of the acquired storage to the bit string you provide. Otherwise, CICS does not initialize the storage. In COBOL programs only, you must use a data area rather than a data value to define the initialization bit string.
LENGTH(data-value)
specifies the number of bytes (unsigned halfword binary value) of storage required. LENGTH implies storage from below the 16MB line and has an upper limit of 65 520 bytes. If you want storage above the 16MB line or a larger area, use FLENGTH.

If LENGTH is equal to zero, LENGERR occurs. If it is greater than the amount of storage available, NOSTG occurs.

Note: FLENGTH, with or without BELOW, is the recommended option: the LENGTH option is supported for compatibility purposes for those programs written to run under earlier releases of CICS.
NOSUSPEND
prevents CICS from suspending the task if no storage is available, and causes it to issue the NOSTG condition instead.

Note, however, that if a HANDLE CONDITION for NOSTG is active when the command is executed, control is passed to the user label supplied in the HANDLE CONDITION. This takes precedence over the NOSUSPEND option but is, of course, negated by either NOHANDLE or RESP.

SET(ptr-ref)
sets the pointer reference to the address of the acquired main storage. The pointer is set to the first byte of the storage area.
SHARED
prevents the automatic release of storage obtained by a GETMAIN command at the end of the task that requested it. This enables task-to-task communication. An area obtained with SHARED is not released until a corresponding FREEMAIN is issued, whether by the requesting task or some other task.

Be aware that if a task abends, any shared storage acquired is not automatically released.

USERDATAKEY
specifies that CICS is to allocate storage from one of the user-key DSAs (the UDSA, SDSA, EUDSA, or ESDSA), overriding the TASKDATAKEY option specified on the transaction resource definition. If you do not specify the data key, CICS determines the type of storage (CICS-key or user-key) according to the TASKDATAKEY option on the transaction resource definition.

Conditions

LENGERR
RESP2 values:
1
The FLENGTH value is less than 1 or greater than the length of the target storage area from which the request is to be satisfied. See the discussion about DSAs in CICS storage allocation.
Also occurs if the LENGTH value is zero.

Default action: terminate the task abnormally.

NOSTG
RESP2 values:
2
The storage requested is more than is currently available in the target DSA. See the discussion about DSAs in CICS storage allocation.

Default action: ignore the condition. An active HANDLE CONDITION NOSTG also raises this condition.

Examples

The following example shows how to get a 1024-byte area from user-key storage below the 16MB line (assuming that TASKDATAKEY(USER) is specified on the RDO TRANSACTION resource definition), and initialize it to spaces:
EXEC CICS GETMAIN SET(PTR)
          FLENGTH(1024)
          BELOW
          INITIMG(BLANK)

You must define BLANK in your program as the character representing a space.

The following example shows how to get a 2048-byte area from CICS-key storage above the 16MB line (regardless of the TASKDATAKEY option specified on the transaction resource definition), and initialize it to spaces:
EXEC CICS GETMAIN SET(PTR)
          FLENGTH(2048)
          INITIMG(BLANK)
          CICSDATAKEY