Dimensioned Arrays

A 'dimensioned array' is a multi-element data structure which provides a programmer with a method of storing sets of related data. It consists of a set of locations, each capable of storing a different data value. Each location, called an element, is accessed by specifying the array name followed by one or more numbers that specify the position of the element within the array (see Syntax below). Each element is stored as a single variable.

Two types of dimensioned array are available:

• One-dimensional (also called a vector).

• Two-dimensional (also called a matrix).

An example of a dimensioned array (vector) with four elements is given below:

1 ABC
2 DEF]GHI]JKL
3 MNO\PQR\STU]VWX
4 YZ

Syntax

The following syntax is used to reference the position of an array element:

dimArray{(row{,column})}

where:

dimArraySpecifies the dimensioned array variable.

rowSpecifies the row number of an element in a vector or matrix.

columnSpecifies the column number of an element in a matrix.

Dimensioning an Array

A dimensioned array is the only type of DataBasic variable which must be pre-defined (dimensioned) before use. This is done using the DIM{ENSION} or COMMON statement which define the variable type (dimensioned array) and the number of array elements.

When dimensioning arrays, the following limits apply:

Maximum number of rows	32,767
Maximum number of columns	32,767
Total number of array elements (rows * columns)	134,217,727
Total number of descriptors (normal variables + array elements)	4,194,272

Creating a One-dimensional Array (Vector)

The following example program sets up a one-dimensional array (vector) NAMES and places data into it.

DIM NAMES(4)         * Dimensions NAMES
NAMES(1)="TIM"       * Places data in elements
NAMES(2)="JOHN"
NAMES(3)="GILL"
NAMES(4)="SUE"

The following table shows the data placed in the vector NAMES by the program:

Array Element	Content
1	TIM
2	JOHN
3	GILL
4	SUE

Creating a Two-dimensional Array (Matrix)

The following example program sets up a two-dimensional array (matrix) LIST into which names and telephone numbers are placed.

DIM LIST(3,3)            * Dimensions LIST
LIST(1,1)="D. Brown"     * Places data in elements: (row,column)
LIST(2,1)="F. Smith"
LIST(3,1)="G. Edwards"
LIST(1,2)="Luton"
LIST(2,2)="Bedford"
LIST(3,2)="Cambridge"
LIST(1,3)="423546"
LIST(2,3)="657456"
LIST(3,3)="453219"

The following table shows the data placed in the matrix LIST by the program.

	Column 1	Column 2	Column 3
Row 1	D. Brown	Luton	423546
Row 2	F. Smith	Bedford	657456
Row 3	G. Edwards	Cambridge	453219

Accessing Array Elements

Note that in the examples given, array elements are accessed, to enter or retrieve data, by specifying their positions in the array. For example, in the vector NAMES the name 'TIM' is assigned to the first element by the statement NAMES(1)="TIM". Similarly, 'JOHN' is assigned to the second element by the statement NAMES(2)="JOHN", and so on.

For a matrix, you must specify both the column and row positions of the element. Hence, 'Cambridge' is assigned to the second column of the third row in LIST by the statement LIST(3,2)="Cambridge". Similarly, the number '657456' is assigned to the third column of the second row in LIST by the statement LIST(2,3)="657456".

Using MATWRITE{U} and MATREAD{U}

Either MATREAD or MATREADU can be used to read data from a Reality file item into a dimensioned array. MATREADU locks the item first before commencing the read. MATWRITE or MATWRITEU can then be used to write the data in the array back to an item. MATWRITEU writes to an item without unlocking it. In transfers between the array and the file item, each element corresponds to an attribute in the file item.

Writing a Matrix to Disk

If you need to write a matrix to a file, this can be done as shown in the following example:

DIM VAR (5,2)
.
.
.
MATWRITE VAR ON FILE,ITEM

However, there are alternative methods you can use. One way is to use the MATBUILD statement to copy the data into a dynamic array, followed by the WRITE statement to write the dynamic array to the file. For example:

MATBUILD VAR3 FROM VAR USING AM
WRITE VAR3 ON FILE,ITEM

Another is to use the MAT statement to copy the matrix to a vector and then use MATWRITE. For example:

DIM VAR(5,2), VAR2(10)
.
.
.
MAT VAR2 = MAT VAR
MATWRITE VAR2 ON FILE,ITEM

In all three of the preceding examples, each array element becomes a single attribute in the filed item. However, what if you want each row of your matrix to become an attribute and each column a value? The problem now becomes more complicated, but it can be done. However, you cannot use MATWRITE or MATBUILD - MATWRITE can only assign each element to an attribute, and though MATBUILD can assign each element to a value, it cannot assign to both attributes and values.

The following example shows one way to do this:

DIM VAR(r,c)
VR=''
.
.
.
FOR R=1 TO r
  FOR C=1 TO c
   VR<R,C>=VAR(R,C)
  NEXT C
NEXT R
WRITE VR ON FILE,ITEM

In the above code, r = the number of rows or attributes and c = the number of columns or values. The contents of the dimensioned array are copied to a dynamic array (VR) with the rows forming the attributes and the columns the values, and the result is written to the file item.