To create the CICS® infrastructure for a SOAP
service requester, you must create a pipeline configuration file and
create a number of CICS resources.
Before you begin
If you want to use a Java pipeline, ensure that a JVMSERVER
resource exists with the JAVA_PIPELINE=YES option specified in the
JVM Profile. See JVMSERVER resources.
A
JVM server can handle SOAP processing for many Java pipelines.
About this task
You can define the PIPELINE resource in a local CICS region using CICS or CICSPlex® SM functions, or you
can use the CICS Explorer® to
define the PIPELINE resource either in a local CICS region or in a CICS bundle. When you use the CICS Explorer to define a PIPELINE
resource in a CICS bundle,
you also create the pipeline configuration file and package it in
the CICS bundle, so you do
not have to manage this file separately. PROGRAM, WEBSERVICE and URIMAP
resources can also be defined in CICS bundles.
When you define a WEBSERVICE resource in a CICS bundle, you can import a web service binding
file and a WSDL document or WSDL archive file and package these in
the bundle, and for a service provider you can choose to include a
PROGRAM definition. You can also create 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,
seeWorking with bundles in the CICS Explorer product documentation.
Procedure
- Define the message handlers and header processing programs
that you want to include in the pipeline configuration file to process
inbound web service requests, and their responses. CICS
provides the following handlers and header processing programs:
- SOAP message handlers, to process SOAP 1.1 or 1.2
messages. You can only support one level of SOAP in a service requester pipeline.
- MTOM handler, to process MIME
Multipart/Related messages that conform to the MTOM/XOP specifications.
- Security handler, to
process secure web service messages.
- WS-AT header processing program, to process atomic
transaction messages.
- Optional: If you want to perform your own processing in the pipeline, you must create a message handler
or header processing program. See Message handlers for details. If you decide
to create custom message handler programs, to optimize performance you must make them
threadsafe.
- Create an XML pipeline configuration file containing your message handlers and header
processing programs. CICS provides
two basic requester mode pipeline configuration file samples,
basicsoap11provider.xml and basicsoap11javaprovider.xml,
which you can copy and edit as appropriate. These samples are provided in the library
/usr/lpp/cicsts/cicsts54/samples/pipelines (where /usr/lpp/cicsts/cicsts54 is the default install
directory for CICS files on z/OS
UNIX). For more
information about options available in the pipeline configuration file, see Pipeline configuration files
- Copy the pipeline configuration file to a suitable directory
in z/OS UNIX.
- Change the pipeline configuration file permissions to allow
the CICS region to read the file.
- Repeat steps 3 to 5 for each different pipeline configuration
that you require.
- Create a PIPELINE resource. See PIPELINE resources. The PIPELINE
resource defines the location of the pipeline configuration file.
It also specifies a pickup directory, which is the z/OS UNIX directory
that contains the web service binding files and optionally the WSDL.
You can also specify a timeout in seconds, which determines how long CICS waits
for a response from web service providers. Repeat this step for each
pipeline configuration file. When you create a PIPELINE
resource, CICS reads any files in the specified pickup
directory and creates the WEBSERVICE resources dynamically (see WEBSERVICE resources).
- Unless you use autoinstall PROGRAM definitions, create
a PROGRAM resource for each program that runs in the pipeline. See PROGRAM resources. These programs
include the service requester application program, which normally
runs under transaction CPIH. The transaction is defined with the attribute TASKDATALOC(ANY).
Therefore, when you link edit the program, you must specify the AMODE(31) option.
- Optional: Create a URIMAP resource (see URIMAP resources) for client requests to
each URI that your service requesters use to make requests, following
the instructions in Creating a URIMAP resource for CICS as a HTTP client. You can specify the URI directly on the INVOKE SERVICE command
in your programs, 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.
Results
Your CICS system now contains the infrastructure
needed for each service requester.
What to do next
You can extend the configuration when you need to do so,
to create additional pipelines.