Data Types

All names referenced in a PL/I program must be declared explicitly, with the exception of entry-point names, statement labels, built-in functions, and the default file constants SYSIN and SYSPRINT. You declare a name and its data type attributes in a DECLARE statement. For example:

DECLARE AVERAGE FIXED DECIMAL;
DECLARE NAME CHARACTER (20);

The keywords DECIMAL, FIXED, and CHARACTER describe characteristics, or attributes, of the variables AVERAGE and NAME.

It is not always necessary to define all the characteristics, or attributes, of a variable; the PL/I compiler makes assumptions about attributes that are not explicitly defined. For example:

DECLARE NUMBER FIXED;

The default FIXED attribute implies the attributes BINARY(31,0). Thus, the variable NUMBER has the attributes FIXED BINARY(31,0).

Table 3.1, “Implied Attributes for Computational Data” shows the default attributes implied by each computational data attribute.

I = 1;

F = 1.333E-12;

PAY_PIC = 123.44;

DECLARE X FLOAT DECIMAL (49);
X = X + 1.3;

In PL/I, the notion of compatible data types is used in the rules for passing arguments by reference and for based, controlled, defined, or external variables. For two nonstructure variables to have compatible data types, the following attributes must agree. That is, if one variable has the attribute, the other variable must also have it after the application of default rules.

Two pictured variables must have identical pictures after the expansion of iteration factors.

In addition, the following values must be equal:

Two structure variables have compatible data types if they have the same number of immediate members, and if corresponding members have compatible data types.

In general, you can specify string lengths, area sizes, and array bounds with expressions or with asterisks. The values used to determine whether two variables have compatible data types are obtained as follows:

Consider the following example:

/* Example of extent determination */

DATAT: PROCEDURE (PTR1);

DECLARE N FIXED, S CHARACTER(N) BASED(PTR1);
DECLARE PTR1 POINTER;

N = 10;

CALL P(S);

P: PROCEDURE(A);

     DECLARE A CHARACTER(*), B CHARACTER(N);
     N = 20;
     PUT LIST(LENGTH(A),LENGTH(B),LENGTH(S));
     END P;

END DATAT;

The PUT statement writes out:

10     10     20

The assignment to N inside the procedure P affects the extent of S, but not the extents of A or B, which were frozen when P was invoked.

The PRECISION attribute applies to decimal and binary data as follows:

The scale of fixed-point data is the number of digits to the right of the decimal or binary point. Floating-point variables do not have a scale factor. In this manual, the letter p is used to indicate precision, and the letter q is used to indicate the scale factor.

You can specify both precision and scale in a declaration. For example:

DECLARE x FIXED DECIMAL(10,3) INITIAL(1.234);

This example indicates that the value of x has 10 decimal digits and that 3 of those are fractional. When a value is assigned to the variable, its internal representation does not include the decimal point; the previous value for x is stored as 1234, and the decimal point is inserted when the number is output. The scale factor has the effect of multiplying the internal representation of the decimal number by a factor of 10^-q (where q is the absolute value of the specified scale).

The ranges of values you can specify for the precision for each arithmetic data type, and the defaults applied if you do not specify a precision, are summarized as follows:

If no scale factor is specified for fixed-point data, the default is 0.

For fixed-point binary data, the scale factor must be within the range -31 through 31 and less than or equal to the specified precision. Positive scale factors for fixed binary numbers function according to the same principles as those for fixed decimal. That is, a positive scale factor is similar to multiplying the internal representation binary number by a factor of 2^-q.

A negative scale factor indicates that the number of fractional bits are shifted in the opposite direction. In effect, this is similar to multiplying the binary number by a factor of 2^q, where q is the absolute value of the specified scale. For example:

DECLARE (A,B) FIXED BINARY(31,-3),
        (C,D) FIXED BINARY(31,3);
A = 128;      /* output = 128   */
B = 7;        /* output =   0   */
C = 128;      /* output = 128.0 */
D = 7;        /* output =   7.0 */

PUT SKIP LIST (A,B,C,D);
END;

Internally, binary numbers undergo an implicit conversion and are represented as powers of 2. For instance, in the previous example variable A is first divided by 2³ because it is declared with a scale factor of -3. The stored number is 16. On output, the number 16 is multiplied by 2³ and the number is again 128. However, when variable B is first divided by 2³, the result is 0, which is the value of the stored number. Therefore, on output, 0 is multiplied by 2³ and the output is 0.

Integer variables declared in the previous example with a positive scale factor are output as they were input, but they are followed on the right with a decimal point and a 0.

Even though arithmetic operands can be of different arithmetic types, all operations must be performed on objects of the same type. Consequently, the compiler can convert operands to a derived type, as previously shown. Therefore, when you declare a fixed binary number with a scale factor and assign it a decimal value, the results may not be as you expect because the binary scale factor left-shifts the specified number of bits to the right of the decimal point. During conversion to a decimal representation, the difference between the resulting binary number and its decimal representation is not the equivalent of dividing or multiplying the decimal number by 10. Instead, the binary number is first converted to its internal representation and then this representation is converted to its decimal representation.

When excess fractional digits are truncated, no condition is signaled. If there is any resulting loss of precision, it may be difficult to detect because truncated fractional digits do not signal a condition.

For example:

A: PROCEDURE OPTIONS (MAIN);
   DECLARE A FIXED BIN (31,3),
           B DECIMAL (10,5),
           C DECIMAL (10,5);
A = .3;
B = 34.8;

C = MULTIPLY(A,B,10,5);

PUT SKIP LIST (A,B,C);
END;

Before the multiplication is performed, the variables are converted to fixed binary so that the operands share a common data type. However, after conversion, variable A is output as 0.2 rather than 0.3. The output from the previous example is:

0.2     34.80000    8.6875

If variable A was declared with the attributes FIXED DECIMAL (10,5), the output will be:

0.30000     34.80000    10.44000

The attributes FIXED and BINARY are used to declare integer variables and fractional variables in which the number of fractional digits is fixed (that is, nonfloating-point numbers). The BINARY attribute is implied by FIXED.

For example, a fixed-point binary variable can be declared as:

DECLARE X FIXED BINARY(31,0);

The variable X is given the attributes FIXED, BINARY, and (31,0) in this declaration. The precision is 31. The scale factor is 0, so the number is an integer.

There is no representation in PL/I for a fixed-point binary constant. Instead, integer constants are represented as fixed decimal. However, fixed decimal integer constants (and variables) are converted to fixed binary when combined with fixed binary variables in expressions. For example:

I = I+3;

In this example, if I is a fixed binary variable, the integer 3 is represented as fixed decimal; however, PL/I converts it to fixed binary when evaluating the expression.

Fixed binary variables have a maximum precision of 31, and therefore fixed binary integers can have values only in the range -2,147,483,648 through 2,147,483,647. An attempt to calculate a binary integer outside this range, in a context that requires an integer value, signals the FIXEDOVERFLOW condition.

The attributes FIXED BINARY are used to declare binary data in PL/I. The BINARY attribute is implied by FIXED. The format of a declaration of a single, fixed-point, binary variable is:

DECLARE identifier FIXED [BINARY] [(precision[,scale-factor])];

There is no form for a fixed-point binary constant, although constants of other computational types are convertible to fixed-point binary. A fixed-point binary variable usually receives given values by being assigned to an expression of another computational type or another fixed-point binary variable.

Fixed-point decimal data is used in calculations where exact decimal values must be maintained, for example, in financial applications. You can also use fixed-point decimal data with a scale factor of 0 whenever integer data is required.

The following sections describe fixed-point constants and variables and their use in expressions.

This discussion is divided into the following parts:

12
4.56
12345.54
-2
01.

DECLARE identifier [FIXED] DECIMAL [(p[,q])];

DECLARE PERCENTAGE FIXED DECIMAL (5,2);
DECLARE TONNAGE FIXED DECIMAL (9);

DECLARE I FIXED BINARY,
       SUM FIXED DECIMAL (10,2);

SUM = SUM + DECIMAL (I);

The floating-point data types provide a way to express very large and very small numbers such as in scientific calculations. All floating-point calculations are performed on values in one of the binary floating-point formats. In general, the precision of the result is determined by the maximum precision of any operands in the operation. The numerical result of an operation is rounded to the result precision.

The following sections describe floating-point constants and variables and their use in expressions.

This discussion of floating-point data is divided into the following parts:

 2E10
 -3E8
 32E-8
 .45632E16

DECLARE identifier FLOAT [BINARY] [(p)];

DECLARE X FLOAT BINARY(53);

DECLARE identifier FLOAT DECIMAL [(p)];

DECLARE X FLOAT DECIMAL (30);

DECLARE X FLOAT BINARY (53);
X = X + 1.3;

FLOAT BINARY (P) P ≤ 24
FLOAT DECIMAL (P) P ≤ 7

FLOAT BINARY (P)  24 < P ≤ 53
FLOAT DECIMAL (P) 7 < P ≤ 15

Use pictured data when you want to manipulate a quantity arithmetically and accept or display its value using a special format.

A picture specification (or picture) describes both the numeric attributes of a pictured variable and its input/output (I/O) format. A simple picture might look like this in a DECLARE statement:

DECLARE CREDIT PICTURE '$99999V.99DB';

This statement declares the variable CREDIT as a pictured variable. The characters within the apostrophes describe its format.

The formatting possible with pictured data is useful in many applications, but pictured data is much less efficient than fixed-point decimal data for strictly computational use.

This section discusses the following topics:

The formatting possible with pictured data is useful in many applications, but pictured data is less efficient than fixed-point decimal data in computations. Therefore, do not use pictured data unless you need the formatting.

DECLARE PRICE PICTURE '$$9V.99',
    BAD_PRICE PICTURE '$$9.99';
        PRICE = .98;      /* Output as $0.98  */
        BAD_PRICE = .98;  /* Output as $0.00  */
        PRICE = 98;       /* Output as $98.00 */
        BAD_PRICE = 98;   /* Output as $0.98  */

'(4)9'

'9999'

'[left-part]center-part[right-part]'

{ $ }
{ + }
{ - }
{ S }

{ $  }
{ +  }
{ -  }
{ S  }
{ CR }
{ DB }

{ 9...[V[9...]]         }
{ V9...                 }
{ Z...[9...[V[9...]]]   }
{ Z...[V[9...]]         }
{ [Z...]VZ...           }
{ *...[9...[V[9...]]]   }
{ *...[V[9...]]         }
{ [*...]V*...           }
{ ++...[9...[V[9...]]]  }
{ ++...[V[9...]]        }
{ - -...[9...[V[9...]]] }
{ - -...[V[9...]]       }
{ SS...[9...[V[9...]]]  }
{ SS...[V[9...]]        }
{ $$...[9...[V[9...]]]  }
{ $$...[V[9...]]        }
{ +[+...]V+...          }
{ -[-...]V-...          }
{ S[S...]VS...          }
{ $[$...]V$...          }

'****99'

'****V.**'

'ZZ99V.99'

'(4)SV.99'

'ZZZ,ZZZV.99'

'ZZZ.ZZZV,99'

'ZZZ/ZZZ/ZZZ'

'$$$-99v.99'

'(4)-V.ZZZ'

CREDIT = '$12443.00';

CREDIT = -12443.00;

DECLARE CREDIT PICTURE '$99999V.99DB';

$12443.00    /* a positive value (credit) */

$12443.00DB  /* a negative value (debit)  */

A character-string constant can consist of any characters in the DEC Multinational Character Set (see Appendix B, Digital Multinational Character Set). When you use character-string constants in a program, you must enclose the strings in apostrophes, as shown in the following examples:

'Total is:'
'Enter your name and age'

'Error - value is out of range'

To specify a string containing a literal apostrophe, use two apostrophes within the string. For example:

'Life isn''t fair'

When a character string that has embedded apostrophes is specified as previously shown, the final result contains only a single apostrophe.

Note that the quotation mark (") is not a legal delimiter for PL/I character constants.

(4)'season   '

'season   season   season   season   '

INITIAL ((10)('ABCABC'))

INITIAL ((10)((2)'ABC'))

The CHARACTER keyword identifies a variable as a character-string variable in a declaration. The format for specifying a character-string variable is:

DECLARE variable-name
[ CHARACTER [(n)]         ];
[ VARYING CHARACTER [(n)] ]
[ CHARACTER [(n)] VARYING ]

The CHARACTER keyword identifies a character-string variable in a declaration.

The addition of the VARYING attribute indicates a varying-length character-string variable.

An optional number in parentheses specifies the length of the variable, that is, the number of bytes needed to contain its value (maximum is 32,767). This length attribute specifies either the length of all values of the variable (fixed-length strings) or the maximum length of a value of the variable (varying-length strings). If the length is not specified, PL/I uses the default length of one character, or byte. The rules for specifying the length are:

If specified, n must immediately follow the keyword CHARACTER and must be enclosed in parentheses.

DECLARE NAME CHARACTER (20) VARYING;
NAME = 'COOPER';
NAME = 'RANDOM FACTOR';

The PL/I language makes a distinction between aligned and unaligned (fixed-length) character-string variables. (No such distinction is made for varying character strings or for character-string constants.) A character-string variable is aligned if it is declared with the ALIGNED attribute.

This distinction affects only argument passing. If a procedure declares a parameter as ALIGNED CHARACTER, and if the corresponding argument is an unaligned character-string variable or vice versa, the actual argument will be a dummy variable. For example:

DECLARE GETSTRING ENTRY (CHARACTER (*) ALIGNED);
DECLARE STRING CHARACTER (8);
CALL GETSTRING (STRING);

PL/I constructs a dummy variable here to pass the unaligned string variable STRING to the called procedure GETSTRING, rather than passing the actual argument by reference.

All character strings on the VAX and Alpha hardware are aligned on byte boundaries. You should not use the ALIGNED attribute to declare character-string variables.

To specify a bit-string constant, enclose the string in apostrophes and follow the closing apostrophe with the letter B. For example:

'0101'B
'10101010'B
'1'B

The length of a bit-string constant is always the number of binary digits specified; the B does not count in the length of the string. You can specify a bit-string constant with a maximum of 1000 characters between the apostrophes.

You can also specify a bit-string constant using the following syntax:

'character-string'Bn

This format allows you to specify bit-string constants with bases other than 2. You can use base 4, 8, and 16, where n equals 2, 3, and 4 respectively. For example:

'EF8'B4
'117'B3
'223'B2

These constants specify the hexadecimal value EF8, the octal value 117, and the base 4 value 223. All such constants are stored internally as bit strings, not as integer representations of the value.

The valid characters for each type of bit-string constant are as follows:

Using the B format items, you can also acquire or output (with the GET EDIT and PUT EDIT statements) bit-string data in binary, base 4, octal, or hexadecimal format. See Section 9.2.4.2, “B Format Items” for more information on the B format item.

(r)'string'Bn

DECLARE (A) BIT (800);
     A = (400) '2'B2;
     PUT SKIP LIST ((A));
END;

'10101010101010101010101010101010
    ⋮
10101010101010101010101010'B

INITIAL ((10)('ABCABC'B4))

INITIAL ((10)((2)'ABC'B4))

Use the BIT attribute to declare a bit-string variable. The format is:

DECLARE variable-name BIT [(length)];

You can optionally specify the length of the variable in parentheses. The length can be from 0 to 32,767; the default length is one bit. The rules for specifying the length are as follows:

A program can assign to a bit-string variable a value larger or smaller than the variable's defined length. In such cases, PL/I does the following:

You can convert bit-string variables to other data types; however, there are some precautions you must observe if you do so. Section 6.4, “Data Type Conversion of Operands and Expressions” describes how to convert bit-string variables.

PL/I distinguishes between aligned and unaligned bit-string variables. (Bit-string constants are always unaligned.) A bit-string variable is aligned only if it is declared with the ALIGNED attribute, as shown in the following example:

DECLARE FLAGS BIT (8) ALIGNED;

If the default packed alignment is in effect, PL/I allocates storage for an aligned bit-string variable on a byte boundary and reserves an integral number of bytes to contain the variable. If natural alignment is in effect, PL/I allocates storage for an aligned bit-string variable on a longword boundary and reserves an integral number of longwords to contain the variable. See the PL/I for OpenVMS Systems User Manual for more information on the /ALIGN and /DATA command line qualifiers, which affect what type of alignment is in effect.

Unaligned bit-string variables always occupy only as many bits as are needed to contain them. They need not be on byte boundaries. You can optionally specify the UNALIGNED attribute in a declaration; UNALIGNED is the default for bit strings.

In general, operations involving unaligned bit-string variables are less efficient than those involving aligned bit-string variables. Unaligned bit-string variables are also invalid as the targets of the FROM and INTO options of record I/O statements, and as the argument of the ADDR built-in function. Moreover, most non-PL/I programs that accept bit-string arguments require the strings to be aligned.

In most cases, you should declare bit-string variables with the ALIGNED attribute. Use unaligned bit-string variables when bit strings must be packed as tightly as possible, for example, in arrays and in structures. See Section 2.2.1, “ALIGNED Attribute” for a description of the ALIGNED attribute.

In this discussion, the term most significant bit means the leftmost bit in an external representation of a string, as, for example, when the string is output by the PUT LIST statement. The least significant bit is the rightmost bit in the external representation.

The notion of significance has no meaning for bit strings unless they are used to store integers. PL/I permits the use of bit strings for this purpose, and has defined rules for conversions between bit strings and other data types.

You should use the UNSPEC built-in function and UNSPEC pseudovariable when you must store integers in a compact form. Otherwise, use the data types FIXED BINARY and FIXED DECIMAL for integer arithmetic.

In Endless PL/I, bit strings are stored in memory with the leftmost bit (as represented by PUT LIST) in the lowest memory location, and bits following the leftmost in successively higher memory locations. This representation of a bit string is reversed by PUT with respect to a conventional picture of memory locations, in which the lowest location appears on the right and higher locations on the left. If you are accustomed to using PL/I on computers other than OpenVMS systems and if you do not change your data to correct for this difference, the result is likely to be in error.

If you wish to use bit strings to represent integers and you would like to associate the leftmost bit (as it might be represented in a PUT LIST statement) with the Most significant bit, use the BINARY builtin function, an example of which appears in Section 11.4.43, “INT”.

PL/I defines conversions between bit-string data and other data types, and the PL/I compiler carries out these conversions. However, the conversions defined by PL/I are not always straightforward or intuitive; the padding and truncation that take place during assignment of bit strings of different lengths result in implicit multiplication or division of the bit string's integer value. For example:

DECLARE BITSTR BIT (10);
        BITSTR = 1;
        PUT LIST (BITSTR);

The output is:

'0001000000'B

The result may seem incorrect, but it conforms to PL/I's rules for conversion to bit strings. In this case, the fixed-decimal constant 1 is converted to a FIXED BINARY(4) value, which is in turn converted to an intermediate bit string of length 4:

'0001'B

Next, this intermediate bit string is assigned to the variable BITSTR. Because BITSTR is of length 10, the intermediate bit string is padded on the right with zeros, producing the result as output by PUT LIST. If you now attempt to interpret the value of BITSTR as an integer (for example, by using BITSTR as the argument of the BINARY built-in function), the result would be 64, not 1.

Extra execution time is required to reverse the order of bits when the integer's value is computed. Using arithmetic variables to represent integers is more efficient.

Because of the unexpected results and longer execution time, avoid using bit strings to represent integers or other data types.

Expressions containing pointer variables are restricted to the relational operators equal (=) and not equal (^=).

For example, to test whether a pointer is currently pointing to valid storage, you can write the following statement:

IF LIST_POINTER ^= NULL() THEN
   DO;

The NULL built-in function always returns a null pointer value.

You can use pointer variables in simple assignment statements that assign a pointer value to a pointer variable. For example:

LIST_POINTER_1 = LIST_POINTER_2;

LIST_END = NULL();

You can also use a pointer variable as the source or target in an assignment statement involving an offset variable or offset value.

A pointer occupies a longword (32 bits) of storage and represents a virtual memory address.

Any label constant except the label of a PROCEDURE or FORMAT statement can have a single subscript. Subscripts must be specified with integer constants; a subscript must appear in parentheses following the label name. An example for VAX and Alpha is:

PART(1):
   ⋮
PART(2):
   ⋮
PART(*):

When labels are written this way, the unscripted label name represents the implicit declaration of a label array constant. In this example, the array is named PART and is treated as if it were declared within the block containing the subscripted labels. In VAX, a default label can be created by using the asterisk (*) in place of a label constant. If a default label is used, it must be the last label in the list. If the variable subscript is out of range and the default label is present, the default label will be executed.

Elements of the array can be referenced in GOTO statements that specify a subscript. For example:

GOTO PART(I);

I is a variable whose value represents the subscript of the element of PART that is the label to be given control.

Within a single block, you cannot use the same subscript value in two different subscripted references with the same name. For example:

PART(1):

This label array constant can be used only once in a block. However, the subscript values are not constrained to be in any particular order or to be consecutive. For example, you can use the array constants PART(1) and PART(3) without using PART(2).

If a name is used as a label array constant in two or more different blocks, each declaration of the name is treated as an internal declaration. For example:

LIST(2): RETURN;
BEGIN;
   GOTO LIST (ELEMENT);
   LIST(1):;
   LIST(3):
   END;

In this example, the value of ELEMENT cannot cause control to pass to the RETURN statement labeled LIST(2) in the containing block. The subscripted LIST labels in the begin block restrict the scope of the name to that block.

Whenever a reference to a label constant is interpreted, the result is a label value. A label value has two components:

The GOTO statement with a label reference transfers control to the designated statement in the designated block activation. If the target block activation is different from the block activation in which the GOTO statement is executed, then the GOTO is nonlocal. For example:

DECLARE LV LABEL; /* LABEL variable */
   .
   .
   .
LV = L;           /* assigns a bound label value to LV */


BEGIN;
   .
   .
   .
GOTO LV;          /* nonlocal GOTO */
END;

L: RETURN;

Operations on label values are restricted to the operators = and ^= for testing the equality or inequality of two values. Two values are equal if they refer to the same statement in the same block activation.

Any reference to a label value after its block activation ceases to exist is an error with unpredictable results.

When an identifier is explicitly declared with the LABEL attribute, it acquires the VARIABLE attribute by default. You can use such a variable to denote different label values during the execution of the program. For example:

DECLARE PROCESS LABEL;
   .
   .
   .
   IF CODE THEN
      PROCESS = BILLING;
   ELSE
      PROCESS = CHARGE;
   .
   .
   .
GOTO PROCESS;

When the GOTO statement evaluates the reference to the label PROCESS, the result is the current value of the variable. The GOTO statement transfers control to either of the labels BILLING or CHARGE, depending on the current value of the Boolean variable CODE.

You can also give values to label variables by passing label values as arguments or by returning a label value as the value of a function (although the latter method can lead to programming errors that are difficult to diagnose). For example:

CALL COMPUTER(ERROR_EXIT, YVAL, XVAL);
   .
   .
   .
ERROR_EXIT:

In this example, the actual argument that is passed for ERROR_EXIT is a dummy argument whose value consists of the following:

Figure 3.12, “Variable Label Data Representation” shows the internal representation of variable label data.

You declare entry constants by using labels on PROCEDURE or ENTRY statements.

You declare internal entry constants by using labels on PROCEDURE or ENTRY statements whose procedure blocks are nested in another block. You can use an internal entry constant anywhere within its scope to invoke its procedure block.

You declare external entry constants either by using labels on PROCEDURE or ENTRY statements that belong to external procedures, or by explicitly declaring the constant names with the ENTRY attribute. You can use an external entry constant to invoke its procedure block from any program location that is within its scope. Its scope is either the scope of its declaration (as a label) or the scope of a DECLARE statement for the constant.

In DECLARE statements, you declare external entry constants with the ENTRY attribute. The declaration must agree with the actual entry point. That is, the declaration of the external entry constant must contain parameter descriptors for any parameters specified at the entry point, and, if the entry constant is to be used in a function reference, the declaration must have a returns descriptor describing the returned value.

Whenever a reference to an entry constant is interpreted, the result is an entry value. An entry value is the entry point of a procedure, and it serves to activate the block in which the entry point is declared (that is, the block in which the entry point's name appears as the label of a PROCEDURE or ENTRY statement). This block activation is the current block activation if the entry point belongs to the current block. If the entry point belongs to a containing block, the activation is on the chain of parent activations that ends at the current block activation.

No conversions are defined between entry data and other data types. You can assign an entry variable only the value of an entry constant or the value of another entry variable. The only operations that are valid for entry data are comparisons for equality (=) and inequality (^=). Two entry values are equal if they refer to the same entry point in the same block activation.

PL/I supports the passing of external procedures, but not internal procedures, as entry value parameters. To pass an internal procedure, use an entry parameter.

Entry variables are variables (including parameters) that take entry values. If the VARIABLE attribute is specified with the ENTRY attribute in a DECLARE statement, the declared identifier is an entry variable. You can assign to an entry variable either another entry variable or an entry constant.

When an entry variable is used to invoke a procedure, its declaration must agree with the definition of the entry point. If the value you assign to an entry variable specifies an entry point with parameters, the parameters must be described with parameter descriptors in the declaration of the variable. If the assigned value specifies an entry point that is invoked as a function, then the declaration of the entry variable must have a RETURNS attribute that describes the data type of the returned value.

The scope of an entry variable name can be either internal or external. If neither the EXTERNAL nor the INTERNAL attribute is specified with the entry variable, the default is INTERNAL.

You can use the entry variable to represent different entry points during the execution of the PL/I program. For example:

DECLARE E ENTRY VARIABLE,
        (A,B) ENTRY;
        E = A;
        CALL E;

The entry constant A is assigned to the entry variable E. The CALL statement results in the invocation of the external entry point A.

You can also declare arrays of entry variables. The following example shows an array of external functions:

DECLARE EXTRACT(10) ENTRY (FIXED,FIXED) VARIABLE RETURNS (FLOAT),
        GETVAL FLOAT;

        GETVAL = EXTRACT(3)(1,3);

This assignment statement references the third element of the array EXTRACT. When the statement is executed, this array element must contain a valid entry value.

Figure 3.13, “Variable Entry Data Representation” shows the internal representation of variable entry data.

You declare file constants by using the FILE attribute without the VARIABLE attribute. All file constants are external by default. To define an internal file constant, you must specify the INTERNAL attribute. For example:

DECLARE INFILE FILE;

This declaration declares a file constant named INFILE whose attributes include EXTERNAL by default.

DECLARE INFILE FILE INTERNAL;

This declaration specifies that the file constant named INFILE is internal to the block in which it is declared.

If you declare a file constant as EXTERNAL, you must use identical attributes, including ENVIRONMENT attributes, in all blocks that declare the constant. Otherwise, PL/I uses the last set of attributes encountered during compilation and ignores the others.

Whenever a reference to a file constant is interpreted, the result is a file value. A file value is a pointer to the file control block for the file with which the constant is associated.

PL/I supports the passing of external files, but not internal files, as file value parameters. To pass an internal file, use a file parameter.

File variables are variables (including parameters) that take file values. If the VARIABLE attribute is specified with the FILE attribute in a DECLARE statement, the declared identifier is a file variable. You can assign to a file variable either another file variable or a file constant.

A file variable is represented internally as a longword that contains a pointer to a file control block. The value of the file variable, when evaluated, is the address of the file control block for the file with which the variable is currently associated.

The scope of a file variable name can be either internal or external. If neither the EXTERNAL nor the INTERNAL attribute is specified with the file variable, the default is external.

If you declare a file variable implicitly or explicitly as EXTERNAL, you must use identical attributes, including ENVIRONMENT attributes, in all blocks that declare the variable. Otherwise, PL/I uses the last set of attributes encountered during compilation and ignores the others.

You can use the file variable to represent different files during the execution of the PL/I program. For example:

DECLARE F FILE VARIABLE,
        (A,B) FILE;
        E = A;
        CALL READFILE(E);

The file constant A is assigned to the file variable E. The CALL statement results in the invocation of the entry point READFILE with file A as its parameter.

You can also declare arrays of file variables. The following example shows an array of external file variables:

DECLARE FILELIST(10) FILE VARIABLE,
        MYFILE FILE VARIABLE;

        MYFILE = FILELIST(3);

This assignment statement references the third element of the array FILELIST. When the statement is executed, this array element must contain a valid file value.

Expressions containing area variables are restricted to the relational operators equal (=) and not equal (^=) and to comparison to the empty () built-in function (BIF).

For example, to test whether an area is empty, that is, to determine whether it currently has storage allocated in it, you can write the following statement:

IF MYAREA = EMPTY() THEN
   DO;

The EMPTY() built-in function always returns an empty area value.

You can use area variables in simple assignment statements that assign one area variable to another. For example:

AREA_1 = AREA_2;

AREA_2 = EMPTY();

An area can be the source or target of data transmission in READ and WRITE record I/O statements. If the area is written by itself (not as a member of a structure), only the current allocated portion is transmitted unless the SCALARVARYING option of the ENVIRONMENT attribute was specified when the file was opened.

An area occupies the number of bytes, specified in the extent, of storage. Since this storage includes overhead used by PL/I for bookkeeping, slightly less than the full amount (specified in the extent) is available for program allocations.