Web services consumer user-defined functions

Simple Object Access Protocol (SOAP) is an XML protocol consisting of the following characteristics:

• An envelope that defines a framework for describing the contents of a message and how to process the message
• A set of encoding rules for expressing instances of application-defined data types
• A convention for representing SOAP requests and responses

DB2 needs the following information to build a SOAP request and receive a SOAP response.

• A service endpoint, for example, http://services.xmethods.net/soap/servlet/rpcrouter
• Some XML content of the SOAP body, which includes the name of an operation with requested namespace URI, an encoding style, and input arguments.
• Optional: A SOAP action URI reference. The reference can be empty, as shown in the following example, http://tempuri.org/ or just ''.

The DB2® function db2xml.soaphttp() does the following actions:

1. It composes a SOAP request
2. It posts the request to the service endpoint
3. It receives the SOAP response
4. It returns the content of the SOAP body

This is an overloaded function that is used for VARCHAR() or CLOB(), depending on the SOAP body.

db2xml.soaphttpv returns VARCHAR():        
    db2xml.soaphttpv (endpoint_url VARCHAR(256),
                     soap_action VARCHAR(256), 
                     soap_body VARCHAR(3072))
                 RETURNS VARCHAR(3072)
db2xml.soaphttpv returns VARCHAR():  
    db2xml.soaphttpv (endpoint_url VARCHAR(256),
                     soap_action VARCHAR(256),
                     soap_body CLOB(1M))
                 RETURNS VARCHAR(3072)


db2xml.soaphttpc returns CLOB(): 
       db2xml.soaphttpc (endpoint_url VARCHAR(256), 
                       soapaction VARCHAR(256),
                       soap_body VARCHAR(3072)) 
                     RETURNS CLOB(1M)
db2xml.soaphttpc returns CLOB(): 
       db2xml.soaphttpc (endpoint_url VARCHAR(256), 
                       soapaction VARCHAR(256),
                       soap_body CLOB(1M))  
                     RETURNS CLOB(1M)

db2xml.soaphttpcl returns CLOB() as locator:
       db2xml.soaphttpcl(endpoint_url VARCHAR(256), 
                        soapaction VARCHAR(256), 
                        soap_body varchar(3072)) 
                     RETURNS CLOB(1M) as locator

Example of a DB2 constructed SOAP request envelope

The example in Figure 1 shows an Hypertext Transfer Protocol (HTTP) post header to post a SOAP request envelope to a host. The bold areas show the web service endpoint (post path and host) and the content of the SOAP body. The SOAP body shows a temperature request for zip code 95120.

POST /soap/servlet/rpcrouter HTTP/1.0  
Host: services.xmethods.net  
Connection: Keep-Alive User-Agent: DB2SOAP/1.0 
Content-Type: text/xml; charset="UTF-8"  
SOAPAction: "" 
Content-Length: 410   

<?xml version='1.0' encoding='UTF-8'?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/ 
                   xmlns:SOAP-ENC=http://schemas.xmlsoap.org/soap/encoding/ 
                   xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance 
                   xmlns:xsd=http://www.w3.org/2001/XMLSchema >
   <SOAP-ENV:Body>
       <ns:getTemp xmlns:ns="urn:xmethods-Temperature">
         <zipcode>95120</zipcode>

       </ns:getTemp>
    </SOAP-ENV:Body> 
</SOAP-ENV:Envelope>

Example of using DB2 to extract the content of the SOAP response envelope

The example in Figure 2 shows the HTTP response header with the SOAP response envelope. The bold content of the SOAP body shows the result of the temperature request. The namespace definitions from the SOAP envelope are not shown here, but they would also be included.

HTTP/1.1 200 OK  
Date: Wed, 31 Jul 2002 22:06:41 GMT  
Server: Enhydra-MultiServer/3.5.2  
Status: 200  
Content-Type: text/xml; charset=utf-8  
Servlet-Engine: Lutris Enhydra Application Server/3.5.2 
  (JSP 1.1; Servlet 2.2; Java™ 1.3.1_04; 
   Linux 2.4.7-10smp i386; java.vendor=Sun Microsystems Inc.)
Content-Length: 467  
Set-Cookie:JSESSIONID=JLEcR34rBc2GTIkn-0F51ZDk;Path=/soap 
X-Cache: MISS from www.xmethods.net  
Keep-Alive: timeout=15, max=10  
Connection: Keep-Alive
<?xml version='1.0' encoding='UTF-8'?> 
<SOAP-ENV:Envelope xmlns:SOAP-ENV=http://schemas.xmlsoap.org/soap/envelope/ 
                   xmlns:xsi=http://www.w3.org/2001/XMLSchema-instance 
                   xmlns:xsd=http://www.w3.org/2001/XMLSchema > 
     <SOAP-ENV:Body> 
           <ns1:getTempResponse xmlns:ns1="urn:xmethods-Temperature" 
           SOAP-ENV:encodingStyle=http://schemas.xmlsoap.org/soap/encoding/ > 
              <return xsi:type="xsd:float">85<return>
           </ns1:getTempResponse>     </SOAP-ENV:Body>  
</SOAP-ENV:Envelope>