Command: GETSUBTREE
Command: MERGEFROM

Purpose: This returns the sub-tree of persistent array references beneath a specified parent array reference. In effect this command returns an array that represents the sub-tree of nodes beneath a specified array reference.

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

myArray="aaa"
myArray[1,"x"]="hello"
myArray[1,"y"]="world"
myArray[1,"y","aa"]=12.34
myArray[1,"y","ab"]=23.45
myArray[1,"y","ab",2,3]=999
myArray[1,"y","ad"]=""
myArray[1,"y","hello world"]="ok"
myArray[1,"z"]=""
myArray[1,"z","hello world"]="not ok"

The example below demonstrates the behaviour of various GETSUBTREE command when applied to this array:

Client: GETSUBTREE myArray[1,"y"]
Server: *12
Server: $-1
Server: $5
Server: world
Server: $4
Server: "aa"
Server: $5
Server: 12.34
Server: $4
Server: "ab"
Server: $5
Server: 23.45
Server: $8
Server: "ab",2,3
Server: $3
Server: 999
Server: $4
Server: "ad"
Server: $-1
Server: $13
Server: "hello world"
Server: $2
Server: ok

The first line sent by the server indicates that ten records follow.

The second line is $-1 because data exists at the specified reference itself (ie myArray[1,"y"]) so no subscripts can be defined. This is followed by two lines that define the 5 bytes of data (ie myArray[1,"y"]="world").

The next lines represent the sub-tree of nodes under myArray[1,"y"]:

subtree("aa")=12.34
subtree("ab")=23.45
subtree("ab",1,2)=999
subtree("ad")=""
subtree("hello world")="ok"

Note that the null data value for the "ad" record is represented by $-1

Arguments:

Argument No Description
1 An array node and subscript(s) whose sub-tree will be returned. This takes the format:
   arrayRef[subscr1,subscr2,..etc]
You may specify no subscripts at all, in which case the entire array contents will be returned,eg:
   arrayRef
Text subscripts must be wrapped in double quote (") characters. Quoting of numeric subscripts is optional.

Response

Multi-line response

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

..followed by pairs of records that represent the sub-tree's subscripts and any data respectively:

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

If no subscripts exists (ie if data exists at the top level of the sub-tree):

Server: $-1
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 example above is the equivalent of:

merge subtree=^myArray(1,"y)