You can create a service requester application from a web
service description that complies with WSDL 1.1 or WSDL 2.0. The CICS® web services assistant helps
you to deploy your CICS applications
in a service requester setting.
Before you begin
Your web services description must be in a file in z/OS® UNIX or
it must be published on an IBM® WebSphere® Services Registry
and Repository (WSRR) server, and a requester mode pipeline must be
installed in the CICS region.You
must allocate sufficient storage to the user ID so that the ID can
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
When you use the CICS web
services assistant to deploy a CICS application
as a service requester, you must start with a web service description
and generate the language data structures from it.
Procedure
- Use the DFHWS2LS batch program to generate a web
service binding file and one or more language structures.
Consider
these options when creating a service requester application from a
web service description:
- 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.
- Which code page do you want to use when transforming data
at run time? If you want to use a specific code page for your application
that is different from the code page for the CICS region, use the CCSID parameter.
- Do you want to support a subset of the operations that are
declared in the web service description? If you have a very large
web service description, and want your service requester application
to support only a certain number of operations, use the OPERATION parameter
to list the ones you want. Each operation must be separated with a
space and is case sensitive.
- Where is the WSDL document stored? If the WSDL document that
you want to use as input to DFHWS2LS is stored on a WSRR server, you
can retrieve it by running DFHWS2LS with certain parameters specified.
Use the WSRR-SERVER parameter to specify the
location of the WSRR server and use the WSRR-NAME parameter
to specify the name of the WSDL document that you want to retrieve.
For information about other parameters on DFHWS2LS that you might
want to use to interact with WSRR, see DFHWS2LS: WSDL to high-level language conversion.
- If you want to retrieve the WSDL document from a WSRR server,
do you want to do so using a secure connection? You can use secure
socket layer (SSL) encryption with the web services assistant to interoperate
securely with WSRR. For an example, see Example of how to use SSL with the web services assistant and WSRR.
Do not specify parameters such as PROGRAM, URI, TRANSACTION,
and USERID when you use DFHWS2LS. These parameters
apply only to a service provider application and, if specified, cause
a provider mode web service binding file to be produced.
In addition
to the web service binding file, the program generates a language
data structure.
-
Check the log file to see whether any problems occurred when DFHWS2LS generated the binding file and language structures.
CICS might not support some elements or options in the web service description. If any warning or error messages are issued, read the advice that is provided and take appropriate action. You might need to rerun the batch program.
- Copy the web service binding file to the pickup directory
of the requester mode pipeline that you want to use for your web service
application.
- Ensure that the PIPELINE resource is configured for service
requester applications.
The value of the MODE parameter
shows whether the pipeline supports requester or provider web service
applications.
- Ensure that the correct SOAP protocol is supported in the
pipeline for your web service.
The SOAPLEVEL parameter
indicates which version is supported. In service requester mode, the
binding of the web service must match the version of SOAP that is
supported in the pipeline. You cannot install a web service with a
SOAP 1.1 binding into a service requester pipeline that supports SOAP
1.2.
- Ensure that the configured timeout for the pipeline is
suitable for your service requester application.
The timeout
is displayed as the value of the RESPWAIT attribute on the PIPELINE
resource. If no timeout is specified on the pipeline, the default
for the transport is used.
- The default timeout for HTTP is 10 seconds.
- The default timeout for WebSphere MQ
is 60 seconds.
Each transaction in the CICS region
has a dispatcher timeout. If this value is less than the default for
either protocol, the timeout occurs with the dispatcher.
- Optional: Copy the web service description
to the same pickup directory as the web service binding file, so that
you can turn on validation for the web service at run time.
- Create the WEBSERVICE resource. This resource encapsulates
the web service binding file in CICS and
is used at run time.
You can do this in the following
ways:
- Using the PIPELINE SCAN command to
dynamically create the WEBSERVICE resource.
- Defining the resource 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 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.
- Write a wrapper program that you can substitute for your
communications logic. Use the language data structure generated in
step 1 to write
your wrapper program.
Use an
EXEC CICS INVOKE
SERVICE command in your wrapper program to communicate with
the web service. The command includes these options:
- The URI of the web service
- The operation for which the web service is being called
When you call the web service, you can specify a
URIMAP resource that contains
the information about the URI of the web service. You can specify
this information directly on the INVOKE SERVICE command instead of
using a URIMAP resource. However, using a URIMAP resource means that
you do not need to recompile your applications if the URI of a service
provider changes. With a URIMAP resource you can also choose to implement
connection pooling, where CICS keeps
the client connection open after use, so that it can be reused by
the application for subsequent requests, or by another application
that calls the same service. The PIPELINE SCAN command does not create
URIMAP resources for a service requester, so you must define the URIMAP
resource yourself following the instructions in
Creating a URIMAP resource for CICS as a HTTP
client.
Results
When you have successfully created the CICS resources, the creation of your service
requester application is complete.