The SOAP <Fault> element carries error
and status information in the SOAP message.
If an error occurs in a web service, a fault message is returned
to the client. The basic structure of the fault message is defined
in the SOAP specifications. Each fault message can include XML that
describes the specific error condition. For example, if an application
abend occurs in a CICS web service, a fault message is returned to
the client reporting the abend.
CICS can send different types of fault message:
- Standard SOAP fault messages are defined by the SOAP specifications
or one of the web service specifications that are supported in CICS.
The faults report common error conditions, such as malformed SOAP
envelopes.
- Application SOAP fault messages are generated using the EXEC
CICS SOAPFAULT API commands in response to conditions that
are detected or handled by the application. The structure of these
fault messages is known to the application, but not to CICS.
- SOAP handler fault messages are generated by the SOAP handler
programs in response to general error handling in CICS. For example,
the SOAP handler programs send SOAP faults for abends, XML parsing
failures, and other common errors.
- Application handler fault messages are generated by
CICS SOAP application handlers in response to finding errors when
processing the body of a SOAP message. These faults occur during the
process of transforming the XML into binary application data or when
generating the response.
If an error occurs, the SOAP <Fault> element
must be a body entry and must not be present more than once in a <Body> element.
The XML elements inside the SOAP <Fault> element
are different in SOAP 1.1 and SOAP 1.2.
SOAP 1.1
In SOAP 1.1, the SOAP
<Fault> element
contains the following elements:
- <faultcode>
- The <faultcode> element is a mandatory element
in the <Fault> element. It provides information
about the fault in a form that can be processed by software. SOAP
defines a small set of SOAP fault codes covering basic SOAP faults,
and this set can be extended by applications.
- <faultstring>
- The <faultstring> element is a mandatory element
in the <Fault> element. It provides information
about the fault in a form intended for a human reader.
- <faultactor>
- The <faultactor> element contains the URI
of the SOAP node that generated the fault. A SOAP node that is not
the ultimate SOAP receiver must include the <faultactor> element
when it creates a fault. An ultimate SOAP receiver is not obliged
to include this element, but may do so.
- <detail>
- The <detail> element carries application-specific
error information related to the <Body> element.
It must be present if the contents of the <Body> element
were not successfully processed. It must not be used to carry information
about error information belonging to header entries. Detailed error
information belonging to header entries must be carried in header
entries.
SOAP 1.2
In SOAP 1.2, the SOAP
<Fault> element
contains the following elements:
- <Code>
- The <Code> element is a mandatory element
in the <Fault> element. It provides information
about the fault in a form that can be processed by software. It contains
a <Value> element and an optional <Subcode> element.
- <Reason>
- The <Reason> element is a mandatory element
in the <Fault> element. The <Reason> element
contains one or more <Text> elements, each of
which contains information about the fault in a different native language.
- <Node>
- The <Node> element contains the URI of the
SOAP node that generated the fault. A SOAP node that is not the ultimate
SOAP receiver must include the <Node> element
when it creates a fault. An ultimate SOAP receiver is not obliged
to include this element, but may do so.
- <Role>
- The <Role> element contains a URI that identifies
the role in which the node was operating at the point the fault occurred.
- <Detail>
- The <Detail> element is an optional element,
which contains application-specific error information related to the
SOAP fault codes describing the fault. The presence of the <Detail> element
has no significance regarding which parts of the faulty SOAP message
were processed.
SOAP fault example and schemas
The following
example shows a SOAP fault message that is generated by the application
handler, DFHPITP, when processing the body of a SOAP message.
<SOAP-ENV:Fault xmlns="">
<faultcode>SOAP-ENV:Server</faultcode>
<faultstring>Conversion to SOAP failed</faultstring>
<detail>
<CICSFault xmlns="http://www.ibm.com/software/htp/cics/WSFault">
DFHPI1008 25/01/2010 14:16:50 IYCWZCFU 00340 XML
generation failed because of incorrect input
(CONTAINER_NOT_FOUND container name) for WEBSERVICE
servicename.
</CICSFault>
</detail>
</SOAP-ENV:Fault>
Most of the content in this example
is common to all fault messages. The <Detail> element
contains the unique information that describes the problem that was
encountered by the application handler. This specific fault message
contains a copy of an error message that is written to the CICS message
logs. If you want to parse application handler SOAP faults programmatically,
use the following XML schema:
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.ibm.com/software/htp/cics/WSFault"
xmlns:tns="http://www.ibm.com/software/htp/cics/WSFault"
elementFormDefault="qualified">
<element name="CICSFault" type="string">
<annotation>
<documentation>
The value of this element is a text string that describes a
problem encountered during the processing of the Body of a
SOAP message.
</documentation>
</annotation>
</element>
</schema>
The general purpose fault messages are
more complicated because the <Detail> section
can be structured in several different ways. If you want to parse
SOAP handler faults programmatically, use the XML schema that is supplied
in usshome/schemas/soapfault/soapfault.xsd,
where usshome is the value of the USSHOME system
initialization parameter.