30 z/TPF and WebSphere Application Server in a Service Oriented Architecture
3.1 SOAP handler
When a SOAP message arrives on the z/TPF system, it triggers a specified path to get
executed, which can be seen in the diagram in Figure 3-1 on page 30.
Figure 3-1 Inbound flow of a SOAP message in z/TPF
The input message has to be handed to the SOAP handler by the communications protocol
software. The SOAP handler receives three pieces of input:
An input message structure:
A soapMsg structure
containing the SOAP input message
An output message structure:
A soapMsg structure
in which the application has to build its SOAP output message
Communications binding information:
A commsBinding structure
that contains information about the communications protocol
and the application routing information
The SOAP handler performs the following tasks:
1. Invokes the SOAP handler user exit:
The z/TPF SOAP handler user exit is shared object CSO2. It allows you to specify
translation of a SOAP message, log messages, or any other user specific processing your
system requires to process the input SOAP message. The SOAP handler handles the
following predefined return codes from the z/TPF SOAP handler user exit:
Translation was completed by the user exit, so processing continues.
The detailed contents of these structures are discussed in Chapter 3.5, “SOAP structures” on page 44.
Chapter 3. z/TPF SOAP processing 31
Translation was not completed by the user exit, so the SOAP handler attempts to
translate the SOAP message.
The SOAP handler user exit determined that an error occurred that was caused by the
receiver, which is the z/TPF system. The SOAP fault builder
is called and a fault
message is built and returned to the client.
The SOAP handler user exit determined that an error occurred that was created by the
sender. The SOAP fault builder
is called and a fault message is built and returned to
the sending client.
The SOAP handler also handles the ErrorReplyNeeded return code, which indicates that
the SOAP application encountered an error but did not create the fault message. The
SOAP handler calls the SOAP fault builder
to create the fault message.
When the SOAP handler receives any other return codes from another component, it
simply returns to the communications binding.
By default the SOAP handler user exit is empty and returns the value
TPF_CONTINUE_DO_TRANSLATE. Example 3-1 shows the way the SOAP handler user
exit is shipped with z/TPF.
2. Translates the input message if necessary:
Depending on the return code from the SOAP handler user exit, the input message is
translated to the host encoding of the z/TPF system.
3. Invokes the B2B XML scanner:
For more about the B2B XML scanner, see Chapter 5, “XML on z/TPF” on page 79.
4. Checks the SOAP syntax:
The SOAP handler performs the following syntax checks:
– The document must not contain a Document Type Definition (DTD) or any processing
– The document must not have a standalone=no value in the docSwitches field of the
– The document must contain a SOAP envelope.
– The SOAP envelope must be namespace-qualified.
– If the document contains a header element, it must follow immediately after the
– If the document contains a header element, it must be namespace-qualified.
– The document must contain a body element.
– The body element must follow the header element if one is present or follow
immediately after the envelope element.
For SOAP version 1.1, if the document contains a mustUnderstand element, the value
must be 0 or 1.
For SOAP version 1.2, the following additional checks are performed:
– The document must not contain an attribute of encodingStyle in the envelope element.
– If the document contains a mustUnderstand element, the value must be true or false.
See Chapter 3.3, “SOAP fault builder” on page 33.