ch19.htm

prrl 5 programs codes in the book

the <TT>/root/document</TT> directory.

<BLOCKQUOTE>

<PRE>

&lt;A HREF=&quot;cgi-bin/search.pl/root/document&quot;&gt;Search the Document 

Directory &lt;A&gt;

</PRE>

</BLOCKQUOTE>

<P>

This <I>extra</I> path information can be accessed through the

<TT>PATH_INFO</TT> environment variable.

<P>

You can also use a question mark to pass information to a CGI

program. Typically, a question mark indicates that you are passing

keywords that will be used in a search.

<BLOCKQUOTE>

<PRE>

&lt;A HREF=&quot;cgi-bin/search.pl?Wine+1993&quot;&gt;Search for 1993 Wines&lt;/A&gt;

</PRE>

</BLOCKQUOTE>

<P>

The information that follows the question mark will be available

to your CGI program through the <TT>QUERY_STRING</TT>

environment variables.

<P>

Using either of these approaches will let you create <I>canned</I>

CGI requests. By creating these requests ahead of time, you can

reduce the amount of typing errors that your users might otherwise

have. Later in this chapter, the &quot;CGI and Environment Variables&quot;

section discusses all of the environment variables you can use

inside CGI programs.<BR>

<p>

<CENTER>

<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>

<TR><TD><B>Note</B></TD></TR>

<TR><TD>

<BLOCKQUOTE>

Generally speaking, visitors to your Web site should never have to type in the URL for a CGI program. A hypertext link should always be provided to start the program.</BLOCKQUOTE>



</TD></TR>

</TABLE>

</CENTER>

<P>

<H2><A NAME="YourFirstCGIProgram"><FONT SIZE=5 COLOR=#FF0000>

Your First CGI Program</FONT></A></H2>

<P>

You can use any text editor or word processor in the world to

create your CGI programs because they are simply Perl programs

that are invoked by a URL instead of the command line. Listing

19.1 contains a five-line CGI program-nearly the smallest program

you can have.

<P>

<IMG SRC="pseudo.gif" tppabs="http://cheminf.nankai.edu.cn/~eb~/Perl%205%20By%20Example/pseudo.gif" BORDER=1 ALIGN=RIGHT><p>

<BLOCKQUOTE>

<I>Turn on the warning option.<BR>

<I>Turn on the strict pragma.<BR>

<I>Send the HTTP header to the Web browser.<BR>

<I>Send a line of text to the Web browser.</I></I></I></I>

</BLOCKQUOTE>

<HR>

<BLOCKQUOTE>

<B>Listing 19.1&nbsp;&nbsp;19LST01.PL-A Very Small CGI Program

<BR>

</B>

</BLOCKQUOTE>

<BLOCKQUOTE>

<PRE>

#!/usr/local/bin/perl -w

use strict;



print &quot;Content-type: text/plain\n\n&quot;;

print &quot;Hello, World.\n&quot;;

</PRE>

</BLOCKQUOTE>

<HR>

<P>

The file that contains this CGI program should be placed in your

Web server's <TT>cgi-bin</TT> directory.

Then, the URL for this program will be something like <TT>http://localhost/cgi-bin/test.pl</TT>

(change localhost to correspond to your Web server's hostname).

Enter this URL into your Web browser and it should display a Web

page saying &quot;This is a test.&quot;<BR>

<p>

<CENTER>

<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>

<TR><TD><B>Note</B></TD></TR>

<TR><TD>

<BLOCKQUOTE>

You may wonder how the Web server knows that a CGI program should be executed instead of being displayed. This is an excellent question. It can be best answered by referring to the documentation that came with your particular server.</BLOCKQUOTE>



</TD></TR>

</TABLE>

</CENTER>

<P>

<P>

When the Web server executes your CGI program, it automatically

opens the <TT>STDIN</TT>, <TT>STDOUT</TT>,

and <TT>STDERR </TT>file handles for

you.

<UL>

<LI><TT><B><FONT FACE="Courier">STDIN</FONT></B></TT>-The standard

input of your CGI program might contain information that was generated

by an HTML form. Otherwise, you shouldn't use STDIN. See &quot;Inputs

to Your CGI Program&quot; later in this chapter for more information.

<LI><TT><B><FONT FACE="Courier">STDOUT</FONT></B></TT>-The standard

output of your CGI program is linked to the <TT>STDIN</TT>

of the Web browser. This means that when you print information

using the <TT>print()</TT> fuNCtion,

you are essentially writing directly to the Web browser's window.

This link will be discussed further in the &quot;HTTP Headers&quot;

section later in this chapter.

<LI><TT><B><FONT FACE="Courier">STDERR</FONT></B></TT>-The standard

output of your CGI program is linked to the Web server's log file.

This is very useful when you are debugging your program. Any output

from the <TT>die()</TT> or <TT>warn()</TT>

fuNCtion will be placed into the server's log file. The STDERR

file handle is discussed further in the &quot;Debugging CGI Programs&quot;

section later in this chapter.

</UL>

<P>

The Web server will also make some information available to your

CGI program through environment variables. You may recall the

<TT>%ENV</TT> hash from <A HREF="ch12.htm" tppabs="http://cheminf.nankai.edu.cn/~eb~/Perl%205%20By%20Example/ch12.htm" >Chapter 12</A>,

&quot;Using Special Variables.&quot; Details about the environment

variables you can use can be found in the &quot;Environment Variables&quot;

section later in this chapter.

<H2><A NAME="WhyAreFilePermissionsImportantinUNIX"><FONT SIZE=5 COLOR=#FF0000>

Why Are File Permissions Important in UNIX?</FONT></A></H2>

<P>

File permission controls can access files in UNIX systems. Quite

often, I hear of beginning CGI programmers who try to write files

into a directory in which they do not have write permission. UNIX

permissions are also called <I>rights</I>.

<P>

UNIX can control file access in a number of ways. There are three

levels of permissions for three classes of users. To view the

permissions on a file use the <TT>ls<I> </I></TT>command

with the <TT>-l</TT> command-line

option. For example:

<BLOCKQUOTE>

<PRE>

C:indyunix:~/public_html/pfind&gt;<B>ls -l

</B>total 40

-rw-r--r--   1 dbewley  staff        139 Jun 18 14:14 home.html

-rwxr-xr-x   1 dbewley  staff       9145 Aug 14 07:06 pfind

drwxr-xr--   2 dbewley  staff        512 Aug 15 07:11 tmp

</PRE>

</BLOCKQUOTE>

<P>

Each line of this listing indicates a separate directory entry.

The first character of the first column is normally either a dash

or the letter <TT>d</TT>. If a directory

entry has a <TT>d</TT>, it means that

the entry is a subdirectory of the current directory.

<P>

The other nine characters are the file permissions. Permissions

should be thought of in groups of three, for the three classes

of user. The three classes of user are:

<UL>

<LI><B>user</B>-the owner of the file or directory. The owner's

name is displayed in the third column of the <TT>ls</TT>

command's output.

<LI><B>group</B>-the group that owns the file. Files can have

both individual owners and a group. Several users can belong to

a single group.

<LI><B>others</B>-any user that is not the owner or in the group

that owns the file.

</UL>

<P>

Each of the classes can have one or more of the following three

levels of permission:

<UL>

<LI><B>r</B>-the class can read the file or directory.

<LI><B>w</B>-the class can write to the file or directory.

<LI><B>x</B>-the class can execute the file or list the directory.

</UL>

<P>

If a permission is not allowed to the user that ran the <TT>ls</TT>

command, its position is filled with a dash. For example:

<BLOCKQUOTE>

<PRE>

<B>ls -l hform.html

</FONT></B><FONT SIZE=2 FACE="Courier">-rwx------   1 dbewley  staff      11816 May  9 09:19 slideshow.pl

</PRE>

</BLOCKQUOTE>

<P>

The owner, <TT>dbewley</TT>, has full

rights - read, write, and execute for this file. The group, staff,

and everyone else have no rights.<BR>

<p>

<CENTER>

<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>

<TR><TD><B>Tip</B></TD></TR>

<TR><TD>

<BLOCKQUOTE>

Perl scripts are not compiled; they must be read by the Perl interpreter each time they are run. Therefore, Perl scripts, unlike compiled programs, must have execute <FONT FACE="LI Helvetica Light Oblique">and</FONT> read permissions.

</BLOCKQUOTE>



</TD></TR>

</TABLE>

</CENTER>

<P>

<P>

Here is another example:

<BLOCKQUOTE>

<PRE>

<B>ls -l pfind.pl

</FONT></B><FONT SIZE=2 FACE="Courier">-rwxr-x--   1 dbewley  staff       2863 Oct 10 1995  pfind.pl

</PRE>

</BLOCKQUOTE>

<P>

This time, the owner has full access while the group staff can

read and execute the file. All others have no rights to this file.

<P>

Most HTML files will have permissions that look like this:

<BLOCKQUOTE>

<PRE>

<B>ls -l schedule.html

</FONT></B><FONT SIZE=2 FACE="Courier">-rw-r--r--   1 dbewley  staff       2439 Feb  8 1996  schedule.html

</PRE>

</BLOCKQUOTE>

<P>

Everyone can read it, but only the user can modify or delete it.

There is no need to have execute permission siNCe HTML is not

an executable language.

<P>

You can change the permissions on a file by using the <TT>chmod</TT>

command. The <TT>chmod</TT> command

recognizes the three classes of user as <TT>u</TT>,

<TT>g</TT>, and <TT>o</TT>

and the three levels of permissions as <TT>r</TT>,

<TT>w</TT>, and <TT>x</TT>.

It grants and revokes permissions with a <TT>+</TT>

or <TT>-</TT> in conjuNCtion with

each permission that you want to change. It also will accept an

<TT>a</TT> for all three classes of

users at oNCe.

<P>

The syntax of the <TT>chmod</TT> command

is:

<BLOCKQUOTE>

<PRE>

chmod &lt;options&gt; &lt;file&gt;

</PRE>

</BLOCKQUOTE>

<P>

Here are some examples of the <TT>chmod</TT>

command in action

<BLOCKQUOTE>

<PRE>

<B>ls -l pfind.pl

</FONT></B><FONT SIZE=2 FACE="Courier">-rw------   1 dbewley  staff       2863 Oct 10 1995  pfind.pl

<B>chmod u+x pfind.pl

ls -l pfind.pl

</B>-rwx------   1 dbewley  staff       2863 Oct 10 1995  pfind.pl

</PRE>

</BLOCKQUOTE>

<P>

The first <TT>ls</TT> command shows

you the original file permissions. Then, the <TT>chmod</TT>

command add execute permission for the owner (or user) of <TT>pfind.pl</TT>.

The second <TT>ls</TT> command displays

the newly changed permissions.

<P>

To add these permissions for both the group and other classes,

use <TT>go+rx</TT> as in the following

example. Remember, users must have at least read and execute permissions

to run Perl scripts.

<BLOCKQUOTE>

<PRE>

<B>ls -l pfind.pl

</FONT></B><FONT SIZE=2 FACE="Courier">-rwx------   1 dbewley  staff       2863 Oct 10 1995  pfind.pl

<B>chmod go+rx pfind.pl

ls -l pfind.pl

</B>-rwxr-xr-x   1 dbewley  staff       2863 Oct 10 1995  pfind.pl

</PRE>

</BLOCKQUOTE>

<P>

Now, any user can read and execute <TT>pfind.pl</TT>.

Let's say a serious bug was found in pfind.pl and we don't want

it to be executed by anyone. To revoke execute permission for

all classes of users, use the <TT>a-x</TT>

option with the <TT>chmod</TT> command.

<BLOCKQUOTE>

<PRE>

<B>ls -l pfind.pl

</FONT></B><FONT SIZE=2 FACE="Courier">-rwxr-xr-x   1 dbewley  staff       2863 Oct 10 1995  pfind.pl

<B>chmod a-x pfind.pl

ls -l pfind.pl

</B>-rw-r--r--   1 dbewley  staff       2863 Oct 10 1995  pfind.pl

</PRE>

</BLOCKQUOTE>

<P>

Now, all users can read <TT>pfind.pl</TT>,

but no one can execute it.

<H2><A NAME="HTTPHeaders"><FONT SIZE=5 COLOR=#FF0000>

HTTP Headers</FONT></A></H2>

<P>

The first line of output for most CGI programs must be an HTTP

header that tells the client Web browser what type of output it

is sending back via <TT>STDOUT</TT>.

Only scripts that are called from a server-side iNClude are exempt

from this requirement.<BR>

<P>

<CENTER><B>Table 19.1&nbsp;&nbsp;A List of HTTP Headers</B></CENTER>

<p>

<CENTER>

<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>

<TR><TD WIDTH=166><I>Response Type</I></TD><TD WIDTH=238><I>HTTP Header</I>

</TD></TR>