ALLOCATE statement

The ALLOCATE statement obtains dynamic storage.

Format

Read syntax diagramSkip visual syntax diagramALLOCATE arithmetic-expression-1CHARACTERSdata-name-1 INITIALIZEDLOCinteger-1RETURNINGdata-name-2

If data-name-1 is specified, the address of the data item is set to the address of the obtained storage, as if the "SET ADDRESS OF data-name-1 TO address" statement was used. If a RETURNING data item is also specified, the pointer data item will contain that address.

If arithmetic-expression-1 CHARACTERS is specified, the RETURNING data-item-2 will be set to the address of the obtained storage.

data-name-1

Must be a level-01 or level-77 item defined in the LINKAGE SECTION.

If data-name-1 is specified, the RETURNING phrase can be omitted. Otherwise, the RETURNING phrase must be specified.

Cannot be reference modified.

Cannot be a group item that contains an unbounded table.

Start of changeinteger-1End of change
Start of change

Must be an unsigned integer with either the value of 24 or 31.

End of change
data-name-2

Must be defined as USAGE IS POINTER.

Can be qualified or subscripted.

arithmetic-expression-1
Specifies a number of bytes of storage to be allocated:
  • If arithmetic-expression-1 does not evaluate to an integer, the result is rounded up to the next whole number.
  • If arithmetic-expression-1 evaluates to 0 or a negative value, the data item referenced by data-name-2 is set to the predefined address NULL.

INITIALIZED phrase

The INITIALIZED phrase initializes the allocated storage:

  • If the INITIALIZED phrase is not specified, the content of the allocated storage is undefined.
  • If both arithmetic-expression-1 and the INITIALIZED phrase are specified, all bytes of the allocated storage are initialized to binary zeros.
  • If both data-name-1 and the INITIALIZED phrase are specified, the allocated storage is initialized as if an INITIALIZE data-name-1 WITH FILLER ALL TO VALUE THEN TO DEFAULT statement were executed.
Start of change

LOC phrase

The LOC phrase controls how ALLOCATE acquires storage:

  • LOC 24 causes ALLOCATE to acquire storage from below the 16 MB line, regardless of the setting of the DATA compiler option.
  • LOC 31 causes ALLOCATE to attempt to acquire storage from above the 16 MB line, regardless of the setting of the DATA compiler option.
    Note: It is still possible that storage is acquired below the 16 MB line with LOC 31 if storage above the 16 MB line is exhausted.

When the LOC phrase is not specified:

  • LOC 31 is assumed to be specified whenever the DATA(31) compiler option is in effect.
  • LOC 24 is assumed to be specified whenever the DATA(24) compiler option is in effect.
Note: It is recommended to use the default value of LOC unless dynamic storage below the 16 MB line is required when the DATA(31) option is in effect, or dynamic storage above the 16 MB line is desired when the DATA(24) option is in effect.
End of change

If data-name-1 is specified, the amount of storage to be allocated is the number of bytes required to hold an item as described by data-name-1. If a data description entry that is subordinate to data-name-1 contains an OCCURS DEPENDING ON clause, the maximum length of the record is allocated.

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, as if the "SET ADDRESS OF data-name-1 TO address-of-obtained-storage" statement was used.
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.
Start of changeThe DATA compiler option setting influences how ALLOCATE acquires storage:
  • If DATA(24) is in effect and the LOC 31 phrase of the ALLOCATE statement is not specified, ALLOCATE acquires storage from below the 16 MB line.
  • If DATA(31) is in effect and the LOC 24 phrase of the ALLOCATE statement is not specified, ALLOCATE will attempt to acquire storage from above the 16 MB line.
End of change

The allocated storage persists until explicitly released with a FREE statement or the run unit is terminated, whichever occurs first.

Start of changeYou can use ALLOCATE to dynamically increase the size of an UNBOUNDED table, see Example: ALLOCATE and FREE storage for UNBOUNDED tables.End of change

related references  
FREE statement  
INITIALIZE statement  
DATA (Enterprise COBOL Programming Guide)  
Storage and its addressability (Enterprise COBOL Programming Guide)