Caché MultiValue Basic Reference
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   

Dimensions an array of variables.
DIM array([rows[,columns]])[,array2([rows[,columns]])[,...]
DIMENSION array([rows[,columns]])[,array2([rows[,columns]])[,...]
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.
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.
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.
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.
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.
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!”
Caché MVBasic does not require the dimension of arrays to be specified, and therefore does not implement the ReDim Statement.
See Also