$QUERY (ObjectScript)

Synopsis

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

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

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:

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

• $DATA function

• $NAME function

• $ORDER function

• $QLENGTH function

• $QSUBSCRIPT function

• $ZREFERENCE special variable