Command: SETSUBTREE
Command: MERGETO

Purpose: Creates a sub-tree of persistent array references beneath a specified parent array reference. In effect this command merges an incoming array into an existing saved array, but as a sub-tree beneath the specified array reference. Any existing references that are not overwritten by the incoming references will remain unchanged.

The use of the SETSUBTREE 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","hello world"]="ok"
myArray[1,"z"]=""
myArray[1,"z","hello world"]="not ok"

The examples below demonstrate the behaviour of various SETSUBTREE commands when applied to this array:

Client: SETSUBTREE myArray
Client: *4
Client: $4
Client: "aa"
Client: $5
Client: 12.34
Client: $4
Client: "ab"
Client: $5
Client: 23.45
Server: +OK

The array myArray will now contain:

myArray="aaa"
myArray[1,"x"]="hello"
myArray[1,"y"]="world"
myArray[1,"y","hello world"]="ok"
myArray[1,"z"]=""
myArray[1,"z","hello world"]="not ok"
myArray["aa"]=12.34
myArray["ab"]=23.45
Client: SETSUBTREE myArray[1,"y"]
Client: *4
Client: $4
Client: "aa"
Client: $5
Client: 12.34
Client: $4
Client: "ab"
Client: $5
Client: 23.45
Server: +OK

The array myArray will now contain:

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","hello world"]="ok"
myArray[1,"z"]=""
myArray[1,"z","hello world"]="not ok"

Arguments:

Argument No Description
1 An array node and subscript(s) into which the incoming array will be merged. This takes the format:
   arrayRef[subscr1,subscr2,..etc]
You may specify no subscripts at all, in which case the array is merged into the the array at its top level,eg:
   arrayRef
Text subscripts must be wrapped in double quote (") characters. Quoting of numeric subscripts is optional.

Request

Multi-line request

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

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

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

To specify a null data value:

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

Response

Single-line response

Server: +OK

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

set xarray("aa")=12.34
set xarray("ab")=23.45
merge ^myArray=xarray
set xarray("aa")=12.34
set xarray("ab")=23.45
merge ^myArray(1,"y")=xarray