Introducing a way to create user-defined errors
InterSystems FAQ rubric
To create a user-defined error you need to prepare the XML that describes the error code and corresponding message that you want to use as a user-defined error.
Please set the error code as a negative integer.
<?xml version="1.0" encoding="UTF-8"?>
<MsgFileLanguage="en"><MsgDomainDomain="UserErrors"><MessageId="-111"Name="MyError">An error has occured</Message>
<MessageId="-222"Name="MyError2">An error has occured 2</Message>
</MsgDomain></MsgFile>Once the XML file is created, load it into the namespace you want to use.
setx=##class(%MessageDictionary).Import("error.xml")Once loaded, you can retrieve and display user-defined errors with a command like the following:
USER>set error=$system.Status.Error(-111) // Create error with error code -111
USER>write$system.Status.GetErrorText(error) // Output error message from error
Error <UserErrors>-111: An error has occurred
USER>do$system.Status.DecomposeStatus(error,.val) // Set error information to array variable
USER>zwrite val
val=1
val(1)="Error <UserErrors>-111: An error has occurred"
val(1,"caller")="zError+1^%SYSTEM.Status.1"
val(1,"code")=-111
val(1,"dcode")=-111
val(1,"domain")="UserErrors"
val(1,"namespace")="TEST"
val(1,"param")=0
val(1,"stack")=$lb("e^zError+1^%SYSTEM.Status.1^1","e^^^0")Comments
Is UserErrors a magic string that somehow connects the message dictionary with $system.Status?
I don't see the string mentioned in https://docs.intersystems.com/irislatest/csp/docbook/DocBook.UI.Page.cls?KEY=GSTRLOC_msgdict nor anywhere in the documentation.
I was able to google https://community.intersystems.com/post/registering-new-error-code-and-error-message that seems identical to this post.
It seems the "UserErrors" domain name is the default name of user-defined errors, although it isn't written in the document.
I tested below:
<?xml version="1.0" encoding="UTF-8"?>
<MsgFileLanguage="en"><MsgDomainDomain="UserErrorsABCDEFG"><MessageId="-911"Name="MyError">Test!!An error has occured</Message>
<MessageId="-922"Name="MyError2">Test!!An error has occured 2</Message>
</MsgDomain></MsgFile>setx=##class(%MessageDictionary).Import("/src/test.xml")
set error=$system.Status.Error("<UserErrorsABCDEFG>-911")
set error=$system.Status.Error("<UserErrorsABCDEFG>-911")
write$system.Status.GetErrorText(error)
//ERROR <UserErrorsABCDEFG>-911: Test!!An error has occuredIf you don't add default domain name, you can get the correct user message by specifying the domain name with the error id to create the error messsage.