NAME

CatalystX::ASP::Server - $Server Object

SYNOPSIS

use CatalystX::ASP::Server;

my $svr = CatalystX::ASP::Server->new(asp => $asp);
my $html = $svr->HTMLEncode('my $has_timeout = $Server->{ScriptTimeout} && 1');

DESCRIPTION

The $Server object is that object that handles everything the other objects do not. The best part of the server object for Win32 users is the CreateObject method which allows developers to create instances of ActiveX components, like the ADO component.

ATTRIBUTES

$Server->{ScriptTimeout} = $seconds: Not implemented. May never be. Please see the Apache Timeout configuration option, normally in httpd.conf.

METHODS

$Server->Config($setting)

API extension. Allows a developer to read the CONFIG settings, like Global, GlobalPackage, StateDir, etc. Currently implemented as a wrapper around

$self->asp->$setting

May also be invoked as $Server->Config(), which will return a hash ref of all the ASP configuration settings.

$Server->CreateObject($program_id)

Not implemented.

$Server->Execute($file, @args)

New method from ASP 3.0, this does the same thing as

$Response->Include($file, @args)

and internally is just a wrapper for such. Seems like we had this important functionality before the IIS/ASP camp!

$Server->File()

Returns the absolute file path to current executing script. Same as $ENV{SCRIPT_NAME} when running under mod_perl.

ASP API extension.

$Server->GetLastError()

Not implemented, will likely not ever be because this is dependent on how IIS handles errors and is not relevant in Apache.

$Server->HTMLEncode( $string || \$string )

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.

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:

my $buffer = '&' x 100000;
$buffer = $Server->HTMLEncode($buffer);
print $buffer;

my $buffer = '&' x 100000;
$Server->HTMLEncode(\$buffer);
print $buffer;

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.

$Server->MapInclude($include)

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.

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:

if ($Server->MapInclude('include.inc')) {
  $Response->Include('include.inc');
}

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.

$Server->MapPath($url);

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.

Only a $url that is relative to the host is valid. Urls like "." and "/" are fine arguments to MapPath, but http://localhost would not be.

$Server->Mail(\%mail, %smtp_args);

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.

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.

You could send an email like so:

$Server->Mail({
  To => 'somebody@yourdomain.com.foobar',
  From => 'youremail@yourdomain.com.foobar',
  Subject => 'Subject of Email',
  Body =>
    'Body of message. '.
    'You might have a lot to say here!',
  Organization => 'Your Organization',
  CC => 'youremailcc@yourdomain.com.foobar',
  BCC => 'youremailbcc@yourdomain.com.foobar',
  Debug => 0 || 1,
});

Any extra fields specified for the email will be interpreted as headers for the email, so to send an HTML email, you could set 'Content-Type' => 'text/html' in the above example.

If you have MailFrom configured, this will be the default for the From header in your email. For more configuration options like the MailHost setting, check out the CONFIG section.

The return value of this method call will be boolean for success of the mail being sent.

If you would like to specially configure the Net::SMTP object used internally, you may set %smtp_args and they will be passed on when that object is initialized. perldoc Net::SMTP for more into on this topic.

If you would like to include the output of an ASP page as the body of the mail message, you might do something like:

my $mail_body = $Response->TrapInclude('mail_body.inc');
$Server->Mail({ %mail, Body => $$mail_body });

$Server->RegisterCleanup($sub)

Not implemented. Sorry!

$Server->Transfer($file, @args)

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.

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.

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:

$Response->Include($file, @args);
$Response->End;

$Server->URLEncode($string)

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:

$data = $Server->URLEncode("test data");
$url = "http://localhost?data=$data";

$url evaluates to http://localhost?data=test+data, and is a valid URL for use in anchor <a> tags and redirects, etc.

$Server->URL($url, \%params)

Will return a URL with %params serialized into a query string like:

$url = $Server->URL('test.asp', { test => value });

which would give you a URL of test.asp?test=value

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 CONFIG section, and the SESSIONS section too.

$Server->XSLT(\$xsl_data, \$xml_data)