Frees the storage that was allocated for a based or controlled variable identified by reference.
In the following example, the FREE statement frees the storage block allocated by the ALLOCATE statement.
DECLARE TABLE(100) FLOAT BASED; DECLARE P POINTER; . . . ALLOCATE TABLE SET(P); . . . FREE P->TABLE;
In the following example, the FREE statement frees an AREA.
DECLARE ITEM1 BIN BASED(O1);
DECLARE ITEM2 BIN BASED(O2);
DECLARE ITEM3 BIN BASED;
DECLARE A AREA(64);
DECLARE O1 OFFSET(A);
DECLARE O2 OFFSET;
DECLARE O3 OFFSET;
ALLOCATE ITEM1; /* implicitly in area A;
implicitly set O1 */
ALLOCATE ITEM2 IN(A); /* explicitly in area A;
implicitly set O2 */
ALLOCATE ITEM3 IN(A) SET(O3); /* explicitly in area A;
explicitly set O3 */
FREE ITEM1; /* both implicit */
FREE ITEM2 IN(A); /* IN is required */
FREE O3->ITEM3 IN(A); /* Locator and IN required */
Description
The FREE statement frees all blocks of storage that were allocated for based or controlled variables identified by reference.
If the reference is not locator-qualified in the FREE statement, the variable will be implicitly qualified using the locator from the declaration of the based variable. If the declaration had no locator, the FREE statement is in error.
If the allocation to be freed occurred in an area, either the IN clause must be specified or the based variable must be qualified by an offset variable that was associated with an area in its declaration.
The locator qualifier used explicitly or implicitly by the reference must point to a block of storage allocated by execution of an ALLOCATE statement. The results are unpredictable when a FREE statement is used on a based or controlled variable that has not had storage allocated for it by an ALLOCATE statement.
The reference must not be subscripted and must identify a nonmember based or controlled variable whose size, shape, and component data types are the same as were used when the storage was allocated.
When a FREE statement has freed storage allocated for a controlled variable, the next most recent allocation for that variable is made available and subsequent references refer to that allocation.
When a FREE statement has freed storage allocated for a based variable, that block of storage must no longer be referenced. Any pointers that address the block are invalid and must not be used. Violation of this rule produces unpredictable results.