Skip to main content

$ORDER (ObjectScript)

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

Synopsis

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

Arguments

Argument Description
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 argument 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 arguments 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,6)) returns the next third-level subscript. That would be 7, if the variable ^client(4,1,7) 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. (See example below).

  • $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); attempting to do so results in a <FUNCTION> error.

  • $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 argument cannot be used with structured system variables (SSVNs) such as ^$ROUTINE. The ZBREAK command cannot specify the target argument as a watchpoint.

First Subscript Returned

You can either start a $ORDER loop with the variable following a specified variable, or with the first variable:

  • Start at specified point: SET key=$ORDER(^mydata(99)) returns the next higher subscript after 99 — subscript 100, if it exists. Note that the node you specify in the argument (here subscript 99) need not exist. To return all positive subscripts you can specify SET key=$ORDER(^mydata(-1)). To return all negative subscripts you can specify SET key=$ORDER(^mydata(0),-1).

  • Start at beginning: SET key=$ORDER(^mydata("")) returns the first subscripted variable in collation sequence. This technique is required if the level may contain negative as well as positive subscripts.

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.

The $ORDER start code and failure code values are both the null string (""). Because $ORDER starts and finishes on the null string, it correctly returns nodes having both negative and positive subscripts.

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)
   }

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)
       }

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 a global variable, it can be an extended global reference, specifying a global in a different namespace. If you specify a nonexistent namespace, InterSystems IRIS® data platform issues a <NAMESPACE> error. If you specify a namespace for which you do not have privileges, InterSystems IRIS issues a <PROTECT> error, followed by the global name and database path, such as the following: <PROTECT> ^myglobal(1),c:\intersystems\iris\mgr\. If the global variable has subscript mapping to a namespace for which the user does not have Read permission, the <PROTECT> error information shows the original global reference because you cannot see a subscript in a namespace for which you do not have privileges. However, the <PROTECT> error database path shows the protected database, not the original database.

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 arguments 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,3) */
   SET rtn=$ORDER(^client(4,5),^dir(1))
   WRITE $ZREFERENCE,!
      /* NOTE: naked global ref is ^client(4,3) */
   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 Checking the Most Recent Global Reference.

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

See Also

FeedbackOpens in a new tab