Apache-ASP
view release on metacpan or search on metacpan
=end html
This module works under the Apache Web Server
with the mod_perl module enabled. See http://www.apache.org and
http://perl.apache.org for further information.
This is a portable solution, similar to ActiveState's PerlScript
for NT/IIS ASP. Work has been done and will continue to make ports
to and from this implementation as smooth as possible.
For Apache::ASP downloading and installation, please read
the INSTALL section. For installation troubleshooting
check the FAQ and the SUPPORT sections.
For database access, ActiveX, scripting languages, and other
miscellaneous issues please read the FAQ section.
=head1 WEBSITE
The Apache::ASP web site is at http://www.apache-asp.org/
which you can also find in the ./site directory of
the source distribution.
=head1 INSTALL
The installation process for Apache::ASP is geared towards those
with experience with Perl, Apache, and unix systems. For those
without this experience, please understand that the learning curve
can be significant. But what you have at the end will be a web site
running on superior open source software.
If installing onto a Windows operating system, please see the section
titled Win32 Install.
=head2 Need Help
Often, installing the mod_perl part of the Apache server
can be the hardest part. If this is the case for you,
check out the FAQ and SUPPORT sections for further help,
as well as the "Modern Linux Distributions" notes in this section.
Please also see the mod_perl site at http://perl.apache.org/
which one ought to give a good read before undertaking
a mod_perl project.
=head2 Download and CPAN Install
You may download the latest Apache::ASP from your nearest CPAN,
and also:
http://search.cpan.org/dist/Apache-ASP/
http://cpan.org/modules/by-module/Apache/
As a Perl developer, you should make yourself familiar with
the CPAN.pm module, and how it may be used to install
Apache::ASP, and other related modules. The easiest way
to install Apache::ASP for the first time from Perl is to
fire up the CPAN shell like:
shell prompt> perl -MCPAN -e shell
... configure CPAN ...
... then upgrade to latest CPAN ...
cpan> install CPAN
...
cpan> install Bundle::Apache::ASP
Installing the Apache::ASP bundle will automatically install
all the modules Apache::ASP is dependent on as well as
Apache::ASP itself. If you have trouble installing the bundle,
then try installing the necessary modules one at a time:
cpan> install MLDBM
cpan> install MLDBM::Sync
cpan> install Digest::MD5 *** may not be needed for perl 5.8+ ***
cpan> install Apache::ASP
For extra/optional functionality in Apache::ASP 2.31 or greater, like
support for FormFill, XSLT, or SSI, you can install this bundle via CPAN:
cpan> install Bundle::Apache::ASP::Extra
=head2 Regular Perl Module Install
If not doing the CPAN install, download Apache::ASP and install it using
the make or nmake commands as shown below. Otherwise, just
copy ASP.pm to $PERLLIB/site/Apache
> perl Makefile.PL
> make
> make test
> make install
* use nmake for win32
Please note that you must first have the Apache Web Server
& mod_perl installed before using this module in a web server
environment. The offline mode for building static html at
./cgi/asp-perl may be used with just perl.
=head2 Modern Linux Distributions
If you have a modern Linux distribution like CentOS or Ubuntu,
you will likely have the easiest path by using the repository tools to
automatically install mod_perl and Apache before installing Apache::ASP via CPAN.
For example for CentOS, this will install mod_perl into your apache httpd, the latter
likely being installed already by default on your server:
bash> sudo yum install mod_perl-devel.x86_64
For Ubuntu this would be done like this:
bash> sudo apt-get install libapache2-mod-perl2
=head2 Quick Start
Once you have successfully built the Apache Web Server with mod_perl,
copy the ./site/eg/ directory from the Apache::ASP installation
to your Apache document tree and try it out! You must put "AllowOverride All"
in your httpd.conf <Directory> config section to let the .htaccess file in the
In the UNIX world, it seems most databases have cross platform support in perl.
You can find the book on DBI programming at http://www.oreilly.com/catalog/perldbi/
DBD::ODBC is often your ticket on Win32. On UNIX, commercial vendors
like OpenLink Software (http://www.openlinksw.com/) provide the nuts and
bolts for ODBC.
Database connections can be cached per process with Apache::DBI.
=item What is the best way to debug an ASP application ?
There are lots of perl-ish tricks to make your life developing
and debugging an ASP application easier. For starters,
you will find some helpful hints by reading the
$Response->Debug() API extension, and the Debug
configuration directive.
=item How are file uploads handled?
Please see the CGI section. File uploads are implemented
through CGI.pm which is loaded at runtime only for this purpose.
This is the only time that CGI.pm will be loaded by Apache::ASP,
which implements all other cgi-ish functionality natively. The
rationale for not implementing file uploads natively is that
the extra 100K in memory for CGI.pm shouldn't be a big deal if you
are working with bulky file uploads.
=item How do I access the ASP Objects in general?
All the ASP objects can be referenced through the main package with
the following notation:
$main::Response->Write("html output");
This notation can be used from anywhere in perl, including routines
registered with $Server->RegisterCleanup().
You use the normal notation in your scripts, includes, and global.asa:
$Response->Write("html output");
=item Can I print() in ASP?
Yes. You can print() from anywhere in an ASP script as it aliases
to the $Response->Write() method. Using print() is portable with
PerlScript when using Win32::ASP in that environment.
=item Do I have access to ActiveX objects?
Only under Win32 will developers have access to ActiveX objects through
the perl Win32::OLE interface. This will remain true until there
are free COM ports to the UNIX world. At this time, there is no ActiveX
for the UNIX world.
=head2 Support and Production
=item How do I get things I want done?!
If you find a problem with the module, or would like a feature added,
please mail support, as listed in the SUPPORT section, and your
needs will be promptly and seriously considered, then implemented.
=item What is the state of Apache::ASP? Can I publish a web site on it?
Apache::ASP has been production ready since v.02. Work being done
on the module is on a per need basis, with the goal being to eventually
have the ASP API completed, with full portability to ActiveState PerlScript
and MKS PScript. If you can suggest any changes to facilitate these
goals, your comments are welcome.
=head1 TUNING
A little tuning can go a long way, and can make the difference between
a web site that gets by, and a site that screams with speed. With
Apache::ASP, you can easily take a poorly tuned site running at
10 hits/second to 50+ hits/second just with the right configuration.
Documented below are some simple things you can do to make the
most of your site.
=head2 Online Resources
For more tips & tricks on tuning Apache and mod_perl, please see the tuning
documents at:
Stas Bekman's mod_perl guide
http://perl.apache.org/guide/
Written in late 1999 this article provides an early look at
how to tune your Apache::ASP web site. It has since been
updated to remain current with Apache::ASP v2.29+
Apache::ASP Site Tuning
http://www.apache-asp.org/articles/perlmonth3_tune.html
=head2 Tuning & Benchmarking
When performance tuning, it is important to have a tool to
measure the impact of your tuning change by change.
The program ab, or Apache Bench, provides this functionality
well, and is freely included in the apache distribution.
Because performance tuning can be a neverending affair,
it is a good idea to establish a threshold where performance
is "good enough", that once reached, tuning stops.
=head2 $Application & $Session State
Use NoState 1 setting if you don't need the $Application or $Session
objects. State objects such as these tie to files on disk and will incur a
performance penalty.
If you need the state objects $Application and $Session, and if
running an OS that caches files in memory, set your "StateDir"
directory to a cached file system. On WinNT, all files
may be cached, and you have no control of this. On Solaris, /tmp is
a RAM disk and would be a good place to set the "StateDir" config
setting to. When cached file systems are used there is little
performance penalty for using state files. Linux tends to do a good job
caching its file systems, so pick a StateDir for ease of system
administration.
+$Application->GetSession($session_id) API extension, useful
for managing active user sessions when storing session ids
in $Application. Documented.
-disable use of flock() on Win95/98 where it is unimplemented
-@array context of $Request->Form('name') returns
undef when value for 'name' is undefined. Put extra
logic in there to make sure this happens.
=item $VERSION = 0.16; $DATE="09/22/99";
-$Response->{Buffer} and PerlSetVar BufferingOn
configs now work when set to 0, to unbuffer output,
and send it out to the web client as the script generates it.
Buffering is enabled by default, as it is faster, and
allows a script to error cleanly in the middle of execution.
+more bullet proof loading of Apache::Symbol, changed the
way Apache::ASP loads modules in general. It used to
check for the module to load every time, if it hadn't loaded
successfully before, but now it just tries once per httpd,
so the web server will have to be restarted to see new installed
modules. This is just for modules that Apache::ASP relies on.
Old modules that are changed or updated with an installation
are still reloaded with the StatINC settings if so configured.
+ASP web site wraps <font face="courier new"> around <pre>
tags now to override the other font used for the text
areas. The spacing was all weird in Netscape before
for <pre> sections.
-Fixed Content-Length calculation when using the Clean
option, so that the length is calculated after the HTML
is clean, not before. This would cause a browser to
hang sometimes.
+Added IncludesDir config option that if set will also be
used to check for includes, so that includes may easily be
shared between applications. By default only Global and
the directory the script is in are checked for includes.
Also added IncludesDir as a possible configuration option
for Apache::ASP->Loader()
-Re-enabled the Application_OnStart & OnEnd events, after
breaking them when implementing the AllowApplicationState
config setting.
+Better pre-fork caching ... StatINC & StatINCMatch are now
args for Apache::ASP->Loader(), so StatINC symbols loading
may be done pre-fork and shared between httpds. This lowers
the child httpd init cost of StatINC. Documented.
+Made Apache::ASP Basic Authorization friendly so authentication
can be handled by ASP scripts. If AuthName and AuthType Apache
config directives are set, and a $Response->{Status} is set to
401, a user will be prompted for username/password authentication
and the entered data will show up in ServerVariables as:
$env = $Request->ServerVariables
$env->{REMOTE_USER} = $env->{AUTH_USER} = username
$env->{AUTH_PASSWD} = password
$env->{AUTH_NAME} = your realm
$env->{AUTH_TYPE} = 'Basic'
This is the same place to find auth data as if Apache had some
authentication handler deal with the auth phase separately.
-MailErrorsTo should report the right file now that generates
the error.
=item $VERSION = 0.15; $DATE="08/24/1999";
--State databases like $Session, $Application are
now tied/untied to every lock/unlock triggered by read/write
access. This was necessary for correctness issues, so that
database file handles are flushed appropriately between writes
in a highly concurrent multi-process environment.
This problem raised its ugly head because under high volume,
a DB_File can become corrupt if not flushed correctly.
Unfortunately, there is no way to flush SDBM_Files & DB_Files
consistently other than to tie/untie the databases every access.
DB_File may be used optionally for StateDB, but the default is
to use SDBM_File which is much faster, but limited to 1024 byte
key/value pairs.
For SDBM_Files before, if there were too many concurrent
writes to a shared database like $Application, some of the
writes would not be saved because another process
might overwrite the changes with its own.
There is now a 10 fold performance DECREASE associated
with reading from and writing to files like $Session
and $Application. With rough benchmarks I can get about
100 increments (++) now per second to $Session->{count}, where
before I could get 1000 increments / second.
You can improve this if you have many reads / writes happening
at the same time, by placing locking code around the group like
$Session->Lock();
$Session->{count}++;
$Session->{count}++;
$Session->{count}++;
$Session->UnLock();
This method will reduce the number of ties to the $Session database
from 6 to 1 for this kind of code, and will improve the performance
dramatically.
Also, instead of using explicit $Session locking, you can
create an automatic lock on $Session per script by setting
SessionSerialize in your config to 1. The danger here is
if you have any long running scripts, the user will have
to wait for it to finish before another script can be run.
To see the number of lock/unlocks or ties/unties to each database
during a script execution, look at the last lines of debug output
to your error log when Debug is set to 1. This can help you
performance tweak access to these databases.
+Updated documentation with new config settings and
API extensions.
+Added AllowApplicationState config option which allows
you to leave $Application undefined, and will not
execute Application_OnStart or Application_OnEnd.
This can be a slight performance increase of 2-3% if
you are not using $Application, but are using $Session.
+Added $Session->Lock() / $Session->UnLock() API routines
necessary additions since access to session is not
serialized by default like IIS ASP. Also prompted
by change in locking code which retied to SDBM_File
or DB_File each lock. If you $Session->Lock / UnLock
around many read/writes, you will increase performance.
+Added StateCache config which, if set will cache
the file handle locks for $Application and an internal
database used for tracking $Session info. This caching can
make an ASP application perform up to 10% faster,
at a cost of each web server process holding 2 more
cached file handles open, per ASP application using
this configuration. The data written to or read from
these state databases is not cached, just the locking
file handles are held open.
-Added in much more locking in session manager
and session garbage collector to help avoid collisions
between the two. There were definite windows that the
two would collide in, during which bad things could
happen on a high volume site.
-Fixed some warnings in DESTROY and ParseParams()
=item $VERSION = 0.14; $DATE="07/29/1999";
-CGI & StatINC or StatINCMatch would have bad results
at times, with StatINC deleting dynamically compiled
CGI subroutines, that were imported into other scripts
and modules namespaces.
A couple tweaks, and now StatINC & CGI play nice again ;)
StatINCMatch should be safe to use in production with CGI.
This affects in particular environments that use file upload,
since CGI is loaded automatically by Apache::ASP to handle
file uploads.
This fix should also affect other seemingly random
times when StatINC or StatINCMatch don't seem to do
the right thing.
+use of ASP objects like $Response are now "use strict"
safe in scripts, while UniquePackages config is set.
+Better handling of "use strict" errors in ASP scripts.
The error is detected, and the developer is pointed to the
Apache error log for the exact error.
The script with "use strict" errors will be recompiled again. Its seems
though that "use strict" will only throw its error once, so that a script
can be recompiled with the same errors, and work w/o any use strict
error messaging.
=item $VERSION = 0.12; $DATE="07/01/1999";
-Compiles are now 10 +times faster for scripts with lots of big
embedded perl blocks <% #perl %>
Compiles were slow because of an old PerlScript compatibility
parsing trick where $Request->QueryString('hi')->{item}
would be parsed to $Request->QueryString('hi') which works.
I think the regexp that I was using had O(n^2) characteristics
( run in 2.608 seconds using v1.01-cache-2.11-cpan-6aa56a78535 )