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
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,
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
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.
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