Skip to main content

$QUERY (ObjectScript)

Performs a physical scan of a local or global array.




Argument Description
reference A reference that evaluates to the name (and optionally subscripts) of a public local or global variable. You cannot specify a simple object property as reference; you can specify a multidimensional property as reference with the syntax
direction Optional — The direction to traverse the array. Forward = 1, backwards = -1. The default is forward.
target Optional — Returns the current data value of reference.


$QUERY 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 argument must evaluate to a public variable or a global. $QUERY cannot scan a private variable.

This argument can be a multidimensional object property. It cannot be a non-multidimensional object property. Attempting to use $QUERY on a non-multidimensional object property results in an <OBJECT DISPATCH> error.

The returned global reference can be at the same level, a lower level, or a higher level as the level specified in the reference argument. 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, an argument 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 argument is undefined, the target value remains unchanged.

The ZBREAK command cannot specify the target argument 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=""
  SET queryary=$QUERY(@ary@(""))
  WRITE !,@queryary
  FOR   {
    SET queryary=$QUERY(@queryary) 
        WRITE !,@queryary
  WRITE !,"Finished."

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 ObjectScript. (Like $ORDER, $QUERY 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 loop, $QUERY 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.

No $DATA 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:

   SET exam=$QUERY(^client(4,1,2))

Based on this example, $QUERY might return any of the following values, assuming a three-level array:

Value Returned by the $QUERY Function If...
^client(4,1,3) If ^client(4,1,3) exists and contains data.
^client(4,2) If ^client(4,1,3) does not exist or does not contain data and if ^client(4,2) does exist and contains data.
^client(5) 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

$QUERY 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.

$QUERY 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.

Like $ORDER, $QUERY 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 and $ORDER functions, $QUERY 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:

   SET a=^client(1)
   SET x=2
   SET z=$QUERY(^(x))

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

You can control whether $QUERY returns global references in Extended Global Reference form on a per-process basis using the RefInKind() method of the %SYSTEM.Process class. The system-wide default behavior can be established by setting the RefInKind property of the Config.Miscellaneous class.

For further details on extended global references, see the Global Structure chapter in Using Globals.

See Also