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.

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.
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.

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.

When data-name-2 references a USAGE POINTER or USAGE POINTER-32 data item, the allocated storage depends on the LP and DATA compiler options, as well as the LOC phrase settings. The following table shows how storage is allocated based on these settings:
Table 1. Location of allocated storage
data-name-2 USAGE LP compiler option DATA compiler option ALLOCATE LOC phrase Location of allocated storage
POINTER/POINTER-32 LP(32) DATA(31)/Not specified Not specified Below the bar
POINTER/POINTER-32 LP(32) DATA(24) Not specified Below the line
POINTER/POINTER-32 LP(32) DATA(24)/DATA(31)/Not specified LOC 24 Below the line
POINTER/POINTER-32 LP(32) DATA(24)/DATA(31)/Not specified LOC 31 Below the bar
POINTER/POINTER-32 LP(32) DATA(24)/DATA(31)/Not specified LOC 64 N/A1
POINTER LP(64) DATA(31)/Not specified Not specified/LOC 64 Above the bar
POINTER/POINTER-32 LP(64) DATA(31)/Not specified LOC 24 Below the line
POINTER/POINTER-32 LP(64) DATA(31)/Not specified LOC 31 Below the bar
POINTER-32 LP(64) DATA(31)/Not specified Not specified Below the bar
POINTER-32 LP(64) DATA(31)/Not specified LOC 64 N/A1
POINTER/POINTER-32 LP(64) DATA(24) LOC 24/LOC 31/LOC 64/Not specified N/A1
Note:
  1. A diagnostic message will be issued, and no storage will be 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.

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  
DATA directive
FREE statement  
INITIALIZE statement  
POINTER phrase
POINTER-32 phrase
DATA compiler option (Enterprise COBOL Programming Guide)  
Storage and its addressability (Enterprise COBOL Programming Guide)