An Introduction to CGI scripting

The Common Gateway Interface(CGI) is a specification for how programs are to be written to enable a web client to ask a web server to run the program on the client's behalf. It is not a scripting language by any stretch but rather a few simple rules to which programs should adhere when being written for the web.

     +-------------------+              +-------------------------------+
     | Client Machine    |              |                               |
     |  +--------------+ |              | +-------------+               |
     |  | BROWSER      |-|--request---->| | httpd       | Web Server    |
     |  +--------------+ |              | +-------------+  Machine      |
     |                   |<--response---|   \/   /\                     |
     +-------------------+              | +-------------+               |
                                        | | cgi app.    |               |
                                        | +-------------+               |
                                        +-------------------------------+

The client machine asks the web server for a page that happens to involve a CGI request. The web server program on the web server machine(httpd) will then run the cgi application and send the results back to the client machine. This differs from a regular web page request in that the server actually has to run a program to generate the output instead of simply opening a file. CGI programs can also be used to generate any type of information on the fly. For example, the counter on the UofL homepage is actually an image file generated dynamically every time the page is requested. The browser doesn't know that it's getting a program, it only knows it's getting an image of some sort.

The Form

Most CGI programs rely on an HTML form to get the information to them. An example would be the UofL mail gateway. This program takes information from a form and processes that information to generate output for the user. There are a few other ways that CGI programs can get their information.

• The environment

  Every program runs in its own environment. All of the information found in that output can be used by a program to figure out what kind of browser the client is using and where they are coming from as well as information about the web server itself.

• The Path Information

  Stuff put after the name of the actual CGI program but preceded by a '/' is called PATH INFORMATION. This is available to a CGI program and can be used as a way to get information to a program without writing an html form.

• The query string

  Data can also be packed on to the end of a URL following a '?' and the program will interpret it as form information.

The form; however, remains the most effective. A few examples of forms used on UofL's site are:

• PPP account requests
• UofL Mail Forms
• Schedules of Courses.

Forms are quite varied in what they do and how they accomplish it. The thing to remember is that it is not the form but the program at the other end that does the work. The example forms are simply html that sends information to a program. They do not run anything. The programs that are called are where CGI comes in.

How CGI information is gathered by the program.

All CGI information that comes into a program must be parsed or processed somehow. The documentation for CGI and how the information comes into the computer is stored at NCSA. How the program handles this information is dependent upon the language in which the program is written. The examples given on athena will be for UNIX and written in shell or PERL. There are libraries all over the 'Net for most languages to help with the basic cgi stuff. The basic items to remember are:

• client and server information not specific to the query are stored in the environment.
• query specific information using the GET method comes in the form of the QUERY_STRING in the environment.
• query specific information using the POST method comes in on STDIN with a total of CONTENT_LENGTH (in the environment) bytes.
• every item in the form is separated by an '&' and put in the form of name=value. If you had a box called "comments" in the form and the user put "great page" in the form, the query would come in as:

        comments=great+page

  Other information would also be separated by '&'
• Spaces become '+'
• Special characters are encoded in the form of %(NN) where NN is a hex number equalling their ASCII code (find someone else's code of how to decode this-- it makes life easier).

Examples of CGI in action on UofL's site

There are hordes of CGI programs on UofL's site. These are just a few examples that can be used by anyone. Documentation for the supported and documented programs that have been developed or modified for UofL is at http://www.louisville.edu/docs/. That page can be an invaluable source for how-to and FAQ pages concerning programs on the web server.

• http://www.louisville.edu/docs/cgi/count.html is the help page for using a graphical counter page in your homepage.
• http://www.louisville.edu/docs/cgiemail/uofl.mail.html. The UofL email gateway documentation for making a nice link for users to send mail to a site's publisher.

Common questions about CGI programming

It is important to have a working program in order to have a working CGI script. Below is a list of common issues and their resolutions.

1. Where is perl or sendmail?
   • In the Unix environment, it is important to know the location of external programs you plan to call in your program. The best way to find the answer is to execute the following command at the Unix prompt: which perl or which programname . This is particularly important for correcting a scripts shebang line.

2. Why won't my program work?
   • It is important to transfer perl scripts in ASCII mode in WS_FTP. Often the extra carriage reture, or ^M, at the end of line will cause the program to fail.