Using SOAP services

To illustrate many of the features of web services, start with a simple Fahrenheit to Celsius temperature convertor as a sample service.

To set up a simple web service server
  1. Create a database.

    dbinit ftc
  2. Start a server using this database.

    dbsrv11 -xs http(port=8082) -n ftc ftc.db
  3. Connect to the server using Interactive SQL.

    dbisql -c "UID=DBA;PWD=sql;ENG=ftc"
  4. Using Interactive SQL, create a web service.

    CREATE SERVICE FtoCService
    TYPE 'SOAP'
    FORMAT 'XML'
    AUTHORIZATION OFF
    USER DBA
    AS CALL FToCConvertor( :temperature );
  5. Define the stored procedure that this service is to call to perform the calculation needed to convert from a temperature expressed in degrees Fahrenheit to a temperature expressed in degrees Celsius:

    CREATE PROCEDURE FToCConvertor( temperature FLOAT )
    BEGIN
        SELECT ROUND((temperature - 32.0) * 5.0 / 9.0, 5) 
        AS answer;
    END;

At this point, you now have a SQL Anywhere web service server running and ready to handle requests. The server is listening for SOAP requests on port 8082.

So how can you test this SOAP request server? The simplest way to do this is to use another SQL Anywhere database server to communicate the SOAP request and retrieve the response.

To send and receive SOAP requests
  1. Create another database for use with a second server.

    dbinit ftc_client
  2. Start the personal server using this database.

    dbeng11 ftc_client.db
  3. Connect to the personal server using another instance of Interactive SQL.

    dbisql -c "UID=DBA;PWD=sql;ENG=ftc_client"
  4. Using Interactive SQL, create a stored procedure.

    CREATE PROCEDURE FtoC( temperature FLOAT )
      URL 'http://localhost:8082/FtoCService'
      TYPE 'SOAP:DOC';

    The URL clause is used to reference the SOAP web service. The string 'http://localhost:8082/FtoCService' specifies the URI of the web service that is going to be used. This is a reference to the web server that is listening on port 8082.

    The default format used when making a web service request is 'SOAP:RPC'. The format chosen in this example is 'SOAP:DOC', which is similar to 'SOAP:RPC' but allows for a richer set of data types. SOAP requests are always sent as XML documents. The mechanism for sending SOAP requests is 'HTTP:POST'.

  5. You need a wrapper for the FtoC stored procedure, so create a second stored procedure.

    CREATE PROCEDURE FahrenheitToCelsius( temperature FLOAT )
    BEGIN
        DECLARE result LONG VARCHAR;   
        DECLARE err INTEGER;
        DECLARE crsr CURSOR FOR 
            CALL FtoC( temperature );
    
        OPEN crsr;
        FETCH crsr INTO result, err;
        CLOSE crsr;
    
        SELECT temperature, Celsius 
        FROM OPENXML(result, '//tns:answer', 1, result)
             WITH ("Celsius" FLOAT 'text()'); 
    END;

    This stored procedure acts as a cover procedure for the call to the web service. The FtoC stored procedure returns a result set that this stored procedure processes. The result set is a single XML string that looks like the following.

    <tns:rowset xmlns:tns="http://localhost/ftc/FtoCService">
     <tns:row>
      <tns:answer>100</tns:answer>
     </tns:row>
    </tns:rowset>

    The OPENXML function is used to parse the XML that is returned, extracting the value that is the temperature in degrees Celsius.

  6. Call the stored procedure to send the request and obtain the response.

    CALL FahrenheitToCelsius(212);

    The Fahrenheit temperature and the Celsius equivalent appear.

    temperature Celsius
    212 100

At this point, a simple web service running on a SQL Anywhere web server has been demonstrated. As you have seen, other SQL Anywhere servers can communicate with this web server. There has been little control over the content of the SOAP requests and responses that have traveled between these servers. In the next section, you will see how this simple web service can be extended by adding your own SOAP headers.

Note

The web service can be provided by the same database server, but must not reside in the same database as the client function. Attempting to access a web service in the same database results in the error 403 Forbidden.

For information about SOAP header processing, see Working with SOAP headers.