ALLOCATE

Purpose:

Allocates a block of storage for the values described by a based or controlled variable. The ALLOCATE statement also permits the assignment of explicit attributes to CONTROLLED variables at the time of allocation.

Syntax:

ALLOCATE var_ref [IN
			 (area_ref)] [SET(loc_ref)] [, var_ref [IN ( area_ref)]
			 [SET( loc_ref)]]...

For CONTROLLED variables:

ALLOCATE based-or-controlled-alloc[, based-or-controlled-alloc]...;

where based-or-controlled-alloc is:

Parameters:

var_ref: One or more references to a based or controlled nonmember variable or variables.

loc_ref: Specifies the locator variable (for based variables) to which the storage location is assigned if the SET option is chosen.

area_ref: Identifies the area in which the based storage is allocated if the IN option is used.

cvar_ref: A CONTROLLED variable

The dimension-attribute can be specified only for variables that are declared with a dimension-attribute, and it must specify the same number of dimensions as in the declaration.

The CHARACTER, BIT, and AREA attributes can be specified only for variables that are declared with the same attribute.

For more detailed information on BASED and CONTROLLED variables and their use with ALLOCATE statements, see the sections Based Variables and Controlled Variables in the chapter Storage Classes.

Description:

The ALLOCATE statement allocates a block of storage for the values described by a based variable.

The SET option and the IN option are not required in an ALLOCATE statement. If used, they can be specified in either order.

If the SET option is used in conjunction with any var_ref, the address of the allocated storage will be stored in the specified loc_ref for that var_ref. The SET option cannot be used when controlled variables are allocated.

If the SET option is not used, the allocated address will be stored in the locator reference that was assigned with the based variable when it was declared. If no locator reference was assigned with the based variable, an error occurs.

If the IN option is used, or if the SET option specifies an offset variable, the allocation occurs in an area. If the IN option is omitted and the SET option specifies an offset variable, that variable must, in its declaration, have been associated with an area. See the description of the OFFSET attribute in the section OFFSET in the chapter Declarations and Attributes.

Example:

Example 1

DECLARE
   1 A_STRUCT BASED (A_PTR),
      2 A_MEMBER FIXED BIN(15);

DECLARE (A_PTR, B_PTR, C_PTR) POINTER;

DECLARE
   1 B_STRUCT BASED (B_PTR),
      2 B_MEMBER FIXED BIN(15);

DECLARE
   1 C_STRUCT BASED (C_PTR);
      2 C_MEMBER FLOAT BIN(23);

DECLARE (P,Q) POINTER;

ALLOCATE A_STRUCT;
A_STRUCT.A_MEMBER = 5;
ALLOCATE B_STRUCT SET (P), C_STRUCT SET(Q);

In the preceding example, A_STRUCT is allocated, and since no SET option was specified and A_STRUCT was declared as based on A PTR, the allocated address is stored in A_PTR. When B_STRUCT is allocated, the SET option specifies that P is to be assigned the allocated address. When B_STRUCT and C_STRUCT are allocated, the SET options cause the addresses of the allocated storage for them to be assigned to P and Q, respectively.

Example 2

DECLARE (A, B)      AREA;
DECLARE A1          CHAR(20) BASED;
DECLARE A2          CHAR(20) BASED(O2);
DECLARE A3          CHAR(20) BASED(O3); 
DECLARE (O1, O2)    OFFSET(A);
DECLARE )3          OFFSET;
DECLARE (P1, P3)    POINTER;

ALLOCATE A1 SET(P1); 

ALLOCATE A1 SET(O1); 

ALLOCATE A2;

ALLOCATE A3 IN(B); 
P3 = POINTER(O3, B);

In Example 2 above, the first allocation of A1 is not in an area because the locator reference in the SET option specifies a pointer variable. The second allocation of A1 occurs in area A, because the locator in the SET option specifies an offset variable associated with area A. The allocation of A2 again occurs in area A, because A2 is based on offset variable O2, which was associated with area A in its declaration. The IN option causes the allocation of A3 to occur in area B. (Note that, in order to address A3, the POINTER built-in function must be used, because O3 was not declared with an area association).

Restrictions

None.