ENTMF 

The ALLOCATE Statement

The ALLOCATE statement allocates dynamic storage.

General Format

Syntax for the ALLOCATE statement

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. integer-1 must be an unsigned integer with either the value of 24 or 31.
  4. data-name-2 must be defined as USAGE IS POINTER.
  5. data-name-2 can be qualified or subscripted.
  6. If arithmetic-expression-1 does not equate to an integer, the result is rounded up to the next whole number.
  7. If arithmetic-expression-1 equates to zero or a negative value, data-name-2 is set to the predefined address NULL.

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. The LOC phrase controls the type of memory address returned by ALLOCATE statements when the AMODE directive is set.
    • LOC 24 - the memory address is stored in 24-bit format, which is compatible with below-the-line storage on the mainframe.
    • LOC 31 - the memory address is stored in 31-bit format, which is compatible with above-the-line storage on the mainframe.
  4. When the LOC phrase is not specified:
    • LOC 24 is assumed whenever AMODE"24" is in effect.
    • LOC 31 is assumed whenever AMODE"31" is in effect.
  5. If the INITIALIZED phrase is specified, the allocated storage is initialized; If it is omitted, the contents of the allocated storage is undefined.
  6. If arithmetic-expression-1 and the INITIALIZED phrase are both specified, all storage bytes are initialized to binary zeroes.
  7. 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.
  8. 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.
  9. 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.
  10. The allocated storage persists until explicitly released using the FREE statement or the run unit is terminated, whichever occurs first.
Parent topic: Statements
Related reference
The FREE Statement