Creating a web service requester using the web services assistant

You can create a service requester application from a web service description that complies with WSDL 1.1 or WSDL 2.0. The CICS® web services assistant helps you to deploy your CICS applications in a service requester setting.

1. Use the DFHWS2LS batch program to generate a web service binding file and one or more language structures.
   Consider these options when creating a service requester application from a web service description:
   • Which mapping level do you want to use? The higher the mapping level, the more control and support you have available for the handling of character and binary data at run time. Some optional parameters are available only at the higher mapping levels. You are recommended to use the highest level of mapping available.
   • Which code page do you want to use when transforming data at run time? If you want to use a specific code page for your application that is different from the code page for the CICS region, use the CCSID parameter.
   • Do you want to support a subset of the operations that are declared in the web service description? If you have a very large web service description, and want your service requester application to support only a certain number of operations, use the OPERATION parameter to list the ones you want. Each operation must be separated with a space and is case sensitive.
   • Where is the WSDL document stored? If the WSDL document that you want to use as input to DFHWS2LS is stored on a WSRR server, you can retrieve it by running DFHWS2LS with certain parameters specified. Use the WSRR-SERVER parameter to specify the location of the WSRR server and use the WSRR-NAME parameter to specify the name of the WSDL document that you want to retrieve. For information about other parameters on DFHWS2LS that you might want to use to interact with WSRR, see DFHWS2LS: WSDL to high-level language conversion.
   • If you want to retrieve the WSDL document from a WSRR server, do you want to do so using a secure connection? You can use secure socket layer (SSL) encryption with the web services assistant to interoperate securely with WSRR. For an example, see Example of how to use SSL with the web services assistant and WSRR.

   Do not specify parameters such as PROGRAM , URI , TRANSACTION , and USERID when you use DFHWS2LS. These parameters apply only to a service provider application and, if specified, cause a provider mode web service binding file to be produced.

   In addition to the web service binding file, the program generates a language data structure.
2. Check the log file to see whether any problems occurred when DFHWS2LS generated the binding file and language structures.
   CICS might not support some elements or options in the web service description. If any warning or error messages are issued, read the advice that is provided and take appropriate action. You might need to rerun the batch program.
3. Copy the web service binding file to the pickup directory of the requester mode pipeline that you want to use for your web service application.
4. Ensure that the PIPELINE resource is configured for service requester applications.
   The value of the MODE parameter shows whether the pipeline supports requester or provider web service applications.
5. Ensure that the correct SOAP protocol is supported in the pipeline for your web service.
   The SOAPLEVEL parameter indicates which version is supported. In service requester mode, the binding of the web service must match the version of SOAP that is supported in the pipeline. You cannot install a web service with a SOAP 1.1 binding into a service requester pipeline that supports SOAP 1.2.
6. Ensure that the configured timeout for the pipeline is suitable for your service requester application.
   The timeout is displayed as the value of the RESPWAIT attribute on the PIPELINE resource. If no timeout is specified on the pipeline, the default for the transport is used.

   • The default timeout for HTTP is 10 seconds.
   • The default timeout for WebSphere MQ is 60 seconds.

   Each transaction in the CICS region has a dispatcher timeout. If this value is less than the default for either protocol, the timeout occurs with the dispatcher.
7. Optional: Copy the web service description to the same pickup directory as the web service binding file, so that you can turn on validation for the web service at run time.
8. Create the WEBSERVICE resource. This resource encapsulates the web service binding file in CICS and is used at run time.

   You can do this in the following ways:

   1. Using the PIPELINE SCAN command to dynamically create the WEBSERVICE resource.
   2. Defining the resource yourself. If you use the CICS Explorer® to define a WEBSERVICE resource in a CICS bundle, you can choose to import a web service binding file and a WSDL document or WSDL archive file and include these in the bundle. You can then generate URIMAP definitions to support the web service and package these in a bundle. For more help with using the CICS Explorer to create and edit resources in CICS bundles, see Working with bundles in the CICS Explorer product documentation.
9. Write a wrapper program that you can substitute for your communications logic. Use the language data structure generated in step 1 to write your wrapper program.
   Use an EXEC CICS INVOKE SERVICE command in your wrapper program to communicate with the web service. The command includes these options:

   • The URI of the web service
   • The operation for which the web service is being called
   When you call the web service, you can specify a URIMAP resource that contains the information about the URI of the web service. You can specify this information directly on the INVOKE SERVICE command instead of using a URIMAP resource. However, using a URIMAP resource means that you do not need to recompile your applications if the URI of a service provider changes. With a URIMAP resource you can also choose to implement connection pooling, where CICS keeps the client connection open after use, so that it can be reused by the application for subsequent requests, or by another application that calls the same service. The PIPELINE SCAN command does not create URIMAP resources for a service requester, so you must define the URIMAP resource yourself following the instructions in Creating a URIMAP resource for CICS as a HTTP client.