Skip to main content

$QUERY (ObjectScript)

Performs a physical scan of a local or global array.

Synopsis

$QUERY(reference,direction,target)
$Q(reference,direction,target)

Arguments

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 obj.property.
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).

Description

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

Arguments

reference

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.

direction

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.

target

You can optionally specify a target variable. If you do so, 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.

Example

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.

 Read !,"Array name: ",queryary
 Quit:queryary=""
 While 1 { 
    Set queryary=$QUERY(@queryary) 
    Quit:queryary="" 
    Write !,queryary, " = ", @queryary
 }
 Write !!,"Finished."

The following code defines an array for demonstration purposes:

 Set test = "name"
 Set test(1) = "1"
 Set test(1,1) = "1,1"
 Set test(1,2) = "1,2"
 Set test(1,1,1) = "1,1,1"
 Set test(2) = "2"
 Set test(2,2,2,2,2,2) = "2,2,2,2,2,2"

Then the following ObjectScript shell session shows the above routine processing this array:

SAMPLES>d ^querysample
 
Array name: test
test(1) = 1
test(1,1) = 1,1
test(1,1,1) = 1,1,1
test(1,2) = 1,2
test(2) = 2
test(2,2,2,2,2,2) = 2,2,2,2,2,2
 
Finished.

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

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