ASP Programmer's Reference

The Server Object

In this short chapter we will move on to cover the Server object. The Server object is a low-level object that provides some basic properties and methods that can be used in almost every Active Server Page. This object will allow you to do things like:

• Set the length of time for which a script can run before an error occurs
• Take a user-supplied string and encode it into HTML format
• Convert a virtual path to a physical path on the server
• Take a user-supplied string and encode it into the proper format for a URL string
• Create an instance of an Active Server component

The interface of the Server object looks like this. These methods and properties don't directly affect the appearance of the page on the browser, but they do provide valuable support in creating Active Server Pages.

Server Object Properties

The Server object has only one property - the ScriptTimeout property, described below.

The ScriptTimeOut Property

The ScriptTimeout property specifies the maximum amount of time that a script can run before it is terminated. This will prevent bugs (such as infinite loops) from causing the server process to hang indefinitely. The ScriptTimeout property is a read/write property. Its default value is 90 seconds.

Server.ScriptTimeOut = intSeconds

[intTimeoutVal = ]Server.ScriptTimeOut

Server Object Methods

The CreateObject method is used to create an instance of an Active Server component.

objCompRef = Server.CreateObject(progID)

For example, we use the CreateObject method to create instances of the server components supplied by Microsoft along with ASP:

Set objBrowser = Server.CreateObject("MSWC.BrowserType")

Response.Write("Hello, " & objBrowser.Browser & " user!")

The progID in this example is MSWC.BrowserType. All objects that come as part of the Microsoft Internet Information Server have MSWC (MicroSoft Web Component) in the Vendor part of the progID.

The CreateObject method is also used to create instances of the ADO database access objects:

Set objConn = Server.CreateObject("ADODB.Connection")

objConn.Open "driver={SQL Server}; server=srv; uid=sa; pwd=; database=pubs"

We will look at ADO in more detail in Chapter 8.

Lastly, the CreateObject method is used to create instances of custom Active Server components. These are components that are acquired from a third party, or that you've developed yourself. In either case, the method for creating an instance of them is the same:

Set objCustomASC = Server.CreateObject("MyComponentName.MyClass")

objCustomASC.methodCall

Objects created with the Server.CreateObject method are visible only to the script that is on the page where the object was created. We call this the page scope. Page-scoped objects are automatically destroyed by the server when at the end of the current page (although destroying the object formally using Set objName = Nothing is a good habit - it's a safer way to ensure that the server's resources are released). As we described in Chapter 4, we use the Application and Session objects to store instances with global scope or with session scope.

The HTMLEncode Method

The HTMLEncode method applies HTML encoding to the string supplied as its parameter.

[strEncoded = ]Server.HTMLEncode(strText)

HTML Encoding ensures that the string supplied will appear in a web page in the exact format that it is stored. Why is this necessary? Suppose you're passing a string to the browser for display. If your string contains any character-strings that look like HTML tags, then the browser interprets them as HTML tags - for example, of your string contains the substring of < B > then the browser will display all subsequent text in bold.

This may be the effect that you are looking for; but if you are writing HTML documentation (or anything else that requires the tags themselves to be visible in HTML), then you have a problem. By HTML-encoding the string, the parts of the string that look like HTML will be converted such that they will appear properly in the page. In the case of the < B > tag, the HTML encoded version would look like <B>. You'll find an example that uses the HTMLEncode method towards the end of Chapter 6.

The MapPath Method

The MapPath method is used to provide file location information for use in our scripts. The MapPath method takes a virtual path and converts it to a physical path.

[strPhysPath = ]Server.MapPath(strPath)

If strPath starts with a forward slash (/) or with a backward slash (\), the MapPath method returns a path as if strPath is a full virtual path. If strPath doesn't start with a slash, the MapPath method returns a path relative to the directory of the script file being processed. The MapPath method is also seen in action in Chapter 6.

The URLEncode Method

The URLEncode method takes a string of information and converts it into URL-encoded form. This method is used mostly for converting URLs into acceptable characters for browsers (hence the name URLEncode). However, the method works for any string, which makes it a very useful function, especially when dealing with e-mail addresses.

[strEncodedString = ]Server.URLEncode(strURL)

Using the Server Object

The Server object is a utility object, and you'll be seeing it action throughout many of the examples in the book. In particular, you'll see a lot of the CreateObject method in the examples of Chapters 7 and 8; you'll find the MapPath method utilized in the FileSystemObject example of Chapter 6, and you'll see URLEncode and HTMLEncode in the TextStream example, also in Chapter 6.

Summary

In this short chapter we have discussed the remaining object from the Active Server Pages object model. The Server object is a utility object that provides methods which are necessary in many web pages:

• A method to create instances of the server-side components
• The ability to set a global script timeout value
• Methods to encode strings based on HTML or URL formatting rules
• A method to translate a virtual directory name to its physical path on the hard drive

In the next chapter we will look at the objects that are part of the Scripting Library. While not exclusively for the use of ASP developers, they provide a great deal of functionality to make developer's lives easier.