The ALLOCATE statement allocates dynamic storage.
General Format
General Rules
- If data-name-1 is specified:
- the amount of storage to be allocated is the number of bytes required to hold data-name-1. If the data description entry for data-name-1 contains a sub-ordinate item containing an OCCURS DEPENDING ON clause, the maximum length of the record is allocated.
- the address of the data item is set to the address of the obtained storage, to the same effect as
SET ADDRESS OF data-name-1 TO address.
- the RETURNING phrase can be omitted, but if specified, data-name-2 will contain that address.
- If arithmetic-expression-1 CHARACTERS is specified:
- arithmetic-expression-1 specifies the number of bytes of storage to allocate.
- the RETURNING data-item-2 must be specified, and will be set to the address of the obtained storage.
- If the INITIALIZED phrase is specified, the allocated storage is initialized; If it is omitted, the contents of the allocated storage is undefined.
- If arithmetic-expression-1 and the INITIALIZED phrase are both specified, all storage bytes are initialized to binary zeroes.
- If data-name-1 and the INITIALIZED phrase are both specified, the storage is initialized to the same effect as:
INITIALIZE data-name-1 WITH FILLER ALL TO VALUE THEN TO DEFAULT.
- If the specified amount of storage is available for allocation:
- If the RETURNING phrase is specified, the data item referenced by data-name-2 is set to the address of that storage.
- If data-name-1 is specified, the address of the 01 or 77 LINKAGE SECTION data item referenced by data-name-1 is set to the address of that storage, to the same effect as:
SET ADDRESS OF data-name-1 TO address-of-obtained-storage.
- If the specified amount of storage is not available for allocation:
- If the RETURNING phrase is specified, the data item referenced by data-name-2 is set to the predefined address NULL.
- If data-name-1 is specified, the address of the 01 or 77 LINKAGE SECTION data item referenced by data-name-1 is set to the predefined address NULL.
- The allocated storage persists until explicitly released using the FREE statement or the run unit is terminated, whichever occurs first.
Syntax Rules
- data-name-1 must be a level-01 or level-77 item defined in the Linkage Section.
- data-name-1 must not be:
- reference modified.
- a group item that contains an unbounded table.
- data-name-2 must be defined as USAGE IS POINTER.
- data-name-2 can be qualified or subscripted.
- If arithmetic-expression-1 does not equate to an integer, the result is rounded up to the next whole number.
- If arithmetic-expression-1 equates to zero or a negative value, data-name-2 is set to the predefined address NULL.
