Command: QUERY

Purpose: Returns the next stored array reference following the one specified. 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. QUERY only returns the array reference. To obtain the corresponding data, you can either follow the QUERY command with a GET command, or use the QUERYGET command instead, which returns both the reference and associated data.

The hierarchical nature of the persistent arrays means that traversal of the levels of the hierarchy is an important aspect of their use. QUERY is an important and useful command for traversing the contents of an array.

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

Client: QUERY myArray
Server: $14
Server: myArray[1,"x"]

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

Client: QUERY myArray[1,"x"]
Server: $14
Server: myArray[1,"y"]

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: QUERY myArray[1,"y"]
Server: $28
Server: myArray[1,"y","hello world"]

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: QUERY 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: QUERY myArray[1,"a"]
Server: $14
Server: myArray[1,"x"]

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

Two-line response

If an array reference following that specified in the command exists:

Server Line 1: $[no of bytes in the next array reference]
Server Line 2: Array Reference

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

write $query(^myArray)
write $query(^myArray(1,"x"))
write $query(^myArray(1,"y"))
write $query(^myArray(1,"z","hello world"))
write $query(^myArray(1,"a"))