Performs a physical scan of a local or global array.
||A reference that evaluates to the name (and optionally subscripts) of a public local or global variable.
||Optional The direction (forwards or backwards) to traverse the array.
||Optional Returns the current data value of the local or global variable specified in reference.
performs a physical scan of a public local or global array; it returns the full reference, name and subscripts, of the defined node next in sequence to the specified array node. If no such node exists, $QUERY
returns the null string.
This parameter must evaluate to a public variable or a global. $QUERY
cannot scan a private variable.
The returned global reference can be at the same level, a lower level, or a higher level as the level specified in the reference
parameter. If you specify reference
without specifying subscripts, $QUERY
returns the first defined node in the array.
If no direction
is specified, the default direction is forward. If you wish to specify a direction, a parameter value of 1 will traverse the array forward, a value of -1 will traverse the array backward.
If you wish to specify a target
, you must specify a direction
. If the variable identified in the reference
parameter is undefined, the target
value remains unchanged.
command cannot specify the target
parameter as a watchpoint.
This example presents a generalized routine for outputting the data values for all the nodes in a user-specified array. It can accommodate arrays with any number of levels. The code performs the same operation as the code shown in the example under the $ORDER
function. Instead of requiring 23 lines, however, it requires only six and is not restricted as to the number of levels it can handle.
Start READ !,"Array name: ",ary QUIT:ary=""
The first SET
command uses $QUERY
with subscript indirection to initialize the global reference to the first existing node that contains data. For more information, refer to Indirection
in Using Caché ObjectScript
. (Like $ORDER
accepts a null string to designate the first subscript in an array.) The first WRITE
command outputs the value of the first node found. If it were omitted, the first node would be skipped.
In the FOR
is used to retrieve the next node and update the global reference, whose contents are then output by the WRITE
command. The postconditional QUIT
terminates the loop when it finds a null string (""), indicating that $QUERY
has reached the end of the array.
tests are required, unless you wish to distinguish between pointer nodes ($DATA=11) and terminal nodes ($DATA=1).
Using $QUERY to Traverse an Array
Used repetitively, $QUERY
can traverse an entire array in left-to-right, top-to-bottom fashion, returning the entire sequence of defined nodes. $QUERY
can start at the point determined by the subscript specified for reference
. It proceeds along both the horizontal and vertical axes. For example:
Based on this example, $QUERY
might return any of the following values, assuming a three-level array:
||Returned by the $QUERY Function If...
||If ^client(4,1,3) exists and contains data.
||If ^client(4,1,3) does not exist or does not contain data and if ^client(4,2) does exist and contains data.
||If ^client(4,1,3) and ^client(4,2) do not exist or do not contain data and if ^client(5) does exist and contains data.
|null string ("")
||If none of the previous global references exist or contain data; $QUERY has reached the end of the array.
With a direction value of -1, $QUERY
can traverse an entire array in reverse order in right-to-left, bottom-to-top fashion.
$QUERY Compared to $ORDER
differs from the $ORDER
function in that $QUERY
returns a full global reference, while $ORDER
returns only the subscript of the next node. $ORDER
proceeds along only the horizontal axis, across nodes at one level.
also differs from $ORDER
in that it selects only those existing nodes that contain data. $ORDER
selects existing nodes, regardless of whether or not they contain data. Where $ORDER
performs an implicit test for existence ($DATA'=0), $QUERY
performs an implicit test for both existence and data ($DATA'=0 and $DATA'=10). Note, however, that $QUERY
does not distinguish between pointer nodes ($DATA=11) and terminal nodes ($DATA=1) that contain data. To make this distinction, you must include appropriate $DATA
tests in your code.
is typically used with loop processing to traverse the nodes in an array that doesn’t use consecutive integer subscripts. $QUERY
simply returns the global reference of the next node with a value. $QUERY
provides very compact code for accessing global arrays.
Like the $NAME
can be used with a naked global reference
, which is specified without the array name and designates the most recently executed global reference. For example:
The first SET
command establishes the current global reference, including the level for the reference. The second SET
command sets up a variable for use with subscripts. The $QUERY
function uses a naked global reference
to return the full global reference for the next node following ^client(2). For example, the returned value might be ^client(2,1) or ^client(3).
$QUERY and Extended Global References