/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



NNNNAAAAMMMMEEEE
     CGI - Simple Common Gateway Interface Class

SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
       use CGI;
       # the rest is too complicated for a synopsis; keep reading


AAAABBBBSSSSTTTTRRRRAAAACCCCTTTT
     This perl library uses perl5 objects to make it easy to
     create Web fill-out forms and parse their contents.  This
     package defines CGI objects, entities that contain the
     values of the current query string and other state
     variables.  Using a CGI object's methods, you can examine
     keywords and parameters passed to your script, and create
     forms whose initial values are taken from the current query
     (thereby preserving state information).

     The current version of CGI.pm is available at

       http://www.genome.wi.mit.edu/ftp/pub/software/WWW/cgi_docs.html
       ftp://ftp-genome.wi.mit.edu/pub/software/WWW/


IIIINNNNSSSSTTTTAAAALLLLLLLLAAAATTTTIIIIOOOONNNN::::
     To install this package, just change to the directory in
     which this file is found and type the following:

             perl Makefile.PL
             make
             make install

     This will copy CGI.pm to your perl library directory for use
     by all perl scripts.  You probably must be root to do this.
     Now you can load the CGI routines in your Perl scripts with
     the line:

             use CGI;

     If you don't have sufficient privileges to install CGI.pm in
     the Perl library directory, you can put CGI.pm into some
     convenient spot, such as your home directory, or in cgi-bin
     itself and prefix all Perl scripts that call it with
     something along the lines of the following preamble:

             use lib '/home/davis/lib';
             use CGI;

     If you are using a version of perl earlier than 5.002 (such
     as NT perl), use this instead:





12/May/97         Last change: perl 5.003 with                  1






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



             BEGIN {
                     unshift(@INC,'/home/davis/lib');
             }
             use CGI;

     The CGI distribution also comes with a cute module called
     the _C_G_I::_C_a_r_p manpage.  It redefines the _d_i_e(), _w_a_r_n(),
     _c_o_n_f_e_s_s() and _c_r_o_a_k() error routines so that they write
     nicely formatted error messages into the server's error log
     (or to the output stream of your choice).  This avoids long
     hours of groping through the error and access logs, trying
     to figure out which CGI script is generating  error
     messages.  If you choose, you can even have fatal error
     messages echoed to the browser to avoid the annoying and
     uninformative "Server Error" message.

DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA NNNNEEEEWWWW QQQQUUUUEEEERRRRYYYY OOOOBBBBJJJJEEEECCCCTTTT::::

          $query = new CGI;

     This will parse the input (from both POST and GET methods)
     and store it into a perl5 object called $query.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA NNNNEEEEWWWW QQQQUUUUEEEERRRRYYYY OOOOBBBBJJJJEEEECCCCTTTT FFFFRRRROOOOMMMM AAAANNNN IIIINNNNPPPPUUUUTTTT FFFFIIIILLLLEEEE

          $query = new CGI(INPUTFILE);

     If you provide a file handle to the _n_e_w() 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 _s_a_v_e() method (see below).  Multiple records
     can be saved and restored.

     Perl purists will be pleased to know that this syntax
     accepts references to file handles, or even references to
     filehandle globs, which is the "official" way to pass a
     filehandle:

         $query = new CGI(\*STDIN);

     You can also initialize the query object from an associative
     array reference:

         $query = new CGI( {'dinosaur'=>'barney',
                            'song'=>'I love you',
                            'friends'=>[qw/Jessica George Nancy/]}
                         );

     or from a properly formatted, URL-escaped query string:



12/May/97         Last change: perl 5.003 with                  2






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



         $query = new CGI('dinosaur=barney&color=purple');

     To create an empty query, initialize it from an empty string
     or hash:

             $empty_query = new CGI("");
                  -or-
             $empty_query = new CGI({});


     FFFFEEEETTTTCCCCHHHHIIIINNNNGGGG AAAA LLLLIIIISSSSTTTT OOOOFFFF KKKKEEEEYYYYWWWWOOOORRRRDDDDSSSS FFFFRRRROOOOMMMM TTTTHHHHEEEE QQQQUUUUEEEERRRRYYYY::::

          @keywords = $query->keywords

     If the script was invoked as the result of an <ISINDEX>
     search, the parsed keywords can be obtained as an array
     using the _k_e_y_w_o_r_d_s() method.

     FFFFEEEETTTTCCCCHHHHIIIINNNNGGGG TTTTHHHHEEEE NNNNAAAAMMMMEEEESSSS OOOOFFFF AAAALLLLLLLL TTTTHHHHEEEE PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS PPPPAAAASSSSSSSSEEEEDDDD TTTTOOOO YYYYOOOOUUUURRRR
     SSSSCCCCRRRRIIIIPPPPTTTT::::

          @names = $query->param

     If the script was invoked with a parameter list (e.g.
     "name1=value1&name2=value2&name3=value3"), the _p_a_r_a_m()
     method will return the parameter names as a list.  If the
     script was invoked as an <ISINDEX> script, there will be a
     single parameter named 'keywords'.

     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).

     FFFFEEEETTTTCCCCHHHHIIIINNNNGGGG TTTTHHHHEEEE VVVVAAAALLLLUUUUEEEE OOOORRRR VVVVAAAALLLLUUUUEEEESSSS OOOOFFFF AAAA SSSSIIIINNNNGGGGLLLLEEEE NNNNAAAAMMMMEEEEDDDD PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR::::

         @values = $query->param('foo');

                   -or-

         $value = $query->param('foo');

     Pass the _p_a_r_a_m() 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.







12/May/97         Last change: perl 5.003 with                  3






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     SSSSEEEETTTTTTTTIIIINNNNGGGG TTTTHHHHEEEE _V_A_L_U_E(S) OF A NAMED PARAMETER:

         $query->param('foo','an','array','of','values');

     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.)

     _p_a_r_a_m() also recognizes a named parameter style of calling
     described in more detail later:

         $query->param(-name=>'foo',-values=>['an','array','of','values']);

                                   -or-

         $query->param(-name=>'foo',-value=>'the value');


     AAAAPPPPPPPPEEEENNNNDDDDIIIINNNNGGGG AAAADDDDDDDDIIIITTTTIIIIOOOONNNNAAAALLLL VVVVAAAALLLLUUUUEEEESSSS TTTTOOOO AAAA NNNNAAAAMMMMEEEEDDDD PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR::::

        $query->append(-name=>;'foo',-values=>['yet','more','values']);

     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.

     IIIIMMMMPPPPOOOORRRRTTTTIIIINNNNGGGG AAAALLLLLLLL PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS IIIINNNNTTTTOOOO AAAA NNNNAAAAMMMMEEEESSSSPPPPAAAACCCCEEEE::::

        $query->import_names('R');

     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!!!!

     In older versions, this method was called iiiimmmmppppoooorrrrtttt(((()))).  As of
     version 2.20, this name has been removed completely to avoid
     conflict with the built-in Perl module iiiimmmmppppoooorrrrtttt operator.

     DDDDEEEELLLLEEEETTTTIIIINNNNGGGG AAAA PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRR CCCCOOOOMMMMPPPPLLLLEEEETTTTEEEELLLLYYYY::::

         $query->delete('foo');

     This completely clears a parameter.  It sometimes useful for
     resetting parameters that you don't want passed down between
     script invocations.




12/May/97         Last change: perl 5.003 with                  4






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     DDDDEEEELLLLEEEETTTTIIIINNNNGGGG AAAALLLLLLLL PPPPAAAARRRRAAAAMMMMEEEETTTTEEEERRRRSSSS::::

     $query->_d_e_l_e_t_e__a_l_l();

     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.

     SSSSAAAAVVVVIIIINNNNGGGG TTTTHHHHEEEE SSSSTTTTAAAATTTTEEEE OOOOFFFF TTTTHHHHEEEE FFFFOOOORRRRMMMM TTTTOOOO AAAA FFFFIIIILLLLEEEE::::

         $query->save(FILEHANDLE)

     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 _n_e_w() method.  Note that the filehandle
     can be a file, a pipe, or whatever!

     The format of the saved file is:

             NAME1=VALUE1
             NAME1=VALUE1'
             NAME2=VALUE2
             NAME3=VALUE3
             =

     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
     nnnneeeewwww.  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:

        use CGI;

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

        # reopen for reading
        open (IN,"test.out") || die;
        while (!eof(IN)) {
            my $q = new CGI(IN);
            print $q->param('counter'),"\n";
        }




12/May/97         Last change: perl 5.003 with                  5






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     The file format used for save/restore is identical to that
     used by the Whitehead Genome Center's data exchange format
     "Boulderio", and can be manipulated and even databased using
     Boulderio utilities.  See
       http://www.genome.wi.mit.edu/genome_software/other/boulder.html

     for further details.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA SSSSEEEELLLLFFFF----RRRREEEEFFFFEEEERRRREEEENNNNCCCCIIIINNNNGGGG UUUURRRRLLLL TTTTHHHHAAAATTTT PPPPRRRREEEESSSSEEEERRRRVVVVEEEESSSS SSSSTTTTAAAATTTTEEEE
     IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN::::

         $myself = $query->self_url;
         print "<A HREF=$myself>I'm talking to myself.</A>";

     _s_e_l_f__u_r_l() 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 _f_o_r_m(s).  Something like
     this will do the trick.

          $myself = $query->self_url;
          print "<A HREF=$myself#table1>See table 1</A>";
          print "<A HREF=$myself#table2>See table 2</A>";
          print "<A HREF=$myself#yourself>See for yourself</A>";

     If you don't want to get the whole query string, call the
     method _u_r_l() to return just the URL for the script:

         $myself = $query->url;
         print "<A HREF=$myself>No query string in this baby!</A>\n";

     You can also retrieve the unprocessed query string with
     _q_u_e_r_y__s_t_r_i_n_g():

         $the_string = $query->query_string;


     CCCCOOOOMMMMPPPPAAAATTTTIIIIBBBBIIIILLLLIIIITTTTYYYY WWWWIIIITTTTHHHH CCCCGGGGIIII----LLLLIIIIBBBB....PPPPLLLL

     To make it easier to port existing programs that use cgi-
     lib.pl the compatibility routine "ReadParse" is provided.
     Porting is simple:

     OLD VERSION
         require "cgi-lib.pl";
         &ReadParse;
         print "The value of the antique is $in{antique}.\n";

     NEW VERSION
         use CGI;
         CGI::ReadParse



12/May/97         Last change: perl 5.003 with                  6






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



         print "The value of the antique is $in{antique}.\n";

     CGI.pm's _R_e_a_d_P_a_r_s_e() 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.

     Once you use ReadParse, you can retrieve the query object
     itself this way:

         $q = $in{CGI};
         print $q->textfield(-name=>'wow',
                             -value=>'does this really work?');

     This allows you to start using the more interesting features
     of CGI.pm without rewriting your old scripts from scratch.

     CCCCAAAALLLLLLLLIIIINNNNGGGG CCCCGGGGIIII FFFFUUUUNNNNCCCCTTTTIIIIOOOONNNNSSSS TTTTHHHHAAAATTTT TTTTAAAAKKKKEEEE MMMMUUUULLLLTTTTIIIIPPPPLLLLEEEE AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS

     In versions of CGI.pm prior to 2.0, it could get difficult
     to remember the proper order of arguments in CGI function
     calls that accepted five or six different arguments.  As of
     2.0, there's a better way to pass arguments to the various
     CGI functions.  In this style, you pass a series of
     name=>argument pairs, like this:

        $field = $query->radio_group(-name=>'OS',
                                     -values=>[Unix,Windows,Macintosh],
                                     -default=>'Unix');

     The advantages of this style are that you don't have to
     remember the exact order of the arguments, and if you leave
     out a parameter, in most cases it will default to some
     reasonable value.  If you provide a parameter that the
     method doesn't recognize, it will usually do something
     useful with it, such as incorporating it into the HTML form
     tag.  For example if Netscape decides next week to add a new
     JUSTIFICATION parameter to the text field tags, you can
     start using the feature without waiting for a new version of
     CGI.pm:

        $field = $query->textfield(-name=>'State',
                                   -default=>'gaseous',
                                   -justification=>'RIGHT');

     This will result in an HTML tag that looks like this:

             <INPUT TYPE="textfield" NAME="State" VALUE="gaseous"
                    JUSTIFICATION="RIGHT">

     Parameter names are case insensitive: you can use -name, or



12/May/97         Last change: perl 5.003 with                  7






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     -Name or -NAME.  You don't have to use the hyphen if you
     don't want to.  After creating a CGI object, call the
     uuuusssseeee____nnnnaaaammmmeeeedddd____ppppaaaarrrraaaammmmeeeetttteeeerrrrssss(((()))) method with a nonzero value.  This
     will tell CGI.pm that you intend to use named parameters
     exclusively:

        $query = new CGI;
        $query->use_named_parameters(1);
        $field = $query->radio_group('name'=>'OS',
                                     'values'=>['Unix','Windows','Macintosh'],
                                     'default'=>'Unix');

     Actually, CGI.pm only looks for a hyphen in the first
     parameter.  So you can leave it off subsequent parameters if
     you like.  Something to be wary of is the potential that a
     string constant like "values" will collide with a keyword
     (and in fact it does!) While Perl usually figures out when
     you're referring to a function and when you're referring to
     a string, you probably should put quotation marks around all
     string constants just to play it safe.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG TTTTHHHHEEEE HHHHTTTTTTTTPPPP HHHHEEEEAAAADDDDEEEERRRR::::

             print $query->header;

                  -or-

             print $query->header('image/gif');

                  -or-

             print $query->header('text/html','204 No response');

                  -or-

             print $query->header(-type=>'image/gif',
                                  -nph=>1,
                                  -status=>'402 Payment required',
                                  -expires=>'+3d',
                                  -cookie=>$cookie,
                                  -Cost=>'$2.00');

     _h_e_a_d_e_r() 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, "No response" to create a script that tells
     the browser to do nothing at all.  If you want to add
     additional fields to the header, just tack them on to the
     end:





12/May/97         Last change: perl 5.003 with                  8






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



         print $query->header('text/html','200 OK','Content-Length: 3002');

     The last example shows the named argument style for passing
     arguments to the CGI methods using named parameters.
     Recognized parameters are ----ttttyyyyppppeeee, ----ssssttttaaaattttuuuussss, ----eeeexxxxppppiiiirrrreeeessss, and ----
     ccccooooooookkkkiiiieeee.  Any other parameters will be stripped of their
     initial hyphens and turned into header fields, allowing you
     to specify any HTTP header you desire.

     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 ----
     eeeexxxxppppiiiirrrreeeessss 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:

             +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-96 00:40:33 GMT  at the indicated time & date

     (_C_G_I::_e_x_p_i_r_e_s() is the static function call used internally
     that turns relative time intervals into HTTP dates.  You can
     call it directly if you wish.)

     The ----ccccooooooookkkkiiiieeee parameter generates a header that tells the
     browser to provide a "magic cookie" during all subsequent
     transactions with your script.  Netscape cookies have a
     special format that includes interesting attributes such as
     expiration time.  Use the _c_o_o_k_i_e() method to create and
     retrieve session cookies.

     The ----nnnnpppphhhh 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 Internet Explorer, which expect all their scripts
     to be NPH.

     GGGGEEEENNNNEEEERRRRAAAATTTTIIIINNNNGGGG AAAA RRRREEEEDDDDIIIIRRRREEEECCCCTTTTIIIIOOOONNNN IIIINNNNSSSSTTTTRRRRUUUUCCCCTTTTIIIIOOOONNNN

        print $query->redirect('http://somewhere.else/in/movie/land');

     redirects the browser elsewhere.  If you use redirection
     like this, you should nnnnooootttt print out a header as well.  As of
     version 2.0, we produce both the unofficial Location: header
     and the official URI:  header.  This should satisfy most



12/May/97         Last change: perl 5.003 with                  9






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     servers and browsers.

     One hint I can offer is that relative links may not work
     correctly when you generate a redirection to another
     document on your site.  This is due to a well-intentioned
     optimization that some servers use.  The solution to this is
     to use the full URL (including the http: part) of the
     document you are redirecting to.

     You can use named parameters:

         print $query->redirect(-uri=>'http://somewhere.else/in/movie/land',
                                -nph=>1);

     The ----nnnnpppphhhh 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 Internet Explorer, which expect all their scripts
     to be NPH.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG TTTTHHHHEEEE HHHHTTTTMMMMLLLL HHHHEEEEAAAADDDDEEEERRRR::::

        print $query->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'},
                                 -BGCOLOR=>'blue');

        -or-

        print $query->start_html('Secrets of the Pyramids',
                                 'fred@capricorn.org','true',
                                 'BGCOLOR="blue"');

     This will return 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 and -target (see below for the explanation).  Any
     additional parameters you provide, such as the Netscape
     unofficial BGCOLOR attribute, are added to the <BODY> tag.

     The argument ----xxxxbbbbaaaasssseeee allows you to provide an HREF for the
     <BASE> tag different from the current location, as in

         -xbase=>"http://home.mcom.com/"

     All relative links will be interpreted relative to this tag.

     The argument ----ttttaaaarrrrggggeeeetttt allows you to provide a default target
     frame for all the links and fill-out forms on the page.  See



12/May/97         Last change: perl 5.003 with                 10






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     the Netscape documentation on frames for details of how to
     manipulate this.

         -target=>"answer_window"

     All relative links will be interpreted relative to this tag.
     You add arbitrary meta information to the header with the ----
     mmmmeeeettttaaaa argument.  This argument expects a reference to an
     associative array containing name/value pairs of meta
     information.  These will be turned into a series of header
     <META> tags that look something like this:

         <META NAME="keywords" CONTENT="pharaoh secret mummy">
         <META NAME="description" CONTENT="copyright 1996 King Tut">

     There is no support for the HTTP-EQUIV type of <META> tag.
     This is because you can modify the HTTP header directly with
     the hhhheeeeaaaaddddeeeerrrr(((()))) method.

     JAVASCRIPTING: The ----ssssccccrrrriiiipppptttt, ----nnnnooooSSSSccccrrrriiiipppptttt, ----oooonnnnLLLLooooaaaadddd and ----oooonnnnUUUUnnnnllllooooaaaadddd
     parameters are used to add Netscape JavaScript calls to your
     pages.  ----ssssccccrrrriiiipppptttt 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.

     The ----oooonnnnLLLLooooaaaadddd and ----oooonnnnUUUUnnnnllllooooaaaadddd 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 ----ssssccccrrrriiiipppptttt field:


















12/May/97         Last change: perl 5.003 with                 11






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



           $query = new CGI;
           print $query->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 $query->start_html(-title=>'The Riddle of the Sphinx',
                                    -script=>$JSCRIPT);

     Use the ----nnnnooooSSSSccccrrrriiiipppptttt parameter to pass some HTML text that will
     be displayed on browsers that do not have JavaScript (or
     browsers where JavaScript is turned off).

     See

        http://home.netscape.com/eng/mozilla/2.0/handbook/javascript/

     for more information about JavaScript.

     The old-style positional parameters are as follows:

     PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

     1.  The title

     2.  The author's e-mail address (will create a <LINK
         REV="MADE"> tag if present

     3.  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!

     4, 5, 6...
         Any other parameters you want to include in the <BODY>
         tag.  This is a good place to put Netscape extensions,
         such as colors and wallpaper patterns.






12/May/97         Last change: perl 5.003 with                 12






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     EEEENNNNDDDDIIIINNNNGGGG TTTTHHHHEEEE HHHHTTTTMMMMLLLL DDDDOOOOCCCCUUUUMMMMEEEENNNNTTTT::::

             print $query->end_html

     This ends an HTML document by printing the </BODY></HTML>
     tags.

CCCCRRRREEEEAAAATTTTIIIINNNNGGGG FFFFOOOORRRRMMMMSSSS::::
     _G_e_n_e_r_a_l _n_o_t_e  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.

     _A_n_o_t_h_e_r _n_o_t_e The default values that you specify for the
     forms are only used the ffffiiiirrrrsssstttt 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.

     If you want to change the value of a field from its previous
     value, you have two choices:

     (1) call the _p_a_r_a_m() method to set it.

     (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:

        print $query->textfield(-name=>'field_name',
                                -default=>'starting value',
                                -override=>1,
                                -size=>50,
                                -maxlength=>80);

     _Y_e_t _a_n_o_t_h_e_r _n_o_t_e By default, the text and labels of form
     elements are escaped according to HTML rules.  This means
     that you can safely use "<CLICK ME>" as the label for a
     button.  However, it also interferes with your ability to
     incorporate special HTML character sequences, such as
     &Aacute;, into your fields.  If you wish to turn off
     automatic escaping, call the _a_u_t_o_E_s_c_a_p_e() method with a
     false value immediately after creating the CGI object:

        $query = new CGI;
        $query->autoEscape(undef);








12/May/97         Last change: perl 5.003 with                 13






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAANNNN IIIISSSSIIIINNNNDDDDEEEEXXXX TTTTAAAAGGGG

        print $query->isindex(-action=>$action);

              -or-

        print $query->isindex($action);

     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.

     SSSSTTTTAAAARRRRTTTTIIIINNNNGGGG AAAANNNNDDDD EEEENNNNDDDDIIIINNNNGGGG AAAA FFFFOOOORRRRMMMM

         print $query->startform(-method=>$method,
                                 -action=>$action,
                                 -encoding=>$encoding);
           <... various form stuff ...>
         print $query->endform;

             -or-

         print $query->startform($method,$action,$encoding);
           <... various form stuff ...>
         print $query->endform;

     _s_t_a_r_t_f_o_r_m() will return a <FORM> tag with the optional
     method, action and form encoding that you specify.  The
     defaults are:
         method: POST
         action: this script
         encoding: application/x-www-form-urlencoded

     _e_n_d_f_o_r_m() returns the closing </FORM> tag.

     _S_t_a_r_t_f_o_r_m()'s encoding method tells the browser how to
     package the various fields of the form before sending the
     form to the server.  Two values are possible:

     aaaapppppppplllliiiiccccaaaattttiiiioooonnnn////xxxx----wwwwwwwwwwww----ffffoooorrrrmmmm----uuuurrrrlllleeeennnnccccooooddddeeeedddd
         This is the older type of encoding used by all browsers
         prior to Netscape 2.0.  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 $$$$CCCCGGGGIIII::::::::UUUURRRRLLLL____EEEENNNNCCCCOOOODDDDEEEEDDDD.

     mmmmuuuullllttttiiiippppaaaarrrrtttt////ffffoooorrrrmmmm----ddddaaaattttaaaa
         This is the newer type of encoding introduced by
         Netscape 2.0.  It is suitable for forms that contain
         very large fields or that are intended for transferring
         binary data.  Most importantly, it enables the "file



12/May/97         Last change: perl 5.003 with                 14






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



         upload" feature of Netscape 2.0 forms.  For your
         convenience, CGI.pm stores the name of this encoding
         type in $$$$CCCCGGGGIIII::::::::MMMMUUUULLLLTTTTIIIIPPPPAAAARRRRTTTT

         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.

     For compatibility, the _s_t_a_r_t_f_o_r_m() method uses the older
     form of encoding by default.  If you want to use the newer
     form of encoding by default, you can call
     ssssttttaaaarrrrtttt____mmmmuuuullllttttiiiippppaaaarrrrtttt____ffffoooorrrrmmmm(((()))) instead of ssssttttaaaarrrrttttffffoooorrrrmmmm(((()))).

     JAVASCRIPTING: The ----nnnnaaaammmmeeee and ----oooonnnnSSSSuuuubbbbmmmmiiiitttt 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.

     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 _s_t_a_r_t__h_t_m_l() for details.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA TTTTEEEEXXXXTTTT FFFFIIIIEEEELLLLDDDD

         print $query->textfield(-name=>'field_name',
                                 -default=>'starting value',
                                 -size=>50,
                                 -maxlength=>80);
             -or-

         print $query->textfield('field_name','starting value',50,80);

     _t_e_x_t_f_i_e_l_d() will return a text input field.

     PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss

     1.  The first parameter is the required name for the field (
         -name).

     2.  The optional second parameter is the default starting
         value for the field contents (-default).

     3.  The optional third parameter is the size of the field in
               characters (-size).




12/May/97         Last change: perl 5.003 with                 15






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     4.  The optional fourth parameter is the maximum number of
         characters the
               field will accept (-maxlength).

     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:

            $value = $query->param('foo');

     If you want to reset it from its initial value after the
     script has been called once, you can do so like this:

            $query->param('foo',"I'm taking over this value!");

     NEW AS OF VERSION 2.15: If you don't want the field to take
     on its previous value, you can force its current value by
     using the -override (alias -force) parameter:

         print $query->textfield(-name=>'field_name',
                                 -default=>'starting value',
                                 -override=>1,
                                 -size=>50,
                                 -maxlength=>80);

     JAVASCRIPTING: You can also provide ----oooonnnnCCCChhhhaaaannnnggggeeee, ----oooonnnnFFFFooooccccuuuussss, ----
     oooonnnnBBBBlllluuuurrrr and ----oooonnnnSSSSeeeelllleeeecccctttt parameters to register JavaScript event
     handlers.  The onChange handler will be called whenever the
     user changes the contents of the text field.  You can do
     text validation if you like.  onFocus and onBlur are called
     respectively when the insertion point moves into and out of
     the text field.  onSelect is called when the user changes
     the portion of the text that is selected.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA BBBBIIIIGGGG TTTTEEEEXXXXTTTT FFFFIIIIEEEELLLLDDDD

        print $query->textarea(-name=>'foo',
                               -default=>'starting value',
                               -rows=>10,
                               -columns=>50);

             -or

        print $query->textarea('foo','starting value',10,50);

     _t_e_x_t_a_r_e_a() 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.





12/May/97         Last change: perl 5.003 with                 16






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     JAVASCRIPTING: The ----oooonnnnCCCChhhhaaaannnnggggeeee, ----oooonnnnFFFFooooccccuuuussss, ----oooonnnnBBBBlllluuuurrrr and ----
     oooonnnnSSSSeeeelllleeeecccctttt parameters are recognized.  See _t_e_x_t_f_i_e_l_d().

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA PPPPAAAASSSSSSSSWWWWOOOORRRRDDDD FFFFIIIIEEEELLLLDDDD

        print $query->password_field(-name=>'secret',
                                     -value=>'starting value',
                                     -size=>50,
                                     -maxlength=>80);
             -or-

        print $query->password_field('secret','starting value',50,80);

     _p_a_s_s_w_o_r_d__f_i_e_l_d() is identical to _t_e_x_t_f_i_e_l_d(), except that
     its contents will be starred out on the web page.

     JAVASCRIPTING: The ----oooonnnnCCCChhhhaaaannnnggggeeee, ----oooonnnnFFFFooooccccuuuussss, ----oooonnnnBBBBlllluuuurrrr and ----
     oooonnnnSSSSeeeelllleeeecccctttt parameters are recognized.  See _t_e_x_t_f_i_e_l_d().

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA FFFFIIIILLLLEEEE UUUUPPPPLLLLOOOOAAAADDDD FFFFIIIIEEEELLLLDDDD

         print $query->filefield(-name=>'uploaded_file',
                                 -default=>'starting value',
                                 -size=>50,
                                 -maxlength=>80);
             -or-

         print $query->filefield('uploaded_file','starting value',50,80);

     _f_i_l_e_f_i_e_l_d() will return a file upload field for Netscape 2.0
     browsers.  In order to take full advantage of this _y_o_u _m_u_s_t
     _u_s_e _t_h_e _n_e_w _m_u_l_t_i_p_a_r_t _e_n_c_o_d_i_n_g _s_c_h_e_m_e for the form.  You can
     do this either by calling ssssttttaaaarrrrttttffffoooorrrrmmmm(((()))) with an encoding type
     of $$$$CCCCGGGGIIII::::::::MMMMUUUULLLLTTTTIIIIPPPPAAAARRRRTTTT, or by calling the new method
     ssssttttaaaarrrrtttt____mmmmuuuullllttttiiiippppaaaarrrrtttt____ffffoooorrrrmmmm(((()))) instead of vanilla ssssttttaaaarrrrttttffffoooorrrrmmmm(((()))).

     PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss

     1.  The first parameter is the required name for the field (
         -name).

     2.  The optional second parameter is the starting value for
         the field contents to be used as the default file name (
         -default).

         The beta2 version of Netscape 2.0 currently doesn't pay
         any attention to this field, and so the starting value
         will always be blank.  Worse, the field loses its
         "sticky" behavior and forgets its previous contents.
         The starting value field is called for in the HTML
         specification, however, and possibly later versions of
         Netscape will honor it.



12/May/97         Last change: perl 5.003 with                 17






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     3.  The optional third parameter is the size of the field in
         characters (-size).

     4.  The optional fourth parameter is the maximum number of
         characters the field will accept (-maxlength).

     When the form is processed, you can retrieve the entered
     filename by calling _p_a_r_a_m().

            $filename = $query->param('uploaded_file');

     In Netscape Gold, the filename that gets returned is the
     full local filename on the rrrreeeemmmmooootttteeee uuuusssseeeerrrr''''ssss machine.  If the
     remote user is on a Unix machine, the filename will follow
     Unix conventions:

             /path/to/the/file

     On an MS-DOS/Windows and OS/2 machines, the filename will
     follow DOS conventions:

             C:\PATH\TO\THE\FILE.MSW

     On a Macintosh machine, the filename will follow Mac
     conventions:

             HD 40:Desktop Folder:Sort Through:Reminders

     The filename returned is also a file handle.  You can read
     the contents of the file using standard Perl file reading
     calls:

             # Read a text file and print it out
             while (<$filename>) {
                print;
             }

             # Copy a binary file to somewhere safe
             open (OUTFILE,">>/usr/local/web/users/feedback");
             while ($bytesread=read($filename,$buffer,1024)) {
                print OUTFILE $buffer;
             }

     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.  Future
     browsers may send other information as well (such as
     modification date and size). To retrieve this information,
     call _u_p_l_o_a_d_I_n_f_o().  It returns a reference to an associative
     array containing all the document headers.





12/May/97         Last change: perl 5.003 with                 18






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



            $filename = $query->param('uploaded_file');
            $type = $query->uploadInfo($filename)->{'Content-Type'};
            unless ($type eq 'text/html') {
               die "HTML FILES ONLY!";
            }

     If you are using a machine that recognizes "text" and
     "binary" 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.

     JAVASCRIPTING: The ----oooonnnnCCCChhhhaaaannnnggggeeee, ----oooonnnnFFFFooooccccuuuussss, ----oooonnnnBBBBlllluuuurrrr and ----
     oooonnnnSSSSeeeelllleeeecccctttt parameters are recognized.  See _t_e_x_t_f_i_e_l_d() for
     details.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA PPPPOOOOPPPPUUUUPPPP MMMMEEEENNNNUUUU

        print $query->popup_menu('menu_name',
                                 ['eenie','meenie','minie'],
                                 'meenie');

           -or-

        %labels = ('eenie'=>'your first choice',
                   'meenie'=>'your second choice',
                   'minie'=>'your third choice');
        print $query->popup_menu('menu_name',
                                 ['eenie','meenie','minie'],
                                 'meenie',\%labels);

             -or (named parameter style)-

        print $query->popup_menu(-name=>'menu_name',
                                 -values=>['eenie','meenie','minie'],
                                 -default=>'meenie',
                                 -labels=>\%labels);

     _p_o_p_u_p__m_e_n_u() creates a menu.

     1.  The required first argument is the menu's name (-name).

     2.  The required second argument (-values) is an array
         rrrreeeeffffeeeerrrreeeennnncccceeee 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".

     3.  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.




12/May/97         Last change: perl 5.003 with                 19






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     4.  The optional fourth parameter (-labels) is provided for
         people who want to use different values for the user-
         visible label inside the popup menu nd the value
         returned to your script.  It's a pointer to an
         associative array 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).

     When the form is processed, the selected value of the popup
     menu can be retrieved using:

           $popup_menu_value = $query->param('menu_name');

     JAVASCRIPTING: _p_o_p_u_p__m_e_n_u() recognizes the following event
     handlers:  ----oooonnnnCCCChhhhaaaannnnggggeeee, ----oooonnnnFFFFooooccccuuuussss, and ----oooonnnnBBBBlllluuuurrrr.  See the
     _t_e_x_t_f_i_e_l_d() section for details on when these handlers are
     called.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA SSSSCCCCRRRROOOOLLLLLLLLIIIINNNNGGGG LLLLIIIISSSSTTTT

        print $query->scrolling_list('list_name',
                                     ['eenie','meenie','minie','moe'],
                                     ['eenie','moe'],5,'true');
           -or-

        print $query->scrolling_list('list_name',
                                     ['eenie','meenie','minie','moe'],
                                     ['eenie','moe'],5,'true',
                                     \%labels);

             -or-

        print $query->scrolling_list(-name=>'list_name',
                                     -values=>['eenie','meenie','minie','moe'],
                                     -default=>['eenie','moe'],
                                     -size=>5,
                                     -multiple=>'true',
                                     -labels=>\%labels);

     _s_c_r_o_l_l_i_n_g__l_i_s_t() creates a scrolling list.

     PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

     1.  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.

     2.  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



12/May/97         Last change: perl 5.003 with                 20






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



         selected when the list first appears.  In the named
         parameter version, you can use the synonym "-defaults"
         for this parameter.

     3.  The optional fourth argument is the size of the list (-
         size).

     4.  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.

     5.  The optional sixth argument is a pointer to an
         associative array containing long user-visible labels
         for the list items (-labels).  If not provided, the
         values will be displayed.

         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:

               @selected = $query->param('list_name');


     JAVASCRIPTING: _s_c_r_o_l_l_i_n_g__l_i_s_t() recognizes the following
     event handlers:  ----oooonnnnCCCChhhhaaaannnnggggeeee, ----oooonnnnFFFFooooccccuuuussss, and ----oooonnnnBBBBlllluuuurrrr.  See
     _t_e_x_t_f_i_e_l_d() for the description of when these handlers are
     called.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA GGGGRRRROOOOUUUUPPPP OOOOFFFF RRRREEEELLLLAAAATTTTEEEEDDDD CCCCHHHHEEEECCCCKKKKBBBBOOOOXXXXEEEESSSS

        print $query->checkbox_group(-name=>'group_name',
                                     -values=>['eenie','meenie','minie','moe'],
                                     -default=>['eenie','moe'],
                                     -linebreak=>'true',
                                     -labels=>\%labels);

        print $query->checkbox_group('group_name',
                                     ['eenie','meenie','minie','moe'],
                                     ['eenie','moe'],'true',\%labels);

        HTML3-COMPATIBLE BROWSERS ONLY:

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


     _c_h_e_c_k_b_o_x__g_r_o_u_p() creates a list of checkboxes that are
     related by the same name.





12/May/97         Last change: perl 5.003 with                 21






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

     1.  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.

     2.  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.

     3.  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.

     4.  The optional fifth argument is a pointer to an
         associative array relating the checkbox values to the
         user-visible labels that will be printed next to them (-
         labels).  If not provided, the values will be used as
         the default.

     5.  HHHHTTTTMMMMLLLL3333----ccccoooommmmppppaaaattttiiiibbbblllleeee bbbbrrrroooowwwwsssseeeerrrrssss (such as Netscape) can take
         advantage of the optional parameters ----rrrroooowwwwssss, and ----
         ccccoooolllluuuummmmnnnnssss.  These parameters cause _c_h_e_c_k_b_o_x__g_r_o_u_p() 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.

         To include row and column headings in the returned
         table, you can use the ----rrrroooowwwwhhhheeeeaaaaddddeeeerrrr and ----ccccoooollllhhhheeeeaaaaddddeeeerrrr
         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
         checkboxes -- they're still a single named unit.

     When the form is processed, all checked boxes will be
     returned as a list under the parameter name 'group_name'.
     The values of the "on" checkboxes can be retrieved with:

           @turned_on = $query->param('group_name');

     The value returned by _c_h_e_c_k_b_o_x__g_r_o_u_p() is actually an array
     of button elements.  You can capture them and use them
     within tables, lists, or in other creative ways:




12/May/97         Last change: perl 5.003 with                 22






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



         @h = $query->checkbox_group(-name=>'group_name',-values=>\@values);
         &use_in_creative_way(@h);

     JAVASCRIPTING: _c_h_e_c_k_b_o_x__g_r_o_u_p() recognizes the ----oooonnnnCCCClllliiiicccckkkk
     parameter.  This specifies a JavaScript code fragment or
     function call to be executed every time the user clicks on
     any of the buttons in the group.  You can retrieve the
     identity of the particular button clicked on using the
     "this" variable.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA SSSSTTTTAAAANNNNDDDDAAAALLLLOOOONNNNEEEE CCCCHHHHEEEECCCCKKKKBBBBOOOOXXXX

         print $query->checkbox(-name=>'checkbox_name',
                                -checked=>'checked',
                                -value=>'ON',
                                -label=>'CLICK ME');

             -or-

         print $query->checkbox('checkbox_name','checked','ON','CLICK ME');

     _c_h_e_c_k_b_o_x() is used to create an isolated checkbox that isn't
     logically related to any others.

     PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

     1.  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.

     2.  The optional second parameter (-checked) specifies that
         the checkbox is turned on by default.  Synonyms are -
         selected and -on.

     3.  The optional third parameter (-value) specifies the
         value of the checkbox when it is checked.  If not
         provided, the word "on" is assumed.

     4.  The optional fourth parameter (-label) is the user-
         readable label to be attached to the checkbox.  If not
         provided, the checkbox name is used.

     The value of the checkbox can be retrieved using:

         $turned_on = $query->param('checkbox_name');

     JAVASCRIPTING: _c_h_e_c_k_b_o_x() recognizes the ----oooonnnnCCCClllliiiicccckkkk parameter.
     See _c_h_e_c_k_b_o_x__g_r_o_u_p() for further details.







12/May/97         Last change: perl 5.003 with                 23






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA RRRRAAAADDDDIIIIOOOO BBBBUUUUTTTTTTTTOOOONNNN GGGGRRRROOOOUUUUPPPP

        print $query->radio_group(-name=>'group_name',
                                  -values=>['eenie','meenie','minie'],
                                  -default=>'meenie',
                                  -linebreak=>'true',
                                  -labels=>\%labels);

             -or-

        print $query->radio_group('group_name',['eenie','meenie','minie'],
                                               'meenie','true',\%labels);

        HTML3-COMPATIBLE BROWSERS ONLY:

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

     _r_a_d_i_o__g_r_o_u_p() creates a set of logically-related radio
     buttons (turning one member of the group on turns the others
     off)

     PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

     1.  The first argument is the name of the group and is
         required (-name).

     2.  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
         _r_e_f_e_r_e_n_c_e in the second argument, either using an
         anonymous array, as shown, or by referencing a named
         array as in "\@foo".

     3.  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 "-" to start up with no
         buttons selected.

     4.  The optional fourth parameter (-linebreak) can be set to
         'true' to put line breaks between the buttons, creating
         a vertical list.

     5.  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.

     6.  HHHHTTTTMMMMLLLL3333----ccccoooommmmppppaaaattttiiiibbbblllleeee bbbbrrrroooowwwwsssseeeerrrrssss (such as Netscape) can take
         advantage of the optional parameters ----rrrroooowwwwssss, and ----



12/May/97         Last change: perl 5.003 with                 24






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



         ccccoooolllluuuummmmnnnnssss.  These parameters cause _r_a_d_i_o__g_r_o_u_p() 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.

         To include row and column headings in the returned
         table, you can use the ----rrrroooowwwwhhhheeeeaaaaddddeeeerrrr and ----ccccoooollllhhhheeeeaaaaddddeeeerrrr
         parameters.  Both of these accept a pointer to an array
         of headings to use.  The headings are just decorative.
         They don't reorganize the interpetation of the radio
         buttons -- they're still a single named unit.

     When the form is processed, the selected radio button can be
     retrieved using:

           $which_radio_button = $query->param('group_name');

     The value returned by _r_a_d_i_o__g_r_o_u_p() is actually an array of
     button elements.  You can capture them and use them within
     tables, lists, or in other creative ways:

         @h = $query->radio_group(-name=>'group_name',-values=>\@values);
         &use_in_creative_way(@h);


     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA SSSSUUUUBBBBMMMMIIIITTTT BBBBUUUUTTTTTTTTOOOONNNN

        print $query->submit(-name=>'button_name',
                             -value=>'value');

             -or-

        print $query->submit('button_name','value');

     _s_u_b_m_i_t() will create the query submission button.  Every
     form should have one of these.

     PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

     1.  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.
         The name will also be used as the user-visible label.
         Be aware that a few older browsers don't deal with this
         correctly and nnnneeeevvvveeeerrrr send back a value from a button.

     2.  The second argument (-value) is also optional.  This
         gives the button a value that will be passed to your
         script in the query string.




12/May/97         Last change: perl 5.003 with                 25






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     You can figure out which button was pressed by using
     different values for each one:

          $which_one = $query->param('button_name');

     JAVASCRIPTING: _r_a_d_i_o__g_r_o_u_p() recognizes the ----oooonnnnCCCClllliiiicccckkkk
     parameter.  See _c_h_e_c_k_b_o_x__g_r_o_u_p() for further details.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA RRRREEEESSSSEEEETTTT BBBBUUUUTTTTTTTTOOOONNNN

        print $query->reset

     _r_e_s_e_t() creates the "reset" button.  Note that it restores
     the form to its value from the last time the script was
     called, NOT necessarily to the defaults.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA DDDDEEEEFFFFAAAAUUUULLLLTTTT BBBBUUUUTTTTTTTTOOOONNNN

        print $query->defaults('button_label')

     _d_e_f_a_u_l_t_s() 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.

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA HHHHIIIIDDDDDDDDEEEENNNN FFFFIIIIEEEELLLLDDDD

             print $query->hidden(-name=>'hidden_name',
                                  -default=>['value1','value2'...]);

                     -or-

             print $query->hidden('hidden_name','value1','value2'...);

     _h_i_d_d_e_n() 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.

     PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

     1.  The first argument is required and specifies the name of
         this field (-name).

     2.  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

     Fetch the value of a hidden field this way:

          $hidden_value = $query->param('hidden_name');

     Note, that just like all the other form elements, the value



12/May/97         Last change: perl 5.003 with                 26






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     of a hidden field is "sticky".  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:

          $query->param('hidden_name','new','values','here');


     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA CCCCLLLLIIIICCCCKKKKAAAABBBBLLLLEEEE IIIIMMMMAAAAGGGGEEEE BBBBUUUUTTTTTTTTOOOONNNN

          print $query->image_button(-name=>'button_name',
                                     -src=>'/source/URL',
                                     -align=>'MIDDLE');

             -or-

          print $query->image_button('button_name','/source/URL','MIDDLE');

     _i_m_a_g_e__b_u_t_t_o_n() produces a clickable image.  When it's
     clicked on the position of the click is returned to your
     script as "button_name.x" and "button_name.y", where
     "button_name" is the name you've assigned to it.

     JAVASCRIPTING: _i_m_a_g_e__b_u_t_t_o_n() recognizes the ----oooonnnnCCCClllliiiicccckkkk
     parameter.  See _c_h_e_c_k_b_o_x__g_r_o_u_p() for further details.

     PPPPaaaarrrraaaammmmeeeetttteeeerrrrssss::::

     1.  The first argument (-name) is required and specifies the
         name of this field.

     2.  The second argument (-src) is also required and
         specifies the URL

may be TOP, BOTTOM or MIDDLE
     3. The third option (-
         align, optional) is an alignment type, and

     Fetch the value of the button this way:
          $x = $query->_p_a_r_a_m('button_name.x');
          $y = $query->_p_a_r_a_m('button_name.y');

     CCCCRRRREEEEAAAATTTTIIIINNNNGGGG AAAA JJJJAAAAVVVVAAAASSSSCCCCRRRRIIIIPPPPTTTT AAAACCCCTTTTIIIIOOOONNNN BBBBUUUUTTTTTTTTOOOONNNN

          print $query->button(-name=>'button_name',
                               -value=>'user visible label',
                               -onClick=>"do_something()");

             -or-

          print $query->button('button_name',"do_something()");

     _b_u_t_t_o_n() produces a button that is compatible with Netscape



12/May/97         Last change: perl 5.003 with                 27






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     2.0's JavaScript.  When it's pressed the fragment of
     JavaScript code pointed to by the ----oooonnnnCCCClllliiiicccckkkk parameter will be
     executed.  On non-Netscape browsers this form element will
     probably not even display.

NNNNEEEETTTTSSSSCCCCAAAAPPPPEEEE CCCCOOOOOOOOKKKKIIIIEEEESSSS
     Netscape browsers versions 1.1 and higher support a so-
     called "cookie" designed to help maintain state within a
     browser session.  CGI.pm has several methods that support
     cookies.

     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.

     In addition to the required name=value pair, each cookie has
     several optional attributes:

     1. an expiration time
         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 Netscape
         and restarts it.  If an expiration date isn't specified,
         the cookie will remain active until the user quits
         Netscape.

     2. a domain
         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
         ".capricorn.com", then Netscape will return the cookie
         to Web servers running on any of the machines
         "www.capricorn.com", "www2.capricorn.com",
         "feckless.capricorn.com", etc.  Domain names must
         contain at least two periods to prevent attempts to
         match on top level domains like ".edu".  If no domain is
         specified, then the browser will only return the cookie
         to servers on the host the cookie originated from.

     3. a path
         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 "/cgi-
         bin", then the cookie will be returned to each of the
         scripts "/cgi-bin/tally.pl", "/cgi-bin/order.pl", and
         "/cgi-bin/customer_service/complain.pl", but not to the
         script "/cgi-private/site_admin.pl".  By default, path



12/May/97         Last change: perl 5.003 with                 28






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



         is set to "/", which causes the cookie to be sent to any
         CGI script on your site.
         " .nr )I secure"n

     4. a
         If the "secure" 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.

     The interface to Netscape cookies is the ccccooooooookkkkiiiieeee(((()))) method:

         $cookie = $query->cookie(-name=>'sessionID',
                                  -value=>'xyzzy',
                                  -expires=>'+1h',
                                  -path=>'/cgi-bin/database',
                                  -domain=>'.capricorn.org',
                                  -secure=>1);
         print $query->header(-cookie=>$cookie);

     ccccooooooookkkkiiiieeee(((()))) creates a new cookie.  Its parameters include:

     ----nnnnaaaammmmeeee
         The name of the cookie (required).  This can be any
         string at all.  Although Netscape limits its cookie
         names to non-whitespace alphanumeric characters, CGI.pm
         removes this restriction by escaping and unescaping
         cookies behind the scenes.

     ----vvvvaaaalllluuuueeee
         The value of the cookie.  This can be any scalar value,
         array reference, or even associative array reference.
         For example, you can store an entire associative array
         into a cookie this way:

                 $cookie=$query->cookie(-name=>'family information',
                                        -value=>\%childrens_ages);


     ----ppppaaaatttthhhh
         The optional partial path for which this cookie will be
         valid, as described above.

     ----ddddoooommmmaaaaiiiinnnn
         The optional partial domain for which this cookie will
         be valid, as described above.

     ----eeeexxxxppppiiiirrrreeeessss
         The optional expiration date for this cookie.  The
         format is as described in the section on the hhhheeeeaaaaddddeeeerrrr(((())))
         method:

                 "+1h"  one hour from now



12/May/97         Last change: perl 5.003 with                 29






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     ----sssseeeeccccuuuurrrreeee
         If set to true, this cookie will only be used within a
         secure SSL session.

     The cookie created by _c_o_o_k_i_e() must be incorporated into the
     HTTP header within the string returned by the _h_e_a_d_e_r()
     method:

             print $query->header(-cookie=>$my_cookie);

     To create multiple cookies, give _h_e_a_d_e_r() an array
     reference:

             $cookie1 = $query->cookie(-name=>'riddle_name',
                                       -value=>"The Sphynx's Question");
             $cookie2 = $query->cookie(-name=>'answers',
                                       -value=>\%answers);
             print $query->header(-cookie=>[$cookie1,$cookie2]);

     To retrieve a cookie, request it by name by calling _c_o_o_k_i_e()
     method without the ----vvvvaaaalllluuuueeee parameter:

             use CGI;
             $query = new CGI;
             %answers = $query->cookie(-name=>'answers');
             # $query->cookie('answers') will work too!

     The cookie and CGI namespaces are separate.  If you have a
     parameter named 'answers' and a cookie named 'answers', the
     values retrieved by _p_a_r_a_m() and _c_o_o_k_i_e() are independent of
     each other.  However, it's simple to turn a CGI parameter
     into a cookie, and vice-versa:

        # turn a CGI parameter into a cookie
        $c=$q->cookie(-name=>'answers',-value=>[$q->param('answers')]);
        # vice-versa
        $q->param(-name=>'answers',-value=>[$q->cookie('answers')]);

     See the ccccooooooookkkkiiiieeee....ccccggggiiii example script for some ideas on how to
     use cookies effectively.

     NNNNOOOOTTTTEEEE:::: There appear to be some (undocumented) restrictions on
     Netscape cookies.  In Netscape 2.01, at least, I haven't
     been able to set more than three cookies at a time.  There
     may also be limits on the length of cookies.  If you need to
     store a lot of information, it's probably better to create a
     unique session ID, store it in a cookie, and use the session
     ID to locate an external file/database saved on the server's
     side of the connection.

WWWWOOOORRRRKKKKIIIINNNNGGGG WWWWIIIITTTTHHHH NNNNEEEETTTTSSSSCCCCAAAAPPPPEEEE FFFFRRRRAAAAMMMMEEEESSSS
     It's possible for CGI.pm scripts to write into several



12/May/97         Last change: perl 5.003 with                 30






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     browser panels and windows using Netscape's frame mechanism.
     There are three techniques for defining new frames
     programmatically:

     1. Create a <Frameset> document
         After writing out the HTTP header, instead of creating a
         standard HTML document using the _s_t_a_r_t__h_t_m_l() call,
         create a <FRAMESET> document that defines the frames on
         the page.  Specify your _s_c_r_i_p_t(s) (with appropriate
         parameters) as the SRC for each of the frames.

         There is no specific support for creating <FRAMESET>
         sections in CGI.pm, but the HTML is very simple to
         write.  See the frame documentation in Netscape's home
         pages for details

           http://home.netscape.com/assist/net_sites/frames.html


     2. Specify the destination for the document in the HTTP header
         You may provide a ----ttttaaaarrrrggggeeeetttt parameter to the _h_e_a_d_e_r()
         method:

             print $q->_h_e_a_d_e_r(-target=>'ResultsWindow');

         This will tell Netscape to load the output of your
         script into the frame named "ResultsWindow".  If a frame
         of that name doesn't already exist, Netscape will pop up
         a new window and load your script's document into that.
         There are a number of magic names that you can use for
         targets.  See the frame documents on Netscape's home
         pages for details.

     3. Specify the destination for the document in the <FORM> tag
         You can specify the frame to load in the FORM tag
         itself.  With CGI.pm it looks like this:

             print $q->startform(-target=>'ResultsWindow');

         When your script is reinvoked by the form, its output
         will be loaded into the frame named "ResultsWindow".  If
         one doesn't already exist a new window will be created.

     The script "frameset.cgi" 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.

DDDDEEEEBBBBUUUUGGGGGGGGIIIINNNNGGGG
     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



12/May/97         Last change: perl 5.003 with                 31






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     your script into reading from environment variables).  You
     can pass keywords like this:

         your_script.pl keyword1 keyword2 keyword3

     or this:

        your_script.pl keyword1+keyword2+keyword3

     or this:

         your_script.pl name1=value1 name2=value2

     or this:

         your_script.pl name1=value1&name2=value2

     or even as newline-delimited parameters on standard input.

     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:

        your_script.pl "name1='I am a long value'" "name2=two\ words"


     DDDDUUUUMMMMPPPPIIIINNNNGGGG OOOOUUUUTTTT AAAALLLLLLLL TTTTHHHHEEEE NNNNAAAAMMMMEEEE////VVVVAAAALLLLUUUUEEEE PPPPAAAAIIIIRRRRSSSS

     The _d_u_m_p() 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:

         print $query->dump


     Produces something that looks like:

         <UL>
         <LI>name1
             <UL>
             <LI>value1
             <LI>value2
             </UL>
         <LI>name2
             <UL>
             <LI>value1
             </UL>
         </UL>

     You can pass a value of 'true' to _d_u_m_p() in order to get it
     to print the results out as plain text, suitable for



12/May/97         Last change: perl 5.003 with                 32






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     incorporating into a <PRE> section.

     As a shortcut, as of version 1.56 you can interpolate the
     entire CGI object into a string and it will be replaced with
     the a nice HTML dump shown above:

         $query=new CGI;
         print "<H2>Current Values</H2> $query\n";


FFFFEEEETTTTCCCCHHHHIIIINNNNGGGG EEEENNNNVVVVIIIIRRRROOOONNNNMMMMEEEENNNNTTTT VVVVAAAARRRRIIIIAAAABBBBLLLLEEEESSSS
     Some of the more useful environment variables can be fetched
     through this interface.  The methods are as follows:

     aaaacccccccceeeepppptttt(((())))
         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 $query-
         >_a_c_c_e_p_t('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.

     rrrraaaawwww____ccccooooooookkkkiiiieeee(((())))
         Returns the HTTP_COOKIE variable, an HTTP extension
         implemented by Netscape browsers version 1.1 and higher.
         Cookies have a special format, and this method call just
         returns the raw form (?cookie dough).  See _c_o_o_k_i_e() for
         ways of setting and retrieving cooked cookies.

     uuuusssseeeerrrr____aaaaggggeeeennnntttt(((())))
         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 $query-
         >_u_s_e_r__a_g_e_n_t(netscape);

     ppppaaaatttthhhh____iiiinnnnffffoooo(((())))
         Returns additional path information from the script URL.
         E.G. fetching /cgi-bin/your_script/additional/stuff will
         result in $query->_p_a_t_h__i_n_f_o() returning
         "additional/stuff".

         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.



12/May/97         Last change: perl 5.003 with                 33






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     ppppaaaatttthhhh____ttttrrrraaaannnnssssllllaaaatttteeeedddd(((())))
         As per _p_a_t_h__i_n_f_o() but returns the additional path
         information translated into a physical path, e.g.
         "/usr/local/etc/httpd/htdocs/additional/stuff".

         The Microsoft IIS is broken with respect to the
         translated path as well.

     rrrreeeemmmmooootttteeee____hhhhoooosssstttt(((())))
         Returns either the remote host name or IP address.  if
         the former is unavailable.

refering scripts.
     ssssccccrrrriiiipppptttt____nnnnaaaammmmeeee(((()))) Return the script name as a partial URL, for self-

     rrrreeeeffffeeeerrrreeeerrrr(((())))
         Return the URL of the page the browser was viewing prior
         to fetching your script.  Not available for all
         browsers.

     aaaauuuutttthhhh____ttttyyyyppppeeee (((())))
         Return the authorization/verification method in use for
         this script, if any.

     sssseeeerrrrvvvveeeerrrr____nnnnaaaammmmeeee (((())))
         Returns the name of the server, usually the machine's
         host name.

     vvvviiiirrrrttttuuuuaaaallll____hhhhoooosssstttt (((())))
         When using virtual hosts, returns the name of the host
         that the browser attempted to contact

     sssseeeerrrrvvvveeeerrrr____ssssooooffffttttwwwwaaaarrrreeee (((())))
         Returns the server software and version number.

     rrrreeeemmmmooootttteeee____uuuusssseeeerrrr (((())))
         Return the authorization/verification name used for user
         verification, if this script is protected.

     uuuusssseeeerrrr____nnnnaaaammmmeeee (((())))
         Attempt to obtain the remote user's name, using a
         variety of different techniques.  This only works with
         older browsers such as Mosaic.  Netscape does not
         reliably report the user name!

     rrrreeeeqqqquuuueeeesssstttt____mmmmeeeetttthhhhoooodddd(((())))
         Returns the method used to access your script, usually
         one of 'POST', 'GET' or 'HEAD'.

CCCCRRRREEEEAAAATTTTIIIINNNNGGGG HHHHTTTTMMMMLLLL EEEELLLLEEEEMMMMEEEENNNNTTTTSSSS::::
     In addition to its shortcuts for creating form elements,
     CGI.pm defines general HTML shortcut methods as well.  HTML



12/May/97         Last change: perl 5.003 with                 34






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     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.

     This example shows how to use the HTML methods:

             $q = new CGI;
             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;

     This results in the following HTML code (extra newlines have
     been added for readability):

             <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>

     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):

             use CGI shortcuts;      # IMPORT HTML SHORTCUTS
             print blockquote(
                          "Many years ago on the island of",
                          a({href=>"http://crete.org/"},"Crete"),
                          "there lived a minotaur named",
                          strong("Fred."),
                          ),
                    hr;


     PPPPRRRROOOOVVVVIIIIDDDDIIIINNNNGGGG AAAARRRRGGGGUUUUMMMMEEEENNNNTTTTSSSS TTTTOOOO HHHHTTTTMMMMLLLL SSSSHHHHOOOORRRRTTTTCCCCUUUUTTTTSSSS

     The HTML methods will accept zero, one or multiple
     arguments.  If you provide no arguments, you get a single
     tag:

             print hr;
             #  gives "<hr>"

     If you provide one or more string arguments, they are
     concatenated together with spaces and placed between opening
     and closing tags:



12/May/97         Last change: perl 5.003 with                 35






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



             print h1("Chapter","1");
             # gives "<h1>Chapter 1</h1>"

     If the first argument is an associative array reference,
     then the keys and values of the associative array become the
     HTML tag's attributes:

             print a({href=>'fred.html',target=>'_new'},
                     "Open a new frame");
             # gives <a href="fred.html",target="_new">Open a new frame</a>

     You are free to use CGI.pm-style dashes in front of the
     attribute names if you prefer:

             print img {-src=>'fred.gif',-align=>'LEFT'};
             # gives <img ALIGN="LEFT" SRC="fred.gif">


     GGGGeeeennnneeeerrrraaaattttiiiinnnngggg nnnneeeewwww HHHHTTTTMMMMLLLL ttttaaaaggggssss

     Since no mere mortal can keep up with Netscape and Microsoft
     as they battle it out for control of HTML, the code that
     generates HTML tags is general and extensible.  You can
     create new HTML tags freely just by referring to them on the
     import line:

             use CGI shortcuts,winkin,blinkin,nod;

     Now, in addition to the standard CGI shortcuts, you've
     created HTML tags named "winkin", "blinkin" and "nod".  You
     can use them like this:

             print blinkin {color=>'blue',rate=>'fast'},"Yahoo!";
             # <blinkin COLOR="blue" RATE="fast">Yahoo!</blinkin>


IIIIMMMMPPPPOOOORRRRTTTTIIIINNNNGGGG CCCCGGGGIIII MMMMEEEETTTTHHHHOOOODDDD CCCCAAAALLLLLLLLSSSS IIIINNNNTTTTOOOO YYYYOOOOUUUURRRR NNNNAAAAMMMMEEEE SSSSPPPPAAAACCCCEEEE
     As a convenience, you can import most of the CGI method
     calls directly into your name space.  The syntax for doing
     this is:

             use CGI <list of methods>;

     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 ppppaaaarrrraaaammmm(((())))
     and hhhheeeeaaaaddddeeeerrrr(((()))) methods, and then use them directly:

             use CGI param,header;
             print header('text/plain');
             $zipcode = param('zipcode');




12/May/97         Last change: perl 5.003 with                 36






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     You can import groups of methods by referring to a number of
     special names:

     ccccggggiiii Import all CGI-handling methods, such as ppppaaaarrrraaaammmm(((()))),
         ppppaaaatttthhhh____iiiinnnnffffoooo(((()))) and the like.

     ffffoooorrrrmmmm
         Import all fill-out form generating methods, such as
         tttteeeexxxxttttffffiiiieeeelllldddd(((()))).

     hhhhttttmmmmllll2222
         Import all methods that generate HTML 2.0 standard
         elements.

     hhhhttttmmmmllll3333
         Import all methods that generate HTML 3.0 proposed
         elements (such as <table>, <super> and <sub>).

     nnnneeeettttssssccccaaaappppeeee
         Import all methods that generate Netscape-specific HTML
         extensions.

     sssshhhhoooorrrrttttccccuuuuttttssss
         Import all HTML-generating shortcuts (i.e. 'html2' +
         'html3' +

     ssssttttaaaannnnddddaaaarrrrdddd
         Import "standard" features, 'html2', 'form' and 'cgi'.

     aaaallllllll Import all the available methods.  For the full list,
         see the CGI.pm code, where the variable %TAGS is
         defined.

     Note that in the interests of execution speed CGI.pm does
     nnnnooootttt use the standard the _E_x_p_o_r_t_e_r manpage syntax for
     specifying load symbols.  This may change in the future.

     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
     ppppaaaarrrraaaammmm(((()))), tttteeeexxxxttttffffiiiieeeelllldddd(((()))), ssssuuuubbbbmmmmiiiitttt(((()))) and the like.  (If you need
     direct access to the CGI object, you can find it in the
     global variable $$$$CCCCGGGGIIII::::::::QQQQ).  By importing CGI.pm methods, you
     can create visually elegant scripts:










12/May/97         Last change: perl 5.003 with                 37






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



        use CGI standard,html2;
        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;


UUUUSSSSIIIINNNNGGGG NNNNPPPPHHHH SSSSCCCCRRRRIIIIPPPPTTTTSSSS
     NPH, or "no-parsed-header", scripts bypass the server
     completely by sending the complete HTTP header directly to
     the browser.  This has slight performance benefits, but is
     of most use for taking advantage of HTTP extensions that are
     not directly supported by your server, such as server push
     and PICS headers.

     Servers use a variety of conventions for designating CGI
     scripts as NPH.  Many Unix servers look at the beginning of
     the script's name for the prefix "nph-".  The Macintosh
     WebSTAR server and Microsoft's Internet Information Server,
     in contrast, try to decide whether a program is an NPH
     script by examining the first line of script output.

     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 _h_e_a_d_e_r() and _r_e_d_i_r_e_c_t() methods are
     called.

     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.



12/May/97         Last change: perl 5.003 with                 38






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     There are a number of ways to put CGI.pm into NPH mode:
     " .nr )I :nph"n

     In the uuuusssseeee statement Simply add

                use CGI qw(:standard :nph)


     By calling the nnnnpppphhhh(((()))) method:
         Call nnnnpppphhhh(((()))) with a non-zero parameter at any point after
         using CGI.pm in your program.

               CGI->nph(1)


statements:
     By using ----nnnnpppphhhh parameters in the hhhheeeeaaaaddddeeeerrrr(((()))) and rrrreeeeddddiiiirrrreeeecccctttt(((())))

               print $q->header(-nph=&gt;1);


AAAAUUUUTTTTHHHHOOOORRRR IIIINNNNFFFFOOOORRRRMMMMAAAATTTTIIIIOOOONNNN
     Copyright 1995,1996, Lincoln D. Stein.  All rights reserved.
     It may be used and modified freely, but I do request that
     this copyright notice remain attached to the file.  You may
     modify this module as you wish, but if you redistribute a
     modified version, please attach a note listing the
     modifications you have made.

     Address bug reports and comments to:
     lstein@genome.wi.mit.edu

CCCCRRRREEEEDDDDIIIITTTTSSSS
     Thanks very much to:

     Matt Heffron (heffron@falstaff.css.beckman.com)

     James Taylor (james.taylor@srs.gov)

     Scott Anguish <sanguish@digifix.com>

     Mike Jewell (mlj3u@virginia.edu)

     Timothy Shimmin (tes@kbs.citri.edu.au)

     Joergen Haegg (jh@axis.se)

     Laurent Delfosse (delfosse@csgrad1.cs.wvu.edu)

     Richard Resnick (applepi1@aol.com)





12/May/97         Last change: perl 5.003 with                 39






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



     Craig Bishop (csb@barwonwater.vic.gov.au)

     Tony Curtis (tc@vcpc.univie.ac.at)

     Tim Bunce (Tim.Bunce@ig.co.uk)

     Tom Christiansen (tchrist@convex.com)

     Andreas Koenig (k@franz.ww.TU-Berlin.DE)

     Tim MacKenzie (Tim.MacKenzie@fulcrum.com.au)

     Kevin B. Hendricks (kbhend@dogwood.tyler.wm.edu)

     Stephen Dahmen (joyfire@inxpress.net)

     Ed Jordan (ed@fidalgo.net)

     David Alan Pisoni (david@cnation.com)

     ...and many many more...
         for suggestions and bug fixes.

AAAA CCCCOOOOMMMMPPPPLLLLEEEETTTTEEEE EEEEXXXXAAAAMMMMPPPPLLLLEEEE OOOOFFFF AAAA SSSSIIIIMMMMPPPPLLLLEEEE FFFFOOOORRRRMMMM----BBBBAAAASSSSEEEEDDDD SSSSCCCCRRRRIIIIPPPPTTTT
             #!/usr/local/bin/perl

             use CGI;

             $query = new CGI;


























12/May/97         Last change: perl 5.003 with                 40






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



             print $query->header;
             print $query->start_html("Example CGI.pm Form");
             print "<H1> Example CGI.pm Form</H1>\n";
             &print_prompt($query);
             &do_work($query);
             &print_tail;
             print $query->end_html;

             sub print_prompt {
                my($query) = @_;

                print $query->startform;
                print "<EM>What's your name?</EM><BR>";
                print $query->textfield('name');
                print $query->checkbox('Not my real name');

                print "<P><EM>Where can you find English Sparrows?</EM><BR>";
                print $query->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>",
                     $query->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 $query->popup_menu(-name=>'Color',
                                         -values=>['black','brown','red','yellow'],
                                         -default=>'red');

                print $query->hidden('Reference','Monty Python and the Holy Grail');

                print "<P><EM>What have you got there?</EM><BR>";
                print $query->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 $query->textarea(-name=>'Comments',
                                       -rows=>10,
                                       -columns=>50);

                print "<P>",$query->reset;
                print $query->submit('Action','Shout');
                print $query->submit('Action','Scream');



12/May/97         Last change: perl 5.003 with                 41






/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)User Contributed Perl Documentation/USR/LOCAL/LIB/PERL5/SITE_PERL/CGI(1)



                print $query->endform;
                print "<HR>\n";
             }

             sub do_work {
                my($query) = @_;
                my(@values,$key);

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

                foreach $key ($query->param) {
                   print "<STRONG>$key</STRONG> -> ";
                   @values = $query->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
             }


BBBBUUUUGGGGSSSS
     This module has grown large and monolithic.  Furthermore
     it's doing many things, such as handling URLs, parsing CGI
     input, writing HTML, etc., that are also done in the LWP
     modules. It should be discarded in favor of the CGI::*
     modules, but somehow I continue to work on it.

     Note that the code is truly contorted in order to avoid
     spurious warnings when programs are run with the ----wwww switch.

SSSSEEEEEEEE AAAALLLLSSSSOOOO
     the _C_G_I::_C_a_r_p manpage, the _U_R_I::_U_R_L manpage, the
     _C_G_I::_R_e_q_u_e_s_t manpage, the _C_G_I::_M_i_n_i_S_v_r manpage, the
     _C_G_I::_B_a_s_e manpage, the _C_G_I::_F_o_r_m manpage, the _C_G_I::_A_p_a_c_h_e
     manpage, the _C_G_I::_S_w_i_t_c_h manpage, the _C_G_I::_P_u_s_h manpage, the
     _C_G_I::_F_a_s_t manpage













12/May/97         Last change: perl 5.003 with                 42