ch8.htm

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

<HR>
<BLOCKQUOTE>
<B>Listing 8.5. Comments form.<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&lt;FORM ACTION=&quot;comments.cgi&quot;
METHOD=POST&gt;<BR>
&lt;P&gt; In order that we may continue to provide a high quality
World Wide Web service,<BR>
please take the time to fill in this form.&lt;/P&gt;<BR>
&lt;DL&gt;<BR>
&lt;DT&gt;Your surname (family name):<BR>
&lt;DD&gt;&lt;INPUT NAME=&quot;surname&quot; SIZE=20 MAXLENGTH=60&gt;
<BR>
&lt;DT&gt;Your first name (given name):<BR>
&lt;DD&gt;&lt;INPUT NAME=&quot;forename&quot; SIZE=20 MAXLENGTH=60&gt;
<BR>
&lt;/DL&gt;<BR>
&lt;P&gt;Your title:<BR>
[&lt;INPUT TYPE=RADIO NAME=&quot;title&quot; VALUE=&quot;Mr&quot;&gt;
Mr.] <BR>
[&lt;INPUT TYPE=RADIO NAME=&quot;title&quot; VALUE=&quot;Ms&quot;&gt;
Ms.] <BR>
[&lt;INPUT TYPE=RADIO NAME=&quot;title&quot; VALUE=&quot;Mrs&quot;&gt;
Mrs.] <BR>
[&lt;INPUT TYPE=RADIO NAME=&quot;title&quot; VALUE=&quot;Miss&quot;&gt;
Miss.] <BR>
[&lt;INPUT TYPE=RADIO NAME=&quot;title&quot; VALUE=&quot;Dr&quot;&gt;
Dr.] <BR>
[&lt;INPUT TYPE=RADIO NAME=&quot;title&quot; VALUE=&quot;&quot;&gt;
Other.] &lt;/P&gt;<BR>
&lt;P&gt; Please tell us what you thought of this Web site. Select
the checkboxes which you agree with: &lt;/P&gt;<BR>
&lt;UL&gt;<BR>
&lt;LI&gt;&lt;INPUT TYPE=chECKBOX NAME=&quot;opinion&quot; VALUE=&quot;understandable&quot;&gt;
<BR>
The text was understandable.<BR>
&lt;LI&gt;&lt;INPUT TYPE=chECKBOX NAME=&quot;opinion&quot; VALUE=&quot;navigable&quot;&gt;
<BR>
I found it easy to find my way through the Web site. <BR>
&lt;LI&gt;&lt;INPUT TYPE=chECKBOX NAME=&quot;opinion&quot; VALUE=&quot;stylish&quot;&gt;
<BR>
I was impressed by the style and presentation.<BR>
&lt;/UL&gt;<BR>
&lt;P&gt; &lt;INPUT TYPE=&quot;HIDDEN&quot; NAME=&quot;pages&quot;
VALUE=&quot;brochure&quot;&gt;<BR>
Please add any other comments:<BR>
&lt;TEXTAREA NAME=&quot;feedback&quot; ROWS=5 COLS=40&gt;<BR>
I think your brochure is:<BR>
&lt;/TEXTAREA&gt; <BR>
&lt;/P&gt;<BR>
&lt;P&gt; &lt;INPUT TYPE=SUBMIT VALUE=&quot;Send comments&quot;&gt;
<BR>
&lt;INPUT TYPE=RESET VALUE=&quot;Clear form&quot;&gt; &lt;/P</FONT></TT>&gt;
<BR>
<TT><FONT FACE="Courier">&lt;/FORM&gt;</FONT></TT>
</BLOCKQUOTE>
<HR>
<P>
Other sample forms can be found at Web sites all over the world.
Simply use the &quot;View Source&quot; facility of your browser
to see the HTML tags that make up a form you find.
<H2><A NAME="HandlingFormSubmissions"><FONT SIZE=5 COLOR=#FF0000>Handling
Form Submissions</FONT></A></H2>
<P>
Handling Web form data submissions using CGI can be conveniently
divided in to two procedures. First, the CGI program must accept
the submitted form data from the Web server (the HTTP server).
The algorithm for this procedure depends on the choice of submission
method. In CGI, the submission method is given by the environment
variable <TT><FONT FACE="Courier">REQUEST_TYPE</FONT></TT> and
will be either <TT><FONT FACE="Courier">GET</FONT></TT> or <TT><FONT FACE="Courier">POST</FONT></TT>.
Second, the CGI program must decode the submitted data before
it can be used by other procedures.
<H3><A NAME="REQUEST_TYPEsGETversusPOST"><TT><FONT SIZE=4 FACE="Courier">REQUEST_TYPE</FONT></TT><FONT SIZE=4>s
</FONT><TT><FONT SIZE=4 FACE="Courier">GET</FONT></TT><FONT SIZE=4>
versus </FONT><TT><FONT SIZE=4 FACE="Courier">POST</FONT></TT></A>
</H3>
<P>
The names of the two <TT><FONT FACE="Courier">REQUEST_TYPE</FONT></TT>s
<TT><FONT FACE="Courier">GET</FONT></TT> and <TT><FONT FACE="Courier">POST</FONT></TT>
correspond to the HTTP mechanism used in each case. They have
different characteristics and so need different treatment.
<H4>Differences between <TT><FONT FACE="Courier">GET</FONT></TT>
and <TT><FONT FACE="Courier">POST</FONT></TT></H4>
<P>
A <TT><FONT FACE="Courier">GET</FONT></TT> form submission is
performed by fetching a URL made up of
<UL>
<LI><FONT COLOR=#000000>The location of the CGI form handler program</FONT>
<LI><FONT COLOR=#000000>Followed by a question mark (</FONT><TT><FONT FACE="Courier">&quot;?&quot;</FONT></TT>)
<LI><FONT COLOR=#000000>Followed by the form data encoded as described
in the section &quot;Decoding </FONT><TT><FONT FACE="Courier">+</FONT></TT>
and <TT><FONT FACE="Courier">%<I>hh</I></FONT></TT> (URL-Encoding)&quot;
</UL>
<P>
For example, the default values in the form in Listing 8.4 might
be submitted as a <TT><FONT FACE="Courier">GET </FONT></TT>of
the<TT><FONT FACE="Courier"> </FONT></TT>URL
<BLOCKQUOTE>
<TT><FONT FACE="Courier"><A HREF="http://www.site.com/cgi-bin/select.cgi?package=text&amp;coords=19,11">http://www.site.com/cgi-bin/select.cgi?package=text&amp;coords=19,11</A></FONT></TT>
</BLOCKQUOTE>
<P>
Because the form data is included as part of the URL in a &quot;<TT><FONT FACE="Courier">GET</FONT></TT>&quot;
request, the reply to the form submission is likely to be remembered
by caching browsers and caching HTTP proxy servers. For this reason,
it is advisable to use <TT><FONT FACE="Courier">GET</FONT></TT>
as the <TT><FONT FACE="Courier">METHOD</FONT></TT> attribute of
forms that always yield the same result for the same input and
that have no side effects, such as index search forms.
<P>
A <TT><FONT FACE="Courier">POST</FONT></TT> form submission is
performed by sending the form data encoded as described in the
section &quot;Decoding <TT><FONT FACE="Courier">+</FONT></TT>
and <TT><FONT FACE="Courier">%<I>hh</I></FONT></TT> (URL-Encoding)&quot;
as a document with the HTTP header
<BLOCKQUOTE>
<TT><FONT FACE="Courier">Content-type: application/x-www-form-urlencoded</FONT></TT>
</BLOCKQUOTE>
<P>
to the server giving the location of the CGI form handler program
as the URL.
<P>
For example, a submission from the form in Listing 8.1 might reach
the Web server as this HTTP transaction:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">POST http://www.site.com HTTP/1.0<BR>
User-agent: Pip/2.53<BR>
Content-type: application/x-www-form-urlencoded <BR>
Content-length: 50<BR>
<BR>
fullname=Charles+Dickens&amp;email=dickens%40literary.org.uk</FONT></TT>
</BLOCKQUOTE>
<P>
Because this operation is easily distinguished from an ordinary
URL fetch and the form data is in an attached document rather
than part of the URL, this sort of request is rarely remembered
by caching proxy servers. <TT><FONT FACE="Courier">POST</FONT></TT>
should be used as the <TT><FONT FACE="Courier">METHOD</FONT></TT>
attribute of forms that are intended to have a useful side effect
every time they are submitted, or that can produce different results
for the same input.
<H4>Accepting <TT><FONT FACE="Courier">GET</FONT></TT> Type Requests
</H4>
<P>
From within a CGI program, form data submitted with the <TT><FONT FACE="Courier">FORM</FONT></TT>
<TT><FONT FACE="Courier">METHOD</FONT></TT> attribute <TT><FONT FACE="Courier">GET</FONT></TT>
is encoded in the environment variable <TT><FONT FACE="Courier">QUERY_STRING</FONT></TT>.
From a C program, this could be referenced by using a call to
the <TT><FONT FACE="Courier">getenv</FONT></TT> library routine,
as shown in Listing 8.6.
<HR>
<BLOCKQUOTE>
<B>Listing 8.6. CGI environment variables in C.<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">encodedQuery=getenv(&quot;QUERY_STRING&quot;);</FONT></TT>
</BLOCKQUOTE>
<HR>
<P>
In a Perl script, it is available in the <TT><FONT FACE="Courier">%ENV</FONT></TT>
associative array:
<BLOCKQUOTE>
<TT><FONT FACE="Courier">$encodedQuery=$ENV{&quot;QUERY_STRING&quot;};</FONT></TT>
</BLOCKQUOTE>
<P>
Because the form data is submitted in an environment variable
by way of a URL, <TT><FONT FACE="Courier">GET</FONT></TT> form
submissions are subject to smaller system defined size limits.
The <TT><FONT FACE="Courier">GET</FONT></TT> method should not
be used for forms where the expected data will be very large.
<H4>Accepting <TT><FONT FACE="Courier">POST</FONT></TT> Type Requests
</H4>
<P>
From the point of view of a CGI program, form data submitted with
the <TT><FONT FACE="Courier">POST</FONT></TT> method is an encoded
stream of characters in the standard input of the program. If
a Content-length: header was supplied by the form browser, the
number of characters that need to be read from the standard input
is available to the CGI program in the <TT><FONT FACE="Courier">CONTENT_LENGTH</FONT></TT>
environment variable. No more than <TT><FONT FACE="Courier">CONTENT_LENGTH</FONT></TT>
characters should be read in. In the event that there is no <TT><FONT FACE="Courier">CONTENT_LENGTH</FONT></TT>
environment variable, the CGI program should read characters from
standard input until an &quot;end-of-file&quot; or other exception
occurs. In a Perl script, <TT><FONT FACE="Courier">POST</FONT></TT>ed
form data would be retrieved with a procedure similar to Listing
8.7.
<HR>
<BLOCKQUOTE>
<B>Listing 8.7. Accepting <FONT SIZE=2 FACE="MCPdigital-B">POST</FONT>
type requests in Perl.<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">$encodedQuery=&quot;&quot;;&nbsp;&nbsp;&nbsp;&nbsp;#
The encoded form data will be appended to this string<BR>
$charsRemaining=65536;&nbsp;&nbsp;&nbsp;&nbsp;# This CGI program
will truncate the encoded form data after 64Kbytes<BR>
&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;#
unless the Content-length: is specified.<BR>
$charsRemaining=$ENV{&quot;CONTENT_LENGTH} if $ENV{&quot;CONTENT_LENGTH&quot;};
<BR>
while ($charsRemaining--) {<BR>
&nbsp;&nbsp;&nbsp;&nbsp;$encodedQuery.=getc;<BR>
}</FONT></TT>
</BLOCKQUOTE>
<HR>
<H4>Accepting <TT><FONT FACE="Courier">ISINDEX</FONT></TT> Requests
</H4>
<P>
Although not strictly forms, queries from <TT><FONT FACE="Courier">&lt;ISINDEX&gt;</FONT></TT>
Web pages behave very similarly to <TT><FONT FACE="Courier">FORM
METHOD=GET</FONT></TT> submissions. The only difference is that
the &quot;Separating data from different form components&quot;
step of the form data decoding procedure is not required.
<H3><A NAME="FormDataDecoding">Form Data Decoding</A></H3>
<P>
Form submissions, whether they are sent using <TT><FONT FACE="Courier">GET</FONT></TT>
or <TT><FONT FACE="Courier">POST</FONT></TT>, have the same encoding
and can be unpacked using the same procedures.
<H4>Separating Data from Different Form Components</H4>
<P>
Except in the case of <TT><FONT FACE="Courier">&lt;ISINDEX&gt;</FONT></TT>
queries, the encoded submission is made up of pairs of input component
<TT><FONT FACE="Courier">NAME</FONT></TT> with input component
contents joined by an equal sign (<TT><FONT FACE="Courier">=</FONT></TT>)
and delimited by ampersands (<TT><FONT FACE="Courier">&amp;</FONT></TT>).
For example, the default contents of the form in Listing 8.8 would
be encoded as shown.
<BLOCKQUOTE>
<TT><FONT FACE="Courier">comments=None&amp;choice=Good&amp;where=HomePage</FONT></TT>
</BLOCKQUOTE>
<HR>
<BLOCKQUOTE>
<B>Listing 8.8. Separating data from different form components
in Perl.<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">&lt;FORM ACTION=&quot;test.cgi&quot;
METHOD=POST&gt;<BR>
&lt;P&gt;Comments: &lt;TEXTAREA NAME=&quot;comments&quot; ROWS=3
COLS=40&gt;None&lt;/TEXTAREA&gt;&lt;/P&gt;<BR>
&lt;SELECT NAME=&quot;choice&quot; SIZE=4&gt;<BR>
&lt;OPTION&gt;Excellent<BR>
&lt;OPTION SELECTED&gt;Good<BR>
&lt;OPTION&gt;Average<BR>
&lt;OPTION&gt;Poor<BR>
&lt;/SELECT&gt;<BR>
&lt;INPUT TYPE=HIDDEN NAME=&quot;where&quot; VALUE=&quot;HomePage&quot;&gt;
<BR>
&lt;/FORM&gt;</FONT></TT>
</BLOCKQUOTE>
<HR>
<P>
The Perl procedure in Listing 8.9 will fill an associative array
with the contents of each form component listed by the form component
<TT><FONT FACE="Courier">NAME</FONT></TT> attribute.
<HR>
<BLOCKQUOTE>
<B>Listing 8.9. Filling a Perl associative array with form data.
<BR>
</B>
</BLOCKQUOTE>
<BLOCKQUOTE>
<TT><FONT FACE="Courier">foreach (split(&quot;&amp;&quot;, $encodedQuery))
{<BR>
&nbsp;&nbsp;&nbsp;&nbsp;($name,$contents) = split(&quot;=&quot;);
<BR>
&nbsp;&nbsp;&nbsp;&nbsp;$encodedForm{$name}=$contents;<BR>
}</FONT></TT>
</BLOCKQUOTE>
<HR>