Creating a service provider application from a web service description

Using the CICS® web services assistant, you can create a service provider application from a web service description that complies with WSDL 1.1 or WSDL 2.0.

Before you begin

Before you can create a service provider application, the following conditions must be satisfied:
  • Your web services description must be in a UNIX file in z/OS® and you must create a suitable provider mode pipeline in the CICS region.
  • You must define to OMVS the user ID under which DFHWS2LS runs.
  • The user ID must have read permission to z/OS UNIX and PDS libraries and write permission to the directories specified on the LOGFILE , WSBIND , and WSDL parameters.
  • You must allocate sufficient storage to the user ID for the ID to run Java™ . You can use any supported version of Java . By default, DFHWS2LS uses the Java version specified in the JAVADIR parameter.

About this task

You can use the web services assistant to create language structures from your WSDL for the service provider application. You can also use a WSDL document that is stored in an IBM® webSphere Service Registry and Repository (WSRR) server.

Procedure

  1. Use the DFHWS2LS batch program to generate a web service binding file and one or more language data structures. DFHWS2LS contains a large set of optional parameters that provide you with flexibility to create the binding file and language structures that your application requires. Consider these options when you enable an existing application for web services:
    1. Which mechanism will CICS use to pass data to the service provider application program?
      • You can use channels and pass the data in containers or use a COMMAREA. Channels and containers are recommended. Specify them with the PGMINT parameter.
    2. Which language do you want to generate?
      • DFHWS2LS can generate COBOL, C/C++, or PL/I language data structures. Specify the language using the LANG parameter.
    3. 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. Specify the mapping level with the MAPPING-LEVEL parameter.
    4. Which URI do you want the web service requester to use?
      • Specify a relative URI using the URI parameter; for example, URI=/my/test/webservice . The value is used by CICS when it creates the URIMAP resource.
    5. Under which transaction and user ID will you run the web service request and response?
      • You can use an alias transaction to run the application to compose a response to the service requester. The alias transaction is attached under the user ID.
      • Specify it with the TRANSACTION and USERID parameters. These values are used when creating the URIMAP resource. If you do not want to use a specific transaction, do not use these parameters.
    6. Where is the WSDL document stored?
      • If you want to retrieve a WSDL document from a WSRR server, instead of from the local file system, you must specify certain parameters in DFHWS2LS.
      • As a minimum, you must specify the WSRR-SERVER parameter with the location of the WSRR server and the WSRR-NAME parameter with the name of the WSDL document that you want to retrieve from WSRR.
      • For information about other parameters that you might want to specify if you are using WSRR, see DFHWS2LS: WSDL to high-level language conversion.
    7. If you intend to retrieve your WSDL document from a WSRR server, do you want to do so using a secure connection?
    • When you submit DFHWS2LS, CICS generates the web service binding file and places it in the location that you specified with the WSBIND parameter. The language structures are placed in the partitioned data set that you specified with the PDSLIB parameter.
  2. Copy the generated web service binding file to the pickup directory of the provider mode PIPELINE resource that you want to use for your web service application. You must copy the binding file in binary mode.
  3. Optional: Copy the web service description or the archive file containing one or more web service descriptions to the same directory as the web service binding file. The archive file must be a .zip file and the file name must match the WSDL file name. With this copy, you can discover the WSDL.
  4. Write a service provider application program to interface with the generated language structures and implement the required business logic.
  5. Create the WEBSERVICE resource and two URIMAP resources.
    • The WEBSERVICE resource encapsulates the web service binding file in CICS and is used at run time.
    • The first URIMAP resource provides CICS with the information to associate the WEBSERVICE resource with a specific URI.
    • The second URIMAP resource provides CICS with the information to associate the WSDL archive file or WSDL document with a specific URI.
      • This URI has the same path as the URI associated with the WEBSERVICE with the suffix ?wsdl appended.
      • This URIMAP resource is created so that external requesters can use the URI to discover the WSDL archive file or WSDL document.
      • This URIMAP resource is created only if the web service description or the archive file containing one or more web service descriptions has been copied to the same directory as the web service binding file.
      • If the pickup directory contains a WSDL archive file and a WSDL document, the URI returns only the WSDL in the archive file.
      • This function is only available for web services installed using the pipeline scan operation.

    You can create the resources in the following ways:

    1. Using the PIPELINE SCAN command to dynamically create the WEBSERVICE resource and URIMAP resources.
    2. Defining the resources 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 the 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.

Results

If you have any problems submitting DFHWS2LS, or the resources do not install correctly, see Diagnosing deployment errors.


dfhws_deployProviderFromWsdl.html | Timestamp icon Last updated: Monday, 5 June 2017