Use the CICS® web
services assistant to 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 your setup complies with these preconditions:
- Your high-level language data structures must meet the following
criteria:
- 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 that DFHLS2JS uses to run.
- 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 JSON-SCHEMA-REQUEST and JSON-SCHEMA-RESPONSE output
parameters.
- The user ID must have a sufficiently large storage allocation
to run Java™. You can use any
supported version of Java. By
default, DFHLS2JS uses the Java version
that is specified in the JAVADIR parameter.
Procedure
Follow these steps to create a service provider application
from a high-level data structure:
- 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.
- 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 FPHLQ.SDFHMOBI where FPHLQ is
the location where you installed the feature pack. 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.
- 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.
- 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.
- 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.
Results
The creation of your service provider application is complete.
If
you have any problems submitting DFHLS2JS, or the resources do not
install correctly, see Troubleshooting the JSON assistant.
What to do next
Make the web services description available to anyone who
develops a web service that will access your service.