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:[EMAIL PROTECTED]"> -</HEAD> - +<html> +<head> +<meta name="generator" content="HTML Tidy, see www.w3.org"> +<title>Dynamic Content with CGI</title> +<link rev="made" href="mailto:[EMAIL PROTECTED]"> +</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>
