The header processing program containers

The CICS®-provided SOAP 1.1 and SOAP 1.2 message handlers link to header processing programs by using channel DFHHHC-V1. The containers that are passed on the channel include DFHHEADER, which is specific to the header processing program interface, and other containers such as DFHHEADER, DFHWS-XMLNS, DFHWS-BODY, and DFHXMLSS-PARSE, which are available elsewhere in your pipeline but have specific uses in a header processing program.

The header processing program interface also passes sets of control containers, context containers and user containers that are accessible to all the header processing programs and message handler programs in the pipeline. For information about these containers, see Containers used in web services pipelines.

DFHHEADER container

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.

DFHWS-XMLNS container

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, as in the following example.
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.

DFHWS-BODY container

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, because every SOAP message must contain a <Body> element.

DFHXMLSS-PARSE container

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.