ALLOCATE statement
The ALLOCATE statement obtains dynamic storage.
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.
- integer-1
Must 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).
- data-name-2
Must be defined as USAGE POINTER or USAGE POINTER-32.
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.
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.
- LOC 64 causes ALLOCATE to attempt to acquire storage from above the 2 GB bar, regardless of the setting of the DATA compiler option.
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.
- LOC 64 is assumed to be specified whenever the LP(64) compiler option is in effect.
If 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.
If LOC 64 is specified and LP(32) is in effect, a diagnostic message will be issued.
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 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.
If 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.
- 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 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.
FREE statement
INITIALIZE statement
POINTER phrase
POINTER-32 phrase
DATA (Enterprise COBOL Programming Guide)
Storage and its addressability (Enterprise COBOL Programming Guide)