Multidimensional Arrays

Caché includes support for multidimensional arrays. A multidimensional array is a persistent variable consisting of one or more elements, each of which has a unique subscript. You can intermix different kinds of subscripts. An example is the following MyVar array:

MyVar
MyVar(22)
MyVar(-3)
MyVar(“MyString”)
MyVar(-123409, “MyString”)
MyVar(“MyString”, 2398)
MyVar(1.2, 3, 4, “Five”, “Six”, 7)

The array node MyVar is an ObjectScript variable and follows the conventions for that variable type.

The subscripts of MyVar are positive and negative numbers, strings, and combinations of these. A subscript can include any characters, including Unicode characters. A numeric subscript is stored and referenced as a canonical number. A string subscript is stored and referenced as a case-sensitive literal. A canonical number (or a number that reduces to a canonical number) and a string containing that canonical number are equivalent subscripts.

What Multidimensional Arrays Are

Succinctly, multidimensional arrays are persistent, n-dimensional arrays that are denoted through the use of subscripts. Individual nodes are also known as “globals” and are the building block of Caché data storage. They have other characteristics as well:

They exist in tree structures.
They are sparse.
They can appear in multiple settings.

Multidimensional Tree Structures

The entire structure of a multidimensional array is called a tree; it begins at the top and grows downwards. The root, MyVar above, is at the top. The root, and any other subscripted form of it, are called nodes. Nodes that have no nodes beneath them are called leaves. Nodes that have nodes beneath them are called parents or ancestors. Nodes that have parents are called children or descendants. Children with the same parents are called siblings. All siblings are automatically sorted numerically or alphabetically as they are added to the tree.

Sparse Multidimensional Storage

Multidimensional arrays are sparse. This means that the example above uses only seven reserved memory locations, one for each defined node. Further, since there is no need to declare arrays or specify their dimensions, there are additional memory benefits: no space is reserved for them ahead of time; they use no space until needing it; and all the space that they use is dynamically allocated. As an example, consider an array used to keep track of players’ pieces for a game of checkers; a checkerboard is 8 by 8. In a language that required an 8–by-8 checkerboard-sized array would use 64 memory locations, even though no more than 24 positions are ever occupied by checkers; in ObjectScript, the array would require 24 positions only at the beginning, and would need fewer and fewer during the course of the game.

Settings for Multidimensional Arrays

Multidimensional arrays can appear in three different settings:

Any global can be used and thereby transformed into an array. In this case, global ^y becomes a node in the array ^y when you create global ^y(1).
Any property can be used and thereby transformed into an array. In this case, property Object.Get(Prop) becomes a node in the array Person.Get(Prop) when you create property Person.Get(Prop,1).
Any local variable can be used and thereby transformed into an array. In this case, variable x becomes a node in array x when you create variable x(1).

Manipulating Multidimensional Arrays

You can write to and read from them using the Read and Write commands respectively.

Caché provides a comprehensive set of commands and functions for working with multidimensional arrays:

Set places values in an array.
Kill removes all or part of an array structure.
Merge copies all or part of an array structure to a second array structure.
$Order and $Query allows you to iterate over the contents of an array.
$Data allows you to test for the existence of nodes in an array.

This set of commands and functions can operate on multidimensional globals and multidimensional local variables. Globals can be easily identified by their leading “^” (caret) character.

For More Information

For further information on multidimensional arrays, see Using Caché Globals.