S2GF gate, GETMAIN function
The GETMAIN function of the S2GF gate is used to allocate an element of storage from a subpool.
Input Parameters
- SUBPOOL_TOKEN
- Optional Parameter
- A token that identifies the subpool within which the element is allocated.
- SUSPEND
- Specifies the action when there is insufficient storage to satisfy the request. When the value is YES, the caller is suspended until the request can be satisfied. When the value is NO, REASON is set to INSUFFICIENT_STORAGE.
- Values for the parameter are as follows:
- NO
- YES
- GET_LENGTH
- Optional Parameter
- The length of the storage requested.
- INITIAL_IMAGE
- Optional Parameter
- An optional byte value to which each byte in the new
element is set, up to a maximum of 2 GB.
Consider carefully whether to use this parameter with 64-bit storage, because system resources to support the allocated storage are required immediately, and auxiliary storage is required if storage needs to be paged out. To avoid using too much real memory, a maximum of 2 GB of storage is initialized, even if more than 2 GB of storage is requested.
If you do not specify an INITIAL_IMAGE parameter, minimal system resources are required until the requested 64-bit storage is used.
- LOCK_POOL
- Optional Parameter
- Indicates whether access to the subpool is controlled by a lock.
- Values for the parameter are as follows:
- NO
- YES
- REMARK
- Optional Parameter
- An optional 8-character field that identifies the GETMAIN operation for problem determination. This field is highlighted when the GETMAIN trace is interpreted. Typically, it is the name of the control block whose storage is being obtained.
Output Parameters
- REASON
- The following values are returned when RESPONSE is DISASTER:
- ABEND
- ACTIVATE_FAILURE
- LOOP
- The following values are returned when RESPONSE is EXCEPTION:
- INSUFFICIENT_STORAGE
- The following values are returned when RESPONSE is INVALID:
- INVALID_GET_LENGTH
- INVALID_INITIAL_IMAGE
- INVALID_STORAGE_CLASS
- INVALID_SUBPOOL_TOKEN
- NO_GET_LENGTH
- NOT_SUBPOOL_OWNER
- SUBPOOL_LOCK_FAILED
- SUBPOOL_UNLOCK_FAILED
- ADDRESS
- The 64-bit address of the new element.
- RESPONSE
- Indicates whether the domain call was successful. For more information, see RESPONSE parameter on domain interfaces.
- ELEMENT_LENGTH
- Optional Parameter
- The length of the new element.