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.
The code page must be EBCDIC and it must be supported by both Java and z/OS conversion services.
- 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 DHWS2LS 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.
- Use the PIPELINE SCAN command to dynamically
create the WEBSERVICE resource. The WEBSERVICE resource
encapsulates the web service binding file in CICS and is used at run time. Alternatively,
you can define the resource yourself, although this is not recommended.
- 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.