[Chapter 9] CGI Overview

The Common Gateway Interface (CGI) is an essential tool for creating and managing comprehensive Web sites. With CGI, you can write scripts that create interactive, user-driven applications.

CGI is the part of the Web server that can communicate with other programs that are running on the server. With CGI, the Web server can invoke an external program, while passing user-specific data to the program (such as what host the user is connecting from, or input the user has supplied through an HTML form). The program then processes that data and the server passes the program's response back to the Web browser (see

Rather than limiting the Web to documents written ahead of time, CGI enables Web pages to be created on the fly, based upon the input of users. You can use CGI scripts to create a wide range of applications, from surveys to search tools, from Internet service gateways to quizzes and games. You can count the number of users who access a document or let them sign an electronic guestbook. You can provide users with all types of information, collect their comments, and respond to them.

Teaching CGI programming from scratch is beyond the scope of this book--for that, we recommend CGI Programming on the World Wide Web, by Shishir Gundavaram (O'Reilly & Associates).

In addition, much of the backbone of CGI resides in the HTTP protocol itself. Effective CGI programming requires some knowledge of HTTP headers and status codes, which are presented in this book as follows:

9.1 A Typical CGI Interaction

For an example of a CGI application, suppose you see a fill-in form, such as that in

The HTML that produces this form might read as follows:

<HTML><HEAD><TITLE>Guestbook</TITLE></HEAD>
<BODY>
<H1>Fill in my guestbook!</H1>
<FORM METHOD="GET" ACTION="/cgi-bin/guestbook.pl">
<PRE>
First Name:   <INPUT TYPE="TEXT" NAME="firstname">
Last Name:    <INPUT TYPE="TEXT" NAME="lastname">
<INPUT TYPE="SUBMIT">    <INPUT TYPE="RESET">
</FORM>

The form is written using special "form" tags (discussed in detail in Chapter 10, HTML Form Tags).

The <form> tag defines the method used for the form (either GET or POST) and the action to take when the form is submitted--that is, the URL of the CGI program to pass the parameters to.
The <input> tag can be used in many different ways. In its first two invocations, it creates a text input field and defines the variable name to associate with the field's contents when the form is submitted. The first field is given the variable name "firstname" and the second field is given the name "lastname."
In its last two invokations, the <input> tag creates a "submit" button and a "reset" button.
The </form> tag indicates the end of the form.

When the user presses the "submit" button, the data entered into the <input> text fields is passed to the CGI program specified by the action attribute of the <form> tag.

Transferring the Form Data

Parameters to a CGI program are transferred either in the URL or in the body text of the request. The method used to pass parameters is determined by the method attribute to the <form> tag. The GET method says to transfer the data within the URL itself; for example, under the GET method, the browser might initiate the HTTP transaction as follows:

GET HTTP/1.0 /cgi-bin/guestbook.pl?firstname=Joe&lastname=Schmoe

See Chapter 17, HTTP Overview for more information on HTTP transactions.

The POST method says to use the body portion of the HTTP request to pass parameters. The same transaction with the POST method would read as follows:

POST HTTP/1.0 /cgi-bin/guestbook.pl
	... [More headers here]
firstname=Joe&lastname=Schmoe

In both these examples, you should recognize the "firstname" and "lastname" variable names that were defined in the HTML form, coupled with the values entered by the user. An ampersand (&) is used to separate the variable=value pairs.

The server now passes the variable=value pairs to the CGI program. It does this either through UNIX environment variables or in standard input (STDIN). If the CGI program is called with the GET method, then parameters are expected to be embedded into the URL of the request, and the server transfers them to the program by assigning them to the QUERY_STRING environment variable. The CGI program can then retrieve the parameters from QUERY_STRING as it would read any environment variable (for example, from the %ENV associative array in Perl). If the CGI program is called with the POST method, parameters are expected to be embedded into the body of the request, and the server passes the body text to the program as standard input (STDIN).

(Other environment variables defined by the server for CGI programs are listed in Chapter 11, CGI Environment Variables. These variables store such information as the format and length of the input, the remote host, the user, and various client information. They also store the server name, the communication protocol, and the name of the software running the server.)

The CGI program needs to retrieve the information as appropriate and then process it. The sky's the limit on what the CGI program actually does with the information it retrieves. It might return an anagram of the user's name, or tell them how many times their name uses the letter "t," or it might just compile the name into a list that the programmer regularly sells to telemarketers. Only the programmer knows for sure.

Creating Virtual Documents

The CGI program must then create a new document to be served to the browser, or point to an existing document. On UNIX, programs send their output to standard output (STDOUT) as a data stream that consists of two parts. The first part is either a full or partial HTTP header that (at minimum) describes the format of the returned data (e.g., HTML, ASCII text, GIF , etc.). A blank line signifies the end of the header section. The second part is the body of the output, which contains the data conforming to the format type reflected in the header. For example:

Content-type: text/html
<HTML>
<HEAD><TITLE>Thanks!</TITLE></HEAD>
<BODY><H1>Thanks for signing my guest book!</H1>
	...
</BODY></HTML>

In this case, the only header line that is output is the Content-type, which gives the media format of the output as HTML (text/html). This line is essential for every CGI program, since it tells the browser what kind of format to expect. The blank line separates the header from the body text (which, in this case, is in HTML format as advertised). See Chapter 20, Media Types and Subtypes for a listing of other media formats that are commonly recognized on the Web.

(Notice that it does not matter to the Web server what language the CGI program is written in. On the UNIX platform, the most popular language for CGI programming is Perl (covered in Chapter 15, Perl Quick Reference). Other languages used on UNIX are C, C++, Tcl, and Python. On Macintosh computers, programmers use Applescript and C/C++, and on Microsoft Windows programmers use Visual Basic, Perl, and C/C++. As long as there's a way in a programming language to get data from the server and send data back, you can use it for CGI.

The server transfers the results of the CGI program back to the browser. The body text is not modified or interpreted by the server in any way, but the server generally supplies additional headers with information such as the date, the name and version of the server, etc. (See Chapter 19, HTTP Headers for a listing of valid HTTP response headers.)

CGI programs can also supply a complete HTTP header itself, in which case the server does not add any additional headers but transfers the response verbatim as returned by the CGI program.

Here is the sample output of a program generating an HTML virtual document, with a complete HTTP header:

HTTP/1.0 200 OK
Date:  Thursday, 28-June-96 11:12:21 GMT
Server: NCSA/1.4.2
Content-type: text/html
Content-length: 2041
<HTML>
<HEAD><TITLE>Thanks!</TITLE></HEAD>
<BODY>
<H1>Thanks for signing my guestbook!</H1>
 	...
</BODY>
</HTML>

The header contains the communication protocol, the date and time of the response, and the server name and version. (The 200 OK is a status code generated by the HTTP protocol to communicate the status of a request, in this case successful. See Chapter 18, Server Response Codes for a list of valid HTTP status codes.) Most importantly, it also contains the content type and the number of characters (equivalent to the number of bytes) of the enclosed data.

The result is that after the user clicks the "Submit" button, he or she sees a response such as that in


Tags of Contention	Book Index	URL Encoding