This sections presents how to use and write Common Gateway Interface (CGI) applications. The CGI standard was originally defined for UNIX web servers, in which information is passed back and forth between the server and the CGI by means of UNIX environment variables and output redirection. Since neither of these functions are available on the Macintosh, CGIs on the Mac platform use AppleEvents to communicate.

The use of AppleEvents for CGI applications is a mixed blessing. Because AppleEvent support is built into the Macintosh operating system, it is relatively easy for application programmers to write AppleEvent-capable applications. Using AppleScript, it is even possible to write AppleEvent handling applications without having to resort to lower-level programming languages like C or C++. AppleEvents are also a limiting factor: they are slow (the AppleEvent Manager is emulated on PowerMacs), and can only pass 64 kilobytes of data in a single event. AppleEvents are not the best possible solution to supporting CGI applications on the Macintosh, but they are the "standard", so that's what Quid Pro Quo supports.

Quid Pro Quo also supports WebSTAR® plug-ins. They provide a faster solution to extending your web server, and incur less overhead than external, AppleEvent-based CGIs. Quid Pro Quo includes several plug-ins, for purposes ranging from remote administration, image-map handling, and automatic directory indexing.


Using CGIs

To use a CGI, a user simply specifies the CGI in the URL. For instance, say you have a CGI called "hello.cgi" that does nothing but return a greeting to the user. The user would specify the URL

http://www.yoursite.com/hello.cgi

When the user opens the URL, Quid Pro Quo launches the CGI, which processes the request and returns the greeting.

More sophisticated CGIs can take arguments to do more complex processing. There are three different ways to pass arguments to a CGI: the path arguments, search arguments, and the post arguments. For instance, an image map handling CGI needs to know the name of the image map file and the coordinates that the user clicked on. For this, the client uses the path arguments and search arguments. The URL in this instance (which is handled automatically by the client's browser software) might be:

http://www.yoursite.com/imagemap.cgi$example.map?39,72

The path arguments are the text after the '$' (and before the '?', if search arguments are included), while the search arguments are the text after the '?'.

Post arguments are typically used in form-processing applications. Unlike the path and search arguments, post arguments do not appear in the URL. Rather, they are placed in the body of HTTP message.

If you are using a third party CGI, refer to the documentation that came with it to learn how to use the arguments for that particular CGI. There are numerous freeware, shareware, and commercial CGIs available, with capabilities ranging from image map handling, forms processing, to graphical hit counters to many others. If you are writing your own CGI, you will have to determine how you want to use the CGI arguments to get the information you need.


Writing CGIs

Quid Pro Quo CGIs can be written in AppleScript or in a programming language such as Pascal or C. The following information presumes a knowledge of AppleEvents and their use in AppleScripts and applications.

When Quid Pro Quo receives a URL request for a CGI, it first launches the CGI. It then constructs an AppleEvent that describes the user request, sends it to the CGI, and waits for a reply. The AppleEvent sent is of class 'WWWomega' (the Greek letter omega is option-Z, which doesn't display well in HTML) and the event code is 'sdoc'. Each 'sdoc' event that your script or application receives will contain a standard set of parameters, which are based on the client request. All parameters are passed as typeChar character strings. They are:

A CGI returns its data in the AppleEvent reply. A CGI is expected to always return a result, even when an error occurs (the exception to this is postprocessor CGIs, which should never return a result). The result should be a full document (usually an HTML page), including the HTTP header. Since the server does no further processing on the results returned from the CGI, the result must be in a form that the client's web browser can deal with.

CGIs built in AppleScript must be saved as Applications, NOT as text-only or compiled scripts. Be sure to choose the "Never Show Startup Screen" and "Stay Open" options selected. Without these options, your CGI will not work correctly. Note that Quid Pro Quo does not support text AppleScripts. All AppleScripts must be built as applications. The reason for this is performance: text scripts would have to be compiled and launched each time they are run (very slow), and it is no more difficult to save the script as an application.

Quid Pro Quo ships with a number of sample CGI applications, written in AppleScript, C, and C++ (with full source code). You can use these CGIs as a basis of your own custom applications.


CGI versus ACGI

CGI applications run "synchronously" while ACGI applications run "asynchronously". What this means is that when Quid Pro Quo passes a request to a CGI application, it waits for the result, doing no more processing until it receives one. In contrast, while processing an ACGI request, Quid Pro Quo continues to process other requests, even requests for the same CGI. Obviously, from a performance standpoint, ACGIs are preferable to CGIs. However, it is not always possible to use ACGIs. The problem lies in reentrancy: the ability to handle two requests simultaneously. While running as an ACGI, an application may receive a request before it has finished processing a previous request. Not all applications can handle this. AppleScript applications, for instance, have a difficult time with receiving multiple, simultaneous AppleEvents.


Server Push

In the usual CGI model, a single AppleEvent is sent to the CGI, which processes the request and returns its result in the reply to the original event. The server push feature allows you to return data as multiple data packets. The mechanism for this is the "Send Partial" AppleEvent. If your CGI intends to use server push, instead of returning its result in the reply to the original event, it should return "<SEND_PARTIAL>" as the result. This tells Quid Pro Quo to keep the connection open, and send any data that is received via "Send Partial" events. To pass data on to the client, the CGI sends the "Send Partial" event (class 'WWWomega' [option-Z], event code 'SPar'). The event contains the data to be sent to the client in the direct parameter. The event should also contain the 'Kcid' parameter identifying which connection the data is to be sent to (the 'Kcid' parameter is obtained from the original event. A third parameter, 'Kmor' (typeBoolean) indicates whether or not there is more data to follow. If false, Quid Pro Quo closes the connection and expects no more data from the CGI. If Quid Pro Quo returns an error when the event is sent, the client has closed the connection and no more data should be sent. The Quid Pro Quo distribution included a sample server push CGI written in C++ that demonstrates how to create server-based animations.


Send questions and comments to me, Chris Hawk

Welcome | Contents | Glossary