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

Start of changeMust be an unsigned integer with value of 24, 31 or 64. The default for LP(64) is 64, and for LP(32) is 31. The value 64 is not supported in LP(32).End of change

End of change
data-name-2

Must be defined as USAGE POINTER Start of changeor USAGE POINTER-32End of change.

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.
  • Start of changeLOC 64 causes ALLOCATE to attempt to acquire storage from above the 2 GB bar, regardless of the setting of the DATA compiler option.End of change

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.
  • Start of changeLOC 64 is assumed to be specified whenever the LP(64) compiler option is in effect.End of change
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.

Start of changeIf LOC 64 is specified and data-name-2 references a USAGE POINTER-32 data item, a diagnostic message will be issued, because the size of the data item is too small for the 64-bit address.End of change

Start of changeIf LOC 64 is specified and LP(32) is in effect, a diagnostic message will be issued.End of change

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.

Start of changeIf the LOC phrase is omitted and data-name-2 references a USAGE POINTER data item:
  • If LP(64) is in effect, the allocated storage will be above the 2 GB bar.
  • If LP(32) is in effect, the allocated storage will be below the 2 GB bar.
End of change

Start of changeIf the LOC phrase is omitted and data-name-2 references a USAGE POINTER-32 data item, the allocated storage will always be below the 2 GB bar regardless of the setting of the LP compiler option.End of change

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.

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

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

Related references  
FREE statement  
INITIALIZE statement  
Start of changePOINTER phraseEnd of change
Start of changePOINTER-32 phraseEnd of change
DATA (Enterprise COBOL Programming Guide)  
Storage and its addressability (Enterprise COBOL Programming Guide)