Page #20 (Chapter 2 - IIS Applications)

	Chapter 2 - IIS Applications
	Visual Basic Developers Guide to ASP and IIS
	A. Russell Jones

Copyright 1999 SYBEX Inc.

---

	ASP Object Model

	The ASP object model has changed very little since version 1. The version described here and that you'll work with in this book is ASP 3, but almost everything in the book will work with version 2. For those of you already familiar with ASP 1, the only significant object model changes are that the Application and Session objects expose a Contents property and that ASP now exposes a ScriptingContext object. The Contents property can be helpful when you need a list of the items stored in the Application or Session objects. Until now, you had to maintain that list yourself.

	There are six objects in the ASP type library:

	•		Server

	•		Application

	•		Session

	•		Request

	•		Response

	•		ScriptingContext

	Each is described in the following sections.

	Server Object

	There's only one Server object for a Web server. All the applications share a single Application object. In an ASP page, you use the Server object to create other object instances—this is equivalent to the Visual Basic command Set myObject = new someObject. The Server object also contains methods and properties to map virtual Web paths to physical paths. In other words, if your Web application is located in the myWeb virtual directory, you can find out where the files for myWeb are physically located. The Server object can also encode and decode string information for transmission to or from the HTTP protocol.

	Table 2.1 lists the Server object's properties and methods.

	Table 2.1: The Server Object

	Name

Description

	CreateObject method

Returns an object instance. The following example creates a Dictionary object:

Dim d

Set d = Server.CreateObject("Scripting.Dictionary")

The Server.CreateObject method is equivalent to the following Visual Basic code:

Dim d as Dictionary

Set d = new Dictionary

You would normally use the CreateObject method only from an ASP page. From VB, use the standard syntax to create a new instance of an object.

	MapPath method

Returns the physical path corresponding to the virtual path parameter. Example:

MyPhysicalPath = Server.MapPath(myVirtualPath)

You use this function to find physical file locations when you know only the virtual path (the URL) for the file. You need physical paths to read and write files.

	HTMLEncode method

Encodes the string parameter in a manner suitable for transmission over HTTP.

	URLEncode method

Encodes a string so that the server can transmit it via Transmission Control Protocol/Internet Protocol (TCP/IP) as a valid URL. URL encoding involves replacing non-text and numeric characters with a percent sign and the hex ASCII value of the character. For example, a space (ASCII 32) is equivalent to %20 (hex 32). You need to use this method to build valid URL strings.

	ScriptTimeout property

Sets or returns an integer value that specifies the number of seconds the server should wait for a specific request to finish executing before it returns a timed out message to the requesting browser.

	Application Object

	There's one Application object for each Web application. An application, to the ASP engine, is the set of all files and subdirectories within a directory that contains a file called global.asa. The .asa extension stands for Active Server Application. The Application object is a container object that can hold other values. In fact, although it's not a Dictionary object, it's easiest to think of the Application object as a Dictionary. Dictionaries, like Visual Basic collections, are lists of key-value pairs.

	The name for such pairs is associations. The association key is a string value, but the value associated with each key is a variant; therefore, each key can be associated with a value of any variant subtype, including Object and Nothing. You can use the Application object in the same way that you normally use global variables in your application. Tempting as it is, don't use the Application object to store anything except simple data types and arrays. You can't store apartment-threaded objects in the Application object, and there are good reasons not to store anything there if you don't have to. Table 2.2 lists the Application object's properties, collections, methods, and events.

	Table 2.2: The Application Object

	Name

Description

	Contents collection

Returns a collection of key-value associations. Because this is a collection, it also supports the For Each…Next syntax, the Count and Item properties, and the Remove method.

	Lock method

Locks the Application object, restricting access to it so that only the current session can use the object. Obviously, you want to minimize the time that any given session locks the Application object. To release the lock, use the Application.Unlock method. If you don't release the lock, the ASP engine releases it when the current page ends.

	Unlock method

Unlocks the Application object, freeing it for use by another session.

	OnEnd event

Occurs when the last session for a Web application either times out or is abandoned (see Session.Timeout and/or Session.Abandon in the following section). You can write code to perform application cleanup in the Application_OnEnd event procedure in the global.asa file.

	OnStart event

Occurs the first time that any user requests any page in your application. You can write code to perform Application-level variable initializations in the Application_OnStart event procedure in the global.asa file.

	StaticObjects collection

Returns a collection of all the objects created with <object> tags that have been stored in the Application object. Like other collections, it has a Count property and an Item property. You can also use For Each to iterate through the collection. This is a read-only property.

	Session Object

	Each application may have many sessions, one for each user accessing the application. The Session object is a container object like the Application object. It's also similar to a Dictionary object, with keys and values. The biggest difference is that each user gets a unique Session object, whereas all users of the application share the Application object. Table 2.3 lists the Session object's properties, collections, methods, and events.

	Table 2.3: The Session Object

	Name

Description

	Contents collection

Returns a collection of key-value associations. Because this is a collection, it also supports the For Each…Next syntax, the Count and Item properties, and the Remove method.

	SessionID property

Returns the ID for the current session. The SessionID is a pseudo-random identifier that is generated automatically by the ASP engine the first time a user requests any page in the application. This is a read-only property.

	Timeout property

Sets or returns an integer value that specifies the number of minutes before a session will expire if no activity occurs.

	Abandon method

Forces the current session to expire when the current page finishes executing.

	OnEnd event

Occurs when a session times out or is abandoned. You can write code to perform end-of-session cleanup in the Session_OnEnd event procedure in the global.asa file. If the current session is the only active session, this event fires immediately before the Application_OnEnd event.

	OnStart event

This event occurs the first time that any user requests any page in your application. You can write code to perform Application-level variable initializations in the Session_OnStart event procedure in the global.asa file. If the current session is the first active session in the application, this event fires immediately after the Application_OnStart event.

	StaticObjects collection

A collection of all the objects created with <object> tags that have been stored in the Session object. Like other collections, it has a Count property and an Item property. You can also use For Each to iterate through the collection.

	CodePage property

Sets or returns the CodePage used for representing characters.

	LCID property

Sets or returns the LocaleID setting for the client machine.

What's a Session?

	At this point, it may be useful to explain what a session is. Unfortunately, this is more complicated than it should be. A session begins when a user requests any file in your Web application and that user's browser does not send a valid ASP-generated SessionID cookie for that site. That's confusing, I know, but bear with me; I'll explain it shortly.

	As soon as the ASP engine sees a request from a browser without a valid SessionID cookie, it creates a new Session object, generates a pseudo-random SessionID value, and sets the cookie. On all subsequent requests from that browser, the ASP engine reads the SessionID cookie and uses the value to match the Session object it generated on the first request to this request. That's how ASP manages to store information about a specific user between page requests.

	If the user's browser refuses the cookie (either the browser doesn't support cookies, or the user has opted to refuse them), the ASP SessionID cannot be stored in the browser, and the user will not have a valid Session object.

	Note that the request created a Session object although the server can't use that Session object to save data between requests.

	Because of the missing cookie value, the ASP engine won't be able to connect subsequent requests to the Session object. When the user's browser refuses the cookie, the ASP engine will create a brand new Session object for each request. Therefore, you can still use the Session object to store values when the user refuses cookies, but you will lose the values after the page is complete. Although you can code around the cookie problem, most ASP sites don't work as intended if the user's browser refuses the cookie.

	Note		Cookies are key-value pairs stored on the client computer, either in memory (transient cookies) or on disk (permanent cookies).

	Request Object

	Browsers send a good deal of information to the server for each page request. You don't normally see any of this "header" information when you're browsing a site, but it is available at the server for applications to use. The ASP engine packages this information nicely in an object called the Request object. The Request object contains all this header information as well as information about the specific page request and any form information submitted by a user. You can retrieve the information through the properties and collections of the Request object. Table 2.4 lists the Request object's properties, collections, and methods.

	Table 2.4: The Request Object

	Name

Description

	BinaryRead method

Reads binary information from submitted form data.

	ClientCertificate collection

Returns a collection of client security certificates. You can use this to provide secure services.

	Cookies collection

Returns a collection of cookies sent by the client. The Request.Cookies collection is read-only. To set, alter, or remove a cookie from the collection, use the Response.Cookies collection instead.

	Form collection

Returns a collection of form key-value associations sent by the client browser. The collection contains information from the input controls enclosed in a <form> tag. The keys are the names or IDs of the controls; the values are the contents. You'll see more about this in Chapter 3, "Building ASP Applications."

	QueryString collection

Returns a collection of key-value associations from the URL sent by the client browser. For example, if the client browser navigates to the URL myFile.asp?Action=1&Total=2, there would be two values in the QueryString collection:

Action=1

Total=2

	ServerVariables collection

Returns a collection of header key-value associations sent by the client browser. These variables are sent regardless of the method (Post or Get) used to request the page. This is a read-only property.

	TotalBytes property

Contains the size of the client form data, in bytes, when the client sends information to the Web server via the Post method. This value is empty when the request method is Get. This is a read-only property.

	Response Object

	You use the methods of the Response object to send a response to the client browser. The Response object is your primary way to communicate with the client. Table 2.5 lists the object's properties, collections, and methods.

	Table 2.5: The Response Object

	Name

Description

	AddHeader method

Adds an HTTP header value to the page.

	AppendToLog method

Logs a message to the Internet server log file.

	BinaryWrite method

Writes binary information (information that should not be HTTP encoded) to the client browser.

	Buffer property

As you process a request, you can either begin returning information immediately, or you can buffer the information and begin returning it only after you have completed processing the request. In practice, you will usually buffer the information; otherwise, you cannot add headers or redirect after processing begins. The Buffer property sets or returns whether the Response object will buffer information. You can set it to True or False.

	CacheControl property

Controls how a client proxy server caches the page. The default value is False. Setting the value to True enables proxy servers to cache the page, which can improve the response time for ASP pages on which the information rarely changes.

	Charset property

Controls which character set the browser will use to display information on the client browser.

	Clear method

Clears all the information from the response buffer.

	ContentType property

Lets you control the contents of the MIME-type header sent to the client browser.

	End method

Ends processing immediately. The server will send any buffered information to the client browser.

	Expires property

Controls how long the information you send to the client remains valid before the client must return to the server to refresh the page. You specify the interval in minutes. A value of 0 tells the browser that the page expires immediately.

	Cookies collection

Provides access to the browser's cookie collection for this site. You can add and delete cookies from the collection by using the Append and Remove methods.

	ExpiresAbsolute property

The Expires property lets you set the number of minutes until the content in a page is no longer valid. In contrast, the ExpiresAbsolute property lets you set a specific date and time when the information will become invalid.

	Flush method

Sends the contents of the response buffer immediately.

	IsClientConnected property

Lets you find out whether a specific SessionID is currently connected. Note that this is not a way to determine whether the client browser is still using your program, only whether it is currently requesting a page.

	PICS property

Adds an HTTP header value containing a Platform for Internet Content Selection (PICS) label. The PICS label contains a rating for the page. Using this system, parents can determine the levels of content that their children can see. For more information, see the PICS specification on the W3C Web site: http://www.w3.org.

	Redirect method

Sends a redirect header to the client browser specifying a page to which the browser should navigate. When the browser receives a redirect header, it immediately requests the specified page from the server.

	Status property

Sets the value of the status line returned by the server. You've probably seen this one before: 404 Not Found. You set the Status property to return a specific number and explanation to the browser.

	Write method

You'll use this method most often. The Response.Write method sends string information to the browser. If buffering is on, the method appends new string information to the string that the server will return.

	ScriptingContext Object

	This is a wrapper object that enables an external ActiveX object to obtain references to the other ASP objects. VB 6 WebClasses provide these references automatically, so the ScriptingContext object is not important. The preferred method for gaining references to the ASP objects from external ActiveX objects is to get a reference to the ObjectContext object by calling the getObjectContext method.

	The ScriptingContext object provides a "wrapper" that encloses all the other ASP objects in a single object that can be passed as a parameter. When a page containing ActiveX object references starts, the ASP engine calls the OnStartPage method for each ActiveX object on the page with a ScriptingContext object as a parameter. The ActiveX objects use the ScriptingContext parameter to gain reference pointers to the Server, Application, Session, Request, and Response objects. Following is a list of the ScriptingContext object properties:

	•		Server

	•		Application

	•		Session

	•		Request

	•		Response

	These five properties return reference pointers to the ASP objects.

	Warning		Microsoft recommends that you use the getObjectContext method rather than the ScriptingContext object. Although the ScriptingContext object still exists for backward compatibility reasons, it is obsolete, and you should no longer use it.

	ObjectContext Object

	The ObjectContext object is the communications channel to Microsoft Transaction Server (MTS). Through MTS, you can let ActiveX objects participate in transactions initiated by an ASP page. You can also gain references to the other ASP objects through the ObjectContext object. You'll see more information about this object in Chapter 11, "Using ActiveX DLLs from WebClasses," when you create ActiveX DLLs for use with ASP pages and WebClasses. The ObjectContext object has no properties. Table 2.6 lists its methods and events.

	Table 2.6: The ObjectContext Object

	Name

Description

	SetComplete method

Calling the SetComplete method tells MTS that, as far as the calling component is concerned, the transaction was a success. MTS declares the transaction successful only when all the participating components call SetComplete.

	SetAbort method

Calling the SetAbort method tells MTS that the transaction was unsuccessful. MTS declares the transaction unsuccessful if any participating component calls SetAbort.

	OnTransactionCommit event

MTS raises the OnTransactionCommit event only if the transaction was successful. You can write code in an OnTransactionCommit subroutine to perform specific actions if the transaction is successful.

	OnTransactionAbort event

MTS raises the OnTransactionAbort method only if the transaction was unsuccessful. You can write code in an OnTransactionAbort subroutine to perform specific actions if the transaction fails.