$Order()

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])
[Note] Note

Name-level $ORDER() always returns an empty string when used with extended references.

Examples of $ORDER()

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.