Although most CGI programs available for download are written in the
Perl language, Perl is not the only language that can be used. A CGI program
can be any program compiled from C, C++, Pascal, BASIC, or any other language
the server can understand.
This is what happens when browser and CGI program interact: (Let's take
a feedback form as an example.) Someone fills in the form and clicks the
button. That button click causes the browser to send the information to
the server. The information includes:
(1) The location and name of the CGI program. (This information is contained
in the form tag's action="_____" attribute.)
(2) The name and values of any hidden fields.
(3) The name and contents of any form fields your visitor filled in.
The server receives the information and sends it to the CGI program.
(If the server can't find the CGI program, you get a 404 "file not found"
error.) The browser waits for the CGI program to reply. When the CGI program
has finished its reply and quits running, the browser gets notification
from the server that the gate has closed and it is no longer necessary
to wait for more information. Note: If the browser leaves before the CGI
program has completed its tasks, the server stops the program. That is
part of CGI's nature -- it takes both a browser and a CGI program to set
up and maintain the interface. When one or the other quits or leaves,
it is no longer CGI and there is no point in letting processes continue
to run. Of course, nothing at all will happen until after a CGI program
is installed.
Because CGI programs written with Perl are so common, the following
installation instructions are for Perl programs. Often, Perl programs
are called scripts. It is correct either way.
In the spirit of recognizing that CGI can utilize programs of other languages,
this article will use the word "programs". Most Perl programs come with
installation instructions. For your first installation, try to find one
with instructions written clearly. Almost every CGI program you install
will need some modification. When you do modifications to Perl programs,
do so with an ASCII/plain text word processor. Window's Notepad and Macintosh's
BBEdit are good for this kind of job. Editing the program with a word
processor capable of rich text (point sizes, colors, bolds, etc) display
or programs specifically designed for HTML editing that tend to convert
text to HTML symbols (such as Front Page) will most likely introduce program
crashing bugs in the form of unrecognized or extraneous characters. The
one rule: Make a backup copy. That way you can start anew, if required.
The following are common modifications for every Perl CGI program installation:
(1) (Unix and Linux only) The first line of your Perl program should
point to the Perl interpreter on your server. That is the line beginning
with #! and continuing with one or more directories and then the name
of the Perl interpreter. Your web hosting company's online manual should
tell you the location of Perl. If you have a choice of Perl versions,
use the latest version unless the program's instructions say otherwise.
Here are two examples of "first lines": #!/usr/bin/perl #!/usr/local/bin/perl
(2) If your program will do any emailing (such as feedback form results),
then you will need to specify your server's mailer. Your web hosting company's
online manual should tell you its mailer's location. The instructions
to the program should tell you where to type in the data. Usually, the
data will be between single or double quotes following a line beginning
with a dollar sign. Examples: $mail="/usr/bin/sendmail -t"; $Sendmail
= '/usr/sbin/sendmail'; $Mailer = '/usr/var/qmail-inject';
Note for NT servers: Your server's mailer may be quite different than
what is described here. Please consult with your technical support if
you want help installing CGI programs that email. A common reason for
program errors: Most Perl programs that utilize sendmail to send email
will use sendmail's -t switch. The -t switch may or may not be specified
in the same line that the mailer was specified. (The first example above
includes the -t switch, the others don't.) If your program works otherwise
but no email is being sent, try adding or deleting the switch.
Now, if you're using qmail and your program won't run, you may need to
go through the code and remove all -t switches because that switch will
wreak havoc with qmail. (By the way, the -t switch simply tells sendmail
to parse the headers of the email going out to determine where it should
be sent. There are other ways to tell sendmail where to send stuff, but
the -t switch is the simplest.)
(3) The program's instructions may require the locations of other files
or directories. It may also require URLs. Please notice the difference
-- file locations are server directory locations and URLs begin with the
characters http:// When the instructions ask for locations, determine
whether that is a server file location or a URL.
(4) If the program's instructions require an email address in the Perl
program, go ahead and do it. If the address is between quotes (double
quotes) the @ symbol must be escaped. Escaping a symbol means putting
a backslash character immediately in front of it: \@ If the address is
between apostrophes (single quotes) then the @ symbol does not need escaping;
but it won't hurt if you do it.
(5) After you have done the other edits per the instructions, upload
the program as ASCII/plain text into a directory which is authorized to
run CGI programs. The reason for the ASCII/plain text upload is because
text line endings are different among operating systems. On Windows, DOS,
and Macintosh systems, line endings are composed of two characters, ASCII
13 and ASCII 10, with Macintosh using the two characters in opposite order.
Unix uses only one character for line endings, ASCII 13. When you specify
your upload as ASCII/plain text, you give your software the chance to
correct the line endings to comply with the receiving operating system's
expectations. If you upload in binary, however, you are surely going to
introduce extraneous and program killing characters. Note that the ASCII/plain
text rule applies only to programs that are text files (such as Perl).
Compiled programs will need to be up-/downloaded as binary files.
(6) (Unix and Linux only) Before your program can do stuff for you,
it must have permission to do so. The available permissions are "read",
"write", and "execute".
"read" has a value of 4. "write" has a value of 2. "execute" has a value
of 1. To set more than one permission, add the values together. "read"
plus "execute" has a value of 5. The permissions are at three levels:
"user" (you, the person with the root password), "group" (the people with
administrative or other group access to the server), and "world" (everybody).
Some FTP programs have checkboxes labeled "read", "write", and "execute"
which you can select from. Others, and also telnet, require three digits.
Unless the instructions say otherwise, CGI programs need permission
755. 7 -> user:read/write/execute 5 -> group:read/execute 5 -> world:read/execute
If you have telnet access, you can change directories to where the program
is and type: CHMOD 755 programname.cgi
If your FTP software allows you to set permissions from within it, you
may need to read its help files to find out how. Here are directions for
two popular FTP programs:
~~ Macintosh Transmit -- shareware, can be downloaded from http://download.com/
In the preferences area, you'll see "automatically set uploaded permissions
to" checkboxes.
~~ Windows WS_FTP LE -- freeware, can be downloaded from http://tucows.com/
When connected to your server, select the file that needs permissions
changed. When the file is selected, right-click on your mouse. Select
CHMOD from the right-click menu. Select the desired permissions from the
checkboxes. Click "OK". (The button marked "DirInfo" will list the files
on your server with its current permissions. You might need to click the
"Refresh" button to make the latest changes display correctly.)
(7) Internal Server Errors -- the generic error that can mean many different
things. To debug: If you have access to telnet, try running the Perl program
from the command line (when you type something in telnet that tells the
server to do something, you are typing on the command line) with the -w
switch: perl -w programname.cgi
If you have access to your error logs, they should give you a clue to
the error and a line number close to where the error occurred. If you
have recourse to neither of the above:
First re-upload the program while making very sure it is uploaded as
ASCII/plain text. Then double-check the permissions. If you still get
errors, closely look over the changes you made to the program to ensure
you left all quotation marks and semi-colons and other punctuations as
they were.
Check to make sure no long comment lines wrapped to the next line. Comments
begin with a # character, which tells the interpreter to ignore the rest
of the line. If a comment line wraps then it needs a # character at the
beginning of the line.
As a last resort, start at the beginning again or try a different program.
The above seven steps will provide some experience. It's probably best
to leave complex programs until after your confidence rises. Not everything
has been covered in this article. Things can go wrong that don't have
room to be addressed here. If you follow the program's installation instructions
(provided they are adequate) then you should be successful. If not, try
again, maybe with a different program. You can ask a CGI programmer or
installer to take a look if things seem too complex or won't work at all.
