Command: QUERYGET

Purpose: Returns the next stored array reference following the one specified, along with its associated data. The sequence in which records are returned is determined by the natural collating sequence in which GT.M and Caché save subscript values (both databases apply the same rules). By definition, the reference returned will have a data value associated with it.

The hierarchical nature of the persistent arrays means that traversal of the levels of the hierarchy is an important aspect of their use. QUERYGET is an important and useful command for traversing the contents of an array. As its name implies, the QUERYGET command is the equivalent of a QUERY command followed by a GET that uses the array reference returned by the QUERY.

The use of the QUERYGET 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 QUERYGET commands when applied to this array:

Client: QUERYGET myArray
Server: *2
Server: $14
Server: myArray[1,"x"]
Server: $5
Server: hello

This is because we're wanting to find the first stored subscripted reference in myArray which is myArray[1,"x"].

Client: QUERYGET myArray[1,"x"]
Server: *2
Server: $14
Server: myArray[1,"y"]
Server: $5
Server: world

This is because we're wanting to find the next stored subscripted reference in myArray which follows myArray[1,"x"], so myArray[1,"y"] is returned.

Client: QUERYGET myArray[1,"y"]
Server: *2
Server: $28
Server: myArray[1,"y","hello world"]
Server: $2
Server: ok

This is because we're wanting to find the next stored subscripted reference in myArray which follows myArray[1,"y"], so myArray[1,"y","hello world"] is returned.

Client: QUERYGET myArray[1,"z","hello world"]
Server: $-1

This is because we're wanting to find the next stored subscripted reference in myArray which follows myArray[1,"z","hello world"]. However, myArray[1,"z","hello world"] is the last stored array reference, so a null response is returned, denoted by $-1.

Note that the array reference you use in the QUERY command does not, itself, have to physically exist. The next reference that exists in collating sequence following the reference you specify will be returned, eg even though myArray[1,"a"] does not actually exist, we can still do the following:

Client: QUERYGET myArray[1,"a"]
Server: *2
Server: $14
Server: myArray[1,"x"]
Server: $5
Server: hello

Arguments:

Argument No Description
1 An array node and subscript(s). This takes the format:
   arrayRef[subscr1,subscr2,..etc]
You may specify no subscripts at all, in which case the first subscripted reference will be returned,eg:
   arrayRef
Otherwise the next saved subscripted reference following the one specified will be returned, based on the natural collating sequence used by GT.M and Caché.
Note that subscripts can be numeric or text. Text subscripts must be wrapped in double quote (") characters. Quoting of numeric subscripts is optional.

Response

Multi-line response

Server Line 1: *2
Server Line 2: $[length of array reference in bytes]
Server Line 3: Array reference
Server Line 4: $[length of data in bytes]
Server Line 5: Data

If no following array reference exists:

Server: $-1

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

set ref=$query(^myArray) write ref,!,@ref
set ref=$query(^myArray(1,"x")) write ref,!,@ef
set ref=$query(^myArray(1,"y")) write ref,!,@ef
set ref=$query(^myArray(1,"z","hello world")) write ref,!,@ef
set ref=$query(^myArray(1,"a")) write ref,!,@ef