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";
            exit;

Description
    These routines are some I knocked together one day when I was
    saying the following: "Why don't my "print" statements output to
    the browser?" and "Why doesn'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). You can also get at print using the OO mechanism
    with $Win32::ASP::SH->print(). Also added recently was code that
    allowed cleanup stuff to be executed when you exit() or die(),
    this comes in the form of the `AddDeathHook' function. The
    `BinaryWrite' function simply wraps up unicode conversion and
    BinaryWrite in one call. Finally I was annoyed that I couldn't
    just develop a script using GET and then change to POST for
    release because of the difference in how the ASP code handles
    the different formats, GetFormValue solves that one.

  Installation instructions

    Download the file. If you get it from my geocities web site you
    will have to rename it (they don't like .pm extensions). Make
    sure the file is called ASP.pm

    Now move the file into the perl\site\<version>\lib\win32
    directory (where <version> is your perl version).

    That's it - you're ready to start PerlScripting with ease.

Function Reference
    use Win32::ASP qw(:strict);
        This allows you to use the ASP module in a "strict" perl
        script. Normally under "use strict" PerlScript would
        complain that the ASP objects ($Response, $Session etc) were
        not initialised: "Global symbol "Response" requires explicit
        package name at - line XXX".

        To get around this I simply assign and assign back the
        variables, and export them into the main namespace.

        Note: In order to use this feature you may have to make
        changes to the registry. This is at your own risk. If your
        computer stops working after you make these changes I am not
        responsible. I have made the changes myself and they appear
        to work, but please be careful.

        Change the following keys:

                HKEY_LOCAL_MACHINE\
                  SYSTEM\
                    CurrentControlSet\
                      Services\
                        W3SVC\
                          ASP\
                            LanguageEngines\
                              PerlScript

                Write = "$main::Response->write(|);"
                WriteBlock = "$main::Response->writeblock(|);"

        The change should be just to add the "main::" after the "$"
        and before "Response".

    Print LIST
        Prints a string or comma separated list of strings to the
        browser. Use as if you were using print in a CGI
        application. Print gets around ASP's limitations of 128k in
        a single Response->Write call.

        Obsolete - use `print' instead.

        NB: `print' calls Print, so you could use either, but print
        is more integrated with "the perl way".

    DebugPrint LIST
        The same as `Print' except the output is between HTML
        comments so that you can only see it with "view source".
        DebugPrint is not exported so you have to use it as
        Win32::ASP::DebugPrint()

        This function is useful to debug 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 taken and encoded
        so that any html tags appear as sent, i.e. < becomes &lt;, >
        becomes &gt; etc. HTMLPrint is not exported, so use it like
        Win32::ASP::HTMLPrint.

        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
        Obsolete: Use `Print' instead

    die LIST
        Prints the contents of LIST to the browser and then exits.
        `die' automatically calls $Response->End for you, it also
        executes any cleanup code you have added with
        `AddDeathHook'.

    exit
        Exits the current script. $Response->End is called
        automatically for you, and any cleanup code added with
        `AddDeathHook' is also called.

    HTMLEncode LIST
        The same as HTMLPrint except the output is not printed but
        returned as a scalar instead. HTMLEncode is not exported, so
        use it like Win32::ASP::HTMLEncode.

        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 ref is passed it uses the ref, otherwise it
        assumes an array of scalars is used. Using a ref 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 return an array: @AllQs = ['a', 'b']

    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, url is:

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

        And code is:

                my $numQs = GetFormCount('Q');

        gives $numQs = 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 should be executed on a graceful exit of the
        script too, but I've been unable to confirm this. If anyone
        has any luck, let me know.

    BinaryWrite LIST
        Performs the same function as `$Response-'>`BinaryWrite()'
        but gets around Perl's lack of unicode support, and the null
        padding it uses to get around this.

        Example:

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

    SetCookie Name, Value [, HASH]
        Sets the cookie Name with the value Value. HASH is option,
        and contains any of the following optional parameters:

    * -expires => A CGI.pm style expires value (see the CGI.pm docs for header() for this).
    * -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.
        Example:

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