GETMAIN
(
Get main storage.
ptr-ref
)
FLENGTH
(
(
data-value data-value
)
)
(1)
BELOW
(1)
ANY
INITIMG (
data-value
)
Notes:
1 Ignored by CICS/400.
SHARED NOSUSPEND
Conditions:
LENGERR, NOSTG
Description
GETMAIN gets a main storage area of the size indicated by the LENGTH or
FLENGTH option. The address of the area is returned in the pointer reference supplied in the SET option.
CICS/400 always allocates storage on pointer boundaries, and rounds the requested length up to the nearest pointer multiple. Because there is no default initialization, you must use the INITIMG option if you require the storage to be initialized to a specific bit configuration.
Storage acquired by a task is accessible until it is freed.
When the SHARED option is not specified on the GETMAIN command non-shared storage is allocated from the task’s private storage space. Non-shared storage is freed either by the owning task explicitly issuing a FREEMAIN command or by
CICS implicitly freeing the storage at task termination.
Shared storage, on the other hand, is allocated from a common storage space shared between all tasks in the control region. Shared storage obtained by a
GETMAIN command with the SHARED option must be explicitly freed by a
FREEMAIN command; it is not freed at task termination. The corresponding
FREEMAIN command may be issued by any task. This means that you can use shared storage in task-to-task communication.
Refer to Chapter 22, “Storage control,” on page 213 for more information.
Options
ANY
retained for compatibility with migrated programs. It is accepted, but ignored, by CICS/400.
BELOW
retained for compatibility with migrated programs. It is accepted, but ignored, by CICS/400.
FLENGTH(
data-value
)
specifies as a fullword binary value the number of bytes of storage required.
Chapter 32. Application programming commands - reference
367
The maximum length that you can specify is the size of the storage space from which the request is satisfied or 65 488 bytes, whichever is smaller.
If the requested length is greater than the storage space, the LENGERR condition occurs. If it is not greater than the storage space but is more than is available, the 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, you must use a data area rather than a data value to define the initialization bit string.
LENGTH(
data-value
)
specifies as a signed halfword binary value the number of bytes of storage required. The maximum length you can specify is 32KB. If you need more than
32KB of storage, use the FLENGTH option.
If the requested length is zero, the LENGERR condition occurs. If it is greater than the amount of storage available, the NOSTG condition occurs.
NOSUSPEND
changes the CICS default action for the NOSTG condition, causing CICS to return control to the task without the requested storage instead of suspending the task until the storage becomes available.
SET(
ptr-ref
)
specifies a pointer reference to be set to the address of the acquired main storage. The pointer is set to the first usable byte of the free space (not to the
CICS control information that precedes it).
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, by the requesting task or another task.
Exception Conditions
LENGERR
RESP2 values:
1
v
The FLENGTH value is less than 1 or greater than the length of the free spaces from which the request can be satisfied.
The LENGTH value is zero.
Default action: Terminate the task abnormally.
NOSTG
RESP2 values:
2
More storage is requested than is currently available.
Default action: When SHARED storage is requested, either suspend the task until enough main storage becomes free to satisfy the request or, if the
NOSUSPEND option is specified, return control to the task without the requested storage. Suspended tasks may subsequently terminate abnormally if purged (abend code ASCP) or under deadlock timeout control (abend code
AKCS).
368
CICS for iSeries Application Programming Guide V5
