The header processing program interface

The CICS-provided SOAP 1.1 and SOAP 1.2 message handlers link to the header processing programs using channel DFHHHC-V1. The containers that are passed on the channel include several that are specific to the header processing program interface, and sets of context containers and user containers that are accessible to all the header processing programs and message handler programs in the pipeline.

Container DFHHEADER is specific to the header processing program interface. Other containers are available elsewhere in your pipeline, but have specific uses in a header processing program. The containers in this category are DFHWS-XMLNS, DFHWS-BODY, and DFHXMLSS-PARSE.
Note: Although web service that use Axis2 to process SOAP messages can use the header processing program interface, it is more efficient to write your own Axis2 handlers in Java to process the SOAP headers. For more information on creating Axis2 handlers, see Writing Your Own Axis2 Module

Container DFHHEADER

When the header processing program is called, DFHHEADER contains the single header block that caused the header processing program to be driven. When the header program is specified with <mandatory>true</mandatory> or <mandatory>1</mandatory> in the pipeline configuration file, it is called even when there is no matching header block in the SOAP message. In this case, container DFHHEADER has a length of zero. This is the case when a header processing program is called to add a header block to a SOAP message that does not have header blocks.

The SOAP message that CICS® creates has no headers initially. If you want to add headers to your message, you must ensure that at least one header processing program is called, by specifying <mandatory>true</mandatory> or <mandatory>1</mandatory>.

When the header program returns, container DFHHEADER must contain zero, one, or more header blocks that CICS inserts in the SOAP message in place of the original:
  • You can return the original header block unchanged.
  • You can modify the contents of the header block.
  • You can append one or more new header blocks to the original block.
  • You can replace the original header block with one or more different blocks.
  • You can delete the header block completely.

Container DFHWS-XMLNS

When the header processing program is called, DFHWS-XMLNS contains information about XML namespaces that are declared in the SOAP envelope. The header program can use this information to perform the following tasks:
  • Resolve qualified names that it encounters in the header block
  • Construct qualified names in new or modified header blocks.
The namespace information consists of a list of namespace declarations, which use the standard XML notation for declaring namespaces. The namespace declarations in DFHWS-XMLNS are separated by spaces. For example:
xmlns:na='http://abc.example.org/schema' xmlns:nx='http://xyz.example.org/schema'

You can add further namespace declarations to the SOAP envelope by appending them to the contents of DFHWS-XMLNS. However, namespaces whose scope is a SOAP header block or a SOAP body are best declared in the header block or the body respectively. You are advised not to delete namespace declarations from container DFHWS-XMLNS in a header processing program, because XML elements that are not visible in the program may rely on them.

Container DFHWS-BODY

This container contains the body section of the SOAP envelope. The header processing program can modify the contents.

When the header processing program is called, DFHWS-BODY contains the SOAP <Body> element.

When the header program returns, container DFHWS-BODY must again contain a valid SOAP <Body>, which CICS inserts in the SOAP message in place of the original:
  • You can return the original body unchanged.
  • You can modify the contents of the body.
You must not delete the SOAP body completely, as every SOAP message must contain a <Body> element.

Container DFHXMLSS-PARSE

When you use either the <cics_soap_1.1_handler> or <cics_soap_1.2_handler> elements in your pipeline configuration, and header program is called, DFHXMLSS-PARSE contains the XML System Services (XMLSS) records for that header. This container is not created when <cics_soap_1.1_handler_java> or <cics_soap_1.2_handler_java> elements are used.

Control, context, and user containers

As well as the containers described, the interface passes the control containers, context containers, and user containers on channel DFHHHC-V1.