Copyright: 1992-1997


Windows Scripting Host Programmer's Reference

The following information is presented in this programmer's reference:

•	About Windows® Scripting Host

•	Using Windows Scripting Host

•	Windows Scripting Host Object Reference


About Windows Scripting Host

The Microsoft® Windows® Scripting Host is a language-independent scripting host for ActiveX™ scripting engines on 32-bit Windows platforms. Windows Scripting Host will be integrated into Windows® 98, Windows NT® Workstation version 5.0, and Windows NT Server version 5.0.

Both Microsoft® Visual Basic® Scripting Edition (VBScript) and Microsoft® JScript™ scripting engines are provided with Windows Scripting Host. Other software companies will provide ActiveX™ scripting engines for languages such as Perl, TCL, REXX, Python, and others.

Windows Scripting Host can be run from either the Windows-based host (Wscript.exe), or the command-shell-based host (Cscript.exe).


ActiveX Scripting Hosts

ActiveX scripting architecture supports powerful scripting using languages such as VBScript, JScript, Perl, and others. Microsoft currently provides three hosts for running these scripting languages across the Windows platform:

•	Microsoft® Internet Explorer. Internet Explorer can execute scripts on client computers from within HTML pages.

•	Internet Information Server (IIS). IIS supports Active Server Pages, so scripts can run on Web servers. In other words, IIS supports server-side scripting over the Internet or an intranet.

•	Windows Scripting Host. Windows Scripting Host provides a low-memory scripting host so scripts can execute directly on the Windows desktop or Command Prompt window; the scripts do not need to be embedded in an HTML document. Windows Scripting Host is an ideal host for non-interactive scripts that perform logon and administrative tasks.


Overview of the Windows Scripting Host Object Model

The Windows Scripting Host object model provides two main categories of ActiveX interfaces:

1.	Script execution and troubleshooting: Properties and methods that are directly related to script execution. This set of interfaces allows scripts to manipulate Windows Scripting Host, display messages on the screen, and perform basic functions such as CreateObject and GetObject.

2.	Helper functions: Properties and methods that map network drives, connect to printers, retrieve and modify environment variables, and manipulate registry keys. These functions are provided so administrators can use Windows Scripting Host to create simple logon scripts.

In addition to the object interfaces provided by Windows Scripting Host, administrators can use any ActiveX controls that expose Automation interfaces to perform various tasks on the Windows platform. For example, administrators can write scripts that use the Active Directory to manage the Windows NT Directory Service.


Using Windows Scripting Host

The following section describes how you can use Windows® Scripting Host.


Writing a Scripting Engine for Windows Scripting Host

The principal requirement for a third-party scripting engine is that it support the ActiveX™ IActiveScriptParse COM interface.

A scripting engine can also call Wshom.ocx, an ActiveX control that supports the IDispatch COM interface. If the scripting engine supports ActiveX control creation in a script, Wshom.ocx can be called from within the script.

If the scripting engine itself calls Wshom.ocx, you should obtain Iwshom.idl, Iwshom.h and Iwshom.iid from the Platform SDK. With these files, you can call methods in Wshom.ocx using the normal COM calling sequence. Wshom.ocx supports a dual interface, aggregation, and the IErrorInfo COM interface.

Example

#include <IWSHom.h>

HRESULT

Use_WSHShell() {

    HRESULT hr;

    IWSHShell* pShell;

    hr = ::CoCreateInstance(CLSID_IWSHShell,

                       NULL,

                       CTX_INPROCSERVER,

                       IID_IWSHShell,

                       (LPVOID*) &pShell );

    if (FAILED(hr)) return hr;

    hr = pShell->Run(bstrCommand,

 &varWindowStyle,

 &varWaitOnReturn,

               &nExitCode );

    pShell->Release();

    return hr;

}


How Windows Scripting Host Uses the Registry

An ActiveX scripting engine is registered for use with Windows Scripting Host by adding registry entries under the HKEY_CURRENT_USER (HKCU) key. Windows Scripting Host determines which scripting engine to use to execute a script by examining the ScriptEngine key. For example, if a user types the following command in a Command Prompt window:

cscript chart.vbs

To look up the scripting engine for the Chart.vbs file, Windows Scripting Host:

1.	Searches HKCU\.vbs to obtain a script identifier, such as VBSfile.

2.	Searches HKCU\VBSFile\ScriptEngine to get a scripting engine identifier, such as VBScript.

3.	Finds the CLSID from the scripting engine identifier; in this example, the CLSID is located in HKCU\VBScript\CLSID.

4.	Calls CoCreateInstance with the CLSID and IUnknown.

5.	Calls QueryInterface to get the IActiveScriptParse COM interface.


Registering a Scripting Engine for Windows Scripting Host

If you have written an ActiveX scripting engine with the following characteristics:

•	The scripting engine identifier is MyScriptLanguage.

•	The file extension for scripts is .msl.

•	The script identifier is MyScriptFile.

The following table shows the registry entries that are necessary to register this engine (none of these has a value name).

For Windows 98, use REG_SZ instead of REG_EXPAND_SZ and change the path of Wscript.exe and Cscript.exe as shown in the following table.

	Windows NT	Windows 98
Wscript	%SystemRoot%\System32\Wscript.exe	C:\Windows\Wscript.exe
Cscript	%SystemRoot%\System32\Cscript.exe	C:\Windows\Command\Cscript.exe


Running Scripts Using Wscript.Exe

Using Wscript.exe, you can run scripts under Windows in two ways:

•	Double-clicking files or icons. These can be files or icons listed in My Computer, Explorer, the Find window, the Start menu, or on the Desktop.

•	Using the Windows Run command to start Wscript.exe.

When you run scripts from Wscript.exe, you can select the Always Use the Windows Scripting Host to open this file check box and set properties on the WSH Properties page.

When you select the Always Use the Windows Scripting Host to open this file check box, Wscript.exe is registered as the default application to run files with a given extension. For example, if you select this check box when you run Chart.vbs, Wscript.exe becomes the default application for all files with the .vbs extension. This check box functions the same as the Cscript.exe //C switch.

The WSH Properties page provides the options shown in the following table.

Property	Function	CSCRIPT equivalent
Stop script after nn seconds	Specifies a maximum number of seconds that a script can run (the default is no limit).	//T:nn
By default, run scripts in Interactive or Batch mode	Suppresses or enables all user interface requests from the script other than those issued at the command line in a Command Prompt window. Interactive mode allows all user-interface requests, while Batch mode allows only command-line user-interface requests.


Running Scripts Using Cscript.exe

To use Cscript.exe, open a Command Prompt window and type a Cscript command line. CScript uses the following syntax:

cscript [host options...] [script name] [script options]

•	Host options enable or disable various Windows Scripting Host features. Host options are always preceeded by two slashes (//).

•	Script name is the name of the script file; for example, Chart.vbs.

•	Script options are passed to the script. Script parameters are always preceeded by only one slash (/).

Each parameter is optional; however, you cannot specify script options without specifying a script name. If you do not specify parameters, Cscript displays the Cscript syntax and the valid host parameters.

Cscript.exe supports the host parameters shown in the following table.

Parameter	Description
//T:nn	Enables time-out: the maximum number of seconds the script can run. The default is no limit. (See the text following this table for more information on this parameter.)
//logo	Displays a banner (default; opposite of //noLogo).
//nologo	Prevents display of an execution banner at run time.
//S	Saves the current command-line options for this user.
//?	Shows command usage (same as with parameters).
The //T parameter prevents excessive execution of scripts; it does this by setting a timer. When execution time exceeds the specified value, Cscript interrupts the scripting engine using the IActiveScript::InterruptThread method and terminates the process.


Document Conventions

Variable prefixes in parameter listings and code examples have the following meanings.

Prefix	Description
any	Any type
b	Boolean
int	Integer
nat	Natural number or nonnegative integer
obj	Object (Idispatch interface)
str	String
Scripting examples are written in the Microsoft® Visual Basic® Scripting Edition (VBScript).

Methods written in Microsoft Jscript™ are case-sensitive. In general, you should use the same case as the syntax examples shown in this document.

Parameters in brackets (for example, [anyValue]) are optional.


Windows Scripting Host Object Reference

Objects provided by Wscript.exe

Wscript	Exposed to scripting engine as "Wscript"
WshArguments	Not exposed; accessed through the Wscript.Arguments property.
Objects provided by WSHom.Ocx

WshShell	Automation object,  ProgID "Wscript.WshShell".
WshNetwork	Automation object, ProgID "Wscript.WshNetwork".
WshShortcut	Not exposed; accessed through WshShell.CreateShortcut method.
WshUrlShortcut	Not exposed; accessed through WshShell.CreateShortcut method .
WshCollection	Not exposed; accessed through WshNetwork.EnumNetworkDrives or WshNetwork.EnumPrinterConnection.
WshEnvironment	Not exposed; accessed through WshShell.Environment property.
WshSpecialFolders	Not exposed; accessed through  WshShell.Folder property.


Wscript Object

ProgID	N/A
Filename	Wscript.exe or Cscript.exe
CLSID	60254CA2-953b-11CF-8C96-00AA00B8708C
IID	60254CA1-953b-11CF-8C96-00AA00B8708C
The following table describes the properties associated with the Wscript object.

Property	Description
Application	The IDispatch interface for Wscript.
Arguments	A parameters collection object.
FullName	Full path to the host executable.
Name	Friendly name of Wscript (the default property).
Path	Name of the directory where Wscript.exe or Cscript.exe resides.
ScriptFullName	Full path to the script being run by the Windows Scripting Host.
ScriptName	File name of the script being run by the Windows Scripting Host.
Version	A version string for the Windows Scripting Host.
The following table describes the methods associated with the Wscript object.

Method	Description
CreateObject	Creates an object and establishes its event handling.
DisconnectObject	Disconnects a previously connected object from Windows Scripting Host.
Echo	Displays parameters in window or at a command prompt in a Command Prompt window.
GetObject	Retrieves an Automation object from a file.
Quit	Quits execution with a specified error code.


Wscript.Application

[This is preliminary documentation and subject to change.]

The Application property provides the IDispatch interface on the Wscript object.

Syntax

Wscript.Application = objWscript


Wscript.Arguments

[This is preliminary documentation and subject to change.]

The Arguments property provides a WshArguments collection object.

Syntax

Wscript.Arguments = objArguments

Example

' Display all command-line parameters

Set objArgs = Wscript.Arguments

For I = 0 to objArgs.Count - 1

          Wscript.Echo objArgs(I)

Next


Wscript.FullName

[This is preliminary documentation and subject to change.]

The FullName property provides a string containing the full path to the host executable.

Syntax

Wscript.FullName = strFullName

Example

Wscript.FullName = C:\WinNT\System32\wscript.exe

See Also

Wscript.Path property.


Wscript.Name

[This is preliminary documentation and subject to change.]

The Name property provides a string containing the friendly name of the Wscript object. This is the default property.

Syntax

Wscript.Name = strName

Example

Wscript.Name = Windows Scripting Host

Wscript = Windows Scripting Host


Wscript.Path

[This is preliminary documentation and subject to change.]

The Wscript.Path property provides a string containing the name of the directory where Wscript.Exe or Cscript.Exe reside.

Syntax

Wscript.Path  = strPath

Example

Wscript.Path = C:\WinNT\System32

See Also

Wscript.FullName property


Wscript.ScriptFullName

[This is preliminary documentation and subject to change.]

The ScriptFullName property provides the full path to the script being run by the Windows Scripting Host.

Syntax

Wscript.ScriptFullName = strScriptFullName

Example

Wscript.ScriptFullName = C:\Users\Default\WSH\Sample.VBS

See Also

Wscript.ScriptName property


Wscript.ScriptName

[This is preliminary documentation and subject to change.]

The ScriptName property provides the file name of the script being run by the Windows Scripting Host.

Syntax

Wscript.ScriptName = strScriptName

Example

Wscript.ScriptName = Sample.VBS

See Also

Wscript.ScriptFullName property


Wscript.Version

[This is preliminary documentation and subject to change.]

The Version property provides a version string for the Windows Scripting Host.

Syntax

Wscript.Version = strVersion

Example

Wscript.Version = 5.0


Wscript.CreateObject

[This is preliminary documentation and subject to change.]

The CreateObject method creates an object specified by the strProgID parameter. If the parameter strPrefix is specified, Windows Scripting Host connects the object's outgoing interface to the script file after creating the object. When the object fires an event, Windows Scripting Host calls a subroutine named strPrefix and the event name.

For example, if strPrefix is "MYOBJ_" and the object fires an event named "OnBegin", Windows Scripting Host calls the "MYOBJ_OnBegin" subroutine located in the script.

Syntax

Wscript.CreateObject(strProgID, [strPrefix]) = objObject

See Also

Wscript.GetObject method, Wscript.DisconnectObject method


Wscript.DisconnectObject

[This is preliminary documentation and subject to change.]

The DisconnectObject method disconnects a previously connected object (obj) from Windows Scripting Host. If the specified object is not already connected to Windows Scripting Host, this method does nothing.

Syntax

Wscript.DisconnectObject obj

Example

' This code fragment instantiates a fictitious object and

' connects it to the script file. The script then calls the

' "SomeMethod" method on the object.

' If an error called "Event" occurs in the object, then the

' MyEvent_Event subroutine is called.

Set MyObject = Wscript.CreateObject("SomeObject", "MyEvent")

MyObject.SomeMethod

Sub MyEvent_Event(strName)

        Wscript.Echo strName

End Sub

' When done with the object, disconnect it from the script

' and then set it to Nothing

Wscript.DisconnectObject MyObject

Set MyObject = Nothing

See Also

Wscript.CreateObject method, Wscript.GetObject method


Wscript.Echo

[This is preliminary documentation and subject to change.]

The Echo method displays parameters in a window (in Wscript.exe) or at the command prompt in a Command Prompt window (in Cscript.exe).

Parameters are delimited by one space. Under Cscript.exe, this method outputs a carriage-return/line feed pair (CR LF) after the last parameter displayed.

Syntax

Wscript.Echo [anyArg...]

Example

Wscript.Echo

Wscript.Echo 1, 2, 3

Wscript.Echo "Windows Scripting Host is cool."


Wscript.GetObject

[This is preliminary documentation and subject to change.]

The GetObject method retrieves an Automation object from a file, or an object specified by strProgID parameter. Use the GetObject method when there is a current instance of the object, or if you want to create the object from a file that is already loaded. If there is no current instance and you don't want the object started from a file that is already loaded, use the CreateObject method.

Syntax

Wscript.GetObject(strPathname [,strProgID] ], [strPrefix]) = objObject

Parameters

strPathname

The full path and the name of the file containing the object to retrieve.  The parameter strPathname is required

strProgID

A string representing the program identifier (ProgID) of the object.

strPrefix

If the parameter strPrefix is specified, Windows Scripting Host connects the object's outgoing interface to the script file after creating object. When the object fires an event, Windows Scripting Host calls a subroutine named strPrefix and the event name.

For example, if strPrefix is "MYOBJ_" and the object fire an event named "OnBegin", Windows Scripting Host calls the "MYOBJ_OnBegin" subroutine located in the script.

Return

objObject

The Automation object retrieved.

Remarks

If an object has registered itself as a single-instance object (for example, the Word.Basic object in Microsoft Word 7.0), only one instance of the object is created, no matter how many times CreateObject is executed. In addition, with a single-instance object, GetObject always returns the same instance when called with the zero-length string syntax (""), and it causes an error if the path parameter is omitted. You can't use GetObject to obtain a reference to a Visual Basic® class created with Visual Basic 4.0 or earlier.

GetObject works will all COM classes, independent of the language used to create the object.

Examples

Dim MyObject As Object

    Set MyObject = GetObject(""C:\CAD\SCHEMA.CAD"")

    = MyCAD.Application

When this code is executed, the application associated with the specified strPathname is started, and the object in the specified file is activated.

If strPathname is a zero-length string (""), GetObject returns a new object instance of the specified type. If the strPathname parameter is omitted entirely, GetObject returns a currently active object of the specified type. If no object of the specified type exists, an error occurs.

Some applications allow you to activate part of a file. To do this, add an exclamation point (!) to the end of the file name and follow it with a string that identifies the part of the file you want to activate. For information on how to create this string, see the documentation for the application that created the object. For example, in a drawing application you might have multiple layers to a drawing stored in a file. You could use the following code to activate a layer within a drawing file called schema.cad:

Set LayerObject = GetObject("C:\CAD\SCHEMA.CAD!Layer3")

If you do not specify the object's class, COM determines the application to start and the object to activate according to the file name you provide. Some files however, may support more than one class of object. For example, a drawing might support three different types of objects: an application object, a drawing object, and a toolbar object, all of which are part of the same file. To specify which object in a file you want to activate, use the optional class parameter. For example:

Dim MyObject As Object

Set MyObject = GetObject("C:\DRAWINGS\SAMPLE.DRW", "FIGMENT.DRAWING")

In the above example, FIGMENT is the name of a drawing application and DRAWING is one of the object types it supports.

Once an object is activated, you reference it in code using the object variable you defined. In the above example, you access properties and methods of the new object using the object variable MyObject. For example:

MyObject.Line 9, 90

MyObject.InsertText 9, 100, "Hello, world."

MyObject.SaveAs "C:\DRAWINGS\SAMPLE.DRW"

See Also

Wscript.CreateObject method, Wscript.DisconnectObject method


Wscript.Quit

[This is preliminary documentation and subject to change.]

The Quit method quits execution with a specified error code.

Syntax

Wscript.Quit [intErrorCode]

Parameters

intErrorCode

If this parameter is included, Wscript returns it as the process exit code. Otherwise, if intErrorCode is omitted, Wscript returns zero (0) as the process exit code.

Example

Wscript.Quit(1)


WshArguments Object

This object is not exposed directly; access it using the Wscript.Arguments property

ProgID	N/A
Filename	Wscript.Exe or Cscript.Exe
CLSID	60254CA4-953b-11CF-8C96-00AA00B8708C
IID	60254CA3-953b-11CF-8C96-00AA00B8708C
The following table describes the properties associated with the WshArguments object.

Property	Description
Item	The nth command-line parameter (the default property).
Count	The number of command-line parameters.
length	The number of command-line parameters (JScript).


WshArguments.Item

[This is preliminary documentation and subject to change.]

The Item property contains the natIndexth command-line parameter as a string. It is the default property.

Syntax

Arguments(natIndex)

Arguments.Item(natIndex) = strArgument

Example

Set oArgs = Wscript.Arguments.

Wscript.Echo oArgs(0)

Wscript.Echo oArgs.Item(0)

See Also

Wscript.Arguments property


WshArguments.Count

[This is preliminary documentation and subject to change.]

The Count property provides the number of command-line parameters.

Syntax

Arguments.Count = natNumberOfArguments

See Also

Wscript.Arguments property, WshArguments.length property


WshArguments.length

[This is preliminary documentation and subject to change.]

The length property provides the number of command-line parameters. This property provides the same functionality as the Count property and is provided for Microsoft JScript™ compatibility

Syntax

Arguments.length = natNumberOfArguments

See Also

Wscript.Arguments property, WshArguments.Count property


WshShell Object

[This is preliminary documentation and subject to change.]

ProgID	Wscript.WshShell
Filename	WSHom.Ocx
CLSID	F935DC22-1CF0-11d0-ADB9-00C04FD58A0B
IID	F935DC21-1CF0-11d0-ADB9-00C04FD58A0B
The following table describes the properties associated with the WshShell object.

Property	Description
Environment	Returns the WshEnvironment collection object.
SpecialFolders	Provides access to Windows shell folders such as the desktop folder, start menu folder, and personal document folder, using the WshSpecialFolders object .
The following table describes the methods associated with the WshShell object.

Method	Description
CreateShortcut	Creates a WshShortcut object and returns it.
ExpandEnvironmentStrings	Expands a PROCESS environment variable and returns the result string.
Popup	Pops up a message box window containing a specified message.
RegDelete	Deletes, from the registry, a specified key or value.
RegRead	Returns a specified key or value from the registry.
RegWrite	Sets a specified key or value in the registry.
Run	Creates a new process that executes a specified command with a specified window style.


WshShell.Environment

[This is preliminary documentation and subject to change.]

The Environment property returns the WshEnvironment object.

Syntax

WshShell.Environment ( [strType]) = objWshEnvironment

Remarks

If strType specifies where the environment variable resides, possible values are "System", "User", "Volatile", and "Process". If strType is not supplied, this method retrieves the system environment variables in Windows NT or the process environment variables in Windows 95.

For Windows 95, only "Process" is supported in the strType parameter.

The following variables are provided with the Windows operating system. Scripts can also get environment variables that were set by other applications.

Name	Description
NUMBER_OF_PROCESSORS	Number of processors running on the machine
PROCESSOR_ARCHITECTURE	Processor type of the user's workstation
PROCESSOR_IDENTIFIER	Processor ID of the user's workstation
PROCESSOR_LEVEL	Processor level of the user's workstation
PROCESSOR_REVISION	Processor version of the user's workstation
OS	Operating system on the user's workstation
COMSPEC	Executable for command Command Prompt (typically cmd.exe)
HOMEDRIVE	Primary local drive (typically the C drive)
HOMEPATH	Default directory for users (on Windows NT this is typically \users\default
PATH	PATH environment variable
PATHEXT	Extensions for executable files (typically .com, .exe, .bat, or .cmd)
PROMPT	Command prompt (typically $P$G)
SYSTEMDRIVE	Local drive on which system directory resides (e.g., c:\)
SYSTEMROOT	System directory (e.g., c:\winnt). This is the same as WINDIR
WINDIR	System directory (e.g., c:\winnt). This is the same as SYSTEMROOT
TEMP	Directory for storing temporary files (e.g., c:\temp). User, Volatile
TMP	Directory for storing temporary files (e.g., c:\temp). User, Volatile
Example

' Retrieve the NUMBER_OF_PROCESSORS system environment variable

    Set WshShell = Wscript.CreateObject("Wscript.Shell")

    Set WshSysEnv = WshShell.Environment("SYSTEM")

    Wscript.Echo WshSysEnv("NUMBER_OF_PROCESSORS")

See Also

WshEnvironment object


WshShell.SpecialFolders

[This is preliminary documentation and subject to change.]

The SpecialFolders property provides the WshSpecialFolders object for accessing Windows® shell folders such as the desktop folder, start menu folder, and personal document folder.

Syntax

WshShell.SpecialFolders = objWshSpecialFolders

Example

' This code fragment shows how to access the desktop folder

    Set WshShell = Wscript.CreateObject("Wscript.Shell")

    MsgBox "Your desktop is " & WshShell.SpecialFolders("Desktop")

See Also

WshSpecialFolders object


WshShell.CreateShortcut

[This is preliminary documentation and subject to change.]

The CreateShortcut method creates a WshShortcut object and returns it. If the shortcut title ends with ".URL", a WshURLShortcut object is created.

Syntax

WshShell.CreateShortcut(strPathname) = objShortcut

Example

' This code fragment creates a shortcut

' to the currently executing script

    Set WshShell = Wscript.CreateObject("Wscript.Shell")

    Set oShellLink = WshShell.CreateShortcut("Current Script.lnk")

    oShellLink.TargetPath = Wscript.ScriptFullName

    oShellLink.Save

    Set oUrlLink = WshShell.CreateShortcut("Microsoft Web Site.URL")

    oUrlLink.TargetPath = "http://www.microsoft.com"

    oUrlLink.Save

See Also

WshShortcut object, WshUrlShortcut object


WshShell.ExpandEnvironmentStrings

[This is preliminary documentation and subject to change.]

The ExpandEnvironmentStrings method expands the PROCESS environment variable in strString and returns the result string. Variables are enclosed by the '%' character.

The environment variable name is not case-sensitive.

Syntax

WshShell.ExpandEnvironmentStrings(strString) = strExpandedString

Example

MsgBox "Prompt is " & WshShell.ExpandEnviromentStrings("%PROMPT%")


WshShell.Popup

[This is preliminary documentation and subject to change.]

The Popup method displays a popup message box window that contains the message contained in strText. The window title of this message box is specified by strTitle. If strTitle is omitted, the window title is "Windows Scripting Host".

Syntax

WshShell.Popup(strText, [natSecondsToWait], [strTitle], [natType]) = intButton

Remarks

If natSecondsToWait is supplied and its value is greater than zero, the message box window will be closed after natSecondsToWait seconds.

The meaning of natType is the same as in the Win32® MessageBox function. The following table shows the value and its meaning in natType. You can combine values in the following tables.

Button Types

Value	Description
0	Show [OK] button
1	Show [OK] and [Cancel] buttons
2	Show [Abort], [Retry] and [Ignore] buttons
3	Show [Yes], [No] and [Cancel] buttons
4	Show [Yes] and [No] buttons
5	Show [Retry] and [Cancel] buttons
Icon Types

Value	Description
16	Show "Stop Mark" icon
32	Show "Question Mark" icon
48	Show "Exclamation Mark" icon
64	Show "Information Mark" icon
The preceding two tables do not cover all values for natType. For a complete list, see the Win32 documentation.

The return value intButton denotes the number of the button that the user clicked. If the user does not click a button before natSecondsToWait seconds, intButton is set to -1.

Value	Description
1	[OK] button
2	[Cancel] button
3	[Abort] button
4	[Retry] button
5	[Ignore] button
6	[Yes] button
7	[No] button
Example

Set WshShell = Wscript.CreateObject("Wscript.Shell")

WshShell.Popup "Where do you want to go today?"

See Also

Wscript.Echo method


WshShell.RegDelete

[This is preliminary documentation and subject to change.]

The RegDelete method deletes from the registry the key or value named strName.

Syntax

WshShell.RegDelete strName

Parameters

strName

If strName ends with a backslash character (\), this method deletes the key instead of the value.

The strName parameter must begin with one of following root key names:

Short	Long
HKCU	HKEY_CURRENT_USER
HKLM	HKEY_LOCAL_MACHINE
HKCR	HKEY_CLASSES_ROOT
	HKEY_USERS
	HKEY_CURRENT_CONFIG
Example

Set WshShell = Wscript.CreateObject("Wscript.Shell")

WshShell.RegDelete "HKCU\ScriptEngine\Value"    ' Delete value "Value"

WshShell.RegDelete "HKCU\ScriptEngine\Key\"     ' Delete key "Key"

See Also

WshShell.RegRead method, WshShell.RegWrite method


WshShell.RegRead

[This is preliminary documentation and subject to change.]

The RegRead method returns the registry key or value named by strName.

Syntax

WshShell.RegRead(strName) = strValue

Parameters

strName

If strName ends with the backslash character (\), this method returns the key instead of the value.

StrName must begin with one of following root key names:

Short	Long
HKCU	HKEY_CURRENT_USER
HKLM	HKEY_LOCAL_MACHINE
HKCR	HKEY_CLASSES_ROOT
	HKEY_USERS
	HKEY_CURRENT_CONFIG
Remarks

The RegRead method supports only REG_SZ, REG_EXPAND_SZ, REG_DWORD, REG_BINARY, and REG_MULTI_SZ data types. If the registry has other data types, RegRead returns DISP_E_TYPEMISMATCH.

Example

Set WshShell = Wscript.CreateObject("Wscript.Shell")

WshShell.RegRead("HKCU\ScriptEngine\Val")    ' Read from value "Val"

WshShell.RegRead("HKCU\ScriptEngine\Key\")   ' Read from key "Key"

See Also

WshShell.RegDelete method, WshShell.RegWrite method


WshShell.RegWrite

[This is preliminary documentation and subject to change.]

The RegWrite method sets the registry key or value named by strName.

Syntax

WshShell.RegWrite strName, anyValue, [strType]

Parameters

strName

If strName ends with a backslash character (\), this method sets the key instead of the value.

StrName must begin with one of following root key names:

Short	Long
HKCU	HKEY_CURRENT_USER
HKLM	HKEY_LOCAL_MACHINE
HKCR	HKEY_CLASSES_ROOT
	HKEY_USERS
	HKEY_CURRENT_CONFIG
Remarks

RegWrite supports strType as REG_SZ, REG_EXPAND_SZ, REG_DWORD and REG_BINARY. If another data type is passed as strType, RegWrite returns E_INVALIDARG.

RegWrite automatically converts anyValue to a string when strType is REG_SZ or REG_EXPAND_SZ. If strType is REG_DWORD, anyValue is converted to an integer. If strType is REG_BINARY, anyValue must be an integer.

Example

Set WshShell = Wscript.CreateObject("Wscript.Shell")

WshShell.RegWrite "HKCU\ScriptEngine\Value", "Some string value"

WshShell.RegWrite "HKCU\ScriptEngine\Key\", 1 "REG_DWORD"

See Also

WshShell.RegDelete method, WshShell.RegWrite method


WshShell.Run

[This is preliminary documentation and subject to change.]

The Run method creates a new process which executes strCommand with window style intWindowStyle.

Syntax

WshShell.Run (strCommand, [intWindowStype], [bWaitOnReturn])

Parameters

strCommand

Environment variables within the strCommand parameter are automatically expanded.

bWaitOnReturn

If bWaitOnReturn is not specified or FALSE, this method immediately returns to script execution rather than waiting on the process termination.

If bWaitOnReturn is set to TRUE, the Run method returns any error code returned by the application. If bWaitOnReturn is not specified or is FALSE, Run returns an error code of 0 (zero).

Example

' This fragment launches Notepad with the current executed script

  Set WshShell = Wscript.CreateObject("Wscript.Shell")

  WshShell.Run ("notepad " & Wscript.ScriptFullName)

  WshShell.Run ("%windir%\notepad" & Wscript.ScriptFullName)

' This fragment returns the error code from the executed application

  Return = WshShell.Run("notepad " & Wscript.ScriptFullName, 1, TRUE)


WshNetwork Object

[This is preliminary documentation and subject to change.]

ProgID	Wscript.WshNetwork
Filename	WSHom.Ocx
CLSID	F935DC26-1CF0-11d0-ADB9-00C04FD58A0B
IID	F935DC25-1CF0-11d0-ADB9-00C04FD58A0B
The following table describes the properties associated with the WshNetwork object.

Property	Description
ComputerName	A string representation of the computer name.
UserDomain	A string representation of the user's domain name.
UserName	A string representation of the user's name.
The following table describes the methods associated with the WshNetwork object.

Method	Description
AddPrinterConnection	Maps a remote printer to a local resource name.
EnumNetworkDrives	Returns the current network drive mappings.
EnumPrinterConnections	Returns the current network drive mappings.
MapNetworkDrive	Maps a share point to a local resource name.
RemoveNetworkDrive	Removes the current resource connection.
RemovePrinterConnection	Removes a current resource connection.
SetDefaultPrinter	Sets the default printer.


WshNetwork.ComputerName

[This is preliminary documentation and subject to change.]

The ComputerName property provides a string representation of the computer name.

Syntax

WshNetwork.ComputerName = strComputerName


WshNetwork.UserDomain

[This is preliminary documentation and subject to change.]

The UserDomain property provides a string representation of the user domain name.

Syntax

WshNetwork.UserDomain = strDomain


WshNetwork.UserName

[This is preliminary documentation and subject to change.]

The UserName property provides a string representation of the user name.

Syntax

WshNetwork.UserName = strName


WshNetwork.AddPrinterConnection

[This is preliminary documentation and subject to change.]

The AddPrinterConnection method maps the remote printer specified by strRemoteName to the local resource name strLocalName.

Syntax

WshNetwork.AddPrinterConnection strLocalName, strRemoteName, [bUpdateProfile], [strUser], [strPassword]

Parameters

strLocalName

Local resource to map to.

strRemoteName

Remote printer to map.

bUpdateProfile

If bUpdateProfile is supplied and its value is TRUE, this mapping is stored in the user profile.

strUser, strPassword

If you are mapping a remote printer using the credentials of someone other than current user, you can specify strUser and strPassword.

Example

Set WshNetwork = Wscript.CreateObject("Wscript.Network")

WshNetwork.AddPrinterConnection "LPT1", "\\Server\Print1"


WshNetwork.EnumNetworkDrives

[This is preliminary documentation and subject to change.]

The EnumNetworkDrives method returns the current network drive mappings as a WshCollection object. Items in this collection are local names and remote names.

Syntax

WshNetwork.EnumNetworkDrive = objWshCollection

Example

Set WshNetwork = Wscript.CreateObject("Wscript.Network")

Set oDrives = WshNetwork.EnumNetworkDrives

Wscript.Echo oDrives.Item(0) = "Z:"

Wscript.Echo oDrives.Item(1) = "\\Server\Share"

See Also

WshNetwork.MapNetworkDrive method, WshNetwork.RemoveNetworkDrive method, WshCollection object


WshNetwork.EnumPrinterConnections

[This is preliminary documentation and subject to change.]

The EnumPrinterConnections method returns the current network drive mappings as a WshCollection object. Items in this collection are local names and remote names.

Syntax

WshNetwork.EnumPrinterConnections = objWshCollection

Example

Set WshNetwork = Wscript.CreateObject("Wscript.Network")

Set oPrinters = WshNetwork.EnumPrinterConnections

Wscript.Echo oPrinters.Item(0) = "LPT1:"

Wscript.Echo oPrinters.Item(1) \\Server\Printer1"

See Also

WshNetwork.AddPrinterConnection method, WshNetwork.RemovePrinterConnection method, WshCollection object


WshNetwork.MapNetworkDrive

[This is preliminary documentation and subject to change.]

The MapNetworkDrive method maps the share point specified by strRemoteName to the local resource name strLocalName.

Syntax

WshNetwork.MapNetworkDrive strLocalName, strRemoteName, [bUpdateProfile], [strUser], [strPassword]

Parameters

strLocalName

Local resource name to map to.

strRemoteName

Remote share to map.

bUpdateProfile

If bUpdateProfile is supplied and its value is TRUE, this mapping is stored in the user profile.

strUser, strPassword

If you are mapping the share point using the credentials of someone other than current user, you can specify strUser and strPassword.

Example

Set WshNetwork = Wscript.CreateObject("Wscript.Network")

WshNetwork.MapNetworkDrive "Z:", "\\Server\Share"


WshNetwork.RemoveNetworkDrive

[This is preliminary documentation and subject to change.]

The RemoveNetworkDrive method removes the current resource connection denoted by strName.

Syntax

WshNetwork.RemoveNetworkDrive strName, [bForce], [bUpdateProfile]

Parameters

strName

The strName parameter can be either a local name or a remote name, depending on how the drive is mapped. If the drive has a mapping between a local name (drive letter) and a remote name, then strName must be set to the local name. If the Network path does not have a local name (drive letter) mapping, then strName must be set to the remote name.

bForce

If bForce is supplied and its value is TRUE, this method removes the connections whether the resource is used or not.

bUpdateProfile

If bUpdateProfile is supplied and its value is TRUE, this mapping is stored in the user profile.

Example

Set WshNetwork = Wscript.CreateObject("Wscript.Network")

' Local name mapped to remote share

  WshNetwork.MapNetworkDrive "Z:", "\\Server\Share"

  WshNetwork.RemoveNetworkDrive "Z:"

' No local name mapping, such as:

' NET USE \\Server\ShareWshNetwork.RemoveNetworkDrive "\\Server\Share"

  WshNetwork.MapNetworkDrive "\\Server\Share"

  WshNetwork.RemoveNetworkDrive "\\Server\Share"


WshNetwork.RemovePrinterConnection

[This is preliminary documentation and subject to change.]

The RemovePrinterConnection method removes the current resource connection denoted by strName.

Syntax

WshNetwork.RemovePrinterConnection strName, [bForce], [bUpdateProfile]

Parameters

strName

The strName parameter can be either a local name or a remote name, depending on how the printer is connected. If the printer has a mapping between a local name (e.g., LPT1) and a remote name, then strName must be set to the local name. If the Network path does not have a local name mapping, then strName must be set to the remote name.

bForce

If bForce is supplied and its value is TRUE, this method removes the connection whether the resource is used or not.

bUpdateProfile

If bUpdateProfile is supplied and its value is TRUE, this mapping is stored in the user profile.

Example

Set WshNetwork = Wscript.CreateObject("Wscript.Network")

' Local name mapped to remote share

  WshNetwork.RemovePrinterConnection "LPT1:"

' No local name mapping. e.g. NET USE "\\Server\Printer1"

  WshNetwork.RemovePrinterConnection "\\Server\Printer1"


WshNetwork.SetDefaultPrinter

[This is preliminary documentation and subject to change.]

The SetDefaultPrinter method sets default print to the remote printer specified by strPrinterName.

Syntax

WshNetwork.SetDefaultPrinter strPrinterName

Parameters

strPrinterName

Remote printer name to set as default, such as  "\\Server\Printer1". Note that strPrinterName cannot be a local name such as "LPT1:".


WshCollection Object

[This is preliminary documentation and subject to change.]

The WshCollection object is not exposed directly. For access to it, use WshNetwork.EnumNetworkDrives or WshNetwork.EnumPrinterConnections.

ProgID	N/A
Filename	WSHom.Ocx
CLSID	F935DC24-1CF0-11d0-ADB9-00C04FD58A0B
IID	F935DC23-1CF0-11d0-ADB9-00C04FD58A0B
The following table describes the properties associated with the WshCollection object.

Property	Description
Item	Provides the nth enumerated item as a string.
Count	The number of enumerated items.
length	The number of enumerated items (JScript).


WshCollection.Item

[This is preliminary documentation and subject to change.]

The Item property provides the natIndexth enumerated item as a string. It is the default property.

Syntax

WshCollection(natIndex) = strEnumeratedItem

WshCollection.Item(natIndex) = strEnumeratedItem

Example

Set WshNetwork = Wscript.CreateObject("Wscript.Network")

Set oDrives = WshNetwork.EnumNetworkDrives

Wscript.Echo oDrives.Item(0) = " "Z:"

Wscript.Echo oDrives.Item(1) = "\\Server\Share"


WshCollection.Count

[This is preliminary documentation and subject to change.]

The Count property provides the number of enumerated items.

Syntax

WshCollection.Count = natNumberOfItemsl

See Also

WshCollection.length property


WshCollection.length

[This is preliminary documentation and subject to change.]

The length property provides the number of enumerated items. This property provides the same functionality as the Count property and is provided for compatibility with JScript™.

Syntax

WshCollection.length = natNumberOfItems

See Also

WshCollection.Count property


WshEnvironment Object

[This is preliminary documentation and subject to change.]

The WshEnvironment object is not exposed directly. For access to it, use the WshShell.Environment property.

ProgID	N/A
Filename	WSHom.Ocx
CLSID
IID
The following table describes the properties associated with the WshEnvironment object.

Property	Description
Item	Gets or sets the value of a specified environment variable.
Count	The number of enumerated items.
length	The number of enumerated items (JScript).
The following table describes the method associated with the WshEnvironment object.

Method	Description
Remove	Deletes a specified environment variable.


WshEnvironment.Item

[This is preliminary documentation and subject to change.]

The Item property sets or returns the value for the strName environment variable. It is the default property.

Syntax

WshEnvironment.Item("strName") = strValue

WshEnvironment("strName") = strValue

Example

' Get the value of NUMBER_OF_PROCESSORS environment variable

  Set WshShell = Wscript.CreateObject("Wscript.Shell")

  Set WshSysEnv = WshShell.Environment("SYSTEM")

  Wscript.Echo WshSysEnv("NUMBER_OF_PROCESSORS")

' Set the value of EXAMPLE volatile environment variable to A_VALUE

  Set WshShell = Wscript.CreateObject("Wscript.Shell")

  Set WshEnv = WshShell.Environment("VOLATILE")

  WshEnv("EXAMPLE")= "A_VALUE"

' List all system environment variables

  Set WshShell = Wscript.CreateObject("Wscript.Shell")

  For Each strVarName In WshShell.Environment("SYSTEM")

    MsgBox strVarName

  Next

See Also

WshShell.Environment property


WshEnvironment.Count

[This is preliminary documentation and subject to change.]

The Count property provides the number of enumerated items.

Syntax

WshEnvironment.Count = natNumberOfItems

See Also

WshEnvironment.length property


WshEnvironment.length

[This is preliminary documentation and subject to change.]

The length property provides the number of enumerated items. This property provides the same functionality as the Count property and is provided for compatibility with JScript™.

Syntax

WshEnvironment.length = natNumberOfItems

See Also

WshEnvironment.Count property


WshEnvironment.Remove

[This is preliminary documentation and subject to change.]

The Remove method deletes the environment variable specified by strName.

Syntax

WshEnvironment.Remove(strName)

Example

' Delete the EXAMPLE volatile environment variable

  Set WshShell = Wscript.CreateObject("Wscript.Shell")

  WshShell.Environment("VOLATILE").Remove("EXAMPLE")

' Delete multiple variables

  Set WshUsrEnv = Wscript.Environment("User")

  WshUsrEnv.Remove("EXAMPLE_1")

  WshUsrEnv.Remove("EXAMPLE_2")

  WshUsrEnv.Remove("EXAMPLE_3")

  WshUsrEnv.Remove("EXAMPLE_4")

See Also

WshShell.Environment property


WshShortcut Object

[This is preliminary documentation and subject to change.]

This object is not exposed directly. To get the WshShortcut object, use the WshShell.CreateShortcut method.

ProgID	N/A
Filename	WSHom.Ocx
CLSID	F935DC28-1CF0-11d0-ADB9-00C04FD58A0B
IID	F935DC27-1CF0-11d0-ADB9-00C04FD58A0B
The following table describes the properties associated with the WshShortcut object.

Property	Description
Arguments	Parameters to a shortcut object.
Description	A description of a shortcut object.
Hotkey	The hotkey of a shortcut object.
IconLocation	The icon location of a shortcut object.
TargetPath	The target path of a shortcut object.
WindowStyle	The window style of a shortcut object.
WorkingDirectory	The working directory of a shortcut object.
The following table describes the method associated with the WshShortcut object.

Method	Description
Save	Saves a shortcut into a specified file system.


WshShortcut.Arguments

[This is preliminary documentation and subject to change.]

The Arguments property provides parameters to a shortcut object.

Syntax

WshShortcut.Arguments = strArguments


WshShortcut.Description

[This is preliminary documentation and subject to change.]

The Description property provides a description of a shortcut object.

Syntax

WshShortcut.Description = strDescription


WshShortcut.FullName

[This is preliminary documentation and subject to change.]

The FullName property provides the full path of a shortcut object.

Syntax

WshShortcut.FullName = strFullName


WshShortcut.Hotkey

[This is preliminary documentation and subject to change.]

The HotKey property provides the hotkey of a shortcut object. A hotkey is a keyboard shortcut to start or switch to a program.

Syntax

WshShortcut.HotKey = strHotKey

Remarks

BNF syntax of strHotKey is as follows:

Hotkey   ::=   modifier* keyname

modifier ::=   "ALT+" | "CTRL+" | "SHIFT+" | "EXT+"

keyname  ::=   "A" .. "Z" |

               "0".. "9" |

               "Back" | "Tab" | "Clear" | "Return" |

               "Escape" | "Space" | "Prior" | ...

Complete key names are found in WINUSER.H. Hotkey is case-insensitive.

Hotkeys can only activate shortcuts located on the Windows desktop or the Windows Start menu .

The Windows Explorer does not accept ESC, ENTER, TAB, SPACE, PRINT SCREEN or BACKSPACE, even though WshShortcut.Hotkey supports these in compliance with the Win32 API. It is therefore recommended that you not use these keys in your shortcut.

Example

Set WshShell = Wscript.CreateObject("Wscript.WshShell")

strDesktop = WshShell.SpecialFolders("Desktop")

Set oMyShortcut = WshShell.CreateShortcut(strDesktop & "\a_key.lnk")

OMyShortcut.TargetPath = "%windir%\notepad.exe"

oMyShortCut.Hotkey = "ALT+CTRL+F"

oMyShortCut.Save

Wscript.Echo oMyShortCut.HotKey = "Alt+Ctrl+F"

See Also

WshSpecialFolders object


WshShortcut.IconLocation

[This is preliminary documentation and subject to change.]

The IconLocation property provides the icon location of a shortcut object. The format of the icon location should be "Path,index".

Syntax

WshShortcut.IconLocation = strIconLocation


WshShortcut.TargetPath

[This is preliminary documentation and subject to change.]

The TargetPath property provides the target path of a shortcut object.

Syntax

WshShortcut.TargetPath = strTargetPath


WshShortcut.WindowStyle

[This is preliminary documentation and subject to change.]

The WindowStyle property provides the window style of a shortcut object.

Syntax

WshShortcut.WindowStyle = natWindowStyle


WshShortcut.WorkingDirectory

[This is preliminary documentation and subject to change.]

The WorkingDirectory property provides the working directory of a shortcut object.

Syntax

WshShortcut.WorkingDirectory = strWorkingDirectory


WshShortcut.Save

[This is preliminary documentation and subject to change.]

The Save method saves the shortcut object to the location specified by the FullName property.

Syntax

WshShortcut.Save


WshSpecialFolders Object

[This is preliminary documentation and subject to change.]

This object is not exposed directly. To get the WshSpecialFolders object, use the WshShell.SpecialFolders property.

ProgID	N/A
Filename	WSHom.Ocx
CLSID
IID
The following table describes the properties associated with the WshSpecialFolders object.

Property	Description
Item	The full path of the specified special folder (default)
Count	The number of enumerated items.
length	The number of enumerated items (JScript).


WshSpecialFolders.Item

[This is preliminary documentation and subject to change.]

The Item property returns the full path for the special folder specified by strFolderName. It is the default property.

Syntax

WshShell.SpecialFolders.Item("strFolderName") = strFolderPath

WshShell.SpecialFolders("strFolderName") = strFolderPath

Remarks

WshShell.SpecialFolders("strFolderName") returns NULL if the requested folder (strFolderName) is not available. For example, Windows 95 does not have an AllUsersDesktop folder and returns NULL if strFolderName = AllUsersDesktop

The following special folders are provided with the Windows 95 and Windows NT 4.0 operating systems:

AllUsersDesktop

AllUsersStartMenu

AllUsersPrograms

AllUsersStartup

Desktop

Favorites

Fonts

MyDocuments

NetHood

PrintHood

Programs

Recent

SendTo

StartMenu

Startup

Templates

Example

' This fragment returns the full path for the Windows Desktop folder

  Set WshShell = Wscript.CreateObject("Wscript.Shell")

  StrMyDesktop = WshShell.SpecialFolders("Desktop")

' List all special folders

  For Each strFolder In WshShell.SpecialFolders

    MsgBox strFolder

  Next

See Also

WshShell.SpecialFolders property


WshSpecialFolders.Count

[This is preliminary documentation and subject to change.]

The Count property provides the number of enumerated items.

Syntax

WshSpecialFolders.Count = natNumberOfItems

See Also

WshSpecialFolders.length property


WshSpecialFolders.length

[This is preliminary documentation and subject to change.]

The length property provides the number of enumerated items. This property provides the same functionality as the Count property and is provided for compatibility with Microsoft® JScript™.

Syntax

WshSpecialFolders.length = natNumberOfItems

See Also

WshSpecialFolders.Count property


WshUrlShortcut Object

[This is preliminary documentation and subject to change.]

This object is not exposed directly. To get the WshUrlShortcut object, use the WshShell.CreateShortcut method.

ProgID	N/A
Filename	WSHom.Ocx
CLSID
IID
The following table describes the properties associated with the WshUrlShortcut object.

Property	Description
FullName	The full path of a URL shortcut object.
TargetPath	The target path of a URL shortcut object.
The following table describes the method associated with the WshUrlShortcut object.

Property	Description
Save	Saves a shortcut into a specified file system.


WshUrlShortcut.FullName

[This is preliminary documentation and subject to change.]

The FullName property provides the full path of a shortcut object.

Syntax

WshUrlShortcut.FullName = strFullName


WshUrlShortcut.TargetPath

[This is preliminary documentation and subject to change.]

The TargetPath property provides the target path of a shortcut object.

Syntax

WshUrlShortcut.TargetPath = strTargetPath


WshUrlShortcut.Save

[This is preliminary documentation and subject to change.]

The Save method saves a shortcut to the location specified by the FullName property.

Syntax

WshUrlShortcut.Save