INFS3141 Advanced M/Caché ObjectScript Programming
RMU C&IS – $ORDER function

 

Given an array reference (parent path), the $ORDER function traverses all the subscripts in an array with the same parent path:

^R(17)=5

^R(2,41)=36

^R(17,6)=2

^R(17,8)=62

^R(17,34)=14

Nodes ^R and ^R(2) have no stored value; trying to write them will result in an UNDEFINED error.

 

At the first level of subscripting, the parent path is the root node reference ^R. The nodes (subscripts) traversed (called siblings) by $ORDER(^R("")) (gold-colored box above) would be: 2, 17:

 

Reference in $ORDER(^R(  )):

""
<null string>

2

17

Returns:

2

17

""
<null string>

 

At the second level of subscripting, with the parent path node reference ^R(17), the nodes (subscripts) traversed (called siblings) by $ORDER(^R(17,"")) (green-colored box above) would be: 6, 8, 34:

 

Reference in
$ORDER(^R(17,  ))

""
<null string>

6

8

34

Returns:

6

8

34

""
<null string>

 

Description of what the $ORDER function does:

 

$ORDER –

  • requires a subscripted (local or global) array reference as argument and
  • checks the rightmost subscript only (possibly the only subscript);
  • for the (only or) rightmost subscript reference in the argument, $ORDER
    • returns the next higher value subscript reference in order at the indicated given level in an array (if there is a higher value subscript reference) or
    • returns null string if there is no higher value subscript reference for the particular level in the array;
  • if the rightmost subscript in the $ORDER function argument is null string, then the lowest value subscript in the array at the indicated level is returned (if any subscripts exist at that level), otherwise a null string is immediately returned.

 

Note 1: there does not have to be a subscript reference in the array corresponding to the rightmost subscript reference in the $ORDER argument – the rule given above applies if such a reference is used and either (a) the next higher value subscript reference in order or (b) a null string will be returned.

  • Thus for $ORDER(^R(  )) above, if the rightmost subscript in the argument is 14, 17 will be returned; if the rightmost subscript in the argument is 22 (higher than the highest subscript 17 at that level), null string will be returned.
  • Thus for $ORDER(^R(17,  )) above, if the rightmost subscript in the argument is 20, 34 will be returned; if the rightmost subscript in the argument is 37 (higher than the highest subscript 34 at that level), null string will be returned.

 

Note 2: the $ORDER function is only concerned with subscript values in array references; values stored at the nodes (shown inside the circles in the diagram above) are not significant.

 

Note 3: if you add a second argument of -1 to the $ORDER function, it will traverse the set of subscripts from high to low ↓ (instead of the default sequence from low to high ↑):

$ORDER(^R(17,""),-1) will return 34.

To practice the traversal concept, please use http://nova.umuc.edu/~jarc/idsv/

 

 

Updated: 2010-11-21 $H 61301

Valerie J. H. Powell, R.T.(R), Ph.D.

© 2004 by Robert Morris University