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.

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.

   • For more information on how to create a channel description document, see Creating 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?
      • You can use secure socket layer (SSL) encryption by setting the appropriate parameters to interoperate securely with WSRR. For an example, see Example of how to use SSL with the web services assistant and WSRR.
   • 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.