Uh-Oh!

If you saw an error message, your Web server had a problem running the CGI program. This may be a problem with the program or the file permissions. First, are you sure the program has the correct file permissions? Did you set the file permissions on your program to 755? If not, do it now. (Windows Web servers will have a different way of doing this.) Try it again; if you see a blank page now, you're good. Second, are you sure the program actually works? (Don't worry, it happens to the best of us.) Change the use CGI line in the program to read:
use CGI ':standard', '-debug';

Now run the program from the command line. You should see the following:
(offline mode: enter name=value pairs on standard input)

This message indicates that you're testing the script. You can now press Ctrl-D to tell the script to continue running without telling it any form items. If Perl reports any errors in the script, you can fix them now. (The -debug option is incredibly useful. Use it whenever you have problems with a CGI program, and ignore it at your peril.) The other common problem is that you're seeing the source code of your program, not the result of running your program. There are two simple problems that can cause this. First, are you sure you're going through your Web server? If you use your browser's "load local file" option (to look at something like /etc/httpd/cgi-bin/backatcha.cgi instead of something like http://localhost/cgi-bin/backatcha.cgi), you aren't even touching the Web server! Your browser is doing what you "wanted" to do: loading the contents of a local file and displaying them. Second, are you sure the Web server knows it's a CGI program? Most Web server software will have a special way of designating a file as a CGI program, whether it's a special cgi-bin directory, the .cgi or .pl extension on a file, or something else. Unless you live up to these expectations, the Web server will think the program is a text file, and serve up your program's source code in plain-text form. Ask your ISP for help. CGI programs are unruly beasts at the best of times; don't worry if it takes a bit of work to make them run properly.

Making the Form Talk Back

At this point, you should have a working copy of backatcha.cgi spitting out blank pages from a Web server. Let's make it actually tell us something. Take the following HTML code and put it in a file:
<FORM ACTION="putyourURLhere" METHOD=GET> <P>What is your favorite color? <INPUT NAME="favcolor"></P> <INPUT TYPE=submit VALUE="Send form"> lt;/FORM>

Be sure to replace putyourURLhere with the actual URL of your copy of backatcha.cgi! If you want, you can use the copy installed here at Perl.com. This is a simple form. It will show a text box where you can enter your favorite color and a "submit" button that sends your information to the server. Load this form in your browser and submit a favorite color. You should see this returned from the server:
favcolor: green

CGI functions

The CGI.pm module loads several special CGI functions for you. What are these functions? The first one, header(), is used to output any necessary HTTP headers before the script can display HTML output. Try taking this line out; you'll get an error from the Web server when you try to run it. This is another common source of bugs! The start_html() function is there for convenience. It returns a simple HTML header for you. You can pass parameters to it by using a hash, like this:
print $cgi->start_html( -title => "My document" );

(The end_html() method is similar, but outputs the footers for your page.) Finally, the most important CGI function is param(). Call it with the name of a form item, and a list of all the values of that form item will be returned. (If you ask for a scalar, you'll only get the first value, no matter how many there are in the list.)
$yourname = param("firstname"); print "<P>Hi, $yourname!</P>\n";

If you call param() without giving it the name of a form item, it will return a list of all the form items that are available. This form of param() is the core of our backatcha script:
for $i (param()) { print "<b>$i</b>: ", param($i), "<br>\n"; }

Remember, a single form item can have more than one value. You might encounter code like this on the Web site of a pizza place that takes orders over the Web:
<P>Pick your toppings!<BR> <INPUT TYPE=checkbox NAME=top VALUE=pepperoni> Pepperoni <BR> <INPUT TYPE=checkbox NAME=top VALUE=mushrooms> Mushrooms <BR> <INPUT TYPE=checkbox NAME=top VALUE=ham> Ham <BR> </P>

Someone who wants all three toppings would submit a form where the form item top has three values: "pepperoni," "mushrooms" and "ham." The server-side code might include this:
print "<P>You asked for the following pizza toppings: "; @top = param("top"); for $i (@top) { print $i, ". "; } print "</P>";

Now, here's something to watch out for. Take another look at the pizza-topping HTML code. Try pasting that little fragment into the backatcha form, just above the <INPUT TYPE=submit...> tag. Enter a favorite color, and check all three toppings. You'll see this:
favcolor: burnt sienna top: pepperonimushroomsham