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.


dfhs3_S2GFgetmain.html | Timestamp icon Last updated: Monday, 5 June 2017