Lesson 1: Set up a web server database to receive SOAP requests and send SOAP responses

In this lesson, you set up a new database server and create a SOAP service to handle incoming SOAP requests. The server anticipates SOAP requests that provide a Fahrenheit value that needs to be converted to Celsius.

 To set up a database server for receiving SOAP requests and sending SOAP responses
  1. Run the following command to create a SQL Anywhere database:

    dbinit ftc
  2. Start the network database server using the following command:

    dbsrv12 -xs http(port=8082) -n ftc ftc.db

    This command indicates that the HTTP web server should listen on port 8082 for requests. Use a different port number if 8082 is disallowed on your network.

  3. Connect to the database server in Interactive SQL using the following command:

    dbisql -c "UID=DBA;PWD=sql;SERVER=ftc"
  4. Create a new SOAP service to accept incoming requests.

    Run the following SQL script in Interactive SQL:

    CREATE SERVICE FtoCService
        TYPE 'SOAP'
        FORMAT 'XML'
        AUTHORIZATION OFF
        USER DBA
        AS CALL FToCConvertor( :temperature );

    This script creates a new SOAP service named FtoCService that generates XML-formatted strings as output. It calls a stored procedure named FToCConvertor when a web client sends a SOAP request to the service. You create the FToCConvertor procedure in the next step.

  5. Create the FToCConvertor procedure to handle incoming SOAP requests. This procedure performs the necessary calculations to convert a client-supplied Fahrenheit value to a Celsius value.

    Run the following SQL script in Interactive SQL:



    CREATE PROCEDURE FToCConvertor( temperature FLOAT )
    BEGIN
        DECLARE hd_key LONG VARCHAR;
        DECLARE hd_entry LONG VARCHAR;
        DECLARE alias LONG VARCHAR;
        DECLARE first_name LONG VARCHAR;
        DECLARE last_name LONG VARCHAR;
        DECLARE xpath LONG VARCHAR;
        DECLARE authinfo LONG VARCHAR;
        DECLARE namespace LONG VARCHAR;
        DECLARE mustUnderstand LONG VARCHAR; 
    header_loop:
        LOOP
            SET hd_key = NEXT_SOAP_HEADER( hd_key );
            IF hd_key IS NULL THEN
                -- no more header entries
                LEAVE header_loop;
            END IF;
            IF hd_key = 'Authentication' THEN
                SET hd_entry = SOAP_HEADER( hd_key );
                SET xpath = '/*:' || hd_key || '/*:userName';
                SET namespace = SOAP_HEADER( hd_key, 1, '@namespace' );
                SET mustUnderstand = SOAP_HEADER( hd_key, 1, 'mustUnderstand' );
                BEGIN
                    -- parse the XML returned in the SOAP header 
                    DECLARE crsr CURSOR FOR 
                        SELECT * FROM OPENXML( hd_entry, xpath )
                            WITH ( alias LONG VARCHAR '@*:alias',
                                first_name LONG VARCHAR '*:first/text()',
                                last_name LONG VARCHAR '*:last/text()' );
                    OPEN crsr;
                    FETCH crsr INTO alias, first_name, last_name;
                    CLOSE crsr;
                END;
    
                -- build a response header
                -- based on the pieces from the request header
                SET authinfo = 
                    XMLELEMENT( 'Authentication',
                        XMLATTRIBUTES(
                            namespace as xmlns,
                            alias,
                            mustUnderstand ),
                            XMLELEMENT( 'first', first_name ),
                            XMLELEMENT( 'last', last_name ) );
                CALL SA_SET_SOAP_HEADER( 'authinfo', authinfo );
            END IF;
        END LOOP header_loop;
        SELECT ROUND((temperature - 32.0) * 5.0 / 9.0, 5) AS answer;
    END;

    The NEXT_SOAP_HEADER function is used in a LOOP structure to iterate through all the header names in a SOAP request, and exits the loop when the NEXT_SOAP_HEADER function returns NULL.

    Note

    This function does not necessarily iterate through the headers in the order that they appear in the SOAP request.

    The SOAP_HEADER function returns the header value or NULL when the header name does not exist. The FToCConvertor procedure searches for a header named Authentication and extracts the header structure, including the @namespace and mustUnderstand attributes.

    The following is an XML string representation of a possible Authentication header structure, where the @namespace attribute has a value of "SecretAgent", and mustUnderstand has a value of 1:

    <Authentication xmlns="SecretAgent" mustUnderstand="1">
        <userName alias="99">
            <first>Susan</first>
            <last>Hilton</last>
        </userName>
    </Authentication>

    The OPENXML system procedure in the SELECT statement is used to extract information from the XML string, where the xpath string is set to "/*:Authentication/*:userName", and then stores the result set in the crsr variable. For more information about the OPENXML system procedure, see openxml system procedure.

    The SET statement is used to build a SOAP response in XML format to send to the client. The following is an XML string representation of a possible SOAP response. It is based on the above Authentication header structure example.

    <Authentication xmlns="SecretAgent" alias="99" 
                                mustUnderstand="1">
      <first>Susan</first>
      <last>Hilton</last>
    </Authentication>

    The SA_SET_SOAP_HEADER system procedure is used to send the SOAP response to the client.

    The final SELECT statement is used to convert the supplied Fahrenheit value to a Celsius value. This information is relayed back to the client.

 See also