Get main 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.
Note for dynamic transaction routing: Using GETMAIN with SHARED could create inter-transaction affinities that adversely affect the use of dynamic transaction routing. See the CICS® Application Programming Guide for more information about transaction affinities.
GETMAIN gets a main storage area of the size indicated by the FLENGTH option. (You can also use the LENGTH option, but this is supported for compatibility purposes and you are strongly recommended to use FLENGTH.) The address of the area is returned in the pointer reference supplied in the SET option.
CICS always allocates on double-word boundaries and rounds the requested length up to the nearest double-word 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.
The data-key option on the GETMAIN command overrides the TASKDATAKEY option on the RDO TRANSACTION resource definition. The effect of the data-key options is summarized in the following table:
No data-key option | USERDATAKEY specified | CICSDATAKEY specified |
---|---|---|
Determined by TASKDATAKEY on transaction definition | User-key storage. From UDSA or EUDSA if SHARED option is not specified, or from SDSA or ESDSA if SHARED option is specified. | CICS-key storage. From CDSA or ECDSA. |
The storage that a task gets is available until it is released with a FREEMAIN command. For an area obtained without the SHARED option, only the task that acquired the storage may release it, and at task end CICS automatically releases such storage not already released. Note that any storage acquired with the SHARED option is accessible by all tasks, including those that are running with transaction isolation.
A SHARED area, on the other hand, is not released at task end and remains until explicitly freed; any task may issue the FREEMAIN. This means that you can use SHARED storage in task-to-task communication.
You cannot, however, use the storage obtained as a TIOA for subsequent terminal operations, because this could cause storage violations.
Specifying CICSDATAKEY ensures 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 maximum length that you can specify is the value of the corresponding DSA limit parameter, either 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.
If the length requested is bigger than the DSALIMIT or EDSALIMIT value, the LENGERR condition occurs. If it is not bigger than these limits, but is more than is available, NOSTG occurs.
If LENGTH is equal to zero, LENGERR occurs. If it is greater than the amount of storage available, NOSTG occurs.
Note, however, that 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, of course, negated by either NOHANDLE or RESP.
Be aware that if a task abends, any shared storage acquired is not automatically released.
Default action: terminate the task abnormally.
Default action: ignore the condition. An active HANDLE CONDITION NOSTG also raises this condition.
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