第二十三章 使用 %Status 值

许多类使用 %Status 数据类型类来表示状态信息，并且它们的方法返回表示成功或错误的 %Status 值（状态）。如果状态表示一个错误（或多个错误），则状态值还包括有关错误的信息。

还可以返回自己的状态值。

本文讨论状态值以及如何使用它们。

使用状态值的基础知识

如上所述，许多 类中的方法返回一个状态以指示成功或错误。例如，%Library.Persistent中的%Save()` 方法返回一个状态。对于任何此类方法，请务必获取返回值。然后检查状态，然后适当地继续。基本工具如下：

• 要检查状态是表示成功还是错误，请使用以下任一方法：

  • $$$ISOK 和 $$$ISERR 宏，在包含文件 %occStatus.inc 中定义。此包含文件在所有对象类中自动可用。
  • $SYSTEM.Status.IsOK() 和 $SYSTEM.Status.IsError() 方法，它们在终端（不能使用宏）中特别方便。

• 要显示错误详细信息，请使用 $SYSTEM.OBJ.DisplayError() 或 $SYSTEM.Status.DisplayError()。这些方法彼此等效。他们将输出写入当前设备。

• 要获取包含错误详细信息的字符串，请使用 $SYSTEM.Status.GetErrorText()。

示例

/// d ##class(PHA.TEST.AdvancedConcepts).Status()
ClassMethod Status()
{
    s object = ##class(Sample.Person).%New()
    s object.Name = "yao,xin"
    s tSC = object.%Save()
    if $$$ISERR(tSC) {
        d $SYSTEM.OBJ.DisplayError(tSC)
        q
    }
}

DHC-APP>d ##class(PHA.TEST.AdvancedConcepts).Status()
 
错误 #5659: 需要属性'Sample.Person::SSN(1@Sample.Person,ID=)'
错误 #7209: 数据类型值''与PATTERN '3N1"-"2N1"-"4N'不匹配
  > 错误 #5802: 属性'Sample.Person:SSN'上的数据类型验证失败,值等于""

下面是一个显示 $SYSTEM.Status.GetErrorText() 用法的部分示例：

If $$$ISERR(tSC) {
   // if error, log error message so users can see them
   Do ..LogMsg($System.Status.GetErrorText(tSC))
 }

注意：一些 ObjectScript 程序员使用字母 t 作为前缀来表示临时变量，因此可能会在代码示例中看到 tSC 用作变量名，意思是“临时状态代码”。你可以随意使用这个约定，但是这个变量名并没有什么特别之处。

/// w ##class(PHA.TEST.AdvancedConcepts).Status1()
ClassMethod Status1()
{
    s object = ##class(Sample.Person).%New()
    s object.Name = "yao,xin"
    s tSC = object.%Save()
    if $$$ISERR(tSC) {
        q $System.Status.GetErrorText(tSC)
    }
}

DHC-APP>d ##class(PHA.TEST.AdvancedConcepts).Status()
 
错误 #5659: 需要属性'Sample.Person::SSN(1@Sample.Person,ID=)'
错误 #7209: 数据类型值''与PATTERN '3N1"-"2N1"-"4N'不匹配
  > 错误 #5802: 属性'Sample.Person:SSN'上的数据类型验证失败,值等于""

状态值中报告的多个错误

如果一个状态值表示多个错误，则这些技术只为提供最新的信息。要获取有关由状态值表示的所有错误的信息，请使用 $SYSTEM.Status.DecomposeStatus()，它返回错误详细信息的数组（通过引用，作为第二个参数）。例如：

 Do $SYSTEM.Status.DecomposeStatus(tSC,.errorlist)
 //then examine the errorlist variable

变量errorlist 是一个包含错误信息的数组。下面显示了一个部分示例，其中包含一些人工换行符以提高可读性：

/// w ##class(PHA.TEST.AdvancedConcepts).Status2()
ClassMethod Status2()
{
    s object = ##class(Sample.Person).%New()
    s object.Name = "yao,xin"
    s tSC = object.%Save()
    if $$$ISERR(tSC) {
        d $SYSTEM.Status.DecomposeStatus(tSC,.errorlist)
        zw errorlist
    }
}

DHC-APP>w ##class(PHA.TEST.AdvancedConcepts).Status2()
errorlist=2
errorlist(1)="错误 #5659: 需要属性'Sample.Person::SSN(1@Sample.Person,ID=)'"
errorlist(1,"caller")="%ValidateObject+10^Sample.Person.1"
errorlist(1,"code")=5659
errorlist(1,"dcode")=5659
errorlist(1,"domain")="%ObjectErrors"
errorlist(1,"namespace")="DHC-APP"
errorlist(1,"param")=1
errorlist(1,"param",1)="Sample.Person::SSN(1@Sample.Person,ID=)"
errorlist(1,"stack")=$lb("e^%ValidateObject+10^Sample.Person.1^3","e^%SerializeObject+3^Sample.Person.1^1","e^%Save+8^Sample.Person.1^5","e^zStatus2+3^PHA.TEST.AdvancedConcepts.1^1","e^^^0")
errorlist(1,"tail")="0 "_$lb($lb(7209,"","3N1""-""2N1""-""4N",,,,,,,$lb("zSSNIsValid+1^Sample.Person.1","DHC-APP",$lb("e^zSSNIsValid+1^Sample.Person.1^1","e^%ValidateObject+11^Sample.Person.1^2","e^%SerializeObject+3^Sample.Person.1^1","e^%Save+8^Sample.Person.1^5","e^zStatus2+3^PHA.TEST.AdvancedConcepts.1^1","e^^^0")),"0 "_$lb($lb(5802,"Sample.Person:SSN","",,,,,,,$lb("EmbedErr+1^%occSystem","DHC-APP",$lb("e^EmbedErr+1^%occSystem^1"))))))/* 错误 #7209: 数据类型值''与PATTERN         '3N1"-"2N1"-"4N'不匹配-   > 错误 #5802: 属性'Sample.Person:SSN'上的数据类型验证                失败,值等于"" */
errorlist(2)="错误 #7209: 数据类型值''与PATTERN '3N1""-""2N1""-""4N'不匹配"_$c(1           3,10)_"  > 错误 #5802: 属性'Sample.Person:SSN'上的数据类型验证失败,值等于"""""
errorlist(2,"caller")="zSSNIsValid+1^Sample.Person.1"
errorlist(2,"code")=7209
errorlist(2,"dcode")=7209
errorlist(2,"domain")="%ObjectErrors"
errorlist(2,"embeddederror")=1
errorlist(2,"embeddederror",1)="0 "_$lb($lb(5802,"Sample.Person:SSN","",,,,,,,$lb("EmbedErr+1^%occSystem","DHC-APP",$lb("e^EmbedErr+1^%occSystem^1"))))/* 错误 #  5802: 属性'Sample.Person:SSN'上的数据类型验证失败,值等于"" */
errorlist(2,"embeddedstatus")="0 "_$lb($lb(5802,"Sample.Person:SSN","",,,,,,,$lb("EmbedErr+1^%occSystem","DHC-APP",$lb("e^EmbedErr+1^%occSystem^1"))))/* 错误 #5  802: 属性'Sample.Person:SSN'上的数据类型验证失败,值等于"" */
errorlist(2,"namespace")="DHC-APP"
errorlist(2,"param")=2
errorlist(2,"param",1)=""
errorlist(2,"param",2)="3N1""-""2N1""-""4N"
errorlist(2,"stack")=$lb("e^zSSNIsValid+1^Sample.Person.1^1","e^%ValidateObject+11^Sample.Person.1^2","e^%SerializeObject+3^Sample.Person.1^1","e^%Save+8^Sample.Person.1^5","e^zStatus2+3^PHA.TEST.AdvancedConcepts.1^1","e^^^0")

如果想记录每条错误消息，可以修改前面的记录示例，如下所示：

/// w ##class(PHA.TEST.AdvancedConcepts).Status3()
ClassMethod Status3()
{
    s object = ##class(Sample.Person).%New()
    s object.Name = "yao,xin"
    s tSC = object.%Save()
    if $$$ISERR(tSC) {
        d $SYSTEM.Status.DecomposeStatus(tSC,.errorlist)
        for i = 1 : 1 : errorlist {
            w errorlist(i),!
        }
    }
}

DHC-APP>w ##class(PHA.TEST.AdvancedConcepts).Status3()
错误 #5659: 需要属性'Sample.Person::SSN(1@Sample.Person,ID=)'
错误 #7209: 数据类型值''与PATTERN '3N1"-"2N1"-"4N'不匹配
  > 错误 #5802: 属性'Sample.Person:SSN'上的数据类型验证失败,值等于""
 

注意：如果再次调用 $SYSTEM.Status.DecomposeStatus() 并传入相同的错误数组，则任何新错误都会附加到数组中。

返回状态值

还可以返回自己的自定义状态值。要创建状态值，请使用以下构造：

 $$$ERROR($$$GeneralError,"your error text here")

或等效地：

 $SYSTEM.Status.Error($$$GeneralError,"your error text here")

例如：

 quit $SYSTEM.Status.Error($$$GeneralError,"Not enough information for request")

要包含有关其他错误的信息，请使用 $SYSTEM.Status.AppendStatus() 修改状态值。例如：

 set tSC=$SYSTEM.Status.AppendStatus(tSCfirst,tSCsecond)
 quit tSC

/// w ##class(PHA.TEST.AdvancedConcepts).Status3()
ClassMethod Status4(flag) As %Status
{
    q:(flag = 1) 100
    q:(flag = 0) $$$ERROR($$$GeneralError,"这是一条错误信息！")
}

/// w ##class(PHA.TEST.AdvancedConcepts).Status5(0)
ClassMethod Status5(flag)
{
    s sc = ..Status4(flag)
    
    if $$$ISERR(sc) {
        d $SYSTEM.Status.DecomposeStatus(sc,.errorlist)
        zw errorlist
        w "GetErrorCodes:"_$System.Status.GetErrorCodes(sc),!
        w "GetOneErrorText:"_$System.Status.GetOneErrorText(sc),!
        w "GetOneStatusText:"_$System.Status.GetOneStatusText(sc),!
        q $System.Status.GetErrorText(sc)
    }
}

DHC-APP>w ##class(PHA.TEST.AdvancedConcepts).Status5(0)
errorlist=1
errorlist(1)="错误 #5001: 这是一条错误信息！"
errorlist(1,"caller")="zStatus4+2^PHA.TEST.AdvancedConcepts.1"
errorlist(1,"code")=5001
errorlist(1,"dcode")=5001
errorlist(1,"domain")="%ObjectErrors"
errorlist(1,"namespace")="DHC-APP"
errorlist(1,"param")=1
errorlist(1,"param",1)="这是一条错误信息！"
errorlist(1,"stack")=$lb("e^zStatus4+2^PHA.TEST.AdvancedConcepts.1^1","e^zStatus5+1^PHA.TEST.AdvancedConcepts.1^1","e^^^0")
GetErrorCodes:5001
GetOneErrorText:错误 #5001: 这是一条错误信息！
GetOneStatusText:这是一条错误信息！
错误 #5001: 这是一条错误信息！