Newtonian Methodology and the Nitty Gritty of Debugging

Upon returning from the void, the first thing I do is to set aside the program and start by coding something really, really small.

You see, debugging is a Newtonian exersise. And in a Newtonian universe the best thing you can do is break everything up into the smallest pieces you can because the whole is going to be a summation of the parts and when you find the faulty part, you find the problem. (1)

Starting with Hello World
So, you should start by creating the most minimal CGI program you can so that you can determine what special traits your local executing environment has that might cause a more complex program to fall apart.

Try this little script which you might call hello_world.cgi....

 
#!/usr/local/bin/perl 
print "Content-type: text/html\n\n"; 
print "Hello World"; 

Okay, now set the permission for this little script so that it is readable and executable by the web server. Typically, you will use the following command on a UNIX server...

 chmod 755 hello_world.cgi (2)

 
http://www.yourdomain.com/cgi-bin/hello_world.cgi

Does it work? If not...

1. The first line (#!/usr/local/bin/perl) might be wrong or you may have accidentally put a blank line before it so that it is not "really" the first line.

   Why would this cause an error?

   Well, because the first line of any cgi script will define the local location of the "Perl Interpreter" which is a program that the server uses to execute your CGI script written in Perl. In this example, you have told the server that the Perl Interpreter (which is a program called "perl") is located in the "/usr/local/bin" directory.

   The script needs to know the location of the Perl Interpreter if it is to use it to execute the program and it is possible that on your server, the Perl Interpreter is not located in the /usr/local/bin directory.

   There are many ways to find out where the Perl Interpreter can be found on your server (several are discussed in Instant Web Scripts with CGI/Perl in chapters freely available from http://www.extropia.com/books/instant_web_scripts/index.html) but the best way is to just ask your sysadmin. That is one of the few easy questions you can ask her. (3)

2. You mis-typed the HTTP header. In order for your browser and server to communicate, you must correctly follow the HTTP protocol. This protocol specifies that an HTML-based response, be preceded with "Content-type: text/html" followed by two newline characters.

3. You did not set the permissions correctly and the web browser has not been given the right permissions to execute the script. Check again.

4. You are not allowed to execute CGI scripts from the directory that you have created the hello_world.cgi in and you either got a 500 error or you received the text of the script in your web browser. The system administrator has restricted you because CGI scripts can be dangerous and she wants to protect her system from your incompetence. Most likely, the system admin has either created a special directory like CGI-BIN for you to put CGI scripts or has allowed you to create special "Access files" which tell the server that in this special case, it is okay to run a CGI script. Either way, you should check with your system admin and ask her how she has determined to deal with CGI scripts and in which directories it is okay for you to run them.

At this level, you can be pretty sure that if the "hello world" script did not run, it was because of one of the three reasons above. After all, there is not much that can be wrong with three lines of code! That is the reason that we are starting so small. We can get our teeth around this!

So I will assume that you've gotten this far and we can go on.

Sherlock Holmes and the Case of the Broken CGI Script
Figuring out Where you are