Contents

1. What Is A CGI Script?
2. What Do I Need To Make One?
3. Installing Your script.
4. Calling Your Script From A Web Page.
5. Debugging Your Script.
6. More Information.

What Is A CGI Script ?
(From NCSA)

The Common Gateway Interface (CGI) is a standard for interfacing external applications with information servers, such as HTTP or Web servers. A plain HTML document that the Web daemon retrieves is static, which means it exists in a constant state: a text file that doesn't change. A CGI program, on the other hand, is executed in real-time, so that it can output dynamic information.

For example, let's say that you wanted to "hook up" your Unix database to the World Wide Web, to allow people from all over the world to query it. Basically, you need to create a CGI program that the Web daemon will execute to transmit information to the database engine, and receive the results back again and display them to the client. This is an example of a gateway, and this is where CGI, currently version 1.1, got its origins.

The database example is a simple idea, but most of the time rather difficult to implement. There really is no limit as to what you can hook up to the Web. The only thing you need to remember is that whatever your CGI program does, it should not take too long to process. Otherwise, the user will just be staring at their browser waiting for something to happen.

A Master's degree in Computer Science ! Just kidding. A CGI script can be written in just about any programming language. The ones we support and recommend are:

Perl - Long live the camel.

The path to Perl on our boxes is /usr/local/bin/perl. The version we support is 5.004. Remember the first line of your script must be:

#!/usr/local/bin/perl

and the script must have UNIX line breaks (LF only). I must recommend using the CGI.pm CGI module. We have version 2.31 installed in the standard include path.
For a great Perl reference, the best book going is O'Reilly and Assoc Learning Perl. They also make very concise books on HTML and CGI Programming.

Java/JavaScript.

Java, like javascript, is available if you put everything you need into your directory for the client to download off of your page like any other file or image. No support is necessary on the server side (us). Java and JavaScript aren't really server-side cgi programming tools, but they can accomplish the same effects on the client-side.

You will also need to know some of the principles behind CGI scripting in order to write code for a CGI script. I suggest picking up a good CGI book or checking out some links on the web.

Installing Your Script.

Okay, so you have written a cool CGI script now, you will need to install and test it on the server.

FTP'ing your CGI script to the server.

This is done in the same way you FTP your web pages to the server. There should be a directory called "cgi-bin" in your home directory (full path /home//cgi-bin). If this directory does not exist, simply create it. Place your cgi script in this directory. The convention is to give your CGI scripts an extension of .cgi, however, this is your choice. Don't let anyone bully you.

Line Breaks!!!

One thing to be careful of: If your script is a compiled program (written in C or another compiled language), you must transfer the program in "BINARY" mode. Your FTP program should tell you how to do this. If your script is text (like a Perl or Python script), then it must have UNIX line breaks. You can use the dos2unix program for Windows or DOS, or use BBEdit or Alpha on a Mac and save with UNIX style line breaks. If you are working on a UNIX / Linux machine at home, you are all set.

Making The Script Executable

In order for your script to "run" on the server, it must be set to "executable". That way Mr. Unix knows that it is a program and not a web page. In order to do this, you must use the "SITE" command.

If you thought UNIX was obscure, wait until you hear this. After you logon to your site and upload your script into the cgi-bin directory, right click anywhere on the gray area of the WS-FTP program window. That's what I said. Hammer that right button. After you right click, a drop down box should appear with a number of choices. Click on FTP Commands. Another drop down box should appear with yet more choices. Click on SITE. A small text entry box will appear. Don't be fooled. This little number is your GUI ticket to UNIX nirvana.

What site will allow you to do is send a UNIX command to perform on one of your files right from your FTP program. So, if you want to change your script from a meager file into a (pseudo) executable, type in the following command within the site text area window: chmod 0755 [script-name minus these here square brackets]

For some reason, you cannot use the more intuitive (yeah, right) chmod +x, but using the 0755 code equivalent does the trick. Your script will now run as an executable.

If you are using Fetch on the Mac, ftp to where your script is and select Remote/Send FTP Command. When the dialog box pops up, enter:

SITE CHMOD 0755 [script-name minus these here square brackets]

Now, how many of you knew that? I should be charging big bucks for this kind of arcana and here I am giving it all away. Fortunately, I get paid for my generosity.

Those of you using other architectures such as OS/2, Amiga, Microsoft Bob, etc., should check out your FTP programs and look for a feature that allows you to work the above command on your file. When you find what works, please send me a note about the particulars and I will round out this FAQ with the information.

Calling Your Script From A Web Page.

<form method="POST" action="/cgi-bin/user/<USERNAME>/<SCRIPTNAME>.cgi">

/cgi-bin/user is the wrapper program itself. (Pretty fancy stuff). /<USERNAME> is, of course, your USER ID. /<SCRIPTNAME>.cgi is the name of your executable cgi script. Together, these three items will take in a request from a browser, send it to the server's main cgi-bin directory, run the /cgi-bin/user program, which will covertly redirect the request to your personal, secret cgi-bin directory. Sneaky, hey? It's a good thing the busy hackers in the backroom work for us.

So, as a real world example, let us say that my USER ID is hubba and that I have a cool script called bubba sitting in my cgi-bin directory. My action tag will look like so:

<form method=get action="/cgi-bin/user/hubba/bubba">

Simple, yet oh-so-sneaky. This way, you can set up your own scripts or grab other scripts located on the Net, pull them into your very own cgi-bin directory, and actively push the ephemeral HTML envelope. Best of all, you won't have to say boo to those ever so cheery guys in the backroom who are ever so busy communing with their code.

Debugging Your Script.

Oh dread, it does not work! If your script does not do what you want, you can try calling it like so: <form method="POST" action="/cgi-bin/userd/<USERNAME>/<SCRIPTNAME>.cgi">

By specifying /cgi-bin/userd/ instead of /cgi-bin/user/, it will print all kinds of debugging info for you.

More Information.

• NCSA Info on CGI.
• Yahoo's CGI Page.
• The Web Developers Virtual Library.
• A CGI Programmer's Reference.