Downloads
7530.zip

The scoop on the Windows Script file format

Microsoft is busy at work putting the finishing touches on Windows 2000 (Win2K). Similar to other parts of the OS, Windows Scripting Host (WSH) has undergone many improvements. The most significant enhancement is a new file type: the Windows Script (WS) file (with the filename extension .ws). The new file type supports the Extensible Markup Language (XML) and script. This month, I review the changes in WSH 2.0 and explain what you need to know to take advantage of WSH 2.0.

WSH 2.0 includes several new features and improvements: include-file support, multiple script-engine support, tools support, external-constant access, new runtime options, WSH object-model enhancements, and drag-and-drop support. Many of the WSH 2.0 enhancements rely on the XML elements that are part of the new WS file format. Let's look at the XML elements and the WS file in relation to the features in WSH 2.0.

Include Files
Include files provide a simple way to package (in a separate physical file) code that you reuse frequently in other WS scripts. Include files let you create script libraries so that you don't have to recreate identical code in every script you develop.

For example, suppose you have a collection of functions that you commonly use in scripts. Library.vbs in Listing 1, page 168, is a script library that contains a string variable (strMyString), a constant (MY_CONSTANT), and a couple of simple functions (NetworkInfo and ScriptInfo). The strMyString variable contains the text "Includes Rock!", MY_CONSTANT contains the integer value 123, and the two functions return strings. The NetworkInfo function returns information obtained from the properties that the Network object provides, and the ScriptInfo function returns information obtained from the properties that the WScript object exposes.

To access the variables and functions that library.vbs defines, you simply include library.vbs using the XML <script> element and src attribute, as callout A in Listing 2, page 168, shows. The trailing slash (appropriately named the empty-element tag) following the src attribute isn't a typographical error but a shorthand way to specify an XML end tag for empty elements. You can omit the slash and close the <script> element and src attribute by appending the end tag, as callout B in Listing 2 shows.

You can name your common library files whatever you want, and you can specify a Uniform Naming Convention (UNC) path for the src attribute to access include files remotely. To run include.ws, place Listing 1 and Listing 2 in the same working directory and run include.ws from the Win2K command prompt (e.g., C:\tmp> cscript include.ws). If you have WSH 2.0, you'll get the result that Screen 1, page 169, shows.

If you examine include.ws, you'll see that the script consists of a statement that echoes the values of the constant and string variable that library.vbs defines. In addition, the echo statement calls the ScriptInfo function that library.vbs defines. Because ScriptInfo returns a string, the echo statement happily echoes the function's return value.

Only the new XML-based WS file type supports include files. However, to turn your existing VBScript (.vbs), JScript (.js), or other ActiveX script source files into WS files, you need to only add two XML elements and change the file extension.

Multiple Script Engines
Multiple script engine support is a powerful feature that lets you develop one script that uses multiple languages. Why is such a script useful? Let's suppose that you develop all your systems administration scripts in VBScript. You're in desperate need of a particular routine that your company's intranet development team has written. The trouble is that the intranet team wrote the routine in JScript. Using WSH 2.0, you have no worries. You simply copy the JScript routine into your WS file, enclose the routine in the appropriate XML elements, and away you go.

Listing 3, page 168, is a simple script that shows how you can incorporate JScript and VBScript routines into one WS file. Mse.ws uses a JScript routine to create a desktop shortcut to Notepad, then uses a VBScript routine to delete the shortcut 10 seconds later.

Mse.ws begins with the two XML elements you need to create a WS file: and <script>. The first script block is in JScript, so you set the <script> element's language attribute equal to "JScript", as callout A in Listing 3 shows. The JScript code that follows creates a WSH Shell object, calls the Shell's CreateShortcut method to create a Shortcut object, sets the shortcut's properties, and saves the shortcut to the desktop. Then, the XML end-of-script block element closes the JScript block.

Because the second script block is in VBScript, you specify a new script block element and set the language attribute equal to "VBScript", as callout B in Listing 3 shows. Notice that the first statement in the VBScript block calls the Shell object's Popup method using the oShell object created in the JScript block. The Popup-generated dialog box informs the user that the script is preparing to delete the previously created shortcut. After the Popup method's 10-second timeout value expires, the method dismisses the dialog box and the script deletes the shortcut. Then, I use the FileSystemObject to delete the shortcut because the Shortcut object doesn't provide a built-in delete method.

The mechanics behind the WS's ability to use JScript and VBScript routines is quite simple. Recall that the WS file is an XML file. As such, the XML parser first parses the script. As the XML parser encounters script blocks, the parser passes the blocks of script to the appropriate interpreter based on what language attribute you set the XML <script> element to. For WS files, the design makes jumping between ActiveX scripting engines easy. And as mse.ws demonstrates with the oShell and strDesktopPath variables, you can share common variables between the different languages.

Tools Support
What new technology would be complete without a feature that makes you say, "Wow"? For WSH 2.0, this feature is the new tools support. If you're trying to get up to speed on WSH but find that learning all the objects, methods, and properties is difficult, the tools support will be very beneficial. The new tools support in WSH 2.0 includes features that Visual Basic (VB) programmers have grown accustomed to over the years and can't function without, such as IntelliSense and two enhanced WSH development environments.

The most powerful tools feature is IntelliSense. During the development process, the IntelliSense feature provides an easy way to examine and select the methods and properties that an object exposes. For example, using Microsoft Visual InterDev 6.0, IntelliSense's List Members pop-up (select List Members from the Edit menu or press Ctrl+J) displays the methods and properties that an object provides. After selecting an object's method, IntelliSense will provide a pop-up displaying Parameter Info for the object's method. The Parameter Info pop-up saves you from having to look up the parameters for methods and functions. You can select the Parameter Info pop-up from the Edit menu, or you can press Ctrl+Shift+I.

This level of tools support for editing and debugging scripts is available in two WSH development environments: Visual InterDev 6.0 and the new Microsoft Script Editor. Microsoft introduced the Microsoft Script Editor in Office 2000. To access the new editor from the Office 2000 versions of Microsoft Excel, Word, or PowerPoint, click Tools from the main menu, select Macro, then select Microsoft Script Editor. These enhanced development environments are certain to make WSH scripting easier.

External Constants
In "Scripting 101, Part 2," July 1999, I discussed constants and noted that you couldn't access constants defined in objects outside of VBScript. Now, WSH 2.0 provides this ability. The WS file XML element lets you reference external type libraries to gain access to the constants that external objects define. In Listing 4, refs.ws uses the XML element to access constants defined in the FileSystemObject.

Callout A in Listing 4 shows how the XML element uses the object attribute in conjunction with a programmatic identifier (ProgID) to identify the object that the element derives the type library from. The ProgID uses the same construct that WScript's and VBScript's CreateObject function uses. (For more information about creating objects and ProgIDs, see "Scripting 101, Part 3," August 1999.) Alternatively, the XML element accepts a guid attribute in conjunction with the object's globally unique ID (GUID). After setting the object or guid attribute, you can access the referenced object's constants as the WScript.Echo statement demonstrates. As Screen 2 shows, the echo statement displays the values for the FileSystemObject's DriveType constants.

New Runtime Options
In addition to the existing command-line options, WSH 2.0 supports four new options: //D, //X, //E:Engine, and //Job:xxxx. The //D option launches the Microsoft Script Debugger and enables Active Debugging in the event your script encounters a runtime error. The debugger highlights the line of code responsible for the error. To manually load and execute the script in the Microsoft Script Debugger, you use the //X option.

The //E:Engine option lets you specify the script engine to use to execute your script. This option is primarily for testing purposes. If you want to test existing code before upgrading to a newer script engine, you can use the //E:Engine option.

The //Job:xxxx option executes a specific WS job contained in a WS package. In Listing 5, jobs.ws contains two jobs. You must define multiple jobs inside a package that you define using the XML element, as callout A in Listing 5 shows. Each job you define within the package must have a unique ID. The //Job:xxxx option uses the XML element's id attribute to provide the ID. The id attributes for the two jobs defined in jobs.ws are "One" and "Two". By default, the first job in the package runs if no job is specified using the //Job:xxxx option. To run a specific job, you identify the target job using the //Job:xxxx option. For example, you can issue the command C:\tmp> cscript //job:two jobs.ws to run job "Two" in jobs.ws. This command will echo the string "Job Two" on the console.

You can use the //Job:xxxx option along with the new ability to define multiple jobs in a WS file. As the //Job:xxxx option shows, WSH's new options add scripting flexibility.

Object Model Enhancements
Microsoft made numerous improvements to the WSH object model. Microsoft added new methods and properties to the three core WSH objects: WScript, Network, and Shell.

The WScript object exposes the new Sleep method, which provides the ability to pause a script for n milliseconds. In addition, the WScript object exposes STDIN, STDOUT, and STDERR. These properties address STDIO support, which WSH 1.0 lacked. Because WSH now supports STDIO, you can use pipes between commands and scripts, and you can perform input and output via the console. Note that STDIO support is available on scripts run with cscript.exe only. (The runtime's FileSystemObject implements STDIN, STDOUT, and STDERR. The developer implemented STDIO in the FileSystemObject to reuse the implementation that the TextStream object already provided. As such, the STDIO streams support the same methods and properties as those that the TextStream object provides--­e.g., Close, Read, ReadAll, ReadLine, Skip, SkipLine, Write, WriteLine, WriteBlankLines, AtEndOfLine, AtEndOfStream, Column, Line. WScript acts as a facade to the three STDIO streams for simplicity and ease of use.)

The Network object exposes the new AddWindowsPrinterConnection method. This method addresses the lack of support for Windows-based printer connections in WSH 1.0's AddPrinterConnection method.

The Shell object exposes the new LogEvent method (which writes an event to the Win2K application log), the AppActivate method, and the SendKeys method. The AppActivate method changes the focus to a named window, and the SendKeys method sends keystrokes to the active window. The AppActivate method complements the new SendKeys method (i.e., you use AppActivate to set the active window). So, the AppActivate method provides a mechanism to set the target application in focus before firing SendKeys. Together, AppActivate and SendKeys are an attempt to eliminate the need for utilities such as ScriptIt.

Microsoft also improved the FileSystemObject. In WSH 2.0, the FileSystemObject exposes the GetFileVersion method to return the version information for a file. For more information about the methods and properties in WSH 2.0 and to obtain the WSH 2.0 documentation, see the Microsoft Windows Script Technologies Web site at http://msdn.microsoft.com/scripting/windowshost/beta. You can view the Windows Scripting Host 2.0 Reference and the Windows Scripting Host Version 2.0 Tutorial online, or download the compiled 32-bit HTML file (wsh-doc.exe).

Drag-and-Drop Support
Last, but certainly not least, is support for the drag-and-drop feature. You can use the new drag-and-drop feature in WSH 2.0 in a couple of ways. You can drag a group of files to a WS file to automatically add the filenames to the script's Arguments collection, or you can drag one or more computers from Win2K's My Network Places on the desktop to a WS file to automatically run the script on the selected computers. As with the other enhancements, the drag-and-drop support shows that big improvements can come in small packages.

XML Elements
WSH 2.0 adds many features to make development easier. But many of these features require the new XML-based WS file format for support. To take advantage of these features, you need to learn the syntax and hierarchical structure of XML elements. Then, you can create a template to use for new WS source files. You can also migrate your existing JScript and VBScript files to WS files and take advantage of WSH 2.0's enhancements.