Apache-ASP
view release on metacpan or search on metacpan
site/objects.html view on Meta::CPAN
<font face="courier new" size=3><pre>
$Response->Include({
File => 'file.inc',
Cache => 1, # to activate cache layer
Expires => 3600, # to expire in one hour
LastModified => time() - 600, # to expire if cached before 10 minutes ago
Key => $Request->Form, # to cache based on checksum of serialized form data,
Clear => 1, # always executes include & cache output
}, @include_args);
File - include file to execute, can be file name or \$script
script data passed in as a string reference.
Cache - activate caching, will run like normal include without this
Expires - only cache for this long in seconds
LastModified - if cached before this time(), expire
Key - The cache item identity. Can be $data, \$data, \%data, \@data,
this data is serialized and combined with the filename & @include_args
to create a MD5 checksum to fetch from the cache with. If you wanted
to cache the results of a search page from form data POSTed,
then this key could be
{ Key => $Request->Form }
Clear - If set to 1, or boolean true, will always execute the include
and update the cache entry for it.
</pre></font>Motivation: If an include takes 1 second to execute
because of complex SQL to a database, and you can
cache the output of this include because it is not realtime data,
and the cache layer runs at .01 seconds, then you have a
100 fold savings on that part of the script. Site scalability
can be dramatically increased in this way by intelligently
caching bottlenecks in the web application.
<font face="courier new" size=3><pre>
</pre></font>Use Sparingly: If you have a fast include, then it may execute faster
than the cache layer runs, in which case you may actually
slow your site down by using this feature. Therefore
try to use this sparingly, and only when sure you really
need it. Apache::ASP scripts generally execute very
quickly, so most developers will not need to use this feature
at all.</font>
<p>
<a name=%24Response-%3EI368566a8></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Response->Include(\$script_text, @args)</b></font>
<font face="courier new" size=3><pre>
</pre></font>Added in Apache::ASP 2.11, this method allows for executing ASP scripts
that are generated dynamically by passing in a reference to the script
data instead of the file name. This works just like the normal
$Response->Include() API, except a string reference is passed in
instead of a filename. For example:
<font face="courier new" size=3><pre>
<%
my $script = "<\% print 'TEST'; %\>";
$Response->Include(\$script);
%>
</pre></font>This include would output TEST. Note that tokens like
<% and %> must be escaped so Apache::ASP does not try
to compile those code blocks directly when compiling
the original script. If the $script data were fetched
directly from some external resource like a database,
then these tokens would not need to be escaped at all as in:
<font face="courier new" size=3><pre>
<%
my $script = $dbh->selectrow_array(
"select script_text from scripts where script_id = ?",
undef, $script_id
);
$Response->Include(\$script);
%>
</pre></font>This method could also be used to render other types of dynamic scripts,
like XML docs using XMLSubs for example, though for complex
runtime XML rendering, one should use something better suited like XSLT.
See the $Server->XSLT API for more on this topic.</font>
<p>
<a name=%24Response-%3EIbe084bb0></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Response->IsClientConnected()</b></font>
<font face="courier new" size=3><pre>
</pre></font>API Extension. 1 for web client still connected, 0 if
disconnected which might happen if the user hits the stop button.
The original API for this $Response->{IsClientConnected}
is only updated after a $Response->Flush is called,
so this method may be called for a refreshed status.
<font face="courier new" size=3><pre>
</pre></font>Note $Response->Flush calls $Response->IsClientConnected
to update $Response->{IsClientConnected} so to use this
you are going straight to the source! But if you are doing
a loop like:
<font face="courier new" size=3><pre>
while(@data) {
$Response->End if ! $Response->{IsClientConnected};
my $row = shift @data;
%> <%= $row %> <%
$Response->Flush;
}
</pre></font>Then its more efficient to use the member instead of
the method since $Response->Flush() has already updated
that value for you.</font>
<p>
<a name=%24Response-%3ER0203b227></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Response->Redirect($url)</b></font>
<font face="courier new" size=3><pre>
</pre></font>Sends the client a command to go to a different url $url.
Script immediately ends.</font>
<p>
<a name=%24Response-%3ET13ecbe6d></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Response->TrapInclude($file, @args)</b></font>
<font face="courier new" size=3><pre>
</pre></font>Calls $Response->Include() with same arguments as
passed to it, but instead traps the include output buffer
and returns it as as a perl string reference. This allows
one to postprocess the output buffer before sending
to the client.
<font face="courier new" size=3><pre>
my $string_ref = $Response->TrapInclude('file.inc');
$$string_ref =~ s/\s+/ /sg; # squash whitespace like Clean 1
print $$string_ref;
</pre></font>The data is returned as a referenece to save on what
might be a large string copy. You may dereference the data
site/objects.html view on Meta::CPAN
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->{ScriptTimeout} = $seconds</b></font>
<font face="courier new" size=3><pre>
</pre></font>Not implemented. May never be. Please see the
Apache Timeout configuration option, normally in httpd.conf.</font>
<p>
<a name=%24Server-%3ECon7d9785f8></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->Config($setting)</b></font>
<font face="courier new" size=3><pre>
</pre></font>API extension. Allows a developer to read the <a href=config.html><font size=-1 face=verdana><b>CONFIG</b></font></a>
settings, like Global, GlobalPackage, StateDir, etc.
Currently implemented as a wrapper around
<font face="courier new" size=3><pre>
Apache->dir_config($setting)
</pre></font>May also be invoked as $Server->Config(), which will
return a hash ref of all the PerlSetVar settings.</font>
<p>
<a name=%24Server-%3ECre0144679e></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->CreateObject($program_id)</b></font>
<font face="courier new" size=3><pre>
</pre></font>Allows use of ActiveX objects on Win32. This routine returns
a reference to an Win32::OLE object upon success, and nothing upon
failure. It is through this mechanism that a developer can
utilize ADO. The equivalent syntax in VBScript is
<font face="courier new" size=3><pre>
Set object = Server.CreateObject(program_id)
</pre></font>For further information, try 'perldoc Win32::OLE' from your
favorite command line.</font>
<p>
<a name=%24Server-%3EExec0fa247a></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->Execute($file, @args)</b></font>
<font face="courier new" size=3><pre>
</pre></font>New method from ASP 3.0, this does the same thing as
<font face="courier new" size=3><pre>
$Response->Include($file, @args)
</pre></font>and internally is just a wrapper for such. Seems like we
had this important functionality before the IIS/ASP camp!</font>
<p>
<a name=%24Server-%3EFileaa99842></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->File()</b></font>
<font face="courier new" size=3><pre>
</pre></font>Returns the absolute file path to current executing script.
Same as Apache->request->filename when running under <a href=http://perl.apache.org><font size=-1 face=verdana><b>mod_perl</b></font></a>.
<font face="courier new" size=3><pre>
</pre></font>ASP API extension.</font>
<p>
<a name=%24Server-%3EGetb3d1ac42></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->GetLastError()</b></font>
<font face="courier new" size=3><pre>
</pre></font>Not implemented, will likely not ever be because this is dependent
on how IIS handles errors and is not relevant in Apache.</font>
<p>
<a name=%24Server-%3EHTMb165f10b></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->HTMLEncode( $string || \$string )</b></font>
<font face="courier new" size=3><pre>
</pre></font>Returns an HTML escapes version of $string. &, ", >, <, are each
escapes with their HTML equivalents. Strings encoded in this nature
should be raw text displayed to an end user, as HTML tags become
escaped with this method.
<font face="courier new" size=3><pre>
</pre></font>As of version 2.23, $Server->HTMLEncode() may take a string reference
for an optmization when encoding a large buffer as an API extension.
Here is how one might use one over the other:
<font face="courier new" size=3><pre>
my $buffer = '&' x 100000;
$buffer = $Server->HTMLEncode($buffer);
print $buffer;
- or -
my $buffer = '&' x 100000;
$Server->HTMLEncode(\$buffer);
print $buffer;
</pre></font>Using the reference passing method in benchmarks on 100K of
data was 5% more efficient, but maybe useful for some.
It saves on copying the 100K buffer twice.</font>
<p>
<a name=%24Server-%3EMapd3711f06></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->MapInclude($include)</b></font>
<font face="courier new" size=3><pre>
</pre></font>API extension. Given the include $include, as an absolute or relative file name to the current
executing script, this method returns the file path that the include would
be found from the include search path. The include search path is the
current script directory, Global, and IncludesDir directories.
<font face="courier new" size=3><pre>
</pre></font>If the include is not found in the includes search path, then undef, or bool false,
is returned. So one may do something like this:
<font face="courier new" size=3><pre>
if($Server->MapInclude('include.inc')) {
$Response->Include('include.inc');
}
</pre></font>This code demonstrates how one might only try to execute an include if
it exists, which is useful since a script will error if it tries to execute an include
that does not exist.</font>
<p>
<a name=%24Server-%3EMap0fe1ebb5></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->MapPath($url);</b></font>
<font face="courier new" size=3><pre>
</pre></font>Given the url $url, absolute, or relative to the current executing script,
this method returns the equivalent filename that the server would
translate the request to, regardless or whether the request would be valid.
<font face="courier new" size=3><pre>
</pre></font>Only a $url that is relative to the host is valid. Urls like "." and
"/" are fine arguments to MapPath, but <tt>http://localhost</tt> would not be.
<font face="courier new" size=3><pre>
</pre></font>To see this method call in action, check out the sample <a href=eg/server.htm>./site/eg/server.htm</a>
script.</font>
<p>
<a name=%24Server-%3EMai03cc9918></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->Mail(\%mail, %smtp_args);</b></font>
<font face="courier new" size=3><pre>
</pre></font>With the Net::SMTP and Net::Config modules installed, which are part of the
perl libnet package, you may use this API extension to send email. The
\%mail hash reference that you pass in must have values for at least
the To, From, and Subject headers, and the Body of the mail message.
<font face="courier new" size=3><pre>
</pre></font>The return value of this routine is 1 for success, 0 for failure. If the MailHost
SMTP server is not available, this will have a return value of 0.
site/objects.html view on Meta::CPAN
"perldoc Net::SMTP" for more into on this topic.
<font face="courier new" size=3><pre>
</pre></font>If you would like to include the output of an ASP page as the
body of the mail message, you might do something like:
<font face="courier new" size=3><pre>
my $mail_body = $Response->TrapInclude('mail_body.inc');
$Server->Mail({ %mail, Body => $$mail_body });
</pre></font>
<p>
<a name=%24Server-%3EReg38562b5d></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->RegisterCleanup($sub) </b></font>
<font face="courier new" size=3><pre>
non-portable extension
</pre></font>Sets a subroutine reference to be executed after the script ends,
whether normally or abnormally, the latter occurring
possibly by the user hitting the STOP button, or the web server
being killed. This subroutine must be a code reference
created like:
<font face="courier new" size=3><pre>
$Server->RegisterCleanup(sub { $main::Session->{served}++; });
or
sub served { $main::Session->{served}++; }
$Server->RegisterCleanup(\&served);
</pre></font>The reference to the subroutine passed in will be executed.
Though the subroutine will be executed in anonymous context,
instead of the script, all objects will still be defined
in main::*, that you would reference normally in your script.
Output written to $main::Response will have no affect at
this stage, as the request to the www client has already completed.
<font face="courier new" size=3><pre>
</pre></font>Check out the <a href=eg/register_cleanup.asp>./site/eg/register_cleanup.asp</a> script for an example
of this routine in action.</font>
<p>
<a name=%24Server-%3ETra98c592dc></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->Transfer($file, @args)</b></font>
<font face="courier new" size=3><pre>
</pre></font>New method from ASP 3.0. Transfers control to another script.
The Response buffer will not be cleared automatically, so if you
want this to serve as a faster $Response->Redirect(), you will need to
call $Response->Clear() before calling this method.
<font face="courier new" size=3><pre>
</pre></font>This new script will take over current execution and
the current script will not continue to be executed
afterwards. It differs from Execute() because the
original script will not pick up where it left off.
<font face="courier new" size=3><pre>
</pre></font>As of Apache::ASP 2.31, this method now accepts optional
arguments like $Response->Include & $Server->Execute.
$Server->Transfer is now just a wrapper for:
<font face="courier new" size=3><pre>
$Response->Include($file, @args);
$Response->End;
</pre></font>
<p>
<a name=%24Server-%3EURL3674cef0></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->URLEncode($string)</b></font>
<font face="courier new" size=3><pre>
</pre></font>Returns the URL-escaped version of the string $string. +'s are substituted in
for spaces and special characters are escaped to the ascii equivalents.
Strings encoded in this manner are safe to put in urls... they are especially
useful for encoding data used in a query string as in:
<font face="courier new" size=3><pre>
$data = $Server->URLEncode("test data");
$url = "<tt>http://localhost?data=$data";</tt>
$url evaluates to <tt>http://localhost?data=test+data,</tt> and is a
valid URL for use in anchor <a> tags and redirects, etc.
</pre></font>
<p>
<a name=%24Server-%3EURL6c8bf743></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->URL($url, \%params) </b></font>
<font face="courier new" size=3><pre>
</pre></font>Will return a URL with %params serialized into a query
string like:
<font face="courier new" size=3><pre>
$url = $Server->URL('test.asp', { test => value });
</pre></font>which would give you a URL of test.asp?test=value
<font face="courier new" size=3><pre>
</pre></font>Used in conjunction with the SessionQuery* settings, the returned
URL will also have the session id inserted into the query string,
making this a critical part of that method of implementing
cookieless sessions. For more information on that topic
please read on the setting
in the <a href=config.html><font size=-1 face=verdana><b>CONFIG</b></font></a> section, and the SESSIONS section too.</font>
<p>
<a name=%24Server-%3EXSL7df794aa></a>
<font face=verdana><font class=title size=-1 color=#555555><b>$Server->XSLT(\$xsl_data, \$xml_data)</b></font>
<font face="courier new" size=3><pre>
* NON-PORTABLE API EXTENSION *
</pre></font>This method takes string references for XSL and XML data
and returns the XSLT output as a string reference like:
<font face="courier new" size=3><pre>
my $xslt_data_ref = $Server->XSLT(\$xsl_data, \$xml_data)
print $$xslt_data_ref;
</pre></font>The XSLT parser defaults to <a href=http://xmlxslt.sourceforge.net/><font size=-1 face=verdana><b>XML::XSLT</b></font></a>, and is configured with the
XSLTParser setting, which can also use XML::Sablotron ( support added in 2.11 ),
and XML::LibXSLT ( support added in 2.29 ).
Please see the <a href=config.html><font size=-1 face=verdana><b>CONFIG</b></font></a> section for more information on the
XSLT* settings that drive this API. The XSLT setting itself
uses this API internally to do its rendering.
<font face="courier new" size=3><pre>
</pre></font>This API was created to allow developers easy XSLT component
rendering without having to render the entire ASP scripts
via XSLT. This will make an easy plugin architecture for
those looking to integrate XML into their existing ASP
application frameworks.
<font face="courier new" size=3><pre>
</pre></font>At some point, the API will likely take files as arguments,
but not as of the 2.11 release.</font>
</font>
</td>
<td bgcolor=white valign=top>
</td>
( run in 2.048 seconds using v1.01-cache-2.11-cpan-39bf76dae61 )