The <cics_soap_1.1_handler> element

Defines the attributes of the CICS-supplied handler program for SOAP 1.1 messages.

Used in:

Contained by:

Contains:

Zero, one, or more <headerprogram> elements. Each <headerprogram> 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 (Universal 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 be called to process the header. The header will be passed in the DFHHEADER container to the selected program. The other header programs will not be called unless they are defined with<mandatory>true</mandatory> in which case they will be called without having the header passed in the DFHHEADER container.

  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.

Example

<cics_soap_1.1_handler>
  <headerprogram>
    <program_name> ... </program_name>
    <namespace>...</namespace>
    <localname>...</localname>
    <mandatory>true</mandatory>
  </headerprogram>
</cics_soap_1.1_handler>