Active Server Pages Guide

Active Server Pages Guide Page 1 of 659
Active Server Pages Guide

This is preliminary documentation for IIS 5.0 and is subject to change.
Welcome to the Active Server Pages Guide. This section provides detailed
information about creating ASP pages and developing Web applications. It
also describes the special event methods and interfaces available for
creating components for access by ASP or ISAPI extensions. In this section
you will find information on how to store your custom IIS configuration data
and how you can use built-in objects to manipulate that data. Finally, the
guide provides a library of script and program samples demonstrating a
variety of ways to interact with IIS.
This section contains:
? Active Server Pages: Provides an introduction to creating Active

Server Pages and demonstrates most of the key concepts for
understanding the IIS programming platform.
? Developing Web Applications: Outlines concepts of how IIS fits into
the Microsoft architecture for distributed applications, as well as
providing specific details for designing and implementing applications
for deployment through HTTP.
? Administering IIS Programmatically: Provides overviews and
reference material to help you manage the IIS configuration
programmatically.
? Visual Basic Object Model: Describes the properties and methods of
the ASP Built-in Objects.
? Installable Components for ASP: Outlines a variety of components
you can install to work with ASP.
? Script Reference: Contains miscellaneous reference material,
including the @ directives and Global.asa references.
? ASP Samples: Provides demonstration scripts, illustrating most of the
concepts presented in the guide.
Active Server Pages

Microsoft® Active Server Pages (ASP) is a server-side scripting environment

that you can use to create interactive Web pages and build powerful Web
applications. When the server receives a request for an ASP file, it
processes server-side scripts contained in the file to build the Web page
that is sent to the browser. In addition to server-side scripts, ASP files can
contain HTML (including related client-side scripts) as well as calls to COM
components that perform a variety of tasks, such as connecting to a
database or processing business logic.
The topics in this section introduce Active Server Pages, explain the basic
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000

concepts of scripting with Active Server Pages, and discuss more complex
application issues such as how to maintain state.
This section includes:
? Understanding Active Server Pages: Introduces ASP and describes

new features in this release.
? Building ASP Pages: Provides the basic information you need to write
a script, and introduces topics ranging from basic syntax to creating
transactional scripts.
This section does not include information on:
? More advanced topics, such as designing and building Web

applications; see Web Applications: An Overview.
? Reference pages for the components that come with ASP; see
Installable Components for ASP.
? Building your own ASP components; see Building Components for ASP.
? Sample scripts; see ASP Samples.
Understanding Active Server

Pages
Active Server Pages (ASP) makes it easy to generate dynamic content for
the Web and to build powerful Web applications. Whether you are a Web
designer or a Web developer, this introduction explains how ASP can help
you.
? Introduction to Active Server Pages: Provides an overview of Active

Server Pages.
? What's New in ASP: Describes new features added in this release.
? Important Changes in ASP: Describes functionality and behavior that
has changed for this release.
This section does not contain information on:
? Fundamental concepts of writing server-side scripts with ASP; see

Building ASP Pages.
? Information on writing more advanced scripts; see Web Applications:
An Overview.
Introduction to Active Server

Pages
Microsoft® Active Server Pages (ASP) is a server-side scripting environment

that you can use to create and run dynamic, interactive Web server
applications. With ASP, you can combine HTML pages, script commands,
and COM components to create interactive Web pages or powerful Web-
based applications, which are easy to develop and modify.
For the HTML Author

If you are an HTML author, you will find that server-side scripts written in
ASP are an easy way to begin creating more complex, real-world Web
applications. If you have ever wanted to store HTML form information in a
database, personalize Web sites according to visitor preferences, or use
different HTML features based on the browser, you will find that ASP
provides a compelling solution. For example, previously, to process user
input on the Web server you would have had to learn a language such as
Perl or C to build a conventional Common Gateway Interface (CGI)
application. With ASP, however, you can collect HTML form information and
pass it to a database using simple server-side scripts embedded directly in
your HTML documents. If you are already familiar with scripting languages
such as Microsoft VBScript or Microsoft® JScript® (JScript is the Microsoft
implementation of the ECMA 262 language specification), you will have
little trouble learning ASP.
For the Experienced Web Scripter

Since ASP is designed to be language-neutral, if you are skilled at a
scripting language such as VBScript, JScript, or PERL, you already know how
to use Active Server Pages. What more, in your ASP pages you can use any
scripting language for which you have installed a COM compliant scripting
engine. ASP comes with VBScript and JScript scripting engines, but you can
also install scripting engines for PERL, REXX, and Python, which are
available through third-party vendors.
For the Web Developer and Programmer

If you develop back-end Web applications in a programming language, such
as Visual Basic, C++, or Java, you will find ASP a flexible way to quickly
create Web applications. Besides adding scripts to create an engaging
HTML interface for your application, you can build your own COM
components. You can encapsulate your application's business logic into
reusable modules that you can call from a script, from another component,
or from another program.
The Active Server Pages Model

A server-side script begins to run when a browser requests an .asp file from

your Web server. Your Web server then calls ASP, which processes the
requested file from top to bottom, executes any script commands, and
sends a Web page to the browser.
Because your scripts run on the server rather than on the client, your Web
server does all the work involved in generating the HTML pages sent to
browsers. Server-side scripts cannot be readily copied because only the
result of the script is returned to the browser. Users cannot view the script
commands that created the page they are viewing.
What's New in ASP

Active Server Pages has been enhanced with features that make it easier to
use for scripters and Web application developers.
? New Flow Control Capabilities The ASP Server object now has two
new methods that you can use to control program flow:
Server.Transfer and Server.Execute. Rather than redirecting
requests, which requires an expensive round-trip to the client, you can
use these methods to transfer requests directly to an .asp file, without
leaving the server. For more information, see Sending Content to the
Browser.
? Error Handling ASP now has a new error-handling capability so that
you can trap errors in a custom error message .asp file. You can use
the new Server.GetLastError method to display useful information,
such as an error description or the line number where the error
occurred. For more information, see ASPError Object.
? Scriptless ASP Because static content is usually processed more
quickly than server-side content it was previously better to assign
an .asp file extension only to files that contained ASP functionality.
Whenever you needed to add ASP functionality to your static .html
files, you had to manually add .asp file extensions and correct related
hyperlinks. With this latest release of ASP, however, .asp files that do
not contain server-side functionality are now processed more quickly
than ever before. So, if you are creating an evolving Web application in
which files may eventually require ASP functionality, you can now
conveniently assign those files .asp file extensions, regardless of
whether they contain static or server-side content. For more
information, see Creating an ASP Page.
? Performance Enhanced Objects Active Server Pages now provides
performance enhanced versions of its popular installable components.
These objects will scale reliably in a wide range of Web publishing
environments. For more information, see Installable Components for
ASP.
? XML Integration Just as HTML enables you to describe the format of a
Web document, Extensible Markup Language (XML) enables you to
describe complex data structures. You will be able to share this
information across a variety of applications, clients, and servers. Using

the new Microsoft® XML Parser, included with Microsoft® Internet

Explorer version 4.0, or later, you will be able to create applications
that enable your Web server to exchange XML formatted data with
Microsoft Internet Explorer version 4.0, or later, or with any server
having XML parsing capabilities. For more information, see the
Microsoft XML Web site located at http://msdn.microsoft.com/xml/.
? Windows Script Components ASP supports Microsoft's powerful new
scripting technology, Windows Script Components. Now you can turn
your business logic script procedures into reusable COM components
that you can use in your Web applications, as well as in other COM
compliant programs. For more information, see Using Components and
Objects.
? A New Way to Determine Browser Capabilities ASP has a new
feature for determining the exact capabilities of a browser. When a
browser sends a cookie describing its capabilities (such a cookie can
be installed by using a simple client-side script) you can create an
instance of the Browser Capabilities Component that retrieves the
browser's properties as returned by the cookie. You can use this
feature to discover a browser's capabilities and adjust your application
accordingly. For more information, see Retrieving Browser Capabilities
from a Cookie.
? ASP Self-Tuning ASP now detects when executing requests are
blocked by external resources and automatically provides more threads
to simultaneously execute additional requests and to continue normal
processing. If the CPU becomes overburdened, ASP curtails the number
of threads in order to reduce the constant switching that occurs when
too many nonblocking requests are executing simultaneously. For more
information, see the metabase property reference for
AspThreadGateEnabled.
? Server-Side Include with SRC Attribute You can now use the HTML
<SCRIPT></SCRIPT> tag's SRC attribute to do server-side includes.
When you use the SRC attribute to specify a virtual or relative path
and use the RUNAT=SERVER attribute to denote server-side execution,
you can achieve the same functionality as the #Include directive. For
more information, see Including Files.
? Encoded ASP Scripts Traditionally, Web developers have been unable
to prevent others from viewing the logic behind their scripts. ASP now
supports a new script encoding utility provided with Microsoft Visual
Basic Scripting Edition (VBScript) and Microsoft JScript 5.0. Web
developers can apply an encoding scheme to both client and server-
side scripts that makes unreadable the programmatic logic using
standard ASCII characters. Encoded scripts are decoded at run time by
the script engine, so there's no need for a separate utility. Although
this feature is not intended as a secure, encrypted solution, it can
prevent most casual users from browsing or copying scripts. For more
information, visit the Microsoft Windows Script Technologies Web site
at http://msdn.microsoft.com/scripting/.
Important Changes in ASP


ASP has undergone several important changes and enhancements. If you

are updating your application from a previous version of ASP, you should be
aware of these changes.
Note To learn about new ASP features, see What's New in ASP.
? Buffering is Now On By Default In IIS 4.0, content buffering was off

by default. In IIS 5.0, unless a script specifically turns off buffering, its
output is always buffered. This means that the final output will be
sent to the client at the completion of processing or when the script
calls the Response.Flush method. For more information, see the
Buffering Content section in the Sending Content to the Browser topic.
? Response.IsClientConnected In IIS 4.0,

Response.IsClientConnected returned the correct information only if
an ASP file sent content to the browser. In IIS 5.0, an ASP file can use
the IsClientConnected property prior to sending content to the
browser. For more information, see IsClientConnected.
? Improved Include File Security In IIS 4.0, when an include file

resided in a virtual root mapped to a physical path, ASP did not use
the security credentials of the physical path to process the file. In
IIS 5.0, ASP applies the credentials of the physical path when
processing include files. For more information, see Including Files.
? Default Document Query String Behavior In IIS 5.0, if an .asp

(or .cdx) file is configured as the default document, it can now receive
a query string from a URL that does not specify the default document.
For example, the URLs http://www.microsoft.com/default.asp?newuser=true
and http://www.microsoft.com/?newuser=true will both send a query string
value to the default .asp file.
? Transaction Flags IIS 4.0 used the required, requires new, and not
supported transaction flags to indicate that ASP was starting a new
transaction. In IIS 5.0, this behavior is unchanged. However, if an .asp
file executes a transacted .asp file using the new Server.Execute or
Server.Transfer methods, then the transaction flag state is
maintained for the second .asp file. If the second .asp file's
transaction flags indicate that transactions are supported or required,
then the existing transaction will be used and a new transaction will
not be started.
? Behavior of Both-Modeled Objects A Both-Modeled COM object which

does not support the Free-Threaded Marshaller will fail if it is stored in
Application state. Both-Modeled components must aggregate the Free-
Threaded Marshaller to be stored in Application state.
? Configurable Entries Moved to the Metabase The following IIS 4.0

registry entries are now in the metabase:
? ProcessorThreadMax
? ErrorsToNTLog

For IIS 5.0, all configurable parameters for ASP can be modified from
the metabase.
? Security for Local Server COM Objects IIS uses a new Windows COM
feature called cloaking to enable local server applications instantiated
from an .asp file to have the security context of the originating client.
In previous versions, the identity assigned to the local server COM
object depended on the identity of the user who created the object
instance.
? Allow Out-of-Process Local Server COM applications By Default In

IIS 4.0, by default the AspAllowOutOfProcComponents metabase
property was set to 0, which disabled the local server COM object's
Server.CreateObject method. In IIS 5.0, the default value is set to
1, enabling creation of local server objects.
? Objects Released Earlier In IIS 4.0, COM objects were only released
when ASP finished processing a page. In IIS 5.0, if a COM object does
not use the OnEndPage method and the reference count for the
object is zero, then the object is released prior to the completion of
processing.
Building ASP Pages

ASP provides a powerful and extensible framework for creating server-side

scripts with any COM compliant scripting or programming language. This
section is intended to teach the fundamentals of using a scripting language
to create an .asp file. You will learn how to accomplish a wide range of
basic programming tasks, from creating a loop to manipulating a database
and processing transactions. Whether you are a beginning or experienced
scripter, you can envision the topics in this section as development goals,
that is, as demonstrations intended to encourage you by suggesting more
sophisticated ways in which you can utilize ASP. This can lead to
applications that perform better and are more maintainable.
Although these topics introduce some scripting and programming concepts,

they are not intended to teach you a scripting language. Microsoft scripting
languages (Microsoft VBScript and Microsoft JScript) provide their own
documentation, and many additional scripting books are available from your
local bookseller. So, if you are new to scripting, take advantage of the
many books, classes, and Internet resources which can help you to master
these languages.
This section includes:

? Creating an ASP Page: Describes an ASP file and explains how to add
script commands to a page.
? Working with Scripting Languages: Explains how to set the primary
language and how to use VBScript and JScript in server scripts.
? Using Variables and Constants: Provides an introduction to using
variables in ASP scripts and explains how to access constant
definitions.
? Interacting with Client-Side Scripts: Shows how to write server-side
scripts that create and interact with client-side scripts.
? Writing Procedures: Describes how to define procedures (functions
and subroutines) and call them from server-side scripts.
? Working with Collections: Describes how to access items in a built-in
object's collections, including access by iterating through a collection.
? Processing User Input: Explains how to collect and process
information gathered from an HTML form.
? Using Components and Objects: Explains how to create an instance
of an object provided by a COM component, how to use the ASP built-
in objects, and how to use the methods and properties of any object.
? Setting Object Scope: Demonstrates the scope, or extent, of an
object and describes how to create session and application scoped
objects.
? Sending Content to the Browser: Describes how to control the ways
in which pages are sent to a browser.
? Including Files: Explains how to use the #include statement to insert
the contents of a file into an .asp file.
? Managing Sessions: Describes how to preserve information about a
user.
? Accessing a Data Source: Explains how to use ASP and Microsoft
ActiveX Data Objects (ADO) to retrieve information from a database.
? Understanding Transactions: Demonstrates how to run a script under
a transaction context. Business and credit card applications often need
to the ability to run scripts and components within transactions.
? Debugging ASP Scripts: Describes how to use the Microsoft Script
Debugger to find and eliminate errors in your scripts.
? Built-in ASP Objects: Provides a quick overview of the ASP built-in
objects, and links to more detailed information.
? Active Server Pages Objects Quick Reference Card: Contains quick
reference information about ASP built-in objects.
This section does not include information on:
? Developing programmatically advanced collections of scripts called

applications; see Developing Web Applications.
? Designing Web applications; see Design Decisions.
Creating an ASP Page


An Active Server Pages (ASP) file is a text file with the extension .asp that
contains any combination of the following:
? Text
? HTML tags
? Server-side scripts
A quick way to create an .asp file is to rename your HTML files by replacing
the existing .htm or .html file name extension with an .asp extension. If
your file does not contain any ASP functionality, then the server dispenses
with the ASP script processing and efficiently sends the file to the client. As
a Web developer, this affords you tremendous flexibility because you can
assign your files .asp extensions, even if you do not plan on adding ASP
functionality until later.
To publish an .asp file on the Web, save the new file in a virtual directory
on your Web site (be sure that the directory has Script or Execute
permission enabled). Next, request the file with your browser by typing in
the file's URL. (Remember, ASP pages must be served, so you cannot
request an .asp file by typing in it's physical path.) After the file loads in
your browser, you will notice that the server has returned an HTML page.
This may seem strange at first, but remember that the server parses and
executes all ASP server-side scripts prior to sending the file. The user will
always receive standard HTML.
You can use any text editor to create .asp files. As you progress, you may
find it more productive to use an editor with enhanced support for ASP,
such as Microsoft® Visual InterDev™. (For more information, visit the
Microsoft Visual InterDev Web site at
http://msdn.microsoft.com/vinterdev/.)
Adding Server-Side Script Commands

A server-side script is a series of instructions used to sequentially issue
commands to the Web server. (If you have previously developed Web sites,
than you are probably familiar with client-side scripts, which are used to
instruct the Web browser.) In .asp files, scripts are differentiated from text
and HTML tags by delimiters. A delimiter is a character or sequence of
characters that marks the beginning or end of a unit. In the case of HTML,
these delimiters are the less than (<) and greater than (>) symbols, which
enclose HTML tags.
ASP uses the delimiters <% and %> to enclose script commands. You can
include within the delimiters any command that is valid for the scripting
language you are using. The following example shows a simple HTML page
that contains a script command:
<HTML>
<BODY>
This page was last refreshed on <%= Now() %>.
</BODY>
</HTML>

The VBScript function Now() returns the current date and time. When the
Web server processes this page, it replaces <%= Now() %> with the current
date and time and returns the page to the browser:
This page was last refreshed on 01/29/99 2:20:00 PM.
Commands enclosed by delimiters are called primary script commands.

These commands are processed using the primary scripting language. Any
command that you use within script delimiters must be valid for the primary
scripting language. By default, the primary scripting language is VBScript.
You can also set a different default language. See Working with Scripting
Languages.
If you are already familiar with client-side scripting, you are familiar with
the HTML <SCRIPT> tag used to enclose script commands and expressions.
You can also use the <SCRIPT> tag for server-side scripting whenever you
need to define procedures in multiple languages within an .asp file. For
more information, see Working with Scripting Languages.
Mixing HTML and Script Commands

You can include within ASP delimiters any statement, expression,
procedure, or operator that is valid for your primary scripting language. A
statement, in VBScript and other scripting languages, is a syntactically
complete unit that expresses one kind of action, declaration, or definition.
The conditional If...Then...Else statement that appears below is a common
VBScript statement.
<%
Dim dtmHour
dtmHour = Hour(Now())
If dtmHour < 12 Then

strGreeting = "Good Morning!"
Else
strGreeting = "Hello!"
End If
%>
<%= strGreeting %>
Depending on the hour, this script assigns either the value "Good Morning!"
or the value "Hello!" to the string variable strGreeting. The <%= strGreeting %
> statement sends the current value of the variable to the browser.
Thus, a user viewing this script before 12:00 noon (in the Web server’s
time zone) would see this line of text:
Good Morning!
A user viewing the script at or after 12:00 noon would see this line of text:

Hello!
You can include HTML text between the sections of a statement. For
example, the following script, which mixes HTML within an If...Then...Else
statement, produces the same result as the script in the previous example:
<%
Dim dtmHour

%>
Good Morning!
<% Else %>
Hello!
<% End If %>
If the condition is true—that is, if the time is before noon—then the Web
server sends the HTML that follows the condition (“Good Morning”) to the
browser; otherwise, it sends the HTML that follows Else (“Hello!”) to the
browser. This way of mixing HTML and script commands is convenient for
wrapping the If...Then...Else statement around several lines of HTML text.
The previous example is more useful if you want to display a greeting in
several places on your Web page. You can set the value of the variable
once and then display it repeatedly.
Rather than interspersing HTML text with script commands, you can return
HTML text to the browser from within a script command. To return text to
the browser, use the ASP built-in object Response. The following example
produces the same result as the previous scripts:
<%
Dim dtmHour

Response.Write "Good Morning!"
Else
Response.Write "Hello!"
End If
%>
Response.Write sends the text that follows it to the browser. Use

Response.Write from within a statement when you want to dynamically
construct the text returned to the browser. For example, you might want to
build a string that contains the values of several variables. You will learn
more about the Response object, and objects in general, in Using
Components and Objects and Sending Content to the Browser. For now,
simply note that you have several ways to insert script commands into an
HTML page.
You can include procedures written in your default primary scripting

language within ASP delimiters. Refer to Working with Scripting Languages

for more information.
If you are working with JScript commands, you can insert the curly braces
that indicate a block of statements directly into your ASP commands even if
they are interspersed with HTML tags and text. For example:
<%
if (screenresolution == "low")
{
%>
This is the text version of a page.
<%
}
else
{
%>
This is the multimedia version of a page.
<%
}
%>
--Or--
<%
if (screenresolution == "low")
{
Response.Write("This is the text version of a page.")
}
else
{
Response.Write("This is the multimedia version of a page.")
}
%>
Using ASP Directives

ASP provides directives that are not part of the scripting language you use.
These directives are the output directive and the processing directives.
The ASP output directive <%= expression %> displays the value of an
expression. This output directive is equivalent to using Response.Write to
display information. For example, the output expression <%= city %> displays
the word Baltimore (the current value of the variable) on the browser.
The ASP processing directive <%@ keyword %> gives ASP information it needs
to process an .asp file. For example, the following directive sets VBScript
as the primary scripting language for the page:
<%@ LANGUAGE=VBScript %>
The processing directive must appear on the first line of an .asp file. To
add more than one directive to a page, the directive must be within the
same delimiter. Do not put the processing directive in a file included with
the #include statement. (For more information, see Including Files.) You
must use a space between the at sign (@) and the keyword. The processing

directive has the following keywords:
? The LANGUAGE keyword sets the scripting language for the .asp file.
See Working with Scripting Languages.
? The ENABLESESSIONSTATE keyword specifies whether an .asp file uses
session state. See Managing Sessions.
? The CODEPAGE keyword sets the code page (the character encoding)
for the .asp file.
? The LCID keyword sets the locale identifier for the file.
? The TRANSACTION keyword specifies that the .asp file will run under a
transaction context. See Understanding Transactions.
Important You can include more than one keyword in a single directive.
Keyword/value pairs must be separated by a space. Do not put spaces
around the equal sign (=).
The following example sets both the scripting language and the code page:
<%@ LANGUAGE="JScript" CODEPAGE="932" %>
White Space in Scripts

If your primary scripting language is either VBScript or JScript, ASP removes
white space from commands. For all other scripting languages, ASP
preserves white space so that languages that depend on position or
indentation, are correctly interpreted. White space includes spaces, tabs,
returns, and line feeds.
For VBScript and JScript, you can use white space after the opening
delimiter and before the closing delimiter to make commands easier to
read. All of the following statements are all valid:
<% Color = "Green" %>
<%Color="Green"%>
<%
Color = "Green"
%>
ASP removes white space between the closing delimiter of a statement and
the opening delimiter of the following statement. However, it is good
practice to use spaces to improve readability. If you need to preserve the
white space between two statements, such as when you are displaying the
values of variables in a sentence, use an HTML nonbreaking space character
( ). For example:
<%
'Define two variables with string values.
strFirstName = "Jeff"
strLastName = "Smith"
%>
<P>This Web page is customized for "<%= strFirstName %> <%= strLastName %>." </P>

Working with Scripting Languages

Programming languages such as Visual Basic, C++, and Java provide low-
level access to computer resources and are used to create complex, large-
scale programs. Scripting languages, however, are used to create programs
of limited capability, called scripts, that execute Web site functions on a
Web server or browser. Unlike more complex programming languages,
scripting languages are interpreted, instruction statements are sequentially
executed by an intermediate program called a command interpreter. While
interpretation reduces execution efficiency, scripting languages are easy to
learn and provide powerful functionality. Scripts can be embedded in HTML
pages to format content or used to implement COM components
encapsulating advanced business logic.
Active Server Pages makes it possible for Web developers to write scripts
that execute on the server in variety of scripting languages. In fact, several
scripting languages can be used within a single .asp file. In addition,
because scripts are read and processed on the server-side, the browser that
requests the .asp file does not need to support scripting.
You can use any scripting language for which the appropriate scripting
engine is installed on your Web server. A scripting engine is a program that
processes commands written in a particular language. Active Server Pages
comes with two scripting engines: Microsoft Visual Basic Scripting Edition
(VBScript) and Microsoft JScript. You can install and use engines for other
scripting languages, such as REXX, PERL, and Python.
If you are already a Visual Basic programmer, you can immediately begin
using VBScript, which is a subset of Visual Basic. If you are a Java, C, or
C++ programmer, you may find that JScript syntax is familiar to you, even
though JScript is not directly related to Java or C.
If you are familiar with another scripting language, such as REXX, Perl, or
Python you can obtain and install the appropriate scripting engine so that
you can use the language you already know. Active Server Pages is a COM
scripting host; to use a language you must install a scripting engine that
follows the COM Scripting standard and resides as a COM (Component
Object Model) object on the Web server.
Setting the Primary Scripting Language

The ASP primary scripting language is the language used to process
commands inside the <% and %> delimiters. By default, the primary
scripting language is VBScript. You can use any scripting language for which
you have a script engine as the primary scripting language. You can set the
primary scripting language on a page-by-page basis, or for all pages in an
ASP application.

Setting the Language for an Application
To set the primary scripting language for all pages in an application, set
the Default ASP Language property on the App Options tab in the
Internet Information Services snap-in. .
Setting the Language for a Page
To set the primary scripting language for a single page, add the <%@
LANGUAGE %> directive to the beginning of your .asp file. The syntax for this
directive is:
<%@ LANGUAGE=ScriptingLanguage %>
where ScriptingLanguage is the primary scripting language that you want to

set for that particular page. The setting for a page overrides the global
setting for all pages in the application.
Follow the guidelines for using an ASP directive; for more information, see
Creating an ASP Page.
Note To use a language that does not support the Object.Method syntax
as the primary scripting language, you must first create the
LanguageEngines registry key.
Using VBScript and JScript on the Server

When using VBScript on the server with ASP, two VBScript features are
disabled. Because scripts written with Active Server Pages are executed on
the server, the VBScript statements that present user-interface elements,
InputBox and MsgBox, are not supported. In addition, do not use the
VBScript functions CreateObject and GetObject in server-side scripts. Use
Server.CreateObject instead so that ASP can track the object instance.
Objects created by CreateObject or GetObject cannot access the ASP
built-in objects and cannot participate in transactions. The exception to
this rule is when you are using the IIS Admin Objects, and when you are
using Java monikers. For more information, see Using IIS Admin Objects
and Creating an Object from a Java Class.
For a list and description of all VBScript and JScript operators, functions,
statements, objects, properties, and methods, refer to the VBScript
Language Reference and JScript Language Reference. You can find this
reference at the Microsoft Windows Script Technologies Web site, located
at http://msdn.microsoft.com/scripting/.
Including Comments
Because the processing of all scripts in ASP is done on the server side,
there is no need to include HTML comment tags to hide the scripts from
browsers that do not support scripting, as is often done with client-side
scripts. All ASP commands are processed before content is sent to the

browser. You can use HTML comments to add remarks to an HTML page;
comments are returned to the browser and are visible if the user views the
source HTML.
VBScript Comments
Apostrophe-style comments are supported in VBScript. Unlike HTML

comments, these are removed when the script is processed and are not
sent to the browser.
<%
'This line and the following two are comments.
'The PrintTable function prints all
'the elements in an array.
PrintTable MyArray()
%>
You cannot include a comment in an output expression. For example, the

first line that follows will work, but the second line will not, because it
begins with <%=.
<% i = i +1 'This statement increments i. (This script will work.) %>
<%= name 'This statement prints the variable name. (This script will fail.) %>
JScript Comments
The // comment characters are supported in JScript. These characters

should be used on each comment line.
<%
var x
x = new Date()
// This line sends the current date to the browser,
// translated to a string.
Response.Write(x.toString())
%>
Case Sensitivity
VBScript is not case sensitive. For example, you can use either Request or
request to refer to the ASP Request object. One consequence of case-
insensitivity is that you cannot distinguish variable names by case. For
example, you cannot create two separate variables named Color and color.
JScript is case sensitive. When you use JScript keywords in scripts, you
must type the keyword exactly as shown in the reference page for that
keyword. For example, using date instead of Date will cause an error. The
case shown in this documentation for the ASP built-in objects will work in
JScript commands.
Using Variables and Constants

A variable is a named storage location in the computer's memory that

contains data, such as a number or a text string. The data contained in a
variable is called the variable's value. Variables give you a way to store,
retrieve, and manipulate values using names that help you understand
what the script does.
Declaring and Naming Variables

Follow the rules and guidelines of your scripting language for naming and
declaring variables. Even if you are not required to declare a variable before
using it, it is a good habit to develop because it helps prevent errors.
Declaring a variable means telling the script engine that a variable with a
particular name exists so that you can use references to the variable
throughout a script.
VBScript
VBScript does not require variable declarations, but it is good scripting

practice to declare all variables before using them. To declare a variable in
VBScript, use the Dim, Public, or Private statement. For example:
<% Dim UserName %>
You can use the VBScript Option Explicit statement in an .asp file to
require variables to be explicitly declared with the Dim, Private, Public,
and ReDim statements. The Option Explicit statement must appear after
any ASP directives and before any HTML text or script commands. This
statement only affects ASP commands that are written in VBScript; it has
no effect on JScript commands.
<% Option Explicit %>

<HTML>
<%
Dim strUserName
Public lngAccountNumber
%>
.
.
.
For more information on these commands, see the VBScript Language

Reference, which can be found at the Microsoft Windows Script
Technologies Web site, located at http://msdn.microsoft.com/scripting/.
JScript
Although JScript does not usually require variable declarations, it is good

scripting practice to declare all variables before using them. To declare a
variable, use the var statement. For example:

<% var UserName %>
Typically, you will only need to declare a variable in JScript when you need
to distinguish a variable inside a function from a global variable used
outside the function. In this case, if you do not distinguish between the
two variables, JScript will assume that that you referring exclusively to the
global variable. For more information on the var statement, see the JScript
Language Reference. You can find this reference at the Microsoft Windows
Script Technologies Web site, located at
http://msdn.microsoft.com/scripting/.
Variable Scope
The scope, or lifetime, of a variable determines which script commands can
access a variable. A variable declared inside a procedure has local scope;
the variable is created and destroyed every time the procedure is executed.
It cannot be accessed by anything outside the procedure. A variable
declared outside a procedure has global scope; its value is accessible and
modifiable by any script command on an ASP page.
Note Limiting variable scope to a procedure will enhance performance.
If you declare variables, a local variable and a global variable can have the
same name. Modifying the value of one will not modify the value of the
other. If you do not declare variables, however, you might inadvertently
modify the value of a global variable. For example, the following script
commands return the value 1 even though there are two variables named
Y:
<%
Option Explicit
Dim Y
Y = 1
SetLocalVariable
Response.Write Y
Sub SetLocalVariable
Dim Y
Y = 2
End Sub
%>
The following script commands, on the other hand, return the value 2
because the variables are not explicitly declared. When the procedure call
sets Y to 2, the scripting engine assumes the procedure intended to modify
the global variable:
<%
Option Explicit
Dim Y = 1

SetLocalVariable
Response.Write Y
Sub SetLocalVariable
Y = 2
End Sub
%>
To avoid problems, develop the habit of explicitly declaring all variables.

This is particularly important if you use the #include statement to include
files into your .asp file. The included script is contained in a separate file
but is treated as though it were part of the including file. It is easy to
forget that you must use different names for variables used in the main
script and in the included script unless you declare the variables.
Giving Variables Session or Application Scope

Global variables are accessible only in a single .asp file. To make a variable
accessible beyond a single page, give the variable either session or
application scope. Session-scoped variables are available to all pages in
one ASP application that are requested by one user. Application-scoped
variables are available to all pages in one ASP application that are
requested by any user. Session variables are a good way to store
information for a single user, such as preferences or the user's name or
identification. Application variables are a good way to store information for
all users of a particular application, such as an application-specific greeting
or general values needed by the application.
ASP provides two built-in objects into which you can store variables: the
Session object and the Application object.
You can also create object instances with session or application scope. For
more information, see Setting Object Scope.
Session Scope
To give a variable session scope, store it in the Session object by

assigning a value to a named entry in the object. For example, the
following commands store two new variables in the Session object:
<%
Session("FirstName") = "Jeff"
Session("LastName") = "Smith"
%>
To retrieve information from the Session object, access the named entry by
using the output directive (<%=) or Response.Write. The following example
uses the output directive to display the current value of Session
("FirstName"):
Welcome <%= Session("FirstName") %>
You can store user preferences in the Session object, and then access

those preferences to determine what page to return to the user. For

example, you can allow a user to specify a text-only version of your content
in the first page of the application and apply this choice on all subsequent
pages that the user visits in this application.
<%
strScreenResolution = Session("ScreenResolution")
If strScreenResolution = "Low" Then
%>
This is the text version of the page.
<% Else %>
This is the multimedia version of the page.
<% End If %>
Note If you refer to a session-scoped variable more than once in a script,

consider assigning it to a local variable, as in the previous example, to
improve performance.
Application Scope
To give a variable application scope, store it in the Application object by

assigning a value to a named entry in the object. For example, the
following command stores an application-specific greeting in the
Application object:
<% Application("Greeting") = "Welcome to the Sales Department!" %>
To retrieve information from the Application object, use the ASP output
directive (<%=) or Response.Write to access the named entry from any
subsequent page in the application. The following example uses the output
directive to display the value of Application("Greeting"):
<%= Application("Greeting") %>
Again, if your script repeatedly refers to an application-scoped variable, you

should assign it to a local variable to improve performance.
Using Constants
A constant is a name that takes the place of a number or string. Some of
the base components provided with ASP, such as ActiveX Data Objects
(ADO), define constants that you can use in your scripts. A component can
declare constants in a component type library, a file that contains
information about objects and types supported by an COM component.
Once you have declared a type library in your .asp file you can use the
defined constants in any scripts in the same .asp file. Likewise, you can
declare a type library in your Global.asa file to use the defined constants in
any .asp file in an application.
To declare a type library, use the <METADATA> tag in your .asp file or
Global.asa file. For example, to declare the ADO type library, use the
following statements:

</SCRIPT>
Incorporating such functionality can produce some useful and interesting

applications. For example, the following is a simple server-side script
(written in VBScript) that manipulates a client-side script (written in
JScript):
<%
Dim dtmTime, strServerName, strServerSoftware, intGreeting
dtmTime = Time()
strServerName = Request.ServerVariables("SERVER_NAME")
strServerSoftware = Request.ServerVariables("SERVER_SOFTWARE")

'Generate a random number.

Randomize
intGreeting = int(rnd * 3)
%>
<SCRIPT LANGUAGE="JScript">

</SCRIPT>
Scripts of this kind can be expanded, for example, to configure a client-side

database or a DHTML personalization script. Innovative use of this
technique can also reduce round-trips and server processing.
Writing Procedures
A procedure is a group of script commands that performs a specific task and

can return a value. You can define your own procedures and call them
repeatedly in your scripts.
You can place procedure definitions in the same .asp file that calls the
procedures, or you can put commonly used procedures in a shared .asp file
and use the #include directive to include it in other .asp files that call the
procedures. Alternatively, you could encapsulate the functionality in a COM
component.
Defining Procedures

Procedure definitions can appear within <SCRIPT> and </SCRIPT> tags and
must follow the rules for the declared scripting language. Use the
<SCRIPT> element for procedures in languages other than the primary
scripting language. However, use the scripting delimiters (<% and %>) for
procedures in the primary scripting language.
When you use the HTML <SCRIPT> tag, you must use two attributes to
ensure server-side processing of the script. The syntax for using the
<SCRIPT> tag is:
<SCRIPT LANGUAGE=JScript RUNAT=SERVER>
procedure definition
</SCRIPT>
The RUNAT=SERVER attribute tells the Web server to process the script on
the server. If you do not set this attribute, the script is processed by the
client browser. The LANGUAGE attribute determines the scripting language
used for this script block. You can specify any language for which you have
the scripting engine installed with the server. To specify VBScript, use the
value VBScript. To specify JScript, use the value JScript. If you do not set
the LANGUAGE attribute, the script block is interpreted in the primary
scripting language.
The commands in the script block must form one or more complete
procedures in the chosen scripting language. For example, the following
commands define the JScript procedure MyFunction.
<HTML>
<SCRIPT LANGUAGE=JScript RUNAT=SERVER >
function MyFunction()
{
Response.Write("You called MyFunction().")
}
</SCRIPT>
Important Do not include within server-side <SCRIPT> tags any script

commands that are not part of complete procedures. Commands that are
not part of a procedure may cause unpredictable results because these
commands may be executed in an uncertain order. In addition, you cannot
use the ASP output directive <%= %> within a procedure. Instead, use
Response.Write to send content to the browser.
Calling Procedures
To call procedures, include the name of the procedure in a command. If you
are calling JScript procedures from VBScript, you must use parentheses
after the procedure name; if the procedure has no arguments, use empty
parentheses. If you are calling either VBScript or JScript procedures from
JScript, always use parentheses after the procedure name.

For VBScript, you can also use the Call keyword when calling a procedure.
However, if the procedure that you are calling requires arguments, the
argument list must be enclosed in parentheses. If you omit the Call
keyword, you also must omit the parentheses around the argument list. If
you use Call syntax to call any built-in or user-defined function, the
function’s return value is discarded.
The following example illustrates creating and calling procedures by using

two different scripting languages (VBScript and JScript).

<HTML>
<BODY>
<% Echo %>
<BR>
<% printDate() %>
</BODY>
</HTML>
<%
Sub Echo
Response.Write "<TABLE>" & _

"<TR><TH>Name</TH><TH>Value</TH></TR>"
Set objQueryString = Request.QueryString
For Each strSelection In objQueryString

Response.Write "<TR><TD>" & p & "</TD><TD>" & _
FormValues(strSelection) & "</TD></TR>"
Next
Response.Write "</TABLE>"
End Sub
%>
<SCRIPT LANGUAGE=JScript RUNAT=SERVER>
function printDate()
{
var x
x = new Date()
Response.Write(x.toString())
}
</SCRIPT>
Note VBScript calls to JScript functions are not case sensitive.
Passing Arrays to Procedures

To pass an entire array to a procedure in VBScript, use the array name
followed by empty parentheses; in JScript, use empty square brackets.

Working with Collections

Most of the ASP built-in objects provide collections. Collections are data
structures similar to arrays that store strings, numbers, objects and other
values. Unlike arrays, collections expand and contract automatically as
items are retrieved or stored. The position of an item will also move as the
collection is modified. You can access an item in a collection by its unique
string key, by its index (position) in the collection, or by iterating through
all the items in the collection.
Accessing an Item by Name or Index

You can access a specific item in a collection by referencing its unique
string key, or name. For example, the Contents collection holds any
variables stored in the Session object. It can also hold any objects
instantiated by calling Server.CreateObject. Suppose you have stored the
following user information in the Session object:
<%
Session.Contents("FirstName") = "Meng"
Session.Contents("LastName") = "Phua"
Session.Contents("Age") = 29
%>
You can access an item by using the string key you associated with the
item when you stored it in the collection. For example, the following
expression returns the string "Meng":
<%= Session.Contents("FirstName") %>
You could also access an item by using the index, or number, associated
with an item. For example, the following expression retrieves the
information stored in the second position of the Session object and returns
"Phua":
<%= Session.Contents(2) %>
ASP collections are numbered starting with 1. The index associated with an
item might change as items are added to or removed from the collection.
You should not depend on an item’s index remaining the same. Indexed
access is generally used to iterate through a collection, as described in the
following topics, or to access an item in a read-only collection.
You can also use a shorthand notation to access items by name. ASP
searches the collections associated with an object in a particular order. If
an item with a particular name appears only once in an object's collections,
you can eliminate the collection name (although doing so may affect

performance):
<%= Session("FirstName") %>
Eliminating the collection name is generally safe when you are accessing
items stored in the Application or Session object. For the Request object,
however, it is safer to specify the collection name because the collections
could easily contain items with duplicate names.
Iterating through a Collection

You can iterate through all the items in a collection to see what is stored in
the collection or to modify the items. You must supply the collection name
when you iterate through a collection. For example, you can use the
VBScript For...Each statement to access the items you stored in the
Session object:
<%
'Declare a counter variable.
Dim strItem
'For each item in the collection, display its value.

For Each strItem In Session.Contents
Response.Write Session.Contents(strItem) & "<BR>"
Next
%>
You can also iterate through a collection by using the VBScript For...Next
statement. For example, to list the three items stored in Session by the
previous example, use the following statements:
<%
Dim intItem
'Repeat the loop until the value of counter is equal to 3.

For intItem = 1 To 3
Response.Write Session.Contents(intItem) & "<BR>"
Next
%>
Because you do not usually know how many items are stored in a
collection, ASP supports the Count property for a collection, which returns
the number of items in the collection. You use the Count property to
specify the end value of the counter.
<%
Dim lngItem, lngCount
lngCount = Session.Contents.Count
'Repeat this loop until the counter equals the number of items
'in the collection.
For lngItem = 1 To lngCount
Response.Write Session.Contents(lngItem) & "<BR>"

Next
%>
In JScript, you use the for statement to loop through a collection. For
greater efficiency when using the Count property with a JScript for
statement, you should assign the value of Count to a local variable and
use that variable to set the end value of the counter. That way, the script
engine does not have to look up the value of Count each time through the
loop. The following example demonstrates this technique:
<%
var intItem, intNumItems;
intNumItems = Session.Contents.Count;
for (intItem = 1; intItem <= intNumItems; intItem++)

{
Response.Write(Session.Contents(intItem) + "<BR>")
}
%>
Microsoft JScript supports an Enumerator object that you can also use to
iterate through an ASP collection. The atEnd method indicates whether
there are any more items in the collection. The moveNext method moves
to the next item in the collection.
<%
Session.Contents("Name") = "Suki White"
Session.Contents("Department") = "Hardware"
.
.
.
//Create an Enumerator object.
var mycollection = new Enumerator(Session.Contents);
//Iterate through the collection and display each item.

while (!mycollection.atEnd())
{
var x = myCollection.item();
Response.Write(Session.Contents(x) + "<BR>");
myCollection.moveNext();
}
%>
Iterating through a Collection with Subkeys

Scripts might embed several related values in a single cookie to reduce the
number of cookies passed between the browser and the Web server. The
Cookies collection of the Request and Response objects can thus hold
multiple values in a single item. These subitems, or subkeys, can be
accessed individually. Subkeys are supported only by the Request.Cookies
and Response.Cookies collections. Request.Cookies supports only read
operations; Response.Cookies supports only write operations.
The following creates a regular cookie and a cookie with a subkeys:

<%
'Send a cookie to the browser.
Response.Cookies("Fruit") = "Pineapple"
'Send a cookie with subkeys to browser.

Response.Cookies("Mammals")("Elephant") = "African"
Response.Cookies("Mammals")("Dolphin") = "Bottlenosed"
%>
The cookie text in the HTTP response sent to the browser would appear as
the following:
HTTP_COOKIE= Mammals=ELEPHANT=African&DOLPHIN=Bottlenosed; Fruit=Pineapple;
You can also enumerate all the cookies in the Request.Cookies collection
and all the subkeys in a cookie. However, iterating through subkeys on a
cookie that does not have subkeys will not produce an item. You can avoid
this situation by first checking to see whether a cookie has subkeys by
using the HasKeys attribute of the Cookies collection. This technique is
demonstrated in the following example.
<%
'Declare counter variables.
Dim Cookie, Subkey
'Display the entire cookie collection.

For Each Cookie In Request.Cookies
Response.Write Cookie
If Request.Cookies(Cookie).HasKeys Then
Response.Write "<BR>"
'Display the subkeys.
For Each Subkey In Request.Cookies(Cookie)
Response.Write " ->" & Subkey & " = " & Request.Cookies(Cookie)(Subkey) & "<BR>"
Next
Else
Response.Write " = " & Request.Cookies(Cookie) & "<BR>"
End If
Next
%>
This script would return the following results:
Mammals
->ELEPHANT = African
->DOLPHIN = Bottlenosed
Fruit = Pineapple
The Case of the Key Name

The Cookies, Request, Response, and ClientCertificate collections can
reference the same, unique string key name. For example, the following
statements reference the same key name, User, but return different values
for each collection:
strUserID = Request.Cookies("User")

strUserName = Request.QueryString("User")
The case of the key name is set by the first collection to assign a value to
the key. Examine the following script:
<%
'Retrieve a value from QueryString collection using the UserID key.
strUser = Request.QueryString("UserID")
'Send a cookie to the browser, but reference the key, UserId, which has a different spel
Response.Cookies("UserId")= "1111-2222"
Response.Cookies("UserId").Expires="December 31, 2000"
%>
Although it may appear that key name UserId was assigned to the cookie,
in actuality, the key name UserID (which is capitalized differently) was
assigned to the cookie. The QueryString collection was first to define the
case of this key.
Because references to collection values are independent of the case of the

key name, this behavior will not affect your scripts unless your application
uses case sensitive processing of key names.
Iterating through a Collection of Objects

The Session and Application collections can hold either scalar variables or
object instances. The Contents collection holds both scalar variables and
object instances created by calling Server.CreateObject. The
StaticObjects collection holds objects created by using the HTML
<OBJECT> tag within the scope of the Session object. For more
information about instantiating objects in this manner, see Setting Object
Scope.
When you iterate through a collection that contains objects, you can either
access the object's Session or Application state information or access the
object's methods or properties. For example, suppose your application uses
several objects to create a user account, and each object has an
initialization method. You could iterate through the StaticObjects
collection to retrieve object properties:
<%
For Each Object in Session.StaticObjects
Response.Write Object & ": " & Session.StaticObjects(Object)
Next
%>
What’s Different About ASP Collections?

Although the ASP collections described in this topic are similar to the Visual
Basic Collection object, there are some differences. The ASP collections
support the Count property and the Item, Remove, and RemoveAll
methods. They do not support the Add method.

Processing User Input

Using the ASP Request object you can create simple, yet powerful scripts
for collecting and processing data gathered with HTML forms. In this topic
you will not only learn how to create basic form processing scripts, but also
acquire useful techniques for validating form information, both on your Web
server and at the user's browser.
About HTML Forms

HTML forms, the most common method for gathering Web-based
information, consist of arrangements of special HTML tags that render user
interface elements on a Web page. Text boxes, buttons, and check boxes
are examples of elements that enable users to interact with a Web page
and submit information to a Web server.
For example, the following HTML tags generate a form where a user can
enter their first name, last name, and age, and includes a button for
submitting information to a Web server. The form also contains an hidden
input tag (not displayed by the Web browser) that you can use to pass
additional information to a Web server.
<FORM METHOD="Post" ACTION="Profile.asp">

<INPUT TYPE="Text" NAME="FirstName">
<INPUT TYPE="Text" NAME="LastName">
<INPUT TYPE="Text" NAME="Age">
<INPUT TYPE="Hidden" NAME="UserStatus" VALUE="New">
<INPUT TYPE="Submit" VALUE="Enter">
</FORM>
Detailing the complete set of HTML form tags is outside the scope of this
topic, however, there are numerous sources of information that you can use
to learn about creating useful and engaging HTML forms. For example, use
your Web browser's source viewing feature to examine how HTML forms are
created on other Web sites. Also, visit Microsoft's MSDN Online Web site at
http://msdn.microsoft.com/ to learn innovative ways of using HTML forms
with other Internet technologies.
Processing Form Inputs with ASP
After creating an HTML form, you will need to process user input, which
means sending the information to an .asp file for parsing and manipulation.
Once again, examine the HTML code from the previous example. Notice that
the <FORM> tag's ACTION attribute refers to a file called Profile.asp. When
the user submits HTML information, the browser uses the POST method to
send to the information to an .asp file on the server, in this case
Profile.asp. The .asp file may contain scripts that process information and
interact with other scripts, COM components, or resources, such as a
database.

Using ASP, there are three basic ways to collect information from HTML
forms:
? A static .htm file can contain a form that posts its values to an .asp
file.
? An .asp file can create a form that posts information to another .asp
file.
? An .asp file can create a form that posts information to itself, that is,
to the .asp file that contains the form.
The first two methods operate in the same way as forms that interact with
other Web server programs, except that with ASP, the task of collecting and
processing form information is greatly simplified. The third method is a
particularly useful and will be demonstrated in the Validating Form Input
section.
Getting Form Input

The ASP Request object provides two collections that facilitate the task of
retrieving form information sent with as a URL request.
The QueryString Collection
The QueryString collection retrieves form values passed to your Web

server as text following a question mark in the request URL. The form
values can be appended to the request URL by using either the HTTP GET
method or by manually adding the form values to the URL.
For example, if the previous form example used the GET method
(METHOD="GET") and the user typed Clair, Hector, and 30, then the
following URL request would be sent to the server:
http://Workshop1/Painting/Profile.asp?FirstName=Clair&LastName=Hector&Age=30&UserStatus=Ne
Profile.asp might contain the following form processing script:
Hello <%= Request.QueryString("FirstName") %> <%= Request.QueryString("LastName") %>.

You are <%= Request.QueryString("Age") %> years old!
<%
If Request.QueryString("UserStatus") = "New" Then
Response.Write "This is your first visit to this Web site!"
End if
%>
In this case, the Web server would return the following text to the user's
Web browser:
Hello Clair Hector. You are 30 years old! This is your first visit to this Web site!
The QueryString collection also has an optional parameter that you can
use to access one of multiple values that appear in the URL request (using

the GET method). You can also use the Count property to count the number
of times that a specific type of value appears.
For example, a form containing a list box with multiple items can generate
the following request:
http://OrganicFoods/list.asp?Food=Apples&Food=Olives&Food=Bread
You could use the following command to count multiple values:
Request.QueryString("Food").Count
To display the multiple values types, List.asp could contain the following
script:
<%
lngTotal = Request.QueryString("Food").Count
For i = 1 To lngTotal
Response.Write Request.QueryString("Food")(i) & "<BR>"
Next
%>
The preceding script would display:
Apples
Olives
Bread
You can also display the entire list of values as a comma-delimited string
by using the following:
<% Response.Write Request.QueryString("Item") %>
This would display the following string:
Apples, Olives, Bread
Form Collection
When you use the HTTP GET method to pass long and complex form values
to a Web server, you run the risk of losing information. Some Web servers
tend to restrict the size of the URL query string, so that lengthy form
values passed with the GET method might be truncated. If you need to
send a large amount of information from a form to a Web server, you
should use the HTTP POST method. The POST method, which sends form
data in the HTTP request body, can send a an almost unlimited number of
characters to a server. You can use the ASP Request object's Form
collection to retrieve the values sent with the POST method.
The Form collection stores values in a manner similar to the QueryString

collection. For example, if a user filled out a form by entering a long list of
names, then you could retrieve the names with the following script:
<%

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

A well-designed Web form often includes a client script that validates user
input prior to sending information to the server. Validation scripts can
check for such things as whether the user entered a valid number or
whether a text box was left empty. Imagine that your Web site includes a
form that enables users to compute the rate of return on an investment.
You will probably want to verify whether a user has actually entered
numerical or text information in the appropriate form fields, prior to sending
potentially invalid information to your server.
In general, it's good practice to do as much form validation as possible on

the client side. Beyond prompting users more quickly about input errors,
client-side validation yields faster response times, reduces server loads,
and frees bandwidth for other applications.
The following client-side script validates user–input (in this case, the script
determines whether an account number entered by the user is actually a
number) prior to sending information to the server:
<SCRIPT LANGUAGE="JScript">
function CheckNumber()
{
if (isNumeric(document.UserForm.AcctNo.value))
return true
else
{
alert("Please enter a valid account number.")
return false
}
}
//Function for determining if form value is a number.

//Note: The JScript isNaN method is a more elegant way to determine whether
//a value is not a number. However, some older browsers do not support this method.
function isNumeric(str)
{
for (var i=0; i < str.length; i++)
{
var ch = str.substring(i, i+1)
if( ch < "0" || ch>"9" || str.length == null)
{
return false
}
}
return true
}
</SCRIPT>
<FORM METHOD="Get" ACTION="balance.asp" NAME="UserForm" ONSUBMIT="return CheckNumber()">

<INPUT TYPE="Text" NAME="AcctNo">

<INPUT TYPE="Submit" VALUE="Submit">
</FORM>
If form validation requires database access, however, you should consider

using server-side form validation. A particularly advantageous way of
carrying out server-side validation is to create a form that posts
information to itself. That is, the .asp file actually contains the HTML form
that retrieves user input. (Remember, you can use ASP to interact with
client-side scripts and HTML. For more information, see Interacting with
client-side Scripts.) The input is returned to the same file, which then
validates the information and alerts the user in case of an invalid input.
Using this method of processing and validating user input can greatly
enhance the usability and responsiveness of your Web based forms. For
example, by placing error information adjacent to the form field where
invalid information was entered, you make it easier for the user to discover
the source of the error. (Typically, Web-based forms forward requests to a
separate Web page containing error information. Users who do not
immediately understand this information may become frustrated.)
For example, the following script determines whether a user entered a valid
account number by posting information to itself (Verify.asp) and calling a
user defined function that queries a database:
<%
strAcct = Request.Form("Account")
If Not AccountValid(strAcct) Then
ErrMsg = "<FONT COLOR=Red>Sorry, you may have entered an invalid account number.</FONT
Else
Process the user input
.
.
.
Server.Transfer("Complete.asp")
End If
Function AccountValid(strAcct)
A database connectivity script or component method call goes here.
End Function
%>
<FORM METHOD="Post" ACTION="Verify.asp">

Account Number: <INPUT TYPE="Text" NAME="Account"> <%= ErrMsg %> <BR>
<INPUT TYPE="Submit">
</FORM>
In this example, the script is located in a file named Verify.asp, the same
file that contains the HTML form; it posts information to itself by specifying
Verify.asp in the ACTION attribute.
Important If your are using JScript for server-side validation, be sure to

place a pair of empty parentheses following the Request collection item
(either QueryString or Form) when you are assigning the collection to a

local variable. Without parenthesis, the collection returns an object, rather

than a string. The following script illustrates the correct way to assign
variables with JScript:
<%
var Name = Request.Form("Name")();
var Password = Request.Form("Password")();
if(Name > "")

{
if(Name == Password)
Response.Write("Your name and password are the same.")
else
Response.Write("Your name and password are different.");
}
%>
VBScript exhibits the same behavior if the collection contains multiple

values that are comma-separated or indexable. This means that for both
VBScript and JScript, in addition to placing a pair of empty parentheses
following the Request collection item, you will need to specify the index of
the desired value. For example, the following line of JScript returns only the
first of multiple values for a form element:
var Name = Request.Form("Name")(1);
Using Components and Objects

COM components are the key to building powerful, real-world Web

applications. Components provide functionality that you use in your scripts
to perform specialized tasks, such as executing financial transactions or
validating data. ASP also provides a set of base components that you can
use to greatly enhance your scripts.
About Components
A COM component is a reusable, programmatic building block that contains
code for performing a task or set of tasks. Components can be combined
with other components (even across networks) to create a Web application.
COM components execute common tasks so that you do not have to create
your own code to perform these tasks. For example, you can use a stock
ticker component to display the latest stock quotes on a Web page.
However, it would be difficult to create a script that provides the same
functionality. Also, the script would not be as reusable as a component.
If you are new to scripting, you can write scripts that use components
without knowing anything about how the component works. ASP comes with
base components that you can use immediately. For example, you can use
the ActiveX Data Objects (ADO) components to add database connectivity

to your Web pages. Additional components can also be obtained from third-
party developers.
If you are a Web application developer, components are the best way to
encapsulate your business logic into reusable, secure modules. For
example, you could use a component to verify credit card numbers by
calling the component from a script that processes sales orders. Because
the verification is isolated from the order process, you can update the
component when the credit card verification process changes, without
changing your order process. Also, since COM components are reusable, you
could reuse the component in other scripts and applications. Once you have
installed a component on your Web server, you can call it from a ASP
server-side script, an ISAPI extension, another component on the server, or
a program written in another COM-compatible language.
You can create components in any programming language that supports the
Component Object Model (COM), such as C, C++, Java, Visual Basic, or
numerous scripting languages. (If you are familiar with COM programming,
COM components are also known as Automation servers.) To run on the
Web server, your COM components cannot have any graphical user interface
elements, such as the Visual Basic MsgBox function; graphical interface
elements would only be viewable on the server, and not the browser.
Creating an Instance of a Component’s Object

A component is executable code contained in a dynamic-link library (.dll) or
in an executable (.exe) file. Components provide one or more objects, self
contained units of code which perform specific functions within the
component. Each object has methods (programmed procedures) and
properties (behavioral attributes). To use an object provided by a
component, you create an instance of the object and assign the new
instance to a variable name. Use the ASP Server.CreateObject method or
the HTML <OBJECT> tag to create the object instance. Use your scripting
language’s variable assignment statement to give your object instance a
name. When you create the object instance, you must provide its
registered name (PROGID). For the base components provided with ASP,
you can get the PROGID for the objects from the reference pages (see
Installable Components for ASP).
For example, the Ad Rotator component randomly rotates through a series

of graphical advertisements. The Ad Rotator component provides one
object, called the Ad Rotator object, whose PROGID is "MSWC.AdRotator."
To create an instance of the Ad Rotator object, use one of the following
statements:
VBScript:
<% Set MyAds = Server.CreateObject("MSWC.AdRotator") %>
JScript:
<% var MyAds = Server.CreateObject("MSWC.AdRotator") %>

If you are already familiar with VBScript or JScript, note that you do not use
the scripting language’s function for creating a new object instance
(CreateObject in VBScript or New in JScript). You must use the ASP
Server.CreateObject method; otherwise, ASP cannot track your use of the
object in your scripts.
You can also use the HTML <OBJECT> tag to create an object instance.
You must supply the RUNAT attribute with a value of Server, and you must
provide the ID attribute set to the variable name you will use in your
scripts. You can identify the object by using either its registered name
(PROGID) or its registered number (CLSID).The following example uses the
registered name (PROGID) to create an instance of the Ad Rotator object:
<OBJECT RUNAT=Server ID=MyAds PROGID="MSWC.AdRotator"></OBJECT>
The following example uses the registered number (CLSID) to create an

instance of the Ad Rotator object:
<OBJECT RUNAT=SERVER ID=MyAds

CLASSID="Clsid:1621F7C0-60AC-11CF-9427-444553540000"></OBJECT>
Use Scripting to Create COM Components

ASP supports Windows Script Components, Microsoft's powerful scripting
technology that you can use to create COM components. Specifically, you
can encapsulate common scripts, such as those used for database access or
content generation, into reusable components accessible from any .asp file
or program. You can create Windows Script Components by writing scripts
in a language such as VBScript or JScript without a special development
tool. You can also incorporate Windows Script Components into programs
written in COM compliant programming languages, such as Visual Basic,
C++, or Java.
The following is an example of a Windows Script Components, written in

VBScript, that defines methods for converting temperature measurements
between Fahrenheit and Celsius:
<SCRIPTLET>
<Registration
Description="ConvertTemp"
ProgID="ConvertTemp.Scriptlet"
Version="1.00"
>
</Registration>
<implements id=Automation type=Automation>

<method name=Celsius>
<PARAMETER name=F/>
</method>
<method name=Fahrenheit>
<PARAMETER name=C/>
</method>
</implements>

<SCRIPT LANGUAGE=VBScript>
Function Celsius(F)
Celsius = 5/9 * (F - 32)
End Function
Function Fahrenheit(C)
Fahrenheit = (9/5 * C) + 32
End Function
</SCRIPT>
</SCRIPTLET>
Before implementing this Windows Script Component you must save this
file with an .sct extension and then in Windows Explorer, right-click this file
and select Register. To use this Windows Script Component in a Web
page, you would use a server-side script such as the following:
<%
Option Explicit
Dim objConvert
Dim sngFvalue, sngCvalue
sngFvalue = 50
sngCvalue = 21
Set objConvert = Server.CreateObject("ConvertTemp.Scriptlet")

%>
<%= sngFvalue %> degrees Fahrenheit is equivalent to <%= objConvert.Celsius(sngFvalue) %>
<%= sngCvalue %> degrees Celsius is equivalent to <%= objConvert.Fahrenheit(sngCValue) %>
Using ASP Built-in Objects

ASP also provides built-in objects for performing useful tasks that simplify
Web development. For example, you can use the Request object to easily
access information associated with an HTTP request, such as user input
coming from HTML forms or cookies. Unlike using the objects provided by a
COM component, you do not need to create an instance of an ASP built-in
object to use it in your scripts. These objects are automatically created for
you when the ASP request starts processing. You access the methods and
properties of a built-in object in the same way in which you access the
methods and properties of a component’s objects, as described in this
topic. For a complete description of the built-in objects, see Active Server
Pages Objects Quick Reference Card.
Calling an Object Method

A method is an action you can perform on an object or with an object. The
syntax for calling a method is:
Object.Method parameters

The parameters vary depending on the method.
For example, you can use the Write method of the Response built-in
object to send information to the browser as shown in the following
statement:
<% Response.Write "Hello World" %>
Note Some scripting languages do not support the Object.Method

syntax. If your language does not, you must add an entry to the registry in
order to use that language as your primary scripting language. See Working
with Scripting Languages for more information.
Setting an Object Property

A property is an attribute that describes the object. Properties define
object characteristics, such as the type of the object, or describe the state
of an object, such as enabled or disabled. The syntax is:
Object.Property
You can sometimes read and set the value of a property. In addition, for
some objects, you can also add new properties.
For example, the Ad Rotator component has a property, Border, which

specifies whether the ad has a border around it and determines the border
thickness. The following expression specifies no border:
<% MyAds.Border = 0 %>
For some properties, you can display the current value by using the ASP
output directive. For example, the following statement returns TRUE if the
browser is still connected to the server:
<%= Response.IsClientConnected %>
Creating an Object from a Java Class

To use Server.CreateObject to create an instance of a Java class, you
must use the JavaReg program to register the class as a COM component.
You can then use Server.CreateObject method or an HTML <OBJECT> tag
with the PROGID or CLSID.
Alternatively, you can use the mechanism provided by Java monikers to

instantiate the Java class directly without using the JavaReg program. To
instantiate a class with monikers, use the VBScript or JScript GetObject
statement and provide the full name of the Java class in the form
java:classname. The following VBScript example creates an instance of the
Java Date class.
<%

Dim dtmDate
Set dtmDate = GetObject("java:java.util.Date")
%>
The date is <%= dtmDate.toString() %>
Objects created by calling GetObject instead of Server.CreateObject can

also access the ASP built-in objects and participate in a transaction. To use
Java monikers, however, you must be using version 2.0, or later, of the
Microsoft virtual machine.
Setting Object Scope

The scope of an object determines which scripts can use that object. By
default, when you create an object instance, the object has page scope.
Any script command in the same ASP page can use a page-scope object;
the object is released when the .asp file completes processing the request.
The recommended scope for most objects is page scope. You can change
the scope of an object, however, to make it accessible from scripts on other
pages. This topic explains how to work with page scope objects and how to
change the scope of objects.
Using Page Scope Objects

An object that you create by using Server.CreateObject or the HTML
<OBJECT> tag on an ASP page exists for the duration of that page. The
object is accessible to any script commands on that page, and it is
released when ASP has finished processing the page. Thus an object has
the scope, or lifetime, of a page.
Creating Objects in Loops
In general, you should avoid creating objects inside a loop. If you must
create objects in a loop, you should manually release the resources used by
an object:
<%
Dim objAd
For i = 0 To 1000
Set objAd = Server.CreateObject("MSWC.AdRotator")
.
.
.
objAd.GetAdvertisement
.
.
.
Set objAd = Nothing
Next
%>

Giving an Object Session Scope

A session-scope object is created for each new session in an application
and released when the session ends; thus, there is one object per active
session. Session scope is used for objects that are called from multiple
scripts but affect one user session. You should give objects session scope
only when needed. If you do use session scope, you must know the
threading model of the component that provides the object because the
threading model affects the performance and security context of the object.
For more information, see Advanced Information: Performance Issues in
this topic.
To give an object session scope, store the object in the ASP Session built-
in object. You can use either the HTML <OBJECT> tag in a Global.asa file
or the Server.CreateObject method on an ASP page to create a session
scope object instance.
In the Global.asa file, you can use the <OBJECT> tag, extended with
RUNAT attribute (which must be set to SERVER) and the SCOPE attribute
(which must be set to Session). The following example creates a session-
scope instance of the Browser Type object of the Browser Capabilities
component:
<OBJECT RUNAT=SERVER SCOPE=Session ID=MyBrowser PROGID="MSWC.BrowserType">

</OBJECT>
Once you have stored the object in the Session object, you can access the
object from any page in the application. The following statement uses the
object instance created by the <OBJECT> tag in the previous example:
<%= If MyBrowser.browser = "IE" and MyBrowser.majorver >= 4 Then . . .%>
On an ASP page, you can also use the Server.CreateObject method to

store an object in the Session built-in object. The following example stores
an instance of the Browser Type object in the Session object.
<% Set Session("MyBrowser") = Server.CreateObject("MSWC.BrowserType") %>
To display browser information in a different .asp file, you first retrieve the
instance of the BrowserType object stored in the Session object, and
then call the Browser method to display the name of the browser:
<% Set MyBrowser = Session("MyBrowser") %>

<%= MyBrowser.browser %>
ASP does not instantiate an object that you declare with the <OBJECT> tag
until that object is referenced by a script command from an .asp file. The
Server.CreateObject method instantiates the object immediately. Thus,
the <OBJECT> tag offers better scalability than the Server.CreateObject
method for session-scope objects.
Giving an Object Application Scope

An application-scope object is a single instance of an object that is created

when the application starts. This object is shared by all client requests.
Some utility objects, such as the objects of the Page Counter Component,
might perform better in application scope, but generally you should use the
alternatives proposed in the following section. In addition, the threading
model affects the performance and security context of the object (see
Advanced Information: Performance Issues in this topic).
To give an object application scope, store the object in the ASP Application
built-in object. You can use either the <OBJECT> tag in a Global.asa file or
the Server.CreateObject method in an .asp file to create an application
scope object instance.
In the Global.asa file, you can use the <OBJECT> tag, extended with
RUNAT attribute (which must be set to Server) and the SCOPE attribute
(which must be set to Application). For example, the following is an
example of using the <OBJECT> tag to create an application-scope
instance of the Ad Rotator object:
<OBJECT RUNAT=SERVER SCOPE=Application ID=MyAds PROGID="MSWC.AdRotator">

</OBJECT>
After storing the Ad Rotator object in Application state, you can access
from any page in you application using a statement such as the following:
<%=MyAds.GetAdvertisement("CustomerAds.txt") %>
Alternatively, in an .asp file, you can use Server.CreateObject to store an

object instance in the Application built-in object, such as in the following
example:
<% Set Application("MyAds") = Server.CreateObject("MSWC.Adrotator")%>
You can display the advertisement in your application's .asp files by

retrieving the instance of the Ad Rotator object from Application state, as
in the following example:
<%Set MyAds = Application("MyAds") %> <%=MyAds.GetAdvertisement

("CustomerAds.txt") %>
Alternatives to Session and Application Scope

In general, you should try to extensively use application or session state
for items or objects that take a long time to initialize, such as dictionary
objects or recordsets. However, if you find that objects in session or
application state are consuming too many resources, such as memory or
database connections, you should seek alternative ways to implement
these objects. For example, the threading model of a component can affect
the performance of objects you create from it, especially objects with
session or application scope.
In many cases, a better solution than creating application or session scope

objects is to use session or application scope variables that pass

information to objects created at the page level. For example, you should
not give an ADO Connection object session or application scope because
the connection it creates remains open for a long time and because your
script no longer takes advantage of connection pooling. You can, however,
store an ODBC or OLE DB connection string in the Session or Application
built-in object and access the string to set a property on the Connection
object instance that you create on a page. In this way, you store frequently
used information in session or application state but you create the object
that uses the information only when needed. For more information about
scoping variables, see Using Variables and Constants.
User-Defined JScript Objects

You can create your own JScript object by defining a constructor function
that creates and initializes the properties and methods of the new object.
The object instance is created when your script uses the new operator to
invoke the constructor. User-defined JScript objects are supported in ASP
server-side scripts and work well when they have page scope. However, you
cannot give a user-defined object application scope. Also, giving a user-
defined JScript object session scope may affect the functionality of the
object. In particular, if an object has session scope, scripts on other pages
can access the object's properties but cannot call its methods. Also, giving
a user-defined JScript object session scope can affect Web application
performance.
Advanced Information: Performance Issues

The threading model of a component may affect the performance of your
Web site. Generally, objects that are marked Both are the recommended
objects to use in .asp files if they will be stored in Session and Application
state. Single-threaded, Apartment, and free-threaded objects are not
recommended.
Because you may not always have control over the threading model of the
objects you use, the following guidelines will help you get the best
performance:
? Page scope objects Objects marked Both or Apartment will give you
the best performance.
? Application scope objects Objects marked Both, that also aggregate
the FreeThreadedMarshaler, will give you the best performance. You
can use either the <OBJECT> tag or the Server.CreateObject method
to store objects marked Both in the Application object. You must use
the HTML <OBJECT> tag with apartment-threaded objects.
? Session scope objects Objects marked Both will give you the best
performance. Using single-threaded or apartment-threaded objects will
cause the Web server to lock the session down to one thread. Free-
threaded objects do not lock down the session, but are slow. You can
use either the <OBJECT> tag or the Server.CreateObject method to
store objects in the Session object.

For more information on threading models and their implications for

component performance, refer to Building Components for ASP.
Sending Content to the Browser

As a script in an ASP page is processed, any text or graphics not enclosed

within ASP delimiters or <SCRIPT> tags is simply returned to the browser.
You can also explicitly send content to the browser by using the Response
object.
Sending Content
To send content to the browser from within ASP delimiters or from a
procedure, use the Write method of the Response object. For example,
the following statement sends a different greeting to the user depending
on whether the user has visited the page before:
<%
If blnFirstTime Then
Response.Write "<H3 ALIGN=CENTER>Welcome to the Overview Page.</H3>"
Else
Response.Write "<H3 ALIGN=CENTER>Welcome Back to the Overview Page.</H3>"
End If
%>
Outside of a procedure, you do not have to use Response.Write to send

content back to the user. Content that is not within scripting delimiters is
sent directly to the browser, which formats and displays this content
accordingly. For example, the following script produces the same output as
the previous script:
<H3 ALIGN=CENTER>
<% If blnFirstTime Then %>
Welcome to the Overview Page.
<% Else %>
Welcome Back to the Overview Page.
<% End If %>
</H3>
Intersperse script commands and HTML when you just need to return output
once or when it is more convenient to add statements to existing HTML
text. Use Response.Write when you do not want to break up a statement
with delimiters or when you want to build the string that is returned to the
browser. For example, you could construct a string of text that builds a
table row with values sent by an HTML form:
Response.Write "<TR><TD>" & Request.Form("FirstName") _

& "</TD><TD>" & Request.Form("LastName") & "</TD></TR>"

Request.Form returns the values sent from an HTML form (see Processing
User Input).
Note The ampersand character (&) is the string-concatenation character

for VBScript. The underscore (_) is the VBScript line-continuation character.
Setting the Content Type

When the Web server returns a file to a browser, it tells the browser what
type of content is contained in the file. This enables the browser to
determine whether it can display the file itself or whether it has to call
another application. For example, if the Web server returns a Microsoft
Excel worksheet, the browser must be able to start a copy of Microsoft
Excel to display the page. The Web server recognizes file types by mapping
the file name extension to a list of MIME (Multipurpose Internet Mail
Extensions) types. For example, to start Microsoft Excel, the browser needs
to recognize the application/vnd.ms-excel MIME type.
You can use the ContentType property of the Response object to set the
HTTP content type string for the content you send to a user. For example,
the following command sets the content type for channel definitions:
<% Response.ContentType = "application/x-cdf" %>
For more information about channels, see Creating Dynamic Channels in

this topic.
Other common content types are text/plain (for content returned as text
instead of interpreted HTML statements), image/gif (for GIF images),
image/jpeg (for JPEG images), video/quicktime (for movies in the Apple
QuickTime® format), and text/xml (for XML documents). In addition, a Web
server or Web browser may support custom MIME types. To see the content
types already defined by your Microsoft Web server, use the Internet
Information Services snap-in, to open the property sheets for your Web
site, click the HTTP Headers tab, and then click the File Types tab. These
file types may be used as a reference when you choose to manually set the
content type with ASP.
Redirecting the Browser

Instead of sending content to a user, you can redirect the browser to
another URL with the Redirect method. For example, if you want to make
sure users have entered your application from a home page so that they
receive a customer ID, you can check to see if they have a customer ID; if
they do not, you can redirect them to the home page.
<%
If Session("CustomerID") = "" Then
Response.Redirect "Register.asp"
End If
%>

server-side scripts which are processed before any content is sent to the
user are said to be buffered. ASP enables you to turn buffering on or off,
and this configuration can greatly affect the behavior of the Redirect
method. Specifically, if you have buffering turned off, then you must
redirect the browser before your page's HTTP headers are returned to the
browser.
Place the Response.Redirect statement at the top of the page, before any
text or <HTML> tags, to ensure that nothing has been returned to the
browser. If you use Response.Redirect after content or headers have been
returned to the browser, you will see an error message. Also note that
Response.Redirect does not need to be followed by Response.End.
If you want to use Response.Redirect from the middle of a page, use it

along with the Response.Buffer property, as explained in the Buffering
Content section in this topic.
Transferring Between .ASP Files

Using Response.Redirect to redirect a browser requires a round-trip,
meaning that the server sends an HTTP response to the browser indicating
the location of the new URL. The browser automatically leaves the server's
request queue and sends a new HTTP request for this URL. The server then
adds this request to the request queue along with other client's requests
that arrived in the meantime. For a busy Web site, round-trips can waste
bandwidth and reduce server performance—especially when the browser is
redirected to a file located on the same sever.
You can use the Server.Transfer method to transfer from one .asp file to
another file located on the same server instead of the Response.Redirect
method. With Server.Transfer you can directly transfer requests for .asp
files without ever leaving the server request queue, thus eliminating costly
round-trips.
For example, the following script demonstrates how you could use
Server.Transfer to jump between the pages of an application depending
on state information:
<%
If Session("blnSaleCompleted") Then
Server.Transfer("/Order/ThankYou.asp")
Else
Server.Transfer("/Order/MoreInfo.asp")
End if
%>
Server.Transfer sends requests from one executing .asp file to another

file. During a transfer, the originally requested .asp file immediately
terminates execution without clearing the output buffer (for more
information, see the Buffering Content section). Request information is
then made available to the destination file when it begins execution.
During execution, this file has access to the same set of intrinsic objects
(Request, Response, Server, Session, and Application) as the originally

requested file.
You can also use Server.Transfer to transfer between .asp files located in
different applications. However, when you transfer to an .asp file located in
another application, the file will behave as if it was part of the application
that initiated the transfer (that is, the file has access only to variables
scoped for the initiating application, not for the application where the file
actually resides). For example, if you transfer from a file located in the
Sales Application to a file located in the Personnel Application, then the
Sales Application effectively borrows this file from the Personnel Application
and runs it as if it were part of the Sales Application.
ASP also provides the Server.Execute command that you can use to
transfer to a file, execute its content, and then return to the file that
initiated the transfer. If you are familiar with VBScript, it will help you to
think of Server.Execute as analogous to a procedure call, except that
instead of executing a procedure, you are executing an entire .asp file.
For example, the following script demonstrates how you could use
Server.Execute to do dynamic inclusion of .asp files:
<%
.
.
.
If blnUseDHTML Then
Server.Execute("DHTML.asp")
Else
Server.Execute("HTML.asp")
End If
.
.
.
%>
As long as the destination file belongs to an application on the same

server, the originating application will transfer to this file, execute its
contents, and then resume executing the file that initiated the transfer.
Just as with Server.Transfer, an executed .asp file behaves as if it were
part of the originating application. Server.Execute, however, will not work
across servers. For more information, see Server.Execute.
Buffering Content
By default, the Web server processes all script commands on a page before
any content is sent to the user. This process is known as buffering. You can
use the Buffer property of the Response object to disable buffering, so
that the Web server returns HTML and the results of scripts as it processes
a page.
The advantage of buffering your .asp files is that you can abort sending a
Web page if, for example, the script processing does not proceed correctly
or if a user does not have appropriate security credentials. Instead, you can
transfer the user to another page using Server.Transfer, or clear the

buffer (using the the Clear method of the Response object) to send
different content to the user. Depending on your application, you may want
to use the Clear method before transferring. The following example uses
both of these methods:
<HTML>
<BODY>
.
.
.
<%
If Request("CustomerStatus") = "" Then
Response.Clear
Server.Transfer("/CustomerInfo/Register.asp")
Else
Response.Write "Welcome back " & Request("FirstName") & "!"
.
.
.
End If
%>
</BODY>
</HTML>
You could also use Response.Buffer to prevent the Web server from
returning the HTTP header before a script can modify the header. Certain
properties and methods, such as Response.Expires and
Response.Redirect, modify the HTTP header.
If the Buffer property in a script is set to TRUE without also calling the
Flush method to immediately send buffered content to the browser, the
server will maintain Keep-Alive requests made by the client. The benefit of
writing scripts in this manner is that server performance is improved
because the server does not have to create a new connection for each
client request (assuming that the server, client, and any proxy servers all
support Keep-Alive requests). However, a potential drawback to this
approach is that buffering prevents the server's response from being sent
to the user until the server has finished processing the entire script. For
long or complicated scripts, users could experience long wait times before
seeing the page.
Buffering is turned on by default for ASP applications. You can use the
Internet Information Services snap-in, to turn off buffering for an entire ASP
application.
Allowing Proxy Servers to Cache Pages

Your application may be sending pages to a client through a proxy server. A
proxy server acts on behalf of client browsers to request pages from Web
sites. The proxy server caches HTML pages so that repeated requests for
the same page can be returned quickly and efficiently to browsers. Having
the proxy server process requests and cache pages reduces the load on the
network and on the Web server.
Although caching works well for many HTML pages, it often does not work

well for ASP pages that contain frequently updated information. For
example, pages that report stock market prices or display inventory for a
high-volume business must provide timely information. Information that is
even one hour old might not be accurate enough. If your application returns
personalized information, such as a custom home page, you want to ensure
that no user sees another user's personal information.
By default, ASP instructs proxy servers not to cache the ASP page itself
(although images, image maps, applets, and other items referenced from
the page are cached). You can allow caching for certain pages by using the
Response.CacheControl property to set the Cache-Control HTTP header
field. The default value of Response.CacheControl is the string "Private",
which prevents proxy servers from caching the page. To allow caching, set
the Cache-Control header field to Public:
<% Response.CacheControl = "Public" %>
Because HTTP headers must be sent to the browser or proxy before any
page content is sent, either put the Response.CacheControl property
before any HTML tags or, if you have disabled buffering, use
Response.Buffer to buffer the page.
The Cache-Control header field is part of the HTTP 1.1 specification. ASP
pages are not cached on proxy servers that support only HTTP 1.0 because
no Expires header field is sent.
Preventing Browsers from Caching Pages

Each browser version has its own rules for determining whether to cache
pages. To prevent a browser from caching ASP pages, use
Response.Expires to set the Expires header:
<% Response.Expires = 0 %>
A value of 0 forces cached pages to expire immediately. Because HTTP

headers must be sent to the browser before any page content is sent,
either put the Response.Expires property before any HTML tags or buffer
the page.
Creating Dynamic Channels

A channel is a Web technology available with Microsoft Internet
Explorer 4.0, or later, that you can use to automatically deliver new or
updated Web content to users. The channel schedules the user's computer
to periodically connect to a server and retrieve updated information. (This
retrieval process is commonly referred to as client pull because information
is "pulled" in, or gathered, from the server.) When new information is made
available at a particular Web site, the content is downloaded to the
browser cache for offline viewing. Clever use of channels for distributing
Web based information (especially on intranets) can help to centralize
information as well as reduce server traffic. For more information about
channels, visit the Microsoft Internet Explorer Web site, at

http://www.microsoft.com/windows/ie/.
Using ASP, you can write scripts that dynamically create channels by
generating a channel definition file. An XML-based channel definition file
(.cdf) describes the organization and update schedule of a channel's
contents. Commands in the .cdf file use syntax similar to HTML tags, so
they are easy to learn and to generate from a script. When you write a
server-side script to create a channel definition file, give the file a .cdx
extension. When ASP reads a file with a .cdx extension, it automatically
sends the application/x-cdf content type, which tells the browser to
interpret the bytes as channel definitions. If you do not use the .cdx
extension, your script must manually set the content type to application/x-
cdf by using Response.ContentType.
Here is an example of how you might use channels. The following HTML
form asks the user to select channels. When submitted, the form calls a
script in a .cdx file to create the channel definitions.
<P> Choose the channels you want. </P>

<FORM METHOD="POST" ACTION="Chan.cdx">
<P><INPUT TYPE=CHECKBOX NAME=Movies> Movies
<P><INPUT TYPE=CHECKBOX NAME=Sports> Sports
<P><INPUT TYPE="SUBMIT" VALUE="SUBMIT">
</FORM>
The script in Chan.cdx builds the channel definitions based on the form
values submitted with the request.
<% If Request.Form("Movies") <> "" Then %>

<CHANNEL>
channel definition statements for the movie pages
</CHANNEL>
<% End If %>
<% If Request.Form("Sports") <> "" Then %>

<CHANNEL>
channel definition statements for the sports pages
</CHANNEL>
<% End If %>
Accessing Server Resources with WebDAV

Distributed Authoring and Versioning (WebDAV), a powerful extension of
the HTTP 1.1 protocol, exposes Web content as a hierarchical file storage
media—similar to a local file system—over an HTTP connection. WebDAV
holds great promise for making the Web into seamless, collaborative
authoring environment. With the IIS 5.0 implementation of WebDAV, you
can enable remote authors to edit, delete, move, search, or apply
attributes to files and directories on your Web server. You can obtain
further details about WebDAV at the Internet Engineering Task Force Web
site, http://www.ietf.org.

Including Files
Server-side include directives give you a way to insert the content of

another file into a file before the Web server processes it. ASP implements
only the #include directive of this mechanism. To insert a file into an .asp
file, use the following syntax:

The virtual and file keywords indicate the type of path you are using to
include the file, and filename is the path and file name of the file you want
to include.
Included files do not require a special file name extension; however, it is

considered good programming practice to give included files an .inc
extension to distinguish them from other types of files.
Using the Virtual Keyword

Use the virtual keyword to indicate a path beginning with a virtual
directory. For example, if a file named Footer.inc resides in a virtual
directory named /Myapp, the following line would insert the contents of
Footer.inc into the file containing the line:

Using the File Keyword

Use the file keyword to indicate a relative path. A relative path begins with
the directory that contains the including file. For example, if you have a file
in the directory Myapp, and the file Header1.inc is in Myapp\Headers, the
following line would insert Header1.inc in your file:

Note that the path to the included file, Headers\header1.inc, is relative to

the including file; if the script containing this #include statement is not in
the directory /Myapp, the statement would not work.
You can also use the file keyword with the syntax (..\) to include a file
from a parent, or higher-level, directory if the Enable Parent Paths option
is selected in the Internet Information Services snap-in.
Location of Included Files

ASP detects changes to an included file regardless of its location and
inserts the files content the next time a browser requests an .asp file which

includes this file. However, in general, it is easier to secure include files if

they reside within the same application or Web site. For better security, it
is advisable to place include files in a separate directory within your
application, such as \Includes, and apply only appropriate Execute (Web
server) permissions.
Important By default, Web server Read permissions are applied to all

files. However, to prevent users from viewing the contents of your include
files, disable Read permissions for the Include directory.
Including Files: Tips and Cautions

An included file can, in turn, include other files. An .asp file can also
include the same file more than once, provided that the #include directives
do not cause a loop. For example, if the file First.asp includes the file
Second.inc, Second.inc must not in turn include First.asp. Nor can a file
include itself. ASP detects such loop or nesting errors, generates an error
message, and stops processing the requested .asp file.
ASP includes files before executing script commands. Therefore, you cannot
use a script command to build the name of an included file. For example,
the following script would not open the file Header1.inc because ASP
attempts to execute the #include directive before it assigns a file name to
the variable name.


<% name=(header1 & ".inc") %>

Scripts commands and procedures must be entirely contained within the

script delimiters <% and %>, the HTML tags <SCRIPT> and </SCRIPT>, or
the HTML tags <OBJECT> and </OBJECT>. That is, you cannot open a
script delimiter in an including .asp file, then close the delimiter in an
included file; the script or script command must be a complete unit. For
example, the following script would not work:


<%
For i = 1 To n
statements in main file

Next
%>
The following script, however, would work:
<%
For i = 1 to n
statements in main file
%>

<% Next %>
Note If the file that your ASP script includes contains a large number of

functions and variables that are unused by the including script, the extra
resources occupied by these unused structures can adversely affect
performance, and ultimately decrease the scalability of your Web
application. Therefore, it is generally advisable to break your include files
into multiple smaller files, and include only those files required by your
server-side script, rather than include one or two larger include files that
may contain superfluous information.
Occasionally, it may be desirable to include a server-side file by using the

HTML <SCRIPT></SCRIPT> tags. For example, the following script includes
a file (by means of a relative path) that can be executed by the server:
<SCRIPT LANGUAGE="VBScript" RUNAT=SERVER SRC="Utils\datasrt.inc"></SCRIPT>
The following table shows the correct syntax for including files with the SRC
attribute by means of either virtual or relative paths:
Type of Syntax Example

Path
Relative SRC="Path\Filename" SRC="Utilities\Test.asp"
Virtual SRC="/Path/Filename" SRC="/MyScripts/Digital.asp"
Virtual SRC="\Path\Filename" SRC="\RegApps\Process.asp"
Note You should not put any programmatic logic between the <SCRIPT>
tags when including by this method; use another set of <SCRIPT> tags to
add such logic.
Managing Sessions
One of the challenges to developing a successful Web application is

maintaining user information over the course of a visit, or session, as the
user travels from page to page in an application. HTTP is a stateless
protocol, meaning that your Web server treats each HTTP request for a
page as an independent request; the server retains no knowledge of
previous requests, even if they occurred only seconds prior to a current
request. This inability to remember previous requests means that it is this
difficult to write applications, such as an online catalog, where the
application may need to track the catalog items a user has selected while
jumping between the various pages of the catalog.
ASP provides a unique solution for the problem of managing session

information. Using the ASP Session object and a special user ID generated
by your server, you can create clever applications that identify each visiting
user and collect information that your application can then use to track user
preferences or selections.

Important ASP assigns the user ID by means of an HTTP cookie, which is

a small file stored on the user's browser. So, if you are creating an
application for browsers that do not support cookies, or if your customers
might set their browsers to refuse cookies, you should not use ASP's
session management features.
Starting and Ending Sessions

A session can begin in four ways:
? A new user requests a URL that identifies an .asp file in an

application, and the Global.asa file for that application includes a
Session_OnStart procedure.
? A user stores a value in the Session object.
? A new session automatically starts whenever the server receives a
request that does not contain a valid SessionID cookie.
? A user requests an .asp file in an application, and the application’s
Global.asa file uses the <OBJECT> tag to instantiate an object with
session scope. See Using Components and Objects for more
information about using the <OBJECT> tag to instantiate an object.
A session automatically ends if a user has not requested or refreshed a

page in an application for a specified period of time. This value is 20
minutes by default. You can change the default for an application by
setting the Session Timeout property on the Application Options property
sheet in the Internet Information Services snap-in. Set this value according
to the requirements of your Web application and the memory capacity of
your server. For example, if you expect that users browsing your Web
application will linger on each page for only a few minutes, then you may
want to significantly reduce the session timeout value from the default. A
long session timeout period can result in too many open sessions, which
can strain your server's memory resources.
If, for a specific session, you want to set a timeout interval that is shorter
than the default application timeout, you can also set the Timeout
property of the Session object. For example, the following script sets a
timeout interval of 5 minutes.
<% Session.Timeout = 5 %>
You can also set the timeout interval to be greater than the default value,
the value determined by the Session Timeout property.
Note Timeout only applies to sessions that have state. During a

stateless session the Session object does not contain content or static
objects. This type of session automatically ends after the request is
processed and is recreated on the next request from the same browser.
Alternatively, to deliberately end a session you can use the Abandon

method of the Session object. For example, you can provide a Quit button
on a form with the ACTION parameter set to the URL of an .asp file that
contains the following command.

<% Session.Abandon %>
Note A user's requests that are queued up for execution prior to initiating
Session.Abandon will execute within the context of the session being
abandoned. After Session.Abandon has completed execution, new
incoming requests will not be associated with the session.
About SessionID and Cookies

The first time a user requests an .asp file within a given application, ASP
generates a SessionID. A number produced by a complex algorithm, the
SessionID uniquely identifies each user's session. At the beginning of a
new session, the server stores the Session ID in the user's Web browser as
a cookie.
The SessionID cookie is similar to a locker key in that, as the user interacts
with an application during a session, ASP can store information for the user
in a "locker" on the server. The user's SessionID cookie, transmitted in the
HTTP request header, enables access to this information in the way that a
locker key enables access to a locker's contents. Each time that ASP
receives a request for a page, it checks the HTTP request header for a
SessionID cookie.
After storing the SessionID cookie in the user's browser, ASP reuses the
same cookie to track the session, even if the user requests another .asp
file, or requests an .asp file running in other application. Likewise, if the
user deliberately abandons or lets the session timeout, and then proceeds
to request another .asp file, ASP begins a new session using the same
cookie. The only time a user receives a new SessionID cookie is when the
server administrator restarts the server, thus clearing the SessionID
settings stored in memory, or the user restarts the Web browser.
By reusing the SessionID cookie, ASP minimizes the number of cookies sent
to the browser. Additionally, if you determine that your ASP application
does not require session management, you can prevent ASP from tracking
session and sending SessionID cookies to users.
ASP will not send the session cookies under the following conditions:
? If an application has session state disabled.

? If an ASP page is defined as sessionless, that is, a page containing
the
<%@ EnableSessionState=False %>
tag. For more information, see Sessionless ASP Pages.
You should also note that SessionID cookies are not intended to provide a
permanent means for tracking users across multiple visits to a Web site.
The SessionID information stored in the server computer's memory can be
easily lost. If you want track users who visit your Web application over a
longer periods, you must create a user identification by storing a special

cookie in a user's Web browser and saving the cookie information to a

database. For more information, see Using Cookies.
Storing and Removing Data from the Session

object
The Session object provides a dynamic, associative array into which you
can store information. You can store scalar variables and object variables
into the Session object.
To store a variable in the Session object, assign a value to a named entry

in the Session object. For example, the following command stores two new
variables in the Session object:
<%
Session("FirstName") = "Jeff"
Session("LastName") = "Smith"
%>
To retrieve information from the Session object, access the named entry.
For example, to display the current value of Session("FirstName"):
Welcome <%= Session("FirstName") %>
You can store user preferences in the Session object, and then access that
preference to determine what page to return to the user. For example, you
can allow a user to specify a text-only version of your content in the first
page of the application and apply this choice on all subsequent pages that
the user visits in this application.
<% If Session("ScreenResolution") = "Low" Then %>

This is the text version of the page.
<% Else %>
This is the multimedia version of the page.
<% End If %>
You can also store an object instance in the Session object, although doing
so can affect server performance. For more information, see Setting Object
Scope.
At times, it may be desirable to delete items stored in the Session object.

For example, it is not uncommon for users visiting an online retail store to
change their minds, abandon a list of purchase items, and decide on a
completely different set of selections. In such a case it may be expedient
to update the Session object by deleting inappropriate values.
The Session object's Contents collection contains all of the variables that
have been stored (that is, those stored without using the HTML <OBJECT>
tag) for a session. By using the Contents collection's Remove method, you
can selectively remove a reference to a variable that was added for the
session state. The following script illustrates how to use the Remove
method to purge an item, in this case user discount information, from the
Session object:

<%
If Session.Contents("Purchamnt") <= 75 then
Session.Contents.Remove("Discount")
End If
%>
If desirable, you can also use the Contents collection's RemoveAll method
to completely remove all variables stored for the session:
Session.Content.RemoveAll()
Using the Remove method you can choose to delete items by name or by
index. The following script demonstrates how to cycle through values stored
in the Session object and conditionally remove values by index:
<%
For Each intQuote in Session.Contents
If Session.Contents(intQuote) < 200 Then
Session.Contents.Remove(intQuote)
End If
Next
%>
Managing Sessions Across Multiple Servers

ASP session information is stored on the Web server. A browser must
request pages from the same Web server for scripts to access session
information. On cluster of Web servers (where many Web servers share the
responsibility for responding to user requests) user requests will not always
be routed to the same server. Instead, special software distributes all
requests for the site URL to whichever server is free, a process called load
balancing. Load balancing makes it difficult to maintain session information
on a cluster of Web servers.
To use ASP session management on a load-balanced site, you must ensure

that all requests within a user session are directed to the same Web
server. One way to do this is to write a Session_OnStart procedure that
uses the Response object to redirect the browser to the specific Web
server on which the user's session is running. If all links in your application
pages are relative, future requests for a page will be routed to the same
server.
For example, a user might access an application by requesting the general

URL for a site: http://www.microsoft.com. The load balancer routes the
request to a specific server, for example, server3.microsoft.com. ASP
creates a new user session on that server. In the Session_OnStart
procedure, the browser is redirected to the specified server:
<% Response.Redirect("http://server3.microsoft.com/webapps/firstpage.asp") %>
The browser will request the specified page, and all subsequent requests
will be routed to the same server as long as specific server names are not
referenced in the original URLs.

Using Cookies
A cookie is a token that the Web server embeds in a user's Web browser to
identify the user. The next time the same browser requests a page, it
sends the cookie it received from the Web server. Cookies allow a set of
information to be associated with a user. ASP scripts can both get and set
the values of cookies by using the Cookies collection of the Response and
Request objects.
Setting Cookies
To set the value of a cookie, use Response.Cookies. If the cookie does

not already exist, Response.Cookies creates a new one. For example, to
send a cookie named ("VisitorID") with an associated value ("49") to the
browser, use the following command, which must appear on your Web page
before the <HTML> tag:
<% Response.Cookies("VisitorID") = 49 %>
If you want a cookie to be used only during the current user session, then
sending the cookie to the browser is all you need to do. However, if you
want to identify a user even after the user has stopped and restarted the
browser, you must force the browser to store the cookie in a file on the
client computer's hard disk. To save the cookie, use the Expires attribute
for Response.Cookies and set the date to some date in the future:
<%
Response.Cookies("VisitorID") = 49
Response.Cookies("VisitorID").Expires = "December 31, 2001"
%>
A cookie can have multiple values; such a cookie is called an indexed

cookie. An indexed cookie value is assigned a key; you can set a particular
cookie key value. For example:
<% Response.Cookies("VisitorID")("49") = "Travel" %>
If an existing cookie has key values but Response.Cookies does not

specify a key name, then the existing key values are deleted. Similarly, if
an existing cookie does not have key values but Response.Cookies
specifies key names and values, the existing value of the cookie is deleted
and new key-value pairs are created.
Getting Cookies
To get the value of a cookie, use the Request.Cookies collection. For

example, if the user HTTP request sets VisitorID=49, then the following
statement retrieves the value 49:
<%= Request.Cookies("VisitorID") %>
Similarly, to retrieve a key value from an indexed cookie, use the key name.

For example, if a user's browser sends the following information in the

HTTP request header:
Cookie: VisitorID=49=Travel
The following statement would then return the value Travel:
<%= Request.Cookies("VisitorID")("49") %>
Setting Cookie Paths
Each cookie stored by ASP on the user's Web browser contains path
information. When the browser requests a file stored in the same location
as the path specified in the cookie, the browser automatically forwards the
cookie to the server. By default, cookie paths correspond to the name of
the application containing the .asp file that originally generated the cookie.
For example, if an .asp file, residing in an application called
UserApplication, generates a cookie, then each time a user's Web browser
retrieves any file residing in that application, the browser will forward the
cookie, in addition to any other cookies containing the
path /UserApplication.
To specify a path for a cookie other than the default application path, you
can use the ASP Response.Cookies collection's Path attribute. For
example, the following script assigns the path SalesApp/Customer/Profiles/
to a cookie called Purchases:
<%
Response.Cookies("Purchases") = "12"
Response.Cookies("Purchases").Expires = "January 1, 2001"
Response.Cookies("Purchases").Path = "/SalesApp/Customer/Profiles/"
%>
Whenever the Web browser containing the Purchases cookie requests a file
residing in the path /SalesApp/Customer/Profiles/ or in any of it
subdirectories, the browser forwards the cookie to the server.
Many Web browsers, including Microsoft Internet Explorer version 4.0, or

later, and Netscape browsers, preserve the case of the cookie path. This
means that if the case of the path of a requested file differs from the case
of the stored cookie path, the browser will not send the cookie to the
server. For example, to ASP, the virtual directories /TRAVEL and /travel are
the same ASP application, but to a browser that preserves the case of a
URL, /TRAVEL and /travel are two different applications. Make sure all URLs
to .asp files have the same case to ensure that the user's browser forwards
stored cookies.
You can use the following statement to set the cookie path so that the
user's Web browser will forward a cookie whenever the browser requests a
file from your server, regardless of application or path:
Response.Cookies("Purchases").Path = "/"
Note, however, that forwarding cookies to the server, without

distinguishing between applications, raises a potential security concern if

the cookies contain sensitive information that should not be accessible
outside of a specific application.
Preserving State without Cookies
Not all browsers support cookies. Even with browsers that do support
cookies, some users prefer to turn off cookie support. If your application
needs to be responsive to browsers that don't support cookies, you cannot
use ASP session management.
In this case, you must write your own mechanism to pass information from
page to page in your application. There are two general ways to do this:
? Add parameters to a URL's query string. For example:
http://MyServer/MyApp/start.asp?name=Jeff
Some browsers, however, will discard any explicit parameters passed

in a query string if a form is submitted with the GET method.
? Add hidden values to a form. For example, the following HTML form
contains a hidden control, which does not appear on the actual form
and remains invisible in the user's Web browser. The form passes a
user identification value, in addition to the information supplied by the
user, by using the HTTP POST method.
<FORM METHOD="POST" ACTION="/scripts/inform.asp">

<INPUT TYPE="text" NAME="city" VALUE="">
<INPUT TYPE="text" NAME="country" VALUE ="">
<INPUT TYPE="hidden" NAME="userid" VALUE= <%= UserIDNum(i) %>
<INPUT TYPE="submit" VALUE="Enter">
This method requires all link destinations that pass user information
to be coded as HTML forms.
If you are not using ASP session management, you should turn off session
support for your application. When sessions are enabled, ASP sends a
SessionID cookie to each browser that requests a page. To turn off session
support, clear the Enable Session State check box on the Application
Options property sheet in the Internet Information Services snap-in.
Sessionless ASP Pages

With ASP, you can also create sessionless pages which can be used to put
off the creation of sessions tracking until needed.
Sessionless pages do not carry out the following:
? Execute Session_OnStart procedures.

? Send session ID cookies.
? Create Session objects.
? Access built-in Session objects or session scope objects created with

the <OBJECT> tag.

? Serialize execution with other session requests.
To configure an .asp file as sessionless, use the following:
<%@ EnableSessionState=False %>
You should place this script as the first line in your .asp file, before any
other scripts. The default, when this tag is omitted, enables session
tracking.
Sessionless ASP pages can often improve the responsiveness of your server
by eliminating potentially time consuming session activity. For example,
consider the case of an ASP page containing two HTML frames: frames 1
and 2, both within one frameset. Frame 1 contains an .asp file that
executes a complex script, while frame 2 contains a simpler .asp file.
Because ASP executes session requests in sequential order, or serially, you
will not be able to see the contents of frame 2 until the script in frame 1
has executed. However, if you make the .asp file for frame 1 sessionless,
then ASP requests will no longer be serialized and the browser will render
the contents of frame 2 before the contents of frame 1 have finished
executing.
Unfortunately, the way in which multiple requests for different frames are
processed ultimately depends on the configuration of the user's Web
browser. Certain Web browsers may serialize requests despite the
sessionless configuration of your .asp files.
Accessing a Data Source

ActiveX Data Objects (ADO) are an easy-to-use yet extensible technology

for adding database access to your Web pages. You can use ADO to write
compact and scalable scripts for connecting to OLE DB compliant data
sources, such as databases, spreadsheets, sequential data files, or e-mail
directories. OLE DB is a system-level programming interface that provides
standard set of COM interfaces for exposing database management system
functionality. With ADO's object model you can easily access these
interfaces (using scripting languages, such as VBScript or JScript) to add
database functionality to your Web applications. In addition, you can also
use ADO to access Open Database Connectivity (ODBC) compliant
databases.
If you are a scripter with a modest understanding of database connectivity,

you will find ADO's command syntax uncomplicated and easy-to-use. If you
are an experienced developer you will appreciate the scalable, high-
performance access ADO provides to a variety of data sources.
For more information about ADO, visit the Microsoft Universal Data Access

(UDA) Web site at http://www.microsoft.com/data/.
Creating a Connection String

The first step in creating a Web data application is to provide a way for
ADO to locate and identify your data source. This is accomplished by means
of a connection string, a series of semicolon delimited arguments that
define parameters such as the data source provider and the location of the
data source. ADO uses the connection string to identify the OLE DB
provider and to direct the provider to the data source. The provider is a
component that represents the data source and exposes information to
your application in the form of rowsets.
The following table lists OLE DB connection strings for several common
data sources:
Data OLE DB Connection String

Source
Microsoft® Provider=Microsoft.Jet.OLEDB.4.0;Data
Access Source=physical path to .mdb file
Microsoft Provider=SQLOLEDB.1;Data
SQL Server Source=path to database on server
Provider=MSDAORA.1;Data
Oracle
Source=path to database on server
Microsoft
Provider=MSIDXS.1;Data Source=path
Indexing
to file
Service
To provide for backward compatibility, the OLE DB Provider for ODBC

supports ODBC connection string syntax. The following table lists commonly
used ODBC connection strings:
Data ODBC Connection String

Source
Driver
Microsoft Driver={Microsoft Access Driver
Access (*.mdb)};DBQ=physical path to .mdb file
SQL DRIVER={SQL Server};SERVER=path to
Server server
DRIVER={Microsoft ODBC for
Oracle
Oracle};SERVER=path to server
Driver={Microsoft Excel Driver
Microsoft
(*.xls)};DBQ=physical path to .xls file;
Excel
DriverID=278

Driver={Microsoft Excel Driver

Microsoft
(*.xls)};DBQ=physical path to .xls
Excel 97
file;DriverID=790
Driver={Microsoft Paradox Driver
Paradox (*.db)};DBQ=physical path to .db
file;DriverID=26
Driver={Microsoft Text Driver
Text (*.txt;*.csv)};DefaultDir=physical path
to .txt file
Microsoft
Visual
Driver={Microsoft Visual FoxPro
FoxPro®
Driver};SourceType=DBC;SourceDb=physical
(with a
path to .dbc file
database
container)
Microsoft
Visual
FoxPro Driver={Microsoft Visual FoxPro
(without Driver};SourceType=DBF;SourceDb=physical
a path to .dbf file
database
container)
Note Connection strings that use a UNC path to refer to a data source
located on a remote computer can pose a potential security issue. To
prevent unauthorized access of your data source, create a Windows account
for computers requiring access to the data and then apply appropriate NTFS
permissions to the data source.
Advanced Issues to Consider When Designing

Web Data Applications
For performance and reliability reasons, it is strongly recommended that
you use a client-server database engine for the deployment of data driven
Web applications that require high-demand access from more than
approximately 10 concurrent users. Although ADO works with any OLE DB
compliant data source, it has been extensively tested and is designed to
work with client server databases such as Microsoft SQL Server or Oracle.
ASP supports shared file databases (Microsoft Access or Microsoft FoxPro)

as valid data sources. Although some examples in the ASP documentation
use a shared file database, it is recommended that these types of
database engines be used only for development purposes or limited
deployment scenarios. Shared file databases may not be as well suited as
client-server databases for very high-demand, production-quality Web
applications.
If you are developing an ASP database application intended to connect to a

remote SQL Server database you should also be aware of the following

issues:
? Choosing Connection Scheme for SQL Server You can choose

between the TCP/IP Sockets and Named Pipes methods for accessing a
remote SQL Server database. With Named Pipes, database clients
must be authenticated by Windows before establishing a connection,
raising the possibility that a remote computer running named pipes
might deny access to a user who has the appropriate SQL Server
access credentials, but does not have a Windows user account on that
computer. Alternatively, connections using TCP/IP Sockets connect
directly to the database server, without connecting through an
intermediary computer—as is the case with Named Pipes. And because
connections made with TCP/IP Sockets connect directly to the
database server, users can gain access through SQL Server
authentication, rather than Windows authentication.
? ODBC 80004005 Error If the connection scheme for accessing SQL
Server is not set correctly, users viewing your database application
may receive an ODBC 80004005 error message. To correct this
situation, try using a local named pipe connection instead of a network
named pipe connection if SQL Server is running on the same computer
as IIS. Windows 2000 security rules will not be enforced because the
pipe is a local connection rather than a network connection, which can
be impersonated by the anonymous user account. Also, in the SQL
Server connection string (either in the Global.asa file or in a page-level
script), change the parameter SERVER=server name to SERVER=
(local). The keyword (local) is a special parameter recognized by the
SQL Server ODBC driver. If this solution does not work, then try to use
a non-authenticated protocol between IIS and SQL Server, such as
TCP/IP sockets. This protocol will work when SQL Server is running
locally or on remote computer.
Note To improve performance when connecting to a remote

databases, use TCP/IP Sockets.
? SQL Server Security If you use SQL Server's Integrated or Mixed

security features, and the SQL Server database resides on a remote
server, you will not be able to use integrated Windows authentication.
Specifically, you cannot forward integrated Windows authentication
credentials to the remote computer. This means that you may have to
use Basic authentication, which relies on the user to provide user
name and password information.
For more information about these issues, visit the Microsoft Product
Support Services Web site at http://www.microsoft.com/support/.
Connecting to a Data Source

ADO provides the Connection object for establishing and managing
connections between your applications and OLE DB compliant data sources
or ODBC compliant databases. The Connection object features properties
and methods you can use to open and close database connections, and to
issue queries for updating information.

To establish a database connection, you first create an instance of the

Connection object. For example, the following script instantiates the
Connection object and proceeds to open a connection:
<%
'Create a connection object.
Set cnn = Server.CreateObject("ADODB.Connection")
'Open a connection using the OLE DB connection string.
cnn.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\MarketData\ProjectedSales.mdb
%>
Note The connection string does not contain spaces before or after the
equal sign (=).
In this case, the Connection object's Open method refers to the

connection string.
Executing SQL Queries with the Connection

Object
With the Execute method of the Connection object you can issue
commands to the data sources, such as Structured Query Language (SQL)
queries. (SQL, an industry standard language for communicating with
databases, defines commands for retrieving and updating information.) The
Execute method can accept parameters that specify the command (or
query), the number of data records affected, and the type of command
being used.
The following script uses the Execute method to issue a query in the form
of a SQL INSERT command, which inserts data into a specific database
table. In this case, the script block inserts the name Jose Lugo into a
database table named Customers.
<%
'Define the OLE DB connection string.
strConnectionString = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\Employees.md
'Instantiate the Connection object and open a database connection.

cnn.Open strConnectionString
'Define SQL SELECT statement.

strSQL = "INSERT INTO Customers (FirstName, LastName) VALUES ('Jose','Lugo')"
'Use the Execute method to issue a SQL query to database.

cnn.Execute strSQL,,adCmdText + adExecuteNoRecords
%>
Note that two parameters are specified in the statement used to execute
the query: adCmdText and adExecuteNoRecords. The optional
adCmdText parameter specifies the type of command, indicating that the
provider should evaluate the query statement (in this case, a SQL query) as
a textual definition of a command. The adExecuteNoRecords parameter

instructs ADO to not create a set of data records if there are no results
returned to the application. This parameter works only with command types
defined as a text definition, such as SQL queries, or stored database
procedures. Although the adCmdText and adExecuteNoRecords
parameters are optional, you should specify theses parameters when using
the Execute method to improve the performance of your data application.
Important ADO parameters, such as adCmdText, need to be defined

before you can use them in a script. A convenient way to define parameters
is to use a component type library, which is a file containing definitions for
all ADO parameters. To implement a component type library, it must first
be declared. Add the following the <METADATA> tag to your .asp file or
Global.asa file to declare the ADO type library:

<% SQL = "SELECT CompanyName, City FROM Customers" Cnn = "DSN=AdvWorks" rsCustomers.Cur
Set myCustomers = Application("rsCustomers").Clone Set CompanyName = myCustomers("Compa
Do Until myCustomers.EOF%><B><%= CompanyName %></B> is located in <B><%= City %></B>.<P>
<%
myCustomers.MoveNext
Loop
%>

The application's Global.asa file creates the recordset and adds it to the application space. The ASP
script then populates the recordset and makes it connectionless by setting the ActiveConnection
property to Nothing. The ASP script then clones this recordset and iterates through its values, which is
much faster than accessing the database itself. This technique is appropriate only if you know that the
data that will be used to populate the recordset is relatively stable.
Client Capabilities
One of the more significant design decisions you will make is how your application will handle differing
client capabilities. For example, one of the most important issues for users is the speed of the connection.
If your application can determine this speed, it can adjust the response to match that capacity. The only
way for your application to be aware of the current connection speed is if the client includes this
information as part of its request.
You can solve the client capabilities problem on either the client side or server side. The client-side
solution relies on Dynamic HTML (DHTML) to include a description of the client's current configuration
as part of the request, as depicted in the graphic below.
The benefits of this approach include:
? Reduction in roundtrips between the client and server.

? Reduced load on the server.
? Improved application responsiveness due to proxy server caching technology.
There are some situations where client-side scripting will not be feasible. For example, applications that
are exposed on the Internet cannot guarantee that the client will support scripting, which means the
applications may fail for some clients. In addition, server-side resources may not be accessible from the
client side, as the client may reside on a network that does not allow scripting for security reasons.
The server-side approach relies on the Browser Capabilities component. This component reads the User
Agent HTTP header included with the request to determine the client's capabilities. The version of the
Browser Capabilities component that shipped with IIS 3.0 and 4.0 determined client capabilities by
looking them up in a static list. The following graphic shows the sequence of events.

This approach presented difficulties for application designers when the list became out of date. More
importantly, this technique did not cover configurable aspects of a client's capabilities and did not provide
a means of what was actually enabled at the time the request was made.
In IIS 5.0 the Browser Capabilities component has been improved to overcome these earlier design
limitations. The Browser Capabilities component can now be modified for an individual request by the
client returning a cookie describing its capabilities. In addition, if the initial request for an .asp file does
not include a cookie, you can call back to a script that will run on the client to create the cookie. The
following illustration shows the sequence of events.
This improvement to the Browser Capabilities component creates another alternative to the server-side
solution. This technique uses a special status code to call back to the client when a request comes in that
does not include a cookie. You can generate this status code by placing a special meta tag as the first line
in your .asp file. For example:

instructs IIS to send the special status code—an HTTP 449 status code—to Internet Explorer 5.0; it
then tells Internet Explorer 5.0 to run the script in Sendcook.htm, which will generate a cookie describing
the client capabilities. When the server receives this cookie, it will use the cookie in conjunction with the
Browser Capabilities component to determine how to send the response back to the client.
Important If the METADATA meta tag exists in a file that is requested by the client as a result of a
redirection using the Server.Transfer or Server.Execute methods, IIS will ignore the meta tag.
METADATA meta tags in the file that actually contains the redirect, however, will be processed
normally.
For more details on how to use this feature, see Retrieving Browser Capabilities from a Cookie.
For more information on DHTML client capabilities, see the DHTML reference information on the Site

Builder Network. The SBN home page is at www.microsoft.com/sitebuilder/. For an example of the
new Client Capabilities component functionality, see the Browser Capabilities Component and ASP
Samples.
Accommodating International Clients

One of the advantages of distributing information over the Internet or an intranet is that you can create
international Web sites that users can access from different countries. Users can request pages that have
been localized into their own language, which they read in localized browser versions.
When you create a Web site that contains pages in different languages, you may need to convert strings
that are passed between the browser and the Web server, or between an ASP script and a COM
component. If all pages on the Web site are written in the default character set used by the Web server,
ASP does the conversion automatically. If you author pages in different character sets, however, you
need to use ASP commands that specify how the strings should be converted. For example, if your site
contains some pages in one of the Japanese character sets and others in one of the Chinese character
sets, you need to specify which character set ASP should use while processing strings for a particular
page.
ASP also provides commands that support the cultural conventions for different locales, such as the
format used for currency, time, and date. As with the string conversion commands, you need to use the
locale commands only if your scripts do not use the default locale for the Web server. For more
information, see the following topics.
? Setting the Code Page for String Conversions: Includes sample code for converting strings used
by ASP.
? Setting the Locale Identifier: Describes how to change the format used for currency, time, and
date.
Setting the Code Page for String Conversions

A code page is an internal table that the operating system uses to map symbols (letters, numerals, and
punctuation characters) to a character number. Different code pages provide support for the character
sets used in different countries. Code pages are referred to by number; for example, code page 932
represents the Japanese character set, and code page 950 represents one of the Chinese character sets.
Active Server Pages, and the script engines it supports, internally use Unicode, a 16-bit fixed-width
character encoding standard. If you author all of your pages in the default code page of the Web server,
ASP automatically converts strings. If your script was not created in the Web server's default code page,
however, you need to specify the code page so that strings are correctly converted as they are passed:
? Between ASP and the script.

? Between the browser and your script.

? Between COM components and your script.
To specify the code page for an ASP page, use the @ CODEPAGE directive. For example, to set the
code page to Japanese, use the following directive:
<%@ CODEPAGE = 932 %>
As ASP processes the content and script on this page, it uses the code page you have specified to
convert characters from your script's character set into Unicode. For example, the value that refers to the
letter "a" in ANSI will be converted into the different value that refers to the letter "a" in Unicode.
Active Server Pages assumes that strings passed between the Web server and the browser, or between
your script and COM components, are in the same code page you have set for your script. If you need
to specify a different code page, you can set the Session.CodePage property to override the
CODEPAGE setting. For example, you may have authored your script in JIS but need to respond to a
client that is using UTF-8 (two different character encodings for the standard Japanese character set).
Session.CodePage defaults to the value of the @ CODEPAGE directive; setting it overrides the current
CODEPAGE setting. For example, to change the code page to one of the Chinese character sets, use
the following command:
<% Session.CodePage = 950 %>
If you are temporarily changing the code page for a portion of your script, be sure to set
Session.CodePage back to its original value. The following script shows how to temporarily change the
code page:

<OBJECT classid="clsid:BD96C556-65A3-11D0-983A-00C04FC29E33" ID=ADC1></OBJECT>

<OBJECT ID="ADS1" WIDTH=1 HEIGHT=1 CLASSID="CLSID:BD96C556-65A3-11D0-983A-00C04FC29E36">
</OBJECT>
<SCRIPT LANGUAGE="VBScript">
Option Explicit
Sub GetRecords()
Dim objInventory, myRS
Set objInventory =
ADS1.CreateObject("Company.Inventory", _
"http://<%=Request.ServerVariables("SERVER_NAME")%>")
' Inventory exposes a method called
' getQuantityonHand that takes connection string and SQL parameters.
Set myRS = objInventory.getQuantityonHand _
("DSN=pubs;UID=sa;PWD=permission;","Select Quantity From Inventory")
' Assign the returned recordset to SourceRecordset.
ADC1.SourceRecordset = myRS
End Sub
</SCRIPT>
</BODY>
</HTML>
The same issues that are described in Component Design Guidelines, in the IIS documentation in the
Platform SDK, apply to any custom data business components you create to communicate with
RDS.DataControl. For example, you should make sure that the component supports either the
Apartment or Both threading model.
Note Remote Data Service (RDS) replaces the Advanced Data Connector (ADC), which is now
considered obsolete. In particular, the ADC remoting functionality (the ability to manipulate and modify
sets of records on the client) has been integrated into ADO as RDS.
For more information, see the DAO SDK.
Processing Transactions
Transaction processing is an approach to application development that divides all processing into
individual units of work, known as transactions. The integration of IIS and Component Services has
made it easy to create Web applications that support transaction processing. If you are designing a Web
application that will support transaction processing, you will face several basic design decisions. This
section outlines the technology that underlies transactional ASP, as well as some fundamental design

issues.
? Designing Transactional Web Applications: Describes the design requirements for transactional
Web applications.
? Transaction Processing Technology: Provides information on Component Services and Message
Queuing Services (MQS).
Designing Transactional Web Applications

One of the most important design concepts for transactional Web applications is the distinction between
business processes and physical transactions. Business processes are the day-to-day processes of most
organizations; for example, processing a sales order. A physical transaction corresponds to the actual
updating of the data resources that are used to record the business process. A business process will
usually be made up of more than one physical transaction.
For example, when a sales order is processed, there are at least three distinct steps that need to be
accomplished:
? Verify product availability.

? Obtain payment.
? Commit the order.
Each of these steps could represent one or more physical transactions, depending on the system design.
The connectionless nature of the Internet mandates that steps be broken into distinct physical
transactions. When a physical transaction is begun, all other users will be prevented from updating the
resources that participate in the transaction until the transaction completes. Imagine what would happen if
the entire sales order process described above was grouped into a single physical transaction. A user
could begin a transaction by indicating his or her interest in a product, which would lock the customer's
account and mark the product as no longer available in the inventory database. The customer could then
leave his or her browser running while attending to other business, but before committing to the sale.
Because the entire order has been treated as one physical transaction, all of the resources are locked
until either the customer commits, or your system throws out the order due to a business rule. Such a
design is not feasible for a transaction processing system that is exposed on the Web.
The design requirements for transactional Web applications will probably always be presented in terms
of business processes. It is important, therefore, to establish some design techniques for breaking
business processes into physical transactions. One important technique is to always limit physical
transactions to a single .asp file.
Note Business processes can span multiple .asp files, but physical transactions should not.
Another design technique is the use of status codes within transactional resources to indicate if a
transaction is pending or committed. By including status codes you can reserve a resource without

actually committing it. When the business process is complete, you can initiate another physical
transaction that commits all pending resources by changing their status code. The Crawford & Sons
Bicycle Company case study illustrates how these two principles affect the implementation of
transactional Web applications.
The Crawford & Sons Web Application
The Crawford & Sons Custom Bicycle Company is a manufacturer of hand-made bicycles that they
distribute throughout North America. They have decided to begin taking orders for their bicycles through
a Web application. They use Microsoft SQL Server to maintain customer and inventory records and
have already developed data and business-logic components that are registered with Component
Services. Now they need to develop the .asp files that will allow their customers to access these
components within the scope of a single business process. The following diagram illustrates the distinct
physical transactions and the .asp files that make up their Web application design.
The sales order application is made up of four .asp files: Login.asp, Credit.asp, Inventory.asp, and
Commit.asp. Notice that each of the physical transactions is represented by a separate .asp file.
(Each .asp file contains the @Transaction = Required directive.) Login, Credit, and Inventory each
interact with a COM component called Sales Order. Sales Order exposes methods for accomplishing
the three steps of taking an order.
When the customer is ready to commit to the sale (that is, the business process is completed),
Commit.asp groups the entire logical transaction into a single physical transaction which changes all of the
status codes in the data resources from "pending" to "complete." This design accommodates both the
connectionless nature of the Web and the requirement for providing the user with a unified business
process.
For more information on Component Services transactions, see Understanding Transactions . To view
samples of transactional scripting, see ASP Transaction Services in ASP Samples.

Transaction Processing Technology

The primary technology that makes it possible for an ASP to participate in a transaction is Component
Services. Component Services provides IIS with transaction services and an environment for hosting
component instances. One of the benefits of this environment is the ability to create attributes for
individual component instances. When IIS compiles an ASP script, a new instance of the IIS Web
Application Manager (IISWAM) is created. IISWAM is a COM component that IIS uses to manage
applications. If the ASP script contains the @TRANSACTION directive, the instance of IISWAM will
be declared within the transaction environment with an appropriate transaction property. For example, if
you include @TRANSACTION = Required in your ASP script, you are telling Component Services
that the instance of IISWAM that it creates should be run in a transaction. If the ASP script creates
instances of any other components that have been registered with Component Services, Component
Services will treat them as part of the same transaction. The following diagram illustrates the relationship
between ASP and IISWAM.
Component Services provides transaction services to IIS through two different layers. At the lowest
layer, Component Services interacts with the Microsoft Distributed Transaction Coordinator (MS DTC)
to guarantee that transactions meet the ACID properties (Atomic, Consistent, Isolated, Durable) of a
reliable transaction processing system. Component Services links component instances to MS DTC
through two mechanisms: resource managers and resource dispensers. A resource manager is a system
service that manages durable data. Component Services supports resource managers that implement
either the OLE Transactions protocol, such as Microsoft SQL Server 6.5, or the X/Open DTP XA
standard. Resource dispensers are similar to resource managers in that they work with components to
share state information. However, the information they share is not durable. For example, resource
dispensers can manage pools of database connections for components that use standard ODBC
interfaces. The ODBC 3.0 Driver Manager is the resource dispenser for ODBC connections.
For more information on Component Services transactions, see Understanding Transactions . To view
samples of transactional scripting, see ASP Transaction Services in ASP Samples.
Security Ramifications for IIS Applications

Securing Web sites is a critical issue for Web developers. It is also one of the most potentially confusing.

A secure system requires careful planning, and Web site administrators and programmers must have a
clear understanding of the options for securing their site. In addition, they need to understand how all of
the various security subsystems interact.
This section provides an overview of the security issues faced by ASP, component, and ISAPI
developers.
? Accessing Client Certificates with ASP: Describes the use of server-side scripts to access client
certificates.
? Passing Security Context: Outlines the various security contexts that may play a part in request
processing.
? Additional Security Considerations: Discusses the various issues surrounding security in IIS
applications.
Accessing Client Certificates with ASP

With Active Server Pages (ASP), you can create a server-side script that extracts the contents of a
user's client certificate and saves this information in a text file. By adding this script to SSL-secured Web
pages, you can effectively catalog and manage the client certificates of users accessing your server.
For more information see ClientCertificate.
Passing Security Context

Windows establishes a security context for each logged on user. When IIS receives a request from a
client, it authenticates the request and then impersonates the client. While IIS is impersonating the client,
IIS operates within the confines of the authenticated client's security context. This security context may
change during the various stages of request processing, depending on the nature of the client request. The
following diagram illustrates the various security contexts that may play a part in request processing.

The security context of the IIS process (inetinfo) is known as LocalSystem. However, when IIS is
processing a client request, it will impersonate the context of the client that generated the request. If the
client is authenticated with the Anonymous authentication scheme, the security context will be
IUSR_machinename for in process applications and IWAM_machinename for applications running in
an isolated process. If the client is authenticated with any other authentication scheme, the security
context will map to the individual account of the client.
If you create an instance of a COM component with ASP, the COM component will inherit the security
context of the .asp file that created it. When IIS destroys the component instance, it will also use the
security context of the .asp file in most instances. There is at least one case, however, where this will not
occur. If the COM component has been given session scope (that is, Session("mysesscomp") =
Server.CreateObject("MyComps.Comp1")), and the session times out before the component is
destroyed, IIS will try to destroy the component by using its own security context (LocalSystem) rather
than the context of the client that accessed the .asp file. If the component has accessed secured
resources that it has not released, this scenario can have side effects throughout the system.
Additional Security Considerations

Registry Issues
Many IIS applications require resources provided by other software components. For instance, an
ISAPI extension DLL may call an Automation server from a third-party software company, or a CGI
application may launch a program built with Microsoft® Visual Basic®. These components may have
persistent information stored in the registry that they require in order to execute properly. For standard
desktop use of these components, the registry information is read from the profile of the user currently
logged on a computer with Windows. These applications often have problems when launched by IIS
because the profile made available to an IIS application is that of the default user. The default-user profile
is filled with information generic to all users, but is specific to no users. Therefore, a component may run
as expected when User1 executes it on his or her desktop because it is reading information from User1's
profile in the registry. The same application may not run at all from IIS because it will not have access to
User1's profile. This is true even if IIS is impersonating User1's account by using Basic or integrated
Windows authentication.
Desktop Issues
Windows NT 4.0, and Windows 2000 uses the concept of having multiple desktops on the same
computer. A desktop can be thought of as the screen that you view when you are logged on your
computer. Your desktop receives all the mouse and keyboard messages that you send as the user at the
computer, and it allows for applications to interact with one another to a certain extent. For instance, one
application on a desktop can post messages to other applications on the desktop. Support for multiple
desktops implies that there are other desktops running; you just can't see them and you have no way of
sending keyboard or mouse messages to them. This may seem like a futile concept, but, in fact, many

applications that run as Windows services require the capabilities that a desktop provides but don't want
to interact with the interactive user's desktop. Therefore, each service gets its own desktop that won't be
interfered with by the currently logged-on user.
If your IIS application interacts with a desktop in any way (for instance, if it displays a message box),
then it will display that message box on a desktop that cannot be seen on the computer's monitor.
Similarly, an IIS application will not be able to send or post messages to an application on the interactive
desktop. If your IIS application needs to interact with the interactive desktop, then you should use
another form of inter-process communication such as Named Pipes. For more information see
"Interprocess Communication" in the Windows Base Services section of the Platform SDK.
ISAPI Filter DLLs
ISAPI filter DLLs, not to be confused with ISAPI extension DLLs, run in the original context of the IIS
service. All services run by default under the Local System account of the computer on which they are
installed. The Local System account has access to almost all resources on the local computer not
specifically denied to it, and no resources on any other computers on the network.
Development Technologies
Microsoft Windows Distributed interNet Application (Windows DNA) Architecture is a dynamic set of
technologies that you can use to build Web applications. Microsoft has added several key aspects to the
architecture with Windows 2000.
? Component Services: Describes the services used in component and web development.
? Dynamic HTML: Discusses Dynamic Hypertext Markup Language (DHTML).
? Windows Script Components: Outlines using COM components using scripting languages.
? XML: Describes Extensible Markup Language (XML).
? Active Directory Service Interfaces: Discusses the Active Directory Service Interfaces and their
use with IIS.
Component Services
New with Windows 2000, Component Services provides a number of services that make component
and Web application development easier. These services include:
? Component Load Balancing

? Queued Components
? In-Memory Database Support
? Component Services Events

More information will be provided in a later release.
Dynamic HTML
Microsoft introduced Dynamic HTML (DHTML) with Internet Explorer 4.0. DHTML allows you to
create much richer HTML that responds to events on the client. By upgrading your HTML pages to take
advantage of DHTML, you will not only enhance the user experience, you will also build Web
applications that use server resources more efficiently.
DHTML controls the appearance of HTML pages by setting properties in the document object model
(DOM). Microsoft has proposed the DOM to the World Wide Web Consortium (W3C) as a standard.
DHTML exposes an event model that allows you to change DOM properties dynamically. The following
simple example demonstrates subdividing an HTML page with <DIV> tags and setting the display style
property to display the division when the user clicks an input button.
<SCRIPT LANGUAGE = "VBScript">
Sub showit()
'This subroutine is called when the user clicks a select button.
'It displays text in the hidden DIV.
document.all.cdiv.style.display = ""
End Sub
</SCRIPT>
<DIV ID= "MyDiv" style="display: 'none'" >

This is some hidden text.
</DIV>
<Select id= "Showit" onclick=showit>
For more information on DHTML, see the Site Builder Network.
Windows Script Components

Windows Script Components provide you with an easy way to create COM components using scripting
languages such as Microsoft® Visual Basic® Scripting Edition (VBScript) and other languages
compatible with the ECMA 262 language specification (such as Microsoft® JScript® 2.0 and JavaScript
1.1). You can use script components as COM components in applications such as Internet Information
Services (IIS), Microsoft Windows Scripting Host (WSH), and any other application that can support
COM components.
Script component technology is made up of the following:

? The script component run-time (scrobj.dll).

? Interface handlers, which are components that extend the script component run-time. An
interface handler is a compiled component (generally written in C++) that implements specific
COM interfaces. When you install the script component run-time you will receive the Automation
interface handler, which makes it possible to call your script component from an .asp file.
? Your script component file (a .sct file). In your script component, you specify which interface
handler you want to use. Your script component also defines the methods that can be called from
an .asp file to accomplish the intended functionality.
Script components are an excellent technology for developing prototypes of COM components. Script
components are like any other COM component in that they can be registered with Component Services
if you intend for them to participate in transactions or to take advantage of the Component Services run-
time environment. Because they are COM components, script components can access the ASP built-in
objects.
For further details on script components, see the Site Builder documentation on
http://microsoft.com/sitebuilder. For further information on building a script component, see Implementing
with Script Components. For specific examples of script components, see Using Components and
Objects.
XML
Extensible Markup Language (XML), like HTML, allows you to apply markup, in the form of tags, to a
document. However, unlike HTML, XML is designed to be used as a generalized markup language. In
other words, markup applied to an XML document can be used to convey not only display and
formatting information as with HTML, but semantic and organizational structure for the document. This
flexibility makes XML extremely powerful, and the possible range of applications is impressive.
For more information on Microsoft's work with XML, refer to the Internet Client SDK, Microsoft's
XML Web site at http://msdn.microsoft.com/xml, and the XML articles available on Microsoft Site
Builder Network at http://msdn.microsoft.com/workshop/. For more detailed information about XML
and related standards, see the World Wide Web Consortium at http://www.w3.org.
Active Directory Service Interfaces

Microsoft Active Directory Service Interfaces (ADSI) is a COM-based directory service model that
allows ADSI-compliant client applications to access a wide variety of distinct directory protocols,
including Windows® Directory Services, LDAP, and NDS, while using a single, standard set of
interfaces. ADSI shields the client application from the implementation and operational details of the
underlying data store or protocol.

An application called an ADSI provider makes itself available to ADSI client applications. The data
exposed by the provider is organized in a custom namespace, defined by the provider. In addition to
implementing the interfaces defined by ADSI, the provider also can implement the ADSI schema. The
schema is used to provide metadata about the namespace structure and objects that are provided by the
ADSI provider.
For more information about ADSI, refer to the Active Directory Service Interfaces Version 2.0 SDK
and the Active Directory Schema SDK in the Platform SDK.
ADSI and IIS
IIS currently stores most Internet site configuration information in a custom data store called the IIS
metabase. IIS exposes a low-level DCOM interface that allows applications to gain access to, and
manipulate, the metabase. To make it easy to access the metabase, IIS also includes an ADSI provider
that wraps most of the functionality provided by the DCOM interface, and exposes it to any ADSI-
compliant client applications. For more information about using ADSI with IIS, see Using IIS Admin
Objects.
Developing Scalable Web Applications

Performance
In the world of single-user desktop software development, the performance requirements are clearly
defined. In that context, it is important that the user does not experience a significant delay when
performing common tasks.
In the early years of the World Wide Web, slow Web pages were commonplace, and for many users a
long wait was tolerated. However, as more and more enterprise Web applications were created, the
requirements for Web application performance began to rival those of the single-user desktop. Today,
with faster communication technologies becoming prevalent, users are demanding greater increases in site
performance.
Scalability
The real issue in Web application design is that while the application appears to the single user as a
traditional desktop application, it is actually a distributed application that could be simultaneously
servicing hundreds or even thousands of users.
Web applications demand performance under a wide range of environment conditions—in other words,
they must be scalable. Certainly, Web applications must perform well, but good performance when being
used by a single user does not necessarily translate into scalability.
There are many different metrics for determining how scalable an application is. Ideally, a truly scalable
Web application should be able to:
? Serve a single user as well as it can serve hundreds or thousands of simultaneous users.

? Perform twice as well when installed on a computer with twice the resources (processors, RAM,
and so on), perform three times as well on a computer with three times the resources, and so on.
Of course, these scalability requirements are ideals. However, the closer your application comes to
fulfilling those ideals, the more successful your application will be when under load.
Design Considerations for Performance and Scalability
The most important thing to keep in mind when beginning a Web application development project is that
Web applications are, for the most part, server applications. Historically, server software has been
second only to operating system internals in complexity and programming difficulty. IIS and Windows®
offer a variety of innovative tools that make Web application development much faster and easier, but the
concerns and challenges of server software programming still exist.
Some important considerations for making your application scalable include:
? Technology Choices: As with any development platform, Windows offers a number of options
for completing a given task. Making the correct choice of technologies is the first, and often most
important, step in designing a scalable Web application. For example, if a client-side technology
provides the same or similar functionality as provided on the server, the client-side option often
makes more sense; as the application is more scalable because the client handles much of the
processing load. Proper technology choices can also lead to fewer round-trips between the client
and server, further improving performance. For more information, see Web Applications: An
Overview and the Internet Client SDK.
? Language Choices: Choosing a development language impacts your Web application by defining
the range of users who have access to it. For example, including scripting in an application will
exclude users who have browsers that do not support scripting. The following lists some of the
development languages available:
? Windows Script Components
? Visual Basic
? Java
? C++
? Algorithm and Work Flow Design: Even the proper technology, if used improperly, will yield
poor results.
? Multithreading: IIS and Windows provides a multithreaded environment, and in order to create
scalable applications, you must choose the appropriate threading model for your components.
? Resource Contention and Delay: Resource contention and leakage are often major culprits
behind applications that cannot scale.
? "Real-World" Testing: You must be sure to thoroughly test your Web application in an
environment that approximates the actual environment in which the application will be deployed.
A detailed analysis of all of these topics is beyond the scope of this documentation. Instead, in this
section you will find a compilation of notes and procedures, specific to IIS, that will help you create a
scalable Web application.
? Developing Scalable ASP Applications

? Developing Scalable Components
? Designing High-Performance ISAPI Applications
? Data Access Performance

? Performance and Scalability Testing
For more information about designing Web applications, see Design Decisions.
Developing Scalable ASP Applications

Proper Use of ASP
With ASP, you can easily and quickly create Web applications, in a fraction of the time it would take
with a more conventional server-side language, such as C or C++.
However, the ease with which you can create ASP-based applications belies the complexity of the
server processing and client-server interaction required by that application. It is possible that Web
applications that have been created with extensive ASP scripting will not scale well.
To avoid scalability problems, there are two points to keep in mind when developing with ASP:
? ASP is the "Glue"

? ASP should not be used for business logic
The first point emphasizes that ASP dovetails with HTML, client-side scripting using DHTML, and XML
to create a powerful platform for interacting with the user. ASP scripting was designed to be used to bind
the user interface to the business logic of the Web application, and ASP was optimized for these sorts of
tasks.
The second point should serve as an important reminder: If you find that most of your business logic is
embedded into the ASP, your application will probably not scale properly. It is true that ActiveX®
scripting languages, hosted by ASP, are capable of accomplishing a great deal of business logic
processing. However, if the business logic required for your Web application is more than trivial, then
that business logic should be folded into a new COM component, rather than embedded in ASP scripts.
Optimizing ASP on IIS
Once you have established that your use of ASP is appropriate for the design of your application, and
you have encapsulated the bulk of your business logic into COM components, there are two avenues by
which you can further improve the performance and scalability of your Web application:
? ASP Scripting Optimization

? IIS Configuration Optimization
For more information about designing Web applications, see Design Decisions.
ASP Scripting Optimization


Code optimization should be performed carefully. In ASP scripting, as in any other programming
language, it is important to determine which areas of the application are consuming the most time and
resources. This information can then be used to efficiently target the critical area for optimization.
Here are several tips that might help minimize performance problems in your ASP scripts:
? Cache Application-scoped objects and data, either by creating the object in Global.asa, or
creating it on-demand in an individual ASP script, and placing it in Application scope.
? Combine output of Response.Write calls by relying on ASP buffering, which is on by default
with IIS 5.0. In order to improve the perceived performance of applications that use buffered
output while performing time-consuming operations, however, your application should periodically
use Reponse.Flush to maintain contact with the user.
If ASP buffering has been disabled for your Web application, performance may be improved if
you minimize the number of separate calls to Response.Write by combining separate output
strings into one larger string. However, if you must perform extensive string manipulations to
accomplish this, the gain in performance is probably offset by the time spent processing the strings.
? Use <OBJECT> tags instead of Server.CreateObject, when instantiating objects at
Application or Session scope. The reason is that IIS delays actually instantiating the object
specified by <OBJECT> tags until the object is actually put to use. If you use <OBJECT> tags,
and your script never uses the object, then your application will not instantiate the object. In
contrast, Server.CreateObject forces IIS to immediately create an instance of the object,
whether the object is used by the script or not.
? Use local variables, avoid public variables. Local variables can be accessed quicker by the
ASP scripting engine than public variables, because the entire namespace doesn't have to be
searched to access the value of a local variable.
? Use client-side validation of user input, where possible, to minimize the HTTP round trips
required. If the browser is full-featured, harness the power of the browser, and free up server-side
resources for more critical tasks. Of course, some integrity checking still should be performed on
the server, depending on the application, as an extra precaution against data corruption.
? Copy individual values from collections into local variables, if you are going to reference the
value more than once. This saves ASP from having to perform lookup processing in the collection
for each and every reference.
? Turn off session state for the entire application, if possible. If your application does not
require the use of IIS sessions, you should use the Internet Information Services snap-in to disable
session state for the entire application. Sessions in IIS remain in memory, and the memory
allocated to the sessions will not be freed until the session has been terminated or timed-out. If
your application is being used by many concurrent users, the server's resources could become
depleted, and performance could be affected. If some parts of your application don't need session
state, you should disable session state for those pages by using the @ENABLESESSIONSTATE
directive.
Turning off session state whenever possible is especially helpful if the page contains a
<FRAMESET> element. Some browsers, including Internet Explorer, will use separate threads to
process the separate frames of the frameset. If session state is turned on for the frameset page, the
client-side performance benefit of these parallel threads will be lost, because IIS will be forced to
serialize the threads processing the separate requests.
? If you do rely on session state, avoid placing large amounts of data into the Session
object, and into session state. Sessions in IIS are persistent, and the memory allocated to the
sessions will not be freed until the session has been terminated or timed-out. If your application is

being used by many concurrent users, the server's resources could become depleted, and
performance could be affected.
? Do not provide empty Session_OnStart or Session_OnEnd.
? Pay close attention to the effects of IIS and ASP configuration changes. See IIS
Configuration Optimization for more details.
? If your ASP page is running as part of an application, designate the application as out-of-
process for application debugging only. Process isolation, which was introduced in IIS 4.0, is
a useful capability. The cross-process marshalling required to support process isolation, however,
can introduce a certain amount of overhead to ASP processing. This difference in overhead is
most significant for simple ASP pages, and is less of a concern for more complex pages. To
maximize scalability and performance, however, consider running the application out-of-process
only until it is sufficiently debugged and stable to be run in-process with IIS.
? Avoid ReDimming arrays, if possible. It is more efficient to simply allocate the full size of the
array when the array is first initialized.
IIS Configuration Optimization

IIS provides several configuration settings that you can adjust to tune the performance and scalability of
your Web applications. These include:
? AppAllowDebugging
? AspAllowSessionState
? AspEnableChunkedEncoding
? AspEnableTypelibCache
? AspProcessorThreadMax
? AspTrackThreadingModel
? AspRequestQueueMax
? AspQueueConnectionTestTime
? AspSessionMax
? AspBufferingOn
? AspScriptEngineCacheMax
? AspSessionTimeout
? AspThreadGateEnabled
Performance tips are provided in the reference page for each property; click a property in preceding list
to see its reference page.
Developing Scalable Components

Because you should encapsulate most of your business logic within COM components, it is important
that your components be designed for high performance, in addition to being readily scalable.

Here are some suggestions for creating scalable components:
? Optimize your algorithms.

? Make your component adhere to the proper threading. Page-scope components should be
use either the Apartment or Both threading model; application-scope components should use the
Both threading model, and should also aggregate the free-threaded marshaller. For more
information about component threading issues, see the topic Selecting a Threading Model in
the IIS documentation in the Platform SDK.
? If your component uses the heap intensively, consider other heap alternatives. Intensive
use of the Windows® heap can cause resource contention. Several memory allocation alternatives
are worth exploring, including:
? Heap Partitioning, accomplished by creating multiple custom heaps, in addition to the
default process heap. Each custom heap would then be controlled by a separate, non-
global lock, and lock contention would be reduced.
? Cached Allocation, which involves using custom allocation operations that operate at a
middle layer between the object users and the heap. Calls to the Win32 heap are made
infrequently, and only for large memory blocks. These blocks are then subdivided and
managed by the custom allocator.
? Stack Allocation, using the C run-time function _alloca to allocate memory for your
objects on the stack instead of the heap. This method is feasible only for relatively small
objects, because the space available on the stack is limited. In addition, your newly
allocated object will be available only within the current functions, or functions called by that
function. Once the current function returns, the storage allocated on the stack will be lost.
? Object Encapsulation, accomplished by simply incorporating a buffer as a member data
structure of your component class. This buffer is then used for tasks that would otherwise
require accesses to the Win32 heap.
? Avoid using global locks within your component, if possible. Global locks can often adversely
affect component scalability.
? If your component is running as part of an application, designate the application as out-
of-process for application debugging only. Process isolation, introduced in IIS 4.0. is a useful
capability. The cross-process marshalling required to support process isolation, however, can
introduce a certain amount of overhead to component execution. This difference in overhead is
most significant for simple components, and is less of a concern for more complex components.
To maximize scalability and performance, however, consider running the application out-of-
process only until it is sufficiently debugged and stable to be run in-process with IIS.
? Consider placing your component in a library (in-process) COM+ application. As part of
the Just-In-Time activation feature of Component Services, the component's COM class factory is
cached, and reused for each instantiation request through CreateInstance.
Designing High-Performance ISAPI

Applications
ISAPI is the highest-performance interface for Web applications. If you create an ISAPI extension or
filter, chances are that it will outperform ASP scripts or even components performing similar tasks.

However, the inherent speed of the ISAPI interface does not mean that you can ignore performance and
scalability considerations. Indeed, ISAPI cannot utilize much of the application support services provided
by ASP and COM. If you would like your ISAPI application to maintain session state, for instance,
much of that session-state functionality would have to be implemented by you.
Here are some suggestions for improving the scalability and performance of your ISAPI extensions:
? Avoid ISAPI filters , unless adding an ISAPI filter is absolutely necessary to your application
architecture. You should especially avoid filters that perform processing on raw incoming or
outgoing data. If you determine that a filter is absolutely necessary, be sure to carefully optimize
the main code paths through the filter event notification code.
? Create your own worker thread pool, so that the main I/O threads can be freed to accomplish
other tasks. This option is available only for ISAPI extensions, and not for ISAPI filters. For more
information about how IIS processes requests, see IIS Request Processing. A sample that
demonstrates a worker thread pool, implemented in an ISAPI extension, is available in ISAPI
Examples.
? Consider using asynchronous operations and I/O completion ports, when feasible. IIS
supports asynchronous reading and writing by using the I/O completion ports, available in
Windows NT 4.0, and Windows 2000 or later. Depending on the type of I/O operations being
performed, asynchronous operations can make better use of the CPU time available, and generally
work particularly well when implemented using a worker thread pool. For more information, see
Asynchronous I/O Processing.
? ISAPI extensions should use the Win32 TransmitFile function, exposed by the
HSE_REQ_TRANSMIT_FILE ServerSupportFunction.
? Use Connection: Keep-Alive headers . Keeping persistent HTTP connections will provide
better performance than using non-persistent connections, in most cases. For more details, see
Keep-Alive Connections.
? Minimize need for thread synchronization by maintaining state information with the request
context. If thread synchronization is required, make sure that critical sections are kept short.
? If your ISAPI application uses the heap intensively, consider other heap alternatives.
Intensive use of the Windows® heap can cause resource contention. Several memory allocation
alternatives are worth exploring, including:
? Heap Partitioning, accomplished by creating multiple custom heaps, in addition to the
default process heap. Each custom heap would then be controlled by a separate, non-
global lock, and lock contention would be reduced.
? Cached Allocation, which involves using custom allocation operations that operate at a
middle layer between the object users and the heap. Calls to the Win32 heap are made
infrequently, and only for large memory blocks. These blocks are then subdivided and
managed by the custom allocator.
? Stack Allocation, using the C run-time function _alloca to allocate memory for your
objects on the stack instead of the heap. This method is feasible only for relatively small
objects, because the space available on the stack is limited. In addition, your newly
allocated object will be available only within the current functions, or functions called by that
function. Once the current function returns, the storage allocated on the stack will be lost.
? Object Encapsulation, accomplished by simply incorporating a buffer as a member data
structure of a class. This buffer is then used for tasks that would otherwise require accesses
to the Win32 heap.
? Avoid using global locks within your ISAPI, if possible. Global locks can often adversely
affect scalability.

For more information about ISAPI extensions and filters, see Developing ISAPI Extensions and Filters,
and the ISAPI Reference.
Data Access Performance

Data access and retrieval is often the most challenging performance area for the Web application
developer.
Many of the scalability and performance concerns that arise around data access are not in your control,
as a Web application developer. However, there are some techniques that you can use to maximize your
performance:
? Cache results from data sources that are stable, or that vary predictably. You can cache
either the recordset returned by a query to the data source, or cache the pure HTML output that
was created using the results of the query.
For instance, if you are using ADO to populate a listbox that will contain the cities in which you
have offices, the first caller to ADO can insert the ADO query results into Application scope.
Subsequent requests for that listbox information could be fulfilled from the Application object,
instead of an expensive call, through ADO, to a data source.
If you wish to cache the resultant recordset directly, you should use a client-side cursor, and
disassociate the recordset from the Command object by setting the ADO ActiveConnection
property to Nothing.
For more information on data caching, see Caching Data.

? In general, avoid putting ADO connections in session state, because ODBC (version 3.0
and later) automatically does connection pooling for you, and OLE DB provides session pooling.
? Use the native OLE DB connection strings as much as possible. Native OLE DB
connection strings are generally faster than most ODBC DNSs. In addition, OLE DB connection
strings are more flexible because your application will be able to make use of any OLE DB
provider.
? If using a data source that supports them, such as Microsoft SQL Server, use stored
procedures whenever possible. A query executed from a stored procedure is faster than a
query passed through a SQL query string.
? To optimize performance, avoid using the ADO record addition and deletion methods,
such as AddNew and Delete. If your application adds and deletes records intensively, your
application will perform better if it uses direct SQL statements, such as INSERT.
? Set the ADO CacheSize property to a larger number than the default (1). By forcing ADO
to retrieve multiple records in one transaction with the data source, you will eliminate a portion of
the overhead involved in that transaction, and your application may become more scalable.
Generally, you are most likely to see benefits if you set CacheSize to equal to either the number
of records expected, or 100, whichever is less.
? Use the ADO 2.0 AdExecuteNoRecords flag when executing commands that don't return
data rows, or that return rows that you don't need to access or save. This new feature,

introduced in ADO 2.0, was created to reduce the amount of overhead incurred by ADO, and
thus increase performance and scalability.
? Disable temporary stored procedures, if your data source supports them.
For more information on data access, see Accessing a Data Source and Accessing Data with ASP.
Performance and Scalability Testing

Careful planning and development are necessary for any Web application development project.
However, in order to make a truly scalable Web application, it is important that you rigorously and
regularly test your Web application for scalability problems. It is important to understand that almost all
Web applications encounter some unforeseen scalability problems during development. The only way
these problems can be found and solved is through careful, thorough testing.
In general, the most useful scalability and performance testing stresses the application in a way that
closely parallels the stresses the application would undergo in a "real-world" setting.
Here are a few tools that you can use to perform scalability testing for your Web application:
? InetLoad can be used to generate customizable loads on various Internet services, over a broad
range of Internet protocols, including HTTP, SMTP, POP3, and LDAP. InetLoad can be set to
the exact mix of protocol traffic you expect to be generated, and can be used to simulate hundreds
or even thousands of users.
InetLoad is available at http://www.microsoft.com/msdownload/inetload/inetload.htm.

? The Web Capacity Analysis Tool (WCAT) is another tool that can be used to generate custom
loads on your application. WCAT is used only with HTTP protocol services, but it offers a richer
set of controls to specify the HTTP protocol loads than InetLoad does.
WCAT is available, along with documentation on how to use it, in the IIS Resource Guide
volume of the Windows 2000 Server Resource Kit. WCAT is also available for Web download
from http://www.microsoft.com/ntserver/web/.
Administering IIS Programmatically

Internet Information Services (IIS) provides powerful programming tools that you can use to access
configuration settings from within a script or application.
? Overview of Programmatic Administration: Describes the metabase, and what you should know
before you create administration applications.

? Using IIS Admin Objects: Explains how you can access the metabase from your scripts or
applications by using an Automation-compatible language of your choice, such as VBScript,
JScript, C++, or Visual Basic.
? Programmatic Administration Reference: Contains reference information for the programmatic
administration objects and interfaces that can be used with IIS.
For more information, see Advanced Programmatic Administration.
Overview of Programmatic Administration

IIS configuration parameter values are stored in a fast-access, memory-resident data store called the
metabase. The metabase is designed specifically for use with IIS and is faster, more flexible, and more
expandable than the Windows registry.
? Introduction to the IIS Metabase: Describes the IIS metabase.

? Development Choices for Programmatic Administration: Explains the two ways in which IIS
exposes the metabase for programmatic administration.
Introduction to the IIS Metabase

The metabase is the repository for most IIS 5.0 configuration information.
? Metabase Structure: Discusses the organization of data in the metabase.

? Key Names and Paths: Describes how metabase keys are addressed.
? Property Inheritance: Provides information about a metabase feature that simplifies configuration
operations and reduces storage requirements.
? Metabase Security and Reliability: Outlines key security and reliability issues that can affect the
metabase.
Metabase Structure
Most configuration settings for IIS reside in a storage facility, similar to the Windows registry, called the
metabase. You should become familiar with how the metabase operates, how the information contained
within the metabase is organized, and how you can access that information.

The metabase is organized in a hierarchical structure that mirrors the structure of your IIS installation.
Each node in the metabase structure is called a key, and each key can contain one or more IIS
configuration values, called metabase properties. The IIS metabase keys correspond to the elements of
IIS, and each key contains properties that affect the configuration of its associated element.
Most of the IIS configuration keys and values that were stored in the system registry for earlier versions
of IIS are now stored as properties in the metabase. New keys and values have been added for finer and
more flexible control of IIS. The metabase was designed to allow the same property to be set differently
at different nodes. For example, the MaxBandWidth property setting can be a different value for each
server.
The general structure of IIS is shown in the following figure, which is arranged by key types. The
metabase structure of your IIS installation can consist of a varied number of elements, depending on your
installation choices. Metabase keys associated with IIS elements are addressed by their paths within the
metabase. See Key Names and Paths.
The top-level metabase key, named Computer, contains properties such as MaxBandWidth. These

properties affect the overall execution of IIS on your computer. Two subkeys of the Computer key are
associated with FTP services and Web services, respectively, and contain properties that affect all FTP
and Web servers hosted on that computer.
Subkeys of the FTP service key are associated with individual FTP servers, and contain properties
specific to each FTP server. A subkey of each FTP server key is associated with the root virtual
directory for that server. Other subkeys are added to the root virtual directory key as you add virtual
directories to your FTP servers. Each of these subkeys contains properties that affect the operation or
configuration of the associated virtual directory. The Info key, directly subordinate to the FTP service
key, also contains some properties associated with the FTP service.
Subkeys of the Web service key are associated with individual Web servers, their root virtual directories,
subordinate virtual directories, disk directories, and files. A subkey of the Web service key affects the
configuration of filters used by Web service operations. The Info key, directly subordinate to the Web
service key, also contains some properties associated with the Web service.
Other keys directly subordinate to the top-level key contain properties that affect logging and MIME
mappings. The IISADMIN key is used to record DCOM extensions to IIS.
Keys can also contain references to objects that can be used by the IIS Admin Objects. For example,
the CertMapper key does not contain any metabase properties, but it does provide access to the
IIsCertMapper object and its methods for mapping certificates.
Key Names and Paths

A metabase key is a location in the metabase analogous to a directory in the file system. A metabase
path is a sequence of keys separated by a forward slash (/) that uniquely identifies the location of a key in
the metabase. Key names in the metabase are not unique unless qualified by their metabase paths, just as
different files with the same name can exist in different directories.
You can use the path of a metabase key with the IIS Admin Objects to access the specific IIS Admin
Object associated with that key. The IIS Admin Objects use the Active Directory Service Interfaces
(ADSI) path, called the ADsPath, to refer to the object associated with a key. The path starts with IIS://
and then uses the term LocalHost, or a specific computer name, to refer to the IIsComputer object,
which is associated with the highest key in the metabase.
The paths to objects associated with other metabase keys are an extension of the ADsPath to the
computer key. For example, the ADsPath for the first Web site in your IIS installation would be
IIS://LocalHost/W3SVC/1. You could also use the path IIS://ComputerName/W3SVC/1 to access the
metabase on a different computer.
Each Web site is a server instance, and is referred to in the path by its number. For example,
IIS://LocalHost/MSFTPSVC/3 represents the third FTP server instance, and
IIS://ComputerName/W3SVC/4 represents the fourth Web server instance.
Each Web site has an associated root virtual directory. All other virtual directories and directories
associated with a server instance are subordinate to this root virtual directory. The name of the root

virtual directory is ROOT. IIS://LocalHost/MSFTPSVC/3/ROOT refers to the root virtual directory for
the third FTP server on the local computer, and IIS://LocalHost/W3SVC/4/ROOT refers to the root
virtual directory for the fourth Web server on the same computer.
You can establish the structure below the root virtual directory of a server instance by adding virtual
directories, directories, and files. For FTP servers, metabase properties can be set to the virtual-
directory level. For Web servers, you can set properties to the level of directories and files. For example,
you could use the path IIS://LocalHost/W3SVC/2/ROOT/MyVdir1/Dir1/File1 to set file properties such
as read, write, and execute permissions.
Property Inheritance
You can use the property inheritance feature of the metabase to configure your IIS installation with few
settings, and to minimize the amount of memory required for the metabase. Most metabase properties
are inheritable, meaning that they are not explicitly set at a specific key and will inherit values assigned at
higher-level keys. For example, you can set file and directory permissions such as AccessScript,
AccessExecute and AccessWrite at the W3SVC level to apply to all files and directories in all server
instances, or you can set them at the W3SVC/2/ROOT level to apply to all files and directories for the
second Web server only. You can then set different permissions for individual subdirectories and files by
explicitly setting them at lower levels. For example, you might set the AccessExecute permission
property to TRUE for specific directories, virtual directories, or files, such
as ...W3SVC/1/ROOT/VDir1/VDir1a, ...W3SVC/1/ROOT/VDir2/Dir2d,
and ...W3SVC/1/ROOT/VDir2/Dir3/File1, and so on.
The default settings for AccessScript, AccessExecute, and AccessWrite are all FALSE. The way
inheritance works is that wherever you set the value of an inheritable property, all instances of that
property in the remaining subnodes will be set automatically. If you use Internet Services Manager to set
an inheritable property, a dialog box will ask you if you are sure you want to change the value for all the
subnodes. However, if you use a script or the command line to set an inheritable property, the values will
be propagated immediately.
In the following example, AccessScript is set to TRUE at the Web service level (.../W3SVC),
AccessExecute to TRUE at the root level (.../W3SVC/1/ROOT), and AccessWrite to TRUE at the
file level (.../W3SVC/n/ROOT/VDir/Dir/File). The round ball represents where the user sets the
property value and the arrows show the path of inheritance as the value is propagated through the
subnodes.

Most metabase properties are inheritable, except for a few that are used only at specific keys. Some
properties in the metabase are lists of values, such as the ServerBindings property.
Flag properties, such as file access permissions, are often combined into one DWORD by use of
bitmasking. The entire set of flags is stored together and inherits together. For example, if you change one
of the file access permissions, such as AccessExecute for a directory, the entire set of file access
permissions is stored at the metabase key for that directory.
Each metabase property is described in detail in the Administration Property Reference. This reference
includes information about whether each property is inheritable. Also, properties that are stored as part
of a larger set are identified as flags; for example, see the property AccessFlags.
Metabase Security and Reliability

Metabase Access Control
The metabase key values are stored in a disk file, which is named Metabase.bin by default. The
metabase is loaded from disk when IIS starts, stored to disk when IIS shuts down, and saved
periodically while IIS is running. It is important to protect this file from unauthorized use. It is
recommended that you store this file on an NTFS partition and use Windows security to protect it.
Metabase.bin is stored in the Inetsrv directory. You can move or rename the file and change the
Windows registry setting that tells IIS where to find the file on startup. To relocate or rename the
metabase file, you must stop IIS, move or rename the file, and modify the registry key
LOCAL_MACHINE\SOFTWARE\Microsoft\INetMgr\Parameters. Then add a REG_SZ value,
named MetadataFile, to this key. MetadataFile specifies the new complete path of the metabase file,
including the drive letter and file name.

Metabase Reliability
You can implement your own custom backup policy for the metabase, or create specialized backup
tools. Your application can use the methods provided by the IIsComputer object (for IIS Admin
Objects) or IMSAdminBase (for the IIS Admin Base Object) to manage metabase backups. You can
store multiple backup versions in long-term storage, restore the metabase from a backup version of your
choice, and enumerate and delete backups.
Important The metabase backup and restore functionality exists for versioning purposes, not for cross-
machine replication. A metabase backup must be restored only to the same machine on which it was
originally created.
Development Choices for Programmatic

Administration
As described in Introduction to the IIS Metabase, the metabase contains most of the configuration
information that IIS needs to operate properly. You can programmatically administer the metabase by
using the IIS Admin Base Object, which also uses the IWamAdmin Interface. Developers can build
applications to use this object; or they can build applications to use the IIS Admin Objects, which
provide a simpler way to implement applications. The following image shows the relationship between the
metabase, the IIS Admin Base Object, and the IIS ADSI Admin Objects layer.
IIS provides two distinct ways to programmatically access the information stored in the metabase:
1. IIS Admin Objects: These objects correspond to the key building blocks of your IIS installation.
Thus, there is an IIS Admin Object named IIsWebServer that exposes properties and methods
that apply to Web servers, another IIS Admin Object named IIsFtpServer that applies to FTP
servers, and so on.

The IIS Admin Objects are most suitable for use with Automation-compatible languages such as
Visual Basic, VBScript, or JScript. For more detailed information, see Using IIS Admin Objects.
2. IIS Admin Base Object: This object provides more advanced development choices. For more
information, see Advanced Programmatic Administration.
Using IIS Admin Objects

The IIS Admin Objects, described in this section, are provided by IIS to make programmatic
administration as straightforward as possible. The IIS Admin Objects are based on Microsoft Active
Directory Service Interfaces (ADSI), are Automation-compatible, and can be easily accessed and
manipulated by any language that supports Automation, such as Microsoft Visual Basic Scripting Edition
(VBScript) or JScript in Active Server Pages (ASP), Visual Basic, Java, or C++.
? IIS Admin Objects Overview: Introduces the IIS Admin Objects and describes what they are and
how they are used.
? Administrative Tasks Using the IIS Admin Objects: Describes how you can use the IIS Admin
Objects for common programmatic administration tasks.
For more information, see IIS Admin Objects Reference, Administration Property Reference, and
Programmatic Administration Examples.
IIS Admin Objects Overview

The IIS Admin Objects are COM Automation objects that you can use within ASP pages or custom
applications to change IIS configuration values stored in the IIS metabase. For example, you could set
permissions for the AccessRead, AccessWrite, and AccessExecute properties by writing a script in
an ASP page.
Individual IIS Admin Objects correspond to keys in the metabase and are addressed by their paths
within the metabase. Each object has properties and each property is stored in the metabase. You can
manipulate your IIS configuration by using IIS Admin Objects; you can change properties, add new
virtual directories, add new Web sites, and so on.
Because modifying an IIS Admin Object property changes the value of the corresponding metabase
property, you can configure individual elements of IIS such as the local machine (LM), FTP server
(FTPSVC), or Web server (W3SVC). Because of the hierarchical structure of the metabase and its
property inheritance feature, you can easily configure properties for a single file, a single server, all Web
servers, all FTP servers, or the common properties of many other groups of objects.

? Object Hierarchy: Describes the relationship of the IIS Admin Objects to the metabase and how
you address these objects in your application.
? ADSI Features: Explains how the IIS Admin Objects implement standard ADSI properties and
methods that you can use to administer IIS.
Object Hierarchy
The IIS Admin Objects are organized in a hierarchical structure that mirrors the IIS structures defined in
the IIS metabase. Objects contain other objects to create the object structure illustrated in the following
diagram. Details of the IIS structure and the metabase are found in the Metabase Structure topic of the
Introduction to the IIS Metabase section. Most objects will inherit characteristics of the parent object,
but child objects can contain unique characteristics implemented by extending the schema. You can use
this object hierarchy to access configuration settings for specific IIS elements. The structure shown in the
diagram can vary slightly depending on how IIS is installed.
ADSI Features

This section discusses ADSI objects and container objects, and how each is implemented and exposed.
The IIS Admin Objects are exposed by IIS as an implementation of ADSI. ADSI provides a standard
syntax for addressing IIS configuration data. The IIS namespace consists of the IIS Admin Objects and
the metabase. The IIS remote administration tool, Internet Service Manager (HTML), uses the IIS
Admin Objects.
? ADSI Objects: Discusses ADSI objects and how they can be used to configure IIS.
? ADSI Container Objects: Describes ADSI container objects and their functionality in IIS.
You can reference IIS Admin Objects by their metabase path. For example, the IIS Admin Object for
the first Web site on the computer named MyComputer would be addressed by the ADSI path
(ADsPath) IIS://MyComputer/W3SVC/1.
The following VBScript code demonstrates how you might use a script to reference the path to the first
Web site (…/1) to open the IIS Admin Object. In the example, this object is associated with the
metabase key for the Web site, which resides on the local machine.
Note You can use the string "LocalHost" instead of the actual machine name.
<%
Dim VSvrObj
Set VSvrObj = GetObject("IIS://LocalHost/W3SVC/1")
Response.Write "Value of ServerComment = " & VSvrObj.ServerComment
%>
ADSI Objects
The IIS Admin Objects each implement the IADs interface defined by the ADSI standard. The IADs
interface for the IIS Admin Objects provides the following basic functionality:
? A simple way to set and retrieve configuration properties on a specific node in the metabase. For
example, you can change permissions (AccessFlags) for a specific Web site.
? A way to retrieve the path of the object's parent container object.
? Binding information that uniquely identifies the object instance in a directory tree.
? A path to the schema definition of the object.
? Identification information that indicates the name and type of the object.
? A way to retrieve namespace properties.
? A simple implicit caching system.
The IIS Admin Objects implement the IADs interface, supporting the Name, ADsPath, Class, GUID,
Parent, and Schema properties in addition to IIS-specific metabase properties. The IADs GetInfo,
SetInfo, Get, Put, GetEx, and PutEx methods are also supported, in addition to others needed for IIS
configuration administration. For more specific information about the ADSI properties and methods
provided by the IIS Admin Objects, see the ADSI Reference.

ADSI Container Objects
Any IIS Admin Object that can contain other objects can also implement the IADsContainer interface,
in addition to the IADs interface. Examples of IIS Admin Objects that support IADsContainer include
the following:
? IIsComputer, which can contain IIsWebService and IIsFtpService objects, among others.
? IIsWebVirtualDir object, which can contain IIsWebDirectory and IIsWebFile objects, as
well as additional IIsWebVirtualDir objects.
The IADsContainer interface permits objects to contain other objects, and provides a way to
implement the following tasks:
? Create objects within the container.

? Delete objects from the container.
? Count the number of objects within the container.
? Enumerate the contained objects.
? Access the contained objects.
The IIS Admin Objects that can contain other objects can also implement container object properties
and methods. These objects accomplish this by supporting the IADsContainer interface, the
_NewEnum and Count properties, and the GetObject, Create, and Delete methods. IIS Admin
Objects also support the basic IADs interface properties and methods, and any IIS-specific or extended
properties and methods.
For more information, see the ADSI Reference.
Administrative Tasks Using the IIS Admin

Objects
IIS configuration information is stored as binary values in the metabase, also referred to as metabase
properties. You can use the IIS Admin Objects to change these configuration values. These objects can
also be used to configure your IIS installation, create new FTP and Web servers, virtual directories, and
other IIS elements. Individual IIS Admin Objects correspond to specific types of keys in the metabase.
With simple scripts or within ASP pages, you can use the IIS Admin Objects to create applications for
remote administration of your IIS installation.
One example of such an application is the Internet Service Manager (HTML), a remote administration
tool that ships with IIS. This tool was constructed with the techniques demonstrated in this section.

? Manipulating the Metabase: Explains one of the more common programmatic administration tasks
you can do with IIS, manipulating the metabase by using a script.
Other sample command-line scripts are provided in the \Inetpub\AdminScripts directory. For more
examples, see Developer Samples.
Manipulating the Metabase

The IIS Admin Objects expose a hierarchical namespace of objects where each object has an ADsPath
property. The ADsPath syntax is similar to that of a Uniform Resource Locator (URL), in the form of
IIS://[path], where [path] represents the directory path of the object being accessed. For example,
IIS://MyComputer/W3SVC refers to the IIsWebService object for the machine named MyComputer.
The object associated with MyComputer is the IIsComputer object, which contains all of the other IIS
Admin Objects.
To obtain a reference to a named object, you can use the GetObject function in Visual Basic or
VBScript.
Note Other scripting languages can be used; see the documentation for the scripting language for
details, as well as the ADSI Reference.
For example, you can retrieve the current value of ServerComment by inserting the following VBScript
into an .asp file. In the following example, the string "LocalHost" is used instead of the explicit name
"MyComputer" to access the computer on which IIS is running.
<%
Dim ComputerObj
Dim MaxBW
Set ComputerObj = GetObject("IIS://LocalHost")
MaxBW = ComputerObj.Get("MaxBandwidth")
%>
This could also be implemented using the object.property syntax, as in the following example.
<%
Dim ComputerObj
Dim MaxBW
MaxBW = ComputerObj.MaxBandwidth
%>
Note ASP pages that access the metabase require administrator privileges on the computer on which
IIS is running; this is also true when running ASP applications out-of-process. When you execute scripts
from a remote computer, you must connect through a secure connection, such as a connection protected
by integrated Windows authentication (also called NTLM authentication). It is suggested that you create
a server or directory for your administrative .asp files and set the authentication method to use integrated
Windows authentication for the server or directory.

For security purposes, out-of-process applications cannot access the metabase unless WamUserName
is recognized as an administrator. It is recommended that you retain this default behavior unless special
circumstances require otherwise.
There are two ways you can modify this out-of-process behavior, but each introduces some security risk:
? You can give the IWAM_machinename account administrator-level access to the metabase,
though this will allow administrator-level access to the metabase for all out-of-process applications
created with this default administrator-level identity.
? Or, you can change the identity of the specific out-of-process package to some other account
identity, and give only that account administrator-level access to the metabase. This method
introduces less potential risk, but it must be implemented for each out-of-process package.
Programmatic Administration Reference

This section contains reference information for the programmatic administration objects and interfaces
that can be used with IIS.
? IIS Admin Objects Reference: Contains a reference page for each of the IIS Admin Objects.
? ADSI Reference: Describes properties and methods that are exposed by the IIS Admin Objects.
? Administration Property Reference: Describes each IIS administration property, including the data
type, default value, inheritance attribute, and provides usage notes.
IIS Admin Objects Reference

This topic contains a reference page for each of the IIS Admin Objects. Each page includes ADSI
container information, the ADsPath for the object, the metabase properties accessible by the object,
and any additional methods specific to the object.
Note Each IIS Admin Object has a property called KeyType which specifies exactly what type of IIS
Admin Object a given ADSI object represents. If the key type is not available, or is not valid, then IIS
assigns the generic type IIsObject. You can use KeyType to change the ADSI object to a valid object,
and gain access to other IIS-specific properties and methods.

IIsCertMapper Maps certificates to Windows accounts.

IIsCompressionSchemes Global settings for HTTP 1.1 compression
schemes.
IIsCompressionScheme Settings for individual compression schemes.
IIsComputer Establishes global settings for IIS configuration.
IIsCustomLogModule Sets properties for custom logging information
field nodes.
IIsFilter Provides information about a specific filter.
IIsFilters Manages filters.
IIsFtpInfo Establishes configuration properties for FTP
servers in addition to those set at IIsFtpService.
IIsFtpServer Establishes configuration properties for a single
FTP server.
IIsFtpService Establishes configuration properties common to all
FTP servers.
IIsFtpVirtualDir Sets properties for an individual FTP virtual
directory.
IIsIPSecurity A custom ADSI object you can use to set access
permissions by IP address and domain address.
IIsLogModule Contains information about a specific logging
module.
IIsLogModules Maintains information about installed logging
modules.
IIsMimeMap Manages Multipurpose Internet Mail Extension
(MIME) mappings.
IIsMimeType Used to manipulate the list of valid MIME types.
IIsWebDirectory Sets properties for an individual Web directory.
IIsWebFile Sets properties for an individual Web file.
IIsWebInfo Establishes configuration properties for Web
servers in addition to those set at
IIsWebService.
IIsWebServer Establishes configuration properties for a single
Web server.
IIsWebService Establishes configuration properties common to all
Web servers.

IIsWebVirtualDir Sets properties for an individual Web virtual

directory.
See Also
Constants A list of constants used with IIS Admin Objects.
IIsCertMapper
The IIsCertMapper object maps client certificates to Windows user accounts. IIsCertMapper is an
ADSI object, but not an ADSI container object. See ADSI Features for more information about ADSI
container objects.
ADsPath
IIS://MachineName/W3SVC/N/IIsCertMapper
where MachineName can be any name or "LocalHost."
Syntax
varReturn = IIsCertMapper.Method
Parts
varReturn
A variable that receives the return value from the method.
Method
The object method chosen.
Methods
CreateMapping Maps a certificate to a Windows account.

DeleteMapping Deletes an existing certificate mapping.
GetMapping Retrieves an existing certificate mapping.
SetAcct Sets a new value for the Windows account string
in an existing certificate mapping.
SetEnabled Enables or disables an existing certificate
mapping.
SetName Sets a new value for the name string in an existing
certificate mapping.

SetPwd Sets a new value for the Windows password

string in an existing certificate mapping.
See Also
ADSI Object Methods Standard methods for ADSI objects.
CreateMapping
The CreateMapping method of the IIsCertMapper object maps a certificate to a Windows account.
Syntax
IIsCertMapper.CreateMapping vCert, NtAcct, NtPwd, strName, IEnabled
Parameters
vCert
Contains the certificate. The certificate is either a string or an array of bytes, usually obtained from
the ClientCertificate collection of the built-in ASP Request Object.
NtAcct
Contains the Windows account string.
NtPwd
Contains the password string for NtAcct.
strName
Contains the friendly name for the account.
IEnabled
Specifies TRUE to enable the mapping, FALSE to disable the mapping.
Code Example
<%
Dim CertObj, vCert
vCert = Request.ClientCertificate("CERTIFICATE")
Set CertObj = GetObject("IIS://..path../IIsCertMapper")
CertObj.CreateMapping vCert, "MYACCT", "MYPASS", "My Name", True
%>
See Also
DeleteMapping, GetMapping, SetAcct, SetEnabled, SetName , SetPwd
DeleteMapping

The DeleteMapping method of the IIsCertMapper object deletes an existing certificate mapping.
Four seek methods are available to search for the mapping: by certificate, by name, by Windows
account, and by numeric string index.
Syntax
IIsCertMapper.DeleteMapping IMethod, vKey
Parameters
IMethod
Specifies the seek method to use for searching the mappings. Valid seek methods are 1, 2, 3, or
4. Seek method 1 specifies search by certificate, seek method 2 searches by name, method 3
searches by Windows account, and method 4 searches by a 1-based numeric string index (for
example "1," "2," and so on).
vKey
Specifies the key to use in the search specified by IMethod. For seek method 1, vKey specifies a
certificate. For seek method 2, vKey specifies a name. For seek method 3, vKey specifies a
Windows account. For seek method 4, vKey specifies a numeric string index (for example, "1,"
"2," and so on).
Code Example
<%
Dim CertObj
'Search by Windows account.
CertObj.DeleteMapping 3, "MYACCT"
%>
See Also
CreateMapping, GetMapping, SetAcct, SetEnabled, SetName , SetPwd
GetMapping
The GetMapping method of the IIsCertMapper object retrieves a certificate and the mapping data
from an existing certificate mapping. Four seek methods are available to search for the mapping: by
certificate, by name, by Windows account, and by numeric string index. The retrieved mapping is
returned in parameter variables you provide.
Syntax
IIsCertMapper.GetMapping IMethod, vKey, vCert, NtAcct, NtPwd, strName, IEnabled

Parameters
IMethod
example, "1," "2," and so on).
vKey
"2," and so on).
vCert
Receives the returned certificate.
NtAcct
Receives the returned Windows account.
NtPwd
Receives the returned Windows account password.
strName
Receives the returned Windows account friendly name.
IEnabled
Receives the returned value TRUE for an enabled mapping, or FALSE for a disabled mapping.
Code Example
<%
Dim CertObj, vCert, NtAcct, NtPwd, strName, IEnabled
CertObj.GetMapping 3, "MYACCT", vCert, NtAcct, NtPwd, strName, IEnabled
%>
See Also
CreateMapping, DeleteMapping, SetAcct, SetEnabled, SetName , SetPwd
SetAcct
The SetAcct method of the IIsCertMapper object sets a new value for the Windows account string in
an existing certificate mapping. Four seek methods are available to search for the mapping: by certificate,
by name, by Windows account, and by numeric string index.
Syntax
IIsCertMapper.SetAcct IMethod, vKey, NTAcct

Parameters
IMethod
vKey
"2," and so on).
NTAcct
Specifies a new value for the Windows account string.
Code Example
<%
Dim CertObj
CertObj.SetAcct 3, "MYACCT", "NewAccount"
%>
See Also
CreateMapping, DeleteMapping, GetMapping, SetEnabled, SetName , SetPwd
SetEnabled
The SetEnabled method of the IIsCertMapper object enables or disables an existing certificate
mapping. Four seek methods are available to search for the mapping: by certificate, by name, by
Windows account, and by numeric string index.
Syntax
IIsCertMapper.SetEnabled IMethod, vKey, IEnabled
Parameters
IMethod


vKey
"2," and so on).
IEnabled
Specifies TRUE to enable the mapping, FALSE to disable the mapping.
Code Example
<%
Dim CertObj
CertObj.SetEnabled 3, "MYACCT", True
%>
See Also
CreateMapping, DeleteMapping, GetMapping, SetAcct, SetName , SetPwd
SetName
The SetName method of the IIsCertMapper object sets a new value for the name string in an existing
certificate mapping. Four seek methods are available to search for the mapping: by certificate, by name,
by Windows account, and by numeric string index.
Syntax
IIsCertMapper.SetName IMethod, vKey, strName
Parameters
IMethod
example, "1", "2", and so on).
vKey
"2," and so on).
strName
Specifies a new value for the name string.

Code Example
<%
Dim CertObj
CertObj.SetName 3, "MYACCT", "NewName"
%>
See Also
CreateMapping, DeleteMapping, GetMapping, SetAcct, SetEnabled, SetPwd
SetPwd
The SetPwd method of the IIsCertMapper object sets a new value for the Windows password string
in an existing certificate mapping. Four seek methods are available to search for the mapping: by
certificate, by name, by Windows account, and by numeric string index.
Syntax
IIsCertMapper.SetPwd IMethod, vKey, NTPwd
Parameters
IMethod
vKey
"2," and so on).
strPwd
Specifies a new value for the Windows password string.
Code Example
<%
Dim CertObj
CertObj.SetPwd 3, "MYACCT", "NewPassword"
%>

See Also
CreateMapping, DeleteMapping, GetMapping, SetAcct, SetEnabled, SetName
IIsCompressionSchemes
This is preliminary documentationfor IIS 5.0 and is subject to change.
IIsCompressionSchemes is an ADSI container object that contains the individual HTTP 1.1
compression schemes that are available to IIS, represented by the ADSI object
IIsCompressionScheme . In addition, all global compression settings for the IIS installation are stored in
IIsCompressionSchemes.
ADsPath
IIS://MachineName/W3SVC/Filters/Compression/Parameters
Syntax
varReturn = object.Method
varReturn = object.Property
Parts
varReturn
object
A variable that refers to the IIsCompressionSchemes object, usually as a result of a previous
GetObject operation.
Method or Property
The particular object method or property that you want to use.
Can Contain
IIsCompressionScheme
Properties
ADSI Object Properties ADSI Container Object Properties
Metabase Properties

HcCacheControlHeader HcIoBufferSize
HcCompressionBufferSize HcMaxDiskSpaceUsage
HcCompressionDirectory HcMaxQueueLength
HcDoDiskSpaceLimiting HcMinFileSizeForComp
HcDoDynamicCompression HcNoCompressionForHttp10
HcDoOnDemandCompression HcNoCompressionForProxies
HcDoStaticCompression HcNoCompressionForRange
HcExpiresHeader HcSendCacheHeaders
HcFilesDeletedPerDiskFree
Methods

ADSI Container Object Methods Standard methods for ADSI container objects.
IIsCompressionScheme
The IIsCompressionScheme IIS Admin Object is an ADSI object that contains configuration
information about an individual compression scheme. All instances of the IIsCompressionScheme
object are contained within IIsCompressionSchemes.
ADsPath
IIS://MachineName/W3SVC/Filters/Compression/Scheme
where MachineName can be any name, or "LocalHost."
Syntax
varReturn = object.Property
Parts
varReturn
object

A variable that refers to the IIsCompressionScheme object, usually as a result of a previous

Method or Property
The particular object method or property that you want to use.
Properties
ADSI Object Properties
Metabase Properties
HcCompressionDll HcFileExtensions
HcCreateFlags HcMimeType
HcDoDynamicCompression HcOnDemandCompLevel
HcDoStaticCompression HcPriority
HcDoOnDemandCompression HcScriptFileExtensions
HcDynamicCompressionLevel
Methods
IIsComputer
You can use the IIsComputer object to set values of global metabase properties that determine how IIS
operates. The IIsComputer object also provides methods to manage metabase backups. You can use
these methods to store multiple backup versions in long-term storage, restore the metabase from a
backup version of your choice, and enumerate and delete backups.
The IIsComputer object is an ADSI container object.
ADsPath
IIS://MachineName
Syntax
Parts

varReturn
object
A variable that contains the IIsComputer object, usually as a result of a previous GetObject
operation.
Method
Can Contain
IIsFtpService IIsMimeMap
IIsLogModules IIsWebService
Properties
ADSI Object Properties Standard properties for ADSI objects.
Metabase Properties
MaxBandwidth MimeMap
MaxBandwidthBlocked
Methods
Backup Saves the metabase to long-term storage.

DeleteBackup Deletes a metabase backup from long-term
storage.
EnumBackups Enumerates metabase backups in long-term
storage.
Restore Restores a metabase backup from long-term
storage.
See Also

Backup
You can use the Backup method of the IIsComputer object to back up the metabase to a location you
specify by providing a backup location name of up to 100 characters in length. Multiple metabase

backups can be stored in a backup location.
Syntax
IIsComputer.Backup BackupLocation, BackupVersion, BackupFlags
Parameters
BackupLocation
A string of up to 100 characters that specifies the backup location. The storage mechanism will be
determined by IIS. If an empty string is specified, the backup will be stored in the default location.
BackupVersion
Specifies the version number to be assigned to the backup. Must be less than or equal to
MD_BACKUP_MAX_VERSION. Can be set to one of the following values.
MD_BACKUP_HIGHEST_VERSION Overwrite the highest existing backup version
in the specified backup location.
MD_BACKUP_NEXT_VERSION Use the next backup version number available
in the specified backup location.
BackupFlags
One or more of the following flags.
MD_BACKUP_FORCE_BACKUP Force the backup even if the SaveData
operation specified by
MD_BACKUP_SAVE_FIRST fails.
MD_BACKUP_OVERWRITE Back up even if a backup of the same name
and version exists in the specified backup
location, overwriting if necessary.
MD_BACKUP_SAVE_FIRST Perform a SaveData operation before the
backup.
Remarks
IIS determines the backup storage mechanism, so the backup location name you provide does not
necessarily translate to a particular directory, file, or database storage mechanism. As implemented in this
release, metabase backups are stored as files in the system32\inetsrv\MetaBack directory.
machine replication. A metabase backup must be restored only to the same machine from which it was
originally created.
Code Example
<%
Dim ComputerObj, iFlags
'Backup to next available version number.
'Set flags to save the metabase first and

'force the backup even if save fails.

iFlags = (MD_BACKUP_SAVE_FIRST or MD_BACKUP_FORCE_BACKUP)
ComputerObj.Backup "MyBackups", MD_BACKUP_NEXT_VERSION, iFlags
%>
See Also
DeleteBackup, EnumBackups, Restore
DeleteBackup
You can use the DeleteBackup method of the IIsComputer object to delete a metabase backup from
a backup location.
Syntax
IIsComputer.DeleteBackup BackupLocation, BackupVersion
Parameters
BackupLocation
A string of up to 100 characters that specifies the backup location. If an empty string is specified,
the backup will be deleted from the default location.
BackupVersion
Specifies the version number of the backup to be deleted from the backup location, or can be the
following constant.
MD_BACKUP_HIGHEST_VERSION Delete the highest existing backup version in
the specified backup location.
Code Example
<%
Dim ComputerObj
'Delete version 1 backup.
ComputerObj.DeleteBackup "MyBackups", 1
%>
See Also
Backup, EnumBackups, Restore
EnumBackups

You can use the EnumBackups method of the IIsComputer object to enumerate metabase backups
stored in one or more backup locations, retrieving the location, version number, and date of each
backup.
Syntax
IIsComputer.EnumBackups BkupLocIn, IndexIn, BkupVerOut, BkupLocOut, BkupDateTimeOut
Parameters
BkupLocIn
all backup locations will be searched.
IndexIn
Specifies the index of the backup to enumerate. Start the index at 0 and increment by 1 until
MD_ERROR_DATA_NOT_FOUND is returned.
BkupVerOut
Receives the version number of the backup enumerated.
BkupLocOut
Receives the backup location of the backup enumerated.
BkupDateTimeOut
Receives the date and time of the backup, in Universal Time Coordinate (UTC), formerly GMT
(Greenwich Mean Time).
Code Example

<SCRIPT LANGUAGE = "JScript" RUNAT = SERVER>
var TempDate = new Date();
TempDif = TempDate.getTimezoneOffset();
Session("sTempDif") = TempDif;
</SCRIPT>
<%
Dim CompObj, Index, Version, Location, GMTDate, LocDate, MinDif
MinDif = Session("sTempDif")
On Error Resume Next
Set CompObj = GetObject("IIS://LocalHost")
Index = 0
' Iterate until method returns an error.
Do While True
' Empty location input string means enumerate all locations.
CompObj.EnumBackups "", Index, Version, Location, GMTDate
If Err.Number <> 0 Then
' If error returned, no more backups to enumerate.
Exit Do
End If
Response.Write Version & ", "
Response.Write Location & ", "
Response.Write GMTDate & ", "
' Convert to server local date and time.
LocDate = DateAdd("n", (-MinDif), GMTDate)

Response.Write "(" & LocDate & ")"

Response.Write "<BR>"
Index = Index + 1
Loop
%>
See Also
Backup, DeleteBackup, Restore
Restore
You can use the Restore method of the IIsComputer object to restore the metabase from a backup.
The restore operation stops all services dependent on IISADMIN, including all servers, until the restore
has completed, then restarts all services. Because of this, if you are restoring the metabase by using a
script in an ASP page, you must specify a machine name other than the one on which your script is
executing. You cannot use LocalHost as the machine name. You should be careful to plan for this service
interruption when restoring the metabase from a backup.
Syntax
IIsComputer.Restore BackupLocation, BackupVersion, BackupFlags
Parameters
BackupLocation
the backup will be retrieved from the default location.
BackupVersion
Specifies the version number of the backup to be restored from the backup location, or can be the
following constant.
MD_BACKUP_HIGHEST_VERSION Restore from the highest existing backup
version in the specified backup location.
BackupFlags
Reserved. Must be zero.
Code Example
<%
Dim ComputerObj, ComputerName
'Restore metabase on a different computer.
ComputerName = "MyOtherComputer"
'You can use LocalHost if running under Windows Script Host.
Set ComputerObj = GetObject("IIS://" & ComputerName)
'Restore the highest number version in MyBackups.

ComputerObj.Restore "MyBackups", MD_BACKUP_HIGHEST_VERSION, 0

%>
Remarks
You can use the Restore method with LocalHost in scripts running in a command window by using
Cscript.exe. For more information, see the Windows Script Host material in the Windows
documentation.
machine replication. A metabase backup must be restored only to the same machine from which it was
originally created.
See Also
Backup, EnumBackups, DeleteBackup
IIsCustomLogModule
You can use the IIsCustomLogModule object to configure custom logging information fields. For more
information about custom logging fields, see Setting Metabase Properties for Logging.
ADsPath
IIS://MachineName/Logging/CustomLogging
IIS://MachineName/Logging/CustomLogging/Field
IIS://MachineName/Logging/CustomLogging/FieldGroup
IIS://MachineName/Logging/CustomLogging/FieldGroup/Field
Syntax
Parts
varReturn
object
A variable that contains the IIsComputer object, usually as a result of a previous GetObject
operation.
Method

Properties
Metabase Properties
LogCustomPropertyDataType LogCustomPropertyMask
LogCustomPropertyHeader LogCustomPropertyName
LogCustomPropertyID LogCustomPropertyServicesString
Methods
IIsFilter
You can use the IIsFilter object to set metabase properties that affect the operation of ISAPI filters.
You can set filter properties at the Web service level or for an individual Web server.
The IIsFilter object is an ADSI object, but not an ADSI container object.
ADsPath
IIS://MachineName/W3SVC/Filters/FilterName
or
IIS://MachineName/W3SVC/N/Filters/FilterName
where MachineName can be any name or "LocalHost," and N is the number of a Web server.
Syntax
Parts
varReturn
object

A variable that contains the IIsFilter object, usually as a result of a previous GetObject
operation.
Method
Properties
Metabase Properties
FilterDescription NotifyNonSecurePort
FilterEnabled NotifyOrderHigh
FilterFlags NotifyOrderLow
FilterPath NotifyOrderMedium
FilterState NotifyPreProcHeaders
NotifyAccessDenied NotifyReadRawData
NotifyAuthentication NotifySecurePort
NotifyEndOfNetSession NotifySendRawData
NotifyEndOfRequest NotifySendResponse
NotifyLog NotifyUrlMap
Methods
ADSI Object Methods Standard methods for ADSI objects
IIsFilters
The IIsFilters object is an ADSI container object that contains the collection of IIsFilter objects. You
can use the IIsFilters object to set the FilterLoadOrder property to specify the sequence in which
filters are to be loaded, and to enumerate through filters. You can use the IIsFilters object to manage
filters at the Web service level or at an individual Web server.
The IIsFilters object is an ADSI container object.
ADsPath
IIS://MachineName/W3SVC/Filters

or
IIS://MachineName/W3SVC/N/Filters
where MachineName can be any name or "LocalHost," and N is the number of a Web server.
Syntax
Parts
varReturn
object
A variable that contains the IIsFilters object, usually as a result of a previous GetObject
operation.
Method
Can Contain
IIsFilter
Properties
Metabase Properties
FilterLoadOrder
Methods

IIsFtpInfo
Some metabase properties associated with the FTP service are stored at the Info subkey of the
MSFTPSVC key. You can use the IIsFtpInfo object to set values for these properties.
The IIsFtpInfo object is an ADSI object, but not an ADSI container object.

ADsPath
IIS://MachineName/MSFTPSVC/Info
Syntax
Parts
varReturn
object
A variable that contains the IIsFtpInfo object, usually as a result of a previous GetObject
operation.
Method
Properties
Metabase Properties
LogModuleList
Methods
IIsFtpServer
You can use the IIsFtpServer object to set metabase properties that apply to a specific FTP server and
to set inheritable metabase properties for FTP virtual directories. Specific methods are also available to
control server operation. FTP servers are identified in the metabase by their index numbers. The first
FTP server is number 1, the second is number 2, and so on.
The IIsFtpServer object is an ADSI container object. For more information on ADSI container
objects, see ADSI Features.
ADsPath

IIS://MachineName/MSFTPSVC/N
Syntax
Parts
varReturn
object
A variable that contains the IIsFtpServer object, usually as a result of a previous GetObject
operation.
Method
Can Contain
IIsFtpVirtualDir
Properties
Metabase Properties
A–I
AccessFlags ConnectionTimeout
AccessRead DefaultLogonDomain
AccessWrite DisableSocketPooling
AdminACL DontLog
AllowAnonymous ExitMessage
AnonymousOnly FtpDirBrowseShowLongDate
AnonymousPasswordSync GreetingMessage
AnonymousUserName IPSecurity
AnonymousUserPass
Log...
LogAnonymous LogExtFileTimeTaken

LogExtFileBytesRecv LogExtFileUriQuery
LogExtFileBytesSent LogExtFileUriStem
LogExtFileClientIp LogExtFileUserAgent
LogExtFileComputerName LogExtFileUserName
LogExtFileCookie LogExtFileWin32Status
LogExtFileDate LogFileDirectory
LogExtFileFlags LogFileLocaltimeRollover
LogExtFileHttpStatus LogFilePeriod
LogExtFileMethod LogFileTruncateSize
LogExtFileProtocolVersion LogNonAnonymous
LogExtFileReferer LogOdbcDataSource
LogExtFileServerIp LogOdbcPassword
LogExtFileServerPort LogOdbcTableName
LogExtFileSiteName LogOdbcUserName
LogExtFileTime LogPluginClsId
LogType
M–S
MaxClientsMessage ServerBindings
MaxConnections ServerComment
MaxEndpointConnections ServerListenBacklog
MSDOSDirOutput ServerListenTimeout
Realm ServerSize
ServerAutoStart ServerState
Methods
Continue Resumes the server.

Pause Pauses the server.
Start Starts the server.
Status Retrieves current status of server.
Stop Stops the server.
See Also


Continue
The Continue method of the IIsFtpServer object continues the server operation after it has been
paused.
Syntax
IIsFtpServer.Continue
Code Example
<%
Dim ServerObj
'Continue the second FTP server.
Set ServerObj = GetObject("IIS://LocalHost/MSFTPSVC/2")
ServerObj.Continue
%>
See Also
Start, Pause, Stop, Status
Pause
The Pause method of the IIsFtpServer object pauses the server operation.
Syntax
IIsFtpServer.Pause
Code Example
<%
Dim ServerObj
'Pause the second FTP server.
ServerObj.Pause

%>
See Also
Start, Continue, Stop, Status
Start
The Start method of the IIsFtpServer object starts the server operation.
Syntax
IIsFtpServer.Start
Code Example
<%
Dim ServerObj
'Start the second FTP server.
ServerObj.Start
%>
See Also
Pause, Continue, Stop, Status
Status
The Status method of the IIsFtpServer object returns an integer that indicates the current status of the
server. The possible values are 1 (starting), 2 (started), 3 (stopping), 4 (stopped), 5 (pausing), 6
(paused), or 7 (continuing).
Syntax
IIsFtpServer.Status
See Also
Start, Pause, Continue, Stop

Stop
The Stop method of the IIsFtpServer object stops the server operation.
Syntax
IIsFtpServer.Stop
Code Example
<%
Dim ServerObj
'Stop the second FTP server.
ServerObj.Stop
%>
See Also
Start, Pause, Continue, Status
IIsFtpService
You can use the IIsFtpService object to set the metabase property values that control FTP sites and
FTP virtual directories. The DownlevelAdminInstance property indicates the specific FTP server
instance to administer (for IIS 2.0 Internet Server Manager clients performing remote administration of
IIS 5.0).
The IIsFtpService object is an ADSI container object.
ADsPath
IIS://MachineName/MSFTPSVC
Syntax

Parts
varReturn
object
A variable that contains the IIsFtpService object, usually as a result of a previous GetObject
operation.
Method
Can Contain
IIsFtpServer IIsFtpInfo
Properties
Metabase Properties
A–I
AccessFlags DefaultLogonDomain
AccessRead DirectoryLevelsToScan
AccessWrite DisableSocketPooling
AdminACL DontLog
AllowAnonymous DownlevelAdminInstance
AnonymousOnly ExitMessage
AnonymousPasswordSync FtpDirBrowseShowLongDate
AnonymousUserName GreetingMessage
AnonymousUserPass IPSecurity
ConnectionTimeout
Log...
LogAnonymous LogExtFileUriQuery
LogExtFileBytesRecv LogExtFileUriStem
LogExtFileBytesSent LogExtFileUserAgent
LogExtFileClientIp LogExtFileUserName
LogExtFileComputerName LogExtFileWin32Status
LogExtFileCookie LogFileDirectory

LogExtFileDate LogFileLocaltimeRollover
LogExtFileFlags LogFilePeriod
LogExtFileHttpStatus LogFileTruncateSize
LogExtFileMethod LogNonAnonymous
LogExtFileProtocolVersion LogOdbcDataSource
LogExtFileReferer LogOdbcPassword
LogExtFileServerIp LogOdbcTableName
LogExtFileServerPort LogOdbcUserName
LogExtFileSiteName LogPluginClsId
LogExtFileTime LogType
LogExtFileTimeTaken
M–S
MaxClientsMessage ServerBindings
MaxConnections ServerComment
MaxEndpointConnections ServerListenBacklog
MSDOSDirOutput ServerListenTimeout
Realm ServerSize
ServerAutoStart
Methods

ADSI Container Object methods Standard methods for ADSI container objects.
IIsFtpVirtualDir
You can use the IIsFtpVirtualDir object to set metabase properties that apply to one or all FTP virtual
directories for an FTP server. If you use this object at the server's root virtual directory (for example,
.../MSFTPSVC/2/ROOT), inheritable property values will apply to all FTP virtual subdirectories of the
root virtual directory of the second FTP server. You can set properties for a specific FTP virtual
directory by using the IIsFtpVirtualDir object for a specific virtual directory (for example,
.../MSFTPSVC/2/ROOT/AVDir).
The IIsFtpVirtualDir object is an ADSI container object.

ADsPath
For the server's root virtual directory,
IIS://MachineName/MSFTPSVC/N/ROOT
For a specific virtual directory,
IIS://MachineName/MSFTPSVC/N/ROOT/vdirName
Syntax
Parts
varReturn
object
A variable that contains the IIsFtpVirtualDir object, usually as a result of a previous GetObject
operation.
Method
Can Contain
IIsFtpVirtualDir
Properties
Metabase Properties
AccessFlags IPSecurity
AccessRead Path
AccessWrite UNCPassword
DontLog UNCUserName
FtpDirBrowseShowLongDate
Methods


ADSI Container Object Methods Standard methods for ADSI container objects
IIsIPSecurity
The IIsIPSecurity object is a custom ADSI object that you can use to set access permissions by IP
address and domain address.
The IIsIPSecurity Boolean property, GrantByDefault, determines if access by users is granted or

denied by default.
If GrantByDefault is set to TRUE, then all IP addresses and Internet domains are granted access,
except those you specify to be denied. Use IPDeny and DomainDeny to deny access to specific IP
addresses and domains.
Note IPDeny and DomainDeny are only valid if GrantByDefault is set to TRUE.
If GrantByDefault is set to FALSE, then all IP addresses and domains are denied access by default,
except those you specify to be granted access. Use IPGrant and DomainGrant to grant access to
specific IPs and domains.
Note IPGrant and DomainGrant are only valid if GrantByDefault is set to FALSE.
ADsPath
IIS://MachineName/W3SVVC/N/ROOT
IIS://MachineName/W3SVC/N/ROOT/vdirName
Syntax
Parts
varReturn


object
A variable that contains the IIsIPSecurity object, usually as a result of a previous GetObject
operation.
Method
Valid Locations
Key Type Metabase Path

IIsWebService /LM/W3SVC/
IIsWebServer /LM/W3SVC/1
IIsWebFile /LM/W3SVC/1/ROOT/vdirName/text.htm
IIsWebDirectory /LM/W3SVC/1/ROOT/vdirName/subdirectory
IIsFtpVirtualDir /LM/SMFTPSVC/1/ROOT/vdirName
IIsFtpService /LM/SMFTPSVC/
IIsFtpServer /LM/SMFTPSVC/1
IIsWebVirtualDir /LM/W3SVC/1/ROOT/Samples
IIsIPSecurity Properties
IPDeny This method accesses an array of IP addresses

that are not allowed access to the server.
IPGrant This method accesses an array of IP addresses
that are allowed access to the server.
DomainDeny This method accesses an array of domains that
are not allowed access to the server.
DomainGrant This method accesses an array of domains that
are allowed access to the server.
GrantByDefault This Boolean property determines if access is
granted by default or not. If GrantByDefault is
Note This property is valid only when used in set to TRUE, then you can use IPDeny and
the context of the IIsIPSecurity object. DomainDeny to deny access by specific IP
addresses and domains. If GrantByDefault is
set to FALSE, then you can use IPGrant and
DomainGrant to grant access by specific IP
addresses and domains.
Metabase Properties

ADSI Object Properties A list of properties valid at multiple objects.

IPSecurity This property specifies the IP access restrictions
for a URL. It can be used to grant or deny access
to client browsers based on either their IP address
or DNS host name.
IPDeny
You can use the IPDeny property of the IIsIPSecurity object to edit lists of IP addresses, held in an
array, that are not allowed access to the server.
Syntax
SecObj.IPDeny "IPAddress,SubnetMask"
Parameters
SecObj
An IIS Admin Object of type IIsIPSecurity.
IPAddress
This is a specific IP address you want to deny access to the server.
SubnetMask
This is the subnet mask for the specified IP address.
Code Example
<%
Dim SecObj
Dim MyIPSec
Dim IPList, DomainList
Set SecObj = GetObject("IIS://LocalHost/W3SVC/1")
Set MyIPSec = SecObj.IPSecurity
'Test value of MyIPSec.GrantByDefault here.
DomainList = MyIPSec.DomainDeny
IPList = MyIPSec.IPDeny
Redim IPList (Ubound(IPList)+1)
IPList (Ubound(IPList)) = "123.0.0.1,255.255.255.0"
Redim DomainList (Ubound(DomainList)+1)
DomainList (Ubound(DomainList)) = "somedomain.com"
IPSec.DomainDeny = DomainList
IPSec.IPDeny = IPList
Set SecObj.IPSecurity = MyIPSec
DirOjb.Setinfo
%>

See Also
IPGrant, DomainDeny, DomainGrant, GrantByDefault, IIsIPSecurity
IPGrant
You can use the IPGrant property of the IIsIPSecurity object to edit lists of IP addresses, in an array,
that are not allowed access to the server.
Syntax
SecObj.IPGrant "IPAddress,SubnetMask"
Parameters
SecObj
IPAddress
This is a specific IP address you want to grant access to the server.
SubnetMask
This is the subnet mask for the specified IP address.
Code Example
<%
Dim SecObj
Dim MyIPSec
DomainList = MyIPSec.DomainGrant
IPList = MyIPSec.IPGrant
IPSec.DomainGrant = DomainList
IPSec.IPGrant = IPList
Ojb.Setinfo
%>
See Also
IPDeny, DomainDeny, DomainGrant, GrantByDefault, IIsIPSecurity

DomainDeny
You can use the DomainDeny property of the IIsIPSecurity object to edit lists of domains that are not
allowed access to the server.
Syntax
SecObj.DomainDeny Domain
Parameters
SecObj
Domain
This is the domain you want denied access to the server.
Code Example
<%
Dim SecObj
Dim MyIPSec
DomainList = MyIPSec.DomainDeny
IPList = MyIPSec.IPDeny
IPSec.DomainDeny = DomainList
IPSec.IPDeny = IPList
Ojb.Setinfo
%>
See Also
IPDeny, IPGrant, DomainGrant, GrantByDefault, IIsIPSecurity
DomainGrant
You can use the DomainGrant property of the IIsIPSecurity object to edit lists of domains that are

allowed access to the server.
Syntax
SecObj.DomainGrant Domain
Parameters
SecObj
Domain
This is the domain you want granted access to the server.
Code Example
<%
Dim SecObj
Dim MyIPSec
DomainList = MyIPSec.DomainGrant
IPList = MyIPSec.IPGrant
IPSec.DomainGrant = DomainList
IPSec.IPGrant = IPList
Ojb.Setinfo
%>
See Also
IPDeny, IPGrant, DomainDeny, GrantByDefault, IIsIPSecurity
GrantByDefault
You can use the GrantByDefault property of the IIsIPSecurity object to set how you would like to
specify server access. GrantByDefault is a Boolean property which determines whether the default
setting is grant all with exceptions or deny all with exceptions. If GrantByDefault is TRUE, then all IP
addresses and domains are granted access to the server (with the exception of the list entries of the
DomainDeny and IPDeny methods). If GrantByDefault is FALSE, then all IP addresses and
domains are denied access to the server (with the exception of the list entries of the DomainGrant and
IPGrant methods).
Syntax

SecObj.GrantByDefault Boolean
Parameters
SecObj
Boolean
This is a value of TRUE or FALSE.
Code Example
<%
Dim SecObj
'Set permissions to grant access by default.
SecObj.GrantByDefault=TRUE
SecObj.SetInfo
%>
See Also
IPDeny, IPGrant, DomainDeny, DomainGrant, IIsIPSecurity
IIsLogModule
You can use the IIsLogModule object to set metabase properties that affect the operation of logging
modules. You can set filter properties at the computer level (IIsComputer), at the FTP and Web
service level, or for an individual FTP or Web server.
The IIsLogModule object is an ADSI object, but not an ADSI container object.
ADsPath
IIS://MachineName/LOGGING/LogModuleName
where MachineName can be any name or "LocalHost," and LogModuleName is the name of a log
module.
Syntax
Parts

varReturn
object
A variable that contains the IIsLogModule object, usually as a result of a previous GetObject
operation.
Method
Properties
Metabase Properties
LogModuleId LogModuleUiId
Methods
IIsLogModules
The IIsLogModules object is an ADSI container object that contains the collection of IIsLogModule
objects. You can use the IIsLogModules object to manage log modules at the computer level
(IIsComputer).
The IIsLogModules object is an ADSI container object.
ADsPath
IIS://MachineName/LOGGING
Syntax
Parts
varReturn
object
A variable that contains the IIsLogModules object, usually as a result of a previous GetObject

operation.
Method
Can Contain
IIsLogModule
Properties
Methods

Code Example
<%
'Get log properties for a log module at a server.
Dim LoggingModules, CurrentObj
'Get the object for the first Web server.
Set CurrentObj = GetObject("IIS://LocalHost/W3SVC/1")
'Access the log modules at the computer level.
Set LoggingModules = GetObject("IIS://LocalHost/logging")
'Loop through the installed modules to find the currently
'selected module at this server.
If CurrentObj.LogPluginClsid <> "" Then
For Each LogModule in LoggingModules
If LogModule.LogModuleID = CurrentObj.LogPluginClsid Then
Response.Write LogModule.Name & "<BR>"
End If
Next
'Display a property of the current module.
Response.Write CurrentObj.LogFileDate
End If
%>
IIsMimeMap
You can use the IIsMimeMap object to set the inherited Multipurpose Internet Mail Extensions
(MIME) mappings used by the Web servers.
The IIsMimeMap object is an ADSI object, but not an ADSI container object.
ADsPath
IIS://MachineName/MIMEMAP

Syntax
Parts
varReturn
object
A variable that contains the IIsMimeMap object, usually as a result of a previous GetObject
operation.
Method
Properties
Metabase Properties
MimeMap
Methods
Code Example
<%
Dim MimeMapObj, aMimeMap, MMType, MMExtension, i, aMimeMapNew()
Const ADS_PROPERTY_UPDATE = 2
'Get the mimemap object.
Set MimeMapObj = GetObject("IIS://LocalHost/MimeMap")
'Get the mappings from the MimeMap property.
aMimeMap = MimeMapObj.GetEx("MimeMap")
' Display the mappings.
ShowMM(MimeMapObj)
' Add a new mapping.
i = UBound(aMimeMap) + 1
Redim Preserve aMimeMap(i)
Set aMimeMap(i) = CreateObject("MimeMap")
aMimeMap(i).Extension = ".jnq"
aMimeMap(i).MimeType = "junque/my-junque"
MimeMapObj.PutEx ADS_PROPERTY_UPDATE, "MimeMap", aMimeMap
MimeMapObj.SetInfo
' Display the mappings.
ShowMM(MimeMapObj)
'Delete a mapping by copying to a new map array.
i = 0
For Each MMItem in aMimeMap

If MMItem.Extension <> ".jnq" Then

Redim Preserve aMimeMapNew(i)
Set aMimeMapNew(i) = CreateObject("MimeMap")
aMimeMapNew(i).Extension = MMItem.Extension
aMimeMapNew(i).MimeType = MMItem.MimeType
i = i + 1
End If
Next
MimeMapObj.PutEx ADS_PROPERTY_UPDATE, "MimeMap", aMimeMapNew
MimeMapObj.SetInfo
'Display the mappings.
ShowMM(MimeMapObj)
'Subroutine to display the mappings in a table.
Sub ShowMM(MMObj)
aMM = MMObj.GetEx("MimeMap")
'Set up table to display mappings.
Response.Write "<HR><TABLE BORDER><CAPTION><B>MIME Maps</B></CAPTION>"
Response.Write "<TR><TH>Type</TH><TH>Extension</TH>"
'Display the mappings in the table.
For Each MM in aMM
Response.Write "<TR><TD>" & MM.MimeType & "</TD>"
Response.Write "<TD>" & MM.Extension & "</TD></TR>"
Next
Response.Write "</TABLE>"
End Sub
%>
IIsMimeType
The MimeMap property contains an array of IISMimeType objects. To add to the array, create a
new IISMimeType object, set its MimeType , create the Extension, add the element to the
MimeMap array, and set it in ADSI.
The IIsMimeType object is a custom ADSI Automation object.
Syntax
varMimeMap = object.MimeMap
Set objMimeType = aMimeMap(0)
Parts
aMimeMap
A variable that receives the list of IIsMimeType objects.
object
A variable that supports the MimeType property, usually as a result of a previous GetObject
operation.
objMimeType

An object variable that receives the IIsMimeType object.
Can Contain
This object cannot contain any other objects.
Properties
Metabase Properties
MimeMap This property provides a list of the file name

extensions for Multipurpose Internet Mail
Extensions (MIME) mappings. MimeMap is an
array of IISMimeType objects.
Object Properties
MimeType This property can be used to GET and PUT the

MimeType for the object.
Extension This property can be used to GET and PUT the
file name extension assigned to the object.
See Also
IIsMimeMap, MimeMap
MimeType
You can use the MimeType property of the IIsMimeType object to GET and PUT the MIME types
for objects of type IISMimeType .
Syntax
DirObj.MimeType =string
Parameters
DirObj
An IIS Admin Object of type IIsMimeType .
string
This is a string that specifies the MIME type for the object.
Code Example

<%
Dim DirObj
Dim MimeMapNode
Dim MimeMapList
Dim MimeMapEntry
Set Obj = GetObject("IIS://LH/MimeMap")
MimeMapList = DirObj.MimeMap
Redim preserve MimeMapList (Ubound(MimeMapList)+1)
Set MimeMapEntry = CreateObject ("IIsMimeTypeEntry")
MimeMapEntry.MimeType = "Text/Plain"
Mime.Extension = ".log"
Set MimeMapList (Ubound(MimeMapList)) = MimeMapEntry
DirObj.MimeMap = MimeMapList
DirObj.Setinfo
%>
See Also
IIsMimeType , Extension
Extension
Use the Extension property of the IIsMimeType object to specify the MIME type of the file name
extension.
Syntax
DirObj.Extension = String
Parameters
DirObj
An IIS Admin Object of type IIsMimeType .
String
This is the specific file name extension associated with the MIME type specified in the
MimeType property.
Code Example
<%
Dim DirObj
Dim MimeMapNode
Dim MimeMapList
Dim MimeMapEntry
Set Obj = GetObject("IIS://LH/MimeMap")
MimeMapList = DirObj.MimeMap
Redim preserve MimeMapList (Ubound(MimeMapList)+1)
Set MimeMapEntry = CreateObject ("IIsMimeTyepEntry")
MimeMapEntry.MimeMap = "Text/Plain"

Mime.Extension = ".log"
Set MimeMapList (Ubound(MimeMapList)) = MimeMapEntry
DirObj.MimeMap = MimeMapList
DirObj.Setinfo
%>
See Also
MimeType , IIsMimeType
IIsWebDirectory
The IIsWebDirectory object is used to set metabase properties that apply to one or more Web
directories for a Web server. When you use the IIsWebDirectory object to set metabase properties for
a Web directory, inheritable properties will apply to all subdirectories and files.
You can also use IIsWebDirectory methods to create and manage Web applications in Web
directories and subdirectories. Applications can also be defined and managed in virtual directories by
using IIsWebVirtualDir.
The IIsWebDirectory object is an ADSI container object.
ADsPath
IIS://MachineName/W3SVC/N/ROOT/vdirName/DirName
Syntax
Parts
varReturn
object
A variable that contains the IIsWebDirectory object, usually as a result of a previous GetObject
operation.
Method
Can Contain
IIsWebDirectory IIsWebFile

Properties
Metabase Properties
A – Asp...
AccessExecute AspBufferingOn
AccessFlags AspCodepage
AccessNoRemoteExecute AspEnableApplicationRestart
AccessNoRemoteRead AspEnableAspHtmlFallback
AccessNoRemoteScript AspEnableChunkedEncoding
AccessNoRemoteWrite AspEnableParentPaths
AccessRead AspEnableTypelibCache
AccessScript AspErrorsToNTLog
AccessSSL AspExceptionCatchEnable
AccessSSL128 AspLogErrorRequests
AccessSSLFlags AspProcessorThreadMax
AccessSSLMapCert AspQueueConnectionTestTime
AccessSSLNegotiateCert AspQueueTimeout
AccessSSLRequireCert AspRequestQueueMax
AccessWrite AspScriptEngineCacheMax
AnonymousPasswordSync AspScriptErrorMessage
AnonymousUserName AspScriptErrorSentToBrowser
AnonymousUserPass AspScriptFileCacheSize
AppAllowClientDebug AspScriptLanguage
AppAllowDebugging AspScriptTimeout
AppFriendlyName AspSessionMax
AppIsolated AspSessionTimeout
AppOopRecoverLimit AspThreadGateEnabled
AppPackageID AspThreadGateLoadHigh
AppPackageName AspThreadGateLoadLow
AppRoot AspThreadGateSleepDelay

AppWamClsID AspThreadGateSleepMax
AspAllowOutOfProcComponents AspThreadGateTimeSlice
AspAllowSessionState AspTrackThreadingModel
Auth... – U
AuthAnonymous DirBrowseShowSize
AuthBasic DirBrowseShowTime
AuthFlags DontLog
AuthNTLM EnableDefaultDoc
AuthPersistence EnableDirBrowsing
AuthPersistSingleRequest EnableDocFooter
AuthPersistSingleRequestIfProxy EnableReverseDns
AuthPersistSingleRequestAlwaysIfProxy HttpCustomHeaders
CacheControlCustom HttpErrors
CacheControlMaxAge HttpExpires
CacheControlNoCache HttpPics
CacheISAPI HttpRedirect
ContentIndexed IPSecurity
CpuAppEnabled LogonMethod
CpuCgiEnabled MimeMap
CreateCGIWithNewConsole PoolIDCTimeout
CreateProcessAsUser PutReadSize
DefaultDoc Realm
DefaultDocFooter RedirectHeaders
DefaultLogonDomain ScriptMaps
DirBrowseFlags SSIExecDisable
DirBrowseShowDate UNCAuthenticationPassthrough
DirBrowseShowExtension UploadReadAheadSize
DirBrowseShowLongDate
Methods

AppCreate Creates an application at a specified metabase

key (parameter is a Boolean).
AppCreate2 Creates an application at a specified metabase
key (parameter is a Long).
AppDelete Deletes an application definition at a specified
key.
AppDeleteRecursive Deletes application definitions at a specified key
and subkeys.
AppDisable Disables an application at a specified key.
AppDisableRecursive Disables applications at a specified key and
subkeys.
AppEnable Enables an application that was previously
disabled at a specified key.
AppEnableRecursive Enables applications that were previously disabled
at a specified key and subkeys.
AppGetStatus Retrieves the status of an application.
AppUnload Unloads an application at a specified key.
AppUnloadRecursive Unloads applications at a specified key and
subkeys.
AspAppRestart This method restarts the ASP application that
invoked it.
See Also

Remarks
Web directories can be nested, and are addressed with the path to the directory, including the directory
name (for example .../vdirName/Dir1/Dir1a/Dir1ab, and so on).
AppCreate
You can use the AppCreate method of the IIsWebDirectory or IIsWebVirtualDir object to create a
Web application definition and mark it as running in-process or out-of-process. If an application already
exists at the specified path, you can use this method to reconfigure the application from in-process to
out-of-process, or the reverse.

Syntax
DirObj.AppCreate InProcFlag
Parameters
DirObj
An IIS Admin Object of type IIsWebDirectory or IIsWebVirtualDir.
InProcFlag
Specifies whether the application being created is to run in-process (TRUE) or out-of-process
(FALSE). If the application already exists and is running in-process, specifying this flag as FALSE
will cause the application definition to be deleted and a new application created to run out-of-
process. If the application already exists and is running out-of-process, specifying this flag as
TRUE will cause the application definition to be deleted and a new application created to run in-
process. If the application exists, and the setting of InProcFlag matches the application's existing
in-process or out-of-process status, then this method will cause no change to the application
definition.
Code Example
<%
Dim DirObj
Const INPROC = True
Const OUTPROC = False
Set DirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppDir")
'Create an application in-process.
DirObj.AppCreate INPROC
%>
See Also
AppCreate2, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive,

AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive,
AspAppRestart
AppCreate2
You can use the AppCreate2 method of the IIsWebDirectory or IIsWebVirtualDir object to create
a Web application definition and mark it as running in-process, out-of-process, or in a process pool. If
an application already exists at the specified path, you can use this method to reconfigure the application
to run in whatever process space you want.
Syntax
DirObj.AppCreate InProcFlag

Parameters
DirObj
InProcFlag
Binary value that specifies whether the application being created is to run in-process (0), out-of-
process (1), or in a pooled process (2). If the application already exists and is running , changing
the value of this flag will cause the application definition to be deleted and a new application
created to run in the specified process space.
Code Example
<%
Dim DirObj
Const INPROC = 0
Const OUTPROC = 1
Const POOLED = 2
'Create an application in-process.
DirObj.AppCreate INPROC
%>
See Also
AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive,

AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive,
AspAppRestart
AppDelete
You can use the AppDelete method of the IIsWebDirectory or IIsWebVirtualDir object to delete a
Web application definition from a metabase key. If the application is running, it will be shut down. If the
application is in-process with IIS, all resources associated with the application, such as out-of-process
applications, will be released if the resource is not referenced by another in-process application.
Note Server component DLLs are not released from in-process applications, even if they are not
currently referenced by other applications.
Deletions performed by using AppDelete cannot be undone.
Syntax
DirObj.AppDelete
Parameters

DirObj
An IIS Admin object of type IIsWebDirectory or IIsWebVirtualDir.
Code Example
<%
Dim DirObj
'Delete the application at this directory.
DirObj.AppDelete
%>
See Also
AppCreate, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus,

AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive, AspAppRestart
AppDeleteRecursive
You can use the AppDeleteRecursive method of the IIsWebDirectory or IIsWebVirtualDir object
to delete Web application definitions from a metabase key and all subkeys. If the applications are
running, they will be shut down. If the application is in-process with IIS, all resources associated with the
application, such as out-of-process packages, will be released if the resource is not referenced by
another in-process application.
Note Server component DLLs are not released from in-process applications, even if they aren't
Deletions performed using AppDeleteRecursive cannot be undone.
Syntax
DirObj.AppDeleteRecursive
Parameters
DirObj
Code Example
<%
Dim DirObj
'Delete the application at this directory
'and all subdirectories.
DirObj.AppDeleteRecursive

%>
See Also
AppCreate, AppDelete, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable,

AppDisableRecursive, AppEnable, AppEnableRecursive, AspAppRestart
AppDisable
You can use the AppDisable method of the IIsWebDirectory or IIsWebVirtualDir object to disable
a Web application that is running out-of-process. All of the application's resources are released and the
application's process is terminated. Attempts to access this application will fail. You can use the
AppEnable method to re-enable a disabled application. Both methods are used primarily when moving,
copying, or renaming metabase keys. The AppDisable method has no effect if the application is running
in-process.
Syntax
DirObj.AppDisable
Parameters
DirObj
Code Example
<%
Dim DirObj
'Disable the application at this directory.
DirObj.AppDisable
%>
See Also

AppGetStatus, AppDisableRecursive, AppEnable, AppEnableRecursive, AspAppRestart
AppDisableRecursive
You can use the AppDisableRecursive method of the IIsWebDirectory or IIsWebVirtualDir

object to disable Web applications that are running out-of-process. The applications at the specified key

and at all subordinate keys will be disabled. All of the application resources are released and the
application processes are terminated. Attempts to access this application will fail. You can use the
AppEnableRecursive method to re-enable disabled applications. Both methods are used primarily
when moving, copying, or renaming metabase keys. The AppDisableRecursive method has no effect if
the applications are running in-process.
Syntax
DirObj.AppDisableRecursive
Parameters
DirObj
Code Example
<%
Dim DirObj
'Disable the application at this directory
'and at all subdirectories.
DirObj.AppDisableRecursive
%>
See Also

AppGetStatus, AppDisable, AppEnable, AppEnableRecursive, AspAppRestart
AppEnable
You can use the AppEnable method of the IIsWebDirectory or IIsWebVirtualDir object to reinstate
a Web application definition that was previously disabled with the AppDisable method. If the
application specified was not previously deleted, it will be reregistered with Component Services.
Syntax
DirObj.AppEnable
Parameters
DirObj
Code Example

<%
Dim DirObj
'Enable the application at this directory.
DirObj.AppEnable
%>
See Also

AppGetStatus, AppDisable, AppDisableRecursive, AppEnableRecursive, AspAppRestart
AppEnableRecursive
You can use the AppEnableRecursive method of the IIsWebDirectory or IIsWebVirtualDir object
to reinstate Web application definitions that were previously disabled with the AppDisableRecursive
method. If the applications specified were not previously deleted, they will be reregistered with
Component Services.
Syntax
DirObj.AppEnableRecursive
Parameters
DirObj
Code Example
<%
Dim DirObj
'Enable the application at this directory
'and at all subdirectories.
DirObj.AppEnableRecursive
%>
See Also

AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AspAppRestart
AppGetStatus

You can use the AppGetStatus method of the IIsWebDirectory or IIsWebVirtualDir object to
retrieve the current status of a Web application.
Syntax
vReturn = DirObj.AppGetStatus
Parameters
vReturn
Receives the status of the application.
DirObj
Return Values
APPSTATUS_NOTDEFINED No application is defined at the specified path.

APPSTATUS_RUNNING The application is running.
APPSTATUS_STOPPED The application is not running.
Code Example
<%
Dim DirObj, vStatus
'Get the status of the application.
vReturn = DirObj.AppGetStatus
%>
See Also
AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppDisable,

AppUnload
You can use the AppUnload method of the IIsWebDirectory or IIsWebVirtualDir object to unload
a Web application that is running out-of-process. All of the application's resources are released and the
application's process is terminated. If the application is running in-process, the application is released if it
is not being referenced by any other applications.

Syntax
DirObj.AppUnload
Parameters
DirObj
Code Example
<%
Dim DirObj
'Unload the application at this directory.
DirObj.AppUnload
%>
See Also
AppCreate, AppDelete, AppDeleteRecursive, AppUnloadRecursive, AppGetStatus,

AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive, AspAppRestart
AppUnloadRecursive
You can use the AppUnloadRecursive method of the IIsWebDirectory or IIsWebVirtualDir object
to unload Web applications that are running out-of-process. The applications at the specified key and at
all subordinate keys will be unloaded. All of the application resources are released and the application
processes are terminated. If the application is running in-process, the application is released if it is not
being referenced by any other applications.
Syntax
DirObj.AppUnloadRecursive
Parameters
DirObj
Code Example

<%
Dim DirObj
'Unload the application at this directory
'and all subordinate directories.
DirObj.AppUnloadRecursive
%>
See Also
AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppGetStatus, AppDisable,

AspAppRestart
You can use the AspAppRestart method of the IIsWebDirectory or IIsWebVirtualDir object to
restart ASP applications. Users can use this method to restart ASP applications without accessing the
Global.asa file or stopping and starting the Web service itself. Essentially, a user can restart the
application on demand.
Syntax
DirObj.AspAppRestart()
Parameters
DirObj
An ASP application object of type IIsWebDirectory or IIsWebVirtualDir.
See Also

AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive
IIsWebFile
You can use the IIsWebFile object to set metabase key values that apply to a file in a Web directory
for a Web virtual server. Metabase property values set for a specific file will override inherited values
that have been set at a higher level in the metabase hierarchy.
The IIsWebFile object is an ADSI object, but not an ADSI container object.

ADsPath
IIS://MachineName/W3SVC/n/Root/vdirName/DirName/FileName
Syntax
Parts
varReturn
object
A variable that contains the IIsWebFile object, usually as a result of a previous GetObject
operation.
Method
Properties
Metabase Properties
AccessExecute CacheControlMaxAge
AccessFlags CacheControlNoCache
AccessNoRemoteExecute CpuAppEnabled
AccessNoRemoteRead CpuCgiEnabled
AccessNoRemoteScript CreateCGIWithNewConsole
AccessNoRemoteWrite CreateProcessAsUser
AccessRead DefaultDocFooter
AccessSource DefaultLogonDomain
AccessScript DontLog
AccessSSL EnableDocFooter
AccessSSL128 EnableReverseDns
AccessSSLFlags HttpCustomHeaders
AccessSSLMapCert HttpErrors
AccessSSLNegotiateCert HttpExpires

AccessSSLRequireCert HttpPics
AccessWrite HttpRedirect
AnonymousPasswordSync IPSecurity
AnonymousUserName LogonMethod
AnonymousUserPass MimeMap
AuthAnonymous PoolIDCTimeout
AuthBasic PutReadSize
AuthFlags Realm
AuthNTLM RedirectHeaders
AuthPersistence ScriptMaps
AuthPersistSingleRequest SSIExecDisable
AuthPersistSingleRequestIfProxy UNCAuthenticationPassthrough
AuthPersistSingleRequestAlwaysIfProxy UploadReadAheadSize
CacheControlCustom
Methods
IIsWebInfo
Some metabase properties associated with the Web service are stored at the Info subkey of the
W3SVC key. You can use the IIsWebInfo object to set values for these properties.
The IIsWebInfo object is an ADSI object, but not an ADSI container object.
ADsPath
IIS://MachineName/W3SVC/INFO
Syntax
Parts

varReturn
object
A variable that contains the IIsWebInfo object, usually as a result of a previous GetObject
operation.
Method
Properties
Metabase Properties
AdminServer ServerConfigFlags
CustomErrorDescriptions ServerConfigSSL128
LogModuleList ServerConfigSSL40
ServerConfigAutoPWSync ServerConfigSSLAllowEncrypt
Methods
IIsWebServer
You can use the IIsWebServer object to set metabase properties that apply to a specific Web virtual
server, and to set inheritable metabase properties for virtual directories, Web directories, and Web files.
Specific methods are also available to control server operation. Web virtual servers are identified in the
metabase by their index numbers. The first Web server is number 1, the second is number 2, and so on.
The IIsWebServer object is an ADSI container object.
ADsPath
IIS://MachineName/W3SVC/N
where MachineName can be any computer name or "LocalHost."
Syntax
varReturn = objWebServer.Method

Parts
varReturn
Specifies result value.
ObjWebServer
Refers to the IIS Admin Object.
Method
Specifies the method called.
Can Contain
IIsCertMapper IIsWebVirtualDir
IIsFilters
Properties
Metabase Properties
A – Asp...
AccessExecute AspAllowOutOfProcComponents
AccessFlags AspAllowSessionState
AccessNoRemoteExecute AspBufferingOn
AccessNoRemoteRead AspCodepage
AccessNoRemoteScript AspEnableApplicationRestart
AccessNoRemoteWrite AspEnableAspHtmlFallback
AccessRead AspEnableChunkedEncoding
AccessSource AspEnableParentPaths
AccessScript AspEnableTypelibCache
AccessSSL AspErrorsToNTLog
AccessSSL128 AspExceptionCatchEnable
AccessSSLFlags AspLogErrorRequests
AccessSSLMapCert AspProcessorThreadMax
AccessSSLNegotiateCert AspQueueConnectionTestTime
AccessSSLRequireCert AspQueueTimeout
AccessWrite AspRequestQueueMax
AdminACL AspScriptEngineCacheMax

AllowKeepAlive AspScriptErrorSentToBrowser
AllowPathInfoForScriptMappings AspScriptFileCacheSize
AnonymousPasswordSync AspScriptLanguage
AnonymousUserName AspSessionMax
AnonymousUserPass AspScriptTimeout
AppAllowClientDebug AspSessionTimeout
AppAllowDebugging AspThreadGateEnabled
AppFriendlyName AspThreadGateLoadHigh
AppIsolated AspThreadGateLoadLow
AppOopRecoverLimit AspThreadGateSleepDelay
AppPackageID AspThreadGateSleepMax
AppPackageName AspThreadGateTimeSlice
AppRoot AspTrackThreadingModel
AppWamClsID
Auth... – I
AuthAnonymous CpuLimitProcStop
AuthBasic CpuLimitsEnabled
AuthFlags CpuLoggingInterval
AuthNTLM CpuLoggingMask
AuthPersistence CpuLoggingOptions
AuthPersistSingleRequest CpuResetInterval
AuthPersistSingleRequestIfProxy CreateCGIWithNewConsole
AuthPersistSingleRequestAlwaysIfProxy CreateProcessAsUser
CacheControlCustom DefaultDoc
CacheControlMaxAge DefaultDocFooter
CacheControlNoCache DefaultLogonDomain
CacheISAPI DirBrowseFlags
CGITimeout DirBrowseShowDate
ConnectionTimeout DirBrowseShowExtension
CpuAppEnabled DirBrowseShowLongDate
CpuCgiEnabled DirBrowseShowSize

CpuEnableActiveProcs DirBrowseShowTime
CpuEnableAllProcLogging DisableSocketPooling
CpuEnableAppLogging DontLog
CpuEnableCgiLogging EnableDefaultDoc
CpuEnableEvent EnableDirBrowsing
CpuEnableKernelTime EnableDocFooter
CpuEnableLogging EnableReverseDns
CpuEnablePageFaults FrontPageWeb
CpuEnableProcType HttpCustomHeaders
CpuEnableTerminatedProcs HttpErrors
CpuEnableTotalProcs HttpExpires
CpuEnableUserTime HttpPics
CpuLimitLogEvent HttpRedirect
CpuLimitPause IPSecurity
CpuLimitPriority
Log...
LogExtFileSiteName LogonMethod

LogExtFileTimeTaken LogType
M–U
MaxBandwidth RedirectHeaders
MaxBandwidthBlocked ScriptMaps
MaxConnections SecureBindings
MaxEndpointConnections ServerAutoStart
MimeMap ServerBindings
NetLogonWorkstation ServerComment
NotDeletable ServerListenBacklog
NTAuthenticationProviders ServerListenTimeout
PasswordCacheTTL ServerSize
PasswordChangeFlags ServerState
PasswordExpirePrenotifyDays SSIExecDisable
PoolIDCTimeout UNCAuthenticationPassthrough
ProcessNTCRIfLoggedOn UploadReadAheadSize
PutReadSize UseHostName
Realm
Methods
Continue Resumes the server.

Pause Pauses the server.
Start Starts the server.
Status Retrieves the current status of the server.
Stop Stops the server.
See Also

Continue

The Continue method of the IIsWebServer object continues the server operation after it has been
paused.
Syntax
IIsWebServer.Continue
Code Example
<%
Dim ServerObj
'Continue the second Web server.
Set ServerObj = GetObject("IIS://LocalHost/W3SVC/2")
ServerObj.Continue
%>
See Also
Start, Pause, Stop, Status
Pause
The Pause method of the IIsWebServer object pauses the server operation.
Syntax
IIsWebServer.Pause
Code Example
<%
Dim ServerObj
'Pause the second Web server.
Set ServerObj = GetObject("IIS://LocalHost/W3SVC/2"
ServerObj.Pause
%>
See Also
Start, Continue, Stop, Status
Start

The Start method of the IIsWebServer object starts the server operation.
Syntax
IIsWebServer.Start
Code Example
<%
Dim ServerObj
'Start the second Web server.
ServerObj.Start
%>
See Also
Pause, Continue, Stop, Status
Status
The Status method of the IIsWebServer object returns an integer that indicates the current status of the
server. The possible values are 1 (starting), 2 (started), 3 (stopping), 4 (stopped), 5 (pausing), 6
(paused), or 7 (continuing).
Syntax
IIsWebServer.Status
See Also
Start, Pause, Continue, Stop
Stop
The Stop method of the IIsWebServer object stops the server operation.
Syntax

IIsWebServer.Stop
Code Example
<%
Dim ServerObj
'Stop the second Web server.
ServerObj.Stop
%>
See Also
Start, Pause, Continue, Status
IIsWebService
You can use the IIsWebService object to set inheritable metabase properties for Web sites and Web
virtual directories. The DownlevelAdminInstance property indicates the specific Web server instance
to administer (for IIS 2.0 Internet Server Manager clients performing remote administration of IIS 5.0).
The IIsWebService object is an ADSI container object. For more information, see ADSI Features.
ADsPath
IIS://MachineName/W3SVC
where MachineName can be any computer name or "LocalHost."
Syntax
Parts
varReturn
object
A variable that contains the IIsWebServer object, usually as a result of a previous GetObject
operation.
Method
Can Contain

IIsFilters IIsWebServer
IIsWebInfo
Properties
Metabase Properties
A – Asp...
AccessExecute AspAllowSessionState
AccessFlags AspBufferingOn
AccessNoRemoteExecute AspCodepage
AccessNoRemoteRead AspEnableApplicationRestart
AccessNoRemoteScript AspEnableAspHtmlFallback
AccessNoRemoteWrite AspEnableChunkedEncoding
AccessRead AspEnableParentPaths
AccessSource AspEnableTypelibCache
AccessScript AspErrorsToNTLog
AccessSSL AspExceptionCatchEnable
AccessSSL128 AspLogErrorRequests
AccessSSLFlags AspProcessorThreadMax
AccessSSLMapCert AspQueueConnectionTestTime
AccessSSLNegotiateCert AspQueueTimeout
AccessSSLRequireCert AspRequestQueueMax
AccessWrite AspScriptEngineCacheMax
AdminACL AspScriptErrorMessage
AllowPathInfoForScriptMappings AspScriptErrorSentToBrowser
AnonymousPasswordSync AspScriptFileCacheSize
AnonymousUserName AspScriptLanguage
AnonymousUserPass AspSessionMax
AppAllowClientDebug AspScriptTimeout
AppAllowDebugging AspSessionTimeout

AppFriendlyName AspThreadGateEnabled
AppIsolated AspThreadGateLoadHigh
AppPackageID AspThreadGateLoadLow
AppPackageName AspThreadGateSleepDelay
AppRoot AspThreadGateSleepMax
AppWamClsID AspThreadGateTimeSlice
AspAllowOutOfProcComponents AspTrackThreadingModel
Auth... – I
AuthAnonymous CpuLimitsEnabled
AuthBasic CpuLoggingInterval
AuthFlags CpuLoggingMask
AuthNTLM CpuLoggingOptions
AuthPersistence CpuResetInterval
AuthPersistSingleRequest CreateCGIWithNewConsole
AuthPersistSingleRequestIfProxy CreateProcessAsUser
AuthPersistSingleRequestAlwaysIfProxy DefaultDoc
CacheControlCustom DefaultDocFooter
CacheControlMaxAge DefaultLogonDomain
CacheControlNoCache DirBrowseFlags
CacheISAPI DirBrowseShowDate
ContentIndexed DirBrowseShowExtension
ConnectionTimeout DirBrowseShowLongDate
CpuAppEnabled DirBrowseShowSize
CpuCgiEnabled DirBrowseShowTime
CpuEnableActiveProcs DirectoryLevelsToScan
CpuEnableAllProcLogging DisableSocketPooling
CpuEnableAppLogging DontLog
CpuEnableCgiLogging DownlevelAdminInstance
CpuEnableEvent EnableDefaultDoc
CpuEnableKernelTime EnableDirBrowsing
CpuEnableLogging EnableDocFooter

CpuEnablePageFaults EnableReverseDns
CpuEnableProcType HttpCustomHeaders
CpuEnableTerminatedProcs HttpErrors
CpuEnableTotalProcs HttpExpires
CpuEnableUserTime HttpPics
CpuLimitLogEvent HttpRedirect
CpuLimitPause InProcessIsapiApps
CpuLimitPriority IPSecurity
CpuLimitProcStop
Log...
LogExtFileSiteName LogonMethod
LogExtFileTimeTaken LogType
M–U
MaxConnections ScriptMaps
MaxEndpointConnections ServerAutoStart
MimeMap ServerBindings
NetLogonWorkstation ServerComment

NTAuthenticationProviders ServerListenBacklog
PasswordCacheTTL ServerListenTimeout
PasswordChangeFlags ServerSize
PasswordExpirePrenotifyDays SSIExecDisable
PoolIDCTimeout SSLUseDSMapper
ProcessNTCRIfLoggedOn UNCAuthenticationPassthrough
PutReadSize UploadReadAheadSize
Realm UseHostName
RedirectHeaders WAMUserName
WAMUserPass
Methods

ADSI Container Object Methods Standard methods for ADSI container objects
IIsWebVirtualDir
You can use the IIsWebVirtualDir object to set metabase properties that apply to one or all virtual
directories for a Web site. If you use the IIsWebVirtualDir object at the server's ROOT directory
(.../W3SVC/2/ROOT), inheritable property values will apply to all virtual subdirectories. You can set
properties for a specific virtual directory by using the IIsWebVirtualDir object for a specific virtual
directory (.../W3SVC/2/ROOT/AVdir).
You can also use IIsWebVirtualDir methods to create and manage Web applications in Web virtual
directories and virtual subdirectories. Applications can also be defined and managed in Web directories.
See IIsWebDirectory.
The IIsWebVirtualDir object is an ADSI container object.
ADsPath
IIS://MachineName/W3SVC/N/ROOT

IIS://MachineName/W3SVC/N/ROOT/vdirName
Syntax
Parts
varReturn
object
A variable that contains the IIsWebVirtualDir object, usually as a result of a previous
Method
Can Contain
IIsWebVirtualDir IIsWebFile
IIsWebDirectory
Properties
Metabase Properties
A – Asp...
AccessExecute AspBufferingOn
AccessFlags AspCodepage
AccessNoRemoteExecute AspEnableApplicationRestart
AccessNoRemoteRead AspEnableAspHtmlFallback
AccessNoRemoteScript AspEnableChunkedEncoding
AccessNoRemoteWrite AspEnableParentPaths
AccessRead AspEnableTypelibCache
AccessSource AspErrorsToNTLog
AccessScript AspExceptionCatchEnable
AccessSSL AspLogErrorRequests

AccessSSL128 AspProcessorThreadMax
AccessSSLFlags AspQueueConnectionTestTime
AccessSSLMapCert AspQueueTimeout
AccessSSLNegotiateCert AspRequestQueueMax
AccessSSLRequireCert AspScriptEngineCacheMax
AccessWrite AspScriptErrorMessage
AnonymousPasswordSync AspScriptErrorSentToBrowser
AnonymousUserName AspScriptFileCacheSize
AnonymousUserPass AspScriptLanguage
AppAllowClientDebug AspScriptTimeout
AppAllowDebugging AspSessionMax
AppFriendlyName AspSessionTimeout
AppIsolated AspThreadGateEnabled
AppOopRecoverLimit AspThreadGateLoadHigh
AppPackageID AspThreadGateLoadLow
AppPackageName AspThreadGateSleepDelay
AppRoot AspThreadGateSleepMax
AppWamClsID AspThreadGateTimeSlice
AspAllowOutOfProcComponents AspTrackThreadingModel
AspAllowSessionState
Auth... – U
AuthAnonymous DirBrowseShowTime
AuthBasic DontLog
AuthFlags EnableDefaultDoc
AuthNTLM EnableDirBrowsing
AuthPersistence EnableDocFooter
AuthPersistSingleRequest EnableReverseDns
AuthPersistSingleRequestIfProxy HttpCustomHeaders
AuthPersistSingleRequestAlwaysIfProxy HttpErrors
CacheControlCustom HttpExpires
CacheControlMaxAge HttpPics

CacheControlNoCache HttpRedirect
CacheISAPI IPSecurity
ContentIndexed LogonMethod
CpuAppEnabled MimeMap
CpuCgiEnabled Path
CreateCGIWithNewConsole PoolIDCTimeout
CreateProcessAsUser PutReadSize
DefaultDoc Realm
DefaultDocFooter RedirectHeaders
DefaultLogonDomain ScriptMaps
DirBrowseFlags SSIExecDisable
DirBrowseShowDate UNCAuthenticationPassthrough
DirBrowseShowExtension UNCPassword
DirBrowseShowLongDate UNCUserName
DirBrowseShowSize UploadReadAheadSize
Methods
AppCreate Creates an application at a specified metabase

key (parameter is a Boolean).
AppCreate2 Creates an application at a specified metabase
key (parameter is a Long).
AppDelete Deletes an application definition at a specified
key.
AppDeleteRecursive Deletes application definitions at a specified key
and its subkeys.
AppDisable Disables an application at a specified key.
AppDisableRecursive Disables applications at a specified key and its
subkeys.
AppEnable Enables an application that was previously
disabled at a specified key.
AppEnableRecursive Enables applications that were previously disabled
at a specified key and its subkeys.
AppGetStatus Retrieves the status of an application.
AppUnload Unloads an application at a specified key.

AppUnloadRecursive Unloads applications at a specified key and its

subkeys.
AspAppRestart This method restarts the ASP application that
invoked it.
See Also

Constants
The following constants are used with methods and properties of the IIS Admin Objects.
<%
Const ADS_PROPERTY_CLEAR = 1 'PutEx
Const ADS_PROPERTY_UPDATE = 2 'PutEx
Const APPSTATUS_NOTDEFINED = 4 'AppStatus
Const APPSTATUS_RUNNING = 2 'AppStatus
Const APPSTATUS_STOPPED = 3 'AppStatus
Const APPSTATUS_UNLOADED = 1 'AppStatus
Const IIS_ANY_PROPERTY = 0 'GetDataPaths
Const IIS_INHERITABLE_ONLY = 1 'GetDataPaths
Const MD_ERROR_DATA_NOT_FOUND = &H800CC801 'GetDataPaths
Const MD_ERROR_IISAO_INVALID_SCHEMA = &H8800CC810 'GetObject
Const MD_BACKUP_FORCE_BACKUP = 4 'Backup
Const MD_BACKUP_HIGHEST_VERSION = &HFFFFFFFE 'Backup, Delete, Restore
Const MD_BACKUP_MAX_VERSION = 9999 'Limit
Const MD_BACKUP_MAX_LEN = 100 'Limit
Const MD_BACKUP_NEXT_VERSION = &HFFFFFFFF 'Backup
Const MD_BACKUP_OVERWRITE = 1 'Backup
Const MD_BACKUP_SAVE_FIRST = 2 'Backup
Const MD_SERVER_STATE_CONTINUING = 7 'ServerState
Const MD_SERVER_STATE_PAUSING = 5 'ServerState
Const MD_SERVER_STATE_PAUSED = 6 'ServerState
Const MD_SERVER_STATE_STARTING = 1 'ServerState
Const MD_SERVER_STATE_STARTED = 2 'ServerState
Const MD_SERVER_STATE_STOPPING = 3 'ServerState
Const MD_SERVER_STATE_STOPPED = 4 'ServerState
Const NOT_A_VALID_PROPERTY = &H80005006 'Various methods
%>
ADSI Reference

The ADSI Reference section describes properties and methods that are exposed by the IIS Admin
Objects. This section contains:
? ADSI Object Properties: Describes the six basic properties that must be implemented by IIS
Admin Objects (Name, ADsPath, Class, GUID, Parent, and Schema).
? ADSI Object Methods: Lists the methods exposed by the IIS Admin Objects.
? ADSI Container Object Properties: Discusses additional attributes implemented by the IIS Admin
Container Object.
? ADSI Container Object Methods: Describes methods, implemented by the ADSI Container
Object, that manipulate IIS Admin Objects and metabase keys.
? ADSI Changes for IIS 5.0: A quick reference to IIS ADSI provider changes in IIS 5.0.

The IIS Admin Objects implement the six basic properties that ADSI objects require. The data type for
all of these properties is string.
ADSI Property Description

Name The name of the object used within the underlying
namespace.
ADsPath The path that uniquely identifies the object, and
which is used in GetObject to retrieve the object.
Class The name of the schema class of the object.
GUID A unique identifier for objects of this schema class.
IIS uses the globally unique identifier (GUID).
Parent The ADsPath of the parent container object.
Schema The ADsPath of the object that represents this
schema class in the schema.
The ADSI object properties are read-only and are provided for use with ADSI client programs for
ADSI namespace administration. The following table provides an example of the ADSI properties for the
IIsWebService object. LocalHost is a placeholder for the name of the local computer on which IIS is
running.
ADSI Property Value

Name W3SVC
ADsPath IIS://LocalHost/W3SVC
Class IIsWebService

GUID {8B645280-7BA4-11CF-B03D-
00AA006E0975}
Parent IIS://LocalHost
Schema IIS://LocalHost/schema/IIsWebService
You can use the ADSI Name property to document the structure of your IIS installation.
You can use the metabase properties supported by the IIS Admin Objects to control the configuration of
your IIS installation. See ADSI Object Methods and the specific metabase properties supported by each
of the individual IIS Admin Objects.
ADSI Object Methods

You can use the ADSI methods of the IIS Admin Objects to change metabase property values that
control your IIS configuration. To configure a specific element of IIS, open the IIS Admin Object that
corresponds to the metabase key associated with that element, modify the property values cached in the
object, and direct the object to store the modified values in the metabase.
The following ADSI methods are exposed by the IIS Admin Objects, and can be used to set or query
metabase properties.
Method Description
Get Retrieves a value for a named property from the object.
GetDataPaths Retrieves the paths to all locations of a metabase property subordinate to a
specified starting path.
GetEx Retrieves a value or values for a named single-valued or multivalued
property of the object.
GetInfo Reloads the object with property values that exist in the metabase.
GetPropertyAttribObj Retrieves an object that contains the property's attributes. This object can
then be used to retrieve individual attributes of ADSI properties.
Put Sets the value for a named property of an object.
PutEx Sets the value or values for a named single-valued or multivalued property
of the object.
SetInfo Writes the object property values to the metabase.
The GetInfo method reloads the property values from the metabase into the object. When one of the
IIS Admin Objects is created or opened with the GetObject function, its properties are initialized from
the metabase. You can refresh these values from the metabase by using the GetInfo method, and
overwriting any changes you have made to the property values cached in the object. You then use the

Get or GetEx methods to retrieve the object properties and assign these values to variables, and the
Put and PutEx methods to modify property values in the object.
The IIS Admin Objects also support the object.property syntax when used with languages such as
VBScript or JScript. You can use the SetInfo method to write property values from the object to the
metabase. When you call SetInfo, only the properties that you changed in the object are written back to
the metabase. If you do not call SetInfo, your changes will not be written to the metabase.
Note When you bind to the metabase to modify properties in one of the IIS Admin Objects, the
metabase is not locked while you are changing property values in the object. Other programs can make
changes to values in the metabase after you have retrieved values but before you save them back into the
metabase. Your program should minimize the time between retrieving and saving values.
ADSI properties apply only to the object, and non-ADSI properties apply to the metabase. You must
use the object.property syntax when retrieving ADSI properties, whereas you can use either the
object.property syntax or the ADSI methods such as Get and Put when manipulating metabase
properties.
Example
The following sample VBScript code shows how you can use the ADSI methods of the IIS Admin
Objects to change values in the metabase, and illustrates the use of metabase property inheritance for
efficiency. MyComputer is a placeholder for the name of the computer on which IIS is running.
<%
Dim WebServerObj
Dim VDirObj
Dim WritePerm
'Open the object for the first virtual Web server root.
Set WebServerObj = GetObject("IIS://MyComputer/W3SVC/1/Root")
'Deny write access for all directories and files

'for the server (except those already specifically set)
'by using the Put method.
WebServerObj.Put "AccessWrite", False
'Save the changed value to the metabase.

WebServerObj.SetInfo
'Get a directory subordinate to the Web server root.

Set VDirObj = GetObject("IIS://MyComputer/W3SVC/1/Root/Vdir1/Dir1a")
'Overwrite the inherited value for write access

'by using the dot method equivalent to Put.
VDirObj.AccessWrite = True
'Save the changed value to the metabase.

VDirObj.SetInfo
%>
Get

The ADSI Get method for IIS Admin Objects retrieves a metabase property value from the object and
stores it in a variable. Some languages, such as VBScript, also support the object.property syntax as an
alternative to the Get and Put methods.
Syntax
value = object.Get(property)
or
value = object.property
Parts
value
Receives the returned value of the property.
object
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
property
A property of the object that has been retrieved from the metabase.
Code Example
<%
Dim IIsObj, vRead, vWrite
Set IIsObj = GetObject("IIS://LocalHost/W3SVC/1/Root")
'Get the value from the object.
vRead = IIsObj.Get("AccessRead")
'Can also use object.property syntax.
vWrite = IIsObj.AccessWrite
'Set the values.
vRead = True
vWrite = False
'Put the values back in the object.
IIsObj.Put "AccessRead", vRead
'Use optional object.property syntax.
IIsObj.AccessWrite = vWrite
'Save the changes back to the metabase.
IIsObj.SetInfo
%>
See Also
GetInfo, SetInfo, Put, GetEx, PutEx
GetDataPaths

The ADSI GetDataPaths method can be used with any of the IIS Admin Objects to find the paths to
metabase keys where a specified property is located. This method can be used to find occurrences of a
property that could be preventing subkeys from inheriting values. The path search will start at the key
associated with the object you use GetDataPaths with, and will return the starting path if the property is
located at that key. For example, if you use GetDataPaths with the IIsWebServer object for the third
Web server, the search path would start at IIS://LocalHost/W3SVC/3 and would return the paths
IIS://LocalHost/W3SVC/3, IIS://LocalHost/W3SVC/3/ROOT/VDir1, and
IIS://LocalHost/W3SVC/3/ROOT/VDir1/Dir1/File1, if those were the keys where the property was
found.
A parameter of the method enables you to specify whether to limit your search to seeking only paths of
an inheritable property, or all property paths. You can use GetDataPaths to determine if a property is
inheritable, as well as where occurrences of it are located.
Syntax
PathList = object.GetDataPaths (property, AttributeFlag)
Parts
PathList
Receives the list of paths to occurrences of the specified property.
object
property
The name of the property whose paths are to be located.
AttributeFlag
One of the following flags:
IIS_ANY_PROPERTY Retrieve paths regardless of whether the
property is inheritable.
IIS_INHERITABLE_ONLY Retrieve paths only if the property is
inheritable. Return
MD_ERROR_DATA_NOT_FOUND if
property is not inheritable.
Remarks
You can use the For each Path in PathList...Next statement to retrieve individual paths from
PathList.
Code Example
<%
Const IIS_ANY_PROPERTY = 0
Const IIS_INHERITABLE_ONLY = 1
Const MD_ERROR_DATA_NOT_FOUND = &H800CC801
Dim WebSvrObj, PathList, vProperty

On Error Resume Next

'Get the object for the first Web server.
Set WebSvrObj = GetObject("IIS://LocalHost/W3SVC/1")
'Get the paths where a property is located.
vProperty = "AccessFlags"
PathList = WebSvrObj.GetDataPaths(vProperty, IIS_INHERITABLE_ONLY)
If Err.Number = 0 Then
Response.Write "Paths for property " & vProperty & "<BR>"
For each Path in PathList
Response.Write Path & "<BR>"
Next
ElseIf Err.Number = MD_ERROR_DATA_NOT_FOUND Then
Response.Write "Property is not inheritable.<BR>"
ElseIf Err.Number = &H80005006 Then
Response.Write "Property does not exist.<BR>"
Else
Response.Write "Error " & Err.Number & " " & Err.Description
End If
%>
GetEx
The ADSI GetEx method retrieves a single-valued or multivalued property value from the object and
puts it into a variant-array variable.
Syntax
value = object.GetEx(property)
Parts
value
Receives the returned property value from the method.
object
property
Return Values
Returns the value of the property.
Code Example
<%
Dim IIsObj, vList
Set IIsObj = GetObject("IIS://LocalHost/W3SVC/Info")
vList = IIsObj.GetEx("CustomErrorDescriptions")
'Modify the list.

'Put the values back in the object

IIsObj.PutEx 2, "CustomErrorDescriptions", vList
IIsObj.SetInfo
%>
See Also
GetInfo, SetInfo, Get, Put, PutEx
GetInfo
The ADSI GetInfo method re-initializes the object's properties by using values from the metabase.
Because the object's properties are automatically initialized when the object is created, you need to use
this method only if you want to refresh properties in the object with current values from the metabase.
Syntax
object.GetInfo
Parts
object
Code Example
<%
Dim IIsObj
'Make some changes to properties.
' . . .
'Discard changes and refresh property values in the object.
IIsObj.GetInfo
%>
See Also
SetInfo, Get, Put, GetEx, PutEx
GetPropertyAttribObj
You can use this method to access information about attributes for individual ADSI properties.
GetPropertyAttribObj works in the following way:

? Returns an object that contains the property's attributes if the property is set at that node or is set
at some parent node and is inheritable.
? Returns an Error if the property is not set at that node, or its parent node and is inheritable.
? Returns an Error if the property is not set at that node, but set at parent and not inheritable.
Syntax
Initializing:
PropAttObj = object.GetPropertyAttribObj(property)
Using:
RetBool = PropAttObj.Attribute
Parts
PropAttObj
Reference to an object that contains the property attributes for the property.
object
property
String that contains the name of the property whose attributes are being requested.
RetBool
Boolean that indicates whether the attribute specified by Attribute is enabled or disabled.
Attribute
Indicates which attribute is being queried. The possible attributes are:
Attribute Description
Inherit Specifies whether the property is inheritable.
PartialPath Indicates whether a partial path is present.
Secure Indicates whether the property is secure.
Reference Specifies if the property was received by a
reference.
Volatile Indicates whether the property is volatile.
IsInherited Specifies whether the property is inherited.
InsertPath Indicates whether a string in a property
contains a special insert value.
AllAttributes Contains all the attributes listed in this table
in one Long.
Remarks
Unlike most other ADSI objects, the property attributes object does not support Get and Set methods.

You must use the object.property syntax to access the individual attributes of the property attribute
object.
Note If a call is made to AppCreate, object path information will be persisted, but you must call
SetInfo before the given object is created. If SetInfo is not called, subsequent calls to the object
created will fail.
Put
The ADSI Put method sets the value for a metabase property in the object. Some languages, such as
VBScript, also support the object.property syntax as an alternative to the Get and Put methods.
Syntax
object.Put property, value
or
object.property = value
Parts
object
property
value
The value for the property.
Code Example
<%
Dim IIsObj, vRead, vWrite
vRead = IIsObj.Get("AccessRead")
'Can also use object.property syntax.
vWrite = IIsObj.AccessWrite
' Set the values.
vRead = True
vWrite = False
IIsObj.Put "AccessRead", vRead
'Use optional object.property syntax.
IIsObj.AccessWrite = vWrite
IIsObj.SetInfo
%>

See Also
GetInfo, SetInfo, Get, GetEx, PutEx
PutEx
The ADSI PutEx method sets the value for a single-valued or multivalued metabase property in the
object. You can use PutEx to remove, or clear, a property from a metabase key.
Syntax
object.PutEx controlcode, property, value
Parts
object
controlcode
Specifies whether to update the property, or to remove the property from the object. One of:
ADS_PROPERTY_CLEAR (value 1) to remove the property, or ADS_PROPERTY_UPDATE
(value 2) to update the property.
property
value
The value for the property. An empty string when removing the property (controlcode =
ADS_PROPERTY_CLEAR).
Remarks
For a metabase property to use inherited data at a key, the property must not already exist at the key; if
it does, you can remove it by using ADS_PROPERTY_CLEAR. (You can use the GetDataPaths
method common to all IIS Admin Objects to locate the keys where a property exists.)
Code Example
<%
Dim IIsObj, vList
Set IIsObj = GetObject("IIS://LocalHost/W3SVC/Info")
vList = IIsObj.GetEx("CustomErrorDescriptions")
'Modify the list.

IIsObj.PutEx 2, "CustomErrorDescriptions", vList
'Remove another property from the object.
IIsObj.PutEx 1, "ObsoleteProperty", ""
IIsObj.SetInfo
%>

See Also
GetInfo, SetInfo, Get, Put, GetEx
SetInfo
The ADSI SetInfo method saves changed property values from the object to the metabase. After you
have changed some or all of the values in the object properties, you must use the SetInfo method to
save the new values back into the metabase. Only the values you changed will be saved back into the
metabase; unchanged values will not be overwritten.
Syntax
object.SetInfo
Parts
object
Code Example
<%
Dim IIsObj
'Make some changes to properties.
' . . .
IIsObj.SetInfo
%>
Note If you attempt to create a custom object by calling AppCreate but fail to call SetInfo, any calls
to the custom object will fail because the path exists but the object does not exist. If a call to AppCreate
is made, preliminary information will be persisted, but the object will not be created until SetInfo is
called.
See Also
GetInfo, Get, Put, GetEx, PutEx
ADSI Container Object Properties

IIS Admin Objects that can contain other objects also can implement the ADSI container methods and

properties. This includes the following read-only ADSI container properties:
ADSI Container Property Description

_NewEnum Returns an Enumerator object that can be used to
retrieve the contained objects. This property
enables Automation languages such as VBScript to
enumerate contained objects using the "For Each
Object in ContainerObject" syntax.
Count The number of objects in the container object.
ADSI Container Object Methods

You can use the ADSI container object methods of the IIS Admin Objects to manipulate keys in the
metabase. You can create, delete, and move keys by creating, deleting, and moving IIS Admin Objects
within container objects. You can also enumerate contained objects such as virtual directories or servers
with container object methods.
These ADSI container object methods manipulate IIS Admin Objects and metabase keys:
Method Description
CopyHere Copies an object into a container.
Create Creates a new object in a container.
Delete Deletes an object from a container.
GetObject Accesses an object in a container.
MoveHere Copies an object into a container and deletes the original object.
Note When one of the IIS Admin Objects is a container object, it retains its own ADSI object
properties and methods as well as any IIS-specific methods and associated metabase properties.
CopyHere
The ADSI container object CopyHere method copies an object into a container.
Syntax
Set CopiedObj = Object.CopyHere(SourceName, NewName)

Parts
CopiedObj
Accesses the copied object in the container.
object
SourceName
The name of the object to be copied.
NewName
The new name for the copied object.
Remarks
The CopiedObj variable receives a pointer to the object itself, which remains in the container.
When the contained object to be copied is part of an application, the CopyHere method will remove the
application definition before copying the object. See the AppDelete method of the IIsWebVirtualDir
and IIsWebDirectory objects.
Code Example
<%
Dim ToVDirObj, FromVDirObj, RootVDirObj
'Get the root virtual directory object for a server.
Set RootVDirObj = GetObject("IIS://LocalHost/W3SVC/4/ROOT")
'Copy a virtual directory object.
'Also get a pointer to the new object.
Set ToVdirObj = RootVDirObj.CopyHere("VDir1", "VDir2")
RootVDirObj.SetInfo
%>
See Also
GetObject, Create, Delete, MoveHere
Create
The ADSI container object Create method creates a new object in a container.
Syntax
Set NewObj = Object.Create(KeyType, Name)
Parts
NewObj
Accesses the new object created in the container.

object
KeyType
The type of IIS Admin Object to create.
Name
The name for the new object.
Code Example
<%
Dim WebServiceObj, ServerObj
'Get the Web service object, which contains servers.
Set WebServiceObj = GetObject("IIS://LocalHost/W3SVC")
'Create a new Web server object in the container.
Set ServerObj = WebServiceObj.Create("IIsWebServer", "3")
'Add code to configure server and create root virtual directory.
%>
See Also
GetObject, Delete, CopyHere, MoveHere
Delete
The ADSI container object Delete method deletes an object from a container.
Syntax
Object.Delete KeyType, Name
Parts
object
KeyType
The type of IIS Admin Object to delete.
Name
The name of the object to delete.
Remarks
When the contained object to be deleted is part of an application, the Delete method will remove the
application definition before deleting the object. See the AppDelete method of the IIsWebVirtualDir
and IIsWebDirectory objects.
Code Example
<%

Dim WebServiceObj
'Delete the fourth server.
WebServiceObj.Delete "IIsWebServer", "4"
%>
See Also
GetObject, Create, CopyHere, MoveHere
GetObject
The ADSI container object GetObject method accesses an object in a container.
Syntax
Set ChildObj = Object.GetObject(Class, ChildName)
Parts
ChildObj
Accesses the object in the same way as the ASP GetObject function does.
Object
Class
Specifies the class of the object to be accessed.
ChildName
The name of the object to be accessed.
Remarks
The ChildObj variable receives a pointer to the object itself, which remains in the container.
Code Example
<%
Dim WebServiceObj, ServerObj
'Access the object for the third Web server.
Set ServerObj = WebServiceObj.GetObject("IIsWebServer", "3")
%>
See Also
Create, Delete, CopyHere, MoveHere

MoveHere
The ADSI container object MoveHere method moves an object into a container and removes the
object from its origin.
Syntax
Set MovedObj = Object.MoveHere (SourceName, NewName)
Parts
MovedObj
Accesses the object moved into the container.
object
SourceName
The name of the object to be moved.
NewName
The name for the moved object.
Remarks
The MovedObj variable receives a pointer to the object itself, which remains in the container.
The MoveHere method is equivalent to CopyHere followed by Delete.
When the contained object to be moved is part of an application, the MoveHere method will disable
the application definition before moving the object. See the AppDisable method of the
IIsWebVirtualDir and IIsWebDirectory objects.
Code Example
<%
Dim ToVDirObj, FromVDirObj, RootVDirObj
'Get the root virtual directory object for a server.
Set RootVDirObj = GetObject("IIS://LocalHost/W3SVC/3/ROOT")
'Get the object to be moved.
Set FromVDirObj = GetObject("IIS://LocalHost/W3SVC/3/ROOT/VDir1")
'Move the object and give it a new name.
Set ToVdirObj = RootVDirObj.MoveHere("VDir1", "VDir2")
'Release the source object because it has been deleted.
Set FromVDirObj = nothing
%>
See Also
GetObject, Create, Delete, CopyHere

ADSI Changes for IIS 5.0

This section contains information about the changes and additions in the ADSI provider for IIS 5.0.
? IIS Performance Features: Describes new performance features for IIS 5.0.
? ADSI Properties Removed from IIS 5.0: Lists any properties that were supported in previous
versions, but which are not valid for IIS 5.0.
? ADSI Properties Added to IIS 5.0: Provides a list of properties new to IIS 5.0, and links to each
property's full reference.
? ADSI Property Key Type Changes for IIS 5.0: Lists any properties whose key type has changed
for IIS 5.0.
? ADSI Properties Changed in IIS 5.0: Lists any properties that have different default behavior for
IIS 5.0.
IIS Performance Features
Site Socket Pooling
In IIS 4.0, each Web site was bound to a different IP address. This meant that each site had its own
socket, which was not shared with sites bound to other IP addresses. These sockets are created when
each site starts, and they can consume significant amounts of nonpaged memory (RAM). This memory
consumption limits the number of sites bound to IP addresses that can be created on a machine, because,
after a certain number of sites are started, the machine is out of RAM.
For IIS 5.0, this process has been modified so that sites bound to different IP addresses—but sharing
the same port number—share the same set of sockets. The end result is that more sites can be bound to
an IP address on the same machine than in IIS 4.0. In IIS 5.0, these shared sockets are used flexibly
among all of the started sites, thus reducing resource consumption.
This is now the default behavior for IIS 5.0. In general, this behavior should not be modified. However,
for critical sites that require a dedicated socket, you can set the DisableSocketPooling to TRUE to
revert back to the IIS 4.0 behavior. This change should be made at the site level only, so that other sites
can continue to take advantage of the new socket pooling feature.
ADSI Properties Removed from IIS 5.0
The following ADSI property is no longer available.

AspMemFreeFactor This property is no longer available.
ADSI Properties Added to IIS 5.0
ADSI properties new for IIS 5.0 include the following:
AccessSource CPUResetInterval
AspEnableApplicationRestart DisableSocketPooling
AspEnableAspHtmlFallback HcCacheControlHeader
AspEnableChunkedEncoding HcCompressionBufferSize
AspEnableTypelibCache HcCompressionDirectory
AspErrorsToNTLog HcCompressionDll
AspProcessorThreadMax HcCreateFlags
AspQueueConnectionTestTime HcDoDiskSpaceLimiting
AspRequestQueueMax HcDoDynamicCompression
AspSessionMax HcDoOnDemandCompression
AspTrackThreadingModel HcDoStaticCompression
CPUAppEnabled HcDynamicCompressionLevel
CPUCGIEnabled HcExpiresHeader
CPUCGILimit HcFileExtensions
CPUEnableActiveProcs HcFilesDeletedPerDiskFree
CPUEnableAllProcLogging HcIoBufferSize
CPUEnableAppLogging HcMaxDiskSpaceUsage
CPUEnableCGILogging HcMaxQueueLength
CPUEnableEvent HcMimeType
CPUEnableKernelTime HcMinFileSizeForComp
CPUEnablePageFaults HcNoCompressionForHttp10
CPUEnableProcType HcNoCompressionForProxies
CPUEnableTerminatedProcs HcNoCompressionForRange
CPUEnableTotalProcs HcOnDemandCompLevel

CPUEnableUserTime HcPriority
CPULimitLogEvent HcSendCacheHeaders
CPULimitPause LogCustomPropertyDataType
CPULimitPriority LogCustomPropertyHeader
CPULimitProcStop LogCustomPropertyID
CPULimitsEnabled LogCustomPropertyMask
CPULoggingInterval LogCustomPropertyName
CPULoggingMask LogCustomPropertyServicesString
CPULoggingOptions NotDeletable
SSLUseDSMapper
ADSI Property Key Type Changes for IIS 5.0
The metabase key types for the following properties have changed since IIS 4.0. To see the full property
reference for a key type, click on the link.
KeyType
FrontPageWeb
CacheISAPI
AspTrackThreadingModel
ADSI Properties Changed in IIS 5.0
There is only one property change to list at this time. Check the IIS 5.0 Alphabetical Property List for
detailed information.
Note For items that were implemented after the time of this release, see the Platform SDK.
Syntax change for ScriptMaps:
ScriptMaps property syntax has changed to required-verb inclusion rather than exclusion. (In previous
versions, it was possible to list verb exclusions, but this was not required for valid syntax.) Because of the
change from exclusions to inclusions, verbs are required in the property syntax. See ScriptMaps for
more details.

Administration Property Reference

Administration properties are associated with the values assigned to keys in the metabase. This reference
provides a description of each property, including the data type, default value, inheritance attribute, and
usage notes. For each property, the IIS Admin Objects that can access that property are listed. For
more information about the IIS Admin Objects, see Using IIS Admin Objects.
Note Additional IIS Admin Base Object information is provided for programmers who are
implementing required algorithms at the IIS Admin Base Object level.
? Alphabetical Property List: Provides quick access to individual property descriptions.

? ADSI vs. Base Object Data types: Provides a quick reference for those programmers
implementing required algorithms at the IIS Admin Base Object level.
Alphabetical Property List

A – Anon…
AccessExecute AccessSSLNegotiateCert
AccessFlags AccessSSLRequireCert
AccessNoRemoteExecute AccessWrite
AccessNoRemoteRead AdminACL
AccessNoRemoteScript AdminServer
AccessNoRemoteWrite AllowAnonymous
AccessRead AllowKeepAlive
AccessScript AllowPathInfoForScriptMappings
AccessSource AnonymousOnly
AccessSSL AnonymousPasswordSync
AccessSSL128 AnonymousUserName
AccessSSLFlags AnonymousUserPass
AccessSSLMapCert
App… – Asp…

AppAllowClientDebug AspLogErrorRequests
AppAllowDebugging AspProcessorThreadMax
AppFriendlyName AspQueueConnectionTestTime
AppIsolated AspQueueTimeout
AppOopRecoverLimit AspRequestQueueMax
AppPackageID AspScriptEngineCacheMax
AppPackageName AspScriptErrorMessage
AppRoot AspScriptErrorSentToBrowser
AppWamClsID AspScriptFileCacheSize
AspAllowOutOfProcComponents AspScriptLanguage
AspAllowSessionState AspScriptTimeout
AspBufferingOn AspSessionMax
AspCodepage AspSessionTimeout
AspEnableApplicationRestart AspThreadGateEnabled
AspEnableAspHtmlFallback AspThreadGateLoadHigh
AspEnableChunkedEncoding AspThreadGateLoadLow
AspEnableParentPaths AspThreadGateSleepDelay
AspEnableTypelibCache AspThreadGateSleepMax
AspErrorsToNTLog AspThreadGateTimeSlice
AspExceptionCatchEnable AspTrackThreadingModel
Auth… – D
AuthAnonymous CpuEnableTerminatedProcs
AuthBasic CpuEnableTotalProcs
AuthFlags CpuEnableUserTime
AuthNTLM CpuLimitLogEvent
AuthPersistence CpuLimitPause
AuthPersistSingleRequest CpuLimitPriority
AuthPersistSingleRequestIfProxy CpuLimitProcStop
AuthPersistSingleRequestAlwaysIfProxy CpuLimitsEnabled
CacheControlCustom CpuLoggingInterval
CacheControlMaxAge CpuLoggingMask

CacheControlNoCache CpuLoggingOptions
CacheISAPI CpuResetInterval
CertCheckMode CreateCGIWithNewConsole
CGITimeout CreateProcessAsUser
ConnectionTimeout CustomErrorDescriptions
ContentIndexed DefaultDoc
CpuAppEnabled DefaultDocFooter
CpuCgiEnabled DefaultLogonDomain
CpuCgiLimit DirBrowseFlags
CpuEnableActiveProcs DirBrowseShowDate
CpuEnableAllProcLogging DirBrowseShowExtension
CpuEnableAppLogging DirBrowseShowLongDate
CpuEnableCgiLogging DirBrowseShowSize
CpuEnableEvent DirBrowseShowTime
CpuEnableKernelTime DirectoryLevelsToScan
CpuEnableLogging DisableSocketPooling
CpuEnablePageFaults DontLog
CpuEnableProcType DownlevelAdminInstance
E-K
EnableDefaultDoc HcExpiresHeader
EnableDirBrowsing HcFileExtensions
EnableDocFooter HcFilesDeletedPerDiskFree
EnableReverseDns HcIoBufferSize
ExitMessage HcMaxDiskSpaceUsage
FilterDescription HcMaxQueueLength
FilterEnabled HcMimeType
FilterFlags HcMinFileSizeForComp
FilterLoadOrder HcNoCompressionForHttp10
FilterPath HcNoCompressionForProxies
FilterState HcNoCompressionForRange
FrontPageWeb HcOnDemandCompLevel

FtpDirBrowseShowLongDate HcPriority
GreetingMessage HcSendCacheHeaders
HcCacheControlHeader HcScriptFileExtensions
HcCompressionBufferSize HttpCustomHeaders
HcCompressionDirectory HttpErrors
HcCompressionDll HttpExpires
HcCreateFlags HttpPics
HcDoDiskSpaceLimiting HttpRedirect
HcDoDynamicCompression InProcessIsapiApps
HcDoOnDemandCompression IPSecurity
HcDoStaticCompression KeyType
Log...
LogAnonymous LogExtFileTimeTaken
LogCustomPropertyDataType LogExtFileUriQuery
LogCustomPropertyHeader LogExtFileUriStem
LogCustomPropertyID LogExtFileUserAgent
LogCustomPropertyMask LogExtFileUserName
LogCustomPropertyName LogExtFileWin32Status
LogCustomPropertyServicesString LogFileDirectory
LogExtFileBytesRecv LogFileLocaltimeRollover
LogExtFileBytesSent LogFilePeriod
LogExtFileClientIp LogFileTruncateSize
LogExtFileComputerName LogModuleId
LogExtFileCookie LogModuleList
LogExtFileDate LogModuleUiId
LogExtFileFlags LogNonAnonymous
LogExtFileHttpStatus LogOdbcDataSource
LogExtFileMethod LogOdbcPassword
LogExtFileProtocolVersion LogOdbcTableName
LogExtFileReferer LogOdbcUserName

LogExtFileServerIp LogonMethod
LogExtFileServerPort LogPluginClsid
LogExtFileSiteName LogType
LogExtFileTime
M–R
MaxBandWidth NotifyPreProcHeaders
MaxBandWidthBlocked NotifyReadRawData
MaxClientsMessage NotifySecurePort
MaxConnections NotifySendRawData
MaxEndpointConnections NotifySendResponse
MimeMap NotifyUrlMap
MSDOSDirOutput NTAuthenticationProviders
NetLogonWorkstation PasswordCacheTTL
NotDeletable PasswordChangeFlags
NotifyAccessDenied PasswordExpirePrenotifyDays
NotifyAuthentication Path
NotifyEndOfNetSession PoolIDCTimeout
NotifyEndOfRequest ProcessNTCRIfLoggedOn
NotifyLog PutReadSize
NotifyNonSecurePort Realm
NotifyOrderHigh RedirectHeaders
NotifyOrderLow
NotifyOrderMedium
Script...– Z
ScriptMaps ServerSize
SecureBindings ServerState
ServerAutoStart SSIExecDisable
ServerBindings SSLUseDSMapper
ServerComment UNCAuthenticationPassthrough
ServerConfigAutoPWSync UNCPassword

ServerConfigFlags UNCUserName
ServerConfigSSL128 UploadReadAheadSize
ServerConfigSSL40 UseHostName
ServerConfigSSLAllowEncrypt WAMUserName
ServerListenBacklog WAMUserPass
ServerListenTimeout Win32Error
AccessExecute
When set to TRUE, the AccessExecute file permission property permits execution of ASP scripts and
other executable files. AccessExecute is one of the access permission flags contained in the
AccessFlags property.
Data type Boolean

Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path IIS Admin Object Type

/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory IIsWebDirectory
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory/WebFile IIsWebFile
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Note This property is a bitmask flag of the identifier MD_ACCESS_PERM.

Metabase identifier MD_ACCESS_PERM

Metabase bitmask identifier MD_ACCESS_EXECUTE
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000004
See Also
AccessFlags, AccessScript
AccessFlags
This single property contains the following file access permission flags:
AccessExecute AccessNoRemoteWrite
AccessNoRemoteExecute AccessRead
AccessNoRemoteRead AccessScript
AccessNoRemoteScript AccessWrite
AccessSource
Permissions established by setting AccessExecute, AccessScript, AccessNoRemoteExecute, and

AccessNoRemoteScript flags to TRUE do not apply to FTP server files.
CAUTION Setting both write and execute permissions can be dangerous, because it allows users to
modify internal files and run potentially damaging scripts on the system.
Remote access flags are operative only when the corresponding general access flag is set. For example,
setting AccessNoRemoteRead has no effect unless AccessRead is set as well. If both are set, the
local host can read the file, but the file cannot be read by the remote client.
The AccessSource flag, if set, grants source access to clients, using the HTTP extensions described by
the Web Distributed Authoring and Versioning (WebDAV) standard. For more information on
WebDAV, see the World Wide Web Consortium and Internet Engineering Task Force Web sites.
Note All permissions are applicable to Web services, servers, directories, and files. Only the
AccessRead and AccessWrite permissions are applicable for the FTP services, FTP servers, and FTP
directories.

Data type Long

Default value AccessRead = TRUE
Access Locations
Metabase Path Key Type

/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/MSFTPSVC/N/ROOT IIsFtpVirtualDir
/LM/MSFTPSVC/N/ROOT/FtpVirtualDir IIsFtpVirtualDir
The following tables list additional information required only for code that uses the IIS Admin Base
Object.

Default bitmask setting MD_ACCESS_READ
Bitmask Values
Constant Value Description

MD_ACCESS_READ 0x00000001 Allow read access.
MD_ACCESS_WRITE 0x00000002 Allow write access.
MD_ACCESS_EXECUTE 0x00000004 Allow file execution (includes
script permission).
MD_ACCESS_SOURCE 0x00000010 Allow source access.

MD_ACCESS_SCRIPT 0x00000200 Allow script execution.

MD_ACCESS_NO_REMOTE_WRITE 0x00000400 Local write access only.
MD_ACCESS_NO_REMOTE_READ 0x00001000 Local read access only.
MD_ACCESS_NO_REMOTE_EXECUTE 0x00002000 Local execution only.
MD_ACCESS_NO_REMOTE_SCRIPT 0x00004000 Local host access only.
AccessNoRemoteExecute
When set to TRUE, this file permission property prohibits the file from being executed by remote clients.
If AccessExecute is set to TRUE, the file can be executed by the Web server.
AccessNoRemoteExecute is one of the access permission flags contained in the AccessFlags
property.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_ACCESS_NO_REMOTE_EXECUTE
See Also
AccessFlags
AccessNoRemoteRead
When set to TRUE, this file permission property prohibits the file from being read by remote clients. If
AccessRead is set to TRUE, the file can be read by the Web server. AccessNoRemoteRead is one
of the access permission flags contained in the AccessFlags property.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_ACCESS_NO_REMOTE_READ
See Also
AccessFlags
AccessNoRemoteScript
When set to TRUE, this file permission property prohibits a script file from being executed by remote
clients. If AccessExecute or AccessScript is set to TRUE, the script file can be executed by the Web
server. AccessNoRemoteScript is one of the access permission flags contained in the AccessFlags
property.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_ACCESS_NO_REMOTE_SCRIPT
See Also
AccessFlags, AccessScript
AccessNoRemoteWrite
When set to TRUE, this file permission property prohibits the file from being written to by remote clients.
If AccessWrite is set to TRUE, the file can be written to by the Web server. AccessNoRemoteWrite
is one of the access permission flags contained in the AccessFlags property.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_ACCESS_NO_REMOTE_WRITE
See Also
AccessFlags
AccessRead
When set to TRUE, this file permission property permits the file to be read. AccessRead is one of the
access permission flags contained in the AccessFlags property.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_ACCESS_READ
Metabase bitmask value 0x00000001 (Default for
MD_ACCESS_PERM)
See Also
AccessFlags
AccessScript
When set to TRUE, this file permission property permits an .asp file to be executed by the ASP engine.
AccessScript is one of the access permission flags contained in the AccessFlags property. The
AccessExecute property allows execution of other types of executable files in addition to .asp files.
Data type Boolean

Default value FALSE
Access Locations


Object.

Metabase bitmask identifier MD_ACCESS_SCRIPT
See Also
AccessFlags
AccessSource
When set to TRUE, this file permission property allows the client full control over the requested
resource. Full control includes full support for the HTTP extensions provided by Web Distributed
Authoring and Versioning (WebDAV). For more information on WebDAV, see the World Wide Web
Consortium and the Internet Engineering Task Force Web sites.
Data type Boolean

Default value FALSE
Access Locations


Object.

Metabase bitmask identifier MD_ACCESS_SOURCE
See Also
AccessFlags
AccessSSL
When set to TRUE, file access requires Secure Sockets Layer (SSL) file permission processing, with or
without a client certificate. AccessSSL is one of the SSL file permission flags contained in the
AccessSSLFlags property.
Data type Boolean

Default value FALSE
Access Locations


Object.
Note This property is a bitmask flag of the identifier MD_SSL_ACCESS_PERM.
Metabase identifier MD_SSL_ACCESS_PERM

Metabase bitmask identifier MD_ACCESS_SSL
See Also
AccessSSLFlags
AccessSSL128
When set to TRUE, file access requires Secure Sockets Layer (SSL) file permission processing with a
minimum key size of 128 bits, with or without a client certificate. AccessSSL128 is one of the SSL file
permission flags contained in the AccessSSLFlags property.
Data type Boolean

Default value FALSE
Access Locations


Object.

Metabase bitmask identifier MD_ACCESS_SSL128
See Also
AccessSSLFlags
AccessSSLFlags
This single property contains the following Secure Sockets Layer (SSL) file permission flags:
AccessSSL AccessSSLNegotiateCert
AccessSSL128 AccessSSLRequireCert
AccessSSLMapCert
Data type Long
Default value 0 (no SSL permissions)
Access Locations


Object.

Metabase bitmask identifier MD_ACCESS_SSL
Values
Default Value
0x00000000 (No SSL protocols required)
MD_ACCESS_SSL 0x00000008 SSL permissions required.
MD_ACCESS_NEGO_CERT 0x00000020 Client certificate optional.
MD_ACCESS_REQUIRE_CERT 0x00000040 Client certificate required.
MD_ACCESS_MAP_CERT 0x00000080 Server will map client
certificate to Windows
account.
MD_ACCESS_SSL128 0x00000100 SSL permissions with 128-
bit key required.
See Also
AccessFlags
AccessSSLMapCert
When set to TRUE, this property indicates that Secure Sockets Layer (SSL) file permission processing
will map a client certificate to a Windows account. The AccessSSLNegotiateCert property must also
be set to TRUE for the mapping to occur. AccessSSLMapCert is one of the SSL file permission flags
contained in the AccessSSLFlags property.

Data type Boolean

Default value FALSE
Access Locations

Object.

Metabase bitmask identifier MD_ACCESS_MAP_CERT
See Also
AccessSSLFlags
AccessSSLNegotiateCert
When set to TRUE, Secure Sockets Layer (SSL) file access processing will request a certificate from
the client. If AccessSSLRequireCert is FALSE, access will continue if the client does not have a
certificate. Note that some versions of Internet Explorer will close the connection if the server requests a

certificate and one is not available, even if AccessSSLRequireCert is also set to TRUE.
AccessSSLNegotiateCert is one of the SSL file permission flags contained in the AccessSSLFlags
property.
Data type Boolean

Default value FALSE
Access Locations

Object.

Metabase bitmask identifier MD_ACCESS_NEGO_CERT
See Also
AccessSSLFlags
AccessSSLRequireCert

When set to TRUE, Secure Sockets Layer (SSL) file access processing will request a certificate from
the client. If no certificate is provided by the client, the connection will be closed.
AccessSSLNegotiateCert must also be set to TRUE when using AccessSSLRequireCert. This
property is one of the SSL file permission flags contained in the AccessSSLFlags property.
Data type Boolean

Default value FALSE
Access Locations

Object.

Metabase bitmask identifier MD_ACCESS_REQUIRE_CERT
See Also
AccessSSLFlags
AccessWrite

When set to TRUE, this file permission property permits writing to the file. AccessWrite is one of the
access permission flags contained in the AccessFlags property.
Data type Boolean

Default value FALSE
Access Locations

Object.

Metabase bitmask identifier MD_ACCESS_WRITE
See Also
AccessFlags
AdminACL

The AdminACL property contains a Microsoft Windows discretionary access control list (DACL) that
can be used to control access to any metabase subtree. This property can be used to grant read access,
restricted write access, or unrestricted write access.
Data type NTACL

Default value Empty (no DACL)
Access Locations

Object.
Metabase identifier MD_ADMIN_ACL

Data type BINARY_METADATA
Values
Default Value
0x00000000 (no SSL protocols required)
MD_ACR_READ 0x00000001 Enable read access to all
properties.
MD_ACR_WRITE 0x00000002 Enable write access to all
properties.
MD_ACR_ENUM_KEYS 0x00000008 Enable key enumeration.
MD_ACR_RESTRICTED_WRITE 0x00000020 See Remarks, following this
table.

MD_ACR_UNSECURE_PROPS_READ 0x00000080 Enable read access to

properties that do not have
METADATA_SECURE
attribute set.
MD_ACR_WRITE_DAC 0x00040000 Enable write access to
AdminACL for security
descriptor creator.
Remarks
MD_ACR_RESTRICTED_WRITE enables write access to the following properties:
AdminACL AppIsolated
Path AccessFlags
AnonymousUserName AnonymousUserPass
MaxBandWidth MaxBandWidthBlocked
SecureBindings ServerBindings
AdminServer
This property identifies the Web server instance being administered by the remote administration
program. This property is read-only.
Data type String

Default value 1 (string)
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:

/LM/W3SVC/Info IIsWebInfo
Object.

Metabase identifier MD_ADMIN_INSTANCE

User type IIS_MD_UT_SERVER
AllowAnonymous
This property specifies whether the FTP or Web server will allow anonymous access.
Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_ALLOW_ANONYMOUS

AllowKeepAlive
This property specifies whether Keep-Alive processing is permitted.

Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_ALLOW_ANONYMOUS

AllowPathInfoForScriptMappings
This property indicates whether clients are permitted to specify path information in script-mapped
requests.
Data type Boolean

Default value FALSE
Access Locations


Object.
Metabase identifier MD_ALLOW_PATH_INFO_FOR_SCRIPT_MAPPINGS

AnonymousOnly
This property specifies whether the service or server restricts access to anonymous FTP users. If the
value is TRUE, only anonymous users will be allowed to log on to the FTP server. If the value is FALSE,
users will be allowed to log on by using a valid user name, as well as anonymously.
Note If the value of AnonymousOnly is set to TRUE, and the value of the metabase property
AllowAnonymous is set to FALSE, no users will be permitted to log on to the FTP server.
Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_ANONYMOUS_ONLY


AnonymousPasswordSync
This property indicates whether IIS should handle the user password for anonymous users attempting to
access resources. For anonymous access to function properly, if the value of
AnonymousPasswordSync is FALSE the administrator must set the password in the
AnonymousUserPass property. If the value of AnonymousPasswordSync is TRUE, no anonymous
user password is required.
Note If the value of AnonymousPasswordSync is set to TRUE, and the value of the metabase
property AllowAnonymous is set to FALSE, no users will be permitted to log on to the FTP server.
Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_ANONYMOUS_USE_SUBAUTH

See also

AnonymousUserName , AnonymousUserPass
AnonymousUserName
The server associates a user name and password with every server action. This value specifies the name
of the registered local user that will be used for anonymous users. See also AnonymousUserPass and
AnonymousPasswordSync.
Data type String

Default value I_USR_Local machine name
Access Locations

Object.
Metabase identifier MD_ANONYMOUS_USER_NAME

AnonymousUserPass

The server associates a user name and password with every server action. This value specifies the
password of the registered local user that will be used for anonymous users. See also
AnonymousUserName and AnonymousPasswordSync.
Data type String

Default value Random string
Access Locations

Object.
Metabase identifier MD_ANONYMOUS_PWD

See Also
AnonymousUserPass, AnonymousPasswordSync
AppAllowClientDebug

This flag specifies whether ASP client-side debugging is enabled. This property is independent of
AppAllowDebugging, which applies to server-side debugging.
Data type Boolean

Default value FALSE
Access Locations

/LM/W3SVC/N/ROOT/WebDirectory IIsWebDirectory
Object.
Metabase identifier MD_ASP_ENABLECLIENTDEBUG

User type IIS_MD_UT_APP
AppAllowDebugging
This flag specifies whether ASP debugging is enabled on the server. This property is independent of the
AppAllowClientDebug property, which applies to client-side debugging.
Tip If server-side debugging is enabled, IIS application threads will be serialized: Only one thread at a
time will be allowed to execute, for each application. On busy sites, this could adversely affect server
performance.

Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_ASP_ENABLESERVERDEBUG

User type IIS_MD_UT_WAM
AppFriendlyName
This property specifies the user-friendly name of the package or application.
Data type String

Default value Empty
Access Locations


Object.
Metabase identifier MD_APP_FRIENDLY_NAME

See Also
AppPackageName
AppIsolated
This property indicates whether an application is to run in-process, out-of-process, or in a pooled-

process. Use the application management methods of the IIsWebVirtualDir and IIsWebDirectory
objects to set the process space for your application. For more information on process pooling see IIS
Performance Features.
Note This property should be considered read-only.
Data type Long

Default value 2 (range 0-2)
Access Locations


Object.
Metabase identifier MD_APP_ISOLATED

See Also
InProcessIsapiApps
AppOopRecoverLimit
This property specifies the maximum number of times an out-of-process application will be restarted
after a failure. The server will not service requests from components that have exceeded this limit.
Note This property does not apply to in-process applications or extensions.
Data type Long

Access Locations


Object.
Metabase identifier MD_APP_OOP_RECOVER_LIMIT

User type IIS_MD_UT_APP
See Also
InProcessIsapiApps
AppPackageID
This property provides the COM+ application identifier (ID) for a transaction. This property is read-
only. This ID is used in all transactions managed by Component Services.
Data type String

Default value Empty
Access Locations


Object.
Metabase identifier MD_APP_PACKAGE_ID

See Also
AppPackageName
AppPackageName
This property provides the COM+ application name for a transaction. This property should be
considered read-only.
Data type String

Default value Empty string
Access Locations

Object.

Metabase identifier MD_APP_PACKAGE_NAME

See Also
AppPackageID, AppFriendlyName
AppRoot
This property provides the URL for the ROOT directory of the application name space. This property
should be considered read-only. To mark a node as an application root, use the application management
methods of the IIsWebVirtualDir and IIsWebDirectory objects.
Data type String

Default value Empty
Access Locations

Object.
Metabase identifier MD_APP_ROOT

AppWamClsID

This property provides the class ID for the application's Web Application Management (WAM)
interface. This property should be treated as read-only.
Data type String

Default value Empty
Access Locations

Object.
Metabase identifier MD_APP_WAM_CLSID

AspAllowOutOfProcComponents
This property specifies whether an ASP script is allowed to call out-of-process components, which are
executables that are launched from within an application. If set to TRUE at the Web service level
(/LM/W3SVC), all in-process applications will be able to launch out-of-process components. If set to
TRUE at the root of a specific application, only that application can launch out-of-process components.
Data type Boolean

Default value TRUE

Access Locations

Object.
Metabase identifier MD_ASP_ALLOWOUTOFPROCCOMPONENTS

AspAllowSessionState
This property enables session state persistence for the ASP application. If the value is TRUE, the server
will create a new Session object for each connection. Session state will be accessible, session storage
will be allowed, the Session_OnStart and Session_OnEnd will occur, and the ASPSessionID cookie
will be sent to the client. If the value is FALSE, state access and storage are not allowed, events are not
processed, and no cookie is sent.
The @ENABLESESSIONSTATE directive can be used to override this metabase setting.
Data type Boolean

Default value TRUE
Access Locations


Object.
Metabase identifier MD_ASP_ALLOWSESSIONSTATE

User type ASP_MD_UT_APP
AspBufferingOn
This property specifies whether output from an ASP application will be buffered. If the value is TRUE
(default), all output from the application is collected in the buffer before the buffer is flushed to the client
browser. If this property is set to FALSE, output from ASP scripts will be written to client browser as it
becomes available.
With buffering on, the ASP application will have to completely process the ASP script before any output
is received by the client browser. For this reason, applications for which buffering has been turned on
could seem slower to users than those applications for which buffering is turned off, even though the total
time taken for the buffered script is less. Therefore, if buffering is turned on, you should consider using
the Response.Flush method to pass the user pieces of content as the script is being processed.
Note If buffering is turned off, any methods that modify existing HTTP headers, or generate new
headers, must be executed before the content body is sent to the client browser. If buffering is turned on,
this restriction is unnecessary.
Important If you installed IIS 5.0 by upgrading from a previous version of IIS, the default setting for
this property will be FALSE, not TRUE.
Data type Boolean

Default value TRUE
Access Locations


Object.
Metabase identifier MD_ASP_BUFFERINGON

AspCodepage
This property specifies the default code page for an application. This setting can be overridden at the
page level by using the @CODEPAGE directive.
Data type Long

Default value CP_ACP (System ANSI code page)
Access Locations


Object.
Metabase identifier MD_ASP_CODEPAGE

AspEnableApplicationRestart
This metabase property determines whether an ASP application can be automatically restarted.
There are two ways in which an application can be restarted. IIS 4.0 can call the application's Global.asa
file; this will immediately cause the application to restart if the AspEnableApplicationRestart property
is set to TRUE.
Important When this property if toggled from FALSE to TRUE, the application will automatically and
immediately be restarted.
IIS 5.0 also provides an ADSI method, AspAppRestart, which can be used to restart the application.
Data type Boolean

Default value TRUE
Access Locations


Object.
Metabase identifier MD_ASP_ENABLEAPPLICATIONRESTART

See Also
AspAppRestart
AspEnableAspHtmlFallback
This property is reserved for future use.
Data type Boolean

Default value FALSE
Access Locations

Object.

Metabase identifier MD_ASP_ENABLEAPPLICATIONRESTART

See Also
AspAppRestart
AspEnableChunkedEncoding
This metabase property specifies whether HTTP 1.1 chunked transfer encoding is enabled for the Web
service.
Note Even if chunked transfer encoding is enabled, it will be used only with browsers that support, and
have enabled, HTTP 1.1.
The Web service setting for this property is applicable to all in-process application nodes, at all levels.
Metabase settings at the Web server level or lower will be ignored for in-process applications. However,
settings at the Web server level or lower will be used if that node is isolated as an out-of-process
application.
Data type Boolean

Default value TRUE
Access Locations


Object.
Metabase identifier MD_ASP_ENABLECHUNKEDENCODING

AspEnableParentPaths
This property specifies whether an ASP page can allow paths relative to the current directory (using
the ..\ notation). If set to TRUE, it constitutes a potential security risk because an include path could
access critical or confidential files outside the application's root directory.
Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_ASP_ENABLEPARENTPATHS


AspEnableTypelibCache
This metabase property specifies whether type libraries will be cached on the server.
application.
Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_ASP_ENABLETYPELIBCACHE

AspErrorsToNTLog
This metabase property specifies whether IIS scripting errors will be written to the Windows Event Log.

The IIsWebService setting for this property is applicable to all in-process application nodes, at all
levels. Metabase settings at the IIsWebServer level or lower will be ignored for in-process applications
unless that IIsWebServer node is isolated as an out-of-process application.
If AspLogErrorRequests is TRUE and AspErrorsToNTLog is FALSE, then the ASP errors will be
sent to the IIS log. If these errors are serious or logging to IIS log previously failed, then each error will
also be sent to the Windows Event Log.
If AspLogErrorRequests is FALSE, then these errors will only be sent to the IIS Log, and not to the
Windows Event Log.
If AspLogErrorRequests is TRUE and AspErrorsToNTLog is TRUE, then all ASP related errors
will go to the Windows Event Log and the IIS log.
Note To completely prevent ASP errors from being logged in the IIS log file, you must disable logging
altogether. To accomplish this see the DontLog and LogType properties.
Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_ASP_ERRORSTONTLOG


AspExceptionCatchEnable
This value specifies whether exceptions thrown by components are trapped by ASP pages. If FALSE
(disabled), Microsoft Script Debugger will not catch exceptions sent by the component you are
debugging.
Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_ASP_EXCEPTIONCATCHENABLE

AspLogErrorRequests
This property controls whether the Web server writes unsuccessful client requests to the Windows Event
Log file. If AspLogErrorRequests is TRUE, a standard set of ASP error requests are logged. For a list
of these errors see ASP Error List.
If AspLogErrorRequests is TRUE and AspErrorsToNTLog is FALSE, then the ASP errors will be

sent to the IIS log. If these errors are serious or logging to IIS log previously failed, then each error will
also be sent to the Windows Event Log.
If AspLogErrorRequests is FALSE, then these errors will only be sent to the IIS Log, and not to the
Windows Event Log.
If AspLogErrorRequests is TRUE and AspErrorsToNTLog is TRUE, then all ASP related errors
will go to the Windows Event Log and the IIS log.
Note To completely prevent ASP errors from being logged in the IIS log file, you must disable logging
altogether. To accomplish this see the DontLog and LogType properties.
Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_ASP_LOGERRORREQUESTS

ASP Error List
This table contains a list of ASP errors that will be logged by the Windows Event Log if
AspLogErrorRequests is set to TRUE.

ASP error code ASP error Description

ASP 0100 Out of memory Unable to allocate required
memory.
ASP 0101 Unexpected error The function returned (exception
name).
ASP 0102 Expecting string input The function expects a string as
input.
ASP 0103 Expecting numeric input The function expects a number as
input.
ASP 0104 Operation not Allowed Operation not allowed.
ASP 0105 Index out of range An array index is out of range.
ASP 0106 Type Mismatch An unhandled data type was
encountered.
ASP 0107 Stack Overflow The data being processed is over
the allowed limit.
ASP 0115 Unexpected error A trappable error (exception
name) occurred in an external
object. The script cannot
continue running.
ASP 0190 Unexpected error A trappable error occurred while
releasing an external object.
ASP 0191 Unexpected error A trappable error occurred in the
OnStartPage method of an
external object.
ASP 0192 Unexpected error A trappable error occurred in the
OnEndPage method of an
external object.
ASP 0193 OnStartPage Failed An error occurred in the
OnStartPage method of an
external object.
ASP 0194 OnEndPage Failed An error occurred in the
OnEndPage method of an
external object.
ASP 0240 Script Engine Exception A script engine threw exception
(exception name) in (object
name) from (object name).
ASP 0241 CreateObject Exception The CreateObject of (object
name) caused exception
(exception name).

ASP 0242 Query OnStartPage Interface Querying object (object name)'s

Exception OnStartPage or OnEndPage
methods caused exception
(exception name).
See Also
AspErrorsToNTLog
AspProcessorThreadMax
This metabase property specifies the maximum number of worker threads per processor that IIS will
create.
Tip This setting can dramatically influence the scalability of your Web applications, and the performance
of your server in general. The optimal setting for your IIS installation depends on what types of
applications and content you are serving.
If this metabase property is changed, the Web server instance must stopped and restarted in order for
the change to take effect. The Web service setting for this property is applicable to all in-process
application nodes, at all levels. Metabase settings at the Web server level or lower will be ignored for in-
process applications. However, settings at the Web server level or lower will be used if that node is
isolated as an out-of-process application.
Data type Long

Default value 10
Access Locations


Object.
Metabase identifier MD_ASP_PROCESSORTHREADMAX

AspQueueConnectionTestTime
IIS places all ASP requests into a queue. If the request has been queued for longer than the number of
seconds specified by the AspQueueConnectionTestTime metabase property, then ASP will check to
determine whether the client is still connected before executing the request. If the client is no longer
connected, the request will not be processed, and will be deleted from the queue.
Tip Users often will not wait very long for ASP pages to be processed. Although the maximum waiting
time varies from user to user, the generally accepted maximum is approximately 10 seconds. You can
use the AspQueueConnectionTestTime metabase property to make sure that IIS does not waste time
processing a request that has been abandoned by the user.
Note that this metabase identifier is useful for making ASP processing efficient only up to the point at
which ASP begins to process the script. Once the script is being executed, however, your application
should continue to check for client connection at appropriate times during the script's execution, by using
the ASP method IResponse::IsClientConnected.
Data type Long

Default value 3 seconds (range 0-0XFFFFFFFF)
Access Locations


Object.
Metabase identifier MD_ASP_QUEUECONNECTIONTESTTIME

AspQueueTimeout
This property specifies the amount of time, in seconds, that an ASP script request will wait in the queue
for execution. When requests are pulled from the queue for execution, they are checked to see if they
have expired (have waited longer than the value of this parameter). Expired requests are rejected with a
message indicating the server is too busy.
Data type Long

Default value -1 (no timeout)
Access Locations

Object.
Metabase identifier MD_ASP_QUEUETIMEOUT


AspRequestQueueMax
This metabase property specifies the maximum number of concurrent ASP requests that will be permitted
into the queue. Any client browsers attempting to request ASP files when the queue is full will be given an
HTTP 500 "Server Too Busy" error.
application.
Data type Long

Default value 500 (range 0-0xFFFFFFFF)
Access Locations

Object.
Metabase identifier MD_ASP_REQUESTQUEUEMAX

AspScriptEngineCacheMax

This property specifies the maximum number of scripting engines that ASP pages will keep cached in
memory.
Data type Long

Default value 50
Access Locations

Object.
Metabase identifier MD_ASP_SCRIPTENGINECACHEMAX

AspScriptErrorMessage
This property specifies the error message that will be sent to the browser if specific debugging errors are
not sent to the client (if AspScriptErrorSentToBrowser is FALSE).

Data type String

Default value An error occurred on the server when processing
the URL. Please contact the system administrator.
Access Locations

Object.
Metabase identifier MD_ASP_SCRIPTERRORMESSAGE

See Also
AspScriptErrorSentToBrowser
AspScriptErrorSentToBrowser
This property specifies whether the Web server writes debugging specifics (file name, error, line number,
description) to the client browser in addition to logging them to the Windows Event Log. The
AspScriptErrorMessage property provides the error message to be sent if this property is FALSE.
Data type Boolean

Default value TRUE

Access Locations

Object.
Metabase identifier MD_ASP_SCRIPTERRORMESSAGE

See Also
AspScriptErrorMessage
AspScriptFileCacheSize
This property specifies the number of precompiled script files to cache. If 0, no script files will be
cached. If -1, all script files requested will be cached. This property can be used to tune performance,
depending on the amount of memory available and the amount of script file traffic.
Data type Long

Default value 256
Access Locations


Object.
Metabase identifier MD_ASP_SCRIPTFILECACHESIZE

AspScriptLanguage
This property specifies the default script language for all ASP applications for the Web server. This
default language will be used within the script language delimiters (<% and %>) unless specifically
overridden by the following directive.
<%
@ LANGUAGE = ScriptingLanguage
%>
Data type String

Default value VBScript
Access Locations


Object.
Metabase identifier MD_ASP_SCRIPTLANGUAGE

AspScriptTimeout
This property specifies the default length of time in seconds that ASP pages will allow a script to run
before terminating and writing an event to the Windows Event Log. The script can override this default
value by using the Server.ScriptTimeout property. The ScriptTimeout property allows your ASP
application to set a higher script timeout value. For example, you might use this setting to adjust the
timeout once a particular user has established a valid session by logging in or ordering a product.
Note The minimum value for this property is one second.
Data type Long

Default value 90 seconds
Access Locations

Object.

Metabase identifier MD_ASP_SCRIPTTIMEOUT

See also
ScriptTimeout, AspSessionTimeout
AspSessionMax
This metabase property specifies the maximum number of concurrent sessions that IIS will permit. If a
client attempts to establish a new session with IIS once this limit is reached, the client will receive an error
(HTTP 500 "Server Too Busy").
Tip ASP incurs a certain amount of memory overhead for each session maintained. Although you could
use AspSessionMax to limit this memory overhead, it is generally more appropriate to manage the
lifetime of session objects within IIS by using the AspSessionTimeout property, so that client browsers
will be rejected once the limit is reached.
If an incoming request doesn't have an ASP session cookie, or has a session cookie that doesn't match
an existing session, it is considered a new session request.
application.
Data type Long

Default value -1 (maximum allowed)
Access Locations


Object.
Metabase identifier MD_ASP_SESSIONMAX

See also
AspSessionTimeout
AspSessionTimeout
This property specifies the default amount of time in minutes a Session object will be maintained after the
last request associated with the object is made. This can be overridden in script by using the
Session.Timeout method.
Tip AspSessionTimeout can be used to tune your ASP applications. Because Session objects
consume some memory resources, limiting the lifetime of an individual Session timeout with this property
will make your applications more scalable.
application.
Data type Long

Default value 10 minutes
Access Locations


Object.
Metabase identifier MD_ASP_SESSIONTIMEOUT

See also
Timeout, AspScriptTimeout
AspThreadGateEnabled
This metabase property indicates whether IIS thread gating is enabled.
Important IIS performs thread gating to dynamically control the number of concurrently executing
threads, in response to varying load conditions. The default settings for this property, and the other
thread gating properties, are designed to be appropriate for the majority of server configurations and
traffic conditions. Changing these properties can lead to significant performance degradation.
application.
Data type Boolean

Default value TRUE
Access Locations


Object.
Metabase identifier MD_ASP_THREADGATEENABLED

AspThreadGateLoadHigh
This metabase property specifies the minimum CPU load, as a percentage of the total, at which the CPU
is considered under high load conditions. This information will be used by IIS to perform thread gating, in
an attempt to maintain CPU load between the percentages specified in AspThreadGateLoadLow and
AspThreadGateLoadHigh.
application.
Data type Long

Default value 90 percent
Access Locations


Object.
Metabase identifier MD_ASP_THREADGATELOADHIGH

AspThreadGateLoadLow
This metabase property specifies the maximum CPU load, as a percentage of the total, at which the CPU
is still considered under low load conditions. This information will be used by IIS to perform thread
gating, in an attempt to maintain CPU load between the percentages specified in
AspThreadGateLoadLow and AspThreadGateLoadHigh.
application.
Data type Long

Default value 75 percent
Access Locations


Object.
Metabase identifier MD_ASP_THREADGATELOADLOW

AspThreadGateSleepDelay
This metabase property specifies how long to defer thread requests, before the request is rechecked by
the IIS thread gating mechanism.
application.
Data type Long

Default value 100 milliseconds
Access Locations


Object.
Metabase identifier MD_ASP_THREADGATESLEEPDELAY

AspThreadGateSleepMax
This metabase property specifies the maximum number of times a specific request can be put to sleep
(deferred) while IIS performs thread gating.
application.
Data type Long

Default value 50
Access Locations


Object.
Metabase identifier MD_ASP_THREADGATESLEEPMAX

AspThreadGateTimeSlice
This metabase property specifies how often the thread gating mechanism in IIS checks the CPU load.
application.
Data type Long

Default value 1000 milliseconds
Access Locations


Object.
Metabase identifier MD_ASP_THREADGATETIMESLICE

AspTrackThreadingModel
This metabase property specifies whether IIS will check the threading model of any components that
your application instantiates.
Important It is usually best to leave this metabase property set to its default value (FALSE), so that
ASP will not use system resources to track the threading model. and your ASP application will usually
provide the best possible performance. If this property is set to FALSE, and you give Application scope
to components that you create, those components must aggregate the free-threaded marshaler. If you do
not aggregate the free-threaded marshaler, ASP will generate an error when you try to instantiate the
component. For more information about this topic, see Building Components for ASP.
Tip Another reason to leave this property at its default setting (FALSE), is that any objects instantiated
in your ASP application that lack the OnStartPage or OnEndPage method will be released earlier than
they would be otherwise. This should improve your application's scalability.
For more details on improving performance, see Developing Scalable ASP Applications .
Note In IIS 4.0, the default for this metabase property was TRUE.
application.

Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_ASP_TRACKTHREADINGMODEL

AuthAnonymous
This property specifies anonymous authentication as one of the possible Windows authentication
schemes returned to clients as being available. AuthAnonymous is one of the authentication scheme
flags contained in the AuthFlags property.
Data type Boolean

Default value TRUE
Access Locations


Object.
Note This property is a bitmask flag of the identifier MD_AUTHORIZATION.
Metabase identifier MD_AUTHORIZATION

Metabase bitmask identifier MD_AUTH_ANONYMOUS
See Also
AuthFlags
AuthBasic
This property specifies Basic authentication as one of the possible Windows authentication schemes
returned to clients as being available. AuthBasic is one of the authentication scheme flags contained in
the AuthFlags property.
Data type Boolean

Default value FALSE
Access Locations


Object.

Metabase bitmask identifier MD_AUTH_BASIC
See Also
AuthFlags
AuthFlags
This single property contains the settings for the Windows authentication schemes that will be returned to
clients as being available.
This single property contains the following file access permission flags:
Authanonymous
AuthBasic
AuthNTLM

Data type Long

Default value AuthAnonymous = TRUE
Access Locations

Object.

Default bitmask setting MD_AUTH_ANONYMOUS
Bitmask Values

MD_AUTH_ANONYMOUS 0x00000001 Anonymous authentication
available.
MD_AUTH_BASIC 0x00000002 Basic authentication available.
MD_AUTH_NT 0x00000004 Windows authentication schemes
available.
AuthNTLM
This property specifies integrated Windows authentication (also known as Challenge/Response or

NTLM authentication) as one of the possible Windows authentication schemes returned to clients as
being available. AuthNTLM is one of the authentication scheme flags contained in the AuthFlags
property.
Data type Boolean

Default value FALSE
Access Locations

Object.

Metabase bitmask identifier MD_AUTH_NT
See Also
AuthFlags
AuthPersistence

This property specifies authentication persistence across requests on a connection. It is recommended

that you set this property by setting the corresponding subflag to TRUE, which will automatically set a
binary value for AuthPersistence.
If the AuthPersistSingleRequest is set to TRUE, then authentication persists only for a single request.
If AuthPersistSingleRequestIfProxy is set to TRUE, then authentication persists only for a single
request if it is a proxy request and the request is not handled by Microsoft Proxy Server. (That is, if
Proxy Server and IIS are running on the local computer, and the request is targeted to a remote server.)
If AuthPersistSingleRequestAlwaysIfProxy is set to TRUE, then authentication is valid for a single
request if the request is by proxy.
Note Only one sub-flag of AuthPersistence can be TRUE at one time. The subflags are
AuthPersistSingleRequest, AuthPersistSingleRequestIfProxy, and
AuthPersistSingleRequestAlwaysIfProxy. When one of these three properties is set to TRUE, the
other two properties are automatically set to FALSE. The value of AuthPersistence always equals the
value of the sub-flag that is set to TRUE.
Data type Long

Default value &H00000080 (or
AuthPersistSingleRequestIfProxy=TRUE)
This single property contains the following file access permission flags. All permissions are applicable to
the Web service, servers, directories, and files. Only the AccessRead and AccessWrite permissions
are applicable for the FTP service, FTP servers, and FTP directories.
AuthPersistSingleRequest AuthPersistSingleRequestAlwaysIfProxy
AuthPersistSingleRequestIfProxy
Access Locations


Object.
Metabase identifier MD_AUTHORIZATION_PERSISTENCE

Default bitmask setting MD_AUTH_SINGLEREQUESTIFPROXY
Bitmask Values

MD_AUTH_SINGLEREQUEST 0x00000040 Authentication is valid for
a single request. IIS will
reset the authentication at
the end of the request,
and force re-
authentication on the next
request of the session.
MD_AUTH_SINGLEREQUESTIFPROXY 0x00000080 Authentication is valid for
the end of the request if
the current authenticated
request is by proxy, and it
is not the special case
where IIS is running
MSPROXY.
MD_AUTH_SINGLEREQUESTALWAYSIFPROXY 0x00000100 Authentication is valid for
the end of the request and
force re-authentication on
the next request if the
current authenticated
request is by any type of
proxy.
AuthPersistSingleRequest
This property specifies authentication will persist only across single requests on a connection. IIS will
reset the authentication at the end of each request, and force re-authentication on the next request of the
session.

AuthPersistSingleRequest is one of the authentication scheme flags contained in the AuthPersistence

property.
Data type Boolean

Default value FALSE
All permissions are applicable to the Web service, servers, directories, and files. Only the AccessRead
and AccessWrite permissions are applicable for the FTP service, FTP servers, and FTP directories.
Access Locations

Object.

Metabase bitmask identifier MD_AUTH_SINGLEREQUEST
See Also
AuthPersistence
AuthPersistSingleRequestIfProxy

This property specifies authentication will persist only across single requests on a connection if the
connection is by proxy. IIS will reset the authentication at the end of the request if the current
authenticated request is by proxy and it is not the special case where IIS is running MSPROXY.
AuthPersistSingleRequestIfProxy is one of the authentication scheme flags contained in the

AuthPersistence property.
Data type Boolean

Default value TRUE
Access Locations

Object.

Metabase bitmask identifier MD_AUTH_SINGLEREQUESTIFPROXY
See Also

AuthPersistence
AuthPersistSingleRequestAlwaysIfProxy
This property specifies that authentication is valid for a single request if by proxy. IIS will reset the
authentication at the end of the request and force re-authentication on the next request if the current
authenticated request is by proxy of any type.
AuthPersistSingleRequestAlwaysIfProxy is one of the authentication scheme flags contained in the

AuthPersistence property.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_AUTH_SINGLEREQUESTALWAYSIFPROXY
See Also
AuthPersistence
CacheControlCustom
This property specifies custom HTTP 1.1 cache control directives. Multiple directives can be specified if
they are separated by carriage return/line feed (CRLF) pairs. There should not be a trailing carriage
return/line feed after the final directive.
Data type String

Default value Empty
By default, this property is not set and cache

control directives are not sent
Access Locations

Object.

Metabase identifier MD_CC_OTHER

CacheControlMaxAge
This property specifies the HTTP 1.1 cache control maximum age value. The range is 0 to
&HFFFFFFFF (-1 or unlimited) , measured in seconds.
Note &H represents VBScript hexadecimal format.
Data type Long

Default value Empty

Access Locations

Object.
Metabase identifier MD_MD_CC_MAX_AGE


CacheControlNoCache
This property specifies the HTTP 1.1 directive to prevent caching of content.
Data type Boolean

Default value FALSE

Access Locations

Object.
Metabase identifier MD_CC_NO_CACHE

CacheISAPI
This property indicates whether ISAPI extensions are cached in memory after use. If the value of this
property is TRUE, the .dll file will remain in the cache until the server is stopped. If the value is FALSE,

extensions are unloaded from memory once the extension .dll is no longer in use.
ISAPI extensions are cached or not cached based on the value of this property at the time they were
loaded into memory for use. Thus, if this property is changed after an extension has been loaded and
cached, the change will have no effect on that extension.
Data type Boolean

Default value TRUE
Access Locations

/LM/W3SVC/1 IIsWebServer
Object.
Metabase identifier MD_CACHE_EXTENSIONS

CertCheckMode
This property is used to enable or disable Certificate Revocation List (CRL) checking. When
CertCheckMode is set to zero (0) the CRL is not searched for certificates that have been revoked.
When CertCheckMode is greater than zero (CertCheckMode>0) the CRL will be searched for
certificates that have been revoked.

Data Type Integer

Default Value 0
Access Locations

Object.
Metabase Property MD_CERT_CHECK_MODE

User Type IIS_MD_UT_SERVER
CGITimeout
This property specifies the timeout in seconds for CGI applications. Its range is 10 to &H80000000 (2.1
million seconds).
Note &H represents VBScript hexadecimal format.
Data type Long

Access Locations


Object.
Metabase identifier MD_SCRIPT_TIMEOUT

ConnectionTimeout
This property specifies the time in seconds the server will wait before disconnecting an inactive
connection.
Data type Long

Default value 900 (15 minutes)
Access Locations


Object.
Metabase identifier MD_CONNECTION_TIMEOUT

ContentIndexed
This property specifies whether the content under this directory tree should be indexed by the installed
content indexer.
Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_CONNECTION_TIMEOUT

CpuAppEnabled

This metabase property specifies whether process accounting and throttling should be performed for
ISAPI extensions and ASP applications. To perform process accounting on CGI applications, use the
property CpuCgiEnabled.
Note Because process accounting in IIS uses Windows Job Objects to monitor CPU times for an
entire process, process accounting will log and throttle only applications that are isolated in a separate
process from IIS.
Process throttling and process accounting are independently controlled by several other metabase
properties. In order to enable process accounting you must set CpuEnableLogging (which is a member
of CpuLoggingMask) to TRUE, and set at least one other CpuLoggingMask property to TRUE. It is
also necessary to set at least one member flag of the CpuLoggingOptions, set CpuLoggingInterval to
a nonzero value, and set either CpuAppEnabled or CpuCgiEnabled, as appropriate, to TRUE.
To properly activate process throttling, CpuLimitsEnabled must be set to TRUE, and at least one of
the following properties should be set to TRUE: CpuLimitLogEvent, CpuLimitPriority,
CpuLimitProcStop, CpuLimitPause.
Data type Boolean

Default value TRUE
Access Locations

Object.

Metabase identifier MD_CPU_APP_ENABLED

CpuCgiEnabled
This metabase property indicates whether IIS should perform process accounting for CGI applications.
To effectively throttle CGI applications, use the CgiTimeout property. To use process accounting for
ISAPI and ASP applications, use CpuAppEnabled.
process from IIS.
Data type Boolean

Default value TRUE
Access Locations


Object.
Metabase identifier MD_CPU_CGI_ENABLED

CpuCgiLimit
When set to a value other than zero, this property limits the time in seconds that a CGI script is allowed
to be in process. When set to zero, the process time is unlimited.
Note CpuCgiLimit requires either CpuLimitsEnabled or CpuLoggingOptions set to TRUE.
Data type Integer

Default value 0 (zero)
Access Locations

Object.
Metabase identifier MD_CPU_CGI_LIMIT

See Also

ScriptTimeout
CpuEnableActiveProcs
This property indicates whether the total number of active processes is recorded when process
accounting is performed.
Data type Boolean

Default value TRUE
Access Locations

Object.
Note This property is a bitmask flag of the identifier MD_CPU_LOGGING_MASK.
Metabase identifier MD_CPU_LOGGING_MASK

Metabase bitmask identifier MD_CPU_ENABLE_ACTIVE_PROCS
See Also
CpuLoggingMask
CpuEnableAllProcLogging

This property indicates whether IIS should log total CPU times for all out-of-process ISAPI extensions
and ASP and CGI applications. For more information, see CpuLoggingOptions.
Data type Boolean

Default value TRUE
Access Locations

Object.
Note This property is a bitmask flag of the identifier MD_CPU_LOGGING_OPTIONS.
Metabase identifier MD_CPU_LOGGING_OPTIONS

Metabase bitmask identifier MD_CPU_ENABLE_ALL_PROC_LOGGING
See Also
CpuLoggingOptions
CpuEnableAppLogging
This property indicates whether IIS should log out-of-process ISAPI extensions and ASP applications.
For more information, see CpuLoggingOptions.

Data type Boolean

Default value FALSE
Access Locations

Object.

Metabase bitmask identifier MD_CPU_ENABLE_APP_LOGGING
See Also
CpuLoggingOptions
CpuEnableCgiLogging
This property indicates whether IIS should log total CPU times for CGI applications. For more
information, see CpuLoggingOptions.
Data type Boolean

Default value FALSE

Access Locations

Object.

Metabase bitmask identifier MD_CPU_ENABLE_CGI_LOGGING
See Also
CpuLoggingOptions
CpuEnableEvent
This property indicates whether the event that triggered the creation of a log record is specified in the log
record itself. For more information, see CpuLoggingMask.
Data type Boolean

Default value TRUE
Access Locations


Object.

Metabase bitmask identifier MD_CPU_ENABLE_EVENT
See Also
CpuLoggingMask
CpuEnableKernelTime
This property indicates whether total kernel-mode CPU time is recorded when process accounting is
performed. For more information, see CpuLoggingMask.
Data type Boolean

Default value TRUE
Access Locations


Object.

Metabase bitmask identifier MD_CPU_ENABLE_KERNEL_TIME
See Also
CpuLoggingMask
CpuEnableLogging
This property specifies whether process accounting is enabled for the Web service or server. Process
accounting can log the amount of CPU time that is taken by a Web server or service, as well as any
process throttling events that might occur. For more information, see CpuLoggingMask.
process from IIS.
Data type Boolean

Default value TRUE
Access Locations


Object.

Metabase bitmask identifier MD_CPU_ENABLE_LOGGING
See Also
CpuLoggingMask
CpuEnablePageFaults
This property indicates whether the total number of page faults is recorded when process accounting is
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_CPU_ENABLE_PAGE_FAULTS
See Also
CpuLoggingMask
CpuEnableProcType
This property indicates whether process type is recorded when process accounting is performed. For
more information, see CpuLoggingMask.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_CPU_ENABLE_PROC_TYPE
See Also
CpuLoggingMask
CpuEnableTerminatedProcs
This property indicates whether the total number of terminated processes is recorded when process
accounting is performed. For more information, see CpuLoggingMask.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_CPU_ENABLE_TERMINATED_PROCS
See Also
CpuLoggingMask
CpuEnableTotalProcs
This property indicates whether the total number of processes is recorded when process accounting is
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_CPU_ENABLE_TOTAL_PROCS
See Also
CpuLoggingMask
CpuEnableUserTime
This property indicates whether total user-mode CPU time is recorded when process accounting is
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_CPU_ENABLE_USER_TIME
See Also
CpuLoggingMask
CpuLimitLogEvent
This metabase property specifies the percentage of CPU time, in 1/1000ths of a percent, that all isolated
processes on the Web server are allowed to occupy during a given process accounting interval (specified
by CpuResetInterval). If the processes attempt to occupy more CPU time than specified in
CpuLimitLogEvent, a note will be made in the Windows Event Log that the processes have exceeded
the limits. If process accounting is enabled, the limit overrun will also be entered into the IIS log.
If CpuLimitLogEvent is set to 0, or a value greater than 100,000 (100 percent), IIS will not log any
events against the process. However, one of the other process throttling properties, such as
CpuLimitPriority, CpuLimitProcStop, or CpuLimitPause, could generate a response from IIS if a
CPU limit is exceeded.
process from IIS.
properties. In order to enable process accounting, you must set CpuEnableLogging (which is a
member of CpuLoggingMask) to TRUE, and set at least one other CpuLoggingMask property to
TRUE. It is also necessary to set at least one flag of CpuLoggingOptions, set CpuLoggingInterval to
CpuLimitProcStop, or CpuLimitPause.
Important Applications that do not have process throttling enabled do not contribute to the total CPU
time for the purposes of calculating CPU limit overruns.

Data type Long

Default value 0 (unlimited)
Access Locations

Object.
Metabase identifier MD_CPU_LIMIT_LOGEVENT

CpuLimitPause
processes on the Web server can occupy during a given process accounting interval (specified by
CpuResetInterval). If the processes attempt to occupy more CPU time than specified in
CpuLimitPause, IIS will pause the entire site, and any new client requests will receive a custom error
indicating that the server is out of resources. The site will remain in a paused state until the current reset
interval has ended. Any limit overrun will be recorded in the Windows Event Log, and, if process
accounting is enabled, in the IIS log as well.
If CpuLimitPause is set to 0, or a value greater than 100,000 (100 percent), IIS will not pause the site.
However, one of the other process throttling properties, such as CpuLimitLogEvent,
CpuLimitPriority, or CpuLimitProcStop, could generate a response from IIS if a CPU limit is
exceeded.
process from IIS.

time for the purposes of calculating CPU limit overruns.
Data type Long

Access Locations

Object.
Metabase identifier MD_CPU_LIMIT_PAUSE

CpuLimitPriority
processes on the Web server can occupy during a given process accounting interval (specified by
CpuResetInterval). If the processes attempt to occupy more CPU time than specified in
CpuLimitPriority, all processes for that server will be set to Idle Class priority until the next process
accounting reset. Any new processes on that server will also be set to Idle Class priority. Any limit
overrun will be recorded in the Windows Event Log, and, if process accounting is enabled, in the IIS log
as well.
If CpuLimitPriority is set to 0, or a value greater than 100,000 (100 percent), IIS will take change the
priority of any of the process' threads. However, one of the other process throttling properties, such as
CpuLimitLogEvent, CpuLimitProcStop, or CpuLimitPause, could generate a response from IIS if a

CPU limit is exceeded.
process from IIS.
time, for the purposes of calculating CPU limit overruns.
Data type Long

Access Locations

Object.
Metabase identifier MD_CPU_LIMIT_PRIORITY

CpuLimitProcStop
processes on the Web server may occupy during a given process accounting interval (specified by

CpuResetInterval). If the isolated processes attempt to occupy more CPU time than specified in
CpuLimitProcStop, IIS halts all isolated processes on that site affected by Process Throttling.
Processes terminated due to limit overruns will not be allowed to restart until the next CPU interval reset.
Any limit overrun will be recorded in the Windows Event Log, and, if process accounting is enabled, in
the IIS log as well.
If CpuLimitProcStop is set to 0, or a value greater than 100,000 (100 percent), IIS will not stop the
process. However, one of the other process throttling properties, such as CpuLimitLogEvent,
CpuLimitPriority, or CpuLimitPause, could generate a response from IIS if a CPU limit is exceeded.
process from IIS.
the following properties should be set to TRUE: CpuLimitLogEvent, CpuLimitPriority, or
time, for the purposes of calculating CPU limit overruns.
Data type Long

Access Locations

Object.
Metabase identifier MD_CPU_LIMIT_PROCSTOP


CpuLimitsEnabled
This metabase property specifies whether process throttling is enabled, Process throttling can be enabled
for an individual virtual server, or for the Web service overall, to limit the amount of CPU time used.
process from IIS.
Process throttling and accounting are independently controlled by several other metabase properties. In
order to enable process accounting you must set CpuEnableLogging (which is a member of
CpuLoggingMask) to TRUE, and set at least one other CpuLoggingMask property to TRUE. It is
Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_CPU_LIMITS_ENABLED


CpuLoggingInterval
This metabase property specifies the logging interval for process accounting and throttling activity, in
minutes. If process accounting is enabled and activated, IIS will write a summary of the process
accounting information to the log file at the end of each interval specified by CpuLoggingInterval.
Important For process accounting to work properly, you must be sure to set the property
CpuLoggingInterval to a value less than that specified by CpuResetInterval. If
CpuLoggingInterval is greater than CpuResetInterval, IIS will reset counters and the logging timer
before the logging interval has elapsed, and process accounting will never occur.
process from IIS.
the following properties should be set to TRUE: CpuLimitLogEvent, CpuLimitPriority, or
Data type Long

Default value 60 minutes (1 minute minimum)
Access Locations

Object.

Metabase identifier MD_CPU_LOGGING_INTERVAL

CpuLoggingMask
This metabase property specifies which process accounting and throttling fields should be written to the
IIS log file. All enabled fields will be written on every process accounting log. All values logged are for
the reset interval in which the logging occurs.
process from IIS.
This property contains the following flags:
CpuEnableLogging CpuEnableProcType
CpuEnableActiveProcs CpuEnableTerminatedProcs
CpuEnableEvent CpuEnableTotalProcs
CpuEnableKernelTime CpuEnableUserTime
CpuEnablePageFaults
You can also change the logging mask flags by directly manipulating the flags contained in
CpuLoggingMask by using the hexadecimal values described in the following tables.
also necessary to set at least one member flag of the CpuLoggingOptions, set to a nonzero value, and
set either CpuAppEnabled or CpuCgiEnabled, as appropriate, to TRUE.
Data type Long

Default value All Member Flags = TRUE
Access Locations


Object.

Default bitmask setting MD_CPU_ENABLE_LOGGING
Note Multiple bits are set by default. MD_CPU_ENABLE_EVENT
MD_CPU_ENABLE_PROC_TYPE
MD_CPU_ENABLE_USER_TIME
MD_CPU_ENABLE_KERNEL_TIME
MD_CPU_ENABLE_PAGE_FAULTS
MD_CPU_ENABLE_TOTAL_PROCS
MD_CPU_ENABLE_ACTIVE_PROCS
MD_CPU_ENABLE_TERMINATED_PROCS
Default bitmask value 0x800000FF
Bitmask Values

MD_CPU_ENABLE_LOGGING 0x80000000 Specifies whether process
accounting is enabled.
MD_CPU_ENABLE_EVENT 0x00000001 Log site events, such as start,
stop, and site process
throttling.
MD_CPU_ENABLE_PROC_TYPE 0x00000002 Log the process type.

MD_CPU_ENABLE_USER_TIME 0x00000004 Log the total user CPU time,

as a percentage of total CPU
time, in 1/1000ths of a
percent.
MD_CPU_ENABLE_KERNEL_TIME 0x00000008 Log the total kernel CPU
time, as a percentage of total
CPU time, in 1/1000ths of a
percent.
MD_CPU_ENABLE_PAGE_FAULTS 0x00000010 Log the total number of page
faults.
MD_CPU_ENABLE_TOTAL_PROCS 0x00000020 Log the total number of
processes.
MD_CPU_ENABLE_ACTIVE_PROCS 0x00000040 Log the total number of active
processes.
MD_CPU_ENABLE_TERMINATED_PROCS 0x00000080 Log the total number of
terminated processes.
CpuLoggingOptions
This metabase property contains flags that specify how IIS should log CPU times for services, servers,
or applications. You can use this property to configure IIS to sum the CPU times of CGI applications
only, of ISAPI extensions and ASP applications only, or of all applications.
Data type Long

Default value 1
process from IIS.
You can also directly manipulate the bit flags within CpuLoggingOptions by using the hexadecimal
values in the following Bitmask Values table.


This property contains the following flags:
CpuEnableAppLogging CpuEnableAllProcLogging
CpuEnableCgiLogging
Access Locations

Object.

Default bitmask setting MD_CPU_ENABLE_ALL_PROC_LOGGING
Bitmask Values

MD_CPU_DISABLE_ALL_LOGGING 0x00000000 Do not log CPU information.
MD_CPU_ENABLE_ALL_PROC_LOGGING 0x00000001 Log the sum of CPU time
used by applications and CGI.
MD_CPU_ENABLE_CGI_LOGGING 0x00000002 Log the CPU time used by
CGI applications.
MD_CPU_ENABLE_APP_LOGGING 0x00000004 Log the CPU time used by
ISAPI and ASP applications.
CpuResetInterval
This metabase property specifies the reset period for process accounting and process throttling limits on
the server or service. When the number of minutes elapsed since the last process accounting reset equals

the number specified by this property, IIS will reset the CPU timers for both the logging and limit
intervals.
Important If you want IIS to log process accounting information to a log file, you must be sure to set
the property CpuLoggingInterval to a value less than that specified by CpuResetInterval. If
CpuLoggingInterval is greater than CpuResetInterval, IIS will reset counters and the logging timer
before the logging interval has elapsed, and process accounting will never occur.
process from IIS.
Data type Long

Default value 1440 minutes (24 hours)
(1 minute minimum)
Access Locations

Object.
Metabase identifier MD_CPU_RESET_INTERVAL

CreateCGIWithNewConsole
This property indicates whether a CGI application runs in its own console. If the value is TRUE, each
CGI application creates a new console when started. A value of FALSE indicates that CGI applications
should run without a console.

Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_CREATE_PROC_NEW_CONSOLE

CreateProcessAsUser
This property specifies whether a CGI process will be created in the system context or in the context of
the requesting user.
Data type Boolean

Default value TRUE
Access Locations


Object.
Metabase identifier MD_CREATE_PROCESS_AS_USER

CustomErrorDescriptions
This property contains a list of custom error messages. Each string in the list specifies an error code and
subcode for the custom message; what the specific error text and subcode error text is to be; and
whether the custom message is supported by file or URL, or just by file only. Each string is in the format
ErrorCode, ErrorSubcode, ErrorText, ErrorSubcodeText, followed by another comma and either a 0
for file and URL support, or a 1 for file support only.
Data type List (string)

Default value Empty list
Access Locations

/LM/W3SVC/INFO IIsWebInfo

Object.
Metabase identifier MD_CUSTOM_ERROR_DESC

Data type MULTISZ_METADATA
See Also
HttpErrors
DefaultDoc
This property contains one or more file names of default documents that will be returned to the client if no
file name is included in the client's request. The default document will be returned if the
EnableDefaultDoc property is TRUE for the directory. This property can contain a list of default
document file names separated by a comma and a space, for example Default1.htm, Default2.htm.
Data type String

Default value Default.htm
Access Locations

Object.

Metabase identifier MD_DEFAULT_LOAD_FILE

Remarks
If the EnableDefaultDoc flag is not set in the DirBrowseFlags property, the server will not search for
a default document.
See Also
DirBrowseFlags
DefaultDocFooter
This value specifies the custom footer that is appended to files returned to the client. The custom footer
will be sent only if the EnableDocFooter property is TRUE. The footer can be a string such as "This is a
custom footer," or a reference to a file such as C:\Wwwroot\Footers\Footer.htm.
Data type String

Access Locations

Object.

Metabase identifier MD_FOOTER_DOCUMENT

Remarks
If the EnableDefaultDoc flag is not set in the DirBrowseFlags identifier, the server will not search for
a default document.
See Also
EnableDocFooter
DefaultLogonDomain
This property specifies the default domain for logon. If this value is not specified, the default domain will
be the domain name controlled by the computer, if the computer is a domain controller. If the computer
is not a domain controller, the default domain will be the computer name.
Data type String

Access Locations


Object.
Metabase identifier MD_DEFAULT_LOGON_DOMAIN

DirBrowseFlags
This property contains flags that control whether directory browsing is enabled, how much directory and
file information is provided if browsing is enabled, and whether there is a default page in the directory.
Note If a client accesses the directory and does not provide a file name, and the EnableDefaultDoc
flag is set to TRUE, the server will look for the file specified in the property DefaultDoc. If the default
file does not exist in the directory, and the EnableDirBrowsing flag is set to TRUE, then directory
browsing is enabled.
Data type Long

Default value DirBrowseShowDate,
DirBrowseShowExtension,
DirBrowseShowSize, DirBrowseShowTime,
EnableDefaultDoc
This property contains the following directory browsing flags:
DirBrowseShowDate DirBrowseShowTime
DirBrowseShowExtension EnableDefaultDoc
DirBrowseShowLongDate EnableDirBrowsing
DirBrowseShowSize
Access Locations


Object.
Metabase identifier MD_DIRECTORY_BROWSING

Default bitmask setting MD_DIRBROW_SHOW_DATE
MD_DIRBROW_SHOW_TIME
MD_DIRBROW_SHOW_SIZE
MD_DIRBROW_SHOW_EXTENSION
MD_DIRBROW_LOADDEFAULT
Default bitmask value 0x4000001E
Bitmask Values

MD_DIRBROW_SHOW_DATE 0x00000002 Show date.
MD_DIRBROW_SHOW_TIME 0x00000004 Show time.
MD_DIRBROW_SHOW_SIZE 0x00000008 Show file size.
MD_DIRBROW_SHOW_EXTENSION 0x00000010 Show file name extension.
MD_DIRBROW_LONG_DATE 0x00000020 Show full date.
MD_DIRBROW_LOADDEFAULT 0x40000000 Load default page, if it exists.
MD_DIRBROW_ENABLED 0x80000000 Enable directory browsing.
DirBrowseShowDate
This property specifies that date information will be displayed when browsing directories.
DirBrowseShowDate is one of the settings contained in the DirBrowseFlags property.

Data type Boolean

Default value TRUE
Access Locations

Object.
Note This property is a bitmask flag of the identifier MD_DIRECTORY_BROWSING.

Metabase bitmask identifier MD_DIRBROW_SHOW_DATE
See Also
DirBrowseFlags
DirBrowseShowExtension
This property specifies that file name extensions will be displayed when browsing directories.
DirBrowseShowExtension is one of the settings contained in the DirBrowseFlags property.

Data type Boolean

Default value TRUE
Access Locations

Object.

Metabase bitmask identifier MD_DIRBROW_SHOW_EXTENSION
See Also
DirBrowseFlags
DirBrowseShowLongDate
This property specifies that date information will be displayed in extended format when displaying
directories. DirBrowseShowLongDate is one of the settings contained in the DirBrowseFlags
property.

Data type Boolean

Default value FALSE
Access Locations

Object.

Metabase bitmask identifier MD_DIRBROW_LONG_DATE
See Also
DirBrowseFlags
DirBrowseShowSize
This property specifies that file size information will be displayed when browsing directories.
DirBrowseShowSize is one of the settings contained in the DirBrowseFlags property.

Data type Boolean

Default value TRUE
Access Locations

Object.

Metabase bitmask identifier MD_DIRBROW_SHOW_SIZE
See Also
DirBrowseFlags
DirBrowseShowTime
This property specifies that file time information will be displayed when displaying directories.
DirBrowseShowTime is one of the settings contained in the DirBrowseFlags property.

Data type Boolean

Default value TRUE
Access Locations

Object.

Metabase bitmask identifier MD_DIRBROW_SHOW_TIME
See Also
DirBrowseFlags
DirectoryLevelsToScan
This property specifies the number of virtual directory levels to scan in the metabase from the top of the
tree (that is, the root virtual directory for a server) to build a list of directories to be monitored for file
system changes. The valid range is 0 to 0xFFFFFFFF (unlimited). If a virtual directory is not included in
the list, then the IIS cache will not be flushed when a file change occurs in the directory. This list is also

used for down-level remote administration from earlier versions of IIS.
Data type Long

Default value 2
Inheritance FALSE
Access Locations

Object.
Metabase identifier MD_LEVELS_TO_SCAN

DisableSocketPooling
This property specifies whether socket pooling is used for sites distinguished by IP address (rather than
port number or host header name, for example). If DisableSocketPooling is set to FALSE, then socket
pooling is enabled and sockets are shared between sites that use the same socket number (but different
IP addresses). If DisableSocketPooling is set to TRUE, then there is no socket sharing for sites based
on IP address.
Note Socket pooling is a new feature in IIS 5.0.
In IIS version 4.0, each Web site was bound to a different IP address, which meant that each site had its
own socket that was not shared with sites bound to other IP addresses. These sockets are created when
the site starts, and they consume significant nonpaged memory (RAM). This memory consumption limits
the number of sites bound to IP addresses that can be created on a single machine.
By default, socket pooling is enabled. In general, this behavior should not be modified. If changed, the
change should be made at the site level only so that other sites can continue to take advantage of the
socket pooling feature.

Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_DISABLE_SOCKET_POOLING

Default value DWORD_METADATA
DontLog
This property specifies whether client requests should be written to the log file. By default (FALSE),
requests are written to the file. You can set this value to TRUE to turn logging off.
Data type Boolean

Default value FALSE
Access Locations


Object.
Metabase identifier MD_DONT_LOG

See Also
LogType
DownlevelAdminInstance
This property indicates the server instance for remote administration clients.
Data type String

Default value 1 (String)
Access Locations


Object.
Metabase identifier MD_DOWNLEVEL_ADMIN_INSTANCE

See Also
AdminServer
EnableDefaultDoc
This property specifies that the default document (specified by the DefaultDoc property) for a directory
will be loaded when the directory is being browsed. EnableDefaultDoc is one of the settings contained
in the DirBrowseFlags property.
Data type Boolean

Default value TRUE
Access Locations


Object.

Metabase bitmask identifier MD_DIRBROW_LOADDEFAULT
See Also
DirBrowseFlags
EnableDirBrowsing
This property specifies that directory browsing is enabled. EnableDirBrowsing is one of the settings
contained in the DirBrowseFlags property.
Data type Boolean

Default value FALSE
Access Locations


Object.

Metabase bitmask identifier MD_DIRBROW_ENABLED
See Also
DirBrowseFlags
EnableDocFooter
This property enables or disables custom footers specified by the DefaultDocFooter property. Higher
performance will be achieved if custom footers are disabled.
Data type Boolean

Default value FALSE
Access Locations

Object.

Metabase identifier MD_FOOTER_ENABLED

See Also
DefaultDocFooter
EnableReverseDns
This property enables or disables reverse Domain Name Server (DNS) lookups (reverse lookups
involve finding the domain name from an IP address). Reverse DNS lookups can use significant
resources and time.
Data type Boolean

Default value FALSE
Access Locations

Object.

Metabase identifier MD_DO_REVERSE_DNS

ExitMessage
This property specifies the message text an FTP server will transmit to a client when the client sends a
quit command.
Data type String

Access Locations

Object.
Metabase identifier MD_EXIT_MESSAGE

FilterDescription
This property holds a string, which serves as the description for the corresponding filter.

Data type String

Default value Empty
Access Locations

/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
Object.
Metabase identifier MD_FILTER_DESCRIPTION

FilterEnabled
This property indicates whether the filter is enabled.
Data type Boolean

Default value FALSE
Access Locations


Object.
Metabase identifier MD_FILTER_ENABLED

FilterFlags
This property contains flags that indicate which events the ISAPI filter has registered to be notified for.
This property, and all its component flags, should be considered read-only. For more information, see
Developing ISAPI Filters .
FilterFlags contains the following flags:
NotifyAccessDenied NotifyNonSecurePort NotifyReadRawData

NotifyAuthentication NotifyOrderHigh NotifySecurePort
NotifyEndOfNetSession NotifyOrderLow NotifySendRawData
NotifyEndOfRequest NotifyOrderMedium NotifySendResponse
NotifyLog NotifyPreProcHeaders NotifyUrlMap
Data type Long

Default value Not set
Access Locations

Object.

Metabase identifier MD_FILTER_FLAGS

Default bitmask setting (None set)
Bitmask Values

MD_NOTIFY_SECURE_PORT 0x00000001 Notify only if port secure.
MD_NOTIFY_NONSECURE_PORT 0x00000002 Notify only if port nonsecure.
MD_NOTIFY_READ_RAW_DATA 0x00008000 Notify if reading raw data.
MD_NOTIFY_PREPROC_HEADERS 0x00004000 Notify if preprocessing
headers.
MD_NOTIFY_AUTHENTICATION 0x00002000 Notify if performing
authentication.
MD_NOTIFY_URL_MAP 0x00001000 Notify if mapping URL to
physical path.
MD_NOTIFY_ACCESS_DENIED 0x00000800 Notify if server sending HTTP
error 401 to client.
MD_NOTIFY_SEND_RESPONSE 0x00000040 Notify if response being sent to
client.
MD_NOTIFY_SEND_RAW_DATA 0x00000400 Notify if sending raw data.
MD_NOTIFY_LOG 0x00000200 Notify if logging.
MD_NOTIFY_END_OF_REQUEST 0x00000080 Notify if request has ended.
MD_NOTIFY_END_OF_NET_SESSION 0x00000100 Notify if network session is
ending.
MD_NOTIFY_ORDER_HIGH 0x00080000 High priority for notifications.
MD_NOTIFY_ORDER_MEDIUM 0x00040000 Medium priority for
notifications.
MD_NOTIFY_ORDER_LOW, 0x00020000 Low priority for notifications.
MD_NOTIFY_ORDER_DEFAULT
FilterLoadOrder
This property, a comma-delimited list, specifies the order in which filters are to be loaded, such as

Filter1, Filter2, and so on.
Data type String

Access Locations

Object.
Metabase identifier MD_FILTER_LOAD_ORDER

FilterPath
This property specifies the full path to a filter DLL; for example C:\Wwwroot\Bin\Filter.dll.
Data type String

Default value Empty
Access Locations


Object.
Metabase identifier MD_FILTER_IMAGE_PATH

FilterState
This property indicates whether the filter is loaded (value 1) or unloaded (value 4). This property is read-
only.
Data type Long

Possible values 1 or 4
Access Locations

Object.
Metabase identifier MD_FILTER_STATE

Bitmask values

MD_FILTER_STATE_LOADED 0x00000001 Filter loaded.
MD_FILTER_STATE_UNLOADED 0x00000004 Filter unloaded.

FrontPageWeb
This property indicates whether this server instance will be targeted by Microsoft® FrontPage ®. Setting
this value to TRUE causes the FrontPage Manager to create the files required for FrontPage Server
Extensions. Setting this value to FALSE causes these files to be deleted.
Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_FRONTPAGE_WEB

FtpDirBrowseShowLongDate
This property indicates whether or not to display two-digit or four-digit years when browsing directories.

Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_SHOW_4_DIGIT_YEAR

GreetingMessage
This property contains a greeting message (in a multiple-line string) that can be sent to new clients from
an FTP server.

Access Locations


Object.
Metabase identifier MD_GREETING_MESSAGE

Date type MULTISZ_METADATA
HcCacheControlHeader
This metabase property specifies the directive that IIS will add to the Cache-Control header. This
header, along with the Expires header specified by HcExpiresHeader, is sent with every compressed
file that is sent to a client browser.
This property specifies a header that overrides the HTTP Expires header specified by
HcExpiresHeader, and is included to ensure that older clients and proxy servers will not attempt to
cache compressed files.
Neither the header specified by HcCacheControlHeader nor the header specified by

HcExpiresHeader will be sent with the response if the metabase property HcSendCacheHeaders is
set to FALSE.
The Web service must be restarted before any changes to this property take effect.
Data type String

Default value max-age=86400
Access Locations

/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes

Object.
Metabase identifier MD_HC_CACHE_CONTROL_HEADER

HcCompressionBufferSize
This metabase property specifies the size of the buffer, in bytes, that IIS will use for receiving
compressed data. This buffer is used for both on-demand compression of static content, as well dynamic
content compression. A larger buffer will yield slightly faster compression performance, but at the cost of
additional memory usage.
The size limit specified by HcCompressionBufferSize is used by IIS only if either

HcDoOnDemandCompression or HcDoDynamicCompression are set to TRUE. The maximum
allowable size of the buffer is 1,048,576 bytes (1 MB).
Data type Long

Default value 8192 (bytes)
Access Locations

Object.
Metabase identifier MD_HC_COMPRESSION_BUFFER_SIZE


HcCompressionDirectory
This metabase property specifies the directory where compressed versions of static files are temporarily
cached. If compression is enabled for IIS, every time IIS receives a request for a static file (such as
an .htm or .txt file), the server searches the compression directory for an already-compressed version of
the static file being requested.
To force IIS to recompress all outgoing static files, erase all files found in the compression directory
specified by HcCompressionDirectory.
Important It is strongly recommended that the directory specified by HcCompressionDirectory

reside on an NTFS volume, not on a FAT volume. If the file being requested resides on an NTFS
volume, and you have set HcCompressionDirectory to specify a FAT volume, IIS will not perform any
HTTP compression on that file. This behavior is due to a number of differences between FAT and NTFS
volumes, including different time stamping and access control mechanisms. In addition, NTFS handles
directories that contain a large number of files more efficiently than FAT volumes do.
Data type String (with replacement)

Default value %windir%\IIS Temporary Compressed Files
Access Locations

Object.
Metabase identifier MD_HC_COMPRESSION_DIRECTORY

Date type EXPANDSZ_METADATA
See Also
HcDoOnDemandCompression

HcCompressionDll
This metabase property specifies the fully qualified file system path and file name of the compression
DLL associated with the compression scheme.
Data type String (with replacement)

Default value %windir%\system32\inetsrv\SchemeName.dll
Access Locations

/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
Object.
Metabase identifier MD_HC_COMPRESSION_DLL

HcCreateFlags
This property is reserved for future use.
Data type Long

Access Locations


Object.
Metabase identifier MD_HC_CREATE_FLAGS

HcDoDiskSpaceLimiting
This metabase property allows you to limit the amount of disk space that compressed files (stored in the
compression directory specified by HcCompressionDirectory) can occupy. If this property is set to
TRUE, then IIS will not occupy more than the number of bytes specified by HcMaxDiskSpaceUsage
with compressed files. Once the limit is reached, compressed files are removed from the compression
directory on a least-recently used (LRU) basis. If HcDoDiskSpaceLimiting is set to FALSE, IIS
enforces no limit to the amount of disk space that the files in the compression directory can occupy.
Tip Limiting the use of disk space has a significant impact on performance because additional overhead
is required to check for the limit. Use this feature only if it is necessary.
HcDoDiskSpaceLimiting is relevant only if you have set the property

HcDoOnDemandCompression to TRUE.
Data type Boolean

Default value FALSE
Access Locations

Object.

Metabase identifier MD_HC_DO_DISK_SPACE_LIMITING

Date type DWORD_METADATA
HcDoDynamicCompression
This property specifies whether compression of responses to requests for dynamic content, such as the
output of ASP scripts and ISAPI extensions, is enabled. At the global level,
HcDoDynamicCompression indicates that all dynamic content will be compressed as it is requested.
For individual compression schemes, HcDoDynamicCompression specifies whether that particular

compression scheme supports compression of dynamic content.
Important Because dynamic content is by definition changeable, IIS does not cache compressed
versions of dynamic output. Thus, if dynamic compression is enabled, each and every response to
requests for dynamic content will have to be compressed each time. Dynamic compression consumes
considerable CPU time and memory resources, and it should only be used on servers that have slow
networks, but CPU power to spare.
Because HcDoDynamicCompression is not inheritable, HcDoDynamicCompression must be set to

TRUE at both the global level and the individual scheme level in order for dynamic compression to
actually be enabled for a server.
If you change the value of this property at the individual compression scheme level, the Web service will
need to be restarted for the change to take effect.
Data type Boolean

Default value FALSE
Access Locations


Object.
Metabase identifier MD_HC_DO_DYNAMIC_COMPRESSION

HcDoOnDemandCompression
This metabase property specifies whether static files, such as .htm and .txt files, will be compressed if no
compressed version of the file exists in the compression directory specified by
HcCompressionDirectory.
At a global level, if this property is set to TRUE, and IIS receives a request for static content, IIS will
check the compression directory. If no corresponding compressed version of the requested file is found,
IIS will send an uncompressed version of the requested file to the client browser while a background
thread compresses the file. The newly compressed file will then be stored in the compression directory,
and subsequent responses to requests for that file will be serviced directly from the directory. If
HcDoOnDemandCompression is set to FALSE at a global level, however, IIS will not compress
static content files for which it finds no corresponding compressed version in the compression directory.
In other words, an uncompressed version of the file will be returned for every request unless a
compressed version of the file already exists in the compression directory.
At an individual compression scheme level, HcDoOnDemandCompression indicates whether that

particular compression scheme supports on-demand compression.
Because HcDoOnDemandCompression is not inheritable, in order for static on-demand compression

to actually be enabled for a server, HcDoOnDemandCompression must be set to TRUE at both the
global and individual scheme level.
If you change the value of this property at the individual compression scheme level, the Web service will
need to be restarted for the change to take effect.
Data type Boolean

Default value TRUE
Access Locations


Object.
Metabase identifier MD_HC_DO_ON_DEMAND_COMPRESSION

HcDoStaticCompression
This metabase property specifies whether responses to requests for static content will be compressed by
IIS. At the global level, HcDoStaticCompression indicates that IIS will respond to requests for static
content (such as .htm and .txt files) first by checking the compression directory specified by
HcCompressionDirectory. If a compressed version of the static file is found in the directory, it will be
sent to the client browser. Otherwise, if on-demand compression is enabled with
HcDoOnDemandCompression, IIS will send the requested file in uncompressed form, and add that
file to the background compression queue.
At the individual compression scheme level, HcDoStaticCompression indicates whether the individual
compression scheme supports compression of static files.
Because HcDoStaticCompression is not inheritable, in order for static compression to actually be

enabled for a server, HcDoStaticCompression must be set to TRUE at both the global level and
individual scheme level.
If you change the value of this property at the individual compression scheme level, the Web service must
be restarted for the change to take effect.
Data type Boolean

Default value TRUE
Access Locations


Object.
Metabase identifier MD_HC_DO_DYNAMIC_COMPRESSION

This metabase property specifies the compression level for the compression scheme, when the scheme is
compressing dynamic content. Low compression levels produce slightly larger compressed files, but with
lower overall impact on CPU and memory resources. Higher compression levels generally result in
smaller compressed files but higher CPU and memory usage.
The Web service must be restarted for any changes to this property take effect.
Data type Long

Access Locations

Object.

Metabase identifier MD_HC_DYNAMIC_COMPRESSION_LEVEL

HcExpiresHeader
This metabase property specifies the content of the HTTP Expires header that is sent with all requested
compressed files, along with the Cache-Control header discussed in HcCacheControlHeader.
The combination of HcExpiresHeader and HcCacheControlHeader ensure that older clients and
proxy servers will not attempt to cache compressed files.
Neither the header specified by HcCacheControlHeader, nor the header specified by

HcExpiresHeader, will be sent with the response if the metabase property HcSendCacheHeaders is
set to FALSE.
Data type String

Default value Wed, 01 Jan 1997 12:00:00 GMT
Access Locations

Object.
Metabase identifier MD_HC_EXPIRES_HEADER


HcFileExtensions
This property indicates which file name extensions are supported by the compression scheme. Only static
files with the specified file extensions will be compressed by IIS. If this setting is empty, then the scheme
supports all file name extensions.
In addition to file name extension matches, HcDoOnDemandCompression and

HcDoStaticCompression must be set to TRUE for compression to be performed.

Default value htm, html, txt
Access Locations

Object.
Metabase identifier MD_HC_FILE_EXTENSIONS

See Also
HcScriptFileExtensions
HcFilesDeletedPerDiskFree
This metabase property specifies the number of compressed files that are deleted from the compression
directory when IIS determines that the compression directory has grown beyond its limits. IIS will delete
a number of files equal to the setting of this property, starting with the least-recently used files.

The HcFilesDeletedPerDiskFree property is relevant only if HcDoDiskSpaceLimiting is set to

TRUE, and HcMaxDiskSpaceUsage is set to something other than 0xFFFFFFFF (unlimited). The
maximum allowable value of HcFilesDeletedPerDiskFree is 1024.
Data type Long

Default value 256
Access Locations

Object.
Metabase identifier MD_HC_FILES_DELETED_PER_DISK_FREE

HcIoBufferSize
This metabase property specifies the size of the buffer, in bytes, that IIS will use to read uncompressed
files. A larger buffer will yield slightly faster compression performance, but at the cost of additional
memory usage.
HcIoBufferSize is used by IIS only if HcDoOnDemandCompression is set to TRUE. The maximum

allowable value is 1,048,576 bytes (1 MB).
Data type Long

Default value 8192 bytes
Access Locations


Object.
Metabase identifier MD_HC_IO_BUFFER_SIZE

HcMaxDiskSpaceUsage
This metabase property specifies whether IIS will limit the number of bytes of disk space occupied by
compressed file in the compression directory.
Disk space limiting is performed, and HcMaxDiskSpaceUsage is checked by IIS, only if

HcDoDiskSpaceLimiting is set to TRUE. If HcMaxDiskSpaceUsage is set to 0xFFFFFFFF, there
will be no limit on the number of bytes occupied by compressed files.
Data type Long

Default value 1,000,000 bytes
Access Locations

Object.
Metabase identifier MD_HC_MAX_DISK_SPACE_USAGE


HcMaxQueueLength
IIS performs on-demand compression of static content in the background. When a static file is
requested, and IIS has determined that a previously compressed version of the requested file does not
already exist in the compression directory, the request is put into a simple FIFO (first in, first out) queue.
HcMaxQueueLength specifies how many concurrent background compression requests can be in the
queue. If the queue is full, additional compression requests are ignored until there is room in the queue.
If HcMaxQueueLength is set to 0xFFFFFFFF, there is no limit to the number of pending requests in

the queue.
Data type Long

Default value 1000
Access Locations

Object.
Metabase identifier MD_HC_MAX_QUEUE_LENGTH

HcMimeType
This property indicates which MIME types are supported by the compression scheme. Only static files
with the specified MIME type will be compressed by IIS. If this setting is empty, then the scheme
supports all MIME types.
In addition to MIME type matches, HcDoOnDemandCompression and HcDoStaticCompression

must be set to TRUE for compression to be performed.

Data type String

Default value text/html text/text
Access Locations

Object.
Metabase identifier MD_HC_MIME_TYPE

Data type STRING_METADATA
HcMinFileSizeForComp
This property allows you to specify the minimum number of bytes a file must contain for it to be
compressed using on-demand compression. Very small files do not compress well, and in some cases
compression may even make the file larger than it was initially.
If HcMinFileSizeForComp is set to 0 (zero), all files will be compressed.
Data type Long

Default value 256 bytes
Access Locations


Object.
Metabase identifier MD_HC_MIN_FILE_SIZE_FOR_COMP

HcNoCompressionForHttp10
This metabase property disables compression for requests containing an HTTP 1.0 version number.
HTTP 1.0, as described in RFC 1945, provides a minimal level of support for certain types of
compression. However, some confusion exists around HTTP 1.0 compression, especially with regard to
proxy servers. In order to minimize the chance of inappropriately returning a compressed file to a client
that cannot decompress the file, you can use this metabase property to disable compression in
questionable scenarios.
Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_HC_NO_COMPRESSION_FOR_HTTP_10

HcNoCompressionForProxies

This metabase property allows you to disable the HTTP 1.1 response for compression requests that
have come through proxy servers. Certain HTTP proxy servers, including some advertised as HTTP
1.1-compliant, do not handle the caching of compressed objects correctly.
Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_HC_NO_COMPRESSION_FOR_PROXIES

HcNoCompressionForRange
This metabase property specifies how IIS handles HTTP Range requests. The HTTP 1.1 RFC, RFC
2068, is ambiguous about whether Range requests should apply to the compressed or uncompressed
version of a file. It is possible that some browsers could be unprepared for compressed Range
responses, so IIS defaults to not sending compressed responses to Range requests, to avoid problems
with browser misbehavior.
Data type Boolean

Default value FALSE
Access Locations


Object.
Metabase identifier MD_HC_NO_COMPRESSION_FOR_RANGE

HcOnDemandCompLevel
This metabase property specifies the compression level for the compression scheme, when the scheme is
to compress static content on demand. Low compression levels produce slightly larger compressed files,
but with lower overall impact on CPU and memory resources. Higher compression levels generally result
in small compressed files but higher CPU and memory usage.
Valid compression levels are from 1 to 10.
Data type Long

Default value 10
Access Locations

Object.

Metabase identifier MD_HC_ON_DEMAND_COMP_LEVEL

See Also
HcPriority
This metabase property specifies the priority rating assigned to a particular compression scheme. If your
installation of IIS has multiple compression schemes installed, and a client browser indicates (in the
Accept-Encoding header) that it can handle multiple compression schemes, IIS uses the priority numbers
specified in HcPriority to determine which scheme to use for the request. In that case, IIS will use the
matching scheme that has the highest priority number.
Valid priority numbers can be from 1 to 10. In general, if you have multiple compression schemes
installed with IIS, you should assign each compression scheme a different priority number.
Data type Long

Default value 5
Access Locations

Object.
Metabase identifier MD_HC_PRIORITY


HcSendCacheHeaders
This metabase property specifies whether the headers specified by HcCacheControlHeader and
HcExpiresHeader are sent with each compressed response. If this property is set to TRUE, Cache-
Control and Expires headers are sent with all compressed responses. If this property is set to FALSE,
however, only the HTTP 1.1 Vary header will be sent with the compressed response.
Important In general, the Cache-Control and Expires HTTP headers are included with compressed
responses to prevent inappropriate caching of compressed files, especially by proxy servers and older
browsers. If you choose to disable these headers, it is recommended that you also set
HcNoCompressionForProxies and HcNoCompressionForHttp10 to TRUE.
Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_HC_SEND_CACHE_HEADERS

HcScriptFileExtensions
This property indicates which file name extensions are supported by the compression scheme. Only
dynamic files with the specified file extensions will be compressed by IIS. If this setting is empty, then the
scheme supports all file name extensions.
Also, HcDoOnDemandCompression and HcDoStaticCompression must be set to TRUE for

compression to be performed.


Default value dll, asp, exe
Access Locations

Object.
Metabase identifier MD_HC_SCRIPT_FILE_EXTENSIONS

See Also
HcFileExtensions
HttpCustomHeaders
This property contains custom headers that are sent to the client in addition to the default header of the
HTML file. Each string in this property is formatted as a key name and value pair: Keyname, Value.

Access Locations


Object.
Metabase identifier MD_HTTP_CUSTOM

HttpErrors
This property specifies the custom error string to be sent to clients in response to HTTP 1.1 errors. Each
string in the list specifies the HTTP error code and subcode, indicates whether the handler will be a URL
or a file, and specifies which URL or file the client will be sent. Each string can be in either format. To
send a URL to the client, use HTTPErrorCode, HTTPErrorSubcode, URL, HandlerURL. To send a
file, use HTTPErrorCode, HTTPErrorSubcode, FILE, Filename.

Access Locations


Object.
Metabase identifier MD_HTTP_CUSTOM

See Also
CustomErrorDescriptions
HttpExpires
This property specifies the expiration of HTML document content by returning the value to the browser
in the HTML file header. The browser compares the value of this property with the current date to
determine whether to display a cached page or to request an updated page from the server. This
property can be made relative, or dynamic, by using the format D,#SecondsUntilExpiration (with
0xFFFFFFFF indicating no expiration date). It can also be absolute, with the format
S,ValidGMTString.
Data type String

Default value D,0xFFFFFFFF (No expiration)
Access Locations


Object.
Metabase identifier MD_HTTP_EXPIRES

HttpPics
This property specifies the World Wide Web Consortium (W3C) Platform for Internet Content
Selection (PICS) rating header. For more information on PICS, see the W3C Web site.

Access Locations


Object.
Metabase identifier MD_HTTP_PICS

HttpRedirect
This property specifies the directory or URL to which a client is redirected when the client attempts to
access a specific resource. There are two general forms that the value for this property can take.
The simple format is Destination, Flag, where Destination can specify either a URL or a virtual path to
a file. Flag can have one of three values: EXACT_DESTINATION indicates that the value provided for
Destination should be considered an absolute target location; CHILD_ONLY indicates that the value
should be added to the beginning of the file name of the request to be redirected; and PERMANENT
indicates that this redirection will be permanent for this resource.
The more complex form of specification for this property involves the use of wildcards. The format is *;
Wildcard1; Destination1; Wildcard2; Destination2, Flag. Each Wildcard; Destination pair indicates
that requests matching the wildcard are redirected to the specified destination. Flag can have the same
values as the simple string format.
Data type String

Default value Empty string (no redirects)
Access Locations


Object.
Metabase identifier MD_HTTP_REDIRECT

InProcessIsapiApps
This property specifies a list of ISAPI filters and extensions that must be run in the Web server process.
The string format is either Fullpath\Appname.dll, or just Appname.dll. ISAPI DLL entries without a
qualifying path will match any ISAPI request that contains the DLL name, regardless of the physical path
specified in the request.
For example, any of the following would be a valid list for the property: "D:\winnt\system32
\inetsrv\ssinc.dll" "D:\winnt\system32\inetsrv\httpodbc.dll" "author.dll" "shtml.dll" "admin.dll."

Default value httpodbc.dll
ssinc.dll
Access Locations


Object.
Metabase identifier MD_IN_PROCESS_ASAPI_APPS

Remarks
This property indicates only which ISAPI applications are required to run in-process. The inclusion of an
application in this list does not imply that the application is automatically run at server startup. Note that
there can be significant performance issues if too many applications are forced to run outside of the
server process.
See Also
AppIsolated
IPSecurity
This property specifies the IP access restrictions for a URL. It can be used to grant or deny access to
browsers based on either their IP address or DNS host name.
Note For a more detailed explanation for this object, see IIsIPSecurity.
Data type Binary reference

Default value No IP restrictions
Access Locations


Object.
Metabase identifier MD_IP_SEC

See Also
IIsIPSecurity
KeyType
The KeyType property specifies the type of a metabase key, and the IIS Admin Object that relates to
that key. The KeyType property is used to specify the class of the object associated with the key, such
as IIsWebServer or IIsWebVirtualDir. The KeyType determines the set of properties accessible at
the key.
Data type String

Remarks
The KeyType property is accessible by all IIS Admin Objects. The value is the name of the IIS Admin
Object accessed, and is the same as the ADSI Class property.
LogAnonymous
This property specifies whether anonymous requests are logged to the event log.

Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_LOG_ANONYMOUS

LogCustomPropertyDataType
This property indicates the data type of a custom logging field to which this property applies. The
constants used to specify the data type are listed in the following table:
Data Type Value

Int 0
Unsigned int 1
Long 2
Unsigned long 3
Float 4
Double 5
Lpstr 6
Lpwstr 7

For more information about custom logging fields, see Setting Metabase Properties for Logging.
Data type Long

Default value 0 (int)
Access Locations

/LM/Logging/CustomLogging IIsCustomLogModule
/LM/Logging/CustomLogging/Field IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup/Field IIsCustomLogModule
Object.
Metabase identifier MD_LOGCUSTOM_PROPERTY_DATATYPE

Bitmask Values

MD_LOGCUSTOM_DATATYPE_INT 0x00000000 Datatype is int.
MD_LOGCUSTOM_DATATYPE_UINT 0x00000001 Datatype is unsigned int.
MD_LOGCUSTOM_DATATYPE_LONG 0X00000002 Datatype is long.
MD_LOGCUSTOM_DATATYPE_ULONG 0X00000003 Datatype is unsigned long.
MD_LOGCUSTOM_DATATYPE_FLOAT 0X00000004 Datatype is float.
MD_LOGCUSTOM_DATATYPE_DOUBLE 0X00000005 Datatype is double.
MD_LOGCUSTOM_DATATYPE_LPSTR 0X00000006 Datatype is long pointer to
string array.
MD_LOGCUSTOM_DATATYPE_LPWSTR 0X00000007 Datatype is lpwstr.

LogCustomPropertyHeader
The LogCustomPropertyHeader property indicates which header string will be written to the log file
for the custom logging field to which this property applies.
Data type String

Access Locations

Object.
Metabase identifier MD_LOGCUSTOM_PROPERTY_HEADER

LogCustomPropertyID
This property specifies the identifier of the metabase property that will be used to determine if logging is
enabled or disabled for the specific logging field in question. To get the identifier for a given property, you
must first determine what the underlying metabase identifier constant is for the administration property in
question. You can then refer to the header file iiscnfg.h to determine the identifier for that constant.
For instance, the ADSI administration property named LogExtFileFlags refers to the underlying

property identified by MD_LOGEXT_FIELD_MASK, the value of which is 4013.
When a logging module is called to log custom information fields, the logging module will access the
property specified by LogCustomPropertyID, and check the individual flag bits, specified by
LogCustomPropertyMask, to determine if that particular field is currently enabled or disabled.
Data type Long

Default value 0
Access Locations

Object.
Metabase identifier MD_LOGCUSTOM_PROPERTY_ID

LogCustomPropertyMask
This property specifies the bitmask that can be used against the metabase property, specified by
LogCustomPropertyID, to determine whether the particular logging field is currently enabled or
disabled.
When a logging module is asked to log custom information fields, the logging module will access the
property specified by LogCustomPropertyID, and check the individual flag bits, specified by
LogCustomPropertyMask, to determine if that particular field is currently enabled or disabled.

Data type Long

Default value 0
Access Locations

Object.
Metabase identifier MD_LOGCUSTOM_PROPERTY_MASK

LogCustomPropertyName
This property specifies the name of the custom logging information field. This name generally should be
the name used in the user interface for the logging module.
Data type String

Access Locations


Object.
Metabase identifier MD_LOGCUSTOM_PROPERTY_NAME

LogCustomPropertyServicesString
This property specifies to which services the custom logging fields will apply.
Data type List

Default value W3SVC
MSFTPSVC
SMTPSVC
NNTPSVC
Access Locations


Object.
Metabase identifier MD_LOGCUSTOM_SERVICES_STRING

LogExtFileBytesRecv
This property indicates whether the total number of bytes received is written to the log file during logging
events. This property is one of the flags contained in the LogExtFileFlags property.
Data type Boolean

Default value FALSE
Access Locations

Object.
Note This property is a bitmask flag of the identifier MD_LOGEXT_FIELD_MASK.

Metabase identifier MD_LOGEXT_FIELD_MASK

Metabase bitmask identifier MD_EXTLOG_BYTES_RECV
See Also
LogExtFileFlags
LogExtFileBytesSent
This property indicates whether the total number of bytes sent is written to the log file during logging
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_BYTES_SENT
See Also
LogExtFileFlags
LogExtFileClientIp
This property indicates whether the client's IP address is written to the log file during logging events. This
property is one of the flags contained in the LogExtFileFlags property.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_CLIENT_IP
See Also
LogExtFileFlags
LogExtFileComputerName
This property enables the name of the local machine to be logged during logging events. This property is
one of the flags contained in the LogExtFileFlags property.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_COMPUTER_NAME
See Also
LogExtFileFlags
LogExtFileCookie
This property indicates whether information from the client cookie is written to the log file during logging
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_COOKIE
See Also
LogExtFileFlags
LogExtFileDate
This property indicates whether the date is included in the information written to the log file during a
logging event. This property is one of the flags contained in the LogExtFileFlags property.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_DATE
See Also
LogExtFileFlags
LogExtFileFlags
This property contains flags that indicate to Windows 2000 Server which categories of information are
written to the log file (or ODBC data source) during logging events. The following individual flags are
included in this property:
LogExtFileBytesRecv LogExtFileMethod LogExtFileTimeTaken

LogExtFileBytesSent LogExtFileProtocolVersion LogExtFileUriQuery
LogExtFileClientIp LogExtFileReferer LogExtFileUriStem
LogExtFileComputerName LogExtFileServerIp LogExtFileUserAgent
LogExtFileCookie LogExtFileServerPort LogExtFileUserName
LogExtFileDate LogExtFileSiteName LogExtFileWin32Status
LogExtFileHttpStatus LogExtFileTime
Data type Long

Default value LogExtFileClientIp, LogExtFileHttpStatus,
LogExtFileMethod, LogExtFileTime,
LogExtFileUriStem (all set to TRUE)
Access Locations


Object.

Default bitmask setting MD_EXTLOG_CLIENT_IP
MD_EXTLOG_TIME
MD_EXTLOG_METHOD
MD_EXTLOG_URI_STEM
MD_EXTLOG_HTTP_STATUS
Default bitmask value 0x 00000586
Bitmask Values

MD_EXTLOG_DATE 0x00000001 Log date.
MD_EXTLOG_TIME 0x00000002 Log time.
MD_EXTLOG_CLIENT_IP 0x00000004 Log client IP address.
MD_EXTLOG_USERNAME 0x00000008 Log user name.
MD_EXTLOG_SITE_NAME 0x00000010 Log site name.
MD_EXTLOG_COMPUTER_NAME 0x00000020 Log computer name.
MD_EXTLOG_SERVER_IP 0x00000040 Log server's own IP address.
MD_EXTLOG_METHOD 0x00000080 Log protocol method.
MD_EXTLOG_URI_STEM 0x00000100 Log URI stem.
MD_EXTLOG_URI_QUERY 0x00000200 Log URI query.

MD_EXTLOG_HTTP_STATUS 0x00000400 Log HTTP status.

MD_EXTLOG_WIN32_STATUS 0x00000800 Log WIN32 status.
MD_EXTLOG_BYTES_SENT 0x00001000 Log total bytes sent.
MD_EXTLOG_BYTES_RECV 0x00002000 Log total bytes received.
MD_EXTLOG_TIME_TAKEN 0x00004000 Log total time elapsed.
MD_EXTLOG_SERVER_PORT 0x00008000 Log server port.
MD_EXTLOG_USER_AGENT 0x00010000 Log user agent.
MD_EXTLOG_COOKIE 0x00020000 Log cookie.
MD_EXTLOG_REFERER 0x00040000 Log referrer.
MD_EXTLOG_PROTOCOL_VERSION 0x00080000 Log client server protocol
version.
LogExtFileHttpStatus
This property indicates whether HTTP status information is written to the log file during a logging event.
This property is one of the flags contained in the LogExtFileFlags property.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_HTTP_STATUS
See Also
LogExtFileFlags
LogExtFileMethod
This property indicates whether the logging method is written to the log file during a logging event. This
property is one of the flags contained in LogExtFileFlags.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_METHOD
See Also
LogExtFileFlags
LogExtFileProtocolVersion
This property indicates whether the client/server protocol version is written to the log file during a logging
event. This property is one of the flags contained in LogExtFileFlags.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_PROTOCOL_VERSION
See Also
LogExtFileFlags
LogExtFileReferer
This property indicates whether the referrer field, sent by the client, is written to the log file during a
logging event. This property is one of the flags contained in the LogExtFileFlags property.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_REFERER
See Also
LogExtFileFlags
LogExtFileServerIp
This property indicates whether the server's IP address is written to the log file during a logging event.
This property is one of the flags contained in the LogExtFileFlags property.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_SERVER_IP
See Also
LogExtFileFlags
LogExtFileServerPort
This property indicates whether the active server port is written to the log file during a logging event. This
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_SERVER_PORT
See Also
LogExtFileFlags
LogExtFileSiteName
This property indicates whether the site name is written to the log file during a logging event. This
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_SITE_NAME
See Also
LogExtFileFlags
LogExtFileTime
This property indicates whether the time is written to the log file during a logging event. This property is
one of the flags contained in the LogExtFileFlags property.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_TIME
See Also
LogExtFileFlags
LogExtFileTimeTaken
This property enables writing into the log file, during logging events, the total time taken for a request to
be completed. This property is one of the flags contained in the LogExtFileFlags property.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_TIME_TAKEN
See Also
LogExtFileFlags
LogExtFileUriQuery
This property indicates whether the Universal Resource Identifier (URI) query information is written to
the log file during logging events. The URI query usually consists of parameters passed to the URL by
using the URL?Parameters format. This property is one of the flags contained in the LogExtFileFlags
property.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_URI_QUERY
See Also
LogExtFileFlags
LogExtFileUriStem
This property indicates whether the Universal Resource Identifier (URI) stem information is written to the
log file during logging events. The URI stem usually consists of the actual resource being requested. This
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_URI_STEM
See Also
LogExtFileFlags
LogExtFileUserAgent
This property indicates whether the contents of the user agent field, sent by the client, are written to the
log file during a logging event. This property is one of the flags contained in the LogExtFileFlags
property.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_USER_AGENT
See Also
LogExtFileFlags
LogExtFileUserName
This property indicates whether the user's name is written to the log file during logging events. This
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_USERNAME
See Also
LogExtFileFlags
LogExtFileWin32Status
This property indicates whether the current Microsoft ® Win32® error status is written to the log file
during a logging event. This property is one of the flags contained in the LogExtFileFlags property.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_EXTLOG_WIN32_STATUS
See Also
LogExtFileFlags
LogFileDirectory
This property specifies the default logging directory, in which the log file and logging-related support files
are stored.
Important The log-file directory specified must be local.
Data type String

Default value %windir%\System32\LogFiles
Access Locations

Object.

Metabase identifier MD_LOGFILE_DIRECTORY

LogFileLocaltimeRollover
This property specifies IIS log file rollover behavior for W3C Extended logging. If the property is set to
FALSE, the default rollover behavior will be in effect: A new log file will be created based on the
Universal Time Coordinate (UTC), not local time. If this property is set to TRUE, a new log file will be
created based on local time, not UTC. (UTC was formerly called Greenwich Mean Time, or GMT.)
Note Regardless of the setting of this property, the time stamp for each W3C Extended Logging log
record will be UTC-based.
Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_LOGFILE_LOCALTIME_ROLLOVER


LogFilePeriod
This property specifies how often Microsoft Windows should create a new log file. This property can be
set to the following values: 1 (daily), 2 (weekly), 3 (monthly), or 4 (hourly). If this property is set to 0, a
new file will be created when the maximum size designated in LogFileTruncateSize is reached.
Data type Long

Default value 1 (Create new log file daily)
Access Locations

Object.
Metabase identifier MD_LOGFILE_PERIOD

Bitmask values

MD_LOGFILE_PERIOD_MAXSIZE 0x00000000 Create new log file after
reaching maximum size.
MD_LOGFILE_PERIOD_DAILY 0x00000001 Create new log file daily.
MD_LOGFILE_PERIOD_WEEKLY 0x00000002 Create new log file weekly.
MD_LOGFILE_PERIOD_MONTHLY 0x00000003 Create new log file monthly.
MD_LOGFILE_PERIOD_HOURLY 0X00000004 Create a new log file hourly.

See Also
LogFileTruncateSize
LogFileTruncateSize
This property specifies the maximum size of the log file, in bytes. A new log file is created if a logging
event causes the original log file to exceed the size specified in this property.
Data type Long

Default value 2048 (2 MB)
Access Locations

Object.
Metabase identifier MD_LOGFILE_TRUNCATE_SIZE

LogModuleId
This property specifies the CLSID for the logging module.

Data type String

Access Locations

/LM/Logging/IIsLogModule IIsLogModule
Object.
Metabase identifier MD_LOG_PLUGIN_MOD_ID

See Also
LogModuleUiId
LogModuleList
This property specifies a string that contains a comma-delimited list that names the available logging
modules.
Data type String

Access Locations

/LM/MSFTPSVC/INFO IIsFtpInfo

Object.
Metabase identifier MD_LOG_PLUGINS_AVAILABLE

LogModuleUiId
This property specifies the CLSID for the logging module's user interface.
Data type String

Access Locations

/LM/Logging/IIsLogModule IIsLogModule
Object.
Metabase identifier MD_LOG_PLUGIN_UI_ID

See Also
LogModuleId
LogNonAnonymous
This property specifies whether non-anonymous hits are logged to the event log.

Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_LOG_NONANONYMOUS

LogOdbcDataSource
This property specifies the name of the ODBC data source to which Microsoft Windows will write data
during logging events.
Data type String

Default value HTTPLOG
Access Locations


Object.
Metabase identifier MD_LOGSQL_DATA_SOURCES

Remarks
The logging module's CLSID determines whether Microsoft Windows will log to an ODBC data source,
or to the file system.
LogOdbcPassword
This property specifies the ODBC database password to be used when writing information to the
database during logging events.
Data type String

Access Locations


Object.
Metabase identifier MD_LOGSQL_PASSWORD

LogOdbcTableName
This property specifies the name of the ODBC database table to which Microsoft Windows will write
information during logging events.
Data type String

Default value InternetLog
Access Locations

Object.
Metabase identifier MD_LOGSQL_TABLE_NAME

LogOdbcUserName

This property specifies the ODBC database user name to be used when writing information to the
database during logging events.
Data type String

Default value InternetAdmin
Access Locations

Object.
Metabase identifier MD_LOGSQL_USER_NAME

LogonMethod
This property specifies the logon method for clear-text logons. Valid settings are: interactive (value set to
0), batch (1), and network (2). Each user attempting to log on to the server must have access
permissions corresponding to the appropriate logon method.
Data type Long

Default value 0 (interactive)
Access Locations


Bitmask values

MD_LOGON_INTERACTIVE 0x00000000 Log on locally.
MD_LOGON_BATCH 0X00000001 Log on as batch job.
MD_LOGON_NETWORK 0x00000002 Log on over network.
Object.
Metabase identifier MD_LOGON_METHOD

LogPluginClsid
This property specifies the order of precedence for the logging modules.
Data type String

Access Locations


Object.
Metabase identifier MD_LOG_PLUGIN_ORDER

LogType
This property indicates whether logging is enabled. A value of 0 indicates that logging is disabled, and a
value of 1 indicates that logging is enabled. This property is read-only.
Data type Long

Default value 1 (logging enabled)
Access Locations

Object.

Metabase identifier MD_LOG_TYPE

Bitmask values

MD_LOG_TYPE_DISABLED 0x00000000 Logging disabled.
MD_LOG_TYPE_ENABLED 0x00000001 Logging enabled.
See Also
DontLog
MaxBandWidth
This property specifies the maximum network bandwidth used for IIS. You can use this setting to help
prevent overloading the network with IIS activity. This is not an inheritable property, but the value set at
the machine level is globally available to all server instances. MaxBandWidth can be set individually so
that specific server instances are used instead of the global value, and can exceed the global setting
established at the machine level. A server instance must be stopped and restarted for a changed
MaxBandWidth value to take effect.
Data type Long

Default value &HFFFFFFFF (unlimited)
Inheritance Global (not inheritable)
Access Locations

/LM IIsComputer
Object.

Metabase identifier MD_MAX_BANDWIDTH

MaxBandWidthBlocked
This property specifies the maximum number of asynchronous requests to be queued in the outstanding
idle queue when the maximum bandwidth of the server is exceeded. The value range for this property is 0
to &HFFFFFFFF (unlimited).
This is not an inheritable property, but the value set at the machine level is globally available to all server
instances.
Data type Long

Inheritance Global (not inheritable)
Access Locations

/LM IIsComputer
Object.
Metabase identifier MD_MAX_BANDWIDTH_BLOCKED

MaxClientsMessage
This property contains the text of a message to send to clients when the current connection exceeds the
maximum connections established by the MaxConnections property. The message is a single line of

text.
Data type String

Access Locations

Object.
Metabase identifier MD_MAX_CLIENTS_MESSAGE

See Also
MaxConnections
MaxConnections
This property specifies the maximum number of simultaneous connections to a server. The valid range is
0 to 0xFFFFFFFF (unlimited). The MaxClientsMessage property can be used to send a message to
clients when this value has been exceeded.
Data type Long

Default value 0xFFFFFFFF (unlimited) for Windows 2000
Server,
10 for Windows 2000 Professional
Access Locations


Object.
Metabase identifier MD_MAX_CONNECTIONS

Operating system Default value and range

Windows 2000 Server &HFFFFFFFF (range 0-&HFFFFFFFF)
Windows 2000 Professional 10 (range 0-10)
Windows 95, 98 10 (range 0-10)
See Also
MaxClientsMessage
MaxEndpointConnections
This property specifies the maximum number of "listen" sockets that will be aggregated on a network
endpoint. For example, if this value is set to 15, then a maximum of 15 total connections can be made to
a single port, even if more than one domain is bound to the port.
Data type Long

Access Locations


Object.
Metabase identifier MD_MAX_ENDPOINT_CONNECTIONS

MimeMap
This property provides a list of the file name extensions for Multipurpose Internet Mail Extensions
(MIME) mappings. The MimeMap key at the local machine level of the metabase establishes the
default list, which can be overridden at the Web service and Web server level keys. See the
IIsMimeMap object for details on managing this property.
Data type List (objects)

Access Locations

/LM IIsComputer
/LM/MimeMap IIsMimeMap

Object.
Metabase identifier MD_MAX_CONNECTIONS

Data type MULTSZ_METADATA
MSDOSDirOutput
This property specifies the style of directory output for a list operation request from an FTP client. If the
value is TRUE, the format is in MS-DOS® style, if FALSE, it is produced in UNIX style.
Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_MSDOS_DIR_OUTPUT


NetLogonWorkstation
This property indicates the criteria that will be used by the domain controller for domain logon restrictions
from computers running Windows 2000 Professional. If NetLogonWorkstation is set to a value of 0,
logon restrictions are based on domain and the Windows Professional client information. If
NetLogonWorkstation is set to a value of 1, logon restrictions are based on the client's IP address.
And if NetLogonWorkstation is set to a value of 2, logon restrictions are based on the client's DNS
name.
Data type Long

Default value 0 (Windows 2000 Professional restrictions only)
Access Locations

Object.
Metabase identifier MD_NET_LOGON_WKS

Default bitmask setting MD_NETLOGON_WKS_NONE
Bitmask values

MD_NETLOGON_WKS_NONE 0x00000000 Windows 2000 Professional
restrictions only.
MD_NETLOGON_WKS_IP 0x00000001 Restrictions based on IP
address.
MD_NETLOGON_WKS_DNS 0x00000002 Restrictions based on DNS host
name.

NotDeletable
This metabase property indicates whether Internet Service Manager (HTML) can delete a server. If this
property is set to TRUE, any attempt to delete the affected server instance will result in an error.
This metabase property is not examined by the Internet Information Services snap-in administration tool.
Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_NOT_DELETABLE

NotifyAccessDenied
This property specifies whether the filter has registered to be notified of access-denial messages. If the
value is TRUE, the filter will be notified when the server is about to send the "401 Access Denied" error
message. If the value is FALSE, the filter ignores access-denied messages. This property is one of the
flags contained in the property FilterFlags, and is read-only.
Data type Boolean

Default value FALSE

Access Locations

Object.
Note This property is a bitmask flag of the identifier MD_FILTER_FLAGS.

Metabase bitmask identifier MD_NOTIFY_ACCESS_DENIED
See Also
FilterFlags
NotifyAuthentication
This property indicates whether the filter has registered to be notified of authentication events. If the value
is TRUE, the filter will be notified when the server is initially authenticating the client. This property is one
of the flags contained in the property FilterFlags, and should be considered read-only.
Data type Boolean

Default value FALSE
Access Locations


Object.

Metabase bitmask identifier MD_NOTIFY_AUTHENTICATION
See Also
FilterFlags
NotifyEndOfNetSession
This property indicates whether the filter has registered to be notified of network sessions that are ending.
This property is one of the flags contained in the property FilterFlags, and should be considered read-
only.
Data type Boolean

Default value FALSE
Access Locations


Object.

Metabase bitmask identifier MD_NOTIFY_END_OF_NET_SESSION
See Also
FilterFlags
NotifyEndOfRequest
This property indicates whether the filter has registered to be notified at the end of every client request.
This property is one of the flags contained in the property FilterFlags, and should be considered read-
only.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_NOTIFY_END_OF_REQUEST
See Also
FilterFlags
NotifyLog
This property indicates whether the filter has registered to be notified when the server is writing to the
log. This property is one of the flags contained in the property FilterFlags, and should be considered
read-only.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_NOTIFY_LOG
See Also
FilterFlags
NotifyNonSecurePort
This property indicates whether the filter has registered to be notified only for sessions on nonsecure
ports. This property is one of the flags contained in the FilterFlags property, and should be considered
read-only.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_NOTIFY_NONSECURE_PORT
See Also
FilterFlags
NotifyOrderHigh
This property indicates whether the filter has registered as high priority. When a notification occurs, if the
filter has registered for that notification, high priority filters are processed first. If other filters have also
registered as high priority, then the filters will be processed in the order they appear in the
FilterLoadOrder property.
This property is one of the flags contained in the FilterFlags property, and should be considered read-
only.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_NOTIFY_ORDER_HIGH
See Also
FilterFlags
NotifyOrderLow
This property indicates whether the filter has registered as low priority. When a notification occurs, if the
filter has registered for that notification, low priority filters are processed last. If other filters have also
registered as low priority, then the filters will be processed in the order they appear in the
FilterLoadOrder property.
only.
Data type Boolean

Default value TRUE
Access Locations

Object.


Metabase bitmask identifier MD_NOTIFY_ORDER_LOW
See Also
FilterFlags
NotifyOrderMedium
This property indicates whether the filter has registered as medium priority. When a notification occurs, if
the filter has registered for that notification, medium priority filters are processed after high priority filters,
but before low priority filters. If other filters have also registered as low priority, then the filters will be
processed in the order they appear in the FilterLoadOrder property.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_NOTIFY_ORDER_MEDIUM
See Also
FilterFlags
NotifyPreProcHeaders
This property indicates whether the filter has registered to be notified when the server has preprocessed
the headers of a request. This property is one of the flags contained in the FilterFlags. This is a read-
only property.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_NOTIFY_PREPROC_HEADERS
See Also
FilterFlags
NotifyReadRawData
This property indicates whether the filter has registered to be given raw data as input, before any
processing has taken place. This property is one of the flags contained in the FilterFlags property, and
should be considered read-only.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_NOTIFY_READ_RAW_DATA
See Also
FilterFlags
NotifySecurePort
This property indicates whether the filter has registered to be notified only for sessions on secure ports.
only.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_NOTIFY_SECURE_PORT
See Also
FilterFlags
NotifySendRawData
This property indicates whether the filter has registered to be notified when the server is sending raw data
back to the client. This property is one of the flags contained in the FilterFlags property, and should be
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_NOTIFY_SEND_RAW_DATA
See Also
FilterFlags
NotifySendResponse
This property indicates whether the filter has registered to be notified when the server is sending a
response to the client. This property is one of the flags contained in the FilterFlags property, and should
be considered read-only.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_NOTIFY_SEND_RESPONSE
See Also
FilterFlags
NotifyUrlMap
This property indicates whether the filter has registered to be notified when the server maps a URL to a
physical path. This property is one of the flags contained in the FilterFlags property, and should be
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_NOTIFY_URL_MAP
See Also
FilterFlags
NTAuthenticationProviders
This property contains a comma-delimited list of Windows authentication providers, such as integrated
Windows authentication (also known as NTLM).
Data type String

Access Locations

Object.
Metabase identifier MD_NTAUTHENTICATION_PROVIDERS

PasswordCacheTTL

This property is used for password types of security authentication schemes. The value specifies the
amount of time in seconds that an expired password will be held in the memory cache.
Data type Long

Default value 600 seconds (10 minutes)
Access Locations

Object.
Metabase identifier MD_ADV_CACHE_TTL

See Also
PasswordExpirePrenotifyDays
PasswordChangeFlags
This property specifies the flags that control password expiration and password change processing
between the server and client. A value of 0 (default) indicates that an SSL connection is required, 1
indicates that changing is allowed on nonsecure ports, 2 indicates that changing is disabled, and 4
indicates that password expiration notification is disabled.
Data type Long

Default value 0 (changes allowed on nonsecure ports)

Access Locations

Object.
Metabase identifier MD_AUTH_CHANGE_FLAGS

Default bitmask setting 0x00000000
Bitmask values

MD_AUTH_CHANGE_UNSECURE 0x00000001 Password changing allowed on
nonsecure ports.
MD_AUTH_CHANGE_DISABLE 0x00000002 Password changing disabled.
MD_AUTH_ADVNOTIFY_DISABLE 0x00000004 Advance notification of
password expiration disabled.
See Also
This property specifies the number of days remaining before the client's password will expire, and is used
to indicate when a password prenotification message will be sent.
Data type Long

Default value 14 days
Access Locations


Object.
Metabase identifier MD_ADV_NOTIFY_PWD_EXP_IN_DAYS

Remarks
When working with the IIS Admin Base Object, password expiration notification can be turned off by
setting the MD_AUTH_ADVNOTIFY_DISABLE flag in the property
MD_AUTH_CHANGE_FLAGS.
See Also
PasswordChangeFlags
Path
This property specifies the physical path associated with a virtual directory.
Data type String

Access Locations


Object.
Metabase identifier MD_VR_PATH

PoolIDCTimeout
This property specifies the timeout value (in seconds) for Internet database connection pooling. A value
of zero specifies that no pooling will be implemented.
Data type Long

Access Locations

Object.
Metabase identifier MD_POOL_IDC_TIMEOUT


ProcessNTCRIfLoggedOn
This property enables processing of integrated Windows (NTLM) authentication even if a user has
already logged on using an alternate authentication scheme.
Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_PROCESS_NTCR_IF_LOGGED_ON

PutReadSize
This property specifies the chunk size (in bytes) to be sent to the client in the HTTP 1.1 Transfer
Encoding header field. Normal values for this property are in the range of 1 KB to 64 KB. Intranet
applications may benefit from values for this property at the upper end of the range. For Internet
applications, values at the lower end of the range are more appropriate.

Data type Long

Default value 8 KB (range 1 KB–64 KB)
Access Locations

Object.
Metabase identifier MD_PUT_READ_SIZE

Realm
This property specifies the realm when the server requests that a client authenticate itself because the
client was denied access to a resource when using Basic (clear-text) authentication. This value appears in
the browser's user name–password prompt.
Data type String

Access Locations


Object.
Metabase identifier MD_REALM

RedirectHeaders
This property specifies additional redirection headers. Multiple headers can be specified if they are
separated by carriage return/line feed (CRLF) pairs. Do not put a trailing carriage return/line feed after
the final header.
Data type String

Access Locations


Object.
Metabase identifier MD_REDIRECT_HEADERS

ScriptMaps
This property specifies the file name extensions of applications for script processor mappings. The List
string requires Extension, ScriptProcessor, Flags, IncludedVerbs. Where Extension is the file name
extension (such as .htm), ScriptProcessor is the full path to the DLL, Flags is the integer value
corresponding to the requested behavior described below, and IncludedVerbs is a list of the verbs for
this ISAPI DLL to handle.
Note In IIS version 4.0 and earlier, the syntax was to list excluded verbs rather than included verbs.
In version 5.0, if no verbs are listed, a value of "all verbs" is assumed. It is recommended that you list the
verbs you want your ISAPI filter or extension to handle.
Three possible flags are allowed for each extension mapping, so one of three possible values can be
assigned to the Flags attribute.
Possible Flag values Description

1 The script is allowed to run in directories given
Script permission. If this value is not set, then the
script can only be executed in directories that are
flagged for Execute permission.

4 The server attempts to access the PATH_INFO

portion of the URL, as a file, before starting the
scripting engine. If the file can't be opened, or
doesn't exist, an error is returned to the client.
5 Both of the above conditions are TRUE.
For example, to specify the file extension for the ISAPI "Test.dll" with a file extension of ".htm", you
might provide the following List (string):
".htm,C:\WINNT40\System32\inetsrv\Test.dll,5,GET, HEAD, POST"

Access Locations

Object.
Metabase identifier MD_SCRIPT_MAPS

Default bitmask value Empty
Bitmask value


MD_SCRIPTMAPFLAG_SCRIPT 0x00000001 Allowed to run if permission
is set to Script.
MD_SCRIPTMAPFLAG_CHECK_PATH_INFO 0x00000004 Server checks
PATH_INFO.
SecureBindings
This property specifies a string that is used by IIS to determine which secure network endpoints are used
by the server instance. The string format is IP:Port.
Note The IP component of each string is optional. If it is not provided, IIS assumes that any IP address
is allowable (wildcard).

Default value Empty list if no keys are installed,
:443: if server keys are installed

Access Locations

Object.
Metabase identifier MD_SECURE_BINDINGS

See Also
ServerBindings

ServerAutoStart
This property indicates if the server instance should start automatically when the service is started.
This property is reset automatically when a server instance is stopped or restarted, to maintain state
across service restarts. For example, if a server is stopped, the value of this property is set to FALSE so
that if the service is stopped and restarted, the server will remain stopped. Likewise, if a server is started,
this property is set to TRUE, allowing the server to remain running whenever the service is running.
Data type Boolean

Default value TRUE
Access Locations

Object.
Metabase identifier MD_SERVER_AUTOSTART

ServerBindings
This property specifies a string that is used by IIS to determine which network endpoints are used by the
server instance. The string format is IP:Port:Hostname.

Note Both the IP and Hostname parameter of the string are optional. Any unspecified parameters
default to an all-inclusive wildcard.

Default value :80: for Web service,
:21: for FTP service

Access Locations

Object.
Metabase identifier MD_SERVER_BINDINGS

See Also
SecureBindings
ServerComment
This property specifies a comment for the server instance.

Data type String

Access Locations

Object.
Metabase identifier MD_SERVER_COMMENT

ServerConfigAutoPWSync
This property is a flag that participates in the ServerConfigFlags server configuration property. A value
of TRUE indicates that the server can perform automatic anonymous user password synchronization
between the Web authentication manager (WAM) and the Microsoft Windows authentication manager.
Data type Boolean

Default value FALSE
Access Locations


Object.
Note This property is a bitmask flag of the identifier MD_SERVER_CONFIGURATION_INFO.
Metabase identifier MD_SERVER_CONFIGURATION_INFO

Metabase bitmask identifier MD_SERVER_CONFIG_AUTO_PW_SYNC
See Also
ServerConfigFlags
ServerConfigFlags
This property contains flags that specify the server configuration established at startup. The flags
contained in this property are individually defined in the following properties:
ServerConfigAutoPWSync ServerConfigSSL128
ServerConfigSSLAllowEncrypt ServerConfigSSL40
Data type Long

Access Locations


Object.

Metabase bitmask value 0x00000000 (not set)
Bitmask values

MD_SERVER_CONFIG_SSL_40 0x00000001 40-bit SSL processing
available on server.
MD_SERVER_CONFIG_SSL_128 0x00000002 128-bit SSL processing
available on server.
MD_SERVER_CONFIG_ALLOW_ENCRYPT 0x00000004 Encryption available on
server.
MD_SERVER_CONFIG_AUTO_PW_SYNC 0x00000008 The subauthenticator DLL
(Iissuba.dll) is enabled on the
server, enabling automatic
password synchronization for
the anonymous user account.
ServerConfigSSL128
This property is a flag that participates in the ServerConfigFlags server configuration specification
property. A value of TRUE indicates that 128-bit Secure Sockets Layer (SSL) processing is installed.
Data type Boolean

Default value FALSE
Access Locations


Object.

Metabase bitmask identifier MD_SERVER_CONFIG_SSL_128
See Also
ServerConfigFlags
ServerConfigSSL40
property. A value of TRUE indicates that 40-bit Secure Sockets Layer (SSL) processing is installed.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_SERVER_CONFIG_SSL_40
See Also
ServerConfigFlags
ServerConfigSSLAllowEncrypt
property. A value of TRUE indicates that the locality allows encryption.
Data type Boolean

Default value FALSE
Access Locations

Object.


Metabase bitmask identifier MD_SERVER_CONFIG_ALLOW_ENCRYPT
See Also
ServerConfigFlags
ServerListenBacklog
This property specifies the number of outstanding sockets that can be queued. The value is based on the
AcceptEx operating system parameter and the server size specified in the ServerSize property. Valid
values for this property range from 5 to 500.
Data type Long

Default value Based on ServerSize
Access Locations

Object.
Metabase identifier MD_SERVER_LISTEN_BACKLOG


See Also
ServerSize
ServerListenTimeout
This property specifies the amount of time in seconds the server should wait before disconnecting a client
that has connected but has not sent any data.
Data type Long

Access Locations

Object.
Metabase identifier MD_SERVER_LISTEN_TIMEOUT

ServerSize
This property specifies the general size of the server, in terms of number of client requests processed per
day. A value of 0 indicates a small Web site that would expect to receive fewer than 10,000 requests per
day, a value of 1 indicates a medium site handling between 10,000 and 100,000 requests a day, and a
value of 2 designates a large site processing more than 100,000 requests a day. The value of this

property is used in calculating the value for the ServerListenBacklog property.
Data type Long

Default value 1 (medium)
Access Locations

Object.
Metabase identifier MD_SERVER_SIZE

Bitmask values

MD_SERVER_SIZE_SMALL 0x00000000 Anticipate fewer than 10,000
requests per day.
MD_SERVER_SIZE_MEDIUM 0x00000001 Anticipate 10,000 to 100,000
requests per day.
MD_SERVER_SIZE_LARGE 0x00000002 Anticipate more than 100,000
requests per day.
See Also
ServerListenBacklog
ServerState

This property presents the current state of the server instance. The states, and the corresponding state
codes, are as follows: 1 (starting), 2 (started), 3 (stopping), 4 (stopped), 5 (pausing), 6 (paused), or 7
(continuing).
This property is read-only.
Data type Long

Access Locations

Object.
Metabase identifier MD_SERVER_STATE

Bitmask values

MD_SERVER_STATE_STARTING 0x00000001 Server starting.
MD_SERVER_STATE_STARTED 0x00000002 Server started.
MD_SERVER_STATE_STOPPING 0x00000003 Server stopping.
MD_SERVER_STATE_STOPPED 0x00000004 Server stopped.
MD_SERVER_STATE_PAUSING 0x00000005 Server pausing.
MD_SERVER_STATE_PAUSED 0x00000006 Server paused.
MD_SERVER_STATE_CONTINUING 0x00000007 Server continuing.
Remarks
To send commands to the server, when working with the IIS Admin Base Object, use the
MD_SERVER_COMMAND property.

SSIExecDisable
This property specifies whether server-side include (SSI) #exec directives are disabled under this path.
Data type Boolean

Default value FALSE (SSIs enabled)
Access Locations

Object.
Metabase identifier MD_SSI_EXEC_DISABLED

SSLUseDSMapper
This property specifies whether IIS is to use the Windows Directory Service certificate mapper or IIS
certificate mapper. If SSLUseDSMapper is set to FALSE, then IIS will use the IIS certificate mapper.

Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_SSL_USE_DS_MAPPER

See Also
AccessSSLFlags
UNCAuthenticationPassthrough
This property enables user authentication passthrough for Universal Naming Convention (UNC) virtual
root access (for authentication schemes that support delegation).
Note Integrated Windows (NTLM) authentication does not support delegation.
Data type Boolean

Default value FALSE
Access Locations


Object.
Metabase identifier MD_VR_PASSTHROUGH

UNCPassword
This property specifies the encrypted password used to gain access to Universal Naming Convention
(UNC) virtual roots.
Data type String

Access Locations


Object.
Metabase identifier MD_VR_PASSWORD

UNCUserName
This property specifies the user name for Universal Naming Convention (UNC) virtual roots.
Data type String

Access Locations

Object.
Metabase identifier MD_VR_USERNAME

See Also
UncPassword, Path
UploadReadAheadSize

This property establishes the number of bytes a Web server will read into a buffer and pass to an ISAPI
extension. This occurs once per client request. The ISAPI extension receives any additional data directly
from the client. The range is 0 to &HFFFFFFFF (4GB).
Data type Long

Default value 49152 (48 KB)
Access Locations

Object.
Metabase identifier MD_UPLOAD_READAHEAD_SIZE

UseHostName
This property specifies whether the server returns its DNS host name (the computer name, by default)
when doing redirects. If the value of this property is FALSE, then the host's IP address is returned
instead of a host name.
Note If the client sends the host header, the server will use the value specified in the host header for the
UseHostName property, regardless of the server's own internal setting.

Data type Boolean

Default value FALSE
Access Locations

Object.
Metabase identifier MD_USE_HOST_NAME

WAMUserName
This property specifies the account user name that IIS uses by default as the COM+ application identity
for newly created IIS out-of-process applications. The values of this property and its companion
property, WAMUserPass, are set when IIS is installed, and match the user name and password values
in the Microsoft Windows user account established at the same time. It is recommended that you do not
change the value of this property. If you do, change it to a valid Windows user account, and change
WAMUserPass to the corresponding password for the new account.
Note Changes to the value of this property and WAMUserPass may disrupt the operation of existing
IIS out-of-process applications. You can synchronize application identities by using Component Services
to edit the user name and password values found on the Identity tab of the property sheet for each
package. See WAMUserPass for additional information. In-process applications are not affected by
these property values.

Data type String

Default value IWAM_MachineName, where MachineName is
the name of the machine on which IIS is installed.
Access Locations

Object.
Metabase identifier MD_WAM_USER_NAME

See Also
WAMUserPass
WAMUserPass
This property specifies the password for the account that IIS uses by default as the COM+ application
identity for newly created IIS out-of-process applications. The values of this property and its companion
property, WAMUserName , are set when IIS is installed, and match the password and user name
values in the Microsoft Windows user account (IWAM_MachineName, where MachineName is the
name of the machine on which IIS is installed) established at the same time. It is recommended that you
do not change the value of this property. If you do, the Windows account password must be changed to
the identical value, and you must also synchronize existing IIS out-of-process application identities by
using Component Services to edit the user name and password values found on the Identity tab of the
property sheet for each package. In-process application packages are not affected by these property
values.
Data type String

Default value (Generated by the setup program when IIS is
installed)

Access Locations

Object.
Metabase identifier MD_WAM_PWD

See Also
WAMUserName
Win32Error
This property indicates the Microsoft Win32 error status code.
Data type Long

Default value (Not set)
Default inheritance Not inheritable
Access Locations
This identifier is available at all metabase keys.
Object.
Metabase identifier MD_WIN32_ERROR

ADSI vs. Base Object Data Types

The ADSI property data types can be used at the scripting level, whereas the IIS Admin Base Object
data types are used only when writing code that uses the IIS Admin Base Object. The difference stems
from the fact that scripting languages such as Microsoft® JScript® and Visual Basic® Scripting Edition
(VBScript) have dissimilar data type implementations when compared to languages such as C and C++.
Use the following table as a reference for ADSI data types, to find the corresponding data type for the
IIS Admin Base Object.
ADSI Data Type Base Object Data Type

Long, Boolean, Integer DWORD_METADATA
String STRING_METADATA
ExpandSz EXPANDSZ_METADATA
IPSec, NTACL BINARY_METADATA
List MULTISZ_METADATA
MimeMapList MULTISZ_METADATA
Visual Basic Object Model

Active Server Pages (ASP) implements classes that enable your component to access the properties and
methods of the ASP built-in objects. The ObjectContext object exposes methods that return an
interface to one of the ASP built-in objects. Your component can use these interfaces to access the
methods and properties of the built-in objects.
The following table lists the built-in object classes:
Class Use to
Application Calls the methods and properties of the Application object.
ASP Error Object Calls the methods and properties of the ASP Error object.
ObjectContext Returns the built-in objects and provide methods used in
transaction processing.
Request Calls the methods and properties of the Request object.
Response Calls the methods and properties of the Response object.

ScriptingContext Returns the built-in objects: Application, Request,

Response, Server, or Session. This is an obsolete
approach. You should use ObjectContext instead.
Server Calls the methods and properties of the Server object.
Session Calls the methods and properties of the Session object.
To use the ObjectContext and built-in objects in a Visual Basic component, you must include a
reference to the Microsoft ® ASP Object Library in your Visual Basic project.
For more information about the built-in objects see the Built-in Object Reference.
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
Collections
Contents Contains all of the items that have been added to the
application through script commands.
StaticObjects Contains all of the objects added to the session with
the <OBJECT> tag.
Methods
Contents.Remove The Contents.Remove method deletes an item from the Application

object's Contents collection.
Contents.RemoveAll The Contents.RemoveAll method deletes all items from the Application
object's Contents collection.
Lock The Lock method prevents other clients from modifying Application object
properties.
Unlock The Unlock method allows other clients to modify Application object
properties.

Events
Application_OnEnd
Application_OnStart
Scripts for the preceding events are declared in the Global.asa file. For more information about these
events and the Global.asa file, see the Global.asa Reference.
Remarks
You can store values in the Application Collections. Information stored in the Application collections is
available throughout the application and has application scope. The following script demonstrates storage
of two types of variables.
<%
Application("greeting") = "Welcome to My Web World!"
Application("num") = 25
%>
Each of these variables would be members of the Application Contents Collection.
You can also assign a component instance to a variable that has application scope. If you assign a
component instance to a variable with the Server.CreateObject method, the variable will be a member
of the Application.Contents collection. If the variable is assigned with the <OBJECT> tag, the variable
will be a member of the Application StaticObjects Collection.
You should be careful about assigning component instances to variables with application scope, because
some components are not designed to be given application scope. For more information, see the
Platform SDK.
If you assign a component instance to a variable in the Application Contents Collection, and use Visual
Basic® Scripting Edition (VBScript) as your primary scripting language, you must use the Set keyword.
This is illustrated in the following script.
<% Set Application("Obj1") = Server.CreateObject("MyComponent") %>
You can then reference the methods and properties of MyComponent on subsequent Web pages by
using this script
<% Application("Obj1").MyObjMethod %>
or by extracting a local copy of the object and using the following
<%
Set MyLocalObj1 = Application("Obj1")
MyLocalObj1.MyObjMethod
%>

Another way to create objects with application scope is by using the <OBJECT> tag in the Global.asa
file. For more information, see the Global.asa Reference.
You cannot store a built-in object in the Application object. For example, each of the following lines
returns an error.
<%
Set Application("var1") = Session
Set Application("var2") = Request
Set Application("var3") = Response
Set Application("var4") = Server
Set Application("var5") = Application
Set Application("var6") = ObjectContext
%>
You should be aware of the threading model used by any components you give application scope. The
threading model used to develop the component will have a significant impact on whether a component
instance should be assigned to a variable in one of the Application collections. For more information,
see Component Design Guidelines.
If you store an array in an Application object, you should not attempt to alter the elements of the stored
array directly. For example, the following script does not work:
<% Application("StoredArray")(3) = "new value" %>
This is because the Application object is implemented as a collection. The array element StoredArray
(3) does not receive the new value. Instead, the value would be included in the Application object
collection, and would overwrite any information that had previously been stored at that location.
It is strongly recommended that if you store an array in the Application object, you retrieve a copy of
the array before retrieving or changing any of the elements of the array. When you are done with the
array, you should store the array in the Application object again, so that any changes you made are
saved. This is demonstrated in the following scripts.
---file1.asp---
<%
'Creating and initializing the array.
dim MyArray()
Redim MyArray(5)
MyArray(0) = "hello"
MyArray(1) = "some other string"
'Storing the array in the Application object.

Application.Lock
Application("StoredArray") = MyArray
Application.Unlock
Server.Transfer("file2.asp")
%>
---file2.asp---
<%
'Retrieving the array from the Application Object

'and modifying its second element.

LocalArray = Application("StoredArray")
LocalArray(1) = " there"
'Printing out the string "hello there."

Response.Write(LocalArray(0)&LocalArray(1))
'Re-storing the array in the Application object.

'This overwrites the values in StoredArray with the new values.
Application.Lock
Application("StoredArray") = LocalArray
Application.Unlock
%>
Example
The following example uses the application variable NumVisits to store the number of times that a
particular page has been accessed. The Lock method is called to ensure that only the current client can
access or alter NumVisits. Calling the Unlock method then enables other users to access the
Application object.
<%
Application.Lock
Application("NumVisits") = Application("NumVisits") + 1
Application.Unlock
%>
This application page has been visited

<%= Application("NumVisits") %> times!
You can see a working sample .asp file that uses the Application object in the Building ASP
Applications section of the ASP Samples.
Application Collections
The Application object supports these collections:
? Contents
? StaticObjects
Application Contents Collection
The Contents collection contains all the items that have been added to the application through a script
command. You can use the Contents collection to obtain a list of items that have been given application
scope, or to specify a particular item to be the target of an operation. You can also remove items from

the collection with the Remove and RemoveAll methods.
Syntax
Application.Contents(Key)
Parameters
Key
Specifies the name of the item to retrieve.
Methods
Contents.Remove Deletes an item from the collection.

Contents.RemoveAll Deletes all items from the collection.
Remarks
The Application.Contents collection contains those items that have been declared at the application
level without using the <OBJECT> tags. This would include both objects created with
Server.CreateObject as well as scalar variables established through an Application declaration. In the
following script, for example, both strHello and objCustom would be members of the
Application.Contents collection:
<%
Application("strHello") = "Hello"
Set Application("objCustom") = Server.CreateObject("MyComponent") %>
The Application.Contents collection supports For...Each and For...Next iteration. The following
script illustrates each of these methods of iterating through the Application.Contents collection:
<%
Application("strText1") = "1234567890"
Application("strText2") = "ABCDEFGHIJ"
Application("strText3") = "A1B2C3D4E5"
%>
<%
For Each Key in Application.Contents
Response.Write Key + " = " + Application(Key) + "<BR>"
Next
%>
<%
For intItem = 1 to Application.Contents.Count
Response.Write CStr(intItem) + " = "
Response.Write Application.Contents(intItem) + "<BR>"
Next
%>
You can see a working sample .asp file that uses the Application.Contents collection in the Building
ASP Applications section of the ASP Samples.

Application StaticObjects Collection
The StaticObjects collection contains all of the objects created with the <OBJECT> tags within the
scope of the Application object. You can use the collection to determine the value of a specific property
for an object, or iterate through the collection and retrieve all properties for all static objects.
Syntax
Application.StaticObjects(Key)
Parameters
Key
Specifies the name of the item to retrieve.
Remarks
You can use an iterating control structure to loop through the keys of the StaticObjects collection. This
is demonstrated in the following example.
<%
Dim strKey
For Each strKey In Application.StaticObjects

Response.Write strKey & " = <i>(object)</i><BR>"
Next
%>
Application Methods
The Application object exposes the following methods:
? Contents.Remove
? Contents.RemoveAll
? Lock
? Unlock
Contents.Remove

The Application.Contents.Remove method deletes an item from a collection.
Syntax
Application.Contents.Remove(name|index)
Parameters
name
The identifier for the item to remove.
index
An index offset indicating which item in the list to remove.
Remarks
The Contents.Remove method takes either a string or an integer as an input parameter. If the input
parameter is a string, the method will search the contents collection for an item with that name and
remove it. If the input parameter is an integer, the method counts that number of items from the start of
the collection, and removes the corresponding item.
Example
The following example adds two items to the Application.Contents collection and removes the second
one.
<%
Application("strFirst")=("First thing")
Application("strSecond")=("Second thing")
Application.Contents.Remove(strFirst)
%>
See Also
Contents.RemoveAll
Contents.RemoveAll
The Application.Contents.RemoveAll method removes all items that have been added to the
Application.Contents collection.
Syntax
Application.Contents.RemoveAll ()
See Also
Contents.Remove

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
Example
<%
Application.Lock
Application("datLastVisited") = Now()
Application.Unlock
%>

In the preceding example the Lock method prevents more than one client from accessing the variable
NumVisits at a time. If the application had not been locked, two clients could try to increment the
variable NumVisits simultaneously.
Applies To
Application Object
See Also
Unlock
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

Example
<%
Application.Lock
Application("datLastVisited") = Now()
Application.Unlock
%>

In the preceding example the Unlock method releases the locked object so that the next client can
increment NumVisits.
Note The application Lock method is cumulative, meaning if the same script calls Lock several times, it
must also call Unlock the same number of times to fully release the application. If this does not occur, the
application lock will be held until the script is finished running.
Applies To
Application Object
See Also
Lock
ASPError Object
You can use the ASPError object to obtain information about an error condition that has occurred in an
ASP script. The ASPError object is returned by the Server.GetLastError method. The ASPError
object exposes read-only properties.
Syntax
ASPError.property
Properties
ASPCode Returns an error code generated by IIS.

Number Returns the standard COM error code.
Source Indicates if the source of the error was internal to
ASP, the scripting language, or an object.

FileName Indicates the name of the .asp file that was being
processed when the error occurred.
LineNumber Indicates the line within the .asp file that generated
the error.
Description Returns a short description of the error.
ASPDescription Returns a more detailed description of the error if
it is an ASP-related error.
Remarks
When IIS encounters an error with either compiling or running an .asp file it will generate a 500;100
custom error. By default all Web sites and applications will transfer processing of a 500;100 custom
error to the file 500-100.asp which is installed by default to windir\Help\iisHelp\common. After a
500;100 custom error is generated, IIS will also create an instance of the ASPError object which
describes the error condition. The file 500-100.asp uses the properties of this object to display a page
describing the error condition. You can develop additional error processing by either modifying 500-
100.asp or by creating a new .asp file for processing errors.
Example
The following example is extracted from the file 500-100.asp and demonstrates writing the information
exposed by the ASPError object to a table.
<TABLE>
<TR><TD><font style="font:9pt/12pt verdana; color:black">ASP Code <TD><font style="
<TR><TD><font style="font:9pt/12pt verdana; color:black">Number <TD><font style="
<TR><TD><font style="font:9pt/12pt verdana; color:black">Source <TD><font style="
<TR><TD><font style="font:9pt/12pt verdana; color:black">FileName <TD><font style="
<TR><TD><font style="font:9pt/12pt verdana; color:black">LineNumber <TD><font style="
<TR><TD><font style="font:9pt/12pt verdana; color:black">Description <TD><font style="
<TR><TD><font style="font:9pt/12pt verdana; color:black">ASP Description <TD><font style="
</TABLE>
See Also
Server.GetLastError
ASPCode
The ASPCode property returns a string that contains an error code generated by IIS.
Syntax
ASPError.ASPCode ()
Applies To

ASPError Object
Number
The Number property returns a long integer that contains the error code returned by a COM
component. This will be a standard COM error code.
Syntax
ASPError.Number ()
Applies To
ASPError Object
Source
The Source property returns a string indicating if the error was generated by IIS, a scripting language, or
a component.
Syntax
ASPError.Source ()
Applies To
ASPError Object
FileName
The FileName property returns a string that indicates the .asp file that generated the error.
Syntax
ASPError.FileName ()

Applies To
ASPError Object
LineNumber
The LineNumber property returns a long integer indicating the number of the line within the .asp file that
generated the error.
Syntax
ASPError.LineNumber ()
Applies To
ASPError Object
Description
The Description property returns a string describing the error.
Syntax
ASPError.Description ()
Applies To
ASPError Object
ASPDescription
The ASPDescription property returns a string providing a more complete description of the error, if
available.
Syntax

ASPError.ASPDescription ()
Applies To
ASPError Object
You can use the ObjectContext object to either commit or abort a transaction, managed by Component
Services, that has been initiated by a script contained in an ASP page.
When an .asp file contains the @TRANSACTION directive, the page runs in a transaction and does not
finish processing until the transaction either succeeds completely or fails.
Syntax
ObjectContext.method
Methods
SetAbort The SetAbort method declares that the transaction initiated by the script
has not completed and the resources should not be updated.
SetComplete The SetComplete method declares that the script is not aware of any
reason for the transaction not to complete. If all components participating
in the transaction also call SetComplete, the transaction will complete.
Events
OnTransactionAbort
OnTransactionCommit
Remarks
ObjectContext implements two methods of the COM ObjectContext object. The SetAbort method
explicitly aborts the transaction. This causes Component Services to prevent any updates to resources
that were contacted during the first phase of the transaction. When the transaction aborts, the script's
OnTransactionAbort event will be processed.
Calling the SetComplete method does not necessarily mean that the transaction is complete. The
transaction will only complete if all of the transactional components called by the script call
SetComplete. In most instances, you will not need to call SetComplete within the script, as the script is

assumed to be complete if it finishes processing without calling SetAbort.
ObjectContext exposes methods in addition to SetAbort and SetComplete. These other methods are
not available to scripts in ASP scripts; however, they are available to components called by the script.
Example
The following example uses the SetAbort and SetComplete methods. The Sales.htm file obtains data
required to process a sales request. The second file, SalesVerify.asp contains a script that uses two
objects, Inventory and Sales, to process the sale. SetAbort is called if Inventory returns an error
code indicating that there is not sufficient inventory on hand to process the sale. If the Inventory object
does not return the error code, SetComplete is called and the sale is processed.
Sales.htm
<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN">
<HTML>
<HEAD>
<TITLE>Sales Order</TITLE>
</HEAD>
<BODY BGCOLOR="#FFFFFF"><FONT FACE="ARIAL,HELVETICA">
<H2>Sales Order Form </H2>
<FORM METHOD=POST ACTION="SalesVerify.asp">

<P>Please enter the product code, quantity, and your account number.
<INPUT TYPE=TEXT NAME=QuantityToBuy>
<INPUT TYPE=TEXT NAME=ProductCode>
<INPUT TYPE=TEXT NAME=AccountIn>
<P>
<INPUT TYPE=SUBMIT>
</FONT>
</BODY>
</HTML>
SalesVerify.asp file
<%@ Transaction = Required %>

<%
Set CurrentQOH = Server.CreateObject("Mycomp.Inventory")
Set CurrentSales = Server.CreateObject("Mycomp.Sales")
CheckQuantity = Request("QuantityToBuy")
CheckProduct = Request("ProductCode")
QuantityStatus = CurrentQOH.CheckQOH(CheckQuantity,CheckProduct)
If QuantityStatus = None
ObjectContext.SetAbort
Response.Write "Sorry, there is not sufficient quantity on hand to
process your sale."
Else
ObjectContext.SetComplete
Account = Request("AccountIn")
Saleupdate = CurrentSales.PostIt(AccountIn)
End If
%>

For more information, see Understanding Transactions and Processing Transactions.
ObjectContext Methods
The ObjectContext object exposes the following methods:
? SetAbort
? SetComplete
SetAbort
The SetAbort method aborts a transaction initiated by an .asp file.
Syntax
Applies To
SetComplete
The SetComplete method overrides any previous SetAbort method that has been called in a script.
Syntax
Applies To
ObjectContext Events

The following events can occur after an ObjectContext method:
? OnTransactionAbort
? OnTransactionCommit
OnTransactionAbort
The OnTransactionAbort event occurs if the transaction is aborted. When the OnTransactionAbort
event occurs, IIS will process the script's OnTransactionAbort subroutine, if it exists.
Example
The following example sends a response to the client with the transaction aborts:
<%@ TRANSACTION=Required LANGUAGE="VBScript" %>

<% Option Explicit
Sub OnTransactionAbort
Response.Write "<p><b>The Transaction just aborted</b>."
Response.Write "This message came from the "
Response.Write "OnTransactionAbort() event handler."
end sub
%>
Applies To
OnTransactionCommit
The OnTransactionCommit event occurs after a transactional script's transaction commits. When the
OnTransactionCommit event occurs, IIS will process the script's OnTransactionCommit subroutine,
if it exists.
Example
The following example sends a response to the client with the transaction commits:
<%@ TRANSACTION=Required LANGUAGE="VBScript" %>

<% Option Explicit
Sub OnTransactionCommit
Response.Write "<p><b>The Transaction just committed</b>."
Response.Write "This message came from the "
Response.Write "OnTransactionCommit() event handler."
end sub

%>
Applies To
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)
Collections
ClientCertificate The values of fields stored in the client certificate that is sent in the
HTTP request.
Cookies The values of cookies sent in the HTTP request.
Form The values of form elements in the HTTP request body.
QueryString The values of variables in the HTTP query string.
ServerVariables The values of predetermined environment variables.
Properties
TotalBytes Read-only; specifies the total number of bytes the client is sending in
the body of the request.
Methods
BinaryRead Retrieves data sent to the server from the client as part of a POST
request.
Variable parameters are strings that specify the item to be retrieved from a collection or to be used as
input for a method or property. For more information about the variable parameter, see the individual
collection descriptions.
Remarks
If the specified variable is not in one of the preceding five collections, the Request object returns
EMPTY.

All variables can be accessed directly by calling Request(variable) without the collection name. In this
case, the Web server searches the collections in the following order.
1. QueryString
2. Form
3. Cookies
4. ClientCertificate
5. ServerVariables
If a variable with the same name exists in more than one collection, the Request object returns the first
instance that the object encounters.
It is strongly recommended that when referring to members of a collection the full name be used. For
example, rather than Request.(AUTH_USER) use Request.ServerVariables(AUTH_USER). This
will allow the server to locate the item more quickly.
See Also
Response Object
Request Collections
The Request object contains the following collections.
? ClientCertificate
? Cookies
? Form
? QueryString
? ServerVariables
ClientCertificate
The ClientCertificate collection retrieves the certification fields (specified in the X.509 standard) from a
request issued by the Web browser.
If a Web browser uses the SSL3.0/PCT1 protocol (in other words, it uses a URL starting with https://
instead of http://) to connect to a server and the server requests certification, the browser sends the
certification fields.
If no certificate is sent, the ClientCertificate collection returns EMPTY.
Before you can use the ClientCertificate collection, you must configure your Web server to request
client certificates.

Syntax
Request.ClientCertificate( Key[SubField] )
Parameters
Key
Specifies the name of the certification field to retrieve. A client certificate consists of the following
fields.
Value Meaning
Certificate A string containing the binary stream of the entire certificate content in
ASN.1 format.
Flags A set of flags that provide additional client certificate information. The
following flags may be set:
ceCertPresent—A client certificate is present.
ceUnrecognizedIssuer—The last certification in this chain is from an

unknown issuer.
Note To use the preceding flags you must include the client-certificate
include file in your ASP page. If you are using VBScript, include
cervbs.inc. If you are using JScript, include cerjavas.inc. These files are
installed in the \Inetpub\ASPSamp\Samples directory.
Issuer A string that contains a list of subfield values containing information about
the issuer of the certificate. If this value is specified without a SubField,
the ClientCertificate collection returns a comma-separated list of
subfields. For example, C=US, O=Verisign, and so on.
SerialNumber A string that contains the certification serial number as an ASCII
representation of hexadecimal bytes separated by hyphens (-). For
example, 04-67-F3-02.
Subject A string that contains a list of subfield values. The subfield values contain
information about the subject of the certificate. If this value is specified
without a SubField, the ClientCertificate collection returns a comma-
separated list of subfields. For example, C=US, O=Msft, and so on.
ValidFrom A date specifying when the certificate becomes valid. This date follows
VBScript format and varies with international settings. For example, in the
U.S., 9/26/96 11:59:59 PM. The year value is displayed as a four-digit
number.
ValidUntil A date specifying when the certificate expires. The year value is displayed
as a four-digit number.
SubField

An optional parameter you can use to a retrieve an individual field in either the Subject or Issuer
keys. This parameter is added to the Key parameter as a suffix. For example, IssuerO or
SubjectCN. The following table lists some common SubField values.
Value Meaning
C Specifies the name of the country of origin.
CN Specifies the common name of the user. (This subfield is only used with the
Subject key.)
GN Specifies a given name.
I Specifies a set of initials.
L Specifies a locality.
O Specifies the company or organization name.
OU Specifies the name of the organizational unit.
S Specifies a state or province.
T Specifies the title of the person or organization.
SubField values other than those listed in the preceding table can be identified by their ASN.1 identifier.
The format of the ASN.1 identifier is a list of numbers separated by a period (.). For example,
3.56.7886.34.
Remarks
You can iterate through the keys of the ClientCertificate collection. This is demonstrated in the
following example.
<%
For Each strKey in Request.ClientCertificate
Response.Write strkey & " = " & Request.ClientCertificate(strkey) & "<BR>")
Next
%>
Example
The following example uses the Subject key to test whether a client certificate has been presented.
<%
If Len(Request.ClientCertificate("Subject")) = 0
Response.Write("No client certificate was presented")
End if
%>
The following example retrieves the common name of the company that issued the client certificate.
<%= Request.ClientCertificate("IssuerCN") %>
The following example checks the organization name of the subject of the client certification.

<%
If (Request.ClientCertificate("Subject")="Msft")
Response.Write("Good Choice!")
End if
%>
The following example displays the expiration date of the client certificate.
This certification will expire on

<%= Request.ClientCertificate("ValidUntil") %>
The following example uses the Flags key to test whether the issuer of the certificate is known. The
include statement in the first line enables this script to use the named flag ceUnrecognizedIssuer.


<%
If Request.ClientCertificate("Flags") and ceUnrecognizedIssuer then
Response.Write "Unrecognized issuer"
End If
%>
Applies To
Request Object
See Also
Cookies, Form, QueryString, ServerVariables
Cookies
The Cookies collection enables you to retrieve the values of the cookies sent in an HTTP request.
Syntax
Request.Cookies(cookie)[(key)|.attribute]
Parameters
cookie
Specifies the cookie whose value should be retrieved.
key
An optional parameter used to retrieve subkey values from cookie dictionaries.
attribute
Specifies information about the cookie itself. The attribute parameter can be the following.

Name Description
HasKeys Read-only. Specifies whether the cookie contains keys.
Remarks
You can access the subkeys of a cookie dictionary by including a value for key. If a cookie dictionary is
accessed without specifying key, all of the keys are returned as a single query string. For example, if
MyCookie has two keys, First and Second, and you do not specify either of these keys in a call to
Request.Cookies, the following string is returned.
First=firstkeyvalue&Second=secondkeyvalue
If two cookies with the same name are sent by the client browser, Request.Cookies returns the one
with the deeper path structure. For example, if two cookies had the same name but one had a path
attribute of /www/ and the other of /www/home/, the client browser would send both cookies to
the /www/home/ directory, but Request.Cookies would only return the second cookie.
To determine whether a cookie is a cookie dictionary (whether the cookie has keys), use the following
script.
<%= Request.Cookies("myCookie").HasKeys %>
If myCookie is a cookie dictionary, the preceding value evaluates to TRUE. Otherwise, it evaluates to
FALSE.
You can iterate through all the cookies in the Cookie collection, or all the keys in a cookie. However,
iterating through keys on a cookie that does not have keys will not produce any output. You can avoid
this situation by first checking to see whether a cookie has keys by using the .HasKeys syntax. This is
demonstrated in the following example:
<%
For Each strKey In Request.Cookies
Response.Write strKey & " = " & Request.Cookies(strKey) & "<BR>"
If Request.Cookies(strKey).HasKeys Then
For Each strSubKey In Request.Cookies(strKey)
Response.Write "->" & strKey & "(" & strSubKey & ") = " & _
Request.Cookies(strKey)(strSubKey) & "<BR>"
Next
End If
Next
%>
Example
The following example prints the value of myCookie in a Web page.
Here is the value of the cookie named myCookie:

<%= Request.Cookies("myCookie") %>

Note Cookies are described in detail in the HTTP state management specification, which is available at
WWW.W3.ORG.
Applies To
Request Object
See Also
ClientCertificate, Form, QueryString, ServerVariables
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 in 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 objects with the same name (for example, HTML SELECT tags),
the item in the form collection will be a comma-delimited list of all the selected values.
Applies To
Request Object
See Also
ClientCertificate, Cookies, QueryString, ServerVariables
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 the 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 variable 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 can 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
Applies To
Request Object
See Also
ClientCertificate, Cookies, Form, ServerVariables
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. It can be one of the following
values.
Variable Description
ALL_HTTP All HTTP headers sent by the client.
ALL_RAW Retrieves all headers in raw form. The difference
between ALL_RAW and ALL_HTTP is that
ALL_HTTP places an HTTP_ prefix before the
header name and the header name is always
capitalized. In ALL_RAW the header name and
values appear as they are sent by the client.
APPL_MD_PATH Retrieves the metabase path for the Application
for the ISAPI DLL.
APPL_PHYSICAL_PATH Retrieves the physical path corresponding to the
metabase path. IIS converts the
APPL_MD_PATH to the physical (directory)
path to return this value.
AUTH_PASSWORD The value entered in the client's authentication
dialog. This variable is available only if Basic
authentication is used.
AUTH_TYPE The authentication method that the server uses to
validate users when they attempt to access a
protected script.
AUTH_USER Raw authenticated user name.
CERT_COOKIE Unique ID for client certificate, returned as a
string. Can be used as a signature for the whole
client certificate.
CERT_FLAGS bit0 is set to 1 if the client certificate is present.
bit1 is set to 1 if the cCertification authority of the

client certificate is invalid (it is not in the list of
recognized CAs on the server).
CERT_ISSUER Issuer field of the client certificate (O=MS,
OU=IAS, CN=user name, C=USA).
CERT_KEYSIZE Number of bits in Secure Sockets Layer
connection key size. For example, 128.
CERT_SECRETKEYSIZE Number of bits in server certificate private key.
For example, 1024.
CERT_SERIALNUMBER Serial number field of the client certificate.
CERT_SERVER_ISSUER Issuer field of the server certificate.

CERT_SERVER_SUBJECT Subject field of the server certificate.

CERT_SUBJECT Subject field of the client certificate.
CONTENT_LENGTH The length of the content as given by the client.
CONTENT_TYPE The data type of the content. Used with queries
that have attached information, such as the HTTP
queries GET, POST, and PUT.
GATEWAY_INTERFACE The revision of the CGI specification used by the
server. The format is CGI/revision.
HTTP_<HeaderName> The value stored in the header HeaderName.
Any header other than those listed in this table
must be prefixed by HTTP_ in order for the
ServerVariables collection to retrieve its value.
Note The server interprets any underscore (_)

characters in HeaderName as dashes in the
actual header. For example if you specify
HTTP_MY_HEADER, the server searches for a
header sent as MY-HEADER.
HTTP_ACCEPT Returns the value of the Accept header.
HTTP_ACCEPT_LANGUAGE Returns a string describing the language to use for
displaying content.
HTTP_USER_AGENT Returns a string describing the browser that sent
the request.
HTTP_COOKIE Returns the cookie string that was included with
the request.
HTTP_REFERER Returns a string containing the URL of the original
request when a redirect has occurred.
HTTPS Returns ON if the request came in through secure
channel (SSL) or it returns OFF if the request is
for a non-secure channel.
HTTPS_KEYSIZE Number of bits in Secure Sockets Layer
connection key size. For example, 128.
HTTPS_SECRETKEYSIZE Number of bits in server certificate private key.
For example, 1024.
HTTPS_SERVER_ISSUER Issuer field of the server certificate.
HTTPS_SERVER_SUBJECT Subject field of the server certificate.

INSTANCE_ID The ID for the IIS instance in textual format. If the

instance ID is 1, it appears as a string. You can
use this variable to retrieve the ID of the Web-
server instance (in the metabase) to which the
request belongs.
INSTANCE_META_PATH The metabase path for the instance of IIS that
responds to the request.
LOCAL_ADDR Returns the Server Address on which the request
came in. This is important on multihomed
machines where there can be multiple IP
addresses bound to the machine and you want to
find out which address the request used.
LOGON_USER The Windows account that the user is logged into.
PATH_INFO Extra path information as given by the client. You
can access scripts by using their virtual path and
the PATH_INFO server variable. If this
information comes from a URL, it is decoded by
the server before it is passed to the CGI script.
PATH_TRANSLATED A translated version of PATH_INFO that takes
the path and performs any necessary virtual-to-
physical mapping.
QUERY_STRING Query information stored in the string following
the question mark (?) in the HTTP request.
REMOTE_ADDR The IP address of the remote host making the
request.
REMOTE_HOST The name of the host making the request. If the
server does not have this information, it will set
REMOTE_ADDR and leave this empty.
REMOTE_USER Unmapped user-name string sent in by the user.
This is the name that is really sent by the user, as
opposed to the names that are modified by any
authentication filter installed on the server.
REQUEST_METHOD The method used to make the request. For
HTTP, this is GET, HEAD, POST, and so on.
SCRIPT_NAME A virtual path to the script being executed. This is
used for self-referencing URLs.
SERVER_NAME The server's host name, DNS alias, or IP address
as it would appear in self-referencing URLs.
SERVER_PORT The port number to which the request was sent.
SERVER_PORT_SECURE A string that contains either 0 or 1. If the request
is being handled on the secure port, then this will
be 1. Otherwise, it will be 0.

SERVER_PROTOCOL The name and revision of the request information

protocol. The format is protocol/revision.
SERVER_SOFTWARE The name and version of the server software that
answers the request and runs the gateway. The
format is name/version.
URL Gives the base portion of the URL.
Remarks
If a client sends a header other than those specified in the preceding table, you can retrieve the value of
that header by prefixing the header name with HTTP_ in the call to Request.ServerVariables. For
example, if the client sent the header
SomeNewHeader:SomeNewValue
you could retrieve SomeNewValue by using the following syntax:
<% Request.ServerVariables("HTTP_SomeNewHeader") %>
You can iterate through each server variable name. For example, the following script prints out all of the
server variables in a table:
<TABLE BORDER="1">
<TR><TD><B>Server Variable</B></TD><TD><B>Value</B></TD></TR>
<% For Each strKey In Request.ServerVariables %>
<TR><TD> <%= strKey %> </TD><TD> <%= Request.ServerVariables(strKey) %> </TD></TR>
<% Next %>
</TABLE>
Example
The following example uses the Request object to display several server variables:
<HTML>

ALL_HTTP server variable =
<%= Request.ServerVariables("ALL_HTTP") %> <BR>
CONTENT_LENGTH server variable =
<%= Request.ServerVariables("CONTENT_LENGTH") %> <BR>
CONTENT_TYPE server variable =
<%= Request.ServerVariables("CONTENT_TYPE") %> <BR>
QUERY_STRING server variable =
<%= Request.ServerVariables("QUERY_STRING") %> <BR>
SERVER_SOFTWARE server variable =
<%= Request.ServerVariables("SERVER_SOFTWARE") %> <BR>
</HTML>
The next example uses the ServerVariables collection to insert the name of the server into a hyperlink.
<A HREF = "http://<%= Request.ServerVariables("SERVER_NAME") %>

/scripts/MyPage.asp">Link to MyPage.asp</A>

Applies To
Request Object
See Also
ClientCertificate, Cookies, Form, QueryString
Request Properties
The Request object supports this property:
? TotalBytes
TotalBytes
The TotalBytes property specifies the total number of bytes the client sent in the body of the request.
This property is Read-only.
Syntax
Counter = Request.TotalBytes
Parameters
Counter
Specifies a variable to receive the total number of bytes that the client sends in the request.
Example
The following script sets a variable equal to the total number of bytes included in a request object.
<%
Dim bytecount
bytecount = Request.TotalBytes
%>
Applies To
Request Object
See Also

BinaryRead
Request Methods
The Request object supports the following method:
? BinaryRead
BinaryRead
The BinaryRead method retrieves data sent to the server from the client as part of a POST request.
This method retrieves the data from the client and stores it in a SafeArray. A SafeArray is an array that
contains information about the number of dimensions and the bounds of its dimensions.
Syntax
variant = Request.BinaryRead(count)
Parameters
variant
Contains an array of unsigned bytes returned by this method. This parameter will be of type
VT_ARRAY | VT_UI1, which is a variant array of unsigned one byte characters.
count
Before execution, specifies how many bytes to read from the client. After this method returns,
count will contain the number of bytes successfully read from the client. The total number of bytes
that will actually be read is less than or equal to Request.TotalBytes.
Remarks
The BinaryRead method is used to read the raw data sent by the client as part of a POST request. This
method is used for low-level access to this data, as opposed to, for example, using the Request.Form
collection to view form data sent in a POST request. Once you have called BinaryRead, referring to
any variable in the Request.Form collection will cause an error. Conversely, once you have referred to
a variable in the Request.Form collection, calling BinaryWrite will cause an error. Remember, if you
access a variable in the Request collection without specifying which subcollection it belongs to, the
Request.Form collection may be searched, bringing this rule into force.
Example
The following example uses the BinaryRead method to place the content of a request into a safe array.

<%
Dim vntPostedData, lngCount
lngCount = Request.TotalBytes
vntPostedData = Request.BinaryRead(lngCount)
%>
Applies To
Request Object
See Also
TotalBytes, ClientCertificate, Cookies, Form, QueryString, ServerVariables
Response Object
You can use the Response object to send output to the client.
Syntax
Response.collection|property|method
Collections
Cookies Specifies cookie values. Using this collection, you can set cookie
values.
Properties
Buffer Indicates whether page output is buffered.

CacheControl Determines whether proxy servers are able to cache the output
generated by ASP.
Charset Appends the name of the character set to the content-type header.
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.
IsClientConnected Indicates whether the client has disconnected from the server.

Pics Set the value for the pics-label response header, to indicate the PICS
content rating.
Status The value of the status line returned by the server.
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.
See Also
Request Object
Response Collections
The Response object has the following collection.
? Cookies
Cookies
The Cookies collection sets the value of a cookie. If the specified cookie does not exist, it is created. If
the cookie exists, it takes the new value and the old value is discarded.
Syntax
Response.Cookies(cookie)[(key)|.attribute] = value

Parameters
cookie
The name of the cookie.
key
An optional parameter. If key is specified, cookie is a dictionary, and key is set to value.
attribute
Specifies information about the cookie itself. The attribute parameter can be one of the following.
Name Description
Domain Write-only. If specified, the cookie is sent only to requests to this
domain.
Expires Write-only. The date on which the cookie expires. This date must be
set in order for the cookie to be stored on the client's disk after the
session ends. If this attribute is not set to a date beyond the current
date, the cookie will expire when the session ends.
HasKeys Read-only. Specifies whether the cookie contains keys.
Path Write-only. If specified, the cookie is sent only to requests to this path.
If this attribute is not set, the application path is used.
Secure Write-only. Specifies whether the cookie is secure.
Value
Specifies the value to assign to key or attribute.
Remarks
If a cookie with a key is created, as in the following script,
<%
Response.Cookies("mycookie")("type1") = "sugar"
Response.Cookies("mycookie")("type2") = "ginger snap"
%>
this header is sent:
Set-Cookie:MYCOOKIE=TYPE1=sugar&TYPE2=ginger+snap
A subsequent assignment to myCookie without specifying a key, would destroy type1 and type2. This
is shown in the following example.
<% Response.Cookies("myCookie") = "chocolate chip" %>
In the preceding example, the keys type1 and type2 are destroyed and their values are discarded. The
myCookie cookie now has the value chocolate chip.

Conversely, if you call a cookie with a key, it destroys any non-key values the cookie contained. For
example, if after the preceding code you call Response.Cookies with the following
<% Response.Cookies("myCookie")("newType") = "peanut butter" %>
The value chocolate chip is discarded and newType would be set to peanut butter.
To determine whether a cookie has keys, use the following syntax.
<%= Response.Cookies("myCookie").HasKeys %>
If myCookie is a cookie dictionary, the preceding value is TRUE. Otherwise, it is FALSE.
You can use an iterator to set cookie attributes. For example, to set all of the cookies to expire on a
particular date, use the following syntax.
<%
For Each cookie in Response.Cookies
Response.Cookie(cookie).ExpiresAbsolute = #July 4, 1997#
Next
%>
You can also iterate through the values of all the cookies in a collection, or all the keys in a cookie.
However, if you try to iterate through the values for a cookie that does not have keys, nothing will be
returned. To avoid this, you can first use the .HasKeys syntax to check whether a cookie has any keys.
This is demonstrated in the following example.
<%
If Not cookie.HasKeys Then
'Set the value of the cookie.
Response.Cookies(cookie) = ""
Else
'Set the value for each key in the cookie collection.
For Each key in Response.Cookies(cookie)
Response.Cookies(cookie)(key) = ""
Next
%>
Example
The following examples demonstrate how you can set a value for a cookie and assign values to its
attributes.
<%
Response.Cookies("Type") = "Chocolate Chip"
Response.Cookies("Type").ExpiresAbsolute = "July 31, 2001"
Response.Cookies("Type").Path = "/"
%>
Applies To

Response Object
See Also
Request.Cookies
Response Properties
The Response object has the following properties:
? Buffer
? CacheControl
? Charset
? ContentType
? Expires
? ExpiresAbsolute
? IsClientConnected
? PICS
? Status
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
Specifies whether or not to buffer page output. It can be one of the following values.

Value Description
FALSE No buffering. The server sends output to the client as it is processed.
This is the default value for versions of IIS up to and including 4.0. For
version 5.0 and later, the default value is True.
TRUE The server does not send output to the client until all of the ASP scripts
on the current page have been processed, or until the Flush or End
method has been called.
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 Using IIS Admin Objects.
Applies To
Response Object
See Also
Flush, End
CacheControl
The CacheControl property overrides the Private default value. When you set this property to Public,
proxy servers can cache the output generated by ASP.
Syntax
Response.CacheControl [= Cache Control Header ]
Parameters
Cache Control Header

A cache control header that will be either Public or Private.

Value Description
Private Only private caches may cache this page. This
is the default value. Most proxy servers will
not cache pages with this setting.
Public Public caches, such as proxy servers, will

cache pages with this setting.
Remarks
Setting CacheControl to public may improve the perceived performance of your .asp files. If your .asp
file generates custom HTML for every request, you will not improve performance by setting
CacheControl to public. The values for Private and Public are strings, and must be enclosed in quotation
marks (" ").
Applies To
Response Object
Charset
The Charset property appends the name of the character set (for example, ISO-LATIN-7) to the
content-type header in the response object.
Syntax
Response.Charset(CharsetName)
Parameters
CharsetName
A string that specifies a character set for the page. The character set name will be appended to
the content-type header in the Response object.
Example
For an ASP page that did not include the Response.Charset property, the content-type header would
be
content-type:text/html
If the same .asp file included
<% Response.Charset= "ISO-LATIN-7" %>

the content-type header would be
content-type:text/html; charset=ISO-LATIN-7
Remarks
This function inserts any string in the header, regardless of whether it represents a valid character set or
not.
If a single page contains multiple tags containing Response.Charset, each Response.Charset will
replace the previous CharsetName. As a result, the character set will be set to the value specified by the
last instance of Response.Charset in the page.
On Macintosh computers, the default U.S. character set is not ISO-LATIN-1. When serving up
documents, Personal Web Server for Macintosh automatically converts from the Macintosh character set
to ISO-Latin-1. In the U.S. version, all pages are assumed to be in the U.S. Macintosh character set
unless the Response.Charset is used. If Response.Charset is used to change the character set,
Personal Web Server for Macintosh does not convert the character set.
Applies To
Response Object
ContentType
The ContentType property specifies the HTTP content type for the response. If no ContentType is
specified, the default is text/HTML.
Syntax
Response.ContentType [= ContentType ]
Parameters
ContentType
A string describing the content type. This string is usually formatted type/subtype where type is
the general content category and subtype is the specific content type. For a full list of supported
content types, see your Web browser documentation or the current HTTP specification.
Example
The following example sets the content type to Channel Definition Format (CDF).
<% Response.ContentType = "application/x-cdf" %>

The following examples set the ContentType property to other common values.
<% Response.ContentType = "text/HTML" %>

<% Response.ContentType = "image/GIF" %>
<% Response.ContentType = "image/JPEG" %>
<% Response.ContentType = "text/plain" %>
<% Response.ContentType = "image/JPEG" %>
Applies To
Response Object
Expires
The Expires property specifies the length of time before a page cached on a browser expires. If the user
returns to the same page before it expires, the cached version is displayed.
Syntax
Response.Expires [= number]
Parameters
number
The time in minutes before the page expires.
Remarks
When your .asp file calls Response.Expires, IIS creates an HTTP header indicating the time on the
server. If the system time on the client is earlier than the system time on the server (due to either the client
or server having an inaccurate time setting, or time-zone differences) setting the parameter to 0 will not
have the effect of expiring the page immediately. You can use the Response.ExpiresAbsolute property
to achieve immediate expiration of a page. In addition, you can use a negative number for the Expires
property. For example
<%Response.Expires = -1 %>
will expire the response immediately.
If there are multiple calls to Response.Expires on a single page, the server will use the shortest time
period.
Applies To
Response Object
See Also

ExpiresAbsolute
ExpiresAbsolute
The ExpiresAbsolute property specifies the date and time at which a page cached on a browser
expires. If the user returns to the same page before that date and time, the cached version is displayed. If
a time is not specified, the page expires at midnight of that day. If a date is not specified, the page expires
at the given time on the day that the script is run.
Syntax
Response.ExpiresAbsolute [= [date] [time]]
Parameters
date
Specifies the date on which the page will expire. The value sent in the expires header conforms to
the RFC-1123 date format.
time
Specifies the time at which the page will expire. This value is converted to GMT before an Expires
header is sent.
Remarks
If this property is set more than once on a page, the earliest expiration date or time is used.
Example
The following example specifies that the page will expire 15 seconds after 1:30 PM on May 31, 2001.
<% Response.ExpiresAbsolute=#May 31,2001 13:30:15# %>
Applies To
Response Object
See Also
Expires
IsClientConnected

The IsClientConnected property is a read-only property that indicates if the client has disconnected
from the server.
Syntax
Response.IsClientConnected ( )
Remarks
This property allows you greater control over circumstances where the client may have disconnected
from the server. For example, if a long period of time has elapsed between when a client request was
made and when the server responded, it may be beneficial to make sure the client is still connected
before continuing to process the script.
Example
<%
'Check to see if the client is connected.
If Not Response.IsClientConnected Then
'Get the sessionid to send to the shutdown function.
Shutdownid = Session.SessionID
'Perform shutdown processing.
Shutdown(Shutdownid)
End If
%>
Applies To
Response Object
PICS
The PICS property adds a value to the pics-label response header.
Syntax
Response.PICS(PICSLabel)
Parameters
PICSLabel
A string that is a properly formatted PICS label. The value specified by PICSLabel will be
appended to the pics-label response header.
Example

For an .asp file that includes
<%
Response.PICS("(PICS-1.1 <http://www.rsac.org/ratingv01.html> labels on " & chr(34) & "199
%>
the following header would be added:
PICS-label:(PICS-1.1 <http://www.rsac.org/ratingv01.html> labels on "1997.01.05T08:15-0500
Remarks
The PICS property inserts any string in the header, whether or not it represents a valid PICS label.
If a single page contains multiple tags containing Response.PICS, each instance will replace the PICS
label set by the previous one. As a result, the PICS label will be set to the value specified by the last
instance of Response.PICS in the page.
Because PICS labels contain quotes, you must replace each quote with " & chr(34) & ".
Applies To
Response Object
Status
The Status property specifies the value of the status line returned by the server. Status values are defined
in the HTTP specification.
Syntax
Response.Status = StatusDescription
Parameters
StatusDescription
A string that consists of both a three-digit number that indicates a status code and a brief
explanation of that code. For example, 310 Move Permanently.
Remarks
Use this property to modify the status line returned by the server.
Example
The following example sets the response status.

<% Response.Status = "401 Unauthorized" %>
Applies To
Response Object
Response Methods
The Response object has the following methods.
? AddHeader
? AppendToLog
? BinaryWrite
? Clear
? End
? Flush
? Redirect
? Write
AddHeader
The AddHeader method adds an HTML header with a specified value. This method always adds a new
HTTP header to the response. It will not replace an existing header of the same name. Once a header
has been added, it cannot be removed.
If another Response method will provide the functionality you require, it is recommended that you use
that method instead.
Syntax
Response.AddHeader name, value
Parameters
name
The name of the new header variable.
value
The initial value stored in the new header variable.
Remarks

To avoid name ambiguity, name should not contain any underscore (_) characters. The
ServerVariables collection interprets underscores as dashes in the header name. For example, the
following script causes the server to search for a header named MY-HEADER.
<% Request.ServerVariables("HTTP_MY_HEADER") %>
Because the HTTP protocol requires that all headers be sent before content, in general you must modify
all outgoing headers before your ASP script generates any output. In IIS 4.0, this meant that you had to
call AddHeader in your script before any output (such as that generated by HTML code or the Write
method) was sent to the client.
However, with IIS 5.0, response buffering (enabled by the metabase property AspBufferingOn) is on
by default. Therefore, you can call the AddHeader method at any point in the script, as long as it
precedes any calls to Flush.
The following .asp file illustrates this point.
<HTML>
Here's some text on your Web page.
<% Response.AddHeader "WARNING", "Error Message Text" %> Here's some more interesting and
<% Response.Flush %>
<% Response.Write("some string") %>
</HTML>
In the preceding example, because the page is buffered by default, the server will not send output to the
client until all the scripts on the ASP page have been processed or until the Flush method is called. With
buffered output, calls to AddHeader can appear anywhere the script, so long as they precede any calls
to Flush. If the call to AddHeader appeared below the call to Flush in the preceding example, the
script would generate a run-time error.
You can use this method to send multiple copies of the same header with different values, as with
WWW-Authenticate headers.
Example
The following example uses the AddHeader method to request that the client use Basic authentication.
<% Response.Addheader "WWW-Authenticate", "BASIC" %>
Note The preceding script merely informs the client browser which authentication to use. If you use this
script in your Web applications, you should ensure that the Web server has Basic authentication enabled.
Applies To
Response Object
See Also
Flush, Write, Buffer

AppendToLog
The AppendToLog method adds a string to the end of the Web server log entry for this request. You
can call it multiple times in one section of script. Each time the method is called it appends the specified
string to the existing entry.
Syntax
Response.AppendToLog string
Parameters
string
The text to append to the log file. Because fields in the log are comma-delimited, this string cannot
contain any comma characters (,).
Remarks
In order for the specified string to be recorded in the log file, you must enable the URI Stem option of
the Extended Properties property sheet for the site whose activity you wish to log.
Example
The following example adds the text "content updated" to the log file.
<% Response.AddToLog "My custom log message" %>
Applies To
Response Object
BinaryWrite
The BinaryWrite method writes the specified information to the current HTTP output without any
character conversion. This method is useful for writing non-string information such as binary data
required by a custom application.
Syntax
Response.BinaryWrite data
Parameters
data
The data to write to the HTTP output. This parameter will be of type VT_ARRAY | VT_UI1,

which is a variant array of unsigned one-byte characters.
Example
If you have an object that generates an array of bytes, you can use the following call to BinaryWrite to
send the bytes to a custom application.
<%
Set objBinaryGen = Server.CreateObject("MyComponents.BinaryGenerator")
vntPicture = objBinaryGen.MakePicture
Response.BinaryWrite vntPicture
%>
Applies To
Response Object
See Also
Write
Clear
The Clear method erases any buffered HTML output. However, the Clear method erases only 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
Applies To
Response Object
See Also
End, Flush
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
%>
Applies To
Response Object
See Also
Buffer, Clear
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.
Applies To
Response Object
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 Microsoft’s primary Web site.
<% Response.Redirect "http://www.microsoft.com" %>
Applies To
Response Object
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%>
Applies To
Response Object
See Also
BinaryWrite
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
Properties
ScriptTimeout The amount of time that a script can run before it times out.
Methods

CreateObject Creates an instance of a server component.

Execute Executes an .asp file.
GetLastError Returns an ASPError object that describes the error condition.
HTMLEncode Applies HTML encoding to the specified 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.
Transfer Sends all of the current state information to another .asp file for
processing.
URLEncode Applies URL encoding rules, including escape characters, to the string.
Server Properties
The Server object has the following property:
? ScriptTimeout
ScriptTimeout
The ScriptTimeout property specifies the maximum amount of time a script can run before it is
terminated.
The timeout will not take effect while a server component is processing.
Syntax
Server.ScriptTimeout = NumSeconds
Parameters
NumSeconds
Specifies the maximum number of seconds that a script can run before the server terminates it. The
default value is 90 seconds.
Remarks
A default ScriptTimeout can be set for a Web service or Web server by using the AspScriptTimeout
property in the metabase. The ScriptTimeout property cannot be set to a value less than that specified

in the metabase. For example, if NumSeconds is set to 10, and the metabase setting contains the default
value of 90 seconds, scripts will time out after 90 seconds. However, if NumSeconds were set to 100,
the scripts would time out after 100 seconds.
For more information about using the metabase, see Using IIS Admin Objects.
Example
The following example causes scripts to time out if the server takes longer than 100 seconds to process
them:
<% Server.ScriptTimeout = 100 %>
The following example retrieves the current value of the ScriptTimeout property and stores it in the
variable TimeOut.
<% TimeOut = Server.ScriptTimeout %>
Applies To
Server Object
See Also
AspScriptTimeout
Server Methods
The Server object has the following methods.
? CreateObject
? Execute
? GetLastError
? HTMLEncode
? MapPath
? Transfer
? URLEncode
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.
For more information about server components, see Building Components for ASP.
Applies To
Server Object

Execute
The Execute method calls an .asp file and processes it as if it were part of the calling ASP script. The
Execute method is similar to a procedure call in many programming languages.
Syntax
Server.Execute( Path )
Parameters
Path
A string specifying the location of the .asp file to execute. If an absolute path is specified for this
parameter then it must be for an .asp file within the same application space.
Remarks
The Server.Execute method provides a way of dividing a complex application into individual modules.
By employing the Server.Execute method, you can develop a library of .asp files that you can call as
needed. This approach is an alternative to server-side includes.
After IIS processes the .asp file specified in the input parameter to Server.Execute, the response is
returned to the calling ASP script. The executed .asp file may modify HTTP headers. However, as with
any .asp file, if the executed .asp file attempts to modify HTTP headers after it sends a response to the
client, it will generate an error.
The path parameter may be for either an absolute or a relative path. If the path is absolute, it must map to
an ASP script in the same application as the calling .asp file.
The path parameter may contain a query string.
If either the calling or called .asp file contains a transaction directive, the status of the transaction will
apply to the .asp file which contains the directive. For example, if ASP1 below calls ASP2 and the
transaction is aborted while ASP2 is being processed, ASP2's OnTransactionAbort (if present) will be
called. After ASP2 completes processing, ASP1's OnTransactionAbort (if present) will be called.
ASP1:
<%@ Transaction=Required%>
<%
Server.Execute ("Page22.asp")
%>
Asp2.asp:
<%@
Transaction=Required

%>
Example
The following example demonstrates executing an .asp file that returns some text. The output from these
two scripts is:
I am going to ASP2
Here I am
ASP1
<HTML><BODY><% Response.Write("I am going to execute ASP2 <BR>")

Server.Execute("/myasps/asp2.asp")
%>
</BODY>
</HTML>
ASP2
<HTML><BODY><% Response.Write("Here I am")%></BODY></HTML>
Applies to
Server Object
See Also
Transfer, OnTransactionAbort, OnTransactionCommit
GetLastError
The GetLastError method returns an ASPError Object describing the error condition that occurred.
This method is available only before the .asp file has sent any content to the client.
Syntax
Server.GetLastError ()
Remarks
If a 500;100 custom error has been defined for an ASP application, it may refer to an .asp file. In this
case, when an error occurs during the running of an .asp file within the application, the server will
automatically transfer to this ASP page via the Server.Transfer method. All of the state information

from the executing ASP application will be available to the .asp file that is handling the error. In addition,
the ASPError Object will be available, so you can expose the properties of the error through the .asp
file that you set up to handle the error.
The default Web site is configured to use the file \iishelp\common\500-100.asp. You can either use this
file for processing ASP errors, or create your own. If you want to change the .asp file for processing the
500;100 custom errors you can use the Internet Information Services snap-in.
Note A 500;100 custom error will be generated if IIS encounters an error while processing either
an .asp file or the application's Global.asa file.
Example
The following three examples demonstrate different sorts of errors that will generate a 500;100 custom
error. The three types of errors are:
? Pre-processing errors
? Script compiling errors
? Run-time errors
The first example demonstrates a pre-processing error, which IIS will generate when it tries to include
the file. This error will be generated because the include statement is missing the file parameter for the
include statement. The second example demonstrates a script compiling error. The scripting engine will
not compile this script because it is missing the keyword "next" in a For...Next loop. The third example
demonstrates a run-time error that will be caught because the script attempts to divide by 0.
Example 1


<%
response.write "hello"
%>
Example 2
<%
dim I
for i=1 to 1
nxt
%>
Example 3
<%
dim i,j
dim sum
sum=0
j=0
for i=1 to 10
sum=sum+1
next
sum=sum/j
%>

Applies To
Server Object
See Also
ASPError Object
HTMLEncode
The HTMLEncode method applies HTML encoding to a specified string.
Syntax
Server.HTMLEncode( string )
Parameters
string
Specifies the string to encode.
Example
<%= Server.HTMLEncode("The paragraph tag: <P>") %>
produces the output
The paragraph tag: <P>
Note The preceding output will be displayed by a Web browser as
The paragraph tag: <P>
If you view source, or open the page as a text file, you will be able to see the encoded HTML.
Applies To
Server Object
See Also
URLEncode

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.
<%= 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>
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>
c:\inetpub\wwwroot<BR>
c:\inetpub\wwwroot<BR>
Applies To
Server Object
See Also
AspEnableParentPaths
Transfer
The transfer method sends all of the information that has been assembled for processing by one .asp

file, to a second .asp file.
Syntax
Server.Transfer (path)
Parameters
Path
The location of the .asp file to which control should be transferred.
Remarks
When you call Server.Transfer the state information for all the built-in objects will be included in the
transfer. This means that any variables or objects that have been assigned a value in the current page,
during the current session, or within the current application-state, will be maintained. In addition, all of the
current contents for the request collections will be available to the .asp file receiving the transfer.
If the path you specify in the input parameter is for an .asp file in another application, the .asp file will
execute as if it were in the application that contains the Server.Transfer command. In other words, all
variables and objects that have been given application scope either by other .asp files in the application
or by the application's Global.asa file will be available to the called .asp file.
Example
The following example demonstrates transferring from one .asp file to another .asp file, and sending the
session identifier to the client.
The output from these scripts will be:
A session ID
I am going to ASP2
The same session ID
ASP1
<HTML><BODY><% Dim sessvar1 Response.Write Session.SessionID

Response.Write ("<BR>")
Response.Write("I am going to ASP2 <BR>")
Server.Transfer("/Myasps/ASP2.asp")
%>
ASP2
<HTML>
<BODY><% Response.Write Session.SessionID %></BODY></HTML>
Applies To

Server Object
See Also
Execute, Global.asa Reference, Application Object
URLEncode
The URLEncode method applies URL encoding rules, including escape characters, to a specified string.
Syntax
Server.URLEncode( string )
Parameters
string
Specifies the string to encode.
Example
<%Response.Write(Server.URLEncode("http://www.microsoft.com")) %>
produces the output
http%3A%2F%2Fwww%2Emicrosoft%2Ecom
Applies To
Server Object
See Also
HTMLEncode
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
Collections
Contents Contains the items that you have added to the session with script
commands.
StaticObjects Contains the objects created with the <OBJECT> tag and given session
scope.
Properties
CodePage The code page that will be used for symbol mapping.
LCID The locale identifier.
SessionID Returns the session identification for this user.
Timeout The timeout period for the session state for this application, in minutes.
Methods
Abandon This method destroys a Session object and releases its resources.
Contents.Remove This method deletes an item from the Contents collection.
Contents.RemoveAll This method deletes all items from the Contents collection.
Events
Scripts for the following events are declared in the Global.asa file.
Session_OnEnd
Session_OnStart
For more information about these events and the Global.asa file, see the Global.asa Reference.

Remarks
You can store values in the Session object. Information stored in the Session object is available
throughout the session and has session scope. The following script demonstrates storage of two types of
variables.
<%
Session("username") = "Janine"
Session("age") = 24
%>
However, if you store an object in the Session object and use VBScript as your primary scripting
language, you must use the Set keyword. This is illustrated in the following script.
<% Set Session("Obj1") = Server.CreateObject("MyComponent.class1") %>
You can then call the methods and properties exposed by MyComponent.class1 on subsequent Web
pages, by using the following.
<% Session("Obj1").MyMethod %>
Or by extracting a local copy of the object and using the following.
<%
Set MyLocalObj1 = Session("Obj1")
MyLocalObj1.MyObjMethod
%>
Another way to create objects with session scope is to use the <OBJECT> tags in the Global.asa file.
You cannot, however, store a built-in object in a Session object. For example, each of the following
lines would return an error.
<%
Set Session("var1") = Session
Set Session("var2") = Request
Set Session("var3") = Response
Set Session("var4") = Server
Set Session("var5") = Application
%>
Before you store an object in the Session object, you should know what threading model it uses. Only
objects marked as both can be stored in the Session object without locking the session to a single
thread.
If you store an array in a Session object, you should not attempt to alter the elements of the stored array
directly. For example, the following script will not work:
<% Session("StoredArray")(3) = "new value" %>

This is because the Session object is implemented as a collection. The array element StoredArray(3)
does not receive the new value. Instead, the value is indexed into the collection, overwriting any
information stored at that location.
It is strongly recommended that if you store an array in the Session object, you retrieve a copy of the
array before retrieving or changing any of the elements of the array. When you are done with the array,
you should store the array in the Session object again so that any changes you made are saved. This is
demonstrated in the following example:
---file1.asp---
<%
'Creating and initializing the array
Dim MyArray()
Redim MyArray(5)
MyArray(0) = "hello"
MyArray(1) = "some other string"
'Storing the array in the Session object.

Session("StoredArray") = MyArray
Response.Redirect("file2.asp")
%>
---file2.asp---
<%
'Retrieving the array from the Session Object
'and modifying its second element.
LocalArray = Session("StoredArray")
LocalArray(1) = " there"
'Printing out the string "hello there."

Response.Write(LocalArray(0)&LocalArray(1))
'Re-storing the array in the Session object.

'This overwrites the values in StoredArray with the new values.
Session("StoredArray") = LocalArray
%>
Example
The following code assigns the string MyName to a session variable called name, assigns a value to a
session variable called year, and assigns an instance of the some.Obj component to a variable called
myObj.
Session("name") = "MyName"
Session("year") = 96
Set Session("myObj") = Server.CreateObject("someObj")
%>
For more information, see Managing Sessions.

Session Collections
The Session Object supports the following collections:
? Contents
? StaticObjects
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
<%@ 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
%>
Session StaticObjects Collection
The StaticObjects collection contains all of the objects created with the <OBJECT> tag within the
scope of the session object. The collection can be used to determine the value of a specific property for
an object, or to iterate through the collection and retrieve all properties for all objects.
Syntax
Session.StaticObjects( Key )
Parameters
Key
The property to retrieve.
Remarks
You can use an iterating control structure to loop through the keys of the StaticObjects collection. This
is demonstrated in the following example.
<%
Dim objProp
For Each objProp in Session.StaticObjects
If IsObject(Session.StaticObjects(objProp)) Then
Response.write(objProp & " : Session object cannot be displayed."&_
"<BR>")
Else
Response.write(objprop & " : " & Session.StaticObjects(objprop) &_
"<BR>")
End if
Next
%>

Session Properties
The Session object has the following properties.
? CodePage
? LCID
? SessionID
? Timeout
CodePage
The CodePage property determines the code page that will be used to display dynamic content.
Syntax
Session.CodePage(=Codepage)
Parameters
Codepage
An unsigned integer that represents a valid code page for the system that is running the scripting
engine.
Remarks
A code page is a character set that can include numbers, punctuation marks, and other glyphs. Different
languages and locales may use different code pages. For example, ANSI code page 1252 is used for
American English and most European languages; OEM code page 932 is used for Japanese Kanji.
A code page can be represented in a table as a mapping of characters to single-byte values or multibyte
values. Many code pages share the ASCII character set for characters in the range 0x00 – 0x7F.
Applies To
Session Object
LCID
The LCID property determines the location identifier that will be used to display dynamic content.

Syntax
Session.LCID(=LCID)
Parameters
LCID
A valid locale identifier.
Remarks
An LCID specifies the locale identifier, which is a standard international abbreviation that uniquely
identifies one of the system-defined locales. If an LCID has been set using the @LCID directive
Session.LCID will override the value set by the directive.
Example
The following example demonstrates setting the locale to British English and using the VBScript
FormatCurrency method to display the value 125 as currency with the £ symbol:
<%
Session.LCID = 2057
Dim curNumb
curNumb = FormatCurrency(125)
Response.Write (curNumb)
%>
Applies To
Session Object
For more information, see Accommodating International Clients and Locale Identifiers.
SessionID
The SessionID property returns the session identifier, 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

Remarks
You should not use the SessionID property to generate primary key values for a database application.
This is because if the Web server is restarted, some SessionID values may be the same as those
generated before the server was stopped. Instead, you should use an auto-increment column data type,
such as IDENTITY with Microsoft® SQL Server, or COUNTER with Microsoft ® Access.
Applies To
Session Object
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.
Applies To
Session Object
See Also
Abandon
Session Methods
The Session object exposes the following methods.
? Abandon
? Contents.Remove

? Content.RemoveAll
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 %>
Applies To
Session Object

See Also
Timeout
Contents.Remove
The Remove method deletes a specific item from the Session object's Contents collection.
Syntax
Session.Contents.Remove( Item|Index )
Parameter
Item
The name of the member to remove from the collection.
Index
The index entry for the member to remove from the collection.
Remarks
The Contents.Remove method takes either a string or an integer as an input parameter. If the input
parameter is a string, the method will search the contents collection for an item with that name and
remove it. If the input parameter is an integer, the method counts that number of items from the start of
the collection, and removes the corresponding item.
Example
The following example adds and removes a variable called myName to the Session.Contents
collection.
<%
Session("myName") = " "
Session.Collection.Remove("myName")
%>
Applies To
Session Object
See Also
Session.Contents.RemoveAll
Contents.RemoveAll

The RemoveAll method deletes all items that have been added to the Session object's Contents
collection.
Syntax
Session.Contents.RemoveAll ()
Example
The following example removes all items that have been added to the Session.contents collection:
<%Session.Contents.RemoveAll()%>
Applies To
Session Object
See Also
Session.Contents.Remove
Installable Components for ASP

You can create dynamic, interactive Web pages by using the server components included with Active
Server Pages (ASP) in your scripts. This reference section contains information about and examples of
these components.
Ad Rotator Creates an AdRotator object that automatically rotates

advertisements displayed on a page according to a specified
schedule.
Browser Capabilities Creates a BrowserType object that determines the capabilities,
type, and version of each browser that accesses your Web site.
Content Linking Creates a NextLink object that creates tables of contents for
Web pages, and links them together sequentially like pages in a
book.
Content Rotator Automates the rotation of HTML content strings on a Web
page.
Counters Creates a Counters object that can create, store, increment,
and retrieve any number of individual counters.

Database Access Provides access to databases using ActiveX® Data Objects

(ADO).
File Access Component Provides access to file input and output.
Logging Utility Allows you to read the HTTP activity log files that IIS generates.
MyInfo Creates a MyInfo object that keeps track of personal
information, such as the site administrator's name, address, and
display choices.
Page Counter Counts and displays the number of times a Web page has been
opened.
Permission Checker Uses the password authentication protocols provided in
Microsoft® Internet Information Services (IIS) to determine
whether a Web user has been granted permissions to read a file.
Status Creates a Status object that has properties that contain server
status information. Currently, this server status is only available
on Personal Web Server for Macintosh.
Tools Creates a Tools object that provides utilities that enable you to
easily add sophisticated functionality to your Web pages.
For information on server scripting with ASP, see Developing Web Applications. For more information
on the built-in objects supplied with the ASP, see Visual Basic Object Model.
Note The examples in this reference use Microsoft® Visual Basic® Scripting Edition (VBScript) as the
primary scripting language. However, ASP scripts can be written in any supported scripting language.
For information on how to change the primary scripting language, see Working with Scripting Languages.
Ad Rotator Component
The Ad Rotator component creates an Ad Rotator object that automates the rotation of advertisement
images on a Web page. Each time a user opens or reloads the Web page, the Ad Rotator component
displays a new advertisement based on the information you specify in a Rotator Schedule File.
You can record how many users click each advertisement by setting the URL parameter in the Rotator
Schedule file to direct users to the Redirection File. When you specify this parameter, each jump to an
advertiser's URL is recorded in the Web server activity logs.
File Names

Adrot.dll The Ad Rotator component.

Rotator Schedule File A text file that contains the display schedule and file information for
advertisements. This file must be available on a Web server virtual path.
Redirection File An optional file that implements redirection and enables the Ad Rotator
component to record how many users click on each advertisement.
Syntax
Set AdRotator = Server.CreateObject( "MSWC.AdRotator" )
Parameters
AdRotator
Specifies the name of the AdRotator object created by the call to Server.CreateObject.
Properties
Border Specifies the size of the border around the

advertisement.
Clickable Specifies whether the advertisement is a hyperlink.
TargetFrame Specifies the name of the frame in which to display
the advertisement.
Methods
GetAdvertisement Gets the specifications for the next scheduled

advertisement from the data file and formats it as
HTML.
Example
The following example displays a different advertisement each time a user views the Web page.
<% Set ad = Server.CreateObject("MSWC.AdRotator") %>
<%= ad.GetAdvertisement("/ads/adrot.txt") %>
The following HTML is generated by the GetAdvertisement method and is added to the page's output,
displaying the next advertisement in the Rotator Schedule file.
<A HREF="http://www.msn.com/isapi/adredir.asp?http://www.company.com/">
<IMG SRC="http://msnnt3web/ads/homepage/chlogolg.gif"
ALT="Check out the new Technology Center"
WIDTH=440 HEIGHT=60 BORDER=1></A>

Rotator Schedule File

The Rotator Schedule file contains information that the Ad Rotator component uses to manage and
display the various advertisement images. In it you can specify the details for the advertisements, such as
the size of the advertisement space, the image files to use, and the percentage of time that each file should
be displayed.
The Rotator Schedule file has two sections. The first section sets parameters that apply to all
advertisement images in the rotation schedule. The second section specifies file and location information
for each individual advertisement and the percentage of display time that each advertisement should
receive. The two sections are separated by a line containing only an asterisk (*).
In the first section there are four global parameters, each consisting of a keyword and a value. All are
optional. If you do not specify values for the global parameters, the Ad Rotator uses default values. In
this case, the first line of the file must contain only an asterisk (*).
Syntax
[REDIRECT URL]
[WIDTH numWidth]
[HEIGHT numHeight]
[BORDER numBorder]
adURL
adHomePageURL
Text
impressions
Parameters
URL
Specifies the path to the dynamic-link library (.dll) or application (.asp) file that implements
redirection. This path can be specified either fully (http://MyServer/MyDir/redirect.asp) or relative
to the virtual directory (/MyDir/redirect.asp).
numWidth
Specifies the width of the advertisement on the page, in pixels. The default is 440 pixels.
numHeight
Specifies the height of the advertisement on the page, in pixels. The default is 60 pixels.

numBorder
Specifies the thickness of the hyperlink border around the advertisement, in pixels. The default is a
1-pixel border. Set this parameter to 0 for no border.
adURL
The location of the advertisement image file.
adHomePageURL
The location of the advertiser's home page. If the advertiser does not have a home page, put a
hyphen (-) on this line to indicate that there is no link for this ad.
Text
Alternate text that is displayed if the browser does not support graphics, or has its graphics
capabilities turned off.
impressions
A number between 0 and 10000 that indicates the relative weight of the advertisement.
For example, if a Rotator Schedule file contains three ads with impressions set to 2, 3, and 5, the
first advertisement is displayed 20 percent of the time, the second 30 percent of the time, and the
third 50 percent of the time.
Remarks
If the sum of the impressions parameters for all items exceeds 10000, an error will be generated the first
time the Rotator Schedule file is accessed by a call to the GetAdvertisement method.
Example
The following script demonstrates how you can use a rotator schedule file to display a variety of
advertisements and how to include a redirection file.
---Adrot.txt---
REDIRECT /scripts/adredir.asp
WIDTH 440
HEIGHT 60
BORDER 1
*
http://kabaweb/ads/homepage/chlogolg.gif
http://www.bytecomp.com/
Check out the ByteComp Technology Center
20
http://kabaweb/ads/homepage/gamichlg.gif
-
Sponsored by Flyteworks
20
http://kabaweb/ads/homepage/ismodemlg.gif
http:// www.proelectron.com/
28.8 internal PC modem, only $99
80
http://kabaweb/ads/homepage/spranklg.gif
http://www.clocktower.com/
The #1 Sports site on the net
10
Redirection File

The Redirection file is a file that you create. It usually includes script to parse the query string sent by the
AdRotator object and to redirect the user to the URL associated with the advertisement that the user
clicked on.
You can also include script in the Redirection file to count the number of users that have clicked on a
particular advertisement, and save this information to a file on the server.
Example
The following example redirects the user to the advertiser's home page.
---Adredir.asp---
<% Response.Redirect(Request.QueryString("url")) %>
Ad Rotator Properties
The AdRotator object has the following properties:
Border Specifies the size of the border around the

advertisement.
Clickable Specifies whether the advertisement is a hyperlink.
TargetFrame Specifies the name of the frame in which to display
the advertisement.
Border
The Border property enables you to specify whether to display the advertisements with a surrounding
border.
Syntax
Border = size
Parameters
size
Specifies the thickness of the border that surrounds the displayed advertisement. The default is the
value set in the header of Rotator Schedule file.

Example
The following example displays the advertisements without a border.
<%
Set ad = Server.CreateObject("MSWC.AdRotator")
ad.Border = 0
%>
See Also
Clickable, TargetFrame
Clickable
The Clickable property enables you to specify whether the advertisements are displayed as hyperlinks.
Syntax
Clickable = value
Parameters
value
Specifies whether the advertisement should be a hyperlink. This parameter can be one of the
following values. The default value is TRUE.
Value Description
TRUE Display the advertisements as hyperlinks.
FALSE Do not display the advertisements as hyperlinks.
Example
The following example displays the advertisements as images only, not as hyperlinks.
<%
ad.Clickable = FALSE
%>
See Also
Border, TargetFrame

TargetFrame
The TargetFrame property specifies the target frame into which the link should be loaded. This
property fulfills the same function as the TARGET parameter in an HTML anchor statement.
Syntax
TargetFrame = frame
Parameters
frame
Specifies the name of the frame in which to display the advertisement. This parameter can also be
one of the HTML frame-keywords, such as _TOP, _NEW, _CHILD, _SELF, _PARENT, or
_BLANK. The default value is NO FRAME.
Example
The following example displays the advertisements in the frame AdFrame.
<%
ad.TargetFrame = AdFrame
%>
See Also
Border, Clickable
Ad Rotator Methods
The AdRotator object has the following method:
GetAdvertisement Gets the specifications for the next scheduled

advertisement from the data file and formats it as
HTML.
GetAdvertisement

The GetAdvertisement method retrieves the next advertisement from the Rotator Schedule file. Each
time the script is run, such as when a user opens or refreshes a page, the method retrieves the next
scheduled advertisement.
Syntax
GetAdvertisement( rotationSchedulePath )
Parameters
rotationSchedulePath
Specifies the location of the Rotator Schedule file relative to the virtual directory. For example, if
the physical path was C:\Inetpub\Wwwroot\Ads\Adrot.txt (where Wwwroot is the "/" virtual
directory) you would specify the path \Ads\Adrot.txt.
Return Values
Returns HTML that displays the advertisement in the current page.
Example
The following example gets an advertisement from the Adrot.txt file in the /Ads/ virtual directory.
<% Set NextAd = Server.CreateObject("MSWC.AdRotator") %>

<%= NextAd.GetAdvertisement("/ads/adrot.txt") %>
Browser Capabilities Component

The Browser Capabilities component creates a BrowserType object that provides your scripts with a
description of the capabilities of the client's Web browser.
When a browser connects to the Web server, it automatically sends an HTTP User Agent header. This
header is an ASCII string that identifies the browser and its version number. The BrowserType object
compares the header to entries in the Browscap.ini file.
If it finds a match, the BrowserType object assumes the properties of the browser listing that matched
the User Agent header.
If the object does not find a match for the header in the Browscap.ini file, it searches for the closest
match using the * and ? wildcards. If a match can not be found using wildcards, the object will use the
default browser settings if they have been specified in the Browscap.ini file. If the object does not find a
match and default browser settings have not been specified in the Browscap.ini file, the object sets every
property to the string "UNKNOWN."

You can add properties or new browser definitions to this component simply by updating the
Browscap.ini file.
File Names
Browscap.dll The Browser Capabilities component.

Browscap.ini A text file that maps browser capabilities to the HTTP User Agent
header. This file must be in the same directory as Browscap.dll.
Syntax
Set BrowserType = Server.CreateObject("MSWC.BrowserType")
Parameters
BrowserType
Specifies the name of the BrowserType object created by the call to Server.CreateObject.
Example
The following example uses the BrowserType object to display a table showing some of the capabilities
of the current browser.
<% Set bc = Server.CreateObject("MSWC.BrowserType") %>

<TABLE BORDER=1>
<TR><TD>Browser</TD><TD> <%= bc.browser %>
<TR><TD>Version</TD><TD> <%= bc.version %> </TD></TR>
<TR><TD>Frames</TD><TD>
<% if (bc.frames = TRUE) then %> TRUE
<% else %> FALSE
<% end if %> </td></TR>
<TR><TD>Tables</TD><TD>
<% if (bc.tables = TRUE) then %> TRUE
<% else %> FALSE
<% end if %> </TD></TR>
<TR><TD>BackgroundSounds</TD><TD>
<% if (bc.BackgroundSounds = TRUE) then %> TRUE
<% else %> FALSE
<% end if %> </TD></TR>
<TR><TD>VBScript</TD><TD>
<% if (bc.vbscript = TRUE) then %> TRUE
<% else %> FALSE
<% end if %> </TD></TR>
<TR><TD>JScript</TD><TD>
<% if (bc.javascript = TRUE) then %> TRUE
<% else %> FALSE
<% end if %> </TD></TR>
</TABLE>
Browscap.ini File

You can declare property definitions for any number of browsers in the Browscap.ini file. You can also
set default values to use if the client's browser is not one of the listed definitions.
For each browser definition, you provide an HTTP User Agent header and the properties and values you
wish to associate with that header. For more information on the format of the HTTP User Agent header,
refer to the HTTP specification available at http://www.w3.org.
Syntax
[; comments]
[HTTPUserAgentHeader]
[parent = browserDefinition]
[property1 = value1]
...
[propertyN = valueN]
[Default Browser Capability Settings]
[defaultProperty1 = defaultValue1]
...
[defaultPropertyN = defaultValueN]

Parameters
comments
Any line that starts with a semicolon (;). Comments, which are ignored by the BrowserType
object, can occur anywhere in the Browscap.ini file.
HTTPUserAgentHeader
Specifies the HTTP User Agent header to associate with the browser-property value statements
specified in propertyN. The Browscap.ini file may contain multiple browser definitions, each one
starting with a unique HTTPUserAgentHeader value.
You can use the asterisk (*) character as a wildcard character in the HTTPUserAgentHeader to
replace zero or more characters and the (?) character as a wildcard to replace a single character.
For example, if you specified the following string for HTTPUserAgentHeader:
[Mozilla/4.0 (compatible; MSIE 5.0;* Windows NT)]
It would match all of the following User Agent headers:
[Mozilla/4.0 (compatible; MSIE 5.0; Windows NT)]
[Mozilla/4.0 (compatible; MSIE 5.0; AK; Windows NT)]
[Mozilla/4.0 (compatible; MSIE 5.0; SK; Windows NT)]
Note The BrowserType object first attempts to match exactly the User Agent header to a value of
HTTPUserAgentHeader. If that fails, it attempts to make a match that uses wildcard characters.
If more than one browser definition containing wildcard characters matches the User Agent header, the
BrowserType object returns the properties of the definition which most closely matches the User Agent
header. The closest match is the match which replaces the fewest characters.
browserDefinition
An optional parameter specifying the HTTP User Agent header-string of a browser to use as the
parent browser. The current browser's definition will inherit all of the property values declared in
the parent browser's definition. This helps define properties for a new version of a browser,
because new versions usually retain most of the properties of the previous release. These inherited
property values can be overwritten by explicitly setting a new value for the property by using the
syntax propertyN = valueN.
propertyN
An optional parameter specifying the name of the browser property to set. It must start with an
alphabetic character and cannot be longer than 255 characters. Each browser definition in the
Browscap.ini file can contain as many statements of property values as needed. For example, if
your application only needed to know whether or not a user's browser supported VBScript, you
would only need one property statement for each browser definition.
The following table lists some possible properties:

Property Description
ActiveXControls Specifies whether the browser supports ActiveX® controls.
Backgroundsounds Specifies whether the browser supports background sounds.
Beta Specifies whether the browser is beta software.
Browser Specifies the name of the browser.
Cdf Specifies whether the browser supports the Channel Definition
Format for Webcasting.
Cookies Specifies whether the browser supports cookies.
Frames Specifies whether the browser supports frames.
Javaapplets Specifies whether the browser supports Java applets.
Javascript Specifies whether the browser supports JScript.
Platform Specifies the platform that the browser runs on.
Tables Specifies whether the browser supports tables.
Vbscript Specifies whether the browser supports VBScript.
Version Specifies the version number of the browser.
valueN
An optional parameter specifying the value of propertyN. This value is a string by default. To
specify an integer, prefix the value with a number sign (#). To specify a Boolean value, use TRUE
or FALSE.
defaultPropertyN
An optional parameter specifying the name of the browser property to which to assign a default
value if none of the defined HTTPUserAgentHeader values match the HTTP User Agent header
sent by the browser.
defaultValueN
An optional parameter specifying the value of defaultPropertyN. This value is a string by default.
To specify an integer, prefix the value with a number sign (#). To specify a Boolean value, use
TRUE or FALSE.
Example
In the following example, the parent tag allows the second browser definition to inherit from the first, so
that the Microsoft® Internet Explorer 5.x definition inherits all the properties of Microsoft® Internet
Explorer 5.0 definition (for example, frames=TRUE, tables=TRUE, and cookies=TRUE). It adds
platform-specific information by adding the line, platform=WinNT, and overwrites the version
information in the line, version=4.0.
;;ie 5.0
[IE 5.0]
browser=IE
Version=5.0
majorver=#5

minorver=#0
frames=TRUE
tables=TRUE
cookies=TRUE
backgroundsounds=TRUE
vbscript=TRUE
javascript=TRUE
javaapplets=True
ActiveXControls=TRUE
Win16=False
beta=False
AK=False
SK=False
AOL=False
;;ie 5.x
[Mozilla/4.0 (compatible; MSIE 5.*; Windows NT)]
parent=IE 5.0
version=5.0
minorver=0
platform=WinNT
; Default Browser
[Default Browser Capability Settings]
browser=Default
frames=FALSE
tables=TRUE
cookies=FALSE
backgroundsounds=FALSE
vbscript=FALSE
javascript=FALSE
Retrieving Browser Capabilities from a Cookie

A new way of determining client capabilities was added in IIS 5.0. If the client sends a cookie describing
their capabilities as part of the request, your ASP page can create an instance of the Browser
Capabilities Component that adds the name value pairs specified by the cookie as properties.
For example, if the client sent a cookie that contained a name-value pair of userLanguage=Spanish, the
Browser Capabilities component would add a userLanguage property and set the value for this property
to Spanish.
Important If the METADATAmetatag exists in a file that is requested by the client as a result of a
redirection using the Server.Transfer or Server.Execute methods, the metatag will be ignored by IIS.
METADATA metatags in the file that actually contains the redirect, however, will be processed
normally.
The following example demonstrates using a cookie to determine browser capabilities. Two files are
required:
? Sendcook.htm runs on the client and uses DHTML to determine a list of properties that have been

set on the client.

? Checkcap.asp creates an instance of the Browser Capabilities component and retrieves the
properties from Sendcook.htm.
Sendcook.htm
<HTML XMLNS:IE>
<HEAD>
<STYLE>
IE\:clientcaps {behavior:url(#default#clientcaps)}
</STYLE>
<SCRIPT language="JavaScript">
function stopAllErrors()
{
// No errors should be presented to the user if they occur.
return true;
}
window.onerror = stopAllErrors;
function window.onload ()
{
bcString = "width= " + oClientCaps.width;
bcString += "&height= " + oClientsCaps.height;
bcString += "&bufferDepth= " + oClientCaps.bufferDepth;
bcString += "&colorDepth= " + oClientCaps.colorDepth;
bcString += "&cookies= " + oClientCaps.cookies;
bcString += "&platform= " + oClientCaps.platform;
document.cookie = "BrowsCap= " + bcString;
}
</SCRIPT>
</HEAD>
<BODY>
<IE:clientcaps ID="oClientCaps" />
</BODY>
<HTML>
Checkcap.asp
<HTML>
<BODY>

<% Set myBrowsCap = Server.CreateObject("MSWC.BrowserType") %>
<%
Response.write(width= " +myBrowsCap.width + "<BR>"
Response.write(height= " +myBrowsCap.height + "<BR>"
Response.write(bufferDepth= " +myBrowsCap.bufferDepth + "<BR>"
Response.write(colorDepth= " +myBrowsCap.colorDepth + "<BR>"
Response.write(cookies= " +myBrowsCap.cookies + "<BR>"
Response.write(platform= " +myBrowsCap.platform + "<BR>"
%>
</BODY>
</HTML>
For more information on the design implications for determining browser capabilities, see Client
Capabilities.

Content Linking Component

The Content Linking component creates a Nextlink object that manages a list of URLs so that you can
treat the pages in your Web site like the pages in a book. You can use the Content Linking component to
automatically generate and update tables of contents and navigational links to previous and subsequent
Web pages. This is ideal for applications such as online newspapers and forum message listings.
The Content Linking component references a Content Linking List file that contains the list of the linked
Web pages. This list is stored on the Web server.
File Names
Nextlink.dll The Content Linking component

Content Linking List A text file that contains a list of Web pages in the order in which they
should be displayed. This file must be available on a Web server
virtual path.
Syntax
Set NextLink = Server.CreateObject( "MSWC.NextLink" )
Parameters
NextLink
Specifies the name of the object created by the call to Server.CreateObject.
Methods
GetListCount Counts the number of items linked in the Content Linking List file.
GetListIndex Gets the index of the current page in the Content Linking List file.
GetNextDescription Gets the description of the next page listed in the Content Linking
List file.
GetNextURL Gets the URL of the next page listed in the Content Linking List
file.
GetNthDescription Gets the description of the Nth page listed in the Content Linking
List file.
GetNthURL Gets the URL of the Nth page listed in the Content Linking List
file.
GetPreviousDescription Gets the description line of the previous page listed in the Content
Linking List file.

GetPreviousURL Gets the URL of the previous pages listed in the Content Linking
List file.
Example
The following example builds a table of contents.
<OL>
<%
Set NextLink = Server.CreateObject ("MSWC.NextLink")
count = NextLink.GetListCount ("/data/nextlink.txt")
I = 1
%>
<UL>
<% Do While (I <= count) %>
<LI><A HREF=" <%= NextLink.GetNthURL ("/data/nextlink.txt", I) %> ">
<%= NextLink.GetNthDescription ("/data/nextlink.txt", I) %> </A>
<%
I = (I + 1)
Loop
%>
</UL>
</OL>
The following script adds the next-page and previous-page buttons to an HTML file.
<%
Set NextLink = Server.CreateObject ("MSWC.NextLink")
If (NextLink.GetListIndex ("/data/nextlink.txt") > 1)
Then
%>
<A HREF=" <%= NextLink.GetPreviousURL ("/data/nextlink.txt") %> ">
Previous Page</A>
<% End If %>
<A HREF=" <%= NextLink.GetNextURL ("/data/nextlink.txt") %> ">Next Page</A>
Content Linking List File

The Content Linking List file contains one line of text for each URL in the list. Each line ends in a carriage
return and each item on a line is separated by a TAB character.
Syntax
Web-page-URL [ text-description [ comment]]

Values
Web-page-URL
The virtual or relative URL of the Web page in the format filename or directory\filename.
Absolute URLs, those that start with "http:", "//", or "\\", are not supported and will not be
processed by methods such as GetNextURL and GetListIndex. When building your content
path, you should ensure that no collisions or infinite loops can occur.
text-description
A value containing text that describes Web-page-URL.
comment
Explanatory text that is not processed by the component.
Example
The following text file creates a list of URLs that can be used by the Content Linking component.
---Nextlink.TXT---
Story1.htm Highlights From the Hockey Playoffs
Story2.htm Congress Passes New Welfare Initiative
Story3.htm Cider Recipes to Warm Long Winter Nights
Story4.htm Winter Storm to bring more snow to East
Story5.htm Reducing Stress on the Job
Sain.htm Return to the table of contents
Content Linking Methods

The NextLink object has the following methods:
? GetListCount
? GetListIndex
? GetNextDescription
? GetNextURL
? GetNthDescription
? GetNthURL
? GetPreviousDescription
? GetPreviousURL
GetListCount
The GetListCount method retrieves the total number of Web pages listed in the Content Linking List
file.
Syntax

GetListCount( listURL )
Parameters
listURL
The location of the Content Linking List file.
Return Values
This method returns an integer.
See Also
GetListIndex
GetListIndex
The GetListIndex method retrieves the index number of the current item in the Content Linking List file.
Syntax
GetListIndex( listURL )
Parameters
listURL
Return Values
The GetListIndex method returns an integer index value specifying the current page's position on the file
list. The index number of the first item is 1. The method returns 0 if the current page is not in the Content
Linking List file.
See Also
GetListCount
GetNextDescription
The GetNextDescription method retrieves the text description of the next item in the Content Linking

List file.
Syntax
GetNextDescription( listURL )
Parameters
listURL
Return Values
The GetNextDescription method returns an ASCII string describing the next item in the Content
Linking List file. If the current page is not found in the list file, GetNextDescription returns the string
description of the last page on the list.
See Also
GetNextURL, GetPreviousDescription, GetNthDescription
GetNextURL
The GetNextURL method retrieves the URL of the next item in the Content Linking List file.
Syntax
GetNextURL( listURL )
Parameters
listURL
Return Values
This method returns the URL of the next page specified in the Content Linking List file. If the current
page is not specified in the Content Linking List file, GetNextURL returns the URL of the last page on
the list.
Example
The following example uses the GetNextURL method to embed a link to the next page in the Content
Linking List file. The advantage of using GetNextURL is that when you change the order or number of
the content pages, you only have to update the list in Content Linking List file and do not need to update
the navigational links on each page.

<% Set NextLink = Server.CreateObject ("MSWC.NextLink") %>
<A HREF="<%= NextLink.GetNextURL ("/data/nextlink.txt") %>">Next Page </A>
See Also
GetPreviousURL, GetNthURL, GetNextDescription
GetNthDescription
The GetNthDescription method retrieves a text description of the Nth item in the Content Linking List
file.
Syntax
GetNthDescription( listURL, i )
Parameters
listURL
i
The index number of an item in the Content Linking List file.
Return Values
This method returns a string.
See Also
GetNextDescription, GetPreviousDescription, GetNthURL
GetNthURL
The GetNthURL method returns the URL of the Nth item in the Content Linking List file.
Syntax
GetNthURL( listURL, i )
Parameters

listURL
i
The index number of an item in the Content Linking List file.
Return Values
This method returns a string.
See Also
GetNextURL, GetPreviousURL, GetNthDescription
GetPreviousDescription
The GetPreviousDescription method retrieves a text description of the previous item in the Content
Linking List file.
Syntax
GetPreviousDescription( listURL )
Parameters
listURL
Return Values
This method returns a string describing either the previous item in the Content Linking List file or, if the
current page is not in the file, the first item on the list.
See Also
GetNextDescription, GetNthDescription, GetPreviousURL
GetPreviousURL
The GetPreviousURL method returns the URL of the previous item in the Content Linking List file.
Syntax
GetPreviousURL( listURL )

Parameters
listURL
Return Values
This method returns a string containing the URL of the previous item in the Content Linking List file. If the
current page is not specified in the Content Linking List file, GetPreviousURL returns the URL of the
first page in the file.
See Also
GetNextURL, GetNthURL, GetPreviousDescription
Content Rotator Component

The Content Rotator component creates a ContentRotator object that automatically rotates HTML
content strings on a Web page. Each time a user requests the Web page, the object displays a new
HTML content string based upon information that you specify in a Content Schedule File.
Because the content strings can contain HTML tags, you can display any type of content that HTML can
represent: text, images, or hyperlinks. For example, you can use this component to rotate through a list of
daily quotations or hyperlinks, or to change text and background colors each time the Web page is
opened.
The following files are used by the Content Rotator component:
File Name Description

Controt.dll The Content Rotator component.
Content Schedule File A text file that contains the display schedule and
file information for Web content. This file must
be available on a Web server virtual path.
Syntax
Set oVar = Server.CreateObject( "MSWC.ContentRotator" )
Parameters
oVar

Specifies the name of the ContentRotator object created by the call to Server.CreateObject.
Methods
ChooseContent Retrieves and displays a content string.

GetAllContent Retrieves and displays all the content strings in the
Content Schedule file.
Remarks
Because the ContentRotator object uses a random generator to select which of the weighted content
strings is displayed, a string may be repeated. This is most likely to occur if there are few entries in the
Content Schedule file, or if one entry is weighted much higher than the others.
Example
The following example displays a different tip of the day each time a user views the Web page.
<%
Set Tip = Server.CreateObject("MSWC.ContentRotator")
Tip.ChooseContent("/tips/tiprot.txt")
%>
Content Schedule File

The Content Schedule file contains information that the ContentRotator object uses to manage and
display the specified content.
In this file you include any number of HTML content string entries. Each entry consists of two parts: a
line that begins with double percentage signs (%%) and contains both the relative weight and any
comments, and a second part that contains the HTML content string itself.
Syntax
%% [#Weight] [//Comments]
ContentString
Parameters
Weight
This optional parameter specifies a number between 0 and 10000 that indicates the relative weight
of the HTML content string. The probability of a particular content string being displayed by the
ContentRotator object can be expressed as the Weight of that content string divided by the sum
of Weight values for all entries in the Content Schedule file.

For example, if a Content Schedule file contained three content strings with respective weights of
1, 3, and 4, the Content Rotator displays the first content string one-eighth of the time, the second
string three-eighths of the time, and the third string half of the time.
A Weight of 0 will cause a content entry to be ignored.
If Weight is not specified, the default value is 1.
If the sum of all weight values exceeds 10000, an error will be generated when the schedule file is
accessed by a call to either the GetAllContent or ChooseContent methods.
Comments
This optional parameter contains comments about the entry. These comments are for development
use only and are not displayed to the user. If you require more than one line of comments, you
must start each additional comment line with a line delimiter (%%) followed by a comment
delimiter (//).
ContentString
The HTML content that the ContentRotator object displays. For example, you can present a
line of text, an image, or a sound.
ContentString may include one or more lines. The ContentRotator object treats everything
between blocks of double percent signs (%%) as a single HTML content string.
Example
The following is an example of a Content Schedule file. Note that because the content strings can contain
HTML tags, you can display any type of content that can be represented with HTML, including text,
images, and hyperlinks.
-------------Content.txt--------------------
%% // Because no value is set for Weight, the default value is 1.
Don't run with scissors.
%% #2 // Content can be more that one line long.

%% // Additional line of comments.
%% // Yet another line of comments.
<FONT FACE="ARIAL,HELVETICA" SIZE="2">
Let a
<H1>smile</H1>
be your umbrella.
</FONT>
%% #3 // This is our favorite image, so show it most often.

<IMG SRC="/images/happy.gif">
%%
Here's the <A HREF="secret.asp">secret link.</A>
ChooseContent

The ChooseContent method retrieves an HTML content string from the Content Schedule file and
displays it on the current page. The method retrieves a new content string each time the script is run, such
as when a user opens or reloads a page.
Syntax
ChooseContent( content-schedule-path )
Parameters
content-schedule-path
Specifies the location of the Content Schedule file.
This parameter can be specified either as a relative or virtual path. For example, if the Content
Schedule file, Content.txt, and the .asp file that called ChooseContent both resided in the
directory /MyApp/Tips/, where MyApp is a virtual directory on the server, then either the full
virtual path (/MyApp/Tips/Content.txt) or the relative path (Content.txt) could be specified for
content-schedule-path.
The ContentRotator object calls the Server.MapPath method to map the specified path to a
physical directory. For more information, see the Server Object reference pages.
Return Value
Returns an HTML content string from the Content Schedule file.
Remarks
Because the ContentRotator object uses a random generator to select which of the weighted content
strings is displayed, a string may be repeated. This is most likely to occur if there are few entries in the
Content Schedule file, or if one entry is weighted much higher than the others.
Example
The following example gets a new tip from the content.txt file in the /Tips/ virtual directory.
<%
Set NextTip = Server.CreateObject("MSWC.ContentRotator")
NextTip.ChooseContent("/Tips/Content.txt")
%>
GetAllContent
The GetAllContent method retrieves all of the HTML content strings from the Content Schedule file
and writes them directly to the Web page as a list with an <HR> tag after each entry.

This method is typically used during authoring, to proofread the Content Schedule file.
Syntax
GetAllContent( content-schedule-path )
Parameters
content-schedule-path
Specifies the location of the Content Schedule file.
This parameter can be specified either as a relative or virtual path. For example, if the Content
Schedule file, content.txt, and the .asp file that called GetAllContent both resided in the
directory /MyApp/Tips/, where MyApp is a virtual root on the server, then either the full virtual
path (/MyApp/Tips/content.txt) or the relative path (content.txt) could be specified for content-
schedule-path.
The ContentRotator object calls the Server.MapPath method to map the specified path to a
physical directory. For more information, see the Server Object Reference pages.
Return Values
None.
Remarks
The Content Rotator component uses the Response.Write method to write output directly to the .asp
page that called the GetAllContent method. For more information, see the Response Object reference
page.
Example
The following example uses the GetAllContent method to display all of the entries in the Content
Schedule file.
<H1>Tips Stored in the Content Schedule File:</H1>

<%
Set Tips = Server.CreateObject("MSWC.ContentRotator")
Tips.GetAllContent("/Tips/Content.txt")
%>
The preceding example produces HTML output such as the following:
<H1>Tips Stored in the Content Schedule File:</H1>

<HR>
Don't run with scissors.

<HR>
<FONT FACE="ARIAL,HELVETICA" SIZE="2">

Let a

<H1>smile</H1>
be your umbrella.
</FONT>
<HR>
<IMG SRC="/images/happy.gif">
<HR>
Here's the <A HREF="secret.asp">secret link.</A>

<HR>
Counters Component
The Counter component creates a Counters object that can create, store, increment, and retrieve any
number of individual counters.
A counter is a persistent value that contains an integer. You can manipulate a counter with the Get,
Increment, Set, and Remove methods of the Counters object. Once you create the counter, it
persists until you remove it.
Counters do not automatically increment on an event like a page hit. You must manually set or increment
counters using the Set and Increment methods.
Counters are not limited in scope. Once you create a counter, any page on your site can retrieve or
manipulate its value. For example, if you increment and display a counter named hits in a page called
Page1.asp, and you increment hits in another page called Page2.asp, both pages will increment the same
counter. If you hit Page1.asp, and increment hits to 34, hitting Page2.asp will increment hits to 35. The
next time you hit Page1.asp, hits will increment to 36.
All counters are stored in a single text file, Counters.txt, which is located in the same directory as the
ounters.dll file.
File Name Description

Counters.dll The Counters component.
Counters.txt The file that stores all individual counters on a site. Counters.txt is a UTF8-
encoded file. You can have any Unicode characters in a counter name.
Syntax
Create the Counters object one time on your server by adding the following to the Global.asa file:
<OBJECT
RUNAT=Server
SCOPE=Application
ID=Counter
PROGID="MSWC.Counters">

</OBJECT>
Remarks
Only create one Counters object in your site. This single Counters object can create any number of
individual counters.
Note For Internet Information Services on Windows® 95 or later, a Counters component has already
been specified in the Global.asa file in the default virtual directory. You can work with the Counters
object the component creates as if it were a built-in object by calling Counters.Get,
Counters.Increment, Counters.Remove, and Counters.Set. You should not create another instance
of the Counters object.
Methods
Get Returns the value of the counter.

Increment Increases the counter by 1.
Remove Removes the counter from the Counters.txt file.
Set Sets the value of the counter to a specific integer.
Example
Create an instance of the Counters object in the Global.asa file with the ID attribute set to Counter:
<OBJECT RUNAT=Server SCOPE=Application ID=Counter PROGID="MSWC.Counters"> </OBJECT>
You can then use that Counters object on one page to create all the counters you need:
There have been <%= Counter.Increment('defaultPageHits') %> to this site.
Then on another page you can increment the counter in the following manner:
You are visitor number<%= Counter.Increment('LinksPageHits') %> to this page.
Get
The Get method takes the name of a counter and returns the current value of the counter. If the counter
doesn't exist, the method creates it and sets it to 0.
Syntax
Counters.Get(CounterName)

Parameters
CounterName
A string containing the name of the counter.
Example
Display the value a counter with <%= Counters.Get(CounterName) %>. Assign the value of the
counter to a variable with <% countervar = Counters.Get(CounterName) %>.
The following script displays the vote tally from a poll about favorite colors.
<%
If colornumber = "1" Then
Counters.Increment("greencounter")
Else
Counters.Increment("bluecounter")
Else
Counters.Increment("redcounter")
End If
End If
End If
%>
<P>Current vote tally:
<P>red: <% =Counters.Get("redcounter") %>
<P>green: <% = Counters.Get("greencounter") %>
<P>blue: <% = Counters.Get("bluecounter") %>
See Also
Increment, Remove, Set
Increment
The Increment method takes the name of a counter, adds 1 to the current value of the counter, and
returns the counter's new value. If the counter doesn't exist, the method creates it and sets its value to 1.
Syntax
Counters.Increment(CounterName)
Parameters
CounterName

Example
Increment the value of a counter with <% Counters.Increment(CounterName) %>. Increment and
display the value of a counter with <%= Counters.Increment(CounterName) %>.
To retrieve the value of a counter, use Counters.Get. To set a counter to a specific value, use
Counters.Set.
The following code implements a one-line page-hit counter.
<P>There have been <%= Counters.Increment("hits") %> visits to this Web page. </P>
In this example, Counters.Increment increases the counter by one each time the client requests the
page from the server.
See Also
Get, Remove, Set
Remove
The Remove method takes the name of a counter, removes the counter from the Counters object, and
deletes the counter from the Counters.txt file.
Syntax
Counters.Remove( CounterName )
Parameters
CounterName
Example
The following code removes the counter hitscounter from the ounters.txt file.
<% Counters.Remove(hitscounter) %>
See Also
Get, Increment, Set

Set
The Set method takes the name of a counter and an integer, sets the counter to the value of the integer,
and returns the new value. If the counter doesn't exist, Counters.Set creates it and sets it to the value of
the integer.
To retrieve the value of a counter, use Counters.Get. To increment a counter by 1, use

Counters.Increment.
Syntax
Counters.Set(CounterName, int)
Parameters
CounterName
int
The new integer value for CounterName.
Example
The following code resets the hit counter pageHits to 0:
<% Counters.Set(pageHits, 0) %>
See Also
Get, Increment, Remove
Database Access Component

The Database Access component uses ActiveX® Data Objects (ADO) to access information stored in a
database or other tabular data structure.
For information about ADO see http://www.microsoft.com/data/ or the Microsoft Data Access SDK in
the Platform SDK.
Note To use the constants specified in the ADO Reference, you must either include a file that contains
information about the ADO constants or include a reference to the ADO type library in your Global.asa
file. Using a type library is generally a better option. The following example demonstrates using the ADO
type library to access constants.

For example, to use:
<% rs.Open "Customers", Conn, adOpenStatic, adLockOptimistic %>
Instead of:
<% rs.Open "Customers", Conn, 3, 3 %>
You would include the following type library declaration in the Global.asa file for the application.

Parameters
file
Absolute path to a type library. If this parameter and the typelibraryuuid parameter are provided,
file is used to identify the type library. Either the file parameter or the typelibraryuuid parameter
is required.
typelibraryuuid
Universally unique identifier for the type library. Either the file parameter or the typelibraryuuid
parameter is required.
majorversionnumber
Used for selecting version. If the requested version is not found, then the most recent version is
used (optional).

minorversionnumber
Used for selecting version. If the requested version is not found, then the most recent version is
used (optional).
localeid
The locale identifier to be used for the type library. If the requested locale is not found, then the
System locale identifier will be used. (optional)
Error Values
The server can return one of the following error messages.
Error Description
ASP 0222 Invalid type library specification. The METADATA tag contains an
invalid type library specification.
ASP 0223 Type library not found. The METADATA tag contains a type library
specification that does not match any registry entry.
ASP 0224 Type library cannot be loaded. ASP cannot load the type library
specified in the METADATA tag.
ASP 0225 Type library cannot be wrapped. ASP cannot create a Type Library
Wrapper object from the type libraries specified in the METADATA
tag.
Remarks
It is recommended that METADATA tags appear near the top of the Global.asa file. However, these
tags can appear anywhere inside of the Global.asa file, including both inside and outside the SCRIPT
tags.
You can avoid ambiguous references to constants by adding the type library name as a prefix for the
constant. For example, ADODB.adErrItemNotFound would be less ambiguous than
adErrItemNotFound.
If you use Microsoft Visual InterDev to create your Global.asa file, the METADATA tags will include
the optional STARTSPAN and ENDSPAN keywords. These keywords are ignored by IIS.
If you do not specify a locale identifier for the type library, the default locale identifier for the system will
be used. If the system locale identifier can not be used, and you have not specified a locale identifier, the
locale identifier for the Type Library will be set to 0.
Example
MyComponent in the following example was developed with Visual Basic 5.0. MyComponent defines the
constant MyError with the following statement.
Public Const MyError = "You are not using MyComponent correctly."
The type library is contained in mycomponent.lib, which you have installed in the following directory.
C:\MyComponent

The following METADATA tag is included in the Global.asa file for the MyApp application.

Any .asp file in the MyApp application can now include the following script:
<%
Dim MyVar
Set MyVar = Server.CreateObject("MyComponent.MyClass")
Currentreturn = MyVar.MyMethod
If Currentreturn = False
Response.Write(MyError)
End If
%>
ASP Samples
Welcome to the ASP samples. Through these clear and simple examples, this section exposes you to the
power and extensibility of Internet Information Services (IIS), one step at a time. Included are sample
ASP scripts and Windows® Scripting Host (WSH) administrative scripts.
? ASP Script Examples: Features a wide variety of scripts, provided in both Microsoft ® Visual
Basic® Scripting Edition (VBScript) and JScript®. Beginners can learn what scripting is all about,
while more experienced users can quickly review ASP fundamentals and move on to more
advanced applications. To see the sample scripts in action, you can run them immediately without
exiting this documentation.
? Programmatic Administration Examples: Provides samples that use the IIS programmatic
interfaces. Here you will find Windows Scripting Host (WSH) scripts, written in VBScript and
JScript, that access the IIS metabase by using the ADSI interface.
For information about overall application development, see Developing Web Applications.
Important These samples are provided for educational purposes only. They are not intended to be
used in a production environment, have not been tested in a production environment, and Microsoft will
not provide technical support for them.
ASP Script Examples


Active Servers Pages (ASP) is one of the features that make IIS the premier Web server. Never before
has it been so easy to create useful, interactive, Web-based applications, even if you have relatively little
experience with programming. If you are a more advanced user, ASP provides a way to rapidly create
sophisticated and robust Web applications without dedicating the often substantial resources required for
development in a more conventional programming language environment, such as C++ or Java.
This section provides an overview of the capabilities of server-side scripting in general, and ASP in
particular, while at the same time providing more advanced examples for experienced developers who
want to discover what ASP can do for them.
Sample scripts provided in this documentation are divided into several categories:
? Simple Scripts: Learn the basics of script syntax, flow control, functions, and procedures.
? Building ASP Applications: Study samples that demonstrate the structure and function of a Web-
based application.
? Web Interactivity using ASP: Discover how to make your application more useful and versatile by
incorporating cookies, client-side scripting, and other techniques.
? Using Installable Components: Learn how to leverage the functionality provided by the Active
Server Pages components that are installed with IIS.
? Database Connectivity: Explore examples that illustrate the power of the bundled database access
component, ActiveX® Data Objects (ADO).
? ASP Transaction Services: Study samples that demonstrate the alliance between Component
Services and ASP scripts.
Although the samples in this section are provided as an educational resource, this is not a tutorial on ASP
scripting or application creation. For more information, see Active Server Pages and Developing Web
Applications.
Simple Scripts
The following scripts illustrate the fundamental techniques used in ASP scripting. If you're a newcomer to
application development, or a programmer who has never scripted before, this is a good starting place.
Choose an example from the following list:
? Variables: Demonstrates how to create and manipulate variables in an ASP script.

? Looping: Provides an example of the three most common looping constructs, For ... Next, Do ...
Loop, and While ... Wend.
? Conditional Operators: Illustrates the use of conditional operators, such as If ... Then, in ASP
scripts.
? Arrays: Demonstrates how to create, access, and manage arrays.
? Server-Side Includes: Demonstrates the use of server-side includes.
? Functions and Procedures: Shows how to create and utilize functions and procedures in ASP
scripts.

Variables
Overview
Every application ever written, regardless of the programming language, has used variables of some sort,
and ASP scripts are no exception. Both VBScript and JScript allow you to create and manage variables
simply and easily.
Each language deals with variable declaration differently. Both JScript and VBScript are quite flexible
about variables and their declaration. In VBScript, any variable is automatically considered to be of the
Variant type when it is initially declared with the Dim statement. Each variable eventually is assigned a
subtype, such as Numeric and Array. JScript is similar; the variable is initially declared with the var
statement. Both languages, in general, try to perform much of the data type management, including type
conversion, automatically. In fact, you don't even have to use the Dim or var statements at all to use a
new variable; they are optional in their respective languages.
Code Tour
This sample declares several different kinds of variables, performs simple operations on them, and then
displays them to the client browser using the special <% = ...%> script delimiters. An integer is assigned
to the variable intVariable, added to itself, and the sum sent to the client browser. StrVariable is set to
equal to the first name, is added to Smith, and sent to the client browser. Booleans and dates are
likewise declared or created, initialized, manipulated, and displayed.
Remarks
Of particular interest is the final step in the date variable demonstration. In VBScript, the variable is first
assigned a literal date string, and displayed. It is then reset, and assigned the value that is returned by the
VBScript Now function, which returns the current system time. The JScript example uses the JScript
Date function to set both the initial literal by passing parameters to the function, and then to set the
variable equal to the current system time by passing no parameters to the function.
Location
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\simple\Variables_VBScript.asp and ...\asp\simple\Variables_JScript.asp.
Looping
Overview
Looping is one of the most important flow-control mechanisms in a programming language. Looping
constructs provide the foundation for any application that must repetitively perform a task, such as adding
1 to a variable, reading a text file, or processing an e-mail message and sending it.

Code Tour
VBScript and JScript provide several looping mechanisms. This sample demonstrates the three most
commonly used looping statements, For ... Next, Do ... Loop, and While ... Wend. These three
statements are subtly different, and the scripting situation will frequently dictate which of the three would
work best. For the purpose of this sample, however, each type of looping statement is used to
accomplish the same task, which is to print a greeting five times using progressively larger font sizes. For
each looping statement, the variable i is initialized, and the test condition for the loop is defined such that i
will never be greater than 5. The variable is then incremented by 1 for each iteration of the loop.
Location
at ...\asp\simple\Looping_VBScript.asp and ...\asp\simple\Looping_JScript.asp.
Conditional Operators
Overview
Conditional operators, together with variables and looping constructs, form the fundamental building
blocks of programming languages and, therefore, applications. The Web-based applications you
implement with ASP scripts can take advantage of both the flow control provided by conditional
operators and the interactivity and sophistication of HTML.
Code Tour
This sample demonstrates the If ... Then, or if ... else statements in both VBScript and JScript, as well
as the more complicated Select ... Case and switch ... case statements. Each statement demonstration
performs the same task, sending a page to the client browser that consists of the current time and date
and a greeting. The text of the greeting will be either "Good Morning" or "Good Evening," depending on
whether the system clock reads A.M. or P.M.
Location
at ...\asp\simple\Conditional_VBScript.asp and ...\asp\simple\Conditional_JScript.asp.
Arrays
Overview
Arrays are essentially variables that can hold more than one value. Both VBScript and JScript support
arrays for most data types. This sample demonstrates how you can create and use arrays in ASP scripts.

Each element of an array is accessed by using an index. Thus, in the array A, A(0) refers to the first
element, A(1) refers to the second element, and so on. Note that array elements in both VBScript and
JScript are numbered starting at 0.
Arrays can be fixed-size, or dynamically sizable. In both VBScript and JScript, the variable name must
be declared, and storage space must be allocated for a new array. This is accomplished by using the
Dim statement in VBScript, and the new statement in JScript. If a specific size is explicitly stated, then
the array is fixed-size; but if a specific size is omitted from the declaration, then the array is considered
dynamically sizable.
Code Tour
This sample creates two arrays, aFixed, which is fixed-size, and aColors, which is dynamically sizable.
The script then assigns specific string values to each element in the arrays, using the index notation
ArrayName(Index) to access the appropriate element. The script then loops through each array by using
a For loop, and displays the results in a table.
Note that dynamically sizable arrays are implicitly expanded in JScript, so as to include the highest
element indexed in an assignment. VBScript, in contrast, requires that you explicitly resize the dynamic
array with the ReDim statement.
Location
at ...\asp\simple\Arrays_VBScript.asp and ...\asp\simple\Arrays_JScript.asp.
Server-Side Includes
Overview
Modularity and reusability of code can be very useful in your development of ASP scripts. For example,
if you want to display copyright information on the bottom of each of your HTML pages and ASP pages,
ASP provides a solution to this problem: server-side includes, which are directives to the server to
include a certain file, which can be a text file, graphical image, or an ASP function. The copyright notice
can exist as one file, and be included into the rest of your Web site's files. And if the copyright notice
changes, you only have to change one file instead of 50 or 500.
The syntax for including a file is:

The PathType parameter consists of a keyword, either FILE or VIRTUAL, which indicates whether the
Name string specified is a physical or virtual path.
Code Tour
This example uses the #include directive to include the file HeaderInfo.asp. When this script is executed,
ASP loads the script line by line, character by character, until it gets to the #include directive, at which

point it loads the contents of the designated file, line by line. Then the remainder of the sample script is
loaded; once this is finished the script is executed, included file and all.
Note If the file that your ASP script includes contains a large number of functions and variables that are
not used by the including script, the extra resources occupied by these unused structures can adversely
affect performance, and ultimately decrease the scalability of your Web application. Therefore, it is
generally advisable to break your include files into multiple smaller files, and include only those files
required by your ASP script, rather than include one or two larger include files that may contain
unneeded information.
Location
at ...\asp\simple\Includes_VBScript.asp and ...\asp\simple\Includes_JScript.asp.
Functions and Procedures

Overview
Functions and procedures provide a way to avoid rewriting the same block of code every time you want
to perform a particular task. Both VBScript and JScript allow you to call a function or procedure from
any point in a script. This sample demonstrates how you can create and use these tools with ASP.
If you don't have any functions in your ASP page, the ASP engine simply processes your entire file, start
to finish, each time it is requested by a client browser. Functions and procedures, however, are executed
only when called, not inline with the rest of the code.
You can denote functions and procedures in VBScript or JScript by using the Function statement. In
addition, VBScript makes a distinction between a function that returns a value and a function that does
not; a function that returns a value is denoted with the Sub statement, indicating that it is a subroutine.
Code Tour
This sample defines one function, PrintOutMsg, which takes as parameters a message, and a number
that specifies how many times the message is to be written to the client browser with the
Response.Write method. The function, for the purposes of this sample, simply returns to the client
browser the number of times the message was printed.
Remarks
It is important to note the RUNAT attribute of the <SCRIPT> tag. If the RUNAT attribute is not
included, ASP will assume that the script is client-side scripting, and will pass the code back to the
browser for processing. ASP would then not recognize the PrintOutMsg function call, return an error,
and abort.
Location
at ...\asp\simple\Functions_VBScript.asp and ...\asp\simple\Functions_JScript.asp.

Building ASP Applications

ASP makes it easy for you to develop Web-based applications. With the tools and services ASP
provides, you can create an integrated, powerful application quickly and easily.
Here you will find examples that show some of the basic application features in action.
? Session Variables: Demonstrates the use of the Session object to retain state during a client
browser's session in an application.
? Application Variables: Illustrates the use of the Application object to store information for the life
of an application.
Session Variables
Overview
You can use the Session object to store variables that will remain available for the length of the session,
and, therefore, have session scope. For instance, if you have created an online shopping application, you
could define Session object variables that allow you to track how much merchandise the shopper has
purchased or how much money is owed.
Code Tour
This example uses the variable SessionCount to store the number of times you have clicked the Click
here to visit it again link.
Remarks
If you visit this sample several times, then visit other sections of this documentation before visiting this
sample again, the count will pick up where you left off. This is because the server's Session object that is
associated with your particular Web session will not be destroyed until your session has timed out.
Location
at ...\asp\applications\Session_VBScript.asp and ...\asp\applications\Session_JScript.asp.
Application Variables

Overview
You can use the built-in Application object to store developer-defined global application information
that is persistent for the life of the application.
Code Tour
This example demonstrates this storage ability by implementing a simple counter. The total number of
times that client browsers visit the sample script is stored in the application variable AppPageCount, and
incremented each time the script is accessed.
Note Because the Application object for a given application is available to many client browsers
simultaneously, the object must be locked before a property or value is changed, and unlocked after the
change. Locking is not necessary if the value or property is simply being queried.
Location
at ...\asp\applications\Application_VBScript.asp and ...\asp\applications\Application_JScript.asp.
Web Interactivity using ASP

With ASP, you can easily create useful Web-based applications. The following examples demonstrate
some of the techniques used in creating an interactive ASP application.
? User Form Input with POST: Illustrates techniques you can use to obtain form values by using the
Request.Form collection.
? HTTP Server Variables: Demonstrates techniques you can use to access server variable
information from an ASP script.
? Using Cookies: Illustrates how your script can set and read cookies by using the
Response.Cookies collection.
? Setting Expiration Information: Shows how you can set the expiration date for a resource by using
the Response.Expires and Response.ExpiresAbsolute properties.
? Client-Side Scripting: Demonstrates simple tasks you can perform with a combination of ASP and
client-side scripting.
? Populating Fields: Illustrates techniques you can use to populate form fields by using ASP.
User Form Input with POST

Overview
The most basic form of interactivity on the Web is probably the HTML form. It is important to note that
ASP does not replace forms, but rather enhances them, and makes them easier for you to implement and

manage.
The HTML <FORM> tag specifies what method the form will use to convey information to the
processing script. The POST method attribute indicates that information from the form will be passed to
the processing script or program through a separate HTTP connection. The processing script or program
can parse the information and do whatever task is required, and return output to the client browser.
Code Tour
This example demonstrates how to implement a simple form by using the HTML POST method
attribute, as well as one key benefit of creating forms with ASP: the ability to combine the form and the
actual processing code into the same file. This sample creates a small form with two text input boxes, one
for the user's first name (fname) and one for his or her last name (lname). The Request.Forms
collection is accessed to get the value of the fname and lname variables from the request, and the results
are displayed at the bottom of the page.
The first time you run this script, no text will be displayed below the horizontal line. This is because no
form information was available to pass to this script when it started, and ASP ignores searches of
Request.Forms for information that does not exist. However, if you press the Submit button, the page is
reloaded and the information you entered into the text boxes is available to the script.
Location
at ...\asp\interaction\Form_VBScript.asp and ...\asp\interaction\Form_JScript.asp.
HTTP Server Variables

Overview
Each HTTP transaction that takes place between a client browser and a server involves the exchange of
a great deal of potentially useful information. This sample demonstrates one way you can access this
information, by accessing server variables. Using server variables, you can, determine the server's name
with the SERVER_NAME variable, or the HTTP headers with the ALL_HTTP variable.
Code Tour
The sample's structure is simple: form a two-column table, and fill each table row with a name, value
variable pair. Each individual server variable is retrieved by using the name as a key, such as
Request.ServerVariables("ALL_HTTP"). In addition, because ServerVariables is a collection, you
can use a For Each ... Next loop to iterate through all variables found in the collection.
Location
at ...\asp\interaction\ServerVariables_VBScript.asp and ...\asp\interaction\ServerVariables_JScript.asp.

Using Cookies
Overview
You can use cookies to store information about a particular client, session, or application. You can then
use this information to customize and streamline a client browser's session.
Code Tour
This sample illustrates how your application can query the value of a particular cookie. IIS makes
cookies available to ASP scripts through the Request.Cookies collection. This example first queries the
cookie CookieVBScript or CookieJScript by using the standard collection-access format,
object.collection(keyname). It then resets that cookie to the current date and time.
If the initial query yields a null string, that indicates the client browser has never visited the page in
question before, and a first-time welcome message is displayed. If a value is returned by the initial query
of CookieVBScript or CookieJScript, however, it indicates not only that the client browser has visited
before, but when that last visit took place.
Note IIS sends all HTTP headers required for a given Web page or script before any HTML is sent to
the client browser. Therefore, all statements and methods that modify the HTTP headers of the response,
including setting of the Response.Cookies collection members, must be located before the <HTML>
tag in your script. If your script attempts to modify the HTTP headers after the server has begun sending
HTML content back to the client browser, the script will generate an error.
Location
at ...\asp\interaction\Cookie_VBScript.asp and ...\asp\interaction\Cookie_JScript.asp.
Setting Expiration Information

Overview
You can give every page or script on the server an expiration date. The expiration date can either be in
the form of an absolute date, such as January 1, 2000, or a relative date, such as 600 minutes from the
time the page was first downloaded by the client browser. If a client browser requests that same page
again before the expiration date and time, then the client browser uses its own cached copy.
Code Tour
This example illustrates how your script can set the expiration date for a file. The Response.Expires
property is used to set the relative expiration date. The unit of measurement is minutes, so if this property
is set to 10, as in the example, then the page will expire after 10 minutes.

The Response.ExpiresAbsolute property is used to specify an absolute expiration date. In this

example, the page is specified to expire on January 1, 1999, at 1:30:15 P.M. Either the time or the date
can be left out when assigning an expiration date.
Note IIS sends all HTTP headers required for a given Web page or script before any HTML is sent to
the client browser. Therefore, all statements and methods that modify the HTTP headers of the response,
including setting the Response.Expires and Response.ExpiresAbsolute properties, must be located
before the <HTML> tag in your script. If your script attempts to modify the HTTP headers after the
server has begun sending HTML content back to the client browser, the script will generate an error.
Location
at ...\asp\interaction\Expire_VBScript.asp and ...\asp\interaction\Expire_JScript.asp.
Client-Side Scripting
Overview
ASP is a server-side scripting environment. Client-side scripting complements ASP nicely, allowing for a
number of enhancements, such as ActiveX® controls, that can make your application more powerful and
user-friendly.
Code Tour
This example demonstrates how you can include a client-side script in your preferred scripting language.
This script defines a subroutine called DoIt within the <SCRIPT> tags. Note that there is no
RUNAT=SERVER attribute present, which indicates that the script is an ASP subroutine. The page
provides one button for the user that, when clicked, executes the DoIt subroutine on the client browser.
This sample demonstrates a very useful advantage to combining ASP scripts with client-side scripting.
When ASP encounters the <SCRIPT> tags, it does not simply ignore everything within that block. It
continues to search for, parse, and execute script elements, specified with delimiters (<% ... %>), that
are meant for the server. This example, therefore, returns within a client-side script the session
information returned from the Session.SessionID method.
Location
at ...\asp\interaction\ClientScript_VBScript.asp and ...\asp\interaction\ClientScript_JScript.asp.
Populating Fields

Overview
You can use forms to collect input from users, but you can also use them to display information as well.
For example, if a client browser accesses your phone-directory search engine, you will want to show the
results of their search. Your search script (which can be implemented in ASP as well) accepts input,
accesses the database, and sends the results in a query string to your display form. This sample is a
simple demonstration of how that display form would look.
Code Tour
For the purposes of this sample, the data is hard-coded into the script, but obviously the information
could come from an interactive form, database, or text file. This sample starts by initializing the variables.
It then creates a form with the HTML <FORM> tags and defines four text boxes. Using the server-side
script delimiters <%= ... %>, the script then fills the text boxes with the values set in the initialization.
Location
at ...\asp\interaction\PopulateForm_VBScript.asp and ...\asp\interaction\PopulateForm_JScript.asp.
Using Installable Components

There are a number of components installed with IIS that your application can call upon to perform a
wide variety of tasks to enhance your Web site. However, the real advantage of using these components
is that, because they run on the server and send to the client browser only normal HTML, any reasonably
current Web browser will be able to display the results. The examples below demonstrate how to access
these components, and show some simple situations in which they can be used.
Choose an example from the list below.
? Ad Rotator: Demonstrates how to use the Ad Rotator component in an ASP script.

? Browser Capabilities: Illustrates how you can use the Browser Capabilities component in an ASP
script.
For more information about working with the installable Active Server components, as well as detailed
descriptions of each individual component, see Installable Components for ASP.
Ad Rotator
Overview
The Ad Rotator component creates an AdRotator object, which automates the rotation of
advertisement images on a Web page. The component is designed to display a new advertisement each

time a client browser opens or reloads a Web page.
Code Tour
This sample demonstrates how to use the Ad Rotator component. The script itself is simple, creating an
instance of the AdRotator object and calling the GetAdvertisement method each time the page is
loaded. GetAdvertisement returns a single ad entry from the Ad Rotator schedule file, adrot.txt in this
example, and the special script delimiter <% = ... %> displays the results to the client browser.
The schedule file for this sample, adrot.txt, is relatively straightforward. The four lines above the asterisk
(*) are global file settings that affect all schedule entries in the file. The most interesting and useful global
setting is the redirection specification. In this sample, if a user clicks on the advertisement, no matter
which particular entry is currently displayed, the user will be transported to the .asp file indicated. These
scripts, or DLLs, usually count how many hits a given ad has received, collect user information, and then
extract the URL from the request and redirect the client browser once again to the URL that was
originally requested.
Each of the entries that occurs below the asterisk consist of four lines, denoting the image to be
displayed, hyperlink, alternate text, and the relative probability that that particular entry will be displayed
on any given visit to that Web page. Thus, the Microsoft® Internet Information Services image has an 80
percent chance of being displayed with each hit on that page, while the Microsoft Internet Explorer image
will be displayed for only 20 percent of the hits.
Note If an advertisement entry in the schedule file does not have a corresponding URL, the hyperlink
line of the entry must contain a hyphen (-) or the Ad Rotator component will return an error.
Location
at ...\asp\components\AdRotator_VBScript.asp and ...\asp\components\AdRotator_JScript.asp.
Browser Capabilities
Overview
Not all browsers have the same capabilities. To make the task of accounting for differences easier, ASP
provides the Browser Capabilities component. This component provides your scripts with a description
of the capabilities of the client browser by use of the BrowserType object.
Code Tour
First, an instance of the BrowserType object must be created and assigned to an object variable, bc.
Then, each property is requested, in turn, from the object by using the object.property syntax. Run the
example, and see what your browser can do.
If you are using Internet Explorer version 5.0 or later, the list of capabilities you will see include those
capabilities that are determined using the new client capabilities cookies, described in Client Capabilities.
Location

at ...\asp\components\BrowserCap_VBScript.asp and ...\asp\components\BrowserCap_JScript.asp.
Database Connectivity
If you are creating a Web-based application, your application is probably going to have forms. And it
will probably also require some kind of database. ActiveX® Data Objects (ADO) provides you with a
set of powerful tools for accessing and manipulating data sources.
The samples in this section illustrate the techniques required to use ADO effectively, and how you can
best put its functionality to use in a Web-based application.
? Simple Query: Illustrates how you can use ADO and ASP together to perform simple database
queries.
? Limit Query Results: Shows how your scripts, using ASP and ADO, can limit the number of rows
returned in a recordset.
? Scrollable Query: Demonstrates a multidirectional, scrollable query with ADO.
? Add/Delete Records: Illustrates the techniques you need to use to add and delete records from a
data source by using ASP and ADO.
? Update Records: Shows how your application can use ADO to update existing records.
? Executing Stored Procedures: Illustrates how your ASP scripts can use ADO to execute stored
database procedures.
For more information on ADO, and Microsoft data access tools in general, refer to the Microsoft Data
Access documentation.
Simple Query
Overview
Although databases can be very complicated systems, and data access tools must be powerful and
responsive, it is equally important that simple database access tasks be easy to accomplish. This sample
demonstrates how ADO provides an easy way to perform such a task.
Code Tour
The goal of this sample application is to retrieve a small recordset from a Microsoft® Access database,
and print the results. The first step is to create an instance of the Connection object, using the
Server.CreateObject method. The sample uses the Connection object instance to open the OLE DB
data provider, then uses the Connection instance again to execute a SQL SELECT command to
retrieve all the records from the Authors table. The script finishes by iterating through the returned
recordset collection and displaying the results. Afterwards, both the recordset and OLE DB data source

connection are closed.
Important OLE DB must be properly configured on the server for this sample to run properly.
Location
at ...\asp\database\SimpleQuery_VBScript.asp and ...\asp\database\SimpleQuery_JScript.asp.
Limit Query Results

Overview
In an Internet environment, it is often desirable to limit the amount of information that a database query
returns to a client browser. This example demonstrates how a script, using ASP and ADO, can limit the
number of rows returned.
Code Tour
The sample first creates an instance of the Connection object, and opens the OLE DB connection with
this object's Open method. CreateObject is used again to instantiate an empty Recordset object. The
ActiveConnection property of the new Recordset object is set to point at the open OLE DB
connection, an SQL source string is assigned, and cursor type specified. The key to limiting the results
lies with the Recordset object's PageSize property. For this example, the value is set to 10, which
indicates that ADO is to return at most 10 records. Finally, the Open method is called, and ADO
searches for the first 10 records that fulfill the SQL search string.
When ADO has returned and placed the results of the search into the Recordset object, the script loops
through the page, displaying all fields of each record in a table. The script then performs the typical
housecleaning operations, closing both the recordset and the connection.
It is important to realize that if the SQL query had returned more than 10 records, this script would not
display them. Instead, the extra records would be deposited on one or more additional, logical pages.
The property PageCount indicates how many logical pages of data were returned.
Location
at ...\asp\database\LimitRows_VBScript.asp and ...\asp\database\LimitRows_JScript.asp.
Scrollable Query
Overview

When you design application for an Internet environment, you will often want to limit the amount of
information that a database query returns to a client browser. This example demonstrates how a script,
using ASP and ADO, can limit the number of rows passed to the client browser in any one chunk, but
still allow the user to browse through all the results of the query.
Code Tour
The script consists of several code sections that all work together to accomplish this task. First, the
database is accessed as usual, creating a Connection object and Recordset object. The Recordset
object's PageSize property is set to 4, and the recordset is opened and populated with the query results
from the database table Authors. The first logical page of four result records are displayed in a table.
Two buttons, PgUp and PgDn, are provided so that the user can view other pages of the recordset.
If a user clicks on a button, the page is accessed again, this time using the POST method to pass some
variables to the next copy of itself. The variable PageNo is used to store what page the user is currently
viewing, while the Mv variable is used to pass the scrolling direction to the next form. If a user clicks on
PgDn, for instance, the page is accessed again, with Mv set to PgDn and PageNo set to 1. The script
would use that information to add 1 to the current page number, and AbsolutePage could then be used
to display the next page of results.
Location
at ...\asp\database\MultiScrolling_VBScript.asp and ...\asp\database\MultiScrolling_JScript.asp.
Add/Delete Records
Overview
This sample illustrates the techniques you need to know in order to use ASP and ADO to add and delete
records from a database.
Code Tour
First, CreateObject is used to create an instance of the Connection object, which in turn is used to
open a connection to the OLE DB data provider. CreateObject is used again, this time to create an
empty Recordset object. The ActiveConnection property is set to refer to the new Connection
object.
Although the ADO Recordset object provides the AddNew method to add new records to a database,
you may be able to achieve better scalability by sending SQL INSERT commands directly to the
database engine. This sample uses the Recordset.Execute command, with the appropriate SQL
command string, to insert information for a new author.
At this point, another Recordset object instance is created and opened with another SQL command.

The record just added is selected, then deleted by passing the SQL DELETE command directly to the
database engine. The script then terminates.
Location
at ...\asp\database\AddDelete_VBScript.asp and ...\asp\database\AddDelete_JScript.asp.
Update Records
Overview
This example demonstrates how your application can use ADO to update existing records.
Code Tour
CreateObject is used to create an instance of the Connection object, which in turn is used to open a
connection to the OLE DB data provider. CreateObject is used again, this time to create an empty
Recordset object. The ActiveConnection property is set to refer to the new Connection object.
The new recordset is then configured. The Recordset.Execute method takes a SQL command string as
a parameter. This sample uses a SQL UPDATE command string to efficiently perform the update to the
appropriate database records.
Location
at ...\asp\database\Update_VBScript.asp and ...\asp\database\Update_JScript.asp.
Executing Stored Procedures

Overview
Stored procedures, such as those provided by Microsoft ® SQL Server, are the keys to making large,
mission-critical database applications function smoothly and efficiently. This example demonstrates how
you can access this functionality by using ADO from within an ASP script.
Code Tour
This script first creates an instance of the Connection object and uses it to open an OLE DB connection
with the sample database, pubs. A special object, called a Command object, is created next. The

Command object's CommandText property is set to the string of the command you want to issue,
which for this sample is the name of a stored procedure, ByRoyalty. The Command object Parameters
property provides a collection of Parameter objects, and this script uses the Append method to add a
new parameter to the collection.
Once CreateParameter has been used to name and configure the parameter instance, the parameter
name assigned can be used to access the value of that parameter directly, as if the Command object
itself were a collection. Thus
oCmd("@Percentage") = 75
assigns the value 75 to the parameter that the script has labeled as @Percentage. The Command
object's Execute method is invoked, and the resulting recordset is assigned to the object variable oRs
defined earlier in the script. The first record of the resultant recordset is displayed.
Important SQL Server must be installed, and configured properly, on the same machine on which IIS
is running in order for this sample to work correctly.
Location
at ...\asp\database\StoredProcedures_VBScript.asp
and ...\asp\database\StoredProcedures_JScript.asp.
ASP Transaction Services

Transaction management is a required component for any serious Web-based application. Answering
that need, ASP and Component Services provide reliable, robust transaction services to your
applications. With ASP and Component Services, most of the technical details of transaction
management are taken care of behind the scenes.
Some of the features of ASP and Component Services are illustrated in the following sample.
? Basic Transaction: Demonstrates the basics of ASP and Component Services, including commits
and the OnTransactionCommit and OnTransactionAbort events.
Basic Transaction
Overview
Using ASP, you can easily take advantage of the reliability provided by Component Services. You only
need to include the @TRANSACTION directive in your script. This directive tells Component Services
that any changes that occur in that page, such as database manipulation or Message Queuing Services

(MQS) message transmission, should be considered transactions. A change that is being managed by
transaction services can be either committed, making it permanent; or aborted, which would result in the
state of the database or queue being rolled back to its previous state, before the changes were made.
Code Tour
In this sample, the entire page has been declared a transaction by use of the @TRANSACTION
directive. The sample provides some scripting commands for two other procedures that are called to
perform additional completion or clean-up tasks. OnTransactionCommit is called when either the
script has successfully completed, or the ObjectContext.SetComplete method has been called.
Likewise, OnTransactionAbort is called when the script either encounters some kind of processing
error, or the ObjectContext.SetAbort method has been called.
This sample commits, by default, because it simply prints a small message and then exits. Because the
directive declared the script to be a transaction, exiting successfully automatically commits changes made
in the script (although in this case there are none), and triggers the OnTransactionCommit procedure,
which prints a message.
Important The @TRANSACTION directive must be on the first line of the .asp file, or an error will
be generated.
Location
at ...\asp\transactional\SimpleTransaction_VBScript.asp
and ...\asp\transactional\SimpleTransaction_JScript.asp.
Programmatic Administration Examples

The samples presented here demonstrate how you can create scripts that use the ADSI interfaces
provided by IIS to administer the IIS installation.
Scripting languages, such as Microsoft® Visual Basic® Scripting Edition (VBScript) and JScript®, can
be used to automate time-consuming administrative tasks. This section provides some simple example
scripts designed to run on your local machine, written in VBScript and JScript, and executed by the
Windows Scripting Host (WSH). The samples provided here illustrate basic techniques for
accomplishing common tasks.
? Logging Module Enumerator

? Metabase Backup Utility
? Metabase Backup Restore Utility
? Web Server Creator
The general format for invoking a WSH script is either Cscript.exe ScriptName to execute the script at
the command line, or Wscript.exe ScriptName to execute the script in a window. You can also create a
batch file that will execute Cscript.exe or Wscript.exe and your script. For more information about
WSH, please refer to the Windows Scripting Host documentation.

Important WSH must be locally installed to execute these sample scripts. In addition, most of these
scripts access functionality provided by IIS, and therefore require that IIS and WSH be installed locally.
Logging Module Enumerator

Overview
Multiple logging modules can lead to multiple problems if you aren't prepared. This sample tool illustrates
some techniques you can use to create logging management tools of your own.
This sample tool serves two separate functions. If it is invoked without command-line arguments, then it
simply lists all logging modules that currently have entries in the metabase on your server. But if an
ADsPath is given, such as IIS://LocalHost/W3SVC/3, then the tool will try to determine what is
considered the active logging module for that metabase node, and will give you information about that
logging module.
Code Tour
To list the available logging modules, the GetObject method is invoked to gain access to the
IIS://LocalHost/Logging node of the metabase. A For ... Each loop is then used to enumerate the
modules that are founded in that node.
Gathering information about a specific server's logging module is a bit more involved. Because the only
property at the server level that indicates what logging module is currently in use by the server is the
LogPluginClsId property, this value must be compared to each and every module listed at
the //LocalHost level until a match is found.
GetObject is used to gain access to the list of logging modules provided at the //LocalHost level. The
CLSID of the logging module is compared to the CLSID of each logging module provided in this main
list until a match is found. When a match is found, the script tells you all it can about the logging module; if
no match is found between the CLSIDs, the script aborts with an error.
Location
This script is available in the IIS samples directory, at ...\admin\logenum.vbs.
Metabase Backup Utility

Overview
The IIS metabase is a large and complicated structure, and has much vital information about your
Internet sites. So that you can easily protect that important data, backing up the metabase has been made

into a relatively easy task. This tool demonstrates how you can create a tool that makes backing up the
metabase even easier.
Code Tour
All metabase backup functionality is provided at the IIS://LocalHost level, so this string is passed to
GetObject to get a reference to the local machine object. The Backup method is then invoked with
several parameters, including a number of flags, a location, and a version number.
The location parameter refers to a name that you give to your set of backup versions. Backup
implementation will probably change in future releases, but at the time of this writing, all backups are
stored in the same directory. Therefore, it might be helpful to think of location as the name of a series of
backup snapshots.
The backup version parameter can be explicit, or you can use one of several special values, the most
important being &HFFFFFFFF. This value, which equals -1 in VBScript, indicates that the Backup
method should assign a version number to this backup that is one higher than the highest version number
found for that location.
Location
This script is available in the IIS samples directory, at ...\admin\metaback.vbs.
Metabase Backup Restore Utility

Overview
If you have backed up your metabase, and then somehow corrupted the configuration on all of your
Web sites, you will need to retrieve your metabase backup. This tool is provided for just such a situation.
Code Tour
The method to restore the metabase is simply called Restore , and is accessed at the same
IIS://LocalHost node of the metabase that the Backup method was. Restore takes several parameters,
including the location string and the version number. Again, there are several constants that can be used
in place of an explicit version number. This sample uses as a default one of those constants,
&HFFFFFFFE (-2 decimal), which indicates that the server should look for, and restore from, the
highest numbered version of the specified backup location.
Location
This script is available in the IIS samples directory, at ...\admin\metabackenum.vbs.
Web Server Creator


Overview
Server creation, deletion, stopping, starting, configuring: These are all tasks that can keep you very busy,
especially if you are an administrator of a large Internet or intranet Web site. This sample tool
demonstrates how you can automate many of those tasks.
Code Tour
This sample script provides a simple interface through which you can create a new Web server. Several
steps are required to accomplish this, starting with invoking GetObject on the IIS://LocalHost/W3SVC
node. The IIsWebService object's ADSI method Create is used to create a new IIsWebServer
object. The server object is then configured, and the new information written back to the metabase with
the SetInfo method.
At this point in the script, the server is not a fully functional Web site. It now has a node in the metabase,
but it is not running, nor does it have a root directory in which to store anything. To finish creating the
Web site, the tool creates an instance of the IIsWebVirtualDir ADSI object, then configures that
object to be the new root directory for the new server. SetInfo is once again called to save the
information to the metabase, and finally, if all has gone well up to this point, the server object's Start
method is invoked.
Remarks
Note that almost every major statement group in this sample has its own set of error-code checking. This
is important when creating any tool in general, but especially for tools that use the IIS metabase.
Location
This script is available in the IIS samples directory, at ...\admin\mkwebsrv.vbs.

Active Server Pages Guide

Hochgeladen von

Dokumentinformationen

Originalbeschreibung:

Copyright

Verfügbare Formate

Dieses Dokument teilen

Dokument teilen oder einbetten

Freigabeoptionen

Stufen Sie dieses Dokument als nützlich ein?

Sind diese Inhalte unangemessen?

Copyright:

Verfügbare Formate

Active Server Pages Guide

Hochgeladen von

Copyright:

Verfügbare Formate

Active Server Pages Guide Page 1 of 659

Active Server Pages Guide

This section contains:

? Active Server Pages: Provides an introduction to creating Active

Active Server Pages

Microsoft® Active Server Pages (ASP) is a server-side scripting environment

file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000

This section includes:

? Understanding Active Server Pages: Introduces ASP and describes

This section does not include information on:

? More advanced topics, such as designing and building Web

Understanding Active Server

This section contains:

? Introduction to Active Server Pages: Provides an overview of Active

This section does not contain information on:

? Fundamental concepts of writing server-side scripts with ASP; see

Introduction to Active Server

Microsoft® Active Server Pages (ASP) is a server-side scripting environment

For the HTML Author

For the Experienced Web Scripter

For the Web Developer and Programmer

The Active Server Pages Model

file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000

What's New in ASP

file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000

the new Microsoft® XML Parser, included with Microsoft® Internet

Important Changes in ASP

file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000

ASP has undergone several important changes and enhancements. If you

? Buffering is Now On By Default In IIS 4.0, content buffering was off

? Response.IsClientConnected In IIS 4.0,

? Improved Include File Security In IIS 4.0, when an include file

? Default Document Query String Behavior In IIS 5.0, if an .asp

? Behavior of Both-Modeled Objects A Both-Modeled COM object which

? Configurable Entries Moved to the Metabase The following IIS 4.0

file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000

? Allow Out-of-Process Local Server COM applications By Default In

Building ASP Pages

ASP provides a powerful and extensible framework for creating server-side

Although these topics introduce some scripting and programming concepts,

This section includes:

file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000

This section does not include information on:

? Developing programmatically advanced collections of scripts called

Creating an ASP Page

file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000

Adding Server-Side Script Commands

file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000

This page was last refreshed on 01/29/99 2:20:00 PM.

Commands enclosed by delimiters are called primary script commands.

Mixing HTML and Script Commands

If dtmHour < 12 Then

<%= strGreeting %>

file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000

If dtmHour < 12 Then

If dtmHour < 12 Then

Response.Write sends the text that follows it to the browser. Use

You can include procedures written in your default primary scripting

file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000

for more information.

Using ASP Directives

<%@ LANGUAGE=VBScript %>

file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000