DIM (DIMENSION)

Dimensions an array of variables.

Synopsis

DIM array([rows[,columns]])[,array2([rows[,columns]])[,...]
DIMENSION array([rows[,columns]])[,array2([rows[,columns]])[,...]

Arguments

array	Name of an array. Follows standard variable naming conventions. Can be a single array or a comma-separated list of arrays.
rows	Optional — A positive, non-zero integer specifying the number of array elements to dimension for a one-dimensional (vector) array, or the number of rows to dimension for a two-dimensional array. Maximum value is 65535. A value less than 1 or greater than 65535 results in an <ARRAY DIMENSION> error.
columns	Optional — For two-dimensional (matrix) arrays, a positive, non-zero integer specifying the number of columns per row. Can only be used in conjunction with the rows argument. Maximum value is 65535. A value less than 1 or greater than 65535 results in an <ARRAY DIMENSION> error.

Description

The DIMENSION and DIM keywords are synonyms.

The DIM statement can be used in two ways: explicitly, to dimension a one-dimensional or two-dimensional array, or implicitly to dimension a multidimensional array.

Most MultiValue systems require you to explicitly dimension the rows and columns of a static array. These values specify the maximum number of elements that can be defined for that array. An explicitly dimensioned array is limited to two subscripts. It can be either one-dimensional, representing a vector array, or two-dimensional, representing the rows and columns of a matrix array. A one-dimensional array can be dimensioned either as a vector array: DIM arrayname(n) or a matrix array with a column dimension of 1: DIM arrayname(n,1).
Caché MVBasic also allows you to dimension arrays of an arbitrary number of dimensions. This allows MVBasic to support the multidimensional arrays used in Caché. You specify a multidimensional array using a DIM statement with empty parentheses: DIM arrayname(). This declares arrayname as a dimensioned array, but the number of dimensions and number of elements in each dimension may be expanded dynamically at runtime.

If a subroutine or function uses a static array (for example, DIM myarray(2)), the static array must be dimensioned within the subroutine or function. However, if a subroutine or function uses an array of unspecified dimensions (for example, DIM myarray()), you may specify the DIM either within or outside the subroutine or function.

The subscripts of a dimensioned array can be specified using named variables, as well as numeric indices. Variables whose names begin with a % are known as public arrays and their values are preserved across SUBROUTINE calls in a similar manner to COMMON arrays. Variables whose names begins with ^ are known as globals and their values are stored on disk automatically. Variables with normal naming conventions are known as local arrays and their value is lost when the program terminates, as with any other variable.

To clear data from an implicitly dimensioned array, use $kill. This clears any values that have been assigned.

Note:

When executing a DIM statement from the MVBasic command shell, you must assign and use the array elements within the same command line. For example:

USER:;DIM x(),y() ;x(1)="fred" ;y(2)="betty" ;CRT x(1),y(2)

Attempting to reference a dimensioned array in a subsequent command line results in a MVBasic syntax error.

You cannot DIM the same array twice in a DIM statement. You cannot DIM an array that has already been declared using the COMMON statement. Attempting to do so results in a compile error.

You can use the EXISTS function or the $DATA function to determine if a variable or array node has been defined.

All uninitialized variables are treated as zero-length strings ("").

Using Dimensioned Arrays

You can use the INMAT function to return the defined dimensions of a static array.

Emulation

IN2, INFORMATION, PIOpen, Prime, UniData, and UniVerse respond to an undimensioned array element by issuing a runtime <UNDEFINED> error. Other emulations respond to an undimensioned array element by issuing a compile-time syntax error.

Examples

The following examples illustrate the use of the DIM statement:

! Dimensions a one-dimensional array with 10 elements.
DIM MyVector(10)
   
! Dimensions a two-dimensional matrix array 
! with 10 rows and 10 columns.
DIM MyMatrix(10,5)
  
! Dimensions a two-dimensional array using local variables
DIM MyMatrix(myrows,mycols)

! Dimension a local array of arbitrary size and subscript type.
DIM MyLocal()
    MyLocal(88) = “88”
    MyLocal(88,”The”) = “The 88”
    MyLocal(“Hello”) = “World!”

Notes

Caché MVBasic does not require the dimension of arrays to be specified, and therefore does not implement the ReDim Statement.