Your XML-aware web service requester application handles
the data conversion between the XML and the programming language and
populates the control containers in the pipeline.
Before you begin
You can write your own XML-aware service requester application
using the XML-ONLY parameter on DFHWS2LS or you
can write it without using any of the tooling. The most straightforward
way to write your own XML-aware service requester application is by
using the XML-ONLY parameter on DFHWS2LS; the XML-ONLY parameter
is available at runtime level 2.1 and later.
About this task
Using the XML-ONLY parameter results
in the generation of a WSBind file that instructs CICS® that the application will work directly
with the contents of the DFHWS-BODY container. The generated WSBind
file must be installed into a requester mode PIPELINE to create a
requester mode WEBSERVICE resource. The application must generate
XML for the body of the web service request and store it in the DFHWS-BODY
container. It must then call the EXEC CICS INVOKE SERVICE command.
The outbound message is sent to the web services provider. The body
of the response message is also in the DFHWS-BODY container after
the call completes.
The XML of the response messages is parsed
during SOAP message handling. To prevent this parsing, you must not
specify SOAP message
handlers in your pipeline configuration file.
XML-aware
requester applications can receive SOAP Fault messages back from the
remote provider mode application. In this case, the requester application
is responsible for interpreting the SOAP Fault and distinguishing
it from a regular response message. If the INVOKE SERVICE command
is used with an XML-ONLY WEBSERVICE, CICS does not set the response
code which is normally used to indicate that a SOAP Fault was received.
If
you are writing your own XML-aware service requester application without
using the XML-ONLY option, complete the following
steps:
Procedure
- Create a channel and populate it with containers.
The
control containers must all be populated in CHAR mode.
Provide
the following information in each container:
- DFHWS-PIPELINE
- The name of the PIPELINE resource used for the outbound request.
- DFHWS-URI
- The URI of the target web service
- DFHWS-BODY
- For an outbound SOAP request, the contents of the SOAP body. Provide
this container when the pipeline includes a CICS-provided SOAP message
handler. The message handler constructs the full SOAP message containing
the body.
- DFHREQUEST
- The complete request message to be passed to the pipeline. Use
this container if you do not use SOAP for your messages or if you
want to build the complete SOAP message, including the envelope, in
your program. The pipeline must not include a CICS-provided SOAP message
handler to avoid duplicate SOAP headers being sent in the outbound
message.
- If you supply a SOAP body in container DFHWS-BODY, DFHREQUEST
must be empty. If you supply content in both DFHWS-BODY and DFHREQUEST, CICS uses DFHREQUEST.
- DFHWS-XMLNS
- A list of name-value pairs that map namespace prefixes to namespaces
for the XML content of the request.
- DFHWS-SOAPACTION
- The SOAPAction header to be added to the SOAP message specified
in container DFHWS-BODY.
Tip: If you add container DFHWS-NOABEND
to the channel, when DFHPIRT is called any abends will not be issued
from within DFHPIRT. This is useful if you are running a C/C++ program
because you can handle errors via the DFHERROR container.
- Link to program DFHPIRT.
Use this command:
EXEC CICS LINK PROGRAM(DFHPIRT) CHANNEL(userchannel)
where
userchannel is
the channel that holds your containers.
The outbound
message is processed by the message handlers and header processing
programs in the pipeline and sent to the web service provider.
- Retrieve the containers that contain the web service response
from the same channel.
The response from the web service
provider might be a successful response or a SOAP fault. The web service
requester application must be able to handle both types of response
from the service provider. The complete response is contained in the
following containers:
- DFHRESPONSE
- The complete response, including the envelope for a SOAP response,
received from the web service provider.
- DFHWS-BODY
- When the pipeline includes a CICS-provided SOAP message handler,
the contents of the SOAP body.
- DFHERROR
- Error information from the pipeline.
Note: In some error cases
DFHWS-BODY might not be updated. You must check DFHRESPONSE for a
SOAP fault.