Untitled Document

CHAPTER 10
Preprocessing Directives, Server-Side

Includes, and GLOBAL.ASA
This chapter provides a catch-all description of several features of Active Server
Pages applications that do not neatly fit into groups defined on the basis of the
ASP object model:
• Preprocessing directives, the method by which you instruct the web server to
perform certain functions before processing the script in the Active Server
Pages
• Server-Side Includes, which allow you to easily include commonly used code
into your scripts; this allows you to write reusable code that need only be
stored and maintained in one centralized location
• The GLOBAL.ASA file
Preprocessing Directives
Active Server Pages provides preprocessing directives similar to the compiler directives
in C and similar languages. Like these precompilation directives, ASP
directives instruct the web server to perform a function before the script is
completed and sent to the client. The web server performs the other directives
before interpreting the script itself. ASP directives, with the exception of <%=
expression %>, must appear on the first line of a script and cannot be included
using a Server-Side Included file. The format for these directives (with the aforementioned
exception of the <%= expression %> directive) is the following:
<%@ DIRECTIVE=Value%>
where DIRECTIVE is one of the ASP directives listed in this section and Value is a
valid value for the directive. Note that you must include a space between the @
character and the directive. Also note that the preprocessing directive must be
placed within <%...%> delimiters.
142 Chapter 10 – Preprocessing Directives, Server-Side Includes, and GLOBAL.
Preprocessing Directives Reference
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
The valid ASP preprocessing directives are listed as follows and are explained in
depth later in this chapter:
CODEPAGE
ENABLESESSIONSTATE
LANGUAGE
LCID
TRANSACTION
Preprocessing Directives: Comments/Troubleshooting
The space between the @ character and the directive and the requirement that
directives be placed on the first line of a script are syntactically the most important
features of an ASP directive. The failure to include the space or to include
directives on the first line of a script are the most common errors when using
directives.
You may ask yourself how you can have more than one directive in a script if
directives, with the exception of <%= expression %>, must be placed on the first
line of a script. To include more than one directive, use the following syntax:
<%@ DIRECTIVE1=Value DIRECTIVE2=Value %>
You must include at least one space between each directive. Also, you must not
place spaces around the equal signs (=).
Preprocessing Directives Reference
CODEPAGE
<%@CODEPAGE=uintCodePage%>
Sets the character set (or code page) to be used to interpret the script on the
server. Different languages and locales use unique code pages. This directive
provides similar functionality for the interpretation of scripts on the server as the
CodePage property of the Session object provides for client-side interpretation of
the HTML sent to the client. However, it is important to note that the CODEPAGE
preprocessing directive dictates how the script itself is interpreted, whereas the
CodePage property of the Session object dictates how the resulting HTML is
processed.
Parameters
uintCodePage
An unsigned integer value corresponding to a valid code page for the web
server running the ASP script
Example
<%@ CODEPAGE=932%>
' This code sets the code page to OEM 932, which is
' used for Japanese Kanji.
LANGUAGE 143
Directives & GLOBAL.ASA
LANGUAGE
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
Notes
You can have both the CODEPAGE directive and the CodePage property for the
Session object in the same script. This results in the server-side script being interpreted
using the unsigned integer set for the CODEPAGE directive and the client
information being interpreted using the code page set of the CodePage property of
the Session object.
ENABLESESSIONSTATE
<%@ ENABLESESSIONSTATE=True|False%>
Turns the storage of user-specific session information on (True) or off (False).
This value is True by default.
Parameters
None.
Example
<%@ ENABLESESSIONSTATE=False%>
' This code prevents the web server from storing
' user session information.
Notes
You also can enable session-state storage using the registry, but this directive
allows significantly more flexibility (and on a script-by-script basis). If you have
used a registry setting to control session-state information, then using this directive
overrides that setting.
Setting this directive to False prevents you from storing any information in
session-scoped variables or objects. This forces you to rely on other methods of
maintaining information about each user, if you need to. However, it does provide
some benefits:
• It does not rely on your clients’ browsers using cookies.
• It increases the speed with which your server scripting is processed by the
web server.
LANGUAGE
<%@ LANGUAGE=ScriptingEngine%>
Sets the default scripting engine the web server will use to process the script in
your ASP. This is set to VBScript by default.
Parameters
ScriptingEngine
A valid scripting engine recognized by Internet Information Server. The valid
scripting engines include VBScript, JScript, PerlScript, Python, and REXX.
144 Chapter 10 – Preprocessing Directives, Server-Side Includes, and GLOBAL.
LCID
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
Example
<%@ LANGUAGE="JScript"%>
' This code sets the language for the current page to
' JScript, Microsoft's interpretation of the JavaScript
' scripting language. All script on this page will be
' interpreted using the JScript DLL.
Notes
Setting the LANGUAGE directive does not prevent you from using other scripting
engines on your script page. It only sets the default scripting engine for interpretation
of script on the current page. For example, the following example shows how
you can set the default scripting engine for the page to JScript and still use
VBScript for a specific procedure:
<%@ LANGUAGE="JScript"%>
<SCRIPT LANGUAGE="VBScript" RUNAT="Server">
Sub ShowReport()
' This script will be interpreted using the VBScript
' scripting engine.
End Sub
</SCRIPT>
Furthermore, setting the LANGUAGE directive value has no effect on the scripting
engine used on the client side. Even if you set the LANGUAGE of the server-side
script to PerlScript,* for example, you can still set the LANGUAGE attribute of the
client-side <SCRIPT> tag to JScript, as in the following example:
<%@ LANGUAGE="PerlScript"%>
<%
' All server-side script is interpreted using the PerlScript
' scripting engine.
%>
HTML here...
<SCRIPT LANGUAGE="JScript">
Sub btnReport_onClick
' This script will be interpreted using the JScript
' scripting engine.
End Sub
</SCRIPT>
LCID
<%@ LCID=dwordLCID%>
Sets a valid locale identifier for a given script. This directive specifies various
formats (such as dates and times) to use for data on the server side.
* Note that only the VBScript and JScript scripting engines are included with IIS. All other
scripting engines must be obtained and installed separately.
TRANSACTION 145
Directives & GLOBAL.ASA
TRANSACTION
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
Parameters
dwordLCID
A DWORD (32-bit unsigned) value that represents a valid locale ID
Example
<%@ LCID=1036%>
' This code sets the locale ID for the server-side
' script to that for French.
Notes
Just as setting the CODEPAGE directive has no effect on the CodePage property of
the Session object and what character set is used on the client side, setting the
LCID directive has no effect on the LCID used on the client side. However, it is
important to note that the LCID preprocessing directive dictates how the script
itself is interpreted, whereas the LCID property of the Session object dictates how
the resulting HTML is processed.
TRANSACTION
<%@ TRANSACTION=strValue%>
Instructs the web server to treat the entire script as a single transaction. If you set
the script as requiring a transaction, the web server uses Microsoft Transaction
Server to ensure that the entire script is processed as a single unit (or transaction)
or not at all. Currently, only database manipulation is available in transactions.
Parameters
strValue
The possible values for the strValue parameter are as follows:
Required
Instructs the web server that the current script requires a transaction
Requires_New
Instructs the web server that the current script requires a new transaction
Supported
Instructs the web server not to start a transaction
Not_Supported
Instructs the web server not to start a transaction
Example
<%@ TRANSACTION=Required%>
' This code instructs the web server to start a new
' transaction for the current script.
Notes
Note that the value for the TRANSACTION directive is not a string. For this reason,
you must use an underscore for those values that contain a space (Requires_New
146 Chapter 10 – Preprocessing Directives, Server-Side Includes, and GLOBAL.
Server-Side Includes
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
and Not_Supported). As discussed in Chapter 5, ObjectContext Object, only a
single script can be encapsulated in a transaction. You must ensure that the
TRANSACTION directive is the first line in a transactional script. Otherwise, it will
result in an error. Finally, you cannot encapsulate the GLOBAL.ASA code in a
transaction.
If an error occurs in a script encapsulated in a transaction, Microsoft Transaction
Server will roll back any actions that support transactions. Currently, only database
actions support transactions. For example, not all disk activity is supported by
MTS-based transactions and must be rolled back manually.
Server-Side Includes
Similar to preprocessing directives, Server-Side Includes allow you to include
various values (for instance, the last modified date of a file) or a complete file in
your script. The following are the Server-Side Include directives supported by IIS:
#config
Configures the format for error messages, dates, and file sizes as they are
returned to the client browser
#echo
Inserts the value of an environment variable (equivalent to the various
elements of the Request object’s ServerVariables collection) into a client’s
HTML page
#exec
Inserts the results of a command-line shell command or application
#flastmod
Inserts the last modified date/time for the current page
#fsize
Inserts the file size of the current file
#include
Includes the contents of another file into the current file
All directives are allowed in HTML. Only the #include directive, however, is
allowed in both HTML and ASP pages. The #include directive is the only one
detailed here.
Server-Side Includes: Comments/Troubleshooting
Including files is an excellent method for writing reusable code. We use it often
for code we use in almost every script, such as establishing a connection to a database
or closing the connection once your code has no more need of it. Your
Server-Side Include files need not end with any specific file extension, but
Microsoft suggests the .INC file extension as a way of maintaining easily manageable
sets of ASP scripts and include files for your projects. Remember that your
Server-Side Include files cannot include other files, nor can they contain preprocessing
directives described in earlier in this section.
#include 147
Directives & GLOBAL.ASA
#include
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
#include

The #include Server-Side Include allows you to insert the contents of a given file
into the HTML content or ASP script. You must surround the #include Server-
Side Include statement in an HMTL comment. Otherwise, the text of the Server-
Side Include will be displayed as straight text.
Parameters
PathType
The type of path specified in the strFileName parameter. The possible
values for PathType are described in the following table.
strFileName
The strFileName parameter represents the name of the file whose contents
you want inserted into the HTML content.
Example
The following script contains only a simple “back to top” line of code and a horizontal
line with a graphic.
<!—ReturnTop.INC -->
<CENTER>
<HR>
Click <A HREF = #top>here</A> to go back to the top of the
page.<BR>
<IMG SRC = "/Images/CorpLogo.GIF"></CENTER><BR>
We could now include this file anywhere we needed a return to the top of a page:
<HTML>
<HEAD><TITLE>Include Example</TITLE></HEAD>
<BODY>
<%
[CODE TO RETRIEVE GLOSSARY TERMS FROM SQL SERVER DATABASE]
' Filter the recordset to include only the A's.
adoRecGlossary.Filter = "UPPER(SUBSTRING(GlossTerm, 1)) = 'A'"
' Iterate through the items in the filtered recordset.
Do While Not adoRecGlossary.EOF
%>
Term: <%=adoRecGlossary("GlossTerm")%><BR>
Definition: <%=adoRecGlossary("GlossDef")%><BR>
<%
adoRecGlossary.MoveNext
Loop
PathType Value Description
File Treats the value of the strFileName parameter as a relative
path from the current directory
Virtual Treats the value of the strFileName parameter as a full
virtual path
148 Chapter 10 – Preprocessing Directives, Server-Side Includes, and GLOBAL.
#include
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
' Next include the link to top file:
%>

<%
' Repeat for the next letter...
...[additional code]
%>
</BODY>
</HTML>
Notes
The example demonstrates how using include files can reduce the amount of
redundant work you are required to do, but it is very simple. Suppose, as a
second example, that you have an include file containing the DSN of your database,
the username, and the password. You could use that include file all over
your site. It would then be a very simple matter to change username and password:
you’d just change it in the include file.
If you use the #include Server-Side Include to incorporate the contents of an
ASP, you must use the <%...%> pair around any script. Otherwise, the contents of
the file are treated as regular HTML code.
One use for this Server-Side Include is to localize the portions of your script that
are used often, such as database access information. This also allows you to
change usernames and passwords quickly and efficiently. If you choose to use the
#include Server-Side Include in this manner, ensure that whatever file you
include is secured properly.
You can include files within files that are, in turn, included in other files. You can
also include the contents of a given file multiple times in the same script. One
example of this is in a simple error-handling script. For example, consider the
following file:
<%
If Err.Number <> 0 Then
%>
<HTML>
<HEAD><TITLE>Error Notice</TITLE></HEAD>
<BODY>
There has been an error in your script (<%=Request.
ServerVariables("SCRIPT_NAME")%>.<BR>
Please contact customer service at 1-800-555-HELP and tell
them that you've experienced an error in (<%=Request.
ServerVariables("SCRIPT_NAME")%> and that the parameters sent
to the script were the following:<BR>
(<%=Request.ServerVariables("QUERY_STRING")%>.<BR><BR>
We apologize for the inconvenience.
</BODY>
</HTML>
<%
End If
%>
#include 149
Directives & GLOBAL.ASA
#include
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
This file (named ERROR.INC in this example) could then be included into your
script anywhere you think an error might arise. For example, in the following
code, ERROR.INC is included after the ADO connection is established and after the
recordset object is created (note that for this form of error trapping to work, the
Buffer property of the Response object must be set to True):
<%Response.Buffer = True%>
<HTML>
<HEAD><TITLE>Database Info Page</TITLE></HEAD>
<BODY>
<%
Set adoCon = Server.CreateObject("ADODB.Connection")
AdoCon.Open "MyDatabase"

Set adoRec = adoCon.Execute ("SELECT * FROM TopSales")

...[additional code]
%>
</BODY>
In this script, if an error is raised when opening the database connection or when
creating the recordset, the user will see the contents of the ERROR.INC file,
containing a standard error notice and a help line phone number.
When you include a file, make sure that the included file does not include the
current file. This will result in a service-stopping error on the web server, requiring
that you stop and restart the web service.
You must also remember that Server-Side Includes are processed before any script
code. For this reason, you cannot dynamically determine which file to include. For
example, the following script will result in a runtime error:
<%
Dim strFileName
strFileName = "/Apps/CustomConstants.INC"
%>

Finally, Server-Side Includes must be placed outside script delimiters (<%…%>),
<SCRIPT></SCRIPT> tags, and <OBJECT></OBJECT> tags. For example, the
following code will result in a runtime error (there is no closing %> delimiter):
<%
Dim strLastName
strLastName = "Weissinger"

The following code will also fail:
<SCRIPT LANGUAGE="VBScript">
Sub btnHello_Click()
Dim strLastName
strLastName = "Weissinger"
150 Chapter 10 – Preprocessing Directives, Server-Side Includes, and GLOBAL.
GLOBAL.ASA
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.

End Sub
</SCRIPT>
This is the only Server-Side Include that you can use in both HTML and ASP files.
If you use the #include Server-Side Include in a file, that file’s extension must be
one of those mapped to SSINC.DLL, the dynamic link library that interprets Server-
Side Includes.
GLOBAL.ASA
The GLOBAL.ASA file is where you declare objects, variables, and event handlers
(for the OnStart and OnEnd event procedures for the Application and Session
objects, specifically) that have session or application scope. There can be only one
GLOBAL.ASA file per virtual directory or ASP application. For example, suppose
you have a Search ASP application made up of all the scripts in the /Search virtual
directory. You can have only one GLOBAL.ASA file in the virtual directory, and it
must be in the root of the directory (/Search). A second GLOBAL.ASA file
anywhere else in any subdirectory of /Search will be ignored by ASP.DLL.
The GLOBAL.ASA file can contain no displayable content; any such content is
ignored by ASP.DLL. Any script that is not encased in a <SCRIPT> tag results in an
error, as does the instantiation of a server component that does not support
session- or application-level scope. Finally, this file must be named GLOBAL.ASA
and cannot reside anywhere other than in the root of the virtual directory that
makes up the ASP application. Like other scripts, you can use any supported
scripting language in the GLOBAL.ASA file, and you can group event procedures
that use the same language within a common set of <SCRIPT>...</SCRIPT> tags.
The GLOBAL.ASA file section of this chapter covers the following topics:
• Application object events and application scope
• Session object events and session scope
• Type library declarations
GLOBAL.ASA: Comments/Troubleshooting
When you make changes to the GLOBAL.ASA file for an application, the web
server completes all current requests for the given application before recompiling
the GLOBAL.ASA file. According to Microsoft, once the current requests are
processed, the file is recompiled, and any new sessions started in the current
application trigger the processing of the GLOBAL.ASA file code. During this recompilation,
the server ignores all new requests for scripts within the application.
Unfortunately, the reality is that this does not work at all with Personal Web
Server, IIS 3.0, and IIS 4.0. You are forced to reboot the machine before the new
GLOBAL.ASA is processed!
Note that any sessions that remain current during this time are unaffected by your
changes to GLOBAL.ASA. Once the web server has recompiled the GLOBAL.ASA
file, all active sessions are deleted and the Session_OnEnd and Application_OnEnd
event procedures in the (new) GLOBAL.ASA file are called. The users must make a
Application Object Events and Application Scope 151
Directives & GLOBAL.ASA
Application Object Events and Application Scope
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
new request in the web application for new sessions to begin. All new sessions
will start with processing of the new GLOBAL.ASA file.
An important consideration for developing your own GLOBAL.ASA files is that
changing any code included in the file through the use of a Server-Side Include
does not result in the recompilation of the GLOBAL.ASA file by the web server.
You must actually resave the GLOBAL.ASA file (even if it hasn’t changed!) to
trigger its recompilation.
You can have procedures and functions in your GLOBAL.ASA file. However, these
procedures can be called only by the Session_OnStart, Session_OnEnd,
Application_OnStart, and Application_OnEnd event procedures (all of which can
reside only in the GLOBAL.ASA file). If you wish to use these functions/procedures
in other files in your application, you should consider using a Server-Side
Include file containing the script you wish called.
Finally, like all other scripts in your web application, you must be careful to secure
your GLOBAL.ASA file using Windows NT security. Otherwise, clients can access
this file. Considering that the GLOBAL.ASA often contains security-related code for
your application, this caveat is very important.
GLOBAL.ASA Reference
Application Object Events and Application Scope
<SCRIPT LANGUAGE=strLangEngine RUNAT = SERVER>
Sub Application_OnStart
Event procedure code...
End Sub
Sub Application_OnEnd
Event procedure code...
End Sub
</SCRIPT>
In the GLOBAL.ASA file, you can include event procedure code for the two events
of the Application object: OnStart and OnEnd. These two events are triggered
when the first client requests a page within your application and at the end of the
last user’s session in your application, respectively. These events are covered in
detail in Chapter 4, Application Object. In this chapter we will reiterate some of the
topics covered there and how those topics relate to the GLOBAL.ASA file and its
use.
To review the information covered in the Application Object chapter, an ASP
application is made up of all the files in a virtual directory and all the files in
subfolders under that virtual directory. When a variable or object has application
scope, it holds the same value(s) for every current user of the application, and any
user can change the value(s) of an application-scoped variable or object. Such a
change affects the value as viewed by any user thereafter.
152 Chapter 10 – Preprocessing Directives, Server-Side Includes, and GLOBAL.
Application Object Events and Application Scope
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
Parameters
strLangEngine
A string whose value represents the name of a valid server-side scripting
engine. This engine is VBScript by default on IIS web servers, but you can use
JScript, PerlScript, Python, REXX, or any other scripting engine that supports
the IIS scripting context.
Example
[Excerpt from GLOBAL.ASA]
<OBJECT RUNAT=Server
SCOPE=Application
ID=AppInfo1
PROGID="MSWC.MyInfo">
</OBJECT>
<SCRIPT LANGUAGE = "VBScript" RUNAT="Server">
Sub Application_OnStart
Dim objCounters
Dim gdatAppStartDate
' The following object variable will hold a Counters
' component.
Set objCounters = Server.CreateObject("MSWC.Counters")
' The following application-level variable will
' hold the start date of the application.
gdatAppStartDate = Date()
End Sub
Sub Application_OnEnd
' The following code destroys the application-scoped
' Counters component.
Set objCounters = Nothing
' The following clears the application-level variable.
gdatAppStartDate = ""
' NOTE: This code is not strictly necessary in this
' instance as this object and variable will be released
' from memory by the web server itself when the application
' ends. This example simply demonstrates how these event
' procedures work. For suggestions for the Application
' object's use, see the following and Chapter 4.
End Sub
</SCRIPT>
Session Object Events and Session Scope 153
Directives & GLOBAL.ASA
Session Object Events and Session Scope
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
Notes
There are several points to remember about the GLOBAL.ASA file in general and
the Application event procedures, specifically. The first is that there is no reason
that you must have a GLOBAL.ASA file. Your ASP application will function
completely normally without it. In fact, the lack of a GLOBAL.ASA file will increase
the speed of access for the first requested page in your ASP application, since
running the GLOBAL.ASA and then running your requested script will always be
slower than running only the requested script.
Next, if you do have a GLOBAL.ASA file, there is no real need for you to code
your own Application_OnEnd event procedure, since the web server itself will
release the memory used for application-scoped objects and variables at the end of
the application. If, however, you wish to save information (in a database, for
example) specific to a particular application’s run time, you could code for this in
the Application_OnEnd event procedure. For example, you could create an application-
level page counter variable and record its value to a text file at the end of
an application for use the next time the application’s files are requested and the
application is restarted. (Note that there are better ways of performing this operation.)
For further notes on the event procedures of the Application object, see Chapter 4.
Session Object Events and Session Scope
<SCRIPT LANGUAGE=strLangEngine RUNAT = SERVER>
Sub Session_OnStart
Event procedure code...
End Sub
Sub Session_OnEnd
Event procedure code...
End Sub
</SCRIPT>
In the GLOBAL.ASA file, you can include event procedure code for the two events
of the Session object: OnStart and OnEnd. These two events are triggered when a
client requests a page within your application for the first time and at the end of
the user’s session (20 minutes after the user’s last request, by default), respectively.
These events are covered in detail in Chapter 9, Session Object. In this
chapter, we will reiterate some of the topics covered there and how those topics
relate to the GLOBAL.ASA file and its use.
Parameters
strLangEngine
A string whose value represents the name of a valid server-side scripting
engine. This engine is VBScript by default on IIS web servers, but you can use
JScript, PerlScript, Python, REXX, or any other scripting engine that supports
the IIS scripting context.
154 Chapter 10 – Preprocessing Directives, Server-Side Includes, and GLOBAL.
Type Library Declarations
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
Example
[Excerpt from GLOBAL.ASA]
<OBJECT RUNAT=Server
SCOPE=Session
ID=Tool1
PROGID="MSWC.Tools">
</OBJECT>
<SCRIPT LANGUAGE = "VBScript" RUNAT="Server">
Sub Session_OnStart
Dim strUserLogon
Dim StrUserSecurity
' The following session-level variables will hold
' the user's logon name and security clearance.
strUserLogon = Request.ServerVariables("USER_LOGON")
strUserSecurity = "PUBLIC"
End Sub
Sub Session_OnEnd
' The following code destroys the session-scoped
' Tools component.
Set Tool1 = Nothing
' The following clears the session-level variables.
strUserLogon = ""
strUserSecurity = ""
' NOTE: This code is not strictly necessary in this
' instance as this object and variable will be released
' from memory by the web server itself when the session
' ends. This example simply demonstrates how these event
' procedures work. For suggestions for the Application
' object's use, see later in this chapter and Chapter 9.
End Sub
</SCRIPT>
Notes
For notes on the Session event procedures, see Chapter 9.
Type Library Declarations

Type libraries are accessory files that contain information about the properties and
methods of COM objects. These files describe any constants used by the object
and the data types of acceptable property values. A type library enables your
application to more accurately report errors in your use of the object to which the
type library corresponds. It also allows you to use constants defined in the object’s
DLL. This can significantly lower the complexity of an object’s code and increase
the readability and reuse of your code without forcing you to create and use
Server-Side Includes that can be difficult to maintain for all of your objects.
As you know, you can instantiate application-scoped and session-scoped objects
in the GLOBAL.ASA file. If any of these objects have a corresponding type library,
you can declare its use in the application’s GLOBAL.ASA file.
Parameters
FileName
The full physical (not virtual) path and filename of the type library file for the
object in question. If you include both a FileName and a TypeLibraryUUID
parameter to the TypeLibrary declaration, the web server will identify the
type library using the filename. You must include either a FileName or a
TypeLibraryUUID.
TypeLibraryUUID
The universally unique identification number of the type library. This is
different from the UUID for the COM object and is defined in the registry as a
subkey of HKEY_CLASSES_ROOT\TypeLib. If you include both a FileName
and a TypeLibraryUUID parameter to the TypeLibrary declaration, the web
server will identify the type library using the filename. You must include
either a FileName or a TypeLibraryUUID.
MajorVersionNumber
The major version number of the type library. If this optional parameter is
supplied and the web server cannot find the file with the correct major
version number, the web server will raise an error. If you include a
MajorVersionNumber, you must also include a MinorVersionNumber
parameter.
MinorVersionNumber
The minor version number of the type library. If this optional parameter is
supplied and the web server cannot find the file with the correct minor
version number, the web server will raise an error. If you include a
MinorVersionNumber, you must also include a MajorVersionNumber
parameter.
LocaleID
Each type library can support different locales. The LocaleID parameter
represents the locale to use for this type library. If this locale is not found in
the type library, the web server will raise an error. Like the VERSION parameter
of the TypeLibrary declaration, this parameter is optional.
156 Chapter 10 – Preprocessing Directives, Server-Side Includes, and GLOBAL.
Type Library Declarations
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
Example
[Excerpt from GLOBAL.ASA]

Notes
This code declares the use of Version 1.5 of the Report COM object’s type library.
The LCID used is that for French. If Version 1.5 of this COM object’s type library is
not found or the LCID 1306 (for French) is not supported by the type library, the
code will result in an error.
When you use a type library from within an ASP application, you are actually
using a wrapper-encapsulated version of the type library. IIS creates this wrapper
for your type library in the background.
For coding style, Microsoft suggests that you include your type library declarations
near the top of the GLOBAL.ASA file. However, I’ve seen no effect from placing it
in other places in the file. Also, you are not required to place the TypeLibrary
declaration outside of the <SCRIPT> tags.
One problem with using type libraries from multiple COM objects in one ASP
application (especially if the COM objects were written by different developers) is
the redundancy of constants within the object. You can avoid this redundancy by
referring to any constant using the name of the COM object itself as a prefix for
the constant name. For example, the adStoredProcedure constant of the
ADODB type library can be referred to as ADODB.adStoredProcedure.
Finally, the web server can return one of the errors listed in the following table if
you incorrectly declare your type library:
Error Code Description
ASP 0222 An invalid type library declaration.
ASP 0223 Type library does not exist. For example, if the type library listed
in the METADATA tag does not exist, you will receive this error.
ASP 0224 The type library you declared cannot be loaded for some
unknown reason, even though it was successfully found.
ASP 0225 The web server is unable, for whatever reason, to create a
wrapper for the type library you declared in the METADATA tag.
ASP in a Nutshell: A Desktop Quick Reference, eMatter Edition
Copyright © 2000 O’Reilly & Associates, Inc. All rights reserved.
PART III
Installable Component
Reference
The following chapters cover the installable components that come with
IIS 4.0:
Chapter 11, ActiveX Data Objects 1.5
Chapter 12, Ad Rotator Component
Chapter 13, Browser Capabilities Component
Chapter 14, Collaboration Data Objects for Windows NT Server
Chapter 15, Content Linking Component
Chapter 16, Content Rotator Component
Chapter 17, Counters Component
Chapter 18, File Access Component
Chapter 19, MyInfo Component
Chapter 20, Page Counter Component
Chapter 21, Permission Checker Component