|
Caché MultiValue Basic Reference
$ORDER ($O)
|
|
Returns the next local variable or the subscript of a local or global variable.
Synopsis
$ORDER(variable,direction,target)
$O(variable,direction,target)
The value
$ORDER returns depends on the parameters 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,2)) returns the next subscript (3), assuming that ^client(4,1,3) 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.
-
$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).
-
$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 parameter cannot be used with structured system variables (SSVNs) such as
^$ROUTINE.
The following example lists the name and value of the next defined global variable subscript after variable ^fruit(1):
^fruit(1)="apple"
^fruit(2)="orange"
^fruit(3)="pear"
^fruit(4)="banana"
PRINT $ORDER(^fruit(1),1,target)
PRINT target
The following example returns 1, the first subscript in ^X. It sets the naked indicator to the first level.
^x(1,2,3)="1"
^x(2)="2"
PRINT $ORDER(^x(-1))
The following example returns 2, the next subscript on the single subscripted level. (The node you specify in the argument need not exist.) The naked indicator is still set to the first level.
^x(1,2,3)="1"
^x(2)="2"
PRINT $ORDER(^x(1))
The following example returns 2, the first subscript on the two-subscript level. The naked indicator is now set at the second level.
^x(1,2,3)="1"
^x(2)="2"
PRINT $ORDER(^x(1,-1))
The following example uses
$ORDER to list all of the primary subscripts in the ^data global:
^data(1)="a"
^data(3)="c"
^data(7)="g"
! Get first subscript
key=$ORDER(^data(""))
WHILE (key'="") {
PRINT key,!
! Get next subscript
key=$ORDER(^data(key))
}
In the following example, a multidimensional property is used as the
variable value. This example returns the names of defined namespaces to the
target parameter:
obj = "%ResultSet"->%New("%SYS.Namespace:List")
obj->Execute()
obj->Next()
rtn = $ORDER(obj->Data(x),1,val)
crt rtn ! returns level "Nsp"
crt val ! returns namespace name
obj->Next()
rtn = $ORDER(obj->Data(x),1,val)
crt val ! returns next namespace name
obj->Next()
rtn = $ORDER(obj->Data(x),1,val)
crt val ! returns next namespace name
Similar programs return the same information using the
$GET and
$DATA functions.
$ORDER is typically used with loop processing to traverse the nodes in a sparse array. A sparse array is an array that may contain undefined nodes on any given level. Unlike the
$DATA function,
$ORDER simply skips over undefined nodes to return the subscript of the next existing node. For example:
struct=""
FOR {
struct=$ORDER(^client(struct))
QUIT:struct=""
PRINT ^client(struct)
}
The above routine writes the values for all the top-level nodes in the ^client global array.
$ORDER skips over undefined nodes, but not nodes that contain no data. Such nodes include both pointer nodes and terminal nodes. If you use
$ORDER in a loop to feed a command (such as
PRINT) that expects data, you must include a
$DATA check for dataless nodes.
Start and End for a Search
To start a search from the beginning of the current level, specify a null string ("") for the subscript. This technique is required if the level may contain negative as well as positive subscripts. The following example returns the first subscript on the array level:
s=$ORDER(^client(""))
PRINT s
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.
$ORDER Uses Naked Global Reference
Like the
$NAME and
$QUERY functions,
$ORDER can be used with a naked global reference, which is specified without the array name and designates the most recently executed global reference. For example:
var1=^client(4,5)
var2=$ORDER(^(""))
PRINT "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 might return the value 1, indicating ^client(4,1).
$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:
Because
$ORDER starts and fails on the null string, it correctly returns nodes having both negative and positive subscripts.