The <cics_soap_1.1_handler> pipeline configuration element

Used in:

• Service requester
• Service provider

Contained by:

• <service_handler_list> element
• <terminal_handler> element

Contains:

1. A <program_name> element, containing the name of a header processing program
2. A <namespace> element, which is used with the following <localname> element to determine which header blocks in a SOAP message should be processed by the header processing program. The <namespace> element contains the URI (Uniform Resource Identifier) of the header block's namespace.
3. A <localname> element, which is used with the preceding <namespace> element to determine which header blocks in a SOAP message should be processed by the header processing program. The <localname> contains the element name of the header block.
   For example, consider this header block:

   <t:myheaderblock xmlns:t="http://mynamespace" ...> .... </t:myheaderblock>

   • The namespace name is http://mynamespace
   • The element name is myheaderblock

   To make a header program match this header block, code the <namespace> and <localname> elements like this:

   <namespace>http://mynamespace</namespace>
   <localname>myheaderblock</localname>

   You can code an asterisk (*) in the <localname> element to indicate that all header blocks in the namespace whose names begin with a given character string should be processed. For example:

   <namespace>http://mynamespace</namespace>
   <localname>myhead*</localname>

   When you use the asterisk in the <localname> element, a header in a message can match more than one <headerprogram> element. For example, this header block

   <t:myheaderblock xmlns:t="http://mynamespace" ...> .... </myheaderblock>

   matches all the following <headerprogram> elements:

   <headerprogram>
     <program_name>HDRPROG1</program_name>
     <namespace>http://mynamespace</namespace>
     <localname>*</localname>
     <mandatory>false</mandatory>
   </headerprogram>
   <headerprogram>
     <program_name>HDRPROG2</program_name>
     <namespace>http://mynamespace</namespace>
     <localname>myhead*</localname>
     <mandatory>false</mandatory>
   </headerprogram>
   <headerprogram>
     <program_name>HDRPROG3</program_name>
     <namespace>http://mynamespace</namespace>
     <localname>myheaderblock</localname>
     <mandatory>false</mandatory>
   </headerprogram>

   When this is the case, the header program that runs is the one specified in the <headerprogram> element in which the element name of the header block is most precisely stated. In the example, that is HDRPROG3.

   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.

   If you code two or more <headerprogram> elements that contain the same <namespace> and <localname>, but that specify different header programs, only one of the header programs will run, but which of the programs will run is not defined.

4. A <mandatory> element, containing an XML boolean value (true or false). Alternatively, you can code the values as 1 or 0 respectively.

   true

   During service request processing in a service provider pipeline, and service response processing in a service requester pipeline, the header processing program is to be invoked at least once, even if none of the headers in the SOAP messages matches the <namespace> and <localname> elements:

   • If none of the headers matches, the header processing program is invoked once.
   • If any of the headers match, the header processing program is invoked once for each matching header.

   During service request processing in a service requester pipeline, and service response processing in a service provider pipeline, the header processing program is to be invoked at least once, even though 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 invoked, by specifying <mandatory>true</mandatory> or <mandatory>1</mandatory>.

   false

   The header processing program is to be invoked only if one or more of the headers in the SOAP messages matches the <namespace> and <localname> elements:

   • If none of the headers matches, the header processing program is not invoked.
   • If any of the headers match, the header processing program is invoked once for each matching header.