Header processing programs

Header processing programs are user-written CICS® programs that are linked to from the CICS-provided SOAP 1.1 and SOAP 1.2 message handlers, in order to process SOAP header blocks.

You can write your header processing program in any of the languages which CICS supports, and use any CICS command in the DPL subset. Your header processing program can link to other CICS programs.

The header processing programs have a channel interface; the containers hold information which the header program can examine or modify, including: Other containers hold information about the environment in which the header program is invoked, such as:

Start of changeHeader processing programs normally run under transaction CPIH, which is defined with the attribute TASKDATALOC(ANY). Therefore, when you link-edit the program, you must specify the AMODE(31) option.End of change

How header processing programs are invoked for a SOAP request

The <cics_soap_1.1_ handler> and <cics_soap_1.2_ handler> elements in a pipeline configuration contain zero, one, or more, <headerprogram> elements, each of which contains the following children:
  • <program_name>
  • <namespace>
  • <localname>
  • <mandatory>
When a pipeline is processing an inbound SOAP message (a request in the case of a service provider, a response in the case of a service requester), the header program specified in the <program_name> element is invoked or not, depending upon:
  • The contents of the <namespace>, <localname>, and <mandatory> elements
  • The value of certain attributes of the root element of the SOAP header itself (the actor attribute for SOAP 1.1; the role attribute for SOAP 1.2)
The following rules determine if the header program will be invoked in a given case:
The <mandatory> element in the pipeline configuration file
If the element contains true (or 1), the header processing program is invoked at least once, even if none of the headers in the SOAP message is selected for processing by the remaining rules:
  • If none of the header blocks is selected, the header processing program is invoked once.
  • If any of the header blocks is selected by the remaining rules, the header processing program is invoked once for each selected header.
Attributes in the SOAP header block
For SOAP 1.1, a header block is eligible for processing only if the actor attribute is absent, or has a value of http://schemas.xmlsoap.org/soap/actor/next
For SOAP 1.2, a header block is eligible for processing only if the role attribute is absent, or has one of the following values:
  • http://www.w3.org/2003/05/soap-envelope/role/next
  • http://www.w3.org/2003/05/soap-envelope/role/ultimateReceiver
A header block that is eligible for processing is not processed unless it is selected by the next rule.
The <namespace> and <localname> elements in the pipeline configuration file
A header block that is eligible for processing according to the previous rule is selected for processing only if:
  • the name of the root element of the header block matches the <localname> element in the pipeline configuration file
  • and the root element's namespace matches the <namespace> element in the pipeline configuration file
For example, consider this header block:
<t:myheaderblock xmlns:t="http://mynamespace" ...> .... </t:myheaderblock>
Subject to the other rules, the header block will be selected for processing when the following is coded in the pipeline configuration file:
<namespace>http://mynamespace</namespace>
<localname>myheaderblock</localname>
The <localname> can contain an * to indicate that all header blocks in the namespace should be processed. Therefore, the same header block will be selected by the following:
<namespace>http://mynamespace</namespace>
<localname>*</localname>

When the SOAP message contains more than one header, the header processing program is invoked once for each matching header, but the sequence in which the headers are processed is undefined.

The CICS-provided SOAP message handlers select the header processing programs that will be invoked based upon the header blocks that are present in the SOAP message at the time when the message handler receives it. Therefore, a header processing program is never invoked as a result of a header block that is added to a message in the same SOAP message handler. If you want to process the new header (or any modified headers) in your pipeline, you must define another SOAP message handler in your pipeline.

For an outbound message (a request in a service requester, a response in a service provider) the CICS-provided SOAP message handlers create a SOAP message that does not contain any headers. In order to add one or more headers to the message, you must write a header handler program to add the headers. To ensure that this header handler is invoked, you must define it in your pipeline configuration file, and specify <mandatory>true</mandatory>.

If a header handler is invoked in the request phase of a pipeline, it will be invoked again in the response phase, even if the message that flows in the response phase does not contain a matching header.