Returns the subscript of the next or prior local or global variable name in collation sequence within the array level specified by its first argument. In doing so, it moves in the direction specified by the second argument. In GT.M, when $ORDER() has an unsubscripted argument, it returns the next or previous unsubscripted local or global variable name in collating sequence.
The format for the $ORDER function is:
$O[RDER](glvn[,expr])
The subscripted global or local variable name specifies the node from which $ORDER() searches for the next or previous node that has data and/or descendants. The number of subscripts contained in the argument implicitly defines the array level.
The optional expression (second argument) specifies the direction for the $ORDER(); 1 specifies forward operation and -1 specifies reverse operation. Any other values for the expression will cause an error.
GT.M extends the M standard to allow unsubscripted names. In this case, $ORDER() returns the next or previous unsubscripted name.
If $ORDER() finds no node (or name) at the specified level after (or before) the specified global or local variable, it returns an empty string (" ").
-
If the last subscript in the subscripted global or local variable name is null and the corresponding subscripted global or local variable has a matching null subscript, $ORDER() returns the next node after that with the null subscript at the specified level.
If the last subscript in the subscripted global or local variable name is null and the corresponding subscripted global or local variable has no matching null subscript , $ORDER() returns first node at the specified level. If the last subscript in the subscripted global or local variable name is null and second argument is -1, $ORDER() always returns the last node at the specified level regardless of the existence a null subscript at the specified level. However when a global or local variable level includes a null subscript and $ORDER(glvn,-1) returns an empty string result, users must test separately for the existence of the node with the null subscript.
$ORDER() can be used as a tool for retrieving data from M sparse arrays in an ordered fashion, independent of the order in which it was entered. In M, routines generally sort by SETting data into an array with appropriate subscripts and then retrieving the information with $ORDER().
$ORDER() returns subscripts, not data values, and does not discriminate between nodes that have data values and nodes that have descendants. Once $ORDER() provides the subscript, the routine must use the subscript to access the data value, if appropriate. Using $ORDER() maintains the naked reference indicator, even if $ORDER() returns a null.
GT.M optionally permits the use of null subscripts. This feature is enabled via the VIEW command for local variables and a REGION qualifier in GDE for global variables. When an application uses null subscripts, they are "invisible" in a $ORDER() loop so the application must test for them as a special case, perhaps using $DATA().
$Order() returns local array subscripts with values that are numeric, but non-canonical (over 18 digit), as strings.
![[Note]](images/note.jpg) |
Note |
|---|---|
Name-level $ORDER() always returns an empty string when used with extended references. |
Example:
GTM>zwrite
lcl(1)=3
lcl("x")=4
GTM>write $order(lcl(""))
1
This example returns the first node, that is 1, because the specified last subscript of the argument is null and lcl has no null subscript.
Example:
GTM>write $order(lcl(1)) x
This example returns the first node after lcl(1) that is x because lcl has no null subscript.
Example:
GTM>write $order(lcl(""),-1)
x
This example returns the last node that is, x, because the last subscript of the first argument is null and second argument is -1.
GTM>set lcl("")=2
GTM>zwrite
lcl("")=2
lcl(1)=3
lcl("x")=4
GTM>write $order(lcl(""))
1
This example returns the second node at the specified level because the null subscript at the end of the argument is ambiguous (does it specify starting at the beginning or starting at the real node with the null subscript?) and returning the subscript of the first node (an empty string) would tend to create an endless loop.
Example:
GTM>write $order(lcl(""),-1)
x
GTM>write $order(lcl("x"),-1)
1
Example:
GTM>kill set (a(1),a(2000),a("CAT"),a("cat"),a("ALF"),a(12))=1
GTM>set x="" for set x=$order(a(x)) quit:x="" write !,x
1
12
2000
ALF
CAT
cat
GTM>kill a("CAT") set a(5,10)="woolworths",a("cat")="last"
GTM>set x="" for set x=$order(a(x),-1) quit:x="" write !,x
cat
ALF
2000
12
5
1
GTM>
This example uses a $ORDER() loop to display all the subscripts at the first level of local variable a, make some changes in a, and then display all the subscripts in reverse order. Notice that $ORDER() returns only the existing subscripts in the sparse array and returns them in M collation sequence, regardless of the order in which they were entered. Also, $ORDER() does not differentiate between node A(5), which has only descendants (no data value), and the other nodes, which have data values.
Example:
GTM>kill set (%(1),tiva(2),A(3),tiv(4),Q(5),%a(6))="" GTM>set x="%" GTM>write:$data(@x) !,x for set x=$order(@x) quit:x="" write !,x % %a A Q tiv tiva x GTM>set $piece(x,"z",32)="" GTM>write:$data(@x) !,x for set x=$order(@x,-1) quit:x="" write !,x x tiva tiv Q A %a % GTM>
This example uses $ORDER() to display the current local variable names in both forward and reverse order. Notice that the first ([^]%) and last ([^]zzzzzzzz) names require handling as special cases and require a $DATA() function.
Example:
set acct="",cntt="" for fet acct=$order(^acct(acct)) quit:acct="" do . for set cntt=$order(^acct(acct,cntt)) do WORK quit
This uses two nested $ORDER() loops to cycle through the ^acct global array and perform some action for each second level node.