Utility functions

The following summarizes the utility functions that are available with z/TPF SOAP support.

Fault builder
The tpf_soap_build_fault and tpf_soap_build_fault C functions build an XML-based fault message when an error occurs along the SOAP message path. This fault message is returned to the SOAP client.
A fault message is built for each of the following conditions:
  • An error occurs during SOAP application processing. (The SOAP fault is built with identification of either receiver or sender error.)
  • A SOAP translation error during SOAP handler processing.
  • The SOAP message sent by the client arrives at z/TPF encoded in a character set other than UTF-8, Latin 1 (ISO-8859–1), or EBCDIC and tpf_soap_handler_exit does not translate the message.
  • When tpf_soap_handler_exit detects an error in the input message, a SendErrorReplySender return value must be set to return to caller.
  • When an application handler returns with ErrorReplyNeeded, the SOAP handler will build a fault message with faultCode Receiver to return to the client.

The tpf_soap_build_fault C function can be also called to build a fault message by other components or applications at any time.

Translation functions
Translation functions allow you to translate a message from one character set to another. Generally, a SOAP message must be in the host encoding before being processed by a z/TPF application. If a SOAP message is sent to the client in response, it also must be encoded in the preferred character set of the client before being sent.

See SOAP provider message encoding support for more information about encoding support on the z/TPF system.

When the input message is encoded in a Unicode character set but contains characters that cannot be translated, a substitute character is used. For example, a euro symbol (U+20AC, which is represented as 0xE282AC in UTF-8) in an input message encoded in Unicode format UTF-8 will be replaced by the 0x3F EBCDIC substitute character during translation. The converted message will instead have the 0x3F EBCDIC substitute character

SOAP bridge support
SOAP bridge support enables you to leverage existing business logic on your z/TPF system and externalize it as a callable service by other systems in a distributed environment. With this support, you can expose legacy applications as Web services without making changes to the actual applications.

Traditional z/TPF applications are activated by the z/TPF message router (segment COA4) and expect input to be in application message (AMSG) format on ECB data level 0. When it completes processing, an application typically issues one or more ROUTC macros to send the response, in output message (OMSG) format, back to the originator. Without SOAP bridge support, application changes would be required to interface with modern Web services technologies such as SOAP, XML, WSDL, HTTP, and so on.

With SOAP bridge support, Web services can be easily deployed to activate existing applications. This support consists of a set of tpf_SOAPBridge* functions, which are used in Web service wrapper programs to interface with the SOAP bridge.

In addition to the tpf_SOAPBridge* functions, two utility functions can be used in a Web service wrapper program to convert input and output messages to and from AMSG and OMSG format, respectively: tpf_convertToAMSG and tpf_convertFromOMSG.

See z/TPF C/C++ Language Support User's Guide for more information about the tpf_SOAPBridge* functions and the tpf_convert* functions.