Articles
Working with %Status Values
[Home]  
InterSystems: The power behind what matters   
Class Reference   
Search:    

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:
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.