Learning
Community
Open Exchange
Global Masters
InterSystems IRIS Data Platform 2019.3 / All Documentation / Working with %Status Values

Working with %Status Values

Many InterSystems classes use the %Status data type class to represent status information, and their methods return a %Status value (a status) that represents either success or error. If the status represents an error (or multiple errors), the status value also includes information about the errors.
You can also return your own status values.
This article discusses status values and how to work with them.

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.Persistent 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.Status class and the %Library.Status class.