Creating an XML-aware service provider application

Your XML-aware service provider application must work with the containers that are passed to it and handle the data conversion between the XML and the program language.

1. Decide if you want to generate a web service binding file for your XML-aware application using DFHWS2LS.
   The advantage of generating a web service binding file is that you can use CICS services, such as validation, to test your web service and CICS monitoring using global user exits.
   • If you want to generate a web service binding file, run DFHWS2LS specifying the XML-ONLY parameter and a MINIMUM-RUNTIME-LEVEL of 2.1 or higher. The web service binding file enables the application program to work directly with the contents of the DFHWS-BODY container. In all other respects, the generated binding file shares the same deployment characteristics and the same runtime behavior as a file generated without the XML-ONLY parameter, including parsing of the XML during SOAP message handling. To prevent this parsing, you must not specify SOAP message handlers in your pipeline configuration file.
   • If you do not want to use a web service binding file, configure your service provider pipeline so that the web service request reaches your XML-aware application. You can either configure the terminal handler in the pipeline configuration file to use your XML-aware application program or create a message handler that dynamically switches to your application depending on the URI that is received in the pipeline.
2. Write your application to handle the web service request that is held in the following containers:

   DFHWS-BODY

   The contents of the SOAP body for an inbound SOAP request when the pipeline includes a CICS-provided SOAP message handler.

   DFHREQUEST

   The complete request, including the envelope for a SOAP request, received from the pipeline.

   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 associated with the SOAP message in container DFHWS-BODY.

   When you code API commands to work with the containers, do not specify the CHANNEL option, because all the containers are associated with the current channel (the channel that was passed to the program). If you need to know the name of the channel, use the EXEC CICS ASSIGN CHANNEL command.

3. Optional: Your application can also use additional containers that are available to message handlers in the pipeline, as well as any other containers that the message handlers create as part of their processing.
   For a complete list of containers, see Containers used in web services pipelines.
4. When your application has processed the request, construct a web service response using the following containers:

   DFHRESPONSE

   The complete response 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 instead of using the CICS-provided SOAP message handler.

   If you supply a SOAP body in container DFHWS-BODY, DFHRESPONSE is ignored.

   DFHWS-BODY

   For an outbound SOAP response, the contents of the SOAP body. Provide this container when the terminal handler of your pipeline is a CICS-provided SOAP message handler. The message handler constructs the full SOAP message containing the body.

   Your program must create this container, even if the request and response are identical. If you do not, CICS issues an internal server error.

   You can also use any of the other containers to pass information that your pipeline needs for processing the outbound response.

   If your web service does not return a response, you must return container DFHNORESPONSE to indicate that there is no response. The contents of the container are unimportant, because the message handler checks only whether the container is present or not.

5. Create a URIMAP resource.
   If you are using the XML-ONLY parameter and you have specified a value for the URI parameter of DFHWS2LS, the URIMAP is created automatically for you during the PIPELINE SCAN process.