Before you can manage disk drives on a computer, you need to know which disk drives are actually available on that computer. The FileSystemObject allows you to return a collection of all the drives installed on a computer, including removable drives and mapped network drives (in other words, any drive with a drive letter).

To return this collection, create an instance of the FileSystemObject, and then create a reference to the Drives property. After the collection has been returned, you can use a For Each loop to iterate through the collection.

For example, the script in Listing 4.1 returns a collection of all the drives installed on a computer and then echoes the drive letter for each drive in the collection.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 Set colDrives = objFSO.Drives
3 For Each objDrive in colDrives
4     Wscript.Echo "Drive letter: " & objDrive.DriveLetter
5 Next

For a complete list of drive properties available using the FileSystemObject, see Table 4.2 later in this chapter.

If you know in advance which drive you want to bind to (for example, drive C, or the shared folder \accounting eceivables), you can use the GetDrive method to bind directly to the drive. This allows you to retrieve information for a specific drive, without having to return and iterate through an entire collection.

The GetDrive method requires a single parameter: the driver letter of the drive or the UNC path to the shared folder. To specify a drive letter, you can use any of the following formats:

The script shown in Listing 4.2 creates an instance of the FileSystemObject, uses the GetDrive method to bind directly to drive C, and then echoes the amount of available space on the drive.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 Set objDrive = objFSO.GetDrive("C:")
3 Wscript.Echo "Available space: " & objDrive.AvailableSpace

Notice that no For Each loop is required to retrieve the drive properties. This is because the script returns an individual drive object rather than a collection of drive objects. Therefore, there is no collection to iterate through.

The Drives collection is typically used for inventory or monitoring purposes; as a system administrator, you need to know what drives are available on a computer, as well as details such as the drive serial number and the amount of free space on the drive. After you have returned a drives collection or an individual drive object, you can retrieve any of the properties shown in Table 4.2.

To enumerate the drives installed on a computer, create an instance of the FileSystemObject, create a reference to the Drives property, and then use a For Each loop to iterate through the set of drives. For each drive in the collection, you can echo any or all of the individual drive object properties shown in Table 4.2.

The script in Listing 4.3 echoes all the drive properties for every drive installed on a computer.

 1 Set objFSO = CreateObject("Scripting.FileSystemObject")
 2 Set colDrives = objFSO.Drives
 3 For Each objDrive in colDrives
 4     Wscript.Echo "Available space: " & objDrive.AvailableSpace
 5     Wscript.Echo "Drive letter: " & objDrive.DriveLetter
 6     Wscript.Echo "Drive type: " & objDrive.DriveType
 7     Wscript.Echo "File system: " & objDrive.FileSystem
 8     Wscript.Echo "Is ready: " & objDrive.IsReady
 9     Wscript.Echo "Path: " & objDrive.Path
10     Wscript.Echo "Root folder: " & objDrive.RootFolder
11     Wscript.Echo "Serial number: " & objDrive.SerialNumber
12     Wscript.Echo "Share name: " & objDrive.ShareName
13     Wscript.Echo "Total size: " & objDrive.TotalSize
14     Wscript.Echo "Volume name: " & objDrive.VolumeName
15 Next

When the script in Listing 4.3 runs under CScript, information similar to the following appears in the command window:

Available space: 10234975744
Drive letter: C
Drive type: 2
File system: NTFS
Free space: 10234975744
Is ready: True
Path: C:
Root folder: C:
Serial number: 1343555846
Share name:
Total size: 20398661632
Volume name: Hard Drive

The script in Listing 4.3 has a potential flaw in it: If there is no floppy disk in the floppy disk drive that is being checked or no CD in the CD-ROM drive, the script will fail with a “Drive not ready” error. Drives that are not ready create problems for scripts that use the FileSystemObject; although the FileSystemObject can identify the existence of those drives, your script will fail if it attempts to access disk drive properties such as AvailableSpace or FreeSpace.

If a drive is not ready (which typically means that a disk has not been inserted into a drive that uses removable disks), you can retrieve only the following four drive properties:

Any attempt to retrieve the properties of another drive will trigger an error. Fortunately, the IsReady property allows the script to check whether a drive is ready before attempting to retrieve any of the properties that can trigger an error. The IsReady property returns a Boolean value; if the value is True, the drive is ready, and you can retrieve all the properties of the drive. If the value is False, the drive is not ready, and you can return only DriveLetter, DriveType, IsReady, and ShareName.

The script in Listing 4.4 returns a collection of disk drives installed on a computer. For each drive, the script uses the IsReady property to ensure that the drive is ready. If it is, the script echoes the drive letter and the amount of free space. If the drive is not ready, the script echoes only the drive letter, one of the four properties that can be accessed even if a drive is not ready.

 1 Set objFSO = CreateObject("Scripting.FileSystemObject")
 2 Set colDrives = objFSO.Drives
 3 For Each objDrive in colDrives
 4     If objDrive.IsReady = True Then
 5         Wscript.Echo "Drive letter: " & objDrive.DriveLetter
 6         Wscript.Echo "Free space: " & objDrive.FreeSpace
 7     Else
 8         Wscript.Echo "Drive letter: " & objDrive.DriveLetter
 9     End If
10 Next

Note

This problem does not occur with WMI. If there is no disk in drive A or no CD in the CD-ROM drive, the script does not fail. Instead, WMI simply reports the amount of free space as Null.

In the Windows Shell, folders are Component Object Model (COM) objects. This means that, before you can access the properties of an individual folder, you must create an object reference to that folder, a process commonly referred to as binding. You can bind to a folder by creating an instance of the FileSystemObject and then using the GetFolder method to connect to the folder.

When using the GetFolder method, you must:

For example, the script in Listing 4.5 binds to the folder C:FSO.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 Set objFolder = objFSO.GetFolder("C:FSO")

Although wildcard characters are not allowed, you can use the dot (.) to bind to the current folder, dot-dot (..) to bind to the parent folder of the current folder, and the backslash () to bind to the root folder. For example, the following code statement binds to the current folder:

Set objFolder = objFSO.GetFolder(".")

Most folder operations, including copying, moving, and deleting, require the specified folder to exist before the operation can be carried out; after all, a script cannot copy, move, or delete a folder that does not exist. If the script attempts to bind to a nonexistent folder, the script will fail with a “Path not found” error.

To avoid this problem, you can use the FolderExists method to verify that a folder exists before attempting to bind to it. FolderExists takes a single parameter (the path name to the folder) and returns a Boolean value: True if the folder exists, False if the folder does not.

For example, in the script in Listing 4.6, the FolderExists method is used to verify the existence of the folder C:FSO. If FolderExists equals True, the script uses the GetFolder method to bind to the folder. If FolderExists is False, the script echoes the message “Folder does not exist.”

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 If objFSO.FolderExists("C:FSO") Then
3     Set objFolder = objFSO.GetFolder("C:FSO")
4     Wscript.Echo "Folder binding complete."
5 Else
6     Wscript.Echo "Folder does not exist.•
7 End If

It is unlikely that you will ever sit down, implement your file system infrastructure (that is, your folders and subfolders), and then never have to touch that infrastructure again. Instead, a file system tends to be dynamic: because of ever-changing needs, existing folders might be deleted and new folders might be created. For example, if your organization provides users with storage space on file servers, you need to create a new folder each time a new user account is created.

The FileSystemObject gives script writers the ability to programmatically create folders, a capability that can make your scripts even more powerful and more useful. For example, the script in Listing 4.6 checks to see whether a specified folder exists. If the folder exists, the script uses the GetFolder method to bind to the folder. If the folder does not exist, the script echoes a message to that effect.

Although this approach prevents the script from crashing, you might prefer that your script create the folder rather than simply report that the folder does not exist. To do this, create an instance of the FileSystemObject, and then call the CreateFolder method, passing the complete path to the new folder as the sole parameter. For example, the script in Listing 4.7 creates a new folder named C:FSO.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 Set objFolder = objFSO.CreateFolder("C:FSO")

If the folder already exists, a “File exists” error will occur. Because of that, you might want to check for the existence of the folder before trying to create (or, in that case, re-create) it.

Note

The FileSystemObject can only create folders on the local computer. If you need to create folders on a remote computer, you will need to use the WshController object. Alternatively, you can create a folder locally and then use WMI to move that folder to the remote computer. (The folder must be created and then moved because WMI does not have a method for creating folders.)

From time to time, folders need to be deleted. For example, you might have a file server that includes a folder for each individual user. When a user leaves the organization, the folder belonging to that user should be deleted; this helps ensure that the orphaned folder does not use up valuable disk space. Likewise, you might have a script that stores temporary files within a folder. Before the script finishes, you might want to delete that folder and thus remove all the temporary files.

The DeleteFolder method provides a way to delete a folder and all its contents. The DeleteFolder method requires a single parameter: the path of the folder to be deleted. For example, the script in Listing 4.8 deletes the folder C:FSO and everything in it.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 objFSO.DeleteFolder("C:FSO")

The DeleteFolder method deletes all items immediately; it does not ask for confirmation of any kind or send the items to the Recycle Bin.

Using Wildcards to Delete Folders

One of the main advantages of using scripts as a management tool is that scripts can operate on multiple items at the same time. For example, rather than delete a series of folders one by one, you can use scripts to delete a set of folders in a single operation.

The FileSystemObject allows you to use wildcard characters to delete a specific set of folders. For example, suppose you have the folder structure shown in Figure 4.1 and you want to delete all the subfolders beginning with the letter S.

Figure 4.1. Sample Folder Structure

This can be done by using the following command; when run against the sample folder structure, the command deletes the folders Scripts, Subfolder1, and Subfolder2:

objFSO.DeleteFolder("C:FSOS*")

This command deletes all the subfolders beginning with the letters Su, meaning only Subfolder1 and Subfolder2 will be deleted:

objFSO.DeleteFolder("C:FSOSu*")

Wildcard characters can appear only in the final part of the path parameter. For example, this command, which features a wildcard character in the middle of the path parameter, generates a “Path not found” error:

objFSO.DeleteFolder("C:*Subfolder1")

The ability to copy a folder, and every item contained within that folder, is important in system administration. Sometimes you need to copy folders in order to create backups; by having the same folder on Computer A that you have on Computer B, you are less likely to experience data loss should Computer B unexpectedly fail. At other times, you might want to deploy all the files contained in a particular folder to a large number of computers. Using a script to copy this folder to each computer is far more efficient than performing the task manually.

The CopyFolder method allows you to copy a folder and its contents to another location. When used without any wildcard characters, the CopyFolder method functions like the Xcopy /E command: It copies all the files and all the subfolders, including any empty subfolders. The CopyFolder method requires two parameters:

In addition, the CopyFolder method accepts an optional third parameter, Overwrite. When this parameter is set to True, the default setting, the script overwrites any existing folders in the destination folder. For example, if you are copying a folder named Scripts, and the destination already contains a folder by that name, the destination folder will be replaced by the newly copied information. By setting this parameter to False, the script will not overwrite existing information and instead generates a run-time error.

Note

The CopyFolder method stops the moment it encounters an error, even if the script contains an On Error Resume Next statement. For example, suppose the script has 100 subfolders to copy, and CopyFolder successfully copies 3 of those subfolders before encountering an error. At that point, the CopyFolder method ends and the script fails; the script will not even attempt to copy the remaining 97 subfolders.

The script in Listing 4.9 uses the CopyFolder method to copy the contents of C:Scripts to C:FSO, overwriting any existing files in the destination folder. Note that this will not result in a folder named C:FSOScripts; instead, the folder C:FSO will simply contain the same files and folders as C:Scripts. To create a folder named C:FSOScripts, you would need to specify C:FSOScripts as the destination folder.

1 Const OverWriteFiles = True
2 Set objFSO = CreateObject("Scripting.FileSystemObject")
3 objFSO.CopyFolder "C:Scripts" , "C:FSO" , OverWriteFiles

Note

Because CopyFolder is a single operation, there is no way to track its progress; you simply have to wait until the operation has finished. If you want to monitor the progress of the copy command, you should use the Shell Application object instead. This object is discussed in “Files and Folders” in this book.

objFSO.CopyFolder "C:ScriptsLog*" , "C:Archive", True

When you copy a folder from one location to another, you end up with duplicate copies of the information. Sometimes that is exactly what you want. On other occasions, however, you do not want two copies of the information; instead, you want to move the sole copy from Computer A to Computer B, or from hard disk C to hard disk D.

Moves such as this are often done to free disk space on a particular drive; for example, you might periodically move seldom-accessed folders to an archive drive. Alternatively, you might have a monitoring script that logs information to the local computer. When monitoring is complete, you might want that information uploaded to a central monitoring station and then deleted from the local computer. That way, the local computer will be prepared for the next round of monitoring.

The MoveFolder method accepts two parameters:

If the destination folder does not exist, the source folder will be moved. If the destination folder already exists, however, the move operation will fail. You cannot use MoveFolder to overwrite an existing folder.

The script in Listing 4.10 moves the local folder, C:Scripts, to the shared folder \helpdeskmanagement.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 objFSO.MoveFolder "C:Scripts" , "\helpdeskmanagement"

Note that the MoveFolder method cannot perform any sort of rollback should the script fail. For example, suppose a network connection fails before a script has been able to move all the files from one computer to another. In a case such as that, you will end up with some files on Computer A, some files on Computer B, and possibly even a file or two lost in transit. However, there is no way for MoveFolder to roll back the failed transactions and restore the two computers to their previous states.

Because of that, you might want to use two methods, CopyFolder and DeleteFolder, when transferring folders and their contents across the network. You can use CopyFolder to copy the folder from Computer A to Computer B. If the copy operation succeeds, you can then use DeleteFolder to delete the folder on Computer A. If the operation fails, you can cancel the delete command and rest assured that the folder and all its contents are still safely stored on Computer A.

The FileSystemObject does not include a method, such as RenameFolder, that provides an obvious way to rename a folder. However, you can rename a folder by using the MoveFolder method and maintaining the same relative location. For example, suppose you have a folder with the following path:

C:ScriptsPerformanceMonitoringServersDomain ControllersCurrent Logs

If you rename the folder by using the Rename command in Windows Explorer, the path remains identical except for the endpoint, the folder itself:

C:ScriptsPerformanceMonitoringServersDomain ControllersArchived Logs

The MoveFolder method enables you to achieve the same end result by moving the folder from C:ScriptsPerformanceMonitoringServersDomain ControllersCurrent Logs to C:ScriptsPerformanceMonitoringServersDomain ControllersArchived Logs. The net result is exactly the same as that of using Windows Explorer to rename the folder.

For example, the script in Listing 4.11 uses MoveFolder to rename the folder C:FSOSamples to C:FSOScripts. Before the script runs, Samples is the only subfolder in C:FSO. After the script runs, Scripts is the only subfolder in C:FSO. Furthermore, Scripts contains all the files and subfolders previously contained in Samples.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 objFSO.MoveFolder "C:FSOSamples" , "C:FSOScripts"

To retrieve the properties of a folder, a script must:

When working with folder properties, note that the Files property and the Subfolders property both return collections rather than a single item. In addition, the Attributes property is returned as a bitmap value. A more detailed explanation of how to work with each of these properties is provided in subsequent sections of this chapter.

The script in Listing 4.12 uses the GetFolder method to bind to the folder C:FSO and then echoes a number of properties for that folder.

 1 Set objFSO = CreateObject("Scripting.FileSystemObject")
 2 Set objFolder = objFSO.GetFolder("C:FSO")
 3 Wscript.Echo "Date created: " & objFolder.DateCreated
 4 Wscript.Echo "Date last accessed: " & objFolder.DateLastAccessed
 5 Wscript.Echo "Date last modified: " & objFolder.DateLastModified
 6 Wscript.Echo "Drive: " & objFolder.Drive
 7 Wscript.Echo "Is root folder: " & objFolder.IsRootFolder
 8 Wscript.Echo "Name: " & objFolder.Name
 9 Wscript.Echo "Parent folder: " & objFolder.ParentFolder
10 Wscript.Echo "Path: " & objFolder.Path
11 Wscript.Echo "Short name: " & objFolder.ShortName
12 Wscript.Echo "Short path: " & objFolder.ShortPath
13 Wscript.Echo "Size: " & objFolder.Size
14 Wscript.Echo "Type: " & objFolder.Type

When this script runs under CScript, output similar to the following appears in the command window:

Date created: 2/7/2002 10:27:50 AM
Date last accessed: 2/13/2002 8:57:18 AM
Date last modified: 2/13/2002 8:57:18 AM
Drive: C:
Is root folder: False
Name: FSO
Parent folder: C:
Path: C:FSO
Short name: FSO
Short path: C:FSO
Size: 0
Type: File Folder

As explained in “Working with Bitmaps,” individual folder attributes can be likened to switches. If the switch for Hidden is on, the folder is a hidden folder. If the switch for Hidden is off, the folder is not a hidden folder.

This analogy can be carried further by noting that light switches are typically under your control: you can choose to turn them on, or you can choose to turn them off. The same thing is true of folder attributes: as with other switches, you can turn these attribute switches on, or you can turn them off.

You can use scripts to toggle these switches on or off (for example, to hide or unhide a folder). The easiest way to change folder attributes is to use the following procedure:

For example, the script in Listing 4.14 uses the AND operator to check whether the switch with the value 2 (hidden folder) has been set on the folder C:FSO. If it has, the script then uses the XOR operator to turn the switch off and unhide the folder.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 Set objFolder = objFSO.GetFolder("C:FSO")
3 If objFolder.Attributes AND 2 Then
4     objFolder.Attributes = objFolder.Attributes XOR 2
5 End If

Except for a few rare cases, folders exist solely to act as storage areas for files. Sometimes these folders are required by the operating system; for example, the operating system expects to find certain files in certain folders. In other cases, folders are created as a way to help system administrators manage their computers, or as a way to help users manage their documents. System administrators might place their scripts in a folder named Scripts and their troubleshooting tools in a folder named Diagnostic Tools; users might place their budget spreadsheets in a folder named Budgets and their payroll information in a folder named Timecards.

Of course, the fact that a folder exists is often of limited use; you must also know what files are stored within that folder. Administrators need to know whether a particular script is stored in C:Scripts; users need to know whether a particular spreadsheet is stored in C:Budgets.

The Folder object includes a Files property that returns a collection of all the files stored in a folder. To retrieve this collection, a script must:

For example, the script in Listing 4.15 retrieves a collection of files found in the folder C:FSO and then echoes the name and size (in bytes) of each file.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 Set objFolder = objFSO.GetFolder("C:FSO")
3 Set colFiles = objFolder.Files
4 For Each objFile in colFiles
5     Wscript.Echo objFile.Name, objFile.Size
6 Next

As with most collections, you have no control over the order in which information is returned; that is, you cannot specify that files be sorted by name, by size, or by any other criteria. If you want to sort the file collection in a particular way, you need to copy the collection to an array, a Dictionary, or a disconnected recordset and then sort the items. For more information on arrays, see “VBScript Primer” in this book. For information on disconnected recordsets, see “Creating Enterprise Scripts” in this book.

In addition to knowing which files are stored in a folder, you need to know which subfolders are stored in a folder; this allows you to develop a complete picture of the folder infrastructure. The Folder object includes a Subfolders property that returns a collection consisting of the top-level subfolders for a folder.

Top-level subfolders are those folders contained directly within a folder; subfolders contained within those subfolders are not part of the collection. For example, in the sample folder structure shown in Figure 4.5, only Subfolder 1 and Subfolder 2 are top-level subfolders of the folder Scripts. As a result, only Subfolder 1 and Subfolder 2 are returned as part of the Subfolders property.

Figure 4.5. Sample Folder Structure

To obtain a subfolder collection, a script must:

After you have obtained the object reference to the collection, you can then use a For Each loop to enumerate each of the subfolders in that collection. The script in Listing 4.16 binds to the folder C:FSO and then echoes the name and size of each subfolder. In addition to the folder name, you can echo any of the folder properties shown in Table 4.3.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 Set objFolder = objFSO.GetFolder("C:FSO")
3 Set colSubfolders = objFolder.Subfolders
4 For Each objSubfolder in colSubfolders
5     Wscript.Echo objSubfolder.Name, objSubfolder.Size
6 Next

Enumerating Subfolders Within Subfolders

Depending on how your file system has been designed, simply knowing the top-level subfolders of a folder might provide sufficient information to map the folder infrastructure. In most file systems, however, folders are nested within folders that are, in turn, nested within other folders. The Subfolders collection can tell you that the folder C:Accounting contains two subfolders: 2001 and 2002. However, it cannot tell which subfolders, if any, are contained within C:Accounting2001 and C:Accounting2002.

Fortunately, you can use recursion to enumerate all the subfolders within a set of subfolders. For example, the Subfolders collection, as shown in Listing 4.16, returns only the two top-level subfolders (Subfolder 1 and Subfolder 2) in the folder structure shown in Figure 4.6.

Figure 4.6. Sample Folder Structure

To return the complete set of subfolders (for example, Subfolder 1A and Subfolder 1B), you need to use a recursive function, a function that can call itself. For more information about recursion, see “VBScript Primer” in this book.

An example of a script that can enumerate all the subfolders of a folder (as well as any subfolders within those subfolders) is shown in Listing 4.17. This script:

1. Creates an instance of the FileSystemObject.

2. Uses the GetFolder method to bind to the folder C:Scripts.

   GetFolder is used to return a folder object for C:Scripts. In turn, the path C:Scripts is passed as a parameter to the recursive subroutine ShowSubfolders. This subroutine will enumerate all the subfolders of C:Scripts, as well as any subfolders within those subfolders.

3. Retrieves a collection consisting of all the subfolders of the folder C:Scripts. This collection has two items: Subfolder1 and Subfolder 2.

4. Echoes the folder path of the first item in the collection, Subfolder 1. The subroutine then uses the name of that folder as a parameter passed to itself. In other words, the script now runs the subroutine ShowSubFolders using Subfolder 1 as the parameter.

5. Retrieves a collection consisting of all the subfolders of Subfolder 1. This collection has two items: Subfolder1A and Subfolder 1B.

6. Echoes the folder path of the first item in the collection, Subfolder 1A. The subroutine then uses the name of that folder as a parameter passed to itself. In other words, it now runs the function ShowSubFolders using Subfolder 1A as the parameter.

7. Passes control to the next item in the collection, Subfolder 1B. This occurs because Subfolder 1A has no subfolders. The subroutine calls itself using Subfolder 1B as the parameter.

8. Finishes recursing through Subfolder 1. This occurs because Subfolder 1B has no subfolders. The script then returns to the second item (Subfolder 2) in the original collection, and repeats the entire process.

Example 4.17. Recursively Enumerating Subfolders

1 Set FSO = CreateObject("Scripting.FileSystemObject")
2 ShowSubfolders FSO.GetFolder("C:Scripts")
3 Sub ShowSubFolders(Folder)
4     For Each Subfolder in Folder.SubFolders
5         Wscript.Echo Subfolder.Path
6         ShowSubFolders Subfolder
7     Next
8 End Sub

When this script runs under CScript, the following output appears in the command window:

C:scriptsSubfolder 1
C:scriptsSubfolder 1Subfolder 1A
C:scriptsSubfolder 1Subfolder 1B
C:scriptsSubfolder 2
C:scriptsSubfolder 2Subfolder 2A
C:scriptsSubfolder 2Subfolder 2ASubfolder 2A-1
C:scriptsSubfolder 2Subfolder 2B
C:scriptsSubfolder 2Subfolder 2C

To return a complete list of all the folders on a hard disk, begin the search in the root folder of the drive (for example, C:).

The FileSystemObject provides a number of methods, such as the CopyFile and DeleteFile methods, that allow a script to act on a file without creating an instance of the File object. Other tasks, however, require the File object. For example, to retrieve a list of file properties, a script must first bind to that file and then retrieve the properties.

The GetFile method allows you to bind to an individual file. To do this, you create an instance of the FileSystemObject and then create an instance of the File object. When using the GetFile method in a script, you must:

For example, the script in Listing 4.18 binds to the file C:FSOScriptLog.txt.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 objFSO.GetFile("C:FSOScriptLog.txt")

In general, it is a good idea to pass the absolute path as the GetFile parameter; this ensures that the script will always be able to locate the file in question. However, it is possible to use relative paths. For example, the following code sample will work provided that ScriptLog.txt is in the same folder as the script attempting to bind to it:

objFSO.GetFile("ScriptLog.txt")

Likewise, the next code sample will work if ScriptLog.txt is in the parent folder of the script attempting to bind to it:

objFSO.GetFile(".ScriptLog.txt")

Please note, however, that the FileSystemObject will not use the path environment variable to search for files. For example, you can start Calculator from the command prompt by typing calc.exe, regardless of the current drive or directory, because the operating system searches all folders in the path to locate the file. This does not happen with the GetFile method. The following code sample will fail unless the script is running in the C:WindowsSystem32 folder, the same folder where calc.exe is located:

objFSO.GetFile("calc.exe")

Sometimes it is important simply to know whether a file exists. This might be done as part of a software inventory; for example, you might want to check all your mail servers and see whether a particular script file is present.

Knowing whether a file exists is also important when using scripts to carry out file system management tasks; as you might expect, attempting to copy, move, delete, or otherwise manipulate a file that does not exist will generate a run-time error. To avoid this kind of error, you can use the FileExists method to verify the existence of the file. The FileExists method requires a single parameter (the path to the file) and returns a Boolean value: True if the file exists; False if it does not.

The script in Listing 4.19 uses the FileExists method to verify the existence of the file C:FSOScriptLog.txt. If the file exists, the script uses the GetFile method to bind to the file. If the file does not exist, the script echoes the message, “File does not exist.”

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 If objFSO.FileExists("C:FSOScriptLog.txt") Then
3     Set objFile = objFSO.GetFile("C:FSOScriptLog.txt")
4 Else
5     Wscript.Echo "File does not exist.•
6 End If

You cannot use wildcard characters to verify whether a particular set of files (such as .txt files) exists in a folder, nor can you use wildcards to verify whether any files at all exist in a folder. For example, the following code sample does not result in an error but always returns the value False, regardless of how many files are in the folder:

WScript.Echo objFSO.FileExists("C:FSO*.*")

If you need to verify the existence of a file based on some criteria other than the path, you have two options:

The ability to delete files by using the FileSystemObject enables you to create scripts that can automatically perform tasks such as disk cleanup operations. For example, you might have a script that periodically searches for and deletes all temporary files (files with the .tmp file name extension). Alternatively, the script might delete files based on some other criteria, such as those that have not been accessed in the past six months, or those with a particular file name extension (such as .bmp or .mp3).

You can delete a file by creating an instance of the FileSystemObject and then calling the DeleteFile method, passing the path to the file as the parameter. For example, the script in Listing 4.20 deletes the file C:FSOScriptLog.txt.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 objFSO.DeleteFile("C:FSOScriptLog.txt")

By default, the DeleteFile method will not delete a read-only file; if fact, a run-time error will occur if you attempt to delete such a file. To avoid errors, and to delete read-only files, add the optional Force parameter. When the Force parameter is set to True, the DeleteFile method can delete any file. For example, this line of code deletes the file ScriptLog.txt, even if that file is marked as read-only:

objFSO.DeleteFile("C:FSOScriptLog.txt", True)

Deleting a Set of Files

There might be occasions when you require a script to delete a single, specified file. More likely, though, you will want to use scripts to delete multiple files. For example, at the end of the week, you might want to delete a set of log files that has been archived or delete all the temporary files that have been created but not removed.

Wildcard characters allow you to delete a set of files within a single folder. However, you cannot use the DeleteFile method to directly delete files from multiple folders. Instead, your script needs to iterate through the folders and use the DeleteFile method to individually delete the files in each folder. To delete files from multiple folders in a single operation (for example, to delete all the .TMP files stored anywhere on a computer), you should use WMI instead of the FileSystemObject.

To delete a set of files, call the DeleteFile method, supplying the path of the folder and the wildcard string required to delete files based on name or file name extension. For example, this line of code deletes all the .doc files in the C:FSO folder:

objFSO.DeleteFile("C:FSO*.doc")

This line of code deletes all the files with the letters log somewhere in the file name:

objFSO.DeleteFile("C:FSO*log.* ")

As noted previously, the DeleteFile method does not delete any documents marked as read-only. If a script attempts to delete a read-only document, a run-time error will occur, and the DeleteFile method will stop, even if the script uses the On Error Resume Next statement. For example, suppose you are trying to delete 1,000 .txt files, and one of those files is marked as read-only. As soon as the script attempts to delete that file, an error will occur, and the DeleteFile method will stop. The script will make no attempt to delete any other files, even though none of them are read-only.

Because of that, you can use an optional second parameter, Force, that can be set to True. When the Force parameter is set to True, the DeleteFile method can delete read-only documents. When the Force parameter is set to False (the default value), the DeleteFile method cannot delete read-only documents.

The script in Listing 4.21 deletes all the .txt files in the folder C:FSO. To ensure that all files, including read-only files, are deleted, the Force parameter is set to True using the constant DeleteReadOnly.

Example 4.21. Deleting a Set of Files

1 Const DeleteReadOnly = True
2 Set objFSO = CreateObject("Scripting.FileSystemObject")
3 objFSO.DeleteFile("C:FSO*.txt"), DeleteReadOnly

Tip

What if you want to delete all files except those marked as read-only? In that case, you can retrieve the complete set of files by using the Folder object Files property. You can then cycle through the collection, check to see whether each individual file is read-only, and, if it is not, delete the file.

Copying files, either from one folder to another on a single computer or from one computer to another, is a common administrative task. For example, you might want to copy a new monitoring script to all your servers or replace an outdated DLL with a newer version. The CopyFile method provides a way to perform these tasks programmatically.

The CopyFile method has two required parameters and one optional parameter:

The script in Listing 4.22 copies C:FSOScriptLog.txt to the folder D:Archive. This operation results in the existence of two files:

To ensure that the procedure will be carried out even if D:ArchiveScriptLog.txt exists, the Overwrite parameter is set to True by using the constant OverWriteExisting.

1 Const OverwriteExisting = True
2 Set objFSO = CreateObject("Scripting.FileSystemObject")
3 objFSO.CopyFile "C:FSOScriptLog.txt" , "D:Archive", OverwriteExisting

When specifying the destination folder, it is important to include the trailing backslash (for example, D:Archive). If the backslash is there, CopyFile will copy the file into the Archive folder. If the backslash is not there, CopyFile will try to create a new file named D:Archive. If the folder D:Archive already exists, a “Permission denied error” will be generated, and the copy procedure will fail.

The CopyFile method will also fail if you attempt to overwrite an existing read-only file, even if you have set the OverWrite parameter to True. To copy over a read-only file, you must first delete the file and then call the CopyFile method.

1 Const OverwriteExisting = True
2 Set objFSO = CreateObject("Scripting.FileSystemObject")
3 objFSO.CopyFile "C:FSO*.txt" , "D:Archive" , OverwriteExisting

objFSO.CopyFile "C:FSO*.*" , "D:Archive"

Instead of copying a file, you might want to move it. For example, if a disk is running low on space, you might want to move a file to a new location. If a computer is changing roles, you might want to move certain diagnostic tools to its replacement. In either case, you do not want two or more copies of the file; you want one copy of the file, stored in a new place.

The MoveFile method enables you to move a file from one location to another. The MoveFile method works exactly like the CopyFile method: You create an instance of the FileSystemObject, call the MoveFile method, and pass two parameters:

For example, the script in Listing 4.24 moves C:FSOScriptLog.log to the Archive folder on drive D.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 objFSO.MoveFile "C:FSOScriptLog.log" , "D:Archive"

C:FSOData*.*

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 objFSO.MoveFile "C:FSO*.log" , "D:Archive"

The FileSystemObject does not include a direct method for renaming a file. However, in much the same way that a folder can be renamed using the MoveFolder method, files can be renamed using the MoveFile method. To rename a file, call the MoveFile method but leave the file in its current folder.

For example, the script in Listing 4.26 renames ScriptLog.txt to BackupLog.txt. Technically, the script actually moves C:FSOScriptLog.txt to a new path: C:FSOBackupLog.txt. The net result, however, is that the file named ScriptLog.txt is now named BackupLog.txt.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 objFSO.MoveFile "C:FSOScriptLog.txt" , "C:FSOBackupLog.txt"

Like folders, files also have attributes that can be retrieved and configured using the FileSystemObject. Also like folders, file attributes are returned as a bitmap value. (For more information on bitmap values and how to use them, see “Managing Folder Attributes” earlier in this chapter.) File attributes can include any or all of the values shown in Table 4.6.

To retrieve the attributes of a file, use the GetFile method to bind to the file. After you have created an object reference to the file, you can use the logical AND operator to determine the file attributes. If the file does not have any attributes configured, the Attributes value will be 0.

For example, the script in Listing 4.28 binds to the file C:FSOScriptLog.txt and then checks for the presence of each attribute that can be retrieved using the FileSystemObject.

 1 Set objFSO = CreateObject("Scripting.FileSystemObject")
 2 Set objFile = objFSO.GetFile("C:FSOScriptLog.txt")
 3 If objFile.Attributes AND 0 Then
 4     Wscript.Echo "No attributes set."
 5 End If
 6 If objFile.Attributes AND 1 Then
 7     Wscript.Echo "Read-only."
 8 End If
 9 If objFile.Attributes AND 2 Then
10     Wscript.Echo "Hidden file."
11 End If
12 If objFile.Attributes AND 4 Then
13     Wscript.Echo "System file."
14 End If
15 If objFile.Attributes AND 32 Then
16     Wscript.Echo "Archive bit set."
17 End If
18 If objFile.Attributes AND 64 Then
19     Wscript.Echo "Link or shortcut."
20 End If
21 If objFile.Attributes AND 2048 Then
22     Wscript.Echo "Compressed file."
23 End If

In addition to enumerating file attributes, the FileSystemObject provides a way to configure the following attributes:

To configure a file attribute, the script should use the following procedure:

The script in Listing 4.29 uses the AND operator to check whether the switch with the value 1 (read-only) has been set on the file C:FSOTestScript.vbs. If the file is not read-only, the script uses the XOR operator to turn the switch on and mark the file as read-only.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 Set objFile = objFSO.GetFile("C:FSOTestScript.vbs")
3 If objFile.Attributes AND 1 Then
4     objFile.Attributes = objFile.Attributes XOR 1
5 End If

You can also simultaneously remove the ReadOnly, Hidden, System, and Archive attributes by using the following code statement:

objFile.Attributes = objFile.Attributes AND 0

A path is a hierarchical series of names that allow you to pinpoint the exact location of a file or folder. In that respect, paths are similar to street addresses: they provide information that tells you precisely where to locate an object. A street address such as One Main Street, Redmond, WA, tells you precisely where to find a particular residence. Likewise, the path C:FSOScriptsScriptLog.txt tells you precisely where to locate a particular file. Just as only one building can be located at One Main Street, Redmond, WA, only one file can be located at C:FSOScriptsScriptLog.txt.

Complete paths such as C:FSOScriptsScriptLog.txt are very important because they provide the only way to uniquely identify a file or folder location. Because of that, there will be times when your script will need the complete path.

At other times, however, you might want only a portion of the path. For example, you might want to extract only the file name or only the file name extension. To allow you to parse paths and extract individual path components, the FileSystemObject provides the methods listed in Table 4.7.

The script in Listing 4.30 parses the path for the file ScriptLog.txt. This script works only if ScriptLog.txt is in the same folder as the script doing the parsing. If the two files are stored in different folders, you must pass the complete path to the GetFile method (for example, C:FSOScriptsScriptLog.txt).

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 Set objFile = objFSO.GetFile("ScriptLog.txt")
3 Wscript.Echo "Absolute path: " & objFSO.GetAbsolutePathName(objFile)
4 Wscript.Echo •Parent folder: • & objFSO.GetParentFolderName(objFile)
5 Wscript.Echo "File name: " & objFSO.GetFileName(objFile)
6 Wscript.Echo "Base name: " & objFSO.GetBaseName(objFile)
7 Wscript.Echo "Extension name: " & objFSO.GetExtensionName(objFile)

When this script is run under CScript, output similar to the following appears in the command window:

Absolute path: C:FSOScriptsScriptLog.txt
Parent folder: C:FSOScripts
File name: ScriptLog.txt
Base name: ScriptLog
Extension name: txt

File versions that are incompatible or out-of-date can create considerable problems for system administrators. For example, a script that runs fine on Computer A, where version 2.0 of a particular DLL has been installed, might fail on Computer B, which has version 1.0 of that DLL installed.

These problems can be difficult to troubleshoot, because you are likely to get back an error saying that the object does not support a particular property or method. This is because the version of the object installed on Computer B does not support the new property or method. If you try to debug the script on Computer A, you will have difficulty finding the problem because the version of the object installed on Computer A does support the property or method in question.

The GetFileVersion method allows you to retrieve version information from a file. To use this method, a script must:

For example, the script in Listing 4.31 retrieves the file version for Scrrun.dll.

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 Wscript.Echo objFSO.GetFileVersion("c:windowssystem32scrrun.dll")

When this script runs on a Windows 2000-based computer with WSH 5.6 installed, the message box shown in Figure 4.7 appears.

Figure 4.7. Version Number for Scrrun.dll

Version numbers are typically displayed in four parts, such as 5.6.0.6626, rather than a single number (such as version 1 or version 5). Version number 5.6.0.6626 contains the following parts:

Not all files types support versioning. Executable files and DLLs typically support versioning; plain-text files, including scripts, typically do not.

Reading data from a text file is a standard procedure used in many enterprise scripts. You might use this capability to:

The FileSystemObject can be used to read the contents of a text file. When using the FileSystemObject, keep the following limitations in mind:

The file-reading methods available through the FileSystemObject are listed in Table 4.8. The examples shown in the table are based on a text file of services and service properties that looks similar to this:

Alerter,Share Process,Running,Auto,LocalSystem,
AppMgmt,Share Process,Running,Manual,LocalSystem,
Ati HotKey Poller,Own Process,Stopped,Auto,LocalSystem,

strText = objTextFile.Readline
objTextFile.SkipLine
strText = objTextFile.Readline

Verifying the Size of a File

Windows will sometimes create text files that are empty — that is, files that contain no characters and have a file size of 0 bytes. This often occurs with log files, which remain empty until a problem is recorded there. For example, if problems occur with a user logon (such as a user attempting to log on with an incorrect password or user account), those problems will be recorded in the Netlogon.log file. Until such a problem occurs, however, the Netlogon.log file remains empty.

Empty files represent a problem for script writers, because a VBScript run-time error will occur if you attempt to read such a file. If you try to read an empty file, an error message similar to the one shown in Figure 4.8 appears.

Figure 4.8. Empty File Error Message

If there is a chance that a file might be empty, you can avoid errors by checking the file size before attempting to read the file. To do this, the script must:

1. Create an instance of the FileSystemObject.

2. Use the GetFile method to bind to the file.

3. Use the Size property to ensure that the file is not empty before attempting open it.

The script in Listing 4.37 binds to the file C:WindowsNetlogon.log. The script checks the size of the file; if the size is greater than 0, the script opens and reads the file. If the file size is 0, the script echoes the message “The file is empty.”

Example 4.37. Verifying the Size of a File

 1 Set objFSO = CreateObject("Scripting.FileSystemObject")
 2 Set objFile = objFSO.GetFile("C:WindowsNetlogon.log")
 3 If objFile.Size > 0 Then
 4     Set objReadFile = objFSO.OpenTextFile("C:WindowsNetlogon.log", 1)
 5     strContents = objReadFile.ReadAll
 6     Wscript.Echo strContents
 7     objReadFile.Close
 8 Else
 9     Wscript.Echo "The file is empty."
10 End If

Reading an Entire Text File

The ReadAll method provides the easiest way to read a text file: You simply call the method, and the entire text file is read and stored in a variable. Having the contents of the text file stored in a single variable can be useful in a number of situations. For example, if you want to search the file for a particular item (such as an error code), it is easier to search a single string than to search the file line by line.

Likewise, if you want to concatenate (combine) text files, the ReadAll method provides the quickest and easiest method. For example, suppose you have a set of daily log files that you want to combine into a single weekly log file. To do that, a script can:

1. Open the text file for Monday and use ReadAll to store the entire contents in a variable.

2. Open the weekly log file for appending, and write the contents of the variable to the file. This is possible because any formatting (such as line breaks or tabs) that is read in from the Monday file is preserved in the variable.

3. Repeat steps 1 and 2 until the entire set of daily files has been copied into the weekly log.

Note

Although it is easier to search a single string, it is not necessarily faster. The ReadAll method took less than a second to search a 388-KB test file of approximately 6,000 lines. Reading and searching the file on a line-by-line basis also took less than a second.

To use the ReadAll method, open a text file for reading and then call ReadAll. (No parameters are needed.) For example, the script in Listing 4.38 opens the file C:FSOScriptLog, reads in the contents of the file, and stores that data in the variable strContents. The script then echoes the value of strContents, which happens to be the contents of the text file as well.

Example 4.38. Reading a Text File Using the ReadAll Method

1 Const ForReading = 1
2 Set objFSO = CreateObject("Scripting.FileSystemObject")
3 Set objFile = objFSO.OpenTextFile("C:FSOScriptLog.txt", ForReading)
4 strContents = objFile.ReadAll
5 Wscript.Echo strContents
6 objFile.Close

atl-dc-01
atl-dc-02
atl-dc-03
atl-dc-04

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 Set objFile = objFSO.OpenTextFile("C:FSOServerList.txt", 1)
3 Do Until objFile.AtEndOfStream
4     strLine = objFile.ReadLine
5     Wscript.Echo strLine
6 Loop
7 objFile.Close

 1 Dim arrFileLines()
 2 i = 0
 3 Set objFSO = CreateObject("Scripting.FileSystemObject")
 4 Set objFile = objFSO.OpenTextFile("C:FSOScriptLog.txt", 1)
 5 Do Until objFile.AtEndOfStream
 6     Redim Preserve arrFileLines(i)
 7     arrFileLines(i) = objFile.ReadLine
 8     i = i + 1
 9 Loop
10 objFile.Close
11 For l = Ubound(arrFileLines) to LBound(arrFileLines) Step -1
12     Wscript.Echo arrFileLines(l)
13 Next

6/19/2002    Success
6/20/2002    Failure
6/21/2002    Failure
6/22/2002    Failure
6/23/2002    Success

6/23/2002    Success
6/22/2002    Failure
6/21/2002    Failure
6/20/2002    Failure
6/19/2002    Success

Server              Value           Status
atl-dc-01           19345           OK
atl-printserver-02  00042           OK
atl-win2kpro-05     00000           Failed

strCharacters = objFile.Read(7)

1 Set objFSO = CreateObject("Scripting.FileSystemObject")
2 Set objFile = objFSO.OpenTextFile("C:FSOScriptLog.txt", 1)
3 Do Until objFile.AtEndOfStream
4     objFile.Skip(5)
5     strCharacters = objFile.Read(1)
6     Wscript.Echo strCharacters
7     objFile.SkipLine
8 Loop

XXXXX1XXXXXXXXXXXXXX
XXXXX2XXXXXXXXXXXXXXXXXXX
XXXXX3XXXXXXXXXXXX
XXXXX4XXXXXXXXXXXXXXXXXXXXXXXXX

1
2
3
4

Writing data to a text file is another powerful aid in writing system administration scripts. Text files provide a way for you to permanently save data retrieved by a script; this data can be saved either instead of or in addition to being displayed on the screen. Text files also provide a way for you to keep a log of the actions carried out by a script. This can be especially useful when creating and debugging scripts. By having the script record its actions in a text file, you can later review the log to determine which procedures the script actually carried out and which ones it did not.

The FileSystemObject gives you the ability to write data to a text file. To write data using the FSO, a script must do the following:

The three methods for writing to a text file are shown in Table 4.9.

objFile.Write ("This is line 1.")
objFile.Write ("This is line 2.")

objFile.WriteLine ("This is line 1.")
objFile.WriteLine ("This is line 2.")

This is line 1.
This is line 2.

objFile.Writeline ("This is line 1.")
objFile.WriteBlankLines(1)
objFile.Writeline ("This is line 2.")

This is line 1.

This is line 2.

In addition to the methods shown in Table 4.9, the VBScript constant VbTab can be useful in writing data to text files. VbTab inserts a tab between characters. To create a tab-separated data file, use code similar to the following:

objTextFile.WriteLine(objService.DisplayName & vbTab & objService.State)

One weakness with the FileSystemObject is that it cannot be used to directly modify specific lines in a text file; for example, you cannot write code that says, in effect, “Skip down to the fifth line in this file, make a change, and then save the new file.” To modify line 5 in a 10-line text file, a script must instead:

1 Const ForWriting = 2
2 Set objFSO = CreateObject("Scripting.FileSystemObject")
3 Set objFile = objFSO.OpenTextFile("C:FSOScriptLog.txt", ForWriting)
4 objFile.Write Now
5 objFile.Close

6/25/2002 8:49:47 AM
6/25/2002 8:49:48 AM
6/25/2002 8:50:33 AM
6/25/2002 8:50:35 AM

1 Const ForAppending = 8
2 Set objFSO = CreateObject("Scripting.FileSystemObject")
3 Set objFile = objFSO.OpenTextFile("C:FSOScriptLog.txt", ForAppending)
4 objFile.WriteLine Now
5 objFile.Close

6/25/2002 8:49:47 AM6/25/2002 8:49:48 AM6/25/2002 8:50:33 AM6/25/2002 8:50:35 AM

The Dictionary object has only one configurable property, Compare Mode, which plays an important role in determining which keys can be added and which ones cannot. (It is also important in verifying which keys are present in a Dictionary and which ones are not.) By default, a Dictionary is created in binary mode, which means each key in the Dictionary is based on its ASCII value. This is important because the ASCII value of an uppercase letter is different from the ASCII value of that same lowercase letter. In binary mode, both of these services can be added to the Dictionary as individual keys:

In other words, with binary mode, you can inadvertently add multiple entries for the same item. Binary mode dictionaries can also be difficult to search. For example, if you try to verify the existence of the key Alerter, you will be told that the key does not exist; that is because no key exists with that same pattern of uppercase and lowercase letters. As a result, you might end up adding yet another key for this same item.

When a Dictionary is configured in text mode, uppercase and lowercase letters are treated identically. This helps eliminate duplicate keys; you cannot add a key for ALERTER if a key for alerter already exists. It is also much easier to verify the existence of a key; searching for either alerter or ALERTer will find the key named Alerter.

To configure the Dictionary mode, create an instance of the Dictionary object and then set the CompareMode property to one of the following values:

For example, the script in Listing 4.44 sets the Dictionary to text mode.

1 Const TextMode = 1
2 Set objDictionary = CreateObject("Scripting.Dictionary")
3 objDictionary.CompareMode = TextMode

You cannot change the CompareMode property of a Dictionary if that Dictionary contains any elements. This is because the binary mode allows you to differentiate between keys based solely on uppercase and lowercase letters. For example, each of these keys can be in the same Dictionary as long as the Dictionary is in binary mode:

In text mode, however, these three keys are considered identical. If you had these elements in a binary Dictionary and were able to reconfigure that Dictionary in text mode, the Dictionary would suddenly contain three duplicate keys, and it would fail. If you must reconfigure the Dictionary mode, you first need to remove all items from the Dictionary.

After you have created an instance of the Dictionary object, you can use the Add method to add key-item pairs to the dictionary. The Add method requires two parameters, which must be supplied in the following order and separated by a comma:

For example, the script in Listing 4.45 creates a Dictionary object and then adds the key-item pairs shown in Table 4.10.

1 Set objDictionary = CreateObject("Scripting.Dictionary")
2 objDictionary.Add "Printer 1", "Printing"
3 objDictionary.Add "Printer 2", "Offline"
4 objDictionary.Add "Printer 3", "Printing"

Dictionary keys must be unique. For example, the following two script statements will generate a run-time error because, after the first line is interpreted, the key “Printer 1” will already be in the Dictionary:

objDictionary.Add "Printer 1", "Printing"
objDictionary.Add "Printer 1", "Offline"

Inadvertently Adding a Key to a Dictionary

One potential problem in using the Dictionary object is that any attempt to reference an element that is not contained in the Dictionary does not result in an error. Instead, the nonexistent element is added to the Dictionary. Consider the following script sample, which creates a Dictionary, adds three key-item pairs to the Dictionary, and then attempts to echo the value of a nonexistent item, Printer 4:

Set objDictionary = CreateObject("Scripting.Dictionary")
objDictionary.Add "Printer 1", "Printing"
objDictionary.Add "Printer 2", "Offline"
objDictionary.Add "Printer 3", "Printing"
Wscript.Echo objDictionary.Item("Printer 4")

When the script tries to echo the value of the nonexistent item, no run-time error occurs. Instead, the new key, Printer 4, is added to the Dictionary, along with the item value Null. As a result, the message box shown in Figure 4.9 appears.

Figure 4.9. Message Resulting from Inadvertently Adding a Key to a Dictionary

To avoid this problem, check for the existence of a key before trying to access the value of the item.

Like most collections, the Dictionary object has a Count property that returns the number of key-item pairs in the collection. The script in Listing 4.46 creates an instance of the Dictionary object, adds three key-item pairs, and then echoes the value of the Count property.

1 Set objDictionary = CreateObject("Scripting.Dictionary")
2 objDictionary.Add "Printer 1", "Printing"
3 objDictionary.Add "Printer 2", "Offline"
4 objDictionary.Add "Printer 3", "Printing"
5 Wscript.Echo objDictionary.Count

When this script runs, the value 3 (the number of key-item pairs in the collection) will be echoed to the screen.

A Dictionary is designed to serve as a temporary repository for information. Any data placed in a Dictionary is not intended for permanent storage; it is simply placed in the Dictionary temporarily and then later recalled for use within the script. For example, a list of server names might be placed in the Dictionary. Later the script might need to connect to each of these servers and retrieve a specified piece of information. As a result, the information stored in the Dictionary will have to be recalled each time the script needs to connect to a new server.

The Keys and Items methods can be used to return arrays consisting of, respectively, all the keys and all the items in a Dictionary. After you have called one of these methods, you can use a For Each loop to enumerate all the keys or items in the array.

For example, the script in Listing 4.47 creates a simple Dictionary with three keys and three items. After the Dictionary has been created, the script uses the Keys method to enumerate all the keys in the Dictionary and the Items method to enumerate all the items in the Dictionary.

 1 Set objDictionary = CreateObject("Scripting.Dictionary")
 2 objDictionary.Add "Printer 1", "Printing"
 3 objDictionary.Add "Printer 2", "Offline"
 4 objDictionary.Add "Printer 3", "Printing"
 5
 6 colKeys = objDictionary.Keys
 7 For Each strKey in colKeys
 8     Wscript.Echo strKey
 9 Next
10
11 colItems = objDictionary.Items
12 For Each strItem in colItems
13     Wscript.Echo strItem
14 Next

When this script is run under CScript, the following output appears in the command window:

Printer 1
Printer 2
Printer 3
Printing
Offline
Printing

To display the value of a specific item, use the Item method. For example, the following code statement displays the item value (Printing) associated with the key Printer 3:

Wscript.Echo objDictionary.Item("Printer 3")

One of the major advantages the Dictionary object has over an array or a standard collection is that you can quickly verify the existence of a particular key. For example, suppose you have a list of files installed on a computer and want to search that list to ensure that a particular set of DLLs has been installed. With either a collection or an array, there is no way to verify the existence of any one file without methodically looping through the entire set and checking each item individually.

With a Dictionary, however, you can use the Exists method to verify the existence of any given key. The Exists method takes a single parameter (the name of the key) and then returns a Boolean value: True if the key is in the Dictionary, False if it is not.

For example, the script in Listing 4.48 creates a Dictionary object and adds three elements: Printer 1, Printer 2, and Printer 3. The script then checks for the existence of a key named Printer 4 and echoes back the results of that check.

1 Set objDictionary = CreateObject("Scripting.Dictionary")
2 objDictionary.Add "Printer 1", "Printing"
3 objDictionary.Add "Printer 2", "Offline"
4 objDictionary.Add "Printer 3", "Printing"
5 If objDictionary.Exists("Printer 4") Then
6     Wscript.Echo "Printer 4 is in the Dictionary."
7 Else
8     Wscript.Echo "Printer 4 is not in the Dictionary."
9 End If

When this script runs, the message “Printer 4 is not in the Dictionary” is echoed to the screen.

Items added to a Dictionary are not set in stone; in fact, you can modify the value of an item at any time. This allows you to do record keeping within a script. For example, your Dictionary might list the names of servers being targeted by the script. Each time the script is run against a server, the value of that Dictionary item can be changed to indicate whether the script succeeded. Right before the script terminates, it can then print a status report showing you a list of successes and failures.

The script shown in Listing 4.49 creates a Dictionary with three keys: servers atl-dc-01, atl-dc-02, and atl-dc-03. In each case, the item value for the key has been set to “No status.” This is done to indicate that status information on the server has not been obtained. The item values are then echoed to the screen.

After the Dictionary has been created, the item value for each of the three keys is changed by using the Item method, with the key name passed as the parameter. For example, the following code statement sets the item value for the key atl-dc-01 to “Available”:

objDictionary.Item("atl-dc-01") = "Available"

After the three item values have been changed, the new item values are echoed to the screen.

 1 Set objDictionary = CreateObject("Scripting.Dictionary")
 2 objDictionary.Add "atl-dc-01", "No status"
 3 objDictionary.Add "atl-dc-02", "No status"
 4 objDictionary.Add "atl-dc-03", "No status"
 5
 6 colKeys = objDictionary.Keys
 7 For Each strKey in colKeys
 8     Wscript.Echo strKey, objDictionary.Item(strKey)
 9 Next
10
11 objDictionary.Item("atl-dc-01") = "Available"
12 objDictionary.Item("atl-dc-02") = "Available"
13 objDictionary.Item("atl-dc-03") = "Unavailable"
14
15 colKeys = objDictionary.Keys
16 For Each strKey in colKeys
17     Wscript.Echo strKey, objDictionary.Item(strKey)
18 Next

When the script is run under CScript, the following information appears in the command window:

atl-dc-01 No status
atl-dc-02 No status
atl-dc-03 No status
atl-dc-01 Available
atl-dc-02 Available
atl-dc-03 Unavailable

Key-Item pairs can also be removed from a Dictionary. The Script Runtime library provides two methods for removing key-item pairs from a Dictionary:

objDictionary.RemoveAll

 1 Set objDictionary = CreateObject("Scripting.Dictionary")
 2 objDictionary.Add "Printer 1", "Printing"
 3 objDictionary.Add "Printer 2", "Offline"
 4 objDictionary.Add "Printer 3", "Printing"
 5 colKeys = objDictionary.Keys
 6 Wscript.Echo "First run: "
 7 For Each strKey in colKeys
 8     Wscript.Echo strKey
 9 Next
10 objDictionary.RemoveAll
11 colKeys = objDictionary.Keys
12 Wscript.Echo VbCrLf & "Second run: "
13 For Each strKey in colKeys
14     Wscript.Echo strKey
15 Next

First run:
Printer 1
Printer 2
Printer 3

Second run:

atl-dc-01
atl-dc-02
atl-dc-03
atl-dc-04
atl-dc-05

atl-dc-03
atl-dc-04

objDictionary.Remove("atl-dc-02")

 1 Set objDictionary = CreateObject("Scripting.Dictionary")
 2 objDictionary.Add "Printer 1", "Printing"
 3 objDictionary.Add "Printer 2", "Offline"
 4 objDictionary.Add "Printer 3", "Printing"
 5 colKeys = objDictionary.Keys
 6 Wscript.Echo "First run: "
 7 For Each strKey in colKeys
 8     Wscript.Echo strKey
 9 Next
10 objDictionary.Remove("Printer 2")
11 colKeys = objDictionary.Keys
12 Wscript.Echo VbCrLf & "Second run: "
13 For Each strKey in colKeys
14     Wscript.Echo strKey
15 Next

First run:
Printer 1
Printer 2
Printer 3

Second run:
Printer 1
Printer 3