[Previous] [Table of Contents] [Next]

Creating and Releasing Objects

If an object isn't exposed automatically from WSH (as is the case with WScript), you must "create" the object before using it—that is, you must load an instance of the object into memory and assign a reference to it to an object variable. The following statement uses the CreateObject method in VBScript to create an object:

Set Object_variable = WScript.CreateObject("ProgID")

JScript uses the following syntax:

var Object_variable = WScript.CreateObject("ProgID");

The only object variable that WSH exposes automatically is WScript. You must create all other objects explicitly. In VBScript, you create the object variable (which is used to keep the object) by using the Set keyword. You can use any valid name for the object variable (such as objAdr or WshObj).

To create the WshShell object, you can use the following statement in VBScript:

Set WshShell = WScript.CreateObject("WScript.Shell")

A JScript statement has the same syntax except that the keyword Set is replaced by var and the line terminates with a semicolon. Let's look again at the statements shown at the beginning of this section. WScript.CreateObject tells the language engine that you want to create an object and get a reference to it. You pass the ProgID within parentheses as a parameter to CreateObject. This ProgID identifies the object. In the statement above, the ProgID for the WshShell object is "WScript.Shell".

The hardest part of this process is getting the ProgID for an object. The examples in this book include the requested ProgIDs. You have to get the ProgIDs of foreign objects from their program documentation. If the documentation is missing, you can use tools such as the OLE/COM Object Viewer to determine an object's ProgID. The Object Browser of the Microsoft Visual Basic 5 Control Creation Edition (CCE) and Microsoft Office also give you the ProgID of a component. My book Advanced Development with Microsoft Windows Script Host 2.0 discusses these more advanced ways to obtain an object's ProgID.

The preceding statement contains the word WScript twice, which might confuse you. The term WScript in WScript.CreateObject is an object; the word WScript in the parameter "WScript.Shell" is the ProgID of the object library.

When you use the CreateObject method, you must be careful about the object hierarchy. In Chapter 6, I mentioned that objects can contain other objects. The dependencies are described within the object model. For example, an application such as Microsoft Word can contain a document. To access the document object, you use the CreateObject method on the application object and then on the document object. Keep in mind that using CreateObject is only one way to create an object. You'll learn about other ways later in this book.

CreateObject vs. GetObject

The WScript object exposes two methods for creating a new object reference: CreateObject and GetObject. CreateObject creates an object and establishes its event handling, and GetObject retrieves an Automation object from a file. What, exactly, is the difference between these two methods?

The CreateObject method creates the object specified in the strProgID parameter. You already saw a simple version of a CreateObject call that uses only one parameter. The CreateObject method also has a second, optional parameter, as shown here:

Set objAdr = WScript.CreateObject(strProgID[, strPrefix])

The first parameter contains the object's ProgID ("WScript.Shell", for example). The optional parameter strPrefix can contain a prefix string. If this parameter is specified, the method connects the script to the outgoing interface of the object after creating this object. This connection allows you to use event handling using callback functions declared within the script. For example, if strPrefix is set to "Test_" and the object fires an event named OnBegin, WSH calls the function Test_OnBegin in the script. (Listing 7-14 uses this method.) I'll discuss this technique in detail in Chapter 9.

You can also access objects by using the GetObject method, which retrieves an Automation object from a file or an object specified by the strProgID parameter. You use the GetObject method when there's a current instance of the object or when you want to create the object from a file that's already loaded. If there's no current instance and you don't want the object started from a file that's already loaded, use the CreateObject method instead.

The GetObject method has this syntax (which is similar to that of CreateObject):

Set objAdr = WScript.GetObject(strPathname[, [strProgID][, strPrefix]])

The strPathname parameter specifies the path to the file containing the Automation object. The optional parameter strProgID contains a string with the object's ProgID so that the method can load the object using Registry entries. The third parameter connects the script to the object's outgoing interface. The second and third parameters have the same meaning as the corresponding parameters of the CreateObject method.

Using DisconnectObject

When you create an object using GetObject or CreateObject, the object is loaded into memory and remains connected to WSH until the script terminates. The script can use the second optional parameter in CreateObject to connect a script's event handler to the outgoing interface of this object. Then the object can raise an event that is handled from an event handler within the script. You can use the DisconnectObject method to disconnect the object from the event handling procedure during the script's lifetime:

WScript.DisconnectObject Object_name

Object_name is the name of an object variable. In VBScript, you can also reset the object variable:

Object_name = Nothing

Listing 7-14 uses this method. It launches Internet Explorer with an empty page and establishes event handling for Internet Explorer's DownloadBegin and OnQuit events. Because of the DisconnectObject call, the IE_OnQuit event handler procedure is never called. If you comment this line, the sample raises a dialog box after calling oIE.Quit.

Listing 7-14 Disconnect.vbs

' File:    Disconnect.vbs (WSH sample in VBScript) 
' Author:  (c) G. Born
' Using the DisconnectObject method to disconnect
' from Internet Explorer event handling
Option Explicit

Dim oIE

' Launch Internet Explorer, and define event-handler prefix.
Set oIE = WScript.CreateObject( _
            "InternetExplorer.Application", "IE_")
oIE.navigate "about:blank"        ' Empty page
oIE.visible = 1                   ' Visible

' Pause script by displaying a message box.
WScript.Echo "Please click OK"

WScript.DisconnectObject oIE  ' Disconnect from Internet Explorer.

oIE.Quit                      ' Terminate Internet Explorer.  

WScript.Echo "Disconnected"

' Script terminates here.
' Here are the Internet Explorer event handlers.

Sub IE_DownloadBegin()
    ' Raised from loading a document in Internet Explorer
    WScript.Echo "Event: Download begins"
End Sub

Sub IE_OnQuit()
    ' Raised from quitting Internet Explorer, but we're
    ' disconnecting from the object before calling
    ' the Quit method to terminate Internet Explorer, so 
    ' the dialog box isn't shown.
    WScript.Echo "Event: Quit Internet Explorer"
End Sub

'*** End