Creating an XML-aware service requester application

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

  1. 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.
  2. 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.
  3. 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.