GETMAIN64

Get 24-bit, 31-bit, or 64-bit storage. This command is for use only in non-Language Environment (LE) AMODE(64) assembler language application programs.

See Assembler language programming restrictions and requirements.

GETMAIN64

Conditions: INVREQ, LENGERR, NOSTG

This command is threadsafe.

Description

GETMAIN64 gets a main storage area of the size indicated by the FLENGTH option. The address of the area is returned in the 64-bit pointer reference supplied in the SET option. By default, the addressing mode (AMODE) of the requesting program determines the location of the obtained storage. Therefore, for an AMODE(64) program, GETMAIN64 obtains 64-bit storage.

You can also use the LOCATION parameter to specify that 24-bit or 31-bit storage is obtained, regardless of the AMODE of the calling program. For example, if you specify LOCATION(LOC31), a 64-bit address for an area of 31-bit storage is returned.

CICS® always allocates on 16-byte boundaries and rounds the requested length up to the nearest 16-byte multiple.

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
DSAs in 64-bit storage: the above-the-bar dynamic storage area (GDSA):
- The above-the-bar CICS DSA (GCDSA)
- The above-the-bar user DSA (GUDSA)
- The above-the-bar shared DSA (GSDSA)

For more information about these DSAs, see CICS dynamic storage areas.

Note: You cannot use GETMAIN64 to obtain storage from the following DSAs:

The read-only DSA (RDSA)
The extended read-only DSA (ERDSA)
The extended trusted DSA (ETDSA)

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 GETMAIN64 command, the TASKDATAKEY option on the RDO TRANSACTION resource definition under which the requesting program is running. See TRANSACTION attributes.

The following table summarizes the effect of the data-key options.

Table 1. Data-key options on GETMAIN64 command
No data-key option	USERDATAKEY specified	CICSDATAKEY specified
Storage key is determined by TASKDATAKEY on the transaction definition	User-key storage. If the SHARED option is not specified, storage is obtained from the UDSA, EUDSA, or GUDSA. If the SHARED option is specified, storage is obtained from the SDSA, ESDSA, or GSDSA.	CICS-key storage. Storage is obtained from the CDSA, ECDSA, or GCDSA.

The data-key option on the GETMAIN64 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 obtains is available until it is released with a FREEMAIN or FREEMAIN64 command. For storage that is obtained without the SHARED option, only the task that acquired the storage can release it. At task end, CICS automatically releases such storage not already released.

Any storage obtained 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 GETMAIN64 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

CICSDATAKEY

Specifies that CICS allocates storage from a CICS-key DSA (CDSA, ECDSA, or GCDSA), 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 a FREEMAIN or FREEMAIN64 request, 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.

For 64-bit storage, the maximum length that you can specify is 2146435056 (2 GB - (1 MB + 16 bytes)). If the length requested is greater than the available storage, a NOSTG condition occurs.

For 24-bit or 31-bit storage, the maximum length that you can specify is the value of the limit for the corresponding DSA, that is, DSALIMIT or EDSALIMIT. DSALIMIT and EDSALIMIT are system initialization parameters that define the overall storage limits within which CICS can allocate and manage the individual DSAs in 24-bit and 31-bit storage, respectively. If the length requested is bigger 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.

LOCATION(cvda)

Specifies that CICS allocates storage from 24-bit or 31-bit storage, regardless of the AMODE of the calling program. CVDA values are as follows:

LOC24: 24-bit storage (below 16 MB) is obtained; that is, from the CDSA, UDSA, or SDSA.
LOC31: 31-bit storage (above 16 MB but below 2 GB ) is obtained; that is, from the ECDSA, EUDSA, or ESDSA.

NOSUSPEND

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

SET(ptr-ref64)

Sets the 64-bit pointer reference to the address of the acquired main storage. The pointer is set to the first byte of the storage area.

The pointer reference returns a 64-bit address for an area of 64-bit, 31-bit, or 24-bit storage. The location of the obtained storage depends on the AMODE of the caller, unless a LOCATION option is specified.

SHARED

Prevents the automatic release of storage obtained by a GETMAIN64 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 FREEMAN or FREEMAIN64 request is issued, whether by the requesting task or another 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 (UDSA, SDSA, EUDSA, ESDSA, GUDSA, or GSDSA), 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

16 INVREQ

RESP2 values:

3: The LOCATION option is not valid.

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.

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.

Example

The following example shows how to get a 1048576 byte area from CICS-key storage above the bar (regardless of the TASKDATAKEY option specified on the transaction resource definition):

EXEC CICS GETMAIN64 SET(5)
          FLENGTH(1048576)
          CICSDATAKEY