Handling SOAP Faults and Other Errors in a Caché Web Client

In a Caché web client, you can use the TRY-CATCH mechanism or the older $ZTRAP mechanism.

In either case, when a Caché web client receives an error, Caché sets the special variables $ZERROR and %objlasterror:

If the error is a SOAP fault, the value of $ZERROR starts with <ZSOAP>, and %objlasterror contains the status error that is formed from the received SOAP fault.
In addition, the client instance has a property named SoapFault, which is an instance of %SOAP.FaultOpens in a new tab or %SOAP.Fault12Opens in a new tab (depending on the SOAP version used in the web service). You can use the information in this property. For more information on %SOAP.FaultOpens in a new tab and %SOAP.Fault12Opens in a new tab, see the previous sections.
If the error is not a SOAP fault, use your normal error handling (typically using $ZERROR). It is your responsibility to specify how to proceed.

Example 1: Try-Catch

The following method uses TRY-CATCH:

ClassMethod Divide(arg1 As %Numeric, arg2 As %Numeric) As %Numeric
{
    Set $ZERROR=""
    Set client=##class(FaultClient.DivideSoap).%New()

    Try {
        Set ans=client.Divide(arg1,arg2)
        }
    Catch {
        If $ZERROR["<ZSOAP>" {
            Set ans=%objlasterror
            } 
            Else {
            Set ans=$$$ERROR($$$CacheError,$ZERROR)
        }
    }
    
    Quit ans
}

This method uses system macros defined in the %systemInclude include file, so the class that contains this method starts with the following:

Include %systemInclude

Example 2: $ZTRAP

The following example uses the older $ZTRAP mechanism. In this case, when a Caché web client receives an error, control is transferred to the label indicated by the $ZTRAP special variable (if that label is defined).

ClassMethod DivideWithZTRAP(arg1 As %Numeric = 1, arg2 As %Numeric = 2) As %Numeric
{
    Set $ZERROR=""
    Set $ZTRAP="ERRORTRAP"
    Set client=##class(FaultClient.DivideSoap).%New()
    Set ans=client.Divide(arg1,arg2)
    Quit ans
 
    //control goes here in case of error
ERRORTRAP 
    if $ZERROR["<ZSOAP>" 
    {
         quit client.SoapFault.Detail
        } 
    else 
    {
        quit %objlasterror
       }
}

SSL Handshake Errors

If a Caché web client uses an SSL connection and a SSL handshake error has occurred, then the SSLError property of the client contains text that describes the SSL error.