Pipeline configuration files
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/cicsts54/schemas/pipeline/ (where /usr/lpp/cicsts/cicsts54 is the default install directory for CICS® files on z/OS UNIX). When you work with configuration files, ensure that the character set encoding is UTF-8. If you import an existing configuration file that is encoded in EBCDIC, it is automatically converted to UTF-8.
| Pipeline | Schema | Root element |
|---|---|---|
| Service provider | Provider.xsd | <provider_pipeline> |
| Service requester | Requester.xsd | <requester_pipeline> |
- 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.
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.
- 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 must 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 must be edited to specify the appropriate JVM server before the configuration can be used.
- jsonjavaprovider.xml
- A service provider pipeline definition that uses the JSON message format for a pipeline that supports Java. The pipeline uses the <cics_json_handler_java> message handler and is used when the CICS application has been deployed using the CICS JSON assistant. This configuration contains the element <jvmserver>. This message handler must be edited to specify the appropriate JVM server before the configuration can be used.
- jsonzosconnectprovider.xml
- A pipeline definition for a JSON web service that is deployed to a PIPELINE that is configured for z/OS Connect for CICS. The pipeline uses the <provider_pipeline_json> message handler. This configuration contains the element <jvmserver>. This message handler must be edited to specify the appropriate JVM server before the configuration can be used.
- kerberosprovider.xml
A service provider pipeline definition that adds configuration information for Kerberos support to basicsoap11provider.xml.
- samlprovider.xml
A service provider pipeline definition that adds configuration information for SAML support to basicsoap11provider.xml.
- samlrequester.xml
A service requester pipeline definition that adds configuration information for SAML support to basicsoap11requester.xml.
- propagatesamlprovider.xml
A service provider pipeline definition that adds configuration information for SAML support with propagation of SAML information through a CICS transaction to basicsoap11provider.xml.
- propagatesamlrequester.xml
A service requester pipeline definition that adds configuration information for SAML support with propagation of SAML information through a CICS transaction to basicsoap11requester.xml.
- 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 (JSON application handler)
This is a simple example of a configuration file for a service provider pipeline that uses the <cics_json_handler_java> element:<p><?xml version="1.0" encoding="EBCDIC-CP-US"?>
<provider_pipeline xmlns="http://www.ibm.com/software/htp/cics/pipeline">
<service>
<terminal_handler>
<cics_json_handler_java>
<jvmserver>DFHAXIS</jvmserver>
<repository>/usr/lpp/cicsts/cicsts52/lib/pipeline/repository</repository>
</cics_json_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 DFHJSON.- 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_json_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 JSON 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 DFHJSON, which is the CICS-supplied program for applications deployed with the CICS JSON assistant.
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>DFHAXIS</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.
Example provider pipeline configuration file for a z/OS Connect for CICS JSON web service
This is a simple example of a configuration file for a service provider pipeline that uses the <provider_pipeline_json> element. Because a java_parser="NO" attribute is supplied, it uses the non-Java JSON parser:
<?xml version="1.0" encoding="EBCDIC-CP-US"?>
<provider_pipeline_json java_parser="NO"
xmlns="http://www.ibm.com/software/htp/cics/pipeline">
<jvmserver>DFHWLP</jvmserver>
</provider_pipeline_json>
The <provider_pipeline_json> element differs from the <provider_pipeline> element in that handler programs cannot be defined.
- The <provider_pipeline_json> element is the root element of the pipeline configuration file for a z/OS Connect for CICS JSON web service provider pipeline.
- The java_parser="NO" attribute specifies that the non-Java JSON parser is used.
- The <jvmserver> element specifies the JVM server to be used.

Example provider pipeline configuration file for non-Java JSON parsing
<?xml version="1.0" encoding="EBCDIC-CP-US"?>
<provider_pipeline
xmlns="http://www.ibm.com/software/htp/cics/pipeline">
<service>
<terminal_handler>
<handler>
<program>DFHPIJT</program><handler_parameter_list/>
</handler>
</terminal_handler>
</service>
</provider_pipeline>
The pipeline contains only one message handler.
- 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 only one message handler.
- The <terminal_handler> element contains the definition of the terminal message handler of the pipeline.
- The <handler> element specifies details of the handler.
- The <program> element specifies the program to be invoked. DFHPIJT is the CICS-supplied handler for non-Java JSON processing.
