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
1
containing the SOAP input message
򐂰 An output message structure:
A soapMsg structure
1
in which the application has to build its SOAP output message
򐂰 Communications binding information:
A commsBinding structure
1
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:
TPF_CONTINUE_DO_NOT_TRANSLATE
Translation was completed by the user exit, so processing continues.
1
The detailed contents of these structures are discussed in Chapter 3.5, “SOAP structures” on page 44.
SOAP Handler
SOAP Handler
User Exit
User Exit
Input Message
Input Message
Translator
Translator
B2B XML
B2B XML
Scanner
Scanner
SOAP Syntax
SOAP Syntax
Checker
Checker
SOAP Application
SOAP Application
Handler
Handler
SOAP
SOAP
Handler
Handler
1
2
3
4
5
Chapter 3. z/TPF SOAP processing 31
TPF_CONTINUE_DO_TRANSLATE
Translation was not completed by the user exit, so the SOAP handler attempts to
translate the SOAP message.
TPF_TRANS_FAILED_RECEIVER:
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
2
is called and a fault
message is built and returned to the client.
TPF_TRANS_FAILED_SENDER
The SOAP handler user exit determined that an error occurred that was created by the
sender. The SOAP fault builder
2
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
2
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
instructions.
The document must not have a standalone=no value in the docSwitches field of the
infoNodes structure.
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
envelope element.
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.
2
See Chapter 3.3, “SOAP fault builder” on page 33.

Get z/TPF and WebSphere Application Server in a Service Oriented Architecture now with O’Reilly online learning.

O’Reilly members experience live online training, plus books, videos, and digital content from 200+ publishers.