第六十四章 Caché 函数大全 $STACK 函数

返回有关保存在流程调用堆栈中的活动上下文的信息。

大纲

$STACK(context_level,code_string)
$ST(context_level,code_string)

参数

• context_level 一个整数，指定要为其请求信息的上下文的从零开始的上下文级别编号。支持的值包括0，正整数和-1。
• code_string 可选-关键字字符串，指定所请求的上下文信息的类型。支持的值为“PLACE”，“MCODE”和“ECODE”

描述

$STACK函数根据$ECODE特殊变量的值返回有关当前执行堆栈或当前错误堆栈的信息。 $STACK最常用于在当前执行栈（也称为流程调用栈）上返回信息。

每次例程调用DO命令，XECUTE命令或用户定义的函数（但不是GOTO命令）时，当前正在执行的例程的上下文都会保存在调用堆栈中，并且在新创建的例程上下文中开始执行称为例行程序。反过来，被调用的例程可以调用另一个例程，依此类推，导致将更多保存的上下文放置在调用堆栈中。

$STACK函数返回有关保存在流程调用堆栈中的这些活动上下文的信息。 $STACK还可以返回有关当前正在执行的上下文的信息。但是，在错误处理期间，$STACK返回当应用程序中发生错误时所有可用上下文信息的快照。

可以使用$STACK特殊变量来确定当前上下文级别。

$ECODE 与 $STACK

$STACK返回的值取决于$ECODE特殊变量。如果清除$ECODE（设置为空字符串），则$STACK返回当前执行堆栈。如果$ECODE包含非空值，则$STACK返回当前错误堆栈。

仅当$ECODE特殊变量包含非空值时，错误堆栈上下文信息才可用。当发生错误或将$ECODE显式设置为非空值时，可能会发生这种情况。在这种情况下，$STACK返回有关错误堆栈上下文的信息，而不是有关指定上下文级别的活动堆栈上下文的信息。

当错误堆栈上下文信息不可用（$ECODE =“”）且使用$STACK的两个参数形式指定当前上下文级别时，Caché返回有关当前正在执行的命令的信息。为了确保访问当前执行堆栈时的行为一致，请在调用$STACK之前指定SET $ECODE =“”。

$STACK的单参数形式

$STACK（context_level）返回一个字符串，该字符串指示如何建立指定的上下文级别。下表描述了可以返回的字符串值：

• DO 通过DO命令建立指定的上下文时返回。
• XECUTE 通过XECUTE命令或BREAK命令建立指定的上下文时返回。
• $$ 通过用户定义的函数引用建立指定的上下文时返回。
• An ECODE string 导致将指定上下文添加到错误堆栈的错误的错误代码值。例如，， M26。当在已经发生错误的上下文级别上发生错误时，上下文信息将放在下一个更高的错误堆栈级别；仅当指定的错误堆栈上下文级别的上下文信息已重定位信息时，才返回它。

当指定的上下文级别为零（0）或未定义时，$STACK返回空字符串。

还可以使用$STACK函数的单参数形式为上下文级别指定-1。在这种情况下，$STACK返回可用信息的最大上下文级别，该信息在正常处理期间是当前正在执行的上下文的上下文级别编号。但是，在错误处理期间，$STACK（-1）返回较大值：

• 过程错误堆栈的最大上下文级别
• 当前执行上下文的上下文级别号

$STACK的两个参数形式

$STACK(context_level,code_string)）根据指定的code_string返回有关指定上下文级别的信息。必须将code_string指定为带引号的字符串。 code_string值不区分大小写。例如，$STACK(1,"PLACE")或 $STACK(1,"place")。

以下描述了代码字符串以及在指定每个字符串时返回的信息。

• PLACE —返回在指定上下文级别执行的最后一个命令的条目引用和命令编号。对于DO和用户定义的函数上下文，将以以下格式返回该值：“ label [+ offset] [^例程名称] + command”。对于XECUTE上下文，使用以下格式：“ @ + command”。
• MCODE —返回源例程行，XECUTE字符串或$ETRAP字符串，其中包含在指定上下文级别执行的最后一个命令。 （常规行的返回方式与$TEXT函数返回的方式相同。）

注意：在错误处理期间，如果在构建或更新错误堆栈时内存不足，则可能没有足够的内存来存储源代码行。在这种情况下，MCODE代码字符串的返回值为空字符串。但是，PLACE代码字符串的返回值指示位置。

• ECODE —在指定上下文级别发生的任何错误的错误代码（仅在错误堆栈上下文中可用）。

当请求的信息在指定的上下文级别不可用时，$STACK的两个参数形式将返回空字符串。

示例

下面的示例演示$STACK可以返回的一些信息：

STAC  ;
    SET $ECODE=""
    XECUTE "DO First"
    QUIT
First 
    SET varSecond=$$Second()
    QUIT
Second()  
    FOR loop=0:1:$STACK(-1) { 
        WRITE !,"Context level:",loop,?25,"Context type: ",$STACK(loop)
        WRITE !,?5,"Current place: ",$STACK(loop,"PLACE")
        WRITE !,?5,"Current source: ",$STACK(loop,"MCODE")
        WRITE ! 
    }
    QUIT 1

DHC-APP>d STAC^PHA.TEST.Command
 
Context level:0          Context type:
     Current place: @ +1
     Current source: D STAC^PHA.TEST.Command
 
Context level:1          Context type: DO
     Current place: STAC+2^PHA.TEST.Command +1
     Current source:    XECUTE "DO First"
 
Context level:2          Context type: XECUTE
     Current place: @ +1
     Current source: DO First
 
Context level:3          Context type: DO
     Current place: First+1^PHA.TEST.Command +1
     Current source:    SET varSecond=$$Second()
 
Context level:4          Context type: $$
     Current place: Second+3^PHA.TEST.Command +4
     Current source:            WRITE !,?5,"Current source: ",$STACK(loop,"MCODE")
 

打印堆栈信息

    FOR loop=0:1:$STACK(-1) { 
        WRITE !,"Context level:",loop,?25,"Context type: ",$STACK(loop)
        WRITE !,?5,"Current place: ",$STACK(loop,"PLACE")
        WRITE !,?5,"Current source: ",$STACK(loop,"MCODE")
        WRITE ! 
    }

注意

跨命名空间的例行调用

如果例程在其他名称空间中调用例程，则$STACK返回名称空间名称作为例程名称的一部分。例如，如果USER名称空间中的例程调用SAMPLES名称空间中的例程，则$STACK返回 ^|“ SAMPLES” |例程名称。

$STACK使用尖号（^）字符作为分隔符。因此，如果隐含的名称空间名称包含插入符号（^）字符，则Caché将此名称空间名称字符显示为@字符。

$STACK计算多个参数的命令

指定多参数命令时，命令计数包括命令关键字和除第一个以外的所有命令参数。考虑以下多参数命令：

TEST
  SET X=1,Y=Z

在Caché中，由于Y = Z参数被视为单独的命令，因此$STACK语句$STACK（1，“ PLACE”）返回"TEST^TEST +2"。

出现<STORE>错误或内存不足的$STACK

在出现<STORE>错误或在内存不足的情况下，可能无法通过应用$STACK的两个参数形式正常获取信息。