Storage Classes

The data types most commonly associated with based variables are pointers, areas, and offsets.

A pointer is a variable whose value represents the location in memory of another variable or data item. Pointers are used to access based variables and buffers allocated by the system as a result of the SET option of the READ and ALLOCATE statements.

Areas are regions of storage in which based variables can be allocated and freed. The use of areas can simplify and speed operations involving large or numerous based variables.

An offset is a value indicating the location of a based variable relative to the beginning of an area.

PL/I supports storage management in areas (see Section 3.10, “Area Data” for a description of area data). If you use the ALLOCATE statement with an area (either implied or explicitly specified), you can cause the allocation of storage to be performed in that area, instead of in the general memory pool for based and controlled storage.

Storage management in areas has a number of uses, including the following:

You allocate storage in areas with the IN and SET options on the ALLOCATE statement, the AREA and OFFSET data attributes, and the EMPTY built-in function.

The IN option on the ALLOCATE statement takes a reference to an area. If the IN option is not specified, the area is implied from the SET option if the SET option specifies an offset variable with a base area. The SET option itself can be implied from the base variable. Whether an area is specified explicitly or implied, the allocation is performed in that area instead of in the available memory pool for based and controlled storage. If an error is detected in the process, the AREA condition is raised.

PL/I provides full support for allocation in areas as specified in the ANSI full PL/I language standard. In addition, it provides extensions to full PL/I, which enhance the usefulness of areas or provide for improved compatibility with other implementations of PL/I. These extensions are as follows:

Note that the last three items in this list are features that differ in some other implementations of PL/I.

For examples showing allocation in areas, see Section 5.5.7, “Examples of Based Variables”.

A reference to a based variable (except in an ALLOCATE statement) must specify a pointer or offset reference designating the storage to be accessed. This qualifying pointer or offset reference can be implicit, if it is specified with the BASED attribute, or explicit, if the based variable reference is prefixed with a locator qualifier. A complete based variable reference (with the locator qualifier) has the following form:

qualifying-reference -> based-reference

Whether explicit or implicit, the qualifying reference must be to a pointer variable, a pointer-valued function, or an offset variable declared with a base area. The qualifying reference is evaluated each time the complete reference is evaluated and must yield a valid pointer value. If the qualifying reference is to an offset variable, the offset value is converted to a pointer using the base area specified in the offset variable's declaration.

You can use both implicit and explicit qualifications with the same based variable; the explicit qualifier overrides the implicit one. For example:

DECLARE X FIXED BIN BASED(P),
    P POINTER,
    (A,B) FIXED BIN;
P = ADDR(A);
X = ADDR(B)->X;

In the second assignment statement, the reference to X on the left-hand side of the assignment has the implicit qualifier P, which is the address of the variable A. The reference to X on the right-hand side is explicitly qualified with the address of another variable, B. This assigns the value of B to the variable A.

In PL/I, you can obtain a valid pointer value in any of the following ways:

A pointer value is valid only as long as the storage to which it applies remains allocated. Moreover, a pointer obtained by the application of ADDR to a parameter or an automatic variable is valid only as long as the parameter's procedure invocation exists, even though the storage pointed to may exist longer.

The NULL built-in function returns a null pointer value that can be assigned to pointer and offset variables, but that is not valid for qualifying a based variable reference.

These subsections discuss the dynamic allocation of storage by the ALLOCATE statement and the READ SET statement.

DECLARE LIST (10) FIXED BINARY BASED, ❶
        (LIST_PTR_A, LIST_PTR_B) POINTER;

ALLOCATE LIST SET (LIST_PTR_A); ❷
ALLOCATE LIST SET (LIST_PTR_B); ❸

LIST_PTR_A -> LIST(1) = 10; ❹
LIST_PTR_B -> LIST(1) = 15;

DECLARE 1 MATRIX_CONTROL_BLOCK STATIC EXTERNAL,
          2 MATRIX_POINTER POINTER,
          2 (ROW_SIZE,COL_SIZE) FIXED BINARY;

DECLARE 1 MATRIX(ROW_SIZE,COL_SIZE)
          BASED(MATRIX_POINTER);

GET LIST(ROW_SIZE,COL_SIZE);
ALLOCATE MATRIX;

DECLARE REC_PTR POINTER,
        NEW_BALANCE FIXED DECIMAL (6,2),
        INFILE FILE RECORD INPUT SEQUENTIAL;
DECLARE 1 RECORD_LAYOUT BASED (REC_PTR),
          2 NAME CHARACTER (15),
          2 AMOUNT PICTURE '999V99',
          2 BALANCE FIXED DECIMAL (6,2);
   .
   .
   .
READ FILE (INFILE) SET (REC_PTR) ;
   .
   .
   .
REC_PTR->BALANCE = NEW_BALANCE;
REWRITE FILE (INFILE);

The ADDR built-in function returns the storage location of a variable. You can use it to associate the storage occupied by a variable with the description of a based variable. For example:

DECLARE A FIXED BINARY BASED (X),
        B FIXED BINARY,
        X POINTER;

X = ADDR (B);
A = 15;

In this example, the variable A is declared as a based variable, with X designated as its pointer. The variable B is an automatic variable; PL/I allocates storage for B when the block is activated. When the ADDR built-in function is referenced, it returns the location in storage of the variable B, and the assignment statement gives this value to the pointer X. This assignment associates the variable A with the storage occupied by B. Because A is based on X and X points to B, an assignment statement that gives a value to A actually modifies the storage occupied by the variable B. Figure 5.4, “Using the ADDR Built-In Function” shows this example.

In most applications, the data type of a based variable reference is identical to the data type under which the accessed storage is allocated. However, it is not required that the data types be identical. The following sections discuss type-matching criteria in more detail.

DECLARE 1 S1 BASED (P),
          2 X,
            3 (A,B) FIXED BIN,
          2 Y,
            3 C CHAR(10),
            3 D(5) FLOAT;

DECLARE 1 S2 BASED(P),
          2 X,
            3 (A,B) FIXED BIN,
          2 Y,
            3 C CHAR(10),
            3 E BIT(32);

ALLOCATE S1;

S2.A = 3;   /* valid l-to-r match */
S2.C = 'X'; /* INVALID */

DECLARE X FLOAT BINARY(24);
DECLARE 1 S BASED(ADDR(X)),
          2 FRAC_1 BIT(7),
          2 EXP BIT(8),
          2 SIGN BIT(1),
          2 FRAC_2 BIT(16);

EXP = '0'B;  /* set exponent to 0 */
SIGN = '1'B; /* set sign negative */
X = X + 1;

The program DEFINED uses based variables and the READ SET statement to process a file of personnel data (PERSONNEL.DAT). The file has two types of valid records, a pay record and a health record, which are identified by a 1-character code in the first position. The two record types are declared as based structures (PAY_RECORD and HEALTH_RECORD), one of which is selected based on the record type character ('P' for pay, 'E' for health). Any record that does not begin with one of these characters is invalid and is written out as a reference to the based character variable INVALID_RECORD.

DEFINED: PROCEDURE OPTIONS(MAIN);

DECLARE P POINTER; /* pointer to structures */

DECLARE 1 PAY_RECORD BASED(P),
          2 RECORD_TYPE CHARACTER(1),
          2 NAME CHARACTER(20),
         /* the two structures differ in this member: */
          2 GROSS_PAY PICTURE '999999V.99';

DECLARE 1 HEALTH_RECORD BASED(P),
          2 RECORD_TYPE CHARACTER(1),
          2 NAME CHARACTER(20),
          2 EXAM_DATE CHARACTER(9);

DECLARE INVALID_RECORD CHARACTER(30) BASED(P);

DECLARE PERSONNEL RECORD FILE;
DECLARE PERSOUT STREAM OUTPUT PRINT FILE;

/* used to control DO group: */
%REPLACE NOTENDFILE BY '1'B;

ON ENDFILE(PERSONNEL) BEGIN;
   PUT FILE(PERSOUT) SKIP LIST
           ('All processing complete.');
   STOP;   /* program stops here */
   END;

OPEN FILE(PERSONNEL) INPUT TITLE('PERSONNEL.DAT');

DO WHILE(NOTENDFILE);
/* terminated by ENDFILE ON-unit */

READ FILE(PERSONNEL) SET(P);
/* P is the location of the
   record acquired by the READ statement */

IF P->PAY_RECORD.RECORD_TYPE = 'P' THEN
   PUT FILE(PERSOUT) SKIP LIST
          ('Name=',P->PAY_RECORD.NAME,
          'Gross pay=',P->GROSS_PAY);

ELSE       /* either a health record or an invalid record */
   DO;
   IF P->HEALTH_RECORD.RECORD_TYPE = 'E' THEN
   PUT FILE(PERSOUT) SKIP LIST
          ('Name=',P->HEALTH_RECORD.NAME,
          'Exam date:',P->EXAM_DATE);
   ELSE /* invalid record type */
   PUT FILE(PERSOUT) SKIP LIST
           ('Invalid record:',P->INVALID_RECORD);
   END;

END; /* repeat DO group until ENDFILE is signaled */

END DEFINED;

For example, assume that the file PERSONNEL.DAT contains these records:

PMary A. Ford        125000.55
EMary A. Ford        22July 80
t12345678901234567890pppppp.pp

The output file (PERSOUT.DAT) will contain the following output:

Name=   Mary A. Ford            Gross pay=      125000.55
Name=   Mary A. Ford            Exam date:      22July 80
Invalid record: t12345678901234567890pppppp.pp
All processing complete.

Notice these other features of the program:

The UNION attribute can be used to declare a single record with a variant portion in place of PAY_RECORD and HEALTH_RECORD. For example:

1 RECORD BASED(P),
  2 RECORD_TYPE CHARACTER(1),
  2 NAME CHARACTER(20),
  2 VARIANS UNION,
    3 GROSS_PAY PICTURE '999999V.99',
    3 EXAM_DATE CHARACTER(9)

Note that the UNION attribute is not available in many other PL/I implementations.

Because only the most recent generation of a controlled variable is available to a program, controlled variables provide an easy way to implement a stack. The ALLOCATE statement is equivalent to a push operation, and the FREE statement is equivalent to a pop operation. The ALLOCATION built-in function returns the number of generations of a variable, so you can use it to find out if the stack is empty. For example:

DECLARE NEXT_MOVE CHARACTER(5) CONTROLLED,
    DIRECTIONS(4) CHARACTER(5) INITIAL(
    'North','East','South','West'),
    D FIXED BINARY (7);
       ⋮
    ALLOCATE NEXT_MOVE;         /* Part of a loop that reports */
    NEXT_MOVE = DIRECTIONS(D);  /* moves in reverse order      */
       ⋮
    DO WHILE                    /* Print moves in correct order */
        (ALLOCATION(NEXT_MOVE) ^= 0);
        PUT SKIP LIST ('Go ', NEXT_MOVE);
        FREE NEXT_MOVE;
    END;

See Section 11.4.7, “ALLOCATION” for more information about the ALLOCATION built-in function.

You can use a controlled variable as the argument of the ADDR built-in function. If a generation exists, ADDR returns a pointer to it. If no generation of the variable exists, ADDR returns the null pointer. Thus, you can use ADDR to preserve a pointer to a generation of a controlled variable that later becomes hidden under further generations, as in the following example:

DECLARE STOPS CHARACTER (20) VARYING CONTROLLED,
    MIDPOINT CHARACTER (20) VARYING BASED (P),
    P POINTER;
       ⋮
    ALLOCATE STOPS;
    STOPS = CURRENT_LOC;
    IF I = 5 THEN P = ADDR(STOPS);
       ⋮
    PUT SKIP LIST (
        'End reached!  Halfway point was', MIDPOINT);

At a certain point during the execution of this program, the ADDR built-in function captures the address of the current generation of STOPS and assigns it to P. After more generations of STOPS have been allocated, MIDPOINT (which is based on P) has the value of that same intermediate generation of STOPS.

Note that the value of P (and therefore of MIDPOINT) is valid only so long as the intermediate generation of STOPS to which P points is allocated. As soon as that generation is freed, the value of P becomes invalid, and it must not be used in a pointer-qualified reference until it is reassigned.

A controlled variable cannot be used in a pointer-qualified reference. In the previous example, a reference like the following would be illegal:

P->STOPS

The ALLOCATE statement obtains storage for a based or controlled variable and sets (with based variables) a locator variable equal to the address of the allocated storage. The format of the ALLOCATE statement is as follows:

{ ALLOCATE }
{ ALLOC    }
allocate-item,...;

DECLARE STATE CHARACTER(100) BASED (STATE_POINTER),
        STATE_POINTER POINTER;

ALLOCATE STATE;

DECLARE BUFFER CHARACTER (BUFLEN) BASED,
         BUF_PTR POINTER;
   .
   .
   .
BUFLEN = 80;
ALLOCATE BUFFER SET (BUF_PTR);

The FREE statement releases the storage that was allocated for a based or controlled variable. The format of the FREE statement is as follows:

FREE free-item[,free-item ...];

FREE LIST;
FREE P->INREC;

ALLOCATE STATE SET (STATE_PTR);
   .
   .
   .
FREE STATE;

PL/I has a variety of dynamic storage management mechanisms available besides those for based and controlled variables. You can also use the following mechanisms:

These storage control mechanisms are generally similar in the amount of overhead that they require both in execution time and in storage space, although certain mechanisms have characteristics that make them useful in specific circumstances.

In general, the standard PL/I language manipulation of dynamic memory provides reasonable performance with some built-in checking.

If the defined variable is specified with the POSITION attribute, then both the defined variable and the base reference must be suitable for bit- or character-string overlay defining.

In brief, a variable is suitable for overlay defining if it consists entirely of characters or bits, and those characters or bits are packed into adjacent storage without gaps. Such a variable can be treated as a string or interpreted as different types of aggregates. For example:

DECLARE A (10) CHARACTER (5);
DECLARE B (5) CHARACTER (10) DEFINED (A);

A (1) = 'AAAAA';
A (2) = 'BBBBB';
PUT LIST (B(1));

Figure 5.5, “An Overlay Defined Variable” shows a 50-byte region of storage treated either as a 10-element array (A) of 5-character strings or as a 5-element array (B) of 10-character strings.

If the defined variable and its base reference have identical data types, a reference to the defined variable is equivalent to the base reference. In the case of overlay defining, the defined variable maps onto part of the base reference's storage as follows:

A variable V is suitable for character-string overlay defining if V is not an unconnected array and if one of the following criteria is satisfied:

A variable V is suitable for bit-string overlay defining if V is not an unconnected array and if one of the following criteria is satisfied: