What's New in WSH 5.6?
When I first glanced at WSH 5.6's new features, I didn't comprehend the full potential of the WshScriptExec object. This object, which is new to version 5.6, provides your scripts with status information about another script that you might have run through the WshShell object's new Exec method. Basically, the Exec method acts as a script-specific clone of the Run method that the same WshShell object exposes.
A unique aspect of WshScriptExec is that it provides access to the child script's StdIn, StdOut, and StdErr streams, giving you an easy way to grab a program's output and errors as well as a way to intervene on the program's input buffer. Also, to grab the output, you no longer need to work with disk files because everything is held in memory in a TextStream object. Let's review methods and properties in further detail.
The WshScriptExec object. You can't explicitly create an instance of the WshScriptExec object; you can obtain it only as the return value of the Exec method. You use the Exec method to run an application in a child command shell. Exec accepts only one argument: the command line that you use to run the script. The command line should appear exactly as it would if you typed it at the command prompt. For example, the code might look like
set shell = _ CreateObject("WScript.Shell")
command = "%comspec% /c dir"
set scriptExec = _ shell.Exec(command)
The WshScriptExec object has a Status property, which returns a value that denotes the status of the execution. Feasible values are WshRunning (0) and WshFinished (1), which mean that the program is still running or has completed, respectively. Typically, the program is free to complete its tasks and terminate as usual. However, the WshScriptExec object also features a Terminate method, which instructs the script engine to kill the process that started with the Exec method. The Terminate method tries two techniques to end the process. The first attempt uses the Windows message that usually quits an application. If this attempt fails (e.g., because the application doesn't have a queue of messages), the Terminate method abruptly terminates the process.
The standard streams. The other properties available on the WshScriptExec object are those that represent the three streams: StdIn, StdOut, and StdErr. A TextStream object (which is part of the Scripting Runtime Library object model) represents each stream.
The StdOut property exposes an object that wraps the write-only standard output channel (i.e., stdout). The stream's content becomes available as read-only text, and you can use the TextStream class's methods and the properties to manipulate the content. For example, the code in Listing 2 runs the Dir command and captures the output as a string. The calling script can't write text to the stdout channel because this functionality is an exclusive privilege of the running application, which is the sole owner of the channel. The StdOut property gives you only the right to read. Note that to read contents out of the stream, you don't need to create or access a disk file.
You can use the StdIn property to pass data to a process that the Exec method starts. The stream represents an alternative way for the process to collect its working data. For the calling script, StdIn is the perfect tool to automatically and silently execute interactive operations such as a logon. Your scripts can't read from StdIn, but the script that calls Exec can write some text to StdIn for the other process to read. For example, the following line of code automatically inserts a password:
se.StdIn.WriteLine password
For all TextStream objects, you can use the method AtEndOfStream to verify that the internal pointer appears at the end of the stream (that is, no more data exists to read or write).
No More Disk Files
Capturing a script's output (or even an application's output) is a common task for which many people have discovered and implemented consolidated approaches. Typically, script capture requires that you deal with disk files—in most cases, disk files created by the redirection symbol. In WSH 5.6, a new object—the WshScriptExec object—lets you obtain the same results in a more elegant and direct way that doesn't require the implicit or explicit manipulation of a disk file.