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

A user-defined structure for storing multiple data values.
Description
A dynamic array is a uniquely named entity used to store and retrieve multiple data values. These data values are called “elements”. These elements can be flat (all on the same level), or in a hierarchical structure. A dynamic array is a string. Its elements are marked by special delimiter characters within the string.
A dynamic array is assigned element values by using the equal sign (=), the same as an ordinary string. The naming conventions for dynamic arrays are the same as for variables. Caché MVBasic does not distinguish between dynamic array names and variable names; you cannot assign the same name to a dynamic array and to a single-value variable.
Note:
MVBasic also supports standard arrays, using the DIM statement. These should not be confused with dynamic arrays, which are a unique feature of MultiValue database systems.
The scope of a dynamic array is the current process.
The level of a dynamic array element can be specified either by delimiter character variables (for example, @FM), or by numeric operators (for example, <1,2>). These two ways of specifying the level of dynamic array elements are described below.
You can use the RAISE and LOWER functions to change the level of dynamic array elements.
Dynamic Array Level Delimiter Characters
Dynamic arrays can be assigned element values using the following format:
val1:@nM:val2:@nM:val3
The dynamic array level is specified by the @nM special variable, which resolves to a single character that is used as a level delimiter. This delimiter character is concatenated into the string between two data values, using the colon (:) string concatenation operator. The level is specified by the first letter of this code variable, as shown in the following table. Levels are listed in descending order:
Level code variable Level abbreviation and name Character value
@IM I = Item Mark CHAR(255)
@FM or @AM F = Field Mark or Attribute Mark CHAR(254)
@VM V = Value Mark CHAR(253)
@SM or @SVM S = Subvalue Mark (see Subvalue Considerations, below) CHAR(252)
@TM T = Text Mark CHAR(251)
  Z CHAR(250)
Note:
Caché MVBasic supports the UniVerse dynamic array levels to CHAR(250). It does not support UniVerse levels below CHAR(250). It does not support UniData dynamic array levels (such as @RM) that are not supported by the UniVerse implementation.
The Text Mark (@TM) character is inserted in a string by the FMT and FMTS functions.
The character values specified in the above table are the English locale default values. The dynamic array level code variables can be mapped to other character values, as specified in your NLS locale definition.
Dynamic Array Level Numeric Operators
You use the <> operators to assigned element values to a dynamic array, extract an element value from a dynamic array, or to replace an element value in a dynamic array. The <> operators use the following formats:
<f>
<f,v>
<f,v,s>
Where f (field), v (value), and s (subvalue) are comma-separated integers representing the position of the desired element (counting from 1). For example, <2,3> indicates the 3rd Value Mark value within the 2nd Field Mark field.
The first dynamic array element is specified by <1>. Specifying <0> means to insert the specified value to the beginning of the dynamic array; this value then becomes the first dynamic array element. Specifying <-1> (or any negative integer) means to insert the specified value at the end of the dynamic array. The use of these integers is shown in the following example:
alphabet<0>="B"   ; "B"
alphabet<0>="Z"   ; "Z^B"
alphabet<1>="A"   ; "A^B"
alphabet<3>="C"   , "A^B^C"
alphabet<-1>="D"  , "A^B^C^D"
The following example assigns the ^fruit global a dynamic array of field elements:
^fruit<1>="Apple"
^fruit<2>="Orange"
^fruit<3>="Banana"
This is exactly equivalent to:
^fruit="Apple":@FM:"Orange":@FM:"Banana"
To extract an element value from a dynamic array:
var=dynarray<f,v,s>
Where dynarray is a dynamic array, and the angle brackets specify by position the element to extract into the var variable.
To replace an element value in a dynamic array:
dynarray<f,v,s>=newval
Where dynarray is a dynamic array, and the angle brackets specify by position the element to replace with the newval value.
The subscript dynarray<0,v> is parsed as dynarray<1,v>. The subscript dynarray<0,0,s> is parsed as dynarray<1,1,s>. This is true for Caché and all emulations except UniData.
Subvalue Considerations
Caché MultiValue and all emulations allow a simple selection by subvalues on multivalued fields. UniData emulation also can select by subvalues in single-valued fields. Caché MultiValue supports selection on subvalued fields if the field is defined as a property in an associated class with the MVSVASSOCIATION parameter set.
When exploding, UniVerse and UniData explode subvalues, but D3, Reality, and jBASE only explode values. Reality provides a BY-EXP-SUB keyword to explode by subvalues which gives the same result as a simple BY-EXP on UniVerse. For further details, refer to the BY clause in Caché MultiValue Query Language (CMQL) Reference.
When using print limiting, D3 and Reality limit to values where the desired subvalue is the first or only subvalue. UniVerse limits to only the subvalues that have the limiting value.