%Status Error Processing

%Status Error Processing

Many of the methods in the Caché class library return success or failure information via the %StatusOpens in a new tab data type. For example, the %Save() method, used to save an instance of a %PersistentOpens in a new tab object, returns a %StatusOpens in a new tab value indicating whether or not the object was saved.

• Successful method execution returns a %StatusOpens in a new tab of 1.

• Failed method execution returns %StatusOpens in a new tab as an encoded string containing the error status and one or more error codes and text messages. Status text messages are localized for the language of your locale.

You can use %SYSTEM.StatusOpens in a new tab class methods to inspect and manipulate %StatusOpens in a new tab values.

Caché provides several options for displaying (writing) the %StatusOpens in a new tab encoded string in different formats. For further details, refer to “Display (Write) Commands” in the “Commands” chapter of this manual.

In the following example, the %Prepare fails because of an error in the myquery text: “ZOP” should be “TOP”. This error is detected by the IsError()Opens in a new tab method, and other %SYSTEM.StatusOpens in a new tab methods display the error code and text:

  ZNSPACE "SAMPLES"
  SET myquery = "SELECT ZOP 5 Name,DOB FROM Sample.Person"
  SET tStatement = ##class(%SQL.Statement).%New()
  SET status = tStatement.%Prepare(myquery)
  IF ($System.Status.IsError(status)) {
      WRITE "%Prepare failed",!
      DO StatusError() }
  ELSE {WRITE "%Prepare succeeded",!
        RETURN }
StatusError()
  WRITE "Error #",$System.Status.GetErrorCodes(status),!
  WRITE $System.Status.GetOneStatusText(status,1),!
  WRITE "end of error display"
  QUIT

The following example is the same as the previous, except that the status error is detected by the $$$ISERR() macro of the %occStatus include file. $$$ISERR() (and its inverse, $$$ISOK()) checks whether or not %StatusOpens in a new tab=1. The error code is returned by the $$$GETERRORCODE() macro:

#include %occStatus
  ZNSPACE "SAMPLES"
  SET myquery = "SELECT ZOP 5 Name,DOB FROM Sample.Person"
  SET tStatement = ##class(%SQL.Statement).%New()
  SET status = tStatement.%Prepare(myquery)
  IF $$$ISERR(status) {
      WRITE "%Prepare failed",!
      DO StatusError() }
  ELSE {WRITE "%Prepare succeeded",!
        RETURN}
StatusError()
  WRITE "Error #",$$$GETERRORCODE(status),!
  WRITE $System.Status.GetOneStatusText(status,1),!
  WRITE "end of error display"
  QUIT

These system-supplied macros are further described in the “ObjectScript Macros and the Macro Preprocessor” chapter of this book.

Some methods, such as %New(), generate, but do not return a %StatusOpens in a new tab. %New() either returns an oref to an instance of the class upon success, or the null string upon failure. You can retrieve the status value for methods of this type by accessing the %objlasterror system variable, as shown in the following example.

  SET session = ##class(%CSP.Session).%New()
  IF session="" {
      WRITE "session oref not created",!
      WRITE "%New error is ",!,$System.Status.GetErrorText(%objlasterror),! }
  ELSE {WRITE "session oref is ",session,! }

For more information, refer to the %SYSTEM.StatusOpens in a new tab class.

Creating %Status Errors

You can invoke system-defined %Status errors from your own methods by using the Error()Opens in a new tab method. You specify the error number that corresponds to the error message you wish to return.

  WRITE "Here my method generates an error",!
  SET status = $System.Status.Error(20)
  WRITE $System.Status.GetErrorText(status),!

You can include %1, %2, and %3 parameters in the returned error message, as shown in the following example:

  WRITE "Here my method generates an error",!
  SET status = $System.Status.Error(214,"3","^fred","BedrockCode")
  WRITE $System.Status.GetErrorText(status),!

You can localize the error message to display in your preferred language.

  SET status = $System.Status.Error(30)
  WRITE "In English:",!
  WRITE $System.Status.GetOneStatusText(status,1,"en"),!
  WRITE "In French:",!
  WRITE $System.Status.GetOneStatusText(status,1,"fr"),!

For a list of error codes and messages (in English), refer to the “General Error Messages” chapter of the Caché Error Reference.

You can use the generic error codes 83 and 5001 to specify a custom message that does not correspond to any of the general error messages.

You can use the AppendStatus()Opens in a new tab method to create a list of multiple error messages. Then you can use GetOneErrorText()Opens in a new tab or GetOneStatusText()Opens in a new tab to retrieve individual error messages by their position in this list:

CreateCustomErrors
  SET st1 = $System.Status.Error(83,"my unique error")
  SET st2 = $System.Status.Error(5001,"my unique error")
  SET allstatus = $System.Status.AppendStatus(st1,st2)
DisplayErrors
  WRITE "All together:",!
  WRITE $System.Status.GetErrorText(allstatus),!!
  WRITE "One by one",!
  WRITE "First error format:",!
  WRITE $System.Status.GetOneStatusText(allstatus,1),!
  WRITE "Second error format:",!
  WRITE $System.Status.GetOneStatusText(allstatus,2),!