## DIMENSION, DIM, REDIMENSION, REDIM |

The DIMENSION statement is used to set the dimensions of a matrix. The short form DIM may be used in place of DIMENSION. The REDIMENSION or REDIM statement is identical except where the matrix is a subroutine argument.
Format
DIMENSION mat(rows {, cols}) REDIMENSION mat(rows {, cols}) DIMENSION var
where
In all cases, multiple comma separated items may be included in a single statement.
A matrix variable is a one or two dimensional array of values. Matrices must be declared by use of the DIMENSION statement and this statement must be executed at program run time before the variable is used in any other way.
A one dimensional matrix of ten elements is defined by a statement of the form
DIMENSION A(10)
For a two dimensional matrix with 5 rows of 8 columns this becomes
DIMENSION B(5,8)
By default, all matrices have an additional element, the zero element, which is used by some QMBasic statements. This is referred to as A(0) or B(0,0).
The elements of a matrix may hold data of differing types (numeric, string, file variable, etc).
A matrix may be re-dimensioned at any time by a further DIMENSION statement, including changing the number of dimensions. Existing values of matrix elements will be retained in the re-dimensioned matrix by effectively copying elements on a row by row basis. Thus, increasing the number of rows in a two dimensional matrix does not affect the previously existing items whereas increasing the number of columns will reorganise the existing data. When enlarging a matrix, the newly created elements will be unassigned. When decreasing the size of a matrix, any values in the excess elements are discarded.
A matrix passed into an external subroutine or function as an argument variable cannot be re-dimensioned using DIMENSION. Instead, the REDIMENSION statement must be used. See the SUBROUTINE statement for more detail.
The $MODE compiler directive can be used to select Pick style matrices which do not have a zero element and cannot be re-dimensioned.
The INMAT() function may be used to check on the success of a DIMENSION statement. A sequence such as DIMENSION A(N) IF INMAT() THEN ABORT "Insufficient memory" will cause the program to abort if there is insufficient memory to hold the matrix. The INMAT() function used in this way returns 0 if the DIMENSION statement was successful, 1 if it failed. With the memory sizes found on modern systems, this test is probably totally unnecessary and usually omitted.
The INMAT() function can also be used to find the current dimensions of a matrix. For a single dimensional matrix, this function returns the number of elements excluding the zero element. For a two dimensional matrix, the function returns the row and column dimensions separated by a value mark.
If the $MODE EXPLICIT compiler directive is in force, scalar variables must also be declared in a DIMENSION statement before any other reference to the variable name in the program. This mode allows improved error checking by trapping errors such as misspelled variable names that might otherwise simply appear to be a separate variable.
Examples
N = DCOUNT(REC, @FM) DIM A(N) MATPARSE A FROM REC, @FM
This program fragment creates an array with the correct number of elements to receive the result of a MATPARSE operation on dynamic array REC and then performs the MATPARSE.
DIM A(3), B(2,3) DISPLAY INMAT(A) DISPLAY CHANGE(INMAT(B), @VM, ',')
This program fragment creates two matrices and reports their sizes. For the second use of INMAT(), the CHANGE() function has been use to replace the value mark in the returned data with a comma. The program output would be 3 2,3
DIM CLIENT, DATA.REC
This statement declares two scalar variables. This is only needed in conjunction with the $MODE EXPLICIT compiler directive.
See also: INMAT(), MAT, MATBUILD, MATREAD, MATREADCSV, MATPARSE, MATWRITE |