Caché MultiValue Basic Reference
[Back] [Next]
Go to:

Builds a dynamic array from a dimensioned array.
MATBUILD dynarray FROM array [,start [,end]] [USING delimiter]
dynarray A dynamic array, each element of which receives the value of the corresponding dimensioned array element.
array Name of an existing dimensioned array. This array must have been dimensioned using the DIM statement.
start Optional — An integer that specifies the first element to be transcribed. The default is 1.
end Optional — An integer that specifies the last element to be transcribed. You must specify a start value to specify an end value. The default is the last element in array.
USING delimiter Optional — The dynamic array delimiter character to be used to separate elements, specified as a variable (for example @VM) or a quoted string. The default is a field mark (@FM). If a string of more than one characters is specified, only the initial character is used. The empty string ("") is a valid value here; it's use would create a string of concatenated elements, not a dynamic array.
The MATBUILD statement assigns the values of the elements of a specified dimensioned array to a dynamic array. You can create a dynamic array containing all of the element values of the dimensioned array, or you can limit the dynamic array to those elements of the dimensioned array between start and end.
This statement cannot be executed from the MVBasic command shell. Attempting to do so results in a MVBasic syntax error.
By default, MATBUILD assigns empty strings to unassigned nodes. If the highest subscripts of the dimensioned array are unassigned or have empty string values, the dynamic array is truncated at the last assigned data value. This behavior can be configured using the %SYSTEM.Process.MVUndefined() method.
MATBUILD is the functional opposite of MATPARSE.
D3, jBASE, MVBase, R83, POWER95, Reality, and Ultimate set $OPTIONS MATBUILD.UNASSIGNED.ERROR. This causes these emulations to not support unassigned dimensioned array nodes. If MATBUILD encounters an unassigned node, it issues an <UNDEFINED> error. This behavior can be configured using the %SYSTEM.Process.MVUndefined() method.
UniData MATBUILD does not truncate the highest subscripts of a dimensioned array if they are unassigned or have empty string values.
The following example illustrates the use of the MATBUILD statement:
! Dimension a one-dimensional array with 6 elements.
DIM MyVector1(6)
! Assign the value "pending" to all elements of MyVector1
MAT MyVector1="pending"
! Assign the values of elements of a dimensioned array 
! to a dynamic array
MATBUILD mydynarray FROM MyVector1 USING "^"
The results are the mydynarray dynamic array string assigned the value "pending^pending^pending^pending^pending^pending". Here the "^" character is used as the dynamic array delimiter, rather than the default field mark character.
See Also