Sending a SOAP fault

In a service provider, you can use the CICS API to send a SOAP fault to a web service requester. The fault can be issued by the service provider application or by a header processing program in the pipeline.

Before you begin

To use the API, the service provider application must use channels and containers. If the application uses COMMAREAs, write a wrapper program that does use channels and containers to create the SOAP fault message. You can use the API in a header processing program only if it is invoked directly from a CICS-supplied SOAP message handler.

About this task

You might want to issue a SOAP fault to the web service requester if your application logic cannot satisfy the request, for example, or if there is an underlying problem with the request message. Note that CICS does not consider issuing a SOAP fault as an error, so the normal message response pipeline processing takes place rather than any error processing. If you do want to roll back any transactions, you must use the application program.

Procedure

In your program, use the EXEC CICS SOAPFAULT CREATE command to send a SOAP fault, see SOAPFAULT CREATE.
Add the CLIENT or SERVER option on the command.
This option indicates where the problem has occurred, either on the client side or on the server.
- CLIENT indicates that the problem is with the request message that was received.
- SERVER indicates that the problem occurs when the request message was processed by CICS. This problem might be in an application program, for example, it might be unable to satisfy the request, or it might be an underlying problem that occurs during the pipeline processing.
Add the FAULTSTRING option and its length in the FAULTSTRLEN option to provide a summary of why the fault has been issued by the service provider.
The contents of this option are in XML. Any data supplied by the application must be in a format that is suitable for direct inclusion in an XML document. The application might have to specify some characters as XML entities.
For example, if the < character is used anywhere other than the start of an XML tag, the application must change it to <. The following example shows an incorrect FAULTSTRING option:
```
dcl msg_faultString char(*) constant('Error: Value A < Value B');
```
The correct way to specify this FAULTSTRING option is as follows:
```
dcl msg_faultString char(*) constant('Error: Value A &lt; Value B');
```
Tip: To avoid using XML entities, you can wrapper the data in an XML CDATA construct. XML processors do not parse character data in this construct. Using this method, you could specify the following FAULTSTRING option:
```
dcl msg_faultString char(*) constant('<![CDATA[Error: Value A < Value B]]>');
```
Code the DETAIL option and its length in the DETAILLENGTH option to provide the details of why the fault has been issued by the service provider.
The contents of this option are in XML. The same guidance applies to the DETAIL option as to the FAULSTRING option.
Optional: If you are invoking the API from a header processing program, define the program in the pipeline configuration file.
The header processing program is defined in either the <cics_soap_1.1_handler>, <cics_soap_1.2_handler>, <cics_soap_1.1_handler_java> or <cics_soap_1.2_handler_java> element.

Results

When your program issues this command, CICS creates the SOAP fault response message at the appropriate SOAP level. If your service provider application issues the command, it does not need to create a SOAP response and put it in the DFHRESPONSE container. The pipeline processes the SOAP fault through the message handlers and sends the response to the web service provider.

Example

The SOAPFAULT CREATE command has a number of options to provide you with flexibility to respond appropriately to a web service requester. Here is a simple example of a completed command that creates a SOAP fault that can be used for both SOAP 1.1 and SOAP 1.2:

EXEC CICS SOAPFAULT CREATE CLIENT
     DETAIL(msg_detail)
     DETAILLENGTH(length(msg_detail))
     FAULTSTRING(msg_faultString)
     FAULTSTRLEN(length(msg_faultString));

You can code msg_detail and msg_faultString with the following values:

dcl msg_detail char(*) constant('<ati:ExampleFault xmlns="http://www.example.org/faults" 
xmlns:ati="http://www.example.org/faults">Detailed error message goes here.</ati:ExampleFault>'); 
dcl msg_faultString char(*) constant('Something went wrong');