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, 31 or 64.
  4. data-name-2 must be defined as USAGE IS POINTER or USAGE IS POINTER-32.
  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.
    • LOC 64 - the memory address is stored in 64-bit format, which is compatible with above-the-bar storage on the mainframe enabled via the LP(64) compiler option. Requires AMODE"64" to be set.

    If LOC 64 is specified and data-name-2 is defined as USAGE IS POINTER-32, a compiler error is reported, because the size of data-name-2 is insufficient for the 64-bit address.

  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.
    • LOC 64 is assumed whenever AMODE"64" is in effect.

    If the LOC phrase is not specified and data-name-2 is defined as USAGE IS POINTER, the allocated storage will be below the 2Gb bar unless AMODE"64" is set, in which case the allocate storage will be above the 2Gb bar.

    If the LOC phrase is not specified and data-name-2 is defined as USAGE IS POINTER-32, the allocated storage will always be below the 2Gb bar.

  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