ALLOCATE statement

Function

The ALLOCATE statement allocates dynamic storage.

Format 1	If storage is requested for a data description (data-name-1) for which the BASED clause is specified, the address of the requested storage is allocated to this data description. If the RETURNING phrase is present, the data pointer identifier-2 also contains the address of the allocated storage.
Format 2	If storage is requested as a number of characters, the address of the allocated storage is returned in the data pointer identifier-2.

Format 1

---

ALLOCATE data-name-1 
    [INITIALIZED] [RETURNING identifier-2]

---

Syntax rule

1. data-name-1 must be an elementary item which is specified with the BASED clause.

2. If identifier-2 is a type-specific data pointer, data-name-1 must also be type-based and the associated types must match.

3. If data-name-1 is strongly typed, identifier-2 must also be a type-specific pointer which is allocated the same type as data-name-1.

4. identifier-2 must reference an elementary item of the category "data pointer".

Format 2

---

ALLOCATE arithmetical-expression CHARACTERS
    [INITIALIZED] RETURNING identifier-2

---

Syntax rule

1. identifier-2 may not be a type-specific data pointer.

2. identifier-2 must reference an elementary item of the category "data pointer".

General rules for formats 1 and 2

1. arithmetical-expression defines the number of bytes in storage which are requested. The result of the evaluation of arithmetical-expression is placed in an internal data item which is defined with PIC S9(9) BINARY .

2. If the result of the evaluation is less than or equal to NULL, no storage is requested and identifier-2 contains the predefined value NULL.

3. With format 1 the size of the requested storage is determined by how much space is required for a data description data-name-1. If a data description which is subordinate to data-name-1 contains an OCCURS DEPENDING clause, the maximum length of the record is requested.

4. If the requested storage space is available, it is allocated. With format 1 the address of data-name-1 is set to the address of the allocated storage. The data pointer identifier-2 from the RETURNING phrase is set to the address of the allocated storage.

5. If the requested storage space is not available, the address of data-name-1 and/or the data pointer identifier-2 from the RETURNING phrase are set to NULL. The exception condition EC-STORAGE-NOT-AVAIL occurs. If the check for EC-STORAGE-NOT-AVAIL is activated, the associated exception condition is triggered and control is transferred to the corresponding USE procedure. After the return from the USE procedure, processing continues with the executable statement following the ALLOCATE statement.

6. The INITIALIZED phrase in format 1 causes an INITIALIZE statement INITIALIZE dataname-1 WITH FILLER ALL TO VALUE THEN TO DEFAULT to be executed for dataname-1.

7. If the INITIALIZED phrase is missing in format 1, an INITIALIZE statement INITIALIZE data-name-1 WITH FILLER REPLACING DATA-POINTER BY NULL, PROGRAM-POINTER BY NULL, OBJECT-REFERENCE BY NULL is executed.

8. The INITIALIZED phrase in format 2 causes the allocated storage to be initialized with binary NULLS.

9. If the INITIALIZED phrase is missing in format 2, the content of the allocated storage is undefined.

10. The storage remains allocated until it is explicitly released with a FREE statement or the program run is terminated.