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
- 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:
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- 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.
- Write a service provider application program to interface
with the generated language structures and implement the required
business logic.
- 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:
- Using the
PIPELINE SCAN
command to
dynamically create the WEBSERVICE resource and URIMAP resources.
- 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.