$ORDER ($O)

Returns the next local variable or the subscript of a local or global variable.

Synopsis

$ORDER(variable,direction,target)
$O(variable,direction,target)

Parameters

variable	Either a local variable or a subscripted local, global, or process-private global variable. If an array, the subscript is required. You cannot specify just the array name. variable may be specified as a variable or an object property with the syntax obj->property.
direction	Optional — The subscript order in which to traverse the target array. An expression that resolves to either: 1 = ascending subscript order (the default) or -1 = descending subscript order. For unsubscripted local variables, 1 (the default) is the only permitted value.
target	Optional — Returns the current data value of the next or previous node of variable. Whether it is the next or previous depends on the setting of direction. You must specify a direction value to specify a target. For unsubscripted local variables, direction must be set to 1. If variable is undefined, the target value remains unchanged. target may be specified as a variable or an object property with the syntax obj->property. The target parameter cannot be used with structured system variables (SSVNs) such as ^$ROUTINE.

Description

The value $ORDER returns depends on the parameters used.

$ORDER(variable) returns the number of the next defined subscript if variable is a subscripted variable. The returned subscript is at the same level as that specified for the variable. For example, $ORDER(^client(4,1,2)) returns the next subscript (3), assuming that ^client(4,1,3) exists.
$ORDER(variable) returns the name of the next defined local variable in alphabetic collating sequence, if variable is an unsubscripted local variable. For example, $ORDER would return the following defined local variables in the following sequence: a, a0a, a1, a1a, aa, b, bb, c.
$ORDER(variable,direction) returns either the next or the previous subscript for the variable. You can specify direction as 1 (next, the default) or –1 (previous).
For unsubscripted local variables, $ORDER returns variables in direction 1 (next) order only; you cannot specify a direction of –1 (previous).
$ORDER(variable,direction,target) returns the subscript for the variable, and sets target to its current data value. This can be either the next or the previous subscript for a subscripted variable, depending on the direction setting. For an unsubscripted local variable, direction must be set to 1 to return the current data value to target. The target parameter cannot be used with structured system variables (SSVNs) such as ^$ROUTINE.

Examples

The following example lists the name and value of the next defined global variable subscript after variable ^fruit(1):

^fruit(1)="apple"
^fruit(2)="orange"
^fruit(3)="pear"
^fruit(4)="banana"
PRINT $ORDER(^fruit(1),1,target)
PRINT target

The following example returns 1, the first subscript in ^X. It sets the naked indicator to the first level.

^x(1,2,3)="1"
^x(2)="2"
PRINT $ORDER(^x(-1))

The following example returns 2, the next subscript on the single subscripted level. (The node you specify in the argument need not exist.) The naked indicator is still set to the first level.

^x(1,2,3)="1"
^x(2)="2"
PRINT $ORDER(^x(1))

The following example returns 2, the first subscript on the two-subscript level. The naked indicator is now set at the second level.

^x(1,2,3)="1"
^x(2)="2"
PRINT $ORDER(^x(1,-1))

The following example uses $ORDER to list all of the primary subscripts in the ^data global:

^data(1)="a"
^data(3)="c"
^data(7)="g"
   ! Get first subscript
key=$ORDER(^data(""))
   WHILE (key'="") {
   PRINT key,!
     ! Get next subscript 
   key=$ORDER(^data(key))
   }

In the following example, a multidimensional property is used as the variable value. This example returns the names of defined namespaces to the target parameter:

obj = "%ResultSet"->%New("%SYS.Namespace:List")
obj->Execute()
obj->Next()
rtn = $ORDER(obj->Data(x),1,val)
crt rtn        ! returns level "Nsp"
crt val        ! returns namespace name
obj->Next()
rtn = $ORDER(obj->Data(x),1,val)
crt val        ! returns next namespace name
obj->Next()
rtn = $ORDER(obj->Data(x),1,val)
crt val        ! returns next namespace name

Similar programs return the same information using the $GET and $DATA functions.

Notes

Uses for $ORDER

$ORDER is typically used with loop processing to traverse the nodes in a sparse array. A sparse array is an array that may contain undefined nodes on any given level. Unlike the $DATA function, $ORDER simply skips over undefined nodes to return the subscript of the next existing node. For example:

struct=""
   FOR  {
     struct=$ORDER(^client(struct)) 
     QUIT:struct=""
  PRINT ^client(struct)
   }

The above routine writes the values for all the top-level nodes in the ^client global array.

$ORDER skips over undefined nodes, but not nodes that contain no data. Such nodes include both pointer nodes and terminal nodes. If you use $ORDER in a loop to feed a command (such as PRINT) that expects data, you must include a $DATA check for dataless nodes.

Start and End for a Search

To start a search from the beginning of the current level, specify a null string ("") for the subscript. This technique is required if the level may contain negative as well as positive subscripts. The following example returns the first subscript on the array level:

s=$ORDER(^client(""))
PRINT s

When $ORDER reaches the end of the subscripts for the given level, it returns a null string (""). If you use $ORDER in a loop, your code should always include a test for this value.

$ORDER Uses Naked Global Reference

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

var1=^client(4,5)
var2=$ORDER(^(""))
PRINT "var1=",var1,"var2=",var2

The first SET command establishes the current global reference, including the subscript level for the reference. The $ORDER function uses a naked global reference to return the first subscript for this level. For example, it might return the value 1, indicating ^client(4,1).

For more details, see Naked Global Reference in Using Caché Globals.

$ORDER and $NEXT

$ORDER is similar to $NEXT. Both functions return the subscripts of the next sibling in collating order to the specified node. However, $ORDER and $NEXT have different start and failure codes, as follows:

	$NEXT	$ORDER
Starting point	-1	Null string
Failure code	-1	Null String

Because $ORDER starts and fails on the null string, it correctly returns nodes having both negative and positive subscripts.