[an error occurred while processing this directive]

webmonkey/programming/

CGI Scripts for Fun and Profit
by Tim Ziegler

I was recently charged with the task of setting up shopping cart programs for a couple of clients. When they asked me if I could do that, I told them, "Sure!" Notice that I didn't say, "Sure, I know how to do that!" Luckily, they weren't listening too carefully, and I was on my way.

I knew two things about shopping carts. One is that Taylor used to roll his eyes and grunt and refuse to write one when readers would request such a beast. And two is that I'd have to bone up on CGI and Perl scripts (though I knew I wouldn't have to actually write any scripts because so many are out there for the copyin'). You could learn to write your own scripts with Colin's tutorial, but I don't have the time.

So I gave myself a refresher course on the ABCs of CGIs and now I'm going to regurgitate the lessons I learned. If you know all about CGIs and Perl, this article will be beneath you, but if you've never walked the CGI walk and aren't afraid to try, well, you're in the right place. You'll find that CGI scripts can be pretty fun because you can make your pages do all kinds of things HTML can't handle on its own.

Before you start messing with this stuff, you need to have an Internet service provider that will allow you to run CGI scripts. You should really have telnet access to your account, too. For the purposes of this tutorial, your Web server needs to be running some flavor of Unix.

Once you've got what it takes, it's time to learn what's what. Let's roll.

How They Work

As you know, there are a lot of things you can do with your Web page using HTML: display pages, show graphics, create mailto links that send email to people. But at a certain point, you want your site to handle tasks that are beyond the browser's capabilities, like having a shopping cart remember what a shopper has selected, displaying a page counter, making a chat room, or figuring out which browser a visitor is using so you can serve different pages to different browsers.

These things require sending information from the user's browser through the Web server to a program that processes the information before sending it back through the server to your browser. Here's a diagram:

CGI, which stands for common gateway interface, is not a programming language but a protocol — a set of rules for how a Web server talks to a program. So when Johnny Web fills out a form and hits Enter, the HTML controls how the form is delivered to the server and how it is processed by a Perl script. The script and the manner in which it returns the information through the server back to Johnny's browser follow the conventions of CGI.

Here's how the NCSA describes it:

A plain HTML document is static, which means it exists in a constant state; it's 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 want 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, receive the results back again, and display them to the client. This is an example of a gateway, and this is where CGI got its origins.

The programs that deal with Web pages are usually written in Perl because it's well suited for that kind of thing. For simplicity's sake, we're just going to deal with Perl in this tutorial, but many other languages can be used as well.

Also for the purposes of this tutorial, I'm going to keep it simple. Before embarking on a huge, shopping-cart installation, I find it's helpful to get a small Perl script up and running to make sure everything is working right. Then if you run into problems installing a more complicated script, you can check the basics against your small script.

Be My Guest

I wanted to use a page-counter script as my example, but my mouse hand shakes uncontrollably every time I try to download one. It's weird. So let's look at a guest book instead. Here's one from Matt's Script Archive, and here's a demo of it in action.

The beauty of Perl is that it's an interpretive language; so the scripts you use don't have to be compiled. You just copy the scripts onto the right part of your server, and they're good to go.

First I downloaded the guestbook files to my computer and decompressed them. You can also copy them compressed to your server and decompress them there (in which case you have to move them around to the right directories yourself). I was left with the following files:

addguest.html
guestbook.html
guestbook.pl
guestlog.html
ReadMe

The .html files are the Web pages related to the script, the .pl file is the Perl script itself, and the ReadMe is what you need to read to figure out how the hell to make this thing work.

You must put all CGI scripts into a specially designated directory on your Web server, which is usually called cgi-bin. If it isn't called that, ask your ISP what the correct name is. If there isn't one there, don't try to create it yourself because it won't work — again, you'll need to get your ISP to help you out.

I put the HTML files in my public HTML directory, where all my Web pages live. Then I copied the script, guestbook.pl, into my cgi-bin directory. If you can't find that directory, you can try renaming your Perl script with a .cgi extension and putting it in the same place as your HTML pages. Some servers can deal with this setup, some can't. Your mileage may vary. Also, when you copy scripts in your FTP program, do so in ASCII mode instead of binary or auto mode; otherwise you could have line-break problems.

Here's what my file structure looked like:

Now let's set up the files so the unwashed masses can't mess with them.

Asking Permission

You have to tell the server what permissions to give your script. This establishes who can read, write (that is, change), or execute the file. You accomplish this by telnetting to your server and using the chmod (change mode) command. If you don't have telnet access to your account, get the support people at your ISP to change permissions for you.

Here's how you do it: Connect to your server using telnet (open a telnet program, list your server name, and enter your username and password at the prompt) and go into your cgi-bin directory. If you don't know how to move around your server, check out Enough Unix for Your Résumé and our Unix reference guide. You'll only need to learn a handful of commands to deal with this sort of stuff.

Once you see your guestbook.pl file there, you must change the permissions. Permission changing comes in two different forms: letters and numbers. Using chmod to change permissions can be confusing at first, but you don't need to grok the whole concept before you use it. The directions for your new CGI script will tell you what to do. You just need to know that the form for chmod is:

chmod [permission] [filename]

For example, the ReadMe file for my guestbook told me, "This file will need to be placed in the cgi-bin of your server and chmoded to a+rx." So I telnetted into the file where the script lives and typed:

chmod a+rx guestbook.pl

The chmod command is successful if you are returned back to the prompt without seeing an error message.

Final Tweaks

Your script (and the HTML pages that go with it) will usually need to be tweaked. A script like mine required only a little bit of tweaking, but something more complicated may need a whole lot. My ReadMe told me that four variables within the guestbook.pl needed to be changed:

# Set Variables

$guestbookurl - The URL of your guestbook.html file
$guestbookreal - The system location of your guestbook.html file
$guestlog - The system location of your guestlog.html file
$cgiurl - The URL portion of the address to the guestbook.pl file

So I telnetted into cgi-bin and opened the file using a text editor inside the Unix shell. I used vi as my text editor, and Lisa's vi tutorial gave me enough info to change the variables.

One common source of errors in CGI scripting is the incorrect listing of URLs. Some files "talk" to other files by using regular Web URLs (http://www.whatever.com/so_on_and_so_forth/), and others use your server's file system to get around. So I looked at my file structure again:

Then I changed some stuff, knowing that the URL for my Web files was http://www.hulagrrl.com/~timz/:

$guestbookurl = "http://www.hulagrrl.com/~timz/guestbook.html";
$guestbookreal = "/home/timz/public_html/guestbook.html";
$guestlog = "/home/timz/public_html/guestlog.html";
$cgiurl = "http://www.hulagrrl.com/~timz/cgi-bin/guestbook.pl";
$date_command = "/usr/bin/date"

Notice how the $guestbookurl and $cgiurl are regular URLs, whereas $guestbookreal and $guestlog are pathnames within my server files. Some ISPs use funky URLs and server paths with CGIs for security reasons, so be sure to check your ISP documentation to see whether this is the case for you.

The next step is to change any of the HTML within the files to suit your fancy. For example, I set the Back to My Home Page link in guestbook.html and changed the text of the page to be a little more personal.

Finally, I fired up the guestbook.html page, entered a trial message and — lo and behold! — it all worked for me. Happiness.

If it's not working for you, there's one last thing for you to check. Make sure you put this as the first line in any Perl script or it won't work:

#!/usr/bin/perl

This line tells your script where Perl is running on your server. You can check that this is, in fact, where Perl resides by logging into your server and typing the following command at the prompt:

whereis perl

And that should do it.

Once you get this or any other smallish scripts working, there's no stopping you. Make sure all is working well and that you understand these concepts we've just gone over before you proceed.

Let's Go Shopping

That about wraps it up. Here's a quick note on security, though. A CGI script allows a visitor to run a program on your server. This kind of entry can lead to lots of evil if that visitor is a smarty-pants hacker who exploits the opening to gain access to your server. Be careful. Wear protection — oh wait, that's something else. Rather, if you want to know how to thwart such problems, check out this site and follow the guidelines.

In the end, I did get my shopping cart up and running. I used a script called Commerce.cgi from Matt's Script Archive. Honestly, I don't know enough about shopping carts to tell you if this is the one, but it was rated highly on the site and it seemed to work pretty well for me.

Of course, I spent hours figuring out how it worked, getting all the little pieces configured right, and so on. You can expect to spend quite a while messing with these things, but it's mighty satisfying when it finally comes together. And at the end of the day, you'll know you've made the world just a little bit safer for capitalism and free commerce!

RESOURCES:

There are lots of great resources for CGI and Perl on the Web and in bookstores. Books of note are the O'Reilly books and The CGI/Perl Cookbook.

Some key sites are Matt's Script Archive, CPAN (the Comprehensive Perl Archive Network), and the World Wide Web Consortium's CGI pages (which include specs, documentation, and discussion).

Tim Ziegler is a Webmonkey contributing editor. He also builds Web sites in Texas and is the founder of the Austin Music Club. His band, The Fence Cutters, is going to break into the big time any day now.