文章目录

第二十三章 使用 %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")

例如：

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

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

=$SYSTEM.Status.AppendStatus(tSCfirst,tSCsecond)
/// 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: