ASP Objects

Beginning ASP Objects

This document is intended to provide you with an overview of the key ASP objects (as version 2.0) that you can use in beginning applications...

For more detailed information, please refer to the Microsoft MSDN Web Site.

Response Object

You can use the Response object to send output to the client.

Write

The Write method writes a specified string to the current HTTP output.

Syntax

Response.Write variant

Parameters

variant: The data to write. This parameter can be any data type supported by the Visual Basic^® Scripting Edition VARIANT data type, including characters, strings, and integers. This value cannot contain the character combination %>; instead you should use the escape sequence %\>. The Web server will translate the escape sequence when it processes the script.

Example

The following examples use the Response.Write method to send output to the client.

I just want to say <% Response.Write "Hello World." %> 
Your name is: <% Response.Write Request.Form("name") %>

The following example adds an HTML tag to the Web page output. Because the string returned by the Write method cannot contain the character combination %>, the escape %\> has been used instead. The following script

<% Response.Write "<TABLE WIDTH = 100%\>" %>

produces the output

<TABLE WIDTH = 100%>

Redirect

The Redirect method causes the browser to attempt to connect to a different URL.

Syntax

Response.Redirect URL

Parameters

URL: The Uniform Resource Locator that the browser is redirected to.

Remarks

Any response body content set explicitly in the page is ignored. However, this method does send other HTTP headers set by this page to the client. An automatic response body containing the redirect URL as a link is generated. The Redirect method sends the following explicit header, where URL is the value passed to the method.

HTTP 1.0 302 Object Moved
Location URL

Example

The following example redirects the user to www.microsoft.com.

<% 
  Response.Redirect "http://www.microsoft.com" 
 %>

Flush

The Flush method sends buffered output immediately. This method will cause a run-time error if Response.Buffer has not been set to TRUE.

Syntax

Response.Flush

Remarks

If the Flush method is called on an ASP page, the server does not honor Keep-Alive requests for that page.

Clear

The Clear method erases any buffered HTML output. However, the Clear method only erases the response body; it does not erase response headers. You can use this method to handle error cases. Note that this method will cause a run-time error if Response.Buffer has not been set to TRUE.

Syntax

Response.Clear

End

The End method causes the Web server to stop processing the script and return the current result. The remaining contents of the file are not processed.

Syntax

Response.End

Remarks

If Response.Buffer has been set to TRUE, calling Response.End will flush the buffer. If you do not want output returned to the user, you should call Response.Clear first.

<% 
  Response.Clear
  Response.End
%>

Buffer

The Buffer property indicates whether to buffer page output. When page output is buffered, the server does not send a response to the client until all of the server scripts on the current page have been processed, or until the Flush or End method has been called.

The Buffer property cannot be set after the server has sent output to the client. For this reason, the call to Response.Buffer should be the first line of the .asp file.

Syntax

Response.Buffer [= flag]

Parameters

flag

Remarks

If the current .asp file has buffering set to TRUE and does not call the Flush method, the server will honor Keep-Alive requests made by the client. This saves time because the server does not have to create a new connection for each client request.

However, buffering prevents any of the response from being displayed to the client until the server has finished all script processing for the current page. For long scripts, this may cause a perceptible delay.

You can use the ASPBufferingOn property in the metabase to set the default value for script buffering. For more information about using the metabase see Introduction to the IIS Metabase.

Request Object

The Request object retrieves the values that the client browser passed to the server during an HTTP request.

Syntax

Request[.collection|property|method](variable)

Form

The Form collection retrieves the values of form elements posted to the HTTP request body by a form using the POST method.

Syntax

Request.Form(element)[(index)|.Count]

Parameters

element: Specifies the name of the form element from which the collection is to retrieve values.
index: An optional parameter that enables you to access one of multiple values for a parameter. It can be any integer in the range 1 to Request.Form(parameter).Count.

Remarks

The Form collection is indexed by the names of the parameters in the request body. The value of Request.Form(element) is an array of all of the values of element that occur in the request body. You can determine the number of values of a parameter by calling Request.Form(element).Count. If a parameter does not have multiple values associated with it, the count is 1. If the parameter is not found, the count is 0.

To reference a single value of a form element that has multiple values, you must specify a value for index. The index parameter may be any number between 1 and Request.Form(element).Count. If you reference one of multiple form parameters without specifying a value for index, the data is returned as a comma-delimited string.

When you use parameters with Request.Form, the Web server parses the HTTP request body and returns the specified data. If your application requires unparsed data from the form, you can access it by calling Request.Form without any parameters.

You can iterate through all the data values in a form request. For example, if a user filled out a form by specifying two values, Chocolate and Butterscotch, for the FavoriteFlavor element, you could retrieve those values by using the following script.

<%
  For i = 1 To Request.Form("FavoriteFlavor").Count
    Response.Write Request.Form("FavoriteFlavor")(i) & "<BR>"
  Next
%>

The preceding script would display the following.

Chocolate
Butterscotch

You can use this technique to display the parameter name, as shown in the following script.

<% 
  For i = 1 to Request.Form("FavoriteFlavor").count %>
    Request.Form(FavoriteFlavor) = <%= Request.Form("FavoriteFlavor")(i)_
    %> <BR>
<% Next %>

This script displays the following on the browser.

Request.Form(FavoriteFlavor) = Chocolate
Request.Form(FavoriteFlavor) = Butterscotch

Example

Consider the following form:

<FORM ACTION = "/scripts/submit.asp" METHOD = "post">
<P>Your first name: <INPUT NAME = "firstname" SIZE = 48>
<P>What is your favorite ice cream flavor: <SELECT NAME = "flavor">
<OPTION>Vanilla 
<OPTION>Strawberry 
<OPTION>Chocolate 
<OPTION>Rocky Road</SELECT>
<P><INPUT TYPE = SUBMIT>
</FORM>

From that form, the following request body might be sent:

firstname=James&flavor=Rocky+Road

The following script can then be used:

Welcome,  <%= Request.Form("firstname") %>. 
Your favorite flavor is <%= Request.Form("flavor") %>.

The following output is the result:

Welcome, James. Your favorite flavor is Rocky Road.

If the following script is used:

The unparsed form data is:  <%= Request.Form %>

the output would be:

The unparsed form data is:  firstname=James&flavor=Rocky+Road

Note If your form includes multiple select objects with the same name, the item in the form collection will be a comma delimited list of all the selected values.

QueryString

The QueryString collection retrieves the values of the variables in the HTTP query string. The HTTP query string is specified by the values following the question mark (?). Several different processes can generate a query string. For example, the anchor tag

<A HREF= "example?string=this is a sample">string sample</A>

generates a variable named string with the value "this is a sample." Query strings are also generated by sending a form, or by a user typing a query into the address box of their browser.

Syntax

Request.QueryString(variable)[(index)|.Count]

Parameters

variable: Specifies the name of the variable in the HTTP query string to retrieve.
index: An optional parameter that enables you to retrieve one of multiple values for variable. It can be any integer value in the range 1 to Request.QueryString(variable).Count.

Remarks

The QueryString collection is a parsed version of the QUERY_STRING variable in the ServerVariables collection. It enables you to retrieve the QUERY_STRING variables by name. The value of Request.QueryString(parameter) is an array of all of the values of parameter that occur in QUERY_STRING. You can determine the number of values of a parameter by calling Request.QueryString(parameter).Count. If a variable does not have multiple data sets associated with it, the count is 1. If the variable is not found, the count is 0.

To reference a QueryString variable in one of multiple data sets, you specify a value for index. The index parameter may be any value between 1 and Request.QueryString(variable).Count. If you reference one of multiple QueryString variables without specifying a value for index, the data is returned as a comma-delimited string.

When you use parameters with Request.QueryString, the server parses the parameters sent to the request and returns the specified data. If your application requires unparsed QueryString data, you can retrieve it by calling Request.QueryString without any parameters.

You can use an iterator to loop through all the data values in a query string. For example, if the following request is sent

http://localhost/script/directory/NAMES.ASP?Q=Fred&Q=Sally

and Names.asp contained the following script,

---NAMES.ASP---
<%
  For Each item In Request.QueryString("Q")
    Response.Write Request.QueryString(“Q”)(item) & "<BR>"
  Next
%>

Names.asp would display the following:

Fred
Sally

The preceding script could also have been written using Count.

<%
  For i = 1 To Request.QueryString("Q").Count   
    Response.Write Request.QueryString("Q")(i) & "<BR>"
  Next
%>

Example

The client request

/scripts/directory-lookup.asp?name=fred&age=22

results in the following QUERY_STRING value:

name=fred&age=22.

The QueryString collection would then contain two members, name and age. You can then use the following script:

Welcome,  <%= Request.QueryString("name") %>. 
Your age is  <%= Request.QueryString("age") %>.

The output would be

Welcome, Fred. Your age is 22.

If the following script is used:

The unparsed query string is:  <%=Request.QueryString %>

The output would be

The unparsed query string is: name=fred&age=22

ServerVariables

The ServerVariables collection retrieves the values of predetermined environment variables.

Syntax

Request.ServerVariables (server environment variable)

Parameters

server environment variable: Specifies the name of the server environment variable to retrieve. (Use a text on web server variables to find a list of the variables)

Session Object

You can use the Session object to store information needed for a particular user-session. 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.

The Web server automatically creates a Session object when a Web page from the application is requested by a user who does not already have a session. The server destroys the Session object when the session expires or is abandoned.

One common use for the Session object is to store user preferences. For example, if a user indicates that they prefer not to view graphics, you could store that information in the Session object. For more information on using the Session object, see Managing Sessions in the ASP Applications section.

Note Session state is only maintained for browsers that support cookies.

Syntax

Session.collection|property|method

Abandon

The Abandon method destroys all the objects stored in a Session object and releases their resources. If you do not call the Abandon method explicitly, the server destroys these objects when the session times out.

Syntax

Session.Abandon

Remarks

When the Abandon method is called, the current Session object is queued for deletion, but is not actually deleted until all of the script commands on the current page have been processed. This means that you can access variables stored in the Session object on the same page as the call to Abandon, but not in any subsequent Web pages.

For example, in the following script, the third line prints the value Mary. This is because the Session object is not destroyed until the server has finished processing the script.

<%
  Session.Abandon 
  Session("MyName") = "Mary"
  Reponse.Write(Session("MyName"))
%>

If you access the variable MyName on a subsequent Web page, it is empty. This is because MyName was destroyed with previous Session object when the page containing the above example finished processing.

The server creates a new Session object when you open a subsequent Web page after abandoning a session. You can store variables and objects in this new Session object.

Example

The following example causes the session state to be released when the server finishes processing the current page.

<% Session.Abandon %>

Timeout

The Timeout property specifies the timeout period assigned to the Session object for this application, in minutes. If the user does not refresh or request a page within the timeout period, the session ends.

Syntax

Session.Timeout [ = nMinutes]

Parameters

nMinutes: Specifies the number of minutes that a session can remain idle before the server terminates it automatically. The default is 10 minutes.

Session Contents Collection

The Session.Contents collection contains all of the items that have been established for a session without using the <OBJECT> tag. The collection can be used to determine the value of a specific session item, or to iterate through the collection and retrieve a list of all items in the session.

Syntax

Session.Contents( Key )

Parameters

Key: The name of the property to retrieve.

Remarks

You can use an iterating control structure to loop through the keys of the Contents collection. This is demonstrated in the following example.

<%@ LANGUAGE="VBSCRIPT" %>
<%
  Dim sessitem
  Dim anArray(2)
  response.write "SessionID: " & Session.SessionID & "<P>"

  anArray(0)="one"
  anArray(1)="second"
  anArray(2)="third"
  Session("anArray")=anArray
  Session("scalar")="1234567890ABCDEFG"

  set objConn=server.createobject("adodb.connection")
  set Session("object")=objConn

  response.write "List of " & Session.Contents.Count & " items in Session
  contents collection:<HR>"
  For Each sessitem in Session.Contents
    If IsObject(Session.Contents(sessitem)) Then
      Response.write(sessitem & " : Session object cannot be displayed." & "<BR>")
    Else
      If IsArray(Session.Contents(sessitem)) Then
         Response.write "Array named " & Session.Content(sessitem) & "<ol>"
         For each objArray in Session.Contents(sessitem)
             Response.write "<li>" & _
             Session.Contents(sessitem)(objArray)& "<BR>"
         Next
             Response.write "</ol>"
      Else
             Response.write(sessitem & " : " & Session.Contents(sessitem) & "<BR>")
       End If
    End If
  Next 
%>

SessionID

The SessionID property returns the session identifier. Each session has a unique identifier that is generated by the server when the session is created. The session ID is returned as a LONG data type.

Syntax

Session.SessionID

Server Object

The Server object provides access to methods and properties on the server. Most of these methods and properties serve as utility functions.

Syntax

Server.property|method

CreateObject

The CreateObject method creates an instance of a server component. If the component has implemented the OnStartPage and OnEndPage methods, the OnStartPage method is called at this time. For more information about server components, see Installable Components for ASP.

Syntax

Server.CreateObject( progID )

Parameters

progID: Specifies the type of object to create. The format for progID is [Vendor.]Component[.Version].

Remarks

By default, objects created by the Server.CreateObject method have page scope. This means that they are automatically destroyed by the server when it finishes processing the current ASP page.

To create an object with session or application scope, you can either use the <OBJECT> tag in the Global.asa file and set the SCOPE attribute to SESSION or APPLICATION, or store the object in a session or application variable.

For example, an object stored in a session variable, as shown in the following script, is destroyed when the Session object is destroyed. That is, when the session times out, or the Abandon method is called.

<% Set Session("ad") = Server.CreateObject("MSWC.AdRotator")%>

You can also destroy the object by setting the variable to Nothing or setting the variable to a new value, as shown below. The first example releases the object ad. The second replaces ad with a string.

<% Session("ad") = Nothing %>
<% Session("ad") = "some other value" %>

You cannot create an object instance with the same name as a built-in object. For example, the following returns an error.

<% Set Response = Server.CreateObject("Response") %>

Example

<% Set MyAd = Server.CreateObject("MSWC.AdRotator") %>

The preceding example creates a server component, MyAd, as a MSWC.AdRotator component that can be used to automate rotation of advertisements on a Web page.

MapPath

The MapPath method maps the specified relative or virtual path to the corresponding physical directory on the server.

Syntax

Server.MapPath( Path )

Parameters

Path: Specifies the relative or virtual path to map to a physical directory. If Path starts with either a forward (/) or backward slash (\), the MapPath method returns a path as if Path is a full virtual path. If Path doesn't start with a slash, the MapPath method returns a path relative to the directory of the .asp file being processed.

Remarks

The MapPath method does not check whether the path it returns is valid or exists on the server.

Because the MapPath method maps a path regardless of whether the specified directories currently exist, you can use the MapPath method to map a path to a physical directory structure, and then pass that path to a component that creates the specified directory or file on the server.

You can use the relative path syntax for the Path parameter if the AspEnableParentPaths property is set to TRUE (which is the default value). If you are concerned about allowing scripts to access the physical directory structure, you can disable this feature by setting the AspEnableParentPaths property to FALSE. You can accomplish this with either the Internet Information Services snap-in or with a script.

Example

For the examples below, the file data.txt is located in the directory, C:\Inetpub\Wwwroot\Script, as is the test.asp file that contains the following scripts. The C:\Inetpub\Wwwroot directory is set as the server's home directory.

The following example uses the server variable PATH_INFO to map the physical path of the current file. The following script

<%= server.mappath(Request.ServerVariables("PATH_INFO"))%><BR>

produces the output

c:\inetpub\wwwroot\script\test.asp<BR>

Because the path parameters in the following examples do not start with a slash character, they are mapped relative to the current directory, in this case C:\Inetpub\Wwwroot\Script. The following scripts

<%= server.mappath("data.txt")%><BR>
<%= server.mappath("script/data.txt")%><BR>

produce the following output

c:\inetpub\wwwroot\script\data.txt<BR>
c:\inetpub\wwwroot\script\script\data.txt<BR>

The next two examples use the slash characters to specify that the path returned should be looked up as complete virtual paths on the server. The following scripts

<%= server.mappath("/script/data.txt")%><BR>
<%= server.mappath("\script")%><BR>

produce the following output

c:\inetpub\wwwroot\script\data.txt<BR>
c:\inetpub\wwwroot\script<BR>

The following examples demonstrate how you can use either a forward slash (/) or a backslash (\) to return the physical path to the home directory. The following scripts

<%= server.mappath("/")%><BR>
<%= server.mappath("\")%><BR>

produce the following output

c:\inetpub\wwwroot<BR>
c:\inetpub\wwwroot<BR>

Application Object

You can use the Application object 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. Because the Application object can be shared by more than one user, there are Lock and Unlock methods to ensure that multiple users do not try to alter a property simultaneously.

Syntax

Application.method

Lock

The Lock method blocks other clients from modifying the variables stored in the Application object, ensuring that only one client at a time can alter or access the Application variables. If you do not call the Unlock method explicitly, the server unlocks the locked Application object when the .asp file ends or times out.

Syntax

Application.Lock

Unlock

The Unlock method enables other clients to modify the variables stored in the Application object after it has been locked using the Lock method. If you do not call this method explicitly, the Web server unlocks the Application object when the .asp file ends or times out.

Syntax

Application.Unlock