Apache::ASP
<% Web Applications with Apache & mod_perl %>
  INTRO
  INSTALL
  CONFIG
  SYNTAX
  EVENTS
  OBJECTS
  SSI
  SESSIONS
  XML/XSLT
% CGI
  PERLSCRIPT
  STYLE GUIDE
  FAQ
  TUNING
  CREDITS
  SUPPORT
  SITES USING
  TESTIMONIALS
  RESOURCES
  TODO
  CHANGES
  LICENSE

  EXAMPLES

Powered by Apache::ASP
Powered by ModPerl and Apache
Powered by Perl
CGI
CGI has been the standard way of deploying web applications long before ASP came along. In the CGI gateway world, CGI.pm has been a widely used module in building CGI applications, and Apache::ASP is compatible with scripts written with CGI.pm. Also, as of version 2.19, Apache::ASP can run in standalone CGI mode for the Apache web server without mod_perl being available. See "Standalone CGI Mode" section below.
Following are some special notes with respect to compatibility with CGI and CGI.pm. Use of CGI.pm in any of these ways was made possible through a great amount of work, and is not guaranteed to be portable with other perl ASP implementations, as other ASP implementations will likely be more limited.

Standalone CGI Mode, without mod_perl CGI headers
CGI.pm print()ing CGI
Query Object Initialization File Upload

Standalone CGI Mode, without mod_perl

As of version 2.19, Apache::ASP scripts may be run as standalone
CGI scripts without mod_perl being loaded into Apache.  Work
to date has only been done with mod_cgi scripts under Apache on a
Unix platform, and it is unlikely to work under other web servers 
or Win32 operating systems without further development.
To run the ./site/eg scripts as CGI scripts, you copy the ./site directory to some location accessible by your web server, in this example its /usr/local/apache/htdocs/aspcgi, then in your httpd.conf activate Apache::ASP cgi scripts like so:
 Alias /aspcgi/ /usr/local/apache/htdocs/aspcgi/
 <Directory /usr/local/apache/htdocs/aspcgi/eg/ >
   AddType application/x-httpd-cgi .htm
   AddType application/x-httpd-cgi .html
   AddType application/x-httpd-cgi .asp
   AddType application/x-httpd-cgi .xml
   AddType application/x-httpd-cgi .ssi
   AllowOverride None
   Options +ExecCGI +Indexes
 </Directory>
Then install the asp-perl script from the distribution into /usr/bin, or some other directory. This is so the CGI execution line at the top of those scripts will invoke the asp-perl wrapper like so:
 #!/usr/bin/perl /usr/bin/asp-perl
The asp-perl script is a cgi wrapper that sets up the Apache::ASP environment in lieu of the normal mod_perl handler request. Because there is no Apache->dir_config() data available under mod_cgi, the asp-perl script will load a asp.conf file that may define a hash %Config of data for populating the dir_config() data. An example of a complex asp.conf file is at ./site/eg/asp.conf
So, a trivial asp.conf file might look like:
 # asp.conf
 %Config = (
   'Global' => '.',
   'StateDir' => '/tmp/aspstate',
   'NoState' => 0,
   'Debug' => 3,
 );
The default for NoState is 1 in CGI mode, so one must set NoState to 0 for objects like $Session & $Application to be defined.

CGI.pm

CGI.pm is a very useful module that aids developers in 
the building of these applications, and Apache::ASP has been made to 
be compatible with function calls in CGI.pm.  Please see cgi.htm in the 
./site/eg directory for a sample ASP script written almost entirely in CGI.
As of version 0.09, use of CGI.pm for both input and output is seamless when working under Apache::ASP. Thus if you would like to port existing cgi scripts over to Apache::ASP, all you need to do is wrap <% %> around the script to get going. This functionality has been implemented so that developers may have the best of both worlds when building their web applications.
For more information about CGI.pm, please see the web site
  http://search.cpan.org/dist/CGI/lib/CGI.pm

Query Object Initialization

You may create a CGI.pm $query object like so:
	use CGI;
	my $query = new CGI;
As of Apache::ASP version 0.09, form input may be read in by CGI.pm upon initialization. Before, Apache::ASP would consume the form input when reading into $Request->Form(), but now form input is cached, and may be used by CGI.pm input routines.

CGI headers

Not only can you use the CGI.pm $query->header() method
to put out headers, but with the CgiHeaders config option
set to true, you can also print "Header: value\n", and add 
similar lines to the top of your script, like:
 Some-Header: Value
 Some-Other: OtherValue

 <html><body> Script body starts here.
Once there are no longer any cgi style headers, or the there is a newline, the body of the script begins. So if you just had an asp script like:
    print join(":", %{$Request->QueryString});
You would likely end up with no output, as that line is interpreted as a header because of the semicolon. When doing basic debugging, as long as you start the page with <html> you will avoid this problem.

print()ing CGI

CGI is notorious for its print() statements, and the functions in CGI.pm 
usually return strings to print().  You can do this under Apache::ASP,
since print just aliases to $Response->Write().  Note that $| has no
affect.
	print $query->header();
	print $query->start_form();

File Upload

CGI.pm is used for implementing reading the input from file upload.  You
may create the file upload form however you wish, and then the 
data may be recovered from the file upload by using $Request->Form().
Data from a file upload gets written to a file handle, that may in
turn be read from.  The original file name that was uploaded is the 
name of the file handle.
	my $filehandle = $Request->Form('file_upload_field_name');
	print $filehandle; # will get you the file name
	my $data;
	while(read($filehandle, $data, 1024)) {
		# data from the uploaded file read into $data
	};
Please see the docs on CGI.pm (try perldoc CGI) for more information on this topic, and ./site/eg/file_upload.asp for an example of its use. Also, for more details about CGI.pm itself, please see the web site:
    http://stein.cshl.org/WWW/software/CGI/
Occasionally, a newer version of CGI.pm will be released which breaks file upload compatibility with Apache::ASP. If you find this to occur, then you might consider downgrading to a version that works. For example, one can install a working CGI.pm v2.78 for a working version, and to get old versions of this module, one can go to BACKPAN at:
    http://backpan.cpan.org/modules/by-authors/id/L/LD/LDS/
There is also $Request->FileUpload() API extension that you can use to get more data about a file upload, so that the following properties are available for querying:
  my $file_upload = $Request->{FileUpload}{upload_field};
  $file_upload->{BrowserFile}
  $file_upload->{FileHandle}
  $file_upload->{ContentType}

  # only if FileUploadTemp is set
  $file_upload->{TempFile}	

  # whatever mime headers are sent with the file upload
  # just "keys %$file_upload" to find out
  $file_upload->{?Mime-Header?}
Please see the $Request section in OBJECTS for more information.