ch20.htm

《Perl 5 Unreleased》

characters in HTML and their codes are
<UL>
<LI><TT><FONT FACE="Courier">&amp;lt;</FONT></TT> as the escape
sequence for <TT><FONT FACE="Courier">&lt;</FONT></TT>.
<LI><TT><FONT FACE="Courier">&amp;gt;</FONT></TT> as the escape
sequence for <TT><FONT FACE="Courier">&gt;</FONT></TT>.
<LI><TT><FONT FACE="Courier">&amp;amp;</FONT></TT> as the escape
sequence for the ampersand (<TT><FONT FACE="Courier">&amp;</FONT></TT>).
<LI><TT><FONT FACE="Courier">&amp;quot;</FONT></TT> the escape
sequence for the double quote (<TT><FONT FACE="Courier">&quot;</FONT></TT>).
</UL>
<P>
So, to show this string in an HTML page, <TT><FONT FACE="Courier">&lt;HELLO&gt;</FONT></TT>,
you would use the text statement <TT><FONT FACE="Courier">&amp;lt;HELLO&amp;gt;</FONT></TT>
in your code. Note that the semicolon is required in each code.
<H2><A NAME="WhatIsaURL"><FONT SIZE=5 COLOR=#FF0000>What Is a
URL?</FONT></A></H2>
<P>
URL stands for <I>uniform resource locator</I>. Basically, it's
an extension of a file name to include the network address of
a &quot;thing&quot; file and where that &quot;thing&quot; may
be found. The &quot;thing&quot; your URL is pointing to may be
a file, directory, database, image, newsgroup, archive, and so
on, on a machine that is residing anywhere on the Internet. It's
up to the browser to show that data to you.
<P>
A URL consists of three parts:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">service://sitename[:port]/path/filename</FONT></TT>
</BLOCKQUOTE>
<P>
The <TT><FONT FACE="Courier">service</FONT></TT> part tells you
which service you are trying to access. The <TT><FONT FACE="Courier">sitename</FONT></TT><B>
</B>is the Internet address of the machine where the service is
being sought. The<B> </B><TT><FONT FACE="Courier">port</FONT></TT>
number is optional, because the default is port 80. The <TT><FONT FACE="Courier">path/filename</FONT></TT>
is the location of the file relative to the root directory for
the server.
<P>
The services your browser can offer will vary. Here are the most
common types of service you can use with a Web browser:
<UL>
<LI><TT><FONT FACE="Courier">Http</FONT></TT> for perusing an
HTML document
<LI><TT><FONT FACE="Courier">Gopher</FONT></TT> for starting a
gopher session
<LI><TT><FONT FACE="Courier">Ftp</FONT></TT> for starting an ftp
session
<LI><TT><FONT FACE="Courier">Telnet</FONT></TT> for starting a
telnet session
<LI><TT><FONT FACE="Courier">File</FONT></TT> for getting a local
file
<LI><TT><FONT FACE="Courier">News</FONT></TT> for a Usenet newsgroup
</UL>
<P>
Here are some examples of URLs:
<UL>
<LI><TT><FONT FACE="Courier">ftp://pop.ikra.com/pub/perl5/VRML.pm</FONT></TT>&nbsp;&nbsp;This
URL specifies a file to get via <TT><FONT FACE="Courier">ftp</FONT></TT>
from the <TT><FONT FACE="Courier">/pub/perl5</FONT></TT> directory.
<LI><TT>http://www.ikra.com/iistv.html</TT>&nbsp;&nbsp;This
URL specifies an HTML document on the node <TT><FONT FACE="Courier">www.ikra.com</FONT></TT>.
<LI><TT><FONT FACE="Courier">news://ikra.com/newsgroups/comp.dcom.telecom</FONT></TT>&nbsp;&nbsp;This
URL specifies a newsgroup to get on <TT><FONT FACE="Courier">ikra.com</FONT></TT>.
</UL>
<P>
To specify URL links to other documents, use the anchor tags,
<TT><FONT FACE="Courier">&lt;A&gt;</FONT></TT> and <TT><FONT FACE="Courier">&lt;/A&gt;</FONT></TT>.
Anchor tags are used to provide links to other documents as well
as provide a location in a document that another HTML document
can refer to. Please check the references in this chapter if you
are not familiar with using HTML anchors. Here's the format for
using anchors for creating links to other documents:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&lt;A HREF=&quot;URL&quot;&gt;Text describing
where the URL points to&lt;/A&gt;</FONT></TT>
</BLOCKQUOTE>
<P>
The <TT><FONT FACE="Courier">HREF</FONT></TT> token specifies
the URL to use. The text between the first ending <TT><FONT FACE="Courier">&gt;</FONT></TT>
and the start of <TT><FONT FACE="Courier">&lt;/A&gt;</FONT></TT>
is shown by the browser in a different color. The space between
<TT><FONT FACE="Courier">&lt;A</FONT></TT> and <TT><FONT FACE="Courier">HREF</FONT></TT>
is required.
<P>
Here is a sample hypertext reference in an HTML document. For
clarity, I refer to the document that specifies the hyperlink
as the first document, and the location to which the URL points
as the second document. Let's look at the URL:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&lt;A HREF=&quot;http://pop.ikra.com/iistv.html&quot;&gt;IISTV&lt;/A&gt;</FONT></TT>
</BLOCKQUOTE>
<P>
The browser showing this link will make the word <TT><FONT FACE="Courier">IISTV</FONT></TT>
show up in a different color than regular text and the link is
underlined. Clicking on the word <TT><FONT FACE="Courier">IISTV</FONT></TT>
will cause the browser to get the file <TT><FONT FACE="Courier">iistv.html</FONT></TT>
from <TT><FONT FACE="Courier">www.ikra.com</FONT></TT>.
<P>
You normally use the absolute pathname of the file in a URL. Pathnames
always use the standard UNIX syntax (<TT><FONT FACE="Courier">/</FONT></TT>),
not the DOS syntax (<TT><FONT FACE="Courier">\</FONT></TT>), for
delimiting directory names in a path. Relative pathnames are also
possible if the anchor being specified happens to reside in the
same directory tree on the same machine as the original document.
<P>
Use relative links if you are likely to move directories around.
Moving the top-level file's location will move the entire tree
with it. On the other hand, a full pathname makes an explicit
link to the file regardless of where other files are moved to.
<P>
Anchors can also be used to move to a particular part within the
same document. Suppose you want to set a link from one document
(<TT><FONT FACE="Courier">index.html</FONT></TT>) to a section
in another document (<TT><FONT FACE="Courier">text.html</FONT></TT>).
Therefore, in the <TT><FONT FACE="Courier">index.html</FONT></TT>
file, define a tag for the topic in the <TT><FONT FACE="Courier">text.html</FONT></TT>
file like this:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&lt;A NAME = &quot;Daumesnil&quot;&gt;Daumesnil
Station&lt;/A&gt;&lt;P&gt;<BR>
The station to go to the Zoo from....</FONT></TT>
</BLOCKQUOTE>
<P>
In the <TT><FONT FACE="Courier">index.html</FONT></TT> file, you
create the anchor to the <TT><FONT FACE="Courier">text.html</FONT></TT>
file with a named anchor. A named anchor uses the name of the
file, followed by the hash mark (<TT><FONT FACE="Courier">#</FONT></TT>)
and the location in the file:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">Get off on &lt;A HREF = &quot;text.html#Daumesnil&quot;&gt;the
Daumesnil stop&lt;/A&gt;<BR>
and go two stations west to Port Doree.</FONT></TT>
</BLOCKQUOTE>
<P>
Now when the user clicks on the words <TT><FONT FACE="Courier">the
Daumesnil stop</FONT></TT>, the browser  loads <TT><FONT FACE="Courier">index.html</FONT></TT>
and goes to the place where the tag is placed for <TT><FONT FACE="Courier">Daumesnil</FONT></TT>.
To go to a location within the same file, skip the filename portion
and use only the hash mark with the anchor name.
<H2><A NAME="CGIScripts"><FONT SIZE=5 COLOR=#FF0000>CGI Scripts</FONT></A>
</H2>
<P>
A request from a client browser at the Web server is handled by
the <TT><FONT FACE="Courier">httpd</FONT></TT> daemon. If the
request is to run a CGI program, the server will run the program
for you and return the results of the program back to the client
browser. Input to the CGI program being run is sent either via
the command line or through environment variables. The CGI program
can be in any language, but it has to be able to process input
in this way. The output from the program is generally to standard
output. Therefore, a CGI program can be a compiled executable,
or a Perl, shell, or awk script, and so on. Naturally, because
this book is about Perl, the CGI scripts I discuss here will be
in Perl.
<P>
CGI scripts are similar to the scripts you would write to handle
the command-line interface but with one glaring exception: You
cannot send command-line options to CGI scripts. CGI uses the
command line for other purposes, so it's impossible to send arguments
to the script via the command line.
<P>
CGI uses environment variables to send your CGI program its parameters.
Environment variables are useful in CGI scripts in that any child
processes created by a CGI script also inherit the values of the
parent's environment variables. Some of the main environment variables
used by CGI scripts are listed in Table 20.1. The dagger (&#134;)
indicates that the variable might not be supported on all servers,
so use it with caution.<BR>
<P>
<CENTER><B>Table 20.1. CGI environment variables.</B></CENTER>
<P>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD WIDTH=186><I>Variable</I></TD><TD WIDTH=404><I>Description</I>
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">AUTH_TYPE</FONT></TT>
</TD><TD WIDTH=404>The authorization type</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">CONTENT_LENGTH</FONT></TT>
</TD><TD WIDTH=404>The size in a decimal number of octets (8-bit bytes) of any attached entity
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">CONTENT_TYPE</FONT></TT>
</TD><TD WIDTH=404>The MIME type of an attached entity</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">DOCUMENT_ROOT</FONT></TT>
</TD><TD WIDTH=404>The root directory for your server's documents&#134;
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">DOCUMENT_URL</FONT></TT>
</TD><TD WIDTH=404>The URL for your client's document&#134;</TD>
</TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">DOCUMENT_NAME</FONT></TT>
</TD><TD WIDTH=404>*The name of your client's document&#134;</TD>
</TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">DATE_LOCAL</FONT></TT>
</TD><TD WIDTH=404>Local to server</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">DATE_GMT</FONT></TT>
</TD><TD WIDTH=404>Local to server</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">GATEWAY_INTERFACE</FONT></TT>
</TD><TD WIDTH=404>The server's CGI specification version</TD>
</TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">HTTP_(string)</FONT></TT>
</TD><TD WIDTH=404>The client's header data</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">PATH_INFO</FONT></TT>
</TD><TD WIDTH=404>The path to be interpreted by the CGI script
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">PATH_TRANSLATED</FONT></TT>
</TD><TD WIDTH=404>The virtual to physical mapping of the path
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">QUERY_STRING</FONT></TT>
</TD><TD WIDTH=404>The URL-encoded search string</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">REMOTE_ADDR</FONT></TT>
</TD><TD WIDTH=404>The IP address of the client</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">REMOTE_HOST</FONT></TT>
</TD><TD WIDTH=404>The full qualified domain name of client</TD>
</TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">REMOTE_IDENT</FONT></TT>
</TD><TD WIDTH=404>The identity data of the client</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">REMOTE_USER</FONT></TT>
</TD><TD WIDTH=404>The user ID sent by the client</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">REQUEST_METHOD</FONT></TT>
</TD><TD WIDTH=404>The request method sent by the client</TD>
</TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">SCRIPT_NAME</FONT></TT>
</TD><TD WIDTH=404>The URL path identifying the CGI script</TD>
</TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">SERVER_NAME</FONT></TT>
</TD><TD WIDTH=404>The server name (the host name of a DNS entry)
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">SERVER_PORT</FONT></TT>
</TD><TD WIDTH=404>The port at which the request was received
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">SERVER_ROOT</FONT></TT>
</TD><TD WIDTH=404>*The root directory for CGI binaries at the server
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">SERVER_PROTOCOL</FONT></TT>
</TD><TD WIDTH=404>A request for protocol name and version number
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=186><TT><FONT FACE="Courier">SERVER_SOFTWARE</FONT></TT>
</TD><TD WIDTH=404>A request for server software name and version number
</TD></TR>
</TABLE></CENTER>
<P>
<P>
Let's briefly cover some of these environment variables and how
your CGI script uses them. Keep in mind that only a few of these
variables are guaranteed to be set at any one invocation. Not
all of these variables are even set by all servers, so check your
documentation (usually a <TT><FONT FACE="Courier">README</FONT></TT>
file of sorts) if you do not have the ncSA server. This book deals
with the ncSA server, which pretty much covers most of these variables.
<P>
To make things easier, you probably will not even use most of
the environment variables all the time. The most often used ones
tend to be <TT><FONT FACE="Courier">QUERY_STRING</FONT></TT>,
<TT><FONT FACE="Courier">REQUEST_METHOD</FONT></TT>, and <TT><FONT FACE="Courier">PATH_INFO</FONT></TT>.
However, I cover some of the others just so you are aware of them
and what they do.
<H3><A NAME="CONTENT_LENGTH"><TT><FONT SIZE=4 FACE="Courier">CONTENT_LENGTH</FONT></TT></A>
</H3>