Creating a service provider application from a data structure

Use the CICS® web services assistant to create a service provider application from a high-level language data structure.

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

1. If the service provider application interface uses channels and many containers, create a channel description document that describes the interface in JSON. You must save the channel description document in a suitable directory on z/OS UNIX.
   CICS uses this document to construct and deconstruct a JSON message from the containers on a channel. Alternatively, you can use one container in a channel and not create a channel description document.

   For more information about how to create a channel description document, see Creating a channel description document.

2. Use the DFHLS2JS batch program to generate a web service binding file and web service description from the language structure.
   The DFHLS2JS batch program can be found in HLQ .XDFHINST where HLQ is the location where you installed CICS. DFHLS2JS 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 the following options when enabling web services for an existing application:

   • Which mechanism do you want CICS to 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 by 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 use these parameters only when the mapping level is 3.0 or higher.
   • 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 must specify the highest level of mapping available in the MAPPING-LEVEL parameter.
   • Which URI do you want the web service to use? Specify an absolute URI by 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.
   When you submit DFHLS2JS, CICS generates the web service binding file and places it in the location that you specified with the WSBIND parameter. The generated JSON schemas are placed in the location that you specified with the JSON-SCHEMA-REQUEST and JSON-SCHEMA-RESPONSE parameters.
3. Review the generated JSON schema.
   These schemas are used to define the input and output data formats for the JSON web service. The application developer must use these schemas when creating an application to interact with the JSON web service.

   Note: Changing the generated schema invalidates the generated web service binding file, WSBind.

   If you want to change the schema, for example, to rename the fields within the schema, you must use DFHJS2LS to generate a new web service binding file, and a new set of language structures. The application program in CICS must be changed to use the new language structures.

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. Use the PIPELINE SCAN command to dynamically create the WEBSERVICE resource and a URIMAP resource.
   • The WEBSERVICE resource contains the web service binding file in CICS and is used at run time.
   • The URIMAP resource provides CICS with the information to associate the WEBSERVICE resource with a specific URI.

   Alternatively, you can define the resources yourself.