Get main storage. GETMAIN gets a main storage area of the size indicated by the FLENGTH option. The address of the area is returned as a pointer reference with the SET option.

CICS always allocates on 16-byte boundaries and rounds the requested length up to the nearest 16-byte multiple. There is no default initialization and must use the INITIMG option to initialise the storage if required.

Syntax -

Parameters -

BELOW -

Specifies the 24-bit (below 16 MB) storage is obtained.

CICSDATAKEY -

Specifies that CICS allocates storage from a key overriding the TASKDATAKEY option specified on the transaction resource definition. If data-key option specified the storage key depends on the TASKDATAKEY option on the transaction resource definition.

FLENGTH(data-value) -

Specifies the number of bytes of storage required in fullword binary format. If the length requested is greater than the corresponding DSALIMIT or EDSALIMIT value, the LENGERR condition occurs. If the length requested is less than the corresponding limit, but is greater than the available storage, a NOSTG condition occurs.

INITIMG(data-value) -

Specifies an optional 1-byte initialization value. In COBOL programs, data area must use rather than a data value to define the initialization bit string.

LENGTH(data-value) -

This option is supported for compatibility with programs that are written to run under earlier releases of CICS. It is advisable to use FLENGTH.

For a larger area or storage above 16 MB, use FLENGTH. If the value of LENGTH is zero, a LENGERR condition occurs. If the length requested is greater than the available storage, a NOSTG condition occurs.

NOSUSPEND -

Specifies that if no storage is available, CICS does not suspend the task but issues the NOSTG condition.

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. A LENGERR condition results from a zero or negative value being specified for FLENGTH or LENGTH will set ptr-ref to zero.

SHARED -

Prevents the automatic release of storage obtained by a GETMAIN command at the end of the task. A memory obtained with SHARED is not released until a corresponding FREEMAIN is issued.

USERDATAKEY -

Specifies that CICS allocates storage from a user-key overriding the TASKDATAKEY option specified on the transaction resource definition.

Error Conditions -

Below are the list of error conditions may occur in combination. If more than one occurs, only the first is passed to the application program.