文章目录
第二十九章 Caché 变量大全 $ZERROR 变量 - 大纲
- 描述
-
- AsSystemError() Method
- 有关某些错误的其他信息
- 5.1版本之前的错误处理代码
- 注意
-
- ZLOAD和错误消息
- $ZERROR和程序栈
- 设置`$ZTRAP`时的`$ZERROR`操作
- 设置`$ZERROR`
包含上一个错误的名称和位置。
大纲$ZERROR $ZE描述
$ZERROR包含最新错误的名称，最新错误的位置（在适用的情况下）以及（对于某些错误代码而言）有关导致错误的原因的其他信息。 $ZERROR始终包含相应语言模式的最新错误。
$ZERROR值旨在错误后立即使用。由于$ZERROR值可能不会在例程调用中保留，因此希望保留$ZERROR值以供以后使用的用户应将其复制到变量中。强烈建议用户在使用后立即将$ZERROR设置为空字符串(“”)。
$ZERROR中包含的字符串可以是以下任何一种形式：
<error> <error>entryref <error> info <error>entryref info
- <error> 错误名称。错误名称始终以全部大写字母返回，并用尖括号括起来。它可能包含空格。
- entryref 对发生错误的代码行的引用。它由标签名称和距该标签的行偏移量组成，后跟^和程序名称。此entryref紧跟在错误名称的右尖括号之后。从终端调用$ZERROR时，此entryref信息没有意义，因此不会返回。对最近使用ZLOAD加载到例程缓冲区中的例程的引用。
- info 特定于某些错误类型的附加信息(见下表)。此信息与<error>或<error>entryref之间用空格分隔。如果有多个组件要提供信息，则用逗号分隔。
例如，一个程序(名为zerrortest)包含以下例程(名为ZerrorMain)，该例程试图写入fred(一个未定义的局部变量)的内容：
/// d ##class(PHA.TEST.SpecialVariables).ZERROR()
ClassMethod ZERROR()
{
ZerrorMain
TRY {
SET $ZERROR=""
WRITE "$ZERROR = ",$ZERROR,!
WRITE fred }
CATCH {
WRITE "$ZERROR = ",$ZCVT($ZERROR,"O","HTML")
}
}
DHC-APP> d ##class(PHA.TEST.SpecialVariables).ZERROR() $ZERROR = $ZERROR = <UNDEFINED>zZERROR+5^PHA.TEST.SpecialVariables.1 *fred
在上面的示例中，第一个$ZERROR包含一个空字符串(“”)，因为自从$ZERROR重置为空字符串以来没有发生任何错误。尝试写入未定义的变量会设置$ZERROR并将其抛给CATCH块。此$ZERROR包含ZerrorMain+4^zerrortest*fred，指定错误的名称、位置和特定于该类型错误的附加信息。在本例中，附加信息是未定义的局部变量fred的名称；星号前缀表示它是局部变量。(请注意，本例中使用$ZCVT($ZERROR，“O”，“HTML”)，因为Caché错误名称用尖括号括起来，并且本例从Web浏览器运行。)
Entryref可能如下所示：
- ZerrorMain+4^zerrortest–程序zerrortest中标签ZerrorMain的4行偏移量
- ZerrorMain^zerrortest–在程序zerrortest中没有与标签ZerrorMain的偏移量；标签行中出现错误
- +3^zerrortest–从程序zerrortest开始的3行偏移量；错误行前面没有标签
$ZERROR值的最大长度为512个字符。超过该长度的值将被截断为512个字符。
AsSystemError() Method
%Exception.SystemException类的AsSystemError()方法返回与$ZERROR相同的值。下面的示例显示了这一点：
/// d ##class(PHA.TEST.SpecialVariables).ZERROR1()
ClassMethod ZERROR1()
{
TRY {
KILL mylocal
WRITE mylocal
}
CATCH myerr {
WRITE "AsSystemError is: ",myerr.AsSystemError(),!
WRITE "$ZERROR is: ",$ZERROR
}
}
DHC-APP>d ##class(PHA.TEST.SpecialVariables).ZERROR1() AsSystemError is: <UNDEFINED>zZERROR1+3^PHA.TEST.SpecialVariables.1 *mylocal $ZERROR is: <UNDEFINED>zZERROR1+3^PHA.TEST.SpecialVariables.1 *mylocal
在Try/Catch异常处理块结构中，AsSystemError()比$ZERROR更可取，因为$ZERROR可能会被异常处理期间发生的错误覆盖。
有关某些错误的其他信息
当发生某些类型的错误时，$ZERROR将以以下格式返回错误：
<ERRORCODE>entryref info
INFO组件包含有关错误原因的附加信息。下表列出了错误列表，其中包括附加信息和该信息的格式。错误代码与INFO组件之间用空格字符分隔。
| 错误代码 | 信息组件 |
|---|---|
| <UNDEFINED> | 未定义变量的名称(包括使用的任何下标)。这可以是局部变量、进程私有全局属性、全局属性或多维类属性。局部变量名称以星号作为前缀。多维属性名以句点开头，以区别于本地变量名。通过设置%SYSTEM.Process.Unfined()方法，可以更改Caché行为，以便在引用未定义的变量时不会生成<unfined>错误。 |
| <SUBSCRIPT> | 错误的下标引用：生成错误的行引用(例程和行偏移)、下标变量以及错误的下标级别。对于结构化系统变量(SSVN)，仅提供行引用(例程和行偏移量)。通过设置%SYSTEM.Process.NullSubscript()方法，可以更改默认行为，以便在引用字符串下标为空的全局变量时不会生成错误。局部变量不允许使用空字符串下标。 |
| <NOROUTINE> | 前缀为星号，即引用的例程名称。 |
| <CLASS DOES NOT EXIST> | 前缀为星号，即引用的类名。 |
| <PROPERTY DOES NOT EXIST> | 前缀为星号(引用属性的名称)，后跟逗号分隔符和应该在其中的类名。 |
| <METHOD DOES NOT EXIST> | 前缀是星号，即调用的方法的名称，后跟逗号分隔符和应该在其中的类名。 |
| <PROTECT> | 全局引用的名称和包含全局引用的目录的名称，用逗号分隔。 |
| <THROW> | 前缀为星号、对象名称，后跟DisplayString()方法返回的值。 |
| <COMMAND> | 当不在事务中调用TCOMMIT时，INFO组件为*NoTransaction。当调用不返回值的用户定义函数时，INFO组件是一条消息，其中包含本应返回值的命令的位置。 |
| <DIRECTORY> | 以星号为前缀的无效目录的完整路径名。 |
| <FRAMESTACK> | 当<FRAMESTACK>错误终止进程时，带有附加信息的<FRAMESTACK>错误将作为消息写入mgr/cconsole.log。信息性消息显示已终止进程的进程ID(PID)和产生错误的行引用(例程和行偏移量)。例如：(PID)0<FRAMESTACK>at+13^|“user\|mytest |
例程(或方法)本地变量的名称以及未定义例程、类、属性和方法的名称都以星号(*)为前缀。进程-专用全局变量由其^||前缀标识。全局变量由它们的^(插入符号)前缀标识。类名以其%前缀形式表示。
以下示例显示了指定错误原因的其他错误信息。在每种情况下，指定的项都不存在。请注意，生成的错误的INFO组件与错误名称之间用空格分隔。星号(*)表示局部变量、类、属性或方法。插入符号(^)表示全局，^||表示进程私有全局。
<unfined>错误示例：
/// d ##class(PHA.TEST.SpecialVariables).ZERROR2()
ClassMethod ZERROR2()
{
UndefTest ;
SET $NAMESPACE="SAMPLES"
KILL x,abc(2)
KILL ^xyz(1,1),^|"USER"|xyz(1,2)
KILL ^||ppg(1),^||ppg(2)
TRY {
WRITE x
} // 未定义的局部变量
CATCH {
WRITE $ZERROR,!
}
TRY {
WRITE abc(2)
} // 未定义的下标局部变量
CATCH {
WRITE $ZERROR,!
}
TRY {
WRITE ^xyz(1,1)
} // 未定义的全局变量
CATCH {
WRITE $ZERROR,!
}
TRY {
WRITE ^|"USER"|xyz(1,2)
} // 另一个命名空间中未定义的全局变量
CATCH {
WRITE $ZERROR,!
}
TRY {
WRITE ^||ppg(1)
} // 未定义的进程专用全局变量
CATCH {
WRITE $ZERROR,!
}
TRY {
WRITE ^|"^"|ppg(2)
} // 未定义的进程专用全局变量
CATCH {
WRITE $ZERROR,!
}
}
DHC-APP>d ##class(PHA.TEST.SpecialVariables).ZERROR2() <UNDEFINED>zZERROR2+7^PHA.TEST.SpecialVariables.1 *x <UNDEFINED>zZERROR2+13^PHA.TEST.SpecialVariables.1 *abc(2) <UNDEFINED>zZERROR2+19^PHA.TEST.SpecialVariables.1 ^xyz(1,1) <UNDEFINED>zZERROR2+25^PHA.TEST.SpecialVariables.1 ^xyz(1,2) <UNDEFINED>zZERROR2+31^PHA.TEST.SpecialVariables.1 ^||ppg(1) <UNDEFINED>zZERROR2+37^PHA.TEST.SpecialVariables.1 ^||ppg(2)
<SUBSCRIPT>错误的示例：
/// d ##class(PHA.TEST.SpecialVariables).ZERROR3()
ClassMethod ZERROR3()
{
SubscriptTest ;
DO $SYSTEM.Process.NullSubscripts(0)
KILL abc,xyz
TRY {
SET abc(1,2,3,"")=123
}
CATCH {
WRITE $ZERROR,!
}
TRY {
SET xyz(1,$JUSTIFY(1,1000))=1
}
CATCH {
WRITE $ZERROR,!
}
}
DHC-APP>d ##class(PHA.TEST.SpecialVariables).ZERROR3() <SUBSCRIPT>zZERROR3+5^PHA.TEST.SpecialVariables.1 *abc() Subscript 4 is "" <SUBSCRIPT>zZERROR3+11^PHA.TEST.SpecialVariables.1 *xyz() Subscript 2 > 511 chars
<NOROUTINE>错误的示例：
/// d ##class(PHA.TEST.SpecialVariables).ZERROR4()
ClassMethod ZERROR4()
{
NoRoutineTest ;
KILL ^NotThere
TRY {
DO ^NotThere
}
CATCH {
WRITE $ZERROR,!
}
TRY {
JOB ^NotThere
}
CATCH {
WRITE $ZERROR,!
}
TRY {
GOTO ^NotThere
}
CATCH {
WRITE $ZERROR,!
}
}
DHC-APP>d ##class(PHA.TEST.SpecialVariables).ZERROR4() <NOROUTINE>zZERROR4+4^PHA.TEST.SpecialVariables.1 *NotThere <NOROUTINE>zZERROR4+10^PHA.TEST.SpecialVariables.1 *NotThere <NOROUTINE>zZERROR4+16^PHA.TEST.SpecialVariables.1 *NotThere
对象错误的示例：
DHC-APP>DO $SYSTEM.SQL.MyMethod() DO $SYSTEM.SQL.MyMethod() ^ <METHOD DOES NOT EXIST> *MyMethod,%SYSTEM.SQL DHC-APP>WRITE $SYSTEM.XXQL.MyMethod() WRITE $SYSTEM.XXQL.MyMethod() ^ <CLASS DOES NOT EXIST> *%SYSTEM.XXQL DHC-APP>SET x=##class(%SQL.Statement).%New() DHC-APP>WRITE x.MyProp WRITE x.MyProp ^ <PROPERTY DOES NOT EXIST> *MyProp,%SQL.Statement
<PROTECT>错误的示例（在Windows上）：
// 用户没有％SYS名称空间的访问权限
SET x=^|"%SYS"|var
<PROTECT> ^var,c:\intersystems\cache\mgr\
调用用户定义函数时的<command>错误示例。在本例中，MyFunc Quit命令不返回值。这将生成一个<command>错误，其中entryref指定$$MyFunc调用的位置，INFO消息指定QUIT命令的位置：
/// d ##class(PHA.TEST.SpecialVariables).ZERROR5()
ClassMethod ZERROR5()
{
Main
TRY {
KILL x
SET x=$$MyFunc(7,10)
WRITE "returned value is ",x,!
RETURN
}
CATCH {
WRITE "$ZERROR = ",$ZCVT($ZERROR,"O","HTML"),!
}
MyFunc(a,b)
SET c=a+b
QUIT
}
DHC-APP>d ##class(PHA.TEST.SpecialVariables).ZERROR5() $ZERROR = <COMMAND>zZERROR5+4^PHA.TEST.SpecialVariables.1 *Function must return a value at zZERROR5+13^PHA.TEST.SpecialVariables.1
使用PUBLIC关键字将函数作为过程调用时，出现相同的<command>错误：
Main
TRY {
KILL x
SET x=$$MyFunc(7,10)
WRITE "returned value is ",x,!
RETURN
}
CATCH {
WRITE "$ZERROR = ",$ZCVT($ZERROR,"O","HTML"),!
}
MyFunc(a,b) PUBLIC {
SET c=a+b
QUIT
}
<DIRECTORY>错误示例(在Windows上)：
/// d ##class(PHA.TEST.SpecialVariables).ZERROR6()
ClassMethod ZERROR6()
{
TRY {
SET prev=$SYSTEM.Process.CurrentDirectory("bogusdir")
WRITE "previous directory: ",prev,!
RETURN
}
CATCH {
WRITE "$ZERROR = ",$ZCVT($ZERROR,"O","HTML"),!
QUIT
}
}
DHC-APP>d ##class(PHA.TEST.SpecialVariables).ZERROR6() $ZERROR = <DIRECTORY>zCurrentDirectory+2^%SYSTEM.Process.1 *e:\dthealth\db\dthis\data\bogusdir\
5.1版本之前的错误处理代码
在Caché5.1和后续版本的这些错误代码中添加INFO组件的结果是，假设$ZERROR中的字符串格式的5.1版本之前的错误处理例程可能需要重新设计才能像以前一样工作。例如，以下内容在5.1版中将不再有效：
WRITE "Error line: ", $PIECE($ZERROR, ">", 2)
并应更改为类似以下内容：
WRITE "Error line: ", $PIECE($PIECE($ZERROR, ">", 2), " ", 1)注意
ZLOAD和错误消息
在ZLOAD操作之后，加载到例程缓冲区中的例程的名称出现在后续错误消息的entryref部分。这将在整个过程中持续存在，或者直到使用ZREMOVE删除，或者被另一个ZLOAD删除或替换。以下终端示例显示例程缓冲区内容的此显示：
SAMPLES>ZLOAD Sample.Person.1 SAMPLES>WRITE 6/0 <DIVIDE>^Sample.Person.1 SAMPLES>WRITE fred <UNDEFINED>^Sample.Person.1 *fred SAMPLES>WRITE ^fred <UNDEFINED>^Sample.Person.1 ^fred SAMPLES>ZNAME "USER" USER>WRITE 7/0 <DIVIDE>^Sample.Person.1 USER>ZREMOVE USER>WRITE ^fred <UNDEFINED> ^fred
$ZERROR和程序栈
$ZERROR字符串的<error>部分包含最新的错误消息。$ZERROR字符串的entryref部分的内容反映了最近错误的堆栈级别。以下终端会话试图调用无意义的命令gobbledegook，导致<SYNTAX>错误。它还运行ZerrorMain(上面指定)，产生$ZERROR值<unfined>。此终端会话期间的后续$ZERROR值反映了此程序调用，如下所示：
SAMPLES>gobbledegook SAMPLES>WRITE $ZERROR <SYNTAX> SAMPLES>DO ^zerrortest SAMPLES>WRITE $ZERROR <UNDEFINED>ZerrorMain+2^zerrortest *FRED SAMPLES 2d0>gobbledegook SAMPLES 2d0>WRITE $ZERROR <SYNTAX>^zerrortest SAMPLES 2d0>QUIT SAMPLES>WRITE $ZERROR <SYNTAX>^zerrortest SAMPLES>gobbledegook SAMPLES>WRITE $ZERROR <SYNTAX>
设置$ZTRAP时的$ZERROR操作
发生错误并设置$ZTRAP时，Caché在$ZERROR中返回错误消息，并分支到为$ZTRAP指定的错误陷阱处理程序
设置$ZERROR
只有在Caché模式下，才能使用set命令将$ZERROR设置为最多512个字符的值。长度超过512个字符的值将被截断为512。
强烈建议在错误处理后将$ZERROR重置为空字符串(“”)。
