第四十一章 Caché 命令大全 ZBREAK 命令

设置断点或观察点。

大纲

ZBREAK:pc
ZB:pc

ZBREAK:pc location:action:condition:execute_code
ZB:pc location:action:condition:execute_code

ZBREAK:pc /command:option
ZB:pc /command:option

参数

• pc
  • 可选-后置条件表达式。
• location
  • 指定代码行位置(设置断点)、局部变量*var(设置观察点)或$(单步断点)。如果指定的位置已经定义了断点/观察点，则新规范将完全替换旧规范。
  • 可以选择在LOCATION前面加一个符号：+、-或--。不带符号前缀的位置设置指定的断点/观察点。A-(减号)前缀禁用断点/观察点。前缀+(加号)重新启用禁用的断点/观察点。--(减号-减号)前缀删除断点/观察点。
  • 可以在没有位置的情况下指定以下符号：-(减号)=禁用所有断点和观察点。+(加号)=重新启用所有禁用的断点和观察点。
• :action
  • 可选-指定触发断点/监视点时要执行的操作，指定为字母代码。操作代码字母可以是大写或小写，但必须用引号引起来。如果省略，则默认为“B”。
  • 如果省略，并指定：CONDITION或：EXECUTE_CODE，则冒号必须显示为占位符。
• :condition
  • 可选-指定在触发断点/监视点时将计算为布尔值的表达式。表达式必须用引号引起来。如果为True，则执行操作。如果未指定，则默认值为true。
  • 如果省略并且指定了：EXECUTE_CODE，则冒号必须显示为占位符。
• :execute_code
  • 可选-指定在：Condition为True时要执行的ObjectScript代码。
  • 如果代码是文字，则代码必须用引号括起来。
• /command:option
  • 管理所有断点和观察点的命令。斜杠(/)前缀是必需的。
  • 可用命令有：/CLEAR、/DEBUG、/TRACE、/ERRORTRAP、/INTERRUPT、/STEP和/NOSTEP。
  • 除/Clear之外的所有选项都接受一个选项，如下所述。大多数/command 名可以指定为单字母缩写：/C、/T等等。

描述

ZBREAK在特定代码行设置断点，并在特定局部变量上设置观察点，以允许您中断程序执行以进行调试。一旦建立，断点或监视点将在当前进程的持续时间内持续存在，或者直到显式删除或清除为止。断点和观察点在命名空间之间是持久的。每个进程最多可以建立20个断点和20个观察点。这些最大值包括启用和禁用的断点和观察点。尝试设置20个以上的断点或监视点会导致<command>错误。

所需权限

要在运行代码时使用ZBREAK语句，必须将用户分配给为%Development资源提供U(使用)权限的角色(如%Developer或%Manager)。可以通过SQL GRANT语句或使用Management Portal System Administration、Security、Users选项将用户分配给角色。选择用户名以编辑其定义，然后选择角色选项卡将该用户分配给角色。

要使用ZBREAK，用户必须对代码所在的数据库具有写访问权限。否则，将禁用单步执行、断点和监视点。例如，对%SYS(CACHESYS)或CACHELIB数据库没有写访问权限的用户将无法调试该数据库中的例程。Caché在进入其中一个数据库中的例程时禁用调试，并且仅在例程退出时恢复调试。这样做的效果是，该例程调用的任何其他代码也将禁用调试，而不管用户是否对该代码的数据库具有写入访问权限。

列出断点

无参数ZBREAK命令列出当前断点和观察点。它列出了启用和禁用的断点和观察点。

列出本地变量值

可以在同一行上的任何ZBREAK命令后面加上一个无参数的WRITE命令。(请注意，无参数ZBREAK后面必须跟两个空格。)无参数WRITE 在遇到ZBREAK行时列出所有局部变量的值；而不是在它生效时列出。

禁用/启用所有现有断点/监视点

ZBREAK命令后面可以跟一个没有位置规范的符号。减号(-)参数禁用所有当前断点和观察点。加号(+)参数将重新启用所有以前禁用的断点和观察点。支持以下不带位置命令的ZBREAK：

ZBREAK帮助文本

要在终端提示符下查看有关ZBREAK的联机帮助文本，请指定问号，如下所示：

用户名:yx
密码:******
DHC-APP>zb ?
 
ZB location{:parms}   Set breakpoint
ZB -location{#delay}  Disable breakpoint
ZB +location          Enable breakpoint
ZB --location         Remove breakpoint
 
location is a line reference, or *variable, or $
 
parms is action:{condition}:{execute}
 
action is B, L, L+, S, S+, T, or N  which mean
 BREAK, Line step, Single step, Trace, or No action
condition is a truth-valued expression
execute is code to be executed
 
/CLEAR                        Remove all breakpoints
/DEBUG{:device}               Clear or set debug device
/TRACE:{ON,OFF,ALL}{:device}  Enable or disable trace, or trace all lines
/ERRORTRAP:{ON,OFF}           Enable or disable error traps
/INTERRUPT:{NORMAL,BREAK}     Specify Control-C action
/{NO}STEP:{EXT,METHOD,DESTRUCT}  Control stepping into extensions and methods
 
DHC-APP>

参数

pc

可选的后置条件表达式。如果后置条件表达式为真(计算结果为非零数值)，Caché 将执行该命令。如果后置条件表达式为false(计算结果为0)，Caché将不执行该命令。

location

如果希望设置或取消断点或观察点，则需要location参数。它可以由一个符号(加号、减号或减号)和一个断点或观察点规范组成。支持各种符号和断点/观察点规范的组合:

• *varname: 局部变量。每次设置变量值时建立一个观察点。星号前缀是必填的。为未定义的局部变量设置观察点不会生成错误。可以选择为每个观察点指定操作、条件和/或EXECUTE_CODE。这些可选参数中的任何一个都可以省略，但如果指定或跳过，则必须指定强制冒号分隔符(：)。
• $：单步断点。
• 行引用，指定为label+offset^{routine以指定断点。可以指定LABEL、+OFFSET和}ROUTINE的任意组合(按该顺序)。如果省略LABEL，断点位置将按从例程顶部开始的偏移量计数(ZBREAK语句被视为偏移量行)。如果省略+Offset，则断点位置为指定的标签行。如果省略^{例程，断点位置假定在当前加载的例程中；可以使用}ROUTINE指定当前加载的例程以外的例程位置。为不存在的标签、偏移量或例程设置断点不会生成错误。
• 要设置断点，请指定LABEL+OFFSET^例程位置和(可选)操作、条件和/或EXECUTE_ CODE，如下所示：label+offset^routine:action:condition:execute_code。这些可选参数中的任何一个都可以省略，但如果跳过某个参数，则必须指定强制冒号分隔符(：)。ZBREAK不移动编辑指针。

或者，位置参数可以加上一个符号作为前缀，该符号指示如何处理指定位置的现有断点或观察点。可以指定无符号(Set)、减号(禁用)、加号(重新启用)或两个减号(删除)。还可以在$单步断点之前指定一个符号。尝试禁用、重新启用或删除不存在的断点或监视点会生成<command>错误。

行引用置必须位于命令边界上。在命令表达式中设置的变量不能用作位置。此类型的变量设置发生在$DATA、$ORDER和$QUERY函数的目标参数中。

condition

布尔表达式。如果为true(1)，则应执行操作并执行EXECUTE_CODE(如果存在)。如果为FALSE(0)，则忽略ACTION和EXECUTE_CODE。默认值为TRUE(1)。

execute_code

要执行的ObjectScript代码。此代码在执行操作之前执行。在执行代码之前，保存test`的值将恢复为它在正在调试的程序中存在的值。

EXECUTE_CODE由XECUTE命令在内部执行。XECUTE只能访问公共变量。

但是，可以指定在EXECUTE_CODE中传递参数，以将私有变量传递给XECUTE。

因为XECUTE参数包含带引号的字符串，所以当通过ZBREAK EXECUTE_ CODE参数传递代码时，必须使用双引号。正确执行此操作的最简单方法是首先将代码编写为实际的XECUTE命令，然后使用双引号创建相应的ZBREAK EXECUTE_CODE。

例如，要在变量var更改时显示它的新值，首先编写一个XECUTE命令来显示它：

  XECUTE ("(arg) WRITE ""now var="",arg,!",$GET(var,"<UNDEFINED>")) 

则等效的ZBREAK命令将为：

  ZBREAK *var:::"(""(arg) WRITE """"now var="""",arg,!"",$GET(var,""<UNDEFINED>""))"

/command:option

用于为后续ZBREAK命令设置ZBREAK环境的命令关键字。/clear命令不接受任何选项。其他命令关键字后面跟一个选项，用冒号分隔。不允许有空格。

/TRACE

/trace命令关键字指定用于接收跟踪消息的跟踪输出设备。它必须在发出带有action=“T”的ZBREAK之前指定。它可以指定为单独的ZBREAK命令(ZBREAK/TRACE：ON：DEVICE)，或者这两个命令可以组合为ZBREAK S:"T",/TRACE:ON:device

一次只能有一个轨迹输出设备处于活动状态。只有跟踪消息写入跟踪输出设备；正常写入操作继续写入用户终端。

• /TRACE：ON激活系统间终端作为跟踪消息的收件人。
• /TRACE：ON：DEVICE将现有输出设备(通常为.txt文件)激活为跟踪消息的收件人。在调用ZBREAK/TRACE：ON：DEVICE之前，必须使用OPEN命令打开设备。如果指定的设备未打开，则Caché会发出<NOTOPEN>错误。要打开顺序文件，目录必须存在，并且文件必须存在，或者OPEN命令必须指定“N”选项才能创建文件。以下终端会话的Windows示例中显示了此操作顺序：

DHC-APP>SET btrace="E:\Logs\mydebugtrace.txt"
 
DHC-APP>OPEN btrace:"WN"
 
DHC-APP>ZBREAK /TRACE:ON:btrace
 
DHC-APP>ZBREAK
BREAK: Trace ON
 Trace device=E:\Logs\mydebugtrace.txt
 No breakpoints
 No watchpoints
 
DHC-APP>

如果先前的ZBREAK/TRACE：ON：DEVICE1已经激活了跟踪输出设备，则ZBREAK/TRACE：ON：DEVICE2会将DEVICE1跟踪设备替换为DEVICE2跟踪设备。

• /TRACE：ALL启用行步进，为每行向跟踪设备写入一条消息。此行单步执行不会停止，但会继续调试代码。可以指定ZBREAK/TRACE：ALL或ZBREAK/TRACE：ALL：DEVICE。/TRACE：ALL启用跟踪行步进；可以在激活跟踪设备之前或之后使用/TRACE：ON：DEVICE调用此选项。/TRACE：ALL：DEVICE既激活跟踪设备，又启用到该跟踪设备的行步进。在调用/TRACE：ALL：DEVICE之前，必须使用OPEN命令打开设备。如果指定的设备未打开，则Caché会发出<NOTOPEN>错误。要打开顺序文件，目录必须存在，并且文件必须存在，或者OPEN命令必须指定“N”选项才能创建文件。以下终端会话的Windows示例中显示了此操作顺序：

DHC-APP>SET steptrace="E:\Logs\mysteptrace.txt"
 
DHC-APP>OPEN steptrace:"WN"
 
DHC-APP>ZBREAK /TRACE:ALL:steptrace
 
DHC-APP>zb
BREAK:L+ Trace ON
 Trace device=E:\Logs\mysteptrace.txt
$ (single step) F:ET S:0 C: E:
 No watchpoints
 
DHC-APP>

/TRACE：OFF停用当前跟踪输出设备；不关闭该设备。可以指定ZBREAK/TRACE：OFF或ZBREAK/TRACE：OFF：DEVICE。/TRACE：OFF停用当前跟踪输出设备；如果没有活动的跟踪设备，则Caché不执行任何操作，也不发出任何错误。/TRACE：OFF：DEVICE停用指定的跟踪输出设备。如果指定的设备不是当前跟踪输出设备，/TRACE：OFF：DEVICE将发出<NOTOPEN>错误。

/STEP和/NOSTEP

/STEP和/NOSTEP命令关键字控制调试器是否单步执行某些类型的代码模块：

• ：EXT选项控制在%ZLANG中创建的用户编写的语言扩展。对于应用程序，这些语言扩展显示为单个命令或函数调用。默认情况下，无论操作参数设置如何，调试器都不会单步执行这些%ZLANG例程。
• :METHOD选项控制应用程序调用的对象方法的单步执行。默认情况下，调试器单步执行对象方法代码。
• :DESTRUCT选项控制通过%destruct对象方法的单步执行。每当销毁对象时，都会隐式调用%destruct方法。默认情况下，调试器不单步执行%Destruct对象方法代码。

可以指定多个/STEP或/NOSTEP选项，如下例所示：

  ZBREAK /STEP:METHOD:DESTRUCT

示例

下面的示例显示不带参数的ZBREAK如何列出断点和监视点。第一个ZBREAK没有列出断点或观察点。然后，程序在x和y局部变量上设置两个观察点，ZBREAK显示此信息。接下来，程序设置$单步断点，ZBREAK显示断点和两个观察点。接下来，程序禁用x局部变量观察点；这对ZBREAK显示没有影响。最后，程序删除x局部变量观察点；该观察点从ZBREAK显示中消失：

  ZBREAK
    ZBREAK *x:"B"
    ZBREAK *y:"B"
  ZBREAK
    ZBREAK $
  ZBREAK
    ZBREAK -*x
  ZBREAK
    ZBREAK --*x
  ZBREAK
    ZBREAK /CLEAR

    ZBREAK /TRACE:ON
    ZBREAK *sp:"T"  

/// w ##class(PHA.COM.MOB.StockQty).GetInclbQty("4450||2",20,1,1)

DHC-APP> w ##class(PHA.COM.MOB.StockQty).GetInclbQty("4450||2",20,1,1)
 
Trace: ZBREAK SET batchQty=0 at zGetBatchQty+1^PHA.COM.MOB.StockQty.1
 
Trace: ZBREAK SET batchQty=2000 at zGetBatchQty+3^PHA.COM.MOB.StockQty.1
 
Trace: ZBREAK SET batchQty=2000 at zGetInclbQty+25^PHA.COM.MOB.StockQty.1
 
Trace: ZBREAK SET batchQty=0 at zGetBatchQty+1^PHA.COM.MOB.StockQty.1
 
Trace: ZBREAK SET batchQty=10 at zGetBatchQty+3^PHA.COM.MOB.StockQty.1
 
Trace: ZBREAK SET batchQty=10 at zGetInclbQty+25^PHA.COM.MOB.StockQty.1
 
Trace: ZBREAK SET batchQty=0 at zGetBatchQty+1^PHA.COM.MOB.StockQty.1
 
Trace: ZBREAK SET batchQty=3000 at zGetBatchQty+3^PHA.COM.MOB.StockQty.1
 
Trace: ZBREAK SET batchQty=3000 at zGetInclbQty+25^PHA.COM.MOB.StockQty.1
1