Apache-ASP
view release on metacpan or search on metacpan
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
./site/eg installation directory do its work. If you want a starter
config file for Apache::ASP, just look at the .htaccess file in the
./site/eg/ directory.
So, you might add this to your Apache httpd.conf file just to get
the scripts in ./site/eg working, where $DOCUMENT_ROOT represents
the DocumentRoot config for your apache server:
<Directory $DOCUMENT_ROOT/asp/eg >
Options FollowSymLinks
AllowOverride All
</Directory>
To copy the entire site, including the examples, you might
do a raw directory copy as in:
shell> cp -rpd ./site $DOCUMENT_ROOT/asp
So you could then reference the Apache::ASP docs at /asp/ at your site,
and the examples at /asp/eg/ .
This is not a good production configuration, because it is insecure
with the FollowSymLinks, and tells Apache to look for .htaccess
which is bad for performance but it should be handy for getting
started with development.
You will know that Apache::ASP is working normally if you
can run the scripts in ./site/eg/ without any errors. Common
problems can be found in the FAQ section.
=head2 Build static Apache and mod_perl for Apache 1.3.x
For a quick build of apache, there is a script in the distribution at
./make_httpd/build_httpds.sh that can compile a statically linked
Apache with mod_ssl and mod_perl. Just drop the sources into the
make_httpd directory, configure the environments as appropriate,
and execute the script like this:
make_httpd> ./build_httpds.sh
You might also find helpful a couple items:
Stas's mod_perl guide install section
http://perl.apache.org/guide/install.html
Apache Toolbox
http://www.apachetoolbox.com/
People have been using Apache Toolbox to automate their
complex builds of Apache 1.3.x with great success.
=head2 Win32 / Windows Install
If you are on a Win32 platform, like WinNT or Windows 2000,
you can download the win32 binaries linked to from:
http://perl.apache.org/download/binaries.html#Win32
and install the latest perl-win32-bin-*.exe file.
Randy Kobes has graciously provided these, which include
compiled versions perl, mod_perl, apache, mod_ssl,
as well as all the modules required by Apache::ASP
and Apache::ASP itself.
After installing this distribution, in Apache2\conf\perl.conf
(pulled in via Apache2\conf\httpd.conf) there's directives that
have Apache::ASP handle files placed under the Apache2\asp\
directory. There should be a sample Apache::ASP script there,
printenv.html, accessed as http://127.0.0.1/asp/printenv.html
which, if working, will print out your environment variables.
=head2 WinME / 98 / 95 flock() workaround
For those on desktop Windows operation systems, Apache::ASP v2.25 and
later needs a special work around for the lack of flock() support
on these systems. Please add this to your Apache httpd.conf to
fix this problem after mod_perl is installed:
<Perl>
*CORE::GLOBAL::flock = sub { 1 };
</Perl>
PerlModule Apache::ASP
Please be sure to add this configuration before Apache::ASP is loaded
via PerlModule, or a PerlRequire statement.
=head1 CONFIG
You may use a <Files ...> directive in your httpd.conf
Apache configuration file to make Apache::ASP start ticking. Configure the
optional settings if you want, the defaults are fine to get started.
The settings are documented below.
Make sure Global is set to where your web applications global.asa is
if you have one!
PerlModule Apache::ASP
<Files ~ (\.asp)>
SetHandler perl-script
PerlHandler Apache::ASP
PerlSetVar Global .
PerlSetVar StateDir /tmp/asp
</Files>
NOTE: do not use this for the examples in ./site/eg. To get the
examples working, check out the Quick Start section of INSTALL
You may use other Apache configuration tags like <Directory>,
<Location>, and <VirtualHost>, to separately define ASP
configurations, but using the <Files> tag is natural for
ASP application building because it lends itself naturally
to mixed media per directory. For building many separate
ASP sites, you might want to use separate .htaccess files,
or <Files> tags in <VirtualHost> sections, the latter being
better for performance.
=head2 Core
=item Global
Global is the nerve center of an Apache::ASP application, in which
the global.asa may reside defining the web application's
For example, let's say you have a header & footer you would like to
include in the output of every page, then you might:
# global.asa
sub Script_OnStart {
$Response->Include('header.inc');
}
sub Script_OnEnd {
$Response->Include('footer.inc');
}
Or let's say you want to initialize a global database connection
for use in your scripts:
# global.asa
use Apache::DBI; # automatic persistent database connections
use DBI;
use vars qw($dbh); # declare global $dbh
sub Script_OnStart {
# initialize $dbh
$dbh = DBI->connect(...);
# force you to explicitly commit when you want to save data
$Server->RegisterCleanup(sub { $dbh->rollback; });
}
sub Script_OnEnd {
# not really necessary when using persistent connections, but
# will free this one object reference at least
$dbh = undef;
}
=head1 FAQ
The following are some frequently asked questions
about Apache::ASP.
=head2 Installation
=item Examples don't work, I see the ASP script in the browser?
This is most likely that Apache is not configured to execute
the Apache::ASP scripts properly. Check the INSTALL QuickStart
section for more info on how to quickly set up Apache to
execute your ASP scripts.
=item Apache Expat vs. XML perl parsing causing segfaults, what do I do?
Make sure to compile apache with expat disabled. The
./make_httpd/build_httpds.sh in the distribution will do
this for you, with the --disable-rule=EXPAT in particular:
cd ../$APACHE
echo "Building apache =============================="
./configure \
--prefix=/usr/local/apache \
--activate-module=src/modules/perl/libperl.a \
--enable-module=ssl \
--enable-module=proxy \
--enable-module=so \
--disable-rule=EXPAT
^^^^^
keywords: segmentation fault, segfault seg fault
=item Why do variables retain their values between requests?
Unless scoped by my() or local(), perl variables in mod_perl
are treated as globals, and values set may persist from one
request to another. This can be seen in as simple a script
as this:
<HTML><BODY>
$counter++;
$Response->Write("<BR>Counter: $counter");
</BODY></HTML>
The value for $counter++ will remain between requests.
Generally use of globals in this way is a BAD IDEA,
and you can spare yourself many headaches if do
"use strict" perl programming which forces you to
explicity declare globals like:
use vars qw($counter);
You can make all your Apache::ASP scripts strict by
default by setting:
PerlSetVar UseStrict 1
=item Apache errors on the PerlHandler or PerlModule directives ?
You get an error message like this:
Invalid command 'PerlModule', perhaps mis-spelled or defined by a
module not included in the server configuration.
You do not have mod_perl correctly installed for Apache. The PerlHandler
and PerlModule directives in Apache *.conf files are extensions enabled by mod_perl
and will not work if mod_perl is not correctly installed.
Common user errors are not doing a 'make install' for mod_perl, which
installs the perl side of mod_perl, and not starting the right httpd
after building it. The latter often occurs when you have an old apache
server without mod_perl, and you have built a new one without copying
over to its proper location.
To get mod_perl, go to http://perl.apache.org
=item Error: no request object (Apache=SCALAR(0x???????):)
Your Apache + mod_perl build is not working properly,
and is likely a RedHat Linux RPM DSO build. Make sure
you statically build your Apache + mod_perl httpd,
recompiled fresh from the sources.
=item I am getting a tie or MLDBM / state error message, what do I do?
<% return(1,2); %>
=item $VERSION = 2.21; $DATE="8/5/2001";
+Documented RequestParams config in CONFIG misc section.
+Documented new XSLT caching directives.
+Updated ./site/eg/.htaccess XSLT example config
to use XSLTCache setting.
+New FAQ section on why perl variables are sticky globals,
suggested by Mark Seger.
-push Global directory onto @INC during ASP script execution
Protect contents of original @INC with local. This makes
things compatible with .09 Apache::ASP where we always had
Global in @INC. Fixed needed by Henrik Tougaard
- ; is a valid separator like & for QueryString Parameters
Fixed wanted by Anders
-XSMLSubsMatch doc fix in CONFIG section
+Reduces number of Session groups to 16 from 32, so
session manager for small user sets will be that much faster.
+optimizations for internal database, $Application, and $Session
creation.
+XSLTCache must be set for XSLT caching to begin using CacheDir
+CacheDB like StateDB bug sets dbm format for caching, which
defaults to MLDBM::Sync::SDBM_File, which works well for caching
output sizes < 50K
+CacheDir config for XSLT caching ... defaults to StateDir
+CacheSize in bytes determines whether the caches in CacheDir
are deleted at the end of the request. A cache will be
reset in this way back to 0 bytes. Defaults to 10000000 bytes
or about 10M.
+Caching infrastructure work that is being used in XSLT
can be leveraged later for output caching of includes,
or arbitrary user caching.
-t/server_mail.t test now uses valid email for testing
purposes ... doesn't actually send a mail, but for SMTP
runtime validation purposes it should be OK.
+fixed where POST data was read from under MOD_PERL,
harmless bug this was that just generated the wrong
system debugging message.
=item $VERSION = 2.19; $DATE="7/10/2001";
+update docs in various parts
+added ./make_httpd/build_httpds.sh scripts for quick builds
of apache + mod_perl + mod_ssl
++plain CGI mode available for ASP execution.
cgi/asp script can now be used to execute ASP
scripts in CGI mode. See CGI perldoc section for more info.
The examples in ./site/eg have been set up to run
in cgi mode if desired. Configuration in CGI section
only tested for Apache on Linux.
-Fixed some faulty or out of date docs in XML/XSLT section.
+added t/server_mail.t test for $Server->Mail(), requires
Net::SMTP to be configured properly to succeed.
+Net::SMTP debugging not enabled by Debug 1,2,3 configs,
not only when system debugging is set with Debug -1,-2,-3
However, a Debug param passed to $Server->Mail() will
sucessfully override the Debug -1,-2,-3 setting even
when its Debug => 0
-Check for undef values during stats for inline includes
so we don't trigger unintialized warnings
+Documented ';' may separate many directories in the IncludesDir
setting for creating a more flexible includes search path.
=item $VERSION = 2.17; $DATE="6/17/2001";
+Added ASP perl mmm-mode subclass and configuration
in editors/mmm-asp-perl.el file for better emacs support.
Updated SYNTAX/Editors documentation.
+Better debugging error message for Debug 2 or 3 settings
for global.asa errors. Limit debug output for lines
preceding rendered script.
-In old inline include mode, there should no longer
be the error "need id for includes" when using
$Response->Include() ... if DynamicIncludes were
enabled, this problem would not have likely occured
anyway. DynamicIncludes are preferrable to use so
that compiled includes can be shared between scripts.
This bug was likely introduced in version 2.11.
-Removed logging from $Response->BinaryWrite() in regular
debug mode 1 or 2. Logging still enabled in system Debug mode, -1 or -2
-Removed other extra system debugging call that is really not
necessary.
=item $VERSION = 2.15; $DATE="06/12/2001";
-Fix for running under perl 5.6.1 by removing parser optimization
introduced in 2.11.
-Now file upload forms, forms with ENCTYPE="multipart/form-data"
can have multiple check boxes and select items marked for
@params = $Request->Form('param_name') functionality. This
will be demonstrated via the ./site/eg/file_upload.asp example.
=item $VERSION = 2.11; $DATE="05/29/2001";
+Turned the documentation of Filter config to value of Off so
people won't cut and paste the On config by default.
+Added SecureSession config option, which forces session cookie to
be sent only under https secured www page requests.
+Added StateDB config option allows use of DB_File for $Session, since
default use of SDBM_File is limited. See StateDB in README.
+file include syntax w/o quotes supported like <!--#include file=test.inc-->
+Nested includes are supported, with includes including each other.
Recursive includes are detected and errors out when an include has been
included 100 times for a script. Better to quit early than
have a process spin out of control. (PORTABLE ? probably not)
+Allow <!--include file=file.inc--> notation w/o quotes around file names
-PerlSetEnv apache conf setting now get passed through to
$Request->ServerVariables. This update has ServerVariables
getting data from %ENV instead of $r->cgi_env
+README FAQ for PerlHandler errors
=item $VERSION = 0.08; $DATE="02/06/1999";
++SSI with Apache::Filter & Apache::SSI, see config options & ./eg files
Currently filtering only works in the direction Apache::ASP -> Apache::SSI,
will not work the other way around, as SSI must come last in a set of filters
+SSI file includes may reference files in the Global directory, better
code sharing
- <% @array... %> no longer dropped from code.
+perl =pod comments are stripped from script before compiling, and associated
PodComments configuration options.
+Command line cgi/asp script takes various options, and allows execution
of multiple asp scripts at one time. This script should be used for
command line debugging. This is also the beginning of building
a static site from asp scripts with the -b option, suppressing headers.
+$Response->AddHeader('Set-Cookie') works for multiple cookies.
-$Response->Cookies('foo', '0') works, was dropping 0 because of boolean test
-Fixed up some config doc errors.
=item $VERSION = 0.07; $DATE="01/20/1999";
-removed SIG{__WARN__} handler, it was a bad idea.
-fixes file locking on QNX, work around poor flock porting
+removed message about Win32::OLE on UNIX platforms from Makefile.PL
-Better lock garbage collection. Works with StatINC seamlessly.
-Multiple select forms now work in array context with $Response->Form()
@values = $Response->Form('multi');
-Better CGI.pm compatibility with $r->header_out('Content-type'),
improved garbage collection under modperl, esp. w/ file uploads
=item $VERSION = 0.06; $DATE="12/21/1998";
+Application_OnStart & Application_OnEnd event handlers support.
-Compatible with CGI.pm 2.46 headers()
-Compatible with CGI.pm $q = new CGI({}), caveat: does not set params
+use strict; followed by use of objects like $Session is fine.
-Multiple cookies may be set per script execution.
+file upload implemented via CGI.pm
++global.asa implemented with events Session_OnStart and Session_OnEnd
working appropriately.
+StateDir configuration directive implemented.
StateDir allows the session state directory to be specified separately
from the Global directory, useful for operating systems with caching file
systems.
+StateManager config directive. StateManager specifies how frequently
Sessions are cleaned up, with 10 (default) meaning that old Sessions
will be cleaned up 10 times per SessionTimeout period (default 20 minutes).
+$Application->SessionCount() implemented, non-portable method.
: returns the number of currently active sessions
-STOP button fix. Users may hit STOP button during script
execution, and Apache::ASP will cleanup with a routine registered
in Apache's $r->register_cleanup. Works well supposedly.
+PerlScript compatibility work, trying to make ports smoother.
: Collection emulator, no ->{Count} property
: $.*(.*)->{Item} parsed automatically,
shedding the ->{Item} for Collection support (? better way ?)
: No VBScript dates support, just HTTP RFC dates with HTTP::Date
: Win32::OLE::in not supported, just use "keys %{$Collection}"
+./cgi/asp script for testing scripts from the command line
: will be upgraded to CGI method of doing asp
: is not "correct" in anyway, so not documented for now
but still useful
+strips DOS carriage returns from scripts automatically, so that
programs like FrontPage can upload pages to UNIX servers
without perl choking on the extra \r characters.
=item $VERSION = 0.05; $DATE="10/19/1998";
( run in 1.698 second using v1.01-cache-2.11-cpan-acf6aa7dc9e )