Use %Status value

许多类使用 %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([email protected],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([email protected],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([email protected],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([email protected],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([email protected],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: 这是一条错误信息！

复制