ch6.htm

CGI programming is the hottest stuff to look out for in this book

That's a bit much, but it's up to you to determine if what you're
creating needs that much effort.
<P>
Whether you go for automated testing or not, you'll need to create
test cases to check and make sure that your program behaves as
expected under a fixed set of circumstances. You can then give
this plan to other people and let them do some of the work for
you.
<H2><A NAME="DebuggingtheApplication"><FONT SIZE=5 COLOR=#FF0000>Debugging
the Application</FONT></A></H2>
<P>
Bugs happen, but you can squash them. If your testing plan has
been thorough, you might uncover a whole slew of problems. Now
the effort needs to be focused on figuring out why they're occurring,
and trying to resolve them.
<P>
First, let's look at some of the most common errors. These are
normally accompanied by Server Error codes, and normal doesn't
tell you much of anything that's of use. However, as you become
more comfortable in debugging applications, you'll learn that
several of the error messages point to some frequently made mistakes.
<H3><A NAME="CommonErrors">Common Errors</A></H3>
<P>
The most common types of errors are ones that the server can help
you resolve, though not willingly. Simple typos, file permissions,
and other easy-to-make mistakes can cost you hours of debugging
time if you're not familiar with what they could be pointing to.
This section introduces you to the three most common errors the
server sends back during the execution of CGI scripts, and explains
some of their most frequent causes.
<H4>Error 404 - Not Found</H4>
<P>
The most obvious meaning of this message is that your script can't
be found. Check the URL that points to the script and make sure
that the file is indeed there. A common cause of it being in <I>what
you believe</I> is the right place is where the <TT><FONT FACE="Courier">DocumentRoot</FONT></TT>
of the server is set to. This is the location that serves as the
base directory for all other directories to be resolved from.
So, if your <TT><FONT FACE="Courier">DocumentRoot</FONT></TT>
is &quot;<TT><FONT FACE="Courier">/usr/stuff/httpds/</FONT></TT>&quot;,
the URL of &quot;<TT><FONT FACE="Courier">http://myhost.com/cgi-bin/script.pl</FONT></TT>&quot;
really points to &quot;<TT><FONT FACE="Courier">/usr/stuff/httpds/cgi-bin/script.pl</FONT></TT>&quot;.
Is that where the file is?
<P>
Another very frequent cause of this error is when the server doesn't
get any output, or gets corrupt output due to an error taking
place. If you'd like to cause this error, you can do it pretty
easily-leave off a trailing semi-colon (;) in a Perl script line.
The server just loves that. Normally, if you've checked your program
out on the command line, or compiled it in C, you'll have encountered
this error beforehand and have resolved it. If you made any changes
to your script recently and this suddenly starts happening, you'll
have a pretty good idea what the root of the problem is.
<H4>403: Forbidden</H4>
<P>
Remember the method discussed earlier, in the section entitled
&quot;Securing the Script,&quot; of hiding your CGI script so
that other people couldn't get at it? Well, it looks like your
server thinks you're one of those people. This error is normally
the result of one of two possible situations whereby the script
can't be executed.
<P>
The first is that the file permissions, as determined by the operating
system, aren't set to allow access. This is more common on UNIX
systems, where file permissions are a fact of daily life, rather
than an afterthought. What you'll want to check is that the script
that you're referencing is able to be executed by the server.
How do you check that? On UNIX systems, the configuration files
determine what user the server tries to run as. It could be root
(the all powerful system account, which is a very bad idea), your
user account (not quite so powerful, but still not great), or
nobody (a generic account that the system can use for process,
it is the best choice). With the configuration file set to the
correct user (most likely the nobody account), check the directory
that holds your CGI script.
<P>
The ideal situation is that the file will be owned by the nobody
account, and executable only by the nobody account. If you use
the <TT><FONT FACE="Courier">ls -lg</FONT></TT> command on UNIX,
you'll see who owns the file, as well as who can execute it. Without
delving too far into the wonders of the UNIX world, here's how
you can ensure that nobody owns the file:
<OL>
<LI>Switch the current directory to the one with the CGI script.
<LI>Type &quot;chown nobody <TT><FONT FACE="Courier">script</FONT></TT>&quot;
(where script is the name of your script file).
<LI>Type &quot;chmod 700 <TT><FONT FACE="Courier">script</FONT></TT>&quot;
(where script is again the name of your CGI program).
</OL>
<P>
You are now all set. What you've done is changed ownership of
the file (chown) to be nobody. Chmod 700 really means &quot;Modify
this file so that only the owner reads, writes and executes permissions.&quot;
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Tip</B></TD></TR>
<TR><TD>
<BLOCKQUOTE>
There are times when the CGI script will have all the right permissions, but files it needs to use (especially output files) can't be accessed. Check to make sure that if you're creating, reading, or modifying files in any way that full access to both the 
files and their directories is available to 'nobody' or whatever user the server is running as.</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<P>
The other possible situation that can cause the 403 Forbidden
error is when the server's own built-in security has taken over,
and doesn't think that you should be able to use that file. Most
servers insist that a particular directory be the only one that
people can execute scripts from, such as cgi-bin or scripts. If
your CGI program is in that directory, then check any security-related
functions that your server has, such as the ability to deny access
to certain directories except for special users, or restricting
access by IP addresses, or even needing an explicit list of what
files can be accessed. How and where you modify those elements
is up to your server, but it shouldn't be too hard to track down.
<H4>500 Server Error</H4>
<P>
The server is having problems doing something, but what? Don't
worry, there aren't too many things that could be going wrong,
even though you'd think the error could try to be more specific
if this were the case. The worst possible case is that something
happened to interrupt communications between the server and the
CGI process, such as someone abruptly terminating the script.
More commonly, however, the CGI script has failed to provide the
server with instructions for how to deal with it's output: it
hasn't provided a <TT><FONT FACE="Courier">Content-type:</FONT></TT>
header.
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Note</B></TD></TR>
<TR><TD>
<BLOCKQUOTE>
Some servers and browsers will assume a <TT><FONT FACE="Courier">Content-type:</FONT></TT> header of <TT><FONT FACE="Courier">text/html</FONT></TT> if there's another header element, such as the Window-target (the header for dealing with frames in 
Netscape). Don't assume, though, it's always better to make the declaration explicit.
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<H3><A NAME="MakeUseofErrorLogs">Make Use of Error Logs</A></H3>
<P>
Error logs, and even general server logs, are great sources for
debugging information. On most ncSA HTTPD servers you'll find
an <TT><FONT FACE="Courier">error_log</FONT></TT> file, normally
located in the logs subdirectory of the directory that contains
your main server process. Any real error message that it generates
will be contained in it for your review, which will also help
if you're not the one doing the testing. The more things that
are written down to check through later, the better.
<P>
When looking through the error logs, be sure to narrow down which
error you got while running the script between specific revisions.
If you changed the section of the code that generated HTML, and
the server started registering more errors after that point, you
know right where to go. Because error logs contain time as well
as the origin, you can approach this in one of two ways:
<OL>
<LI>Try different revisions of the code from different machines.
This will give you a different source IP number to look for.
<LI>Write down the time that you modified the code and what was
changed. This is good general coding practice, and normally done
in internal revision comments. But, because you normally don't
include the exact time of the change in the revision notes, you
might get sidetracked if you start making lots of changes.
</OL>
<H3><A NAME="DebuggingFlags">Debugging Flags</A></H3>
<P>
A debugging flag can come in several forms. One form is a check
that forces the program down a particular path if it's in debugging
mode. This is much like hardcoding data in the application-it
allows you to ignore possible variations in certain sections by
skipping them entirely or by feeding them data that you can be
sure is expected and needed.
<P>
The other kind of debugging flag is nothing more than a print
statement that happens to announce when something's happening,
or to show what the value of some element of data is. If you're
stuck, and can't figure out where the problem is occurring, this
is an easy way to check.
<P>
<CENTER><TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR><TD><B>Note</B></TD></TR>
<TR><TD>
<BLOCKQUOTE>
Certain special cases exist when dealing with functions such as Internet Server API (ISAPI) DLL functions. More information on debugging ISAPI DLLs is given in <A HREF="ch25.htm" >Chapter 25</A>, &quot;ISAPI.&quot; 
</BLOCKQUOTE>

</TD></TR>
</TABLE></CENTER>
<P>
<H3><A NAME="ReTestingYourApplication">Re-Testing Your Application</A>
</H3>
<P>
What do you do once you've fixed all the problems? Go through
it all over again. You can never be sure that fixing one problem
didn't cause two more, especially if they're all tied together.
This is when the advantage of a testing plan comes into full effect.
<P>
The first time through you looked for cases where things didn't
work, and saw what the output was. Does it look different now
that you run through it again? If you're using automated testing
scripts, compare the output of one testing round to another. Are
there inconsistencies that could indicate a deeper problem?
<P>
Problems seem to come in layers. By peeling back what seems to
be the problem, you might be able to fix a symptom, while the
root of the problem remains. You have to dig deep enough until
you're sure that what you've produced is as stable as it can be.
<H2><A NAME="Summary"><FONT SIZE=5 COLOR=#FF0000>Summary</FONT></A>
</H2>
<P>
Testing isn't easy, and it takes a lot of concerted effort and
planning to be sure that what you've developed meets your needs
and those of the people who will be using it. Take your time,
wherever possible. Plan out what the script needs to do, and how
it will meet those needs, before leaving the planning phase and
entering into the coding phase. Once you're in the coding phase,
look through very carefully to identify what areas may be a concern,
and be sure to pay special attention to them without skimping
on other portions. Don't rush through any one phase, or give any
one section of your code less attention because it doesn't seem
like it should have any problems. Even one tiny typo can ruin
your whole day.
<P>
Remember, debugging methods and special tools exist for almost
every language and situation. If you take it slow and make use
of all the things that are available to you during testing, you'll
rarely spend time going back to fix problems, and you can concentrate
on building the next cool program while people enjoy your other
ones.
<P>
<HR WIDTH="100%"></P>

<CENTER><P><A HREF="ch5.htm"><IMG SRC="pc.gif" BORDER=0 HEIGHT=88 WIDTH=140></A><A HREF="#CONTENTS"><IMG SRC="cc.gif" BORDER=0 HEIGHT=88 WIDTH=140></A><A HREF="index.htm"><IMG SRC="hb.gif" BORDER=0 HEIGHT=88 WIDTH=140></A><A HREF="ch7.htm"><IMG 
SRC="nc.gif" BORDER=0 HEIGHT=88 WIDTH=140></A></P></CENTER>

<P>
<HR WIDTH="100%"></P>

</BODY>
</HTML>