Generate CICS MTOM/XOP Web Service (Bottom-Up)

Edit online

This topic describes the ability for Enterprise Service Tools Single-service projects to create MTOM/XOP compatible Web service artifacts for CICS® runtimes.

The ability to generate an MTOM/XOP compatible Web service description and runtime specific XML message processing from a high-level language data structure is available. This is used when an applicative program is exposed by a service provider and transmits language structures in binary instead of using an XML representation.

Key components are:
  • MTOM (Message Transformation Optimization Mechanism) an abstract specification that in this implementation describes, a technique to optimize SOAP messages where binary objects are used to carry data instead of the typical XML payload.
  • XOP (XML-binary Optimization Package) describes how the binary objects, attached using MTOM, can be represented in binary octets instead of base64 .

Using MTOM/XOP, a service requester and service provider can exchange the actual binary/native request and response language structures without having to use an intermediate XML representation. While SOAP messages are still used in this configuration, the Body of the messages is very brief, essentially containing a single XML element that references a binary attachment. In this scenario both the requester and provider are entirely responsible creation of the language structures and must be sensitive to character encoding differences between the platforms.

Using the Enterprise Service Tools Web Service Wizard:

Available runtime: Web Services for CICS

Available development scenario: Create New MTOM/XOP Service Interface (bottom-up)

Note: Only allowed values: Application Mode: Service Provider and Conversion Type: Interpretive XML Conversion
Limitations are:
  • CICS COBOL MTOM/XOP Service Providers:
    • COMMAREA-based: The maximum size of an MTOM/XOP attachment (derived from a language structure) is 32767 bytes as this is the maximum size of a DFHCOMMAREA.
    • CHANNEL-based: The maximum size of an MTOM/XOP attachment (derived from a language structure) is 128mb, which is the maximum size of a COBOL data item.
    • CHANNEL DESCRIPTION DOCUMENT-based: Not supported.
  • CICS PL/I MTOM/XOP Service Providers:
    • COMMAREA-based: The maximum size of an MTOM/XOP attachment (derived from a language structure) is 32767 bytes as this is the maximum size of a DFHCOMMAREA.
    • CHANNEL-based: The maximum size of an MTOM/XOP attachment (derived from a language structure) is 32767 bytes as this is the maximum size of a character array in PL/I.
    • CHANNEL DESCRIPTION DOCUMENT-based: Not supported
In order to take advantage of MTOM/XOP support in CICS, provider and requester mode Web services must reside in pipelines that are respectively configured for MTOM/XOP message handling. Figure 1 is an example configuration file for a provider-mode pipeline that supports bi-directional MTOM/XOP messaging.
Figure 1. Example MTOM/XOP enabled provider-mode pipeline configuration

<?xml version="1.0" encoding="EBCDIC-CP-US"?>
<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/pipelineprovider.xsd ">
      <cics_mtom_handler>
            <dfhmtom_configuration version="1">
                  <mtom_options send_mtom="yes" send_when_no_xop="yes" />
                  <xop_options apphandler_supports_xop="yes" />
                  <mime_options content_id_domain="example.org" />
            </dfhmtom_configuration>
      </cics_mtom_handler>
      <service>
             <terminal_handler>
                   <cics_soap_1.1_handler />
             </terminal_handler>
      </service>
      <apphandler>DFHPITP</apphandler>
</provider_pipeline>

CICS applies message handlers to the request message in the order the messages appear in the configuration file; this order is reversed for the response message. In Figure 1, MTOM/XOP message handling is applied first to unpack MTOM attachments from the request message and last to package MTOM attachments with the response message. To compliment Figure 1, Figure 2 is a sample configuration file for a requester-mode pipeline that supports bi-directional MTOM/XOP messaging:

Figure 2. Example MTOM/XOP enabled requester-mode pipeline configuration

<?xml version="1.0" encoding="EBCDIC-CP-US"?>
<requester_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/pipelinerequester.xsd ">
      <service>
            <service_handler_list>
                  <cics_soap_1.1_handler />
            </service_handler_list>
      </service>
      <cics_mtom_handler>
            <dfhmtom_configuration version="1">
                  <mtom_options send_mtom="yes" send_when_no_xop="yes" />
                  <xop_options apphandler_supports_xop="yes" />
                  <mime_options content_id_domain="example.org" />
            </dfhmtom_configuration>
      </cics_mtom_handler>
</requester_pipeline>