第四十一章 Caché 函数大全 $NAME 函数

返回变量的名称值或下标引用的一部分

大纲

$NAME(variable,integer)
$NA(variable,integer)

参数

• variable 要返回其Name值的变量。它可以指定局部变量或全局变量，这些变量既可以是下标的，也可以是取消下标的。它不需要是定义的变量。但是，它可能不是已定义的私有变量。如果变量是带下标的全局变量，则可以指定裸全局引用。
• integer 可选-指定要返回下标引用的哪个部分(级别)的数字值。它可以是正整数、变量名或表达式。使用时，变量必须是下标引用。

描述

$NAME返回以变量形式提供的变量名引用的格式。它不会检查此变量是否已定义或具有数据值。 $NAME返回的值取决于所使用的参数。

• $NAME（variable）以规范形式返回指定变量的名称值；即，作为完全扩展的参考。
• $NAME（variable，integer）返回下标引用的一部分。具体来说，整数控制函数返回的下标数量。

该功能的执行不影响裸指示器。

参数

variable

变量可以是局部变量，进程专用全局变量或全局变量。它可以不下标或下标。如果变量是全局变量，则可以使用扩展的全局引用。 NAME`返回完整的全局引用。如果变量是私有变量，则会发生编译错误。

它可以是多维对象属性。它不能是非多维对象属性。尝试在非多维对象属性上使用$NAME会导致<OBJECT DISPATCH> 错误

$NAME无法返回特殊变量，即使是可以使用SET修改的变量也是如此。尝试返回特殊变量将导致<SYNTAX>错误。

integer

当变量是带下标的引用时，使用整数参数。如果整数的值为0，则$NAME仅返回变量的名称。如果整数的值小于变量中的下标数目，则$NAME返回由整数的值指示的下标数目。如果integer大于变量中的下标数目，则$NAME返回完整的下标引用。

如果变量是未下标的变量，则整数值将被忽略；否则，整数将被忽略。 $NAME返回变量名称。如果整数是空字符串（“”）或非数字字符串，则$NAME返回不带下标的变量名称。

整数的值接收标准整数解析。例如，前导零和加号将被忽略。小数位将被截断并忽略。负整数值会导致<FUNCTION>错误。

示例

在此示例中，integer参数指定要返回的级别。如果指定的整数下标数目匹配或超过下标级别的数目（在本例中为3），则$NAME返回所有定义的级别，其行为就像指定了一个参数形式。如果指定整数级别零（0），空字符串（“”）或任何非数字字符串（例如“A”），则$NAME返回数组的名称（在这种情况下为“^client”）

/// d ##class(PHA.TEST.Function).NAME()
ClassMethod NAME()
{
    SET ^client(4)="Vermont"
    SET ^client(4,1)="Brattleboro"
    SET ^client(4,1,1)="Yankee Ingenuity"
    SET ^client(4,1,2)="Vermonster Systems"
    SET ^client("a",1,"b",2)="Vermont11"
    WRITE !,$NAME(^client(4,1,1),1) ; returns 1 level
    WRITE !,$NAME(^client(4,1,1),2) ; returns 2 levels
    WRITE !,$NAME(^client(4,1,1),3) ; returns 3 levels
    WRITE !,$NAME(^client(4,1,1),4) ; returns all (3) levels
    WRITE !,$NAME(^client(4,1,1),0) ; returns array name
    WRITE !,$NAME(^client(4,1,1),"") ; returns array name
    WRITE !,$NAME(^client(4,1,1))    ; returns all (3) levels
    WRITE !,$NAME(^client("a",1,"b",2),1)    
    WRITE !,$NAME(^client("a",1,"b",2),2)    
    WRITE !,$NAME(^client("a",1,"b",2),3)   
    WRITE !,$NAME(^client("a",1,"b",2),4)
}

DHC-APP> d ##class(PHA.TEST.Function).NAME()
 
^client(4)
^client(4,1)
^client(4,1,1)
^client(4,1,1)
^client
^client
^client(4,1,1)
^client("a")
^client("a",1)
^client("a",1,"b")
^client("a",1,"b",2)

在以下示例中，$NAME在循环中与裸引用一起使用，以输出当前（用户提供）数组级别中所有元素的值。

/// d ##class(PHA.TEST.Function).NAME1()
ClassMethod NAME1()
{
    READ !,"Array element: ",ary
    SET x=@ary ; dummy operation to set current array and level
    SET y=$ORDER(^("")) ; null string to find beginning of level
    FOR i=0:0 {
        WRITE !,@$NAME(^(y)) 
        SET y=$ORDER(^(y)) 
        QUIT:y=""
    }
}

第一个SET命令执行虚拟分配，以建立用户提供的数组和级别，作为后续裸引用的基础。 $ORDER函数与裸引用一起使用以返回当前级别的第一个下标（无论是负数还是正数）的编号。

FOR循环中的WRITE命令将$NAME与裸露的全局引用和参数间接引用一起使用，以输出当前元素的值。 SET命令使用带有裸全局引用的$ORDER返回下一个包含数据的现有元素的下标。最后，后置条件QUIT检查$ORDER返回的值以检测当前级别的结束并终止循环处理。

可以将返回的$NAME字符串值用于名称或下标间接寻址，或将其作为参数传递给例程或用户定义的函数考虑例程^DESCEND，该例程列出了指定节点的后代节点。

DESCEND(ROOT)  ;List descendant nodes
    NEW REF 
    SET REF=ROOT
    IF ROOT'["(" {
        FOR {
            SET REF=$QUERY(@REF) 
            QUIT:REF="" 
            WRITE REF,! 
        }
    }
    ELSE {
        SET $EXTRACT(ROOT,$LENGTH(ROOT))=","
        FOR {
            SET REF=$QUERY(@REF)
            QUIT:REF'[ROOT 
            WRITE REF,!   
        }
    }

下面的示例演示如何使用$NAME将参数传递给上一个示例中定义的^DESCEND例程。

    FOR var1="ONE","TWO","THREE" { 
        DO ^DESCEND($NAME(^X(var1))) 
    }

注意

用于$NAME

通常，使用$NAME返回用于$DATA和$ORDER函数的数组元素的名称值。

如果对数组元素的引用包含表达式，则$NAME将在返回名称的规范形式之前对表达式进行求值。例如：

/// d ##class(PHA.TEST.Function).NAME4()
ClassMethod NAME4()
{
    SET x=1+2
    SET y=$NAME(^client(4,1,x))
    WRITE y
}

DHC-APP>d ##class(PHA.TEST.Function).NAME4()
^client(4,1,3)

裸全局引用

$NAME还接受裸全局引用，并以规范形式返回名称值（即完整（非裸）引用）。指定一个没有数组名称的裸引用，并指定最近执行的全局引用。在以下示例中，第一个SET命令建立全局引用，第二个SET命令将$NAME函数与裸全局引用一起使用。

/// d ##class(PHA.TEST.Function).NAME5()
ClassMethod NAME5()
{
    SET ^client(5,1,2)="Savings/27564/3270.00"
    SET y=$NAME(^(3))
    WRITE y
}

DHC-APP>d ##class(PHA.TEST.Function).NAME5()
^client(5,1,3)
DHC-APP>zw ^client(5,1,3)
^client(5,1,3)="Reserve Credit/32456/125.00"

在这种情况下，$NAME返回值^client（5,1,3）。提供的下标值（3）替换了当前级别的现有下标值（2）。

扩展的全局引用

可以使用%SYSTEM的RefInKind()方法控制$NAME是否在每个进程的基础上以扩展的全局引用形式返回名称值。过程类。系统范围的默认行为可以通过设置配置的RefInKind属性来建立。

在扩展引用模式生效的情况下，以下示例返回已定义的名称空间和名称^["PAYROLL"]MyRoutine(如第一个示例所示)，而不仅仅是^MyRoutine(如第二个示例所示):

/// d ##class(PHA.TEST.Function).NAME6()
ClassMethod NAME6()
{
    DO ##class(%SYSTEM.Process).RefInKind(0)
    WRITE $NAME(^["PAYROLL"]MyRoutine)
}

DHC-APP> d ##class(PHA.TEST.Function).NAME6()
^["PAYROLL"]MyRoutine

/// d ##class(PHA.TEST.Function).NAME7()
ClassMethod NAME7()
{
    DO ##class(%SYSTEM.Process).RefInKind(1)
    WRITE $NAME(^["PAYROLL"]MyRoutine)
}

DHC-APP>d ##class(PHA.TEST.Function).NAME7()
^MyRoutine