Downloads
40883.zip

ActiveX COM controls (aka components) are useful tools that you can use in your scripts. For example, one Microsoft control called DSOleFile lets you read and modify the file properties of Microsoft Office documents on computers that don't have a licensed copy of Office installed on them. Another Microsoft control called ScriptPW lets you enter a password in a script without having that password displayed on screen. ActiveX COM controls don't have to be Microsoft components. Many third-party controls are also available, such as ServerObjects' WaitFor component. This component lets you pause a script for a specified amount of time. Let's take a look at how you can use DSOleFile, ScriptPW, and WaitFor in your scripts.

DSOleFile
In Windows Server 2003 and Windows XP, you can use the DSOleFile control, which lets you write scripts that read and modify the summary properties of Office documents (e.g., Microsoft Word files, Microsoft Excel files), without needing to automate Office directly. This functionality is useful if you need to manipulate the properties of such files but you haven't installed Office on the computer on which you're working. This situation typically occurs on servers. Many systems administrators don't want to install Office on servers because they want to limit interactive use and prevent the propagation of viruses. With the DSOleFile component, you can manipulate Office documents' properties without buying a license for Office, so you have more flexibility in where you run your scripts.

You can download the DSOleFile control's self-extracting executable, dsofile.exe, from Microsoft's Web site at http://support.microsoft.com/?kbid=224351. When the executable runs, the installation program installs the control in the location you specify and automatically registers it. The installation program creates two registry keys—HKEY_CLASSES_ROOT\DSOleFile.PropertReader and HKEY_CLASSES_ROOT\DSOleFile.PropertyReader.1—along with their associated subkeys, value names, and values.

Scant documentation exists for the DSOleFile control. In addition to the aforementioned Web site, the Object Browser in Word (or another Office application) provides information about the component's functionality. The reference you need to add to the Object Browser is DS: OLE Document Properties 1.4 Object Library. If you're unfamiliar with how to use the Object Browser, see the Web-exclusive sidebar "How to Examine Components with Word's Object Browser," http://www.winnetmag.com/windowsscripting, InstantDoc ID 40884.

Another place you can find information about the component's functionality is in the \dsofile\vbtest folder. This folder contains a DS: OLE Document Properties demonstration project and workspace that you can open in Visual Studio (VS) or another IDE that can read Visual Basic (VB). If you want to look at some of the VB code in this project but you don't have VS or another IDE, you can open the FileProp.frm file in that folder. This file can be confusing because it describes Windows forms for onscreen display, but toward the bottom is some VB code that provides a glimpse of what the developers intended for DSOleFile.

The script DocPropTester.vbs, which Listing 1 shows, demonstrates how to use the DSOleFile control with VBScript code. This script reads some of the available properties from a Word file, then adds a custom property to that file.

DocPropTester.vbs begins by declaring the variables and initializing the strFile variable with the pathname of a Word document. The script then creates a DSOleFile PropertyReader object and stores a reference to that object in the objFilePropReader variable. The script calls the PropertyReader object's GetDocumentProperties method, which returns a DocumentProperties object, and stores a reference to the DocumentProperties object in the objDocProp variable. As the code at callout A in Listing 1 shows, you use the DocumentProperties object to read the Word document's properties. If you've worked with file properties before, these properties will be familiar to you. They include such properties as Name, Author, and WordCount, whose values specify the document's name, author, and word count, respectively.

Next, the script uses the CustomProperties object's Add method to add a new custom property called TestProp to the file and add a value for that property. VBScript's MsgBox function then displays all the previously retrieved constants, one on each line. When the property has no value, the script displays a blank line.

Finally, a For Each...Next statement loops through all the custom properties and displays in a separate message box each custom property's name and value. Before displaying a custom property's value, the script converts the value to a string in case it was stored as something else.

If you want to change the value of an existing property, you simply need to include a line such as

objDocProp.Comments = "AGLN"

in the script. This code changes the Comments property's value to the string AGLN. To run DocPropTester.vbs from the command-shell window, you use the command:

cscript.exe DocPropTester.vbs

ScriptPW
Windows 2003 and XP include a new system COM component called ScriptPW, which lets you create a Password object that masks passwords from view. This object is part of the scriptpw.dll file, which you can find in the C:\windows\system32 folder. The component also works in Windows 2000 if you copy scriptpw.dll to a Win2K system and use regsvr32.exe to register the DLL as a COM component. Assuming that you place the scriptpw.dll file in the C:\windows\system32 folder, you can use the following command to register the DLL:

C:\windows\system32\regsvr32.exe
C:\windows\system32\scriptpw.dll

(Although this command appears on two lines here, you would enter it on one line in the command-shell window. The same holds true for the other multiline commands in this article.)

Scriptpw.dll isn't officially part of the Windows Script Host (WSH) 5.6 object model, but you can use it in your WSH scripts. The ScriptPW control works as a password reader and lets you type sensitive data without displaying it. This control is useful because it delivers functionality that was previously absent. However, you'll likely encounter a couple of minor annoyances when you use it. First, the control doesn't work in a GUI environment. Thus, it's only available to console scripts running under the control of WSH's cscript.exe. Second, the control captures all typed text without providing any onscreen feedback to the user. Specifically, it simply displays an unmoving blinking cursor as the user enters a password. It doesn't provide a row of asterisks (*), as you might expect. All that being said, the control is still an important component to be aware of.

SimplePasswordMask.vbs, which Listing 2 shows, is a short script that demonstrates how to use the ScriptPW component. After the script declares the variables, it creates a Password object and stores a reference to it in the objPassword variable. The script then writes the message Please enter your password: to the standard output (i.e., the console window) without forcing a new line at the end of that text. When the user enters his or her password, nothing but the blinking cursor appears on screen. The Password object's GetPassword method then retrieves the password. As the code at callout A in Listing 2 shows, the script ends by displaying a blank line followed by the user's password to prove that the script really retrieved the password.

You can use SimplePasswordMask.vbs to test the control. To run the script, you use the command

cscript.exe
   SimplePasswordMask.vbs

If you use the code in Listing 2 in a script that you'll run in a production environment, you'll want to remove the lines that callout A highlights. Otherwise, you'll be defeating the purpose of the control.

WaitFor
The WaitFor control is one of several free components that you can download from the ServerObjects Web site (http://www.serverobjects.com/products.htm#free). WaitFor can pause a script for a specified number of seconds, pause a script while it tries to find a file, and pause a script while it determines whether it has access to a particular file. Although you can use Windows Management Instrumentation (WMI) events or the WSH WScript object's Sleep method to perform these three tasks, using WaitFor is much easier.

After you download WaitFor, you need to use regsvr32.exe to register the waitfor.dll file. For example, if you placed the DLL in the C:\waitfor folder, you can use the command

C:\windows\system32\regsvr32.exe
   C:\waitfor\waitfor.dll

The script WaitForTester.vbs, which Listing 3 shows, demonstrates how to use WaitFor. After the script declares the variables, it creates a WaitFor Comp object, which it will use to perform each of the three WaitFor tasks.

In Section 1, the Comp object's WaitForSeconds method pauses the script for 5 seconds. This method takes one parameter: a value that specifies the number of seconds to pause. For demonstration purposes, the script displays the time before and after the pause.

In Section 2, the Comp object's WaitForFileExists method pauses the script while it tries to find the specified file. You might expect that this method would take two parameters: the file's pathname and the maximum amount of time to wait. However, this method takes only the file's pathname as a parameter. For this method to know the maximum amount of time to pause the script, you need to preset the Comp object's TimeOut property to the desired number of seconds. As the code at callout A in Listing 3 shows, you must set the TimeOut property before you call the WaitForFileExists method. If the method finds the file in the allotted time, it stops looking for the file, restarts the script, and returns a Boolean value of TRUE. If the method doesn't find the file within the allotted time, it restarts the script and returns a Boolean value of FALSE. The script passes the Boolean value to an If...Then...Else statement, which displays an appropriate message based on that value.

In Section 3, the Comp object's WaitForExclusiveFileAccess method pauses the script while it determines whether access is granted to the specified file. Similar to WaitForFileExists, WaitForExclusiveFileAccess takes the file's pathname as the only parameter. Once again, the TimeOut property specifies the maximum amount of time to pause the script, as the code at callout B in Listing 3 shows. In this case, the timeout period is 15 seconds. If you would want to use the same timeout period that WaitForFileExists used previously (i.e., 10 seconds), you wouldn't even have to include the line at callout B.

WaitForExclusiveFileAccess returns a Boolean value of TRUE when access to the specified file is granted or FALSE when access is denied. Depending on the returned value, the script displays an appropriate message.

You can easily test whether the WaitForFileExists and WaitForExclusiveFileAccess methods in WaitForTester.vbs are working properly. First, set the TimeOut property in Section 2 and Section 3 to a high number, such as 60. In Section 2, set the strFilename variable to C:\scripts\file1.txt. In Section 3, set the strFilename variable to C:\scripts\file2.doc.

Next, create file1.txt and put it in a folder other than the one you hard-coded in the script. Create file2.doc and leave the file open. Now run WaitForTester.vbs. To run the script from the command-shell window, use the following command

cscript.exe WaitForTester.vbs

While the script is looking for file1.txt in Section 2, copy that file into the C:\scripts folder. As soon as you do, the script will detect the existence of the file and move on to Section 3. While the script is looking for the file2.doc permissions, close that file in Word. The script will detect that it can now access that file and will alert you to that fact.

Useful Tools for Your Toolbox
I've found the DSOleFile, ScriptPW, and WaitFor controls quite useful in my scripts. I'm sure you'll find them useful, too. If you come across any other interesting controls in your scripting endeavors, let me know.