第四十七章 Caché 函数大全 $ORDER 函数

返回下一个局部变量或局部或全局变量的下标。

大纲

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

参数

• variable 下标的局部，私有进程或全局变量。如果是数组，则需要下标。不能仅指定数组名称。可以使用间接指定未下标的局部变量。不能将简单的对象属性引用指定为变量。可以使用语法obj.property将多维属性引用指定为变量。
• direction 可选-下标顺序，遍历目标数组。下标变量的值可以是：1 =下标升序（默认）或–1 =下标降序。对于未下标的局部变量，1（默认值）是唯一允许的值。
• target 可选-返回变量的下一个或上一个节点的当前数据值。下一个还是上一个取决于方向的设置。必须指定方向值才能指定目标。对于未下标的局部变量，必须将方向设置为1。如果未定义变量，则目标值保持不变。目标参数不能与诸如^$ROUTINE之类的结构化系统变量（SSVN）一起使用。

描述

$ORDER主要用于从指定起点在指定下标级别循环遍历下标变量。它按整理顺序返回顺序变量。它允许下标序列中有间隔。

$ORDER返回的值取决于所使用的参数。

• 如果变量是下标变量，则$ORDER（variable）返回下一个定义的下标的编号。返回的下标与为变量指定的下标处于同一级别。例如，$ORDER（^client（4,1,6））返回下一个第三级下标。如果变量^client（4,1,7）存在，则为7。
• 如果变量是未下标的局部变量，则$ORDER（variable）返回按字母顺序排列的下一个定义的局部变量的名称。例如，$ORDER将按以下顺序返回以下定义的局部变量：a，a0a，a1，a1a，aa，b，bb，c。
• $ORDER（variable，direction）返回变量的下一个或上一个下标。可以将方向指定为1（下一个，默认值）或–1（上一个）。
• 对于未下标的局部变量，$ORDER仅按方向1（下一个）顺序返回变量。不能将方向指定为-1（先前）；尝试这样做会导致 <FUNCTION>错误。
• $ORDER（variable，direction，target）返回变量的下标，并将target设置为其当前数据值。下标变量可以是下一个或上一个下标，具体取决于方向设置。对于未下标的局部变量，必须将direction设置为1才能将当前数据值返回给目标。目标参数不能与诸如^$ROUTINE之类的结构化系统变量（SSVN）一起使用。 ZBREAK命令无法将目标参数指定为观察点。

第一个下标返回

可以使用指定变量后的变量或第一个变量启动$ORDER循环：

• 从指定点开始 SET key=$ORDER(^mydata(99))返回99 －下标100之后的下一个更高的下标（如果存在）。请注意，在参数（此处为下标99）中指定的节点不必存在。要返回所有正下标，可以指定SET key=$ORDER(^mydata(-1))。要返回所有负下标，可以指定SET key=$ORDER(^mydata(0),-1)。
• 从头开始：SET key=$ORDER(^mydata(""))返回排序规则序列中的第一个下标变量。如果水平可能包含负下标和正下标，则需要此技术。

下面的示例按升序返回负一级正标和负一级正标。

/// d ##class(PHA.TEST.Function).ORDER()
ClassMethod ORDER()
{
    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))
    }
}

DHC-APP>d ##class(PHA.TEST.Function).ORDER()
-5
-3
1
5
 

当$ORDER到达给定级别的下标末尾时，它将返回一个空字符串（“”）。如果在循环中使用$ORDER，则代码应始终包含对此值的测试。

可以使用$ORDER返回定义的局部变量的有限子集。可以使用无参数WRITE显示所有定义的局部变量。

示例

此处显示的示例返回局部变量。 $ORDER还可以返回下标的全局变量和下标的进程专用全局变量。

以下示例在WHILE循环中使用$ORDER返回mydata（n）全局变量中的所有第一级下标：

/// d ##class(PHA.TEST.Function).ORDER1()
ClassMethod ORDER1()
{
    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))
    }
}

DHC-APP>d ##class(PHA.TEST.Function).ORDER1()
1
3
7

以下示例在WHILE循环中使用$ORDER返回mydata（1，n）全局变量中的所有第二级下标。请注意，将忽略第一级和第三级下标。本示例同时返回下标编号和相应的变量值：

/// d ##class(PHA.TEST.Function).ORDER2()
ClassMethod ORDER2()
{
    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)
    }
}

DHC-APP> d ##class(PHA.TEST.Function).ORDER2()
1 = a
3 = c
7 = g

在以下示例中，多维属性用作变量值。本示例将所有定义的名称空间的名称返回给目标参数：

/// d ##class(PHA.TEST.Function).ORDER3()
ClassMethod ORDER3()
{
    SET obj = ##class(%ResultSet).%New("%SYS.Namespace:List")
    DO obj.Execute()
    SET target="blank", x=""
    WHILE target'="" {
        DO obj.Next()
        SET rval=$ORDER(obj.Data(x),1,target)
        IF rval="Nsp",target'="" {
            WRITE "Namespace: ",target,! 
        } ELSE {
            WRITE !,"Done!"  RETURN
        }
    }
}

DHC-APP>d ##class(PHA.TEST.Function).ORDER3()
Namespace: %SYS
Namespace: DHC-APP
Namespace: DHC-CHSSWEB
Namespace: DHC-CSM
Namespace: DHC-DATA
Namespace: DHC-DWR
Namespace: DHC-EKG
Namespace: DHC-HEIS
Namespace: DHC-HR
Namespace: DHC-LISDATA
Namespace: DHC-LISSRC
Namespace: DHC-MEDSRC
Namespace: DHC-MRQ
Namespace: DOCBOOK
Namespace: FDBMS
Namespace: PACS
Namespace: PIS
Namespace: RIS
Namespace: SAMPLES
Namespace: USER
 
Done!

下面的示例在WHILE循环中使用$ORDER返回未下标的局部变量。局部变量按整理顺序返回。本示例同时返回本地变量名称及其值。请注意，在遍历未下标的局部变量时，必须使用@间接运算符。本示例以排序规则序列中b之后的下一个局部变量（在本例中为bminus）开始。然后，它按排序顺序遍历所有在其后定义的局部变量。为了避免列出变量foo和target，这些变量被定义为进程专用全局变量，而不是局部变量：

/// d ##class(PHA.TEST.Function).ORDER4()
ClassMethod ORDER4()
{
    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)
    }
}

注意

使用$ORDER

$ORDER通常与循环处理一起使用，以遍历不使用连续整数下标的数组中的节点。 $ORDER仅返回下一个现有节点的下标。例如：

/// d ##class(PHA.TEST.Function).ORDER5()
ClassMethod ORDER5()
{
    SET struct=""
    FOR  {
        SET struct=$ORDER(^client(struct)) 
        QUIT:struct=""
        WRITE !,$d(^client(struct))
    }
}

DHC-APP>d ##class(PHA.TEST.Function).ORDER5()
 
10
11
11
10

上面的例程为^client全局数组中的所有顶级节点写入值。

$ORDER返回现有节点的下标，但并非所有节点都包含值。如果在循环中使用$ORDER来提供需要数据的命令（例如WRITE），则必须包括$DATA检查无值节点。例如，可以在前一个示例中使用后置条件测试来指定WRITE命令，如下所示：

WRITE:($DATA(^client(struct))#10) !,^client(struct)

/// d ##class(PHA.TEST.Function).ORDER5()
ClassMethod ORDER5()
{
    SET struct=""
    FOR  {
        SET struct=$ORDER(^client(struct)) 
        QUIT:struct=""
        WRITE:($DATA(^client(struct))#10) !,^client(struct)
    }
}

DHC-APP>d ##class(PHA.TEST.Function).ORDER5()
 
Vermont
John Jones

该测试涵盖了无值指针节点和无值终端节点的情况。如果代码对于简单的FOR循环而言过于繁琐，则可以将其一部分委托给块结构的DO。

全局变量引用

如果一个变量是全局变量，它可以包含一个扩展的全局引用，在不同的命名空间中指定一个全局。如果指定了一个不存在的命名空间，Caché会发出一个<namespace>错误。如果指定了一个没有权限的命名空间，InterSystems IRIS会发出一个<PROTECT>错误，后跟全局名称和数据库路径，如下所示:<protect> ^myglobal(1),c:\intersystems\iris\mgr\.如果全局变量的下标映射到用户没有读取权限的命名空间，则<PROTECT>错误信息会显示原始全局引用，因为在没有权限的命名空间中看不到下标。但是，<PROTECT>错误数据库路径显示的是受保护的数据库，而不是原始数据库。

如果变量是下标的全局变量，它可以是裸全局引用。裸全局引用是在没有数组名称的情况下指定的，并且指定最近执行的全局引用。例如:

/// d ##class(PHA.TEST.Function).ORDER6()
ClassMethod ORDER6()
{
    s ^client(4,5)="4,5"
    SET var1=^client(4,5)
    SET var2=$ORDER(^(""))
    WRITE "var1=",var1,!,"var2=",var2
}

DHC-APP>d ##class(PHA.TEST.Function).ORDER6()
var1=4,5
var2=1

第一个SET命令建立当前的全局参考，包括参考的下标级别。 $ORDER函数使用裸全局引用返回该级别的第一个下标。例如，如果定义了下标全局，它将返回值1，表示^client（4,1）。如果未定义^client（4,1），它将返回值2，指示是否定义了下标全局变量^client（4,2），依此类推。

$ORDER的所有三个参数都可以采用裸全局引用，也可以指定全局引用。但是，如果direction指定了显式全局引用，则后续的裸全局引用将不使用该方向全局引用。他们继续使用先前建立的全局引用，如以下示例所示：

/// d ##class(PHA.TEST.Function).ORDER7()
ClassMethod ORDER7()
{
    k client
    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,5) */
    SET rtn=$ORDER(^client(4,5),^dir(1))
    WRITE $ZREFERENCE,!
    /* NOTE: naked global ref is ^client(4,5) */
    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)
    b
}

DHC-APP>d ##class(PHA.TEST.Function).ORDER7()
^client(4,3)
^client(4,3)
^client(4,1)
Jones
^targ(1)
Jones
^rtn(1)
Jones
 b }
 ^
<BREAK>zORDER7+23^PHA.TEST.Function.1
DHC-APP 2d1>zw ^client
^client(4,1)="Jones"
^client(4,3)="Jones"
^client(4,5)="Smith"
 
DHC-APP 2d1>zw ^dir
^dir(1)=-1
 
DHC-APP 2d1>zw ^targ
^targ(1)="Jones"
^targ(2)="Jones"

DOUBLE下标

$DOUBLE浮点数可用作下标标识符。但是，当用作下标标识符时，$DOUBLE数字将转换为字符串。 $ORDER返回此类型的下标时，将其作为数字字符串而不是$DOUBLE浮点数返回。

NEXT

$ORDER与$NEXT类似。这两个函数均按整理顺序将下一个同级的下标返回到指定节点。但是，$ORDER和$NEXT具有不同的开始和失败代码，如下所示：

因为$ORDER在空字符串上开始和结束，所以它正确地返回具有负和正下标的节点。