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 re-compilation, 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 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.
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>
  
<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. 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.
 
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>
 
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>
  
<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 10. 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.
 
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 strLogonUser
    Dim StrUserSecurity

    ' The following session-level variables will hold
    ' the user's logon name and security clearance.
    strLogonUser = 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.
    strLogonUser = "
    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 10.

End Sub

</SCRIPT>
 
Notes

For notes on the Session event procedures, see Chapter 10.

 
Type Library Declarations   
<!-- METADATA TYPE="TypeLibrary"
FILE="FileName"
UUID="TypeLibraryUUID"
VERSION="MajorVersionNumber.MinorVersionNumber"
LCID="LocaleID"
-->
  
<!-- METADATA TYPE="TypeLibrary"
FILE="FileName"
UUID="TypeLibraryUUID"
VERSION="MajorVersionNumber.MinorVersionNumber"
LCID="LocaleID"
-->

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.
 
Example 
[Excerpt from GLOBAL.ASA]

<!-- METADATA TYPE="TypeLibrary"
FILE="Report.LIB"
VERSION="1.5"
LCID="1306"
-->
 
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.