NAME

Win32::ASP - a module for ASP (PerlScript) Programming

SYNOPSIS

    use Win32::ASP;

    print "This is a test<BR><BR>";

    $PageName = GetFormValue('PageName');

    if ($PageName eq 'Select a page...')
      {
        die "Please go back and select a value from the Pages list.";
      }

    print "You selected the ", $PageName, " page.<BR>";

    exit;

DESCRIPTION

I knocked these routines together one day when I was wondering "Why don't my print statements output to the browser?" and "Why don't exit and die end my script?" So I started investigating how I could overload the core functions. print is overloaded via the tie mechanism (thanks to Eryq (eryq@zeegee.com), Zero G Inc. for the code which I ripped from IO::Scalar).

Also added recently was AddDeathHook, which allows cleanup code to be executed upon an exit or die. BinaryWrite wraps up Unicode conversion and $Response->BinaryWrite in one call. Finally, I was annoyed that I couldn't just develop a script using GET, then change to POST for release, since ASP code handles each one differently. GetFormValue solves that one.

Installation instructions

Assuming the ActiveState repository is up-to-date with the latest archive from CPAN, you should be able to type:

    ppm install Win32-ASP

on the command line. Make sure you're connected to the Internet first.

Installing via MakeMaker is pretty standard -- just download the archive from CPAN, extract it to some directory, then type in that directory:

    perl Makefile.PL
    nmake
    nmake install

Don't do nmake test because the ASP objects won't be available.

Function Reference

Print LIST

Obsolete - use print instead.

Outputs a string or comma-separated list of strings to the browser. Use as if you were using print in a CGI application. Print handles the ASP limitation of 128K per $Response->Write call.

Note: print calls Print, so you can actually use either one, but print is more integrated with "the Perl way."

DebugPrint LIST

The same as Print, except the output is wrapped in HTML comment markers, so that you can only see it by viewing the page source. DebugPrint is not exported, so call it as

    Win32::ASP::DebugPrint($val);

This function is useful for debugging your application. For example, I use it to print out SQL before it is executed.

HTMLPrint LIST

The same as Print, except the output is encoded so that any HTML tags appear as sent, i.e. < becomes &lt;, > becomes &gt;, etc. HTMLPrint is not exported, so call it as

  Win32::ASP::HTMLPrint($val);

This function is useful for printing output that comes from a database or a file, where you don't have total control over the input.

wprint LIST

Deprecated - use print instead.

die LIST

Outputs the contents of LIST to the browser and then exits. die automatically calls $Response->End and executes any cleanup code added with AddDeathHook.

exit

Exits the current script. exit automatically calls $Response->End and executes any cleanup code added with AddDeathHook.

HTMLEncode LIST

The same as HTMLPrint, except the output is not printed but returned as a scalar instead. HTMLEncode is not exported, so call it as

    my $text = Win32::ASP::HTMLEncode($val);

This function is useful to handle output that comes from a database or a file, where you don't have total control over the input.

If an array reference is passed, HTMLEncode uses it. Otherwise, it assumes an array of scalars is used. Using a reference makes for less time spent passing values back and forth, and is the prefered method.

GetFormValue EXPR [, EXPR]

Returns the value passed from a form (or non-form GET request). Use this method if you want to be able to develop in GET mode (for ease of debugging) and move to POST mode for release. The second (optional) parameter is for getting multiple parameters, as in

    http://localhost/scripts/test.asp?Q=a&Q=b

In the above, GetFormValue("Q", 1) returns "a" and GetFormValue("Q", 2) returns "b".

GetFormValue will work in an array context too, returning all the values for a particular parameter. For example, with the above URL:

    my @AllQs = GetFormValue('Q');

will result in the array @AllQs containing ('a', 'b').

If you call GetFormValue without any parameters, it will return a list of form parameters in the same way that CGI.pm's param function does. This allows easy iteration over the form elements:

    for my $key (GetFormValue())
      {
        print "$key = ", GetFormValue($key), "<br>\n";
      }

For convenience, Win32::ASP exports param as an alias for GetFormValue.

param EXPR [, EXPR]

param is an alias for GetFormValue.

GetFormCount EXPR

Returns the number of times EXPR appears in the request (Form or QueryString). Use this value as $i to iterate over GetFormValue(EXPR, $i).

For example, if the URL is:

    http://localhost/scripts/myscript.asp?Q=a&Q=b

And code is:

    my $numQs = GetFormCount('Q');

Then $numQs will equal 2.

AddDeathHook LIST

This frightening-sounding function allows you to have cleanup code executed when you die or exit. For example, you may want to disconnect from your database if there is a problem:

    <%
        my $Conn = $Server->CreateObject('ADODB.Connection');
        $Conn->Open( "DSN=BADEV1;UID=sa;DATABASE=ProjAlloc" );
        $Conn->BeginTrans();

        Win32::ASP::AddDeathHook( sub { $Conn->Close if $Conn; } );
    %>

Now when you die because of an error, your database connection will close gracefully, instead of you having loads of rogue connections that you have to kill by hand, or restart your database once a day.

Death hooks are not executed upon the normal termination of the script, so if you have processing that should occur upon a normal exit, be sure to execute it directly.

BinaryWrite LIST

Performs the same function as $Response->BinaryWrite, but handles Perl's Unicode-related null padding. This function is not exported, so call it as

  Win32::ASP::BinaryWrite($val);

LoadEnvironment

Copies the $Request->ServerVariables collection to the %ENV hash, allowing the values to be accessed as environment variables. Changes to %ENV are not propagated back to the ServerVariables collection, and changes to the ServerVariables collection do not automatically appear in %ENV. To see any such changes, simply run LoadEnvironment again.

LoadEnvironment is not exported, so run it as follows:

    Win32::ASP::LoadEnvironment;

SetCookie Name, Value [, HASH]

Sets the cookie Name with the value Value. The optional HASH can contain any of the following parameters:

• -expires => A CGI.pm style expires value (see the CGI.pm header() documentation).

• -domain => a domain in the style ".matt.com" that the cookie is returned to.

• -path => a path that the cookie is returned to.

• -secure => cookie only gets returned under SSL if this is true.

If Value is a hash reference, then it creates a cookie dictionary. See the ASP docs for more info on cookie dictionaries.

Example:

    Win32::ASP::SetCookie("Matt", "Sergeant", ( -expires => "+3h",
        -domain => ".matt.com",
        -path => "/users/matt",
        -secure => 0 ));

AUTHORS

Originally created by Matt Sergeant <matt@sergeant.org>.

Currently being maintained and updated by Bill Odom <wnodom@intrasection.com>.