第四十一章 Caché 函数大全 $NAME 函数
返回变量的名称值或下标引用的一部分
大纲
$NAME(variable,integer)
$NA(variable,integer)
参数
- variable 要返回其Name值的变量。它可以指定局部变量或全局变量，这些变量既可以是下标的，也可以是取消下标的。它不需要是定义的变量。但是，它可能不是已定义的私有变量。如果变量是带下标的全局变量，则可以指定裸全局引用。
- integer 可选-指定要返回下标引用的哪个部分(级别)的数字值。它可以是正整数、变量名或表达式。使用时，变量必须是下标引用。
描述
$NAME返回以变量形式提供的变量名引用的格式。它不会检查此变量是否已定义或具有数据值。 $NAME返回的值取决于所使用的参数。
-
$NAME（variable）以规范形式返回指定变量的名称值；即，作为完全扩展的参考。 -
$NAME（variable，integer）返回下标引用的一部分。具体来说，整数控制函数返回的下标数量。
该功能的执行不影响裸指示器。
参数
variable
变量可以是局部变量，进程专用全局变量或全局变量。它可以不下标或下标。如果变量是全局变量，则可以使用扩展的全局引用。
它可以是多维对象属性。它不能是非多维对象属性。尝试在非多维对象属性上使用$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
