Working with %Status Values

Basics of Working with Status Values

As noted above, methods in many InterSystems classes return a status to indicate success or error. For example, the %Save() method in %Library.PersistentOpens in a new tab returns a status. For any such method, be sure to obtain the returned value. Then check the status and then proceed appropriately. The basic tools are as follows:

• To check whether the status represents success or error, use any of the following:

  • The $$$ISOK and $$$ISERR macros, which are defined in the include file %occStatus.inc. This include file is automatically available in all object classes.

  • The $SYSTEM.Status.IsOK() and $SYSTEM.Status.IsError() methods, which are especially convenient in the Terminal (where you cannot use macros).

• To display the error details, use $SYSTEM.OBJ.DisplayError() or $SYSTEM.Status.DisplayError(). These methods are equivalent to each other. They write output to the current device.

• To obtain a string that contains the error details, use $SYSTEM.Status.GetErrorText().

Examples

For example:

 Set object=##class(Sample.Person).%New()
 Set object.Name="Smith,Janie"
 Set tSC=object.%Save()
 If $$$ISERR(tSC) {
   Do $SYSTEM.OBJ.DisplayError(tSC)
   Quit
 } 

Here is a partial example that shows use of $SYSTEM.Status.GetErrorText():

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

Multiple Errors Reported in a Status Value

If a status value represents multiple errors, the techniques give you information about only the latest. To obtain information about all the errors represented by a status value, use $SYSTEM.Status.DecomposeStatus(), which returns an array of the error details (by reference, as the second argument). For example:

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

The variable errorlist is an array that contains the error information. The following shows a partial example with some artificial line breaks for readability:

ZWRITE errorlist
errorlist=2
errorlist(1)="ERROR #5659: Property 'Sample.Person::SSN(1@Sample.Person,ID=)' required"
errorlist(1,"caller")="%ValidateObject+9^Sample.Person.1"
errorlist(1,"code")=5659
errorlist(1,"dcode")=5659
errorlist(1,"domain")="%ObjectErrors"
errorlist(1,"namespace")="SAMPLES"
errorlist(1,"param")=1
errorlist(1,"param",1)="Sample.Person::SSN(1@Sample.Person,ID=)"
...
errorlist(2)="ERROR #7209: Datatype value '' does not match 
PATTERN '3N1""-""2N1""-""4N'"_$c(13,10)_"  > 
ERROR #5802: Datatype validation failed on property 'Sample.Person:SSN', 
with value equal to """""
errorlist(2,"caller")="zSSNIsValid+1^Sample.Person.1"
errorlist(2,"code")=7209
...

If you wanted to log each error message, you could adapt the previous logging example as follows:

 If $$$ISERR(tSC) {
   // if error, log error message so users can see them
   Do $SYSTEM.Status.DecomposeStatus(tSC,.errorlist)
   For i=1:1:errorlist {
       Do ..LogMsg(errorlist(i))
   }
 }

Returning Status Values

You can also return your own custom status value. To create a status value, use the following construction:

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

Or equivalently:

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

For example:

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

To include information about additional errors, use $SYSTEM.Status.AppendStatus() to modify the status value. For example:

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

For More Information

For more information, see the class reference for the %SYSTEM.StatusOpens in a new tab class and the %Library.StatusOpens in a new tab class.