The following example attempts to explain how a CGI program functions in the scheme of things on the Web. It uses WebSTAR server software on a Macintosh but can be easily substituted by any number of server configurations.

This document originally came from: http://www.clearink.com/fun_stuff/frontier/CGI.html

What does CGI mean?

CGI stands for "Common Gateway Interface". There. Now you know. The CGI definition provides a standard for external gateway programs to interface with information servers such as WebSTAR. When WebSTAR passes information off to a CGI application it not only sends the data from the user, but it also includes useful information about the transaction such as the client address, username, and password.

How They Work - The Basics

When trying to understand how CGI applications work, the first thing to learn is the difference between the server and the client. Let's say WebSTAR is the server and Mosaic, MacWeb, and Netscape are all clients. When a user clicks on a link, the client send a request to the server to see the file that the link points to. Here's an example of some typical client-server interaction with an HTML page:

  Netscape: I want to look at the page with the URL
            http://www.uwtc.washington.edu/UWHome.html

  WebSTAR: Ah!  That's one of my pages.  Here is all
           the data from the URL you sent.  I'm sending
           it as text.

  Netscape: Ah!  I see the text begins with an HTML tag
            that I recognize.  I'll interpret this as HTML
            then and display it correctly for my user.

  WebSTAR: I couldn't care less how you display it.  I'm
           done dumping the data so goodbye.

As you can see, the client and the server both have their responsibilities in the interaction. The server decides what the client is requesting and how to feed it back to the client. The client decides what to do with what is returned to display it for the user.

When the user requests a URL that involves a CGI application (like clicking on a map, submitting a form, or many other things), the interaction is a little different because there is also interaction between the server and the CGI. Let's take a look now at the conversation that might occur between a server and client when handling a map click (assuming they speak English, of course).

  User: Hmmmm.  A map of Washington state.  There's a star in
        the upper right-hand corner.  I wonder what that's
        for.  Let's click on it.

  Netscape: Let's see, that click was at 287,48.  I'll add
            that to the URL that was given with the map and
            send it back to the server.

  WebSTAR: Hey, someone sent me a URL with some extra data.
           That URL is for a CGI application on this machine.
           Well I'll just send an Apple event to that CGI
           application with the data enclosed in the post_args
           argument.  I'm glad I don't have to do anything to
           the data myself.

  CGI app: Finally, an Apple event!  Let's see, first I
           decode the information in the post_args argument.
           Now I can use these map click coordinates to figure
           out what page to return to the client.  Here it is -
           I'll send the server an Apple event reply,
           containing the URL for the new page and a code to
           redirect the client to that page.

  WebSTAR: Finally.  I've been waiting for this Apple event reply.
           This code says I should redirect the client to this
           other page instead.  I'll send back the new page then.

  Netscape: Here comes another HTML page.  Better display it
            nicely for my user.

  User: Republic, Washington? I've never even heard of that
        place before!

Well, that was a bit long, but it should give you an idea of the complex interactions that go on when you're using a CGI application. There are a couple of important points to remember from the above nonsense:

• The client is responsible for packaging data to be passed to the CGI application. With maps this is easy, but when you begin trying to do forms, there will be significant differences in how clients package the information from a form. Buy plenty of aspirin first or read these tutorial documents. :)
• The server generally does not do any processing of the actual data going to the CGI application or of pages being returned to the client. The server's only job is to handle connections, use the proper method to return pages and files, and handle communications between the client and CGI applications.
• The CGI application is responsible for either returning a complete page, including HTTP header, or for returning a code to redirect to a new URL and the new URL. The server has no idea what is going on and will generate an error if the CGI fails to provide the needed information.
• Apple events are used for communications between WebSTAR and outside applications. There is a special Apple event used for communicating with CGI applications. This Apple event contains quite a bit of information in addition to information passed by from the user, as defined by the CGI definition. Any application that can accept this Apple event and reply to it can be a CGI application.

Synchronicity

Not too long ago (back when it was known as MacHTTP) WebSTAR was only able to handle CGI applications synchronously. That meant that every time a CGI application was called, WebSTAR waited for a response. Therefore, noone else could get any information until that CGI application finished and returned some information. A very slow connection, sending lots of data to a slow application, could tie up your server for several minutes or cause an error when WebSTAR got tired of waiting.

Later, Chuck Shotton added the ability to run the CGI applications asynchronously. This meant that WebSTAR didn't have to wait uselessly while the CGI application ran. Instead, it passed an Apple event to the application then went on processing other things until a reply was received. To distinguish between the two, WebSTAR now recognizes two different file extensions. ".cgi" means the file should be handled synchronously and ".acgi" means to handle it asynchronously. The latter is almost always preferable, but a well-written CGI application can run either way. The key with asynchronous CGI's is to remember that Apple events might be queued up in your application while it is processing the current event. Luckily, this is not a problem with Frontier (unlike AppleScript) since it runs each copy of your CGI within its own "thread".

by Jon Stevens
Original Content: Copyright Jon Wiederspan, 1994,1995
Frontier Content and Modifications: Copyright Jon Stevens, 1995