CICS Manual do Usuário -GETMAIN

GETMAIN

Gets main storage.

Sintaxe:

Descrição:

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

Because no default initialization is done, you must use the INITIMG option if you require the storage to be initialized to a specific bit configuration.

The storage that is acquired by a task is available until it is released with a FREEMAIN command.
For an area that is obtained by a GETMAIN command without the SHARED option, only the task that acquired the storage can release it; at task termination, CICS automatically releases any such storage that is not already released.

A SHARED area, on the other hand, is not released at task termination and remains until explicitly freed; any task can issue the corresponding FREEMAIN.
This means that you can use SHARED storage in task-to-task communication.
However, because no automatic release of such storage occurs, ensure that some task releases the storage when it is no longer needed, to prevent an overall shortage.

The following example shows how to get a 1024-byte area of main storage and initialize it to spaces:

    EXEC CICS GETMAIN
         SET(PTR)
         LENGTH(1024)
         INITIMG(BLANK)
    END-EXEC

You must define BLANK in your program as the character that represents a space.

Opções:

FLENGTH(data-value)

Specifies as a 32-bit binary value the number of bytes of storage that are required.
If the requested length is less than zero, the LENGERR condition occurs; otherwise, if more storage is requested than is currently available, the NOSTG condition occurs.
FLENGTH and LENGTH are mutually exclusive.

INITIMG(data-value)

Specifies, as a one-byte value, the bit configuration that is to be used by CICS to initialize every byte of the acquired storage.
If you omit this option, CICS does not initialize the storage.
In COBOL programs, you must specify the INITIMG argument as a one-byte data area that contains the required initialization value.

LENGTH(data-value)

Specifies, as a 16-bit binary value, the number of bytes of storage that are required.
LENGTH has an upper limit of 32767 bytes.
To request a larger area, you must use the FLENGTH option.
If the requested length is less than zero, the LENGERR condition occurs; otherwise, if more storage is requested than is currently available, the NOSTG condition occurs.
LENGTH and FLENGTH are mutually exclusive.
See LENGTH for more information about using this option.

NOSUSPEND

Provided for compatibility with other CICS environments.
It is non-operational in CICS systems, where the default action for the NOSTG condition is to terminate the task abnormally instead of suspending task activity until enough storage is available to satisfy the request.

SET(ptr-ref)

Specifies a pointer reference that is to be set to the address of the acquired main storage.
The pointer is set to the first byte of the storage area.
See INTO and SET for more information about using this option.

SHARED

Specifies that the storage allocation is to occur from the task shared storage pool instead of a task private storage pool.
This option also prevents the automatic release at task termination of storage that is acquired by the GETMAIN command, and therefore enables task-to-task communication.
The SHARED area is not released until a corresponding FREEMAIN command is issued by the requesting task or some other task.

Condições:

LENGERR

Occurs for the following conditions:
- The FLENGTH value is less than zero.
- The LENGTH value is less than zero.
Ação pré-definida: Terminates the task abnormally.

NOSTG

occurs if more storage is requested than is currently available.
Ação pré-definida: Terminates the task abnormally.

Informações relacionadas:

FREEMAIN