ENTMF 

The ALLOCATE Statement

The ALLOCATE statement allocates dynamic storage.

General Format

GUID-501EA7C4-A0B0-4D96-837D-163F1AADB82E-low.png

General Rules

  1. 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.
  2. 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.
  3. If the INITIALIZED phrase is specified, the allocated storage is initialized; If it is omitted, the contents of the allocated storage is undefined.
  4. If arithmetic-expression-1 and the INITIALIZED phrase are both specified, all storage bytes are initialized to binary zeroes.
  5. 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.
  6. 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.
  7. 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.
  8. The allocated storage persists until explicitly released using the FREE statement or the run unit is terminated, whichever occurs first.

Syntax Rules

  1. data-name-1 must be a level-01 or level-77 item defined in the Linkage Section.
  2. data-name-1 must not be:
    • reference modified.
    • a group item that contains an unbounded table.
  3. data-name-2 must be defined as USAGE IS POINTER.
  4. data-name-2 can be qualified or subscripted.
  5. If arithmetic-expression-1 does not equate to an integer, the result is rounded up to the next whole number.
  6. If arithmetic-expression-1 equates to zero or a negative value, data-name-2 is set to the predefined address NULL.
Parent topic: Statements
Related reference
The FREE Statement