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 file system 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. The XML schemas for the pipeline configuration files are in
the directory /usr/lpp/cicsts/cicsts51/schemas/pipeline/ (where /usr/lpp/cicsts/cicsts51 is the default install directory for CICS files on CICS® UNIX). 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 needs several different
pipeline configurations. However, where different applications have
similar requirements, they can share the same pipeline configuration.
There are two kinds of pipeline configurations: 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
<provider_pipeline> and
<requester_pipeline> elements have the following immediate sub-elements:
- 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 optional <apphandler> element, which is used
to specify channel-attached application handlers.
- For the <provider_pipeline> only,
an optional <apphandler_class> element, which
is used to specify an Axis2 application handler.
- An optional <service_parameter_list> element,
which contains the parameters that are available to the message handlers
in the pipeline.
Certain elements can have attributes associated with them. Each
attribute value must have quotes around it to produce a valid XML
document.
Associated with the pipeline configuration file is a PIPELINE resource.
The attributes include CONFIGFILE, which specifies the name of the
pipeline configuration file in z/OS UNIX. 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 configuration files.
They are provided in library
/usr/lpp/cicts/samples/pipelines.
- basicsoap11provider.xml
- A service provider pipeline definition that uses the SOAP 1.1
protocol for a pipeline that does not support Java. The pipeline uses
the <cics_soap_1.1_handler> message handler
and is used when the CICS application has been deployed using the CICS web services assistant.
- basicsoap11requester.xml
- A service requester pipeline definition that uses the SOAP 1.1
protocol for a pipeline that does not support Java. The pipeline uses
the <cics_soap_1.1_handler> message handler
and is used when the CICS application has been deployed using the CICS web services assistant.
- basicsoap11javaprovider.xml
- A service provider pipeline definition that uses the SOAP 1.1
protocol for a pipeline that supports Java. The pipeline uses the <cics_soap_1.1_handler_java> message handler
and is used when the application has been deployed using the CICS web services assistant. This configuration contains the
element <jvmserver>. This message handler has
to be edited to specify the appropriate JVM server before the configuration
can be used.
- basicsoap11javarequester.xml
- A service requester pipeline definition that uses the SOAP 1.1
protocol for a pipeline that supports Java. The pipeline uses the <cics_soap_1.1_handler_java> message handler
and is used when the application has been deployed using the CICS web services assistant. This configuration contains the
element <jvmserver>. This message handler has
to be edited to specify the appropriate JVM server before the configuration
can be used.
- 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 provider pipeline configuration file (Channel-attached
application handler)
This is a simple example
of a configuration file for a service provider pipeline that uses
the <cics_soap_1.1_handler> element: <?xml version="1.0" encoding="EBCDIC-CP-US"?>
<provider_pipeline
xmlns="http://www.ibm.com/software/htp/cics/pipeline"
<service>
<terminal_handler>
<cics_soap_1.1_handler/>
</terminal_handler>
</service>
<apphandler>DFHPITP</apphandler>
</provider_pipeline>
The pipeline contains just one 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> element
indicates that the pipeline is not a Java-based pipeline and the terminal
handler of the pipeline is a message handler that supports SOAP 1.1
messages.
- The <apphandler> element specifies
the name of the application handler that the terminal handler of the
pipeline links to by default. In this case, the program is DFHPITP,
which is the CICS-supplied program for applications deployed with
the CICS web services assistant.
Example provider pipeline configuration file (Axis2
application handler)
This is a simple example
of a configuration file for a service provider pipeline that uses
the <cics_soap_1.1_handler_java> element: <?xml version="1.0" encoding="EBCDIC-CP-US"?>
<provider_pipeline
xmlns="http://www.ibm.com/software/htp/cics/pipeline"
<service>
<terminal_handler>
<cics_soap_1.1_handler_java>
<jvmserver>DFH$AXIS</jvmserver>
</cics_soap_1.1_handler_java>
</terminal_handler>
</service>
<apphandler_class>com.ibm.cicsts.axis2.CICSAxis2ApplicationHandler</apphandler_class>
</provider_pipeline>
The pipeline contains just one 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_java> element indicates that the pipeline is a Java-based pipeline and
the service handler of the pipeline is a message handler that supports
SOAP 1.1 messages.
- The <apphandler_class> element specifies
the supplied Axis2 application handler.
Example requester pipeline configuration
file
This is a simple example of a configuration file for a
service requester pipeline that uses the
<cics_soap_1.2_handler_java> element with
Axis2 MTOM/XOP support:
<?xml version="1.0" encoding="EBCDIC-CP-US"?>
<requester_pipeline
xmlns="http://www.ibm.com/software/htp/cics/pipeline">
<service>
<service_handler_list>
<cics_soap_1.2_handler_java>
<jvmserver>JVMSERV1</jvmserver>
<mtom>
</cics_soap_1.2_handler_java>
</service_handler_list>
</service>
</requester_pipeline>
The pipeline contains just one
message handler.
- The <requester_pipeline> element is the root
element of the pipeline configuration file for a service requester
pipeline.
- The <service> element specifies the message
handlers that are invoked for every request. In the example, there
is just one message handler.
- The <service_handler_list> specifies a list
of message handlers that are invoked for every request.
- The <cics_soap_1.2_handler_java> element indicates
that the pipeline supports Java and the service handler of the pipeline
is a message handler that supports SOAP 1.2 messages.
- The <jvmserver> element specifies the JVM
server to be used.
- The <mtom/> element specifies that
outbound XOP documents are packaged into MTOM messages and sent. By
default, inbound MTOM messages are accepted and unpackaged for Java-based
pipelines.