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 the reference returned as the result of $QUERY evaluation. For example, if reference is ^a(1) and $QUERY returns ^a(2), then target is the value of ^a(2).


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


You can optionally specify a target variable. If you wish to specify a target variable, you must specify a direction argument.

If the value returned by $QUERY evaluation is the null string (""), 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 Operator. (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).


If the $QUERY reference argument is not a global reference, $ZREFERENCE is not changed.

If the $QUERY reference argument is a global reference:

  • If $QUERY returns a global reference, $ZREFERENCE is set to that global reference.

  • If $QUERY returns the empty string:

    • If the $QUERY reference argument is a global reference with subscripts, $ZREFERENCE is set to the reference argument. The reference argument is expanded if it is a naked reference.

    • If the $QUERY reference argument is a global reference without any subscripts:

      If direction is forward then $ZREFERENCE is set to the reference argument global with a single subscript which is the empty string, "". For example, $QUERY(^a,1) returns the empty string and sets $ZREFERENCE to ^a("").

      If direction is backwards then $ZREFERENCE is not changed.

$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()Opens in a new tab method of the %SYSTEM.ProcessOpens in a new tab class. The system-wide default behavior can be established by setting the RefInKindOpens in a new tab property of the Config.MiscellaneousOpens in a new tab class.

For further details on extended global references, see Extended Global References.

See Also

FeedbackOpens in a new tab