GETMAIN

Get main 24-bit or 31-bit storage.

Syntax

GETMAIN

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

Conditions: LENGERR, NOSTG

This command is threadsafe.

NOHANDLE, RESP, and RESP2 are common options that can be added to all EXEC CICS commands to process error conditions. They are not explicitly included in the command syntax diagram and option descriptions. For information about these common options and EXEC CICS command syntax, see EXEC CICS command format and programming considerations.

Description

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

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, and BELOW not specified

    The AMODE of the requesting program determines the location of the obtained storage. For example, for an AMODE(31) program, CICS can obtain the storage from the EDSA.

  • The LENGTH option

    CICS obtains the storage from a DSA in 24-bit storage. The LENGTH option is included for compatibility purposes only; for programs that run with current versions of CICS, use FLENGTH.

To obtain storage from DSAs in 64-bit storage, use the GETMAIN64 command.

If enabled, instruction execution protection protects CICS DSAs from instruction execution. This helps to protect systems from errors such as stack overflow and malicious attacks. However, if circumstances arise such that instructions are to be executed from the storage area obtained by the GETMAIN or GETMAIN64 command, use the EXECUTABLE option so that CICS allocates storage from DSAs that are never protected from instruction execution. The attributes of the requested storage determine the DSA from which the storage is obtained. Without the EXECUTABLE option, CICS allocates storage from DSAs that are protected from instruction execution.

Recommendation: Customer applications should not use the EXECUTABLE option unless they build and execute instructions from storage that is obtained through the GETMAIN or GETMAIN64 command. Normally, applications do not execute as such. To prevent developers from using this function, you can add it to the restricted commands parmlib member DFHAPIR so that the CICS translator can help govern the use of restricted commands at program translation. For details, see Controlling the use of specific CICS API and SPI commands.

CICS always allocates on 16-byte boundaries and rounds the requested length up to the nearest 16-byte multiple. An 8-byte crumple zone is added to the start and end of task GETMAIN storage: that is, storage that is obtained by GETMAIN and GETMAIN64 commands that do not specify the SHARED option. The address that is returned in this case is on an 8-bye (doubleword) boundary.

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 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 TRANSACTION resource definition under which the requesting program is running. For more information about the TASKDATAKEY resource definition option, see TRANSACTION resources.

The data key option on the GETMAIN command overrides the TASKDATAKEY option on the 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 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 that is not already released. If the program is running under a task that is 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.

Any storage that is acquired with the SHARED option is accessible by all tasks, including tasks 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 behavior means that you can use SHARED storage in task-to-task communication.

Using GETMAIN with the SHARED option might 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. The actual (below 16 MB) DSA from which the storage is obtained depends on the required key of the storage, if Instruction Execution Protection is required, and if shared storage is required.
CICSDATAKEY
Specifies that CICS allocates storage from one of the CICS-key DSAs. This option overrides the TASKDATAKEY option 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. The actual DSA from which the storage is obtained depends on the required key of the storage, on whether Instruction Execution Protection is required, and on whether shared storage is required.
EXECUTABLE

Specifies that the storage should be obtained from one of the DSAs that are never protected from instruction execution. See Instruction execution protection for information about these DSAs.

The option is ignored for user-key storage if instruction execution protection is not enabled, or if transaction isolation is active.

If the option is not ignored, the actual DSA from which the storage is obtained depends on the key of the location of the requested storage. Table 1 and Table 2 summarize the effect of the data key options.

Table 1. Data key options on GETMAIN command where EXECUTABLE is not specified or is ignored
No data key option USERDATAKEY CICSDATAKEY
Storage key is determined by TASKDATAKEY on the TRANSACTION resource 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. This option overrides the TASKDATAKEY option on the TRANSACTION resource definition. CICS-key storage. Storage is obtained from the CDSA or ECDSA. This option overrides the TASKDATAKEY option on the TRANSACTION resource definition.
Table 2. Data key options on GETMAIN command where EXECUTABLE is specified and not ignored
No data key option USERDATAKEY specified CICSDATAKEY specified
Storage key is determined by TASKDATAKEY on the TRANSACTION resource definition User-key storage. Storage is obtained from the PUDSA or EPUDSA. This option overrides the TASKDATAKEY option on the TRANSACTION resource definition. CICS-key storage. Storage is obtained from the PCDSA or EPCDSA. This option overrides the TASKDATAKEY option on the TRANSACTION resource definition.
FLENGTH(data-value)
Specifies the number of bytes of storage that is 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 system initialization parameters 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 a 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 that is specified for FLENGTH or LENGTH sets ptr-ref to zero.

SHARED
Prevents the automatic release of storage that is obtained by a GETMAIN command at the end of the task that requested it. This behavior enables task-to-task communication. An area that is obtained with SHARED is not released until a corresponding FREEMAIN command is issued, whether by the requesting task or some other task.

If a task abends, any shared storage that is acquired is not automatically released.

USERDATAKEY
Specifies that CICS allocates storage from a user-key DSA. This option overrides the TASKDATAKEY option 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. The actual DSA from which the storage is obtained depends on the required key of the storage, on whether Instruction Execution Protection is required, and on whether shared storage is required.

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.

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.

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 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 that represents 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