Caché ObjectScript Reference
$ORDER
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   
Search:    

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 A subscripted local, process-private global, or global variable. If an array, the subscript is required. You cannot specify just the array name. You can specify an unsubscripted local variable using indirection (see example below). You cannot specify a simple object property reference as variable; you can specify a multidimensional property reference as variable with the syntax obj.property.
direction Optional — The subscript order in which to traverse the target array. Values for subscripted variables can be: 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. The target parameter cannot be used with structured system variables (SSVNs) such as ^$ROUTINE.
Description
$ORDER is primarily used to loop through subscripted variables at a specified subscript level from a specified starting point. It returns sequential variables in collation sequence. It allows for gaps in the subscript sequence.
The value $ORDER returns depends on the parameters used.
First Subscript Returned
You can either start a $ORDER loop with the variable following a specified variable, or with the first variable:
The following example returns both negative and positive first-level subscripts in ascending numeric sequence.
    SET mydata(1)="a",mydata(-3)="C",mydata(5)="e",mydata(-5)="E"
   // Get first subscript
   SET key=$ORDER(mydata(""))
   WHILE (key'="") {
     WRITE key,!
     // Get next subscript 
     SET key = $ORDER(mydata(key))
   }
 
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.
You can use $ORDER to return a limited subset of the defined local variables. You can use argumentless WRITE to display all defined local variables.
Examples
The examples shown here return local variables. $ORDER can also return subscripted global variables and subscripted process-private global variables.
The following example uses $ORDER in a WHILE loop to return all of the first-level subscripts in the mydata(n) global:
    SET mydata(1)="a",mydata(3)="c",mydata(7)="g"
   // Get first subscript
   SET key=$ORDER(mydata(""))
   WHILE (key'="") {
     WRITE key,!
     // Get next subscript 
     SET key = $ORDER(mydata(key))
   }
 
The following example uses $ORDER in a WHILE loop to return all of the second-level subscripts in the mydata(1,n) global. Note that the first-level and third-level subscripts are ignored. This example returns both the subscript numbers and the corresponding variable values:
   SET mydata(1,1)="a",mydata(1,3)="c",mydata(1,3,1)="lcase",mydata(1)="A",mydata(1,7)="g"
   SET key=$ORDER(mydata(1,""),1,target)
   WHILE (key'="") {
     WRITE key," = ",target,!
     // Get next subscript 
     SET key = $ORDER(mydata(1,key),1,target)
   }
 
In the following example, a multidimensional property is used as the variable value. This example returns the names of all defined namespaces to the target parameter:
  SET obj = ##class(%ResultSet).%New("%SYS.Namespace:List")
  DO obj.Execute()
    SET target="blank", x=""
  WHILE target'="" {
     DO obj.Next()
     SET rval=$ORDER(obj.Data(x),1,target)
     IF rval="Nsp",target'="" {
     WRITE "Namespace: ",target,! }
     ELSE {WRITE !,"Done!"  RETURN}
   }
 
The following example uses $ORDER in a WHILE loop to return unsubscripted local variables. Local variables are returned in collation sequence. This example returns both the local variable names and their values. Note that the @ indirection operator must be used when looping through unsubscripted local variables. This example starts with the next local variable in collation sequence after b (in this case, bminus). It then loops through all defined local variables that follow it in collation sequence. To avoid listing the variables foo and target, these variables are defined as process-private globals, rather than local variables:
   SET a="great",b="good",bminus="pretty good",c="fair",d="poor",f="failure"
   SET ^||foo="b"
   SET ^||foo=$ORDER(@^||foo,1,^||target)
   WHILE ^||foo '= "" {
   WRITE ^||foo," = ",^||target,!
   SET ^||foo=$ORDER(@^||foo,1,^||target)
       }
Notes
Uses for $ORDER
$ORDER is typically used with loop processing to traverse the nodes in an array that doesn’t use consecutive integer subscripts. $ORDER simply returns the subscript of the next existing node. For example:
   SET struct=""
   FOR  {
     SET struct=$ORDER(^client(struct)) 
     QUIT:struct=""
     WRITE !,^client(struct)
   }
The above routine writes the values for all the top-level nodes in the ^client global array.
$ORDER returns subscripts of existing nodes, but not all nodes contain a value. If you use $ORDER in a loop to feed a command (such as WRITE) that expects data, you must include a $DATA check for valueless nodes. For example, you could specify the WRITE command in the previous example with a postconditional test, as follows:
   WRITE:($DATA(^client(struct))#10) !,^client(struct)
This test covers the case of both a valueless pointer node and a valueless terminal node. If your code becomes too cumbersome for a simple FOR loop, you can relegate part of it to a block-structured DO.
Global References
If a variable is global variable, it can include an extended global reference, specifying a global in a different namespace. If you specify a nonexistent namespace, Caché issues a <NAMESPACE> error. If you specify a namespace for which you do not have privileges, Caché issues a <PROTECT> error, followed by the global name and database path, such as the following: <PROTECT> ^myglobal(1),c:\intersystems\cache\mgr\.
If variable is a subscripted global variable, it can be a naked global reference. A naked global reference is specified without the array name and designates the most recently executed global reference. For example:
   SET var1=^client(4,5)
   SET var2=$ORDER(^(""))
   WRITE "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 would return the value 1, indicating ^client(4,1), if that subscripted global is defined. If ^client(4,1) is not defined, it would return the value 2, indicating ^client(4,2) if that subscripted global is defined, and so forth.
All three parameters of $ORDER can take a naked global reference, or specify the global reference. However, if direction specifies an explicit global reference, subsequent naked global references do not use the direction global reference. They continue to use the prior established global reference, as shown in the following example:
   SET ^client(4,3)="Jones"
   SET ^client(4,5)="Smith"
   SET ^dir(1)=-1
   SET rtn=$ORDER(^client(4,5),-1)
   WRITE $ZREFERENCE,!  
      /* naked global ref is ^client(4,5) */
   SET rtn=$ORDER(^client(4,5),^dir(1))
   WRITE $ZREFERENCE,!
      /* NOTE: naked global ref is ^client(4,5) */
   SET rtn=$ORDER(^client(4,5),^dir(1),^(1))
   WRITE $ZREFERENCE
      /* NOTE: naked global ref is ^client(4,1) */
   WRITE ^client(4,1),!
   SET rtn=$ORDER(^client(4,5),^dir(1),^targ(1))
   WRITE $ZREFERENCE
      /* naked global ref is ^targ(1) */
   WRITE ^targ(1),!
   SET ^rtn(1)=$ORDER(^client(4,5),^dir(1),^targ(2))
   WRITE $ZREFERENCE
      /* naked global ref is ^rtn(1) */
   WRITE ^targ(2)
For more details, see Naked Global Reference in Using Caché Globals.
$ORDER and $DOUBLE Subscripts
$DOUBLE floating point numbers can be used as subscript identifiers. However, when used as a subscript identifier, the $DOUBLE number is converted to a string. When $ORDER returns a subscript of this type, it returns it as a numeric string, not a $DOUBLE floating point number.
$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 finishes on the null string, it correctly returns nodes having both negative and positive subscripts.
See Also