GETMAIN

Get main 24-bit or 31-bit storage.

GETMAIN

Read syntax diagramSkip visual syntax diagramGETMAINSET( ptr-ref)FLENGTH( data-value)BELOWLENGTH( data-value)INITIMG( data-value)SHAREDNOSUSPENDUSERDATAKEYCICSDATAKEY

Conditions: LENGERR, NOSTG

This command is threadsafe.

Description

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

This command includes the LENGTH option for compatibility purposes only; for programs that run with current versions of CICS®, use FLENGTH.

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

CICS allocates storage from one of the following dynamic storage areas (DSAs):
  • DSAs in 24-bit storage:
    • The CICS dynamic storage area (CDSA), below 16 MB (below the line)
    • The user dynamic storage area (UDSA), below 16 MB
    • The shared dynamic storage area (SDSA), below 16 MB
  • DSAs in 31-bit storage; the extended dynamic storage area (EDSA):
    • The extended CICS dynamic storage area (ECDSA), above 16 MB but below 2 GB (above the line)
    • The extended user dynamic storage area (EUDSA), above 16 MB but below 2 GB
    • The extended shared dynamic storage area (ESDSA), above 16 MB but below 2 GB
For more information about these DSAs, see CICS dynamic storage areas.
Note: You cannot use GETMAIN to get storage from the following DSAs:
  • The read-only DSA (RDSA).
  • The extended read-only DSA (ERDSA).
  • The extended trusted DSA (ETDSA).
  • DSAs in the above-the-bar dynamic storage area (GDSA). To obtain storage from these DSAs, use the GETMAIN64 command.
CICS allocates storage from 24-bit or 31-bit storage, depending on the following options:
  • The FLENGTH option with BELOW also specified. CICS obtains the storage from a DSA in 24-bit storage.
  • The FLENGTH option, BELOW not specified. The AMODE of the requesting program determines the location of the obtained storage. For example, for an AMODE(31) program, CICS obtains the storage from the EDSA.
  • The LENGTH option. CICS obtains the storage from a DSA in 24-bit storage.
CICS allocates storage from a CICS-key, user-key, or shared DSA, depending on the following options:
  • USERDATAKEY
  • CICSDATAKEY
  • SHARED
  • If no data-key option is specified on the GETMAIN command, the TASKDATAKEY option on the RDO TRANSACTION resource definition under which the requesting program is running. See TRANSACTION attributes.
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
Storage key is determined by TASKDATAKEY on transaction definition User-key storage. Storage is obtained from the UDSA or EUDSA if the SHARED option is not specified, or from the SDSA or ESDSA if the SHARED option is specified. CICS-key storage. Storage is obtained from the CDSA or ECDSA.

The data-key option on the GETMAIN command overrides the TASKDATAKEY option on the RDO TRANSACTION resource definition. For example, you can specify CICSDATAKEY to ensure that the requesting program obtains CICS-key storage from a CICS DSA, even if TASKDATAKEY(USER) is specified on the RDO TRANSACTION resource definition.

The storage that a task gets is available until it is released with a FREEMAIN or FREEMAIN64 command. For an area that is obtained without the SHARED option, only the task that acquired the storage can release it, and at task end CICS automatically releases such storage not already released.

Any storage acquired with the SHARED option is accessible by all tasks, including those that are running with transaction isolation. However, a SHARED area is not released at task end and remains until explicitly freed; any task can issue the FREEMAIN or FREEMAIN64 request. This means that you can use SHARED storage in task-to-task communication.

Note: Using the GETMAIN command with the SHARED option could create inter-transaction affinities that adversely affect the use of dynamic transaction routing. For more information about transaction affinities, see Affinity.

Options

BELOW
Specifies that 24-bit (below 16 MB) storage is obtained; that is, from the CDSA, UDSA, or SDSA.
CICSDATAKEY
Specifies that CICS allocates storage from a CICS-key DSA (CDSA or ECDSA), overriding the TASKDATAKEY option specified on the transaction resource definition. If you do not specify a data-key option, the storage key (CICS-key or user-key) depends on 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 or FREEMAIN64, 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 limit for the corresponding DSA; that is, 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 in 24-bit and 31-bit storage, respectively.

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. 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)
This option is supported only for compatibility with programs that are written to run under earlier releases of CICS. It is advisable to use FLENGTH.
LENGTH specifies the number of bytes (unsigned halfword binary value) of storage required. This option implies storage from below the 16 MB line and has an upper limit of 65520 bytes. 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.

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 deactivated by 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.

A LENGERR condition that 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 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 allocates storage from a user-key DSA (the UDSA, SDSA, EUDSA, or ESDSA), overriding the TASKDATAKEY option specified on the transaction resource definition. If you do not specify a data-key option, the storage key (CICS-key or user-key) depends on the TASKDATAKEY option on the transaction resource definition.

Conditions

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

Default action: terminate the task abnormally.

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

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 16 MB (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 16 MB but below 2 GB (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