Active Server Pages Object Model

Although VBScript is a powerful, flexible scripting language when used to develop ASP applications, you can do relatively little with VBScript by itself. That is, most of the power and efficiency of ASP becomes available only when you use VBScript to access the Active Server Pages object model. In an ASP application, each of the objects in the ASP object model is globally available throughout your script; you don't have to do anything special to instantiate ASP objects.

ASP includes six intrinsic objects, each of which are detailed in the following:

Application

An object whose collections and property values are shared across all instances of the application. (An ASP application, once again, is the entire set of files that can be accessed in a virtual directory and its subdirectories.) The Application object supports the members listing in Table 5-1.

Table 5-1. Members of the Application object

Name

Description

Contents Collection

Contains all application-scoped variables and objects added by script.

Lock Method

Locks the Contents collection, preventing other instances from accessing it until it is unlocked. Its syntax is Application.Lock( ).

OnEnd Event

Fired when the last user session ends.

OnStart Event

Fired when the first user session starts.

StaticObjects Collection

Contains all application-scoped variables added by the tag.

Unlock Method

Unlocks the Contents collection so that other instances can access it. Its syntax is Application.Unlock( ).

The Contents and StaticObjects collections have the members shown in Table 5-2.

Table 5-2. Members of the Application object's Contents collections

Name

Description

Count Property

Indicates the number of members in the collection.

Item Property

Retrieves a member by its ordinal position in the collection or its name. Its syntax is oCollec.Item(index) where index is the one-based position of the member in the collection or its name.

Key Property

Returns the name of a particular element in the collection that's found at a specified ordinal position. Its syntax is oCollec.Key(index) where index is the one-based position of the member in the collection.

Remove Method

Removes a designated member from the Contents collection; it is not supported for the StaticObjects collection. Its syntax is oCollec.Key(index) where index is the one-based position of the member in the collection or its name. Available in IIS 5.0 only.

RemoveAll Method

Removes all the members from the Contents collection; it is not supported for the StaticObjects collection. Available in IIS 5.0 only.

ObjectContext

An object that provides transactional support to scripts. TheObjectContext object supports the members listed in Table 5-3 from a scripted page.

Table 5-3. Members of the ObjectContext object

Name

Description

OnTransactionAbort Event

Fired when a transaction is aborted.

OnTransactionCommit Event

Fired when a transaction is committed.

SetAbort Method

Indicates the transaction cannot complete and changes should be rolled back. Its syntax is ObjectContext.SetAbort( ).

SetComplete Method

Indicates that from the viewpoint of the script, the transaction has completed successfully. If all other components participating in the transaction also call SetComplete, the transaction can be committed. Its syntax is ObjectContext.SetComplete( ).

Request

Gives you access to the client's HTTP request header and body, as well as to some information about the server handling the request. The members of the Request object are listed in Table 5-4. All collections are read-only. TheRequest object also maintains a sort of "super-collection" that allows you to search for any members of the QueryString, Form, Cookies, ClientCertificate, and ServerVariables collections using the syntax:

vValue = Request("name")

Table 5-4. Members of the Request object

Name

Description

BinaryRead Method

Returns a SAFEARRAY structure containing data retrieved from the client. This method is primarily for C/C++ programmers.

ClientCertificate Collection

Contains the fields stored in the client certificate that is sent in the HTTP request, if there is one.

Cookies Collection

Contains the cookies sent in the HTTP request.

Form Collection

Contains form elements sent in the HTTP request body.

QueryString Collection

Contains the values of variables sent in the HTTP query string.

ServerVariables Collection

Contains predefined environment variables and their values.

TotalBytes Property

Indicates the total number of bytes sent by the client in the body of the request; read-only.

The collections of the Request object support the members shown in Table 5-5.

Table 5-5. Members of the Request object's collections

Name

Description

Count Property

A read-only property that returns the total number of members in the collection. The property is not available for the ClientCertificate collection, whose members are predefined.

Item Property

A read-only property that returns the value of a specific element in the collection. Its syntax is oCollec.Item(Index) where Index can be either the one-based ordinal position of the item in the collection or its key.

Key Property

A read-only property that returns the name or key value of a specific element in the collection. Its syntax is oCollec.Item(Index) where Index is the one-based ordinal position in the collection of the key whose name you want to retrieve.

Retrieving and then outputting raw user input from the Request object's Form and QueryString collections leaves a site open to cross-site security scripting attacks. For details on what these security holes are and how to avoid them, see an article written by Michael Howard at http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dncode/html/secure07152002.asp.

Response

Allows you to control the output sent back to the requestor. TheResponse object's members are shown in Table 5-6.

Table 5-6. Members of the Response object

Name

Description

AddHeader Method

Adds a custom HTTP response header and its corresponding value to the HTTP output stream. Its syntax is Response.AddHeader strName, strValue where strName is the name of the response header and strValue is its value.

AppendToLog Method

Adds a string to the server's log entry for the current client request. Its syntax is Response.AppendToLog strLogEntry where strLogEntry is a string of up to 80 characters without commas that will be appended to the log.

BinaryWrite Method

Writes information directly to the response body without any character conversion. Its syntax is Request.BinaryWrite arbyteData where arbyteData is an array containing the binary bytes to be written.

Buffer Property

Determines whether script output is included in the HTML stream all at once (Buffer = True) or a line at a time (Buffer = False).

CacheControl Property

A string value that determines whether proxy servers serving your pages can cache your page. If set to "Public," pages can be cached; if set to "Private," pages cannot be cached.

Charset Property

Specifies a character set for the HTTP response content. The default character set is ISO-LATIN.

Clear Method

Clears any part of the response body that's been written to the output buffer. Its syntax is Response.Clear. The use of this method requires that the Buffer property of the Response object be set to True.

ContentType Property

Defines the value of the Content-Type in the HTTP response header, which determines the type of data sent in the response body. The default value of the ContentType property is "Text/HTML."

Cookies Collection

Defines or accesses cookies to be written to the client machine. It has the same members as the Cookies collection of the Request object, except the Item property can be used to add a cookie to the collection as well as to retrieve an existing cookie.

End Method

Closes the output buffer, sends its contents to the client, and stops the web server from processing additional code. Its syntax is Response.End.

Expires Property

Specifies the number of minutes that the client may cache the current page.

ExpiresAbsolute Property

Provides a date and time after which the content of the current page should no longer be cached by the client.

Flush Method

Immediately sends all content in the output buffer to the client. Its syntax is Response.Flush.

IsClientConnected Property

A read-only property that indicates whether the client is still connected to the server (its value is True) or not (its value is False).

PICS Property

Provides a PICS (Platform for Internet Content Selection) label to the HTTP response header.

Redirect Method

Redirects the client's request to another URL. Its syntax is Response.Redirect strURL where strURL is the URL of the resource to which the client will be redirected.

Status Property

Defines the HTTP status line that is returned to the client. Its default value is "200 OK."

Write Method

Writes information directly to the HTTP response body. Its syntax is Response.Write strData where strData is the data to be written to the output stream.

Server

Provides miscellaneous functionality, including the ability to instantiate ActiveX components and to get any information from the server necessary for properly handling your application. TheServer object has the members listed in Table 5-7.

Table 5-7. Members of the Server object

Name

Description

CreateObject Method

Instantiates an object on the server. Its syntax is Set obj = Server.CreateObject(strProgID) where strProgID is the programmatic identifier of the object to be instantiated, as defined in the system registry.

You should use the Server object's CreateObject method to instantiate an external component (like ADO, CDO, or one of the custom components included with IIS) rather than calling the VBScript CreateObject function.

Execute Method

Calls an .asp file and processes it as if it were part of the calling script. Its syntax is Server.Execute strPath where strPath is the location of the .asp file to execute. Available with IIS 5.0 and later.

GetLastError Method

Returns an ASPError object providing information about the last error. Its syntax is Server.GetLastError( ). The method (as well as the ASPError object) is new to IIS 5.0.

The ASPError object itself has the following members:

ASPCode

Returns the error code generated by IIS.

ASPDescription

For ASP-related errors, returns a longer description of the error than that provided by the Description property.

Category

Returns a string indicating whether the source of the error was IIS, the scripting language, or a component.

Column

Indicates the column within the .asp file that generated the error.

Description

Returns a short description of the error.

File

Returns the name of the .asp file that was being processed when the error occurred.

Line

Indicates the line within the .asp file that generated the error.

Number

Returns a standard COM error code.

Source

If available, returns the source code on the line containing the error.

HTMLEncode Method

Sends the actual HTML source to the output stream. Its syntax is Server.HTMLEncode strHTMLString where strHTMLString is the string whose HTML code is to be displayed on the client.

MapPath Method

Returns the physical path on the server that corresponds to a virtual or relative path. Its syntax is Server.MapPath strPath where strPath is a complete virtual path or a path relative to the current script's directory.

ScriptTimeout Property

Defines the maximum number of seconds that the web server will continue processing a script. Its default value is 90 seconds.

Transfer Method

Sends all of the information available to one .asp fileits Application and Session objects and variables as well as all information from the client requestto a second .asp file for processing. Its syntax is Server.Transfer strPath where strPath is the path and name of the .asp file to which control is to be transferred. New to IIS 5.0.

URLEncode Method

Applies URL encoding to a string so that it can be sent as a query string. Its syntax is Server.URLEncode strURL where strURL is the string to be encoded.

Session

A Session is created for every visitor to your web site. You can use this object to store Session-specific information and to retain "state" throughout the client session. The Session object has the members listed in Table 5-8.

Table 5-8. Members of the Session object

Name

Description

Abandon Method

Releases the memory used by the web server to maintain information about a given user session. Its syntax is Session.Abandon.

CodePage Property

Sets or retrieves the code page that the web server uses to display content in the current page.

Contents Collection

Contains all session-scoped variables and objects added by script.

LCID Property

Sets or returns a valid local identifier that the web server uses to display content to the client.

OnEnd Event

Fired when the user session ends.

OnStart Event

Fired when the new user session starts.

SessionID Property

A read-only value of type Long that uniquely identifies each current user session.

StaticObjects Collection

Contains all session-scoped variables and objects added by the tag.

TimeOut Property

A Long that defines the number of minutes the web server will maintain a user's session without the user requesting or refreshing a page. Its default value is 20 minutes.

The Session object's Contents and StaticObjects collections have the members listed in Table 5-9.

Table 5-9. Members of the Session objects Contents and StaticObjects collections

Name

Description

Count Property

Indicates the number of members in the collection.

Item Property

Retrieves a member by its ordinal position in the collection or its name. Its syntax is oCollec.Item(index) where index is the one-based position of the member in the collection or its name.

Key Property

Returns the name of a particular element in the collection that's found at a specified ordinal position. Its syntax is oCollec.Key(index) where index is the one-based position of the member in the collection.

Remove Method

Removes a designated member from the Contents collection; it is not supported for the StaticObjects collection. Its syntax is oCollec.Key(index) where index is the one-based position of the member in the collection or its name. Available in IIS 5.0 only.

RemoveAll Method

Removes all the members from the Contents collection; it is not supported for the StaticObjects collection. Available in IIS 5.0 only.

For more detailed information about the ASP Object Model, refer to ASP in a Nutshell, Second Edition, by A. Keyton Weissinger (O'Reilly).

Part I: The Basics

Introduction

Program Structure

Data Types and Variables

Error Handling and Debugging

VBScript with Active Server Pages

Programming Outlook Forms

Windows Script Host 5.6

VBScript with Internet Explorer

Windows Script Components

Part II: Reference

Part III: Appendixes

Appendix A. Language Elements by Category

Appendix B. VBScript Constants

Appendix C. Operators

Appendix E. The Script Encoder



Vbscript in a Nutshell
VBScript in a Nutshell, 2nd Edition
ISBN: 0596004885
EAN: 2147483647
Year: 2003
Pages: 335

Flylib.com © 2008-2020.
If you may any questions please contact us: flylib@qtcs.net