Area Data

An area is a region of storage in which based variables can be allocated and freed. Area variables can have any storage class and may be scalars or arrays. Explicit declaration with an area attribute has the following format:

AREA[(exp [REFER (variable)])]

AREA (*)

The exp used with the area attribute specifies the number of bytes reserved for the area. This size is rounded up to an 8-byte boundary as necessary.

For an area with the STATIC storage class, the size must be an integer constant.

For areas having the AUTOMATIC, CONTROLLED, or BASED storage classes, the size is defined by an integer expression; if an area is a member of a BASED structure, however, the size specification can use the REFER option.

If neither expression nor asterisk is specified, the default size is 1000 bytes. For example,

DECLARE AREA1   AREA(4096), 
   AREA2        AREA,
   1 S       BASED,
   2 X       FIXED BIN(15),
   2 AREA3(1024 REFER(X));

An alternate way to declare an AREA is implicitly, through its use in the following contexts:

The IN option of an ALLOCATE statement. For example:
```
ALLOCATE X IN(A1);
```
The OFFSET attribute of an offset variable declaration. For example:
```
DECLARE 0 OFFSET(A1);
```

Area variables are always aligned on 8-byte boundaries. The UNALIGNED attribute is not applicable to AREA variables.

Only based variables can be allocated in an area. Use of an area allows related items to be allocated and freed only in that region of storage reserved for the area. The area can be assigned or transmitted as a unit, complete with all the allocations it contains. To preserve the desired alignment constraints in the area, the size of any allocation within the area is always rounded to an 8-byte boundary.

The amount of reserved storage that is actually in use is known as the "extent" of the area. When first allocated (prior to any allocation in it), the extent of the area is zero. The maximum extent is represented by the "area size." When a based variable is allocated or freed, the extent of the area is updated to reflect the change in the amount of storage in use. In addition, when a based variable is freed, the storage it occupied is added to a chain of available storage blocks within the area. The area extent and the free chain are maintained in an 8-byte control block, adjacent to the space reserved for the area.

Areas may be assigned and passed as arguments. However, areas cannot be compared or otherwise have any operators applied to them.

When an area variable is assigned to another, all allocations in the target area are freed and the extent of the target area is set equal to that of the source area.

The AREA condition is raised for an illegal area assignment detected at run-time. This situation occurs if the maximum size of the source area exceeds that of the target area. The AREA condition is also raised when an attempt is made to allocate a based variable within an area that has too little free storage to accommodate it. For more information about the AREA condition, see the information for AREA in the ON topic in the Statements help section.

Offset variables are used to indicate the locations of based variables within the area. See the discussion in the Offset Data topic of the Data Types help section .

Variables of type AREA display as <...> because of their complex content and potentially large size.