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, to process SOAP header blocks. You can write your header processing program in any of the languages that CICS supports, and use any CICS command in the DPL subset. Your header processing program can link to other CICS programs.

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

The header processing programs have a channel interface (see The header processing program interface); the containers hold information that the header processing program can examine or modify, including the SOAP header block for which the program is invoked and the SOAP message body. Other containers hold information about the environment in which the header program is invoked, for example:
  • The transaction ID under which the header program was invoked.
  • Whether the program was invoked for a service provider or requester pipeline.
  • Whether the message being processed is a request or response.

The channel and the containers that the header processing program can use are described in The header processing program containers.

How header processing programs are invoked for a SOAP request

The <cics_soap_1.1_handler>, <cics_soap_1.2_handler>, <cics_soap_1.1_handler_java>, and <cics_soap_1.2_handler_java> 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 following items:
  • 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 is 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 are selected for processing by the remaining rules:
  • If none of the header blocks are selected, the header processing program is invoked once.
  • If any of the header blocks are 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 following conditions are satisfied:
  • The name of the root element of the header block matches the <localname> element in the pipeline configuration file
  • The namespace of the root element 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 is selected for processing when the following lines are coded in the pipeline configuration file:
<namespace>http://mynamespace</namespace>
<localname>myheaderblock</localname>
The <localname> elements can contain an * to indicate that all header blocks in the namespace should be processed. Therefore, the same header block is selected by the following code:
<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 are 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. 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 is invoked again in the response phase, even if the message that flows in the response phase does not contain a matching header.