ASP Built-in Objects

ASP Built-In Objects
K. Yue, copyright 2000
Created October 27, 2000

Introduction

ASP comes with several built-in objects.
The following ASP objects are especially important:

Request: get information from a user.
Response: send information to a user.
Server: control the ASP execution
Session: store information about a user’s session.
Application: share information among users of an application.

The Request Object

The Request object retrieves the values of the HTTP request passed to the Web server.
The values include:
- a standard set of information included in the server variable set.
- a set of parameters passed with the POST method.
- a set of query parameters attached to the GET method.
- cookies that are passed from a browser.
- client Certificates.
There are five element collections:
- QueryString
- Form
- Cookies
- ServerVariables
- ClientCertificate

Example:

servervar.asp: listing the contents of the server variables.

<body bgcolor="#ccccff">
<table border="1">
<tr>
<td><span style="background-color:#ffffcc;color:blue">Server Variable</span></td>
<td><span style="background-color:#ffffcc;color:blue">Value
</span></td>
</tr>
<% for each strKey in Request.ServerVariables %>
<tr>
<td><%= strKey %></td>
<td>
<% strVal = Request.ServerVariables(strKey)
   if (strVal = "") then
      strVal = " "
   end if
   Response.write(strVal)
%>
</td>
</tr>
<% next %>
</table>
</body>

Example:

QueryString

<body bgcolor="#ccccff">
<table border="1">
<tr>
<td><span style="background-color:#ffffcc;color:blue"
>Get Parameters</span></td>
<td><span style="background-color:#ffffcc;color:blue"
>Value</span></td>
</tr>
<% for each strKey in Request.QueryString %>
<tr>
<td><%= strKey %></td>
<td>
<% for i = 1 to Request.QueryString(strKey).Count
      Response.write ("[" & i & "]: " & _
      Request.QueryString(strKey)(i) & "<br>")
   next ' i
%>
</td>
</tr>
<% next %>
</table>
</body>

Notes:

The QueryString collection gives the values of the Get parameters.
The count property gives the number of values of a parameter.
The values of a parameter are stored in an array started with the index 1, not 0.

Example:

QueryStringExampleSource.html:

<a href="QueryStringExample.asp?name=Bun+Yue&name=Joe+Lee&course=database">
Click here to see an example of QueryString
</a>

QueryStringExample.asp:

Course:
<%= Request.QueryString("course") %>. <br>
COURSE:
<%= Request.QueryString("COURSE") %>. <br>
Title:
<%= Request.QueryString("title") %>. <br>
Names are:
<%= Request.QueryString("name") %>. <br>
Name #1:
<%= Request.QueryString("name") (1)%>. <br>
Name #2:
<%= Request.QueryString("name") (2)%>. <br>

The Form collection contains all HTTP parameters submitted with the POST method.

Example:

FormExampleSource.html:

<FORM ACTION ="FormExample.asp" METHOD=POST>
<H3>A simple example of forms</H3>
<P>
Your name:
<INPUT TYPE=TEXT SIZE=40 NAME=user>
<P>
Are you a CIS student?
<INPUT TYPE=CHECKBOX CHECKED name=cisstudent value=yes>
<P>
Your age:<BR>
<INPUT TYPE=RADIO NAME=age value="0-12">0-12<BR>
<INPUT TYPE=RADIO NAME=age value="13-19" CHECKED>13-19<BR>
<INPUT TYPE=RADIO NAME=age value="20-30">20-30<BR>
<INPUT TYPE=RADIO NAME=age value="31-45">31-45<BR>
<INPUT TYPE=RADIO NAME=age value="46-">46-<BR>

<P>
Your flavorite ice cream:<BR>
<SELECT NAME=icecream MULTIPLE><BR>
<OPTION value=Vanila SELECTED>Vanila<BR>
<OPTION value="Rocky Road">Rocky Road<BR>
<OPTION value=Strawberry>Strawberry<BR>
<OPTION value=Peach>Peach<BR>
<OPTION value="Chocolate Mint">Chocolate Mint<BR>
</SELECT>

<P>
Your comments:<BR>
<TEXTAREA NAME=comments ROWS=6 COLS=65>
</TEXTAREA>

<P>
<INPUT TYPE=SUBMIT VALUE="Submit">
<INPUT TYPE=RESET VALUE="Reset">
</FORM>

FormExample.asp:

<H3> Result of your form submission </H3>

<P>
Your name: <% = Request.Form("user") %>.<BR>
Your age: <% = Request.Form("age") %>.<BR>

<% IF Request.Form("cisstudent") = "yes" THEN %>
You are a CIS student.<BR>
<% ELSE %>
You are not a CIS student.<BR>
<% END IF %>

<P>
Your favorite ice cream:<BR>
<UL>
<% FOR EACH icecream in Request.Form("icecream") %>
<LI> <% = icecream %>
<% NEXT %>
</UL>
<P>
Your comments:
<P>
<% = Request.Form("comments") %>

The Response Object

The response object is used to send output to the user.
The response object has one collection: Cookies.
The Cookies collection allow the setting of cookie values.
specifies cookie values. Using this collection, you can set cookie values.

The response object has nine properties. The more important ones:
- Buffer: indicates whether page output is buffered.
- ContentType: specifies the HTTP content type for the response.
- Expires: specifies the length of time before a page cached on a browser expires.
- ExpiresAbsolute: specifies the date and time on which a page cached on a browser expires.
- Status: the value of the status line returned by the server.

The response object has 8 methods
- AddHeader: sets the HTML header name to value.
- AppendToLog: Adds a string to the end of the Web server log entry for this request.
- BinaryWrite: writes the given information to the current HTTP output without any character-set conversion.
- Clear: erases any buffered HTML output.
- End: stops processing the .asp file and returns the current result.
- Flush: sends buffered output immediately.
- Redirect: sends a redirect message to the browser, causing it to attempt to connect to a different URL.
- Write: writes a variable to the current HTTP output as a string.

Example:

redirect.asp: redirecting to another page.

<%
Response.Redirect("http://sce.uhcl.edu/yue")
%>

Example:

cookies.asp

<%
Name = Request.QueryString("Name")
If (Name <> "") Then ' Set cookies.
   Response.Cookies("Name") = Name
   Response.Cookies("Name").Expires = #December 31, 2001#
Else ' Read from Cookie
   Name = Request.Cookies("Name")
End If

FavoriteColor = Request.QueryString("FavoriteColor")
If (FavoriteColor <> "") Then
   Response.Cookies("FavoriteColor") = FavoriteColor
   Response.Cookies("FavoriteColor").Expires = #December 31, 1998#
Else
   FavoriteColor = Request.Cookies("FavoriteColor")
End If
%>

<html>
<head>
<title>Simple Cookies</title>
</head>

<body bgcolor="#ccffff">
<%
If (Name = "" and FavoriteColor = "") Then
%>


<form name="GetInput">
Your Name:
<input type="text" name="Name" value="<% =Name %>"><br>
Your Favorite Color:
<input type="text" name="FavoriteColor"
value="<% =FavoriteColor %>"><BR>
<input type="submit">
</form>

<% Else %>
<span style="color:<% = FavoriteColor %>">
<% =Name %></span>, welcome!
<% End If %>
</body>
</html>

Note:

The code that stores the cookie must come before the HTML contents as cookies are part of the HTTP response header.
The HTTP header sent may include:

Set-Cookie: ASPSESSIONIDQQQGQHWB=KLCNDCPCHPEGHBMNEINPDFNN; path=/
Set-Cookie: Name=Bun+Yue; expires=Mon, 31-Dec-2001 06:00:00 GMT; path=/yue

The Server Object

The Server object provides access to methods and properties on the server, utility functions.
The property of the server object is ScriptTimeout , which is the amount of time that a script can run before it times out. The default value is 90 seconds.
The methods for the server object are:
- CreateObject: creates an instance of a server component.
- HTMLEncode: applies HTML encoding to the specified string.
- URLEnocde: applies URL encoding rules, including escape characters, to the string.
- MapPath: maps the specified virtual path, either the absolute path on the current server or the path relative to the current page, into a physical path.
- Execute: executes an .asp file.
- Transfer: sends all of the information that has been assembled for processing to another asp file (IIS 5.0).
  - Server.Transfer acts as an efficient replacement for Response.Redirect.
  - The argument must of Transfer must be a relative URL.
- GetLastError: returns an ASPError Object describing the error condition that occurred.

Example:

transfer.asp: transferring to another asp file in the same directory.

<%
Server.Transfer("cookies.asp")
%>

Example:

mappath.asp: illustrating the mappath function.

<%
   Response.write("This URL file: " & _
      server.mappath(Request.ServerVariables("PATH_INFO")) & _
      "<br>")
   Response.write("cookies.asp: " & _
      server.mappath("cookies.asp") & _
   "<br>")
%>

The Application Object

The Application object is used to share information among all users of a given application.
An ASP-based application is defined as all the .asp files in a virtual directory and its subdirectories.
The methods of Applications are:
Lock: prevents other clients from modifying Application object properties.
Unlock: allows other clients to modify Application object properties.

Example:

ApplicationSet.asp:

<body bgcolor="#ccccff">
Setting author and id properties for
the Application object.
<%
Application("author") = "Kwok-Bun Yue"
Application("id") = "007"
%>
</body>

ApplicationContents.asp:

<body bgcolor="#ccccff">
<h2>Contents of the Application Objects:</h2>
<%
For Each Key in Application.Contents
Response.Write Key + " = " + Application(Key) + "<br>"
Next
%>
</body>

ApplicationRemove.asp:

<body bgcolor="#ccccff">
Removing "author" and "id" from
the application object.
<%
Application.Contents.Remove("author")
Application.Contents.Remove("id")
%>
</body>

Example:

A Microsoft's example

<%
Application.Lock
Application("NumVisits") = Application("NumVisits") + 1
Application.Unlock
%>

This application page has been visited
<%= Application("NumVisits") %> times!

The events are Application_OnStart and Application_OnEnd.
The event Application_OnStart is executed the first time a session of the application starts, before Session_OnStart.
The event Applicatoin_OnEnd is executed when the application is ended.
The two event handlers should be defined in the file global.asa.

The Session Object

The Session object is used to store information needed for a particular user session.
Sessions are automatically created and destroyed by the web server. They are cookie based.
Variables stored in the Session object are not discarded when the user jumps between pages in the application; instead, these variables persist for the entire user session.
Properties of the Session object are:
SessionID Returns the session identification for this user.
Timeout The timeout period for the session state for this application, in minutes.
There is one method of the object Session: Abandon.
Abandon: destroys a Session object and releases its resources.
Session variables are like global variables and may degrade the performance of the server. Use them very selectively.

Global References

Global.asa is an optional file for specifying event scripts and declaring objects that have session or application scope.
Global.asa is not a content file displayed to the users; instead it stores event information and objects used globally by the application.
Global.asa must be stored in the root directory of the application. An application can only have one Global.asa file.
Inside Global.asa, the following can be defined.
Application events: Application_OnStart, Application_OnEnd
Session events: Session_OnStart, Session_OnEnd.
<OBJECT> Declarations

Example:

<OBJECT RUNAT=Server SCOPE=Application ID=MyConnection
PROGID="ADODB.Connection">
REM Object Script
' With username yue and password sleeping.
MyConnection.open "Resume", "yue", "sleeping"
</OBJECT>