NAME Win32::ASP - a module for ASP (PerlScript) Programming SYNOPSIS use Win32::ASP; print "This is a test

"; $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 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 <, > becomes >, 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), "
\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 . Currently being maintained and updated by Bill Odom .