<![CDATA[
<! Main section>
<BODY BGCOLOR="#609aba" LINK="#0000FF" ALINK="#00FF00" VLINK="FF0000">
<!-- BEGIN INTERNET LINK EXCHANGE CODE -->
<center><a href="http://ad.linkexchange.com/X967057/gotoad.map"
target="_top">
</a>
<br><font size=1><a href="http://www.linkexchange.com/" target="_top">
Member of the Internet Link Exchange</a></font></center><br>
<!-- END INTERNET LINK EXCHANGE CODE -->
<CENTER><h1>An Absolute Beginners Guide to CGI and Perl</h1>
<P>
<font size=+1>
<TABLE BORDER="0" CELLPADDING="4" CELLSPACING="0"></font>
<TR>
<TD BGCOLOR=GOLD>
<B>
<FONT SIZE="2" COLOR="RED">
<SCRIPT LANGUAGE="JavaScript">
var theDate = ""
theDate = document.lastModified
document.write("Last Updated: ");
document.write(theDate);
document.write();
</SCRIPT>
</FONT>
</B>
</TD>
</TR>
</TABLE></center>
<font size=+1>
<HR WIDTH=50%><P>
I have written this guide to help beginners learn to set up and use cgi scripts, particularly perl.<p>
I am eminently qualified to do this, as I am a beginner myself, having started playing with cgi on 10 Aug 96.<p>
What I found out in the painful, long-drawn-out process of setting up my perl scripts, was that the experienced "gurus" assume (making an ass out of u and me) that because they know something, everybody else will automatically know it too, which makes getting guidance like getting blood out of a stone.<p>
To make it easier for you to tell explanations and instructions from example code etc, I have used the following colour (<color>) conventions:<p>
<center>
<!Black, Olive, Teal, Red, Blue, Maroon, Navy, Gray, Lime, Fuchsia, White, Green, Purple, Silver, Yellow or Aqua.>
<TABLE BORDER="0" CELLPADDING="4" CELLSPACING="0">
<tr>
<td width=100 bgcolor=black><font color=black size=+1><b>Black</b></font></td>
<td width=400><font color=black size=+1><b>Black</b> - All the boring explanations and instructions</td></tr>
<tr><td width=100 bgcolor=white><font color=white size=+1><b>White</b></font></td>
<td width=400><font color=white size=+1><b>White</b> - Examples of perl code</font></td></tr>
<tr><td width=100 bgcolor=yellow><font color=yellow size=+1><b>Yellow</b></font></td>
<td width=400><font color=yellow size=+1><b>Yellow</b> - Examples from html forms</font></td></tr>
<tr><td width=100 bgcolor=lime><font color=lime size=+1><b>Lime</b></font></td><td width=400><font color=lime size=+1><b>Lime</b> - Your keyboard input - what I want you to type.</font></td></tr>
<tr><td width=100 bgcolor=aqua><font color=aqua size=+1><b>aqua</b></font></td><td width=400><font color=aqua size=+1><b>Aqua</b> - Program Menu Items</font></td></tr>
</table></center><p>
<font color=red>Important!!</font> If you want to print this page, you need to change all the yellow and white to another colour (<color>) before printing it. To do this, go to <font color=aqua>File...Save As</font> and save it somewhere, then edit it by doing a global search and replace - case sensitive (so the words White and Yellow in the table above don't change) - suggest <font color=lime>color=white</font> replace with <font color=lime>color=navy</font> , <font color=lime>color=yellow</font> replace with <font color=lime>color=green</font> , then save it and in your browser go to <font color=aqua>File...Open</font> and open it, then print that one.<p><hr>
Before you get too deep into cgi and perl, ask yourself a few questions like these:<p>
<font color=maroon><h2>1.
Do I need to learn cgi and perl?
</h2></font>If all you want to do is get feedback from a web form such as <a href=http://www.iinet.net.au/~jaguar/fogform.html>Add Yourself to The Fogies Photo Gallery</a> or <a href=http://www.iinet.net.au/~onthenet/survey.html>Julie and Jay's Tarot on the Net Survey</a>, you can use a mailform script located on someone else's site.<br> If you examine either of those forms (by following the links and then selecting <font color=aqua><b>View...Document Source</b></font>) you will find a line like this:<br><b><font color=yellow><FORM method=POST ACTION="http://www.iinet.net.au/cgi-bin/cgi/jaguar/mailform.pl"></font><br>OR<br><font color=yellow><form action="http://www.iinet.net.au/cgi-bin/cgi/jaguar/mailtoda3.pl" method="POST"></font></b><br> Note that only one of these forms is located on my site, but both of them use one of my scripts which is located on my site. The Tarot on The Net Survey uses a special script I wrote so that Julie can copy from the email and paste directly into an Excel spreadsheet.<br>These scripts could as easily be used from any site in the world, so maybe you don't need to do the hard stuff.
<font color=maroon><h2>2.
What Do I Want To Do?
</h2></font>If all you want is a simple feedback form, why go through the angst of getting into cgi & perl? - forms are very easy in comparison, and you will still need a form anyway.<p>
If that is all you are after, <A HREF="mailto:Keith Lewis <jaguar@iinet.net.au>?Subject=I'd Like Help With A Feedback Form">Email Me</a> with your Homepage URL and a description of what feedback you are after.<p>
If you want a guestbook, and you are an iinet subscriber, you can also have a very nice guestbook without learning cgi and perl. If you are with another isp, and you can get CGI permission and the answer to a few simple questions, you can also get by without learning cgi and perl.<p>
Take a look at any of these guestbooks to see what is available from me:<p>
<a href=http://www.iinet.net.au/~keen/guestbookadrian.html>Commander Keen's Guestbook</a><br>
<a href=http://www.iinet.net.au/~judy/guestbookjudy.html>Judy's Guestbook</a><br>
<a href=http://www.iinet.net.au/~onthenet/genealogy/guestbookgenealogy.html>Julie and Jay's Genealogy Guestbook</a><br>
<a href=http://www.iinet.net.au/~gaynor/guestbookrod.html>Rod's Guestbook</a><br>
<a href=http://www.iinet.net.au/~evo/guestbooktony.html>Tony's Guestbook</a><br>
<a href=http://www.iinet.net.au/~jaguar/guestbookfoglinks.html>The Fogies Photo Gallery Guestbook</a><br>
<a href=http://www.iinet.net.au/~jaguar/guestbookaxcel.html>My Grandson Axcel's Guestbook</a><br>
<a href=http://www.iinet.net.au/~jaguar/guestbookkeith.html>My Guestbook</a><p>
If that is all you are after, and you are an iinet subscriber, <A HREF="mailto:Keith Lewis <jaguar@iinet.net.au>?Subject=I'd Like A Guestbook">Email Me</a> with your Homepage URL.<p>
If you are not an iinet subscriber, but you would still like a Guestbook like mine, <A HREF="mailto:Keith Lewis <jaguar@iinet.net.au>?Subject=I'd Like A Guestbook - not on iinet">Email Me</a> with your Homepage URL, and the answers to questions 1 to 5 below. Make sure your isp will give you CGI permission first though.
<font color=maroon><h2>3.
So - Do You Still Want To Go Ahead?
</h2></font>Now that we've got that out of the way, let's get serious about how we are going to do this. First off, there are a couple of things you need to know about your server:<p>
<h3>1.
Where do I find the perl interpreter?
</h3>If you are an iinet subscriber, the perl interpreter is located at /usr/bin/perl - it may be located at the same path on most servers, which makes it easy, but you <b>DO</b> need to know where it is.<br>All perl scripts must have a line like the following as the first line in the script:<br><font color=white>#!/usr/bin/perl</font><br> It <b>must</b> have the #! before the path.
<h3>2.
Where is the Mail Program on the Server?
</h3>If you want a feedback form, You need to know where the Mail Program is on your server. On iinet, it used to be located at /usr/lib/sendmail, but now it is located at /usr/bin/sendmail , and my scripts tell the interpreter where to find it with this line:<br>
<font color=white>$mailprog = '/usr/bin/sendmail';</font><br>
<h3>3.
Where is the Date Program on the Server?
</h3>Just about every script needs to have a date, so you need to know where the date program is. On iinet it is located at /bin/date , and my scripts tell the interpreter where to find it with this line:<br>
<font color=white>$date_command = '/bin/date';</font>
<h3>4.
Where are Your Files on the Server?
</h3>If you want a Guestbook or a Free For All Links page, or want to keep a log of respondents to a feedback form, you need to know the path to your files. On iinet they are located at /u/<i>{first letter of user id}/{userid}</i>/public_html/ , and my scripts tell the interpreter where to find them with lines like this:<p>
<font color=white>$database = "//u/j/jaguar/public_html/database.txt";</font> Note that there is no <font size=+1><b>~</b></font> (tilde) in the <b>PATH</b>.<br>
or (in some of my scripts) like this:<br>
<font color=white>$userpublicreal = "//u/j/jaguar/public_html/";<br>
$guestbookfile = "guestbookkeith.html";<br>
$guestlogfile = "guestlogkeith.html";<br>
$database = "database.txt";</font><br>
These will be put together later in a script with lines like these:<br>
<font color=white>$guestbookreal = $userpublicreal$guestbookfile;<br>
$guestlog = $userpublicreal$guestlogfile;</font><br>
Because I write some of my scripts, particularly my Guestbook script, to be used universally within a domain, often the <b>Form</b> which calls the script will have details of the file path, in this form:<br>
<font color=yellow><INPUT TYPE="hidden" name="userpublicreal" value="//u/j/gaynor/public_html/"><br>
<INPUT TYPE="hidden" name="guestbookfile" value="guestbookrod.html"><br>
<INPUT TYPE="hidden" name="guestlogfile" value="guestlogrod.html"></font><br>
These are put together later in the script with lines like these:<br>
<font color=white>if ( $FORM{'userpublicreal'} && $FORM{'guestlogfile'}){<br>
$guestbookreal = "$FORM{'userpublicreal'}$FORM{'guestbookfile'}";<br>
$guestlog = "$FORM{'userpublicreal'}$FORM{'guestlogfile'}";<br>
}<br>
else {<br>
die "Guestbookreal or filename or logfile not specified in form \n";<br>
}</font><br>
The same form also passes the <b>URL</b> of the user's homepage with this line: Note the <font size=+1><b>~</b></font> (tilde) in the <b>URL</b>.<br>
<font color=yellow><INPUT TYPE="hidden" name="userpublicurl" value="http://www.iinet.net.au/~gaynor/"></font><br>
This is then used to find the <b>URL</b> of the guestbook with these lines:<br>
<font color=white>if ( $FORM{'guestbookfile'} && $FORM{'userpublicurl'}){<br>
$guestbookurl = "$FORM{'userpublicurl'}$FORM{'guestbookfile'}";<br>
}<br>
else {<br>
die "Guestbook url or filename not specified in form \n";<br>
}</font><br><br>
If this all looks a bit confusing, please bear with me, I will explain all the weird looking stuff when we get <b><i>down to the nitty gritty</i></b>.
<h3>5.
How do you call a script on your Server?
</h3>You need to know the <b><i>calling convention</i></b> for cgi on your server. The easy way to find this out is to find a form on another users page on your server, and <b>View Source</b>. You should find a line looking something like this:<br>
<font color=yellow><form method=POST action="http://www.iinet.net.au/cgi-bin/cgi/jaguar/guestbookmulti.pl"></font><br>
Notice that this doesn't look like a normal url - it's a cgi call. I'm told that, since an upgrade made earlier this year at iinet, the following line would also work<br>
<font color=yellow><form method=POST action="http://www.iinet.net.au/~jaguar/cgi-bin/guestbookmulti.pl"></font><br>
Note that this one does look like a normal url. Personally, on the basis that "If it ain't broke, don't fix it", I'm sticking with the old cgi calling convention.
<font color=maroon><h2>Getting Down to Business</h2></font>
Now that we know "what we need to know", we can get down to the business of working out the mechanics.<p>
<!font size=+2>Here is my step by step guide to getting started.<p>
<h3>1.
CGI-BIN DIRECTORY
</h3>Use an FTP programme (I use CuteFTP) to create a directory named cgi-bin (must be in lower case) directly below your public_html directory.<br>Note that the two directories are " public underscore html " and " cgi dash bin ".
<h3>2.
CGI PERMISSION
</h3>Ask Support at your ISP (Internet Service Provider) to give you CGI permission. If they won't give you CGI permission they may allow you to place your scripts in their cgi-bin instead (after they've tested them). That makes it much harder and is not the preferred option. (The perl script for this situation might read:-<br><font color=white>get (cgi_permission) || die "rotten ISP won't give me cgi permission: $!\\n"</font> )
<h3>3.
UPLOADING THE SCRIPT
</h3>Use an FTP programme (I use CuteFTP) to upload your script to your cgi-bin directory.<br><font color=red size=+1><b>Important!</b></font> The file must be uploaded as <b>AASCI</b> or it won't work. To do this in CuteFTP, the easiest way so you never have to worry about it again, go to <font color=aqua><b>FTP...Settings...Text File Extensions...Add</b></font> and type <font color=lime><b>pl</b></font> in the dialog box, then click on <b>OK</b>. From then on, as long as your setup in Site Manager for <b>Transfer Type</b> is "<b>Auto Detect</b>", all files with a <b>pl</b> extension will automatically upload as ASCII.
<h3>4.
CREATING A CUSTOM COMMAND TO CHANGE THE FILE ACCESS MASK
</h3>You can use Telnet or an FTP programme (I use CuteFTP) to set the file access mask to <b>executable</b>.<br> To do this in CuteFTP, the easiest way so you never have to worry about it again, go to <font color=aqua><b>Command...Custom Commands...Define...Add</b></font>. Type <b><font color=lime>Change to Executable</font></b> in the "Label" dialog box, then type <b><font color=lime>SITE CHMOD 755 %f</font></b> in the "Command Text" box, make sure there is a tick in "Show server's response", insert the letter of your choice in the "Hot key" box (I recommend <font color=lime><b>E</b></font> for Execute) then click <b>OK</b>. From then on, to set a file to "Executable", all you have to do is hold down <font color=lime><b>Ctrl</b></font> and <font color=lime><b>Shift</b></font> and hit <font color=lime><b>E</b></font> (or whichever letter you chose), then hit <font color=lime><b><Enter></b></font> to clear the server report box. <p>
<h3>5.
CHANGING THE FILE ACCESS MASK
</h3><font color=red size=+1><b>Important!</b></font> Every time your script on the server changes, whether by editing it on the server or by uploading it from your hard drive, you <b>MUST</b> change the file access mask to "Executable". <br>You can use Telnet or an FTP programme (I use CuteFTP) to set the file access mask to <b>executable</b>.<br>If you use CuteFTP and have followed step 4 above, just select the file or files you want to change the access mask for (only your scripts though), and do the [Ctrl][Shift]E. If you use Telnet or another FTP program, and can't set up the Custom Command, change to your cgi-bin directory by typing <br><b><font color=lime>cd public_html/cgi-bin</b> then type <br><b><font color=lime>chmod 755 yourfilename.ext</font></b> or <br><b><font color=lime>chmod a+x yourfilename.ext</font></b> .(insert your actual filename and extension, e.g. guestbook.pl) <p>
<font color=maroon><h2>CHOOSING A SCRIPT</h2></font>
The easiest way to do anything with scripts is to use one that someone else has written and tested. The best source I've found is <a href="http://worldwidemart.com/scripts/">Matt Wright's Script Archive</a>, but there are plenty of others around. A search with <a href=http://webcrawler.com/>Webcrawler</a> for <font color=lime>"perl script download"</font> <b>WITHOUT</b> the quotes should find plenty. Another excellent source is <a href=http://www.excite.com/computers_and_internet/programming/perl/>Excite's Perl Page</a>. A search with <a href=http://www.excite.com/>Excite</a> for <font color=lime>"perl script download"</font> <b>WITH</b> the quotes should also find plenty, including a link to their perl page at the start of the list which says "Try these first: Web sites about Perl". <p>Personally I find <a href="http://worldwidemart.com/scripts/">Matt's Script Archive</a> is the most comprehensive collection of useful scripts, with excellent <b>Read Me</b> files and clear internal documentation. That is the reason that most of my forms have something like the following at the bottom:
<center>
<table><tr><td width=100 valign=middle><img src="images/jaguar.gif"
border=0 alt="Jaguar Scripts" width=100 height=88></td><td width=450 valign=middle>Script modified by Keith Lewis from an original script Created by Matt Wright which can be found at<br><center> <a href="http://worldwidemart.com/scripts/">Matt's Script Archive</a>.</center><a href="http://www.worldwidemart.com/scripts/"></td><td width=90 valign=middle>
<img src="http://worldwidemart.com/scripts/images/logos/MSA_Logo_01.gif"
border=0 alt="Matt's Script Archive" width=90 height=60></a></td></tr></table></center>
<hr> <center>This <b>page</b> has been accessed <IMG SRC="/cgi-bin/nph-count?link=/jaguar/cgitutor.html&width=4" alt="Counter" width=60 height=22> times since 8 November 1997.</center><p>
<p>
<LI><A HREF="intro1.html" TARGET="detail_frame">My Real Front Page</A>
<LI><A HREF="aboutme1.html" TARGET="detail_frame">About Me</A>
<LI><A HREF="whatsnew.html" TARGET="detail_frame">What's New on My Home Page</A>
<LI><A HREF="addguestkeith.html" TARGET="_blank">Sign My Guest Book</A>
<LI><a href="guestbookkeith.html" target="_blank">View My Guestbook</a>
<LI><A HREF="mailto:jaguar@iinet.net.au">Email Me</a>
<LI><A HREF="powwow:jaguar@iinet.net.au">Call me on Powwow</a><p>
</UL>
If anything doesn't load properly or you have any suggestions
for improving this page, please feel free to email me at <A HREF="mailto:jaguar@iinet.net.au">jaguar@iinet.net.au</A>.
</BODY>
]]>