ch20.htm

《Perl 5 Unreleased》

<P>
This variable is set to the number of bytes for the attached data
to a file. If there is no attached data, this is set to <TT><FONT FACE="Courier">NULL</FONT></TT>.
In Perl, this is interpreted as zero. For example, for a string
of <TT><FONT FACE="Courier">&quot;x=10&amp;y=10&quot;</FONT></TT>,
the variable is set as <TT><FONT FACE="Courier">CONTENT_LENGTH=9</FONT></TT>.
<H3><A NAME="CONTENT_TYPE"><TT><FONT SIZE=4 FACE="Courier">CONTENT_TYPE</FONT></TT></A>
</H3>
<P>
The <TT><FONT FACE="Courier">CONTENT_TYPE</FONT></TT> variable
is set to the type of MIME entity (data) being sent to the CGI
script. If there is no data, this variable is set to <TT><FONT FACE="Courier">NULL</FONT></TT>,
as well. The MIME types are defined in HTTP 1.0 (and later versions).
With MIME types you can represent different types of data: video,
audio, images, or just plain text. Each type of data has its own
format: for example, GIF files are in the GIF format, text files
are in ASCII, and so on. For a GIF file, the <TT><FONT FACE="Courier">CONTENT_TYPE</FONT></TT>
variable is set as follows:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">CONTENT_TYPE = image/gif</FONT></TT>
</BLOCKQUOTE>
<P>
A client may specify a list of the types of acceptable media in
its request header. This allows the server some flexibility in
how it returns data. Most types of data are registered with the
Internet Assigned Numbers Authority (IANA). The most common registered
types and subtypes are listed in Table 20.2. Subtypes and types
are not case sensitive-so GIF is equivalent to gif.<BR>
<P>
<CENTER><B>Table 20.2. MIME registered content types used by HTTP.</B></CENTER>
<CENTER>
<TABLE BORDERCOLOR=#000000 BORDER=1 WIDTH=80%>
<TR VALIGN=TOP><TD WIDTH=129><I>Type</I></TD><TD WIDTH=189><I>Subtypes</I>
</TD><TD WIDTH=272><I>Description</I></TD></TR>
<TR VALIGN=TOP><TD WIDTH=129><TT><FONT FACE="Courier">text</FONT></TT></TD>
<TD WIDTH=189><TT><FONT FACE="Courier">plain</FONT></TT></TD>
<TD WIDTH=272>ASCII text information</TD></TR>
<TR VALIGN=TOP><TD WIDTH=129><TT><FONT FACE="Courier">image</FONT></TT></TD>
<TD WIDTH=189><TT><FONT FACE="Courier">jpeg</FONT></TT>, <TT><FONT FACE="Courier">gif</FONT></TT>
</TD><TD WIDTH=272>Supported formats</TD></TR>
<TR VALIGN=TOP><TD WIDTH=129><TT><FONT FACE="Courier">audio</FONT></TT></TD>
<TD WIDTH=189><TT><FONT FACE="Courier">basic</FONT></TT></TD>
<TD WIDTH=272>Audio information (includes <TT><FONT FACE="Courier">.au</FONT></TT> format)
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=129><TT><FONT FACE="Courier">video</FONT></TT></TD>
<TD WIDTH=189><TT><FONT FACE="Courier">mpeg</FONT></TT></TD><TD WIDTH=272>Video data
</TD></TR>
<TR VALIGN=TOP><TD WIDTH=129><TT><FONT FACE="Courier">application</FONT></TT>
</TD><TD WIDTH=189><TT><FONT FACE="Courier">octet-stream</FONT></TT>
</TD><TD WIDTH=272>Application-specific data</TD></TR>
<TR VALIGN=TOP><TD WIDTH=129><TT><FONT FACE="Courier">message</FONT></TT>
</TD><TD WIDTH=189><TT><FONT FACE="Courier">rfc822</FONT></TT>, <TT><FONT FACE="Courier">partial</FONT></TT>,
<BR>
<TT><FONT FACE="Courier">external-body</FONT></TT>
</TD><TD WIDTH=272>An encapsulated message</TD></TR>
<TR VALIGN=TOP><TD WIDTH=129><TT><FONT FACE="Courier">multipart</FONT></TT>
</TD><TD WIDTH=189><TT><FONT FACE="Courier">mixed</FONT></TT>, <TT><FONT FACE="Courier">alternative</FONT></TT>,
<BR>
<TT><FONT FACE="Courier">digest</FONT></TT>, <TT><FONT FACE="Courier">parallel</FONT></TT>
</TD><TD WIDTH=272>Multiple parts of individual data 
<BR>
types
</TD></TR>
</TABLE></CENTER>
<P>
<P>
The types shown in Table 20.2 are by no means complete. Servers
may support more types and subtypes. The application type describes
transmitted application-specific data. This is generally binary
data that is not interpreted by the server. Here is the usual
setting for such data:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">CONTENT_TYPE=application/octet-stream
</FONT></TT>
</BLOCKQUOTE>
<P>
The text type describes textual data. The primary and default
subtype is <TT><FONT FACE="Courier">plain</FONT></TT>. Here is
the general setting for this variable:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">CONTENT_TYPE=text/plain. </FONT></TT>
</BLOCKQUOTE>
<P>
With the introduction of &quot;rich text&quot; as specified by
RFC 1521 it may be necessary to specify the character set being
used. RFC 1521 is the Internet standard for defining internet
MIME formats. For more information on RFC 1521, check out the
HTML page on <TT><A HREF="http://www.cis.ohio-state.edu/htbin/rfc/rfc1521.html" tppabs="http://www.cis.ohio-state.edu/htbin/rfc/rfc1521.html">http://www.cis.ohio-state.edu/htbin/rfc/rfc1521.html</A></TT>.
<P>
Therefore, the setting for sending a plain text file via CGI would
be the following:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">CONTENT_TYPE=text/plain; charset=us-ascii
<BR>
A blank like here is manadatory per standard</FONT></TT>
</BLOCKQUOTE>
<P>
Note that each content type must be followed by a mandatory blank
line as required by HTML/CGI specifications. The image <TT><FONT FACE="Courier">Content-Type</FONT></TT>
can also be used to describe image data. The two well-known image
types are JPEG and GIF. The type of format for a GIF would be
<BLOCKQUOTE>
<TT><FONT FACE="Courier">CONTENT_TYPE=image/gif<BR>
A blank like here is manadatory per standard</FONT></TT>
</BLOCKQUOTE>
<P>
The video <TT><FONT FACE="Courier">Content-Type</FONT></TT> describes
video data in the MPEG format. For audio, the <TT><FONT FACE="Courier">Content-Type</FONT></TT>
would be in the basic format. In extended subtypes, you'll see
an <TT><I><FONT FACE="Courier">x</FONT></I></TT> in front of the
subtype.
<H3><A NAME="GATEWAY_INTERFACE"><TT><FONT SIZE=4 FACE="Courier">GATEWAY_INTERFACE</FONT></TT></A>
</H3>
<P>
This represents the version of the CGI specification to which
the server complies. This variable is set for all HTTP requests.
<H3><A NAME="PATH_INFO"><TT><FONT SIZE=4 FACE="Courier">PATH_INFO</FONT></TT></A>
</H3>
<P>
This variable represents additional path information. It describes
a resource to be returned by the CGI application once it has completed
its execution. The value of the <TT><FONT FACE="Courier">PATH_INFO</FONT></TT>
variable can be a URL, a string provided to the CGI script, or
some other client information. It is up to the handling CGI script
as to how to use this information (if the information is needed).
If this information is a valid URL, the server may interpret the
URL before passing it to the CGI application.
<H3><A NAME="QUERY_STRING"><TT><FONT SIZE=4 FACE="Courier">QUERY_STRING</FONT></TT></A>
</H3>
<P>
The <TT><FONT FACE="Courier">QUERY_STRING</FONT></TT> variable
is defined as anything that follows the first question mark (<TT><FONT FACE="Courier">?</FONT></TT>)
in a URL. This information can be added either by an <TT><FONT FACE="Courier">ISINDEX</FONT></TT>
document or an HTML form (with the <TT><FONT FACE="Courier">GET</FONT></TT>
action). This string is encoded in the standard URL format of
changing spaces to <TT><FONT FACE="Courier">+</FONT></TT>, individual
assignments separated by ampersands and encoding special characters
with <TT><FONT FACE="Courier">%XX</FONT></TT> hexadecimal encoding.
You will need to decode the value of <TT><FONT FACE="Courier">QUERY_STRING</FONT></TT>
before you can use it.
<P>
Assignments to values in an HTML <TT><FONT FACE="Courier">FORM</FONT></TT>
are done in the form <TT><FONT FACE="Courier">x=value</FONT></TT>.
Spaces are converted into plus (<TT><FONT FACE="Courier">+</FONT></TT>)
signs. So an assignment of the form <TT><FONT FACE="Courier">x=hello
world</FONT></TT>, will be converted to <TT><FONT FACE="Courier">x=hello+world</FONT></TT>.
<P>
Individual assignments are separated by ampersands (<TT><FONT FACE="Courier">&amp;</FONT></TT>).
The equal (<TT><FONT FACE="Courier">=</FONT></TT>) sign, the plus
(<TT><FONT FACE="Courier">+</FONT></TT>) sign, and the ampersand
(<TT><FONT FACE="Courier">&amp;</FONT></TT>) may only be included
as encoded values (by using the <TT><FONT FACE="Courier">#</FONT></TT>
operator, for example). Therefore, these assignments, <TT><FONT FACE="Courier">x=&quot;hello
world&quot;</FONT></TT>, <TT><FONT FACE="Courier">&quot;a=2&quot;</FONT></TT>
and <TT><FONT FACE="Courier">&quot;y=I am here&quot;</FONT></TT>,
are encoded as this:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">x=hello+world&amp;a=2&amp;y=I+am+here</FONT></TT>
</BLOCKQUOTE>
<H2><A NAME="InputandOutputtoCGIScripts"><FONT SIZE=5 COLOR=#FF0000>Input
and Output to CGI Scripts</FONT></A></H2>
<P>
The server is responsible for packing the data and setting the
environment variables before running the CGI script. Information
being passed to the CGI script can be passed in one of two ways:
as part of <TT><FONT FACE="Courier">STDIN</FONT></TT> (the Perl
handle for <TT><FONT FACE="Courier">standard input</FONT></TT>)
or by setting the value in <TT><FONT FACE="Courier">QUERY_STRING</FONT></TT>.
The results from the execution are sent back from the CGI script
to <TT><FONT FACE="Courier">STDOUT</FONT></TT> (the default output
file handle for Perl).
<P>
When data is passed in via <TT><FONT FACE="Courier">STDIN</FONT></TT>,
the <TT><FONT FACE="Courier">CONTENT_LENGTH</FONT></TT> and <TT><FONT FACE="Courier">CONTENT_TYPE</FONT></TT>
variables are set to reflect the length and type of data, respectively.
This kind of input is the result of the <TT><FONT FACE="Courier">POST</FONT></TT>
method at the client. For the <TT><FONT FACE="Courier">GET</FONT></TT>
method of requesting data, the variable <TT><FONT FACE="Courier">QUERY_STRING</FONT></TT>
is set to the values.
<P>
Incoming strings take the form of an input string. Assignments
to values are done in the form <TT><FONT FACE="Courier">x=value</FONT></TT>.
Spaces are converted into plus (<TT><FONT FACE="Courier">+</FONT></TT>)
signs. Individual assignments are separated by ampersands (<TT><FONT FACE="Courier">&amp;</FONT></TT>).
The equal (<TT><FONT FACE="Courier">=</FONT></TT>) sign, the plus
(<TT><FONT FACE="Courier">+</FONT></TT>) sign, and the ampersand
(<TT><FONT FACE="Courier">&amp;</FONT></TT>) may only be included
as encoded values (by using the <TT><FONT FACE="Courier">#</FONT></TT>
operator, for example). Therefore, two assignments, <TT><FONT FACE="Courier">x=1</FONT></TT>
and <TT><FONT FACE="Courier">&quot;y=42 and 32&quot;</FONT></TT>,
are encoded as this:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">x=1&amp;y=42+and+32</FONT></TT>
</BLOCKQUOTE>
<P>
There is a method to send data to a CGI script with the command
line, provided you have the support in the server and your data
traffic is not large. Command-line interfaces tend to be restricted
by the number of bytes available for the interface. The method
of passing data via the environment variables is considered safer
and is the preferred way of passing data.
<P>
A CGI script must always return something back to the client.
This is a requirement; otherwise, the client at the other end
might hang for a long time. The standard output from the CGI program
is the output that the script writes to <TT><FONT FACE="Courier">STDOUT</FONT></TT>.
Output is returned in one of two ways: a nonparsed header output
or a parsed header output. In the nonparsed header output, a complete
HTTP message is sent back. In the parsed header output, an HTML
header and the body of a message is sent with another URL. The
latter method is the preferred way of sending data back from a
server to a browser.
<P>
CGI programs can return a number of document types back to the
client. The CGI standard specifies what format of data to expect
at the server via the MIME header. The most common MIME types
are <TT><FONT FACE="Courier">text</FONT></TT>/<TT><FONT FACE="Courier">html</FONT></TT>
for HTML, and <TT><FONT FACE="Courier">text</FONT></TT>/<TT><FONT FACE="Courier">plain</FONT></TT>
for straight ASCII text.
<P>
For example, to send back HTML to the client, your output should
look like the example shown here:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&nbsp;&nbsp;&nbsp;Content-type: text/html
<BR>
<BR>
&nbsp;&nbsp;&nbsp;&lt;HTML&gt;&lt;HEAD&gt;<BR>
&nbsp;&nbsp;&nbsp;&lt;TITLE&gt;HTML Output from test CGI script&lt;/TITLE&gt;
<BR>
&nbsp;&nbsp;&nbsp;&lt;/HEAD&gt;&lt;BODY&gt;<BR>
&nbsp;&nbsp;&nbsp;&lt;H1&gt;Test output&lt;/H1&gt;<BR>
&lt;P&gt;<BR>
&nbsp;&nbsp;&nbsp;&nbsp; Body of text<BR>
&lt;P&gt;<BR>
&nbsp;&nbsp;&nbsp;&lt;/BODY&gt;&lt;/HTML&gt;</FONT></TT>
</BLOCKQUOTE>
<P>
Let's look a test script to see how an HTML file can be sent back.
<H2><A NAME="ATestCGIScript"><FONT SIZE=5 COLOR=#FF0000>A Test
CGI Script</FONT></A></H2>
<P>
The CGI script in Listing 20.8 shows how to display information
about the environment variables in use. The best way to learn
is by example-and this sample script will show you how to write
a very basic CGI script in Perl.
<HR>
<BLOCKQUOTE>
<B>Listing 20.8. A sample test script.<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&nbsp;1 #!/usr/bin/perl<BR>
&nbsp;2 #&nbsp;&nbsp;A very common echo script on just about every
server<BR>
&nbsp;3 $| = 1;<BR>
&nbsp;4 print &quot;Content-type: text/plain\n\n&quot;;<BR>
&nbsp;5 print &quot;CGI/1.0 t