*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> perl5/CGI (3)              
Title
Content
Arch
Section
 

Contents


CGI(3)									CGI(3)


NAME    [Toc]    [Back]

     CGI - Simple Common Gateway Interface Class

SYNOPSIS    [Toc]    [Back]

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

ABSTRACT    [Toc]    [Back]

     This perl library uses perl5 objects to make it easy to create Web	fillout
 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/

INSTALLATION    [Toc]    [Back]

     CGI is a part of the base Perl installation.  However, you	may need to
     install a newer version someday.  Therefore:

     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:





									Page 1






CGI(3)									CGI(3)



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

     The CGI distribution also comes with a cute module	called the CGI::Carp
     manpage.  It redefines the	die(), warn(), confess() and croak() 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.

DESCRIPTION    [Toc]    [Back]

     CREATING A	NEW QUERY OBJECT:

	  $query = new CGI;

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

     CREATING A	NEW QUERY OBJECT FROM AN INPUT FILE

	  $query = new CGI(INPUTFILE);

     If	you provide a file handle to the new() method, it will read parameters
     from the file (or STDIN, or whatever).  The file can be in	any of the
     forms describing below under debugging (i.e. a series of newline
     delimited TAG=VALUE pairs will work).  Conveniently, this type of file is
     created by	the save() method (see below).	Multiple records can be	saved
     and restored.

     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:

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

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



									Page 2






CGI(3)									CGI(3)



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


     FETCHING A	LIST OF	KEYWORDS FROM THE QUERY:

	  @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 keywords() method.

     FETCHING THE NAMES	OF ALL THE PARAMETERS PASSED TO	YOUR SCRIPT:

	  @names = $query->param

     If	the script was invoked with a parameter	list (e.g.
     "name1=value1&name2=value2&name3=value3"),	the param() 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).

     FETCHING THE VALUE	OR VALUES OF A SINGLE NAMED PARAMETER:

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

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

     Pass the param() method a single argument to fetch	the value of the named
     parameter.	If the parameter is multivalued	(e.g. from multiple selections
     in	a scrolling list), you can ask to receive an array.  Otherwise the
     method will return	a single value.

     SETTING THE VALUE(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.)

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





									Page 3






CGI(3)									CGI(3)



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

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


     APPENDING ADDITIONAL VALUES TO A NAMED PARAMETER:

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

     IMPORTING ALL PARAMETERS INTO A NAMESPACE:

	$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 import().  As of	version	2.20,
     this name has been	removed	completely to avoid conflict with the built-in
     Perl module import	operator.

     DELETING A	PARAMETER COMPLETELY:

	 $query->delete('foo');

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

     DELETING ALL PARAMETERS:

     $query->delete_all();

     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.

     SAVING THE	STATE OF THE FORM TO A FILE:

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





									Page 4






CGI(3)									CGI(3)



     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 new.  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";
	}

     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.

     CREATING A	SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:

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

     self_url()	will return a URL, that, when selected,	will reinvoke this
     script with all its state information intact.  This is most useful	when
     you want to jump around within the	document using internal	anchors	but
     you don't want to disrupt the current contents of the form(s).  Something
     like this will do the trick.




									Page 5






CGI(3)									CGI(3)



	  $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 url() 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 query_string():

	 $the_string = $query->query_string;


     COMPATIBILITY WITH	CGI-LIB.PL

     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
	 print "The value of the antique is $in{antique}.\n";

     CGI.pm's ReadParse() routine creates a tied variable named	%in, which can
     be	accessed to obtain the query variables.	 Like ReadParse, you can also
     provide your own variable.	 Infrequently used features of ReadParse, such
     as	the creation of	@in and	$in variables, are not supported.

     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.

     CALLING CGI FUNCTIONS THAT	TAKE MULTIPLE ARGUMENTS

     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



									Page 6






CGI(3)									CGI(3)



     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 -Name or
     -NAME.  You don't have to use the hyphen if you don't want	to.  After
     creating a	CGI object, call the use_named_parameters() 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.

     CREATING THE HTTP HEADER:

	     print $query->header;

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




									Page 7






CGI(3)									CGI(3)



		  -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');

     header() returns the Content-type:	header.	 You can provide your own MIME
     type if you choose, otherwise it defaults to text/html.  An optional
     second parameter specifies	the status code	and a human-readable message.
     For example, you can specify 204, "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:

	 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	-type,
     -status, -expires,	and -cookie.  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 -expires 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

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

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



									Page 8






CGI(3)									CGI(3)



     attributes	such as	expiration time.  Use the cookie() method to create
     and retrieve session cookies.

     The -nph 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.

     GENERATING	A REDIRECTION INSTRUCTION

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

     redirects the browser elsewhere.  If you use redirection like this, you
     should not	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 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 -nph 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.

     CREATING THE HTML HEADER:

	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'},
				 -style=>{'src'=>'/styles/style1.css'},
				 -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



									Page 9






CGI(3)									CGI(3)



     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 -xbase 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 -target allows you to	provide	a default target frame for all
     the links and fill-out forms on the page.	See 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 -meta 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 header() method.
     For example, if you want to send the Refresh: header, do it in the
     header() method:

	 print $q->header(-Refresh=>'10; URL=http://www.capricorn.com');

     The -style	tag is used to incorporate cascading stylesheets into your
     code.  See	the section on CASCADING STYLESHEETS for more information.

     You can place other arbitrary HTML	elements to the	<HEAD> section with
     the -head tag.  For example, to place the rarely-used <LINK> element in
     the head section, use this:

	 print $q->header(-head=>link({-rel=>'next',
				       -href=>'http://www.capricorn.com/s2.html'}));

     To	incorporate multiple HTML elements into	the <HEAD> section, just pass
     an	array reference:

	 print $q->header(-head=>[ link({-rel=>'next',
					 -href=>'http://www.capricorn.com/s2.html'}),
				   link({-rel=>'previous',
					 -href=>'http://www.capricorn.com/s1.html'})
				  ]
			  );



								       Page 10






CGI(3)									CGI(3)



     JAVASCRIPTING: The	-script, -noScript, -onLoad and	-onUnload parameters
     are used to add Netscape JavaScript calls to your pages.  -script 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 -onLoad and -onUnload 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
     -script field:

	   $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 -noScript parameter to pass some HTML text	that will be displayed
     on	browsers that do not have JavaScript (or browsers where	JavaScript is
     turned off).

     Netscape 3.0 recognizes several attributes	of the <SCRIPT>	tag, including
     LANGUAGE and SRC.	The latter is particularly interesting,	as it allows
     you to keep the JavaScript	code in	a file or CGI script rather than
     cluttering	up each	page with the source.  To use these attributes pass a
     HASH reference in the -script parameter containing	one or more of
     -language,	-src, or -code:







								       Page 11






CGI(3)									CGI(3)



	 print $q->start_html(-title=>'The Riddle of the Sphinx',
			      -script=>{-language=>'JAVASCRIPT',
					-src=>'/javascript/sphinx.js'}
			      );

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

     See

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

     for more information about	JavaScript.

     The old-style positional parameters are as	follows:

     Parameters:

     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.

     ENDING THE	HTML DOCUMENT:

	     print $query->end_html

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

CREATING FORMS    [Toc]    [Back]

     General note  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.

     Another note The default values that you specify for the forms are	only
     used the first 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.



								       Page 12






CGI(3)									CGI(3)



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

     (1) call the param() 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);

     Yet another note 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 autoEscape() method with a false value immediately after
     creating the CGI object:

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



     CREATING AN ISINDEX TAG    [Toc]    [Back]

	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.

     STARTING AND ENDING A FORM    [Toc]    [Back]

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

	     -or





								       Page 13






CGI(3)									CGI(3)



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

     startform() 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

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

     Startform()'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:

     application/x-www-form-urlencoded
	 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 $CGI::URL_ENCODED.

     multipart/form-data
	 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 upload" feature of Netscape 2.0 forms.  For your
	 convenience, CGI.pm stores the	name of	this encoding type in
	 $CGI::MULTIPART

	 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 startform()	method uses the	older form of encoding
     by	default.  If you want to use the newer form of encoding	by default,
     you can call start_multipart_form() instead of startform().

     JAVASCRIPTING: The	-name and -onSubmit 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 start_html() for details.




								       Page 14






CGI(3)									CGI(3)



     CREATING A	TEXT FIELD

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

     textfield() will return a text input field.

     Parameters    [Toc]    [Back]

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

     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 -onChange, -onFocus, -onBlur and
     -onSelect 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



								       Page 15






CGI(3)									CGI(3)



     text that is selected.

     CREATING A	BIG TEXT FIELD

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

	     -or

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

     textarea()	is just	like textfield,	but it allows you to specify rows and
     columns for a multiline text entry	box.  You can provide a	starting value
     for the field, which can be long and contain multiple lines.

     JAVASCRIPTING: The	-onChange, -onFocus, -onBlur and -onSelect parameters
     are recognized.  See textfield().

     CREATING A	PASSWORD FIELD

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

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

     JAVASCRIPTING: The	-onChange, -onFocus, -onBlur and -onSelect parameters
     are recognized.  See textfield().

     CREATING A	FILE UPLOAD FIELD

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

     filefield() will return a file upload field for Netscape 2.0 browsers.
     In	order to take full advantage of	this you must use the new multipart
     encoding scheme for the form.  You	can do this either by calling
     startform() with an encoding type of $CGI::MULTIPART, or by calling the
     new method	start_multipart_form() instead of vanilla startform().




								       Page 16






CGI(3)									CGI(3)



     Parameters    [Toc]    [Back]

     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.

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

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

     In	Netscape Gold, the filename that gets returned is the full local
     filename on the remote user's 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;
	     }








								       Page 17






CGI(3)									CGI(3)



	     # 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 uploadInfo().	 It returns a reference	to an associative array
     containing	all the	document headers.

	    $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	-onChange, -onFocus, -onBlur and -onSelect parameters
     are recognized.  See textfield() for details.

     CREATING A	POPUP MENU

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

     popup_menu() creates a menu.





								       Page 18






CGI(3)									CGI(3)



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

     2.	 The required second argument (-values)	is an array reference
	 containing the	list of	menu items in the menu.	 You can pass the
	 method	an anonymous array, as shown in	the example, or	a reference to
	 a named array,	such as	"\@foo".

     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.

     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: popup_menu() recognizes the	following event	handlers:
     -onChange,	-onFocus, and -onBlur.	See the	textfield() section for
     details on	when these handlers are	called.

     CREATING A	SCROLLING LIST

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

     scrolling_list() creates a	scrolling list.






								       Page 19






CGI(3)									CGI(3)



     Parameters:

     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 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: scrolling_list() recognizes	the following event handlers:
     -onChange,	-onFocus, and -onBlur.	See textfield()	for the	description of
     when these	handlers are called.

     CREATING A	GROUP OF RELATED CHECKBOXES

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




								       Page 20






CGI(3)									CGI(3)



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

     Parameters:

     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.	 HTML3-compatible browsers (such as Netscape) can take advantage of
	 the optional parameters -rows,	and -columns.  These parameters	cause
	 checkbox_group() to return an HTML3 compatible	table containing the
	 checkbox group	formatted with the specified number of rows and
	 columns.  You can provide just	the -columns parameter if you wish;
	 checkbox_group	will calculate the correct number of rows for you.

	 To include row	and column headings in the returned table, you can use
	 the -rowheader	and -colheader 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 checkbox_group() is actually	an array of button
     elements.	You can	capture	them and use them within tables, lists,	or in
     other creative ways:

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

     JAVASCRIPTING: checkbox_group() recognizes	the -onClick parameter.	 This



								       Page 21






CGI(3)									CGI(3)



     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.

     CREATING A	STANDALONE CHECKBOX

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

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

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

     Parameters:

     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: checkbox() recognizes the -onClick parameter.  See
     checkbox_group() for further details.

     CREATING A	RADIO BUTTON GROUP

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

	     -or


								       Page 22






CGI(3)									CGI(3)



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

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

     Parameters:

     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 reference 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.	 HTML3-compatible browsers (such as Netscape) can take advantage of
	 the optional parameters -rows,	and -columns.  These parameters	cause
	 radio_group() to return an HTML3 compatible table containing the
	 radio group formatted with the	specified number of rows and columns.
	 You can provide just the -columns parameter if	you wish; radio_group
	 will calculate	the correct number of rows for you.

	 To include row	and column headings in the returned table, you can use
	 the -rowheader	and -colheader 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:





								       Page 23






CGI(3)									CGI(3)



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

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

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


     CREATING A	SUBMIT BUTTON

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

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

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

     Parameters:

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

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

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

     JAVASCRIPTING: radio_group() recognizes the -onClick parameter.  See
     checkbox_group() for further details.

     CREATING A	RESET BUTTON

	print $query->reset

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







								       Page 24






CGI(3)									CGI(3)



     CREATING A	DEFAULT	BUTTON

	print $query->defaults('button_label')

     defaults()	creates	a button that, when invoked, will cause	the form to be
     completely	reset to its defaults, wiping out all the changes the user
     ever made.

     CREATING A	HIDDEN FIELD

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

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

     hidden() produces a text field that can't be seen by the user.  It	is
     useful for	passing	state variable information from	one invocation of the
     script to the next.

     Parameters:

     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 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');


     CREATING A	CLICKABLE IMAGE	BUTTON

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

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




								       Page 25






CGI(3)									CGI(3)



     image_button() 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: image_button() recognizes the -onClick parameter.  See
     checkbox_group() for further details.

     Parameters:

     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

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

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

     CREATING A	JAVASCRIPT ACTION BUTTON

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

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

     button() produces a button	that is	compatible with	Netscape 2.0's
     JavaScript.  When it's pressed the	fragment of JavaScript code pointed to
     by	the -onClick parameter will be executed.  On non-Netscape browsers
     this form element will probably not even display.

NETSCAPE COOKIES    [Toc]    [Back]

     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:






								       Page 26






CGI(3)									CGI(3)



     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 is set	to "/",	which
	 causes	the cookie to be sent to any CGI script	on your	site.

     4.	a "secure" flag
	 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 cookie() method:

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

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

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





								       Page 27






CGI(3)									CGI(3)



     -value
	 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);


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

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

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

		 "+1h"	one hour from now


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

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

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

     To	create multiple	cookies, give header() 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 cookie() method
     without the -value	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
     param() and cookie() are independent of each other.  However, it's	simple



								       Page 28






CGI(3)									CGI(3)



     to	turn a CGI parameter into a cookie, and	vice-versa:

	# turn a CGI parameter into a cookie
	$c=$q->cookie(-name=

 Similar pages
Name OS Title
sitemgr.cgi IRIX sitemgr primary Common Gateway Interface process
sitemgr IRIX sitemgr primary Common Gateway Interface process
smdbf.cgi IRIX sitemgr database creation Common Gateway Interface process
sitestat.cgi IRIX sitemgr HTTP log file analysis Common Gateway Interface process
XmSimpleSpinBox HP-UX a simple SpinBox widget class
ciss FreeBSD Common Interface for SCSI-3 Support driver
perltie IRIX how to hide an object class in a simple variable
perltie OpenBSD how to hide an object class in a simple variable
CGI::Push IRIX Simple Interface to Server Push
dialog_tree FreeBSD provide a simple ncurses-based GUI interface
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service