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
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>
.
- 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.
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.
<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.
<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.