To create a new instance of a COM object, a script can call the WScript CreateObject method and pass it the Programmatic Identifier (ProgID) of the COM object by using the following syntax:

WScript.CreateObject("ProgID")

To continue the analogy with the library, the ProgID is roughly equivalent to the call number assigned to a book. If you go to the library and give the librarian the call number, he or she can locate the book for you. Likewise, if you pass the scripting host a ProgID, the scripting host can look in the registry and locate the COM object you want to create. ProgIDs are unique to each COM object, just as call numbers are unique to each book.

How do you know the correct ProgID for a given COM object? Unfortunately, there is no simple answer to that question; your best course of action is to look at the documentation that accompanies the object. All ProgIDs are stored in the HKEY_CLASSES_ROOT portion of the registry, as shown in Figure 3.4. However, this listing is of only limited use because not all of these ProgIDs can be accessed using scripts.

Figure 3.4. ProgIDs in the Registry

To be able to use a newly created object, the script needs to store a reference to the object in a variable by using the following syntax:

Set objVariable = WScript.CreateObject ("ProgID")

After a reference to the object is stored in a variable, the script can call a method or access a property of the object by using dot notation. (Dot notation is discussed in the “VBScript Primer” chapter of this book.)

Scripts call methods by using the following syntax:

objVariable.MethodName

Scripts access properties by using the same syntax:

objVariable.PropertyName

The script in Listing 3.1 creates a new instance of the ADSI System Information object (using the ProgID ADSystemInfo), stores a reference to it in the objSysInfo variable, and then displays the Domain Name System (DNS) domain name for the logged-on user.

1 Set objSysInfo = Wscript.CreateObject("ADSystemInfo")
2 Wscript.Echo "Domain DNS name: " & objSysInfo.DomainDNSName

As shown in Figure 3.5, only two portions of the code statement must change when you create different COM objects: the ProgID, and the name of the reference variable (if your script must reference multiple COM objects).

Figure 3.5. Elements of a Statement That Creates a COM Object

For example, the following lines of code bind to various COM objects. From line to line, the only item that changes is the ProgID:

Set objReference = Wscript.CreateObject("Word.Application")
Set objReference = Wscript.CreateObject("InternetExplorer.Application")
Set objReference = Wscript.CreateObject("Scripting.Dictionary")
Set objReference = Wscript.CreateObject("Wscript.Network")

If the COM object you want to use is already running, you can use that existing object rather than create a new instance. The WScript GetObject method lets you reference and use a previously instantiated object instead of creating a new one.

When you write scripts that use WMI or ADSI, you will typically use the GetObject method; this is because both WMI and ADSI are always available. (For example, you can stop the WMI service, but if you run a script that uses WMI, the service will automatically restart.) Although there are exceptions, a typical WMI script might start like this:

Set objWMIService = Wscript.GetObject("winmgmts:")

When you are writing scripts that use the WSH objects, you will usually use the CreateObject method because the WSH objects are not usually preinstantiated.

The VBScript language also provides CreateObject and GetObject functions. The VBScript CreateObject function and the WScript CreateObject method both instantiate COM objects when they are called with a single parameter, the ProgID of the COM object to instantiate. For example, these two lines of code — the first using the VBScript version of CreateObject and the second using the WSH version — are functionally identical; both instantiate an instance of the FileSystemObject:

Set objFSO = CreateObject("Scripting.FileSystemObject")
Set objFSO = Wscript.CreateObject("Scripting.FileSystemObject")

Both versions of CreateObject can also accept a second parameter; however, each interprets this second parameter in a completely different way. Consider these two lines of code. The first line uses VBScript, and the second uses WSH:

Set objExcel = CreateObject("Excel.Application", "Parameter2")
Set objExcel = Wscript.CreateObject("Excel.Application", "Parameter2")

The VBScript CreateObject function interprets the second parameter as a remote computer name and tries to create the COM object on that remote computer; in this example, it tries to instantiate an instance of Microsoft Excel on a remote computer named Parameter2. The WScript CreateObject method interprets a second parameter as a subroutine prefix to be used in handling events from the object. The two GetObject functions are similarly related.

To simply create a COM object, you can use either the VBScript function or the WScript CreateObject method. After the object has been created, there are no differences in capabilities; all the methods and properties of the object available using Wscript CreateObject are also available using VBScript CreateObject. Furthermore, these properties and methods are all called in identical fashion.

On the other hand, if you want to use the remote object creation or event-handling capabilities, you need to choose the method or function that provides that additional functionality. For more information about the VBScript CreateObject and GetObject functions, see “VBScript Primer” in this book.

One of the primary purposes of system administration scripting is to answer questions. How much free hard disk space is available on this server? Which user account is Internet Information Service running under? Available memory is quite low on this mail server; what processes are running and using up the memory?

For a script to answer questions such as these, it must retrieve the answers and have a way to communicate those answers back to you. Although scripts can save retrieved information in text files or databases, it is more common to have the script display that information on the screen. WSH can display information by using the Echo method.

The WScript Echo method takes one or more items as parameters and displays those items to the user. If a script is run under CScript, the items are displayed in the command window. If a script is run under WScript, the items appear in message boxes. The Echo method can display almost any kind of data, including strings, numbers, dates and times, and even the results of mathematical calculations. For example, this line of code displays the value 4, the result of adding 2 and 2:

Wscript.Echo 2 + 2

The Echo method is easy to implement; you simply call the method, followed by the information you want to display on the screen. To display the value of a variable, specify the variable name as the parameter:

Wscript.Echo strMyVariable

This also holds true for VBScript variables such as Now and Time:

Wscript.Echo Now

To display a string, simply enclose it in quotation marks:

Wscript.Echo "This is my string."

In fact, the only real trick to working with Wscript.Echo is understanding the difference between what happens when a script using this method runs under CScript and what happens when that same script runs under WScript. For example, consider the script in Listing 3.3, which displays three status messages by using the WScript.Echo method.

1 Wscript.Echo "Examining System Drives"
2 Wscript.Echo "Determining Free Drive Space"
3 Wscript.Echo "Mapping Network Drives"

When run under CScript, the script displays the following in a command window — all at once, without stopping or requiring any user interaction.

Examining System Drives
Determining Free Drive Space
Mapping Network Drives

When run under WScript, however, the script creates three separate message boxes, as shown in Figure 3.7. The message boxes are presented one at a time, and each requires a user to click the OK button before the next one can be displayed.

Figure 3.7. Three Separate Message Boxes Produced by the Echo Method Running Under WScript

Under WScript, each call to the WScript.Echo method results in the creation of a new message box. Depending on the script, this can be very important. If your script simply returns the amount of free disk space on drive C, the fact that this information is displayed in a message box rather than in the command window might be irrelevant. Suppose, however, that the script returns a list of all the services installed on a computer. Using WScript, you would need to respond to 100 or so message boxes, one for each service. In addition, as each message box was dismissed, that piece of information would disappear from the screen.

Under CScript, not only is the information displayed in the command window without the need for any user intervention (such as dismissing message boxes), but all the information also remains on the screen until the command window is dismissed. This allows you to copy the data and paste it into another application.

Command-line tools (including batch files) typically interact with three standard input and output streams. These are known as Standard In (StdIn), Standard Out (StdOut), and Standard Error (StdErr). Unless you specify otherwise, the command processor assumes that input will be received from the keyboard (StdIn) and output (StdOut) and error messages (StdErr) should be sent to the command window.

StdIn, StdOut, and StdErr (available only when your scripts run under CScript) provide your scripts with access to each of these streams. These streams serve several important purposes:

StdOut can be used to display output within a command window. StdOut includes the properties shown in Table 3.4.

Wscript.StdOut.Write "ABCD"
Wscript.StdOut.Write "EFGHIJKLMN"
Wscript.StdOut.Write "OPQRSTUV"
Wscript.StdOut.Write "WXYZ"

ABCDEFGHIJKLMNOPQRSTUVWXYZ

Wscript.StdOut.WriteLine "ABCD"
Wscript.StdOut.WriteLine "EFGHIJKLMN"
Wscript.StdOut.WriteLine "OPQRSTUV"
Wscript.StdOut.WriteLine "WXYZ"

ABCD
EFGHIJKLMN
OPQRSTUV
WXYZ

Wscript.StdOut.WriteLine "ABCD"
Wscript.StdOut.WriteBlankLines 1
Wscript.StdOut.WriteLine "EFGHIJKLMN"
Wscript.StdOut.WriteLine "OPQRSTUV"
Wscript.StdOut.WriteBlankLines 2
Wscript.StdOut.WriteLine "WXYZ"

ABCD

EFGHIJKLMN
OPQRSTUV

WXYZ

The script in Listing 3.4 displays a message in the command window by using the Write and WriteLine methods of the StdOut TextStream object.

 1 Set objNetwork = Wscript.CreateObject("Wscript.Network")
 2 Set objStdOut = WScript.StdOut
 3 objStdOut.Write "User: "
 4 objStdOut.Write objNetwork.UserDomain
 5 objStdOut.Write ""
 6 objStdOut.Write objNetwork.UserName
 7 objStdOut.WriteBlankLines(1)
 8 objStdOut.WriteLine objNetwork.ComputerName
 9 objStdOut.Write "Information retrieved."
10 objStdOut.Close

The following is output from the script in Listing 3.4:

User: FABRIKAMkenmyer

atl-wk-01
Information retrieved.

By contrast, here is what output from the same script would look like if Wscript.Echo were substituted for the StdOut methods:

User:
FABRIKAM

kenmeyer

atl-wk-01
Information retrieved.

One way to provide a script with input is to use arguments (discussed later in this chapter). For example, the following command runs a script named DeleteUser.vbs, passing as an argument the name of the user account to be deleted:

cscript DeleteUser.vbs kenmyer

Arguments provide a quick and easy way to add input to a script. On the other hand, arguments require the user running the script to know which arguments need to be supplied and to know how to supply them. Instead of requiring users to memorize the syntax for your scripts, you can prompt users to supply the correct information after the script has started. For example:

C:Scriptscscript DeleteUser.vbs
Please enter the name of the user account to be deleted: _

StdIn can be used to read information entered at the command line. StdIn includes the methods and properties shown in Table 3.5.

Do Until Wscript.StdIn.AtEndOfLine
    strInput = Wscript.StdIn.Read(3)
    Wscript.Echo strInput
Loop

abc
def
ghi
jkl
mno
pqr
stu
vwx
yz

strInput = Wscript.StdIn.ReadLine
Wscript.Echo strInput

abcdefghijklmnopqrstuvwxyz

Wscript.StdIn.Skip(23)
Do Until Wscript.StdIn.AtEndOfLine
    strInput = Wscript.StdIn.Read(1)
    Wscript.Echo strInput
Loop

x
y
z

Do Until Wscript.StdIn.AtEndOfLine
    strInput = Wscript.StdIn.Read(1)
    Wscript.Echo strInput
Loop

You can use StdIn to retrieve information from the user. To obtain input from the user, you do the following:

For instance, suppose you create a script that converts numbers from decimal to hexadecimal. You need to prompt the user to enter the decimal value to convert. The script in Listing 3.5 uses the ReadLine method of the WScript StdIn object to retrieve a decimal value from the user and store it in the strDecimal variable. The VBScript Hex function is used to convert the decimal value to hexadecimal, and the WriteLine method of the WScript StdOut object is used to display the results.

1 Wscript.StdOut.Write "Enter a Decimal Number: "
2 strDecimal = Wscript.StdIn.ReadLine
3
4 Wscript.StdOut.WriteLine strDecimal & " is equal to " & _
5     Hex(strDecimal) & " in hex. "

When run under CScript, the interaction between the script and the user looks similar to this:

C:Scripts>cscript test.vbs
Microsoft (R) Windows Script Host Version 5.6
Copyright (C) Microsoft Corporation 1996-2001. All rights reserved.

Enter a Decimal Number: 256
256 is equal to 100 in hex.

When you run a script with command-line arguments, the WSH runtime stores these values in a location in memory represented by the WshArguments collection. The WSH runtime stores the arguments in the WshArguments collection in the order in which they were entered on the command line: WScript.Arguments.Item(0) contains the first command-line argument, WScript.Arguments.Item(1) contains the second argument, and so on.

In addition to storing all command-line arguments in the WshArguments collection, WSH automatically filters the command-line arguments into one of two subcollections: WshNamed or WshUnnamed. Arguments that conform to /name:value format are stored in the WshNamed collection, and arguments that do not follow the /name:value format are stored in the WshUnnamed collection. The purpose behind filtering arguments will become clear later in this section.

For example, the following command runs the ServerStats.vbs script and passes three command-line arguments to the script: /s:atl-dc-01, /u:admin, and perf.

cscript serverstats.vbs /s:atl-dc-01 /u:admin perf

The command-line arguments follow the script name and are separated by one or more spaces. Because of this, command-line arguments that contain white space must be enclosed in quotation marks to be treated as a single argument. For example, in this command, the third argument contains a blank space. As a result, the entire argument must be enclosed in quotation marks:

cscript serverstats.vbs /s:atl-dc-01 /u:admin "perf monitor"

Without the quotation marks, perf and monitor would be treated as separate arguments.

Figure 3.9 illustrates the contents of the three argument collections having run status.vbs with the three command-line arguments /s:atl-dc-01, /u:admin, and perf.

Figure 3.9. Mechanics of the WSH Argument Collections

All command-line arguments are stored in the WshArguments collection exactly as they are typed on the command line. Count and Length return the total number of command-line arguments entered on the command line.

The WshNamed filtered collection contains the two named arguments. Named arguments are arguments that consist of two parts: a name and a value. The name must be prefaced with a forward slash, and a colon must separate the name from the value. The slash prefix and the colon separator are fixed and cannot be changed. For example, you cannot use a hyphen in place of the slash; the following command will not pass Server as a named argument; instead, it will treat -Server:atl-dc-01 as the value of a single unnamed argument:

cscript serverstats.vbs -Server:atl-dc-01

If you examine Figure 3.9 closely, you will see that named arguments are modified before they are stored in the WshNamed collection. The name portion of the argument becomes the index, or key, and is used with the WshNamed Item property to identify the argument to retrieve. The name is also used with the WshNamed Exists method to check whether a named argument was provided to the script at run time. The slash prefix and the colon separator are discarded, and only the value portion of the named argument is stored in the Item property of the WshNamed collection. Like WshArguments, the WshNamed Count method and Length property return the number of filtered arguments in the WshNamed collection.

The WshUnnamed filtered collection contains the one unnamed argument: perf. The WshUnnamed Count method and Length property return the number of filtered arguments in the WshUnnamed collection.

There are three ways to access command-line arguments:

As described in the preceding topic, all command-line arguments are stored in the default arguments collection, WshArguments. The WshArguments collection is accessed through the WScript Arguments property. WshArguments provides two methods and four properties to read and work with command-line arguments.

Methods

Count. Returns the total number of arguments in the WshArguments collection.

ShowUsage. Echoes usage instructions about the script. This is constructed from information provided in the <runtime> section of a Windows Script File (.wsf). Windows Script Files are not discussed in this book.

Properties

Named. Provides access to the WshNamed collection. WshNamed is a filtered collection of arguments, where each argument conforms to the following format: /name:value. Command-line arguments that conform to the /name:value format are called named arguments in WSH.

Unnamed. Provides access to the WshUnnamed collection. WshUnnamed is a filtered collection of arguments, drawn from WshArguments, that do not conform to the /name:value format. Windows Script Host refers to these as unnamed arguments.

Length. Returns the total number of arguments in the WshArguments collection.

Note

You might have noticed that the Length property is identical to the Count method. Length was provided to maintain a level of consistency with the ECMAScript Language Specification, Standard ECMA-262, which JScript is based on. Although either Count or Length can be used to determine the number of arguments passed to VBScript, you must use Length with JScript. Any attempt to use Count with JScript will result in a run-time error.

Item(n). Retrieves the element from the WshArguments collection that corresponds to the index number enclosed in parentheses.

The following command runs a fictitious script named GetEvents.vbs with three arguments:

cscript getevents.vbs atl-dc-01 "Directory Service" 1130

WSH stores the three arguments in the WshArguments collection in the order in which they were entered, and exactly as they were typed on the command line. To read the three arguments, you use the WScript Arguments property in combination with the WshArguments Item property as shown here:

ServerName = WScript.Arguments.Item(0)
EventLog = WScript.Arguments.Item(1)
EventID = WScript.Arguments.Item(2)

Because collections are zero-based, WScript.Arguments.Item(0) points to the first argument in the WshArguments collection. WScript.Arguments.Item(1) points to the second argument, which is enclosed inside quotation marks because the argument, Directory Services, contains a space. Omitting the quotation marks would cause the two words to be treated as separate arguments, which would lead to errors because incorrect values would be assigned to the EventLog and EventID variables. WScript.Arguments.Item(2) points to the third argument.

The collection looks like the one shown in Table 3.6.

If the fictitious script employed additional arguments, WScript.Arguments.Item(3) would point to the fourth argument, WScript.Arguments.Item(4) would point to the fifth argument, and so on.

There is no fixed limit on the number of arguments that can be stored in the WshArguments collection. However, the entire command line, which includes the host name, host options, script name, and script arguments, cannot exceed the maximum command-line length. Exceeding the maximum command-line length generally is not a problem unless you use the WSH Drag and Drop feature to populate WshArguments. The maximum command-line length also applies to WSH Drag and Drop.

You can reduce the amount of typing necessary to access each argument by setting a reference to the WshArguments collection by way of the WScript Arguments property. Use the VBScript Set keyword followed by the variable name you want to use to access the WshArguments collection. Set is required because collections are standard COM objects. The following example is functionally equivalent to the preceding example despite some syntactical differences.

Set args = WScript.Arguments
ServerName = args.Item(0)
EventLog = args.Item(1)
EventID = args.Item(2)

The previous three examples assume GetEvents.vbs is always passed three command-line arguments. While omitting any kind of argument verification might be OK for a quick ad hoc script, failing to perform some level of verification can lead to error-prone scripts, especially when the script is shared with other users.

The following command runs the fictitious GetEvents.vbs script without any arguments.

cscript getevents.vbs

Running GetEvents.vbs without arguments using one of the three previous examples would result in the following run-time error:

C:ScriptsGetEvents.vbs(2, 1) Microsoft VBScript runtime error: Subscript out of
range

Any attempt at using the Item property to access an argument that does not exist will result in a Subscript out of range run-time error. Listing 3.6 demonstrates how to use the WshArguments Count method to verify that the correct number of command-line arguments is provided to the script at run time.

1 If WScript.Arguments.Count = 3 Then
2     ServerName = WScript.Arguments.Item(0)
3     EventLog = WScript.Arguments.Item(1)
4     EventID = WScript.Arguments.Item(2)
5 Else
6     Wscript.Echo "Usage: GetEvents.vbs ServerName EventLog EventID"
7     Wscript.Quit
8 End If

In Line 1 of Listing 3.6, the script uses the WshArguments Count method to obtain the number of command-line arguments in the WshArguments collection. If the value is equal to 3, the script initializes the ServerName, EventLog, and EventID variables with the three arguments in the WshArguments collection. Otherwise, the script echoes usage instructions and immediately exits.

Unnamed arguments are entered on the command line as values only, without an associated name. At times the order of your arguments might be irrelevant; for example, a script might require you to type in three computer names, and it makes no difference which computer the script runs against first. Otherwise, unnamed arguments must be entered in the order that the script requires.

You might want to use unnamed arguments when your script:

When you run a script with unnamed command-line arguments, the WSH runtime stores the arguments in the WshArguments collection in the order in which they were entered on the command line. The arguments can then be referenced in the script using index numbers that represent the order in which they were entered. The sequence of index numbers begins with 0.

The script in Listing 3.7 uses the unnamed command-line arguments collection to retrieve and display the command-line arguments provided to it.

1 strServer = WScript.Arguments.Item(0)
2 strPacketSize = WScript.Arguments.Item(1)
3 strTimeout = WScript.Arguments.Item(2)
4
5 Wscript.Echo "Pinging Server: " & strServer
6 Wscript.Echo "Packet Size: " & strPacketSize
7 Wscript.Echo "Timeout: " & strTimeout

The following command runs the script with the command-line arguments entered in the order required by the script.

EchoUnnamedArgs.vbs DCServer01 100 5000

This command produces the following output:

Pinging Server: DCServer01
Packet Size: 100
Timeout: 5000

This command runs the same script with the command-line arguments entered in the wrong order.

EchoUnnamedArgs.vbs 100 DCServer01 5000

This command produces the following output:

Pinging Server: 100
Packet Size: DCServer01
Timeout: 5000

The output from the first command is correct but the output from the second command is incorrect. Because the script is written using unnamed arguments, the order in which the command-line arguments are entered is crucial for the script to work properly. If the script actually tried to run Ping.exe, the procedure would fail because there is no server named 100 and no such thing as a packet size of DCServer01.

As the preceding example showed, the order in which unnamed arguments are entered can make the difference between a script that runs successfully and a script that does not. This places a considerable burden on administrators running the script; not only must they supply the correct arguments, but they must also supply them in the correct order. One mistake will likely cause the script to fail.

To make it easier for people to run scripts that use multiple arguments, you can use named arguments instead. Named arguments are entered on the command line as values with associated names. They can be entered in any order.

A named argument begins with a slash (/), and the name and the value are separated by a colon (:). The following command runs a script named ServerTest.vbs with two named arguments:

ServerTest.vbs /Server:HRServer01 /Timeout:3000

The name of the first argument is Server, and its value is HRServer01. The name of the second argument is Timeout, and its value is 3000. These arguments could also be entered in the reverse order, as follows:

ServerTest.vbs /Timeout:3000 /Server:HRServer01

When you run a script with named command-line arguments, each argument’s name and value are stored in the WshNamed collection.

The script in Listing 3.8 uses the named command-line arguments collection to retrieve and display the command-line arguments it receives in the command window.

1 Set colNamedArguments = WScript.Arguments.Named
2
3 strServer = colNamedArguments.Item("Server")
4 strPacketSize = colNamedArguments.Item("PacketSize")
5 strTimeout = colNamedArguments.Item("Timeout")
6 Wscript.Echo "Server Name: " & strServer
7 Wscript.Echo "Packet Size: " & strPacketSize
8 Wscript.Echo "Timeout (ms): " & strTimeout

The following command runs the script with three named arguments.

EchoNamedArgs.vbs /Server:HRServer01 /PacketSize:300 /Timeout:8000

This command produces the following output:

Server Name: HRServer01
Packet Size: 300
Timeout (ms): 8000

This command runs the same script with the order of the named arguments changed.

EchoNamedArgs.vbs /Timeout:8000 /PacketSize:300 /Server:HRServer01

This command produces the following output:

Server Name: HRServer01
Packet Size: 300
Timeout (ms): 8000

The output from the first command and the second command is the same. You can enter named arguments in any order without affecting the outcome of the script.

Named arguments are also useful when you want to include optional parameters within your scripts. The script in Listing 3.9 is similar to the script in Listing 3.8, but the PacketSize argument is an optional argument. If the script user does not enter a packet size, the script uses a default packet size.

The script uses the Exists method to check whether the user entered an argument named PacketSize. If the result of the test is True, the script proceeds to line 7. If the result of the test is False, the script proceeds to line 9, where the PacketSize variable is set to 100, using the DEFAULT_PACKET_SIZE constant.

 1 Const DEFAULT_PACKET_SIZE = 100
 2
 3 Set colNamedArguments = WScript.Arguments.Named
 4
 5 strServer = colNamedArguments.Item("Server")
 6 If colNamedArguments.Exists("PacketSize") Then
 7     strPacketSize = colNamedArguments.Item("PacketSize")
 8 Else
 9     strPacketSize = DEFAULT_PACKET_SIZE
10 End If
11 strTimeout = colNamedArguments.Item("Timeout")
12
13 Wscript.Echo "Server Name: " & strServer
14 If colNamedArguments.Exists("PacketSize") Then
15     Wscript.Echo "Packet Size :" & strPacketSize
16 Else
17     Wscript.Echo "Packet Size [default]: " & strPacketSize
18 End If
19 Wscript.Echo "Timeout (ms): " & strTimeout

In most cases, you should not use both named and unnamed arguments in the same script. Using both types of arguments makes the required command-line syntax more difficult to remember. If your script accepts two or fewer arguments or multiple arguments of the same type, you might want to use unnamed arguments. If your script accepts three arguments of distinct types or has optional arguments, you should probably use named arguments.

Occasionally, however, it can be useful to mix named and unnamed arguments in a script. For example, if you have a script that has one required argument and a number of optional arguments, you can use an unnamed argument for the required argument and named arguments for all of the optional arguments. The following command contains a required server name (HRServer01) plus three optional arguments. In this command, the unnamed argument must be listed first, or the script will likely fail.

CheckServer.vbs HRServer01 /timeout:200 /logfile:serverlog.txt /verbose:true

Many of your scripts will require you to enter the required number and types of command-line arguments for the scripts to run correctly. You might need to perform two verifications on command-line arguments:

Verifying the Number of Arguments Entered

Some scripts require a specific number of command-line arguments. For example, suppose you have a script that copies files from one computer to another. This script likely requires two, and only two, command-line arguments: the name of the source computer and the name of the target computer. Trying to run this script with one command-line argument or with three command-line arguments would not make any sense; there would be no way for the script to correctly determine the source and target computers.

In a situation such as this, one of the first things the script should do is verify that two command-line arguments were entered. This requires little effort on your part because arguments are returned as part of a collection, and collections typically include a Count property. The purpose of the Count property is to tell you how many items are in the collection. If Wscript.Arguments.Count equals 2, two arguments are in the collection.

The script in Listing 3.10 verifies the number of command-line arguments entered. The script accepts up to four arguments, any two of which are optional. Therefore, the user must enter at least two but no more than four arguments.

1 iNumberOfArguments = WScript.Arguments.Count
2 If iNumberOfArguments >= 2 And iNumberOfArguments <= 4 Then
3     Wscript.Echo iNumberOfArguments & " arguments entered. " & _
4         "This is a valid number."
5 Else
6     Wscript.Echo "Error: invalid number of arguments entered. " & _
7         "Please enter 2, 3, or 4 arguments."
8     Wscript.Quit
9 End If

In line 1 of Listing 3.10, the script uses WScript.Arguments.Count to determine the number of command-line arguments entered. The script stores this value in the iNumberOfArguments variable.

In line 2, the script uses iNumberOfArguments >=2 And iNumberOfArguments <=4 to test whether the user entered 2, 3, or 4 arguments:

The following command tries to run the script with more than four arguments.

CheckNumArgs.vbs HRServer01 RASServer01 SQLServer01 1000 300

This command produces the following output:

Error:    invalid number of arguments entered. Please enter 2, 3, or 4 arguments.

The output informs you that you have entered the wrong number of arguments. You are told that you should have entered between two, three, or four arguments instead of the five you entered.

This command runs the script with three arguments, an acceptable number for the script.

CheckNumArgs.vbs HRServer01 1000 300

This command produces the following output:

3 arguments entered. This is a valid number.

The output validates the fact that you have entered the correct number of arguments and that, as a result, the script is proceeding as expected. The script then displays the number of arguments you entered.

Verifying That All Required Arguments Are Entered

When you use command-line arguments in a script, the script should check to ensure that any required arguments have been entered before it proceeds. Unfortunately, WSH does not allow you to specify that an argument is required, and then notify you if the argument is not found. For example, if you run a command-line tool without a required argument, the tool typically will not run; instead, it displays usage instructions. Your scripts can do the same thing, but it is up to you to write code that checks the arguments collection and ensures that all the required arguments are present.

If you need to use required arguments in a script, it is recommended that you use named arguments. One advantage of using named arguments is that you can then use the Exists method to check whether an argument has been provided. For example, this line of code checks whether an argument named FolderName is present in the arguments collection. If the argument exists, the value –1 (True) will be echoed to the screen. Otherwise, the value 0 (False) will be displayed:

Wscript.Echo colNamedArguments.Exists("FolderName")

Suppose you enter the correct number of arguments but omit a required argument. The script in Listing 3.11 builds on the script in Listing 3.10. It uses the WshNamed collection Exists method to ensure that the named argument, Server, is among the arguments that you entered. In line 4, the script uses Not colNamedArgument.Exists(“Server”) to test whether the user has entered the named argument Server:

 1 iNumberOfArguments = WScript.Arguments.Count
 2 Set colNamedArguments = WScript.Arguments.Named
 3
 4 If Not colNamedArguments.Exists("Server") Then
 5     Wscript.Echo "Usage: /Server:<servername> is required."
 6     Wscript.Quit
 7 ElseIf iNumberOfArguments >= 2 Or iNumberOfArguments <= 4 Then
 8     Wscript.Echo iNumberOfArguments & " arguments entered"
 9     Wscript.Echo "including Server Name: " & _
10         colNamedArguments.Item("Server")
11 Else
12     Wscript.Echo "Usage: Please enter between 2 and 4 arguments."
13     Wscript.Quit
14 End If

The following command tries to run the script without including the Server named argument.

CheckReqArgs.vbs 1000 300

This command produces the following output:

Usage: /Server:<servername> is required.

The output reflects the fact that you have not entered the Server named argument, which is required, by displaying a usage message.

This command runs the script with the required argument and an acceptable number of arguments.

CheckReqArgs.vbs /Server:HRServer01 1000 300

This command produces the following output:

3 arguments entered
including Server Name: HRServer01

The output reflects the fact that you have entered the correct number of arguments, including the required Server named argument. The script displays the value entered for the Server argument to reinforce the fact that this required argument was actually entered.

Most of the time, WSH attempts to complete a script as quickly as possible; as soon as WSH finishes executing the first line of code, it begins executing the second line of code. More often than not, this is the desired behavior: In general, the faster a script can complete its tasks, the better.

There are times, however, when you do not want a script to run as quickly as possible. For example, suppose you need to monitor processor use on a computer. To do this, you might want to record processor use every 10 seconds until you have collected 100 measurements. In this case, you do not want the script to take these 100 measurements as quickly as it can. Instead, you want it to take the first measurement and then wait 10 seconds before taking the second measurement.

A script can force itself to pause by calling the WScript Sleep method. The Sleep method accepts a single parameter that indicates how long, in milliseconds, to pause the script. (There are 1,000 milliseconds in a second and 60,000 milliseconds in a minute.)

You will need to use the Sleep method in your scripts when:

The script in Listing 3.12 checks the amount of free space on all the disk drives on a computer. The script then pauses for 5 minutes (300,000 milliseconds) and then checks free disk space again.

 1 strComputer = "."
 2 Set objWMIService = GetObject("winmgmts:" _
 3     & "{impersonationLevel=impersonate}!\" & strComputer & "
ootcimv2")
 4 Do While True
 5     Set colDisks = objWMIService.ExecQuery _
 6         ("SELECT * FROM Win32_LogicalDisk")
 7     For Each objDisk in colDisks
 8         Wscript.Echo "DeviceID: " & objDisk.DeviceID
 9         Wscript.Echo "Free Disk Space: " & objDisk.FreeSpace
10     Next
11     Wscript.Sleep 300000
12 Loop

Note

The preceding script is designed to run indefinitely. To stop the script, you will need to terminate the process under which it is running.

In general, scripts begin by executing line 1 and continue to run until each line in the script has been executed. (This is not entirely true, but it will do for the purposes of this discussion. In reality, some lines of code — such as those in a particular function — might be skipped rather than executed.) After each line of code has been executed, the script automatically terminates itself. For example, this simple little script echoes three numbers to the screen and then quits. The script does not include any special instructions telling it to quit; it automatically terminates after executing the last line:

Wscript.Echo "1"
Wscript.Echo "2"
Wscript.Echo "3"

Most of the time, this is exactly what you want a script to do. However, there might be occasions when you want a script to terminate before every line of code has been executed. For example, suppose you have a script that requires two command-line arguments: a source computer and a target computer. At the very beginning of the script, you check to see whether two (and only two) arguments have been supplied. If they have, the script continues.

But what if they have not? What if the user supplied only one argument, or what if the user supplied four arguments? In that case, there is no reason to proceed; after all, the script is likely to fail and could leave one or more computers in an indeterminate state. In this case, the best course of action might be to echo a message stating that the user must supply two command-line arguments, and then immediately terminate the script, regardless of how many lines of code remain unexecuted.

A script can force itself to stop running before it reaches its last command by calling the Quit method. This can be done using a single line of code:

Wscript.Quit

When a script executes the Quit method, it immediately terminates. For example, this script echoes three messages and then quits. The last three Wscript.Echo commands will never execute:

Wscript.Echo "1"
Wscript.Echo "2"
Wscript.Echo "3"
Wscript.Quit
Wscript.Echo "4"
Wscript.Echo "5"
Wscript.Echo "6"

It is good practice to set the time-out value on any script, but it is particularly important if the script is liable to run into issues that might force it to run indefinitely.

For example, suppose you have a script that must first connect to a remote computer. What if this connection cannot be made? In that case, you might include code that tells the script to wait 60 seconds after a failed connection and then try again. The script will continue in this loop until the connection is made.

But what if the remote computer has been permanently removed from the network? In that case, the script could theoretically run forever, taking up computer processing cycles and using up network bandwidth as it tries to make a connection that can no longer be made. In a situation such as that, it might be beneficial to set the Timeout property. This instructs the script to run only for a set amount of time. If it cannot complete its task when the time period expires, the script simply terminates.

The WScript Timeout property sets a time period, in seconds, after which a script will stop running. (By default, WSH does not time out the running of a script.) Setting a Timeout ensures that no script will run forever.

The script in Listing 3.13 sets a time-out value of 5 seconds. If the script has not finished executing 5 seconds after it starts, the script will automatically terminate. Because the script includes a 60-second pause (line 2), the timeout will always expire before the script completes. As a result, line 3, which echoes a message to the screen, will never run.

1 Wscript.Timeout = 5
2 Wscript.Sleep 60000
3 Wscript.Echo "Script is finished."

The fact that there are two ways to run programs from a script leads to an obvious question: which method should you use in your scripts? The answer to that question depends on the script and what it needs to accomplish.

A script can use either the Run method or the Exec method to run a program in a manner similar to using the Run dialog box from the Start menu. Regardless of the method used, the program starts, and runs in a new process.

However, when you use the Run method, your script will not have access to the standard input, output, and error streams generated by the program being run. A script cannot use the Run method to run a command-line tool and retrieve its output.

For example, suppose you want to run Ping.exe and then examine the output to see whether the computer could be successfully contacted. This cannot be done using the Run command. Instead, you would need to ping the computer, save the results of the ping command to a text file, open the text file, read the results, and then parse those results to determine the success or failure of the command.

The following script uses the Run method to call Ping.exe, redirecting the output to a temporary file. The script opens and reads the text file, checks to see whether the command succeeded (by determining whether any of the lines of output begin with the word Reply), and then closes and deletes the temporary file:

Set objFSO = Wscript.CreateObject("Scripting.FileSystemObject")
Set objShell = Wscript.CreateObject("Wscript.Shell")
objName = objFSO.GetTempName
objTempFile = objName
objShell.Run "cmd /c ping -n 3 -w 1000 157.59.0.1 >" & objTempFile, 0, True
Set objTextFile = objFSO.OpenTextFile(objTempFile, 1)
Do While objTextFile.AtEndOfStream <> True
    strText = objTextFile.ReadLine
    If Instr(strText, "Reply") > 0 Then
        Wscript.Echo "Reply received."
        Exit Do
    End If
Loop
objTextFile.Close
objFSO.DeleteFile(objTempFile)

Although this approach works, it is somewhat complicated. If you need access to command-line output, you should use the Exec method instead. The following script also parses the output generated by Ping.exe. However, it does so by using the Exec method and by directly reading the output. There is no need to create, open, read, and delete a temporary file, and the script is only 9 lines long, compared with the 15 lines required to perform this same task using the Run method:

Set objShell = WScript.CreateObject("WScript.Shell")
Set objExecObject = objShell.Exec("cmd /c ping -n 3 -w 1000 157.59.0.1")
Do While Not objExecObject.StdOut.AtEndOfStream
    strText = objExecObject.StdOut.ReadLine()
    If Instr(strText, "Reply") > 0 Then
        Wscript.Echo "Reply received."
        Exit Do
    End If
Loop

In many respects, this makes the Exec method a better choice than the Run method. However, the Run method is still useful in a number of situations:

The Run method accepts three parameters. The first and only required parameter is the name of the program you want to run. If the program is in the same folder as the script, or if it is located within the computer path, you need enter only the name (for example, Calc.exe). Otherwise, enter the full path to the program (C:AdminMonitoringDiskSpace.exe).

The second parameter is an integer that indicates the window style with which the program should begin (assuming the program has a window). The window style determines such things as whether a window will be the active window or be maximized. Table 3.9 lists the integers that Run accepts as a second parameter as well as the corresponding the window styles.

For example, the script in Listing 3.15 starts Notepad. In line 1, the script sets the MAXIMIZE_WINDOW constant to 3, which represents an activated and maximized window style. In line 3, the script uses the WshShell Run method to start Notepad, passing it the MAXIMIZE_WINDOW constant so that the program runs in a maximized window.

1 Const MAXIMIZE_WINDOW = 3
2 Set objShell = WScript.CreateObject("WScript.Shell")
3 objShell.Run "notepad.exe", MAXIMIZE_WINDOW

Note

Not all applications respond to the window style options. For example, Control Panel (Control.exe) always opens in the same way, regardless of the window style specified in the script.

The Run method also accepts a Boolean value as a third parameter that determines whether the script pauses until the called program is finished running or instead continues with the next command in the script. If this value is set to False (the default), the Run method simply issues the command to run the program but does not check to ensure that the program actually ran. If the third parameter is set to True, the script will wait for the program to finish running, return the integer exit code provided by the program, and then continue with the next line of the script.

If you set this value to False, you can run multiple programs at the same time; the script will start program A and then immediately start program B, even though program A is still running. This can enable your scripts to complete faster. However, it can also lead to possible problems: For example, what if program B cannot be run until program A has finished? If you are worried about possible “collisions” between programs, set this value to True. In that case, program B will not start until program A has concluded.

For example, this script runs Calculator and then waits until Calculator has been closed before proceeding. If Calculator is never closed, line 3 of this script will never execute:

Set objShell = WScript.CreateObject("WScript.Shell")
objShell.Run("calc.exe"),1,True
Wscript.Echo "Script completed."

Note

WSH keeps track of the specific instance of a program started using Run. For example, suppose you run the preceding script and then manually start a second instance of Calculator. If you close this second instance, the script will not respond. Instead, it will continue to wait until the initial instance of Calculator, the one started using Run, has been closed.

Although both Run and Exec are well suited for running GUI programs from scripts, you are unlikely to call many GUI programs from within a script. After all, the basic idea behind most system administration scripts is to carry out a task without the need for any human intervention. Because GUI applications typically require human intervention, about the best you can do within a script is open the application; you are very limited in what you can do with the application after it has been opened.

This is not true for command-line tools, however. Most command-line tools are designed to run in automated fashion; after they have been started, there is no need for any human intervention. The tools start, perform their appointed task, and then terminate.

Both the Run method and the Exec method can be used to run command-line tools, although in either case you should use a slightly different syntax from the one used to run GUI tools. When you run a command-line tool using either of these methods, you should always preface the tool name with one of the following:

The %comspec% variable is an environment variable that specifies the command-line processor. By using %comspec%, you can create scripts that run on both Windows 98 computers (where the command-line processor is Command.exe) and on Windows 2000 computers (where the command-line processor is named Cmd.exe).

The %comspec% variable is not required; however, it does provide a way for a the command window in which a tool runs to remain on the screen. (By default, a command window opens, the tool runs, and then the command window closes as soon as the tool finishes. This means that you might not have time to view the output generated by that tool.)

Including %comspec% is also the only way to run command-line commands such as dir. This script will not run the dir command. Instead, you will receive an error message stating that dir could not be found. (This is because dir is not a stand-alone tool; there is, for example, no program named dir.exe.)

Set objShell = WScript.CreateObject("WScript.Shell")
objShell.Run("dir"), 1, True

However, this script, which first starts the command interpreter, will run the dir command:

Set objShell = WScript.CreateObject("WScript.Shell")
objShell.Run("%comspec% /K dir"), 1, True

The /k and /c parameters allow you to specify whether the command window will remain open after the script completes or whether it will be closed. If you want the window to remain open so that you can view the script output, use the /k parameter. If you want the window to close (as you might with a logon script), use the /c parameter.

For example, the following script runs the Cacls.exe tool, which, in this instance, displays permission settings for the folder C:Scripts. The script leaves the command window open so that the results can be viewed:

Set objShell = WScript.CreateObject("WScript.Shell")
objShell.Run("%comspec% /K cacls.exe c:scripts"), 1, True

By contrast, this script runs the Sc.exe tool and stops the Alerter service. As soon as the script completes, the command window closes:

Set objShell = WScript.CreateObject("WScript.Shell")
objShell.Run("%comspec% /c sc.exe stop alerter"), 1, True

If a parameter passed to a command-line tool includes a space, that parameter must be enclosed in quotation marks. For example, to use Sc.exe to determine the keyname for the Upload Manager service, you need to use the following syntax:

sc.exe getkeyname "Upload Manager"

To use this same command within a script, you must also include quotation marks around the parameter. However, this is not entirely straightforward. For example, you might try placing quotation marks around Upload Manager, like this:

Set objShell = WScript.CreateObject("WScript.Shell")
objShell.Run("%comspec% /k sc.exe getkeyname "Upload Manager""), 1, True

When you run this script, you do not get the keyname for Upload Manager. Instead, you get the error message shown in Figure 3.11.

Figure 3.11. Incorrectly Specifying the Run Parameter

At first, this error message might seem nonsensical; after all, it says that the script expected to see a right parenthesis, and your code has a right parenthesis. As it turns out, though, the problem lies not with the parentheses but with the quotation marks. WSH correctly sees the first set of quotation marks (the ones right before %comspec%) as marking the start of the command string being passed to the Run method. However, it sees the second set of quotation marks (the ones right before the word Upload) as marking the end of the command string. To WSH, this is the command you are trying to execute:

objShell.Run("%comspec% /k sc.exe getkeyname ""

Because the syntax is not correct (a right parenthesis is required immediately after the second set of quotation marks), the script fails.

Anytime you need to include quotation marks as part of the command string, you must use a pair of quotation marks. For example:

Set objShell = WScript.CreateObject("WScript.Shell")
objShell.Run("%comspec% /k sc.exe getkeyname ""Upload Manager"""), 1, True

In this script:

To run a program and use its output, a script can use the WshShell Exec method. The WshShell Exec method returns a WshScriptExec object that provides access to the program’s standard output, standard input, and standard error streams. Your scripts can retrieve the output that results from running a program by accessing the program’s standard output stream (StdOut).

The script in Listing 3.16 runs the command-line tool, Ipconfig.exe, which retrieves information about the networking configuration of a computer, including the IP address currently assigned to that computer. The script captures the output of the tool and filters it line by line, displaying only lines that include the word Address.

 1 Set objShell = WScript.CreateObject("WScript.Shell")
 2 Set objExecObject = objShell.Exec("%comspec% /c ipconfig.exe")
 3
 4 Do Until objExecObject.StdOut.AtEndOfStream
 5     strLine = objExecObject.StdOut.ReadLine()
 6     strIP = Instr(strLine,"Address")
 7     If strIP <> 0 Then
 8         Wscript.Echo strLine
 9     End If
10 Loop

In line 2 of Listing 3.16, the script uses the Exec method to run the Ipconfig.exe command-line tool. The output generated by Opconfig.exe will be stored in the object reference named objExecObject.

In line 4, the script sets up a loop that will continue until the end of the program’s standard output stream is reached. The script checks for the end of the stream by using the AtEndOfStream property of the StdOut TextStream object.

In line 5, the script reads a line of the program’s output and stores it in the strLine variable.

In line 6, the script uses the VBScript Instr function to determine whether the word Address is stored in strLine. If the word Address is found, the script displays the line using the Echo method on line 8.

When you run Ipconfig.exe, you receive output similar to this:

Windows IP Configuration

Ethernet adapter Local Area Connection 2:

        Connection-specific DNS Suffix . : fabrikam.com
        IP Address. . . . . . . . . . . . : 192.168.248.248
        Subnet Mask . . . . . . . . . . . : 255.255.252.0
        Default Gateway . . . . . . . . . : 192.168.248.1

When you run the preceding script, you receive output only for those lines that contain the word Address:

        IP Address. . . . . . . . . . . . : 192.168.248.248

This enables you to run a command-line tool, check its output, and then have your script proceed accordingly.

Creating a standard shortcut involves three steps:

The script in Listing 3.17 creates a shortcut to the Internet Information Services (IIS) manager on the desktop. The shortcut is visible to all users of the computer and can be opened either by double-clicking it or by using the key combination CTRL+SHIFT+I.

1 Set objShell = WScript.CreateObject("WScript.Shell")
2 strDesktopFolder = objShell.SpecialFolders("AllUsersDesktop")
3 Set objShortCut = objShell.CreateShortcut(strDesktopFolder & _
4     "IIS Manager.lnk")
5 objShortCut.TargetPath = "%SystemRoot%System32Inetsrviis.msc"
6 objShortCut.Description = "Run the Internet Information Services Manager."
7 objShortCut.HotKey = "Ctrl+Shift+I"
8 objShortCut.Save

In line 2 of Listing 3.17, the WshShell SpecialFolders property retrieves the directory path to the Desktop special folder. This path is stored in the strDesktopFolder variable.

In lines 3–4, the CreateShortcut method creates a shortcut file named IISManager.lnk in the Desktop folder.

In lines 5–7, the script sets the TargetPath, Description, and HotKey properties of the WshShortcut object.

In line 8, the script creates the actual shortcut by calling the WshShortcut Save method.

Note

An icon will be created on the desktop even if you do not set any properties, but the icon will not be a functional shortcut; if you double-click it, nothing will happen. (You will not even receive an error message.) To create a functional shortcut, you must set the TargetPath property. If the TargetPath property is not set, double-clicking the shortcut will not do anything.

Creating a URL Shortcut involves three similar steps:

The script in Listing 3.18 creates a shortcut to the MSDN® Web site on the desktop. The shortcut is visible only to users who run the script. This is because the shortcut is created in the Desktop folder for the current user and not in the AllUsersDesktop folder.

1 Set objShell = WScript.CreateObject("WScript.Shell")
2 strDesktopFld = objShell.SpecialFolders("Desktop")
3 Set objURLShortcut = objShell.CreateShortcut(strDesktopFld & "MSDN.url")
4 objURLShortcut.TargetPath = "http://msdn.microsoft.com"
5 objURLShortcut.Save

The script in Listing 3.19 uses a URL shortcut to create a Quick Launch button that opens the Microsoft® TechNet Web site. The Quick Launch button is visible only to users who run the script because the shortcut is created in the personal Quick Launch bar for the user.

1 Set objShell = WScript.CreateObject("WScript.Shell")
2 Set colEnvironmentVariables = objShell.Environment("Volatile")
3
4 strQLFolder = colEnvironmentVariables.Item("APPDATA") & _
5     "MicrosoftInternet ExplorerQuick Launch"
6
7 Set objURLShortcut = objShell.CreateShortcut(strQLFolder & "TechNet.url")
8 objURLShortcut.TargetPath = "http://www.microsoft.com/technet"
9 objURLShortcut.Save

Shortcuts are files that can be deleted in the same way you delete any other file. For example, the following script deletes the shortcut created in Listing 3.18:

Set objShell = WScript.CreateObject("WScript.Shell")
Set colEnvironmentVariables = objShell.Environment("Volatile")
Set objFSO = CreateObject("Scripting.FileSystemObject")

strQLFolder = colEnvironmentVariables.Item("APPDATA") & _
    "MicrosoftInternet ExplorerQuick LaunchTechNet.URL"
objFSO.DeleteFile(strQLFolder)

For more information about working with files in WSH scripts, see “Script Runtime Primer” in this book.

The script in Listing 3.20 determines the location of the Fonts special folder. The script echoes the location of the Fonts folder.

1 Set objShell = WScript.CreateObject("WScript.Shell")
2 strFontDirectoryPath = objShell.SpecialFolders.Item("Fonts")
3 Wscript.Echo "Font Directory Path: " & strFontDirectoryPath

When you install an application, that application often associates itself with a particular file type. For example, when you install the Microsoft® FrontPage® Web site creation and management tool, FrontPage associates itself with all .htm files. If you right-click on a .htm file and click Edit, the file will open in FrontPage.

Of course, there might be times when you simply want to view the .htm file in Notepad. Recognizing this fact, Windows includes a special folder named SendTo. The SendTo option presents a menu of applications or locations to which you can send the selected file. You can add to the options available in the SendTo menu by adding shortcuts to the SendTo special folder. The next time you want to open an .htm file (or any file) in Notepad, you can simply right-click the file, select SendTo, and then click Notepad.

The script in Listing 3.21 creates a shortcut to the Notepad application in the SendTo special folder, thus adding Notepad to the SendTo menu.

1 Set objShell = WScript.CreateObject("WScript.Shell")
2 strSendToFolder = objShell.SpecialFolders("SendTo")
3 strPathToNotepad = objShell.ExpandEnvironmentStrings _
4     ("%SystemRoot%/system32/notepad.exe")
5
6 Set objShortcut = objShell.CreateShortcut(strSendToFolder & _
7     "
otepad.lnk")
8 objShortcut.TargetPath = strPathToNotepad
9 objShortcut.Save

To retrieve a collection of environment variables of a specific type, your script must access the WshShell Environment property and provide a string parameter that represents the desired type of environment variable: system, user, process, or volatile. Your script can then use the resulting WshEnvironment collection to access the values of those environment variables by name.

The environment variables that can be retrieved using WSH are shown in Table 3.13.

The environment variables shown in the preceding table are present on all Windows computers. However, you might also have additional user-specific or computer-specific environment variables, which can also be accessed through a script. If you do not know the names of these variables, you can obtain a complete list of the variables (and their values) by typing set from the command prompt.

The script in Listing 3.22 retrieves both the user-specific and computer-specific PATH environment variables.

1 Set objShell = WScript.CreateObject("WScript.Shell")
2 Set colSystemEnvVars = objShell.Environment("System")
3 Set colUserEnvVars = objShell.Environment("User")
4 Wscript.Echo "Computer-specific PATH Environment Variable"
5 Wscript.Echo colSystemEnvVars("PATH")
6 Wscript.Echo "User-specific PATH Environment Variable"
7 Wscript.Echo colUserEnvVars("PATH")

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

Computer-specific PATH Environment Variable
%SystemRoot%system32;%SystemRoot%;%SystemRoot%system32WBEM;C:Program FilesM
icrosoft.NETFrameworkSDKBin;C:Program FilesMicrosoft Visual Studio.NETVc7
bin;C:Program FilesMicrosoft Visual Studio.NETCommon7IDE;C:WINNTMicrosof
t.NETFrameworkv1.0.2914;C:Program FilesMicrosoft Visual Studio.NETVc7in
;C:Program FilesMicrosoft Visual Studio.NETCommon7IDE;
C:MSSQL7BINN;C:Program FilesSupport Tools;C:Program Files
Resource KitC:PROGRA~1CACommonSCANEN~1;C:PROGRA~1CAeTrustANTIVI~1
User-specific PATH Environment Variable
C:Perlin;C:Perlin;C:Perlin

To create a new environment variable, your script must start with the same first step required for retrieving the values of environment variables: It must obtain a reference to a collection of environment variables of one of the four types (user, system, process, or volatile).

After your script has a reference to the collection corresponding to the type of environment variable being created, it can then store a new string value in the corresponding collection location.

Storing the string value creates the new environment variable. The new index becomes the name of the new environment variable, and the corresponding string becomes its initial value. For example, this line of code creates an environment variable named MyVariable, with the initial value 0:

colUsrEnvVars("MyVariable") = 0

You can write scripts that create process or volatile environment variables, but neither of these types is saved between logons and reboots. You can also create a volatile type, which is stored in the registry and lasts for a logon session; this type of environment variable can be used as a mechanism for communicating information between two scripts that both run during a single logon session. However, you will likely find that creating system or user types is more useful because these environment variables are saved between logon sessions and computer reboots.

The script in Listing 3.23 creates a user environment variable named APP_VARIABLE and sets its initial value to “Installed.” The script then retrieves the value of the new APP_VARIABLE environment variable to confirm that it was created.

1 Set objShell = WScript.CreateObject("WScript.Shell")
2 Set colUsrEnvVars = objShell.Environment("USER")
3 colUsrEnvVars("APP_VARIABLE") = "Installed"
4 Wscript.Echo colUsrEnvVars("APP_VARIABLE")

To modify an environment variable, your script must use steps similar to those used to create a new environment variable. It must obtain a reference to a collection of environment variables of one of the four types (user, system, process, or volatile) and store that reference in a variable.

After your script has a reference to the collection corresponding to the type of environment variable being modified, it can then reference the name of the environment variable to modify and store a string value in the corresponding collection location, overwriting the string previously located in that location.

The script in Listing 3.24 modifies the value of a user-specific environment variable named APP_VARIABLE by changing the value to Upgraded.

1 Set objShell = WScript.CreateObject("WScript.Shell")
2 Set colUsrEnvVars = objShell.Environment("USER")
3 strCurrentValue = colUsrEnvVars("APP_VARIABLE")
4 colUsrEnvVars("APP_VARIABLE") = "Upgraded"
5 Wscript.Echo colUsrEnvVars("APP_VARIABLE")

When constructing environment variables or configuration strings to be used in the registry or elsewhere, you might want to incorporate the current value of an existing environment variable within those variables or strings. For example, if a script needs access to the temporary folder, you need to somehow indicate that, for this user on this computer, the temporary folder can be found in C:Temp.

However, you would not want to hard-code the value of that environment variable in your configuration string, as it might change in the future and your script would no longer be valid. Although the temporary folder might be C:Temp today, there is no reason why that cannot be changed to something else (for example, C:Temporary Folder) tomorrow. Because of that, it is better to use an environment variable to dynamically retrieve the location of the temporary folder rather than hard-coding in the value and hoping that it never changes.

To refer to the value of environment variables within configuration strings, you must use the WshShell ExpandEnvironmentStrings method.

This method accepts, as a parameter, a string with an embedded environment variable name enclosed in percentage symbols (%) and returns a string in which the environment variable name and percentage symbols (%) have been replaced with the value of the corresponding environment variable.

The script in Listing 3.25 shows the difference between echoing the value of an environment variable and echoing the expanded value of an environment variable.

1 Set objShell = WScript.CreateObject("WScript.Shell")
2 Set colEnvVars = objShell.Environment("User")
3 Wscript.Echo "Temporary folder (Unexpanded):"
4 Wscript.Echo colEnvVars("TEMP") & vbCrLf
5 Wscript.Echo "Temporary folder (Expanded)"
6 Wscript.Echo objShell.ExpandEnvironmentStrings("%TEMP%")

When run under Cscript, output similar to the following appears in the command window:

Temporary folder (Unexpanded):
%USERPROFILE%Local SettingsTemp

Temporary folder (Expanded)
C:DOCUME~1kmyerLOCALS~1Temp

The registry is the primary configuration database for the Windows operating system; the ability of an operating system component to run, and to run correctly, often depends on the configuration of one or more settings within the registry.

As a system administrator, you spend a considerable amount of time checking values set within the registry. For example, in the event of computer problems, support personnel will often ask you to verify specific registry settings. This can be done directly, using a tool such as Regedit.exe, or it can be done programmatically, using the WshShell RegRead method.

For the most part, the RegRead method requires you to do just two things: 1) Create an instance of the WScript Shell object and 2) call the RegRead method, specifying the registry entry you wand to read. For example, the version number of the Windows operating system is stored in HKLMSoftwareMicrosoftWindows NTCurrentVersionCurrentVersion. You can retrieve this value by using the following code:

Set objShell = WScript.CreateObject("WScript.Shell")
sngVersion = objShell.RegRead _
    ("HKLMSoftwareMicrosoftWindows NTCurrentVersionCurrentVersion")
Wscript.Echo sngVersion

Registry Data Types

Each value stored in the registry has a particular data type. Table 3.15 lists the subset of registry types that WSH supports and the corresponding VBScript-compatible types into which the RegRead method translates corresponding registry values.

The data types listed in Table 3.15 are the ones most commonly used in the registry. If your script attempts to use the RegRead method to retrieve the value of a registry entry with an unsupported data type, the call will result in an error.

Note

Unfortunately, WSH does not provide a way for you to verify the data type of a registry entry before you attempt to read it. However, you can use WMI to verify data types.

The script in Listing 3.27 uses the RegRead method to read the value of a multistring registry entry. Because this is a multistring value, the information is returned as an array, and a For Each loop is used to report each item in that array.

1 Set objShell = WScript.CreateObject("WScript.Shell")
2 arrValues = objShell.RegRead _
3     ("HKLMSYSTEMCurrentControlSetServicesEventLogSecuritySources")
4 For Each strValue In arrValues
5      Wscript.Echo strValue
6 Next

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

Spooler
Security Account Manager
SC Manager
NetDDE Object
LSA
DS
Security

Your scripts can use the RegWrite method to create a new registry entry or modify an existing one. The RegWrite method accepts three parameters: the registry entry to create or modify, the value to assign to the entry, and (optionally) the data type of the entry.

The script in Listing 3.28 uses the RegWrite method to create a DWORD entry (and set the value to 56) in the registry.

1 Set objShell = WScript.CreateObject("WScript.Shell")
2 objShell.RegWrite "HKCUTestKeyVersion", 56, "REG_DWORD"

Note

The WshShell RegWrite method does not support writing the REG_MULTI_SZ data type.

Your scripts can use the RegDelete method to delete registry subkeys or entries. The RegDelete method accepts a single parameter that specifies the subkey or entry to delete. Deleting a subkey deletes all the entries in that subkey.

The script in Listing 3.29 uses the RegDelete method to delete a DWORD value in the registry.

1 Set objShell = WScript.CreateObject("WScript.Shell")
2 objShell.RegDelete "HKCUTestKeyVersion"

If you run your script under Wscript, you can use Wscript.Echo instead of the WshShellPopup method to display messages in a message box. However, with Wscript.Echo, users can only click the OK button or do nothing. Wscript.Echo does not enable you to present users with multiple choices.

In addition, your script is paused while the Wscript.Echo message is displayed. Only after the user clicks the OK button does the script proceed. In cases where no user acknowledges the message, Wscript.Echo pauses your script indefinitely or until it times out (if a time-out has been set). If you want your script to display messages in GUI message boxes as it progresses, but continue regardless of whether a user clicks the OK button, you cannot use Wscript.Echo.

As shown in Figure 3.14, the message box displayed by Wscript.Echo has a single OK button. The user can either do nothing and keep the script waiting or click the OK button, allowing the script to continue.

Figure 3.14. Message Box Produced by Using Wscript.Echo Under WScript

Note

Unlike Wscript.Echo, the Popup method always displays a message box, regardless of whether a script is running under CScript or WScript.

The script in Listing 3.32 uses the WScript Popup method to create three messages in message boxes, each of which has a single OK button. Each message box will be displayed on the screen for a maximum of 5 seconds. If no one has clicked the OK button after 5 seconds, the message box will automatically dismiss itself from the screen.

1 Const TIMEOUT = 5
2 Set objShell = WScript.CreateObject("WScript.Shell")
3
4 objShell.Popup "Disk Report Complete", TIMEOUT
5 objShell.Popup "Memory Report Complete", TIMEOUT
6 objShell.Popup "CPU Report Complete", TIMEOUT

Timed message boxes are useful in at least two instances. For one, they enable you to provide a sort of graphical progress indicator without interrupting the flow of the script. For example, the script shown in Listing 3.32 can be incorporated within a script that actually generates a disk report, a memory report, and a CPU report.

As each report is completed, you might want to display a message box notifying users of the current status. If this message box were displayed using the Echo method, the message box would remain on the screen, and the script would remain paused until someone clicked OK. With the Popup method, the message remains on the screen either until someone clicks OK or until the time-out period expires. In the preceding script, the message appears — and the script pauses — for no more than 5 seconds before continuing.

Along similar lines, you might want to give users the opportunity to make a decision but, if no decision is immediately forthcoming, allow the script to follow a default course of action. For example, you might have a script that carries out a number of activities and then copies a set of files across the network. Because this copying procedure might take considerable time and bandwidth, you can display a pop-up message box asking the user whether he or she wants to proceed with the copying. The message can could be displayed for a minute or so; if there is no response, the script can automatically begin copying files.

The WshShell Popup method enables you to create message boxes with various sets of buttons and icons. For example, you can create a message box with Yes and No buttons or a message box with the button set Abort, Retry, Ignore. In addition, you can determine which button a user clicked and then take appropriate action based on the user choice. This helps differentiate the Popup method from the Echo method; message boxes displayed using Echo have only an OK button.

You specify both the button set and the icon by providing the Popup method with a fourth parameter. This parameter accepts a combination of predefined constants that specify the button set and the icon the message box should use.

Table 3.17 lists the icons available to use with the Popup method along with their corresponding constants.

Table 3.18 lists the button sets available to use with the Popup method along with their corresponding constants.

Although you can use either the constant names or the constant values within a script, using the constant names makes it much easier to understand the code. For example, it is relatively easy to see that the following line of code creates a pop-up message box with Yes and No buttons. (This message box also has a time-out value of 10 seconds and the title Popup Example.)

objShell.Popup "Stop Icon / Abort, Retry and Ignore Buttons", _
     10, "Popup Example", vbYesNo

To display both an icon and a button set, use two constants (joined by a plus sign) in the code:

objShell.Popup "Stop Icon / Abort, Retry and Ignore Buttons", _
     10, "Popup Example", vbCritical + vbYesNo

The script in Listing 3.33 displays a series of message boxes, each of which has a different icon and button set. If you click any button on a message box, the next message box will be displayed; otherwise, the script displays each message box for five seconds.

 1 Const TIMEOUT = 5
 2 Const POPUP_TITLE = "Icons and Buttons"
 3 Set objShell = WScript.CreateObject("WScript.Shell")
 4 objShell.Popup "Stop Icon / Abort, Retry and Ignore Buttons", _
 5      TIMEOUT,POPUP_TITLE,vbCritical+vbAbortRetryIgnore
 6
 7 objShell.Popup "Question Mark Icon / Yes, No and Cancel Buttons", _
 8      TIMEOUT,POPUP_TITLE,vbQuestion+vbYesNoCancel
 9
10 objShell.Popup "Exclamation Mark Icon / Yes and No Buttons", _
11      TIMEOUT,POPUP_TITLE,vbExclamation+vbYesNo
12
13 objShell.Popup "Information Icon / Retry and Cancel Buttons", _
14      TIMEOUT,POPUP_TITLE,vbInformation+vbRetryCancel

In lines 4–14, the WshShell Popup method is called four times in succession to display pop-up message boxes with various icons and button sets. The third parameter passed to Popup is always the POPUP_TITLE constant and results in each pop-up message box having Icons and Buttons as its title. The fourth parameter is passed various constants representing both the icon and the button set to be used. Note that the constants are combined by using the plus (+) operator.

The WshShell Popup method lets you specify the default button when you create a message box. The default button is the button that has focus and will be chosen if the user presses ENTER.

It is not unusual for users to reflexively press ENTER any time a message box is displayed. Because of that, some care should be taken when choosing the default button. For example, you might choose the button that, 9 times out of 10, users will select anyway. Or you might choose the button that is the “safest” should a user press ENTER without realizing what they are doing. For example, your message box might prompt the user, “Are you sure you want to delete all the files on this hard drive?” In a case such as this, you might want to configure No as the default button. That way, no damage will be done if a user accidentally presses ENTER.

You can specify which button to make the default by adding another constant to the fourth parameter of the Popup method. Table 3.19 lists the constants you can use to set the default button in a message box. If you try to set the second or third button as the default when the message box does not have a second or third button, the default button constant you specify will be ignored and the left button will be set as the default.

The script in Listing 3.34 displays two message boxes in succession. Both message boxes use the Abort, Retry, Ignore button set. The first message box does not specify the default button, so the leftmost button, Abort, is automatically selected as the default. The second message box uses the vbDefaultButton2 constant to make Retry the default button.

1 Const TIMEOUT = 5
2 Set objShell = WScript.CreateObject("WScript.Shell")
3
4 objShell.Popup "Abort, Retry, Ignore. No Default Specified." _
5      ,TIMEOUT,,vbAbortRetryIgnore
6
7 objShell.Popup "Abort, Retry, Ignore. Retry Set as Default." _
8      ,TIMEOUT,,vbAbortRetryIgnore+vbDefaultButton2

One of the advantages of using the Popup method rather than the Echo method is that you can give users the chance to make a choice: Yes, I want to try again; no, I would rather just quit. This means that the script needs to determine which button a user has clicked. The Popup method returns an integer that you can compare with a set of constants to determine which button was clicked. If a message box times out, the Popup method returns –1.

Table 3.20 lists the values you can use to identify which button a user has clicked. If the return value of the Popup method is equal to one of these constants, the user has clicked the associated button. Within a script, you can check either for the value of the constant or for the constant itself. For example, these two lines of code both check to see whether the OK button was clicked:

If intClicked = 1
If intClicked = vbOK

The script in Listing 3.35 displays a message box that uses the Yes, No button set to determine whether the user would like more detailed information.

The script uses the FileSystemObject to present the user with information about the host the script is running under. The script determines and displays the version of the script host file and uses the Popup method to allow the user to decide whether or not they would like to see more details about the file.

 1 Const TIMEOUT = 7
 2 Set objShell = WScript.CreateObject("WScript.Shell")
 3 Set objFS = WScript.CreateObject("Scripting.FileSystemObject")
 4
 5 strPath = Wscript.FullName
 6 strFileVersion = objFS.GetFileVersion(strPath)
 7
 8 iRetVal = objShell.Popup(Wscript.FullName & vbCrLf & _
 9      "File Version: " & _
10      strFileVersion & vbCrLf & _
11      "Would you like more details?" _
12      ,TIMEOUT,"More Info?",vbYesNo + vbQuestion)
13
14 Select Case iRetVal
15     Case vbYes
16         Set objFile = objFS.GetFile(strPath)
17         objShell.Popup WScript.FullName & vbCrLf & vbCrLf & _
18          "File Version: " & strFileVersion & vbCrLf & _
19          "File Size: " & Round((objFile.Size/1024),2) & _
20              " KB" & vbCrLf & _
21              "Date Created: " & objFile.DateCreated & vbCrLf & _
22              "Date Last Modified: " & objFile.DateLastModified & _
23              vbCrLf,TIMEOUT
24         Wscript.Quit
25    Case vbNo
26         Wscript.Quit
27    Case -1
28         WScript.StdOut.WriteLine "Popup timed out."
29         Wscript.Quit
30 End Select

You map a local drive letter to a shared folder using the WshNetwork object’s MapNetworkDrive method. You can use MapNetworkDrive to connect directly to a shared folder or any child folder beneath a shared folder. MapNetworkDrive has two mandatory and three optional arguments, defined in Table 3.22.

The following example demonstrates how MapNetworkDrive can be used in a user’s logon script to connect to two network shares.

Set objNetwork = Wscript.CreateObject("WScript.Network")
objNetwork.MapNetworkDrive "G:", "\atl-fs-01Sales"
objNetwork.MapNetworkDrive "H:", "\atl-fs-01Users$lewjudy"

Drive G is mapped to the Sales share on the file server named atl-fs-01. Drive H is mapped to the user’s home directory located directly beneath the hidden share named Users$ on atl-fs-01.

By default, MapNetworkDrive uses the access token of the current user to validate permissions prior to making the connection; you cannot map a drive to a folder unless you have permission to access that folder. In administrative scripts, it might be necessary to supply an alternate or elevated set of credentials to successfully connect to a share. You can use the optional UserName and Password arguments to supply a set of credentials that are used in lieu of the current user’s access token. After the connection is established, the supplied credentials govern access to the network drive for the duration of the connection.

Two common conditions can cause MapNetworkDrive to fail:

Left unchecked, both conditions can result in run-time errors. To avoid permissions-related or password-related issues, your best defense is to trap and handle the error using VBScript’s On Error Resume Next statement. To handle a local drive letter that is already in use, you can forcibly disconnect the mapped drive or locate and use a different drive letter.

Your scripts can use the RemoveNetworkDrive method to unmap a network drive. If the network drive has a mapping between a local drive letter and the remote UNC path, the method requires the local drive letter as its single parameter.

If the network drive does not have a mapping between a local drive letter and the remote UNC path, the method requires the remote UNC path as its single parameter.

The script in Listing 3.36 unmaps a drive G.

1 Set objNetwork = WScript.CreateObject("Wscript.Network")
2 objNetwork.RemoveNetworkDrive "G:"

In addition to the mandatory parameter that specifies the mapped drive to be removed, the MapNetworkDrive method accepts two additional, optional, parameters:

Your scripts can use the EnumNetworkDrives method to retrieve a list of the current mapped network drives on a computer.

The EnumNetworkDrives method returns a collection that holds pairs of items: network drive local names and their associated UNC names. The collection is zero-indexed; the even-numbered items in the collection are the local drive names, and the odd-numbered items are the associated UNC paths.

A sample network drive collection is shown in Table 3.23. In this sample collection, drive D (index number 0) maps to \atl-fs-01userskmyer (index number 1).

A script can retrieve both pieces of information about each mapped network drive by iterating through the collection returned by EnumNetworkDrives and retrieving two items from the collection during each iteration. An example of this is shown in Listing 3.37.

1 Set objNetwork = WScript.CreateObject("WScript.Network")
2 Set colDrives = objNetwork.EnumNetworkDrives
3 For i = 0 to colDrives.Count-1 Step 2
4    Wscript.Echo colDrives.Item(i) & vbTab & colDrives.Item (i + 1)
5 Next

Two WshNetwork methods enable your scripts to add printer connections: AddWindowsPrinterConnection and AddPrinterConnection.

The AddWindowsPrinterConnection method enables a script to add a Windows-based printer connection (like using the Control Panel Add Printer Wizard), while the AddPrinterConnection method enables a script to add an MS-DOS®-based printer connection.

Adding Windows-based Printer Connections

When used to add a Windows-based printer connection to a Windows NT–based operating system such as Windows 2000, Windows XP, or Windows NT, the AddWindowsPrinterConnection method accepts, as its only required parameter, the UNC path of the printer.

The script in Listing 3.38 adds a connection to the network printer with the UNC path \HRServer01Printer1.

1 Set objNetwork = Wscript.CreateObject("WScript.Network")
2 objNetwork.AddWindowsPrinterConnection "\HRServer01Printer1"

When used to add a Windows-based printer connection to Windows 95, Windows 98, or Windows Me, the AddWindowsPrinterConnection method requires two parameters: the UNC path of the printer and the name of the printer driver (which must already be installed on the computer). In addition, when used with these operating systems, the method accepts a third, optional, parameter that specifies the local port through which the printer should be made available.

Adding MS-DOS-based printer connections

The AddPrinterConnection method enables a script to add an MS-DOS-based printer connection. The method takes two required parameters: the local port through which the printer will be available and the UNC path of the network printer.

The AddPrinterConnection method also lets you add the mapping to the user profile. If you want to do this, set the updateProfile Boolean argument to True. The user name and the password parameters let you connect to the specified printer by using another user’s credentials.

Unlike the AddWindowsPrinterConnection method, the AddPrinterConnection method requires you to specify a port name.

To remove a printer connection, use the RemovePrinterConnection method.

WshNetwork.RemovePrinterConnection(printerName, [forced], [updateProfile])

The first argument identifies the shared printer. The other two optional arguments let you specify:

The RemovePrinterConnection method removes both Windows and MS-DOS-based printer connections. If the printer was connected using AddPrinterConnection, the printerName argument must be the same as the printer’s local port. If the printer was set up using the AddWindowsPrinterConnection method or was added manually through the Add Printer wizard, the printerName argument must be the printer’s UNC name.

For example, this command removes the connection to the printer \atl-ps-01colorprinter.

Set objNetwork = WScript.CreateObject("WScript.Network")
objNetwork.RemovePrinterConnection "\atl-ps-01colorprinter"

To obtain a list of the printers set up on a computer, you use code similar to that used to list the mapped network drives.

You use the EnumPrinterConnections method to obtain a WshCollection object where each network printer is made up of two elements in the collection. The even-positioned item contains the printer’s local name or port. The odd-positioned item contains the UNC name. As shown in Listing 3.39, you can use a For Next loop with the step value 2 to collect all the information you need.

1 Set objNetwork = WScript.CreateObject("WScript.Network")
2 Set colPrinters = objNetwork.EnumPrinterConnections
3 For i = 0 to colPrinters.Count -1 Step 2
4    Wscript.Echo colPrinters.Item(i) & vbTab & colPrinters.Item (i + 1)
5 Next

When run under CScript, output similar to this is displayed in the command window:

LPT1: Art Department Printer
XRX00034716DD75 \atl-prn-xrxplotter
XRX0000AA622E89 \atl-prn-xrxcolorprinter

Many users print documents by clicking the printer icon within their application; in most cases that means that documents are automatically sent to the user’s default printer. By assigning different users different default printers, you can help divide the print load among your print devices and ensure that documents are printed quickly and efficiently.

The SetDefaultPrinter method lets you assign a specific printer the role of the default printer. SetDefaultPrinter uses the following syntax:

WshNetwork.SetDefaultPrinter(printerName)

The printerName parameter is the UNC name of the printer. (If the printer is a local printer, you can also use a port name such as LPT1.) This script sets the printer \atl-ps-01colorprinter as the default:

Set objNetwork = WScript.CreateObject("WScript.Network")
objNetwork.SetDefaultPrinter("\atl-ps-01colorprinter")

The SetDefaultPrinter method cannot retrieve the current default printer.