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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Active Server Pages Guide Page 2 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
This section contains:
? 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 3 of 659
Pages
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 4 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 5 of 659
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
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
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 6 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 7 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 8 of 659
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 9 of 659
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 () symbols, which
enclose HTML tags.
ASP uses the delimiters 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:
This page was last refreshed on .
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 10 of 659
The VBScript function Now() returns the current date and time. When the
Web server processes this page, it replaces 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 tag used to enclose script commands and expressions.
You can also use the 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.
Depending on the hour, this script assigns either the value "Good Morning!"
or the value "Hello!" to the string variable strGreeting. The 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:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 11 of 659
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:
Good Morning!
Hello!
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:
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 12 of 659
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:
This is the text version of a page.
This is the multimedia version of a page.
--Or--
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 displays the value of an
expression. This output directive is equivalent to using Response.Write to
display information. For example, the output expression displays
the word Baltimore (the current value of the variable) on the browser.
The ASP processing directive 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:
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 13 of 659
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:
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:
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:
This Web page is customized for " ."
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 14 of 659
Working with Scripting Languages
This is preliminary documentation for IIS 5.0 and is subject to change.
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 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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 15 of 659
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 directive to the beginning of your .asp file. The syntax for this
directive is:
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 16 of 659
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.
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
JScript Comments
The // comment characters are supported in JScript. These characters
should be used on each comment line.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 17 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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:
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.
.
.
.
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:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 18 of 659
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:
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:
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:
To retrieve information from the Session object, access the named entry by
using the output directive (
You can store user preferences in the Session object, and then access
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 20 of 659
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.
This is the text version of the page.
This is the multimedia version of the page.
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:
To retrieve information from the Application object, use the ASP output
directive (
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 tag in your .asp file or
Global.asa file. For example, to declare the ADO type library, use the
following statements:
The following table lists commonly used type libraries and UUIDs:
Type Library UUID
Microsoft
ActiveX Data {00000205-0000-0010-8000-
Objects 2.5 00AA006D2EA4}
Library
Microsoft CDO
1.2 Library for {0E064ADD-9D99-11D0-ABE5-
Windows 00AA0064D470}
2000 Server
MSWC
Advertisement {090ACFA1-1580-11D1-8AC0-
Rotator 00C0F00910F9}
Object Library
MSWC IIS Log {B758F2F9-A3D6-11D1-8B9C-
Object Library 080009DCC2FA}
For reference information about the tag, see TypeLibrary
Declarations.
In previous versions of ASP, some components provided constant
definitions in files that had to be included in each ASP file that used those
constants. The use of the #include directive to include constant definitions
is still supported, but type libraries are generally easier to use and make
your scripts more easily upgraded. Components might not provide constant
definition files in future releases of ASP.
Note Using the tag rather than the #include directive may
improve the performance of your Web application.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 22 of 659
You can define your own constants. In VBScript, use the Const statement.
In JScript, you can the var statement to assign a constant value to
variable. If you want to use your constants on more than one .asp file, put
the definitions in a separate file and include them in each .asp file that
uses the constants.
Interacting with Client-Side
Scripts
This is preliminary documentation for IIS 5.0 and is subject to change.
ASP's effectiveness can be extended by using it to generate or manipulate
client-side scripts. For example, you can write server-side scripts that
assemble client-side scripts based on server-specific variables, a user's
browser type, or HTTP request parameters.
By interspersing server-side script statements within client-side scripts
(enclosed by HTML tags), as shown in the following example
template, you can dynamically initialize and alter client-side scripts at the
request time:
.
.
.
client-side script
client-side 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):
)
{
case 0:
msg = "This is the Web server running .
break
case 1:
msg = "Welcome to the Web server. The local time is ."
break
}
document.write(msg)
}
-->
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 24 of 659
Procedure definitions can appear within and tags and
must follow the rules for the declared scripting language. Use the
element for procedures in languages other than the primary
scripting language. However, use the scripting delimiters () for
procedures in the primary scripting language.
When you use the HTML tag, you must use two attributes to
ensure server-side processing of the script. The syntax for using the
tag is:
procedure definition
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.
function MyFunction()
{
Response.Write("You called MyFunction().")
}
Important Do not include within server-side 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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 25 of 659
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).
" & _
"NameValue"
Set objQueryString = Request.QueryString
For Each strSelection In objQueryString
Response.Write "" & p & "" & _
FormValues(strSelection) & ""
Next
Response.Write ""
End Sub
%>
function printDate()
{
var x
x = new Date()
Response.Write(x.toString())
}
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 26 of 659
Working with Collections
This is preliminary documentation for IIS 5.0 and is subject to change.
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:
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":
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":
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 27 of 659
performance):
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:
"
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:
"
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.
"
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 28 of 659
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:
")
}
%>
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.
");
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:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 29 of 659
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.
"
'Display the subkeys.
For Each Subkey In Request.Cookies(Cookie)
Response.Write " ->" & Subkey & " = " & Request.Cookies(Cookie)(Subkey) & ""
Next
Else
Response.Write " = " & Request.Cookies(Cookie) & ""
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")
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 30 of 659
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:
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
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:
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 31 of 659
Processing User Input
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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 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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 32 of 659
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 .
You are years old!
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 33 of 659
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:
"
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:
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:
"
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:
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 "9" || str.length == null)
{
return false
}
}
return true
}
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 35 of 659
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:
Sorry, you may have entered an invalid account number.
Account Number:
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 36 of 659
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:
"")
{
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 37 of 659
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 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:
JScript:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 38 of 659
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 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:
The following example uses the registered number (CLSID) to create an
instance of the Ad Rotator 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:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 39 of 659
Function Celsius(F)
Celsius = 5/9 * (F - 32)
End Function
Function Fahrenheit(C)
Fahrenheit = (9/5 * C) + 32
End Function
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:
degrees Fahrenheit is equivalent to
degrees Celsius is equivalent to
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 40 of 659
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:
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:
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:
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 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.
The date is
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 42 of 659
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 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 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:
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 tag in the previous example:
= 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.
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:
ASP does not instantiate an object that you declare with the tag
until that object is referenced by a script command from an .asp file. The
Server.CreateObject method instantiates the object immediately. Thus,
the tag offers better scalability than the Server.CreateObject
method for session-scope objects.
Giving an Object Application Scope
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 43 of 659
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 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 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 tag to create an application-scope
instance of the Ad Rotator 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:
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:
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:
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 44 of 659
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 tag or the Server.CreateObject method
to store objects marked Both in the Application object. You must use
the HTML 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 tag or the Server.CreateObject method to
store objects in the Session object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 45 of 659
For more information on threading models and their implications for
component performance, refer to Building Components for ASP.
Sending Content to the Browser
This is preliminary documentation for IIS 5.0 and is subject to change.
As a script in an ASP page is processed, any text or graphics not enclosed
within ASP delimiters or 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:
Welcome to the Overview Page."
Else
Response.Write "Welcome Back to the Overview Page."
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:
Welcome to the Overview Page.
Welcome Back to the Overview Page.
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 "" & Request.Form("FirstName") _
& "" & Request.Form("LastName") & ""
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 46 of 659
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:
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 47 of 659
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 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:
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 48 of 659
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:
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 49 of 659
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:
.
.
.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 50 of 659
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:
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:
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 51 of 659
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.
Choose the channels you want.
Movies
Sports
The script in Chan.cdx builds the channel definitions based on the form
values submitted with the request.
"" Then %>
channel definition statements for the movie pages
"" Then %>
channel definition statements for the sports pages
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 52 of 659
Including Files
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 53 of 659
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.
" -->
Scripts commands and procedures must be entirely contained within the
script delimiters , the HTML tags and , or
the HTML tags and . 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:
Next
%>
The following script, however, would work:
Note If the file that your ASP script includes contains a large number of
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 54 of 659
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 tags. For example, the following script includes
a file (by means of a relative path) that can be executed by the server:
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
tags when including by this method; use another set of tags to
add such logic.
Managing Sessions
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 55 of 659
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 tag to instantiate an object with
session scope. See Using Components and Objects for more
information about using the 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.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 56 of 659
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
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 57 of 659
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:
To retrieve information from the Session object, access the named entry.
For example, to display the current value of Session("FirstName"):
Welcome
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.
This is the text version of the page.
This is the multimedia version of the page.
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
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:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 58 of 659
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:
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:
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 59 of 659
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 tag:
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:
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:
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:
Similarly, to retrieve a key value from an indexed cookie, use the key name.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 60 of 659
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:
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:
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 61 of 659
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.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 62 of 659
the tag.
? Serialize execution with other session requests.
To configure an .asp file as sessionless, use the following:
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 63 of 659
(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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 64 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 65 of 659
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 66 of 659
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:
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.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 67 of 659
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 tag to your .asp file or
Global.asa file to declare the ADO type library:
To remove specific records from a database table, use the SQL DELETE
command. The following script removes all rows from the Customers table
where the last name is Smith:
Note You must be careful when using the SQL DELETE command. A
DELETE command without an accompanying WHERE clause will delete all
rows from a table. Be sure to include a SQL WHERE clause, which specifies
the exact rows to be deleted.
Using the Recordset Object for Manipulating
Results
For retrieving data, examining results, and making changes to your
database, ADO provides the Recordset object. As its name implies, the
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 68 of 659
Recordset object has features that you can use, depending on your query
constraints, for retrieving and displaying a set of database rows, or records.
The Recordset object maintains the position of each record returned by a
query, thus enabling you to step through results one item at a time.
Retrieving a Record Set
Successful Web data applications employ both the Connection object, to
establish a link, and the Recordset object, to manipulate returned data.
By combining the specialized functions of both objects you can develop
database applications to carry out almost any data handling task. For
example, the following server-side script uses the Recordset object to
execute a SQL SELECT command. The SELECT command retrieves a
specific set of information based on query constraints. The query also
contains a SQL WHERE clause, used to narrow down a query to a specific
criterion. In this example, the WHERE clause limits the query to all records
containing the last name Smith from the Customers database table.
"
rstCustomers.MoveNext
Loop
%>
Note that in the previous example, the Connection object established the
database connection, and the Recordset object used the same connection
to retrieve results from the database. This method is advantageous when
you need to precisely configure the way in which the link with the database
is established. For example, if you needed to specify the time delay before
a connection attempt aborts, you would need to use the Connection object
to set this property. However, if you just wanted to establish a connection
using ADO's default connection properties, you could use Recordset
object's Open method to establish a link:
"
rstCustomers.MoveNext
Loop
%>
When you establish a connection using the Recordset object's Open
method to establish a connection, you are implicitly using the Connection
object to secure the link. For more information, see Microsoft ActiveX Data
Objects (ADO) documentation available from the Microsoft Universal Data
Access Web site at http://www.microsoft.com/data/.
Note To significantly improve the performance of your ASP database
applications, consider caching the recordset in Application state. For more
information, see Caching Data.
It is often useful to count the number of records returned in a recordset.
The Open method of the Recordset object enables you to specify an
optional cursor parameter that determines how the underlying provider
retrieves and navigates the recordset. By adding the adOpenKeyset cursor
parameter to the statement used to execute the query, you enable the
client application to fully navigate the recordset. As a result, the
application can use the RecordCount property to accurately count the
number of records in the recordset. See the following example:
= 5 then
Response.Write "We've received the following " & rs.RecordCount & " new orders"
Response.Write rs("Quantity") & ""
Response.Write rs("DeliveryDate") & ""
rs.MoveNext
Loop
Else
Response.Write "There are less than " & rs.RecordCount & " new orders."
End If
rs.Close
%>
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 70 of 659
Improving Queries with the Command Object
With the ADO Command object you can execute queries in the same way
as queries executed with the Connection and Recordset object, except
that with the Command object you can prepare, or compile, your query on
the database source and then repeatedly reissue the query with a different
set of values. The benefit of compiling queries in this manner is that you
can vastly reduce the time required to reissue modifications to an existing
query. In addition, you can leave your SQL queries partially undefined, with
the option of altering portions of your queries just prior to execution.
The Command object's Parameters collection saves you the trouble of
reconstructing your query each time you want to reissue your query. For
example, if you need to regularly update supply and cost information in
your Web-based inventory system, you can predefine your query in the
following way:
Important ADO parameters, such as adCmdText, are simply variables,
this means that before using an ADO parameter in a data access script you
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 71 of 659
need to define its value. Since ADO uses a large number of parameters, it
is easier to define parameters by means of a component type library, a file
containing definitions for every ADO parameter and constant. For details
about implementing ADO's type library, see the Using Constants section of
the Using Variables and Constants topic.
In the previous example, you will note that the script repeatedly constructs
and reissues a SQL query with different values, without having to redefine
and resend the query to the database source. Compiling your queries with
the Command object also offers you the advantage of avoiding problems
that can arise from concatenating strings and variables to form SQL
queries. In particular, by using the Command object's Parameter
collection, you can avoid problems related to defining certain types of
string, date, and time variables. For example, SQL query values containing
apostrophes (') can cause a query to fail:
strSQL = "INSERT INTO Customers (FirstName, LastName) VALUES ('Robert','O'Hara')"
Note that the last name O'Hara contains an apostrophe, which conflicts
with the apostrophes used to denote data in the SQL VALUES keyword. By
binding the query value as a Command object parameter, you avoid this
type of problem.
Combining HTML Forms and Database Access
Web pages containing HTML forms can enable users to remotely query a
database and retrieve specific information. With ADO you can create
surprisingly simple scripts that collect user form information, create a
custom database query, and return information to the user. Using the ASP
Request object, you can retrieve information entered into an HTML form
and incorporate this information into your SQL statements. For example,
the following script block inserts information supplied by an HTML form into
a table. The script collects the user information with the Request object 's
Form collection.
For more information about forms and using the ASP Request object, see
Processing User Input.
Managing Database Connections
One of the main challenges of designing a sophisticated Web database
application, such as an online order entry application that services
thousands of customers, is properly managing database connections.
Opening and maintaining database connections, even when no information
is being transmitted, can severely strain a database server's resources and
result in connectivity problems. Well designed Web database applications
recycle database connections and compensate for delays due to network
traffic.
Timing Out a Connection
A database server experiencing a sudden increase in activity can become
backlogged, greatly increasing the time required to establish a database
connection. As a result, excessive connection delays can reduce the
performance of your database application.
With the Connection object's ConnectionTimeout you can limit the
amount of time that your application waits before abandoning a connection
attempt and issuing an error message. For example, the following script
sets the ConnectionTimeout property to wait twenty seconds before
cancelling the connection attempt:
Set cnn = Server.CreateObject("ADODB.Connection")
cnn.ConnectionTimeout = 20
cnn.Open "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\Inventory.mdb"
The default for the ConnectionTimeout property is 30 seconds.
Note Before incorporating the ConnectionTimeout property into your
database applications, make sure that your connection provider and data
source support this property.
Pooling Connections
Connection pooling enables your Web application to use a connection from
a pool, or reservoir of free connections that do not need to be
reestablished. After a connection has been created and placed in a pool,
your application reuses that connection without having to perform the
connection process. This can result in significant performance gains,
especially if your application connects over a network or repeatedly
connects and disconnects. In addition, a pooled connection can be used
repeatedly by multiple applications.
OLE DB Session Pooling
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 73 of 659
OLE DB has a pooling feature, called session pooling, optimized for
improving connectivity performance in large Web database applications.
Session pooling preserves connection security and other properties. A
pooled connection is only reused if matching requests are made from both
sides of the connection. By default, the OLE DB providers for Microsoft SQL
server and Oracle support session pooling. This means that you do not
have to configure your application, server, or database to use session
pooling. However, if your provider does not support session pooling by
default, you need to create a registry setting to enable session pooling. For
more information about session pooling, see the OLE DB 2.0 Software
Development Kit (SDK) documentation.
ODBC Connection Pooling
If you want your ODBC driver to participate in connection pooling you must
configure your specific database driver and then set the driver's CPTimeout
property in the Windows registry. The CPTimeout property determines the
length of time that a connection remains in the connection pool. If the
connection remains in the pool longer than the duration set by CPTimeout,
the connection is closed and removed from the pool. The default value for
CPTimeout is 60 seconds.
You can selectively set the CPTimeout property to enable connection
pooling for a specific ODBC database driver by creating a registry key with
the following settings:
\HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\driver-name\CPTimeout = timeout
(REG_SZ, units are in seconds)
For example, the following key sets the connection pool timeout to 180
seconds (3 minutes) for the SQL Server driver.
\HKEY_LOCAL_MACHINE\SOFTWARE\ODBC\ODBCINST.INI\SQL Server\CPTimeout = 180
Note By default, your Web server activates connection pooling for SQL
Server by setting CPTimeout to 60 seconds.
Using Connections Across Multiple Pages
Although you can reuse a connection across multiple pages by storing the
connection in ASP's Application object, doing so may unnecessarily keep
open a connection open, defeating the advantages of using connection
pooling. If you have many users that need to connect to the same ASP
database application, a better approach is to reuse a database connection
string across several Web pages by placing the string in ASP's Application
object. For example, you can specify a connection string in the Global.asa
file's Application_OnStart event procedure, as in the following script:
Application("ConnectionString") = "Provider=Microsoft.Jet.OLEDB.4.0;Data Source=C:\Data\In
Then in each ASP file that accesses the database, you can write
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 74 of 659
to create an instance of the connection object for the page, and use the
script
cnn.Open Application("ConnectionString")
to open the connection. At the end of the page, you close the connection
with
cnn.Close
In the case of an individual user who needs to reuse a connection across
multiple Web pages, you may find it more advantageous to use the
Session object rather than the Application object for storing the connection
string.
Closing Connections
To make the best use of connection pooling, explicitly close database
connections as soon as possible. By default, a connection terminates after
your script finishes execution. However, by explicitly closing a connection in
your script after it is no longer needed, you reduce demand on the
database server and make the connection available to other users.
You can use Connection object's Close method to explicitly terminate a
connection between the Connection object and the database. The following
script opens and closes a connection:
Understanding Transactions
This is preliminary documentation for IIS 5.0 and is subject to change.
Business applications frequently need to be able to run scripts and
components within transactions. A transaction is a server operation that
succeeds or fails as a whole, even if the operation involves many steps (for
example, ordering, checking inventory, and billing). You can create server-
side scripts that run within a transaction so that if any portion of the script
fails, the entire transaction is aborted.
ASP transaction processing is based on Component Services transactioning
environment, a transaction processing system for developing, deploying,
and managing high performance, scalable, and robust enterprise, Internet,
and intranet server applications. This transactioning environment defines
an application programming model for developing distributed, component-
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 75 of 659
based applications. It also provides a run-time environment for deploying
and managing these applications.
The functionality required to create transactional scripts is built into your
Web server. If you install Component Services, you can also package
components so they run within transactions.
About Transactions
A transaction is an operation that succeeds or fails as a whole. Transaction
processing is used to update databases reliably. When you are making
many related changes to a database or updating several databases at
once, you want to ensure that all of the changes are correctly executed. If
any of the changes fail, you want to restore the original state of the
database tables.
Without Component Services, you would have to write your scripts and
components to manually track the requested changes and restore data if
any changes failed. With Component Services, you simply declare your
scripts and components to require transactions and let Component Services
handle the transaction coordination. Transaction processing applies only to
database access; Component Services cannot roll back changes to the file
system or changes to other, nontransactional resources. The database your
application accesses must be supported by Component Services. Currently
Component Services supports SQL Server and any database that supports
the XA protocol from the X/Open consortium. Component Services will
continue to expand its support for other databases in the future.
Using the Server.Transfer and Server.Execute methods a transaction can
span multiple ASP pages. If a script contains the @TRANSACTION directive,
with the value specified as Required, and the script is called by either the
Server.Transfer or Server.Execute method, then the script will continue
the transaction of the calling .asp file if the calling .asp file was
transacted. If the calling .asp file was not transacted, the called .asp file
will then automatically create a new transaction.
For example, the following script initiates a transaction:
However, following script calls another script that also initializes a
transaction:
However, the interaction between the two scripts would constitute only a
single transaction. For more information about writing scripts with
Server.Transfer and Server.Execute, see Sending Content to the
Browser.
Declaring a Transactional Script
When you declare a page to be transactional, any script commands and
objects used on the page are run under the same transaction context.
Component Services handles the details of creating the transaction and
determining whether the transaction succeeds (commits) or fails (aborts).
To declare a page transactional, add the @TRANSACTION directive to the
top of the page:
For more information on the value argument, see the @TRANSACTION
directive reference.
The @TRANSACTION directive must be the very first line on the page,
otherwise an error is generated. You must add the directive to each page
that should be run under a transaction. The current transaction ends when
the script finishes processing.
Most applications only require transaction context for certain operations.
For example, an airline site might use transactional scripts for ticket
purchasing and seat assignments. All other scripts could be safely run
without a transaction context. Because transactions should be used only for
pages that need transaction processing, you cannot declare an application's
Global.asa file as transactional.
If a transaction is aborted, Component Services rolls back any changes
made to resources that support transactions. Currently, only database
servers fully support transactions because this data is the most critical to
enterprise applications. Component Services does not roll back changes to
files on a hard disk, ASP session and application variables, or collections.
You can, however, write scripts that restore variables and collections by
writing transaction events, as described later in this topic. Your script can
also explicitly commit or abort a transaction if an operation such as writing
data to a file fails.
Committing or Aborting a Script
Because Component Services tracks transaction processing, it determines
whether a transaction has completed successfully or failed. A script can
explicitly declare that it is aborting a transaction by calling
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 77 of 659
ObjectContext.SetAbort. For example, your script might abort a
transaction if it receives an error from a component, if a business rule is
violated (for example, if the account balance falls below 0), or if a
nontransactional operation (such as reading from or writing to a file) fails.
The transaction is also aborted if the page times out before the transaction
is completed.
Writing Transaction Events
A script itself cannot determine whether a transaction has succeeded or
failed. However, you can write events that are called when the transaction
commits or aborts. For example, suppose you have a script that credits a
bank account, and you want to return different pages to the user depending
on the status of the transaction. You can use the OnTransactionCommit
and OnTransactionAbort events to write different responses to the user.
Welcome to the online banking service
Thank you. Your transaction is being processed.
Thank you. Your account has been credited.
We are unable to complete your transaction.
Registering a Component in Component
Services Manager
To participate in a transaction, a component must be registered in a COM+
application and must be configured to require a transaction. For example, if
your script processes orders by calling a component that updates an
inventory database and a component that updates a payment database,
you would want both components to run under a transaction context.
Component Services ensures that if either component fails, the entire order
is rolled back and neither database is updated. Some components do not
require transactions; for example, the Ad Rotator component has no need
of transactions.
You use Component Services Manager to register and configure a
transactional component. Components must be registered in an COM+
application. Do not put your components in the IIS in-process COM+
application; instead, create your own COM+ application. Generally, you
should put all your components in one Library application. Components in
Library applications can be used by multiple ASP applications and are run in
the ASP application process.
You can also register transactional components in a Server application, a
COM+ application that always runs in a separate process on the server. You
use Server applications for your transactional components if you want to
use role-based security or if you want your components to be accessible
from applications on remote computers.
You must have Component Services installed to use Component Services
Manager.
Object Scope
Generally, you should not store objects created from an COM component in
the ASP Application or Session objects. COM objects are deactivated when
the transaction is completed. Because the Session and Application objects
are intended for object instances that can be used across multiple ASP
pages, you should not use them to hold objects that will be released at the
end of a transaction.
An ASP script is the root, or start, of a declared transaction. Any COM
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 79 of 659
object used on a transactional ASP page is considered part of the
transaction. When the transaction is completed, COM objects used on the
page are deactivated, including objects stored in the Session or
Application object. Subsequent attempts to call the session-scope or
application-scope object from another transactional page will fail.
Queuing Transactions
Updates to a database on a remote server could delay or abort the
completion of a transaction due to network delays or failures. Because all
portions of a transaction must be committed, your application might be
held up waiting for the commit or abort message from the remote server or
might abort a transaction because the database update could not be sent.
For updates that must be completed simultaneously, it is appropriate to
abort or even delay the completion of the transaction until all participants
in the transaction can commit. For example, an airline ticket-ordering
application should complete both the debit to a customer's bank account
and the credit to the airline's bank account simultaneously. If an update is
integral to a transaction but could occur later than the other updates, you
might prefer not to keep the customer waiting for the completion of the
update. For example, a transaction to order an airline ticket might also
send a special meal request to a food services vendor or update the
customer's mileage. These activities must be completed, but could be
completed later.
You can use Message Queuing Services to bundle an update or set of
updates into a transactional message that is delivered to a remote server.
Message Queuing Services guarantees that updates will be delivered to the
remote server, even if the network is currently unavailable. Your application
receives a commit message and can continue with the transaction.
Debugging ASP Scripts
This is preliminary documentation for IIS 5.0 and is subject to change.
Regardless of your level of experience, you will encounter programmatic
errors, or bugs, that will prevent your server-side scripts from working
correctly. For this reason, debugging, the process of finding and correcting
scripting errors, is crucial for developing successful and robust ASP
applications, especially as the complexity of your application grows.
The Microsoft Script Debugger Tool
The Microsoft® Script Debugger is a powerful debugging tool that can help
you quickly locate bugs and interactively test your server-side scripts. With
Script Debugger, which also works with Windows Internet Explorer
version 3.0 or later, you can:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 80 of 659
? Run your server-side scripts one line at a time.
? Open a command window to monitor the value of variables, properties,
or array elements, during the execution of your server-side scripts.
? Set pauses to suspend execution of your server-side scripts (using
either the debugger or a script command) at a particular line of script.
? Trace procedures while running your server-side script.
Note You can use the debugger to view scripts and locate bugs, but not
to directly edit your scripts. To fix bugs, you must edit your script with an
editing program, save your changes, and run the script again.
Enabling Debugging
Before you can begin debugging your server-side scripts, you must first
configure your Web server to support ASP debugging.
After enabling Web server debugging, you can use either of the following
methods to debug your scripts:
? Manually open Script Debugger to debug your ASP server-side scripts.
? Use Internet Explorer to request an .asp file. If the file contains a bug
or an intentional statement to halt execution, Script Debugger will
automatically start, display your script, and indicate the source of the
error.
Scripting Errors
While debugging your server-side scripts you might encounter several types
of errors. Some of these errors can cause your scripts to execute incorrectly,
halt the execution of your program, or return incorrect results.
Syntax Errors
A syntax error is a commonly encountered error that results from incorrect
scripting syntax. For example, a misspelled command or an incorrect
number of arguments passed to a function generates an error. Syntax errors
can prevent your script from running.
Run-Time Errors
Run-time errors occur after your script commences execution and result
from scripting instructions that attempt to perform impossible actions. For
example, the following script contains a function that divides a variable by
zero (an illegal mathematical operation) and generates a run-time error:
Result = Findanswer(15)
Document.Write ("The answer is " &Result)
Function Findanswer(x)
'This statement generates a run-time error.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 81 of 659
Findanswer = x/0
End Function
Bugs that result in run-time errors must be corrected for your script to
execute without interruption.
Logical Errors
A logical error can be the most difficult bug to detect. With logical errors,
which are caused by typing mistakes or flaws in programmatic logic, your
script runs successfully, but yields incorrect results. For example, a server-
side script intended to sort a list of values may return an inaccurate
ordering if the script contains a > (greater than) sign for comparing values,
when it should have used a
When you request this script, the debugger starts and automatically
displays the .asp file with the statement pointer indicating the location of
the Stop statement. At this point you could choose to inspect the values
assigned to variables before passing those variables to the component.
Important Remember to remove Stop statements from production .asp
files.
JScript Debugger Statement Debugging
To add breakpoints to your server-side scripts written in JScript, insert a
debugger statement before a suspect line of script. For example, the
following script includes a debugger statement that interrupts execution
and automatically starts Script Debugger each time the script loops through
a new value.
")
}
%>
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 83 of 659
Remember to remove debugger statements from production .asp files.
Note Do not confuse the debugger statement with the JScript break
statement. The break statement exits a currently running loop during
execution and does not activate the Microsoft Script Debugger, nor pause
execution.
Tips for Debugging Scripts
Aside from Script Debugger, a good set of debugging tips can greatly
reduce the amount of time you spend investigating the source of scripting
errors. Although most bugs result from obvious sources, misspelled
commands or missing variables, certain types of logical and execution
errors can be hard to find.
For more information about Microsoft Script Debugger, see the Microsoft
Scripting Technologies site at http://msdn.microsoft.com/scripting/.
Built-in ASP Objects
This is preliminary documentation for IIS 5.0 and is subject to change.
Active Server Pages provides built-in objects that make it easier for you to
gather information sent with a browser request, to respond to the browser,
and to store information about a particular user, such as user-selected
preferences. This topic briefly describes each object.
Application Object
You use the Application object to share information among all users of a
given application.
Request Object
You use the Request object to gain access to any information that is
passed with an HTTP request. This includes parameters passed from an
HTML form using either the POST method or the GET method, cookies, and
client certificates. The Request object also gives you access to binary data
sent to the server, such as file uploads.
Response Object
You use the Response object to control the information you send to a
user. This includes sending information directly to the browser, redirecting
the browser to another URL, or setting cookie values.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 84 of 659
Server Object
The Server object provides access to methods and properties on the
server. The most frequently used method is the one that creates an
instance of an COM component (Server.CreateObject). Other methods
apply URL or HTML encoding to strings, map virtual paths to physical paths,
and set the timeout period for a script.
Session Object
You 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 time the user is accessing pages in your application.
You can also use Session methods to explicitly end a session and set the
timeout period for an idle session.
ObjectContext Object
You use the ObjectContext object to either commit or abort a transaction
initiated by an ASP script.
ASPError Object
You can use the ASPError object to trap ASP error and return more
informative descriptions to users.
This is preliminary documentation for IIS 5.0 and is subject to change.
Application Object Response Object
Collections: Collections:
StaticObjects Cookies
Contents Properties:
Contents Collection Methods: Buffer
Remove CacheControl
RemoveAll Charset
Methods: ContentType
Lock Expires
Unlock ExpiresAbsolute
Events: IsClientConnected
Application_OnEnd PICS
Application_OnStart Status
Methods:
AddHeader
ObjectContext Object AppendToLog
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 85 of 659
ObjectContext Object
Methods: BinaryWrite
SetAbort Clear
SetComplete End
Events: Flush
OnTransactionAbort Redirect
OnTransactionCommit Write
Request Object Server Object
Collections: Properties:
ClientCertificate ScriptTimeout
Cookies Methods:
Form CreateObject
QueryString Execute
ServerVariables GetLastError
Properties: HTMLEncode
TotalBytes MapPath
Methods: Transfer
BinaryRead URLEncode
ASPError Object Session Object
ASPCode Collections:
Number StaticObjects
Source Contents
FileName Contents Collection Methods:
LineNumber Remove
Description RemoveAll
ASPDescription Properties:
CodePage
LCID
SessionID
Timeout
Methods:
Abandon
Events:
Session_OnEnd
Session_OnStart
Developing Web Applications
This is preliminary documentation for IIS 5.0 and is subject to change.
This guide provides an overview of Web application design and introduces the more advanced topics of
building components and ISAPI extensions, data access, Web-based transactions, and performance.
This section contains:
? Web Applications: An Overview: Introduces the IIS programming model.
? Design Decisions: Describes several key issues you should consider in designing web applications.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 86 of 659
? Accessing Data with ASP: Introduces data access from a Web page with Microsoft ® ActiveX®
Data Objects (ADO).
? Processing Transactions: Outlines how IIS and Component Services, available with Windows
2000 or later, work together to provide Web-based transactions.
? Security Ramifications for IIS Applications: Introduces the issues Web developers face when
accessing and providing secure data.
? Development Technologies: Reviews some of the more recent Web technologies, such as XML
and Dynamic HTML.
? Developing Scalable Web Applications: Describes the impact that Web application design
decisions can have on server performance.
? Building Components for ASP: Reviews the development cycle for building components to be
used by ASP.
? Developing ISAPI Extensions and Filters: Describes the Internet Server API (ISAPI) within the
IIS architecture, and provides guidelines for developing ISAPI extensions and filters.
Web Applications: An Overview
This is preliminary documentation for IIS 5.0 and is subject to change.
Open Internet standards have changed the architecture of distributed computing forever. The basic
language of the Web, HTML, has become a popular language for representing the elements of the user
interface. Cross-platform support for scripting languages and Java applets, as well as support for
embedded COM components, makes it possible to combine dynamic elements with static text for a
more interactive user experience. Web technologies aren't solely for use on the Internet, however. They
have been adapted for use by businesses to:
? Create an environment for component-based development.
? Enable distribution of applications throughout an enterprise.
? Create and customize new applications quickly.
? Update databases remotely by using an ordinary Web browser.
? Add transaction processing to Web applications.
? Provide business-to-business information sharing.
? Manage resources and enable remote system administration.
This section outlines general concepts that will assist you in building Web applications, such as the
following:
? Building on the Client/Server Architecture: Briefly outlines the history of the traditional client/server
design model.
? The New System Design: Introduces n-tier and distributed systems design, as an enhancement to
the client/server model.
? Microsoft Windows Distributed interNet Application Architecture: Outlines Microsoft Windows
DNA, the Microsoft architecture for building Web applications.
? Internet Information Services Architecture: Reviews the IIS components and programming model.
Building on the Client/Server Architecture
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 87 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
Before delving into the details of building a Web-based application, it might be helpful to review the
architectural model of the Web, and the roles of the browser and server in that model.
Typically, cooperating applications can be categorized as either a client or a server. The client application
requests services and data from the server, and the server application responds to client requests. Early
two-tier (client/server) applications were developed to access large databases, and incorporated the
rules used to manipulate the data with the user interface into the client application. The server's task was
simply to process as many requests for data storage and retrieval as possible.
Two-tier applications perform many of the functions of stand-alone systems: They present a user
interface, gather and process user input, perform the requested processing, and report the status of the
request. This sequence of commands can be repeated as many times as necessary. Because servers
provide only access to the data, the client uses its local resources to perform most of the processing. The
client application must contain information about where the data resides and how it is organized in the
database. Once the data has been retrieved, the client is responsible for formatting and displaying it to the
user.
One major advantage of the client/server model was that by allowing multiple users to simultaneously
access the same application data, updates from one computer were instantly made available to all
computers that had access to the server. However, as the number of clients increased, the server would
quickly become overwhelmed with client requests. Also, because much of the processing logic was tied
to a monolithic suite of applications, changes in business rules led to expensive and time-consuming
alterations to source code. Although the ease and flexibility of two-tier products continue to drive many
small-scale business applications, the need for faster data access and more rapid developmental timelines
has persuaded systems developers to seek out a new way of creating distributed applications.
The New System Design
This is preliminary documentation for IIS 5.0 and is subject to change.
Today's client/server applications resemble their ancestors so little that they have been given a new name,
the multi-tier application, also known as n-tier architecture. In this model, processing is distributed
between the client and the server, and business logic is captured in a middle tier. Most systems will
perform the following three main tasks, which correspond to three tiers, or layers, of the n-tier model:
Task Description
User interface and Labeled Tier 1 in the following graphic, this layer comprises the entire user
navigation experience. Not only does this layer provide a graphical interface so that users
can interact with the application, input data, and view the results of requests, it
also manages the manipulation and formatting of data once it arrives at the client.
In Web applications, the browser performs the tasks of this layer.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 88 of 659
Business logic Tier 2, between the interface and data services layers, is the domain of the
distributed application developer. Business logic, which captures the rules that
govern application processing, connects the user at one end with the data at the
other. The functions that the rules govern closely mimic everyday business tasks,
and can be a single task, or a series of tasks.
Data services Shown as Tier 3 in the following graphic, data services are provided by a
structured (SQL, Oracle database) or unstructured store (Microsoft ®
Exchange, Microsoft® Message Queue Services), which manages and provides
access to the application data. A single application may enlist the services of one
or more data stores.
The three-tier architecture isolates each major piece of functionality. The presentation is independent of
the processing rules and business logic, which in turn is separate from the data. This model requires much
more analysis and design up front, but greatly reduces maintenance costs and increases functional
flexibility in the long run. The following diagram depicts the Microsoft technologies that service the
various tiers in the new system design.
Microsoft Windows Distributed interNet
Application Architecture
This is preliminary documentation for IIS 5.0 and is subject to change.
Microsoft developed the Windows Distributed interNet Application Architecture (Windows DNA) as a
way to fully integrate the Web with the n-tier model of development. Windows DNA defines a
framework for delivering solutions that meet the demanding requirements of corporate computing, the
Internet, intranets, and global electronic commerce, while reducing overall development and deployment
costs.
Windows DNA architecture employs standard Windows-based services to address the requirements of
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 89 of 659
each tier in the multi-tiered solution: user interface and navigation, business logic, and data storage. The
various services are integrated through the Component Object Model (COM). The services used in
Windows DNA include:
? Dynamic HTML (DHTML)
? Active Server Pages (ASP)
? COM components
? Component Services
? Active Directory Services
? Windows® security services
? Microsoft® Message Queue Services
? Microsoft Data Access Components
Microsoft built Windows DNA using open protocols and public interfaces, making it easy for
organizations to integrate third-party products. In addition, by supporting industry-defined standards for
Internet computing, Windows DNA will make it easier for developers to respond to technology changes.
Some of the technologies recently added to the Windows DNA are outlined in the Development
Technologies section. The following diagram illustrates these technologies.
Internet Information Services Architecture
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 90 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
IIS is an integral part of the Windows DNA architecture. An important role of IIS is to link clients
accessing the system through the Hypertext Transfer Protocol (HTTP) to the other Windows DNA
services, such as DHTML, ASP, and so on. In addition, IIS includes a basic set of functionality that
systems developers can extend to define a customized application architecture.
This section contains:
? IIS Core Functionality: Describes the basic functionality that you can use to build Web
applications.
? IIS and Component Services: Outlines the functionality used to isolate, manage and coordinate
processing for transactional ASP applications.
? IIS Request Processing: Describes the evaluation procedure used to determine a request type.
The topics in this section describe this basic functionality, and define the relationship of IIS architecture to
the rest of the Windows DNA architecture. A general outline of how IIS processes HTTP requests is
also provided.
IIS Core Functionality
This is preliminary documentation for IIS 5.0 and is subject to change.
IIS defines a basic functionality that you can use to build Web applications. Active Server Pages (ASP)
and other Microsoft technologies have extended this basic functionality to create a rich environment for
application development. The basic server functionality is exposed through the Internet Server
Application Programmer Interface (ISAPI). ISAPI is described in detail in the Developing ISAPI
Extensions section.
The core functions which IIS provides include:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 91 of 659
? Establishing and maintaining HTTP connections.
? Reading HTTP requests and writing HTTP responses.
? Modifying HTTP headers.
? Obtaining client certificate information.
? Managing asynchronous connections.
? Mapping Uniform Resource Locators (URLs) to physical paths.
? Managing and running applications.
? Transmitting files.
ASP extends this functionality by providing a link to the COM architecture and thus the other participants
in Windows DNA. Similarly, you can extend the IIS architecture by defining a custom set of functions
using ISAPI. The relationship between the IIS core functionality, ASP, and extended architectures is
depicted in the following graphic:
IIS and Component Services
This is preliminary documentation for IIS 5.0 and is subject to change.
IIS and Component Services work together to form a basic architecture for building Web applications.
IIS uses the functionality provided by Component Services to:
? Isolate applications into distinct processes.
? Manage communication between COM components (including the ASP built-in objects).
? Coordinate transaction processing for transactional ASP applications.
Note In IIS version 4.0, Microsoft Transaction Server (MTS) provided transaction support. In IIS 5.0,
and Windows 2000, Component Services provides all the transaction support of MTS, in addition to a
number of other component development and deployment features.
IIS defines Web applications as a collection of resource files that are grouped into a logical namespace.
By grouping resources into applications you gain the ability to share data throughout the namespace and
to run the application in an isolated process.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 92 of 659
Internally, IIS coordinates isolated applications through an object known as the Web Application
Manager. This object includes a public interface (IWAMAdmin) that you can use to create programs
for administering Web applications. When you run a Web application in an isolated process, IIS uses
Component Services to coordinate concurrent access to resources and pass context information
between COM components.
IIS uses the Component Services ObjectContext object to give COM components that are called by
ASP access to the ASP built-in objects. For example, if you were building a COM component in Visual
Basic that needed to access a form submission from an HTML file, you could use the following code:
Dim objObjectContext As ObjectContext
Dim vntIn As Variant
Set objObjectContext = GetObjectContext ()
vntIn = objObjectContext.Item("Request").Form("Field1")
Component Services uses ObjectContext to maintain information about a particular instance of a COM
component. When IIS compiles the ASP script, it calls Component Services to create an
ObjectContext for tracking information about the ASP script. The ObjectContext includes an identity
property that uniquely identifies instance of the ASP script. For example, if your ASP script creates
instances of COM components that have been registered with Component Services, each of these
objects will be associated with the ASP script's ObjectContext. Similarly, when you create a
transactional ASP script with the @Transaction directive, Component Services is notified and a new
transaction is started. From that point onwards, Component Services will coordinate the updating of any
resources that are under its control. Component Services guarantees the transaction's integrity by
tracking any changes made to persisted resources.
Note In IIS version 4.0, transaction support was provided by Microsoft Transaction Server (MTS).
For IIS 5.0, and Windows 2000, Component Services provides all the transaction support of MTS, in
addition to a number of other features.
For further information on isolating and managing applications, see Defining Application Boundaries.
For further information on transaction processing, see Processing Transactions, Understanding
Transactions.
IIS Request Processing
This is preliminary documentation for IIS 5.0 and is subject to change.
When IIS receives an HTTP request, it evaluates the URL to determine if the request is for static content
(HTML), or dynamic content (ASP or ISAPI).
Request Processing Actions
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 93 of 659
Request Action
HTML Page IIS returns the page immediately in HTML format.
ISAPI extension IIS loads the ISAPI DLL (if it is not already running) and
the request is sent to the extension through the
Extension_Control_Block data structure.
File name extension mapped to a IIS loads the appropriate DLL file and presents the request
particular ISAPI extension through the Extension_Control_Block data structure.
The .asp extension, for example, is mapped to Asp.dll, so
that all requests for files with an .asp extension will be
directed to Asp.dll.
CGI application IIS creates a new process. IIS will then provide the query
string and other parameters that are included with the
request through the environment and standard input
(STDIN) handle for the process.
Design Decisions
This is preliminary documentation for IIS 5.0 and is subject to change.
Although there is a rich and continually expanding set of tools for Web application development, the
basic development cycle is similar to developing desktop applications in many respects. This section
focuses on design decisions that are unique to Web applications.
This section contains:
? Defining Application Boundaries: Describes the necessary steps needed to assemble you ASP
pages into a single Web application.
? Controlling Application Flow: Outlines the issues to keep in mind when designing how you will
control the flow of Web applications.
? Accommodating International Clients: Contains information relating to the localization of your Web
site into various languages.
Defining Application Boundaries
This is preliminary documentation for IIS 5.0 and is subject to change.
An ASP-based application is a collection of ASP pages and COM components. When you define an
application, you use the Internet Information Services snap-in to designate the application's starting-point
directory in your Web site. Every file and folder under the starting-point directory in your Web site is
considered part of the application . Therefore, you can use the directory structure to form application
boundaries that define the scope of an application. You can have more than one application per Web
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 94 of 659
site, and each application can be configured differently.
One of the most important tasks you face in developing your Web application is to determine how to
assemble your ASP pages into a single Web application. IIS uses the concept of a namespace to
identify applications. A namespace is a way of associating an area of memory with an easily recognized
name; it identifies a group of files as belonging together. IIS uses virtual directories to define namespaces
for applications. The following diagram illustrates this concept.
Scripts and ISAPI extension DLLs within an application boundary form a unit of isolation, which always
runs in a single server process. IIS administrators can either run applications in the same server process
as IIS, a pooled process (the default process), or they can isolate the application by running it in an
isolated process, which is particularly helpful during development and testing.
See Simplify Development With Process Isolation to learn more about isolating applications and
components.
In addition to running applications in a single process, you can also separate your components from .asp
files that call them, by running them in an isolated or pooled process. An isolated process would be a
good configuration for debugging your components. A pooled process provides superior protection for
the server without the overhead involved in maintaining a large number of isolated processes. To run your
components in their own process, you must create a new application and add your components to it with
the Component Services Manager.
Five possible configurations for applications are:
1. Put all .asp files and components in the same process as IIS; this configuration provides the fastest
performance.
2. Put all .asp files and components in one process and IIS in an another process.
3. Put all .asp files and components in a pooled process, IIS in another process, and special
applications in an isolated process.
4. Put all .asp files and IIS in one process, and components in another process.
5. Put all .asp files in one process, components in another process, and IIS in a third process.
Because process boundaries represent different areas of memory, calling between them requires some
extra work by IIS. The mechanism for calling across process boundaries is known as marshaling.
Marshaled calls are slower than calls within a single process. Pooled and isolated applications, therefore,
do not perform as well as applications sharing the IIS process.
Simplify Development With Process Isolation
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 95 of 659
In earlier versions of IIS, all ISAPI applications (including ASP) shared the resources and memory of the
server process. Although this provided fast performance, unstable components could cause the server to
crash—not an acceptable behavior for a mission-critical application such as IIS. To make matters worse,
in-process components couldn't be unloaded unless the server was restarted—which meant that
modifying existing components would affect all sites that shared the same server, whether they were
directly affected by the upgrade or not.
Thanks to close integration with Component Services, applications in IIS version 4.0 and above can be
started in an isolated process. There are two reasons for doing this:
1. Component development; rather than taking down the entire server to update a single component,
you can stop and restart just a single application. In earlier versions of IIS, to add an updated
component to an application, or an entirely new application, you previously had to stop the Web
service, replace the old DLL with your new version in its shared location on the server, and restart
the Web service again. Now with an isolated process, you can update a production Web site
without shutting down all applications.
2. Process isolation, which limits the effects of a crash to the single application that caused it. In
addition to protecting your primary Web service from the crash, the application can be configured
to restart automatically as often as you like. In the case of an application fatal error, the
application's process is automatically terminated. Because the application is running in the
Component Services system process, all transactions in progress are aborted. The Windows
event log stores a record of the event, and Component Services restarts the application. The only
clients affected by the failure are those with outstanding requests to that specific application.
Process Isolation
If you decide to run your application as a separate process, or with other applications in a single pooled
process, you will need to select High (Isolated) or Medium (Pooled) from the Application
Protection drop-down list on the Home Directory or Virtual Directory property sheet. You should
first create an application for your application starting-point directory, if you haven't already done so.
Components that will run in the new process must be installed into the appropriate COM application.
For more information, see the Component Services documentation.
Out-of-Process Components
This is preliminary documentation for IIS 5.0 and is subject to change.
Note that out-of-process applications are different from out-of-process components, which are
executables that are run in a separate process. When Server.CreateObject is used to launch an
executable, the following error may occur:
Server object error 'ASP 0196'
Cannot launch out of process component
/HR/report.asp, line 16
This error is the result of a safety mechanism in ASP that prevents the unauthorized launching of
executables from within ASP. Not all executables are safe to use on the server, and may pose security
risks as well. Because in-process components are faster, more secure, and can be hosted by Component
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 96 of 659
Services, they are much better suited for server-side use.
If you want to enable the use of out-of-process components for testing and development purposes, you
must first set the AspAllowOutOfProcComponents metabase property to TRUE. This metabase
setting is accessible on both the IIsWebService and the IIsWebVirtualDir IIS Admin Objects.
? Take note that if you set the AspAllowOutOfProcComponents property to TRUE on the
IIsWebService object, all in-process applications will be able to launch executables from script.
An in-process application is a directory that has been marked as an application starting point, by
having the Low (IIS Process) or Medium (Pooled) option selected.
? If you set the AspAllowOutOfProcComponents property to TRUE on the IIsWebVirtualDir
object, and the application is marked to run in separate memory space (out of process), only the
affected application is allowed to launch executables from script. If the application is set to run in
process, the setting will have no effect.
The following ASP code demonstrates the steps required for setting the
AspAllowOutOfProcComponents parameter on the IIsWebService IIS Admin Object.
Note The user must have adequate permission to modify the metabase. If you attempt to modify the
metabase from an ASP script without sufficient privileges, you will encounter an error. In order to modify
the metabase from script, you must first log on as a user with administrative rights.
Important You will need to restart the Web service after making this change.
For more information about setting metabase properties using the IIS Admin Objects, see Using IIS
Admin Objects.
Security Considerations for Out-of-Process Applications
This is preliminary documentation for IIS 5.0 and is subject to change.
By default, out-of-process applications and components, including ISAPI extensions, are not able to
access metabase properties. This restriction is primarily for security reasons, to prevent unauthorized
changes to the metabase. If you want to allow out-of-process applications to access the metabase, you
must do one of the following:
? Give the IWAM_machinename account access to the metabase (this is probably a bad idea,
from a system security standpoint).
? Change the identity of the out-of-process COM application from the interactive user
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 97 of 659
(IUSR_machinename, by default) to a specific user account, and give that account access to the
metabase (this is also somewhat risky, but the risk is limited to a single application).
For more information on changing application identity, see the Component Services documentation in the
Platform SDK.
Controlling Application Flow
This is preliminary documentation for IIS 5.0 and is subject to change.
One of the primary choices of any application design is the pattern of execution. In a well-designed
application, the logic of converting inputs to outputs by using modular processing units is obvious. The
COM architecture and Active Server Pages (ASP) address this need for modular design to control the
flow of execution in the Windows DNA architecture.
This section outlines some of the more important issues to keep in mind when designing how you will
control the flow of your Web application. The topics included are:
? Application Control Techniques: Describes the different ways to affect the general flow of
execution.
? Coordinating Client/Server Processing: Outlines the design goals when you distribute processing
between the client and server.
Application Control Techniques
This is preliminary documentation for IIS 5.0 and is subject to change.
ASP provides six different ways to affect the general flow of execution. These six methods are depicted
in the following diagrams. The arrows in the diagrams represent the flow of execution.
Redirecting
Redirection is the process of diverting a request to another location. Redirecting requires a new request
to be sent to the server. However, in general, you should design your application to minimize the amount
of communication between the client and server. Many design problems that have been addressed by
redirecting in the past can now be accomplished by transferring, which does not initiate a new request.
See Coordinating Client/Server Processing for more information on this aspect of application design.
You can accomplish redirecting by using the Response.Redirect method.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 98 of 659
Transferring
The ability to transfer a request from one ASP page to another is introduced in IIS 5.0. Transferring is
similar to redirecting; however, it does not require that a new request be initiated. This is a much more
efficient way to control application flow. If you transfer the request to an ASP page outside of the
application boundary, the boundary will be temporarily extended to include the external ASP page. The
external ASP page will behave as if it were included within the application boundary of the calling ASP
page. Therefore, any objects or variables that have been given application scope will still be available in
the ASP page to which you have transferred. In addition to being faster than redirecting, transferring
preserves all of the ASP built-in objects from the original request, including form values from an HTTP
post.
You can accomplish transferring by using the Server.Transfer method.
Executing
The ability to execute a particular ASP script and return the result is introduced in IIS 5.0. Executing is
similar to a procedure call in most programming languages. This method of application flow control is
appropriate if you have developed an ASP application that accomplishes some function that you want to
incorporate, but have not built that function into a component.
You can accomplish executing by using the Server.Execute method.
Component Invocation
This is probably the most common way to control the flow of an application. The COM programming
model is integral to the Windows DNA, and should address the vast majority of design problems. Script
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 99 of 659
Components, a technology supported in IIS 5.0, make it easier to take existing scripts and convert them
to components.
You can accomplish component invocation by using the Server.CreateObject method. For more
information on script components, see Windows Script Components and Using Components and
Objects.
Exiting
Under normal circumstances you will want your ASP application to complete each line of script in the
page. There may be some circumstances, however, where you will need to simply end the response. For
example, if you have detected (by using the Response.IsClientConnected method) that the client is no
longer waiting for a response, you will want to terminate the ASP application.
You can accomplish exiting the ASP by using the Response.End method.
Procedural Processing
If you want to define subroutines or functions within your .asp file, you can do so by using the procedure
syntax that is appropriate for the scripting language you are using. For example, VBScript defines
subroutines with the Sub … End Sub syntax and functions with the Function … End Function syntax.
JScript, on the other hand, supports procedural processing through function calls. For more information
on subroutine processing, see Writing Procedures.
Coordinating Client/Server Processing
This is preliminary documentation for IIS 5.0 and is subject to change.
Web applications are, by their very nature, distributed. As clients increase their processing capability, the
degree to which you can distribute processing between the client and server increases. By distributing
some of the processing to the client you will increase your application's responsiveness. Distribution of
processing, however, also increases the complexity of your application design.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 100 of 659
You should keep in mind two design goals when you distribute processing between the client and server.
First, you want to minimize communication across the HTTP connection. Regardless how fast the
connection you have established is, local processing will always be faster. You should pass information
between the client and server only when absolutely necessary.
A second design goal is to expose only those server resources to the client that are absolutely necessary
to accomplish the processing task. Each request from the client should be fully qualified so that the server
does not have to respond to the client for further information and thereby increase roundtrips across the
HTTP connection. For example, if a client can completely describe its capabilities to the server when it
makes a request, the server can immediately send a response that matches those capabilities rather than
requesting further information from the client. This design concept can also be applied to the design of
Web applications that support database access. For example, if a client is checking the status of an
order, you should provide the client with a recordset that describes only that particular order, rather than
all the records in the orders table.
? Caching Data: Introduces a technique that you can use to minimize communication across the
HTTP connection.
? Client Capabilities: Describes functionality provides you with a design tool to help make client
requests fully qualified.
? Remote Data Binding with Remote Data Service: Explains a technique that you can use to limit
client access to appropriate data resources.
Caching Data
This is preliminary documentation for IIS 5.0 and is subject to change.
When clients access your ASP page, there are basically two ways to provide them with the information
they need:
? Your ASP page can either obtain information from server resources, such as from data that has
been persisted to a database, or
? Your ASP page can obtain information from within the application.
Retrieving data from a resource outside the application will require more processing steps, and will
therefore require more time than generating the data from within the application space.
If the data you are going to send to the browser has already been prepared by a previous request, your
application will be able to retrieve that data faster if you store it in a cache. This form of caching is called
output caching. Output caching is particularly suitable when you expect to return the same data in the
same format for many different requests. For example, one common task for developing an input form is
to gather persisted data as members of a drop-down list box. This is preferable to writing the entries
directly into the HTML page, because updates to the persisted data will automatically be reflected in the
form.
The following script is an example of output caching. In this example, the getSportsListBox function
creates a list box from persisted data. The list box is added to the application space so that clients can
access it more quickly than they could if they populated the list box on an individual basis. The example
assumes that a Data Source Name (DSN) called "Sports" is defined on the server.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 101 of 659
What is your favorite sport?
" + crlf;
SQL = "SELECT SportName FROM Sports ORDER BY SportName";
cnnSports = Server.CreateObject("ADODB.Connection");
cnnSports.Open("Sports", "WebUser", "WebPassword");
rstSports = cnnSports.Execute(SQL);
fldSportName = rstSports("SportName");
While (!rstSports.EOF)
{ SportsListBox = SportsListBox + " " + fldSportName + "" + crlf
SportsListBox = SportsListBox + ""
Application("SportsListBox") = SportsListBox
return SportsListBox;
}
%>
In some circumstances, your application will receive many different requests for the same data, but you
will need to change the presentation of that data for each request. In that case, you use input caching.
With input caching you save the data, but not the presentation of it. You accomplish this by caching the
data with a Dictionary object provided by VBScript, or with an ADO recordset.
The following example demonstrates caching data by adding a connectionless recordset to your
application. ASP scripts within the application space can then access the recordset rather than retrieve
the data from the database. The following two ASP scripts demonstrate this technique.
Excerpt from Global.asa:
is located in .
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 102 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 103 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 104 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 105 of 659
? 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:
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:
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:
Session.CodePage = 950
Sender = ReadMailHeader("Sender")
Found = FindFriend("Sender")
Session.CodePage = Session("OriginalCodePage")
If Found == TRUE
ReplyWithPersonalizedForm()
Else
ReplyWithBusinessForm()
%>
Setting the Locale Identifier
This is preliminary documentation for IIS 5.0 and is subject to change.
A locale is a set of user preference information related to the user's language. The locale determines how
dates and times are formatted, how items are alphabetically sorted, and how strings are compared. The
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 106 of 659
locale identifier (LCID) is a 32-bit value that uniquely defines a locale. ASP uses the default locale of
the Web server unless you specify a different locale for a particular script.
To set the locale identifier for an ASP page, use the @ LCID directive. For example, to set the locale to
Japanese, use the following locale identifier:
The @ LCID directive tells ASP the locale in which the script was authored. If you need to change the
locale for input to or output from the script, use the Session.LCID property.
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:
The Session.LCID property defaults to the @ LCID directive setting. Setting the value of
Session.LCID in a script overrides the default setting.
For more information on LCIDs see "International Features" in the "Windows Base Services" section.
Accessing Data with ASP
This is preliminary documentation for IIS 5.0 and is subject to change.
ASP offers the Web developer flexible, easy-to-use, scalable methods to interact with OLE DB
database providers for Internet or intranet applications. Using ASP and the Microsoft Data Access
Components (MDAC) not only means that you can initially develop a solution using Microsoft Access
and scale up to Microsoft SQL Server 6.5, but that you can access any other databases that have OLE
DB providers. With the additional power of Component Services, you can create highly scalable multi-
tier applications that support Web-based transactions.
This section contains:
? ADO Overview: Provides a brief overview of ActiveX® Data Objects.
? Remote Data Binding with Remote Data Service: Gives an introduction to Remote Data Services
and client-side data binding.
ADO Overview
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 107 of 659
ActiveX® Data Objects (ADO) provides a common programming model for any OLE DB data source;
it is essentially a collection of objects that expose the attributes and methods used to communicate with a
data source. ADO uses general OLE DB providers to accesse unique features of specific data sources; it
also uses native OLE DB providers, including a specific OLE DB provider that provides access to Open
Database Connectivity (ODBC) drivers. Designed to replace the need for all other high-level data access
methods, ADO can access relational, Indexed Sequential Access Method (ISAM), or hierarchical
databases, or any type of data source—as long as there is an ODBC-compliant driver.
ADO's ease of use, speed, and low memory overhead make it ideal for server-side scripting. In fact,
ADO is the recommended technology for data access for ASP applications. ADO can be called directly
from server-side scripts or from business components.
Unlike earlier data access methods, ADO does not require navigation through a hierarchy to create
objects; most ADO objects can be created independently, which allows greater flexibility in reusing
objects in different contexts and reduces memory consumption. ADO also takes advantage of ODBC
3.0 connection pooling for ODBC data sources, and session pooling for OLE DB providers. This
eliminates the need to continuously create new Connection objects for each user, which is very resource
intensive.
What ADO cannot do, however, is provide remote data to the client. Once the data has been retrieved
and sent to the browser, the user cannot easily manipulate it or make changes to it within the client
application. Data operations—including filtering and record modifications—must take place on the
server, where the actual data manipulation objects reside. If your application design requirements include
client manipulation of data, see Remote Data Binding with Remote Data Service.
OLE DB, the foundation of Microsoft's Universal Data Access model, is a set of COM interfaces that
provides a standard way for programs to access data. The way your application uses ADO functionality
will be partially determined by whether or not there is an OLE DB provider for the data. ADO is
designed to work with OLE DB, and in most instances your ADO components will communicate with
databases through OLE DB; you can also use ADO to communicate directly with the ODBC driver, if
no OLE DB provider is available. Using ADO through an OLE DB provider has an impact on the
following areas:
? Using Stored Procedures with ADO: Describes several key issues you should consider when
using stored procedures.
? Choosing the Client Networking Library for ADO:Explains the issues surrounding the selection of
a networking library and it's impact on database access speed.
For more information on ADO, see the ADO SDK . For performance information, see Data Access
Performance. To see examples of using ADO, see Database Connectivity under the ASP Script
Examples in ASP Samples.
Using Stored Procedures with ADO
This is preliminary documentation for IIS 5.0 and is subject to change.
A stored procedure is a precompiled collection of SQL statements and optional control-of-flow
statements stored under a name and processed as a unit. Creating stored procedures with connection
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 108 of 659
pooling enabled can present some special considerations. For example, creating temporary stored
procedures for prepared SQL statements is an option that is configurable from the ODBC Data Source
Administrator. The default for this setting is "On" for the SQL Server 2.65 and 3.5 drivers, which means
that when a SQL statement is prepared, a temporary stored procedure is created and compiled. When
the prepared command is called by one of the ADO methods, the temporary stored procedure is
executed, saving the overhead of parsing and compiling the SQL statement. This feature can improve the
performance of your application, if it is used properly. If your SQL statement is going to be executed
more than twice, or if it will be run more than once and contain parameters, the statement should be
prepared. Keep in mind that to prepare a SQL statement it must be compiled the first time you run it,
and that the preparation is lost once you disconnect from the database.
When connection pooling is enabled, you have to decide when temporary stored procedures should be
deleted. With the SQL Server 2.65 driver, stored procedures will be released when the connection is
released. With the SQL Server 3.5 driver, you have the option of deleting them either when the
connection is released, or as appropriate while connected.
There can be storage problems with temporary stored procedures and connection pooling. If you are
using the default setting, you risk of running out of space in TempDB, where temporary stored
procedures are created and stored. When connection pooling is enabled, a connection is made to the
database, but when the client is finished with it and releases it, the connection goes back into the pool.
The connection is not released and the stored procedures are not deleted from the TempDB—even
though they are no longer associated with a client and will never be called again.
Thus, when running the SQL Server 2.65 driver, it may be advisable to disable the creation of stored
procedures on preparation when connection pooling is enabled. With the SQL Server 3.5 driver, the
option to create temporary stored procedures should be disabled or set to "disconnect and as
appropriate" when running connection pooling. Setting this option to "disconnect and as appropriate"
means that the ODBC SQL Server driver will drop the connection when the OLE DB ICommand
object that created the temporary stored procedure is released. If your client code uses ADO, the stored
procedure would be released when the ADODB.Recordset and ICommand object are closed.
Choosing the Client Networking Library for ADO
This is preliminary documentation for IIS 5.0 and is subject to change.
When ADO communicates with a database it does so through a networking library. Your selection of a
networking library will be determined by the data provider and system configuration, and can have a
significant impact on database access speed. For example, if you are accessing data from a Microsoft
SQL Server database your access speed, in general, will be faster if you use the TCP/IP networking
library. However, if SQL Server is running on the same computer as IIS, you may find some
performance improvements by using the Named Pipes networking library.
You can set the networking library for a DSN by using the Data Sources (ODBC) option in Control
Panel. Once you set a library for one connection, it will become the default library for all subsequent
connections, as well as for any DSN-less connections that your application may use.
Note If you change the network library from Named Pipes to TCP/IP, be sure not to remove Named
Pipes as one of the options, because SQL Server Enterprise Manager relies on this library.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 109 of 659
Remote Data Binding with Remote Data
Service
This is preliminary documentation for IIS 5.0 and is subject to change.
If your Web application provides clients with the ability to access data, you can distribute the processing
of that data between the client and the server with Remote Data Service (RDS). Client-side RDS
components send queries to the Web server. The server-side RDS components process these requests
and send them to the Database Management System (DBMS) by use of a business object. The DBMS
responds to the request, sending back the data to the Web server. The RDS components on the Web
server transform that data into an ADO Recordset object. The data is parsed for transport to the client
and sent back across the network to the client computer where it may be displayed in data-aware
controls, such as a text or combo box.
The two main objects that you will use to accomplish remote data binding are RDS.DataControl and
RDS.DataFactory. First, create a copy of the RDS.DataControl object on the client computer by
inserting an object tag in an HTML page. For example:
The preceding object tag creates an instance of the RDS.DataControl object and sets the SQL,
Connect, and Server parameters for it. If you add this tag to an HTML page, you could then bind the
data control object to multiple data-aware controls on the HTML page. For example, the following
HTML tags display an HTML table that is bound to the above RDS.DataControl object.
ID
Author
The object on the server that communicates with the RDS.DataControl object is either the
RDS.DataFactory, or a business component. You can instantiate the RDS.DataFactory object by
first creating a RDS.DataSpace object on the client, which then creates an instance of the
DataFactory object on the server with the CreateObject method. The following example script
demonstrates this process.
If your data access needs cannot be served by the RDS.DataFactory object, you can either a create a
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 110 of 659
custom business component to communicate with the client, or you can use ADO directly from your
ASP script to retrieve the data. In the following example, the custom business component, Inventory,
exposes a method called getQuantityonHand. The RDS.DataControl object creates an instance of
Inventory on the server, and then calls the getQuantityonHand method to retrieve records.
Option Explicit
Sub GetRecords()
Dim objInventory, myRS
Set objInventory =
ADS1.CreateObject("Company.Inventory", _
"http://")
' 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
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 111 of 659
issues.
This section contains:
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 112 of 659
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 113 of 659
Transaction Processing Technology
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
Securing Web sites is a critical issue for Web developers. It is also one of the most potentially confusing.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 114 of 659
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.
This section contains:
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 115 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 116 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
This section contains:
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 117 of 659
More information will be provided in a later release.
Dynamic HTML
This is preliminary documentation for IIS 5.0 and is subject to change.
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 tags and setting the display style
property to display the division when the user clicks an input button.
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
This is some hidden text.
For more information on DHTML, see the Site Builder Network.
Windows Script Components
This is preliminary documentation for IIS 5.0 and is subject to change.
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:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 118 of 659
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 119 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 120 of 659
? 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.
This section contains:
? Developing Scalable ASP Applications
? Developing Scalable Components
? Designing High-Performance ISAPI Applications
? Data Access Performance
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 121 of 659
? Performance and Scalability Testing
For more information about designing Web applications, see Design Decisions.
Developing Scalable ASP Applications
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 122 of 659
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 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 tags until the object is actually put to use. If you use 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
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 123 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 124 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 125 of 659
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 126 of 659
For more information about ISAPI extensions and filters, see Developing ISAPI Extensions and Filters,
and the ISAPI Reference.
Data Access Performance
This is preliminary documentation for IIS 5.0 and is subject to change.
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,
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 127 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
Internet Information Services (IIS) provides powerful programming tools that you can use to access
configuration settings from within a script or application.
This section contains:
? Overview of Programmatic Administration: Describes the metabase, and what you should know
before you create administration applications.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 128 of 659
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
This section contains:
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
The metabase is the repository for most IIS 5.0 configuration information.
This section contains:
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 129 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 130 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 131 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 132 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 133 of 659
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.
For more information, see Advanced Programmatic Administration.
Development Choices for Programmatic
Administration
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 134 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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++.
This section contains:
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 135 of 659
This section contains:
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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 is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 136 of 659
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.
This section contains:
? 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.
ADSI Objects
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 137 of 659
ADSI Container Objects
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
This section contains:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 138 of 659
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
This could also be implemented using the object.property syntax, as in the following example.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 139 of 659
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 is preliminary documentation for IIS 5.0 and is subject to change.
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.
For more information, see Advanced Programmatic Administration.
IIS Admin Objects Reference
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 140 of 659
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 141 of 659
IIsWebVirtualDir Sets properties for an individual Web virtual
directory.
See Also
Constants A list of constants used with IIS Admin Objects.
IIsCertMapper
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 142 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
See Also
DeleteMapping, GetMapping, SetAcct, SetEnabled, SetName , SetPwd
DeleteMapping
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 143 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
See Also
CreateMapping, GetMapping, SetAcct, SetEnabled, SetName , SetPwd
GetMapping
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 144 of 659
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).
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
See Also
CreateMapping, DeleteMapping, SetAcct, SetEnabled, SetName , SetPwd
SetAcct
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 145 of 659
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).
NTAcct
Specifies a new value for the Windows account string.
Code Example
See Also
CreateMapping, DeleteMapping, GetMapping, SetEnabled, SetName , SetPwd
SetEnabled
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 146 of 659
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).
IEnabled
Specifies TRUE to enable the mapping, FALSE to disable the mapping.
Code Example
See Also
CreateMapping, DeleteMapping, GetMapping, SetAcct, SetName , SetPwd
SetName
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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).
strName
Specifies a new value for the name string.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 147 of 659
Code Example
See Also
CreateMapping, DeleteMapping, GetMapping, SetAcct, SetEnabled, SetPwd
SetPwd
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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).
strPwd
Specifies a new value for the Windows password string.
Code Example
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 148 of 659
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
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
varReturn = object.Property
Parts
varReturn
A variable that receives the return value from the method.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 149 of 659
HcCacheControlHeader HcIoBufferSize
HcCompressionBufferSize HcMaxDiskSpaceUsage
HcCompressionDirectory HcMaxQueueLength
HcDoDiskSpaceLimiting HcMinFileSizeForComp
HcDoDynamicCompression HcNoCompressionForHttp10
HcDoOnDemandCompression HcNoCompressionForProxies
HcDoStaticCompression HcNoCompressionForRange
HcExpiresHeader HcSendCacheHeaders
HcFilesDeletedPerDiskFree
Methods
ADSI Object Methods Standard methods for ADSI objects.
ADSI Container Object Methods Standard methods for ADSI container objects.
IIsCompressionScheme
This is preliminary documentation for IIS 5.0 and is subject to change.
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.Method
varReturn = object.Property
Parts
varReturn
A variable that receives the return value from the method.
object
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 150 of 659
A variable that refers to the IIsCompressionScheme object, usually as a result of a previous
GetObject operation.
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
ADSI Object Methods Standard methods for ADSI objects.
IIsComputer
This is preliminary documentation for IIS 5.0 and is subject to change.
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
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
Parts
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 151 of 659
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsComputer object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
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
ADSI Object Methods Standard methods for ADSI objects.
ADSI Container Object Methods Standard methods for ADSI container objects.
Backup
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 152 of 659
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.
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 from which it was
originally created.
Code Example
See Also
DeleteBackup, EnumBackups, Restore
DeleteBackup
This is preliminary documentation for IIS 5.0 and is subject to change.
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
See Also
Backup, EnumBackups, Restore
EnumBackups
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 154 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
A string of up to 100 characters that specifies the backup location. If an empty string is specified,
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
var TempDate = new Date();
TempDif = TempDate.getTimezoneOffset();
Session("sTempDif") = TempDif;
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)
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 155 of 659
Response.Write "(" & LocDate & ")"
Response.Write ""
Index = Index + 1
Loop
%>
See Also
Backup, DeleteBackup, Restore
Restore
This is preliminary documentation for IIS 5.0 and is subject to change.
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
A string of up to 100 characters that specifies the backup location. If an empty string is specified,
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
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.
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 from which it was
originally created.
See Also
Backup, EnumBackups, DeleteBackup
IIsCustomLogModule
This is preliminary documentation for IIS 5.0 and is subject to change.
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
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
Parts
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsComputer object, usually as a result of a previous GetObject
operation.
Method
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 157 of 659
The object method chosen.
Properties
ADSI Object Properties
Metabase Properties
LogCustomPropertyDataType LogCustomPropertyMask
LogCustomPropertyHeader LogCustomPropertyName
LogCustomPropertyID LogCustomPropertyServicesString
Methods
ADSI Object Methods Standard methods for ADSI objects.
IIsFilter
This is preliminary documentation for IIS 5.0 and is subject to change.
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
where MachineName can be any name or "LocalHost."
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
varReturn = object.Method
Parts
varReturn
A variable that receives the return value from the method.
object
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 158 of 659
A variable that contains the IIsFilter object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
Properties
ADSI Object 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
where MachineName can be any name or "LocalHost."
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 159 of 659
or
IIS://MachineName/W3SVC/N/Filters
where MachineName can be any name or "LocalHost," and N is the number of a Web server.
Syntax
varReturn = object.Method
Parts
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsFilters object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
Can Contain
IIsFilter
Properties
ADSI Object Properties
Metabase Properties
FilterLoadOrder
Methods
ADSI Object Methods Standard methods for ADSI objects.
ADSI Container Object Methods Standard methods for ADSI container objects.
IIsFtpInfo
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 160 of 659
ADsPath
IIS://MachineName/MSFTPSVC/Info
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
Parts
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsFtpInfo object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
Properties
ADSI Object Properties
Metabase Properties
LogModuleList
Methods
ADSI Object Methods Standard methods for ADSI objects.
IIsFtpServer
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 161 of 659
IIS://MachineName/MSFTPSVC/N
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
Parts
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsFtpServer object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
Can Contain
IIsFtpVirtualDir
Properties
ADSI Object 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 162 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 163 of 659
ADSI Object Methods Standard methods for ADSI objects.
ADSI Container Object Methods Standard methods for ADSI container objects.
Continue
This is preliminary documentation for IIS 5.0 and is subject to change.
The Continue method of the IIsFtpServer object continues the server operation after it has been
paused.
Syntax
IIsFtpServer.Continue
Code Example
See Also
Start, Pause, Stop, Status
Pause
This is preliminary documentation for IIS 5.0 and is subject to change.
The Pause method of the IIsFtpServer object pauses the server operation.
Syntax
IIsFtpServer.Pause
Code Example
See Also
Start, Continue, Stop, Status
Start
This is preliminary documentation for IIS 5.0 and is subject to change.
The Start method of the IIsFtpServer object starts the server operation.
Syntax
IIsFtpServer.Start
Code Example
See Also
Pause, Continue, Stop, Status
Status
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 165 of 659
Stop
This is preliminary documentation for IIS 5.0 and is subject to change.
The Stop method of the IIsFtpServer object stops the server operation.
Syntax
IIsFtpServer.Stop
Code Example
See Also
Start, Pause, Continue, Status
IIsFtpService
This is preliminary documentation for IIS 5.0 and is subject to change.
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
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 166 of 659
Parts
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsFtpService object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
Can Contain
IIsFtpServer IIsFtpInfo
Properties
ADSI Object 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 167 of 659
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 Object Methods Standard methods for ADSI objects.
ADSI Container Object methods Standard methods for ADSI container objects.
IIsFtpVirtualDir
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 168 of 659
ADsPath
For the server's root virtual directory,
IIS://MachineName/MSFTPSVC/N/ROOT
where MachineName can be any name or "LocalHost."
For a specific virtual directory,
IIS://MachineName/MSFTPSVC/N/ROOT/vdirName
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
Parts
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsFtpVirtualDir object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
Can Contain
IIsFtpVirtualDir
Properties
ADSI Object Properties
Metabase Properties
AccessFlags IPSecurity
AccessRead Path
AccessWrite UNCPassword
DontLog UNCUserName
FtpDirBrowseShowLongDate
Methods
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 169 of 659
ADSI Object Methods Standard methods for ADSI objects
ADSI Container Object Methods Standard methods for ADSI container objects
IIsIPSecurity
This is preliminary documentation for IIS 5.0 and is subject to change.
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
For the server's root virtual directory,
IIS://MachineName/W3SVVC/N/ROOT
where MachineName can be any name or "LocalHost."
For a specific virtual directory,
IIS://MachineName/W3SVC/N/ROOT/vdirName
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
Parts
varReturn
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 170 of 659
A variable that receives the return value from the method.
object
A variable that contains the IIsIPSecurity object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 171 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 172 of 659
See Also
IPGrant, DomainDeny, DomainGrant, GrantByDefault, IIsIPSecurity
IPGrant
This is preliminary documentation for IIS 5.0 and is subject to change.
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
An IIS Admin Object of type IIsIPSecurity.
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
See Also
IPDeny, DomainDeny, DomainGrant, GrantByDefault, IIsIPSecurity
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 173 of 659
DomainDeny
This is preliminary documentation for IIS 5.0 and is subject to change.
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
An IIS Admin Object of type IIsIPSecurity.
Domain
This is the domain you want denied access to the server.
Code Example
See Also
IPDeny, IPGrant, DomainGrant, GrantByDefault, IIsIPSecurity
DomainGrant
This is preliminary documentation for IIS 5.0 and is subject to change.
You can use the DomainGrant property of the IIsIPSecurity object to edit lists of domains that are
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 174 of 659
allowed access to the server.
Syntax
SecObj.DomainGrant Domain
Parameters
SecObj
An IIS Admin Object of type IIsIPSecurity.
Domain
This is the domain you want granted access to the server.
Code Example
See Also
IPDeny, IPGrant, DomainDeny, GrantByDefault, IIsIPSecurity
GrantByDefault
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 175 of 659
SecObj.GrantByDefault Boolean
Parameters
SecObj
An IIS Admin Object of type IIsIPSecurity.
Boolean
This is a value of TRUE or FALSE.
Code Example
See Also
IPDeny, IPGrant, DomainDeny, DomainGrant, IIsIPSecurity
IIsLogModule
This is preliminary documentation for IIS 5.0 and is subject to change.
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
varReturn = object.Method
Parts
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 176 of 659
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsLogModule object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
Properties
ADSI Object Properties
Metabase Properties
LogModuleId LogModuleUiId
Methods
ADSI Object Methods Standard methods for ADSI objects.
IIsLogModules
This is preliminary documentation for IIS 5.0 and is subject to change.
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
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
Parts
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsLogModules object, usually as a result of a previous GetObject
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 177 of 659
operation.
Method
The object method chosen.
Can Contain
IIsLogModule
Properties
ADSI Object Properties
Methods
ADSI Object Methods Standard methods for ADSI objects.
ADSI Container Object Methods Standard methods for ADSI container objects.
Code Example
"" Then
For Each LogModule in LoggingModules
If LogModule.LogModuleID = CurrentObj.LogPluginClsid Then
Response.Write LogModule.Name & ""
End If
Next
'Display a property of the current module.
Response.Write CurrentObj.LogFileDate
End If
%>
IIsMimeMap
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 178 of 659
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
Parts
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsMimeMap object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
Properties
ADSI Object Properties
Metabase Properties
MimeMap
Methods
ADSI Object Methods Standard methods for ADSI objects.
Code Example
".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 "MIME Maps"
Response.Write "TypeExtension"
'Display the mappings in the table.
For Each MM in aMM
Response.Write "" & MM.MimeType & ""
Response.Write "" & MM.Extension & ""
Next
Response.Write ""
End Sub
%>
IIsMimeType
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 180 of 659
An object variable that receives the IIsMimeType object.
Can Contain
This object cannot contain any other objects.
Properties
ADSI Object 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 181 of 659
See Also
IIsMimeType , Extension
Extension
This is preliminary documentation for IIS 5.0 and is subject to change.
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
See Also
MimeType , IIsMimeType
IIsWebDirectory
This is preliminary documentation for IIS 5.0 and is subject to change.
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
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
Parts
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsWebDirectory object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
Can Contain
IIsWebDirectory IIsWebFile
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 183 of 659
Properties
ADSI Object 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 184 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 185 of 659
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
ADSI Object Methods Standard methods for ADSI objects.
ADSI Container Object Methods Standard methods for ADSI container objects.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 186 of 659
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
See Also
AppCreate2, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive,
AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive,
AspAppRestart
AppCreate2
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 187 of 659
Parameters
DirObj
An IIS Admin Object of type IIsWebDirectory or IIsWebVirtualDir.
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
See Also
AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive,
AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive,
AspAppRestart
AppDelete
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 188 of 659
DirObj
An IIS Admin object of type IIsWebDirectory or IIsWebVirtualDir.
Code Example
See Also
AppCreate, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus,
AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive, AspAppRestart
AppDeleteRecursive
This is preliminary documentation for IIS 5.0 and is subject to change.
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
currently referenced by other applications.
Deletions performed using AppDeleteRecursive cannot be undone.
Syntax
DirObj.AppDeleteRecursive
Parameters
DirObj
An IIS Admin object of type IIsWebDirectory or IIsWebVirtualDir.
Code Example
See Also
AppCreate, AppDelete, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable,
AppDisableRecursive, AppEnable, AppEnableRecursive, AspAppRestart
AppDisable
This is preliminary documentation for IIS 5.0 and is subject to change.
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
An IIS Admin object of type IIsWebDirectory or IIsWebVirtualDir.
Code Example
See Also
AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive,
AppGetStatus, AppDisableRecursive, AppEnable, AppEnableRecursive, AspAppRestart
AppDisableRecursive
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 190 of 659
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
An IIS Admin Object of type IIsWebDirectory or IIsWebVirtualDir.
Code Example
See Also
AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive,
AppGetStatus, AppDisable, AppEnable, AppEnableRecursive, AspAppRestart
AppEnable
This is preliminary documentation for IIS 5.0 and is subject to change.
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
An IIS Admin Object of type IIsWebDirectory or IIsWebVirtualDir.
Code Example
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 191 of 659
See Also
AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive,
AppGetStatus, AppDisable, AppDisableRecursive, AppEnableRecursive, AspAppRestart
AppEnableRecursive
This is preliminary documentation for IIS 5.0 and is subject to change.
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
An IIS Admin Object of type IIsWebDirectory or IIsWebVirtualDir.
Code Example
See Also
AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive,
AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AspAppRestart
AppGetStatus
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 192 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
An IIS Admin Object of type IIsWebDirectory or IIsWebVirtualDir.
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
See Also
AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppDisable,
AppDisableRecursive, AppEnable, AppEnableRecursive, AspAppRestart
AppUnload
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
Note Server component DLLs are not released from in-process applications, even if they aren't
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 193 of 659
currently referenced by other applications.
Syntax
DirObj.AppUnload
Parameters
DirObj
An IIS Admin Object of type IIsWebDirectory or IIsWebVirtualDir.
Code Example
See Also
AppCreate, AppDelete, AppDeleteRecursive, AppUnloadRecursive, AppGetStatus,
AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive, AspAppRestart
AppUnloadRecursive
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
Note Server component DLLs are not released from in-process applications, even if they aren't
currently referenced by other applications.
Syntax
DirObj.AppUnloadRecursive
Parameters
DirObj
An IIS Admin Object of type IIsWebDirectory or IIsWebVirtualDir.
Code Example
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 194 of 659
See Also
AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppGetStatus, AppDisable,
AppDisableRecursive, AppEnable, AppEnableRecursive, AspAppRestart
AspAppRestart
This is preliminary documentation for IIS 5.0 and is subject to change.
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
AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive,
AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive
IIsWebFile
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 195 of 659
ADsPath
IIS://MachineName/W3SVC/n/Root/vdirName/DirName/FileName
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
Parts
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsWebFile object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
Properties
ADSI Object 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 196 of 659
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
ADSI Object Methods Standard methods for ADSI objects.
IIsWebInfo
This is preliminary documentation for IIS 5.0 and is subject to change.
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
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
Parts
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 197 of 659
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsWebInfo object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
Properties
ADSI Object Properties
Metabase Properties
AdminServer ServerConfigFlags
CustomErrorDescriptions ServerConfigSSL128
LogModuleList ServerConfigSSL40
ServerConfigAutoPWSync ServerConfigSSLAllowEncrypt
Methods
ADSI Object Methods Standard methods for ADSI objects.
IIsWebServer
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 198 of 659
Parts
varReturn
Specifies result value.
ObjWebServer
Refers to the IIS Admin Object.
Method
Specifies the method called.
Can Contain
IIsCertMapper IIsWebVirtualDir
IIsFilters
Properties
ADSI Object 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 199 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 200 of 659
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...
LogExtFileBytesRecv LogExtFileUriQuery
LogExtFileBytesSent LogExtFileUriStem
LogExtFileClientIp LogExtFileUserAgent
LogExtFileComputerName LogExtFileUserName
LogExtFileCookie LogExtFileWin32Status
LogExtFileDate LogFileDirectory
LogExtFileFlags LogFileLocaltimeRollover
LogExtFileHttpStatus LogFilePeriod
LogExtFileMethod LogFileTruncateSize
LogExtFileProtocolVersion LogOdbcDataSource
LogExtFileReferer LogOdbcPassword
LogExtFileServerIp LogOdbcTableName
LogExtFileServerPort LogOdbcUserName
LogExtFileSiteName LogonMethod
LogExtFileTime LogPluginClsId
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 201 of 659
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
ADSI Object Methods Standard methods for ADSI objects.
ADSI Container Object Methods Standard methods for ADSI container objects.
Continue
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 202 of 659
The Continue method of the IIsWebServer object continues the server operation after it has been
paused.
Syntax
IIsWebServer.Continue
Code Example
See Also
Start, Pause, Stop, Status
Pause
This is preliminary documentation for IIS 5.0 and is subject to change.
The Pause method of the IIsWebServer object pauses the server operation.
Syntax
IIsWebServer.Pause
Code Example
See Also
Start, Continue, Stop, Status
Start
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 203 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
The Start method of the IIsWebServer object starts the server operation.
Syntax
IIsWebServer.Start
Code Example
See Also
Pause, Continue, Stop, Status
Status
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The Stop method of the IIsWebServer object stops the server operation.
Syntax
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 204 of 659
IIsWebServer.Stop
Code Example
See Also
Start, Pause, Continue, Status
IIsWebService
This is preliminary documentation for IIS 5.0 and is subject to change.
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
varReturn = object.Method
Parts
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsWebServer object, usually as a result of a previous GetObject
operation.
Method
The object method chosen.
Can Contain
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 205 of 659
IIsFilters IIsWebServer
IIsWebInfo
Properties
ADSI Object 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 206 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 207 of 659
CpuEnablePageFaults EnableReverseDns
CpuEnableProcType HttpCustomHeaders
CpuEnableTerminatedProcs HttpErrors
CpuEnableTotalProcs HttpExpires
CpuEnableUserTime HttpPics
CpuLimitLogEvent HttpRedirect
CpuLimitPause InProcessIsapiApps
CpuLimitPriority IPSecurity
CpuLimitProcStop
Log...
LogExtFileBytesRecv LogExtFileUriQuery
LogExtFileBytesSent LogExtFileUriStem
LogExtFileClientIp LogExtFileUserAgent
LogExtFileComputerName LogExtFileUserName
LogExtFileCookie LogExtFileWin32Status
LogExtFileDate LogFileDirectory
LogExtFileFlags LogFileLocaltimeRollover
LogExtFileHttpStatus LogFilePeriod
LogExtFileMethod LogFileTruncateSize
LogExtFileProtocolVersion LogOdbcDataSource
LogExtFileReferer LogOdbcPassword
LogExtFileServerIp LogOdbcTableName
LogExtFileServerPort LogOdbcUserName
LogExtFileSiteName LogonMethod
LogExtFileTime LogPluginClsId
LogExtFileTimeTaken LogType
M–U
MaxConnections ScriptMaps
MaxEndpointConnections ServerAutoStart
MimeMap ServerBindings
NetLogonWorkstation ServerComment
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 208 of 659
NTAuthenticationProviders ServerListenBacklog
PasswordCacheTTL ServerListenTimeout
PasswordChangeFlags ServerSize
PasswordExpirePrenotifyDays SSIExecDisable
PoolIDCTimeout SSLUseDSMapper
ProcessNTCRIfLoggedOn UNCAuthenticationPassthrough
PutReadSize UploadReadAheadSize
Realm UseHostName
RedirectHeaders WAMUserName
WAMUserPass
Methods
ADSI Object Methods Standard methods for ADSI objects
ADSI Container Object Methods Standard methods for ADSI container objects
IIsWebVirtualDir
This is preliminary documentation for IIS 5.0 and is subject to change.
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
For the server's root virtual directory,
IIS://MachineName/W3SVC/N/ROOT
where MachineName can be any name or "LocalHost."
For a specific virtual directory,
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 209 of 659
IIS://MachineName/W3SVC/N/ROOT/vdirName
where MachineName can be any name or "LocalHost."
Syntax
varReturn = object.Method
Parts
varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsWebVirtualDir object, usually as a result of a previous
GetObject operation.
Method
The object method chosen.
Can Contain
IIsWebVirtualDir IIsWebFile
IIsWebDirectory
Properties
ADSI Object 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 210 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 211 of 659
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 212 of 659
AppUnloadRecursive Unloads applications at a specified key and its
subkeys.
AspAppRestart This method restarts the ASP application that
invoked it.
See Also
ADSI Object Methods Standard methods for ADSI objects.
ADSI Container Object Methods Standard methods for ADSI container objects.
Constants
This is preliminary documentation for IIS 5.0 and is subject to change.
The following constants are used with methods and properties of the IIS Admin Objects.
ADSI Reference
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 213 of 659
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.
ADSI Object Properties
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 214 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 215 of 659
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.
Get
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 216 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
See Also
GetInfo, SetInfo, Put, GetEx, PutEx
GetDataPaths
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 217 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
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
"
For each Path in PathList
Response.Write Path & ""
Next
ElseIf Err.Number = MD_ERROR_DATA_NOT_FOUND Then
Response.Write "Property is not inheritable."
ElseIf Err.Number = &H80005006 Then
Response.Write "Property does not exist."
Else
Response.Write "Error " & Err.Number & " " & Err.Description
End If
%>
GetEx
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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.
Return Values
Returns the value of the property.
Code Example
See Also
GetInfo, SetInfo, Get, Put, PutEx
GetInfo
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
Code Example
See Also
SetInfo, Get, Put, GetEx, PutEx
GetPropertyAttribObj
This is preliminary documentation for IIS 5.0 and is subject to change.
You can use this method to access information about attributes for individual ADSI properties.
GetPropertyAttribObj works in the following way:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 220 of 659
? 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
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 221 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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.
value
The value for the property.
Code Example
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 222 of 659
See Also
GetInfo, SetInfo, Get, GetEx, PutEx
PutEx
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
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
A property of the object that has been retrieved from the metabase.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 223 of 659
See Also
GetInfo, SetInfo, Get, Put, GetEx
SetInfo
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
Code Example
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
This is preliminary documentation for IIS 5.0 and is subject to change.
IIS Admin Objects that can contain other objects also can implement the ADSI container methods and
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 224 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The ADSI container object CopyHere method copies an object into a container.
Syntax
Set CopiedObj = Object.CopyHere(SourceName, NewName)
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 225 of 659
Parts
CopiedObj
Accesses the copied object in the container.
object
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
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
See Also
GetObject, Create, Delete, MoveHere
Create
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 226 of 659
object
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
KeyType
The type of IIS Admin Object to create.
Name
The name for the new object.
Code Example
See Also
GetObject, Delete, CopyHere, MoveHere
Delete
This is preliminary documentation for IIS 5.0 and is subject to change.
The ADSI container object Delete method deletes an object from a container.
Syntax
Object.Delete KeyType, Name
Parts
object
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
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
See Also
GetObject, Create, CopyHere, MoveHere
GetObject
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
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
See Also
Create, Delete, CopyHere, MoveHere
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 228 of 659
MoveHere
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
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
See Also
GetObject, Create, Delete, CopyHere
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 229 of 659
ADSI Changes for IIS 5.0
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The following ADSI property is no longer available.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 230 of 659
AspMemFreeFactor This property is no longer available.
ADSI Properties Added to IIS 5.0
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 231 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 232 of 659
Administration Property Reference
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
This section contains:
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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…
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 233 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 234 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 235 of 659
FtpDirBrowseShowLongDate HcPriority
GreetingMessage HcSendCacheHeaders
HcCacheControlHeader HcScriptFileExtensions
HcCompressionBufferSize HttpCustomHeaders
HcCompressionDirectory HttpErrors
HcCompressionDll HttpExpires
HcCreateFlags HttpPics
HcDoDiskSpaceLimiting HttpRedirect
HcDoDynamicCompression InProcessIsapiApps
HcDoOnDemandCompression IPSecurity
HcDoStaticCompression KeyType
HcDynamicCompressionLevel
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 236 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 237 of 659
ServerConfigFlags UNCUserName
ServerConfigSSL128 UploadReadAheadSize
ServerConfigSSL40 UseHostName
ServerConfigSSLAllowEncrypt WAMUserName
ServerListenBacklog WAMUserPass
ServerListenTimeout Win32Error
AccessExecute
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 238 of 659
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 is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 239 of 659
Data type Long
Default value AccessRead = TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/MSFTPSVC/N/ROOT IIsFtpVirtualDir
/LM/MSFTPSVC/N/ROOT/FtpVirtualDir IIsFtpVirtualDir
/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 tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ACCESS_PERM
Default bitmask setting MD_ACCESS_READ
User type IIS_MD_UT_FILE
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 240 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 241 of 659
Metabase identifier MD_ACCESS_PERM
Metabase bitmask identifier MD_ACCESS_NO_REMOTE_EXECUTE
Metabase bitmask value 0x00002000
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessFlags
AccessNoRemoteRead
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 242 of 659
Metabase identifier MD_ACCESS_PERM
Metabase bitmask identifier MD_ACCESS_NO_REMOTE_READ
Metabase bitmask value 0x00001000
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessFlags
AccessNoRemoteScript
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 243 of 659
Note This property is a bitmask flag of the identifier MD_ACCESS_PERM.
Metabase identifier MD_ACCESS_PERM
Metabase bitmask identifier MD_ACCESS_NO_REMOTE_SCRIPT
Metabase bitmask value 0x00004000
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessFlags, AccessScript
AccessNoRemoteWrite
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 244 of 659
Note This property is a bitmask flag of the identifier MD_ACCESS_PERM.
Metabase identifier MD_ACCESS_PERM
Metabase bitmask identifier MD_ACCESS_NO_REMOTE_WRITE
Metabase bitmask value 0x00000400
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessFlags
AccessRead
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 245 of 659
Note This property is a bitmask flag of the identifier MD_ACCESS_PERM.
Metabase identifier MD_ACCESS_PERM
Metabase bitmask identifier MD_ACCESS_READ
Metabase bitmask value 0x00000001 (Default for
MD_ACCESS_PERM)
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessFlags
AccessScript
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 246 of 659
Object.
Note This property is a bitmask flag of the identifier MD_ACCESS_PERM.
Metabase identifier MD_ACCESS_PERM
Metabase bitmask identifier MD_ACCESS_SCRIPT
Metabase bitmask value 0x00000200
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessFlags
AccessSource
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 247 of 659
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_SOURCE
Metabase bitmask value 0x00000010
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessFlags
AccessSSL
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 248 of 659
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_SSL_ACCESS_PERM.
Metabase identifier MD_SSL_ACCESS_PERM
Metabase bitmask identifier MD_ACCESS_SSL
Metabase bitmask value 0x00000008
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessSSLFlags
AccessSSL128
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 249 of 659
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_SSL_ACCESS_PERM.
Metabase identifier MD_SSL_ACCESS_PERM
Metabase bitmask identifier MD_ACCESS_SSL128
Metabase bitmask value 0x00000100
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessSSLFlags
AccessSSLFlags
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 250 of 659
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory/WebFile IIsWebFile
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SSL_ACCESS_PERM
Metabase bitmask identifier MD_ACCESS_SSL
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000008
Values
Default Value
0x00000000 (No SSL protocols required)
Constant Value Description
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 251 of 659
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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_SSL_ACCESS_PERM.
Metabase identifier MD_SSL_ACCESS_PERM
Metabase bitmask identifier MD_ACCESS_MAP_CERT
Metabase bitmask value 0x00000080
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessSSLFlags
AccessSSLNegotiateCert
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 252 of 659
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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_SSL_ACCESS_PERM.
Metabase identifier MD_SSL_ACCESS_PERM
Metabase bitmask identifier MD_ACCESS_NEGO_CERT
Metabase bitmask value 0x00000020
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessSSLFlags
AccessSSLRequireCert
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 253 of 659
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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_SSL_ACCESS_PERM.
Metabase identifier MD_SSL_ACCESS_PERM
Metabase bitmask identifier MD_ACCESS_REQUIRE_CERT
Metabase bitmask value 0x00000040
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessSSLFlags
AccessWrite
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 254 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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_WRITE
Metabase bitmask value 0x00000002
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
AccessFlags
AdminACL
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 255 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ADMIN_ACL
Data type BINARY_METADATA
User type IIS_MD_UT_FILE
Values
Default Value
0x00000000 (no SSL protocols required)
Constant Value Description
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 256 of 659
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 is preliminary documentation for IIS 5.0 and is subject to change.
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:
Metabase Path Key Type
/LM/W3SVC/Info IIsWebInfo
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 257 of 659
Metabase identifier MD_ADMIN_INSTANCE
User type IIS_MD_UT_SERVER
AllowAnonymous
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies whether the FTP or Web server will allow anonymous access.
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ALLOW_ANONYMOUS
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
AllowKeepAlive
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies whether Keep-Alive processing is permitted.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 258 of 659
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ALLOW_ANONYMOUS
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
AllowPathInfoForScriptMappings
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether clients are permitted to specify path information in script-mapped
requests.
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 259 of 659
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ALLOW_PATH_INFO_FOR_SCRIPT_MAPPINGS
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
AnonymousOnly
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ANONYMOUS_ONLY
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 260 of 659
AnonymousPasswordSync
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/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.
Metabase identifier MD_ANONYMOUS_USE_SUBAUTH
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See also
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 261 of 659
AnonymousUserName , AnonymousUserPass
AnonymousUserName
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/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.
Metabase identifier MD_ANONYMOUS_USER_NAME
User type IIS_MD_UT_FILE
AnonymousUserPass
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 262 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/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.
Metabase identifier MD_ANONYMOUS_PWD
User type IIS_MD_UT_FILE
See Also
AnonymousUserPass, AnonymousPasswordSync
AppAllowClientDebug
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 263 of 659
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_ENABLECLIENTDEBUG
Data type DWORD_METADATA
User type IIS_MD_UT_APP
AppAllowDebugging
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 264 of 659
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_ENABLESERVERDEBUG
Data type DWORD_METADATA
User type IIS_MD_UT_WAM
AppFriendlyName
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the user-friendly name of the package or application.
Data type String
Default value Empty
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 265 of 659
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_APP_FRIENDLY_NAME
User type IIS_MD_UT_WAM
See Also
AppPackageName
AppIsolated
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 266 of 659
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_APP_ISOLATED
Data type DWORD_METADATA
User type IIS_MD_UT_WAM
See Also
InProcessIsapiApps
AppOopRecoverLimit
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value 5 (range 1-5)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 267 of 659
Metabase Path Key Type
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_APP_OOP_RECOVER_LIMIT
Data type DWORD_METADATA
User type IIS_MD_UT_APP
See Also
InProcessIsapiApps
AppPackageID
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 268 of 659
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_APP_PACKAGE_ID
User type IIS_MD_UT_WAM
See Also
AppPackageName
AppPackageName
This is preliminary documentation for IIS 5.0 and is subject to change.
This property provides the COM+ application name for a transaction. This property should be
considered read-only.
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 269 of 659
Metabase identifier MD_APP_PACKAGE_NAME
User type IIS_MD_UT_WAM
See Also
AppPackageID, AppFriendlyName
AppRoot
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_APP_ROOT
User type IIS_MD_UT_FILE
AppWamClsID
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 270 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_APP_WAM_CLSID
User type IIS_MD_UT_WAM
AspAllowOutOfProcComponents
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 271 of 659
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_ALLOWOUTOFPROCCOMPONENTS
Data type DWORD_METADATA
User type IIS_MD_UT_WAM
AspAllowSessionState
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 272 of 659
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_ALLOWSESSIONSTATE
User type ASP_MD_UT_APP
AspBufferingOn
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 273 of 659
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_BUFFERINGON
Data type DWORD_METADATA
User type ASP_MD_UT_APP
AspCodepage
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 274 of 659
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_CODEPAGE
User type ASP_MD_UT_APP
AspEnableApplicationRestart
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 275 of 659
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_ENABLEAPPLICATIONRESTART
Data type DWORD_METADATA
User type ASP_MD_UT_APP
See Also
AspAppRestart
AspEnableAspHtmlFallback
This is preliminary documentation for IIS 5.0 and is subject to change.
This property is reserved for future use.
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 276 of 659
Metabase identifier MD_ASP_ENABLEAPPLICATIONRESTART
Data type DWORD_METADATA
User type ASP_MD_UT_APP
See Also
AspAppRestart
AspEnableChunkedEncoding
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 277 of 659
Object.
Metabase identifier MD_ASP_ENABLECHUNKEDENCODING
Data type DWORD_METADATA
User type ASP_MD_UT_APP
AspEnableParentPaths
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_ENABLEPARENTPATHS
Data type DWORD_METADATA
User type ASP_MD_UT_APP
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 278 of 659
AspEnableTypelibCache
This is preliminary documentation for IIS 5.0 and is subject to change.
This metabase property specifies whether type libraries will be cached on the server.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_ENABLETYPELIBCACHE
Data type DWORD_METADATA
User type ASP_MD_UT_APP
AspErrorsToNTLog
This is preliminary documentation for IIS 5.0 and is subject to change.
This metabase property specifies whether IIS scripting errors will be written to the Windows Event Log.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 279 of 659
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_ERRORSTONTLOG
Data type DWORD_METADATA
User type ASP_MD_UT_APP
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 280 of 659
AspExceptionCatchEnable
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_EXCEPTIONCATCHENABLE
Data type DWORD_METADATA
User type IIS_MD_UT_WAM
AspLogErrorRequests
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 281 of 659
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_LOGERRORREQUESTS
Data type DWORD_METADATA
User type IIS_MD_UT_WAM
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 282 of 659
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).
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 283 of 659
ASP 0242 Query OnStartPage Interface Querying object (object name)'s
Exception OnStartPage or OnEndPage
methods caused exception
(exception name).
See Also
AspErrorsToNTLog
AspProcessorThreadMax
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 284 of 659
Object.
Metabase identifier MD_ASP_PROCESSORTHREADMAX
Data type DWORD_METADATA
User type ASP_MD_UT_APP
AspQueueConnectionTestTime
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 285 of 659
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_QUEUECONNECTIONTESTTIME
Data type DWORD_METADATA
User type ASP_MD_UT_APP
AspQueueTimeout
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_QUEUETIMEOUT
Data type DWORD_METADATA
User type ASP_MD_UT_APP
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 286 of 659
AspRequestQueueMax
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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 500 (range 0-0xFFFFFFFF)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_REQUESTQUEUEMAX
Data type DWORD_METADATA
User type ASP_MD_UT_APP
AspScriptEngineCacheMax
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 287 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the maximum number of scripting engines that ASP pages will keep cached in
memory.
Data type Long
Default value 50
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_SCRIPTENGINECACHEMAX
Data type DWORD_METADATA
User type IIS_MD_UT_WAM
AspScriptErrorMessage
This is preliminary documentation for IIS 5.0 and is subject to change.
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).
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 288 of 659
Data type String
Default value An error occurred on the server when processing
the URL. Please contact the system administrator.
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_SCRIPTERRORMESSAGE
User type IIS_MD_UT_WAM
See Also
AspScriptErrorSentToBrowser
AspScriptErrorSentToBrowser
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 289 of 659
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_SCRIPTERRORMESSAGE
Data type DWORD_METADATA
User type IIS_MD_UT_WAM
See Also
AspScriptErrorMessage
AspScriptFileCacheSize
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 290 of 659
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_SCRIPTFILECACHESIZE
User type IIS_MD_UT_WAM
AspScriptLanguage
This is preliminary documentation for IIS 5.0 and is subject to change.
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 () unless specifically
overridden by the following directive.
Data type String
Default value VBScript
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 291 of 659
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_SCRIPTLANGUAGE
User type ASP_MD_UT_APP
AspScriptTimeout
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 292 of 659
Metabase identifier MD_ASP_SCRIPTTIMEOUT
User type ASP_MD_UT_APP
See also
ScriptTimeout, AspSessionTimeout
AspSessionMax
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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 -1 (maximum allowed)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 293 of 659
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_SESSIONMAX
User type ASP_MD_UT_APP
See also
AspSessionTimeout
AspSessionTimeout
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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 minutes
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 294 of 659
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_SESSIONTIMEOUT
Data type DWORD_METADATA
User type ASP_MD_UT_APP
See also
Timeout, AspScriptTimeout
AspThreadGateEnabled
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 295 of 659
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_THREADGATEENABLED
Data type DWORD_METADATA
User type ASP_MD_UT_APP
AspThreadGateLoadHigh
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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.
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 90 percent
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 296 of 659
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_THREADGATELOADHIGH
Data type DWORD_METADATA
User type ASP_MD_UT_APP
AspThreadGateLoadLow
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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.
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 75 percent
Inheritance Inheritable
Access Locations
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 297 of 659
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_THREADGATELOADLOW
Data type DWORD_METADATA
User type ASP_MD_UT_APP
AspThreadGateSleepDelay
This is preliminary documentation for IIS 5.0 and is subject to change.
This metabase property specifies how long to defer thread requests, before the request is rechecked by
the IIS thread gating mechanism.
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.
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 100 milliseconds
Inheritance Inheritable
Access Locations
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 298 of 659
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_THREADGATESLEEPDELAY
Data type DWORD_METADATA
User type ASP_MD_UT_APP
AspThreadGateSleepMax
This is preliminary documentation for IIS 5.0 and is subject to change.
This metabase property specifies the maximum number of times a specific request can be put to sleep
(deferred) while IIS performs thread gating.
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.
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 50
Inheritance Inheritable
Access Locations
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 299 of 659
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_THREADGATESLEEPMAX
User type ASP_MD_UT_APP
AspThreadGateTimeSlice
This is preliminary documentation for IIS 5.0 and is subject to change.
This metabase property specifies how often the thread gating mechanism in IIS checks the CPU load.
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.
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 1000 milliseconds
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 300 of 659
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_THREADGATETIMESLICE
User type ASP_MD_UT_APP
AspTrackThreadingModel
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 301 of 659
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ASP_TRACKTHREADINGMODEL
Data type DWORD_METADATA
User type ASP_MD_UT_APP
AuthAnonymous
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 302 of 659
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_AUTHORIZATION.
Metabase identifier MD_AUTHORIZATION
Metabase bitmask identifier MD_AUTH_ANONYMOUS
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000001
See Also
AuthFlags
AuthBasic
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 303 of 659
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_AUTHORIZATION.
Metabase identifier MD_AUTHORIZATION
Metabase bitmask identifier MD_AUTH_BASIC
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000002
See Also
AuthFlags
AuthFlags
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 304 of 659
Data type Long
Default value AuthAnonymous = TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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 tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_AUTHORIZATION
User type IIS_MD_UT_FILE
Default bitmask setting MD_AUTH_ANONYMOUS
Bitmask Values
Constant Value Description
MD_AUTH_ANONYMOUS 0x00000001 Anonymous authentication
available.
MD_AUTH_BASIC 0x00000002 Basic authentication available.
MD_AUTH_NT 0x00000004 Windows authentication schemes
available.
AuthNTLM
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies integrated Windows authentication (also known as Challenge/Response or
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 305 of 659
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
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_AUTHORIZATION.
Metabase identifier MD_AUTHORIZATION
Metabase bitmask identifier MD_AUTH_NT
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000004
See Also
AuthFlags
AuthPersistence
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 306 of 659
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)
Inheritance Inheritable
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
This property is accessible at the following locations:
Metabase Path Key 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 307 of 659
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_AUTHORIZATION_PERSISTENCE
User type IIS_MD_UT_FILE
Default bitmask setting MD_AUTH_SINGLEREQUESTIFPROXY
Bitmask Values
Constant Value Description
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
a single request. 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.
MD_AUTH_SINGLEREQUESTALWAYSIFPROXY 0x00000100 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 if the
current authenticated
request is by any type of
proxy.
AuthPersistSingleRequest
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 308 of 659
AuthPersistSingleRequest is one of the authentication scheme flags contained in the AuthPersistence
property.
Data type Boolean
Default value FALSE
Inheritance Inheritable
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
This property is accessible at the following locations:
Metabase Path Key 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_AUTHORIZATION.
Metabase identifier MD_AUTHORIZATION_PERSISTENCE
Metabase bitmask identifier MD_AUTH_SINGLEREQUEST
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000040
See Also
AuthPersistence
AuthPersistSingleRequestIfProxy
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 309 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
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
This property is accessible at the following locations:
Metabase Path Key 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_AUTHORIZATION.
Metabase identifier MD_AUTHORIZATION_PERSISTENCE
Metabase bitmask identifier MD_AUTH_SINGLEREQUESTIFPROXY
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000080
See Also
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 310 of 659
AuthPersistence
AuthPersistSingleRequestAlwaysIfProxy
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
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
This property is accessible at the following locations:
Metabase Path Key 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_AUTHORIZATION.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 311 of 659
Metabase identifier MD_AUTHORIZATION_PERSISTENCE
Metabase bitmask identifier MD_AUTH_SINGLEREQUESTALWAYSIFPROXY
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000100
See Also
AuthPersistence
CacheControlCustom
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 312 of 659
Metabase identifier MD_CC_OTHER
User type IIS_MD_UT_FILE
CacheControlMaxAge
This is preliminary documentation for IIS 5.0 and is subject to change.
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
By default, this property is not set and cache
control directives are not sent
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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.
Metabase identifier MD_MD_CC_MAX_AGE
User type IIS_MD_UT_FILE
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 313 of 659
CacheControlNoCache
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the HTTP 1.1 directive to prevent caching of content.
Data type Boolean
Default value FALSE
By default, this property is not set and cache
control directives are not sent
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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.
Metabase identifier MD_CC_NO_CACHE
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
CacheISAPI
This is preliminary documentation for IIS 5.0 and is subject to change.
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,
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 314 of 659
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/1 IIsWebServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CACHE_EXTENSIONS
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
CertCheckMode
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 315 of 659
Data Type Integer
Default Value 0
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase Property MD_CERT_CHECK_MODE
User Type IIS_MD_UT_SERVER
CGITimeout
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value 300 seconds
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 316 of 659
Metabase Path Key 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.
Metabase identifier MD_SCRIPT_TIMEOUT
User type IIS_MD_UT_FILE
ConnectionTimeout
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the time in seconds the server will wait before disconnecting an inactive
connection.
Data type Long
Default value 900 (15 minutes)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 317 of 659
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CONNECTION_TIMEOUT
User type IIS_MD_UT_SERVER
ContentIndexed
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies whether the content under this directory tree should be indexed by the installed
content indexer.
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CONNECTION_TIMEOUT
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
CpuAppEnabled
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 318 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 319 of 659
Metabase identifier MD_CPU_APP_ENABLED
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
CpuCgiEnabled
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 320 of 659
/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.
Metabase identifier MD_CPU_CGI_ENABLED
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
CpuCgiLimit
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CPU_CGI_LIMIT
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
See Also
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 321 of 659
ScriptTimeout
CpuEnableActiveProcs
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether the total number of active processes is recorded when process
accounting is performed.
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_CPU_LOGGING_MASK.
Metabase identifier MD_CPU_LOGGING_MASK
Metabase bitmask identifier MD_CPU_ENABLE_ACTIVE_PROCS
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000040
See Also
CpuLoggingMask
CpuEnableAllProcLogging
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 322 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_CPU_LOGGING_OPTIONS.
Metabase identifier MD_CPU_LOGGING_OPTIONS
Metabase bitmask identifier MD_CPU_ENABLE_ALL_PROC_LOGGING
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000001
See Also
CpuLoggingOptions
CpuEnableAppLogging
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether IIS should log out-of-process ISAPI extensions and ASP applications.
For more information, see CpuLoggingOptions.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 323 of 659
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_CPU_LOGGING_OPTIONS.
Metabase identifier MD_CPU_LOGGING_OPTIONS
Metabase bitmask identifier MD_CPU_ENABLE_APP_LOGGING
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000004
See Also
CpuLoggingOptions
CpuEnableCgiLogging
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether IIS should log total CPU times for CGI applications. For more
information, see CpuLoggingOptions.
Data type Boolean
Default value FALSE
Inheritance Inheritable
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 324 of 659
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_CPU_LOGGING_OPTIONS.
Metabase identifier MD_CPU_LOGGING_OPTIONS
Metabase bitmask identifier MD_CPU_ENABLE_CGI_LOGGING
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000002
See Also
CpuLoggingOptions
CpuEnableEvent
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 325 of 659
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_CPU_LOGGING_MASK.
Metabase identifier MD_CPU_LOGGING_MASK
Metabase bitmask identifier MD_CPU_ENABLE_EVENT
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000001
See Also
CpuLoggingMask
CpuEnableKernelTime
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 326 of 659
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_CPU_LOGGING_MASK.
Metabase identifier MD_CPU_LOGGING_MASK
Metabase bitmask identifier MD_CPU_ENABLE_KERNEL_TIME
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000008
See Also
CpuLoggingMask
CpuEnableLogging
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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.
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 327 of 659
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_CPU_LOGGING_MASK.
Metabase identifier MD_CPU_LOGGING_MASK
Metabase bitmask identifier MD_CPU_ENABLE_LOGGING
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x80000000
See Also
CpuLoggingMask
CpuEnablePageFaults
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether the total number of page faults is recorded when process accounting is
performed. For more information, see CpuLoggingMask.
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_CPU_LOGGING_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 328 of 659
Metabase identifier MD_CPU_LOGGING_MASK
Metabase bitmask identifier MD_CPU_ENABLE_PAGE_FAULTS
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000010
See Also
CpuLoggingMask
CpuEnableProcType
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether process type is recorded when process accounting is performed. For
more information, see CpuLoggingMask.
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_CPU_LOGGING_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 329 of 659
Metabase identifier MD_CPU_LOGGING_MASK
Metabase bitmask identifier MD_CPU_ENABLE_PROC_TYPE
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000002
See Also
CpuLoggingMask
CpuEnableTerminatedProcs
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_CPU_LOGGING_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 330 of 659
Metabase identifier MD_CPU_LOGGING_MASK
Metabase bitmask identifier MD_CPU_ENABLE_TERMINATED_PROCS
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000080
See Also
CpuLoggingMask
CpuEnableTotalProcs
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether the total number of processes is recorded when process accounting is
performed. For more information, see CpuLoggingMask.
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_CPU_LOGGING_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 331 of 659
Metabase identifier MD_CPU_LOGGING_MASK
Metabase bitmask identifier MD_CPU_ENABLE_TOTAL_PROCS
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000020
See Also
CpuLoggingMask
CpuEnableUserTime
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether total user-mode CPU time is recorded when process accounting is
performed. For more information, see CpuLoggingMask.
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_CPU_LOGGING_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 332 of 659
Metabase identifier MD_CPU_LOGGING_MASK
Metabase bitmask identifier MD_CPU_ENABLE_USER_TIME
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000004
See Also
CpuLoggingMask
CpuLimitLogEvent
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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 flag of 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, 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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 333 of 659
Data type Long
Default value 0 (unlimited)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CPU_LIMIT_LOGEVENT
User type IIS_MD_UT_SERVER
CpuLimitPause
This is preliminary documentation for IIS 5.0 and is subject to change.
This metabase property specifies the percentage of CPU time, in 1/1000ths of a percent, that all isolated
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.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 334 of 659
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, 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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CPU_LIMIT_PAUSE
User type IIS_MD_UT_SERVER
CpuLimitPriority
This is preliminary documentation for IIS 5.0 and is subject to change.
This metabase property specifies the percentage of CPU time, in 1/1000ths of a percent, that all isolated
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 335 of 659
CPU limit is exceeded.
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, 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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CPU_LIMIT_PRIORITY
User type IIS_MD_UT_SERVER
CpuLimitProcStop
This is preliminary documentation for IIS 5.0 and is subject to change.
This metabase property specifies the percentage of CPU time, in 1/1000ths of a percent, that all isolated
processes on the Web server may occupy during a given process accounting interval (specified by
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 336 of 659
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.
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, or
CpuLimitProcStop, 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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CPU_LIMIT_PROCSTOP
User type IIS_MD_UT_SERVER
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 337 of 659
CpuLimitsEnabled
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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 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, or CpuLimitPause.
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CPU_LIMITS_ENABLED
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 338 of 659
CpuLoggingInterval
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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, or
CpuLimitProcStop, CpuLimitPause.
Data type Long
Default value 60 minutes (1 minute minimum)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 339 of 659
Metabase identifier MD_CPU_LOGGING_INTERVAL
User type IIS_MD_UT_SERVER
CpuLoggingMask
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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.
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.
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 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, or CpuLimitPause.
Data type Long
Default value All Member Flags = TRUE
Inheritance Inheritable
Access Locations
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 340 of 659
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CPU_LOGGING_MASK
User type IIS_MD_UT_SERVER
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
Constant Value Description
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 341 of 659
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 is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
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.
You can also directly manipulate the bit flags within CpuLoggingOptions by using the hexadecimal
values in the following Bitmask Values table.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 342 of 659
the following properties should be set to TRUE: CpuLimitLogEvent, CpuLimitPriority,
CpuLimitProcStop, or CpuLimitPause.
This property contains the following flags:
CpuEnableAppLogging CpuEnableAllProcLogging
CpuEnableCgiLogging
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CPU_LOGGING_OPTIONS
User type IIS_MD_UT_SERVER
Default bitmask setting MD_CPU_ENABLE_ALL_PROC_LOGGING
Bitmask Values
Constant Value Description
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 is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 343 of 659
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.
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.
Data type Long
Default value 1440 minutes (24 hours)
(1 minute minimum)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CPU_RESET_INTERVAL
User type IIS_MD_UT_SERVER
CreateCGIWithNewConsole
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 344 of 659
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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.
Metabase identifier MD_CREATE_PROC_NEW_CONSOLE
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
CreateProcessAsUser
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 345 of 659
Metabase Path Key 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.
Metabase identifier MD_CREATE_PROCESS_AS_USER
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
CustomErrorDescriptions
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/INFO IIsWebInfo
IIS Admin Base Object Information
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 346 of 659
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_CUSTOM_ERROR_DESC
Data type MULTISZ_METADATA
User type IIS_MD_UT_SERVER
See Also
HttpErrors
DefaultDoc
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 347 of 659
Metabase identifier MD_DEFAULT_LOAD_FILE
User type IIS_MD_UT_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 is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 348 of 659
Metabase identifier MD_FOOTER_DOCUMENT
User type IIS_MD_UT_FILE
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 is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 349 of 659
Object.
Metabase identifier MD_DEFAULT_LOGON_DOMAIN
User type IIS_MD_UT_FILE
DirBrowseFlags
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
This property contains the following directory browsing flags:
DirBrowseShowDate DirBrowseShowTime
DirBrowseShowExtension EnableDefaultDoc
DirBrowseShowLongDate EnableDirBrowsing
DirBrowseShowSize
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 350 of 659
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_DIRECTORY_BROWSING
User type IIS_MD_UT_FILE
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
Constant Value Description
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 is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies that date information will be displayed when browsing directories.
DirBrowseShowDate is one of the settings contained in the DirBrowseFlags property.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 351 of 659
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
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_DIRECTORY_BROWSING.
Metabase identifier MD_DIRECTORY_BROWSING
Metabase bitmask identifier MD_DIRBROW_SHOW_DATE
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000002
See Also
DirBrowseFlags
DirBrowseShowExtension
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies that file name extensions will be displayed when browsing directories.
DirBrowseShowExtension is one of the settings contained in the DirBrowseFlags property.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 352 of 659
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
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_DIRECTORY_BROWSING.
Metabase identifier MD_DIRECTORY_BROWSING
Metabase bitmask identifier MD_DIRBROW_SHOW_EXTENSION
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000010
See Also
DirBrowseFlags
DirBrowseShowLongDate
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 353 of 659
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
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_DIRECTORY_BROWSING.
Metabase identifier MD_DIRECTORY_BROWSING
Metabase bitmask identifier MD_DIRBROW_LONG_DATE
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000020
See Also
DirBrowseFlags
DirBrowseShowSize
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies that file size information will be displayed when browsing directories.
DirBrowseShowSize is one of the settings contained in the DirBrowseFlags property.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 354 of 659
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
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_DIRECTORY_BROWSING.
Metabase identifier MD_DIRECTORY_BROWSING
Metabase bitmask identifier MD_DIRBROW_SHOW_SIZE
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000008
See Also
DirBrowseFlags
DirBrowseShowTime
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies that file time information will be displayed when displaying directories.
DirBrowseShowTime is one of the settings contained in the DirBrowseFlags property.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 355 of 659
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
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_DIRECTORY_BROWSING.
Metabase identifier MD_DIRECTORY_BROWSING
Metabase bitmask identifier MD_DIRBROW_SHOW_TIME
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
Metabase bitmask value 0x00000004
See Also
DirBrowseFlags
DirectoryLevelsToScan
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 356 of 659
used for down-level remote administration from earlier versions of IIS.
Data type Long
Default value 2
Inheritance FALSE
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/W3SVC IIsWebService
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LEVELS_TO_SCAN
User type IIS_MD_UT_SERVER
DisableSocketPooling
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 357 of 659
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_DISABLE_SOCKET_POOLING
Default value DWORD_METADATA
User type IIS_MD_UT_SERVER
DontLog
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 358 of 659
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/MSFTPSVC/N/ROOT IIsFtpVirtualDir
/LM/MSFTPSVC/N/ROOT/FtpVirtualDir IIsFtpVirtualDir
/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.
Metabase identifier MD_DONT_LOG
Default value DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
LogType
DownlevelAdminInstance
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates the server instance for remote administration clients.
Data type String
Default value 1 (String)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 359 of 659
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/W3SVC IIsWebService
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_DOWNLEVEL_ADMIN_INSTANCE
User type IIS_MD_UT_SERVER
See Also
AdminServer
EnableDefaultDoc
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 360 of 659
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_DIRECTORY_BROWSING.
Metabase identifier MD_DIRECTORY_BROWSING
Metabase bitmask identifier MD_DIRBROW_LOADDEFAULT
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
Metabase bitmask value 0x40000000
See Also
DirBrowseFlags
EnableDirBrowsing
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 361 of 659
Object.
Note This property is a bitmask flag of the identifier MD_DIRECTORY_BROWSING.
Metabase identifier MD_DIRECTORY_BROWSING
Metabase bitmask identifier MD_DIRBROW_ENABLED
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
Metabase bitmask value 0x80000000
See Also
DirBrowseFlags
EnableDocFooter
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 362 of 659
Metabase identifier MD_FOOTER_ENABLED
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
See Also
DefaultDocFooter
EnableReverseDns
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 363 of 659
Metabase identifier MD_DO_REVERSE_DNS
Data type DWORD_METADATA
User type IIS_MD_UT_FILE
ExitMessage
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the message text an FTP server will transmit to a client when the client sends a
quit command.
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_EXIT_MESSAGE
User type IIS_MD_UT_SERVER
FilterDescription
This is preliminary documentation for IIS 5.0 and is subject to change.
This property holds a string, which serves as the description for the corresponding filter.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 364 of 659
Data type String
Default value Empty
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_FILTER_DESCRIPTION
User type IIS_MD_UT_SERVER
FilterEnabled
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether the filter is enabled.
Data type Boolean
Default value FALSE
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
IIS Admin Base Object Information
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 365 of 659
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_FILTER_ENABLED
User type IIS_MD_UT_SERVER
FilterFlags
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 366 of 659
Metabase identifier MD_FILTER_FLAGS
User type IIS_MD_UT_SERVER
Default bitmask setting (None set)
Bitmask Values
Constant Value Description
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 is preliminary documentation for IIS 5.0 and is subject to change.
This property, a comma-delimited list, specifies the order in which filters are to be loaded, such as
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 367 of 659
Filter1, Filter2, and so on.
Data type String
Default value Empty string
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_FILTER_LOAD_ORDER
User type IIS_MD_UT_SERVER
FilterPath
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the full path to a filter DLL; for example C:\Wwwroot\Bin\Filter.dll.
Data type String
Default value Empty
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
IIS Admin Base Object Information
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 368 of 659
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_FILTER_IMAGE_PATH
User type IIS_MD_UT_SERVER
FilterState
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether the filter is loaded (value 1) or unloaded (value 4). This property is read-
only.
Data type Long
Default value Not set
Possible values 1 or 4
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_FILTER_STATE
User type IIS_MD_UT_SERVER
Bitmask values
Constant Value Description
MD_FILTER_STATE_LOADED 0x00000001 Filter loaded.
MD_FILTER_STATE_UNLOADED 0x00000004 Filter unloaded.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 369 of 659
FrontPageWeb
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir/WebDirectory IIsWebDirectory
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_FRONTPAGE_WEB
Default value DWORD_METADATA
User type IIS_MD_UT_SERVER
FtpDirBrowseShowLongDate
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether or not to display two-digit or four-digit years when browsing directories.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 370 of 659
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/MSFTPSVC/N/ROOT IIsFtpVirtualDir
/LM/MSFTPSVC/N/ROOT/FtpVirtualDir IIsFtpVirtualDir
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SHOW_4_DIGIT_YEAR
Default value DWORD_METADATA
User type IIS_MD_UT_FILE
GreetingMessage
This is preliminary documentation for IIS 5.0 and is subject to change.
This property contains a greeting message (in a multiple-line string) that can be sent to new clients from
an FTP server.
Data type List (string)
Default value Empty list
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 371 of 659
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_GREETING_MESSAGE
Date type MULTISZ_METADATA
User type IIS_MD_UT_SERVER
HcCacheControlHeader
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 372 of 659
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_CACHE_CONTROL_HEADER
User type IIS_MD_UT_SERVER
HcCompressionBufferSize
This is preliminary documentation for IIS 5.0 and is subject to change.
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).
The Web service must be restarted before any changes to this property take effect.
Data type Long
Default value 8192 (bytes)
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
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_DIRECTORY_BROWSING.
Metabase identifier MD_HC_COMPRESSION_BUFFER_SIZE
User type IIS_MD_UT_SERVER
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 373 of 659
HcCompressionDirectory
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_COMPRESSION_DIRECTORY
Date type EXPANDSZ_METADATA
User type IIS_MD_UT_SERVER
See Also
HcDoOnDemandCompression
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 374 of 659
HcCompressionDll
This is preliminary documentation for IIS 5.0 and is subject to change.
This metabase property specifies the fully qualified file system path and file name of the compression
DLL associated with the compression scheme.
The Web service must be restarted before any changes to this property take effect.
Data type String (with replacement)
Default value %windir%\system32\inetsrv\SchemeName.dll
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_COMPRESSION_DLL
Date type EXPANDSZ_METADATA
User type IIS_MD_UT_SERVER
HcCreateFlags
This is preliminary documentation for IIS 5.0 and is subject to change.
This property is reserved for future use.
Data type Long
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 375 of 659
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_CREATE_FLAGS
User type IIS_MD_UT_SERVER
HcDoDiskSpaceLimiting
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 376 of 659
Metabase identifier MD_HC_DO_DISK_SPACE_LIMITING
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
HcDoDynamicCompression
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 377 of 659
Object.
Metabase identifier MD_HC_DO_DYNAMIC_COMPRESSION
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
HcDoOnDemandCompression
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 378 of 659
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_DO_ON_DEMAND_COMPRESSION
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
HcDoStaticCompression
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 379 of 659
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_DO_DYNAMIC_COMPRESSION
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
HcDynamicCompressionLevel
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value 1 (range 1-10)
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 380 of 659
Metabase identifier MD_HC_DYNAMIC_COMPRESSION_LEVEL
User type IIS_MD_UT_SERVER
HcExpiresHeader
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
The Web service must be restarted for any changes to this property take effect.
Data type String
Default value Wed, 01 Jan 1997 12:00:00 GMT
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_EXPIRES_HEADER
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 381 of 659
HcFileExtensions
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
The Web service must be restarted for any changes to this property take effect.
Data type List (string)
Default value htm, html, txt
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_FILE_EXTENSIONS
Date type MULTISZ_METADATA
User type IIS_MD_UT_SERVER
See Also
HcScriptFileExtensions
HcFilesDeletedPerDiskFree
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 382 of 659
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_FILES_DELETED_PER_DISK_FREE
User type IIS_MD_UT_SERVER
HcIoBufferSize
This is preliminary documentation for IIS 5.0 and is subject to change.
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).
The Web service must be restarted before any changes to this property take effect.
Data type Long
Default value 8192 bytes
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 383 of 659
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_IO_BUFFER_SIZE
User type IIS_MD_UT_SERVER
HcMaxDiskSpaceUsage
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_MAX_DISK_SPACE_USAGE
User type IIS_MD_UT_SERVER
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 384 of 659
HcMaxQueueLength
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_MAX_QUEUE_LENGTH
User type IIS_MD_UT_SERVER
HcMimeType
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
The Web service must be restarted before any changes to this property take effect.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 385 of 659
Data type String
Default value text/html text/text
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_MIME_TYPE
Data type STRING_METADATA
User type IIS_MD_UT_SERVER
HcMinFileSizeForComp
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 386 of 659
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_MIN_FILE_SIZE_FOR_COMP
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
HcNoCompressionForHttp10
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_NO_COMPRESSION_FOR_HTTP_10
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
HcNoCompressionForProxies
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 387 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_NO_COMPRESSION_FOR_PROXIES
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
HcNoCompressionForRange
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 388 of 659
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_NO_COMPRESSION_FOR_RANGE
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
HcOnDemandCompLevel
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
The Web service must be restarted before any changes to this property take effect.
Data type Long
Default value 10
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 389 of 659
Metabase identifier MD_HC_ON_DEMAND_COMP_LEVEL
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
See Also
HcDynamicCompressionLevel
HcPriority
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
The Web service must be restarted before any changes to this property take effect.
Data type Long
Default value 5
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_PRIORITY
User type IIS_MD_UT_SERVER
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 390 of 659
HcSendCacheHeaders
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Parameters IIsCompressionSchemes
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_SEND_CACHE_HEADERS
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
HcScriptFileExtensions
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 391 of 659
The Web service must be restarted for any changes to this property take effect.
Data type List (string)
Default value dll, asp, exe
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Compression/Scheme IIsCompressionScheme
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_HC_SCRIPT_FILE_EXTENSIONS
Date type MULTISZ_METADATA
User type IIS_MD_UT_SERVER
See Also
HcFileExtensions
HttpCustomHeaders
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
Data type List (string)
Default value Empty list
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 392 of 659
Metabase Path Key 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.
Metabase identifier MD_HTTP_CUSTOM
Date type MULTISZ_METADATA
User type IIS_MD_UT_FILE
HttpErrors
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
Data type List (string)
Default value Empty list
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 393 of 659
Metabase Path Key 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.
Metabase identifier MD_HTTP_CUSTOM
Date type MULTISZ_METADATA
User type IIS_MD_UT_FILE
See Also
CustomErrorDescriptions
HttpExpires
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 394 of 659
Metabase Path Key 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.
Metabase identifier MD_HTTP_EXPIRES
Date type MULTISZ_METADATA
User type IIS_MD_UT_FILE
HttpPics
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
Data type List (string)
Default value Empty list
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 395 of 659
/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.
Metabase identifier MD_HTTP_PICS
Date type MULTISZ_METADATA
User type IIS_MD_UT_FILE
HttpRedirect
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 396 of 659
/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.
Metabase identifier MD_HTTP_REDIRECT
Date type MULTISZ_METADATA
User type IIS_MD_UT_FILE
InProcessIsapiApps
This is preliminary documentation for IIS 5.0 and is subject to change.
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."
Data type List (string)
Default value httpodbc.dll
ssinc.dll
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 397 of 659
Object.
Metabase identifier MD_IN_PROCESS_ASAPI_APPS
Date type MULTISZ_METADATA
User type IIS_MD_UT_SERVER
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 is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/MSFTPSVC/N/ROOT IIsFtpVirtualDir
/LM/MSFTPSVC/N/ROOT/FtpVirtualDir IIsFtpVirtualDir
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 398 of 659
/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.
Metabase identifier MD_IP_SEC
User type IIS_MD_UT_FILE
See Also
IIsIPSecurity
KeyType
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value Empty string
Inheritance Not inheritable
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 is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies whether anonymous requests are logged to the event log.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 399 of 659
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOG_ANONYMOUS
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
LogCustomPropertyDataType
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 400 of 659
For more information about custom logging fields, see Setting Metabase Properties for Logging.
Data type Long
Default value 0 (int)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/Logging/CustomLogging IIsCustomLogModule
/LM/Logging/CustomLogging/Field IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup/Field IIsCustomLogModule
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGCUSTOM_PROPERTY_DATATYPE
User type IIS_MD_UT_SERVER
Bitmask Values
Constant Value Description
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 401 of 659
LogCustomPropertyHeader
This is preliminary documentation for IIS 5.0 and is subject to change.
The LogCustomPropertyHeader property indicates which header string will be written to the log file
for the custom logging field to which this property applies.
For more information about custom logging fields, see Setting Metabase Properties for Logging.
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/Logging/CustomLogging IIsCustomLogModule
/LM/Logging/CustomLogging/Field IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup/Field IIsCustomLogModule
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGCUSTOM_PROPERTY_HEADER
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
LogCustomPropertyID
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 402 of 659
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.
For more information about custom logging fields, see Setting Metabase Properties for Logging.
Data type Long
Default value 0
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/Logging/CustomLogging IIsCustomLogModule
/LM/Logging/CustomLogging/Field IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup/Field IIsCustomLogModule
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGCUSTOM_PROPERTY_ID
User type IIS_MD_UT_SERVER
LogCustomPropertyMask
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
For more information about custom logging fields, see Setting Metabase Properties for Logging.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 403 of 659
Data type Long
Default value 0
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/Logging/CustomLogging IIsCustomLogModule
/LM/Logging/CustomLogging/Field IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup/Field IIsCustomLogModule
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGCUSTOM_PROPERTY_MASK
User type IIS_MD_UT_SERVER
LogCustomPropertyName
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
For more information about custom logging fields, see Setting Metabase Properties for Logging.
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 404 of 659
Metabase Path Key Type
/LM/Logging/CustomLogging IIsCustomLogModule
/LM/Logging/CustomLogging/Field IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup/Field IIsCustomLogModule
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGCUSTOM_PROPERTY_NAME
User type IIS_MD_UT_SERVER
LogCustomPropertyServicesString
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies to which services the custom logging fields will apply.
For more information about custom logging fields, see Setting Metabase Properties for Logging.
Data type List
Default value W3SVC
MSFTPSVC
SMTPSVC
NNTPSVC
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/Logging/CustomLogging IIsCustomLogModule
/LM/Logging/CustomLogging/Field IIsCustomLogModule
/LM/Logging/CustomLogging/FieldGroup IIsCustomLogModule
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 405 of 659
/LM/Logging/CustomLogging/FieldGroup/Field IIsCustomLogModule
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGCUSTOM_SERVICES_STRING
Date type MULTISZ_METADATA
User type IIS_MD_UT_SERVER
LogExtFileBytesRecv
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 406 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_BYTES_RECV
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00002000
See Also
LogExtFileFlags
LogExtFileBytesSent
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether the total number of bytes sent 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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 407 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_BYTES_SENT
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00001000
See Also
LogExtFileFlags
LogExtFileClientIp
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 408 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_CLIENT_IP
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000004
See Also
LogExtFileFlags
LogExtFileComputerName
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 409 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_COMPUTER_NAME
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000020
See Also
LogExtFileFlags
LogExtFileCookie
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether information from the client cookie 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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 410 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_COOKIE
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00020000
See Also
LogExtFileFlags
LogExtFileDate
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 411 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_DATE
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000001
See Also
LogExtFileFlags
LogExtFileFlags
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 412 of 659
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGEXT_FIELD_MASK
User type IIS_MD_UT_FILE
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
Constant Value Description
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 413 of 659
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 is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 414 of 659
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_HTTP_STATUS
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000400
See Also
LogExtFileFlags
LogExtFileMethod
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 415 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_METHOD
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000080
See Also
LogExtFileFlags
LogExtFileProtocolVersion
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 416 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_PROTOCOL_VERSION
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00080000
See Also
LogExtFileFlags
LogExtFileReferer
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 417 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_REFERER
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00040000
See Also
LogExtFileFlags
LogExtFileServerIp
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 418 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_SERVER_IP
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000040
See Also
LogExtFileFlags
LogExtFileServerPort
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether the active server port 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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 419 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_SERVER_PORT
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00008000
See Also
LogExtFileFlags
LogExtFileSiteName
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether the site name 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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 420 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_SITE_NAME
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000010
See Also
LogExtFileFlags
LogExtFileTime
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 421 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_TIME
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000002
See Also
LogExtFileFlags
LogExtFileTimeTaken
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 422 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_TIME_TAKEN
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00004000
See Also
LogExtFileFlags
LogExtFileUriQuery
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 423 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_URI_QUERY
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000200
See Also
LogExtFileFlags
LogExtFileUriStem
This is preliminary documentation for IIS 5.0 and is subject to change.
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
property is one of the flags contained in the LogExtFileFlags property.
Data type Boolean
Default value TRUE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 424 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_URI_STEM
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000100
See Also
LogExtFileFlags
LogExtFileUserAgent
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 425 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_USER_AGENT
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00010000
See Also
LogExtFileFlags
LogExtFileUserName
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether the user's name 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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 426 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_USERNAME
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000008
See Also
LogExtFileFlags
LogExtFileWin32Status
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
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_LOGEXT_FIELD_MASK.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 427 of 659
Metabase identifier MD_LOGEXT_FIELD_MASK
Metabase bitmask identifier MD_EXTLOG_WIN32_STATUS
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000800
See Also
LogExtFileFlags
LogFileDirectory
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 428 of 659
Metabase identifier MD_LOGFILE_DIRECTORY
Date type EXPANDSZ_METADATA
User type IIS_MD_UT_SERVER
LogFileLocaltimeRollover
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGFILE_LOCALTIME_ROLLOVER
User type IIS_MD_UT_SERVER
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 429 of 659
LogFilePeriod
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGFILE_PERIOD
Date type DWORD_METADATA
User type IIS_MD_UT_SERVER
Bitmask values
Constant Value Description
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 430 of 659
See Also
LogFileTruncateSize
LogFileTruncateSize
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGFILE_TRUNCATE_SIZE
User type IIS_MD_UT_SERVER
LogModuleId
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the CLSID for the logging module.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 431 of 659
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/Logging/IIsLogModule IIsLogModule
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOG_PLUGIN_MOD_ID
User type IIS_MD_UT_SERVER
See Also
LogModuleUiId
LogModuleList
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies a string that contains a comma-delimited list that names the available logging
modules.
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC/INFO IIsFtpInfo
/LM/W3SVC/INFO IIsWebInfo
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 432 of 659
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOG_PLUGINS_AVAILABLE
User type IIS_MD_UT_SERVER
LogModuleUiId
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the CLSID for the logging module's user interface.
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/Logging/IIsLogModule IIsLogModule
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOG_PLUGIN_UI_ID
User type IIS_MD_UT_SERVER
See Also
LogModuleId
LogNonAnonymous
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies whether non-anonymous hits are logged to the event log.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 433 of 659
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOG_NONANONYMOUS
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
LogOdbcDataSource
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 434 of 659
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGSQL_DATA_SOURCES
User type IIS_MD_UT_SERVER
Remarks
The logging module's CLSID determines whether Microsoft Windows will log to an ODBC data source,
or to the file system.
LogOdbcPassword
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the ODBC database password to be used when writing information to the
database during logging events.
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 435 of 659
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGSQL_PASSWORD
User type IIS_MD_UT_SERVER
LogOdbcTableName
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGSQL_TABLE_NAME
User type IIS_MD_UT_SERVER
LogOdbcUserName
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 436 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGSQL_USER_NAME
User type IIS_MD_UT_SERVER
LogonMethod
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 437 of 659
This property is accessible at the following locations:
Metabase Path Key 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
Bitmask values
Constant Value Description
MD_LOGON_INTERACTIVE 0x00000000 Log on locally.
MD_LOGON_BATCH 0X00000001 Log on as batch job.
MD_LOGON_NETWORK 0x00000002 Log on over network.
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOGON_METHOD
User type IIS_MD_UT_SERVER
LogPluginClsid
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the order of precedence for the logging modules.
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 438 of 659
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_LOG_PLUGIN_ORDER
User type IIS_MD_UT_SERVER
LogType
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 439 of 659
Metabase identifier MD_LOG_TYPE
User type IIS_MD_UT_SERVER
Bitmask values
Constant Value Description
MD_LOG_TYPE_DISABLED 0x00000000 Logging disabled.
MD_LOG_TYPE_ENABLED 0x00000001 Logging enabled.
See Also
DontLog
MaxBandWidth
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This property is accessible at the following locations:
Metabase Path Key Type
/LM IIsComputer
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 440 of 659
Metabase identifier MD_MAX_BANDWIDTH
User type IIS_MD_UT_SERVER
MaxBandWidthBlocked
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value &HFFFFFFFF (unlimited)
Inheritance Global (not inheritable)
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM IIsComputer
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_MAX_BANDWIDTH_BLOCKED
User type IIS_MD_UT_SERVER
MaxClientsMessage
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 441 of 659
text.
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_MAX_CLIENTS_MESSAGE
User type IIS_MD_UT_SERVER
See Also
MaxConnections
MaxConnections
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 442 of 659
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_MAX_CONNECTIONS
User type IIS_MD_UT_SERVER
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 is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value &HFFFFFFFF (unlimited)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 443 of 659
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_MAX_ENDPOINT_CONNECTIONS
User type IIS_MD_UT_SERVER
MimeMap
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Default value Empty list
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM IIsComputer
/LM/MimeMap IIsMimeMap
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 444 of 659
/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.
Metabase identifier MD_MAX_CONNECTIONS
Data type MULTSZ_METADATA
User type IIS_MD_UT_FILE
MSDOSDirOutput
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_MSDOS_DIR_OUTPUT
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 445 of 659
NetLogonWorkstation
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_NET_LOGON_WKS
Default bitmask setting MD_NETLOGON_WKS_NONE
User type IIS_MD_UT_SERVER
Bitmask values
Constant Value Description
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 446 of 659
NotDeletable
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_NOT_DELETABLE
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
NotifyAccessDenied
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 447 of 659
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_ACCESS_DENIED
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000800
See Also
FilterFlags
NotifyAuthentication
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 448 of 659
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_AUTHENTICATION
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00002000
See Also
FilterFlags
NotifyEndOfNetSession
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 449 of 659
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_FILTER_FLAGS.
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_END_OF_NET_SESSION
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000100
See Also
FilterFlags
NotifyEndOfRequest
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 450 of 659
Note This property is a bitmask flag of the identifier MD_FILTER_FLAGS.
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_END_OF_REQUEST
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000080
See Also
FilterFlags
NotifyLog
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 451 of 659
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_LOG
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000200
See Also
FilterFlags
NotifyNonSecurePort
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 452 of 659
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_NONSECURE_PORT
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000002
See Also
FilterFlags
NotifyOrderHigh
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 453 of 659
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_ORDER_HIGH
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00080000
See Also
FilterFlags
NotifyOrderLow
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
This property is one of the flags contained in the FilterFlags property, and should be considered read-
only.
Data type Boolean
Default value TRUE
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 454 of 659
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_ORDER_LOW
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00020000
See Also
FilterFlags
NotifyOrderMedium
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 455 of 659
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_ORDER_MEDIUM
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00040000
See Also
FilterFlags
NotifyPreProcHeaders
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 456 of 659
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_PREPROC_HEADERS
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00004000
See Also
FilterFlags
NotifyReadRawData
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 457 of 659
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_READ_RAW_DATA
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00008000
See Also
FilterFlags
NotifySecurePort
This is preliminary documentation for IIS 5.0 and is subject to change.
This property indicates whether the filter has registered to be notified only for sessions on secure 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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 458 of 659
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_SECURE_PORT
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000001
See Also
FilterFlags
NotifySendRawData
This is preliminary documentation for IIS 5.0 and is subject to change.
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
considered read-only.
Data type Boolean
Default value FALSE
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 459 of 659
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_SEND_RAW_DATA
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000400
See Also
FilterFlags
NotifySendResponse
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 460 of 659
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_SEND_RESPONSE
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000040
See Also
FilterFlags
NotifyUrlMap
This is preliminary documentation for IIS 5.0 and is subject to change.
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
considered read-only.
Data type Boolean
Default value FALSE
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC/Filters/Filter IIsFilter
/LM/W3SVC/N/Filters/Filter IIsFilter
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_FILTER_FLAGS.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 461 of 659
Metabase identifier MD_FILTER_FLAGS
Metabase bitmask identifier MD_NOTIFY_URL_MAP
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00001000
See Also
FilterFlags
NTAuthenticationProviders
This is preliminary documentation for IIS 5.0 and is subject to change.
This property contains a comma-delimited list of Windows authentication providers, such as integrated
Windows authentication (also known as NTLM).
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_NTAUTHENTICATION_PROVIDERS
User type IIS_MD_UT_FILE
PasswordCacheTTL
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 462 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ADV_CACHE_TTL
User type IIS_MD_UT_SERVER
See Also
PasswordExpirePrenotifyDays
PasswordChangeFlags
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 463 of 659
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_AUTH_CHANGE_FLAGS
User type IIS_MD_UT_SERVER
Default bitmask setting 0x00000000
Bitmask values
Constant Value Description
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
PasswordExpirePrenotifyDays
PasswordExpirePrenotifyDays
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 464 of 659
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_ADV_NOTIFY_PWD_EXP_IN_DAYS
User type IIS_MD_UT_SERVER
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 is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the physical path associated with a virtual directory.
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC/N/ROOT IIsFtpVirtualDir
/LM/MSFTPSVC/N/ROOT/FtpVirtualDir IIsFtpVirtualDir
/LM/W3SVC/N/ROOT IIsWebVirtualDir
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 465 of 659
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_VR_PATH
User type IIS_MD_UT_FILE
PoolIDCTimeout
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value 30 seconds
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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.
Metabase identifier MD_POOL_IDC_TIMEOUT
User type IIS_MD_UT_FILE
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 466 of 659
ProcessNTCRIfLoggedOn
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_PROCESS_NTCR_IF_LOGGED_ON
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
PutReadSize
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 467 of 659
Data type Long
Default value 8 KB (range 1 KB–64 KB)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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.
Metabase identifier MD_PUT_READ_SIZE
User type IIS_MD_UT_FILE
Realm
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 468 of 659
Metabase Path Key Type
/LM/MSFTPSVC/N IIsFtpServer
/LM/MSFTPSVC IIsFtpService
/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.
Metabase identifier MD_REALM
User type IIS_MD_UT_FILE
RedirectHeaders
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 469 of 659
Metabase Path Key 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.
Metabase identifier MD_REDIRECT_HEADERS
User type IIS_MD_UT_FILE
ScriptMaps
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 470 of 659
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"
Data type List (string)
Default value Empty list
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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 tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SCRIPT_MAPS
Data type MULTISZ_METADATA
Default bitmask value Empty
User type IIS_MD_UT_FILE
Bitmask value
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 471 of 659
Constant Value Description
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 is preliminary documentation for IIS 5.0 and is subject to change.
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).
Data type List (string)
Default value Empty list if no keys are installed,
:443: if server keys are installed
Inheritance Inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SECURE_BINDINGS
Data type MULTISZ_METADATA
User type IIS_MD_UT_SERVER
See Also
ServerBindings
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 472 of 659
ServerAutoStart
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SERVER_AUTOSTART
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
ServerBindings
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 473 of 659
Note Both the IP and Hostname parameter of the string are optional. Any unspecified parameters
default to an all-inclusive wildcard.
Data type List (string)
Default value :80: for Web service,
:21: for FTP service
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SERVER_BINDINGS
Data type MULTISZ_METADATA
User type IIS_MD_UT_SERVER
See Also
SecureBindings
ServerComment
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies a comment for the server instance.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 474 of 659
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SERVER_COMMENT
User type IIS_MD_UT_SERVER
ServerConfigAutoPWSync
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 475 of 659
Metabase Path Key Type
/LM/W3SVC/INFO IIsWebInfo
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_SERVER_CONFIGURATION_INFO.
Metabase identifier MD_SERVER_CONFIGURATION_INFO
Metabase bitmask identifier MD_SERVER_CONFIG_AUTO_PW_SYNC
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000008
See Also
ServerConfigFlags
ServerConfigFlags
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value Not set
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/INFO IIsWebInfo
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 476 of 659
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SERVER_CONFIGURATION_INFO
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000000 (not set)
Bitmask values
Constant Value Description
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 is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 477 of 659
Metabase Path Key Type
/LM/W3SVC/INFO IIsWebInfo
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_SERVER_CONFIGURATION_INFO.
Metabase identifier MD_SERVER_CONFIGURATION_INFO
Metabase bitmask identifier MD_SERVER_CONFIG_SSL_128
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000002
See Also
ServerConfigFlags
ServerConfigSSL40
This is preliminary documentation for IIS 5.0 and is subject to change.
This property is a flag that participates in the ServerConfigFlags server configuration specification
property. A value of TRUE indicates that 40-bit Secure Sockets Layer (SSL) processing is installed.
Data type Boolean
Default value FALSE
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/INFO IIsWebInfo
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 478 of 659
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_SSL_40
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000001
See Also
ServerConfigFlags
ServerConfigSSLAllowEncrypt
This is preliminary documentation for IIS 5.0 and is subject to change.
This property is a flag that participates in the ServerConfigFlags server configuration specification
property. A value of TRUE indicates that the locality allows encryption.
Data type Boolean
Default value FALSE
Inheritance Not inheritable
Access Locations
This property is accessible at the following location:
Metabase Path Key Type
/LM/W3SVC/INFO IIsWebInfo
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_SERVER_CONFIGURATION_INFO.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 479 of 659
Metabase identifier MD_SERVER_CONFIGURATION_INFO
Metabase bitmask identifier MD_SERVER_CONFIG_ALLOW_ENCRYPT
Data type DWORD_METADATA
User type IIS_MD_UT_SERVER
Metabase bitmask value 0x00000004
See Also
ServerConfigFlags
ServerListenBacklog
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SERVER_LISTEN_BACKLOG
User type IIS_MD_UT_SERVER
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 480 of 659
See Also
ServerSize
ServerListenTimeout
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Default value 120 seconds
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SERVER_LISTEN_TIMEOUT
User type IIS_MD_UT_SERVER
ServerSize
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 481 of 659
property is used in calculating the value for the ServerListenBacklog property.
Data type Long
Default value 1 (medium)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC IIsFtpService
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following tables list additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SERVER_SIZE
User type IIS_MD_UT_SERVER
Bitmask values
Constant Value Description
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 is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 482 of 659
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
Default value Not set
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC/N IIsFtpServer
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SERVER_STATE
User type IIS_MD_UT_SERVER
Bitmask values
Constant Value Description
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 483 of 659
SSIExecDisable
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies whether server-side include (SSI) #exec directives are disabled under this path.
Data type Boolean
Default value FALSE (SSIs enabled)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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.
Metabase identifier MD_SSI_EXEC_DISABLED
User type IIS_MD_UT_FILE
SSLUseDSMapper
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 484 of 659
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_SSL_USE_DS_MAPPER
User type IIS_MD_UT_SERVER
See Also
AccessSSLFlags
UNCAuthenticationPassthrough
This is preliminary documentation for IIS 5.0 and is subject to change.
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
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 485 of 659
Metabase Path Key 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.
Metabase identifier MD_VR_PASSTHROUGH
User type IIS_MD_UT_FILE
UNCPassword
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the encrypted password used to gain access to Universal Naming Convention
(UNC) virtual roots.
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC/N/ROOT IIsFtpVirtualDir
/LM/MSFTPSVC/N/ROOT/FtpVirtualDir IIsFtpVirtualDir
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
IIS Admin Base Object Information
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 486 of 659
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_VR_PASSWORD
User type IIS_MD_UT_FILE
UNCUserName
This is preliminary documentation for IIS 5.0 and is subject to change.
This property specifies the user name for Universal Naming Convention (UNC) virtual roots.
Data type String
Default value Empty string
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/MSFTPSVC/N/ROOT IIsFtpVirtualDir
/LM/MSFTPSVC/N/ROOT/FtpVirtualDir IIsFtpVirtualDir
/LM/W3SVC/N/ROOT IIsWebVirtualDir
/LM/W3SVC/N/ROOT/WebVirtualDir IIsWebVirtualDir
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_VR_USERNAME
User type IIS_MD_UT_FILE
See Also
UncPassword, Path
UploadReadAheadSize
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 487 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key 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.
Metabase identifier MD_UPLOAD_READAHEAD_SIZE
User type IIS_MD_UT_FILE
UseHostName
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 488 of 659
Data type Boolean
Default value FALSE
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
/LM/W3SVC/N IIsWebServer
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_USE_HOST_NAME
Default value DWORD_METADATA
User type IIS_MD_UT_SERVER
WAMUserName
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 489 of 659
Data type String
Default value IWAM_MachineName, where MachineName is
the name of the machine on which IIS is installed.
Inheritance Inheritable
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_WAM_USER_NAME
User type IIS_MD_UT_FILE
See Also
WAMUserPass
WAMUserPass
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
Inheritance Inheritable
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 490 of 659
Access Locations
This property is accessible at the following locations:
Metabase Path Key Type
/LM/W3SVC IIsWebService
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_WAM_PWD
User type IIS_MD_UT_FILE
See Also
WAMUserName
Win32Error
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
IIS Admin Base Object Information
The following table lists additional information required only for code that uses the IIS Admin Base
Object.
Metabase identifier MD_WIN32_ERROR
User type IIS_MD_UT_SERVER
ADSI vs. Base Object Data Types
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 491 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 492 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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 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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 493 of 659
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.
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 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.
You can then reference the methods and properties of MyComponent on subsequent Web pages by
using this script
or by extracting a local copy of the object and using the following
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 494 of 659
Another way to create objects with application scope is by using the 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.
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:
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---
---file2.asp---
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.
This application page has been visited
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The Application object supports these collections:
? Contents
? StaticObjects
Application Contents Collection
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 496 of 659
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 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:
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:
"
Next
%>
"
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 497 of 659
Application StaticObjects Collection
This is preliminary documentation for IIS 5.0 and is subject to change.
The StaticObjects collection contains all of the objects created with the 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.
(object)"
Next
%>
Application Methods
This is preliminary documentation for IIS 5.0 and is subject to change.
The Application object exposes the following methods:
? Contents.Remove
? Contents.RemoveAll
? Lock
? Unlock
Contents.Remove
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 498 of 659
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.
See Also
Contents.RemoveAll
Contents.RemoveAll
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 499 of 659
Lock
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This application page has been visited
times!
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 500 of 659
Example
This application page has been visited
times!
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 501 of 659
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.
ASP Code Number Source FileName LineNumber Description ASP Description
See Also
Server.GetLastError
ASPCode
This is preliminary documentation for IIS 5.0 and is subject to change.
The ASPCode property returns a string that contains an error code generated by IIS.
Syntax
ASPError.ASPCode ()
Applies To
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 502 of 659
ASPError Object
Number
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The FileName property returns a string that indicates the .asp file that generated the error.
Syntax
ASPError.FileName ()
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 503 of 659
Applies To
ASPError Object
LineNumber
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The Description property returns a string describing the error.
Syntax
ASPError.Description ()
Applies To
ASPError Object
ASPDescription
This is preliminary documentation for IIS 5.0 and is subject to change.
The ASPDescription property returns a string providing a more complete description of the error, if
available.
Syntax
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 504 of 659
ASPError.ASPDescription ()
Applies To
ASPError Object
ObjectContext Object
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 505 of 659
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
Sales Order
Sales Order Form
Please enter the product code, quantity, and your account number.
SalesVerify.asp file
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 506 of 659
For more information, see Understanding Transactions and Processing Transactions.
ObjectContext Methods
This is preliminary documentation for IIS 5.0 and is subject to change.
The ObjectContext object exposes the following methods:
? SetAbort
? SetComplete
SetAbort
This is preliminary documentation for IIS 5.0 and is subject to change.
The SetAbort method aborts a transaction initiated by an .asp file.
Syntax
ObjectContext.SetAbort
Applies To
ObjectContext Object
SetComplete
This is preliminary documentation for IIS 5.0 and is subject to change.
The SetComplete method overrides any previous SetAbort method that has been called in a script.
Syntax
ObjectContext.SetComplete
Applies To
ObjectContext Object
ObjectContext Events
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 507 of 659
The following events can occur after an ObjectContext method:
? OnTransactionAbort
? OnTransactionCommit
OnTransactionAbort
This is preliminary documentation for IIS 5.0 and is subject to change.
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:
The Transaction just aborted."
Response.Write "This message came from the "
Response.Write "OnTransactionAbort() event handler."
end sub
%>
Applies To
ObjectContext Object
OnTransactionCommit
This is preliminary documentation for IIS 5.0 and is subject to change.
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:
The Transaction just committed."
Response.Write "This message came from the "
Response.Write "OnTransactionCommit() event handler."
end sub
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 508 of 659
%>
Applies To
ObjectContext Object
Request Object
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 509 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The Request object contains the following collections.
? ClientCertificate
? Cookies
? Form
? QueryString
? ServerVariables
ClientCertificate
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 510 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 511 of 659
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.
")
Next
%>
Example
The following example uses the Subject key to test whether a client certificate has been presented.
The following example retrieves the common name of the company that issued the client certificate.
The following example checks the organization name of the subject of the client certification.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 512 of 659
The following example displays the expiration date of the client certificate.
This certification will expire on
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.
Applies To
Request Object
See Also
Cookies, Form, QueryString, ServerVariables
Cookies
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 513 of 659
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.
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:
"
If Request.Cookies(strKey).HasKeys Then
For Each strSubKey In Request.Cookies(strKey)
Response.Write "->" & strKey & "(" & strSubKey & ") = " & _
Request.Cookies(strKey)(strSubKey) & ""
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:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 514 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 515 of 659
specifying two values, Chocolate and Butterscotch, for the FavoriteFlavor element, you could retrieve
those values by using the following script.
"
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.
Request.Form(FavoriteFlavor) =
This script displays the following in the browser.
Request.Form(FavoriteFlavor) = Chocolate
Request.Form(FavoriteFlavor) = Butterscotch
Example
Consider the following form:
Your first name:
What is your favorite ice cream flavor:
Vanilla
Strawberry
Chocolate
Rocky Road
From that form, the following request body might be sent:
firstname=James&flavor=Rocky+Road
The following script can then be used:
Welcome, .
Your favorite flavor is .
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 516 of 659
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:
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
string sample
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 517 of 659
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---
"
Next
%>
Names.asp would display the following:
Fred
Sally
The preceding script could also have been written using Count.
"
Next
%>
Example
The client request
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 518 of 659
/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, .
Your age is .
The output would be
Welcome, Fred. Your age is 22.
If the following script is used:
The unparsed query string is:
The output would be
The unparsed query string is: name=fred&age=22
Applies To
Request Object
See Also
ClientCertificate, Cookies, Form, ServerVariables
ServerVariables
This is preliminary documentation for IIS 5.0 and is subject to change.
The ServerVariables collection retrieves the values of predetermined environment variables.
Syntax
Request.ServerVariables (server environment variable)
Parameters
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 519 of 659
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 520 of 659
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_ 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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 521 of 659
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 522 of 659
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:
You can iterate through each server variable name. For example, the following script prints out all of the
server variables in a table:
Server VariableValue
Example
The following example uses the Request object to display several server variables:
ALL_HTTP server variable =
CONTENT_LENGTH server variable =
CONTENT_TYPE server variable =
QUERY_STRING server variable =
SERVER_SOFTWARE server variable =
The next example uses the ServerVariables collection to insert the name of the server into a hyperlink.
/scripts/MyPage.asp">Link to MyPage.asp
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 523 of 659
Applies To
Request Object
See Also
ClientCertificate, Cookies, Form, QueryString
Request Properties
This is preliminary documentation for IIS 5.0 and is subject to change.
The Request object supports this property:
? TotalBytes
TotalBytes
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
Applies To
Request Object
See Also
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 524 of 659
BinaryRead
Request Methods
This is preliminary documentation for IIS 5.0 and is subject to change.
The Request object supports the following method:
? BinaryRead
BinaryRead
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 525 of 659
Applies To
Request Object
See Also
TotalBytes, ClientCertificate, Cookies, Form, QueryString, ServerVariables
Response Object
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 526 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The Response object has the following collection.
? Cookies
Cookies
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 527 of 659
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,
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.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 528 of 659
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
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.
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.
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.
Example
The following examples demonstrate how you can set a value for a cookie and assign values to its
attributes.
Applies To
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 529 of 659
Response Object
See Also
Request.Cookies
Response Properties
This is preliminary documentation for IIS 5.0 and is subject to change.
The Response object has the following properties:
? Buffer
? CacheControl
? Charset
? ContentType
? Expires
? ExpiresAbsolute
? IsClientConnected
? PICS
? Status
Buffer
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 530 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 531 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 532 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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).
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 533 of 659
The following examples set the ContentType property to other common values.
Applies To
Response Object
Expires
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 534 of 659
ExpiresAbsolute
ExpiresAbsolute
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
Applies To
Response Object
See Also
Expires
IsClientConnected
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 535 of 659
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
Applies To
Response Object
PICS
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 536 of 659
For an .asp file that includes
labels on " & chr(34) & "199
%>
the following header would be added:
PICS-label:(PICS-1.1 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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 537 of 659
Applies To
Response Object
Response Methods
This is preliminary documentation for IIS 5.0 and is subject to change.
The Response object has the following methods.
? AddHeader
? AppendToLog
? BinaryWrite
? Clear
? End
? Flush
? Redirect
? Write
AddHeader
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 538 of 659
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.
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.
Here's some text on your Web page.
Here's some more interesting and
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.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 539 of 659
AppendToLog
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
Applies To
Response Object
BinaryWrite
This is preliminary documentation for IIS 5.0 and is subject to change.
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,
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 540 of 659
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.
Applies To
Response Object
See Also
Write
Clear
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 541 of 659
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.
Applies To
Response Object
See Also
Buffer, Clear
Flush
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 542 of 659
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.
Applies To
Response Object
Write
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 543 of 659
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
Your name is:
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
" %>
produces the output
Applies To
Response Object
See Also
BinaryWrite
Server Object
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 544 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The Server object has the following property:
? ScriptTimeout
ScriptTimeout
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 545 of 659
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:
The following example retrieves the current value of the ScriptTimeout property and stores it in the
variable TimeOut.
Applies To
Server Object
See Also
AspScriptTimeout
Server Methods
This is preliminary documentation for IIS 5.0 and is subject to change.
The Server object has the following methods.
? CreateObject
? Execute
? GetLastError
? HTMLEncode
? MapPath
? Transfer
? URLEncode
CreateObject
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 546 of 659
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 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.
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.
You cannot create an object instance with the same name as a built-in object. For example, the following
returns an error.
Example
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 547 of 659
Execute
This is preliminary documentation for IIS 5.0 and is subject to change.
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:
Asp2.asp:
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
")
Server.Execute("/myasps/asp2.asp")
%>
ASP2
Applies to
Server Object
See Also
Transfer, OnTransactionAbort, OnTransactionCommit
GetLastError
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 549 of 659
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
Example 2
Example 3
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 550 of 659
Applies To
Server Object
See Also
ASPError Object
HTMLEncode
This is preliminary documentation for IIS 5.0 and is subject to change.
The HTMLEncode method applies HTML encoding to a specified string.
Syntax
Server.HTMLEncode( string )
Parameters
string
Specifies the string to encode.
Example
The following script
") %>
produces the output
The paragraph tag: <P>
Note The preceding output will be displayed by a Web browser as
The paragraph tag:
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 551 of 659
MapPath
This is preliminary documentation for IIS 5.0 and is subject to change.
The MapPath method maps the specified relative or virtual path to the corresponding physical directory
on the server.
Syntax
Server.MapPath( Path )
Parameters
Path
Specifies the relative or virtual path to map to a physical directory. If Path starts with either a
forward (/) or backward slash (\), the MapPath method returns a path as if Path is a full virtual
path. If Path doesn't start with a slash, the MapPath method returns a path relative to the
directory of the .asp file being processed.
Remarks
The MapPath method does not check whether the path it returns is valid or exists on the server.
Because the MapPath method maps a path regardless of whether the specified directories currently
exist, you can use the MapPath method to map a path to a physical directory structure, and then pass
that path to a component that creates the specified directory or file on the server.
You can use the relative path syntax for the Path parameter if the AspEnableParentPaths property is set
to TRUE (which is the default value). If you are concerned about allowing scripts to access the physical
directory structure, you can disable this feature by setting the AspEnableParentPaths property to
FALSE. You can accomplish this with either the Internet Information Services snap-in or with a script.
Example
For the examples below, the file data.txt is located in the directory, C:\Inetpub\Wwwroot\Script, as is the
test.asp file that contains the following scripts. The C:\Inetpub\Wwwroot directory is set as the server's
home directory.
The following example uses the server variable PATH_INFO to map the physical path of the current file.
The following script
produces the output
c:\inetpub\wwwroot\script\test.asp
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 552 of 659
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
produce the following output
c:\inetpub\wwwroot\script\data.txt
c:\inetpub\wwwroot\script\script\data.txt
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
produce the following output
c:\inetpub\wwwroot\script\data.txt
c:\inetpub\wwwroot\script
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
produce the following output
c:\inetpub\wwwroot
c:\inetpub\wwwroot
Applies To
Server Object
See Also
AspEnableParentPaths
Transfer
This is preliminary documentation for IIS 5.0 and is subject to change.
The transfer method sends all of the information that has been assembled for processing by one .asp
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 553 of 659
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
")
Response.Write("I am going to ASP2 ")
Server.Transfer("/Myasps/ASP2.asp")
%>
ASP2
Applies To
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 554 of 659
Server Object
See Also
Execute, Global.asa Reference, Application Object
URLEncode
This is preliminary documentation for IIS 5.0 and is subject to change.
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
The following script
produces the output
http%3A%2F%2Fwww%2Emicrosoft%2Ecom
Applies To
Server Object
See Also
HTMLEncode
Session Object
This is preliminary documentation for IIS 5.0 and is subject to change.
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;
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 555 of 659
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 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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 556 of 659
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.
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.
You can then call the methods and properties exposed by MyComponent.class1 on subsequent Web
pages, by using the following.
Or by extracting a local copy of the object and using the following.
Another way to create objects with session scope is to use the 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.
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:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 557 of 659
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---
---file2.asp---
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 558 of 659
Session Collections
This is preliminary documentation for IIS 5.0 and is subject to change.
The Session Object supports the following collections:
? Contents
? StaticObjects
Session Contents Collection
This is preliminary documentation for IIS 5.0 and is subject to change.
The Session.Contents collection contains all of the items that have been established for a session
without using the tag. The collection can be used to determine the value of a specific session
item, or to iterate through the collection and retrieve a list of all items in the session.
Syntax
Session.Contents( Key )
Parameters
Key
The name of the property to retrieve.
Remarks
You can use an iterating control structure to loop through the keys of the Contents collection. This is
demonstrated in the following example.
"
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:"
For Each sessitem in Session.Contents
If IsObject(Session.Contents(sessitem)) Then
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 559 of 659
Response.write(sessitem & " : Session object cannot be displayed." & "")
Else
If IsArray(Session.Contents(sessitem)) Then
Response.write "Array named " & Session.Content(sessitem) & ""
For each objArray in Session.Contents(sessitem)
Response.write "" & _
Session.Contents(sessitem)(objArray)& ""
Next
Response.write ""
Else
Response.write(sessitem & " : " & Session.Contents(sessitem) & "")
End If
End If
Next
%>
Session StaticObjects Collection
This is preliminary documentation for IIS 5.0 and is subject to change.
The StaticObjects collection contains all of the objects created with the 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.
")
Else
Response.write(objprop & " : " & Session.StaticObjects(objprop) &_
"")
End if
Next
%>
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 560 of 659
Session Properties
This is preliminary documentation for IIS 5.0 and is subject to change.
The Session object has the following properties.
? CodePage
? LCID
? SessionID
? Timeout
CodePage
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The LCID property determines the location identifier that will be used to display dynamic content.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 561 of 659
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:
Applies To
Session Object
For more information, see Accommodating International Clients and Locale Identifiers.
SessionID
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 562 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The Session object exposes the following methods.
? Abandon
? Contents.Remove
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 563 of 659
? Content.RemoveAll
Abandon
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
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.
Applies To
Session Object
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 564 of 659
See Also
Timeout
Contents.Remove
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
Applies To
Session Object
See Also
Session.Contents.RemoveAll
Contents.RemoveAll
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 565 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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:
Applies To
Session Object
See Also
Session.Contents.Remove
Installable Components for ASP
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 566 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 567 of 659
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.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 568 of 659
Rotator Schedule File
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 569 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 570 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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---
Ad Rotator Properties
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 571 of 659
Example
The following example displays the advertisements without a border.
See Also
Clickable, TargetFrame
Clickable
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
See Also
Border, TargetFrame
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 572 of 659
TargetFrame
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
See Also
Border, Clickable
Ad Rotator Methods
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 573 of 659
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.
Browser Capabilities Component
This is preliminary documentation for IIS 5.0 and is subject to change.
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."
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 574 of 659
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.
Browser
Version
Frames
TRUE
FALSE
Tables
TRUE
FALSE
BackgroundSounds
TRUE
FALSE
VBScript
TRUE
FALSE
JScript
TRUE
FALSE
Browscap.ini File
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 575 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
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]
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 576 of 659
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:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 577 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 578 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 579 of 659
set on the client.
? Checkcap.asp creates an instance of the Browser Capabilities component and retrieves the
properties from Sendcook.htm.
Sendcook.htm
IE\:clientcaps {behavior:url(#default#clientcaps)}
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;
}
Checkcap.asp
"
Response.write(height= " +myBrowsCap.height + ""
Response.write(bufferDepth= " +myBrowsCap.bufferDepth + ""
Response.write(colorDepth= " +myBrowsCap.colorDepth + ""
Response.write(cookies= " +myBrowsCap.cookies + ""
Response.write(platform= " +myBrowsCap.platform + ""
%>
For more information on the design implications for determining browser capabilities, see Client
Capabilities.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 580 of 659
Content Linking Component
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 581 of 659
GetPreviousURL Gets the URL of the previous pages listed in the Content Linking
List file.
Example
The following example builds a table of contents.
">
The following script adds the next-page and previous-page buttons to an HTML file.
1)
Then
%>
">
Previous Page
">Next Page
Content Linking List File
This is preliminary documentation for IIS 5.0 and is subject to change.
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]]
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 582 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The NextLink object has the following methods:
? GetListCount
? GetListIndex
? GetNextDescription
? GetNextURL
? GetNthDescription
? GetNthURL
? GetPreviousDescription
? GetPreviousURL
GetListCount
This is preliminary documentation for IIS 5.0 and is subject to change.
The GetListCount method retrieves the total number of Web pages listed in the Content Linking List
file.
Syntax
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 583 of 659
GetListCount( listURL )
Parameters
listURL
The location of the Content Linking List file.
Return Values
This method returns an integer.
See Also
GetListIndex
GetListIndex
This is preliminary documentation for IIS 5.0 and is subject to change.
The GetListIndex method retrieves the index number of the current item in the Content Linking List file.
Syntax
GetListIndex( listURL )
Parameters
listURL
The location of the Content Linking List file.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The GetNextDescription method retrieves the text description of the next item in the Content Linking
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 584 of 659
List file.
Syntax
GetNextDescription( listURL )
Parameters
listURL
The location of the Content Linking List file.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The GetNextURL method retrieves the URL of the next item in the Content Linking List file.
Syntax
GetNextURL( listURL )
Parameters
listURL
The location of the Content Linking List file.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 585 of 659
">Next Page
See Also
GetPreviousURL, GetNthURL, GetNextDescription
GetNthDescription
This is preliminary documentation for IIS 5.0 and is subject to change.
The GetNthDescription method retrieves a text description of the Nth item in the Content Linking List
file.
Syntax
GetNthDescription( listURL, i )
Parameters
listURL
The location of the Content Linking List file.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The GetNthURL method returns the URL of the Nth item in the Content Linking List file.
Syntax
GetNthURL( listURL, i )
Parameters
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 586 of 659
listURL
The location of the Content Linking List file.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The GetPreviousDescription method retrieves a text description of the previous item in the Content
Linking List file.
Syntax
GetPreviousDescription( listURL )
Parameters
listURL
The location of the Content Linking List file.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
The GetPreviousURL method returns the URL of the previous item in the Content Linking List file.
Syntax
GetPreviousURL( listURL )
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 587 of 659
Parameters
listURL
The location of the Content Linking List file.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 588 of 659
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.
Content Schedule File
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 589 of 659
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.
Let a
smile
be your umbrella.
%% #3 // This is our favorite image, so show it most often.
%%
Here's the secret link.
ChooseContent
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 590 of 659
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.
GetAllContent
This is preliminary documentation for IIS 5.0 and is subject to change.
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 tag after each entry.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 591 of 659
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.
Tips Stored in the Content Schedule File:
The preceding example produces HTML output such as the following:
Tips Stored in the Content Schedule File:
Don't run with scissors.
Let a
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 592 of 659
smile
be your umbrella.
Here's the secret link.
Counters Component
This is preliminary documentation for IIS 5.0 and is subject to change.
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:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 593 of 659
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:
You can then use that Counters object on one page to create all the counters you need:
There have been to this site.
Then on another page you can increment the counter in the following manner:
You are visitor number to this page.
Get
This is preliminary documentation for IIS 5.0 and is subject to change.
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)
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 594 of 659
Parameters
CounterName
A string containing the name of the counter.
Example
Display the value a counter with . Assign the value of the
counter to a variable with .
The following script displays the vote tally from a poll about favorite colors.
Current vote tally:
red:
green:
blue:
See Also
Increment, Remove, Set
Increment
This is preliminary documentation for IIS 5.0 and is subject to change.
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
A string containing the name of the counter.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 595 of 659
Example
Increment the value of a counter with . Increment and
display the value of a counter with .
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.
There have been visits to this Web page.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
A string containing the name of the counter.
Example
The following code removes the counter hitscounter from the ounters.txt file.
See Also
Get, Increment, Set
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 596 of 659
Set
This is preliminary documentation for IIS 5.0 and is subject to change.
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
A string containing the name of the counter.
int
The new integer value for CounterName.
Example
The following code resets the hit counter pageHits to 0:
See Also
Get, Increment, Remove
Database Access Component
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 597 of 659
For example, to use:
Instead of:
You would include the following type library declaration in the Global.asa file for the application.
creates the new properties DogName and DogBreed. These new properties are stored persistently along
with the other MyInfo properties.
Create new MyInfo properties for values that remain consistent throughout a site.
The values of MyInfo properties are stored in a single text file, Myinfo.xml. MyInfo.xml is installed to
the \winnt\system32 directory on Windows 2000, and to the root directory on Windows95 or later.
File Names
MyInfo.dll The MyInfo component.
MyInfo.xml The file that stores the values of the MyInfo properties.
Syntax
Create a MyInfo object once in the Global.asa file by adding the following:
Remarks
Only create one MyInfo object on your site.
You can create a MyInfo object with Set MyInfoObject = Server.CreateObject('MSWC.MyInfo').
Note For Personal Web Server for Windows® 95, the declaration that creates MyInfo
has already been included in the Global.asa file in the default virtual directory. You can work with
MyInfo as if it were a built-in object.
Syntax
MyInfo.property
Properties Set by Personal Web Services:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 611 of 659
MyInfo.PageType Returns a number corresponding to the value in the
"This site is ..." pop-up menu in the Personal Web
Services control panel. These are the pop-up menu
options with their corresponding numerical values:
1 = About My Company
2 = About My Life
3 = About My School
4 = About My Organization
5 = About My Community
MyInfo.PersonalName Returns the owner's name.
MyInfo.PersonalAddress Returns the owner's address.
MyInfo.PersonalPhone Returns the owner's phone number.
MyInfo.PersonalMail Returns the owner's e-mail address.
MyInfo.PersonalWords Returns additional text associated with the owner.
MyInfo.CompanyName Returns the name of the owner's company.
MyInfo.CompanyAddress Returns the address of the owner's company.
MyInfo.CompanyPhone Returns the phone number of the owner's company.
MyInfo.CompanyDepartment Returns the owner's department name.
MyInfo.CompanyWords Returns additional text associated with the owner's
company.
MyInfo.HomeOccupation Returns the owner's occupation.
MyInfo.HomePeople Returns text listing the people the owner lives with.
MyInfo.HomeWords Returns additional text associated with the owner.
MyInfo.SchoolName Returns the name of the owner's school.
MyInfo.SchoolAddress Returns the address of the owner's school.
MyInfo.SchoolPhone Returns the phone number of the owner's school.
MyInfo.SchoolDepartment Returns the owner's department or class.
MyInfo.SchoolWords Returns text associated with the owner's school.
MyInfo.OrganizationName Returns the name of the organization featured on the
site.
MyInfo.OrganizationAddress Returns the address of the organization.
MyInfo.OrganizationPhone Returns the phone number of the organization.
MyInfo.OrganizationWords Returns text describing the organization.
MyInfo.CommunityName Returns the name of the community featured on the
site.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 612 of 659
MyInfo.CommunityLocation Returns the location of the community.
MyInfo.CommunityPopulation Returns the population of the community.
MyInfo.CommunityWords Returns text describing the community.
MyInfo.URL(n) Returns the nth user-defined URL. Corresponds to
the nth link description in MyInfo.URLWords .
MyInfo.URLWords(n) Returns a string containing the nth user-defined
description of a link. Corresponds to the nth URL in
MyInfo.URL.
MyInfo.Style Returns the relative URL (starting with '/') of a style
sheet.
MyInfo.Background Returns the background for the site.
MyInfo.Title Returns the user-defined title for the home page.
MyInfo.Guestbook Returns –1 if the guest book should be available on
the site. Otherwise, returns 0. The default value is "".
MyInfo.Messages Returns –1 if the private message form should be
available on the site. Otherwise, returns 0. The
default value is "".
Page Counter Component
This is preliminary documentation for IIS 5.0 and is subject to change.
The Page Counter component creates a PageCounter object that counts and displays the number of
times a Web page has been opened. At regular intervals the object writes the number of hits to a text file
so that in the event of a server shutdown, the data is not lost. The Page Counter component uses an
internal Central Management object to record how many times each page in the application has been
opened.
When an instance of the PageCounter object is created on a page by using the Server.CreateObject
method, the object retrieves the current hit count for the specified Web page from the Central
Management object. The object can then be manipulated with the methods it exposes.
The Page Counter component uses the following files:
File Names Description
Pagecnt.dll The Page Counter component.
Hit Count Data file The text file to which the Page Counter component saves
the current hit count.
Syntax
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 613 of 659
Set oVar = Server.CreateObject( "MSWC.PageCounter" )
Parameters
oVar
Specifies the name of the PageCounter object created by the call to Server.CreateObject.
Registry Entries
The Page Counter adds the key MSWC.PageCounter to the registry when the object is compiled or
registered. The key is added under HKEY_CLASSES_ROOT and contains the following named values.
Named Value Description
File_Location A string that specifies the path and filename of the Hit Count Data file. The
default filename is Hitcnt.cnt. This file is located in your Windows directory.
Save_Count A DWORD that specifies the number of hits before the hit count is saved to the
Hit Count Data file. Note that this is the total number of hits, not the number of
hits per page. The default value is 25.
Methods
Hits Displays the number of times that a specified URL has been
opened.
PageHit Increments the Hit Count.
Reset Sets the hit count for a specified page to 0.
Example
The following example uses the PageCounter object to track the number of visitors to the page and
sends a special message to the one millionth visitor.
You are the lucky 1,000,000th Customer!!!
Sorry, you are customer #
Hit Count Data file
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 614 of 659
The Hit Count Data file is a text file on the server to which the Central Management object
periodically saves the hit count data. Editing this file is not recommended; errors in the format will prevent
the PageCounter object from properly loading the hit count information.
Hits
This is preliminary documentation for IIS 5.0 and is subject to change.
The Hits method returns the number of times that a specified Web page has been opened.
Syntax
Object.Hits( [pathInfo] )
Parameters
pathInfo
Optional parameter that specifies the PATH_INFO of the Web page using the
format /virtualdirectoryname/filename.asp. If this parameter is not specified, the hit count for
the current page is displayed.
Return Values
A LONG indicating the number of times that the specified Web page has been opened.
Examples
The following example uses the Hits method to display the number of times that the current Web page
has been opened.
This Web page has been viewed times.
Page Myscript.asp has been viewed t
See Also
Reset, PageHit
PageHit
This is preliminary documentation for IIS 5.0 and is subject to change.
The PageHit method increments the hit count for the current Web page.
Syntax
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 615 of 659
Object.PageHit()
Example
The following example uses the PageHit method to increment the number of times that the current Web
page has been opened.
This Web page has been viewed times.
See Also
Reset, Hits
Reset
This is preliminary documentation for IIS 5.0 and is subject to change.
The Reset method sets the hit count for a specified Web page to 0.
Syntax
Reset([pathInfo])
Parameters
pathInfo
Optional parameter that specifies the PATH_INFO of the Web page using the
format /virtualdirectoryname/filename.asp. If this parameter is not specified, the hit count for
the current page is reset.
Examples
The following example resets the page counters for the current Web page and Mypage.asp.
(The following two values should be 0)
Hits to this page =
Hits to Mypage.asp =
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 616 of 659
See Also
Hits, PageHit
Permission Checker Component
This is preliminary documentation for IIS 5.0 and is subject to change.
The Permission Checker component creates a PermissionChecker object that 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.
You can use the Permission Checker component to customize an ASP-based page for different types of
users. For example, if a Web page contains hyperlinks, you can use the Permission Checker component
to test whether the user has permissions for the target Web pages. If the user does not have the proper
permissions, you can then omit or alter the hyperlinks to those pages the user may not access.
Syntax
Set oVar = Server.CreateObject( "MSWC.PermissionChecker" )
Parameters
oVar
Specifies the name of the PermissionChecker object created by the call to
Server.CreateObject.
Methods
HasAccess Determines whether the user has permissions to
access a specified file.
Examples
The following example uses the HasAccess method to test whether the current user has access to a
specified file. Note that you can specify either a physical or virtual path.
Physical Path Access =
Virtual Path Access =
Remarks
IIS supports the following three types of password authentication in any combination:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 617 of 659
? Anonymous
? Basic
? Integrated Windows authentication
When Anonymous authentication is enabled, all users are initially logged on under the IIS anonymous
user account. Because anonymous users all share the same account, the Permissions Checker
component cannot authenticate individual users when anonymous access is allowed.
For applications where all users have individual accounts, such as intranet-only Web sites, it is
recommended that you disable anonymous authentication so that the Permissions Checker component
can authenticate individual users.
For applications where some pages must be available to anonymous users and other pages need to be
secure, such as mixed Internet and intranet Web sites, you should enable anonymous authentication and
at least one other password authentication method, either integrated Windows authentication or Basic.
Then if you deny anonymous access to a specific page, the server will attempt to authenticate the user by
using either integrated Windows authentication or Basic password authentication.
You can use either of the following two methods to deny anonymous access to a specific page.
? Set the Access Control List for the ASP-based file to exclude the anonymous user account.
? In the ASP script, check for the anonymous user account (if the LOGON_USER server variable
is empty) and set Response.Status to the 401 Unauthorized error message. This will cause
IIS to attempt to identify the user by using NTLM or Basic authentication.
This is illustrated in the following example.
If all the files in your application must be available to anonymous users, the Permission Checker
component will not able to distinguish individual user accounts. You can still use it, however, to ensure
that the specified Web page exists and test whether the anonymous user account has access permissions
for that page.
Note NTLM password authentication is currently supported only by Microsoft Internet Explorer, and
may not work over a proxy server. Thus, if users connect to your site with browsers other than Internet
Explorer or through a proxy server and your application requires a non-anonymous user context, you
must also enable Basic password authentication.
HasAccess
This is preliminary documentation for IIS 5.0 and is subject to change.
The HasAccess method tests whether a user has permission to access a specified file.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 618 of 659
Syntax
HasAccess( FilePath )
Parameters
FilePath
A string that specifies the path and name of the file; this can be either a physical or virtual path.
Return Values
Returns a BOOLEAN value that indicates whether the Web user has access to the specified file. If the
file does not exist, the PermissionChecker object returns False.
Examples
The following example uses the PermissionChecker object to test whether the Web user has access to
the file C:\pages\private\default.htm. If the user has access, the script creates a hyperlink to that file;
otherwise it writes a message. This example uses a virtual path.
Go to the Clubhouse!
Sorry, you are not a member.
The following example repeats the preceding one but uses a physical path to determine the user’s
permissions.
Go to the Clubhouse!
Sorry, you are not a member.
Status Component
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 619 of 659
The Status component 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.
File Names
Status.dll The Status component.
Syntax
Set Status = Server.CreateObject( "MSWC.Status" )
Parameters
Status
Specifies the name of the Status object created by the call to Server.CreateObject.
Remarks
Currently, the Status object only returns server status information for Personal Web Server for
Macintosh. For all Windows platforms, the properties of the Status object currently all return the string
"unavailable."
The only time you may need to include a Status object is when you are running ASP scripts that were
developed on Macintosh and use Status properties.
Note The following table describes the Status properties as they are implemented on Macintosh.
Properties
VisitorsSinceStart The number of unique visitors (IP addresses or domain
names) since the server started up.
RequestsSinceStart The number of requests since the server started up.
ActiveHTTPSessions The current number of HTTP connections.
HighHTTPSessions The highest number of concurrent HTTP connections since
the server started up.
ServerVersion The Personal Web Server version string.
StartTime The time the server started up.
StartDate The date the server started up.
FreeMem The amount of unused memory available to the server.
FreeLowMem The lowest value for the amount of unused memory available
to the server since it started up.
VisitorsToday Number of unique visitors (IP addresses or domain names)
since midnight.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 620 of 659
RequestsToday The number of requests since midnight.
BusyConnections The total number of requests that were rejected because the
server was already handling the maximum number of
connections it can handle.
RefusedConnections The total number of requests that were refused because the
authentication was invalid.
TimedoutConnections The total number of connections that were closed without a
request having been received.
Ktransferred The total number of kilobytes sent by the server since the
server started up.
TotalRequests The total number of requests received since the status
counters were reset using the admin tool.
CurrentThreads The sum of the number active http connections and the
number of threads in the connection thread pool that are not
currently handling connections.
AvailableThreads The number of threads in the connection thread pool that are
not currently handling connections.
RecentVisitors An HTML table listing the 32 most recent unique visitors.
This table includes each visitor's domain name (or IP
address if the domain name is not available) and the number
of requests generated by each visitor.
PopularPages An HTML table listing the 32 most recently visited pages.
This table includes each page's URL and the number of
requests for each page.
Tools Component
This is preliminary documentation for IIS 5.0 and is subject to change.
The Tools component creates a Tools object that provides utilities that enable you to easily add
sophisticated functionality to your Web pages.
File Names
Tools.dll The Tools component.
Syntax
Set Tools = Server.CreateObject("MSWC.Tools")
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 621 of 659
Parameters
Tools
Specifies the name of the Tools object created by the call to Server.CreateObject.
Remarks
In Personal Web Server for Windows® 95 or Windows 98, the Tools object has already been included
in the Global.asa file in the default virtual directory. You can work with the Tools object as if it were a
built-in object by calling Tools.FileExists, Tools.ProcessForm, and Tools.Random.
Methods
FileExists Checks for the existence of a file.
Owner Checks if the current user is the site owner.
PluginExists Checks the existence of a server plug-in (on Macintosh only).
ProcessForm Processes an HTML form.
Random Generates a random integer.
FileExists
This is preliminary documentation for IIS 5.0 and is subject to change.
The FileExists method checks the existence of a file. It returns –1 if the specified URL exists within a
published directory. If the file does not exist, it returns 0.
Syntax
Tools.FileExists(URL)
Parameters
URL
A string that specifies the relative URL of the file you are checking.
Remarks
FileExists only checks the existence of files published on your site. Therefore, it takes a relative URL
rather than an absolute URL.
Example
The following example demonstrates using the FileExists property to create a link if a particular file is
present.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 622 of 659
See Also
ProcessForm, Random
Owner
This is preliminary documentation for IIS 5.0 and is subject to change.
The Owner method checks whether the current user is the site administrator. It returns -1 if the name
and password submitted in the request header matches the Administrator name and password set in the
Personal Web Services interface. It returns 0 if there is not a match.
Syntax
Tools.Owner
Remarks
Currently, Owner only works properly on Personal Web Server for Macintosh.
See Also
FileExists, ProcessForm, Random
PluginExists
This is preliminary documentation for IIS 5.0 and is subject to change.
The PluginExists method checks whether the specified Macintosh server plug-in exists. It returns -1 if
the specified Macintosh server plug-in name is currently registered. It returns 0 if the plug-in is not
registered.
Syntax
Tools.PluginExists(PluginName)
Parameters
PluginName
A string that specifies the name of the server plug-in.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 623 of 659
Remarks
Server plug-ins are only used on Macintosh. For IIS and Personal Web Server for Windows95 or later,
PluginExists always returns 0.
See Also
FileExists, ProcessForm, Random
ProcessForm
This is preliminary documentation for IIS 5.0 and is subject to change.
The ProcessForm method processes the contents of a form that has been submitted by a visitor to the
Web site.
Syntax
Tools.ProcessForm(OutputFileURL, TemplateURL, [InsertionPoint])
Parameters
OutputFileURL
A string containing the relative URL of the file to which the processed data is written.
TemplateURL
A string containing the relative URL of the file that contains the template, or instructions, for
processing the data.
InsertionPoint
An optional parameter indicating where in the output file to insert the process data. This parameter
has not been implemented. If you include a value for this parameter it will be ignored.
Remarks
The template files can contain ASP scripts. A script between delimiters is treated just like
other text in the template and copied into the output file. If the output file is an ASP document, the script
will run when the output file is accessed. Scripts in template files can also be put between special delimiters which cause the script to execute while Tools.ProcessForm is executing. Since
these scripts are executed before the template data is saved in the output file, the results get saved in the
output file, usually as standard text.
If the specified output file does not exist, the server creates it.
If the InsertionPoint parameter does not exist, Tools.ProcessForm replaces the entire output file. If the
InsertionPoint parameter exists, and does not begin with an asterisk (*), Tools.ProcessForm finds the
InsertionPoint string in the output file and inserts the data immediately after it. If the InsertionPoint
string begins with an asterisk (*), Tools.ProcessForm finds the InsertionPoint string in the output file
and inserts the data immediately before it. If the InsertionPoint string exists, but is not found in the
output file, the data is appended to the end of the file.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 624 of 659
Example
The following code demonstrates calling an .asp file to process a form.
*
%>
See Also
FileExists, Random
Random
This is preliminary documentation for IIS 5.0 and is subject to change.
The Random method returns an integer between –32768 and 32767.
Syntax
Tools.random
Remarks
This method is similar to the Rnd function but returns an integer.
To get a positive random integer, use the Abs function.
To get a random integer below a specific value, use the Mod function.
Example
will display a random integer between –32768 to 32767. For example,
will display a positive random integer. For example, 23054
will display a random integer between 0 and 99. Fo
See Also
FileExists, ProcessForm
Script Reference
This is preliminary documentation for IIS 5.0 and is subject to change.
This section contains reference information for building ASP pages. The following topics are included:
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 625 of 659
? JScript Reference
? VBScript Reference
? @ Directives Reference
? Global.asa Reference
JScript Reference
This is preliminary documentation for IIS 5.0 and is subject to change.
You can read the JScript Reference at http://msdn.microsoft.com/scripting/.
VBScript Reference
This is preliminary documentation for IIS 5.0 and is subject to change.
You can read the VBScript Reference at http://msdn.microsoft.com/scripting.
@ Directives Reference
This is preliminary documentation for IIS 5.0 and is subject to change.
You can use @ processing directives in your scripts to send information to IIS about how to process
an .asp file. For example, the following script uses the @LANGUAGE processing directive to set the
scripting language to VBScript.
The following five @ directives are supported by Active Server Pages (ASP) in IIS 5.0.
? @CODEPAGE
? @ENABLESESSIONSTATE
? @LANGUAGE
? @LCID
? @TRANSACTION
@CODEPAGE
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 626 of 659
This is preliminary documentation for IIS 5.0 and is subject to change.
You can use the @CODEPAGE directive to set the code page to be used for the .asp file. A code page
is a character set, which 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.
You can override the code page that has been set by the @CODEPAGE directive with the
Session.CodePage property. Doing so, however, only applies to script running within the scope of the
session.
Syntax
Parameters
codepage
An unsigned integer that represents a valid code page for the system that is running the ASP
scripting engine.
See Also
Session.CodePage
@ENABLESESSIONSTATE
This is preliminary documentation for IIS 5.0 and is subject to change.
You can use the @ENABLESESSIONSTATE directive to turn off session tracking for a page. Session
tracking maintains information about a set of requests that are issued by a single client. If your page does
not rely on session information, turning off session tracking may decrease the time it takes for IIS to
process the script.
Syntax
Remarks
For more information about session tracking, see Managing Sessions.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 627 of 659
@LANGUAGE
This is preliminary documentation for IIS 5.0 and is subject to change.
You can use the @LANGUAGE directive to set the language that will be used to interpret the
commands in a script. You can set your scripting language to any scripting engine that has been installed
in IIS. The default scripting language is VBScript, so if you do not include a @LANGUAGE directive in
your script, the script will be interpreted by the VBScript engine.
Syntax
Parameters
Scriptengine
The script engine that should compile the script. IIS ships with two script engines, VBScript and
JScript.
Remarks
You can change the default scripting language with the IIS Admin Objects AspScriptLanguage property.
You can apply this property to a Web Service, Web Server, Virtual Directory or Web Directory. For
more information, see Using IIS Admin Objects.
@LCID
This is preliminary documentation for IIS 5.0 and is subject to change.
You can use the @LCID directive to set the locale identifier (LCID) for a script. The LCID is a
DWORD containing the language identifier in the lower word and a reserved value in the upper word.
The identifier supplied in an LCID is a standard international numeric abbreviation. This LCID has the
components necessary to uniquely identify one of the installed system-defined locales. There are two
predefined LCID values. LOCALE_SYSTEM_DEFAULT is the system default locale, and
LOCALE_USER_DEFAULT is the current user's locale.
Syntax
Parameters
localeidentifier
A valid locale identifier.
See Also
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 628 of 659
Session.LCID, Accommodating International Clients, Locales
@TRANSACTION
This is preliminary documentation for IIS 5.0 and is subject to change.
You can use the @TRANSACTION directive to indicate that the script should be treated as a
transaction. If a script is treated as a transaction, Component Services will create a transaction to
coordinate the updating of resources.
Syntax
Parameters
Value
A string that indicates the type of transaction support. Possible values are:
Value Meaning
Required The script will initiate a transaction
Requires_New The script will initiate a transaction
Supported The script will not initiate a transaction
Not_Supported The script will not initiate a transaction
Remarks
If a script contains the @TRANSACTION directive, it must be the very first line in the .asp file,
otherwise an error is generated. You must add the directive to each page that should be run under a
transaction. The current transaction ends when the script finishes processing.
If the script containing the @TRANSACTION directive has been called by either the Server.Transfer
or Server.Execute method, and the value is specified as Required the script will continue the transaction
of the calling asp if the calling asp was transacted. If the calling asp was not transacted, the called asp will
create a new transaction.
For example, the following two scripts would be considered one transaction.
ASP
ASP2
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 629 of 659
See Also
ObjectContext
Global.asa Reference
This is preliminary documentation for IIS 5.0 and is subject to change.
The Global.asa file is an optional file in which you can specify event scripts and declare objects that have
session or application scope. It is not a content file displayed to the users; instead it stores event
information and objects used globally by the application. This file must be named Global.asa and must be
stored in the root directory of the application. An application can only have one Global.asa file.
Global.asa files can contain only the following:
? Application Events
? Session Events
? Declarations
? TypeLibrary Declarations
If you include script that is not enclosed by tags, or that defines an object that does not have
session or application scope, the server returns an error. The server ignores both tagged script that the
application or session events do not use, as well as any HTML in the file.
The scripts contained in the Global.asa file may be written in any supported scripting language. If multiple
event or object scripts use the same scripting language, they can be combined inside a single set of
tags.
When you save changes to the Global.asa file, the server finishes processing all of the current application
requests before it recompiles the Global.asa file. During that time, the server refuses additional requests
and returns an error message stating that the request cannot be processed while the application is being
restarted.
After all of the current user requests have been processed, the server deletes all active sessions, calling
the Session_OnEnd event for each session it deletes, closes the application, and calls the
Application_OnEnd event. The Global.asa file is then recompiled. Subsequent user requests will start
the application and create new sessions, and trigger the Application_OnStart and Session_OnStart
events.
Procedures declared in the Global.asa file can only be called from one or more of the scripts associated
with the Application_OnStart, Application_OnEnd, Session_OnStart, and Session_OnEnd events.
They are not available to the ASP pages in the ASP-based application.
To share procedures across an application, you can declare the procedures in a separate file, and then
use server-side include (SSI) statements to include the file in the ASP pages that call the procedures.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 630 of 659
You typically give include files an .inc extension.
Note The examples in this document use Microsoft® Visual Basic® Scripting Edition (VBScript) as the
primary scripting language. However, ASP scripts can be written in any supported scripting language,
such as JScript®. For more information on how to change the primary language, see Working with
Scripting Languages.
Application Events
This is preliminary documentation for IIS 5.0 and is subject to change.
An ASP-based application is made up of all the files in its root directory and in any subdirectories. An
application starts the first time that a user opens one of the Web pages in the application and ends when
the server shuts down. The application has two events, an Application_OnStart event and an
Application_OnEnd event.
You can specify script for these events in the Global.asa file. When the application starts, the server
looks in the Global.asa file and processes the Application_OnStart event script. When the application
ends, the server processes the Application_OnEnd event script.
Application_OnStart
This is preliminary documentation for IIS 5.0 and is subject to change.
The Application_OnStart event occurs before the first new session is created, that is, before the
Session_OnStart event. Only the Application and Server built-in objects are available. Referencing the
Session, Request, or Response objects in the Application_OnStart event script causes an error.
Syntax
Sub Application_OnStart
...
End Sub
Parameters
ScriptLanguage
Specifies the scripting language used to write the event script. It may be any supported scripting
language, such as VBScript or JScript. If more than one event uses the same scripting language,
they can be combined under a single set of tags.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 631 of 659
Examples
Sub Application_OnStart
Application("NumberofVisitors") = 0
End Sub
Note There is no need to use Application.Lock and Application.Unlock methods in the
Application_OnStart event, as this event can only be called once, by the first session that starts the
application.
See Also
Application_OnEnd, Session_OnStart
Application_OnEnd
This is preliminary documentation for IIS 5.0 and is subject to change.
The Application_OnEnd event occurs when the application quits, after the Session_OnEnd event.
Only the Application and Server built-in objects are available.
Syntax
Sub Application_OnEnd
...
End Sub
Parameters
ScriptLanguage
Specifies the scripting language used to write the event script. It may be any supported scripting
language, such as VBScript or JScript. If more than one event uses the same scripting language,
they can be combined under a single set of tags.
Remarks
You cannot call the MapPath method in the Application_OnEnd script.
See Also
Application_OnStart, Session_OnEnd
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 632 of 659
Session Events
This is preliminary documentation for IIS 5.0 and is subject to change.
The Web server automatically creates a session when a user, who did not previously have a session,
opens a Web page in the application. The server destroys the session either when it times out or when
the server calls the Abandon method.
The session has two events, a Session_OnStart event and a Session_OnEnd event.
You can specify script for these events in the global file, Global.asa. When the session starts, the server
looks in the Global.asa file and processes the Session_OnStart event script. This script is processed
before the Web page that the user requested is processed. When the session ends, the server processes
the Session_OnEnd event script.
Note Session tracking on by default. If you do not want to track sessions, you can disable sessions
with the @ENABLESESSIONSTATE directive.
See Also
Session Object
Session_OnStart
This is preliminary documentation for IIS 5.0 and is subject to change.
The Session_OnStart event occurs when the server creates a new session. The server processes this
script prior to executing the requested page. The Session_OnStart event is a good time for you to set
any session-wide variables, because they will be set before any pages are accessed. All the built-in
objects (Application, ObjectContext, Request, Response, Server, and Session) are available and can be
referenced in the Session_OnStart event script.
Syntax
Sub Session_OnStart
...
End Sub
Parameters
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 633 of 659
ScriptLanguage
Specifies the scripting language used to write the event script. It may be any supported scripting
language, such as VBScript or JScript. If more than one event uses the same scripting language,
they can be combined under a single set of tags.
Example
Although the Session object persists if the Session_OnStart event contains a call to the Redirect or
End methods, the server stops processing the script in both the Global.asa file and in the file that
triggered the Session_OnStart event.
You can call the Redirect method in the Session_OnStart event, for example, to ensure that users
always start a session at a particular Web page. When the user enters the application, the server creates
a session for that user and processes the Session_OnStart event script. You can include script in this
event to check whether the page opened by the user is the starting page and, if not, direct the user to the
starting page by calling the Response.Redirect method. This is demonstrated in the following example.
Sub Session_OnStart
'Make sure that new users start on the correct
'page of the ASP application.
'Replace the value given to startPage below
'with the virtual path to your application's
'start page.
startPage = "/MyApp/StartHere.asp"
currentPage = Request.ServerVariables("SCRIPT_NAME")
'Do a case-insensitive compare, and if they
'don't match, send the user to the start page.
If strcomp(currentPage,startPage,1) then
Response.Redirect(startPage)
End If
End Sub
The preceding example only works for browsers that support cookies. Because a noncookie browser
does not return the SessionID cookie, the server creates a new session each time the user requests a
page. Thus for each request, the server processes the Session_OnStart script and redirects the user to
the starting page. If you use the script below, it is recommended that you put a notice on your starting
page to inform users that the site requires a cookie-enabled browser.
Remarks
You should note that any Session_OnStart event script that follows a call to the Redirect method is not
executed. For this reason, you should call the Redirect method last in your event script. This is
demonstrated in the following example.
Sub Session_OnStart
'Session initialization script.
Response.Redirect "http:/server/app/StartHere.asp"
End sub
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 634 of 659
In the preceding example the Redirect method hides any text displayed to the client during the session-
initialization script.
See Also
Session_OnEnd, Application_OnStart
Session_OnEnd
This is preliminary documentation for IIS 5.0 and is subject to change.
The Session_OnEnd event occurs when a session is abandoned or times out. Of the server built-in
objects, only the Application, Server, and Session objects are available.
Syntax
Sub Session_OnEnd
...
End Sub
Parameters
ScriptLanguage
Specifies the scripting language used to write the event script. It may be any supported scripting
language, such as VBScript or JScript. If more than one event uses the same scripting language,
they can be combined under a single set of tags.
Remarks
You cannot call the MapPath method in the Session_OnEnd script.
See Also
Session_OnStart, Application_OnEnd
Declarations
This is preliminary documentation for IIS 5.0 and is subject to change.
You can create objects with session or application scope in the Global.asa file by using the extended
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 635 of 659
tag. This tag is self-contained and is outside of any tags.
The objects declared in the Global.asa file are not created until the server processes a script that calls
that object. This saves resources by creating only the objects that are needed.
The server does not call the OnStartPage and OnEndPage methods for objects created with application
scope. For more information on component scope see Setting Object Scope and Determining Object
Scope.
Syntax
...
Parameters
Scope
Specifies the scope of the object. In the Global.asa file, Scope will be set to either Session or
Application.
Identifier
Specifies a name for the object instance.
ProgID
An identifier associated with a class identifier. Either ProgID or ClassID must be specified in the
tag. The format for ProgID is [Vendor.]Component[.Version].
ClassID
Specifies a unique identifier for an COM class object. Either ProgID or ClassID must be
specified in the tag.
Examples
The first of the following examples creates an object of session scope named MyConnection by using
the ProgID parameter. The second example uses the ClassID parameter.
REM Object Script
REM Object Script
Remarks
The objects declared in the Global.asa file can be used by any script in the application. For example, if
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 636 of 659
you declared the following object.
---GLOBAL.ASA---
You could reference the object MyAd from any page in the application:
---SOME.ASP---
TypeLibrary Declarations
This is preliminary documentation for IIS 5.0 and is subject to change.
A type library is a file that contains information about objects and types supported by a COM
component. It is very common for a COM component to describe any constants that it supports in a
type library. If your Web application relies on COM objects that have declared data types in type
libraries, you can declare the type libraries in Global.asa. Doing so will make it possible to refer to the
constants declared in the type libraries from any script within the application boundary.
For more information about using constants in ASP, see Using Variables and Constants.
Syntax
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).
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 637 of 659
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 638 of 659
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:
ASP Samples
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
This section contains:
? 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
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 639 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 640 of 659
Variables
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 641 of 659
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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\simple\Looping_VBScript.asp and ...\asp\simple\Looping_JScript.asp.
Conditional Operators
This is preliminary documentation for IIS 5.0 and is subject to change.
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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\simple\Conditional_VBScript.asp and ...\asp\simple\Conditional_JScript.asp.
Arrays
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 642 of 659
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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\simple\Arrays_VBScript.asp and ...\asp\simple\Arrays_JScript.asp.
Server-Side Includes
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 643 of 659
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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\simple\Includes_VBScript.asp and ...\asp\simple\Includes_JScript.asp.
Functions and Procedures
This is preliminary documentation for IIS 5.0 and is subject to change.
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 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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\simple\Functions_VBScript.asp and ...\asp\simple\Functions_JScript.asp.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 644 of 659
Building ASP Applications
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\applications\Session_VBScript.asp and ...\asp\applications\Session_JScript.asp.
Application Variables
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 645 of 659
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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\applications\Application_VBScript.asp and ...\asp\applications\Application_JScript.asp.
Web Interactivity using ASP
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 646 of 659
manage.
The HTML 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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\interaction\Form_VBScript.asp and ...\asp\interaction\Form_JScript.asp.
HTTP Server Variables
This is preliminary documentation for IIS 5.0 and is subject to change.
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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\interaction\ServerVariables_VBScript.asp and ...\asp\interaction\ServerVariables_JScript.asp.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 647 of 659
Using Cookies
This is preliminary documentation for IIS 5.0 and is subject to change.
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
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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\interaction\Cookie_VBScript.asp and ...\asp\interaction\Cookie_JScript.asp.
Setting Expiration Information
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 648 of 659
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 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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\interaction\Expire_VBScript.asp and ...\asp\interaction\Expire_JScript.asp.
Client-Side Scripting
This is preliminary documentation for IIS 5.0 and is subject to change.
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 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 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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\interaction\ClientScript_VBScript.asp and ...\asp\interaction\ClientScript_JScript.asp.
Populating Fields
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 649 of 659
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 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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\interaction\PopulateForm_VBScript.asp and ...\asp\interaction\PopulateForm_JScript.asp.
Using Installable Components
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 650 of 659
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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\components\AdRotator_VBScript.asp and ...\asp\components\AdRotator_JScript.asp.
Browser Capabilities
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 651 of 659
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\components\BrowserCap_VBScript.asp and ...\asp\components\BrowserCap_JScript.asp.
Database Connectivity
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 652 of 659
connection are closed.
Important OLE DB must be properly configured on the server for this sample to run properly.
Location
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\database\SimpleQuery_VBScript.asp and ...\asp\database\SimpleQuery_JScript.asp.
Limit Query Results
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
Important OLE DB must be properly configured on the server for this sample to run properly.
Location
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\database\LimitRows_VBScript.asp and ...\asp\database\LimitRows_JScript.asp.
Scrollable Query
This is preliminary documentation for IIS 5.0 and is subject to change.
Overview
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 653 of 659
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.
Important OLE DB must be properly configured on the server for this sample to run properly.
Location
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\database\MultiScrolling_VBScript.asp and ...\asp\database\MultiScrolling_JScript.asp.
Add/Delete Records
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 654 of 659
The record just added is selected, then deleted by passing the SQL DELETE command directly to the
database engine. The script then terminates.
Important OLE DB must be properly configured on the server for this sample to run properly.
Location
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\database\AddDelete_VBScript.asp and ...\asp\database\AddDelete_JScript.asp.
Update Records
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
Important OLE DB must be properly configured on the server for this sample to run properly.
Location
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\database\Update_VBScript.asp and ...\asp\database\Update_JScript.asp.
Executing Stored Procedures
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 655 of 659
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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\database\StoredProcedures_VBScript.asp
and ...\asp\database\StoredProcedures_JScript.asp.
ASP Transaction Services
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 656 of 659
(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
The VBScript and JScript versions of this script are available in the IIS samples directory,
at ...\asp\transactional\SimpleTransaction_VBScript.asp
and ...\asp\transactional\SimpleTransaction_JScript.asp.
Programmatic Administration Examples
This is preliminary documentation for IIS 5.0 and is subject to change.
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 657 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 658 of 659
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
This is preliminary documentation for IIS 5.0 and is subject to change.
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
This is preliminary documentation for IIS 5.0 and is subject to change.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000
Active Server Pages Guide Page 659 of 659
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.
file://C:\WINNT\Profiles\Administrator\Local Settings\Temp\~hhB820.htm 22/11/2000