Declarations

A simple declaration defines a single name and describes its attributes. The format of a simple declaration is:

DECLARE identifier [attribute ...] ;

The following are examples of simple declarations:

DECLARE COUNTER FIXED BINARY (7);
DECLARE TEXT_STRING CHARACTER (80) VARYING;
DECLARE INFILE FILE;

Names that are not given specific attributes in a DECLARE statement or that are referenced without being declared, receive the default attributes FIXED BINARY (31,0) AUTOMATIC. Note that the compiler issues a warning message whenever it gives these default attributes to a name.

You can declare a variable outside any procedure. Any variable so declared will be visible within all procedures contained by the module. The format for declarations outside procedures is the same as for other declarations, except that the storage-class attribute cannot be AUTOMATIC. If a storage-class is not specified or is specified as AUTOMATIC, the compiler will issue a warning and supply the STATIC attribute. The following example shows the use of this type of declaration:

DECLARE A STATIC FIXED BINARY(31);
   .
   .
   .
FIRST: PROCEDURE;
    DECLARE B FIXED BINARY(31);
       .
       .
       .
END FIRST;

SECOND: PROCEDURE;
    DECLARE C FIXED BINARY(31);
       .
       .
       .
END SECOND;

In this example, variable A is visible in both the FIRST and SECOND procedures, but variables B and C are visible only in their containing procedures.

Multiple simple declarations define two or more names and their individual attributes. This format of the DECLARE statement is:

DECLARE identifier [attribute ...]
        [,identifier [attribute ...]] ...;

When you specify more than one set of names and their attributes, separate each name and attribute set from the preceding set with a comma. A semicolon must follow the last name.

The following is an example of multiple declarations:

DECLARE COUNTER FIXED BINARY (7),
        TEXT_STRING CHARACTER (80) VARYING,
        Y FILE;

This DECLARE statement defines the variables COUNTER, TEXT_STRING, and Y. The attributes for each variable follow the name of the variable.

When two or more names have common attributes, you can combine the declarations into a single, factored declaration. This format of the DECLARE statement is:

DECLARE (identifier[,identifier ...])
        [attribute ...];

When you use this format, you must place names that share common attributes within parentheses and separate them with commas. The attributes that follow the parenthetical list of names are applied to all the named identifiers.

The following are examples of factored declarations:

DECLARE (COUNTER, RATE, INDEX) FIXED BINARY (7) INITIAL (0);
DECLARE (INPUT_MESSAGE, OUTPUT_MESSAGE, PROMPT)
        CHARACTER (80) VARYING;

In these declarations, the variables COUNTER, RATE, and INDEX share the attributes FIXED BINARY (7) and are given the initial value of zero. The variables INPUT_MESSAGE, OUTPUT_MESSAGE, and PROMPT share the attributes CHARACTER (80) VARYING.

You can also specify, within the parentheses, attributes that are unique to specific variable names, using the following format:

DECLARE (declaration-item, declaration-item [,declaration-item])
        attribute ...

For example:

DECLARE (INFILE INPUT RECORD,
         OUTFILE OUTPUT STREAM) FILE;

The DECLARE statement declares INFILE as a RECORD INPUT file and OUTFILE as an STREAM OUTPUT file.

The parentheses can be nested. For example:

DECLARE ( (INFILE INPUT, OUTFILE OUTPUT) RECORD,
          SYSFILE STREAM ) FILE;

The DECLARE statement declares INFILE as a RECORD INPUT file, OUTFILE as a RECORD OUTPUT file, and SYSFILE as a STREAM file.

The declaration of an array specifies the dimensions of the array and the bounds of each dimension. This format of a DECLARE statement is:

DECLARE declaration (bound-pair,...) [attribute ...];

where each bound pair has the following format:

{ [lower-bound:]upper-bound }
{ *                         }

One bound pair is specified for each dimension of the array. The number of elements per dimension is defined by the bound pair. The extent of an array is the product of the numbers of elements in its dimensions. If the lower bound is omitted, the lower bound for that dimension is 1 by default.

You can use the asterisk (*) as the bound pair when arrays are declared as parameters of a procedure. The asterisk indicates that the parameter can accept array arguments with any number of elements. (If one dimension is specified with an asterisk, all must be specified with asterisks.)

For example:

DECLARE SALARIES(100) FIXED DECIMAL(7,2);

This statement declares a 100-element array with the identifier SALARIES. Each element is a fixed-point decimal number with a total of seven digits, two of which are fractional. The identifier in the statement can be replaced with a list of declarations, to declare several objects with the same attributes. For instance:

DECLARE (SALARIES,PAYMENTS) (100) FIXED DECIMAL(7,2);

This declares SALARIES and another array, PAYMENTS, with the same dimensions and other attributes.

For further details on how to specify the bounds of an array, and for examples of array declarations, see Section 4.1.1, “Array Declarations”.

The declaration of a structure defines the organization of the structure and the names of members at each level in the structure. This format of a DECLARE statement is:

{ DECLARE } level declaration-item [,level declaration-item ...];
{ DCL     }

Each declaration specifies a member of the structure and must be preceded by a level number. As shown in the following example, a single variable can be declared at a particular level; or the level can contain one or more complete declarations, including declarations of arrays or other structures. The major structure name is declared as structure level 1; minor members must be declared with level numbers greater than 1.

DECLARE 1 PAYROLL,
          2 NAME,
            3 LAST CHARACTER(80) VARYING,
            3 FIRST CHARACTER(80) VARYING,
          2 SALARY FIXED DECIMAL(7,2);

This statement declares a structure named PAYROLL.

Alternatively, because the last and first names have the same attributes, the same structure can be declared as follows:

DECLARE 1 PAYROLL,
          2 NAME,
            3 (LAST,FIRST) CHARACTER(80) VARYING,
          2 SALARY FIXED DECIMAL(7,2);

For details and examples of structure declarations, see Section 4.2.1, “Structure Declarations and Attributes”.

The ALIGNED attribute controls the storage boundary of bit-string data in storage. The format of the ALIGNED attribute is:

ALIGNED

You can specify the ALIGNED attribute in conjunction with the BIT attribute in a DECLARE statement to request alignment of a bit-string variable on a byte boundary. If you specify ALIGNED for an array of bit-string variables, each element of the array is aligned.

You can specify ALIGNED in the declaration of a nonvarying character-string variable. Specifying ALIGNED is not recommended with character strings, as all character strings are byte-aligned.

The ANY attribute specifies that an entry's corresponding argument can be of any data type. This attribute is applicable only to the declaration of entry names denoting non-PL/I procedures. The format of the ANY attribute is:

ANY
[ VALUE        ]
[ CHARACTER(*) ]
[ REFERENCE    ]
[ DESCRIPTOR   ]

DECLARE SYS$SETEF ENTRY (ANY VALUE);

The AREA attribute defines an area variable. The format of the AREA attribute is:

AREA [(extent)]

The AUTOMATIC attribute specifies, for one or more variables, that PL/I is to allocate storage only for the duration of a block. An automatic variable is not allocated storage until the block that declares it is activated. The storage is released when the block is deactivated. The format of the AUTOMATIC attribute is:

{ AUTOMATIC }
{ AUTO      }

AUTOMATIC explicitly defines the storage-class of a variable, array, or major structure in a DECLARE statement. Because AUTOMATIC is the default for internal variables, you need not specify it.

The BASED attribute defines a based variable, that is, a variable whose actual storage will be denoted by a pointer or offset reference. The format of the BASED attribute is:

BASED [ (reference) ]

The BINARY attribute specifies that an arithmetic variable has a binary base. The format of the BINARY attribute is:

{ BINARY }
{ BIN    }

When you specify the BINARY attribute for an identifier, you can also specify one of the following attributes to define the scale and precision of the data:

FIXED [(precision[,scale])]
FLOAT [(precision)]

FIXED indicates a fixed-point binary value and FLOAT indicates a floating-point binary value.

For a fixed-point binary value, the precision specifies the number of bits representing an integer and must be in the range 1 through 31. For a fixed-point binary value, the scale factor represents the number of bits to the right of the binary point and must be in the range -31 through 31. The magnitude of the scale factor must be less than or equal to the specified precision.

For a floating-point value, the precision specifies the number of bits representing the mantissa of a floating-point number and must be in the range:

The maximum floating-point binary precision is always 53 and 113 for OpenVMS VAX. The default values applied to the BINARY attribute are:

The BIT attribute identifies a variable as a bit-string variable. The format of the BIT attribute is:

BIT[(length)]

If you give a variable the BIT attribute, you can also specify the ALIGNED attribute to request alignment of the variable on a byte boundary in storage.

The BUILTIN attribute indicates that the name declared is the name of a PL/I built-in function. Within the block in which the name is declared, all references to the name will be interpreted as references to the built-in function or pseudovariable of that name. The format of the BUILTIN attribute is:

BUILTIN

Use the BUILTIN attribute when you want to refer to a built-in function within a block in which the function's name has been used to declare a variable.

You also use the BUILTIN attribute when you want to invoke a built-in function that takes no arguments (such as the DATE function) and you do not want to include a null argument list.

OUTER: PROCEDURE;
DECLARE MAX FIXED BINARY STATIC INITIAL (10);
      .
      .
      .
      INNER: PROCEDURE;
      DECLARE MAX BUILTIN;
            TEST = MAX(A,B);
               .
               .
               .
      END INNER;
END OUTER;

DECLARE DATE BUILTIN;
PUT LIST(DATE);

PUT LIST(DATE());

The CHARACTER attribute identifies a variable as a character-string variable. The format of the CHARACTER attribute is:

{ CHARACTER }
{ CHAR      }
[(length)]

If you give a variable the CHARACTER attribute, you can also specify the attribute VARYING, NONVARYING, ALIGNED, or UNALIGNED.

You can optionally use the CONDITION attribute in a declaration to specify that the variable name is a condition name. You can specify INTERNAL or EXTERNAL scope attributes with the CONDITION attribute. The default scope is external. The format of the CONDITION attribute is:

{ CONDITION } (condition-name)
{ COND      }

The CONTROLLED attribute causes a variable's actual storage to be allocated and freed dynamically in generations, only the most recent of which is accessible to the program. The format of the CONTROLLED attribute is:

{ CONTROLLED }
{ CTL        }

The DECIMAL attribute specifies that an arithmetic variable has a decimal base. The format of the DECIMAL attribute is:

{ DECIMAL }
{ DEC     }

When you specify the DECIMAL attribute for a variable, you can also specify the following attributes to define the scale factor and precision of the data:

FIXED (precision[,scale-factor])
FLOAT (precision)

FIXED indicates a fixed-point value, and FLOAT indicates a floating-point decimal value.

The default values applied to the DECIMAL attribute are:

The DEFINED attribute indicates that PL/I is not to allocate storage for the variable, but is to map the description of the variable onto the storage of another base variable. The DEFINED attribute provides a way to access the same data using different names. The format of the DEFINED attribute is:

{ DEFINED }(variable-reference)
{ DEF     }

The DEFINED attribute can optionally specify a position within the referenced variable at which the definition begins. For example:

DECLARE ZONE CHARACTER(10)
      DEFINED(ZIP) POSITION(4);

The DESCRIPTOR attribute forces a parameter to be passed by descriptor to a non-PL/I procedure.

The format of the DESCRIPTOR attribute is:

{ DESCRIPTOR }
{ DESC       }

The DIMENSION attribute defines a variable as an array. It specifies the number of dimensions of the array and the bounds of each dimension. The format of the DIMENSION attribute is:

[ DIMENSION ]
[ DIM       ]
(bound-pair,...)

The following two declarations are exactly equivalent:

DECLARE A(10) FIXED BIN;

DECLARE A FIXED BIN DIMENSION(10);

The following two declarations are also equivalent:

DECLARE B(1:5,1:5) FLOAT DEC;

DECLARE B DIM(1:5,1:5) FLOAT DEC;

The DIRECT file description attribute indicates that a file will be accessed only in a nonsequential manner, that is, by key or by relative record number.

The format of the DIRECT attribute is:

DIRECT

The DIRECT attribute implies the RECORD and KEYED attributes.

Specify the DIRECT attribute on a DECLARE statement for a file constant or on an OPEN statement to access the file. A file declared with the DIRECT attribute must be one of the following:

To access a file both randomly and sequentially, use the SEQUENTIAL attribute instead of DIRECT.

The ENTRY attribute declares a constant or variable whose value is an entry point and describes the attributes of the parameters (if any) that are declared for the entry point. The format of the ENTRY attribute is:

ENTRY [ (parameter-descriptor, ...) ]
        [ OPTIONS (VARIABLE) ]
        [ RETURNS (returns-descriptor) ]

The ENTRY attribute without the VARIABLE attribute implies the EXTERNAL attribute (and implies that the declared item is a constant), unless the ENTRY attribute is used to declare a parameter.

You must declare all external entry constants with the ENTRY attribute.

DECLARE COPYSTRING ENTRY (CHARACTER (40) VARYING,
                          FIXED BINARY(7))
        RETURNS (CHARACTER(*));

The ENVIRONMENT file description attribute is used in DECLARE, OPEN, and CLOSE statements to specify options that define file characteristics specific to the OpenVMS file system and options that request special processing not available in the standard PL/I language. The format of the ENVIRONMENT attribute is:

{ ENVIRONMENT }(option,...)
{ ENV         }

DECLARE IFDELETE BIT(1);
   ⋮
OPEN FILE (XYZ) ENVIRONMENT(DELETE(IFDELETE));

The EXTERNAL attribute declares an external name, that is, a name whose value can be known to blocks outside the block in which it is declared. The format of the EXTERNAL attribute is:

{ EXTERNAL }
{ EXT      }

The EXTERNAL attribute is implied by the FILE, GLOBALDEF, and GLOBALREF attributes. EXTERNAL is also implied by declarations of entry constants (declarations that contain the ENTRY attribute but not the VARIABLE attribute). For variables, the EXTERNAL attribute implies the STATIC attribute.

The FILE attribute declares a file constant or file variable. The format of the FILE attribute is:

FILE

The FILE attribute is implied by any of the following file description attributes:

See Table 9.2, “Summary of File Description Attributes” for definitions of these file description attributes.

If the VARIABLE attribute is not specified, the FILE attribute declares a file constant. If the INTERNAL attribute is not specified, the file has the EXTERNAL attribute by default. All external declarations of a file constant are associated with the same file.

The FIXED attribute indicates that the variable so declared is arithmetic with a fixed number of fractional digits. Such variables are called fixed-point (as opposed to floating-point) variables because the decimal point and binary point are fixed relative to the representation of the value. The format of the FIXED attribute is:

FIXED [(precision[,scale-factor])]

When you specify the FIXED attribute in a DECLARE statement, you can specify either the BINARY or the DECIMAL attribute to indicate a binary or decimal fixed-point variable. For example, the attributes FIXED BINARY(31,5) define a variable that takes fixed-point binary values of up to a maximum of 31 bits, 5 of which are fractional. The attributes FIXED DECIMAL(10,2) define a variable that takes fixed-point decimal values of up to 10 decimal digits, 2 of which are fractional. PL/I supplies default attributes for attributes that you do not specify (as shown in the following table).

You normally use fixed-point binary data to represent integers. The precision of a fixed-point binary variable must be in the range 1 through 31. The scale factor can be in the range -31 through 31.

You can also use fixed-point decimal data, which can represent larger absolute values. You use fixed-point data whenever arithmetic values must be precise to a specified number of fractional digits. For a fixed-point decimal value, the precision must be in the range 1 through 31 (decimal digits). The scale factor, if specified, must be greater than or equal to zero and less than or equal to the specified precision.

If the scale factor is omitted, zero is used (that is, an integer variable is declared).

The default values given for unspecified related attributes are:

The FLOAT attribute indicates that a variable is a floating-point arithmetic item. The format of the FLOAT attribute is:

FLOAT [(precision)]

When you specify the FLOAT attribute in a DECLARE statement, you can specify either the BINARY or the DECIMAL attribute. The default values given for unspecified related attributes are:

The GLOBALDEF attribute declares an external variable or an external file constant. It can optionally control the program section in which the data is allocated. The format of the GLOBALDEF attribute is:

GLOBALDEF [ (psect-name) ]

The GLOBALDEF attribute implies the EXTERNAL attribute. The GLOBALDEF attribute also implies STATIC except when used for file constants.

The GLOBALREF attribute indicates that the declared name is a global symbol defined in an external procedure. The format of the GLOBALREF attribute is:

GLOBALREF

The GLOBALREF attribute implies the EXTERNAL attribute. The corresponding name must be declared in another procedure with the GLOBALDEF attribute or, if the external procedure is written in another programming language, with its equivalent in that language.

The INITIAL attribute provides an initial value for a declared variable. The format of the INITIAL attribute is:

{ INITIAL }  { (initial-element[,initial-element...]) }
{ INIT    }  { ((*) valid-expression)                 }

DECLARE RATE FIXED DECIMAL (2,2) STATIC INITIAL (.04);

DECLARE SWITCH BINARY STATIC INITIAL ('1'B);

DECLARE BELL_CHAR BINARY STATIC INITIAL ('07'B4);

DECLARE OUTPUT_MESSAGE CHARACTER(20) STATIC
            INITIAL ('GOOD MORNING');

DECLARE (A INITIAL ('A'), B INITIAL ('B'),
      C INITIAL ('C')) STATIC CHARACTER;

DECLARE QUEUE_END POINTER STATIC INITIAL(NULL());

DECLARE X(10,5) FIXED BIN(31) INITIAL ((*) -2);  /* Initializes all 50
                                                    elements to -2    */

DECLARE 1 A(10),
          2 B(10),
            3 C(10) FIXED BIN(31) INITIAL ((*) 4);  /* Initializes all
                                                       1000 elements
                                                       to 4           */

DECLARE A(10) FIXED INIT ((5) 1,(5) 2);          /* Initializes the first
                                                    5 elements to 1 and
                                                    the second 5 elements
                                                    to 2              */

DECLARE A(10) FIXED INIT ((5) 1,(*)2);           /* Invalid use of asterisk
                                                    iteration factor  */

The INPUT file description attribute indicates that the associated file is to be an input file. The format of the INPUT attribute is:

INPUT

Specify the INPUT attribute on a DECLARE statement for a file constant or on an OPEN statement to access the file for reading.

You can specify the INPUT attribute with either the STREAM or the RECORD attribute. For a stream file, INPUT indicates that the file will be accessed with GET statements. For a record file, INPUT indicates that the file will be accessed only with READ statements.

For example:

DECLARE INFILE RECORD INPUT;

OPEN FILE(INFILE);
READ FILE(INFILE) INTO(RECORD_BUFFER);

These statements declare, open, and access the first record in the input file INFILE.

For a description of the attributes that can be applied to files, see Table 9.2, “Summary of File Description Attributes”.

The INPUT attribute can be supplied by default for a file, depending on the context of its opening. See Section 9.1.3.3, “Establishing the File's Attributes” for more information.

The INTERNAL attribute limits the scope of an identifier to the block in which the identifier is declared and its dynamic descendents.

The format of the INTERNAL attribute is:

{ INTERNAL }
{ INT      }

You only need to use the INTERNAL attribute to explicitly declare the scope of a file constant as internal. File constants, by default, have the EXTERNAL attribute.

The KEYED file description attribute indicates that you can randomly access records in the specified file. The KEYED attribute implies the RECORD attribute.

Specify KEYED in a DECLARE statement to identify a file or in an OPEN statement to open the file. For a description of the attributes that can be applied to files, see Table 9.2, “Summary of File Description Attributes”.

The LABEL attribute declares a label variable; it indicates that values given to the variable will be statement labels. The format of the LABEL attribute is:

LABEL

The LIKE attribute copies the member declarations contained within a major or minor structure declaration into the structure variable to which it is applied. The format of the LIKE attribute is:

level-number identifier [attributes] LIKE reference

The LIKE attribute causes the structuring and member declarations of its reference to be copied, but not the name, storage class, or dimensioning (if any) of the reference. The exception to this rule is that the UNION attribute is propagated in a LIKE declaration. While logical structuring is copied, the level numbers themselves are not copied.

You can use the LIKE attribute on a structure already containing the LIKE attribute.

The LIST attribute is used in the declaration of a formal parameter to indicate that the parameter can accept a list of actual parameters of arbitrary length. This list must contain at least one argument. To allow a list of zero or more arguments, you must declare the formal parameter with both the TRUNCATE attribute and the LIST attribute. The format of the LIST attribute is:

LIST

The LIST attribute is valid only on formal parameters of external procedures. It is not supported for PL/I procedures. (To simulate list parameters in PL/I, use asterisk-extent arrays.)

You can only use the LIST attribute for the last formal parameter in an argument list.

DCL NUMBER FIXED BINARY;
DCL LIST_PROC1 ENTRY (FIXED BINARY,FIXED BINARY LIST);
DCL LIST_PROC2 ENTRY (FIXED BINARY,FIXED BINARY LIST TRUNCATE);

CALL LIST_PROC1 (NUMBER,NUMBER);
CALL LIST_PROC1 (NUMBER,NUMBER,NUMBER);

CALL LIST_PROC2 (NUMBER);
CALL LIST_PROC2 (NUMBER,NUMBER,NUMBER,NUMBER);

You can optionally specify the MEMBER attribute in the declaration of a structure member (minor structure). A structure member has the MEMBER attribute implicitly. The format of the MEMBER attribute is:

MEMBER

The NONVARYING attribute keyword explicitly states that a bit-string or character-string variable has a fixed length, not a varying length. Because NONVARYING is the default for bit and character strings, it need not be specified. The format of the NONVARYING attribute is:

{ NONVARYING }
{ NONVAR     }

The OFFSET attribute declares a variable that will be used to reference a based variable within an area. The format of the OFFSET attribute is:

OFFSET [(area-reference)]

DECLARE MAP_SPACE AREA (40960),
        MAP_START OFFSET (MAP_SPACE),
        MAP_LIST(100) CHARACTER(80) BASED (MAP_START);

The OPTIONAL attribute indicates that an actual parameter need not be specified in a call. If the actual parameter is not specified, a placeholder for it must be specified, and PL/I will pass a longword zero as the actual parameter in that position. There is an exception if there are no further actual parameters that are being supplied in the call. For that case, the programmer does not need to supply commas, although she may choose to do so to make the program more readable by humans. The format of the OPTIONAL attribute is:

OPTIONAL

DCL E ENTRY (FIXED,FIXED OPTIONAL);
CALL E(1,2);
CALL E(1,);
CALL E(1);

The OUTPUT file description attribute indicates that data is to be written to, and not read from, the associated external device or file. The format of the OUTPUT attribute is:

OUTPUT

Specify the OUTPUT attribute on a DECLARE statement for a file constant or on an OPEN statement to access the file for writing. You can specify the OUTPUT attribute with either the STREAM or the RECORD attribute. For a stream file, OUTPUT indicates that the file will be accessed with PUT statements. For a record file, OUTPUT indicates that the file will be accessed with only WRITE statements.

DECLARE OUTFILE RECORD OUTPUT;

OPEN FILE(OUTFILE);
WRITE FILE(OUTFILE) FROM(RECORD_BUFFER);

A variable occurring in the parameter list of a PROCEDURE or ENTRY statement has the PARAMETER attribute implicitly. You can optionally use the PARAMETER keyword in the declaration of a variable name to state explicitly that it is a parameter. The format of the PARAMETER attribute is:

{ PARAMETER }
{ PARM      }

TEST: PROC( A, B );
    DCL A CHAR(*) PARAMETER;
    DCL B FIXED BIN PARM;
        .
        .
        .

The PICTURE attribute is used to declare a pictured variable. Pictured variables have fixed-point decimal attributes, but values of the variable are stored internally as character strings. The character string contains decimal digits representing the numeric value of the variable, plus special editing symbols described in the picture. The format of the PICTURE attribute is:

{ PICTURE } 'picture'
{ PIC     }

See Section 3.2.5.1, “Picture Characters” for detailed information about picture characters, syntax, and examples.

The POINTER attribute indicates that the associated variable will be used to identify locations of data. The format of the POINTER attribute is:

{ POINTER }
{ PTR     }

The POSITION attribute specifies the character or bit position in a defined variable's base at which the defined variable begins. The format of the POSITION attribute is:

{ POSITION }(expression)
{ POS      }

The PRECISION attribute specifies the maximum number of decimal or binary digits in a number. You can specify the precision of an arithmetic variable in any of the following formats, depending on the numeric base of the data item. The formats of the PRECISION attribute are:

The ranges of values you can specify for the precision of each arithmetic data-type, and the defaults applied if you do not specify a precision, are summarized Section 3.2.1, “Precision and Scale of Arithmetic Data Types”.

The PRINT attribute is used to declare a print file. The file SYSPRINT, used as the default output by PUT statements, is a print file. The format of the PRINT attribute is:

PRINT

Print files are stream output files with special formatting characteristics. The PRINT attribute implies the OUTPUT and STREAM attributes.

You can apply the READONLY attribute to any static computational variable whose value does not change during program execution. The format for the READONLY attribute is:

READONLY

When you specify READONLY in conjunction with the declaration of a static variable, the PL/I compiler allocates storage for the variable based on the fact that its value does not change. A static variable with the READONLY attribute is given an initial value with the INITIAL attribute.

The RECORD file description attribute indicates that data in an input or output file consists of separate records and that the file will be processed by record I/O statements. The format of the RECORD attribute is:

RECORD

The RECORD attribute is implied by the DIRECT, SEQUENTIAL, KEYED, and UPDATE attributes.

You can specify this attribute in a DECLARE statement for a file constant or in the OPEN statement that accesses the file.

The REFER attribute defines dynamically self-defining structures. The format of the REFER attribute is:

REFER

See Section 4.2.6.3, “Using the REFER Option” for more information on the REFER option.

The REFERENCE attribute forces a parameter to be passed by reference. The format of the REFERENCE attribute is:

{ REFERENCE }
{ REF       }

By default, most parameters are passed by reference in PL/I. However, the REFERENCE attribute is needed for passing an asterisk-extent array or character string by reference, because asterisk-extent parameters are passed by descriptor by default.

DECLARE E ENTRY((*) FIXED BIN(31) REFERENCE, FIXED BIN(31));

The RETURNS option must be specified on the PROCEDURE or ENTRY statement if the corresponding entry point is invoked as a function. The RETURNS attribute is specified with the ENTRY attribute to give the data-type of a value returned by an external function. The format of the RETURNS option and attribute is:

RETURNS (returns-descriptor...)

CALLER: PROCEDURE OPTIONS (MAIN);
        DECLARE COMPUTER ENTRY (FIXED BINARY)
           RETURNS (FIXED BINARY); /* RETURNS attribute */
        DECLARE TOTAL FIXED BINARY;
           .
           .
           .
        TOTAL = COMPUTER (A+B);

COMPUTER: PROCEDURE (X) RETURNS (FIXED BINARY); /* RETURNS option */
          DECLARE (X, VALUE) FIXED BINARY;
             .
             .
             .
          RETURN (VALUE);                       /* RETURN statement */

The SEQUENTIAL file description attribute indicates that records in the file will be accessed in a sequential manner. The format of the SEQUENTIAL attribute is:

{ SEQUENTIAL }
{ SEQL       }

If you specify SEQUENTIAL, the RECORD attribute is implied.

Specify the SEQUENTIAL attribute in a DECLARE statement for a file constant or in the OPEN statement that accesses the file.

You can apply the SEQUENTIAL attribute to files with sequential, relative, or indexed sequential file organizations.

The STATIC attribute specifies the way that PL/I is to allocate storage for a variable. The format of the STATIC attribute is:

STATIC

The STATIC attribute is implied by the EXTERNAL attribute. For more information on STATIC and on other storage-class attributes, see Chapter 5, Storage Classes.

The STREAM file description attribute indicates that the file consists of ASCII characters and that it will be processed using GET and PUT statements. The format of the STREAM attribute is:

STREAM

The STREAM attribute is implied by the PRINT attribute. It is also supplied by default for a file that is implicitly opened with a GET or PUT statement.

Specify the STREAM attribute in a DECLARE statement for a file identifier or in the OPEN statement that opens the file.

You can optionally specify the STRUCTURE attribute in the declaration of a structure. The format of the STRUCTURE attribute is:

STRUCTURE

The TYPE attribute copies the declarations contained within the type declaration to the variable to which it is applied. The format of the TYPE attribute is:

level-number identifier [attributes] TYPE reference

The TYPE attribute causes the declaration of its reference to be copied, but not the name, storage class, or dimensioning (if any) of the reference. The exception to this rule is that the UNION attribute is propagated in a TYPE declaration. While logical structuring is copied, the level numbers themselves are not copied.

You can use the TYPE attribute on a declaration already containing the TYPE attribute.

The TRUNCATE attribute is used in the declaration of a formal parameter to indicate that the actual parameter list can be truncated at the point where this argument should occur. The format of the TRUNCATE attribute is:

TRUNCATE

When the actual call is made, the actual parameter list can stop at the parameter before the one declared with the TRUNCATE attribute. It is possible to pass an actual parameter in a position with the TRUNCATE attribute. Note that in this case, all remaining parameters must also be specified unless they have the TRUNCATE attribute.

A subtle difference between trailing formal parameters for which the TRUNCATE attribute is specified and trailing formal parameters for which the OPTIONAL attribute is specified is that when no actual parameters are specified, the compiler will automatically fill out the minimum argument vector length requires (such as by certain VMS system services) in the OPTIONAL case, but not if only TRUNCATE is specified.

DCL E ENTRY (FIXED,FIXED TRUNCATE,FIXED);
CALL E(1);
CALL E(1,2,3);

CALL E(1,2);

The UNALIGNED attribute is used in conjunction with the BIT attribute to specify that a bit-string variable should not be aligned on a byte boundary. Because UNALIGNED is the default for bit strings, it need not be specified. The format of the UNALIGNED attribute is:

{ UNALIGNED }
{ UNAL      }

You can use the UNALIGNED attribute in the declaration of character strings. All character strings are aligned on byte boundaries; therefore, the UNALIGNED attribute has no effect on the actual storage of a character string.

The UNION attribute, which can be used only in conjunction with a level number in a structure declaration, signifies that all immediate members of the major or minor structure so designated occupy the same storage. Immediate members are those members having a level number 1 higher than the major or minor structure with the UNION attribute. For example, if the UNION attribute were associated with level n, then all members or minor structures at level n+1 up to the next member at level n would be immediate members and would occupy the same storage. The format for the UNION attribute is:

level-number identifier [storage-class] UNION

The UPDATE attribute is a file description attribute indicating that the associated file is to be used for both input and output. You can apply the UPDATE attribute to relative files, indexed files, and sequential disk files with fixed-length records. The format of the UPDATE attribute is:

UPDATE

Specify the UPDATE attribute on a DECLARE statement for a file constant or on an OPEN statement to access the file for update. The UPDATE attribute implies the RECORD attribute.

For a description of the attributes that are applied to files, see Section 9.1.3.3, “Establishing the File's Attributes”.

The VALUE attribute is provided for passing parameters by value rather than by reference, or it can be used to specify a global constant value. The format of the VALUE attribute is:

{ VALUE }
{ VAL   }

The VALUE attribute serves two purposes:

The VALUE attribute, when specified with the BIT attribute, implies the ALIGNED attribute.

The VARIABLE attribute indicates that the associated identifier is a variable. VARIABLE is implied by all computational data-type attributes and by all noncomputational attributes except FILE and ENTRY. The format of the VARIABLE attribute is:

VARIABLE

If you specify the FILE or ENTRY attribute in a DECLARE statement without the VARIABLE attribute, the defined object is assumed to be a file or entry constant.

The VARIABLE attribute is implied by the LABEL attribute. You can declare label constants only by using the label identifier in the program; you cannot define a label constant in a DECLARE statement.

The VARYING attribute indicates that a character-string variable does not have a fixed length, but that its length changes according to its current value. The format of the VARYING attribute is:

{ VARYING }
{ VAR     }

You must specify a length attribute in conjunction with VARYING by giving the maximum length allowed for the variable. The current length is stored with the value and can be determined at any time with the LENGTH built-in function. If you need to determine the maximum declared length of a varying- length character string, use the MAXLENGTH built-in function.

The value of an uninitialized CHARACTER VARYING variable is undefined.

Special rules apply to reading and writing record files into and from variables that have the VARYING attribute. See the Endless PL/I for OpenVMS User Manual.

DECLARE STRING CHARACTER(80) VARYING;

S: PROCEDURE OPTIONS(MAIN);
DECLARE STRING CHARACTER(80) VARYING;
    STRING = 'PIE';
    PUT LIST (LENGTH(STRING));
    PUT LIST (MAXLENGTH(STRING));
    PUT LIST (SIZE(STRING));
END;