HP OpenVMS Systems Documentation

HP BASIC for OpenVMS
User Manual

Executable DIM statements have at least one variable bound. Bounds can be constants or simple variables, but at least one bound must be a variable. Executable DIM statements let you redimension an array at run time. The bounds of the array can become larger or smaller, but the number of dimensions cannot change. For example, you cannot redimension a four-dimensional array to be five-dimensional.

The executable DIM statement cannot be used on arrays in COMMON, MAP, DECLARE, or declarative DIM statements, nor on virtual arrays or arrays received as formal parameters.

Whenever an executable DIM statement executes, it reinitializes the array. If you change the values of an executable DIM statement, the initial values are reset each time the DIM statement is executed.

In the following example, the second DIM statement reinitializes the array real_array; therefore, real_array(1%) equals zero in the second PRINT statement:

X% = 10%
Y% = 20%
DIM real_array(X%)
real_array(1%) = 100
PRINT real_array(1%)
DIM real_array(Y%)
PRINT real_array(1%)
END

Output

100
0

You cannot reference an array named in an executable DIM statement until after the DIM statement executes. If you reference an array element declared in an executable DIM statement whose subscripts are larger than the bounds specified in the last execution of the DIM statement, BASIC signals the run-time error "Subscript out of range" (ERR = 55), provided subscript checking is enabled.

6.2.3 Creating Arrays with the COMMON Statement

Create arrays with the COMMON statement when you need an array of fixed-length strings, or when you want to share an array among program modules. Program modules can share arrays in COMMON statements by defining a common block with the same name.

The COMMON statements in the following programs create a 100-element array of fixed-length strings, each element 10 characters long. Because the main program and subprograms use the same common name, the storage for these arrays is overlaid when the programs are linked; therefore, both programs can read and write data to the array.

!Main Program
COMMON (ABC) STRING access_list(1 TO 100) = 10

!Subprogram
SUB SUB1
COMMON (ABC) STRING new_list(1 TO 100) = 10

Create arrays with the MAP statement only when you want the array to be part of a record buffer, or when you want to overlay the storage containing the array. Note that string arrays in maps are always fixed-length.

You associate the array with a record buffer by naming the map in the MAP clause of the OPEN statement.

In the following example, the MAP statement creates two arrays: an 11-element fixed-length string array named team and a 33-element array of WORD integers named bowling_scores. Because the OPEN statement specifies MAP ABC, the storage for these arrays is used as the record buffer for the open file.

MAP (ABC) STRING team(10) = 20, WORD bowling_scores(0 TO 32)
OPEN "BOWLING.DAT" AS FILE #1%, SEQUENTIAL VARIABLE, MAP ABC

Create arrays implicitly as follows:

• By referencing an element of an array that has not been explicitly declared
• By using MAT statements

When you first create an implicit array, the lower bound is zero and the upper bound is 10. An array created by referencing an element can have up to 32 dimensions in BASIC. An array created with a MAT statement can have only one or two dimensions.

If you reference an element of an array that has not been explicitly declared, BASIC creates a new array with the name you specify. Arrays created by reference have default subscripts of (0 TO 10), (0 TO 10, 0 TO 10), (0 TO 10, 0 TO 10, 0 TO 10), and so on, depending on the number of dimensions specified in the array reference. For example, the following program implicitly creates three arrays and assigns a value to one element of each:

LET A(5,5,5) = 3.14159
LET B%(3) = 33
LET C$(2,2) = "Russell Scott"
END

The first LET statement creates an 11-by-11-by-11 array that stores floating-point numbers and assigns the value 3.14159 to element (5,5,5). The second LET statement creates an 11-element list that stores integers and assigns the value 33 to element (3), and the third LET statement creates an 11-by-11 string array and assigns the value "Russell Scott" to element (2,2).

When you create an implicit numeric array by referring to an element, BASIC initializes all elements (except the one assigned a value) to zero. For implicit string arrays, BASIC initializes all elements (except the one assigned a value) to a null string. When you implicitly create an array, you cannot specify a subscript greater than 10. An attempt to do so causes BASIC to signal "Subscript out of range" (ERR = 55), provided that subscript checking is enabled.

Note that you cannot create an array implicitly, then redimension the array with an executable DIM statement. The DIM statement must execute before any reference to the array.

An array name cannot appear in a declarative statement after the array has been implicitly declared by a reference. The following DECLARE statement is therefore illegal and causes HP BASIC to signal the compile-time error "illegal multiple definition of name NEW_ARRAY."

new_array (5,5,5) = 1
DECLARE LONG new_array (15,10,5)

BASIC provides two built-in functions, LBOUND and UBOUND, that allow you to determine the lower and upper bounds, respectively, for any dimension in an array.

The following example sets up four variables that contain the lower and upper bounds of both dimensions of the array Sales_data. These variables represent the years and months for which there is sales data available. The two FOR...NEXT loops print all the sales information in the array, starting with the first year and month, and ending with the last year and month.

DECLARE Sales_data(1900 TO 1999, 1 TO 12)

Month_start% = LBOUND (Sales_data, 2)
Year_start% = LBOUND (Sales_data, 1)
Month_end% = UBOUND (Sales_data, 2)
Year_end% = UBOUND (Sales_data, 1)
FOR Year% = Year_start% TO Year_end%

    FOR Month% = Month_start% TO Month_end%
        PRINT Sales_data(Year%, Month%)
    NEXT Month%

NEXT Year%

The following sections explain how to access and write to BASIC arrays with the LET and PRINT statements.

6.5.1 Assigning Values with the LET Statement

The LET statement assigns values to individual array elements. For example:

DIM voucher_num%(100)
   .
   .
   .
LET voucher_num%(20) = 3253%
   .
   .
   .
END

You can also assign values to a portion of an array with the LET statement and a FOR...NEXT loop. In the following example, the FOR...NEXT loop assigns zero to array elements (1,5) to (1,10), (2,5) to (2,10), and (3,5) to (3,10):

DIM po_number%(100,100)
   .
   .
   .
FOR I% = 1% TO 3%
    FOR J% = 5% TO 10%
           LET po_number%(I%,J%) = 0%
    NEXT J%
NEXT I%
   .
   .
   .
END

You print individual array elements by naming those elements in the PRINT statement. For example:

PRINT parts_list$(35%)

With a FOR...NEXT loop, you can print all or part of an array. For example:

DIM capture_ratio(10,10)
   .
   .
   .
FOR Y% = 7% TO 10%
  FOR X% = 7% TO 10%
      PRINT capture_ratio(X%,Y%)
  NEXT X%
NEXT Y%

MAT statements let you assign values to or display entire arrays with a single statement. They also let you do the following:

• Implicitly create arrays
• Assign names to arrays
• Specify array dimensions
• Redimension existing arrays (to equal or smaller sizes)
• Assign element values
• Print the contents of arrays
• Perform matrix arithmetic

MAT statements are valid only on arrays of one or two dimensions. When MAT statements execute, they use row and column zero to store intermediate calculations. This means that MAT statements can overwrite data stored in row and column zero of your arrays, and you should not depend on data in these elements if your program uses MAT statements.

The default subscripts for arrays created implicitly with MAT statements are (10) or (10,10). The default is two dimensions. This means that if you create an array with a MAT statement and do not specify any subscripts, BASIC creates a two-dimensional, 11-by-11 array. If you specify a single subscript, BASIC creates a one-dimensional array with 11 elements.

Table 6-1 lists MAT statements and explains their functions.

In the following example, the first MAT statement creates the string array z_array$ with eight rows and eight columns and assigns a null string to all elements. The second MAT statement redimensions the array to six rows and six columns. The third MAT statement adds the values in each corresponding element of arrays B and C and stores the values in the corresponding elements of array A.

MAT z_array$ = NUL$(7,7)
MAT z_array$ = NUL$(5,5)
MAT A = B + C
END

The MAT statement can create an array and optionally assign values to all elements in that array. By specifying one of the MAT statement keywords, you can initialize arrays in one of four ways. Table 6-2 lists the MAT statement keywords and their functions.

The array name can specify an existing array. MAT statements do not assign values to row and column zero.

Note that the MAT statement does not require subscripts. In the case of existing arrays:

• If you do not specify subscripts, BASIC does not change the current subscripts.
• If you specify subscripts, BASIC redimensions the array to the specified subscripts. When redimensioning arrays with MAT, you cannot increase the total number of array elements (including those in row and column zero).

When you are creating arrays with MAT:

• If you do not supply subscripts, BASIC assigns two subscripts, each with a value of 10.
• If you specify subscripts, they define the dimensions of the array being implicitly created. Subscript values cannot exceed 10. Consider the following example:

DIM A(10,10), B(15), C(20,20)
MAT A = ZER             !Sets all elements of A to 0
MAT B = CON(10)         !Sets elements of B to 1; redimensions B
MAT C = IDN(10,10)      !Redimensions C to 10x10 identity matrix
PRINT "ARRAY A:"
MAT PRINT A;
PRINT
PRINT "ARRAY B:"
MAT PRINT B;
PRINT
PRINT "ARRAY C:"
MAT PRINT C;

Output

ARRAY A:
0  0  0  0  0  0  0  0  0  0
0  0  0  0  0  0  0  0  0  0
0  0  0  0  0  0  0  0  0  0
0  0  0  0  0  0  0  0  0  0
0  0  0  0  0  0  0  0  0  0
0  0  0  0  0  0  0  0  0  0
0  0  0  0  0  0  0  0  0  0
0  0  0  0  0  0  0  0  0  0
0  0  0  0  0  0  0  0  0  0
0  0  0  0  0  0  0  0  0  0

ARRAY B:
1  1  1  1  1  1  1  1  1  1

ARRAY C:
1  0  0  0  0  0  0  0  0  0
0  1  0  0  0  0  0  0  0  0
0  0  1  0  0  0  0  0  0  0
0  0  0  1  0  0  0  0  0  0
0  0  0  0  1  0  0  0  0  0
0  0  0  0  0  1  0  0  0  0
0  0  0  0  0  0  1  0  0  0
0  0  0  0  0  0  0  1  0  0
0  0  0  0  0  0  0  0  1  0
0  0  0  0  0  0  0  0  0  1

The MAT READ statement assigns values from DATA statements to array elements. Subscripts define either the dimensions of the array being created or the new dimensions of an existing array; subscripts are optional in MAT READ statements.

If you do not provide enough data in DATA statements to fill the specified array, BASIC leaves the remaining array elements unchanged. If you provide more data values than there are array elements, BASIC assigns enough values to fill the array and leaves the DATA pointer at the next value.

In the following example, BASIC fills matrix B with the first four DATA items, fills matrix C with the next four DATA values, and leaves the DATA pointer at the ninth value in the DATA list:

MAT READ B(2,2)
MAT READ C(2,2)
PRINT
PRINT "MATRIX B"
PRINT
PRINT
MAT PRINT B;
PRINT
PRINT "MATRIX C"
PRINT
PRINT
MAT PRINT C;
DATA 1,2,3,4,5,6,7,8,9,10
END

Output

MATRIX B

 1  2
 3  4
MATRIX C

 5  6
 7  8

The MAT INPUT statement assigns values from your terminal to array elements. The MAT INPUT statement reads data from a terminal-format file and writes it to an array. The optional subscripts in a MAT INPUT statement define either the dimensions of the array being created implicitly or the new dimensions of an existing array. If you are implicitly creating the array, the value of a subscript cannot exceed 10.

The MAT INPUT statement requests data from your terminal, as does the INPUT statement; it prints a question mark (?) prompt that you can disable with the SET NO PROMPT statement and then enable with the SET PROMPT statement. However, you cannot include a string prompt with the MAT INPUT statement.

When you enter a series of values separated by commas, BASIC enters the values you supply into successive array elements by row, starting with element (1,1) and filling row 1 before starting row 2. If you provide fewer data items than there are elements, the remaining elements are unchanged. If you provide more items than there are elements, BASIC ignores the excess.

The MAT INPUT statement takes values from an open file and assigns them to the matrix elements by rows, starting with element (1,1). It fills the elements in row 1 before starting row 2. The file can have one or more values in each record; however, multiple values must be separated with commas.

In the following example, the open file on channel 3 contains the following data: 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13. The MAT INPUT statement reads this data and uses it to fill the array A, filling in row 1 before beginning row 2. The MAT INPUT B(2,2) statement dimensions array B to 9 elements (0 to 2 in each dimension) and provides values for all the elements except those in row and column zero.

MAT INPUT #3, A
PRINT
MAT PRINT A;
MAT INPUT B(2,2)
PRINT
MAT PRINT B;

Output

  1  2  3  4  5  6  7  8  9  10
 11 12 13  0  0  0  0  0  0  0
  0  0  0  0  0  0  0  0  0  0
  0  0  0  0  0  0  0  0  0  0
  0  0  0  0  0  0  0  0  0  0
  0  0  0  0  0  0  0  0  0  0
  0  0  0  0  0  0  0  0  0  0
  0  0  0  0  0  0  0  0  0  0
  0  0  0  0  0  0  0  0  0  0
  0  0  0  0  0  0  0  0  0  0

? 1,2,3,4

 1  2
 3  4

Note that the MAT PRINT statement does not print row and column zero. For more information about the MAT PRINT statement, see Section 6.6.5.

The MAT INPUT statement can also redimension an existing array.

DIM new_array%(5,5)
MAT INPUT new_array%(2,4)
MAT PRINT new_array%;
END

Output

 ? 1,2,3,4,5,6,7,8

 1 2 3 4
 5 6 7 8

When entering values in response to MAT INPUT, you can enter an ampersand (&) as the last character on the line and continue on the next line.

6.6.4 MAT LINPUT [#] Statement

The MAT LINPUT statement assigns string values to string array elements. The MAT LINPUT statement reads string values from a terminal-format file and writes them to a string array.

The MAT LINPUT statement prompts for individual array elements. It fills the array by rows, starting with element (1,1). It assigns the line you supply (including commas, semicolons, and quotation marks, but excluding the line terminator) to an array element.

DIM emp_nam$(5,5)
MAT LINPUT emp_nam$(2,2)
PRINT emp_nam$(1,1)
PRINT emp_nam$(1,2)
PRINT emp_nam$(2,1)
PRINT emp_nam$(2,2)
END

Output

? SMITH
? JONES
? WHITE
? BLACK
SMITH
JONES
WHITE
BLACK

By specifying the subscripts (2,2), MAT LINPUT redimensions the array to nine elements and overwrites the old values (assigning the values in the same manner as MAT INPUT; see Section 6.6.3). BASIC then prompts for these elements.

MAT LINPUT also excludes line terminators when assigning values to string array elements. MAT LINPUT places the values from the open file into the specified array, filling the array by rows, starting with element (1,1). If there are more values in the file than there are array elements, BASIC ignores the excess records. If there are fewer, BASIC assigns a null string to the remaining elements.

The following program reads 50 records from the open disk file and assigns them to the array named part_name$. If there are more than 50 records in the file, BASIC ignores the excess records. If there are fewer than 50 records, then BASIC fills the remaining elements of the array with the null string.

DIM part_name$(50)
MAT LINPUT #1%, part_name$