Aggregates

To declare an array, specify its dimensions in a DECLARE statement using one of the following syntaxes:

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

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

To declare two or more array variables that have the same dimensions, bounds, and attributes, use the following syntax:

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

DECLARE VERBS (6) CHARACTER (12) ;

DECLARE TEMPERATURES (-60:120) ;

DECLARE TABLE (10,10) FIXED BINARY ;
DECLARE SETS (5,5,5,5) CHARACTER (80) ;

DECLARE WINDOWS (1:10,-2:32) FIXED;
DECLARE HISTORIES (10,30:102,50) ...

ADDIT: PROCEDURE (ARR) ;
   DECLARE ARR(*,*) FIXED ;

The declaration of an array specifies its dimensions, the bounds of each dimension, and the attributes of the elements.

One bound pair is specified for each dimension of the array to define the number of elements in that dimension. The total number of elements in the array, called its extent, is the product of the number of elements in all the dimensions of the array. If omitted, the lower bound is 1 by default.

You can use an asterisk (*) as the bound pair when you declare arrays 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 following statement declares a two-dimensional array of 64 integers:

DECLARE GAME_BOARD (8,8) FIXED BINARY (7);

The following statement declares a one-dimensional array of 12 character strings, each having a length of 2:

DECLARE PM_HOURS(13:24) CHARACTER(2);

The elements of the previous array is numbered 13 through 24 instead of 1 through 12.

You can replace the identifier in a statement with a list of declarations, which declares several arrays with the same attributes. For example:

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

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

You refer to an individual element in the array with subscripts. Because an array's attributes are common to all of its elements, a subscripted reference has the same properties as a reference to a scalar variable with those attributes.

You must enclose subscripts in parentheses in a reference to an array element. For example, in a one-dimensional array named ARRAY declared with the bounds (1:10), the elements are numbered 1 through 10 and are referred to as ARRAY(1), ARRAY(2), ARRAY(3), and so on. The lower and upper bounds that you declare for a dimension determine the range of subscripts you can specify for that dimension.

The lower and upper bounds that you declare for a dimension determine the range of subscripts that you can specify for that dimension. The number of elements in any dimension of any array is:

(upper bound) - (lower bound) + 1

For multidimensional arrays, the subscript values represent an element's position with respect to each dimension in the array. Figure 4.1, “Specifying Elements of an Array” shows subscripts for elements of one-, two-, and three-dimensional arrays. In subscripted references for multidimensional arrays, the number of subscripts must match the number of dimensions of the array and must be separated by commas.

You can specify the subscript of an array element using any variables or expressions having integer values, that is, values that can be expressed as fixed binary or fixed decimal with a zero scale factor. For example:

DECLARE DAYS_IN_MONTH(12) FIXED BINARY;

DECLARE (COUNT, TOTAL) FIXED BINARY;
TOTAL = 0;
DO COUNT = 1 TO 12;
      TOTAL = TOTAL + DAYS_IN_MONTH(COUNT);
      END;

Here, the variable COUNT is used as a control variable in a DO loop. As the value of COUNT is incremented from 1 to 12, the value of the corresponding element of the array DAYS_IN_MONTH is added to the value of the variable TOTAL.

Specify the INITIAL attribute for an array to initialize its values in the declaration. For example:

DECLARE MONTHS (12) CHARACTER (9) VARYING
   INITIAL ('January', 'February', 'March', 'April',
      'May', 'June', 'July', 'August',
      'September', 'October', 'November', 'December');

Each element of the array MONTHS is assigned a value according to the order of the character-string constants in the initial list: MONTH(1) is assigned the value 'January'; MONTH(2) is assigned the value 'February'; and so on.

If the array being initialized is multidimensional, the initial values are assigned in row-major order.

To assign identical initial values to some or all elements of an array, you can use an iteration factor with the INITIAL attribute. For example:

DECLARE TEST_AVGS (30,4) FIXED DECIMAL (5,2)
    STATIC INITIAL ((120) 50);

This statement declares the array TEST_AVGS with 120 elements, each of which is given an initial value of 50.

You can also use the asterisk (*) iteration factor to initialize all the elements of an array to the same value. For example:

DECLARE TEST_AVGS (30,4) FIXED DECIMAL (5,2)
    STATIC INITIAL ((*) 50);

This statement also declares the array TEST_AVGS with 120 elements, each of which is given an initial value of 50.

Although Endless PL/I V3.9 for OpenVMS VAX and Endless PL/I V5.0 for OpenVMS Alpha both support the initialization of automatic arrays with the INITIAL attribute, for the following reasons this is not always the most efficient way (in terms of program compilation and execution) to initialize array elements:

If the array is not modified by your program, you can increase program efficiency by declaring the array with the STATIC and READONLY attributes and using the INITIAL attribute to initialize its elements. In this case, the compiler checks that you have initialized all the elements and that they are valid.

DECLARE SCORES (100) FIXED STATIC INITIAL ((100)1);

DECLARE SCORES (100) FIXED STATIC INITIAL ((50)1,(50)-1);

DECLARE SCORES (100) FIXED STATIC INITIAL ((49)1,(2)*,(49)-1);

DECLARE ALPHABETS (10) CHARACTER(26) STATIC
   INITIAL((10)('ABCDEFGHIJKLMNOPQRSTUVWXYZ'));

You can specify an array variable as the target of an assignment statement in the following cases:

array-variable = expression;

This is valid where the expression yields a scalar value. Every element of the array is assigned the resulting value. The array variable must be a connected array whose elements are scalar. You can use the asterisk in an assignment:

array-variable (*,...) = expression;

You can use a single asterisk regardless of how many dimensions an array has, or you can use an asterisk for each dimension.

Note that the arithmetic operators, such as the plus sign (+) and the minus sign (-), cannot have arrays as operands. An assignment of the following form is invalid:

ARRAYC = ARRAYA + ARRAYB;

The following assignment is valid where the specified array variables have identical data-type attributes and dimensions:

array-variable-1 = array-variable-2;

Each element in array-variable-1 is assigned the value of the corresponding element in array-variable-2. In this type of assignment, both arrays must be connected. The actual storage they occupy must not overlap, unless the arrays are identical.

All other specifications of an array variable as the target of an assignment statement are invalid.

When a multidimensional array is initialized, or when it is assigned values without references to specific elements, PL/I assigns the values in row-major order. In row-major order, the rightmost subscript varies the most rapidly. For example, an array can be declared as follows:

DECLARE TESTS (2,2,3);

If TESTS is specified in a GET statement or in a declaration with the INITIAL attribute, values are assigned to the elements in the following order:

When an array is output with a PUT statement, PL/I uses the same order to output the array elements. For example:

PUT LIST (TESTS);

This PUT statement outputs the contents of TESTS in the order previously shown.

DECLARE VERBS (6) CHARACTER (15) VARYING;
GET LIST (VERBS);

You can pass an array variable as an argument to another procedure. Within the invoked procedure, the corresponding parameter must be declared with the same number of dimensions. The rules for specifying the bounds in a parameter descriptor for an array parameter are as follows:

For example:

DECLARE SCAN ENTRY ((5,5,5) FIXED,(*) FIXED),
    MATRIX (5,5,5) FIXED,
    OUTPUT (20) FIXED;

    CALL SCAN (MATRIX,OUTPUT);

The procedure SCAN receives two arrays as arguments. The first is a three-dimensional array whose bounds are known. The second is a one-dimensional array whose bounds are not known. The procedure SCAN can declare these parameters as follows:

SCAN: PROCEDURE (IN,OUT);
DECLARE IN (*,*,*) FIXED,
        OUT (*) FIXED;

An array whose storage is unconnected cannot be passed as an argument. Arrays are always passed by reference.

PL/I provides the following built-in functions that return information about the dimensions of an array:

For the first dimension of an array X, the relationship of these functions can be expressed as follows:

DIMENSION (X,1) = HBOUND (X,1) - LBOUND (X,1) + 1

The procedure that follows uses the HBOUND and LBOUND built-in functions:

ADDIT: PROCEDURE (X);
DECLARE X (*) FIXED BINARY,
        (COUNT,I) FIXED BINARY;

        COUNT = 0;
        DO I = LBOUND (X,1) TO HBOUND(X,1);
            COUNT = COUNT + 1;
            X(I) = COUNT;
            END;
        RETURN;
        END;

This procedure receives a one-dimensional array as a parameter and initializes the elements of the array with integral values beginning with 1.

The declaration of a structure defines its organization and the names of members at each level in the structure. The major structure name is declared as structure level 1; minor members must be declared with level numbers greater than 1. For example:

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. You can access the last name with a qualified reference:

PAYROLL.NAME.LAST = 'ROOSEVELT';

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

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

The following additional rules apply to the specification of level numbers:

A union is a variation of a structure in which all immediate members occupy the same storage. The UNION attribute (which must be associated with a level number in a structure declaration) declares a union. All immediate members of the union-that is, all members having a logical level number one higher-occupy the same storage. A reference to one member of a union refers to storage occupied by all members of the union. Therefore, a union provides a convenient way to look at a large entity (such as a character string or a bit mask) as a series of smaller entities (such as component character strings or individual flag bits).

A variable declared with the UNION attribute must be a major or minor structure. All members of a union must have a constant size (see Chapter 2, Declarations for format and details).

The UNION attribute is not part of the PL/I General-Purpose Subset; it is provided in ESS implementations of PL/I to give users convenient access to data as it is internally represented. Potential applications of unions might depend on the internal representation of data, and would therefore not be transportable between OpenVMS VAX and OpenVMS Alpha systems. The following example shows unions:

DECLARE 1 CUSTOMER_INFO,
             ⋮
          2 PHONE_DATA UNION,
            3 PHONE_NUMBER CHARACTER (13),
            3 COMPONENTS,
              4 LEFT_PAREN CHARACTER (1),
              4 AREA_CODE CHARACTER (3),
              4 RIGHT_PAREN CHARACTER (1),
              4 EXCHANGE CHARACTER (3),
              4 HYPHEN CHARACTER (1),
              4 SPECIFIC_NUMBER CHARACTER (4),
          2 ADDRESS_DATA,
             ⋮

The UNION attribute associated with the declaration of PHONE_DATA signifies that PHONE_DATA's immediate members (PHONE_NUMBER and COMPONENTS) occupy the same storage. Any modification of PHONE_NUMBER also modifies one or more members of COMPONENTS; conversely, modification of a member of COMPONENTS also modifies PHONE_NUMBER. Note, however, that the UNION attribute does not apply to the members of COMPONENTS because they are not immediate members of PHONE_DATA. The members of COMPONENTS occupy separate storage in the normal fashion for structure members.

Unions provide capabilities similar to those provided by defined variables. However, the rules governing defined variables are more restrictive than those governing unions. The following example (for VAX only) demonstrates a use of a union that would not be possible with a defined variable:

DECLARE 1 X UNION,
          2 FLOAT_NUM FLOAT BINARY (24),
          2 BREAKDOWN,
            3 FRAC_1 BIT (7),
            3 EXPONENT BIT (8),
            3 SIGN BIT (1),
            3 FRAC_2 BIT (16);

The union X has two immediate members, FLOAT_NUM (a floating-point variable) and BREAKDOWN. The members of BREAKDOWN are bit-string variables that overlay the storage occupied by FLOAT_NUM and provide access to the individual components of an VAX floating-point value. Assignment to FLOAT_NUM modifies the members of BREAKDOWN and vice versa. For example:

EXPONENT = '0'B;
SIGN = '1'B;

FLOAT_NUM = FLOAT_NUM + 1;

The first two assignment statements set the exponent and sign fields of FLOAT_NUM to the reserved operand combination; the expression FLOAT_NUM + 1 causes a reserved operand exception to occur.

Note that, unlike the character-string example that precedes it, this example depends on the VAX internal representation of data.

You can initialize a structure by giving the INITIAL attribute to its members. Not all members need be initialized. For example:

DECLARE 1 COUNTS,
          2 FIRST FIXED BIN(15) INITIAL(0),
          2 SECOND FIXED BIN(15),
          2 THIRD (5) FIXED BIN(15) INITIAL (5(1));

The first and third members of the structure COUNTS are initialized.

The INITIAL attribute cannot be applied, however, to a major or a minor structure name.

In a union, the same data can only be initialized once.

You can specify the name of a major or minor structure in an assignment statement only if the source expression and the target variable are identical in size and structure, and all corresponding members have the same data types.

You can pass a structure variable as an argument to another procedure. The relative structuring of the structure variable specified as the argument and the corresponding parameter must be the same. The level numbers do not have to be identical. The following example shows the parameter descriptor for a structure variable:

DECLARE SEND_REC ENTRY (1,
                          2 FIXED BINARY(31),
                          2 CHARACTER(40),
                          2 PICTURE '999V99');

The written argument in the invocation of the external procedure SEND_REC must have the same structure, and its corresponding members must have the same data types.

When structures are passed as arguments, they must match the corresponding parameters. They cannot be passed by dummy argument.

PL/I supports three member attributes, so named because they apply specifically to the declaration of structure members rather than to the structure as a whole. The member attributes are as follows:

Each is discussed in detail in the following sections.

DECLARE NO_OF_SINGLE_ROOMS FIXED BINARY(31);
DECLARE NO_OF_DOUBLE_ROOMS TYPE (NO_OF_SINGLE_ROOMS);

DECLARE NO_OF_DOUBLE_ROOMS FIXED BINARY(31);

DECLARE BED_SERIAL_NOS((NO_OF_SINGLE_ROOMS + NO_OF_DOUBLE_ROOMS),2)
                                                           CHARACTER(12);
DECLARE TABLE_SERIAL_NOS TYPE(BED_SERIAL_NOS);

DECLARE TABLE_SERIAL_NOS((NO_OF_SINGLE_ROOMS + NO_OF_DOUBLE_ROOMS),2)
                                                           CHARACTER(12);

DECLARE 1 RES_DATA BASED (RPTR),
          2 DATE CHARACTER(8),
          2 HOTEL_CODE CHARACTER(3),
          2 PARTY_NAME,
            3 LAST CHARACTER(20),
            3 FIRST CHARACTER(10),
          2 STAY FIXED BIN(7),
        1 NEW_RESER TYPE(RES_DATA),
           ⋮
    GET LIST (NEW_RESER.DATE,NEW_RESER.HOTEL_CODE);
       ⋮
    RES_DATA = NEW_RESER;

DECLARE 1 NEW_RESER,
          2 DATE CHARACTER(8),
          2 HOTEL_CODE CHARACTER(3),
          2 PARTY_NAME,
            3 LAST CHARACTER(20),
            3 FIRST CHARACTER(10),
          2 STAY FIXED BINARY(7);

DECLARE 1 PARTY_NAME,
          2 LAST CHAR(20),
          2 FIRST CHAR(10);

DECLARE 1 SPOUSE_NAME TYPE(PARTY_NAME);

DECLARE 1 SPOUSE_NAME,
          2 LAST CHAR(20),
          2 FIRST CHAR(10);

DECLARE 1 KID_NAMES (10) TYPE(PARTY_NAME);

DECLARE 1 DAILY_DATA,
          2 DATE CHAR(8),
          2 TODAYS_RESERS (NO_OF_RES) TYPE(RES_DATA);
             ⋮

DECLARE 1 RES_DATA BASED (RPTR),
          2 DATE CHARACTER(8),
          2 HOTEL_CODE CHARACTER(3),
          2 PARTY_NAME,
            3 LAST CHARACTER(20),
            3 FIRST CHARACTER(10),
          2 STAY FIXED BIN(7),
        1 NEW_RESER LIKE RES_DATA,
           ⋮
    GET LIST (NEW_RESER.DATE,NEW_RESER.HOTEL_CODE);
       ⋮
    RES_DATA = NEW_RESER;

DECLARE 1 NEW_RESER,
          2 DATE CHARACTER(8),
          2 HOTEL_CODE CHARACTER(3),
          2 PARTY_NAME,
            3 LAST CHARACTER(20),
            3 FIRST CHARACTER(10),
          2 STAY FIXED BINARY(7);

DECLARE 1 SPOUSE_NAME LIKE PARTY_NAME;

DECLARE 1 SPOUSE_NAME,
          2 LAST CHAR(20),
          2 FIRST CHAR(10);

DECLARE 1 KID_NAMES (10) LIKE PARTY_NAME;

DECLARE 1 DAILY_DATA,
          2 DATE CHAR(8),
          2 TODAYS_RESERS (NO_OF_RES) LIKE RES_DATA;
             ⋮

refer-element REFER (refer-object-reference)

DECLARE 1 STRUCTURE S BASED(P),
          2 I FIXED BINARY(31),
          2 A CHARACTER(20 REFER(I));

DECLARE 1 S BASED (POINTER),
          2 I FIXED BINARY(15),
          2 J FIXED BINARY(15),
          2 A CHARACTER ((X*2+2) REFER(I)),
          2 B(2) CHARACTER (Y REFER(J));

X = 5;
Y = 10;

ALLOCATE S;
S.A = 'ABCDEFGHIJKL';
S.B(1) = '0123456789';
S.B(2) = 'NOW IS THE';
    ⋮
END;

To refer to a structure in a program, you use the major structure name, minor structure names, and individual member names. Member names need not be unique even within the same structure. To refer to the name of a member or minor structure, you must ensure only that the reference uniquely identifies it. You can qualify the variable name by preceding it with the name or names of higher-level (lower-numbered) variables in the structure; names in this format, called a qualified reference, must be separated by periods (.).

The following sample structure definition shows the rules for identifying names of variables within structures:

DECLARE 1 STATE,
          2 NAME CHARACTER (20),
          2 POPULATION FIXED (10),
          2 CAPITAL,
            3 NAME CHARACTER (30),
            3 POPULATION FIXED (10,0),
          2 SYMBOLS,
            3 FLOWER CHARACTER (20),
            3 BIRD CHARACTER (20);

The rules for selecting and specifying variable names for structures are as follows:

If a name is ambiguous, the compiler cannot resolve the reference and issues a message. In the example, the names POPULATION and NAME are ambiguous.

You can specify the name of a major or minor structure in an assignment statement only if the source expression and the target variable are identical in size and structure, and all corresponding members have the same data types.

A structure that is defined with a dimension can have members that are arrays. For example:

DECLARE 1 STATE (50),
          2 AVERAGE_TEMPS(12) FIXED DECIMAL (5,2),
             ⋮

In this example, the elements of the array STATE are structures. At the second level of the hierarchy of each structure, AVERAGE_TEMPS is an array of 12 elements. Because AVERAGE_TEMPS inherits the dimension of STATE, any of AVERAGE_TEMPS's elements must be referred to by two subscripts:

These subscripts can appear following any name in the qualified reference. For example:

STATE(3).AVERAGE_TEMPS(4)
STATE.AVERAGE_TEMPS(3,4)

These references are equivalent.

Note the following rules for specifying subscripts for members of structures containing arrays:

A connected array is one whose elements occupy consecutive locations in storage. For example:

DECLARE NEWSPAPERS (10) CHARACTER (30);

In storage, the 10 elements of the array NEWSPAPERS occupy 10 consecutive 30-byte units. Thus, NEWSPAPERS is a connected array.

A connected array is valid as the target of an assignment statement, as long as the source expression is a similarly dimensioned array or a single scalar value. The top diagram in Figure 4.4, “Connected and Unconnected Arrays” shows the storage of a connected array.

In an unconnected array, the elements do not occupy consecutive storage locations. The bottom diagram in Figure 4.4, “Connected and Unconnected Arrays” shows the storage of an unconnected array. An unconnected array is not valid in an assignment statement or as the source or target of a record I/O statement. A structure with the dimension attribute always results in unconnected arrays. When a structure is dimensioned, each member of the structure inherits the dimensions of the structure and becomes, in effect, an array. For example:

DECLARE 1 STATE (50),
          2 NAME CHARACTER (20) VARYING,
          2 POPULATION FIXED (31);

In this example, the members NAME and POPULATION of the major structure STATE inherit the dimension 50 from the major structure. When PL/I allocates storage for a structure or a dimensioned structure, each member is allocated consecutive storage locations; thus, the elements of the arrays NAME and POPULATION are not connected.