Controlling How a Script Runs

Microsoft® Windows® 2000 Scripting Guide

When you run a script, the commands in the script are typically executed in the order in which they appear in the script file. There are no pauses in the running of the script, and the script ends only after the last command is completed.

The WScript object provides two properties (Timeout and Interactive) and two methods (Sleep and Quit) that enable you to alter how a script runs. A script can use these properties and methods to cause itself to:

  • Pause for a specified length of time.

  • Immediately stop running.

  • Stop running after a specified length of time.

Pausing a Script

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:

  • Your script must wait for an event to occur before continuing to run.

  • You want your script to periodically check the status of a system parameter (for example, checking processor usage every 10 seconds).

  • Your script is interacting with a user and you want to slow the interaction to a usable speed. For example, when displaying events retrieved from an event log, you might want to insert a pause, giving the user time to read the first event before displaying the next event.

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.

Listing 3.12 Using the Sleep Method to Pause a Script


strComputer = "."
Set objWMIService = GetObject("winmgmts:" _
 & "{impersonationLevel=impersonate}!\\" & strComputer & "\root\cimv2")
Do While True
 Set colDisks = objWMIService.ExecQuery _
 ("SELECT * FROM Win32_LogicalDisk")
 For Each objDisk in colDisks
 Wscript.Echo "DeviceID: " & objDisk.DeviceID 
 Wscript.Echo "Free Disk Space: " & objDisk.FreeSpace
 Wscript.Sleep 300000


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

Quitting a Script

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 "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:


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 "1"
Wscript.Echo "2"
Wscript.Echo "3"
Wscript.Echo "4"
Wscript.Echo "5"
Wscript.Echo "6"

Setting a Time-out Value for a Script

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.

Listing 3.13 Setting the Time-out Value of a Script


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