tpf_soap_handler_ext: Pass SOAP information to the SOAP handler with extended options
This function passes SOAP message and communications information to the SOAP handler. The function is called by the SOAP communications binding program for the z/TPF HTTP server, which enables the SOAP handler to process SOAP messages synchronously (the same ECB handles the request and sends the response) or asynchronously (different ECBs handle the request and response).
Last updated
Changed in 2025.
- Added for PUT09.
Format
#include <tpf/c_soap.h>
int tpf_soap_handler_ext(void *inputMsg,
void *outputMsg,
commsBindingExt *commsBinding);
- inputMsg
- A pointer to an input instance of the soapMsg structure
that was previously initialized. The soapMsg structure contains
the following fields:
- msgLength
- The length of the XML message being passed.
- XMLptr
- A pointer to the first byte of the XML message being passed.
- tpf_ccsid_t serverEncoding
- Identifies the host encoding of the z/TPF system, where serverEncoding is initially set to TPF_CCSID_NOT_SET.
- tpf_ccsid_t clientEncoding
- Identifies the encoding of the XML message being passed, where clientEncoding is the coded character set identifier (CCSID) of the XML message.
- options
- Specifies any appropriate option flags. The value of this field is 0.
- SOAP_VERSION version
- Identifies the version of SOAP being used, where version is
one of the following:
- UNKNOWN
- SOAP version is not known; also used if the communications binding cannot determine the version without reading the actual XML document.
- SOAP1_1
- SOAP version is 1.1.
- SOAP1_2
- SOAP version is 1.2.
- outputMsg
- A pointer to an output instance of the soapMsg structure that is used for the output message. The soapMsg structure was previously initialized to NULL by the communication binding. The fields for the outputMsg field are the same as for the inputMsg field.
- commsBinding
- A pointer to a commsBindingExt structure that was previously initialized. The commsBindingExt structure was completed by the communication binding based on the SOAP message received from the client.
- The commsBindingExt structure contains the following
fields:
- BINDING bindingType
- Specifies the communication method used, where bindingType is one of the
following values:
- tpf_HTTP
- The z/TPF HTTP server is the communications binding
- otherbinding
- A communications binding other than the z/TPF HTTP server is the communications binding. See the
BINDING enumeration in the c_soap.h header file for acceptable values. The
communications binding must be able to take a message from the network and pass the appropriate
information to this function.
- applRoutingInfo
- Specifies appropriate application routing information. This field is initialized with a pointer to the requested URI, which is represented as a null-terminated EBCDIC string.
- ECBctl
- Specifies options for use during communications processing:
- DEFAULT
- Use default processing.
- termAfterCxn
- Exit the entry control block (ECB) when the connection ends.
- termAfterReply
- Exit the ECB after the reply has been sent.
Note:- The ECBctl field is extendable. See the c_soap.h header file for acceptable values.
- The ECBctl field is not used if the bindingType is tpf_HTTP.
- BINDING_VERSION version
- Identifies the commsBindingExt structure version.
- BINDING_EXT_V1
- Version 1.
- tpf_Token
- One of the following values:
- Asynchronous SOAP request message token used by communications binding types that allows for
asynchronous SOAP message processing (such as
tpf_HTTP) to associate an asynchronous SOAP response message with the original SOAP request message. - X’00’s
- Asynchronous SOAP request message token used by communications binding types that allows for
asynchronous SOAP message processing (such as
- asyncResponsePgm
- The 4-character program name identifying the communications
binding response program used to send the SOAP response message. If the binding type is
tpf_HTTP, this field must be set to CSOX. For communication binding types that do not support asynchronous SOAP message processing, this field must be set to X'00's. - asyncReqTimeout
- Integer representing the asynchronous SOAP request timeout
value in milliseconds. If a SOAP response is not received for the SOAP request, a SOAP fault
response message is sent. If an asynchronous SOAP message is being processed (if
asyncResponsePgm is specified), this field must be nonzero. For communication
binding types that do not support asynchronous SOAP message processing, this field must be set to
X'00's.
Normal return
- Synchronous communications binding types (asyncResponsePgm not specified)
- SendReply
- Asynchronous communications binding type (asyncResponsePgm specified)
- SendReply
- No Return
- The SOAP message is being processed asynchronously and the current ECB has been exited in the Web service wrapper program for the SOAP request message.
Error return
One of the following is returned
to the caller:
- SendErrorReplySender
- A client error occurred and the SOAP message could not be processed.
The XMLptr field in the soapMsg structure is updated
with one of the following values:
- A pointer to the SOAP fault output message that is sent to the client.
- NULL. A SOAP fault output message is not sent to the client.
- SendErrorReplyReceiver
- A server error occurred and the SOAP message could not be processed.
The XMLptr field in the soapMsg structure is updated
with one of the following values:
- A pointer to the SOAP fault output message that is sent to the client
- NULL. A SOAP fault output message is not sent to the client.
- SendMessageFailure
- The asynchronous response program received an error from tpf_httpSendResponse
Note: The soapMsg structure is completed
and tpf_soap_build_fault is
called when there is an error. The SOAP handler translates the fault
message after it is built, and the soapMsg structure is updated
with a new pointer and length.
Programming considerations
- tpf_soap_handler can be used for communications binding programs that require synchronous SOAP message processing.
- You can extend this function by using the SOAP handler exit (tpf_soap_handler_exit) user exit (CSO2), which allows you to specify how to translate a SOAP message, log messages, or perform any other user-specific processing your system requires to process the incoming SOAP message. See the code comments in this user exit for more information.
- If the XMLptr field is not NULL when this function completes, the storage associated with the input XML document is released.
- The asynchronous SOAP handler checks the Web service deployment table (WSDT) for the subsystem in which the ECB is running to determine the deployment status of the Web service to be called.
- The communications binding response program specified in asyncResponsePgm must
take the following input parameters in the following order:
- soapMsg *OutputMsg
- Pointer to SOAP response message
- commsBindingExt *binding
- Pointer to extended communications binding info
- int *soapResponseStatus
- Status of SOAP response message
Examples
In the following SOAP communications
binding example, a SOAP request is received from the z/TPF HTTP server
to be processed asynchronously by the SOAP handler:
#include <tpf/c_soap.h>
void CSOH (tpf_httpsvr_req *requestMsg, tpf_httpsvr_token token)
{
soapMsg inputMsg = {0};
soapMsg outputMsg = {0};
commsBindingExt binding = {0};
inputMsg.clientEncoding = TPF_CCSID_IBM1047;
inputMsg.msgLength = requestMsg->bodylen;
inputMsg.XMLptr = requestMsg->body;
binding.bindingType = tpf_HTTP;
binding.applRoutingInfo = requestMsg->url;
memcpy(&binding.tpf_Token, &token, sizeof(binding.tpf_Token));
binding.asyncReqTimeout = requestMsg->requestTimeout; /* milliseconds */
binding.version = BINDING_EXT_V1;
/* program to send the async response */
memcpy (binding.asyncResponsePgm, "CSOX", sizeof(binding.asyncResponsePgm));
tpf_soap_handler_ext(&inputMsg, &outputMsg, &binding);
exit(0);
}