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