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.
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.
- 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)
- The read-only DSA (RDSA)
- The extended read-only DSA (ERDSA)
- The extended trusted DSA (ETDSA)
- 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.
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.
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
EXEC CICS GETMAIN64 SET(5)
FLENGTH(1048576)
CICSDATAKEY