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:
- The SOAP header block for which the program is invoked
- The SOAP message body
Other containers hold information about the environment in which the
header program is invoked, such as:
- 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
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.
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.