Creating a service provider application from a data structure

Using the CICS® web services assistant, you can create a service provider application from a high-level language data structure.

Before you begin

Before you create a service provider application, make sure that these preconditions have been completed:
  • Your high-level language data structures must meet the following criteria:
    • The data structures must be defined separately from the source program; for example, in a COBOL copybook.
    • If your PL/I or COBOL application program uses different data structures for input and output, the data structures must be defined in two different members in a partitioned data set. If the same structure is used for input and output, the structure must be defined in a single member.

      For C and C++, your data structures can be in the same member in a partitioned data set.

  • The data structures you process depend on whether you are using a wrapper program:
    • If you are using a wrapper program, the copybook is the interface to the wrapper program.
    • If you are not using a wrapper program, the copybook is the interface to the business logic.
  • The language structures must be available in a partitioned data set and you must create a suitable PIPELINE resource in the CICS region:
    • You must define to OMVS the user ID under which DFHLS2WS 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.
    • The user ID must have a sufficiently large storage allocation to run Java™. You can use any supported version of Java. By default, DFHLS2WS uses the Java version specified in the JAVADIR parameter.

Procedure

Follow these steps to create a service provider application from a data structure:

  1. If the service provider application interface uses channels and many containers, create a channel description document that describes the interface in XML. You must put the channel description document in a suitable directory on z/OS UNIX.
    CICS uses this document to construct and deconstruct a SOAP message from the containers on a channel. Alternatively, you can use one container on a channel and not create a channel description document.
  2. Use the DFHLS2WS batch program to generate a web service binding file and web service description from the language structure.
    DFHLS2WS 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 web service enabling an existing application:
    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. Specify the mechanism using the PGMINT parameter. If your application interface uses channels and many containers, specify the REQUEST-CHANNEL parameter and optionally the RESPONSE-CHANNEL. You can only use these parameters when the mapping level is 3.0 or higher.
    2. Which level of web service description (WSDL document) do you want to generate?
      • CICS generates descriptions that comply with either WSDL 1.1 or WSDL 2.0 documents. If you want the service provider application to support requests that comply with both levels of WSDL, specify values for the WSDL_1.1 and WSDL_2.0 parameters. Ensure that the file names are different when using more than one WSDL parameter. This specification produces two web service descriptions and a binding file.
    3. Which version of the SOAP protocol do you want to use?
      • You can specify the version with the SOAPVER parameter. You are recommended to use the ALL value, which gives the flexibility to use either SOAP 1.1 or SOAP 1.2 as the binding for the web service description, although you must install the web service into a pipeline that is configured with the SOAP 1.2 message handler. You can use this parameter only when the MINIMUM-RUNTIME-LEVEL is 2.0 or higher.
    4. 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 specify the highest level of mapping available in the MAPPING-LEVEL parameter.
    5. Which URI do you want the web service requester to use?
      • Specify an absolute URI using the URI parameter; for example, URI=http://www.example.org:80/my/test/webservice. The relative part of this address, /my/test/webservice, is used when creating the URIMAP resource. The full URI is used as the<soap:address> element in the web service description. This usage is true for both HTTP and WebSphere® MQ URIs.
    6. Do you want to publish your WSDL document to an IBM® WebSphere Service Registry and Repository (WSRR)?
      • If you want to publish your WSDL document to a WSRR, you must specify the WSRR-SERVER parameter in DFHLS2WS. For more information on the parameters that you can specify when using WSRR, see DFHLS2WS: high-level language to WSDL conversion.
    7. If you intend to publish your WSDL document on a WSRR server, do you want to do so using a secure connection?
    • When you submit DFHLS2WS, CICS generates the web service binding file and places it in the location that you specified with the WSBIND parameter. The generated web service description is placed in the location that you specified with the WSDL, WSDL_1.1, or WSDL_2.0 parameter.
    • If you have used the WSRR parameters in DFHLS2WS, your WSDL document is published to the WSRR server that you specified.
  3. Review the generated web service description and perform any necessary customization.
    For more information, see Customizing generated web service description documents.
  4. Copy the web service binding file to the pickup directory of the provider mode pipeline that you want to use for your web service application.
    You must copy the web service binding file in binary mode.
  5. 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.
  6. Use the PIPELINE SCAN command to dynamically 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.
    Alternatively, you can define the resources yourself, although this is not recommended.

Results

When you have successfully created the CICS resources, the creation of your service provider application is complete.

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

What to do next

Make the web services description available to anyone who needs to develop a web service requester that will access your service.