ch7.htm

CGI programming is the hottest stuff to look out for in this book

here offers the possibility of randomly inserting an image inside
an HTML page. It is more a random image tag generator than a random
image generator, in fact (it is the tag that is generated by the
script, not the image itself). This feature is used in a lot of
well known Web pages. Yahoo! and Lycos, for example, use it to
display random advertisements on their search pages. Follow these
steps to install the randimg.cgi script on your server:
<OL>
<LI>In the page you want the random image to appear, insert the
tag <TT><FONT FACE="Courier">&lt;!--#exec cgi=&quot;/cgi-bin/randimg.cgi&quot;--&gt;</FONT></TT>.
<LI>Copy the images (GIF or JPG) files to a directory inside your
document hierarchy, a directory called Images under the document
root, for example.
<LI>Type in the Perl script shown in Listing 7.2 and save it in
your <TT><FONT FACE="Courier">cgi-bin</FONT></TT> directory (don't
forget to make it an executable, using <TT><FONT FACE="Courier">chmod
700 randimg.cgi</FONT></TT> on UNIX platforms).
<LI>Edit the script to reflect your settings (number of images,
images paths, alternative tags, and anchors).
<LI>Use your browser and open the page in which you've just inserted
the SSI tag. You should see a different image at each request
(you may have to use the Reload option of your browser instead
of just opening the URL because the page may be in cache). Each
image points to a different place, as you have defined in the
script.
</OL>
<HR>
<BLOCKQUOTE>
<B>Listing 7.2. A random image tag generator script in Perl.<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">#!/usr/bin/perl<BR>
#<BR>
# randimg.cgi - Random image tag generator<BR>
#<BR>
# [e-mail], March 1996<BR>
### Number of images<BR>
$total = 2;<BR>
### Relative paths of each image<BR>
@images = (&quot;/Images/hello.gif&quot;, &quot;/Images/hi.gif&quot;);
<BR>
### ALT tag for each image<BR>
@alt = (&quot;Hello&quot;, &quot;Hi, how are you?&quot;);<BR>
### Link for each image<BR>
@link = (&quot;http://www.esoterica.pt/newbie/&quot;, &quot;http://www.somewhere.com/&quot;);
<BR>
srand;<BR>
$number = int(rand($total));<BR>
print &quot;Content-Type: text/html\n\n&quot;</FONT></TT>;<BR>
<TT><FONT FACE="Courier">print &quot;&lt;A HREF=\&quot;$link[$number]\&quot;&gt;&lt;IMG
SRC=\&quot;$images[$number]\&quot; </FONT></TT><FONT FACE="ZapfDingbats">&Acirc;</FONT><TT><FONT FACE="Courier">ALT=\&quot;$alt[$number]\&quot;
BORDER=0&gt;&lt;/A&gt;&quot;</FONT></TT>
</BLOCKQUOTE>
<HR>
<P>
Imagine that you want to display a random image but also log in
the number of times users actually click on a given image. If
the URL you have defined for an image points out to a distant
site, you have no way to know if your advertisements really call
a user's attention. One possible improvement to this script is
the addition of URLs pointing to another script on your system-a
script that receives URLs, saves or counts them on a file, and
then redirects the Web browser to this same URL (using the <TT><FONT FACE="Courier">Location:</FONT></TT>
directive as the output of the script).
<H2><A NAME="TheProtocoloftheWebHTTP"><FONT SIZE=5 COLOR=#FF0000>The
Protocol of the Web: HTTP</FONT></A></H2>
<P>
The <I>HyperText Transfer Protocol (HTTP)</I> was designed for
the transfer of pages between programs called <I>clients</I> and
<I>servers</I>. The client is the entity requesting a given document
and is what we usually call the <I>browser</I> (in the context
of the World Wide Web). The server is responsible for replying
to a client's demands, and it is up to the server to find and
send a given page. The usual functioning is as follows:
<OL>
<LI>The browser connects and requests the server for a page.
<LI>The server reads the page from the file system, sends it,
and terminates connection.
</OL>
<P>
Although being adequate to the task it was designed for (transfer
of hypertext pages), the HTTP protocol does not cover-which is
absolutely normal-other Internet user's needs, such as reading
mail or getting information from other users by using finger.
The HTTP protocol is also a stateless protocol making the server
forget any information it may have about the client (user), even
if the client has asked for a page a few seconds before.
<H2><A NAME="GatewaysAccessingOtherProtocolsthro"><FONT SIZE=5 COLOR=#FF0000>Gateways:
Accessing Other Protocols through the Web</FONT></A></H2>
<P>
The HTTP protocol limits the possibilities and usefulness of the
Web as an integrated Internet access platform because many things
we expect to use are not available through the Web. Sure, the
Web could live by itself, and it would already be a very interesting
and appealing Internet service. But the need to integrate other
protocols and functions arose, and gateways are the answer to
the problem.
<P>
As the name suggests, a <I>gateway</I> is a program that functions
as an interface between two systems. In this case, on one side
there is the Web and its HTTP protocol, and on the other side
there are other Internet protocols or applications. The gateway
is the solution, providing the Internet user and its browser a
picture of both sides.
<P>
Gateways are no more than specially designed programs in any computer
language (C, Perl, shell scripts, and so on), respecting the CGI
specification or some proprietary API specification. In order
to develop a gateway, one needs to know the CGI specification
(methods of calling the scripts, variables passed by the server,
format of the output, and so on) but also the protocol or program
to which the gateway will be talking. This can be as simple as
using a finger or archie program, or as complex as talking to
a mail or news server. Before starting to develop your own gateways,
you should search the Internet for pre-written gateways because
virtually anything you might think of has already been handled
by someone on the other side of the world. Welcome to the Internet!
<P>
In fact, some gateways come standard with the Web server software
(in the <TT><FONT FACE="Courier">cgi-bin</FONT></TT> directory)
and are ready to use. The Apache server, for example, comes with
a finger, wais, and archie gateway (among others) that you only
need to customize to reflect your system settings.
<H2><A NAME="ImprovingExistingGateways"><FONT SIZE=5 COLOR=#FF0000>Improving
Existing Gateways</FONT></A></H2>
<P>
To improve existing gateways, you must first search for them.
You can have a look at the tools available in your <TT><FONT FACE="Courier">cgi-bin</FONT></TT>
directory or check out a searching engine or Internet index site
if you need a specific gateway.
<P>
Improvement of prewritten gateways can be done in several ways:
<UL>
<LI><FONT COLOR=#000000>Editing the gateways to suit your settings
(paths, file and server names, and so on)</FONT>
<LI><FONT COLOR=#000000>Improving the presentation of results</FONT>
<LI><FONT COLOR=#000000>Adding new functions</FONT>
</UL>
<P>
While the editing to suit your settings is mandatory and the improvement
of the presentation is optional but frequently useful, the addition
of new functions is the most complex task. You need to fully understand
the existing gateway code if you want to add a new feature. Imagine
that you have found a mail gateway that allows the reading of
mail messages from a Web page, and you think that deleting a message
from your mailbox would be a nice feature to integrate in the
gateway. So, you need to understand the mail protocol (POP in
general), but you also need to read and understand the code of
the gateway in order to introduce alterations.
<H2><A NAME="SomeGatewayExamples"><FONT SIZE=5 COLOR=#FF0000>Some
Gateway Examples</FONT></A></H2>
<P>
This section covers some examples of gateways that could be used
in the World Wide Web. Both examples presented here are custom
developed but exist in several different variations on the Internet.
<H3><A NAME="finger"><TT><FONT SIZE=4 FACE="Courier">finger</FONT></TT></A>
</H3>
<P>
The <TT><FONT FACE="Courier">finger</FONT></TT> program is useful
to find information, by using an e-mail address, about someone
on the Internet. In general, we can get a person's name, the last
login time, and if he or she has received mail lately. If you
don't use a Web gateway, you must either use a shell in a UNIX
platform (with the telnet program) in order to issue the finger
command or use a finger client on your personal computer. On the
other side (the remote server), the finger server waits for requests
and sends information about a user.
<P>
The use of <TT><FONT FACE="Courier">finger</FONT></TT> through
the Web has a lot more potential. Just think of the display capabilities
of a Web browser. It is possible to include some HTML tags on
the finger information so that when others use <TT><FONT FACE="Courier">finger</FONT></TT>
to check your e-mail address, they actually see an attractive
information page about you.
<P>
In a UNIX environment, the finger server reads the user <TT><FONT FACE="Courier">.plan</FONT></TT>
and <TT><FONT FACE="Courier">.project</FONT></TT> file placed
on each user's home directory and displays the contents. So, you
can edit your <TT><FONT FACE="Courier">.plan</FONT></TT> file
(by opening a telnet session on the server or by editing it at
home and transferring it with an FTP program) and put in something
such as
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&lt;H1 ALIGN=center&gt;Hello, it is me,
look&#133;&lt;/H1&gt;<BR>
&lt;IMG SRC=&quot;/~amcf/photo.gif&quot;&gt;</FONT></TT>
</BLOCKQUOTE>
<P>
which would display the sentence and the photo indicated by the
<TT><FONT FACE="Courier">&lt;IMG SRC&gt;</FONT></TT> tag.
<P>
The finger gateway presented in Listing 7.3 allows users to retrieve
and display this kind of personal information inside a Web page
(along with other data that the finger server sends).
<P>
In order to use this script, you must install it in your <TT><FONT FACE="Courier">cgi-bin</FONT></TT>
directory and then call the corresponding URL with <TT><FONT FACE="Courier">/cgi-bin/finger.cgi</FONT></TT>.
There is no need to develop a separate page to let users introduce
the e-mail address they want to have information about because
the script is intelligent enough to display the main page itself.
<HR>
<BLOCKQUOTE>
<B>Listing 7.3. The finger gateway.<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">#!/usr/bin/perl<BR>
<BR>
require '/usr/lib/cgi-lib.pl';&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;#
The useful cgi-lib<BR>
<BR>
##### Paths, binaries and system specific information #####<BR>
$url = '/cgi-bin/finger.pl';&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;#
finger URL<BR>
$finger = '/usr/bin/finger';&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;#
Path for the finger client program<BR>
<BR>
&amp;ReadParse(*input);&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
# cgi-lib, constructs list of key=value form data<BR>
print &amp;PrintHeader();&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;
# cgi-lib, prints header &quot;Content-type: text/&Acirc;html\n\n&quot;
<BR>
<BR>
if (&amp;MethGet()) {&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;#
GET was used, so...<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&amp;InitialForm();&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;#
... retrieve the initial form<BR>
} else {&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;#
POST was used so process the query<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&amp;Finger();<BR>
}<BR>
<BR>
exit(0);<BR>
<BR>
##### Presents initial form #####<BR>
sub InitialForm {<BR>
&nbsp;&nbsp;&nbsp;&nbsp;print &lt;&lt;EOM;<BR>
&lt;HTML&gt;<BR>
&lt;HEAD&gt;<BR>
&lt;TITLE&gt;Finger&lt;/TITLE&gt;<BR>
&lt;/HEAD&gt;<BR>
&lt;BODY&gt;<BR>
&lt;H1 ALIGN=center&gt;Finger&lt;/H1&gt;<BR>
&lt;P&gt;<BR>
This page allows you to use a finger client and discover information
<BR>
about an email address.<BR>
&lt;/P&gt;<BR>
&lt;FORM ACTION=&quot;$url&quot; METHOD=post&gt;<BR>
&lt;P ALIGN=center&gt;Email address: &lt;INPUT NAME=email VALUE=&quot;&quot;&gt;&lt;/P&gt;
<BR>
&lt;P ALIGN=center&gt;&lt;INPUT TYPE=submit VALUE=&quot;Go Get
It&quot;&gt;&lt;/P&gt;<BR>
&lt;/FORM&gt;<BR>
&lt;/BODY&gt;<BR>
&lt;/HTML&gt;<BR>
EOM<BR>
}<BR>
<BR>
##### Gets user's name from finger information, using login as
the key #####<BR>
sub Finger {<BR>
&nbsp;&nbsp;&nbsp;&nbsp;$email = $input{'email'};<BR>
&nbsp;&nbsp;&nbsp;&nbsp;if ($email =~ /[^a-zA-Z0-9_\-\.@]/) {
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$_ = &quot;The
email address should be on the form &lt;I&gt;user@server&lt;/I&gt;!&quot;;
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;} else {<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;$_ = '$finger
$email';<BR>
&nbsp;&nbsp;&nbsp;&nbsp;}<BR>
&nbsp;&nbsp;&nbsp;&nbsp;print &lt;&lt;EOM;<BR>
&lt;HTML&gt;<BR>
&lt;HEAD&gt;<BR>
&lt;TITLE&gt;Finger: $email&lt;/TITLE&gt;<BR>
&lt;BODY&gt;<BR>
&lt;/HEAD&gt;<BR>
&lt;BODY&gt;<BR>
&lt;H2 ALIGN=center&gt;Finger: $email&lt;/H2&gt;<BR>
&lt;PRE&gt;<BR>
$_<BR>
&lt;/PRE&gt;<BR>
&lt;/BODY&gt;<BR>
&lt;/HTML&gt;<BR>
EOM<BR>
}</FONT></TT>
</BLOCKQUOTE>
<HR>
<P>
The <TT><FONT FACE="Courier">cgi-lib.pl</FONT></TT> used by this
script (see the require command at the bottom of Listing 7.3)
is a useful CGI library for Perl programs and can be found at
<TT><FONT FACE="Courier"><A HREF="http://www.bio.cam.ac.uk/web/">http://www.bio.cam.ac.uk/web/</A></FONT></TT>.
It is very often used in CGI scripts. I suggest you download a
copy and keep it handy because you will need it often.
<P>
Also, notice the verification of user input:
<BLOCKQUOTE>