<LI><A HREF="#creating a new query object (objectoriented style):">CREATING A NEW QUERY OBJECT (OBJECT-ORIENTED STYLE):</A></LI>
<LI><A HREF="#creating a new query object from an input file">CREATING A NEW QUERY OBJECT FROM AN INPUT FILE</A></LI>
<LI><A HREF="#fetching a list of keywords from the query:">FETCHING A LIST OF KEYWORDS FROM THE QUERY:</A></LI>
<LI><A HREF="#fetching the names of all the parameters passed to your script:">FETCHING THE NAMES OF ALL THE PARAMETERS PASSED TO YOUR SCRIPT:</A></LI>
<LI><A HREF="#fetching the value or values of a single named parameter:">FETCHING THE VALUE OR VALUES OF A SINGLE NAMED PARAMETER:</A></LI>
<LI><A HREF="#setting the value(s) of a named parameter:">SETTING THE <CODE>VALUE(S)</CODE> OF A NAMED PARAMETER:</A></LI>
<LI><A HREF="#appending additional values to a named parameter:">APPENDING ADDITIONAL VALUES TO A NAMED PARAMETER:</A></LI>
<LI><A HREF="#importing all parameters into a namespace:">IMPORTING ALL PARAMETERS INTO A NAMESPACE:</A></LI>
<LI><A HREF="#deleting a parameter completely:">DELETING A PARAMETER COMPLETELY:</A></LI>
<LI><A HREF="#deleting all parameters:">DELETING ALL PARAMETERS:</A></LI>
<LI><A HREF="#direct access to the parameter list:">DIRECT ACCESS TO THE PARAMETER LIST:</A></LI>
<LI><A HREF="#fetching the parameter list as a hash:">FETCHING THE PARAMETER LIST AS A HASH:</A></LI>
<LI><A HREF="#saving the state of the script to a file:">SAVING THE STATE OF THE SCRIPT TO A FILE:</A></LI>
<LI><A HREF="#creating a standard http header:">CREATING A STANDARD HTTP HEADER:</A></LI>
<LI><A HREF="#generating a redirection header">GENERATING A REDIRECTION HEADER</A></LI>
<LI><A HREF="#creating the html document header">CREATING THE HTML DOCUMENT HEADER</A></LI>
<LI><A HREF="#ending the html document:">ENDING THE HTML DOCUMENT:</A></LI>
<LI><A HREF="#creating a selfreferencing url that preserves state information:">CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:</A></LI>
<LI><A HREF="#obtaining the script's url">OBTAINING THE SCRIPT'S URL</A></LI>
<LI><A HREF="#mixing post and url parameters">MIXING POST AND URL PARAMETERS</A></LI>
</UL>
<LI><A HREF="#creating standard html elements:">CREATING STANDARD HTML ELEMENTS:</A></LI>
<UL>
<LI><A HREF="#providing arguments to html shortcuts">PROVIDING ARGUMENTS TO HTML SHORTCUTS</A></LI>
<LI><A HREF="#the distributive property of html shortcuts">THE DISTRIBUTIVE PROPERTY OF HTML SHORTCUTS</A></LI>
<LI><A HREF="#html shortcuts and list interpolation">HTML SHORTCUTS AND LIST INTERPOLATION</A></LI>
<LI><A HREF="#nonstandard html shortcuts">NON-STANDARD HTML SHORTCUTS</A></LI>
Any other parameters you want to include in the <BODY> tag. This is a good
place to put Netscape extensions, such as colors and wallpaper patterns.
<P></P></DL>
<P>
<H2><A NAME="ending the html document:">ENDING THE HTML DOCUMENT:</A></H2>
<PRE>
print $query->end_html</PRE>
<P>This ends an HTML document by printing the </BODY></HTML> tags.</P>
<P>
<H2><A NAME="creating a selfreferencing url that preserves state information:">CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:</A></H2>
<PRE>
$myself = $query->self_url;
print "<A HREF=$myself>I'm talking to myself.</A>";</PRE>
<P><CODE>self_url()</CODE> will return a URL, that, when selected, will reinvoke
this script with all its state information intact. This is most
useful when you want to jump around within the document using
internal anchors but you don't want to disrupt the current contents
of the form(s). Something like this will do the trick.</P>
<PRE>
$myself = $query->self_url;
print "<A HREF=$myself#table1>See table 1</A>";
print "<A HREF=$myself#table2>See table 2</A>";
print "<A HREF=$myself#yourself>See for yourself</A>";</PRE>
<P>If you want more control over what's returned, using the <STRONG>url()</STRONG>
method instead.</P>
<P>You can also retrieve the unprocessed query string with query_string():</P>
<PRE>
$the_string = $query->query_string;</PRE>
<P>
<H2><A NAME="obtaining the script's url">OBTAINING THE SCRIPT'S URL</A></H2>
<LI><STRONG><A NAME="item_Specify_the_destination_for_the_document_in_the_HT">Specify the destination for the document in the HTTP header</A></STRONG><BR>
You may provide a <STRONG>-target</STRONG> parameter to the <A HREF="#item_header"><CODE>header()</CODE></A> method:
<PRE>
print $q->header(-target=>'ResultsWindow');</PRE>
<P>This will tell the browser to load the output of your script into the
frame named ``ResultsWindow''. If a frame of that name doesn't already
exist, the browser will pop up a new window and load your script's
document into that. There are a number of magic names that you can
use for targets. See the frame documents on Netscape's home pages for
details.</P>
<P></P>
<LI><STRONG><A NAME="item_Specify_the_destination_for_the_document_in_the_%3">Specify the destination for the document in the <FORM> tag</A></STRONG><BR>
You can specify the frame to load in the FORM tag itself. With
<P>NPH, or ``no-parsed-header'', scripts bypass the server completely by
sending the complete HTTP header directly to the browser. This has
slight performance benefits, but is of most use for taking advantage
of HTTP extensions that are not directly supported by your server,
such as server push and PICS headers.</P>
<P>Servers use a variety of conventions for designating CGI scripts as
NPH. Many Unix servers look at the beginning of the script's name for
the prefix ``nph-''. The Macintosh WebSTAR server and Microsoft's
Internet Information Server, in contrast, try to decide whether a
program is an NPH script by examining the first line of script output.</P>
<P>CGI.pm supports NPH scripts with a special NPH mode. When in this
mode, CGI.pm will output the necessary extra header information when
the <A HREF="#item_header"><CODE>header()</CODE></A> and <CODE>redirect()</CODE> methods are
called.</P>
<P>The Microsoft Internet Information Server requires NPH mode. As of version
2.30, CGI.pm will automatically detect when the script is running under IIS
and put itself into this mode. You do not need to do this manually, although
it won't hurt anything if you do.</P>
<P>There are a number of ways to put CGI.pm into NPH mode:</P>
<DL>
<DT><STRONG><A NAME="item_In_the_use_statement">In the <STRONG>use</STRONG> statement</A></STRONG><BR>
<DD>
Simply add the ``-nph'' pragmato the list of symbols to be imported into
your script:
<PRE>
use CGI qw(:standard -nph)</PRE>
<P></P>
<DT><STRONG><A NAME="item_nph">By calling the <STRONG>nph()</STRONG> method:</A></STRONG><BR>
<DD>
Call <STRONG>nph()</STRONG> with a non-zero parameter at any point after using CGI.pm in your program.
<PRE>
CGI->nph(1)</PRE>
<P></P>
<DT><STRONG><A NAME="item_header">By using <STRONG>-nph</STRONG> parameters in the <STRONG>header()</STRONG> and <STRONG>redirect()</STRONG> statements:</A></STRONG><BR>
<DD>
<PRE>
print $q->header(-nph=>1);</PRE>
</DL>
<P>
<HR>
<H1><A NAME="server push">Server Push</A></H1>
<P>CGI.pm provides three simple functions for producing multipart
documents of the type needed to implement server push. These
functions were graciously provided by Ed Jordan <<A HREF="mailto:ed@fidalgo.net">ed@fidalgo.net</A>>. To
import these into your namespace, you must import the ``:push'' set.
You are also advised to put the script into NPH mode and to set $| to
1 to avoid buffering problems.</P>
<P>Here is a simple script that demonstrates server push:</P>
<PRE>
#!/usr/local/bin/perl
use CGI qw/:push -nph/;
$| = 1;
print multipart_init(-boundary=>'----------------here we go!');
while (1) {
print multipart_start(-type=>'text/plain'),
"The current time is ",scalar(localtime),"\n",
multipart_end;
sleep 1;
}</PRE>
<P>This script initializes server push by calling <STRONG>multipart_init()</STRONG>.
It then enters an infinite loop in which it begins a new multipart
section by calling <STRONG>multipart_start()</STRONG>, prints the current local time,
and ends a multipart section with <STRONG>multipart_end()</STRONG>. It then sleeps
