Create a SOAP message handler

To implement a SOAP message handler, you must determine if the message handler will be used with SOAP provider support, SOAP consumer support, or both.

  • To use the SOAP message handler with SOAP provider support, you must implement three aspects of processing: request, response, and fault.
  • To use the SOAP message handler with SOAP consumer support, you must implement four aspects of processing: consumer request, consumer response, consumer fault, and consumer error return.
  • To use the SOAP message handler with both SOAP provider and SOAP consumer support, you must implement all seven aspects of processing: provider request, provider response, provider fault, consumer request, consumer response, consumer fault, and consumer error return.
SOAP support uses the TPF_CALL_BY_NAME API to call the 4-character z/TPF program name that is specified in the SOAP message handler deployment descriptor for a SOAP message handler. Processing is implemented in C shared objects; CSOs must have a single entry point as defined in the makefile. The interface to the CSO must match the interface that is defined by the typedef that is used to define SOAP message handlers. The format of the typedef is: 
typedef SOAP_MSGHDLR_RET(*intfn)(SOAP_MSGHDLR_ACT, tpfSoapMsgCtx*);
An explanation of the typedef follows:
  • SOAP message handlers must return an integer; this is defined by the SOAP_MSGHDLR_RET enumeration in the tpf/c_soap.h header file.
  • The first parameter is an integer; it represents an action code (defined by the SOAP_MSGHDLR_ACT enumeration in the tpf/c_soap.h header file) that identifies whether the message is a provider request, provider response, provider fault, consumer request, consumer response, consumer fault, or consumer error return.
  • The second parameter is a pointer to a tpfSoapMsgCtx structure, which is defined in the tpf/c_soapctx.h header file.
  • The intfn pointer is a pointer to function type and is passed to the TPF_CALL_BY_NAME macro. With this pointer and the 4-character program name that implements a SOAP message handler, the TPF_CALL_BY_NAME macro returns a pointer to function value that calls an enter with return (ENTRC linkage) to the specified program.
The tpfSoapMsgCtx structure contains information about the SOAP message handler that is being processed, for example:
  • An XMLHandle structure that represents the SOAP message and is called requestMsg.
  • An XMLHandle structure that represents a response message and is called responseMsg.

You can use the z/TPF parser APIs to help in accessing the data in the message and in creating the response message.

You must write code to add function to the SOAP message handler to perform any installation- or environment-specific processing. Think of a SOAP message handler as a kind of specialized user exit; for example, if a set of deployed Web services require that each SOAP request for them is logged to a specific logging facility, you can develop a logging message handler and deploy it to SOAP support.

Each Web service can specify a SOAP message handler chain, which is a list of the message handlers that a SOAP message that is destined for the Web service must go through before it gets to a Web service wrapper or after it has gone through a Web service stub. The SOAP message handler chain also specifies the order in which the specified SOAP message handlers are executed; the order is reversed for response messages and SOAP faults.

To download a sample SOAP message handler, go to the TPF Family Products: Tools web page.

Like Web services on the z/TPF system, SOAP message handlers use a deployment descriptor to define their attributes and to control their deployment and undeployment to the SOAP runtime. When a SOAP request is received by the SOAP runtime, some SOAP header blocks could have the mustUnderstand attribute set to true or 1. The SOAP 1.1 and SOAP 1.2 specifications indicate that a provider must generate a fault message if it is the intended actor on the SOAP header block and it does not have knowledge about how to process the particular SOAP header block. The provider Web service deployment descriptor has an element that signifies to the SOAP runtime whether it should perform this validation.
  • If the VerifySOAPHeaders element is set to true, the SOAP runtime compares the unique namespace URIs present in all SOAP header blocks of the SOAP request with the namespace URIs of the SOAP message handlers that were listed in the provider Web service deployment descriptor.
  • If any namespace URIs appear in the SOAP request for which a SOAP message handler is not known, the SOAP runtime generates a fault message to be returned to the originator.
  • The VerifySOAPHeaders element should be set to false if there are SOAP header blocks that will be processed by Web service wrappers or by the application itself; otherwise, erroneous fault messages could be generated.
It is also possible for a SOAP response message (that is received because of a SOAP consumer request) to contain SOAP header blocks that have the mustUnderstand attribute set to true or 1. Unlike provider Web services, however, consumer Web services cannot return fault messages to the original provider to indicate that they do not understand the SOAP header block. The consumer Web service deployment descriptor has an element that indicates to the SOAP runtime whether it should validate the SOAP header blocks that are received as part of SOAP responses.
  • When the VerifySOAPHeaders element is set to true, the SOAP runtime compares the unique namespace URIs that are present in all SOAP header blocks of the SOAP response with the namespace URIs of the SOAP message handlers that were listed in the consumer Web service deployment descriptor.
  • When the namespace URIs appear in the SOAP response for which a SOAP message handler is not known, the SOAP runtime stops processing the SOAP response and returns an error to the application that originated the request.