TclSOAP CGI Server Package

• Introduction
• Installation
• Writing Services
• TclSOAP main page

The SOAP::CGI package allows you to provide SOAP web services from Tcl scripts via the CGI script capabilities of your web server. This document describes the use of this package with the Apache httpd server but the package should be applicable to any other server supporting the Common Gateway Interface.

The package provides a fairly comprehensive framework to deal with hiding the details of the web service protocols. The Tcl scripts implementing the service need to know nothing of XML nor the RPC protocol in use. Errors are returned via the normal Tcl error mechanism. The only special feature needed is variable type hinting. It is not possible to distingush between a string with whitespace and a list in Tcl, so the XMLRPC::TypedVariable package is used to provide the additional type information when required.

Installation really only requires placing a script into the http servers cgi-bin directory and writing some service implementations. A generic script is provided as cgi-bin/rpc with some example services in cgi-bin/soap. The package has three variables to configure so that it can find the service implementations:

The script needs to be able to execute using tcl 8.3 or better and needs to be able to find the TclSOAP package. Bear in mind that the httpd process will not run with your environment (unless you are working on Windows). The supplied script shows how you can set the location of the package, should you need to. If you are using the Windows Apache server then you can't set the environment before execing tclsh so you need to manipulate the auto_path variable from within the CGI script instead.

Upon receipt of an HTTP POST the CGI framework examines the data and decides which RPC protocol should handle the request. The handlers then retrieve the method name from the request and look for a file with this name in the configured directory. This is sourced and then evaluated with the arguments obtained from the POST data. For example, the implementation for the square service will be the file ../method-scripts/square with the following code:

proc square {num} {
    return [expr $num * $num]
}

For more complex types such as structs, the reply will need to be an XMLRPC::TypedVariable so that the RPC handler can package the result correctly. So the implementation of the platform service which returns a struct containing the ::tcl_platform variable information is as follows

package require XMLRPC::TypedVariable
proc platform {} {
    return [XMLRPC::TypedVariable struct [array get ::tcl_platform]]
}

Structs are passed to the implementing procedure as a list of name value pairs suitable for use with array set ..., arrays are passed in as Tcl lists and everything else is passed in as a string. If the result type cannot be guessed then you should return a typed variable otherwise it will be assumed to be a string. The only types that can be guessed are integer, double and boolean (if expressed with true or false).

Look in the cgi-bin/soap subdirectory in the TclSOAP distribution for some examples of service implementations. There is an implementation of the UserLand SOAP interoperability suite that is used to ensure the package conforms to this standard. These illustrate the use of arrays and structs fairly comprehensively.

This site is hosted by SourceForge