Framework - Cyclone3

Can't convert this docbook content

<article>
<title>CGI - Handle Common Gateway Interface requests and responses</title>
   <section id="ID-dce27bc02e24a4e689cecd01f0adfaff"><title>SYNOPSIS</title>
      <screen><![CDATA[use CGI;

my $q = CGI->new;

# Process an HTTP request
 @values  = $q->param('form_field');

$fh      = $q->upload('file_field');

$riddle  = $query->cookie('riddle_name');
%answers = $query->cookie('answers');

# Prepare various HTTP responses
print $q->header();
print $q->header('application/json');

$cookie1 = $q->cookie(-name=>'riddle_name', -value=>"The Sphynx's Question");
    $cookie2 = $q->cookie(-name=>'answers', -value=>\%answers);
print $q->header(
    -type    => 'image/gif',
    -expires => '+3d',
    -cookie  => [$cookie1,$cookie2]
    );

print  $q->redirect('http://somewhere.else/in/movie/land');]]></screen>
   </section>
   <section id="ID-b302a83ae3073272dcfe7a6e7ce412d5"><title>DESCRIPTION</title>
      <para>
	 CGI.pm is a stable, complete and mature solution for processing
	 and preparing HTTP requests and responses.  Major features
	 including processing form submissions, file uploads, reading and
	 writing cookies, query string generation and manipulation, and
	 processing and preparing HTTP headers. Some HTML generation
	 utilities are included as well.
      </para>
      <para>
	 CGI.pm performs very well in in a vanilla CGI.pm environment and
	 also comes with built-in support for mod_perl and mod_perl2 as
	 well as FastCGI.
      </para>
      <para>
	 It has the benefit of having developed and refined over 10 years
	 with input from dozens of contributors and being deployed on
	 thousands of websites. CGI.pm has been included in the Perl
	 distribution since Perl 5.4, and has become a de-facto standard.
      </para>
      <section id="ID-1b0702aeb85dd25651c1a1bc600556a5"><title>PROGRAMMING STYLE</title>
         <para>
	    There are two styles of programming with CGI.pm, an
	    object-oriented style and a function-oriented style.  In the
	    object-oriented style you create one or more CGI objects and
	    then use object methods to create the various elements of the
	    page.  Each CGI object starts out with the list of named
	    parameters that were passed to your CGI script by the server. 
	    You can modify the objects, save them to a file or database and
	    recreate them.  Because each object corresponds to the <quote>state</quote>
	    of the CGI script, and because each object's parameter list is
	    independent of the others, this allows you to save the state of
	    the script and restore it later.
         </para>
         <para>
	    For example, using the object oriented style, here is how you
	    create a simple <quote>Hello World</quote> HTML page:
         </para>
         <screen><![CDATA[#!/usr/local/bin/perl -w
use CGI;                             # load CGI routines
$q = CGI->new;                        # create new CGI object
print $q->header,                    # create the HTTP header
      $q->start_html('hello world'), # start the HTML
      $q->h1('hello world'),         # level 1 header
      $q->end_html;                  # end the HTML]]></screen>
         <para>
	    In the function-oriented style, there is one default CGI object
	    that you rarely deal with directly.  Instead you just call
	    functions to retrieve CGI parameters, create HTML tags, manage
	    cookies, and so on.  This provides you with a cleaner
	    programming interface, but limits you to using one CGI object
	    at a time.	The following example prints the same page, but
	    uses the function-oriented interface. The main differences are
	    that we now need to import a set of functions into our name
	    space (usually the <quote>standard</quote> functions), and we don't need to
	    create the CGI object.
         </para>
         <screen><![CDATA[#!/usr/local/bin/perl
use CGI qw/:standard/;           # load standard CGI routines
print header,                    # create the HTTP header
      start_html('hello world'), # start the HTML
      h1('hello world'),         # level 1 header
      end_html;                  # end the HTML]]></screen>
         <para>
	    The examples in this document mainly use the object-oriented
	    style. See HOW TO IMPORT FUNCTIONS for important information on
	    function-oriented programming in CGI.pm
         </para>
      </section>
      <section id="ID-a7f07340f856a1b43728fe843c646026"><title>CALLING CGI.PM ROUTINES</title>
         <para>
	    Most CGI.pm routines accept several arguments, sometimes as
	    many as 20 optional ones!  To simplify this interface, all
	    routines use a named argument calling style that looks like
	    this:
         </para>
         <screen><![CDATA[print $q->header(-type=>'image/gif',-expires=>'+3d');]]></screen>
         <para>
	    Each argument name is preceded by a dash.  Neither case nor
	    order matters in the argument list.  -type, -Type, and -TYPE
	    are all acceptable.  In fact, only the first argument needs to
	    begin with a dash.	If a dash is present in the first argument,
	    CGI.pm assumes dashes for the subsequent ones.
         </para>
         <para>
	    Several routines are commonly called with just one argument. 
	    In the case of these routines you can provide the single
	    argument without an argument name.	header() happens to be one
	    of these routines.	In this case, the single argument is the
	    document type.
         </para>
         <screen><![CDATA[print $q->header('text/html');]]></screen>
         <para>
	    Other such routines are documented below.
         </para>
         <para>
	    Sometimes named arguments expect a scalar, sometimes a
	    reference to an array, and sometimes a reference to a hash. 
	    Often, you can pass any type of argument and the routine will
	    do whatever is most appropriate. For example, the param()
	    routine is used to set a CGI parameter to a single or a
	    multi-valued value.  The two cases are shown below:
         </para>
         <screen><![CDATA[$q->param(-name=>'veggie',-value=>'tomato');
$q->param(-name=>'veggie',-value=>['tomato','tomahto','potato','potahto']);]]></screen>
         <para>
	    A large number of routines in CGI.pm actually aren't
	    specifically defined in the module, but are generated
	    automatically as needed. These are the <quote>HTML shortcuts,</quote>
	    routines that generate HTML tags for use in
	    dynamically-generated pages.  HTML tags have both attributes
	    (the attribute=<quote>value</quote> pairs within the tag itself) and
	    contents (the part between the opening and closing pairs.)	To
	    distinguish between attributes and contents, CGI.pm uses the
	    convention of passing HTML attributes as a hash reference as
	    the first argument, and the contents, if any, as any subsequent
	    arguments.	It works out like this:
         </para>
         <screen><![CDATA[Code                           Generated HTML
----                           --------------
h1()                           <h1>
h1('some','contents');         <h1>some contents</h1>
h1({-align=>left});            <h1 align="LEFT">
h1({-align=>left},'contents'); <h1 align="LEFT">contents</h1>]]></screen>
         <para>
	    HTML tags are described in more detail later.
         </para>
         <para>
	    Many newcomers to CGI.pm are puzzled by the difference between
	    the calling conventions for the HTML shortcuts, which require
	    curly braces around the HTML tag attributes, and the calling
	    conventions for other routines, which manage to generate
	    attributes without the curly brackets.  Don't be confused.	As
	    a convenience the curly braces are optional in all but the HTML
	    shortcuts.	If you like, you can use curly braces when calling
	    any routine that takes named arguments.  For example:
         </para>
         <screen><![CDATA[print $q->header( {-type=>'image/gif',-expires=>'+3d'} );]]></screen>
         <para>
	    If you use the <emphasis role="bold">-w</emphasis> switch, you
	    will be warned that some CGI.pm argument names conflict with
	    built-in Perl functions.  The most frequent of these is the
	    -values argument, used to create multi-valued menus, radio
	    button clusters and the like.  To get around this warning, you
	    have several choices:
         </para>
         <para>
            <orderedlist numeration="arabic">
               <listitem>
                  <para>
		     Use another name for the argument, if one is
		     available. For example, -value is an alias for
		     -values.
                  </para>
               </listitem>
               <listitem>
                  <para>
		     Change the capitalization, e.g. -Values
                  </para>
               </listitem>
               <listitem>
                  <para>
		     Put quotes around the argument name, e.g. '-values'
                  </para>
               </listitem>
            </orderedlist>
         </para>
         <para>
	    Many routines will do something useful with a named argument
	    that it doesn't recognize.	For example, you can produce
	    non-standard HTTP header fields by providing them as named
	    arguments:
         </para>
         <screen><![CDATA[print $q->header(-type  =>  'text/html',
                 -cost  =>  'Three smackers',
                 -annoyance_level => 'high',
                 -complaints_to   => 'bit bucket');]]></screen>
         <para>
	    This will produce the following nonstandard HTTP header:
         </para>
         <screen><![CDATA[HTTP/1.0 200 OK
Cost: Three smackers
Annoyance-level: high
Complaints-to: bit bucket
Content-type: text/html]]></screen>
         <para>
	    Notice the way that underscores are translated automatically
	    into hyphens.  HTML-generating routines perform a different
	    type of translation.
         </para>
         <para>
	    This feature allows you to keep up with the rapidly changing
	    HTTP and HTML <quote>standards</quote>.
         </para>
      </section>
      <section id="ID-831b994b0f17b99d48c9fc29e53cf2c9"><title>CREATING A NEW QUERY OBJECT (OBJECT-ORIENTED STYLE):</title>
         <screen><![CDATA[$query = CGI->new;]]></screen>
         <para>
	    This will parse the input (from both POST and GET methods) and
	    store it into a perl5 object called $query.
         </para>
         <para>
	    Any filehandles from file uploads will have their position
	    reset to the beginning of the file.
         </para>
      </section>
      <section id="ID-f8861febb178c714e8e6deed8fc75cff"><title>CREATING A NEW QUERY OBJECT FROM AN INPUT FILE</title>
         <screen><![CDATA[$query = CGI->new(INPUTFILE);]]></screen>
         <para>
	    If you provide a file handle to the new() method, it will read
	    parameters from the file (or STDIN, or whatever).  The file can
	    be in any of the forms describing below under debugging (i.e. a
	    series of newline delimited TAG=VALUE pairs will work). 
	    Conveniently, this type of file is created by the save() method
	    (see below).  Multiple records can be saved and restored.
         </para>
         <para>
	    Perl purists will be pleased to know that this syntax accepts
	    references to file handles, or even references to filehandle
	    globs, which is the <quote>official</quote> way to pass a filehandle:
         </para>
         <screen><![CDATA[$query = CGI->new(\*STDIN);]]></screen>
         <para>
	    You can also initialize the CGI object with a FileHandle or
	    IO::File object.
         </para>
         <para>
	    If you are using the function-oriented interface and want to
	    initialize CGI state from a file handle, the way to do this is
	    with <emphasis role="bold">restore_parameters()</emphasis>. 
	    This will (re)initialize the default CGI object from the
	    indicated file handle.
         </para>
         <screen><![CDATA[open (IN,"test.in") || die;
restore_parameters(IN);
close IN;]]></screen>
         <para>
	    You can also initialize the query object from a hash reference:
         </para>
         <screen><![CDATA[$query = CGI->new( {'dinosaur'=>'barney',
                   'song'=>'I love you',
                   'friends'=>[qw/Jessica George Nancy/]}
                );]]></screen>
         <para>
	    or from a properly formatted, URL-escaped query string:
         </para>
         <screen><![CDATA[$query = CGI->new('dinosaur=barney&color=purple');]]></screen>
         <para>
	    or from a previously existing CGI object (currently this clones
	    the parameter list, but none of the other object-specific
	    fields, such as autoescaping):
         </para>
         <screen><![CDATA[$old_query = CGI->new;
$new_query = CGI->new($old_query);]]></screen>
         <para>
	    To create an empty query, initialize it from an empty string or
	    hash:
         </para>
         <screen><![CDATA[$empty_query = CGI->new("");

-or-

$empty_query = CGI->new({});]]></screen>
      </section>
      <section id="ID-355fe12bcc3e31678b58baa2d1e8b7d3"><title>FETCHING A LIST OF KEYWORDS FROM THE QUERY:</title>
         <screen><![CDATA[@keywords = $query->keywords]]></screen>
         <para>
	    If the script was invoked as the result of an <ISINDEX>
	    search, the parsed keywords can be obtained as an array using
	    the keywords() method.
         </para>
      </section>
      <section id="ID-9585d92f9891d5bbea3d2ea406b1e888"><title>FETCHING THE NAMES OF ALL THE PARAMETERS PASSED TO YOUR SCRIPT:</title>
         <screen><![CDATA[@names = $query->param]]></screen>
         <para>
	    If the script was invoked with a parameter list (e.g.
	    <quote>name1=value1&name2=value2&name3=value3</quote>), the param()
	    method will return the parameter names as a list.  If the
	    script was invoked as an <ISINDEX> script and contains a
	    string without ampersands (e.g. <quote>value1+value2+value3</quote>) , there
	    will be a single parameter named <quote>keywords</quote> containing the
	    <quote>+</quote>-delimited keywords.
         </para>
         <para>
	    NOTE: As of version 1.5, the array of parameter names returned
	    will be in the same order as they were submitted by the
	    browser. Usually this order is the same as the order in which
	    the parameters are defined in the form (however, this isn't
	    part of the spec, and so isn't guaranteed).
         </para>
      </section>
      <section id="ID-5dc07004622561a5197c05270b2d6bfd"><title>FETCHING THE VALUE OR VALUES OF A SINGLE NAMED PARAMETER:</title>
         <screen><![CDATA[@values = $query->param('foo');

-or-

$value = $query->param('foo');]]></screen>
         <para>
	    Pass the param() method a single argument to fetch the value of
	    the named parameter. If the parameter is multivalued (e.g. from
	    multiple selections in a scrolling list), you can ask to
	    receive an array.  Otherwise the method will return a single
	    value.
         </para>
         <para>
	    If a value is not given in the query string, as in the queries
	    <quote>name1=&name2=</quote>, it will be returned as an empty string.
         </para>
         <screen><![CDATA[]]></screen>
         <para>
	    If the parameter does not exist at all, then param() will
	    return undef in a scalar context, and the empty list in a list
	    context.
         </para>
         <screen><![CDATA[]]></screen>
      </section>
      <section id="ID-8c463807461346bf32d7eeaa51bad70b"><title>SETTING THE VALUE(S) OF A NAMED PARAMETER:</title>
         <screen><![CDATA[$query->param('foo','an','array','of','values');]]></screen>
         <para>
	    This sets the value for the named parameter 'foo' to an array
	    of values.	This is one way to change the value of a field
	    AFTER the script has been invoked once before.  (Another way is
	    with the -override parameter accepted by all methods that
	    generate form elements.)
         </para>
         <para>
	    param() also recognizes a named parameter style of calling
	    described in more detail later:
         </para>
         <screen><![CDATA[$query->param(-name=>'foo',-values=>['an','array','of','values']);

-or-

$query->param(-name=>'foo',-value=>'the value');]]></screen>
      </section>
      <section id="ID-fecb608bfe95a2b689d1235b136ddc52"><title>APPENDING ADDITIONAL VALUES TO A NAMED PARAMETER:</title>
         <screen><![CDATA[$query->append(-name=>'foo',-values=>['yet','more','values']);]]></screen>
         <para>
	    This adds a value or list of values to the named parameter. 
	    The values are appended to the end of the parameter if it
	    already exists. Otherwise the parameter is created.  Note that
	    this method only recognizes the named argument calling syntax.
         </para>
      </section>
      <section id="ID-4e1ba96e1606a5ee76e6152bfb0d6f7f"><title>IMPORTING ALL PARAMETERS INTO A NAMESPACE:</title>
         <screen><![CDATA[$query->import_names('R');]]></screen>
         <para>
	    This creates a series of variables in the 'R' namespace.  For
	    example, $R::foo, @R:foo.  For keyword lists, a variable
	    @R::keywords will appear. If no namespace is given, this method
	    will assume 'Q'. WARNING:  don't import anything into 'main';
	    this is a major security risk!!!!
         </para>
         <para>
	    NOTE 1: Variable names are transformed as necessary into legal
	    Perl variable names.  All non-legal characters are transformed
	    into underscores.  If you need to keep the original names, you
	    should use the param() method instead to access CGI variables
	    by name.
         </para>
         <para>
	    NOTE 2: In older versions, this method was called <emphasis
	    role="bold">import()</emphasis>.  As of version 2.20, this name
	    has been removed completely to avoid conflict with the built-in
	    Perl module <emphasis role="bold">import</emphasis> operator.
         </para>
      </section>
      <section id="ID-532c4deff9fa1ab7c84636c7db32c9e9"><title>DELETING A PARAMETER COMPLETELY:</title>
         <screen><![CDATA[$query->delete('foo','bar','baz');]]></screen>
         <para>
	    This completely clears a list of parameters.  It sometimes
	    useful for resetting parameters that you don't want passed down
	    between script invocations.
         </para>
         <para>
	    If you are using the function call interface, use <quote>Delete()</quote>
	    instead to avoid conflicts with Perl's built-in delete
	    operator.
         </para>
      </section>
      <section id="ID-9449dd64d4cd34cca96cca2436d1a1d5"><title>DELETING ALL PARAMETERS:</title>
         <screen><![CDATA[$query->delete_all();]]></screen>
         <para>
	    This clears the CGI object completely.  It might be useful to
	    ensure that all the defaults are taken when you create a
	    fill-out form.
         </para>
         <para>
	    Use Delete_all() instead if you are using the function call
	    interface.
         </para>
      </section>
      <section id="ID-b80881d3cdda8937c5b1211cd864bf16"><title>HANDLING NON-URLENCODED ARGUMENTS</title>
         <screen><![CDATA[]]></screen>
         <para>
	    If POSTed data is not of type application/x-www-form-urlencoded
	    or multipart/form-data, then the POSTed data will not be
	    processed, but instead be returned as-is in a parameter named
	    POSTDATA.  To retrieve it, use code like this:
         </para>
         <screen><![CDATA[my $data = $query->param('POSTDATA');]]></screen>
         <para>
	    Likewise if PUTed data can be retrieved with code like this:
         </para>
         <screen><![CDATA[my $data = $query->param('PUTDATA');]]></screen>
         <para>
	    (If you don't know what the preceding means, don't worry about
	    it.  It only affects people trying to use CGI for XML
	    processing and other specialized tasks.)
         </para>
         <screen><![CDATA[]]></screen>
      </section>
      <section id="ID-80018d0e7f59b5365695abbd5709ee00"><title>DIRECT ACCESS TO THE PARAMETER LIST:</title>
         <screen><![CDATA[$q->param_fetch('address')->[1] = '1313 Mockingbird Lane';
unshift @{$q->param_fetch(-name=>'address')},'George Munster';]]></screen>
         <para>
	    If you need access to the parameter list in a way that isn't
	    covered by the methods above, you can obtain a direct reference
	    to it by calling the <emphasis
	    role="bold">param_fetch()</emphasis> method with the name of
	    the .  This will return an array reference to the named
	    parameters, which you then can manipulate in any way you like.
         </para>
         <para>
	    You can also use a named argument style using the <emphasis
	    role="bold">-name</emphasis> argument.
         </para>
      </section>
      <section id="ID-5cfbcd098813ceba23e30c7e23c0539c"><title>FETCHING THE PARAMETER LIST AS A HASH:</title>
         <screen><![CDATA[$params = $q->Vars;
print $params->{'address'};
@foo = split("\0",$params->{'foo'});
%params = $q->Vars;

use CGI ':cgi-lib';
$params = Vars;]]></screen>
         <para>
	    Many people want to fetch the entire parameter list as a hash
	    in which the keys are the names of the CGI parameters, and the
	    values are the parameters' values.	The Vars() method does
	    this.  Called in a scalar context, it returns the parameter
	    list as a tied hash reference. Changing a key changes the value
	    of the parameter in the underlying CGI parameter list.  Called
	    in a list context, it returns the parameter list as an ordinary
	    hash.  This allows you to read the contents of the parameter
	    list, but not to change it.
         </para>
         <para>
	    When using this, the thing you must watch out for are
	    multivalued CGI parameters.  Because a hash cannot distinguish
	    between scalar and list context, multivalued parameters will be
	    returned as a packed string, separated by the <quote>\0</quote> (null)
	    character.	You must split this packed string in order to get
	    at the individual values.  This is the convention introduced
	    long ago by Steve Brenner in his cgi-lib.pl module for Perl
	    version 4.
         </para>
         <para>
	    If you wish to use Vars() as a function, import the <emphasis
	    role="italic">:cgi-lib</emphasis> set of function calls (also
	    see the section on CGI-LIB compatibility).
         </para>
      </section>
      <section id="ID-95c19da3539eb1298a5ec81033795904"><title>SAVING THE STATE OF THE SCRIPT TO A FILE:</title>
         <screen><![CDATA[$query->save(\*FILEHANDLE)]]></screen>
         <para>
	    This will write the current state of the form to the provided
	    filehandle.  You can read it back in by providing a filehandle
	    to the new() method.  Note that the filehandle can be a file, a
	    pipe, or whatever!
         </para>
         <para>
	    The format of the saved file is:
         </para>
         <screen><![CDATA[NAME1=VALUE1
NAME1=VALUE1'
NAME2=VALUE2
NAME3=VALUE3
=]]></screen>
         <para>
	    Both name and value are URL escaped.  Multi-valued CGI
	    parameters are represented as repeated names.  A session record
	    is delimited by a single = symbol.	You can write out multiple
	    records and read them back in with several calls to <emphasis
	    role="bold">new</emphasis>.  You can do this across several
	    sessions by opening the file in append mode, allowing you to
	    create primitive guest books, or to keep a history of users'
	    queries.  Here's a short example of creating multiple session
	    records:
         </para>
         <screen><![CDATA[use CGI;

open (OUT,'>>','test.out') || die;
$records = 5;
for (0..$records) {
    my $q = CGI->new;
    $q->param(-name=>'counter',-value=>$_);
    $q->save(\*OUT);
}
close OUT;

# reopen for reading
open (IN,'<','test.out') || die;
while (!eof(IN)) {
    my $q = CGI->new(\*IN);
    print $q->param('counter'),"\n";
}]]></screen>
         <para>
	    The file format used for save/restore is identical to that used
	    by the Whitehead Genome Center's data exchange format
	    <quote>Boulderio</quote>, and can be manipulated and even databased using
	    Boulderio utilities.  See
         </para>
         <screen><![CDATA[http://stein.cshl.org/boulder/]]></screen>
         <para>
	    for further details.
         </para>
         <para>
	    If you wish to use this method from the function-oriented
	    (non-OO) interface, the exported name for this method is
	    <emphasis role="bold">save_parameters()</emphasis>.
         </para>
      </section>
      <section id="ID-db7e4cb01c582130c88c53f7a1c108fa"><title>RETRIEVING CGI ERRORS</title>
         <para>
	    Errors can occur while processing user input, particularly when
	    processing uploaded files.	When these errors occur, CGI will
	    stop processing and return an empty parameter list.  You can
	    test for the existence and nature of errors using the <emphasis
	    role="italic">cgi_error()</emphasis> function. The error
	    messages are formatted as HTTP status codes. You can either
	    incorporate the error text into an HTML page, or use it as the
	    value of the HTTP status:
         </para>
         <screen><![CDATA[my $error = $q->cgi_error;
if ($error) {
    print $q->header(-status=>$error),
          $q->start_html('Problems'),
          $q->h2('Request not processed'),
          $q->strong($error);
    exit 0;
}]]></screen>
         <para>
	    When using the function-oriented interface (see the next
	    section), errors may only occur the first time you call
	    <emphasis role="italic">param()</emphasis>. Be ready for this!
         </para>
      </section>
      <section id="ID-fe97d34e13c9182e8d78c795ffa90748"><title>USING THE FUNCTION-ORIENTED INTERFACE</title>
         <para>
	    To use the function-oriented interface, you must specify which
	    CGI.pm routines or sets of routines to import into your
	    script's namespace. There is a small overhead associated with
	    this importation, but it isn't much.
         </para>
         <screen><![CDATA[use CGI <list of methods>;]]></screen>
         <para>
	    The listed methods will be imported into the current package;
	    you can call them directly without creating a CGI object first.
	     This example shows how to import the <emphasis
	    role="bold">param()</emphasis> and <emphasis
	    role="bold">header()</emphasis> methods, and then use them
	    directly:
         </para>
         <screen><![CDATA[use CGI 'param','header';
print header('text/plain');
$zipcode = param('zipcode');]]></screen>
         <para>
	    More frequently, you'll import common sets of functions by
	    referring to the groups by name.  All function sets are
	    preceded with a <quote>:</quote> character as in <quote>:html3</quote> (for tags defined
	    in the HTML 3 standard).
         </para>
         <para>
	    Here is a list of the function sets you can import:
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-c4e7b9c11df4639e6654a599452ae84a"/><emphasis role="bold">:cgi</emphasis></term>
                  <listitem>
                     <para>
			Import all CGI-handling methods, such as <emphasis
			role="bold">param()</emphasis>, <emphasis
			role="bold">path_info()</emphasis> and the like.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-d9e76b7fd89ee942c18e019e8aa3de8e"/><emphasis role="bold">:form</emphasis></term>
                  <listitem>
                     <para>
			Import all fill-out form generating methods, such
			as <emphasis role="bold">textfield()</emphasis>.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-7e7a6a860ec45cefed810e99ad0fc281"/><emphasis role="bold">:html2</emphasis></term>
                  <listitem>
                     <para>
			Import all methods that generate HTML 2.0 standard
			elements.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-041bcc3164cddd96d4509c318d465819"/><emphasis role="bold">:html3</emphasis></term>
                  <listitem>
                     <para>
			Import all methods that generate HTML 3.0 elements
			(such as <table>, <super> and
			<sub>).
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-288230b27671ced27b07d379742894b6"/><emphasis role="bold">:html4</emphasis></term>
                  <listitem>
                     <para>
			Import all methods that generate HTML 4 elements
			(such as <abbrev>, <acronym> and
			<thead>).
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-09870ec83539c60b479e1d40d1692833"/><emphasis role="bold">:netscape</emphasis></term>
                  <listitem>
                     <para>
			Import the <blink>, <fontsize> and
			<center> tags.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-e3317396d06f79ef422d6b37c6086d17"/><emphasis role="bold">:html</emphasis></term>
                  <listitem>
                     <para>
			Import all HTML-generating shortcuts (i.e. 'html2',
			'html3', 'html4' and 'netscape')
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-6ec9750d89ad12401360d670e08f4fc5"/><emphasis role="bold">:standard</emphasis></term>
                  <listitem>
                     <para>
			Import <quote>standard</quote> features, 'html2', 'html3',
			'html4', 'form' and 'cgi'.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-7914b232fee5166dca2cd30e5ecf75c8"/><emphasis role="bold">:all</emphasis></term>
                  <listitem>
                     <para>
			Import all the available methods.  For the full
			list, see the CGI.pm code, where the variable
			%EXPORT_TAGS is defined.
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
         <para>
	    If you import a function name that is not part of CGI.pm, the
	    module will treat it as a new HTML tag and generate the
	    appropriate subroutine.  You can then use it like any other
	    HTML tag.  This is to provide for the rapidly-evolving HTML
	    <quote>standard.</quote>  For example, say Microsoft comes out with a new
	    tag called <gradient> (which causes the user's desktop to
	    be flooded with a rotating gradient fill until his machine
	    reboots).  You don't need to wait for a new version of CGI.pm
	    to start using it immediately:
         </para>
         <screen><![CDATA[use CGI qw/:standard :html3 gradient/;
print gradient({-start=>'red',-end=>'blue'});]]></screen>
         <para>
	    Note that in the interests of execution speed CGI.pm does
	    <emphasis role="bold">not</emphasis> use the standard
	    <citerefentry> <refentrytitle>Exporter</refentrytitle>
	    </citerefentry> syntax for specifying load symbols.  This may
	    change in the future.
         </para>
         <para>
	    If you import any of the state-maintaining CGI or
	    form-generating methods, a default CGI object will be created
	    and initialized automatically the first time you use any of the
	    methods that require one to be present.  This includes
	    <emphasis role="bold">param()</emphasis>, <emphasis
	    role="bold">textfield()</emphasis>, <emphasis
	    role="bold">submit()</emphasis> and the like.  (If you need
	    direct access to the CGI object, you can find it in the global
	    variable <emphasis role="bold">$CGI::Q</emphasis>).  By
	    importing CGI.pm methods, you can create visually elegant
	    scripts:
         </para>
         <screen><![CDATA[use CGI qw/:standard/;
print 
    header,
    start_html('Simple Script'),
    h1('Simple Script'),
    start_form,
    "What's your name? ",textfield('name'),p,
    "What's the combination?",
    checkbox_group(-name=>'words',
                   -values=>['eenie','meenie','minie','moe'],
                   -defaults=>['eenie','moe']),p,
    "What's your favorite color?",
    popup_menu(-name=>'color',
               -values=>['red','green','blue','chartreuse']),p,
    submit,
    end_form,
    hr,"\n";

if (param) {
   print 
       "Your name is ",em(param('name')),p,
       "The keywords are: ",em(join(", ",param('words'))),p,
       "Your favorite color is ",em(param('color')),".\n";
}
print end_html;]]></screen>
      </section>
      <section id="ID-64cf728f1c695fc4ecf072de6a91bc8b"><title>PRAGMAS</title>
         <para>
	    In addition to the function sets, there are a number of pragmas
	    that you can import.  Pragmas, which are always preceded by a
	    hyphen, change the way that CGI.pm functions in various ways. 
	    Pragmas, function sets, and individual functions can all be
	    imported in the same use() line.  For example, the following
	    use statement imports the standard set of functions and enables
	    debugging mode (pragma -debug):
         </para>
         <screen><![CDATA[use CGI qw/:standard -debug/;]]></screen>
         <para>
	    The current list of pragmas is as follows:
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-6b2a8cd997f5af870a8a8223a253dfc2"/>-any</term>
                  <listitem>
                     <para>
			When you <emphasis role="italic">use CGI
			-any</emphasis>, then any method that the query
			object doesn't recognize will be interpreted as a
			new HTML tag.  This allows you to support the next
			<emphasis role="italic">ad hoc</emphasis> HTML
			extension.  This lets you go wild with new and
			unsupported tags:
                     </para>
                     <screen><![CDATA[use CGI qw(-any);
$q=CGI->new;
print $q->gradient({speed=>'fast',start=>'red',end=>'blue'});]]></screen>
                     <para>
			Since using <cite>any</cite> causes any
			mistyped method name to be interpreted as an HTML
			tag, use it with care or not at all.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-48a9bbe93d6ae149a7abb3afa34b30f6"/>-compile</term>
                  <listitem>
                     <para>
			This causes the indicated autoloaded methods to be
			compiled up front, rather than deferred to later. 
			This is useful for scripts that run for an extended
			period of time under FastCGI or mod_perl, and for
			those destined to be crunched by Malcolm Beattie's
			Perl compiler.	Use it in conjunction with the
			methods or method families you plan to use.
                     </para>
                     <screen><![CDATA[use CGI qw(-compile :standard :html3);]]></screen>
                     <para>
			or even
                     </para>
                     <screen><![CDATA[use CGI qw(-compile :all);]]></screen>
                     <para>
			Note that using the -compile pragma in this way
			will always have the effect of importing the
			compiled functions into the current namespace.	If
			you want to compile without importing use the
			compile() method instead:
                     </para>
                     <screen><![CDATA[use CGI();
CGI->compile();]]></screen>
                     <para>
			This is particularly useful in a mod_perl
			environment, in which you might want to precompile
			all CGI routines in a startup script, and then
			import the functions individually in each mod_perl
			script.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ab16691f0ef994b0c80aa37c77525159"/>-nosticky</term>
                  <listitem>
                     <para>
			By default the CGI module implements a
			state-preserving behavior called <quote>sticky</quote> fields. 
			The way this works is that if you are regenerating
			a form, the methods that generate the form field
			values will interrogate param() to see if
			similarly-named parameters are present in the query
			string. If they find a like-named parameter, they
			will use it to set their default values.
                     </para>
                     <para>
			Sometimes this isn't what you want.  The <emphasis
			role="bold">-nosticky</emphasis> pragma prevents
			this behavior.	You can also selectively change the
			sticky behavior in each element that you generate.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ea3d9ea3cfb7429d9b1ae1da4620edb6"/>-tabindex</term>
                  <listitem>
                     <para>
			Automatically add tab index attributes to each form
			field. With this option turned off, you can still
			add tab indexes manually by passing a -tabindex
			option to each field-generating method.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-c905f9022fb2d5fb6f310a85e77ee153"/>-no_undef_params</term>
                  <listitem>
                     <para>
			This keeps CGI.pm from including undef params in
			the parameter list.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-567a52215a03bbb7295be657a18f2247"/>-no_xhtml</term>
                  <listitem>
                     <para>
			By default, CGI.pm versions 2.69 and higher emit
			XHTML (http://www.w3.org/TR/xhtml1/).  The
			-no_xhtml pragma disables this feature.  Thanks to
			Michalis Kabrianis <kabrianis@hellug.gr> for
			this feature.
                     </para>
                     <para>
			If start_html()'s -dtd parameter specifies an HTML
			2.0, 3.2, 4.0 or 4.01 DTD, XHTML will automatically
			be disabled without needing to use this pragma.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-63ff0ccf7aaf4587ac7a4272be4d8f17"/>-utf8</term>
                  <listitem>
                     <para>
			This makes CGI.pm treat all parameters as UTF-8
			strings. Use this with care, as it will interfere
			with the processing of binary uploads. It is better
			to manually select which fields are expected to
			return utf-8 strings and convert them using code
			like this:
                     </para>
                     <screen><![CDATA[use Encode;
my $arg = decode utf8=>param('foo');]]></screen>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-b6d9e91c6835de7d80777fdad8a01312"/>-nph</term>
                  <listitem>
                     <para>
			This makes CGI.pm produce a header appropriate for
			an NPH (no parsed header) script.  You may need to
			do other things as well to tell the server that the
			script is NPH.	See the discussion of NPH scripts
			below.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-b7739767aaa53d8a462529921ff31d76"/>-newstyle_urls</term>
                  <listitem>
                     <para>
			Separate the name=value pairs in CGI parameter
			query strings with semicolons rather than
			ampersands.  For example:
                     </para>
                     <screen><![CDATA[?name=fred;age=24;favorite_color=3]]></screen>
                     <para>
			Semicolon-delimited query strings are always
			accepted, and will be emitted by self_url() and
			query_string(). newstyle_urls became the default in
			version 2.64.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-fbbcf73edd238a463514a5cd3c71c190"/>-oldstyle_urls</term>
                  <listitem>
                     <para>
			Separate the name=value pairs in CGI parameter
			query strings with ampersands rather than
			semicolons.  This is no longer the default.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-35dd5a1b18fc9c13b5a1fa2220dc0429"/>-autoload</term>
                  <listitem>
                     <para>
			This overrides the autoloader so that any function
			in your program that is not recognized is referred
			to CGI.pm for possible evaluation. This allows you
			to use all the CGI.pm functions without adding them
			to your symbol table, which is of concern for
			mod_perl users who are worried about memory
			consumption.  <emphasis
			role="italic">Warning:</emphasis> when <emphasis
			role="italic">-autoload</emphasis> is in effect,
			you cannot use <quote>poetry mode</quote> (functions without the
			parenthesis).  Use <emphasis
			role="italic">hr()</emphasis> rather than <emphasis
			role="italic">hr</emphasis>, or add something like
			<emphasis role="italic">use subs qw/hr p
			header/</emphasis> to the top of your script.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-17355ff85d2ee07bfd0e6ac35dd974d5"/>-no_debug</term>
                  <listitem>
                     <para>
			This turns off the command-line processing
			features.  If you want to run a CGI.pm script from
			the command line to produce HTML, and you don't
			want it to read CGI parameters from the command
			line or STDIN, then use this pragma:
                     </para>
                     <screen><![CDATA[use CGI qw(-no_debug :standard);]]></screen>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ca80fa463a4b8fed2c2aab3274afc3b3"/>-debug</term>
                  <listitem>
                     <para>
			This turns on full debugging.  In addition to
			reading CGI arguments from the command-line
			processing, CGI.pm will pause and try to read
			arguments from STDIN, producing the message
			<quote>(offline mode: enter name=value pairs on standard
			input)</quote> features.
                     </para>
                     <para>
			See the section on debugging for more details.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-2ec2b17a2c580e2c71729e86426aa317"/>-private_tempfiles</term>
                  <listitem>
                     <para>
			CGI.pm can process uploaded file. Ordinarily it
			spools the uploaded file to a temporary directory,
			then deletes the file when done. However, this
			opens the risk of eavesdropping as described in the
			file upload section.  Another CGI script author
			could peek at this data during the upload, even if
			it is confidential information. On Unix systems,
			the -private_tempfiles pragma will cause the
			temporary file to be unlinked as soon as it is
			opened and before any data is written into it,
			reducing, but not eliminating the risk of
			eavesdropping (there is still a potential race
			condition).  To make life harder for the attacker,
			the program chooses tempfile names by calculating a
			32 bit checksum of the incoming HTTP headers.
                     </para>
                     <para>
			To ensure that the temporary file cannot be read by
			other CGI scripts, use suEXEC or a CGI wrapper
			program to run your script.  The temporary file is
			created with mode 0600 (neither world nor group
			readable).
                     </para>
                     <para>
			The temporary directory is selected using the
			following algorithm:
                     </para>
                     <screen><![CDATA[1. if the current user (e.g. "nobody") has a directory named
"tmp" in its home directory, use that (Unix systems only).

2. if the environment variable TMPDIR exists, use the location
indicated.

3. Otherwise try the locations /usr/tmp, /var/tmp, C:\temp,
/tmp, /temp, ::Temporary Items, and \WWW_ROOT.]]></screen>
                     <para>
			Each of these locations is checked that it is a
			directory and is writable.  If not, the algorithm
			tries the next choice.
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
      </section>
      <section id="ID-beee5f98769ea58a0032957f5fadb52f"><title>SPECIAL FORMS FOR IMPORTING HTML-TAG FUNCTIONS</title>
         <para>
	    Many of the methods generate HTML tags.  As described below,
	    tag functions automatically generate both the opening and
	    closing tags. For example:
         </para>
         <screen><![CDATA[print h1('Level 1 Header');]]></screen>
         <para>
	    produces
         </para>
         <screen><![CDATA[<h1>Level 1 Header</h1>]]></screen>
         <para>
	    There will be some times when you want to produce the start and
	    end tags yourself.	In this case, you can use the form
	    start_<emphasis role="italic">tag_name</emphasis> and
	    end_<emphasis role="italic">tag_name</emphasis>, as in:
         </para>
         <screen><![CDATA[print start_h1,'Level 1 Header',end_h1;]]></screen>
         <para>
	    With a few exceptions (described below), start_<emphasis
	    role="italic">tag_name</emphasis> and end_<emphasis
	    role="italic">tag_name</emphasis> functions are not generated
	    automatically when you <emphasis role="italic">use
	    CGI</emphasis>.  However, you can specify the tags you want to
	    generate <emphasis role="italic">start/end</emphasis> functions
	    for by putting an asterisk in front of their name, or,
	    alternatively, requesting either <quote>start_<emphasis
	    role="italic">tag_name</emphasis></quote> or <quote>end_<emphasis
	    role="italic">tag_name</emphasis></quote> in the import list.
         </para>
         <para>
	    Example:
         </para>
         <screen><![CDATA[use CGI qw/:standard *table start_ul/;]]></screen>
         <para>
	    In this example, the following functions are generated in
	    addition to the standard ones:
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-9e369583ce232bb416a7819bb6c8c188"/>1. start_table() (generates a <table> tag)</term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-45b074805ff9334aad7d5834b2b166ef"/>2. end_table() (generates a </table> tag)</term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-7b4ace0a5562e29af15f82f4df59f293"/>3. start_ul() (generates a <ul> tag)</term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-8761dfd928c2c27bfa08b9b787728953"/>4. end_ul() (generates a </ul> tag)</term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
      </section>
   </section>
   <section id="ID-8fca7c1e7617cd664dcfc7d0d474a414"><title>GENERATING DYNAMIC DOCUMENTS</title>
      <para>
	 Most of CGI.pm's functions deal with creating documents on the
	 fly. Generally you will produce the HTTP header first, followed by
	 the document itself.  CGI.pm provides functions for generating
	 HTTP headers of various types as well as for generating HTML.	For
	 creating GIF images, see the GD.pm module.
      </para>
      <para>
	 Each of these functions produces a fragment of HTML or HTTP which
	 you can print out directly so that it displays in the browser
	 window, append to a string, or save to a file for later use.
      </para>
      <section id="ID-a50060f645b44b9a6ef62d9454d8ea31"><title>CREATING A STANDARD HTTP HEADER:</title>
         <para>
	    Normally the first thing you will do in any CGI script is print
	    out an HTTP header.  This tells the browser what type of
	    document to expect, and gives other optional information, such
	    as the language, expiration date, and whether to cache the
	    document.  The header can also be manipulated for special
	    purposes, such as server push and pay per view pages.
         </para>
         <screen><![CDATA[print header;

-or-

print header('image/gif');

-or-

print header('text/html','204 No response');

-or-

print header(-type=>'image/gif',
                     -nph=>1,
                     -status=>'402 Payment required',
                     -expires=>'+3d',
                     -cookie=>$cookie,
                     -charset=>'utf-7',
                     -attachment=>'foo.gif',
                     -Cost=>'$2.00');]]></screen>
         <para>
	    header() returns the Content-type: header.	You can provide
	    your own MIME type if you choose, otherwise it defaults to
	    text/html.	An optional second parameter specifies the status
	    code and a human-readable message.	For example, you can
	    specify 204, <quote>No response</quote> to create a script that tells the
	    browser to do nothing at all.
         </para>
         <para>
	    The last example shows the named argument style for passing
	    arguments to the CGI methods using named parameters. 
	    Recognized parameters are <emphasis
	    role="bold">-type</emphasis>, <emphasis
	    role="bold">-status</emphasis>, <emphasis
	    role="bold">-expires</emphasis>, and <emphasis
	    role="bold">-cookie</emphasis>.  Any other named parameters
	    will be stripped of their initial hyphens and turned into
	    header fields, allowing you to specify any HTTP header you
	    desire. Internal underscores will be turned into hyphens:
         </para>
         <screen><![CDATA[print header(-Content_length=>3002);]]></screen>
         <para>
	    Most browsers will not cache the output from CGI scripts. 
	    Every time the browser reloads the page, the script is invoked
	    anew.  You can change this behavior with the <emphasis
	    role="bold">-expires</emphasis> parameter.	When you specify an
	    absolute or relative expiration interval with this parameter,
	    some browsers and proxy servers will cache the script's output
	    until the indicated expiration date.  The following forms are
	    all valid for the -expires field:
         </para>
         <screen><![CDATA[+30s                              30 seconds from now
+10m                              ten minutes from now
+1h                               one hour from now
-1d                               yesterday (i.e. "ASAP!")
now                               immediately
+3M                               in three months
+10y                              in ten years time
Thursday, 25-Apr-1999 00:40:33 GMT  at the indicated time & date]]></screen>
         <para>
	    The <emphasis role="bold">-cookie</emphasis> parameter
	    generates a header that tells the browser to provide a <quote>magic
	    cookie</quote> during all subsequent transactions with your script.
	    Some cookies have a special format that includes interesting
	    attributes such as expiration time.  Use the cookie() method to
	    create and retrieve session cookies.
         </para>
         <para>
	    The <emphasis role="bold">-nph</emphasis> parameter, if set to
	    a true value, will issue the correct headers to work with a NPH
	    (no-parse-header) script.  This is important to use with
	    certain servers that expect all their scripts to be NPH.
         </para>
         <para>
	    The <emphasis role="bold">-charset</emphasis> parameter can be
	    used to control the character set sent to the browser.  If not
	    provided, defaults to ISO-8859-1.  As a side effect, this sets
	    the charset() method as well.
         </para>
         <para>
	    The <emphasis role="bold">-attachment</emphasis> parameter can
	    be used to turn the page into an attachment.  Instead of
	    displaying the page, some browsers will prompt the user to save
	    it to disk.  The value of the argument is the suggested name
	    for the saved file.  In order for this to work, you may have to
	    set the <emphasis role="bold">-type</emphasis> to
	    <quote>application/octet-stream</quote>.
         </para>
         <para>
	    The <emphasis role="bold">-p3p</emphasis> parameter will add a
	    P3P tag to the outgoing header.  The parameter can be an
	    arrayref or a space-delimited string of P3P tags. For example:
         </para>
         <screen><![CDATA[print header(-p3p=>[qw(CAO DSP LAW CURa)]);
print header(-p3p=>'CAO DSP LAW CURa');]]></screen>
         <para>
	    In either case, the outgoing header will be formatted as:
         </para>
         <screen><![CDATA[P3P: policyref="/w3c/p3p.xml" cp="CAO DSP LAW CURa"]]></screen>
         <para>
	    Note that if a header value contains a carriage return, a
	    leading space will be added to each new line that doesn't
	    already have one as specified by RFC2616 section 4.2.  For
	    example:
         </para>
         <screen><![CDATA[print header( -ingredients => "ham\neggs\nbacon" );]]></screen>
         <para>
	    will generate
         </para>
         <screen><![CDATA[Ingredients: ham
 eggs
 bacon]]></screen>
      </section>
      <section id="ID-aa4850905975561fb4bb6c6d074bf392"><title>GENERATING A REDIRECTION HEADER</title>
         <screen><![CDATA[print $q->redirect('http://somewhere.else/in/movie/land');]]></screen>
         <para>
	    Sometimes you don't want to produce a document yourself, but
	    simply redirect the browser elsewhere, perhaps choosing a URL
	    based on the time of day or the identity of the user.
         </para>
         <para>
	    The redirect() method redirects the browser to a different URL.
	     If you use redirection like this, you should <emphasis
	    role="bold">not</emphasis> print out a header as well.
         </para>
         <para>
	    You should always use full URLs (including the http: or ftp:
	    part) in redirection requests.  Relative URLs will not work
	    correctly.
         </para>
         <para>
	    You can also use named arguments:
         </para>
         <screen><![CDATA[print $q->redirect(
    -uri=>'http://somewhere.else/in/movie/land',
        -nph=>1,
     -status=>301);]]></screen>
         <para>
	    All names arguments recognized by header() are also recognized
	    by redirect(). However, most HTTP headers, including those
	    generated by -cookie and -target, are ignored by the browser.
         </para>
         <para>
	    The <emphasis role="bold">-nph</emphasis> parameter, if set to
	    a true value, will issue the correct headers to work with a NPH
	    (no-parse-header) script.  This is important to use with
	    certain servers, such as Microsoft IIS, which expect all their
	    scripts to be NPH.
         </para>
         <para>
	    The <emphasis role="bold">-status</emphasis> parameter will set
	    the status of the redirect.  HTTP defines three different
	    possible redirection status codes:
         </para>
         <screen><![CDATA[301 Moved Permanently
302 Found
303 See Other]]></screen>
         <para>
	    The default if not specified is 302, which means <quote>moved
	    temporarily.</quote> You may change the status to another status code
	    if you wish.  Be advised that changing the status to anything
	    other than 301, 302 or 303 will probably break redirection.
         </para>
      </section>
      <section id="ID-05c4df4e1ce5d62296f219cd959d1817"><title>CREATING THE HTML DOCUMENT HEADER</title>
         <screen><![CDATA[print start_html(-title=>'Secrets of the Pyramids',
                         -author=>'fred@capricorn.org',
                         -base=>'true',
                         -target=>'_blank',
                         -meta=>{'keywords'=>'pharaoh secret mummy',
                                 'copyright'=>'copyright 1996 King Tut'},
                         -style=>{'src'=>'/styles/style1.css'},
                         -BGCOLOR=>'blue');]]></screen>
         <para>
	    After creating the HTTP header, most CGI scripts will start
	    writing out an HTML document.  The start_html() routine creates
	    the top of the page, along with a lot of optional information
	    that controls the page's appearance and behavior.
         </para>
         <para>
	    This method returns a canned HTML header and the opening
	    <body> tag. All parameters are optional.  In the named
	    parameter form, recognized parameters are -title, -author,
	    -base, -xbase, -dtd, -lang and -target (see below for the
	    explanation).  Any additional parameters you provide, such as
	    the unofficial BGCOLOR attribute, are added to the <body>
	    tag.  Additional parameters must be proceeded by a hyphen.
         </para>
         <para>
	    The argument <emphasis role="bold">-xbase</emphasis> allows you
	    to provide an HREF for the <base> tag different from the
	    current location, as in
         </para>
         <screen><![CDATA[-xbase=>"http://home.mcom.com/"]]></screen>
         <para>
	    All relative links will be interpreted relative to this tag.
         </para>
         <para>
	    The argument <emphasis role="bold">-target</emphasis> allows
	    you to provide a default target frame for all the links and
	    fill-out forms on the page.  <emphasis role="bold">This is a
	    non-standard HTTP feature which only works with some
	    browsers!</emphasis>
         </para>
         <screen><![CDATA[-target=>"answer_window"]]></screen>
         <para>
	    All relative links will be interpreted relative to this tag.
	    You add arbitrary meta information to the header with the
	    <emphasis role="bold">-meta</emphasis> argument.  This argument
	    expects a reference to a hash containing name/value pairs of
	    meta information.  These will be turned into a series of header
	    <meta> tags that look something like this:
         </para>
         <screen><![CDATA[<meta name="keywords" content="pharaoh secret mummy">
<meta name="description" content="copyright 1996 King Tut">]]></screen>
         <para>
	    To create an HTTP-EQUIV type of <meta> tag, use <emphasis
	    role="bold">-head</emphasis>, described below.
         </para>
         <para>
	    The <emphasis role="bold">-style</emphasis> argument is used to
	    incorporate cascading stylesheets into your code.  See the
	    section on CASCADING STYLESHEETS for more information.
         </para>
         <para>
	    The <emphasis role="bold">-lang</emphasis> argument is used to
	    incorporate a language attribute into the <html> tag. 
	    For example:
         </para>
         <screen><![CDATA[print $q->start_html(-lang=>'fr-CA');]]></screen>
         <para>
	    The default if not specified is <quote>en-US</quote> for US English, unless
	    the -dtd parameter specifies an HTML 2.0 or 3.2 DTD, in which
	    case the lang attribute is left off.  You can force the lang
	    attribute to left off in other cases by passing an empty string
	    (-lang=>'').
         </para>
         <para>
	    The <emphasis role="bold">-encoding</emphasis> argument can be
	    used to specify the character set for XHTML.  It defaults to
	    iso-8859-1 if not specified.
         </para>
         <para>
	    The <emphasis role="bold">-declare_xml</emphasis> argument,
	    when used in conjunction with XHTML, will put a <?xml>
	    declaration at the top of the HTML header. The sole purpose of
	    this declaration is to declare the character set encoding. In
	    the absence of -declare_xml, the output HTML will contain a
	    <meta> tag that specifies the encoding, allowing the HTML
	    to pass most validators.  The default for -declare_xml is
	    false.
         </para>
         <para>
	    You can place other arbitrary HTML elements to the <head>
	    section with the <emphasis role="bold">-head</emphasis> tag. 
	    For example, to place the rarely-used <link> element in
	    the head section, use this:
         </para>
         <screen><![CDATA[print start_html(-head=>Link({-rel=>'next',
                              -href=>'http://www.capricorn.com/s2.html'}));]]></screen>
         <para>
	    To incorporate multiple HTML elements into the <head>
	    section, just pass an array reference:
         </para>
         <screen><![CDATA[print start_html(-head=>[ 
                         Link({-rel=>'next',
                               -href=>'http://www.capricorn.com/s2.html'}),
                         Link({-rel=>'previous',
                               -href=>'http://www.capricorn.com/s1.html'})
                         ]
                 );]]></screen>
         <para>
	    And here's how to create an HTTP-EQUIV <meta> tag:
         </para>
         <screen><![CDATA[print start_html(-head=>meta({-http_equiv => 'Content-Type',
                              -content    => 'text/html'}))

]]></screen>
         <para>
	    JAVASCRIPTING: The <emphasis role="bold">-script</emphasis>,
	    <emphasis role="bold">-noScript</emphasis>, <emphasis
	    role="bold">-onLoad</emphasis>, <emphasis
	    role="bold">-onMouseOver</emphasis>, <emphasis
	    role="bold">-onMouseOut</emphasis> and <emphasis
	    role="bold">-onUnload</emphasis> parameters are used to add
	    JavaScript calls to your pages.  <emphasis
	    role="bold">-script</emphasis> should point to a block of text
	    containing JavaScript function definitions. This block will be
	    placed within a <script> block inside the HTML (not HTTP)
	    header.  The block is placed in the header in order to give
	    your page a fighting chance of having all its JavaScript
	    functions in place even if the user presses the stop button
	    before the page has loaded completely.  CGI.pm attempts to
	    format the script in such a way that JavaScript-naive browsers
	    will not choke on the code: unfortunately there are some
	    browsers, such as Chimera for Unix, that get confused by it
	    nevertheless.
         </para>
         <para>
	    The <emphasis role="bold">-onLoad</emphasis> and <emphasis
	    role="bold">-onUnload</emphasis> parameters point to fragments
	    of JavaScript code to execute when the page is respectively
	    opened and closed by the browser.  Usually these parameters are
	    calls to functions defined in the <emphasis
	    role="bold">-script</emphasis> field:
         </para>
         <screen><![CDATA[$query = CGI->new;
print header;
$JSCRIPT=<<END;
// Ask a silly question
function riddle_me_this() {
   var r = prompt("What walks on four legs in the morning, " +
                 "two legs in the afternoon, " +
                 "and three legs in the evening?");
   response(r);
}
// Get a silly answer
function response(answer) {
   if (answer == "man")
      alert("Right you are!");
   else
      alert("Wrong!  Guess again.");
}
END
print start_html(-title=>'The Riddle of the Sphinx',
                         -script=>$JSCRIPT);]]></screen>
         <para>
	    Use the <emphasis role="bold">-noScript</emphasis> parameter to
	    pass some HTML text that will be displayed on browsers that do
	    not have JavaScript (or browsers where JavaScript is turned
	    off).
         </para>
         <para>
	    The <script> tag, has several attributes including <quote>type</quote>
	    and src. The latter is particularly interesting, as it allows
	    you to keep the JavaScript code in a file or CGI script rather
	    than cluttering up each page with the source.  To use these
	    attributes pass a HASH reference in the <emphasis
	    role="bold">-script</emphasis> parameter containing one or more
	    of -type, -src, or -code:
         </para>
         <screen><![CDATA[print $q->start_html(-title=>'The Riddle of the Sphinx',
                     -script=>{-type=>'JAVASCRIPT',
                               -src=>'/javascript/sphinx.js'}
                     );

print $q->(-title=>'The Riddle of the Sphinx',
           -script=>{-type=>'PERLSCRIPT',
                     -code=>'print "hello world!\n;"'}
           );

]]></screen>
         <para>
	    A final feature allows you to incorporate multiple
	    <script> sections into the header.  Just pass the list of
	    script sections as an array reference. this allows you to
	    specify different source files for different dialects of
	    JavaScript.  Example:
         </para>
         <screen><![CDATA[print $q->start_html(-title=>'The Riddle of the Sphinx',
                     -script=>[
                               { -type => 'text/javascript',
                                 -src      => '/javascript/utilities10.js'
                               },
                               { -type => 'text/javascript',
                                 -src      => '/javascript/utilities11.js'
                               },
                               { -type => 'text/jscript',
                                 -src      => '/javascript/utilities12.js'
                               },
                               { -type => 'text/ecmascript',
                                 -src      => '/javascript/utilities219.js'
                               }
                            ]
                        );]]></screen>
         <para>
	    The option <quote>-language</quote> is a synonym for -type, and is supported
	    for backwad compatibility.
         </para>
         <para>
	    The old-style positional parameters are as follows:
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-f1175ecbd12cad155a774c73f27591af"/><emphasis role="bold">Parameters:</emphasis></term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-072f866177c2c92f6193284d104f55f0"/>1.</term>
                  <listitem>
                     <para>
			The title
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ea059db0464e33f2d3f5909eba69ef6f"/>2.</term>
                  <listitem>
                     <para>
			The author's e-mail address (will create a <link
			rev=<quote>MADE</quote>> tag if present
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-83a967e68594b7b2297284f375998f0f"/>3.</term>
                  <listitem>
                     <para>
			A 'true' flag if you want to include a <base>
			tag in the header.  This helps resolve relative
			addresses to absolute ones when the document is
			moved, but makes the document hierarchy
			non-portable.  Use with care!
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-476589f77d879ee51ddee260f73c5cd8"/>4, 5, 6...</term>
                  <listitem>
                     <para>
			Any other parameters you want to include in the
			<body> tag.  This is a good place to put HTML
			extensions, such as colors and wallpaper patterns.
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
      </section>
      <section id="ID-f51ebea59f1611bb670b8718f3b6a549"><title>ENDING THE HTML DOCUMENT:</title>
         <screen><![CDATA[print end_html]]></screen>
         <para>
	    This ends an HTML document by printing the
	    </body></html> tags.
         </para>
      </section>
      <section id="ID-7ca9d976da68d7f028982bee40af48e5"><title>CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:</title>
         <screen><![CDATA[$myself = self_url;
print q(<a href="$myself">I'm talking to myself.</a>);]]></screen>
         <para>
	    self_url() 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.
         </para>
         <screen><![CDATA[$myself = 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>";]]></screen>
         <para>
	    If you want more control over what's returned, using the
	    <emphasis role="bold">url()</emphasis> method instead.
         </para>
         <para>
	    You can also retrieve the unprocessed query string with
	    query_string():
         </para>
         <screen><![CDATA[$the_string = query_string;]]></screen>
      </section>
      <section id="ID-b8b527fd44041fb987296e18ca8cc27f"><title>OBTAINING THE SCRIPT'S URL</title>
         <screen><![CDATA[$full_url      = url();
$full_url      = url(-full=>1);  #alternative syntax
$relative_url  = url(-relative=>1);
$absolute_url  = url(-absolute=>1);
$url_with_path = url(-path_info=>1);
$url_with_path_and_query = url(-path_info=>1,-query=>1);
$netloc        = url(-base => 1);]]></screen>
         <para>
	    <emphasis role="bold">url()</emphasis> returns the script's URL
	    in a variety of formats.  Called without any arguments, it
	    returns the full form of the URL, including host name and port
	    number
         </para>
         <screen><![CDATA[http://your.host.com/path/to/script.cgi]]></screen>
         <para>
	    You can modify this format with the following named arguments:
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-68119b166750ca0e98d063f3eab03630"/><emphasis role="bold">-absolute</emphasis></term>
                  <listitem>
                     <para>
			If true, produce an absolute URL, e.g.
                     </para>
                     <screen><![CDATA[/path/to/script.cgi]]></screen>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-e3778032c945f9610ab9b4081ef8ca81"/><emphasis role="bold">-relative</emphasis></term>
                  <listitem>
                     <para>
			Produce a relative URL.  This is useful if you want
			to reinvoke your script with different parameters.
			For example:
                     </para>
                     <screen><![CDATA[script.cgi]]></screen>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-1d30859c0578e8cc096576883191be55"/><emphasis role="bold">-full</emphasis></term>
                  <listitem>
                     <para>
			Produce the full URL, exactly as if called without
			any arguments. This overrides the -relative and
			-absolute arguments.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-3461bce8448e6cece10188711d9666d6"/><emphasis role="bold">-path</emphasis> (<emphasis role="bold">-path_info</emphasis>)</term>
                  <listitem>
                     <para>
			Append the additional path information to the URL. 
			This can be combined with <emphasis
			role="bold">-full</emphasis>, <emphasis
			role="bold">-absolute</emphasis> or <emphasis
			role="bold">-relative</emphasis>.  <emphasis
			role="bold">-path_info</emphasis> is provided as a
			synonym.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-321c523a0fc15783b8cc2f24b37d7648"/><emphasis role="bold">-query</emphasis> (<emphasis role="bold">-query_string</emphasis>)</term>
                  <listitem>
                     <para>
			Append the query string to the URL.  This can be
			combined with <emphasis
			role="bold">-full</emphasis>, <emphasis
			role="bold">-absolute</emphasis> or <emphasis
			role="bold">-relative</emphasis>.  <emphasis
			role="bold">-query_string</emphasis> is provided as
			a synonym.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-f83a715505248432f0d36b6e83a3207c"/><emphasis role="bold">-base</emphasis></term>
                  <listitem>
                     <para>
			Generate just the protocol and net location, as in
			http://www.foo.com:8000
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-2848b5704f4fe301dc300e9084f73dd3"/><emphasis role="bold">-rewrite</emphasis></term>
                  <listitem>
                     <para>
			If Apache's mod_rewrite is turned on, then the
			script name and path info probably won't match the
			request that the user sent. Set -rewrite=>1
			(default) to return URLs that match what the user
			sent (the original request URI). Set -rewrite=>0
			to return URLs that match the URL after
			mod_rewrite's rules have run. Because the
			additional path information only makes sense in the
			context of the rewritten URL, -rewrite is set to
			false when you request path info in the URL.
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
      </section>
      <section id="ID-9c86aae6c2528afc0815665602889f88"><title>MIXING POST AND URL PARAMETERS</title>
         <screen><![CDATA[$color = url_param('color');]]></screen>
         <para>
	    It is possible for a script to receive CGI parameters in the
	    URL as well as in the fill-out form by creating a form that
	    POSTs to a URL containing a query string (a <quote>?</quote> mark followed
	    by arguments).  The <emphasis role="bold">param()</emphasis>
	    method will always return the contents of the POSTed fill-out
	    form, ignoring the URL's query string.  To retrieve URL
	    parameters, call the <emphasis
	    role="bold">url_param()</emphasis> method.	Use it in the same
	    way as <emphasis role="bold">param()</emphasis>.  The main
	    difference is that it allows you to read the parameters, but
	    not set them.
         </para>
         <screen><![CDATA[]]></screen>
         <para>
	    Under no circumstances will the contents of the URL query
	    string interfere with similarly-named CGI parameters in POSTed
	    forms.  If you try to mix a URL query string with a form
	    submitted with the GET method, the results will not be what you
	    expect.
         </para>
      </section>
   </section>
   <section id="ID-541105bf945d4340055450f933931ed6"><title>CREATING STANDARD HTML ELEMENTS:</title>
      <para>
	 CGI.pm defines general HTML shortcut methods for most, if not all
	 of the HTML 3 and HTML 4 tags.  HTML shortcuts are named after a
	 single HTML element and return a fragment of HTML text that you
	 can then print or manipulate as you like.  Each shortcut returns a
	 fragment of HTML code that you can append to a string, save to a
	 file, or, most commonly, print out so that it displays in the
	 browser window.
      </para>
      <para>
	 This example shows how to use the HTML methods:
      </para>
      <screen><![CDATA[print $q->blockquote(
                  "Many years ago on the island of",
                  $q->a({href=>"http://crete.org/"},"Crete"),
                  "there lived a Minotaur named",
                  $q->strong("Fred."),
                 ),
    $q->hr;]]></screen>
      <para>
	 This results in the following HTML code (extra newlines have been
	 added for readability):
      </para>
      <screen><![CDATA[<blockquote>
Many years ago on the island of
<a href="http://crete.org/">Crete</a> there lived
a minotaur named <strong>Fred.</strong> 
</blockquote>
<hr>]]></screen>
      <para>
	 If you find the syntax for calling the HTML shortcuts awkward, you
	 can import them into your namespace and dispense with the object
	 syntax completely (see the next section for more details):
      </para>
      <screen><![CDATA[use CGI ':standard';
print blockquote(
   "Many years ago on the island of",
   a({href=>"http://crete.org/"},"Crete"),
   "there lived a minotaur named",
   strong("Fred."),
   ),
   hr;]]></screen>
      <section id="ID-0a1eda4de521a2fe8cad3dfbf7b11ad8"><title>PROVIDING ARGUMENTS TO HTML SHORTCUTS</title>
         <para>
	    The HTML methods will accept zero, one or multiple arguments. 
	    If you provide no arguments, you get a single tag:
         </para>
         <screen><![CDATA[print hr;    #  <hr>]]></screen>
         <para>
	    If you provide one or more string arguments, they are
	    concatenated together with spaces and placed between opening
	    and closing tags:
         </para>
         <screen><![CDATA[print h1("Chapter","1"); # <h1>Chapter 1</h1>"]]></screen>
         <para>
	    If the first argument is a hash reference, then the keys and
	    values of the hash become the HTML tag's attributes:
         </para>
         <screen><![CDATA[print a({-href=>'fred.html',-target=>'_new'},
   "Open a new frame");

<a href="fred.html",target="_new">Open a new frame</a>]]></screen>
         <para>
	    You may dispense with the dashes in front of the attribute
	    names if you prefer:
         </para>
         <screen><![CDATA[print img {src=>'fred.gif',align=>'LEFT'};

<img align="LEFT" src="fred.gif">]]></screen>
         <para>
	    Sometimes an HTML tag attribute has no argument.  For example,
	    ordered lists can be marked as COMPACT.  The syntax for this is
	    an argument that that points to an undef string:
         </para>
         <screen><![CDATA[print ol({compact=>undef},li('one'),li('two'),li('three'));]]></screen>
         <para>
	    Prior to CGI.pm version 2.41, providing an empty ('') string as
	    an attribute argument was the same as providing undef. 
	    However, this has changed in order to accommodate those who
	    want to create tags of the form <img alt="">.  The
	    difference is shown in these two pieces of code:
         </para>
         <screen><![CDATA[CODE                   RESULT
img({alt=>undef})      <img alt>
img({alt=>''})         <img alt="">]]></screen>
      </section>
      <section id="ID-fa4d4e21056bf7c6d8ffaf70fa3e31b6"><title>THE DISTRIBUTIVE PROPERTY OF HTML SHORTCUTS</title>
         <para>
	    One of the cool features of the HTML shortcuts is that they are
	    distributive.  If you give them an argument consisting of a
	    <emphasis role="bold">reference</emphasis> to a list, the tag
	    will be distributed across each element of the list.  For
	    example, here's one way to make an ordered list:
         </para>
         <screen><![CDATA[print ul(
          li({-type=>'disc'},['Sneezy','Doc','Sleepy','Happy'])
        );]]></screen>
         <para>
	    This example will result in HTML output that looks like this:
         </para>
         <screen><![CDATA[<ul>
  <li type="disc">Sneezy</li>
  <li type="disc">Doc</li>
  <li type="disc">Sleepy</li>
  <li type="disc">Happy</li>
</ul>]]></screen>
         <para>
	    This is extremely useful for creating tables.  For example:
         </para>
         <screen><![CDATA[print table({-border=>undef},
        caption('When Should You Eat Your Vegetables?'),
        Tr({-align=>'CENTER',-valign=>'TOP'},
        [
           th(['Vegetable', 'Breakfast','Lunch','Dinner']),
           td(['Tomatoes' , 'no', 'yes', 'yes']),
           td(['Broccoli' , 'no', 'no',  'yes']),
           td(['Onions'   , 'yes','yes', 'yes'])
        ]
        )
     );]]></screen>
      </section>
      <section id="ID-e1ea86ca34e1b960098ed30e8cd0b88e"><title>HTML SHORTCUTS AND LIST INTERPOLATION</title>
         <para>
	    Consider this bit of code:
         </para>
         <screen><![CDATA[print blockquote(em('Hi'),'mom!'));]]></screen>
         <para>
	    It will ordinarily return the string that you probably expect,
	    namely:
         </para>
         <screen><![CDATA[<blockquote><em>Hi</em> mom!</blockquote>]]></screen>
         <para>
	    Note the space between the element <quote>Hi</quote> and the element <quote>mom!</quote>.
	    CGI.pm puts the extra space there using array interpolation,
	    which is controlled by the magic $<quote> variable.  Sometimes this
	    extra space is not what you want, for example, when you are
	    trying to align a series of images.  In this case, you can
	    simply change the value of $</quote> to an empty string.
         </para>
         <screen><![CDATA[{
   local($") = '';
   print blockquote(em('Hi'),'mom!'));
 }]]></screen>
         <para>
	    I suggest you put the code in a block as shown here.  Otherwise
	    the change to $" will affect all subsequent code until you
	    explicitly reset it.
         </para>
      </section>
      <section id="ID-e39d1750d38c698eb9e3a3bb540383a8"><title>NON-STANDARD HTML SHORTCUTS</title>
         <para>
	    A few HTML tags don't follow the standard pattern for various
	    reasons.
         </para>
         <para>
	    <emphasis role="bold">comment()</emphasis> generates an HTML
	    comment ().  Call it like
         </para>
         <screen><![CDATA[print comment('here is my comment');]]></screen>
         <para>
	    Because of conflicts with built-in Perl functions, the
	    following functions begin with initial caps:
         </para>
         <screen><![CDATA[Select
Tr
Link
Delete
Accept
Sub]]></screen>
         <para>
	    In addition, start_html(), end_html(), start_form(),
	    end_form(), start_multipart_form() and all the fill-out form
	    tags are special. See their respective sections.
         </para>
      </section>
      <section id="ID-4353feb9c07fb5f09ceb737ad49d6466"><title>AUTOESCAPING HTML</title>
         <para>
	    By default, all HTML that is emitted by the form-generating
	    functions is passed through a function called escapeHTML():
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-8c7ffa645e8bbc371e62aaf8ab5657ed"/>$escaped_string = escapeHTML("unescaped string");</term>
                  <listitem>
                     <para>
			Escape HTML formatting characters in a string.
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
         <para>
	    Provided that you have specified a character set of ISO-8859-1
	    (the default), the standard HTML escaping rules will be used. 
	    The <quote><</quote> character becomes <quote><</quote>, <quote>></quote> becomes
	    <quote>></quote>, <quote>&</quote> becomes <quote>&</quote>, and the quote
	    character becomes <quote>"</quote>.  In addition, the hexadecimal
	    0x8b and 0x9b characters, which some browsers incorrectly
	    interpret as the left and right angle-bracket characters, are
	    replaced by their numeric character entities (<quote>&#8249</quote> and
	    <quote>&#8250;</quote>).  If you manually change the charset, either by
	    calling the charset() method explicitly or by passing a
	    -charset argument to header(), then <emphasis
	    role="bold">all</emphasis> characters will be replaced by their
	    numeric entities, since CGI.pm has no lookup table for all the
	    possible encodings.
         </para>
         <para>
	    <literal role="code"><![CDATA[escapeHTML()]]></literal> expects
	    the supplied string to be a character string. This means you
	    should Encode::decode data received from <quote>outside</quote> and
	    Encode::encode your strings before sending them back outside.
	    If your source code UTF-8 encoded and you want to upgrade
	    string literals in your source to character strings, you can
	    use <quote>use utf8</quote>. See <citerefentry>
	    <refentrytitle>perlunitut</refentrytitle> </citerefentry>,
	    <citerefentry> <refentrytitle>perlunifaq</refentrytitle>
	    </citerefentry> and <citerefentry>
	    <refentrytitle>perlunicode</refentrytitle> </citerefentry> for
	    more information on how Perl handles the difference between
	    bytes and characters.
         </para>
         <para>
	    The automatic escaping does not apply to other shortcuts, such
	    as h1().  You should call escapeHTML() yourself on untrusted
	    data in order to protect your pages against nasty tricks that
	    people may enter into guestbooks, etc..  To change the
	    character set, use charset(). To turn autoescaping off
	    completely, use autoEscape(0):
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-00f6a23d940a9018bca48ff199f90018"/>$charset = charset([$charset]);</term>
                  <listitem>
                     <para>
			Get or set the current character set.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-52f0c9f48e84e9955d9ea6a2d62d27b0"/>$flag = autoEscape([$flag]);</term>
                  <listitem>
                     <para>
			Get or set the value of the autoescape flag.
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
      </section>
      <section id="ID-0ba9515f0f34657194bfd6c511e7f144"><title>PRETTY-PRINTING HTML</title>
         <para>
	    By default, all the HTML produced by these functions comes out
	    as one long line without carriage returns or indentation. This
	    is yuck, but it does reduce the size of the documents by
	    10-20%.  To get pretty-printed output, please use
	    <citerefentry> <refentrytitle>CGI::Pretty</refentrytitle>
	    </citerefentry>, a subclass contributed by Brian Paulsen.
         </para>
      </section>
   </section>
   <section id="ID-c4c3fdfae693aebca125b105a3586cd3"><title>CREATING FILL-OUT FORMS:</title>
      <para>
	 <emphasis role="italic">General note</emphasis>  The various
	 form-creating methods all return strings to the caller, containing
	 the tag or tags that will create the requested form element.  You
	 are responsible for actually printing out these strings. It's set
	 up this way so that you can place formatting tags around the form
	 elements.
      </para>
      <para>
	 <emphasis role="italic">Another note</emphasis> The default values
	 that you specify for the forms are only used the <emphasis
	 role="bold">first</emphasis> time the script is invoked (when
	 there is no query string).  On subsequent invocations of the
	 script (when there is a query string), the former values are used
	 even if they are blank.
      </para>
      <para>
	 If you want to change the value of a field from its previous
	 value, you have two choices:
      </para>
      <para>
	 (1) call the param() method to set it.
      </para>
      <para>
	 (2) use the -override (alias -force) parameter (a new feature in
	 version 2.15). This forces the default value to be used,
	 regardless of the previous value:
      </para>
      <screen><![CDATA[print textfield(-name=>'field_name',
                        -default=>'starting value',
                        -override=>1,
                        -size=>50,
                        -maxlength=>80);]]></screen>
      <para>
	 <emphasis role="italic">Yet another note</emphasis> By default,
	 the text and labels of form elements are escaped according to HTML
	 rules.  This means that you can safely use <quote><CLICK ME></quote> as
	 the label for a button.  However, it also interferes with your
	 ability to incorporate special HTML character sequences, such as
	 Á, into your fields.  If you wish to turn off automatic
	 escaping, call the autoEscape() method with a false value
	 immediately after creating the CGI object:
      </para>
      <screen><![CDATA[$query = CGI->new;
$query->autoEscape(0);]]></screen>
      <para>
	 Note that autoEscape() is exclusively used to effect the behavior
	 of how some CGI.pm HTML generation fuctions handle escaping.
	 Calling escapeHTML() explicitly will always escape the HTML.
      </para>
      <para>
	 <emphasis role="italic">A Lurking Trap!</emphasis> Some of the
	 form-element generating methods return multiple tags.	In a scalar
	 context, the tags will be concatenated together with spaces, or
	 whatever is the current value of the $" global.  In a list
	 context, the methods will return a list of elements, allowing you
	 to modify them if you wish.  Usually you will not notice this
	 behavior, but beware of this:
      </para>
      <screen><![CDATA[printf("%s\n",end_form())]]></screen>
      <para>
	 end_form() produces several tags, and only the first of them will
	 be printed because the format only expects one value.
      </para>
      <para>
	 <p>
      </para>
      <screen><![CDATA[]]></screen>
      <section id="ID-f348456cbecc02c81c474be927ec43ef"><title>CREATING AN ISINDEX TAG</title>
         <screen><![CDATA[print isindex(-action=>$action);

-or-

print isindex($action);]]></screen>
         <para>
	    Prints out an <isindex> tag.	Not very exciting.  The
	    parameter -action specifies the URL of the script to process
	    the query.	The default is to process the query with the
	    current script.
         </para>
      </section>
      <section id="ID-49a5f91c8e86df4375c947c9711c1bb3"><title>STARTING AND ENDING A FORM</title>
         <screen><![CDATA[print start_form(-method=>$method,
                -action=>$action,
                -enctype=>$encoding);
  <... various form stuff ...>
print end_form;

-or-

print start_form($method,$action,$encoding);
  <... various form stuff ...>
print end_form;]]></screen>
         <para>
	    start_form() will return a <form> tag with the optional
	    method, action and form encoding that you specify.	The
	    defaults are:
         </para>
         <screen><![CDATA[method: POST
action: this script
enctype: application/x-www-form-urlencoded for non-XHTML
         multipart/form-data for XHTML, see mulitpart/form-data below.]]></screen>
         <para>
	    end_form() returns the closing </form> tag.
         </para>
         <para>
	    Start_form()'s enctype argument tells the browser how to
	    package the various fields of the form before sending the form
	    to the server.  Two values are possible:
         </para>
         <para>
	    <emphasis role="bold">Note:</emphasis> These methods were
	    previously named startform() and endform(). These methods are
	    now DEPRECATED. Please use start_form() and end_form() instead.
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-7449a04f63901194f1b889c5dce4fa55"/><emphasis role="bold">application/x-www-form-urlencoded</emphasis></term>
                  <listitem>
                     <para>
			This is the older type of encoding.  It is
			compatible with many CGI scripts and is suitable
			for short fields containing text data.	For your
			convenience, CGI.pm stores the name of this
			encoding type in <emphasis
			role="bold">&CGI::URL_ENCODED</emphasis>.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-386be8b6dcf2fd4180822c55cbc62101"/><emphasis role="bold">multipart/form-data</emphasis></term>
                  <listitem>
                     <para>
			This is the newer type of encoding. It is suitable
			for forms that contain very large fields or that
			are intended for transferring binary data.  Most
			importantly, it enables the <quote>file upload</quote> feature. 
			For your convenience, CGI.pm stores the name of
			this encoding type in <emphasis
			role="bold">&CGI::MULTIPART</emphasis>
                     </para>
                     <para>
			Forms that use this type of encoding are not easily
			interpreted by CGI scripts unless they use CGI.pm
			or another library designed to handle them.
                     </para>
                     <para>
			If XHTML is activated (the default), then forms
			will be automatically created using this type of
			encoding.
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
         <para>
	    The start_form() method uses the older form of encoding by
	    default unless XHTML is requested.	If you want to use the
	    newer form of encoding by default, you can call <emphasis
	    role="bold">start_multipart_form()</emphasis> instead of
	    <emphasis role="bold">start_form()</emphasis>.  The method
	    <emphasis role="bold">end_multipart_form()</emphasis> is an
	    alias to <emphasis role="bold">end_form()</emphasis>.
         </para>
         <para>
	    JAVASCRIPTING: The <emphasis role="bold">-name</emphasis> and
	    <emphasis role="bold">-onSubmit</emphasis> parameters are
	    provided for use with JavaScript.  The -name parameter gives
	    the form a name so that it can be identified and manipulated by
	    JavaScript functions.  -onSubmit should point to a JavaScript
	    function that will be executed just before the form is
	    submitted to your server.  You can use this opportunity to
	    check the contents of the form for consistency and
	    completeness.  If you find something wrong, you can put up an
	    alert box or maybe fix things up yourself.	You can abort the
	    submission by returning false from this function.
         </para>
         <para>
	    Usually the bulk of JavaScript functions are defined in a
	    <script> block in the HTML header and -onSubmit points to
	    one of these function call.  See start_html() for details.
         </para>
      </section>
      <section id="ID-b164906015a1c299dabb41b79b98ecc8"><title>FORM ELEMENTS</title>
         <para>
	    After starting a form, you will typically create one or more
	    textfields, popup menus, radio groups and other form elements. 
	    Each of these elements takes a standard set of named arguments.
	     Some elements also have optional arguments.  The standard
	    arguments are as follows:
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-01bc5d14a3939c7992df9ef5c73d7a99"/><emphasis role="bold">-name</emphasis></term>
                  <listitem>
                     <para>
			The name of the field. After submission this name
			can be used to retrieve the field's value using the
			param() method.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ae80760a5bf1d6ede7ec316507a0e715"/><emphasis role="bold">-value</emphasis>, <emphasis role="bold">-values</emphasis></term>
                  <listitem>
                     <para>
			The initial value of the field which will be
			returned to the script after form submission.  Some
			form elements, such as text fields, take a single
			scalar -value argument. Others, such as popup
			menus, take a reference to an array of values. The
			two arguments are synonyms.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ea3d9ea3cfb7429d9b1ae1da4620edb6"/><emphasis role="bold">-tabindex</emphasis></term>
                  <listitem>
                     <para>
			A numeric value that sets the order in which the
			form element receives focus when the user presses
			the tab key. Elements with lower values receive
			focus first.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-437b8b98379a336cacee38f21459ae7c"/><emphasis role="bold">-id</emphasis></term>
                  <listitem>
                     <para>
			A string identifier that can be used to identify
			this element to JavaScript and DHTML.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-cf87957c088daa310a9a49038d623eac"/><emphasis role="bold">-override</emphasis></term>
                  <listitem>
                     <para>
			A boolean, which, if true, forces the element to
			take on the value specified by <emphasis
			role="bold">-value</emphasis>, overriding the
			sticky behavior described earlier for the <emphasis
			role="bold">-nosticky</emphasis> pragma.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-c77d17a0c6d79ee7415b25b4ec4b25db"/><emphasis role="bold">-onChange</emphasis>, <emphasis role="bold">-onFocus</emphasis>, <emphasis role="bold">-onBlur</emphasis>, <emphasis role="bold">-onMouseOver</emphasis>, <emphasis role="bold">-onMouseOut</emphasis>, <emphasis role="bold">-onSelect</emphasis></term>
                  <listitem>
                     <para>
			These are used to assign JavaScript event handlers.
			See the JavaScripting section for more details.
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
         <para>
	    Other common arguments are described in the next section. In
	    addition to these, all attributes described in the HTML
	    specifications are supported.
         </para>
      </section>
      <section id="ID-9fc2697d835f3023a2898d475e8c5daf"><title>CREATING A TEXT FIELD</title>
         <screen><![CDATA[print textfield(-name=>'field_name',
                -value=>'starting value',
                -size=>50,
                -maxlength=>80);
    -or-

print textfield('field_name','starting value',50,80);]]></screen>
         <para>
	    textfield() will return a text input field.
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-77fe8585c636102919d6757d06e8fdca"/><emphasis role="bold">Parameters</emphasis></term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-072f866177c2c92f6193284d104f55f0"/>1.</term>
                  <listitem>
                     <para>
			The first parameter is the required name for the
			field (-name).
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ea059db0464e33f2d3f5909eba69ef6f"/>2.</term>
                  <listitem>
                     <para>
			The optional second parameter is the default
			starting value for the field contents (-value,
			formerly known as -default).
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-83a967e68594b7b2297284f375998f0f"/>3.</term>
                  <listitem>
                     <para>
			The optional third parameter is the size of the
			field in characters (-size).
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-64cc202599711665deba33ef3ea21d6a"/>4.</term>
                  <listitem>
                     <para>
			The optional fourth parameter is the maximum number
			of characters the field will accept (-maxlength).
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
         <para>
	    As with all these methods, the field will be initialized with
	    its previous contents from earlier invocations of the script.
	    When the form is processed, the value of the text field can be
	    retrieved with:
         </para>
         <screen><![CDATA[$value = param('foo');]]></screen>
         <para>
	    If you want to reset it from its initial value after the script
	    has been called once, you can do so like this:
         </para>
         <screen><![CDATA[param('foo',"I'm taking over this value!");]]></screen>
      </section>
      <section id="ID-64af6ea2f22c3f19afabaa3d9f114e9d"><title>CREATING A BIG TEXT FIELD</title>
         <screen><![CDATA[print textarea(-name=>'foo',
                       -default=>'starting value',
                       -rows=>10,
                       -columns=>50);

-or

print textarea('foo','starting value',10,50);]]></screen>
         <para>
	    textarea() is just like textfield, but it allows you to specify
	    rows and columns for a multiline text entry box.  You can
	    provide a starting value for the field, which can be long and
	    contain multiple lines.
         </para>
      </section>
      <section id="ID-822e56d02e3d46b7170f92a5e271a5ad"><title>CREATING A PASSWORD FIELD</title>
         <screen><![CDATA[print password_field(-name=>'secret',
                             -value=>'starting value',
                             -size=>50,
                             -maxlength=>80);
     -or-

print password_field('secret','starting value',50,80);]]></screen>
         <para>
	    password_field() is identical to textfield(), except that its
	    contents will be starred out on the web page.
         </para>
      </section>
      <section id="ID-fcd2ba40031d6b92707b4a00a89d5931"><title>CREATING A FILE UPLOAD FIELD</title>
         <screen><![CDATA[print filefield(-name=>'uploaded_file',
                        -default=>'starting value',
                        -size=>50,
                        -maxlength=>80);
    -or-

print filefield('uploaded_file','starting value',50,80);]]></screen>
         <para>
	    filefield() will return a file upload field. In order to take
	    full advantage of this <emphasis role="italic">you must use the
	    new multipart encoding scheme</emphasis> for the form.  You can
	    do this either by calling <emphasis
	    role="bold">start_form()</emphasis> with an encoding type of
	    <emphasis role="bold">&CGI::MULTIPART</emphasis>, or by calling
	    the new method <emphasis
	    role="bold">start_multipart_form()</emphasis> instead of
	    vanilla <emphasis role="bold">start_form()</emphasis>.
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-77fe8585c636102919d6757d06e8fdca"/><emphasis role="bold">Parameters</emphasis></term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-072f866177c2c92f6193284d104f55f0"/>1.</term>
                  <listitem>
                     <para>
			The first parameter is the required name for the
			field (-name).
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ea059db0464e33f2d3f5909eba69ef6f"/>2.</term>
                  <listitem>
                     <para>
			The optional second parameter is the starting value
			for the field contents to be used as the default
			file name (-default).
                     </para>
                     <para>
			For security reasons, browsers don't pay any
			attention to this field, and so the starting value
			will always be blank.  Worse, the field loses its
			<quote>sticky</quote> behavior and forgets its previous
			contents.  The starting value field is called for
			in the HTML specification, however, and possibly
			some browser will eventually provide support for
			it.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-83a967e68594b7b2297284f375998f0f"/>3.</term>
                  <listitem>
                     <para>
			The optional third parameter is the size of the
			field in characters (-size).
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-64cc202599711665deba33ef3ea21d6a"/>4.</term>
                  <listitem>
                     <para>
			The optional fourth parameter is the maximum number
			of characters the field will accept (-maxlength).
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
         <para>
	    JAVASCRIPTING: The <emphasis role="bold">-onChange</emphasis>,
	    <emphasis role="bold">-onFocus</emphasis>, <emphasis
	    role="bold">-onBlur</emphasis>, <emphasis
	    role="bold">-onMouseOver</emphasis>, <emphasis
	    role="bold">-onMouseOut</emphasis> and <emphasis
	    role="bold">-onSelect</emphasis> parameters are recognized. 
	    See textfield() for details.
         </para>
      </section>
      <section id="ID-9f73a3824fcb2afe713a813e7c5302dc"><title>PROCESSING A FILE UPLOAD FIELD</title>
         <section id="ID-c6ec29ad718b95d23561385d8f7a0daa"><title>Basics</title>
            <para>
	       When the form is processed, you can retrieve an
	       <citerefentry> <refentrytitle>IO::Handle</refentrytitle>
	       </citerefentry> compatibile handle for a file upload field
	       like this:
            </para>
            <screen><![CDATA[$lightweight_fh  = $q->upload('field_name');

# undef may be returned if it's not a valid file handle
if (defined $lightweight_fh) {
  # Upgrade the handle to one compatible with IO::Handle:
  my $io_handle = $lightweight_fh->handle;

open (OUTFILE,'>>','/usr/local/web/users/feedback');
  while ($bytesread = $io_handle->read($buffer,1024)) {
    print OUTFILE $buffer;
  }
}]]></screen>
            <para>
	       In a list context, upload() will return an array of
	       filehandles. This makes it possible to process forms that
	       use the same name for multiple upload fields.
            </para>
            <para>
	       If you want the entered file name for the file, you can just
	       call param():
            </para>
            <screen><![CDATA[$filename = $q->param('field_name');]]></screen>
            <para>
	       Different browsers will return slightly different things for
	       the name.  Some browsers return the filename only.  Others
	       return the full path to the file, using the path conventions
	       of the user's machine. Regardless, the name returned is
	       always the name of the file on the <emphasis
	       role="italic">user's</emphasis> machine, and is unrelated to
	       the name of the temporary file that CGI.pm creates during
	       upload spooling (see below).
            </para>
            <para>
	       When a file is uploaded the browser usually sends along some
	       information along with it in the format of headers.  The
	       information usually includes the MIME content type. To
	       retrieve this information, call uploadInfo().  It returns a
	       reference to a hash containing all the document headers.
            </para>
            <screen><![CDATA[$filename = $q->param('uploaded_file');
$type = $q->uploadInfo($filename)->{'Content-Type'};
unless ($type eq 'text/html') {
 die "HTML FILES ONLY!";
}]]></screen>
            <para>
	       If you are using a machine that recognizes <quote>text</quote> and
	       <quote>binary</quote> data modes, be sure to understand when and how to
	       use them (see the Camel book). Otherwise you may find that
	       binary files are corrupted during file uploads.
            </para>
         </section>
         <section id="ID-29c7baa005bda6e5fcf3547093097336"><title>Accessing the temp files directly</title>
            <para>
	       When processing an uploaded file, CGI.pm creates a temporary
	       file on your hard disk and passes you a file handle to that
	       file. After you are finished with the file handle, CGI.pm
	       unlinks (deletes) the temporary file. If you need to you can
	       access the temporary file directly. You can access the temp
	       file for a file upload by passing the file name to the
	       tmpFileName() method:
            </para>
            <screen><![CDATA[$filename = $query->param('uploaded_file');
$tmpfilename = $query->tmpFileName($filename);]]></screen>
            <para>
	       The temporary file will be deleted automatically when your
	       program exits unless you manually rename it. On some
	       operating systems (such as Windows NT), you will need to
	       close the temporary file's filehandle before your program
	       exits. Otherwise the attempt to delete the temporary file
	       will fail.
            </para>
         </section>
         <section id="ID-b47d682023872345c378f7230fbd2aa3"><title>Handling interrupted file uploads</title>
            <para>
	       There are occasionally problems involving parsing the
	       uploaded file. This usually happens when the user presses
	       <quote>Stop</quote> before the upload is finished.  In this case, CGI.pm
	       will return undef for the name of the uploaded file and set
	       <emphasis role="italic">cgi_error()</emphasis> to the string
	       <quote>400 Bad request (malformed multipart POST)</quote>.  This error
	       message is designed so that you can incorporate it into a
	       status code to be sent to the browser. Example:
            </para>
            <screen><![CDATA[$file = $q->upload('uploaded_file');
if (!$file && $q->cgi_error) {
   print $q->header(-status=>$q->cgi_error);
   exit 0;
}]]></screen>
            <para>
	       You are free to create a custom HTML page to complain about
	       the error, if you wish.
            </para>
         </section>
         <section id="ID-e32a4913a86cde20ccfb4d4652fa617e"><title>Progress bars for file uploads and avoiding temp files</title>
            <para>
	       CGI.pm gives you low-level access to file upload management
	       through a file upload hook. You can use this feature to
	       completely turn off the temp file storage of file uploads,
	       or potentially write your own file upload progess meter.
            </para>
            <para>
	       This is much like the UPLOAD_HOOK facility available in
	       <citerefentry>
	       <refentrytitle>Apache::Request</refentrytitle>
	       </citerefentry>, with the exception that the first argument
	       to the callback is an <citerefentry>
	       <refentrytitle>Apache::Upload</refentrytitle>
	       </citerefentry> object, here it's the remote filename.
            </para>
            <screen><![CDATA[$q = CGI->new(\&hook [,$data [,$use_tempfile]]);

sub hook {
       my ($filename, $buffer, $bytes_read, $data) = @_;
       print  "Read $bytes_read bytes of $filename\n";
}]]></screen>
            <para>
	       The <literal role="code"><![CDATA[$data]]></literal> field
	       is optional; it lets you pass configuration information
	       (e.g. a database handle) to your hook callback.
            </para>
            <para>
	       The <literal role="code"><![CDATA[$use_tempfile]]></literal>
	       field is a flag that lets you turn on and off CGI.pm's use
	       of a temporary disk-based file during file upload. If you
	       set this to a FALSE value (default true) then
	       $q->param('uploaded_file') will no longer work, and the
	       only way to get at the uploaded data is via the hook you
	       provide.
            </para>
            <para>
	       If using the function-oriented interface, call the
	       CGI::upload_hook() method before calling param() or any
	       other CGI functions:
            </para>
            <screen><![CDATA[CGI::upload_hook(\&hook [,$data [,$use_tempfile]]);]]></screen>
            <para>
	       This method is not exported by default.	You will have to
	       import it explicitly if you wish to use it without the CGI::
	       prefix.
            </para>
         </section>
         <section id="ID-9bd9ce17c138800f87cd7889cbf5fdeb"><title>Troubleshooting file uploads on Windows</title>
            <para>
	       If you are using CGI.pm on a Windows platform and find that
	       binary files get slightly larger when uploaded but that text
	       files remain the same, then you have forgotten to activate
	       binary mode on the output filehandle.  Be sure to call
	       binmode() on any handle that you create to write the
	       uploaded file to disk.
            </para>
         </section>
         <section id="ID-f0471f72b7831741d8b602459d8bdb27"><title>Older ways to process file uploads</title>
            <para>
	       ( This section is here for completeness. if you are building
	       a new application with CGI.pm, you can skip it. )
            </para>
            <para>
	       The original way to process file uploads with CGI.pm was to
	       use param(). The value it returns has a dual nature as both
	       a file name and a lightweight filehandle. This dual nature
	       is problematic if you following the recommended practice of
	       having <literal role="code"><![CDATA[use strict]]></literal>
	       in your code. Perl will complain when you try to use a
	       string as a filehandle.	More seriously, it is possible for
	       the remote user to type garbage into the upload field, in
	       which case what you get from param() is not a filehandle at
	       all, but a string.
            </para>
            <para>
	       To solve this problem the upload() method was added, which
	       always returns a lightweight filehandle. This generally
	       works well, but will have trouble interoperating with some
	       other modules because the file handle is not derived from
	       <citerefentry> <refentrytitle>IO::Handle</refentrytitle>
	       </citerefentry>. So that brings us to current recommedation
	       given above, which is to call the handle() method on the
	       file handle returned by upload(). That upgrades the handle
	       to an IO::Handle. It's a big win for compatibility for a
	       small penalty of loading IO::Handle the first time you call
	       it.
            </para>
            <screen><![CDATA[]]></screen>
         </section>
      </section>
      <section id="ID-adfbfdb3fb58403992f9d6c734013e08"><title>CREATING A POPUP MENU</title>
         <screen><![CDATA[print popup_menu('menu_name',
                         ['eenie','meenie','minie'],
                         'meenie');

-or-

%labels = ('eenie'=>'your first choice',
           'meenie'=>'your second choice',
           'minie'=>'your third choice');
%attributes = ('eenie'=>{'class'=>'class of first choice'});
print popup_menu('menu_name',
                         ['eenie','meenie','minie'],
       'meenie',\%labels,\%attributes);

-or (named parameter style)-

print popup_menu(-name=>'menu_name',
                         -values=>['eenie','meenie','minie'],
                         -default=>['meenie','minie'],
       -labels=>\%labels,
       -attributes=>\%attributes);]]></screen>
         <para>
	    popup_menu() creates a menu.
         </para>
         <para>
            <orderedlist numeration="arabic">
               <listitem>
                  <para>
		     The required first argument is the menu's name
		     (-name).
                  </para>
               </listitem>
               <listitem>
                  <para>
		     The required second argument (-values) is an array
		     <emphasis role="bold">reference</emphasis> containing
		     the list of menu items in the menu.  You can pass the
		     method an anonymous array, as shown in the example, or
		     a reference to a named array, such as <quote>\@foo</quote>.
                  </para>
               </listitem>
               <listitem>
                  <para>
		     The optional third parameter (-default) is the name of
		     the default menu choice.  If not specified, the first
		     item will be the default. The values of the previous
		     choice will be maintained across queries. Pass an
		     array reference to select multiple defaults.
                  </para>
               </listitem>
               <listitem>
                  <para>
		     The optional fourth parameter (-labels) is provided
		     for people who want to use different values for the
		     user-visible label inside the popup menu and the value
		     returned to your script.  It's a pointer to an hash
		     relating menu values to user-visible labels.  If you
		     leave this parameter blank, the menu values will be
		     displayed by default.  (You can also leave a label
		     undefined if you want to).
                  </para>
               </listitem>
               <listitem>
                  <para>
		     The optional fifth parameter (-attributes) is provided
		     to assign any of the common HTML attributes to an
		     individual menu item. It's a pointer to a hash
		     relating menu values to another hash with the
		     attribute's name as the key and the attribute's value
		     as the value.
                  </para>
               </listitem>
            </orderedlist>
         </para>
         <para>
	    When the form is processed, the selected value of the popup
	    menu can be retrieved using:
         </para>
         <screen><![CDATA[$popup_menu_value = param('menu_name');]]></screen>
      </section>
      <section id="ID-0f2b47e439bfe6b99fecb4aa4dd2ea0e"><title>CREATING AN OPTION GROUP</title>
         <para>
	    Named parameter style
         </para>
         <screen><![CDATA[print popup_menu(-name=>'menu_name',
                -values=>[qw/eenie meenie minie/,
                          optgroup(-name=>'optgroup_name',
                                           -values => ['moe','catch'],
                                           -attributes=>{'catch'=>{'class'=>'red'}})],
                -labels=>{'eenie'=>'one',
                          'meenie'=>'two',
                          'minie'=>'three'},
                -default=>'meenie');

Old style
print popup_menu('menu_name',
                ['eenie','meenie','minie',
                 optgroup('optgroup_name', ['moe', 'catch'],
                                 {'catch'=>{'class'=>'red'}})],'meenie',
                {'eenie'=>'one','meenie'=>'two','minie'=>'three'});]]></screen>
         <para>
	    optgroup() creates an option group within a popup menu.
         </para>
         <para>
            <orderedlist numeration="arabic">
               <listitem>
                  <para>
		     The required first argument (<emphasis
		     role="bold">-name</emphasis>) is the label attribute
		     of the optgroup and is <emphasis
		     role="bold">not</emphasis> inserted in the parameter
		     list of the query.
                  </para>
               </listitem>
               <listitem>
                  <para>
		     The required second argument (<emphasis
		     role="bold">-values</emphasis>)  is an array reference
		     containing the list of menu items in the menu.  You
		     can pass the method an anonymous array, as shown in
		     the example, or a reference to a named array, such as
		     \@foo.  If you pass a HASH reference, the keys will be
		     used for the menu values, and the values will be used
		     for the menu labels (see -labels below).
                  </para>
               </listitem>
               <listitem>
                  <para>
		     The optional third parameter (<emphasis
		     role="bold">-labels</emphasis>) allows you to pass a
		     reference to a hash containing user-visible labels for
		     one or more of the menu items.  You can use this when
		     you want the user to see one menu string, but have the
		     browser return your program a different one. If you
		     don't specify this, the value string will be used
		     instead (<quote>eenie</quote>, <quote>meenie</quote> and <quote>minie</quote> in this
		     example).	This is equivalent to using a hash
		     reference for the -values parameter.
                  </para>
               </listitem>
               <listitem>
                  <para>
		     An optional fourth parameter (<emphasis
		     role="bold">-labeled</emphasis>) can be set to a true
		     value and indicates that the values should be used as
		     the label attribute for each option element within the
		     optgroup.
                  </para>
               </listitem>
               <listitem>
                  <para>
		     An optional fifth parameter (-novals) can be set to a
		     true value and indicates to suppress the val attribute
		     in each option element within the optgroup.
                  </para>
                  <para>
		     See the discussion on optgroup at W3C
		     (http://www.w3.org/TR/REC-html40/interact/forms.html#edef-OPTGROUP)
		     for details.
                  </para>
               </listitem>
               <listitem>
                  <para>
		     An optional sixth parameter (-attributes) is provided
		     to assign any of the common HTML attributes to an
		     individual menu item. It's a pointer to a hash
		     relating menu values to another hash with the
		     attribute's name as the key and the attribute's value
		     as the value.
                  </para>
               </listitem>
            </orderedlist>
         </para>
      </section>
      <section id="ID-5d9cfcf5ac08fb779a793726db579b85"><title>CREATING A SCROLLING LIST</title>
         <screen><![CDATA[print scrolling_list('list_name',
                             ['eenie','meenie','minie','moe'],
     ['eenie','moe'],5,'true',{'moe'=>{'class'=>'red'}});
   -or-

print scrolling_list('list_name',
                             ['eenie','meenie','minie','moe'],
                             ['eenie','moe'],5,'true',
     \%labels,%attributes);

-or-

print scrolling_list(-name=>'list_name',
                             -values=>['eenie','meenie','minie','moe'],
                             -default=>['eenie','moe'],
                             -size=>5,
                             -multiple=>'true',
     -labels=>\%labels,
     -attributes=>\%attributes);]]></screen>
         <para>
	    scrolling_list() creates a scrolling list.
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-f1175ecbd12cad155a774c73f27591af"/><emphasis role="bold">Parameters:</emphasis></term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-072f866177c2c92f6193284d104f55f0"/>1.</term>
                  <listitem>
                     <para>
			The first and second arguments are the list name
			(-name) and values (-values).  As in the popup
			menu, the second argument should be an array
			reference.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ea059db0464e33f2d3f5909eba69ef6f"/>2.</term>
                  <listitem>
                     <para>
			The optional third argument (-default) can be
			either a reference to a list containing the values
			to be selected by default, or can be a single value
			to select.  If this argument is missing or
			undefined, then nothing is selected when the list
			first appears.	In the named parameter version, you
			can use the synonym <quote>-defaults</quote> for this parameter.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-83a967e68594b7b2297284f375998f0f"/>3.</term>
                  <listitem>
                     <para>
			The optional fourth argument is the size of the
			list (-size).
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-64cc202599711665deba33ef3ea21d6a"/>4.</term>
                  <listitem>
                     <para>
			The optional fifth argument can be set to true to
			allow multiple simultaneous selections (-multiple).
			 Otherwise only one selection will be allowed at a
			time.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-3ee76aa88c81bc1db8185d0bb7e19a78"/>5.</term>
                  <listitem>
                     <para>
			The optional sixth argument is a pointer to a hash
			containing long user-visible labels for the list
			items (-labels). If not provided, the values will
			be displayed.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-52c3161e1f47cf3c836673d8e16784bf"/>6.</term>
                  <listitem>
                     <para>
			The optional sixth parameter (-attributes) is
			provided to assign any of the common HTML
			attributes to an individual menu item. It's a
			pointer to a hash relating menu values to another
			hash with the attribute's name as the key and the
			attribute's value as the value.
                     </para>
                     <para>
			When this form is processed, all selected list
			items will be returned as a list under the
			parameter name 'list_name'.  The values of the
			selected items can be retrieved with:
                     </para>
                     <screen><![CDATA[@selected = param('list_name');]]></screen>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
      </section>
      <section id="ID-05e7b7124508172da3592d06804fc6d9"><title>CREATING A GROUP OF RELATED CHECKBOXES</title>
         <screen><![CDATA[print checkbox_group(-name=>'group_name',
                             -values=>['eenie','meenie','minie','moe'],
                             -default=>['eenie','moe'],
                             -linebreak=>'true',
                             -disabled => ['moe'],
     -labels=>\%labels,
     -attributes=>\%attributes);

print checkbox_group('group_name',
                             ['eenie','meenie','minie','moe'],
     ['eenie','moe'],'true',\%labels,
     {'moe'=>{'class'=>'red'}});

HTML3-COMPATIBLE BROWSERS ONLY:

print checkbox_group(-name=>'group_name',
                             -values=>['eenie','meenie','minie','moe'],
                             -rows=2,-columns=>2);

]]></screen>
         <para>
	    checkbox_group() creates a list of checkboxes that are related
	    by the same name.
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-f1175ecbd12cad155a774c73f27591af"/><emphasis role="bold">Parameters:</emphasis></term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-072f866177c2c92f6193284d104f55f0"/>1.</term>
                  <listitem>
                     <para>
			The first and second arguments are the checkbox
			name and values, respectively (-name and -values). 
			As in the popup menu, the second argument should be
			an array reference.  These values are used for the
			user-readable labels printed next to the checkboxes
			as well as for the values passed to your script in
			the query string.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ea059db0464e33f2d3f5909eba69ef6f"/>2.</term>
                  <listitem>
                     <para>
			The optional third argument (-default) can be
			either a reference to a list containing the values
			to be checked by default, or can be a single value
			to checked.  If this argument is missing or
			undefined, then nothing is selected when the list
			first appears.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-83a967e68594b7b2297284f375998f0f"/>3.</term>
                  <listitem>
                     <para>
			The optional fourth argument (-linebreak) can be
			set to true to place line breaks between the
			checkboxes so that they appear as a vertical list. 
			Otherwise, they will be strung together on a
			horizontal line.
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
         <screen><![CDATA[]]></screen>
         <para>
	    The optional <emphasis role="bold">-labels</emphasis> argument
	    is a pointer to a hash relating the checkbox values to the
	    user-visible labels that will be printed next to them.  If not
	    provided, the values will be used as the default.
         </para>
         <screen><![CDATA[]]></screen>
         <para>
	    The optional parameters <emphasis role="bold">-rows</emphasis>,
	    and <emphasis role="bold">-columns</emphasis> cause
	    checkbox_group() to return an HTML3 compatible table containing
	    the checkbox group formatted with the specified number of rows
	    and columns.  You can provide just the -columns parameter if
	    you wish; checkbox_group will calculate the correct number of
	    rows for you.
         </para>
         <para>
	    The option <emphasis role="bold">-disabled</emphasis> takes an
	    array of checkbox values and disables them by greying them out
	    (this may not be supported by all browsers).
         </para>
         <para>
	    The optional <emphasis role="bold">-attributes</emphasis>
	    argument is provided to assign any of the common HTML
	    attributes to an individual menu item. It's a pointer to a hash
	    relating menu values to another hash with the attribute's name
	    as the key and the attribute's value as the value.
         </para>
         <para>
	    The optional <emphasis role="bold">-tabindex</emphasis>
	    argument can be used to control the order in which radio
	    buttons receive focus when the user presses the tab button.  If
	    passed a scalar numeric value, the first element in the group
	    will receive this tab index and subsequent elements will be
	    incremented by one.  If given a reference to an array of radio
	    button values, then the indexes will be jiggered so that the
	    order specified in the array will correspond to the tab order. 
	    You can also pass a reference to a hash in which the hash keys
	    are the radio button values and the values are the tab indexes
	    of each button.  Examples:
         </para>
         <screen><![CDATA[-tabindex => 100    #  this group starts at index 100 and counts up
-tabindex => ['moe','minie','eenie','meenie']  # tab in this order
-tabindex => {meenie=>100,moe=>101,minie=>102,eenie=>200} # tab in this order]]></screen>
         <para>
	    The optional <emphasis role="bold">-labelattributes</emphasis>
	    argument will contain attributes attached to the <label>
	    element that surrounds each button.
         </para>
         <para>
	    When the form is processed, all checked boxes will be returned
	    as a list under the parameter name 'group_name'.  The values of
	    the <quote>on</quote> checkboxes can be retrieved with:
         </para>
         <screen><![CDATA[@turned_on = param('group_name');]]></screen>
         <para>
	    The value returned by checkbox_group() is actually an array of
	    button elements.  You can capture them and use them within
	    tables, lists, or in other creative ways:
         </para>
         <screen><![CDATA[@h = checkbox_group(-name=>'group_name',-values=>\@values);
&use_in_creative_way(@h);]]></screen>
      </section>
      <section id="ID-811442639a7415f90e63d73561887edd"><title>CREATING A STANDALONE CHECKBOX</title>
         <screen><![CDATA[print checkbox(-name=>'checkbox_name',
                       -checked=>1,
                       -value=>'ON',
                       -label=>'CLICK ME');

-or-

print checkbox('checkbox_name','checked','ON','CLICK ME');]]></screen>
         <para>
	    checkbox() is used to create an isolated checkbox that isn't
	    logically related to any others.
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-f1175ecbd12cad155a774c73f27591af"/><emphasis role="bold">Parameters:</emphasis></term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-072f866177c2c92f6193284d104f55f0"/>1.</term>
                  <listitem>
                     <para>
			The first parameter is the required name for the
			checkbox (-name).  It will also be used for the
			user-readable label printed next to the checkbox.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ea059db0464e33f2d3f5909eba69ef6f"/>2.</term>
                  <listitem>
                     <para>
			The optional second parameter (-checked) specifies
			that the checkbox is turned on by default. 
			Synonyms are -selected and -on.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-83a967e68594b7b2297284f375998f0f"/>3.</term>
                  <listitem>
                     <para>
			The optional third parameter (-value) specifies the
			value of the checkbox when it is checked.  If not
			provided, the word <quote>on</quote> is assumed.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-64cc202599711665deba33ef3ea21d6a"/>4.</term>
                  <listitem>
                     <para>
			The optional fourth parameter (-label) is the
			user-readable label to be attached to the checkbox.
			 If not provided, the checkbox name is used.
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
         <para>
	    The value of the checkbox can be retrieved using:
         </para>
         <screen><![CDATA[$turned_on = param('checkbox_name');]]></screen>
      </section>
      <section id="ID-41d5e89da0cd775fb053bb98ec0099de"><title>CREATING A RADIO BUTTON GROUP</title>
         <screen><![CDATA[print radio_group(-name=>'group_name',
                          -values=>['eenie','meenie','minie'],
                          -default=>'meenie',
                          -linebreak=>'true',
        -labels=>\%labels,
        -attributes=>\%attributes);

-or-

print radio_group('group_name',['eenie','meenie','minie'],
         'meenie','true',\%labels,\%attributes);

HTML3-COMPATIBLE BROWSERS ONLY:

print radio_group(-name=>'group_name',
                          -values=>['eenie','meenie','minie','moe'],
                          -rows=2,-columns=>2);]]></screen>
         <para>
	    radio_group() creates a set of logically-related radio buttons
	    (turning one member of the group on turns the others off)
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-f1175ecbd12cad155a774c73f27591af"/><emphasis role="bold">Parameters:</emphasis></term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-072f866177c2c92f6193284d104f55f0"/>1.</term>
                  <listitem>
                     <para>
			The first argument is the name of the group and is
			required (-name).
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ea059db0464e33f2d3f5909eba69ef6f"/>2.</term>
                  <listitem>
                     <para>
			The second argument (-values) is the list of values
			for the radio buttons.	The values and the labels
			that appear on the page are identical.	Pass an
			array <emphasis role="italic">reference</emphasis>
			in the second argument, either using an anonymous
			array, as shown, or by referencing a named array as
			in <quote>\@foo</quote>.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-83a967e68594b7b2297284f375998f0f"/>3.</term>
                  <listitem>
                     <para>
			The optional third parameter (-default) is the name
			of the default button to turn on. If not specified,
			the first item will be the default.  You can
			provide a nonexistent button name, such as <quote>-</quote> to
			start up with no buttons selected.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-64cc202599711665deba33ef3ea21d6a"/>4.</term>
                  <listitem>
                     <para>
			The optional fourth parameter (-linebreak) can be
			set to 'true' to put line breaks between the
			buttons, creating a vertical list.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-3ee76aa88c81bc1db8185d0bb7e19a78"/>5.</term>
                  <listitem>
                     <para>
			The optional fifth parameter (-labels) is a pointer
			to an associative array relating the radio button
			values to user-visible labels to be used in the
			display.  If not provided, the values themselves
			are displayed.
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
         <screen><![CDATA[]]></screen>
         <para>
	    All modern browsers can take advantage of the optional
	    parameters <emphasis role="bold">-rows</emphasis>, and
	    <emphasis role="bold">-columns</emphasis>.	These parameters
	    cause radio_group() to return an HTML3 compatible table
	    containing the radio group formatted with the specified number
	    of rows and columns.  You can provide just the -columns
	    parameter if you wish; radio_group will calculate the correct
	    number of rows for you.
         </para>
         <para>
	    To include row and column headings in the returned table, you
	    can use the <emphasis role="bold">-rowheaders</emphasis> and
	    <emphasis role="bold">-colheaders</emphasis> parameters.  Both
	    of these accept a pointer to an array of headings to use. The
	    headings are just decorative.  They don't reorganize the
	    interpretation of the radio buttons -- they're still a single
	    named unit.
         </para>
         <para>
	    The optional <emphasis role="bold">-tabindex</emphasis>
	    argument can be used to control the order in which radio
	    buttons receive focus when the user presses the tab button.  If
	    passed a scalar numeric value, the first element in the group
	    will receive this tab index and subsequent elements will be
	    incremented by one.  If given a reference to an array of radio
	    button values, then the indexes will be jiggered so that the
	    order specified in the array will correspond to the tab order. 
	    You can also pass a reference to a hash in which the hash keys
	    are the radio button values and the values are the tab indexes
	    of each button.  Examples:
         </para>
         <screen><![CDATA[-tabindex => 100    #  this group starts at index 100 and counts up
-tabindex => ['moe','minie','eenie','meenie']  # tab in this order
-tabindex => {meenie=>100,moe=>101,minie=>102,eenie=>200} # tab in this order

]]></screen>
         <para>
	    The optional <emphasis role="bold">-attributes</emphasis>
	    argument is provided to assign any of the common HTML
	    attributes to an individual menu item. It's a pointer to a hash
	    relating menu values to another hash with the attribute's name
	    as the key and the attribute's value as the value.
         </para>
         <para>
	    The optional <emphasis role="bold">-labelattributes</emphasis>
	    argument will contain attributes attached to the <label>
	    element that surrounds each button.
         </para>
         <para>
	    When the form is processed, the selected radio button can be
	    retrieved using:
         </para>
         <screen><![CDATA[$which_radio_button = param('group_name');]]></screen>
         <para>
	    The value returned by radio_group() is actually an array of
	    button elements.  You can capture them and use them within
	    tables, lists, or in other creative ways:
         </para>
         <screen><![CDATA[@h = radio_group(-name=>'group_name',-values=>\@values);
&use_in_creative_way(@h);]]></screen>
      </section>
      <section id="ID-00b6f009d96e64ce7f45b1b061c0ceb8"><title>CREATING A SUBMIT BUTTON</title>
         <screen><![CDATA[print submit(-name=>'button_name',
                     -value=>'value');

-or-

print submit('button_name','value');]]></screen>
         <para>
	    submit() will create the query submission button.  Every form
	    should have one of these.
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-f1175ecbd12cad155a774c73f27591af"/><emphasis role="bold">Parameters:</emphasis></term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-072f866177c2c92f6193284d104f55f0"/>1.</term>
                  <listitem>
                     <para>
			The first argument (-name) is optional.  You can
			give the button a name if you have several
			submission buttons in your form and you want to
			distinguish between them.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ea059db0464e33f2d3f5909eba69ef6f"/>2.</term>
                  <listitem>
                     <para>
			The second argument (-value) is also optional. 
			This gives the button a value that will be passed
			to your script in the query string. The name will
			also be used as the user-visible label.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-83a967e68594b7b2297284f375998f0f"/>3.</term>
                  <listitem>
                     <para>
			You can use -label as an alias for -value.  I
			always get confused about which of -name and -value
			changes the user-visible label on the button.
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
         <para>
	    You can figure out which button was pressed by using different
	    values for each one:
         </para>
         <screen><![CDATA[$which_one = param('button_name');]]></screen>
      </section>
      <section id="ID-1f9a85d5f5404c338113e002a5d526f4"><title>CREATING A RESET BUTTON</title>
         <screen><![CDATA[print reset]]></screen>
         <para>
	    reset() creates the <quote>reset</quote> button.  Note that it restores the
	    form to its value from the last time the script was called, NOT
	    necessarily to the defaults.
         </para>
         <para>
	    Note that this conflicts with the Perl reset() built-in.  Use
	    CORE::reset() to get the original reset function.
         </para>
      </section>
      <section id="ID-5ac26dc558104453b10eb491132d8501"><title>CREATING A DEFAULT BUTTON</title>
         <screen><![CDATA[print defaults('button_label')]]></screen>
         <para>
	    defaults() creates a button that, when invoked, will cause the
	    form to be completely reset to its defaults, wiping out all the
	    changes the user ever made.
         </para>
      </section>
      <section id="ID-05f860d4fdcd71da43dfd5b452e3e0da"><title>CREATING A HIDDEN FIELD</title>
         <screen><![CDATA[print hidden(-name=>'hidden_name',
                     -default=>['value1','value2'...]);

-or-

print hidden('hidden_name','value1','value2'...);]]></screen>
         <para>
	    hidden() produces a text field that can't be seen by the user. 
	    It is useful for passing state variable information from one
	    invocation of the script to the next.
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-f1175ecbd12cad155a774c73f27591af"/><emphasis role="bold">Parameters:</emphasis></term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-072f866177c2c92f6193284d104f55f0"/>1.</term>
                  <listitem>
                     <para>
			The first argument is required and specifies the
			name of this field (-name).
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ea059db0464e33f2d3f5909eba69ef6f"/>2.</term>
                  <listitem>
                     <para>
			The second argument is also required and specifies
			its value (-default).  In the named parameter style
			of calling, you can provide a single value here or
			a reference to a whole list
                     </para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
         <para>
	    Fetch the value of a hidden field this way:
         </para>
         <screen><![CDATA[$hidden_value = param('hidden_name');]]></screen>
         <para>
	    Note, that just like all the other form elements, the value of
	    a hidden field is <quote>sticky</quote>.  If you want to replace a hidden
	    field with some other values after the script has been called
	    once you'll have to do it manually:
         </para>
         <screen><![CDATA[param('hidden_name','new','values','here');]]></screen>
      </section>
      <section id="ID-ae2b3f3ad660ba0a684f0a0411e1620b"><title>CREATING A CLICKABLE IMAGE BUTTON</title>
         <screen><![CDATA[print image_button(-name=>'button_name',
                           -src=>'/source/URL',
                           -align=>'MIDDLE');

-or-

print image_button('button_name','/source/URL','MIDDLE');]]></screen>
         <para>
	    image_button() produces a clickable image.	When it's clicked
	    on the position of the click is returned to your script as
	    <quote>button_name.x</quote> and <quote>button_name.y</quote>, where <quote>button_name</quote> is the
	    name you've assigned to it.
         </para>
         <para>
            <variablelist>
               <varlistentry>
                  <term><anchor id="ID-f1175ecbd12cad155a774c73f27591af"/><emphasis role="bold">Parameters:</emphasis></term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-072f866177c2c92f6193284d104f55f0"/>1.</term>
                  <listitem>
                     <para>
			The first argument (-name) is required and
			specifies the name of this field.
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-ea059db0464e33f2d3f5909eba69ef6f"/>2.</term>
                  <listitem>
                     <para>
			The second argument (-src) is also required and
			specifies the URL
                     </para>
                  </listitem>
               </varlistentry>
               <varlistentry>
                  <term><anchor id="ID-145c19194e2774c70e8743394082e51c"/>3.
The third option (-align, optional) is an alignment type, and may be
TOP, BOTTOM or MIDDLE</term>
                  <listitem>
                     <para></para>
                  </listitem>
               </varlistentry>
            </variablelist>
         </para>
         <para>
	    Fetch the value of the button this way: $x =
	    param('button_name.x'); $y = param('button_name.y');
         </para>
      </section>
      <section id="ID-584cc1843cebca3d3818eeb297fbad4f"><title>CREATING A JAVASCRIPT ACTION BUTTON</title>
         <screen><![CDATA[print button(-name=>'button_name',
                     -value=>'user visible label',
                     -onClick=>"do_something()");

-or-

print button('button_name',"user visible value","do_something()");]]></screen>
         <para>
	    button() produces an <literal
	    role="code"><![CDATA[<input>]]></literal> tag with <literal
	    role="code"><![CDATA[type="button"]]></literal>.  When it's
	    pressed the fragment of JavaScript code pointed to by the
	    <emphasis role="bold">-onClick</emphasis> parameter will be
	    executed.
         </para>
      </section>
   </section>
   <section id="ID-65a5d5d96a39858386e79342d3938148"><title>HTTP COOKIES</title>
      <para>
	 Browsers support a so-called <quote>cookie</quote> designed to help maintain
	 state within a browser session.  CGI.pm has several methods that
	 support cookies.
      </para>
      <para>
	 A cookie is a name=value pair much like the named parameters in a
	 CGI query string.  CGI scripts create one or more cookies and send
	 them to the browser in the HTTP header.  The browser maintains a
	 list of cookies that belong to a particular Web server, and
	 returns them to the CGI script during subsequent interactions.
      </para>
      <para>
	 In addition to the required name=value pair, each cookie has
	 several optional attributes:
      </para>
      <para>
         <variablelist>
            <varlistentry>
               <term><anchor id="ID-74d8347da7dcb30881443f7e8819456d"/>1. an expiration time</term>
               <listitem>
                  <para>
		     This is a time/date string (in a special GMT format)
		     that indicates when a cookie expires.  The cookie will
		     be saved and returned to your script until this
		     expiration date is reached if the user exits the
		     browser and restarts it.  If an expiration date isn't
		     specified, the cookie will remain active until the
		     user quits the browser.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-d9a3cba26e07e5d1c7e50f2ff7208e09"/>2. a domain</term>
               <listitem>
                  <para>
		     This is a partial or complete domain name for which
		     the cookie is valid.  The browser will return the
		     cookie to any host that matches the partial domain
		     name.  For example, if you specify a domain name of
		     <quote>.capricorn.com</quote>, then the browser will return the
		     cookie to Web servers running on any of the machines
		     <quote>www.capricorn.com</quote>, <quote>www2.capricorn.com</quote>,
		     <quote>feckless.capricorn.com</quote>, etc.  Domain names must
		     contain at least two periods to prevent attempts to
		     match on top level domains like <quote>.edu</quote>.  If no domain
		     is specified, then the browser will only return the
		     cookie to servers on the host the cookie originated
		     from.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-6741ae49cf2260e1a0904295cbe2eb30"/>3. a path</term>
               <listitem>
                  <para>
		     If you provide a cookie path attribute, the browser
		     will check it against your script's URL before
		     returning the cookie.  For example, if you specify the
		     path <quote>/cgi-bin</quote>, then the cookie will be returned to
		     each of the scripts <quote>/cgi-bin/tally.pl</quote>,
		     <quote>/cgi-bin/order.pl</quote>, and
		     <quote>/cgi-bin/customer_service/complain.pl</quote>, but not to
		     the script <quote>/cgi-private/site_admin.pl</quote>.  By default,
		     path is set to <quote>/</quote>, which causes the cookie to be sent
		     to any CGI script on your site.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-3f927cdfbbe1b90e48d9dd91bcf69eeb"/>4. a "secure" flag</term>
               <listitem>
                  <para>
		     If the <quote>secure</quote> attribute is set, the cookie will only
		     be sent to your script if the CGI request is occurring
		     on a secure channel, such as SSL.
                  </para>
               </listitem>
            </varlistentry>
         </variablelist>
      </para>
      <para>
	 The interface to HTTP cookies is the <emphasis
	 role="bold">cookie()</emphasis> method:
      </para>
      <screen><![CDATA[$cookie = cookie(-name=>'sessionID',
                         -value=>'xyzzy',
                         -expires=>'+1h',
                         -path=>'/cgi-bin/database',
                         -domain=>'.capricorn.org',
                         -secure=>1);
print header(-cookie=>$cookie);]]></screen>
      <para>
	 <emphasis role="bold">cookie()</emphasis> creates a new cookie. 
	 Its parameters include:
      </para>
      <para>
         <variablelist>
            <varlistentry>
               <term><anchor id="ID-01bc5d14a3939c7992df9ef5c73d7a99"/><emphasis role="bold">-name</emphasis></term>
               <listitem>
                  <para>
		     The name of the cookie (required).  This can be any
		     string at all. Although browsers limit their cookie
		     names to non-whitespace alphanumeric characters,
		     CGI.pm removes this restriction by escaping and
		     unescaping cookies behind the scenes.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-1d039d19455fa3f12c494ced8239f967"/><emphasis role="bold">-value</emphasis></term>
               <listitem>
                  <para>
		     The value of the cookie.  This can be any scalar
		     value, array reference, or even hash reference.  For
		     example, you can store an entire hash into a cookie
		     this way:
                  </para>
                  <screen><![CDATA[$cookie=cookie(-name=>'family information',
                       -value=>\%childrens_ages);]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-00766861d955a82eb788d985a069ed18"/><emphasis role="bold">-path</emphasis></term>
               <listitem>
                  <para>
		     The optional partial path for which this cookie will
		     be valid, as described above.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-c8a7c23f9706a7861160f080b031089a"/><emphasis role="bold">-domain</emphasis></term>
               <listitem>
                  <para>
		     The optional partial domain for which this cookie will
		     be valid, as described above.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-dbde092a5f49226611c85a59aff38a7a"/><emphasis role="bold">-expires</emphasis></term>
               <listitem>
                  <para>
		     The optional expiration date for this cookie.  The
		     format is as described in the section on the <emphasis
		     role="bold">header()</emphasis> method:
                  </para>
                  <screen><![CDATA["+1h"  one hour from now]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-afc5d035a1fb5fd886c95d99d3c5e0f1"/><emphasis role="bold">-secure</emphasis></term>
               <listitem>
                  <para>
		     If set to true, this cookie will only be used within a
		     secure SSL session.
                  </para>
               </listitem>
            </varlistentry>
         </variablelist>
      </para>
      <para>
	 The cookie created by cookie() must be incorporated into the HTTP
	 header within the string returned by the header() method:
      </para>
      <screen><![CDATA[use CGI ':standard';
print header(-cookie=>$my_cookie);]]></screen>
      <para>
	 To create multiple cookies, give header() an array reference:
      </para>
      <screen><![CDATA[$cookie1 = cookie(-name=>'riddle_name',
                          -value=>"The Sphynx's Question");
$cookie2 = cookie(-name=>'answers',
                          -value=>\%answers);
print header(-cookie=>[$cookie1,$cookie2]);]]></screen>
      <para>
	 To retrieve a cookie, request it by name by calling cookie()
	 method without the <emphasis role="bold">-value</emphasis>
	 parameter. This example uses the object-oriented form:
      </para>
      <screen><![CDATA[use CGI;
$query = CGI->new;
$riddle = $query->cookie('riddle_name');
%answers = $query->cookie('answers');]]></screen>
      <para>
	 Cookies created with a single scalar value, such as the
	 <quote>riddle_name</quote> cookie, will be returned in that form.  Cookies with
	 array and hash values can also be retrieved.
      </para>
      <para>
	 The cookie and CGI namespaces are separate.  If you have a
	 parameter named 'answers' and a cookie named 'answers', the values
	 retrieved by param() and cookie() are independent of each other. 
	 However, it's simple to turn a CGI parameter into a cookie, and
	 vice-versa:
      </para>
      <screen><![CDATA[# turn a CGI parameter into a cookie
$c=cookie(-name=>'answers',-value=>[param('answers')]);
# vice-versa
param(-name=>'answers',-value=>[cookie('answers')]);]]></screen>
      <para>
	 If you call cookie() without any parameters, it will return a list
	 of the names of all cookies passed to your script:
      </para>
      <screen><![CDATA[@cookies = cookie();]]></screen>
      <para>
	 See the <emphasis role="bold">cookie.cgi</emphasis> example script
	 for some ideas on how to use cookies effectively.
      </para>
   </section>
   <section id="ID-e18b0257d96860a3bc96008ed3334104"><title>WORKING WITH FRAMES</title>
      <para>
	 It's possible for CGI.pm scripts to write into several browser
	 panels and windows using the HTML 4 frame mechanism.  There are
	 three techniques for defining new frames programmatically:
      </para>
      <para>
         <variablelist>
            <varlistentry>
               <term><anchor id="ID-f4c672bf83b4ec6dba18eca7687786d7"/>1. Create a <Frameset> document</term>
               <listitem>
                  <para>
		     After writing out the HTTP header, instead of creating
		     a standard HTML document using the start_html() call,
		     create a <frameset> document that defines the
		     frames on the page.  Specify your script(s) (with
		     appropriate parameters) as the SRC for each of the
		     frames.
                  </para>
                  <para>
		     There is no specific support for creating
		     <frameset> sections in CGI.pm, but the HTML is
		     very simple to write.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-db05d63b2ce46dde6399b0175538ca20"/>2. Specify the destination for the document in the HTTP header</term>
               <listitem>
                  <para>
		     You may provide a <emphasis
		     role="bold">-target</emphasis> parameter to the
		     header() method:
                  </para>
                  <screen><![CDATA[print header(-target=>'ResultsWindow');]]></screen>
                  <para>
		     This will tell the browser to load the output of your
		     script into the frame named <quote>ResultsWindow</quote>.  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 HTML <literal
		     role="code"><![CDATA[<frame>]]></literal>
		     documentation for details.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-efb3e2dc24702c698215ac2679e951b5"/>3. Specify the destination for the document in the <form> tag</term>
               <listitem>
                  <para>
		     You can specify the frame to load in the FORM tag
		     itself.  With CGI.pm it looks like this:
                  </para>
                  <screen><![CDATA[print start_form(-target=>'ResultsWindow');]]></screen>
                  <para>
		     When your script is reinvoked by the form, its output
		     will be loaded into the frame named <quote>ResultsWindow</quote>. 
		     If one doesn't already exist a new window will be
		     created.
                  </para>
               </listitem>
            </varlistentry>
         </variablelist>
      </para>
      <para>
	 The script <quote>frameset.cgi</quote> in the examples directory shows one way
	 to create pages in which the fill-out form and the response live
	 in side-by-side frames.
      </para>
   </section>
   <section id="ID-14ab977274edcb4e4247df47a7c8c561"><title>SUPPORT FOR JAVASCRIPT</title>
      <para>
	 The usual way to use JavaScript is to define a set of functions in
	 a <SCRIPT> block inside the HTML header and then to register
	 event handlers in the various elements of the page. Events include
	 such things as the mouse passing over a form element, a button
	 being clicked, the contents of a text field changing, or a form
	 being submitted. When an event occurs that involves an element
	 that has registered an event handler, its associated JavaScript
	 code gets called.
      </para>
      <para>
	 The elements that can register event handlers include the
	 <BODY> of an HTML document, hypertext links, all the various
	 elements of a fill-out form, and the form itself. There are a
	 large number of events, and each applies only to the elements for
	 which it is relevant. Here is a partial list:
      </para>
      <para>
         <variablelist>
            <varlistentry>
               <term><anchor id="ID-b6b0281815b284b948c2a490f4a350a4"/><emphasis role="bold">onLoad</emphasis></term>
               <listitem>
                  <para>
		     The browser is loading the current document. Valid in:
                  </para>
                  <screen><![CDATA[+ The HTML <BODY> section only.]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-5d2d3389b34e2c7f9410a31d8a50a925"/><emphasis role="bold">onUnload</emphasis></term>
               <listitem>
                  <para>
		     The browser is closing the current page or frame.
		     Valid for:
                  </para>
                  <screen><![CDATA[+ The HTML <BODY> section only.]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-0694137a54f35ea8099b718c8b25b1d2"/><emphasis role="bold">onSubmit</emphasis></term>
               <listitem>
                  <para>
		     The user has pressed the submit button of a form. This
		     event happens just before the form is submitted, and
		     your function can return a value of false in order to
		     abort the submission.  Valid for:
                  </para>
                  <screen><![CDATA[+ Forms only.]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-7c25a7e757d3318ec89f819c23e63c8d"/><emphasis role="bold">onClick</emphasis></term>
               <listitem>
                  <para>
		     The mouse has clicked on an item in a fill-out form.
		     Valid for:
                  </para>
                  <screen><![CDATA[+ Buttons (including submit, reset, and image buttons)
+ Checkboxes
+ Radio buttons]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-e9142cbaf2bf9792752aaf1b400a2fcf"/><emphasis role="bold">onChange</emphasis></term>
               <listitem>
                  <para>
		     The user has changed the contents of a field. Valid
		     for:
                  </para>
                  <screen><![CDATA[+ Text fields
+ Text areas
+ Password fields
+ File fields
+ Popup Menus
+ Scrolling lists]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-21b6ee27b5efc9b4915ad77e6248b31e"/><emphasis role="bold">onFocus</emphasis></term>
               <listitem>
                  <para>
		     The user has selected a field to work with. Valid for:
                  </para>
                  <screen><![CDATA[+ Text fields
+ Text areas
+ Password fields
+ File fields
+ Popup Menus
+ Scrolling lists]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-e46736d8922352c20fa130c734e0d394"/><emphasis role="bold">onBlur</emphasis></term>
               <listitem>
                  <para>
		     The user has deselected a field (gone to work
		     somewhere else).  Valid for:
                  </para>
                  <screen><![CDATA[+ Text fields
+ Text areas
+ Password fields
+ File fields
+ Popup Menus
+ Scrolling lists]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-707d8c81c5a769ecf416eaa2f8c063cb"/><emphasis role="bold">onSelect</emphasis></term>
               <listitem>
                  <para>
		     The user has changed the part of a text field that is
		     selected.	Valid for:
                  </para>
                  <screen><![CDATA[+ Text fields
+ Text areas
+ Password fields
+ File fields]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-2c38e8ec3264fe42e586b0a47def596c"/><emphasis role="bold">onMouseOver</emphasis></term>
               <listitem>
                  <para>
		     The mouse has moved over an element.
                  </para>
                  <screen><![CDATA[+ Text fields
+ Text areas
+ Password fields
+ File fields
+ Popup Menus
+ Scrolling lists]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-11fe19e38a32455d1166e0ce74f18d79"/><emphasis role="bold">onMouseOut</emphasis></term>
               <listitem>
                  <para>
		     The mouse has moved off an element.
                  </para>
                  <screen><![CDATA[+ Text fields
+ Text areas
+ Password fields
+ File fields
+ Popup Menus
+ Scrolling lists]]></screen>
               </listitem>
            </varlistentry>
         </variablelist>
      </para>
      <para>
	 In order to register a JavaScript event handler with an HTML
	 element, just use the event name as a parameter when you call the
	 corresponding CGI method. For example, to have your validateAge()
	 JavaScript code executed every time the textfield named <quote>age</quote>
	 changes, generate the field like this:
      </para>
      <screen><![CDATA[print textfield(-name=>'age',-onChange=>"validateAge(this)");]]></screen>
      <para>
	 This example assumes that you've already declared the
	 validateAge() function by incorporating it into a <SCRIPT>
	 block. The CGI.pm start_html() method provides a convenient way to
	 create this section.
      </para>
      <para>
	 Similarly, you can create a form that checks itself over for
	 consistency and alerts the user if some essential value is missing
	 by creating it this way: print
	 start_form(-onSubmit=><quote>validateMe(this)</quote>);
      </para>
      <para>
	 See the javascript.cgi script for a demonstration of how this all
	 works.
      </para>
      <screen><![CDATA[]]></screen>
   </section>
   <section id="ID-2079556890b89d5b05838056d847d0fd"><title>LIMITED SUPPORT FOR CASCADING STYLE SHEETS</title>
      <para>
	 CGI.pm has limited support for HTML3's cascading style sheets
	 (css). To incorporate a stylesheet into your document, pass the
	 start_html() method a <emphasis role="bold">-style</emphasis>
	 parameter.  The value of this parameter may be a scalar, in which
	 case it is treated as the source URL for the stylesheet, or it may
	 be a hash reference.  In the latter case you should provide the
	 hash with one or more of <emphasis role="bold">-src</emphasis> or
	 <emphasis role="bold">-code</emphasis>.  <emphasis
	 role="bold">-src</emphasis> points to a URL where an
	 externally-defined stylesheet can be found.  <emphasis
	 role="bold">-code</emphasis> points to a scalar value to be
	 incorporated into a <style> section.  Style definitions in
	 <emphasis role="bold">-code</emphasis> override similarly-named
	 ones in <emphasis role="bold">-src</emphasis>, hence the name
	 <quote>cascading.</quote>
      </para>
      <para>
	 You may also specify the type of the stylesheet by adding the
	 optional <emphasis role="bold">-type</emphasis> parameter to the
	 hash pointed to by <emphasis role="bold">-style</emphasis>.  If
	 not specified, the style defaults to 'text/css'.
      </para>
      <para>
	 To refer to a style within the body of your document, add the
	 <emphasis role="bold">-class</emphasis> parameter to any HTML
	 element:
      </para>
      <screen><![CDATA[print h1({-class=>'Fancy'},'Welcome to the Party');]]></screen>
      <para>
	 Or define styles on the fly with the <emphasis
	 role="bold">-style</emphasis> parameter:
      </para>
      <screen><![CDATA[print h1({-style=>'Color: red;'},'Welcome to Hell');]]></screen>
      <para>
	 You may also use the new <emphasis role="bold">span()</emphasis>
	 element to apply a style to a section of text:
      </para>
      <screen><![CDATA[print span({-style=>'Color: red;'},
           h1('Welcome to Hell'),
           "Where did that handbasket get to?"
           );]]></screen>
      <para>
	 Note that you must import the <quote>:html3</quote> definitions to have the
	 <emphasis role="bold">span()</emphasis> method available.  Here's
	 a quick and dirty example of using CSS's.  See the CSS
	 specification at http://www.w3.org/Style/CSS/ for more
	 information.
      </para>
      <screen><![CDATA[use CGI qw/:standard :html3/;

#here's a stylesheet incorporated directly into the page
$newStyle=<<END;

END
print header();
print start_html( -title=>'CGI with Style',
                  -style=>{-src=>'http://www.capricorn.com/style/st1.css',
                           -code=>$newStyle}
                 );
print h1('CGI with Style'),
      p({-class=>'Tip'},
        "Better read the cascading style sheet spec before playing with this!"),
      span({-style=>'color: magenta'},
           "Look Mom, no hands!",
           p(),
           "Whooo wee!"
           );
print end_html;]]></screen>
      <para>
	 Pass an array reference to <emphasis role="bold">-code</emphasis>
	 or <emphasis role="bold">-src</emphasis> in order to incorporate
	 multiple stylesheets into your document.
      </para>
      <para>
	 Should you wish to incorporate a verbatim stylesheet that includes
	 arbitrary formatting in the header, you may pass a -verbatim tag
	 to the -style hash, as follows:
      </para>
      <para>
	 print start_html (-style  =>  {-verbatim => '@import
	 url(<quote>/server-common/css/'.$cssFile.'</quote>);', -src    => 
	 '/server-common/css/core.css'});
      </para>
      <screen><![CDATA[]]></screen>
      <para>
	 This will generate an HTML header that contains this:
      </para>
      <screen><![CDATA[<link rel="stylesheet" type="text/css"  href="/server-common/css/core.css">
  <style type="text/css">
  @import url("/server-common/css/main.css");
  </style>]]></screen>
      <para>
	 Any additional arguments passed in the -style value will be
	 incorporated into the <link> tag.  For example:
      </para>
      <screen><![CDATA[start_html(-style=>{-src=>['/styles/print.css','/styles/layout.css'],
                         -media => 'all'});]]></screen>
      <para>
	 This will give:
      </para>
      <screen><![CDATA[<link rel="stylesheet" type="text/css" href="/styles/print.css" media="all"/>
<link rel="stylesheet" type="text/css" href="/styles/layout.css" media="all"/>]]></screen>
      <para>
	 <p>
      </para>
      <para>
	 To make more complicated <link> tags, use the Link()
	 function and pass it to start_html() in the -head argument, as in:
      </para>
      <screen><![CDATA[@h = (Link({-rel=>'stylesheet',-type=>'text/css',-src=>'/ss/ss.css',-media=>'all'}),
      Link({-rel=>'stylesheet',-type=>'text/css',-src=>'/ss/fred.css',-media=>'paper'}));
print start_html({-head=>\@h})]]></screen>
      <para>
	 To create primary and	<quote>alternate</quote> stylesheet, use the <emphasis
	 role="bold">-alternate</emphasis> option:
      </para>
      <screen><![CDATA[start_html(-style=>{-src=>[
                          {-src=>'/styles/print.css'},
                          {-src=>'/styles/alt.css',-alternate=>1}
                          ]
                   });]]></screen>
   </section>
   <section id="ID-414e38f146787bf61c473d1e97d20947"><title>DEBUGGING</title>
      <para>
	 If you are running the script from the command line or in the perl
	 debugger, you can pass the script a list of keywords or
	 parameter=value pairs on the command line or from standard input
	 (you don't have to worry about tricking your script into reading
	 from environment variables).  You can pass keywords like this:
      </para>
      <screen><![CDATA[your_script.pl keyword1 keyword2 keyword3]]></screen>
      <para>
	 or this:
      </para>
      <screen><![CDATA[your_script.pl keyword1+keyword2+keyword3]]></screen>
      <para>
	 or this:
      </para>
      <screen><![CDATA[your_script.pl name1=value1 name2=value2]]></screen>
      <para>
	 or this:
      </para>
      <screen><![CDATA[your_script.pl name1=value1&name2=value2]]></screen>
      <para>
	 To turn off this feature, use the -no_debug pragma.
      </para>
      <para>
	 To test the POST method, you may enable full debugging with the
	 -debug pragma.  This will allow you to feed newline-delimited
	 name=value pairs to the script on standard input.
      </para>
      <para>
	 When debugging, you can use quotes and backslashes to escape
	 characters in the familiar shell manner, letting you place spaces
	 and other funny characters in your parameter=value pairs:
      </para>
      <screen><![CDATA[your_script.pl "name1='I am a long value'" "name2=two\ words"]]></screen>
      <para>
	 Finally, you can set the path info for the script by prefixing the
	 first name/value parameter with the path followed by a question
	 mark (?):
      </para>
      <screen><![CDATA[your_script.pl /your/path/here?name1=value1&name2=value2]]></screen>
      <section id="ID-9e0b7853355b5a5d6f89166a1c2095db"><title>DUMPING OUT ALL THE NAME/VALUE PAIRS</title>
         <para>
	    The Dump() method produces a string consisting of all the
	    query's name/value pairs formatted nicely as a nested list. 
	    This is useful for debugging purposes:
         </para>
         <screen><![CDATA[print Dump

]]></screen>
         <para>
	    Produces something that looks like:
         </para>
         <screen><![CDATA[<ul>
<li>name1
    <ul>
    <li>value1
    <li>value2
    </ul>
<li>name2
    <ul>
    <li>value1
    </ul>
</ul>]]></screen>
         <para>
	    As a shortcut, you can interpolate the entire CGI object into a
	    string and it will be replaced with the a nice HTML dump shown
	    above:
         </para>
         <screen><![CDATA[$query=CGI->new;
print "<h2>Current Values</h2> $query\n";]]></screen>
      </section>
   </section>
   <section id="ID-ad66e38e2d4e305073b25bf60186f26c"><title>FETCHING ENVIRONMENT VARIABLES</title>
      <para>
	 Some of the more useful environment variables can be fetched
	 through this interface.  The methods are as follows:
      </para>
      <para>
         <variablelist>
            <varlistentry>
               <term><anchor id="ID-1a6646b19f9ef4e712638cce32be41e9"/><emphasis role="bold">Accept()</emphasis></term>
               <listitem>
                  <para>
		     Return a list of MIME types that the remote browser
		     accepts. If you give this method a single argument
		     corresponding to a MIME type, as in
		     Accept('text/html'), it will return a floating point
		     value corresponding to the browser's preference for
		     this type from 0.0 (don't want) to 1.0.  Glob types
		     (e.g. text/*) in the browser's accept list are handled
		     correctly.
                  </para>
                  <para>
		     Note that the capitalization changed between version
		     2.43 and 2.44 in order to avoid conflict with Perl's
		     accept() function.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-dfb31b12ebf405b3eaa8c4638330e6da"/><emphasis role="bold">raw_cookie()</emphasis></term>
               <listitem>
                  <para>
		     Returns the HTTP_COOKIE variable.	Cookies have a
		     special format, and this method call just returns the
		     raw form (?cookie dough).	See cookie() for ways of
		     setting and retrieving cooked cookies.
                  </para>
                  <para>
		     Called with no parameters, raw_cookie() returns the
		     packed cookie structure.  You can separate it into
		     individual cookies by splitting on the character
		     sequence <quote>; </quote>.  Called with the name of a cookie,
		     retrieves the <emphasis
		     role="bold">unescaped</emphasis> form of the cookie. 
		     You can use the regular cookie() method to get the
		     names, or use the raw_fetch() method from the
		     CGI::Cookie module.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-dec7f8527f7ee8458bdc9d344390e384"/><emphasis role="bold">user_agent()</emphasis></term>
               <listitem>
                  <para>
		     Returns the HTTP_USER_AGENT variable.  If you give
		     this method a single argument, it will attempt to
		     pattern match on it, allowing you to do something like
		     user_agent(Mozilla);
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-7a4787a9c940157f1fa74cd636682b34"/><emphasis role="bold">path_info()</emphasis></term>
               <listitem>
                  <para>
		     Returns additional path information from the script
		     URL. E.G. fetching
		     /cgi-bin/your_script/additional/stuff will result in
		     path_info() returning <quote>/additional/stuff</quote>.
                  </para>
                  <para>
		     NOTE: The Microsoft Internet Information Server is
		     broken with respect to additional path information. 
		     If you use the Perl DLL library, the IIS server will
		     attempt to execute the additional path information as
		     a Perl script. If you use the ordinary file
		     associations mapping, the path information will be
		     present in the environment, but incorrect.  The best
		     thing to do is to avoid using additional path
		     information in CGI scripts destined for use with IIS.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-36e55ed3329837849309f619cf681733"/><emphasis role="bold">path_translated()</emphasis></term>
               <listitem>
                  <para>
		     As per path_info() but returns the additional path
		     information translated into a physical path, e.g.
		     <quote>/usr/local/etc/httpd/htdocs/additional/stuff</quote>.
                  </para>
                  <para>
		     The Microsoft IIS is broken with respect to the
		     translated path as well.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-8016e79398dd781584eaeb77d1094bf3"/><emphasis role="bold">remote_host()</emphasis></term>
               <listitem>
                  <para>
		     Returns either the remote host name or IP address. if
		     the former is unavailable.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-7ebaad93cf65c56eded9029e85df81bf"/><emphasis role="bold">remote_addr()</emphasis></term>
               <listitem>
                  <para>
		     Returns the remote host IP address, or 127.0.0.1 if
		     the address is unavailable.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-9830c19a09d4f62a73fa1984cd68edef"/><emphasis role="bold">script_name()</emphasis>
Return the script name as a partial URL, for self-refering
scripts.</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-084c29731b829741d3e0844856a4d0e0"/><emphasis role="bold">referer()</emphasis></term>
               <listitem>
                  <para>
		     Return the URL of the page the browser was viewing
		     prior to fetching your script.  Not available for all
		     browsers.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-f181e3a8df2551a3f3ea3f2635f47c0c"/><emphasis role="bold">auth_type ()</emphasis></term>
               <listitem>
                  <para>
		     Return the authorization/verification method in use
		     for this script, if any.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-caa28f362f15f9016f674e0de7d09081"/><emphasis role="bold">server_name ()</emphasis></term>
               <listitem>
                  <para>
		     Returns the name of the server, usually the machine's
		     host name.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-99393cd89bdba4b551cca32d4a532a2a"/><emphasis role="bold">virtual_host ()</emphasis></term>
               <listitem>
                  <para>
		     When using virtual hosts, returns the name of the host
		     that the browser attempted to contact
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-1499b3dbd83262dc52a7de66d513428f"/><emphasis role="bold">server_port ()</emphasis></term>
               <listitem>
                  <para>
		     Return the port that the server is listening on.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-7fd7eaa451f8705458ed3cb6518e72f9"/><emphasis role="bold">virtual_port ()</emphasis></term>
               <listitem>
                  <para>
		     Like server_port() except that it takes virtual hosts
		     into account. Use this when running with virtual
		     hosts.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-193a0c8c4362605121baee6047981561"/><emphasis role="bold">server_software ()</emphasis></term>
               <listitem>
                  <para>
		     Returns the server software and version number.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-1b1405a4b0c01655a9dd689b83bfda6e"/><emphasis role="bold">remote_user ()</emphasis></term>
               <listitem>
                  <para>
		     Return the authorization/verification name used for
		     user verification, if this script is protected.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-51915654a790f965487e5beb09f19cee"/><emphasis role="bold">user_name ()</emphasis></term>
               <listitem>
                  <para>
		     Attempt to obtain the remote user's name, using a
		     variety of different techniques.  This only works with
		     older browsers such as Mosaic. Newer browsers do not
		     report the user name for privacy reasons!
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-0c1dc6fc09248a2c2bee7bfc0c1554b5"/><emphasis role="bold">request_method()</emphasis></term>
               <listitem>
                  <para>
		     Returns the method used to access your script, usually
		     one of 'POST', 'GET' or 'HEAD'.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-db6cb5c48123cc5122c1e49973b95d88"/><emphasis role="bold">content_type()</emphasis></term>
               <listitem>
                  <para>
		     Returns the content_type of data submitted in a POST,
		     generally multipart/form-data or
		     application/x-www-form-urlencoded
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-e35ffff465d2eb6e38638f0dcddcfa96"/><emphasis role="bold">http()</emphasis></term>
               <listitem>
                  <para>
		     Called with no arguments returns the list of HTTP
		     environment variables, including such things as
		     HTTP_USER_AGENT, HTTP_ACCEPT_LANGUAGE, and
		     HTTP_ACCEPT_CHARSET, corresponding to the like-named
		     HTTP header fields in the request.  Called with the
		     name of an HTTP header field, returns its value. 
		     Capitalization and the use of hyphens versus
		     underscores are not significant.
                  </para>
                  <para>
		     For example, all three of these examples are
		     equivalent:
                  </para>
                  <screen><![CDATA[$requested_language = http('Accept-language');
$requested_language = http('Accept_language');
$requested_language = http('HTTP_ACCEPT_LANGUAGE');]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-5b47760516d15a0ac18860261c969b55"/><emphasis role="bold">https()</emphasis></term>
               <listitem>
                  <para>
		     The same as <emphasis role="italic">http()</emphasis>,
		     but operates on the HTTPS environment variables
		     present when the SSL protocol is in effect.  Can be
		     used to determine whether SSL is turned on.
                  </para>
               </listitem>
            </varlistentry>
         </variablelist>
      </para>
   </section>
   <section id="ID-01c49ff71ae3d9996975be25f3a0944d"><title>USING NPH SCRIPTS</title>
      <para>
	 NPH, or <quote>no-parsed-header</quote>, 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.
      </para>
      <para>
	 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 <quote>nph-</quote>.  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.
      </para>
      <screen><![CDATA[]]></screen>
      <para>
	 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 header() and redirect() methods are called.
      </para>
      <para>
	 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.  However, note that if you have applied Service Pack 6, much
	 of the functionality of NPH scripts, including the ability to
	 redirect while setting a cookie, <emphasis role="bold">do not work
	 at all</emphasis> on IIS without a special patch from Microsoft. 
	 See
	 http://web.archive.org/web/20010812012030/http://support.microsoft.com/support/kb/articles/Q280/3/41.ASP
	 Non-Parsed Headers Stripped From CGI Applications That Have nph-
	 Prefix in Name.
      </para>
      <para>
         <variablelist>
            <varlistentry>
               <term><anchor id="ID-40511415312fe10548818ffee44c40d2"/>In the <emphasis role="bold">use</emphasis> statement</term>
               <listitem>
                  <para>
		     Simply add the <quote>-nph</quote> pragmato the list of symbols to
		     be imported into your script:
                  </para>
                  <screen><![CDATA[use CGI qw(:standard -nph)]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-acc3712756037ca89cd8345802b1f6d5"/>By calling the <emphasis role="bold">nph()</emphasis> method:</term>
               <listitem>
                  <para>
		     Call <emphasis role="bold">nph()</emphasis> with a
		     non-zero parameter at any point after using CGI.pm in
		     your program.
                  </para>
                  <screen><![CDATA[CGI->nph(1)]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-0d26b5fef5c91b31854b30dead6b5185"/>By using <emphasis role="bold">-nph</emphasis> parameters</term>
               <listitem>
                  <para>
		     in the <emphasis role="bold">header()</emphasis> and
		     <emphasis role="bold">redirect()</emphasis> 
		     statements:
                  </para>
                  <screen><![CDATA[print header(-nph=>1);]]></screen>
               </listitem>
            </varlistentry>
         </variablelist>
      </para>
   </section>
   <section id="ID-498a2cae3889729ea454a587effab5ed"><title>Server Push</title>
      <para>
	 CGI.pm provides four simple functions for producing multipart
	 documents of the type needed to implement server push.  These
	 functions were graciously provided by Ed Jordan
	 <ed@fidalgo.net>.  To import these into your namespace, you
	 must import the <quote>:push</quote> set. You are also advised to put the
	 script into NPH mode and to set $| to 1 to avoid buffering
	 problems.
      </para>
      <para>
	 Here is a simple script that demonstrates server push:
      </para>
      <screen><![CDATA[#!/usr/local/bin/perl
use CGI qw/:push -nph/;
$| = 1;
print multipart_init(-boundary=>'----here we go!');
for (0 .. 4) {
    print multipart_start(-type=>'text/plain'),
          "The current time is ",scalar(localtime),"\n";
    if ($_ < 4) {
            print multipart_end;
    } else {
            print multipart_final;
    }
    sleep 1;
}]]></screen>
      <para>
	 This script initializes server push by calling <emphasis
	 role="bold">multipart_init()</emphasis>. It then enters a loop in
	 which it begins a new multipart section by calling <emphasis
	 role="bold">multipart_start()</emphasis>, prints the current local
	 time, and ends a multipart section with <emphasis
	 role="bold">multipart_end()</emphasis>.  It then sleeps a second,
	 and begins again. On the final iteration, it ends the multipart
	 section with <emphasis role="bold">multipart_final()</emphasis>
	 rather than with <emphasis role="bold">multipart_end()</emphasis>.
      </para>
      <para>
         <variablelist>
            <varlistentry>
               <term><anchor id="ID-660c44600ce3aaa99c3ada5781a40d00"/>multipart_init()</term>
               <listitem>
                  <screen><![CDATA[multipart_init(-boundary=>$boundary);]]></screen>
                  <para>
		     Initialize the multipart system.  The -boundary
		     argument specifies what MIME boundary string to use to
		     separate parts of the document. If not provided,
		     CGI.pm chooses a reasonable boundary for you.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-bed03dbc87c05f22f4040e5bc2f27149"/>multipart_start()</term>
               <listitem>
                  <screen><![CDATA[multipart_start(-type=>$type)]]></screen>
                  <para>
		     Start a new part of the multipart document using the
		     specified MIME type.  If not specified, text/html is
		     assumed.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-41dadb3b1e69e475fe0ed75458d50ca8"/>multipart_end()</term>
               <listitem>
                  <screen><![CDATA[multipart_end()]]></screen>
                  <para>
		     End a part.  You must remember to call multipart_end()
		     once for each multipart_start(), except at the end of
		     the last part of the multipart document when
		     multipart_final() should be called instead of
		     multipart_end().
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-d23763be699652f057f71c20f82611a2"/>multipart_final()</term>
               <listitem>
                  <screen><![CDATA[multipart_final()]]></screen>
                  <para>
		     End all parts.  You should call multipart_final()
		     rather than multipart_end() at the end of the last
		     part of the multipart document.
                  </para>
               </listitem>
            </varlistentry>
         </variablelist>
      </para>
      <para>
	 Users interested in server push applications should also have a
	 look at the CGI::Push module.
      </para>
   </section>
   <section id="ID-f395e7a86516be9ce239532b2f5ecd48"><title>Avoiding Denial of Service Attacks</title>
      <para>
	 A potential problem with CGI.pm is that, by default, it attempts
	 to process form POSTings no matter how large they are.  A wily
	 hacker could attack your site by sending a CGI script a huge POST
	 of many megabytes.  CGI.pm will attempt to read the entire POST
	 into a variable, growing hugely in size until it runs out of
	 memory.  While the script attempts to allocate the memory the
	 system may slow down dramatically.  This is a form of denial of
	 service attack.
      </para>
      <para>
	 Another possible attack is for the remote user to force CGI.pm to
	 accept a huge file upload.  CGI.pm will accept the upload and
	 store it in a temporary directory even if your script doesn't
	 expect to receive an uploaded file.  CGI.pm will delete the file
	 automatically when it terminates, but in the meantime the remote
	 user may have filled up the server's disk space, causing problems
	 for other programs.
      </para>
      <para>
	 The best way to avoid denial of service attacks is to limit the
	 amount of memory, CPU time and disk space that CGI scripts can
	 use.  Some Web servers come with built-in facilities to accomplish
	 this. In other cases, you can use the shell <emphasis
	 role="italic">limit</emphasis> or <emphasis
	 role="italic">ulimit</emphasis> commands to put ceilings on CGI
	 resource usage.
      </para>
      <screen><![CDATA[]]></screen>
      <para>
	 CGI.pm also has some simple built-in protections against denial of
	 service attacks, but you must activate them before you can use
	 them. These take the form of two global variables in the CGI name
	 space:
      </para>
      <para>
         <variablelist>
            <varlistentry>
               <term><anchor id="ID-c11b24788d323cc94fbfcbb43e8ef26d"/><emphasis role="bold">$CGI::POST_MAX</emphasis></term>
               <listitem>
                  <para>
		     If set to a non-negative integer, this variable puts a
		     ceiling on the size of POSTings, in bytes.  If CGI.pm
		     detects a POST that is greater than the ceiling, it
		     will immediately exit with an error message.  This
		     value will affect both ordinary POSTs and multipart
		     POSTs, meaning that it limits the maximum size of file
		     uploads as well.  You should set this to a reasonably
		     high value, such as 1 megabyte.
                  </para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-403304ed24f030ab7e5b2c998cf7dc58"/><emphasis role="bold">$CGI::DISABLE_UPLOADS</emphasis></term>
               <listitem>
                  <para>
		     If set to a non-zero value, this will disable file
		     uploads completely.  Other fill-out form values will
		     work as usual.
                  </para>
               </listitem>
            </varlistentry>
         </variablelist>
      </para>
      <para>
	 You can use these variables in either of two ways.
      </para>
      <para>
         <variablelist>
            <varlistentry>
               <term><anchor id="ID-e67b4167e4f72779f022331a1b0a4d37"/><emphasis role="bold">1. On a script-by-script basis</emphasis></term>
               <listitem>
                  <para>
		     Set the variable at the top of the script, right after
		     the <quote>use</quote> statement:
                  </para>
                  <screen><![CDATA[use CGI qw/:standard/;
use CGI::Carp 'fatalsToBrowser';
$CGI::POST_MAX=1024 * 100;  # max 100K posts
$CGI::DISABLE_UPLOADS = 1;  # no uploads]]></screen>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-fdadd6cefea4f293bc460ee07381a1f5"/><emphasis role="bold">2. Globally for all scripts</emphasis></term>
               <listitem>
                  <para>
		     Open up CGI.pm, find the definitions for $POST_MAX and
		     $DISABLE_UPLOADS, and set them to the desired values. 
		     You'll find them towards the top of the file in a
		     subroutine named initialize_globals().
                  </para>
               </listitem>
            </varlistentry>
         </variablelist>
      </para>
      <para>
	 An attempt to send a POST larger than $POST_MAX bytes will cause
	 <emphasis role="italic">param()</emphasis> to return an empty CGI
	 parameter list.  You can test for this event by checking <emphasis
	 role="italic">cgi_error()</emphasis>, either after you create the
	 CGI object or, if you are using the function-oriented interface,
	 call <param()> for the first time.  If the POST was
	 intercepted, then cgi_error() will return the message <quote>413 POST
	 too large</quote>.
      </para>
      <para>
	 This error message is actually defined by the HTTP protocol, and
	 is designed to be returned to the browser as the CGI script's
	 status code.  For example:
      </para>
      <screen><![CDATA[$uploaded_file = param('upload');
if (!$uploaded_file && cgi_error()) {
   print header(-status=>cgi_error());
   exit 0;
}]]></screen>
      <para>
	 However it isn't clear that any browser currently knows what to do
	 with this status code.  It might be better just to create an HTML
	 page that warns the user of the problem.
      </para>
   </section>
   <section id="ID-9b8a3ca6689efd375ccb0e8620a9e9a0"><title>COMPATIBILITY WITH CGI-LIB.PL</title>
      <para>
	 To make it easier to port existing programs that use cgi-lib.pl
	 the compatibility routine <quote>ReadParse</quote> is provided.  Porting is
	 simple:
      </para>
      <para>
	 OLD VERSION require <quote>cgi-lib.pl</quote>; &ReadParse; print <quote>The value
	 of the antique is $in{antique}.\n</quote>;
      </para>
      <para>
	 NEW VERSION use CGI; CGI::ReadParse(); print <quote>The value of the
	 antique is $in{antique}.\n</quote>;
      </para>
      <para>
	 CGI.pm's ReadParse() routine creates a tied variable named %in,
	 which can be accessed to obtain the query variables.  Like
	 ReadParse, you can also provide your own variable.  Infrequently
	 used features of ReadParse, such as the creation of @in and $in
	 variables, are not supported.
      </para>
      <para>
	 Once you use ReadParse, you can retrieve the query object itself
	 this way:
      </para>
      <screen><![CDATA[$q = $in{CGI};
print textfield(-name=>'wow',
                    -value=>'does this really work?');]]></screen>
      <para>
	 This allows you to start using the more interesting features of
	 CGI.pm without rewriting your old scripts from scratch.
      </para>
   </section>
   <section id="ID-0a240e276f9f34115e126702ba28804f"><title>AUTHOR INFORMATION</title>
      <para>
	 The CGI.pm distribution is copyright 1995-2007, Lincoln D. Stein. 
	 It is distributed under GPL and the Artistic License 2.0.
      </para>
      <para>
	 Address bug reports and comments to: lstein@cshl.org.	When
	 sending bug reports, please provide the version of CGI.pm, the
	 version of Perl, the name and version of your Web server, and the
	 name and version of the operating system you are using.  If the
	 problem is even remotely browser dependent, please provide
	 information about the affected browers as well.
      </para>
   </section>
   <section id="ID-22fa2d998869ad3176ce9eac7b6cb0ac"><title>CREDITS</title>
      <para>
	 Thanks very much to:
      </para>
      <para>
         <variablelist>
            <varlistentry>
               <term><anchor id="ID-508c8fb7cf481971321d53f56e5e372c"/>Matt Heffron (heffron@falstaff.css.beckman.com)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-4ce934bea3f012524f002598cc596e39"/>James Taylor (james.taylor@srs.gov)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-0f8e8d9f8a46700fdda894e7dc3cb446"/>Scott Anguish <sanguish@digifix.com></term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-b33ed308c876f88d339e02a94374784b"/>Mike Jewell (mlj3u@virginia.edu)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-b69a2baabd244dbceecc2485a3122ab3"/>Timothy Shimmin (tes@kbs.citri.edu.au)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-36acf38ad885f36d0b9c90bf3b04c1d3"/>Joergen Haegg (jh@axis.se)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-a13ec9be3573271043363055151c08a4"/>Laurent Delfosse (delfosse@delfosse.com)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-85cbeb5853d05cd123c1d04bfbe76c2f"/>Richard Resnick (applepi1@aol.com)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-ab85979c204e9ac4df975a9076b67ff4"/>Craig Bishop (csb@barwonwater.vic.gov.au)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-a653b49202ad5feeaf21bcda61e846aa"/>Tony Curtis (tc@vcpc.univie.ac.at)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-6bdd87370837a42dc9b8a340a96d2980"/>Tim Bunce (Tim.Bunce@ig.co.uk)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-f70b07d81a9867569bc6595d3af17972"/>Tom Christiansen (tchrist@convex.com)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-9bd1407b90fdebc6c490061e18eabda1"/>Andreas Koenig (k@franz.ww.TU-Berlin.DE)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-e7991fef8ce596719ba191ce124bc3bf"/>Tim MacKenzie (Tim.MacKenzie@fulcrum.com.au)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-f7234542f1e7f95d88164dd1c2b8b1d9"/>Kevin B. Hendricks (kbhend@dogwood.tyler.wm.edu)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-1b5c02985b23fc4539908ea55cd41c33"/>Stephen Dahmen (joyfire@inxpress.net)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-583d0e5e2d0ca4cd3d82e98c4e87842d"/>Ed Jordan (ed@fidalgo.net)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-e3acb6df499116c20a6041b383a38924"/>David Alan Pisoni (david@cnation.com)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-6d4c07fe370338e928c26140a449b42c"/>Doug MacEachern (dougm@opengroup.org)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-bade0f65cd6268f93e561264a49e8c54"/>Robin Houston (robin@oneworld.org)</term>
               <listitem>
                  <para></para>
               </listitem>
            </varlistentry>
            <varlistentry>
               <term><anchor id="ID-a6298554c7a480c55c35a2515ff108cb"/>...and many many more...</term>
               <listitem>
                  <para>
		     for suggestions and bug fixes.
                  </para>
               </listitem>
            </varlistentry>
         </variablelist>
      </para>
   </section>
   <section id="ID-fd43f780d09ee7b893300e26ad4b8182"><title>A COMPLETE EXAMPLE OF A SIMPLE FORM-BASED SCRIPT</title>
      <screen><![CDATA[

#!/usr/local/bin/perl

use CGI ':standard';

print header;
print start_html("Example CGI.pm Form");
print "<h1> Example CGI.pm Form</h1>\n";
print_prompt();
do_work();
print_tail();
print end_html;

sub print_prompt {
   print start_form;
   print "<em>What's your name?</em><br>";
   print textfield('name');
   print checkbox('Not my real name');

print "<p><em>Where can you find English Sparrows?</em><br>";
print checkbox_group(
                      -name=>'Sparrow locations',
                      -values=>[England,France,Spain,Asia,Hoboken],
                      -linebreak=>'yes',
                      -defaults=>[England,Asia]);

print "<p><em>How far can they fly?</em><br>",
     radio_group(
             -name=>'how far',
             -values=>['10 ft','1 mile','10 miles','real far'],
             -default=>'1 mile');

print "<p><em>What's your favorite color?</em>  ";
print popup_menu(-name=>'Color',
                         -values=>['black','brown','red','yellow'],
                         -default=>'red');

print hidden('Reference','Monty Python and the Holy Grail');

print "<p><em>What have you got there?</em><br>";
print scrolling_list(
              -name=>'possessions',
              -values=>['A Coconut','A Grail','An Icon',
                        'A Sword','A Ticket'],
              -size=>5,
              -multiple=>'true');

print "<p><em>Any parting comments?</em><br>";
print textarea(-name=>'Comments',
                       -rows=>10,
                       -columns=>50);

print "<p>",reset;
   print submit('Action','Shout');
   print submit('Action','Scream');
   print end_form;
   print "<hr>\n";
}

sub do_work {

print "<h2>Here are the current settings in this form</h2>";

for my $key (param) {
      print "<strong>$key</strong> -> ";
      my @values = param($key);
      print join(", ",@values),"<br>\n";
  }
}

sub print_tail {
   print <<END;
<hr>
<address>Lincoln D. Stein</address><br>
<a href="/">Home Page</a>
END
}]]></screen>
   </section>
   <section id="ID-5dbd4f3a21f990717e243b8f99cfda80"><title>BUGS</title>
      <para>
	 Please report them.
      </para>
   </section>
   <section id="ID-0eb4a22a8f13cf46aee8a6ad0fc50d3b"><title>SEE ALSO</title>
      <para>
	 <citerefentry> <refentrytitle>CGI::Carp</refentrytitle>
	 </citerefentry> - provides a <citerefentry>
	 <refentrytitle>Carp</refentrytitle> </citerefentry> implementation
	 tailored to the CGI environment.
      </para>
      <para>
	 <citerefentry> <refentrytitle>CGI::Fast</refentrytitle>
	 </citerefentry> - supports running CGI applications under FastCGI
      </para>
      <para>
	 <citerefentry> <refentrytitle>CGI::Pretty</refentrytitle>
	 </citerefentry> - pretty prints HTML generated by CGI.pm (with a
	 performance penalty)
      </para>
   </section>
</article>

dir:/.libs