ActivePerl User Guide

• Active Server Pages
  • The Script Delimiters
  • The Scripting Host
  • Creating An ASP Page
• The ASP Interface
  • The ASP Intrinsic Objects
  • The Application Object
  • The ASPError Object
  • The ObjectContext Object
  • The Request Object
  • The Response Object
  • The Server Object
  • The Session Object
• Active Server Pages Samples
  • Say "Hello World!"
  • Accessing HTTP Server Variables
  • Reading the QueryString
  • Interactive Web Forms
  • Database Connections (ADO and ASP)
• Variants and Binary Data
  • To Read And Display Binary Large Objects (ADO and ASP)
• Appendix A
  • How To Set Up A System DSN
  • Why Not To Use A System DSN
  • How To Use The Native OLE DB Provider
• Appendix B
  • Book Resources
  • Online Resources
• AUTHOR AND COPYRIGHT

Active Server Pages (ASP)

Introduced in 1996, Active Server Pages (ASP) is an easy to learn server-side technology from Microsoft that has taken the web by storm. ASP is implemented as a set of objects with built-in features for fast and simple access to common services provided by the web-server for the Internet. As we will see, there are versatile reasons for using ASP as a server-side technology with ActivePerl.

To begin, if you in general are unfamiliar with server-side technologies, let's start at the core by describing the need-to-know about ASP. ASP is a feature that installs with Microsoft's Internet Information Services (IIS) web-server. No special interaction or configuration is needed afterwards, and it should run out of the box just as easily as IIS. Fundamentally, a server-side technology such as ASP puts no requirements on the client or browser, and, as a result, no browser-compatibility issues will ever occur, no browser plug-ins have to be installed, and the client does not need a local installation of ActivePerl.

Since there are no client requirements for ASP, it needs something on the server-side that tells it what to do with its features. A special implementation of a scripting language is therefore installed on the server and used in order to control and program ASP; PerlScript, which installs with ActivePerl, is suitable for the role as scripting language because it brings the power of Perl into the environment of ASP and there merges it with the services provided by ASP. There are only two things that you either may already know or will need to learn while using PerlScript:

• The Active Server Pages Object Model
• How Perl Works with Objects

On the Internet, ASP serves documents of its own filetype as opposed to familiar document types like HTML documents. This is so that the ASP document can be processed on the server side before returned to the client's browser. An ASP document has the file extension .asp, and it provides both existing features derived from ASP and the ability to execute script commands within the document. The file extension is by the webserver recognized in a special way which results in the underlying technology executing script commands that are within the file and treat other markup such as HTML in a standard fashion. The source code of your saved file's PerlScript script commands will by default never be available to the user when choosing to view the document source in the browser, so any script that you write can not be copied. The reason for this is because everything is processed on the server side and what is returned to the browser is a standard format such as HTML.

For a closure, it deserves to be repeated that if you are unfamiliar with object-oriented programming in Perl, it is strongly recommended that you sometime browse the Perl documentation on object-oriented programming to get a basic understanding of the aspects of an object and its origin. Next up, let's look at how to embed PerlScript commands within an ASP document.

The Script Delimiters

To successfully execute the script commands within an ASP file, you must specify what scripting language ASP should use to interpret the script commands. You can do this within the .asp document by either setting a default scripting language in which all script commands within the script-delimiters <% and %> will be executed by the specified scripting language. Either you can apply that setting within the Microsoft Management Console's IIS snap-in or you can use what ASP recognizes as a page command, which is indicated by the special directive @. The following example is for illustrational purposes only and it shows you how to set the default scripting language for the ASP file to PerlScript; as a result, all commands will be treated by the PerlScript engine; however, please note that no actual output or result is being displayed by the script, so if you run the code shown in the example below, you won't see an output although the code is being executed and interpreted.


<%@ Language=PerlScript %>
<%
for($i=0; $i<=10; $i++) {
#
# Your Perl code here
#
}
%>

In addition to page-commands, you can set the scripting language for a defined scope by using the <SCRIPT Language=PerlScript RUNAT=Server> and </SCRIPT> delimiters. This results in the scripting language only executing the code within the <script> elements regardless of what the default scripting language is set to for a language by the webserver or by an ASP page command for the current document.


<SCRIPT Language=PerlScript RUNAT=Server>
for($i=0; $i<=10; $i++) {
#
# Your Perl code here
#
}
</SCRIPT>

The Scripting Host

When Active Server Pages acts as the scripting host for PerlScript, it is initalized as a host first when an ASP file on the web-server is requested by the way of a URL (such as http://www.domain.com/home.asp). The web-server locates the file, and the scripting host locates the script commands that are within the script delimiters. The chunks of code found within the delimiters are passed on to PerlScript, which creates a Perl interpreter that treats the code. Afterwards, it returns to the scripting host, which waits for the next incoming call. Certain rules apply to when you write code to interact with scripting hosts such as ASP, and let's look at one of those necessary things to know by illustrating it as a parallel to writing a command-line Perl script. When you began programming Perl, among the first things you probably learned was how to print text to the screen, and it is not unusual that such a script looks as follows.

print "Hello World";

As seen, the "print()"-function of Perl outputs the string "Hello World" to what is known as the Standard Output. PerlScript, too, will send any output to what it knows as Standard Output, and when executed within the ASP scripting host, the PerlScript engine will use the features of the host's object-model in order to reach the standard output. Essentially, the host provides a set of features, and you pick the scripting language in which you wish to write your application to interact with the host. In ASP, you need to know the host because it decides what method and what object you need to deploy of the host's in order to output a string. A scripting language would become extremely bloated if it had to keep track of all those things. In contrast, the scripter needs to keep track of such features. :-) To send "Hello World" to the client's browser by using ASP, you call the "Write()"-method of the Response object as in the next example.

$Response->Write("Hello World");

In essence, it is of most importance that you know the object-model of the ASP scripting host within which you use PerlScript so that you know what object to call and how to get the best performance out of your application.

Creating An ASP Page

When looking back, the little we've seen about ASP so far is that it contains a set of objects that you can use for your programming. It also requires a scripting language that is used to access these objects, and for that purpose, PerlScript can be used to execute Perl commands that are mixed and embedded within the HTML of your Active Server Pages document. Lastly, the ASP document has its own file extension .asp which is recognized by the web server as a document parsed for first script commands and then HTML tags.

1) Create a file named PerlScript.asp
2) Edit it and enter "<HTML> Hello World </HTML>"
3) Save the file where you can access it by a URL such as http://localhost/. On IIS, the following path is often valid <device>:\inetpub\wwwroot\ where <device> is a hard-disk such as C:\ or D:\
4) Run the file in your browser by entering the URL pointing to PerlScript.asp; for example, http://localhost/PerlScript.asp

If it instead of finding the file reports an error such as "File Not Found," you need to open Windows Explorer and reassure yourself of that the file is saved with the .asp file-extension and in the correct physical location for being accessible by the browser. If the browser finds the file and "Hello World" is outputted, you can place a few script commands in the file and rest assured that ASP will execute everything as for which it was built. Edit the file so that is looks as follows.

<%@Language=PerlScript%>
<HTML>
<TITLE> PerlScript Test </TITLE>
<%
for($i=0; $i<=10; $i+=2) {
$Response->Write("<FONT SIZE=$i COLOR=#000000>");
$Response->Write("Hello World! </FONT> <BR>");
}
%>
</HTML>

The script shown is used only to output HTML and text. Essentially, the Response object's "Write()"-method sends the HTML and variable value of $i to the browser. However, $i is a part of the HTML Font element, so the result is that the font size is increased by 2 for each time "Hello World" is sent to the client's browser. You could also write the script this way:

<HTML>
<TITLE> PerlScript Example </TITLE>
<script language=perlscript runat=server>
for($i=0; $i<=10; $i+=2) {
$Response->Write("<FONT SIZE=$i COLOR=#000000>");
$Response->Write("Hello World! </FONT> <BR>");
}
</script>
</HTML>

A closure to this example, there is a shorthand for writing $Response->Write($variable), and it is not available when already within script delimiters; however, to easily mix variables with HTML you can automatically call the mentioned method by <%=$variable%> where the equal-sign automatically translates into $Response->Write(). For example:

<HTML>
<TITLE> PerlScript Example </TITLE>
<% @Language=PerlScript %>
<% for($i=0; $i<=10; $i+=2) {
%>
<FONT SIZE=<%=$i%> COLOR=#000000>
Hello World!
</FONT>
<BR>
<% } >%
</HTML>


The ASP Programming Interface

Providing an interface to common tasks for a web programmer, ASP simplifies web-programming by making the simple tasks even easier. The features of ASP are implemented and exposed as objects, and, in addition, a scripting language is enabled to not only use those features of the ASP host, the language can certainly use its own features, too.

The ASP Intrinsic Objects

Application

ASPError

The ASPError object is the only new object that shipped with ASP 3.0. It contains detailed information about an error which occured during the processing of an ASP page. Unless told otherwise by the administrator, ASP 3.0 redirects the client to a page named 500-100.asp when an error occurs, and in that page, the ASPError object is deployed to show detailed descriptions about the error. You can with PerlScript easily also extend the use the 500-100.asp page to perform custom tasks such as emailing you a formatted page of the contents of the ASPError object on an arror or writing it to a special log. Some of its useful properties include: SourceCode for returning the source code of the part of a script that generated the error, Category for tracking down the categoru of the error to ASP, scripting language, or an object, File for the name of the file processed when error was generated, and Description to return a description of the error; however, please note that ASPError objects are only returned by the Server object's GetLastError method.


# Return the ASPError object
#
$ASPError = $Server->GetLastError();

# Output the error's description
#
$Response->Write( $ASPError->{Description} );

ObjectContext

The ObjectContext object is used for a page that is run as a transaction. This object enables you to commit or abort a transaction, which is an important functionality for deployed business applications. Its only methods are SetAbort() and SetComplete(). They are used to commit or abort the transaction. Before this can be used, your page must include a @TRANSACTION page command in the page, whereas you are enabled only to define @ once per file; however, you can use multiple directives within the @ such as <%@directiveA=something directiveB=somethingelse%>. If you use PerlScript a lot, you are better off setting it as the default language in the Microsoft Management Console. Setting the default language in the MMC is unfortunately not an option for Personal Web Server. PWS is good for practicing a scripting language and ASP, but it is not good for tailormaking your webservice in terms of IIS applications and other tasks that are administrative. For example, it does not have the Microsoft Management Console. What PWS mainly does is to allow you to publish and develop Active Server Pages within reson while it hides the administrative tasks.

Request

For good reason, the Request object is a widely used object. It contains a collection of information such as form-data or cookies gathered from the client. With this object you can gather the contents submitted from any type of web-form, read server variables or the contents of a digital client certificate. You can also read binary data such as an uploaded file by first determining the number of bytes sent with the TotalBytes-property and then read it with the BinaryRead($bytes_to_read) method.


# Get the number of total bytes in the request
#
$bytes_to_read = $Request->{TotalBytes};

# Read and return a variant array of type VT_U1
#
$read_bytes=$Request->BinaryRead( $bytes_to_read );

In the Request object, collections that you can read includes ClientCertificate for digital certificated, Cookies for cookies sent with the HTTP request, Form for data posted by a web form using the POST method, QueryString for data passed with the QueryString or GET method from a web form, and ServerVariables for HTTP environment variables such as the server software or the users browser.

# Let's see what's in the ALL_HTTP variable
#
$Response->Write( $Request->ServerVariables('ALL_HTTP')->Item() );

Response

The Response Object is responsible for sending data from the client to the server. For example, you can print strings such as HTML or scalar variables, and you can also print binary data such as images, set cookies, control cache, character sets, and content-types, plus send the client status headers, append data to the log, set PICS labels, and see if the client is still connected. A cookie can contain the attributed Domain, Expires, HasKeys, Path, and Secure, and you first declare a cookie before setting these attributes.

# Ask the client's browser if it wants a cookie
#
$Response->Cookies->SetProperty(
'Item',
'someCookie',
'Hi! This is a cookie!'
);


# ==================================================
# Let's set some attributes of the cookie!
# ==================================================

# This is the domain that can read the cookie; to specify it further,
# use the Path-attribute to define a more complete URL
#
$Response->Cookies('someCookie')->{Domain} = 'somesite.com';

# The expiration date for the cookie
#
$Response->Cookies('someCookie')->{Expires} = 'January 1, 1999';

# Not a secure cookie; 1 defines it as secure
#
$Response->Cookies('someCookie')->{Secure} = 0;