In any piece of interpreted or compiled software, the output is all that really matters. Some programs return output on the command line, whereas others condense output into a disk file in a certain directory. Other programs let the user grab and process results when necessary. For the most part, the application model and platform determine a program's behavior. Traditional GUI programs (e.g., Windows programs) display their output through windows and controls.
Scripts fall into another category of applications that mostly concern administrators and power users. Although scripts are powerful, they follow a simple, basic schema. Rather than relying on visual tools such as windows, dialog boxes, and controls, scripts are usually limited to the set of features that the language in use provides. For example, certain OS scripts, even in a GUI-centric OS such as Windows, are limited in their UI options. Windows Script Host (WSH) and VBScript are significant exceptions because they let you plug into many COM components to accomplish a variety of otherwise impossible tasks.
The model for script applications is based on the black-box model: The input data enters one end, then comes out properly transformed at the other end. A script's input channels are the read-only input console stream and the list of command-line arguments. A script's output channel is the output stream in which the code writes the results. Like many Windows GUI applications, scripts don't always provide text that represents output.
The ability to capture a script's output is a common need for users whose job involves repetitive administrative tasks. Let's review the common techniques you might use for such tasks, then take a look at some new techniques that WSH 5.6 offers.
Output Redirection
Any OS can take any text that a given script sends to its standard I/O console and automatically redirect it to a particular device. From the script's perspective, the output stream is a virtual device that the underlying OS can map from time to time to a different physical device (e.g., a printer, the screen, a file). To achieve redirection, MS-DOS supplies an old acquaintance—the redirection operator (>)—which a generation of system users cut their teeth on.
To redirect to a file named output.txt every byte that a program (not necessarily a batch file or a script) dumps out to the standard I/O console, you would use the code
myprogram.exe >output.txt
If you want to know details about a given folder's contents, you typically open your MS-DOS console box and type the Dir command. Alternatively, you can launch Windows Explorer and read through the lengthy list of files and subdirectories. If the list of items is particularly long and you need to check the items individually, both of these solutions are of little help. When I recently faced a similar problem, I rediscovered the effective simplicity of redirection. The following command writes the typical output of the Dir command into a text file:
dir >output.txt
Redirection isn't rocket science, but it is a useful resource if you need more than a glance to solve a file-related problem. This simple command provides a text-based list of files that you can format, print, and refer to.
The redirection operator turns a script's output into a data item that other software can use for further operations. For example, redirection can help you get rid of the introductory text that the Dir command generates. Listing 1 is a WSH script that runs the Dir command, redirects the output to a file, then reads it back, removing the Dir command's typical heading, such as
Volume in drive C has no label.
Volume Serial Number is 1CC4-3870
Directory of C:
07/02/2002 03:58p <DIR>
To run the Dir command through the WSH shell, use the OS-specific command-shell executable (e.g., cmd.exe), whose full path resides in the %comspec% environment variable, as callout A in Listing 1 shows. The /c switch after the %comspec% variable opens the command-shell window, then closes it on completion of the Dir command.
The Dir command's output is redirected to the file called output.txt. To remove the unwanted introductory text, the script then opens output.txt and reads the output into a string variable, OutputString. At this point, the command's entire output is in memory as a string. After deleting the original file (i.e., output.txt), the script extracts only the characters that follow the ".." expression—in other words, the actual file listing.
Error Redirection
The redirection technique is useful for capturing and using as a string any output that scripts—and executables in general—send through the standard output console. Redirection is always possible regardless of whether the program is GUI-centric or console-based. Any Windows or non-Windows program can always send text to the output console or read from it. When I discovered that the Win32 API includes low-level functions that specifically allow such freedom, I recompiled an old 32-bit GUI program that I now use throughout my company to generate input for many scripts. Before this discovery, I used the 32-bit GUI program to create a text file in a network share that scripts accessed and read. By simply adding a couple of new API calls in the code, I now can inject into the output console the same text destined to disk, thereby eliminating the need for scripts to access a file remotely. Each script can now create the dump locally.
I implemented another significant improvement later when I decided to redirect the error messages of both the executables and scripts to a separate file. With little effort, I created a simple but effective journal of errors. Again, this improvement required no advanced logic, but it's an effective piece of functionality. The following code redirects all error messages to a file called errors.txt:
myprogram.exe 2>errors.txt
To successfully implement this error redirection, the application must be designed to send its errors on the standard error output console, whose order number is set to 2.