DIMENSION statement

Syntax

DIM[ENSION] matrix (rows, columns) [ , matrix (rows, columns) ...]
DIM[ENSION] vector (subscript) [ , vector (subscript) ...]

Description

Use the DIMENSION statement to define the dimensions of an array variable before referencing the array in the program. For a matrix (a two-dimensional array), use the DIMENSION statement to set the maximum number of rows and columns available for the elements of the array. For a vector (a one-dimensional array), use the DIMENSION statement to set the maximum value of the subscript (the maximum elements) in the array.

matrix and vector can be any valid variable name. The maximum dimension can be any valid numeric expression. When specifying the two dimensions of a matrix, you must use a comma to separate the row and column expressions. These expressions are called indices.

You can use a single DIMENSION statement to define multiple arrays. If you define more than one array with a DIMENSION statement, you must use commas to separate the array definitions.

The DIMENSION statement declares only the name and size of the array. It does not assign values to the elements of the array. Assignment of values to the elements is done with the MAT statement, MATPARSE statement, MATREAD statements, MATREADU statement, and Assignment Statements.

The DIMENSION statement in an IDEAL or INFORMATION flavor account is executed at run time. The advantage of the way InfoSphere® DataStage® handles this statement is that the amount of memory allocated is not determined until the DIM statement is executed. This means that arrays can be redimensioned at run time.

When redimensioning an array, you can change the maximum number of elements, rows, columns, or any combination thereof. You can even change the dimensionality of an array (that is, from a one-dimensional to a two-dimensional array or vice versa).

The values of the array elements are affected by redimensioning as follows:

Common elements (those with the same indices) are preserved.
New elements (those that were not indexed in the original array) are initialized as unassigned.
Abandoned elements (those that can no longer be referenced in the altered array) are lost, and the memory space is returned to the operating system.

The DIMENSION statement fails if there is not enough memory available for the array. When this happens, the INMAT function is set to a value of 1.

An array variable that is passed to a subroutine in its entirety as an argument in a CALL statement cannot be redimensioned in the subroutine. Each array in a subroutine must be dimensioned once. The dimensions declared in the subroutine DIMENSION statement are ignored, however, when an array is passed to the subroutine as an argument (for more information, see the CALL statement).

PICK, IN2, and REALITY Flavors

In PICK, IN2, and REALITY flavor accounts, arrays are created at compile time, not run time. Arrays are not redimensionable, and they do not have a zero element. To get the same characteristics in an INFORMATION or IDEAL flavor account, use the STATIC.DIM option of the $OPTIONS statement.

Examples

DIM ARRAY(2,2)
ARRAY(1,1)="KK"
ARRAY(1,2)="GG"
ARRAY(2,1)="MM"
ARRAY(2,2)="NN"

In the next example warning messages are printed for the unassigned elements in the matrix. The elements are assigned empty strings as their values.

DIM ARRAY(2,3)
*
PRINT
FOR X=1 TO 2
   FOR Y=1 TO 3
      PRINT "ARRAY(":X:",":Y:")", ARRAY(X,Y)
   NEXT Y
NEXT X
DIM S(3,2)
S(1,1)=1
S(1,2)=2
S(2,1)=3
S(2,2)=4
S(3,1)=5
S(3,2)=6

In the next example the common elements are preserved. Those elements that cannot be referenced in the new matrix (S(3,1), S(3,2) ) are lost.

DIM S(2,2)
*
PRINT
FOR X=1 TO 2
FOR Y=1 TO 2
PRINT "S(":X:",":Y:")", S(X,Y)
NEXT Y
NEXT X

This is the program output:

ARRAY(1,1)         KK
ARRAY(1,2)         GG
ARRAY(1,3)         Program 'DYNAMIC.DIMENSION':
Line 12, Variable previously undefined, empty string 
used.

ARRAY(2,1)         MM
ARRAY(2,2)         NN
ARRAY(2,3)         Program 'DYNAMIC.DIMENSION':
Line 12, Variable previously undefined, empty string 
used.

S(1,1)   1
S(1,2)   2
S(2,1)   3
S(2,2)   4