Visual Objects Talks SOAP – Part 2

Introduction

In the 1st part of this article – in magazine nr. 87 - we have been looking mostly at the theoretical parts behind XML, SOAP and WSDL so far. Now we will put an end to the theory here and approach the stuff more practically. Let’s start doing things!

Programming & publishing  a web service

In the following we will program a web service in two different ways. First of all, because this is a VO article, we will use Visual Objects to expose a class as a web service. We will see which tools we need, and how to use them. In a second test, we will build a web service on top of Sybase SQL Anywhere Version 9.

Using Visual Objects 2.7b

Unlike most modern environments (like the .NET framework), VO doesn’t have any native SOAP or web service support. Fortunately, Microsoft offers a toolkit which we can used to very easily add SOAP support to our beloved VO environment. We need to download and install the so called SOAP Toolkit, which can be found at:

http://www.microsoft.com/downloads/details.aspx?FamilyID=66ba5e7f-d98f-4cdd-9bf6-7663c7310cb1&displaylang=en

The SOAP toolkit includes an ActiveX control, which can be used to automate the SOAP messages being sent to a service, or received by it.

The second thing we need is often already running on your XP machine: IIS. We don’t want to make our own HTTP server, but we’re using the IIS as a host for our web service component. So far, that’s all we need.

A new ActiveX component

Visual Objects enables us to create ActiveX components, which can be used by other systems. Therefore, our web service is constructed as an in-process OLE automation server. Which other system you might ask? Well...IIS will host our VO DLL, and redirect SOAP request for the web service automatically to our VO component.

After pressing the OK button VO will generate a skeleton for an ActiveX component. Now that we have customized this generic skeleton to our own needs, we still need to adjust the application options.

The ProgId is the key which will be used to identify our component through the registry. In the field “Automation” we have to provide the name of the class we’re going to publish.

Implementation of the functionality

What to do, what to do … the hardest thing is to decide what services to offer. Let’s start with something very simple. We will publish a method which will return the current timestamp from the server, and a second method, to echo input. So, here’s the class definition:

CLASS DevFest2005Webservice INHERIT AutoServer
DECLARE METHOD GetDateTime
DECLARE METHOD Echo

So the class DevFest2005Webservice, which represents our web service, will publish two methods: GetDateTime and Echo. Here’s the implementation:

METHOD INIT() CLASS DevFest2005Webservice
SUPER:init()

METHOD Echo ( input AS STRING ) AS STRING ;
PASCAL CLASS DevFest2005Webservice
RETURN input

METHOD GetDateTime) AS STRING ;
PASCAL CLASS DevFest2005Webservice
Return DTOS(today())+” “+time()

Some do’s and don’ts in this period of work are:

• Don’t forget the Super:Init()! If you forget this, the web service will be instantiated, but the internal ActiveX mechanisms won’t be initialized. In this case, the life management of the component doesn’t work. That invalidates the component, and eventually leads to a runtime error.
• Web services should be principally stateless.
• Program as defensive as you can.
• Modal dialogs and DataDialog have to be avoided, because they would kill the server.
• A web service should always implement a simple mechanism to test the communication and accessibility. In our example, this is the method echo, which simply echoes the given string back to the client.

Program as defensive as you can

Publish with the SOAP toolkit, or….

We’ll take a closer look at the SOAP toolkit later on. At the moment, we will use a helpful little tool out of the package, called wsdlgen3.exe. It helps us generate a WSDL document for our web service (remember, this will be needed by others to examine the capabilities of our service) and secondly it will generate an ASP file, which is a kind of glue between the IIS and our component. So just let’s get started wsdlgen3.exe:

Let’s press on to the next, more interesting page.

At the moment, we don’t have a configuration file. This dialog is helpful if you have to re-generate the information. We’ll leave this dialog untouched and go to the next dialog.

Now the tool can inspect the component, and determine which methods are being offered. If there may be “internal” methods, which should not meant be published, they can be disallowed on the next dialog.

P

Press finish and you’re ready.

Publish the service

Due to the fact, that the VO-DLL is being used via SOAP-toolkit, you have to make sure that the toolkit is installed on the machine where the IIS is running on. Then you have to perform the following steps:

1. Create a physical directory for the generated documents and DLL’s. Remember to copy the VO runtime DLL’s to this directory, if you can’t access them via a path variable.
2. Create a virtual directory inside IIS. The name of the page should be the same as you used during the generation of the WSDL document.
3. The VO-DLL, which represents the service, must be registered on the server where IIS is running on! Use regsvr32.exe for this purpose.

Caution : If you have to update the component on your server, you have to unload the web page from the IIS administration tools. Otherwise, you might not be able to re-write it; it’s still in use. Sometimes, it’s necessary to unload the standard web site to clear the cache.

Test the web service

After a successful installation, it’s a good idea to test it:

1. Using a browser, navigate to the URL of the WSDL document. This should be shown in the browser then.
2. Connect the web service by using a simple client program and test the echo method.

Using Sybase SQL Anywhere Version 9

Version 9 of Sybase SQL Anywhere enables Adaptive Server Anywhere-Database Server to act as a web server (HTTP server). That way we don’t need other products (in particular, no IIS) other than Adaptive Server Anywhere and a browser to build web-based applications. This new functionality allows the database server to accept HTTP-, HTTPS- or SOAP-requests.

Adaptive Server Anywhere Version 9 must be installed on your machine. If you were lucky, you already hold one of the demo CD’s in your hands, or even better already have bought the full blown product. If not, you can download the free demo version from http://www.ianywhere.com/promos/dev_edition/index.html.

Shut down any web servers (HTTP servers) which may be running (including ASA and Microsoft IIS) on the server machine (in our sample, this is our development machine). 

Build the service

Building a service on top of Adaptive Server Anywhere is straightforward. The only problem, at least I think, is that Sybase uses technical terms, which are quite different from previous definitions. In the Anywhere-context, a service corresponds to the method of a web service. The web service itself is a so-called DISH service. Don’t worry about these different vocabulary, lets add a new service to the demo database, which is installed with Version 9:

call sa_make_object('procedure','sp_sample');

ALTER PROCEDURE "DBA"."sp_sample" AS MESSAGE
  'SOAP Request Received!' SELECT * FROM department;

call sa_make_object('service','sqldish');
ALTER SERVICE sqldish TYPE 'DISH'
AUTHORIZATION OFF USER DBA USING sqlservice;

call sa_make_object('service','sqlservice/sample');
ALTER SERVICE "sqlservice/sample" TYPE 'soap'
AUTHORIZATION OFF SECURE OFF USER DBA AS
  CALL sp_sample();

This little script adds a stored procedure ‘sp_sample’ to your database, which, when called, prints a message on the console window and returns a result set. In addition, it adds two service definitions to the database:

• A service named “sqldish” which serves as a container for the definition of other services.
• A service named “sample”, which is added to the previously defined container.

Shut down the server.

Activate the service

The service will be automatically activated, when the server restarts with the HTTP server enabled. To do so, start the server engine with the following parameters:

dbeng9 -xs http "%asany9%\asademo.db"

This way the server acts now as an HTTP server and should respond to your request.

Test the service

Open your browser and navigate to http://localhost/sqldish?wsdl. 

If everything works as expected, you should see the following WSDL document (which is only partially displayed here):

  name="sqldish"
  targetNamespace=http://localhost/asademo/sqldish
  xmlns:s3=http://localhost/asademo/sqldish
  ... >
  
    ...
 
  
    
  
  
    
  
 
   
 
  
    
      
      

      
    

 
       type="s3:sqldishSoapPort">
          transport="http://schemas.xmlsoap.org/soap/http"/>
    
              http://localhost/asademo/sqlservice/sample
        style="document" />
      
        
      
      

        
      

      
        
      
    
  
 
   
      
    
  

Easy, isn’t it? So much for the server side of things.

In the the 3^rd and las part of this article, we will be heading for something completely different: the client side!