20.2 Server-Side PerlScript (Perl in a Nutshell)

20.2 Server-Side PerlScript

PerlScript on the server-side of business is a much more viable method of incorporating Perl into your web applications. You can use PerlScript as the scripting language for Active Server Pages (ASP), which are used by such applications as Microsoft's IIS and O'Reilly's WebSite Pro. See the documentation for these products to properly set up ASP on your server. ActivePerl with PerlScript must be installed on the server machine to be used with ASP.

Active Server Pages use PerlScript in pages much like client-side scripting except that the object model is different, and most importantly, the script is executed on the server. When an Active Server Page is requested, the .asp file is processed, scripts are executed, and an HTML page is produced and delivered to the client.

Each script is contained within <SCRIPT> tags. PerlScript must be declared as the default scripting language for each file with:

<SCRIPT LANGUAGE="PerlScript" RUNAT=Server>

The RUNAT attribute signals that the script is to be executed on the server and not the client. The lines of the script follow, and the script is closed with an ending </SCRIPT> tag.

An alternative syntax to the <SCRIPT> tags are the <% %> delimiters. These are not HTML tags, but indicate that whatever happens between them is to be executed. There are also special constructs used with these delimiters. Since they can be interspersed with HTML throughout a file, the default language must be declared at the top of the file with the <%@ %> tag:

<%@ PerlScript%>

This delimiter syntax completely replaces the declarative <SCRIPT> tag shown above, but it must be placed at the top of any file using the <% %> syntax for scripting. In addition to this tag, you can use the <%= %> tag throughout your file to automatically assign a value to the output of your file (i.e., a $Response->write function). Here is an example:

<%@ PerlScript>
<HTML>
<HEAD></HEAD>
<BODY>
<H1>Say Hello, Boys!</H1>

<% my @onehit = ("Bel", "Biv", "DeVoe"); %>

<P>
<%= $onehit[0] %> says "Hello."
<BR>
<%= $onehit[1] %> says "Hello."
<BR>
<%= $onehit[2] %> says "Hello."

</P>
</BODY>
</HTML>

The return value of any code within <%= %> is placed into the output HTML returned to the client. This syntax makes it very easy to intersperse the output of commands with HTML throughout the ASP file.

The scripting object model for ASP contains the following top-level objects:

Application: Application objects can be created to share data among multiple users of defined groups of .asp files under a virtual directory on the server.
Request: The Request object encapsulates all of the information about the browser and any data it supplies in its request, such as POST data from a form. It is equivalent to the information contained in an HTTP request.
Response: The Response object represents information and data sent to a client after a request. It is equivalent to an HTTP server response.
Server: The Server object contains certain control parameters for the server and provides methods for creating connections to other applications.
Session: The Session object uses cookies to store state information for a user across multiple pages accessed during a session.

The Request and Response objects provide an ASP interface to the HTTP protocol used in web transactions. The other objects encapsulate special server features and connections to outside applications.

20.2.1 The Request Object

The Request object contains all the information sent to the server in the client's request. This object has only one property, TotalBytes, which is read-only and gives the number of bytes sent in the body of a client request. The BinaryRead method of the Request object retrieves the client request as raw binary data.

The information contained in a request is stored in various collection objects. Collections contain objects that represent the important pieces of a request, for example, form or cookie data. There are five collections under the Request object:

ClientCertificate: Contains information from a client certificate sent in the request.
Cookies: Contains the data from any cookies sent in the request.
Form: Contains POST data from forms.
QueryString: Contains form data passed in the query string of the URL.
ServerVariables: Contains the values of environment variables and header values in the request.

To access the objects in the collection, the name of an object is given as the argument to the Collection object. For example, to access a form variable named "birthday" from the Form collection, you would use:

$object = $Request->Form("birthday");

This returns an object for the "birthday" form variable. To get the value, you use the Item method on the object:

$data = $Request->Form("birthday")->Item;

This returns the value assigned to "birthday" in the request. Since ASP collection objects are OLE collections, the functionality of the Win32::OLE modules can be employed. See Chapter 19, Win32 Modules and Extensions, for more information on OLE collections.

The QueryString collection contains form data input by the GET method and transmitted at the end of the requested URL. Values are retrieved from the QueryString object the same way they are retrieved from the form object, for example:

$data = $Request->QueryString("birthday")->Item;

Cookies sent within a client request are stored the same way. The name of the cookie variable retrieves the cookie object from the collection, and Item retrieves the value:

$data = $Request->Cookie("birthday")->Item;

The ServerVariables collection stores both environment variables relevant to the transaction and HTTP headers sent in the request. The header objects are accessible by using the syntax: HTTP_HeaderName. Underscores contained within HeaderName are interpreted as dashes.

20.2.2 The Response Object

The Response object contains the information output to the client. The Write method is primarily used to write the output of code to the client, but the Response object is also used to create and send cookies to the client, as well as manipulate headers, update server logs, and set control parameters for the document.

20.2.2.1 Setting cookies

The Response object contains one collection for setting cookies with the client. The Cookies collection allows you to create cookies and sets the information that is delivered to the client in the Set-Cookie header of the HTTP response.

In the ASP file, you can check for a returned cookie in the request, and if there is none, you can set a new cookie:

<%
if ( defined($Request->Cookie("user") )
  { $userid = $Request->Cookie("user")->Item; }
else
  { $Response->Cookie("user") = 123; };
%>

This will check to see if a cookie named user was sent in the request. If it was not, a new cookie is sent in the response and set on the client machine.

The Response cookie collection uses a number of properties to set the standard attributes used with cookies. For example, to set the expiration of a cookie, you would use the Expires attribute:

$Response->Cookie("user")->{Expires} = "Tuesday, 31-Dec-99 00:00:00 GMT";

The client will no longer return a cookie after its expiration date.

The following properties are used to set attributes on a response cookie:

Domain: If specified, the cookie will be sent in any request to this domain. The value must contain at least two dots, e.g., .oreilly.com. This value would cover both www.oreilly.com and software.oreilly.com.
Expires: Sets the expiration date for the cookie.
Path: Sets the URL range for which the cookie is valid. If the value is set to /pub, for example, the cookie will be returned for URLs in /pub as well as subpaths such as /pub/docs and /pub/images. A path value of "/" indicates that the cookie will be used for all URLs at the originating site. If no path value is set, the cookie will be returned only for the originating URL.
Secure: If set to true, this attribute instructs the client to return the cookie over only a secure connection (via SHTTP or SSL).

20.2.2.2 Response properties

The following properties can be set on the Response object. The property syntax is as follows:

$Response->{property} = value;

Buffer: If set to false, output is sent the client immediately as it is processed by the script. If set to true, output is buffered and sent only when the entire page has been processed, or upon calls to the Flush or End methods.
CacheControl: If set to Private, output from this ASP page will not be cached by a proxy server. If set to Public, the output can be cached by a proxy server.
Charset: Appends the given character set name to the Content-Type header.
ContentType: Specifies the HTTP content type of the response; for example, text/html.
Expires: Specifies the length of time in minutes before a client-cached page expires. After this time, the page will be requested again. A setting of 0 forces the page to expire immediately.
ExpiresAbsolute: Specifies the date and time on which a client-cached page expires. The date and time are given in a format such as "June 18,1999 00:00:00", where the time is GMT.
IsClientConnected: Returns true if the client is still connected to the server (possibly waiting on a request); false, otherwise.
Pics: Adds a PICS-label header to the response with the given PICS formatted string.
Status: Sets the status code and explanation string in a server response, for example "403 Forbidden".

20.2.2.3 Response methods

The following methods can be used on the Response object.

AddHeader (header, value): Adds an HTTP header with assigned value to the header of the HTTP response. The specified header will simply be added to the response; it will not replace an existing header. This method must be used in the ASP file before any page content is output. For buffered pages, it can be used anywhere before the first Flush call.
AppendToLog (string): Appends string to the server log (if extended logging is properly configured). string can be a maximum of 80 characters and should not contain commas.
BinaryWrite (data): Writes the given binary data to the HTTP output without any conversion.
Clear (): Clears any response content from the output buffer. This method will not clear header information, and will cause a runtime error if $Response->Buffer has not been set to true.
End (): Stops all processing of the ASP file and outputs any buffered content.
Flush (): If buffering has been enabled with $Response->Buffer, this call clears the buffer and outputs its contents.
Redirect (url): Instructs the client to connect to the specified url.
Write (data): Writes the data to the HTML output stream.


20.1 Client-Side PerlScript