ch19.htm

this is a book on pearl , simple example with explanation is given here. it could be beneficial for

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" 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" >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>

<TR><TD WIDTH=166>Text</TD><TD WIDTH=238>Content Type: text/plain

</TD></TR>

<TR><TD WIDTH=166>HTML page</TD><TD WIDTH=238>Content Type: text/html

</TD></TR>

<TR><TD WIDTH=166>Gif graphic</TD><TD WIDTH=238>Content Type: image/gif

</TD></TR>

<TR><TD WIDTH=166>Redirection to another Web page</TD><TD WIDTH=238>Location: http://www.foobar.com

</TD></TR>

<TR><TD WIDTH=166>Cookie</TD><TD WIDTH=238>Set-cookie: ...</TD>

</TR>

<TR><TD WIDTH=166>Error Message</TD><TD WIDTH=238>Status: 402 

</TD></TR>

</TABLE>

</CENTER>

<P>

<P>

All HTTP headers must be followed by a blank line. Use the following

line of code as a template:

<BLOCKQUOTE>

<PRE>

print(&quot;Content Type: text/html\n\n&quot;);

</PRE>

</BLOCKQUOTE>

<P>

Notice that the HTTP header is followed by <I>two</I> newline

characters. This is very important. It ensures that a blank line

will always follow the HTTP header.

<P>

If you have installed any helper applications for Netscape or

are familiar with MIME types, you already recognize the <TT>text/plain</TT>

and <TT>text/html</TT> parts of the

<TT>Content Type</TT> header. They

tell the remote Web browser what type of information you are sending.

The two most common MIME types to use are <TT>text/plain</TT>

and <TT>text/html</TT>.

<P>

The <TT>Location</TT> header is used

to redirect the client Web browser to another Web page. For example,

let's say that your CGI script is designed to randomly choose

from among 10 different URLs in  order to determine the next Web

page to display. ONCe the new Web page is chosen, your program

outputs it like this:

<BLOCKQUOTE>

<PRE>

print(&quot;Location: $nextPage\n\n&quot;);