The configuration of a pipeline used to handle a Web service request
is specified in an XML document, known as a pipeline configuration file.
The pipeline configuration file is stored in the z/OS® UNIX System Services
hierarchical file system (HFS), and its name is specified in the CONFIGFILE
attribute of a PIPELINE resource definition. Use a suitable XML editor or
text editor to work with your pipeline configuration files. When you work
with configuration files, ensure that the character set encoding is US EBCDIC
(Code page 037).
When CICS® processes a Web service request, it uses a pipeline
of one or more message handlers to handle the request. A pipeline is configured
to provide aspects of the execution environment that apply to different categories
of applications, such as support for Web Service Security, and Web Service
transactions. Typically, a CICS region that has a large number of service provider
or service requester applications will need several different pipeline configurations.
However, where different applications have similar requirements, they can
share the same pipeline configuration.
There are two kinds of pipeline configuration: one describes the configuration
of a service provider pipeline; the other describes a service requester pipeline.
Each is defined by its own schema, and each has a different root element.
Pipeline |
Schema |
Root element |
Service provider |
Provider.xsd |
<provider_pipeline> |
Service requester |
Requester.xsd |
<requester_pipeline> |
Although many of the XML elements used are common to both kinds of
pipeline configuration, others are used only in one or the other, so you cannot
use the same configuration file for both a provider and requester.
Restriction: Namespace-qualified element names
are not supported in the pipeline configuration file.
The immediate sub-elements of the
<provider_pipeline> and
<requester_pipeline> elements
are:
A <service> element, which specifies the
message handlers that are invoked for every request. This element is mandatory
when used within the <provider_pipeline> element, and
optional within the <requester_pipeline> element.
- An optional <transport> element, which specifies message
handlers that are selected at run time, based upon the resources that are
being used for the message transport.
- For the <provider_pipeline> only, an <apphandler> element,
which is used in some cases to specify the target application (or wrapper
program) that provides the service.
- An optional <service_parameter_list> element, which
contains the parameters that are available to the message handlers in the
pipeline.
Associated with the pipeline configuration file is a PIPELINE resource.
The attributes include CONFIGFILE, which specifies the name of the pipeline
configuration file in HFS. When you install a PIPELINE definition, CICS reads the
information that it needs in order to configure the pipeline from the file.
CICS supplies
sample configuration files that you can use as a basis for developing your
own. They are provided in library
/usr/lpp/cicts/samples/pipelines.
- File
- Description
- basicsoap11provider.xml
- A pipeline definition for a service provider that uses the CICS-provided
SOAP 1.1 handler, for use when the application has been deployed using the CICS Web
services assistant.
- basicsoap11requester.xml
- A pipeline definition for a service requester that uses the CICS-provided
SOAP 1.1 handler, for use when the application has been deployed using the CICS Web
services assistant.
- wsatprovider.xml
- A pipeline definition that adds configuration information for Web Services
transactions to basicsoap11provider.xml.
- wsatrequester.xml
- A pipeline definition that adds configuration information for Web Services
transactions to basicsoap11requester.xml.
Example pipeline configuration file
This is a simple
example of a configuration file for a service provider pipeline:
<?xml version="1.0" encoding="UTF-8"?>
<provider_pipeline
xmlns="http://www.ibm.com/software/htp/cics/pipeline"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.ibm.com/software/htp/cics/pipeline/provider.xsd">
<service>
<terminal_handler>
<cics_soap_1.1_handler/>
</terminal_handler>
</service>
<apphandler>DFHPITP</apphandler>
</provider_pipeline>
The pipeline contains just one message handler, the CICS-supplied
SOAP 1.1 message handler. The handler links to program DFHPITP.
- The <provider_pipeline> element is the root element
of the pipeline configuration file for a service provider pipeline.
- The <service> element specifies the message handlers
that are invoked for every request. In the example, there is just one message
handler.
- The <terminal_handler> element contains the definition
of the terminal message handler of the pipeline.
- The <cics_soap_1.1_handler> indicates that the terminal
handler of the pipeline is the CICS-supplied handler program for SOAP 1.1
messages.
The <apphandler> element specifies the name
of the program to which the terminal handler of the pipeline will link by
default. In this case, the program is DFHPITP, which is the CICS-supplied
target program for applications deployed with the CICS Web services assistant. For programs
that are not deployed with the Web services assistant, this is the name of
the target application program.