You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by sl...@locus.apache.org on 2000/11/12 22:39:34 UTC
cvs commit: httpd-docs-1.3/htdocs/manual/howto cgi.html
slive 00/11/12 13:39:34
Modified: htdocs/manual/howto cgi.html
Log:
Just running this through html-tidy to make it easier to edit by hand.
Revision Changes Path
1.2 +414 -290 httpd-docs-1.3/htdocs/manual/howto/cgi.html
Index: cgi.html
===================================================================
RCS file: /home/cvs/httpd-docs-1.3/htdocs/manual/howto/cgi.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- cgi.html 2000/11/12 13:15:52 1.1
+++ cgi.html 2000/11/12 21:39:34 1.2
@@ -1,315 +1,439 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
-<HTML>
-<HEAD>
-<TITLE>Dynamic Content with CGI</TITLE>
-<LINK REV="made" HREF="mailto:rbowen@rcbowen.com">
-</HEAD>
-
+<html>
+<head>
+<meta name="generator" content="HTML Tidy, see www.w3.org">
+<title>Dynamic Content with CGI</title>
+<link rev="made" href="mailto:rbowen@rcbowen.com">
+</head>
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-<BODY
- BGCOLOR="#FFFFFF"
- TEXT="#000000"
- LINK="#0000FF"
- VLINK="#000080"
- ALINK="#FF0000"
->
+<body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#000080"
+alink="#FF0000">
<!--#include virtual="header.html" -->
-<H1 ALIGN="CENTER">Dynamic Content with CGI</H1>
+<h1 align="CENTER">Dynamic Content with CGI</h1>
+
+<a name="__index__"></a> <!-- INDEX BEGIN -->
+
+
+<ul>
+<li><a href="#dynamic content with cgi">Dynamic Content with
+CGI</a></li>
+
+<li><a href="#configuring apache to permit cgi">Configuring Apache to
+permit CGI</a></li>
+<li style="list-style: none">
+<ul>
+<li><a href="#scriptalias">ScriptAlias</a></li>
-<A NAME="__index__"></A>
-<!-- INDEX BEGIN -->
+<li><a href="#cgi outside of scriptalias directories">CGI outside of
+ScriptAlias directories</a></li>
-<UL>
+<li style="list-style: none">
+<ul>
+<li><a href=
+"#explicitly using options to permit cgi execution">Explicitly using
+Options to permit CGI execution</a></li>
- <LI><A HREF="#dynamic content with cgi">Dynamic Content with CGI</A></LI>
- <LI><A HREF="#configuring apache to permit cgi">Configuring Apache to permit CGI</A></LI>
- <UL>
+<li><a href="#.htaccess files">.htaccess files</a></li>
+</ul>
+</li>
+</ul>
+</li>
- <LI><A HREF="#scriptalias">ScriptAlias</A></LI>
- <LI><A HREF="#cgi outside of scriptalias directories">CGI outside of ScriptAlias directories</A></LI>
- <UL>
+<li><a href="#writing a cgi program">Writing a CGI program</a></li>
- <LI><A HREF="#explicitly using options to permit cgi execution">Explicitly using Options to permit CGI execution</A></LI>
- <LI><A HREF="#.htaccess files">.htaccess files</A></LI>
- </UL>
+<li style="list-style: none">
+<ul>
+<li><a href="#your first cgi program">Your first CGI program</a></li>
+</ul>
+</li>
- </UL>
+<li><a href="#but it's still not working!">But it's still not
+working!</a></li>
- <LI><A HREF="#writing a cgi program">Writing a CGI program</A></LI>
- <UL>
+<li style="list-style: none">
+<ul>
+<li><a href="#file permissions">File permissions</a></li>
- <LI><A HREF="#your first cgi program">Your first CGI program</A></LI>
- </UL>
+<li><a href="#path information">Path information</a></li>
- <LI><A HREF="#but it's still not working!">But it's still not working!</A></LI>
- <UL>
+<li><a href="#syntax errors">Syntax errors</a></li>
- <LI><A HREF="#file permissions">File permissions</A></LI>
- <LI><A HREF="#path information">Path information</A></LI>
- <LI><A HREF="#syntax errors">Syntax errors</A></LI>
- <LI><A HREF="#error logs">Error logs</A></LI>
- </UL>
+<li><a href="#error logs">Error logs</a></li>
+</ul>
+</li>
- <LI><A HREF="#what's going on behind the scenes">What's going on behind the scenes?</A></LI>
- <UL>
+<li><a href="#what's going on behind the scenes">What's going on behind
+the scenes?</a></li>
- <LI><A HREF="#environment variables">Environment variables</A></LI>
- <LI><A HREF="#stdin and stdout">STDIN and STDOUT</A></LI>
- </UL>
+<li style="list-style: none">
+<ul>
+<li><a href="#environment variables">Environment variables</a></li>
- <LI><A HREF="#cgi modules/libraries">CGI modules/libraries</A></LI>
- <LI><A HREF="#for more information">For more information</A></LI>
-</UL>
+<li><a href="#stdin and stdout">STDIN and STDOUT</a></li>
+</ul>
+</li>
+
+<li><a href="#cgi modules/libraries">CGI modules/libraries</a></li>
+
+<li><a href="#for more information">For more information</a></li>
+</ul>
+
<!-- INDEX END -->
+<hr>
+<h1><a name="dynamic content with cgi">Dynamic Content with
+CGI</a></h1>
+
+<p>The CGI (Common Gateway Interface) is the simplest, and most common,
+way to put dynamic content on your web site. This document will be an
+introduction to setting up CGI on your Apache web server, and getting
+started writing CGI programs.</p>
+
+<p>For all the gory details about CGI, see the CGI specification, at <a
+href=
+"http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</a></p>
+
+<hr>
+<h1><a name="configuring apache to permit cgi">Configuring Apache to
+permit CGI</a></h1>
+
+<p>In order to get your CGI programs to work properly, you'll need to
+have Apache configured to permit CGI execution. There are several ways
+to do this.</p>
+
+<h2><a name="scriptalias">ScriptAlias</a></h2>
+
+<p>The <code>ScriptAlias</code> directive tells Apache that a
+particular directory is set aside for CGI programs. Apache will assume
+that every file in this directory is a CGI program, and will attempt to
+execute it, when that particular resource is requested by a client.</p>
+
+<p>The <code>ScriptAlias</code> direcive looks like:</p>
+
+<pre>
+ ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/
+</pre>
+
+<p>The example shown is from your default <code>httpd.conf</code>
+configuration file, if you installed Apache in the default location.
+The <code>ScriptAlias</code> directive is much like the
+<code>Alias</code> directive, which defines a URL prefix that is to
+mapped to a particular directory. <code>Alias</code> and
+<code>ScriptAlias</code> are usually used for directories that are
+outside of the <code>DocumentRoot</code> directory. The difference
+between <code>Alias</code> and <code>ScriptAlias</code> is that
+<code>ScriptAlias</code> has the added meaning that everything under
+that URL prefix will be considered a CGI program. So, the example above
+tells Apache that any request for a resource beginning with
+<code>/cgi-bin/</code> should be served from the directory
+<code>/usr/local/apache/cgi-bin/</code>, and should be treated as a CGI
+program.</p>
+
+<p>For example, if the URL
+<code>http://dev.rcbowen.com/cgi-bin/test.pl</code> is requested,
+Apache will attempt to execute the file
+<code>/usr/local/apache/cgi-bin/test.pl</code> and return the output.
+Of course, the file will have to exist, and be executable, and return
+output in a particular way, or Apache will return an error message.</p>
+
+<h2><a name="cgi outside of scriptalias directories">CGI outside of
+ScriptAlias directories</a></h2>
+
+<p>Occasionally you will want to have CGI programs outside of
+<code>ScriptAlias</code>'ed directories. Usually, this will be for the
+purpose of letting users have web content in their home directories
+with the <code>UserDir</code> directive. If they want to have their own
+CGI programs, but don't have access to the main <code>cgi-bin</code>
+directory, they will need to be able to run CGI programs elsewhere.</p>
+
+<h3><a name=
+"explicitly using options to permit cgi execution">Explicitly using
+Options to permit CGI execution</a></h3>
+
+<p>You could explicitly use the <code>Options</code> directive, inside
+your main server configuration file, to specify that CGI execution was
+permitted in a particular directory:</p>
-<HR>
-<P>
-<H1><A NAME="dynamic content with cgi">Dynamic Content with CGI</A></H1>
-<P>The CGI (Common Gateway Interface) is the simplest, and most common, way to put
-dynamic content on your web site. This document will be an introduction
-to setting up CGI on your Apache web server, and getting started writing
-CGI programs.</P>
-<P>For all the gory details about CGI, see the CGI specification, at
-<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</A></P>
-<P>
-<HR>
-<H1><A NAME="configuring apache to permit cgi">Configuring Apache to permit CGI</A></H1>
-<P>In order to get your CGI programs to work properly, you'll need to have Apache
-configured to permit CGI execution. There are several ways to do this.</P>
-<P>
-<H2><A NAME="scriptalias">ScriptAlias</A></H2>
-<P>The <CODE>ScriptAlias</CODE> directive tells Apache that a particular directory is
-set aside for CGI programs. Apache will assume that every file in this
-directory is a CGI program, and will attempt to execute it, when that particular
-resource is requested by a client.</P>
-<P>The <CODE>ScriptAlias</CODE> direcive looks like:</P>
-<PRE>
- ScriptAlias /cgi-bin/ /usr/local/apache/cgi-bin/</PRE>
-<P>The example shown is from your default <CODE>httpd.conf</CODE> configuration file, if you
-installed Apache in the default location.
-The <CODE>ScriptAlias</CODE> directive is much like the <CODE>Alias</CODE> directive, which defines
-a URL prefix that is to mapped to a particular directory. <CODE>Alias</CODE> and <CODE>ScriptAlias</CODE>
-are usually used for directories that are outside of the <CODE>DocumentRoot</CODE> directory.
-The difference between <CODE>Alias</CODE> and <CODE>ScriptAlias</CODE> is
-that <CODE>ScriptAlias</CODE> has the added meaning that everything under that URL prefix
-will be considered a CGI program.
-So, the example above tells Apache that any request
-for a resource beginning with <CODE>/cgi-bin/</CODE> should be served from the directory
-<CODE>/usr/local/apache/cgi-bin/</CODE>, and should be treated as a CGI program.</P>
-<P>For example, if the URL <CODE>http://dev.rcbowen.com/cgi-bin/test.pl</CODE> is requested,
-Apache will attempt to execute the file <CODE>/usr/local/apache/cgi-bin/test.pl</CODE> and
-return the output. Of course, the file will have to exist, and be executable,
-and return output in a particular way, or Apache will return an error message.</P>
-<P>
-<H2><A NAME="cgi outside of scriptalias directories">CGI outside of ScriptAlias directories</A></H2>
-<P>Occasionally you will want to have CGI programs outside of <CODE>ScriptAlias</CODE>'ed
-directories. Usually, this will be for the purpose of letting users have web
-content in their home directories with the <CODE>UserDir</CODE> directive. If they
-want to have their own CGI programs, but don't have access to the main
-<CODE>cgi-bin</CODE> directory, they will need to be able to run CGI programs
-elsewhere.</P>
-<P>
-<H3><A NAME="explicitly using options to permit cgi execution">Explicitly using Options to permit CGI execution</A></H3>
-<P>You could explicitly use the <CODE>Options</CODE> directive, inside your main server
-configuration file, to specify that CGI execution was permitted in a particular
-directory:</P>
-<PRE>
+<pre>
<Directory /usr/local/apache/htdocs/somedir>
Options +ExecCGI
- </Directory></PRE>
-<P>The above directive tells Apache to permit the execution of CGI files.
-You will also need to tell the server what files are CGI files.
-This is done with the <CODE>AddHandler</CODE> directive:</P>
-<PRE>
- AddHandler cgi-script cgi pl</PRE>
-<P>
-<H3><A NAME=".htaccess files">.htaccess files</A></H3>
-<P>A <CODE>.htaccess</CODE> file is a way to set configuration directives on a per-directory
-basis. When Apache serves a resource, it looks in the directory from which it
-is serving a file for a file called <CODE>.htaccess</CODE>, and, if it finds it, it will
-apply directives found therein. <CODE>.htaccess</CODE> files can be permitted with the
-<CODE>AllowOverride</CODE> directive, which specifies what types of directives
-can appear in these files, or if they are not allowed at all. To permit
-the directive we will need for this purpose, the following configuration
-will be needed in your main server configuration:</P>
-<PRE>
- AllowOverride Options</PRE>
-<P>In the <CODE>.htaccess</CODE> file, you'll need the following directive:</P>
-<PRE>
- Options +ExecCGI</PRE>
-<P>which tells Apache that execution of CGI programs is permitted in this
-directory.</P>
-<P>
-<HR>
-<H1><A NAME="writing a cgi program">Writing a CGI program</A></H1>
-<P>There are two main differences between ``regular'' programming, and CGI programming.</P>
-<P>First, all output from your CGI program must be preceeded by a MIME-type header.
-This is HTTP header that tells the client what sort of content it is receiving.
-Most of the time, this will look like:</P>
-<PRE>
- Content-type: text/html</PRE>
-<P>Secondly, your output needs to be in HTML, or some other format that a browser
-will be able to display. Most of the time, this will be HTML, but occasionally
-you might write a CGI program that outputs a gif image, or other non-HTML content.</P>
-<P>Apart from those two things, writing a CGI program will look a lot like any other
-program that you might write.</P>
-<P>
-<H2><A NAME="your first cgi program">Your first CGI program</A></H2>
-<P>The following is an example CGI program that prints one line to your browser.
-Type in the following, save it to a file called <CODE>first.pl</CODE>, and put it in your
-<CODE>cgi-bin</CODE> directory.</P>
-<PRE>
+ </Directory>
+</pre>
+
+<p>The above directive tells Apache to permit the execution of CGI
+files. You will also need to tell the server what files are CGI files.
+This is done with the <code>AddHandler</code> directive:</p>
+
+<pre>
+ AddHandler cgi-script cgi pl
+</pre>
+
+<h3><a name=".htaccess files">.htaccess files</a></h3>
+
+<p>A <code>.htaccess</code> file is a way to set configuration
+directives on a per-directory basis. When Apache serves a resource, it
+looks in the directory from which it is serving a file for a file
+called <code>.htaccess</code>, and, if it finds it, it will apply
+directives found therein. <code>.htaccess</code> files can be permitted
+with the <code>AllowOverride</code> directive, which specifies what
+types of directives can appear in these files, or if they are not
+allowed at all. To permit the directive we will need for this purpose,
+the following configuration will be needed in your main server
+configuration:</p>
+
+<pre>
+ AllowOverride Options
+</pre>
+
+<p>In the <code>.htaccess</code> file, you'll need the following
+directive:</p>
+
+<pre>
+ Options +ExecCGI
+</pre>
+
+<p>which tells Apache that execution of CGI programs is permitted in
+this directory.</p>
+
+<hr>
+<h1><a name="writing a cgi program">Writing a CGI program</a></h1>
+
+<p>There are two main differences between ``regular'' programming, and
+CGI programming.</p>
+
+<p>First, all output from your CGI program must be preceeded by a
+MIME-type header. This is HTTP header that tells the client what sort
+of content it is receiving. Most of the time, this will look like:</p>
+
+<pre>
+ Content-type: text/html
+</pre>
+
+<p>Secondly, your output needs to be in HTML, or some other format that
+a browser will be able to display. Most of the time, this will be HTML,
+but occasionally you might write a CGI program that outputs a gif
+image, or other non-HTML content.</p>
+
+<p>Apart from those two things, writing a CGI program will look a lot
+like any other program that you might write.</p>
+
+<h2><a name="your first cgi program">Your first CGI program</a></h2>
+
+<p>The following is an example CGI program that prints one line to your
+browser. Type in the following, save it to a file called
+<code>first.pl</code>, and put it in your <code>cgi-bin</code>
+directory.</p>
+
+<pre>
#!/usr/bin/perl
- print "Content-type: text/html\r\n\r\n";
- print "Hello, World.";</PRE>
-<P>Even if you are not familiar with Perl, you should be able to see what is happening
-here. The first line tells Apache (or whatever shell you happen to be running
-under) that this program can be executed by feeding the file to the interpreter
-found at the location <CODE>/usr/bin/perl</CODE>. The second line prints the content-type
-declaration we talked about, followed by two carriage-return newline pairs. This
-puts a blank line after the header, to indicate the end of the HTTP headers, and
-the beginning of the body. The third line prints the string ``Hello, World.'' And
-that's the end of it.</P>
-<P>If you open your favorite browser and tell it to get the address</P>
-<PRE>
- <A HREF="http://your.server.com/cgi-bin/first.pl">http://your.server.com/cgi-bin/first.pl</A></PRE>
-<P>or wherever you put your file, you will see the one line <CODE>Hello, World.</CODE> appear
-in your browser window. It's not very exciting, but once you get that working,
-you'll have a good chance of getting just about anything working.</P>
-<P>
-<HR>
-<H1><A NAME="but it's still not working!">But it's still not working!</A></H1>
-<P>If your program still is not working, here are some of the things that you need
-to look for in order to resolve your problem.</P>
-<P>
-<H2><A NAME="file permissions">File permissions</A></H2>
-<P>Remember that the server does not run as you. That is, when the server starts up,
-it is running with the permissions of an unpriveleged user - usually ``nobody'', or
-``www'' - and so it will need extra permissions to execute files that are owned
-by you. Usually, the way to give a file sufficient permissions to be executed
-by ``nobody'' is to give everyone execute permission on the file:</P>
-<PRE>
- chmod a+x first.pl</PRE>
-<P>Also, if your program reads from, or writes to, any other files, those files
-will need to have the correct permissions to permit this.</P>
-<P>
-<H2><A NAME="path information">Path information</A></H2>
-<P>When you run a program from your command line, you have certain information that
-is passed to the shell without you thinking about it. For example, you have a path,
-which tells the shell where it can look for files that you reference.</P>
-<P>When a program runs through the web server as a CGI program, it does not have that
-path. Any programs that you invoke in your CGI program (like 'sendmail', for example)
-will need to be specified by a full path, so that the shell can find them
-when it attempts to execute your CGI program.</P>
-<P>A common manifestation of this is the path to the script interpreter
-(often <CODE>perl</CODE>) indicated in the first line of your CGI program, which will
-look something like:</P>
-<PRE>
- #!/usr/bin/perl</PRE>
-<P>Make sure that this is in fact the path to the interpreter.</P>
-<P>
-<H2><A NAME="syntax errors">Syntax errors</A></H2>
-<P>Most of the time when a CGI program fails, it's because of a problem with the
-program itself. This is particularly true once you get the hang of this CGI stuff,
-and no longer make the above two mistakes. Always attempt to run your program
-from the command line before you test if via a browser. This will elimate most
-of your problems.</P>
-<P>
-<H2><A NAME="error logs">Error logs</A></H2>
-<P>The error logs are your friend. Anything that goes wrong generatesa message
-in the error log. You should always look there first. If the place where
-you are hosting your web site does not permit you access to the error log,
-you should probably host your site somewhere else. Learn to read the error
-logs, and you'll find that almost all of your problems are quickly
-identified, and quickly solved.</P>
-<P>
-<HR>
-<H1><A NAME="what's going on behind the scenes">What's going on behind the scenes?</A></H1>
-<P>As you become more advanced in CGI programming, it will become useful to understand
-more about what's happening behind the scenes. Specifically, how the browser and
-server communicate with one another. Because although it's all very well
-to write a program that prints ``Hello, World.'', it's not particularly useful.</P>
-<P>
-<H2><A NAME="environment variables">Environment variables</A></H2>
-<P>Environment variables are values that float around you as you use your
-computer. They are useful things like your path (where the computer searches
-for a the actual file implementing a command when you type it), your username,
-your terminal type, and so on. For a full list of your normal, every day
-environment variables, type <CODE>env</CODE> at a command prompt.</P>
-<P>During the CGI transaction, the server and the browser also set environment
-variables, so that they can communicate with one another. These are things
-like the browser type (Netscape, IE, Lynx), the server type (Apache, IIS,
-WebSite), the name of the CGI program that is being run, and so on.</P>
-<P>These variables are available to the CGI programmer, and are half of the
-story of the client-server communication. The complete list of required
-variables is at <A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/env.html">http://hoohoo.ncsa.uiuc.edu/cgi/env.html</A></P>
-<P>This simple Perl CGI program will display all of the environment variables that
-are being passed around. Note that some variables are required, while others
-are optional, so you may see some variables listed that were not in the
-official list.</P>
-<PRE>
+ print "Content-type: text/html\r\n\r\n";
+ print "Hello, World.";
+</pre>
+
+<p>Even if you are not familiar with Perl, you should be able to see
+what is happening here. The first line tells Apache (or whatever shell
+you happen to be running under) that this program can be executed by
+feeding the file to the interpreter found at the location
+<code>/usr/bin/perl</code>. The second line prints the content-type
+declaration we talked about, followed by two carriage-return newline
+pairs. This puts a blank line after the header, to indicate the end of
+the HTTP headers, and the beginning of the body. The third line prints
+the string ``Hello, World.'' And that's the end of it.</p>
+
+<p>If you open your favorite browser and tell it to get the address</p>
+
+<pre>
+ <a href=
+"http://your.server.com/cgi-bin/first.pl">http://your.server.com/cgi-bin/first.pl</a>
+</pre>
+
+<p>or wherever you put your file, you will see the one line
+<code>Hello, World.</code> appear in your browser window. It's not very
+exciting, but once you get that working, you'll have a good chance of
+getting just about anything working.</p>
+
+<hr>
+<h1><a name="but it's still not working!">But it's still not
+working!</a></h1>
+
+<p>If your program still is not working, here are some of the things
+that you need to look for in order to resolve your problem.</p>
+
+<h2><a name="file permissions">File permissions</a></h2>
+
+<p>Remember that the server does not run as you. That is, when the
+server starts up, it is running with the permissions of an unpriveleged
+user - usually ``nobody'', or ``www'' - and so it will need extra
+permissions to execute files that are owned by you. Usually, the way to
+give a file sufficient permissions to be executed by ``nobody'' is to
+give everyone execute permission on the file:</p>
+
+<pre>
+ chmod a+x first.pl
+</pre>
+
+<p>Also, if your program reads from, or writes to, any other files,
+those files will need to have the correct permissions to permit
+this.</p>
+
+<h2><a name="path information">Path information</a></h2>
+
+<p>When you run a program from your command line, you have certain
+information that is passed to the shell without you thinking about it.
+For example, you have a path, which tells the shell where it can look
+for files that you reference.</p>
+
+<p>When a program runs through the web server as a CGI program, it does
+not have that path. Any programs that you invoke in your CGI program
+(like 'sendmail', for example) will need to be specified by a full
+path, so that the shell can find them when it attempts to execute your
+CGI program.</p>
+
+<p>A common manifestation of this is the path to the script interpreter
+(often <code>perl</code>) indicated in the first line of your CGI
+program, which will look something like:</p>
+
+<pre>
#!/usr/bin/perl
- print "Content-type: text/html\n\n";
- foreach $key (keys %ENV) {
- print "$key --> $ENV{$key}<br>";
- }</PRE>
-<P>
-<H2><A NAME="stdin and stdout">STDIN and STDOUT</A></H2>
-<P>Other communication between the server and the client happens over standard
-input (<CODE>STDIN</CODE>) and standard output (<CODE>STDOUT</CODE>). In normal everyday context,
-<CODE>STDIN</CODE> means the keyboard, or a file that a program is given to act on,
-and <CODE>STDOUT</CODE> usually means the console or screen.</P>
-<P>When you <CODE>POST</CODE> a web form to a CGI program, the data in that form is
-bundled up into a special format and gets delivered to your CGI program
-over <CODE>STDIN</CODE>. The program then can process that data as though it wsa coming
-in from the keyboard, or from a file</P>
-<P>The ``special format'' is very simple. A field name and its value are joined
-together with an equals (=) sign, and pairs of values are joined together
-with an ampersand (&). Inconvenient characters like spaces, ampersands, and
-equals signs, are converted into their hex equivalent so that they don't gum
-up the works. The whole data string might look something like:</P>
-<PRE>
- name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey</PRE>
-<P>You'll sometimes also see this type of string appended to the a URL. When
-that is done, the server puts that string into the environment variable
-called <CODE>QUERY_STRING</CODE>. That's called a <CODE>GET</CODE> request. Your HTML form
-specifies whether a <CODE>GET</CODE> or a <CODE>POST</CODE> is used to deliver the data, by
-setting the <CODE>METHOD</CODE> attribute in the <CODE>FORM</CODE> tag.</P>
-<P>Your program is then responsible for splitting that string up into useful
-information. Fortunately, there are libraries and modules available to
-help you process this data, as well as handle other of the aspects of
-your CGI program.</P>
-<P>
-<HR>
-<H1><A NAME="cgi modules/libraries">CGI modules/libraries</A></H1>
-<P>When you write CGI programs, you should consider using a code library,
-or module, to do most of the grunt work for you. This leads to fewer
-errors, and faster development.</P>
-<P>If you're writing CGI programs in Perl, modules are available on CPAN
-(http://www.cpan.org/). The most popular module for this purpose is
-CGI.pm. You might also consider CGI::Lite, which implements a
-minimal set of functionality, which is all you need in most programs.</P>
-<P>If you're writing CGI programs in C, there are a variety of options.
-One of these is the CGIC library, from <A HREF="http://www.boutell.com/cgic/">http://www.boutell.com/cgic/</A></P>
-<P>
-<HR>
-<H1><A NAME="for more information">For more information</A></H1>
-<P>There are a large number of CGI resources on the web. You can discuss CGI
-problems with other users on the Usenet group
-comp.infosystems.www.authoring.cgi. And the -servers mailing list from the
-HTML Writers Guild is a great source of answers to your questions. You can
-find out more at <A HREF="http://www.hwg.org/lists/hwg-servers/">http://www.hwg.org/lists/hwg-servers/</A></P>
-<P>And, of course, as I mentioned above, you should probably read the CGI
-specification, which you can find at
-<A HREF="http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</A></P>
-<P>When you post a question about a CGI problem that you're having, whether
-to a mailing list, or to a newsgroup, make sure you provide enough information
-about what happened, what you expected to happen, and how what actually happened
-was different, what server you're running, what language your CGI program
-was in, and, if possible, the offending code. This will make finding your
-problem much simpler.</P>
+</pre>
+
+<p>Make sure that this is in fact the path to the interpreter.</p>
-</BODY>
+<h2><a name="syntax errors">Syntax errors</a></h2>
+
+<p>Most of the time when a CGI program fails, it's because of a problem
+with the program itself. This is particularly true once you get the
+hang of this CGI stuff, and no longer make the above two mistakes.
+Always attempt to run your program from the command line before you
+test if via a browser. This will elimate most of your problems.</p>
+
+<h2><a name="error logs">Error logs</a></h2>
+
+<p>The error logs are your friend. Anything that goes wrong generatesa
+message in the error log. You should always look there first. If the
+place where you are hosting your web site does not permit you access to
+the error log, you should probably host your site somewhere else. Learn
+to read the error logs, and you'll find that almost all of your
+problems are quickly identified, and quickly solved.</p>
+
+<hr>
+<h1><a name="what's going on behind the scenes">What's going on behind
+the scenes?</a></h1>
+
+<p>As you become more advanced in CGI programming, it will become
+useful to understand more about what's happening behind the scenes.
+Specifically, how the browser and server communicate with one another.
+Because although it's all very well to write a program that prints
+``Hello, World.'', it's not particularly useful.</p>
+
+<h2><a name="environment variables">Environment variables</a></h2>
+
+<p>Environment variables are values that float around you as you use
+your computer. They are useful things like your path (where the
+computer searches for a the actual file implementing a command when you
+type it), your username, your terminal type, and so on. For a full list
+of your normal, every day environment variables, type <code>env</code>
+at a command prompt.</p>
+
+<p>During the CGI transaction, the server and the browser also set
+environment variables, so that they can communicate with one another.
+These are things like the browser type (Netscape, IE, Lynx), the server
+type (Apache, IIS, WebSite), the name of the CGI program that is being
+run, and so on.</p>
+
+<p>These variables are available to the CGI programmer, and are half of
+the story of the client-server communication. The complete list of
+required variables is at <a href=
+"http://hoohoo.ncsa.uiuc.edu/cgi/env.html">http://hoohoo.ncsa.uiuc.edu/cgi/env.html</a></p>
+
+<p>This simple Perl CGI program will display all of the environment
+variables that are being passed around. Note that some variables are
+required, while others are optional, so you may see some variables
+listed that were not in the official list.</p>
+
+<pre>
+ #!/usr/bin/perl
+ print "Content-type: text/html\n\n";
+ foreach $key (keys %ENV) {
+ print "$key --> $ENV{$key}<br>";
+ }
+</pre>
+
+<h2><a name="stdin and stdout">STDIN and STDOUT</a></h2>
+
+<p>Other communication between the server and the client happens over
+standard input (<code>STDIN</code>) and standard output
+(<code>STDOUT</code>). In normal everyday context, <code>STDIN</code>
+means the keyboard, or a file that a program is given to act on, and
+<code>STDOUT</code> usually means the console or screen.</p>
+
+<p>When you <code>POST</code> a web form to a CGI program, the data in
+that form is bundled up into a special format and gets delivered to
+your CGI program over <code>STDIN</code>. The program then can process
+that data as though it wsa coming in from the keyboard, or from a
+file</p>
+
+<p>The ``special format'' is very simple. A field name and its value
+are joined together with an equals (=) sign, and pairs of values are
+joined together with an ampersand (&). Inconvenient characters like
+spaces, ampersands, and equals signs, are converted into their hex
+equivalent so that they don't gum up the works. The whole data string
+might look something like:</p>
+
+<pre>
+ name=Rich%20Bowen&city=Lexington&state=KY&sidekick=Squirrel%20Monkey
+</pre>
+
+<p>You'll sometimes also see this type of string appended to the a URL.
+When that is done, the server puts that string into the environment
+variable called <code>QUERY_STRING</code>. That's called a
+<code>GET</code> request. Your HTML form specifies whether a
+<code>GET</code> or a <code>POST</code> is used to deliver the data, by
+setting the <code>METHOD</code> attribute in the <code>FORM</code>
+tag.</p>
+
+<p>Your program is then responsible for splitting that string up into
+useful information. Fortunately, there are libraries and modules
+available to help you process this data, as well as handle other of the
+aspects of your CGI program.</p>
+
+<hr>
+<h1><a name="cgi modules/libraries">CGI modules/libraries</a></h1>
+
+<p>When you write CGI programs, you should consider using a code
+library, or module, to do most of the grunt work for you. This leads to
+fewer errors, and faster development.</p>
+
+<p>If you're writing CGI programs in Perl, modules are available on
+CPAN (http://www.cpan.org/). The most popular module for this purpose
+is CGI.pm. You might also consider CGI::Lite, which implements a
+minimal set of functionality, which is all you need in most
+programs.</p>
+
+<p>If you're writing CGI programs in C, there are a variety of options.
+One of these is the CGIC library, from <a href=
+"http://www.boutell.com/cgic/">http://www.boutell.com/cgic/</a></p>
+
+<hr>
+<h1><a name="for more information">For more information</a></h1>
+
+<p>There are a large number of CGI resources on the web. You can
+discuss CGI problems with other users on the Usenet group
+comp.infosystems.www.authoring.cgi. And the -servers mailing list from
+the HTML Writers Guild is a great source of answers to your questions.
+You can find out more at <a href=
+"http://www.hwg.org/lists/hwg-servers/">http://www.hwg.org/lists/hwg-servers/</a></p>
+
+<p>And, of course, as I mentioned above, you should probably read the
+CGI specification, which you can find at <a href=
+"http://hoohoo.ncsa.uiuc.edu/cgi/interface.html">http://hoohoo.ncsa.uiuc.edu/cgi/interface.html</a></p>
+
+<p>When you post a question about a CGI problem that you're having,
+whether to a mailing list, or to a newsgroup, make sure you provide
+enough information about what happened, what you expected to happen,
+and how what actually happened was different, what server you're
+running, what language your CGI program was in, and, if possible, the
+offending code. This will make finding your problem much simpler.</p>
+</body>
+</html>
-</HTML>