Get main 24-bit or 31-bit storage.
GETMAIN >>-GETMAIN--SET(ptr-ref)--+-FLENGTH(data-value)--+-------+-+----> | '-BELOW-' | '-LENGTH(data-value)-------------' >--+---------------------+--+--------+--+-----------+-----------> '-INITIMG(data-value)-' '-SHARED-' '-NOSUSPEND-' >--+-------------+--------------------------------------------->< +-USERDATAKEY-+ '-CICSDATAKEY-'
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.
- 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
- 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.
- 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.
- 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.
| 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.
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.
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
EXEC CICS GETMAIN SET(PTR)
FLENGTH(1024)
BELOW
INITIMG(BLANK)You must define BLANK in your program as the character representing a space.
EXEC CICS GETMAIN SET(PTR)
FLENGTH(2048)
INITIMG(BLANK)
CICSDATAKEY