Purpose: Traverses a specified array and level of subscripting and returns the value of the subscript and its corresponding data if any exists. The sequence in which subscript values are returned is determined by the natural collating sequence in which GT.M and Caché save subscript values (both databases apply the same rules).

The hierarchical nature of the persistent arrays means that traversal of the levels of the hierarchy is an important aspect of their use.

The use of these commands is best illustrated by an example. Consider the following array structure:

myArray[1,"y","hello world"]="ok"
myArray[1,"z","hello world"]="not ok"

The examples below demonstrate the behaviour of various GETALLSUBS or ORDERALL commands when applied to this array:

Client: GETALLSUBS myArray
Server: *2
Server: $1
Server: 1
Server: $-1

This is because we're wanting to find all values that exists for the first subscript of the myArray array. There is only one: 1 denoted by the first record returned. No data exists at that level of subscripting (ie myArray[1]), so the second record returned is $-1

Client: GETALLSUBS myArray[1]
Server: *6
Server: $1
Server: x
Server: $5
Server: hello
Server: $1
Server: y
Server: $5
Server: world
Server: $1
Server: z
Server: $0

This is because we've asked to return all values of the second subscript of the myArray array where the value of the first subscript is 1. Six records are returned, corresponding to the subscript values x, y and z. Data exists for each subscript value (ie myArray[1,"x"], myArray["1,"y"] and myArray[1,"z"]. Note the way the null value held at myArray[1,"z"] is represented as a data length of 0 and an empty data line. This is to differentiate it from $-1 which signifies no data at all.


Argument No Description
1 An array node and subscript(s). This takes the format:
You may specify no subscripts at all, in which case the first subscript is traversed,eg:
Traversing the second level of subscripting would look like:
Traversing the third level of subscripting would look like:

Note that subscripts can be numeric or text. Text subscripts must be wrapped in double quote (") characters. Quoting of numeric subscripts is optional.


Multi-line response

Server Line 1: *[no of records that follow]

..followed by pairs of records that represent the subscript and any data respectively:

Server: $[length of subscript value in bytes]
Server: Subscript value
Server: $[length of data in bytes]
Server: Data

If no data exists for a subscript value:

Server: $[length of subscript value in bytes]
Server: Subscript value
Server: $-1

For those familiar with the native language of GT.M and Caché systems, the earlier examples above are roughly the equivalent of:

set sub1=""
for  set sub1=$order(^myArray(sub1)) quit:sub1=""  write sub1,!,$get(^myArray(sub1)),!
set sub1=""
for  set sub1=$order(^myArray(1,sub1)) quit:sub1=""  write sub1,!,$get(^myArray(1,sub1)),!