Caché MultiValue Basic Reference
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   

Returns the next local variable or the subscript of a local or global variable.
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.
The value $ORDER returns depends on the parameters used.
The following example lists the name and value of the next defined global variable subscript after variable ^fruit(1):
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.
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.
The following example returns 2, the first subscript on the two-subscript level. The naked indicator is now set at the second level.
PRINT $ORDER(^x(1,-1))
The following example uses $ORDER to list all of the primary subscripts in the ^data global:
   ! Get first subscript
   WHILE (key'="") {
   PRINT key,!
     ! Get next subscript 
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")
rtn = $ORDER(obj->Data(x),1,val)
crt rtn        ! returns level "Nsp"
crt val        ! returns namespace name
rtn = $ORDER(obj->Data(x),1,val)
crt val        ! returns next namespace name
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.
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:
   FOR  {
  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:
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:
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 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:
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.
See Also