How to debug Perl CGI scripts

284354749

How to debug Perl CGI scripts

Introduction

One of the most frustrating tasks you'll encounter when developing a web site is trying to debug CGI scripts. If you've ever had to stare at the silly "500 Internal Server Error" message for the third hour (or day!) you'll know what I'm talking about.

Fortunately, the errors can be resolved once you know what they are. So let's take a look at what can go wrong, and learn how to fix it. 　　 　　The key to understanding why some of the errors occur is to know a little about how CGI programs are executed on the server. The Common Gateway Interface (CGI) is not rocket science, its a protocol, nothing more. If you're going to be doing any web development using CGI, I recommend reading the protocol specification Standard CGI Interface. CGI 101 　　The minimal explanation of how things run is as follows. First, the server receives a request for a document via a URL and a method type (usually GET or POST). A document is identified by its suffix, and this information is configured within the server itself. For instance, it may be required that your scripts end in either .cgi or .pl. 　　If the server can't find the file type based on the suffix, it tries to spit the file back to the browser via STDOUT. If this happens, the browser is responsible for deciding what to do with it. 　　If the server can identify the suffix, but finds that the suffix is not registered as a CGI type, it will send the MIME type to the browser as well as sending the file. This helps the browser decide what to do with the file, such as display it in the browser window, or launch an external application or plug-in. 　　If the server can identify the suffix, and it is configured to execute that type of file, it will first perform security checks such as determining whether a directory is allowed to run CGI scripts or not. These security issues are configurable and that is why so often you'll see "check with your system administrator" as part of an answer to CGI questions. 　　Assuming that the security checks are passed, the server will then try to execute the script. At this point the server will pass a bevy of Environment Variables to the CGI program. After that, control is handed to the script so it can do its job. 　　That's a lot of information, but what does it mean, and how does it apply to your script? Well, understanding the process helps you to understand the types of errors that can occur, when they occur, and how to solve them. A script might not work because of errors related to the server, or there may be syntax errors in the code itself. Either way, the script won't run until you fix the problem. This feature will take a detailed look at server errors, and will present ways to find syntax errors. We won't go into how to fix the syntax errors here, but a good book on Perl will help you. Common Server Errors 　　OK, so what are the server errors? Well, there's 404 File not found, and 403 Forbidden. There's also 501 Method not implemented and Document contains no data. And then there's 500 Internal Server Error, which is the most useless message you'll ever see. Let's look at them one by one. 404 File not found 　　When you see this one, it means that the server can't find the file. The first thing to do is check the obvious: did you type the URL correctly? Did you remember that its case sensitive? OK, you did and you still have the problem. Some servers are configured not to allow subdirectories in a cgi-bin directory, and this can give you the problem. For instance http://www.mydomain.com/cgi-bin/myscript.cgi is OK, but http://www.mydomain.com/cgi-bin/my_subdirectory/myscript.cgi is not. Yup, you'll need to ask your server administrator if this case applies to you. 　　 　　If you've done all this and you still have the problem, do ask your server administrator for more information. The server may have a complex mapping system for matching a URL to an actual path on your system. An example is if scripts are run in a chrooted environment where scripts run on the server are configured to only see part of the file system. If you're absolutely sure that you've typed in the URL correctly, that may be your problem. 403 Forbidden 　　This is a pretty straightforward error message, and it means that the server doesn't find the correct permissions to run the script. There are three things you can do to fix the problem. The first is to make sure you have given the script the correct permissions. If you are using telnet, type chmod 755 scriptname.cgi If you are using an FTP program, there is usually some way to use the program to set the permissions. Check the documentation to see how to do it. 　　 　　The second thing to do is to make sure that you are trying to run the script in the correct directory. Some servers are configured to only run CGI scripts in a specific subdirectory, such as cgi-bin. You'll have to ask your server administrator about this. 　　The third thing to do is to determine if you are allowed to run CGI scripts at all. For security reasons, these privileges are sometimes denied. You'll have to check with your server administrator to see if you're allowed to run CGI scripts. If you're not, you're out of luck. Sorry.

Common Server Errors, continued
This error will crop up when the POST method is used to call the script. If you aren't allowed to run a script in a directory, it will be treated as a normal file. Since only CGI files are allowed to be called with POST, the server will return this error message. As you can see, this is similar to a 403 Forbidden error, and you solve it in the same way.



Sponsored Links

Need Perl Cgi Scripting?Find perl cgi scripting now Sign up today online for free!www.GetACoder.com
Debugging ASP Pages?Team Remote ASP Debugger Make your development life easierwww.ASPdebugger.com
Perl IdeFind Solutions for Your Business. Free Reports, Info. & Registration!www.KnowledgeStorm.com

Document contains no data 　　If you see this message, it means that the server found your script and ran it. The content-header was sent to the browser successfully, but any further information was never sent. It could be that there was a runtime error in the script, such as a file didn't open and the script exited through die(). Normally you won't see these error messages, so here's how to redirect them to your browser. Add these lines somewhere near the beginning of your script: $| = 1; open(STDERR, ">&STDOUT"); Or, use the CGI:Carp module, as discussed below. 　　 　　This will redirect any error messages to your browser that normally show up in STDERR, like error messages from die(). It will not report any syntax errors that crash your program, though. And don't forget to take the debugging code out when you're done! 　　Another reason this message may be reported is because the server timed out. If you have a script that runs for a long time, you should provide some sort of progress report to the browser. You can bet that if your script is running long enough for the server to time out, your user will be long gone before it happens. Well, if they're like me, anyway! If you can let them know what's happening, you'll maintain both the connection and the interest. 　　It is also possible that your script really isn't sending any data. It may run successfully, but if that doesn't include sending anything to STDOUT, then you'll see this message. An example is if your script processes data and saves it to a file, but never reports success to the user. There may be a logic flow problem, or maybe you just forgot. If you look through the code you may find the error. 500 Internal Server Error 　　This message may say "Internal Server Error", but what it means is "I attempted to access your file, and I found that it existed but I can't run it, or maybe I did run it, but it gave me some output I didn't understand, and heck, I don't know what to do with it now. Fix it." Gee, thanks. 　　The next two steps will take care of a majority of the problems. First of all, if you upload your script to your server via FTP, always use ASCII mode. If you used binary mode, chances are that's why you have this message. Some FTP applications can use auto detect, but you'll need to verify that it knows .cgi and .pl files are ASCII files. Check the documentation for your application to see how to do that. 　　Next, be sure that the first line of your script has the correct path to Perl. If you're on a Unix system, in most cases it will look like one of the following #!/usr/local/bin/perl or #!/usr/bin/perl If you're not sure, use telnet and type which perl You'll then have the correct path to put in your script. 　　 　　If you're using the Apache server on Windows, the path will be #! perl 　　 　　The reason you need this line is that your server doesn't actually run the CGI script. Once the server has determined that all is well, it turns your script over to the Perl interpreter. That's why that line must be the first line in your script, and why the path has to be correct. 　　If the script was uploaded correctly and the pathname is correct, that may be all you need to do. If not, you'll need to do some sleuthing. 　　First, use telnet and connect to your server. If you don't have telnet privileges, please consider using another hosting service. No, I'm not kidding. Once you've connected to the server, switch to the CGI directory (usually cgi-bin), and check the syntax on your script with the following command line. perl -c myscript.cgi Any syntax errors will be reported for you to correct. If you want to be nice to yourself, add the -w switch to the first line in your script. #!/usr/bin/perl -w If the warnings confuse you, try use diagnostics; You'll get the expanded version of the warnings, and that may help you fix any syntax errors. Keep on going until there aren't any more warnings to correct, then try to run the script again. 　　 　　While you're still connected, use the following command to run the script: perl myscript.cgi | head -2 The command will run the script and print the first two lines of output. The two lines should be Content-type: text/html or Content-type: text/plain followed by one blank line. If this isn't what prints, you may have discovered the source of the problem. Make sure the header line is print "Content-type: text/plain\n\n"; If your script passes all the syntax checks, but you still have the problem, you'll need to check and make sure that your script can find all the files that it needs to execute properly. One trick is to cut and paste each filename, complete with the full pathname, to the command line and see that the file shows up in the directory listing. For instance, ls -l /home/mydir/data.txt If you use the same filename, including the full path, on the command line as you do in your script, you should be able to locate the file. 　　 　　This is a common source of trouble, especially if you are using a script that you downloaded from the internet. Different developers use different conventions for building the pathname, and its easy to get tripped up. Do yourself a favor, and don't skip this step. 　　The script still won't run? Check the "here-documents", which look something like this: print << "END"; Hello World! END The quoted token ("END" in this example, or whatever is used in your script) must EXACTLY match the token that terminates the text. It may look OK to you, but if you've moved the file from DOS/Windows to UNIX, remember that UNIX uses to delimit lines and DOS/Windows uses . What that means to Perl is that there is an invisible in the end token, but there isn't one in the quoted token. Guess what? They don't match, at least in Perl's opinion. Make sure that the end token is flush on the left margin with a following it - and no trailing space or hidden on the line. 　　 　　The easiest way to do this is to simply hit the Return key right after the end token, whether it needs it or not. That way you'll know its the right line delimiter for your system. 　　Finally, you may need to verify that you are using the correct version of Perl. At the command line type perl -e 'print $]' or perl -v The version you are using will be printed, so you'll know if you have the right one. If you're trying to run a Perl 5 script with Perl 4, that could be the problem.

Another tool in the debugging arsenal is to use CGI::Carp. Its now part of the standard Perl distribution, but if you have an earlier version you can download it from CPAN.

Somewhere near the top of your script type use CGI::Carp qw(fatalsToBrowser); This will redirect all fatal error messages to your browser, so you have a better idea of what is going wrong. 　　 Other problems 　　If your browser displays the script code instead of running the script, it is likely that you either named the file with an incorrect extension, or you've installed it in the wrong place. This is a case where the server is returning what it considers a "normal file". Make sure you are using the correct extension, and that the script is in the correct directory. 　　If your browser prompts you to save the file instead of executing it, check the Content-type: header. If its incorrect your script won't run properly. Summary 　　The errors you may encounter when you're trying to run a Perl CGI script can be frustrating. That's the bad news. The good news is that, in most cases, the problems can easily be solved by following a few simple steps. You know what they say, "its easy when you know how". 　　This article presented some of the common errors that can trip you up when you're debugging your Perl scripts. If you've tried everything and still can't get your script to run, you might try posting your problem to the About Perl/PHP Forum. Other programmers are one of the best resources on the planet, and it never hurts to tap in to that.