VBScript Objects

In this chapter, you will examine how VBScript interacts with its environment by working with objects. This will include an examination of VBScript's built-in and run-time objects as well as a complete listing of the objects' associated properties and methods. In addition, you'll get a brief overview of the importance of browser- and WSH-specific objects. You will also learn how to create your own custom objects replete with their own sets of properties and methods.

VBScript Object Based Programming

In order to get any real work done, VBScript depends upon the use of objects. An object provides access to system resources and data manipulation structures by way of methods and properties. Methods are functions built into objects that, when executed, interact with or manipulate the resources represented by the objects. Properties are qualities of the resources represented by objects that describe the resource in some manner. Some properties are read-only, allowing VBScript to collect information about the resource. Other properties can be modified, thus providing the ability to directly change some quality of a resource represented by an object.

By itself, VBScript has only limited capabilities. It cannot access HTML page elements, the Windows file system, or other system resources. VBScript supplies only a small collection of built-in objects. These objects provide VBScript with the ability to react to errors and to parse and extract data from strings. VBScript's built-in objects are listed in Table 7.1.

Table 7.1: VBScript Built-in Objects

Object	Description
Class	Provides the ability to create custom objects Properties: This object does not support any properties Methods: This object does not support any methods Events: Initialize, Terminate
Err	Provides details about run-time errors Properties: Description, HelpContext, HelpFile, Number, Source Methods: Clear, Raise Events: This object does not support any events
Match	Accesses read-only properties of a regular expression match Properties: FirstIndex, Length, Value Methods: This object does not support any methods Events: This object does not support any events
Matches Collection	A collection of regular expression Match objects Properties: This object does not support any properties Methods: This object does not support any methods Events: This object does not support any events
RegExp	Supports regular expressions Properties: Global, IgnoreCase, Pattern Methods: Execute, Replace, Test Events: This object does not support any events
SubMatches Collection	Accesses read-only values of regular expression submatch strings Properties: This object does not support any properties Methods: This object does not support any methods Events: This object does not support any events

Note

VBScript's built-in collection of objects is provided by the VBScript interpreter. These objects are available to all VBScripts regardless of the environment in which they are executed.

Properties Belonging to VBScript s Built in Objects

As Table 7.1 indicates, VBScript's built-in collection of objects provides access to a number of different properties. Table 7.2 lists each of these properties and describes their purpose.

Table 7.2: VBScript Object Properties

Property	Description
Description	Retrieves an error message
FirstIndex	Returns the first position of a specified substring in a string
Global	Changes or retrieves a Boolean value
HelpContext	Retrieves the context ID of a Help file topic
HelpFile	Returns the path to a Help file
IgnoreCase	Retrieves a Boolean value that indicates whether a pattern search is case-sensitive
Length	Returns the length of a search string match
Number	Returns the error number for the specified error
Pattern	Retrieves the regular expression pattern in a search operation
Source	Retrieves the name of the object that generates an error
Value	Returns the value of a search string match

Methods Belonging to VBScript s Built in Objects

VBScript's built-in Err and RegExp objects provide access to a small number of methods. Table 7.3 lists each of these methods and describes their purpose.

Table 7.3: VBScript Object Methods

Object	Method	Description
Err	Clear	Clears an Err object's property settings
Err	Raise	Used to simulate a run-time error
RegExp	Execute	Performs a regular expression search against a string
RegExp	Replace	Replaces text in a regular expression search
RegExp	Test	Performs a regular expression search against a string

Working with VBScript s Built in Objects

As Table 7.1 shows, VBScript provides a number of built-in objects. These objects provide the ability to perform all of the following actions:

• Work with VBScript run-time errors
• Define custom objects and assign to them properties and methods
• Perform character and pattern matching using regular expressions

The next several sections cover some of these objects and their capabilities.

The Err Object

You already learned how to work with the built-in Err object back in Chapter 6, "Data Collection, Notification, and Error Reporting." This object provides access to run-time error information by providing access to the following properties:

• Description. A string describing the error condition
• Error Number. The VBScript error number associated with the error
• Source. The name of the resource that reported the error
• HelpContext. Sets a context ID for a topic in the specified Help file
• HelpFile. The name and location of an external file containing help information

In addition, this object provides two methods for working with errors:

• Clear(). Deletes information stored by the Err object regarding the current error
• Raise(). Provides the ability to generate and test run-time errors

The Class Object

VBScript provides support for a number of different data subtypes, including strings and dates. VBScript also supports the more complex array data structure. VBScript provides the Class object as a means of creating a customized complex data structure, or custom objects. By creating your own custom objects, you can encapsulate data functions to create new objects, which your VBScripts can then access like any other objects. Creating custom objects provides your scripts with a tool that helps ensure data consistency, because it allows you to define procedures for validating and enforcing object properties and for controlling object manipulation.

Class Object Syntax

Custom objects are created using the Class…End Class statement. The Class object therefore provides a template for defining other objects and their structures. Once defined, these objects can be instantiated just like another object. The syntax for this statement is outlined below.

Class ClassName
 Statements
End Class

ClassName represents the name to be assigned to the new object. Statements represent the variables, properties, and methods defined within the object. Methods are established by defining the Sub or Function procedures. Properties are defined by using any of the following statements to manipulate variables defined within the Class…End Class statement:

• Property Get. Provides the ability to retrieve the value assigned to a private variable
• Property Let. Provides the ability to change the value assigned to a private variable
• Property Set. Provides the ability to change the value of an object variable

Creating Variables, Properties, and Methods

Variables, properties, and methods can be defined as public (accessible throughout the script) or private (available only within the Class) using the Public and Private keywords. Unless specified, Public is always assumed.

Note

Although you can allow variables defined within the Class…End Class statement to have a public scope, this is not recommended. This prevents you from being able to validate the value assigned to the variable from within the object. Instead, it is recommended that you make all variables private and expose them using the Property Get and Property Let statements. This way, you can build data-validation logic into your object and ensure data integrity.

The following example demonstrates how to use the Class object to create a custom object called Customer.

Class Customer

 Private strCustName

 Public Property Get CustomerName
 CustomerName = strCustName
 End Property

 Public Property Let CustomerName (strNameAssignment)
 StrCustName = strnameAssignment
 End property

 Function DisplayName
 MsgBox(strCustName)
 End Function
End Class

The first statement defines a private variable named strCustName. The next three statements use that variable to create a property and make it readable. The three statements that follow make the property writable. Finally, the last three statements within the Class…End Class statement define a function that will serve as an object method.

Now that a new object has been defined, you can instantiate it, as shown below.

Dim objCustName
Set objCustName = New Customer

You can then store a customer's name to the object.

objCustName.CustomerName = "ABC Inc."

You can then execute the object's DisplayGreeting() method.

objCustName.DisplayName()

Note

Data stored in objects is destroyed as soon as the script ends. This has a somewhat limiting effect on its value. However, there are a number of ways to store and retrieve object data. For example, when working with the WSH, you could write object data to a file or store it in a system variable. Similarly, when using VBScript in Web page development, you could store nonsensitive object data locally on client computers using cookies.

Setting Up Initialization and Termination Procedures

Objects created by the Class…End Class statement support the following events:

• Class_Initialize. If present, this method executes whenever an instance of the object is created, providing an opportunity to perform initialization tasks such as defining initial variable values.
• Class_Terminate. If present, this method executes whenever an instance of the object is destroyed, providing an opportunity to perform any required cleanup tasks.

The following statements demonstrate how to trigger statement execution based on the occurrence of the Class_Initialize and Class_Terminate events.

Private Sub Class_Initialize
 MsgBox("The Class_Initialize Subroutine is executing!")
End Sub

Private Sub Class_Terminate
 MsgBox("The Class_Terminate Subroutine is executing!")
End Sub

Once added inside a Class…End Class statement, these events will automatically execute whenever a new instance of the associated object is created or destroyed.

Note

You can create a new instance of a custom object using the Set statement and the New keywords, as demonstrated below.

 Set objCustName = New Customer

Similarly, you can destroy a custom object using the Set statement.

 Set objCustName = Nothing

Nothing is a VBScript keyword that disassociates an object variable from an object. As long as no other object variables refer to the object in question, the memory used to store its data is released.

The RegExp Object and Other Related Objects

Except for the Err object and the Class object, all the rest of VBScript's built-in objects are designed to work with regular expressions. A regular expression is a pattern of text made up of characters and metacharacters. Regular expressions provide the ability to identify patterns and perform complex search and replace operations.

The RegExp object allows you to work with regular expressions in VBScript. To add a RegExp object to your VBScripts, you must first define a variable to represent it and then use the New keyword to instantiate it, as demonstrated below.

Dim regExpObj
Set regExpObj = New RexExp

The RegExp object has three properties:

• Pattern. Specifies the regular expression pattern to be matched
• IgnoreCase. A Boolean value that determines whether a case-sensitive search is performed
• Global. A Boolean value that determines whether all occurrences of a pattern match should be replaced

In addition, the RegExp object provides a number of methods, one of which is the Replace() method. This method replaces the matching text patterns in a search string. Its syntax is shown in the following statement.

RegExp.Replace(String1, String2)

String1 is the string in which the replacements are to occur and String2 is the replacement string.

For example, the following statements demonstrate how to use the RegExp object to search a string variable called strQuote and replace an occurrence of the word child.

Dim regExpObj, strQuote
Set regExpObj = New RegExp
regExpObj.Pattern = "boy"
strQuote = "Once upon a time there was a little boy."
MsgBox RegExpObj.Replace(strQuote, "child")

The first two statements in this example define and create an instance of the RegExp object named regExpObj. The next line uses the RegExp project's Pattern property to set a search pattern. The statement that follows sets up the string to be searched. Finally, the last statement in the example replaces the first occurrence of the characters boy with the characters child (the value assigned to the RegExp Pattern property).

The previous example replaces only the first occurrence of the specified pattern match. However, you can modify the search pattern as shown below to search for and replace all pattern matches in the search string.

Dim regExpObj, strQuote
Set regExpObj = New RegExp
regExpObj.Pattern = "boy"
regExpObj.Global = True
strQuote = "Once upon a time there was a little boy."
MsgBox RegExpObj.Replace(strQuote, "child")

As you can see, a new statement has been added to the example, which uses the Global property of the RegExp property to replace all matching instances in the search string. VBScript also supplies a number of metacharacters that you can use when working with the RegExp object's Pattern property. For example, the following statements perform a pattern replacement using a range of values:

Dim regExpObj, strQuote
Set regExpObj = New RegExp
regExpObj.Pattern = "[d]"
regExpObj.Global = True
strQuote = "Your customer number is 8."
MsgBox RegExpObj.Replace(strQuote, "1008")

The d metacharacter specifies that any single digit should be used as the replacement string. In the case of this example, the number 8 is replaced with the number 1008. Table 7.4 lists the metacharacters supported by VBScript regular expressions.

Table 7.4: VBScript Object Methods

Character	Description
	Sets the next character as a special character, a back reference, a literal, or an octal escape
⁁	Matches the beginning of the input string
$	Matches the end of the input string
*	Matches the preceding expression (zero or more times)
+	Matches the preceding expression (one or more times)
?	Matches the preceding expression (zero or one time)
{n}	Matches exactly n times
{n,}	Matches a minimum of n times
{n, m}	Matches a minimum of n times and a maximum of m times
.	Matches any individual character except the newline character
(pattern)	Matches a pattern and allows the matched substring to be retrieved from the Matches collection.
x|y	Matches x or y
[xyz]	Matches any of the specified characters
[⁁xyz]	Matches any character except those specified
[a-z]	Matches any character specified in the range
[⁁a-z]	Matches any character except for those specified in the range
	Matches on a word boundary
B	Matches on a non-word boundary
cx	Matches the control character specified as x
d	Matches a single digit number
D	Matches any single non-numeric character
f	Matches the form-feed character
	Matches the newline character
	Matches the carriage return character
s	Matches any white space character (for example, space, tab, form-feed)
S	Matches any non-white-space character
	Matches the tab character
v	Matches the vertical tab character
w	Matches any word character
W	Matches any non-word character
xn	Matches n, where n is a two-digit hexadecimal escape value
num	Matches num, where num is a positive integer in a backward reference to captured matches
	Specifies an octal escape value or a back reference
nml	Matches octal escape value nml where n is an octal digit in the range of 0–3 and m and l are octal digits in the range of 0–7
un	Matches n, where n is a four-digit hexadecimal Unicode character

The RegExp object provides two additional methods, as outlined below.

• Test(). Searches a regular expression and returns a Boolean value indicating whether a matching pattern was found
• Execute(). Creates a Matches collection from a search of a regular expression

The Test() Method

The Test() method allows you to check whether a string contains a pattern match. It has the following syntax:

RegExp. Test(string)

For example, the following statements demonstrate how to use the Text() method to report on the presence or absence of a pattern match:

Dim regExpObj, strQuote
Set regExpObj = New RegExp
regExpObj.Pattern = "boy"
strQuote = "Once upon a time there was a little boy."
If regExpObj. Test(strQuote) = True Then
 MsgBox "Match Found"
Else
 MsgBox "No Match Found"
End If

The Execute() Method

The RegExp object's Execute() method creates a Matches collection from a search of a regular expression and has the following syntax:

RegExp.Execute(string)

The resulting Matches collection is read-only, as are the individual Match objects that make up the collection. Once created, you can loop through each object in the Matches collection and process it, as demonstrated in the following example.

'*************************************************************************
'Script Name: Script 7.1.vbs
'Author: Jerry Ford
'Created: 02/05/2003
'Description: Performing Regular Expression pattern replacements
'*************************************************************************

'Initialization Section

Option Explicit

Dim regExpObj, strQuote, colMatchStmts, strDisplayText, intCount, Match
Set regExpObj = New RegExp

regExpObj.Pattern = "File" 'Specify the string to search for

regExpObj.Global = True 'Perform a global pattern match

'Specify the string to be searched
strQuote = "Filename filename logFile logfile File file"


'Main Processing Section

CreateMatchesCollection()
ProcessMatchesConnection()
DisplayResults()


'Procedure Section

Sub CreateMatchesCollection()
 'Use the RegExp object's Execute() method to create a matches collection
 Set colMatchStmts = regExpObj.Execute(strQuote)
End Sub

Sub ProcessMatchesConnection()
 'Set up a counter to count the number of matches found
 intCount = 0
 'Loop through the Matches collection
 For Each Match in colMatchStmts
 'Build a string that displays the location where each match was found
 strDisplayText = strDisplayText & "A match occurred at position " & _
 Match.FirstIndex & vbCrLf
 intCount = intCount + 1
 Next
End Sub

Sub DisplayResults()
 'Display the results
 MsgBox "Total number of matches = " & intCount & vbCrLf & vbCrLf & "" & _
 strDisplayText
End Sub

In this example, a Matches collection consisting of three Match objects is created using the RegExp object's Execute() method. Each of these match objects has its own set of associated properties, including the FirstIndex property, which specifies the location in the search string where a match is found. A For Each…Next loop is then used to assemble a display string that shows the location of each pattern match, as shown in Figure 7.1.

Figure 7.1: Processing the contents of a Matches collection created by the RegExp object's Execute() method

Other Collections of Objects Available to VBScript

VBScript's limited built-in collection of objects makes it a safe scripting language, meaning that it has no inherent ability to affect the environment in which it operates. In order to operate in and control the environment in which it executes, VBScript depends on external collections of objects.

Browser Based Objects

VBScripts that are executed within HTML pages and loaded into Internet Explorer have access to two different collections of objects. The first collection of objects is referred to as the DHTML (Dynamic HTML) object model. This is an older object model originally developed for Internet Explorer versions 3 and 4. The DHTML object model is also supported by Internet Explorer 5 and 6 for the purposes of backward compatibility. The second collection of objects is known as the DOM (Document Object Model). This object model provides VBScript with the ability to access and control objects on an HTML page, such as links, images, frames, forms, and form elements.

Note

For more information on the object models provided by Internet Explorer, refer to Chapter 8, "VBScript and Internet Explorer."

Objects Available When Executed in the WSH

When VBScripts are executed by the WSH, they have access to two different sets of objects. One set of objects available to VBScripts executed by the WSH is referred to as the WSH core object model. The objects that make up this object model provide access to a collection of Windows resources, including the Windows desktop, file system, registry, and network resources.

Note

For more information on the WSH object model, refer to Chapter 9, "VBScript and the WSH."

The second set of objects is referred to as VBScript run-time objects. These objects are provided by an external DLL (Dynamic Link Library) named scrrun.dll. They provide VBScript with the ability to access the Windows file system. In addition, the VBScript run-time objects include an object known as a Dictionary object. The Dictionary object allows you to store data in an associative array and to retrieve the data stored in that array using keys instead of an index position as is the case with regular VBScript arrays. VBScript's run-time objects are listed in Table 7.5.

Table 7.5: VBScript Run-Time Objects

Object Name	Description
Dictionary	Stores data key, item pairs Properties: Count, Item, Key Methods: Add, Exists, Items, Keys, Remove, RemoveAll
Drive	Provides script with access to disk properties Properties: AvailableSpace, DriveLetter, DriveType, FileSystem, FreeSpace, IsReady, Path, RootFolder, SerialNumber, ShareName, TotalSize, VolumeName Methods: This object does not support any methods
Drives Collection	Provides script with access to information regarding a drive's location Properties: Count, Item Methods: This object does not support any methods
File	Provides script with access to file properties Properties: Attributes, DateCreated, DateLastAccessed, DateLastModified, Drive, Name, ParentFolder, Path, ShortName, ShortPath, Size, Type Methods: Copy, Delete, Move, OpenAsTextStream
Files Collection	Provides scripts with access to files stored in a specified folder Properties: Count, Item Methods: This object does not support any methods
FileSystemObject	Provides scripts with access to the file system Properties: Drives Methods: BuildPath, CopyFile, CopyFolder, CreateFolder, CreateTextFile, DeleteFile, DeleteFolder, DriveExists, FileExists, FolderExists, GetAbsolutePathName, GetBaseName, GetDrive, GetDriveName, GetExtensionName, GetFile, GetFileName, GetFolder, GetParentFolderName, GetSpecialFolder, GetTempName, MoveFile, MoveFolder, OpenTextFile
Folder	Provides scripts with access to folder properties Properties: Attributes, DateCreated, DateLastAccessed, DateLastModified, Drive, Files, IsRootFolder, Name, ParentFolder, Path, ShortName, ShortPath, Size, SubFolders, Type Methods: Copy, Delete, Move, OpenAsTextStream
Folders Collection	Provides scripts with access to folders located within another folder Properties: Count, Item Methods: Add

Properties Belonging to VBScript Run-Time Objects

VBScript run-time objects provided by the WSH offer an extensive collection of properties. These properties provide information about the Windows file system and Windows files and folders. Table 7.6 contains a complete list of run-time properties.

Table 7.6: VBScript Run-Time Properties

Property Name	Description
AtEndOfLine	Returns a value of either True or False based on whether the file pointer has reached the TextStream file's end-of-line marker
AtEndOfStream	Returns a value of either True or False based on whether the end of a TextStream file has been reached
Attributes	Modifies or retrieves file and folder attributes
AvailableSpace	Retrieves the amount of free space available on the specified drive
Column	Retrieves the current column position in a TextStream file
CompareMode	Sets or returns the comparison mode used to compare a Dictionary object's string keys
Count	Returns a value representing the number of items in a collection or Dictionary object
DateCreated	Retrieves a file or folder's creation date and time
DateLastAccessed	Retrieves the date and time that a file or folder was last accessed
DateLastModified	Retrieves the date and time that a file or folder was last modified
Drive	Retrieves the drive letter where a file or folder is stored
DriveLetter	Retrieves the specified drive's drive letter
Drives	Establishes a Drives collection representing all the drives found on the computer
DriveType	Returns a value identifying a drive's type
Files	Establishes a Files collection to represent all of the File objects located within a specified folder
FileSystem	Retrieves the name of the file system used on the specified drive
FreeSpace	Retrieves the amount of free space available on the specified drive
IsReady	Returns a value of either True or False based on the availability of the specified drive
IsRootFolder	Returns a value of either True or False based on whether the specified folder is the root folder
Item	Retrieves or sets an item based on the specified Dictionary object key
Key	Sets a Dictionary object key
Line	Retrieves the current line number in the TextStream file
Name	Gets or modifies a file or folder's name
ParentFolder	Returns a reference the specified file or folder's parent folder object
Path	Retrieves the path associated with the specified file, folder, or drive
RootFolder	Retrieves the Folder object associated with the root folder on the specified drive
SerialNumber	Retrieves the specified disk volume's serial number
ShareName	Retrieves the specified network drive's share name
ShortName	Retrieves the specified file or folder's 8.3 character short name
ShortPath	Retrieves a file or folder's short path name associated with a file or folder's 8.3 character name
Size	Returns the number of bytes that make up a file or folder
SubFolders	Establishes a Folders collection made up of the folders located within a specified folder
TotalSize	Retrieves a value representing the total number of bytes available on a drive
Type	Retrieves information about the specified file's or folder's type
VolumeName	Gets or modifies a drive's volume name

Methods Belonging to VBScript Run-Time Objects

VBScript's run-time methods provide the ability to access the Windows file system; to create, modify, and delete files and folders; and to create and process text files. Table 7.7 contains a complete list of the methods provided by VBScript's run-time objects.

Table 7.7: VBScript Run-Time Methods

Method Name	Description
Add (Dictionary)	Adds a key and item pair to a Dictionary object
Add (Folders)	Adds a Folder to a collection
BuildPath	Appends a name to the path
Close	Closes an open TextStream file
Copy	Copies a file or folder
CopyFile	Copies one or more files
CopyFolder	Recursively copies a folder
CreateFolder	Creates a new folder
CreateTextFile	Creates a file and a TextStream object so that it can be read from and written to
Delete	Deletes a file or folder
DeleteFile	Deletes a file
DeleteFolder	Deletes a folder's contents
DriveExists	Returns a value of True or False based on whether a drive exists
Exists	Returns a value of True or False based on whether a key exists in a Dictionary object
FileExists	Returns a value of True or False based on whether the specified file can be found
FolderExists	Returns a value of True or False based on whether the specified folder can be found
GetAbsolutePathName	Retrieves a complete path name
GetBaseName	Retrieves a file name without its file extension
GetDrive	Returns the Drive object associated with the drive in the specified path
GetDriveName	Returns the name of a drive
GetExtensionName	Returns a file's extension
GetFile	Returns a File object
GetFileName	Returns the last file name or folder of the specified path
GetFileVersion	Returns a file's version number
GetFolder	Returns the Folder object associated with the folder in the specified path
GetParentFolderName	Returns the name of the parent folder
GetSpecialFolder	Returns a special folder's name
GetTempName	Returns the name of a temporary file or folder
Items	Returns an array where items in a Dictionary object are stored
Keys	Returns an array containing the keys in a Dictionary object
Move	Moves a file or folder
MoveFile	Moves one or more files
MoveFolder	Moves one or more folders
OpenAsTextStream	Opens a file and retrieves a TextStream object in order to provide a reference to the file
OpenTextFile	Opens a file and retrieves a TextStream object in order to provide a reference to the file
Read	Returns a string containing a specified number of characters from a TextStream file
ReadAll	Reads the entire TextStream file and its contents
ReadLine	Reads an entire line from the TextStream file
Remove	Deletes a Dictionary object's key, item pair
RemoveAll	Deletes all Dictionary objects' key, item pairs
Skip	Skips a specified number of character positions when processing a TextStream file
SkipLine	Skips an entire line when processing a TextStream file
Write	Places a specified string in the TextStream file
WriteBlankLines	Writes a specified number of newline characters to the TextStream file
WriteLine	Writes the specified string to the TextStream file

The Run-Time Dictionary Object

All of the VBScript run-time objects, except for the Dictionary object, are designed to work with files and the Windows file system. Use of these objects is covered extensively in Parts III, IV, and V of this book. This section provides a review of the Dictionary object.

The Dictionary object and the FileSystemObject object are the two top-level VBScript run-time objects. The Dictionary object provides the ability to set up an associative array based on key and item pairs. In other words, unlike traditional VBScript arrays, which store and retrieve data based on its indexed position within the array, items stored in a Dictionary object are stored and retrieved using a key. This key can be a number, a string, or any of the data subtypes supported by VBScript. The Dictionary object does not even support the use of index numbers because it does not store items based on order. The Dictionary object has all the benefits of an array while providing greater flexibility in storing and retrieving data. In addition, the Dictionary object provides a number of properties and methods that enhance your ability to control data stored in a Dictionary object.

The Dictionary object supports three properties:

• Count. Retrieves the number of items stored in a Dictionary object
• Item. Retrieves or adds an item with a specified key in a Dictionary object
• Key. Adds a key in a Dictionary object

In addition, the Dictionary object provides access to the following methods:

• Add. Adds a key and item pair to a Dictionary object
• Exists. Returns a Boolean value of True if a specified key exists in the Dictionary object and False if it does not
• Items. Returns an array containing all the items in a Dictionary object
• Keys. Returns an array containing all existing keys in a Dictionary object
• Remove. Removes a key, item pair from a Dictionary object
• RemoveAll. Removes all key, item pairs from a Dictionary object

To better demonstrate the implementation of the Dictionary object, consider the following example. To add an instance of the Dictionary object to a VBScript, you must first define a variable by which it can be referenced and then create an instance of the object.

Dim dicObject
Set dicObject = CreateObject("Scripting.Dictionary")

Once instantiated, you may then store items in the object along with their associated keys, as demonstrated below.

dicObject.Add "Aug2003Rpt", "AugReports.txt"
dicObject.Add "Sep2003Rpt", "SepReports.txt"
dicObject.Item("Oct2003Rpt") = "OctReports.txt"

The first two statements add data to the Dictionary object using the Add() method. The first argument specified is the key that is to be associated with the data, which follows as the second argument. The last statement adds a third piece of data by using the Item() property, thus demonstrating that if you reference a key/item pair that does not exist, VBScript will automatically add it for you.

Once you have populated your Dictionary object with data, you can come back and work with its data. For example, the following statements use the Exists() method to determine whether a key/item pair exists. If it does, then the Item() method retrieves and displays a data element by supplying its associated key.

If dicObject.Exists("Sep2003Rpt") = True Then
 MsgBox "The value stored in Sep2003Rpt is " & dicObject.Item("Sep2003Rpt")
End If

Removing key/item pairs from a Dictionary object is just as easy as adding them. For example, the following statement shows how to use the Remove() method to delete a data element using its associated key:

DicObject.Remove "Sep2003Rpt"

Alternatively, if you prefer to delete all the data stored in a Dictionary object, you may do so using the RemoveAll() method, as shown below.

DicObject.RemoveAll

Summary

In this chapter, you were presented with a complete listing of VBScript's built-in and run-time objects. In addition to reviewing these objects and their associated properties and methods, you learned how to create your own custom objects. You also learned how to create an associative array using the Dictionary object when developing VBScripts that run with the WSH. Other object models were also discussed, including those provided by Internet Explorer and the WSH.