By default, when your Caché web service encounters an error, it returns a standard SOAP message containing a fault. The following shows an example (for SOAP 1.1). The SOAP envelope is omitted in this example:

Call the ReturnFault() method of the web service, passing the fault object as an argument. Note that ReturnFault()) does not return to its caller; it just sends the fault and terminates processing of the web method.

The following shows an example:

MethodDivide(arg1As%Numeric,arg2As%Numeric)As%Numeric[WebMethod]{Try{Setans=arg1/arg2}Catch{//<detail> element must contain element(s) or whitespace//specify this element by passing valid XML as string argument to MakeFault() setmydetail="<mymessage>Division error detail</mymessage>"setfault=..MakeFault($$$FAULTServer,"Division error",mydetail)// ReturnFault must be called to send the fault to the client.// ReturnFault will not return here.Do..ReturnFault(fault)}Quitans}

pFaultString is used within the <faultstring> element of the SOAP fault. Specify a string that indicates the reason for the fault, as intended for users to see.

pDetail is used within the <detail> element of the SOAP fault. Use this to specify information about the cause of the fault.

If specified, this argument should be a string containing valid XML that can be used within the <detail> element. Caché does not verify that the string you provide is valid; it is the responsibility of your application to check this.

pFaultActor specifies the URI of the SOAP node on the SOAP message path that caused the fault to happen.

This is useful if the SOAP message travels through several nodes in the SOAP message path, and the client needs to know which node caused the error. It is beyond the scope of this book to discuss this advanced topic.

The SOAP include file (%soap.inc) defines macros for some of the standard SOAP fault codes; these are listed in the following table. You can use these macros to specify SOAP fault codes. The table notes the version or versions of SOAP to which each macro applies.

If you need more control than is given by the steps in the previous section, you can create and return a custom SOAP fault as follows:

Create a fault object manually.

To do so, create an instance of %SOAP.Fault (for SOAP 1.1) or %SOAP.Fault12 (for SOAP 1.2) and then set its properties, as described in the following sections.

Note:

You can use %SOAP.Fault in all cases. If a web service receives a SOAP 1.2 request and needs to return a fault, the web service automatically converts the fault to SOAP 1.2 format.

Call the ReturnFault() method of the web service, passing the fault object as an argument. Note that ReturnFault()) does not return to its caller; it just sends the fault and terminates processing of the web method.

Used within the <detail> element of the SOAP fault. Use this to specify information about the cause of the fault.

If specified, this argument should be a string containing valid XML that can be used within the <detail> element. Caché does not verify that the string you provide is valid; it is the responsibility of your application to check this.

Specifies the URI of the SOAP node on the SOAP message path that caused the fault to happen.

This is useful if the SOAP message travels through several nodes in the SOAP message path, and the client needs to know which node caused the error. It is beyond the scope of this book to discuss this advanced topic.

Used within the <detail> element of the SOAP fault. Use this to specify information about the cause of the fault.

If specified, this argument should be a string containing valid XML that can be used within the <detail> element. Caché does not verify that the string you provide is valid; it is the responsibility of your application to check this.

Specifies the URI of the SOAP node on the SOAP message path that caused the fault to happen; optional for the destination node.

This is useful if the SOAP message travels through several nodes in the SOAP message path, and the client needs to know which node caused the error. It is beyond the scope of this book to discuss this advanced use of SOAP.

A list of instances of %SOAP.Fault12.Text, discussed in a following section. Each instance contains a reason string and a language code that indicates the language or locality of the reason string. These are used within the <Reason> element.

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.Fault or %SOAP.Fault12 (depending on the SOAP version used in the web service). You can use the information in this property. For more information on %SOAP.Fault and %SOAP.Fault12, 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.

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