Footnotes for "CGI Made Really Easy"

Back to main page

1. Sample CGI programs
2. CGI Mailer Script
3. Placing Your Script on the Server
4. Sending an Existing File Back as a Response
5. Other Useful CGI Environment Variables
6. Returning an Image or Other Non-HTML Response from a CGI Script
7. What is the difference between GET and POST?

Sample CGI programs

By request, here are some "hello, world" CGI programs to get you started. The simple version demonstrates CGI output only, and the longer (such as it is) version will echo back any input fields you pass to it. Both Perl and C versions are provided, with source.

• The output-only script:
  • Perl version: run it, or view the source.
  • C version: run it, or view the source.
• The input-echoing script, called with two input fields. Look at the URL listed in your browser after you run the scripts:
  • Perl version: run it, or view the source.
  • C version: run it, or view the source.

CGI Mailer Script

Since putting CGI Made Really Easy in place, I've had tons of people ask how to have form data emailed to them. So here's a simple CGI script that does that, written in Perl, which I call mailer.pl.

Make these changes to the script before putting it in place:

• Make sure the path to your server's perl program is correct, in the first line. You can usually find this with the Unix command "which perl".
• Change the two variables $mailprog and $recipient to match your server's mailing program, and your email address, respectively.
• ... surely you can come up with more imaginative HTML output than I did.

I personally think that the HTML <FORM> tag should allow its action to point to a mailto: URL, and let the browser handle it, but that's not standard yet. Until then, use the script above.

Placing Your Script on the Server

Different Web servers are configured differently. Some let you put your CGI scripts in the same directory as your Web pages, and their filenames should end in ".cgi". Other servers make you put all CGI scripts in a specific directory, usually called "cgi-bin". Your webmaster has all the final answers.

You need to set the right permissions on the program file. It needs to be executable by the server, plus readable if it's a Perl or shell script. In Unix, set the correct permissions with "chmod 750 *.cgi" (or "chmod 755 *.cgi", if your server doesn't have group access to your files-- try both, or ask your webmaster).

If your script doesn't run:

• Try "perl -c myscript.cgi" to check the syntax of your perl script.
• Make sure the path to the perl (or shell) interpreter is correct, in the first line of the script. For example, find the perl interpreter with the Unix command "which perl".
• Of course, make sure your HTML file calls the correct URL of the script, either relative or absolute.
• For clues, run the script from the command line and see how it fails. This doesn't always get far, because the CGI environment variables aren't set correctly. Get farther by tweaking a test copy of your source code.

Sending an Existing File Back as a Response

If your HTML response is always the same, or if you want to respond with one of several existing files, you may find the "Location:" response header useful. Use it to redirect the browser to another URL.

By way of example, if your CGI script prints the following line to STDOUT:

Location: response.html

In this situation, do not print the "Content-type:" response header.

Other Useful CGI Environment Variables

CGI scripts have access to 20 or so environment variables, such as QUERY_STRING and CONTENT_LENGTH mentioned on the main page. Here's the complete list at NCSA.

A few others you may find handy:

REQUEST_METHOD

The HTTP method this script was called with. Generally "GET" or "POST".

HTTP_REFERER

The URL of the form that was submitted. This isn't always set, so don't rely on it. Don't go invading people's privacy with it, neither.

PATH_INFO

Extra "path" information. It's possible to pass extra info to your script after the filename of the CGI script. For example, calling the URL

http://www.myhost.com/mypath/myscript.cgi/path/info/here

will set PATH_INFO to "/path/info/here". Commonly used for path-like data, but you can use it for anything.

SERVER_NAME

Your Web server's hostname or IP address.

SERVER_PORT

Your Web server's port (at least for this request).

SCRIPT_NAME

The local URL of the script being executed. The CGI standard is unclear on whether the leading slash is included. You can support both cases with this line of Perl, which guarantees "no leading slash":
$ENV{'SCRIPT_NAME'}=~ s#^/## ;

So the URL of the script that's being executed is, in Perl,

"http://$ENV{'SERVER_NAME'}:$ENV{'SERVER_PORT'}/$ENV{'SCRIPT_NAME'}"

The complete URL the script was invoked with may also have PATH_INFO and QUERY_STRING at the end.

Once again, see them all at NCSA's complete list.

Returning an Image or Other Non-HTML Response from a CGI Script

Most CGI scripts return HTML data, but you can return whatever kind of data you want. Just use the right MIME type in the "Content-type:" line, followed by the required blank line, followed by the raw data of the file you're sending back. In the case of HTML files, that raw data is the HTML text. In the case of images, audio, or video, it's raw binary data. For example, to respond with a GIF file, use:

Content-type: image/gif

&^%#$^&%--- binary contents of GIF file here ---$(*&%(*@#......

Your HTML file can load a script-generated image with

<img src="gifmaker.cgi?param1=value1&param2=value2">

One of my favorite examples of this is the Interactive Graphics Renderer, which renders 3-D icons according to the colors, shape, texture, lighting, etc. that you define. You can use the resulting icons on your Web pages, as better list bullets and horizontal rules. Note: This site has temporarily lost its home; here's a mirror of it in Finland.

MIME Types

MIME types are standard strings that identify a file type, used throughout the Internet. They start with the general type of file (like text, image, or audio), followed by a slash, and end with the specific type of file (like html, gif, or jpeg). HTML files are identified with text/html, and GIFs and JPEGs are identified with image/gif and image/jpeg.

What is the difference between GET and POST?

GET and POST are two different methods defined in HTTP that do very different things, but both happen to be able to send the user's form data back to the server.

Normally, GET is used to get a file or other resource, possibly with parameters specifying more exactly what is needed. In the case of form input, GET fully includes it in the URL, like

http://myhost.com/mypath/myscript.cgi?name1=value1&name2=value2

GET is how your browser usually downloads all files, like HTML files and images. It's just that it can also be used for most form submissions, if there's not too much data (the limit varies from browser to browser).

Normally, POST is used to send a chunk of data back to the server to be processed, whatever that may entail. (The name POST may have come from the idea of posting a note to a discussion group or newsgroup.) When an an HTML form is submitted using POST, your form data is attached to the end of the POST request, in its own object. This is not as quick and easy as using GET, but is more versatile. For example, you can send back entire files using POST. Also, the data size is not limited as it is with GET.

All this is behind the scenes, however. To the CGI programmer, GET and POST work almost identically, and are equally easy to use. The advantage of POST is that you're unlimited in the data you can submit. The advantage of GET is that your entire form submission can be encapsulated in one URL, like a hyperlink or bookmark (though see the unreleased AutoPOST utility to do this with POST).

© 1996 James Marshall (comments encouraged)