A declaration of a based variable is a description of the generation: the amount of storage required and its attributes. (A based variable does not identify the location of a generation in main storage.) A locator value identifies the location of the generation. Any reference to a based variable that is not allocated is in error.
|
When reference is made to a based variable, the data and alignment attributes used are those of the based variable, while the qualifying locator variable identifies the location of data.
A based variable cannot have the EXTERNAL attribute, but a locator reference for a based variable can have any storage class, including based.
A based structure or union can be declared to contain adjustable area sizes, array-bounds, and string-length specifications, by using the REFER option. See REFER option (self-defining data). The maximum length of a based VARYING or VARYINGZ string must be equal to the maximum length of any string upon which the based VARYING or VARYINGZ string is overlaid. For example:
declare A char(50) varying based(Q),
B char(50) varying;
Q=addr(B);A based VARYING string can only be overlaid on a VARYING string; a based VARYINGZ string can only be overlaid on a VARYINGZ string.
Storage for a based variable can be allocated by using the ALLOCATE statement, the ALLOCATE built-in function, the AUTOMATIC built-in function, or the LOCATE statement. A based variable can also be used to access existing data by using the READ statement (with SET option), or the FETCH statement (with SET option), or the ADDR built-in function.
Based AREA variables can be allocated using the ALLOCATE statement; PL/I automatically initializes the area to EMPTY upon allocation. However, if you obtain storage for the area variable using the ALLOCATE or the AUTOMATIC built-in function, you must assign EMPTY to the variable after obtaining the storage.
Because a locator variable identifies the location of any generation, you can refer at any point in a program to any generation of a based variable by using an appropriate locator value. The following example declares that references to X, except when the reference is explicitly qualified, use the locator variable P to locate the storage for X.
dcl X fixed bin based(P);
The association of a locator reference in this way is not permanent. The locator reference can be used to identify locations of other based variables and other locator references can be used to identify other generations of the variable X. When a based variable is declared without a locator reference, any reference to the based variable must always be explicitly locator-qualified.
In the following example, the arrays A and C refer to the same storage. The elements B and C(2,1) also refer to the same storage.
dcl A(3,2) character(5) based(P),
B char(5) based(Q),
C(3,2) character(5);
P = addr(C);
Q = addr(A(2,1));
You can also use the DEFINED and UNION attributes to overlay variable storage, but DEFINED and UNION overlay the storage permanently. When based variables are overlaid with a locator reference, the association can be changed at any time in the program by assigning a new value to the locator variable.
For more information on the DEFINED and UNION attributes, refer to DEFINED and POSITION attributes, and Unions.
The INITIAL attribute can be specified for a based variable. The initial values are assigned only upon explicit allocation of the based variable with an ALLOCATE or LOCATE statement.