The MS ScriptIt Utility
| Archived content. No warranty is made as to technical accuracy. Content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist. |
Updated : April 1, 1998
On This Page
Abstract
Introduction
Using ScriptIt
Script File Format
sample SCRIPTs
For More Information
Abstract
This White Paper describes Microsoft® ScriptIt, a tool for automating interactive software installations and system configuration tasks. ScriptIt can be used to start a process, monitor the window titles of active processes, and, when appropriate, send a set of keystrokes to the correct window. The keystrokes can be predetermined or they can be determined at run time. ScriptIt can be configured to differentiate (and respond appropriately) between multiple windows that have the same title bar but different instructional text.
Note that ScriptIt is not a traditional scripting language and does not offer many of the traditional programming language constructs. The ScriptIt command must be started by a user with sufficient security privileges to perform the designated installation or configuration task.
Important: Microsoft does not provide technical support for scripts prepared with the ScriptIt tool. Consequently, it is important that you test your scripts thoroughly before using them in a production environment.
Introduction
Microsoft® ScriptIt is a command-line utility for automating interactive software installations and system configuration tasks. ScriptIt works by monitoring the window titles of active processes. When it finds a window with which it should interact, it sends a set of keystrokes to that window. ScriptIt uses the window title or a combination of the window title and text that appears on controls within the window to identify the window that will receive the keystrokes. The use of the window title combined with text allows ScriptIt to differentiate between multiple windows that have the same title bar.
Important: Microsoft does not provide technical support for scripts prepared with the ScriptIt tool. Consequently, it is important that you test your scripts thoroughly before using them in a production environment.
Document Conventions
This White Paper uses the following document conventions:
monospace
Indicates source code, structure syntax, examples, user input, and program output.
Bold
Indicates a function, structure, macro, interface, method, data type, or other keyword in the programming interface or programming language.
Italic
Indicates a placeholder, most often a function or method parameter; these placeholders represent the information that the user must supply or implement. In addition, italics are used to highlight the first use of terms and to emphasize meaning.
UPPERCASE
Indicates a flag, return value, or property. In addition, uppercase letters indicate registers and terms used at the operating system command-level.
[ ]
Square brackets indicate the beginning of a script file section.
< >
Angle brackets indicate optional function or method parameters. Type only the syntax within the brackets, not the brackets themselves.
Using ScriptIt
To use ScriptIt, you need the ScriptIt script processing engine, ScriptIt.exe, and a valid script file as described in this document. To use ScriptIt to automate a software installation or system configuration change, the user that launches ScriptIt must be logged on with sufficient security privileges to perform the designated installation or configuration task.
To start the ScriptIt utility, type the following from the Run command:
SCRIPTIT script file
where script file is a text file in .ini file format. This script file uses .ini file keys to identify the window titles that ScriptIt should interact with, and specifies the keystrokes that ScriptIt sends to these windows as .ini file key values. For example, the script file entries:
run=notepad.exe Untitled - Notepad=Hello World
launch an instance of Notepad and then send the string "Hello World" to the open Microsoft Notepad window with the title bar Untitled – Notepad.
Note that ScriptIt is not a traditional scripting language and does not offer many of the traditional programming language constructs (such as if, then, else, while, gosub, and so forth). The remainder of this paper describes the ScriptIt script file structure and variables, and provides sample code and examples of valid script files.
Script File Format
The basic ScriptIt script file can have the following format and line types:
[SCRIPT] run=command runwait=command WindowTitle=keystrokes WindowTitle<+text>=keystrokes mkfile filename.ext=fileline REM comment [ADLIB] WindowTitle=keystrokes WindowTitle<+text>=keystrokes
The [SCRIPT] Section
Each script file begins with the section tag [SCRIPT]. [SCRIPT] tells ScriptIt where to begin processing the script file. Any text above the [SCRIPT] tag is ignored and can be used to document your script. Lines in the [SCRIPT] section are processed sequentially.
Within the [SCRIPT] section, ScriptIt recognizes four types of .ini file lines:
Run lines (run and runwait), which start executables, run valid MS-DOS® operating system commands, and interpret valid WinBatch commands.
Window title lines (title and title+text), which identify an instance of a window and send the designated keystrokes.
Make file lines (mkfile), which cause the script to open a new file as specified by filename and write lines of text to it as specified by fileline.
Remarked lines ( REM), which allow script lines to be deactivated and documented.
The optional [ADLIB] section provides instructions for ScriptIt to use when the setup program displays a window or dialog box that is not part of a normal scripted process and therefore not specified in the [SCRIPT] section. Entries in the [ADLIB] section allow ScriptIt to respond appropriately to errors or exceptions that occur during the processing of the [SCRIPT] section. Lines in the [ADLIB] section can also be used to accommodate setup programs that behave differently if they are run a second time on the same system. Lines that appear in this section are processed only if a matching window is displayed; otherwise, they are ignored.
Run and Runwait
Run lines (run and runwait) execute command lines. ScriptIt handles run and runwait lines by parsing and executing the value(s) to the right of the equal sign. For example, the line
run=notepad.exe
causes ScriptIt to start Notepad and then continue with processing the next line in the [SCRIPT] section.
A runwait line is similar to a run line except that ScriptIt allows the runwait command-line to complete processing before proceeding to the next line in the [SCRIPT] section. For example, the line
runwait=notepad.exe
starts Notepad, but does not go on to the next script file line until that instance of Notepad is closed.
If the command to be run is an executable or batch file, the run or runwait line needs both a file name and extension. In addition, if the command you wish to run is not in the path, you must also specify a fully qualified path. If the command is an internal command such as for, echo, or type, the command-line must start with the left quotation mark (`). The left quotation mark directs ScriptIt to pass the command line to the %ComSpec% command interpreter for execution.
Syntax
run= <`> <@> fileName.ext runwait= <`> <@> fileName.ext
With run or runwait, the value to the right of the equal sign can take various forms. If environment variables appear in the command line, ScriptIt substitutes the %envVar% string with the value of the appropriate environment variable.
In addition to environment variable expansion, ScriptIt uses the first character to the right of the equal sign to determine how to evaluate the string at run time. The following paragraphs document the parameters that ScriptIt recognizes and describe how ScriptIt responds in each case.
The parameters are as follows:
fileName.extension
If the value to the right of the equal sign begins with the name of the command you wish to run, ScriptIt treats the line as if it had been typed at the Run command dialog box. (This is the default.)
`
When a single left quotation mark (`) is the first character to the right of the equal sign, ScriptIt assumes the command that follows is an internal command, such as for, echo, or type. ScriptIt prefaces the command line with the value of %ComSpec% /C before executing the command line.
@
When the @ sign is the first character to the right of the equal sign, ScriptIt interprets the remainder of the line as a WinBatch command. (WinBatch is a scripting language written by Wilson Window Ware. It has more than 400 functions that can be used to interrogate and manipulate Microsoft Windows® 95 and Microsoft Windows NT® operating systems.)
Title and Title+text
The second type of .ini file line is known as a title line. ScriptIt handles title lines by locating an active window with a window title that matches the key name. ScriptIt then sends the values to the right of the equal sign to that window as keystrokes.
While case and spacing is important in matching window titles, you do not need to specify the entire window title. ScriptIt can match partial window titles. For example, you could use "Calculator" or "Calcul" to identify the Calculator window.
When there are multiple windows open with the same window title, you can uniquely identify a specific window by using a plus sign (+) combined with text that appears on one of the controls in the target window. This is referred to as a title+text line. For example, if there are two instances of the Windows Calculator accessory application (Calc.exe) running, the line
Calculator+999=*9=
sends the string *9= to the Calculator window instance that has 999 displayed in the input box. This results in the total 8991 (999 *9). The other instance of the Calculator receives no keystrokes.
Note that ScriptIt cannot detect all text in all windows. To determine if ScriptIt can see specific text, run ScriptIt /reveal and then use ALT+TAB to go to the window you wish to analyze. The ScriptIt window will list the window title and any text that it can see on controls within that window.
If ScriptIt doesn't find a window title that matches the current title line in the script file, ScriptIt will wait indefinitely until a matching window appears. This behavior allows ScriptIt to avoid the timing problems that affect other graphical user interface (GUI) automation tools.
Syntax
WindowTitle<+text>= <@> <`> <#> <~ > keystrokes
As with the run line syntax, the first character to the right of the equal sign of a title line is evaluated at run time. The major difference is that the result is sent to the designated window as keystrokes instead of being executed. Also, as with run lines, any title string value enclosed in percent (%) signs is expanded to the value of the corresponding environment variable before it is sent to the window as keystrokes.
The parameters are as follows:
WindowTitle
This is the title of the target window (required).
<+text>
Text on one of the target window controls that may further distinguish the target window from other open windows with the same title (optional). run ScriptIt.exe /reveal to learn what text ScriptIt can see on a particular window.
@
ScriptIt passes any title line value that begins with the ampersand (@) character to the WinBatch Interpreter for evaluation. The return value of the WinBatch function is then passed as keystrokes to the designated window.
`
When ScriptIt sees the left single quotation mark (`) character as the first character, it assumes the command that follows is an internal or external command which generates output that can be redirected. ScriptIt prefaces the command line with %ComSpec% /C before executing the command. This allows ScriptIt to run internal commands such as for, echo, or type. The command output is redirected to a temporary file that ScriptIt reads and sends as keystrokes to the targeted window.
#
The number sign (#) is the key delimiter. You can put multiple keystroke sequences on the same line and use the number sign to delimit them. ScriptIt interprets two consecutive number signs (##) as a five-second pause, and each subsequent number sign after the first two results in an additional five-second pause.
~
The tilde (~) indicates a number of commands that can be invoked to provide window management and limited flow control. Note that these commands can be used only on title lines, and not on run lines. The tilde commands are as follows:
Tilde Command |
Description |
|---|---|
~exit |
Exits the script immediately. For example: |
~wait |
Causes a five-second delay in the execution of the script (this is the same as using ##). For example: Network=~wait |
~winwaitclose |
Causes the script to pause until the window is closed. For example: |
~winclose |
Causes ScriptIt to close the window and terminate the executable that created it. For example: |
~winhide |
Causes ScriptIt to make the specified window invisible. For example: |
~winshow |
Causes ScriptIt to show the specified window if it is currently hidden. For example: |
~winmin |
Causes ScriptIt to display the specified window as an icon. For example: |
~winmax |
Causes ScriptIt to display the specified window as a full-screen window. For example: |
keystrokes
Keys that do not begin with any of the special keystroke notations listed above are sent unchanged to the designated window. For example, the string "Hello" would be sent as "Hello" and would not be subjected to any processing prior to being sent. (This is the default.)
ScriptIt also has a sendkey notation that can send special key strokes to controls within windows. This notation is similar to that used with the Microsoft Visual Basic® Sendkey command. Note that all sendkey abbreviations are enclosed in braces ({}).
The following table outlines the ScriptIt title line sendkey notation.
Key |
SendKey Equivalent |
Description |
|---|---|---|
~ |
{~} |
Sends a tilde (~). |
! |
{!} |
Sends an exclamation point (!). |
^ |
{^} |
Sends a caret (^). |
+ |
{+} |
Sends a plus sign (+). |
{ |
{ { } |
Sends a left brace ({). |
} |
{ } } |
Sends a right brace (}). |
Alt |
{ALT} |
Sends an Alt keystroke. |
Backspace |
{BACKSPACE} or {BS} |
Sends a Backspace keystroke. |
Clear |
{CLEAR} |
Clears the field. |
Delete |
{DELETE} or {DEL} |
Sends a Delete keystroke. |
Down Arrow |
{DOWN} |
Sends a Down Arrow keystroke. |
End |
{END} |
Sends an End keystroke. |
Enter |
{ENTER} or ~ |
Sends an Enter keystroke. |
Escape |
{ESCAPE} or {ESC} |
Sends an Esc keystroke. |
F1 through F16 |
{F1} through {F16} |
Sends the appropriate Function keystroke. |
Help |
{HELP} |
Sends a Help (F1) keystroke. |
Home |
{HOME} |
Sends a Home keystroke. |
Insert |
{INSERT} or {INS} |
Sends an Insert keystroke. |
Left Arrow |
{LEFT} |
Sends a Left Arrow keystroke. |
Page Down |
{PGDN} |
Sends a Page Down keystroke. |
Page Up |
{PGUP} |
Sends a Page Up keystroke. |
Right Arrow |
{RIGHT} |
Sends a Right Arrow keystroke. |
Space |
{SPACE} or {SP} |
Sends a Spacebar keystroke. |
Tab |
{TAB} |
Sends a Tab keystroke. |
Up Arrow |
{UP} |
Sends an Up Arrow keystroke. |
To enter an Alt, Control, or Shift key combination, precede the desired character with one or more of the following symbols:
Key |
Precede With |
|---|---|
Alt Key |
! |
Control Key |
^ |
Shift Key |
+ |
For example, to enter Alt+S, type
!s
To enter Ctrl+Shift+F7 type
^+{F7}
You can repeat a key by typing the key followed by a space and the total number of repetitions desired. For example, to type 20 asterisks, use
{* 20}
To move the cursor down eight lines, type
{DOWN 8}
To check a checkbox, use
{+}
To uncheck a checkbox, use
{-}
MkFile
ScriptIt does not have many of the sophisticated features of traditional scripting languages such as Microsoft Visual Basic, Scripting Edition, Microsoft Jscript™ development software, or Perl. However, the mkfile line allows you to enhance and extend ScriptIt's capabilities with the features of these other scripting languages. The mkfile line capability allows ScriptIt to write a Visual Basic, Scripting Edition, Jscript, Perl script, and so forth, at run time. The external script can then be executed using a ScriptIt run or runwait line, or it can be executed from a title line using the left quotation mark (`) directive as described earlier. This will result in the standard output of the external script being redirected to the designated window title. Note that when you use any of the supported Windows Script Host languages from within the context of a title line, you should use CScript.exe, not WScript.exe, to launch them. ScriptIt expects that any command launched from a title line will send its output to standard output. WScript.exe does not use standard output.
Syntax
mkfile filename.ext=fileline
The parameters are as follows.
filename.ext
This parameter specifies the file name that is to be created or appended. Environment variables such as %Temp% can appear in the filename string.
fileline
This parameter specifies the line that is to be written or appended to filename. This line could be Visual Basic, Scripting Edition code, Jscript code, Perl code, and so forth. Or it could just be normal text that you want to save in a file.
If you want to create a multiple-line file, you need to include multiple mkfile lines in your script, each with the same filename.ext. The first instance of a given filename.ext opens a new file. All subsequent mkfile lines with the same filename.ext append lines to that file. Once you have finished building your new external script file, a ScriptIt run or runwait line can execute it. As indicated earlier, you can also redirect your external script's output to a specific window by using a ScriptIt title line with a keystroke segment that begins with the left quotation mark (`) followed by the command-line necessary to run the external script. For example, the following uses a run line to launch an instance of Notepad:
run=notepad.exe
mkfile %tmp%\t.vbs=set wshshell=wscript.createobject("wscript.shell")
mkfile %tmp%\t.vbs=set wshnetwork=wscript.createobject("wscript.network")
mkfile %tmp%\t.vbs=wscript.echo wshnetwork.username
Untitled - Notepad=`cscript //nologo %tmp%\t.vbs
run=`if exist %tmp%\t.vbs del %tmp%\t.vbs
It then uses mkfile lines to build a three-line Visual Basic, Scripting Edition file named %tmp%\t.vbs, and then uses a title line and a command line preceded by a left quotation mark (') to run t.vbs, redirecting the output to the Notepad window. Finally, the ScriptIt script cleans up after itself by using a run line with a left quotation mark to delete %tmp%\t.vbs.
REM
Lines that begin with REM are remarked lines. If a line begins with the string REM, ScriptIt recognizes the string and skips the line without processing its contents.
Some Sample [SCRIPT] Sections
The following are examples of completed [SCRIPT] sections with multiple run lines.
Example 1
[SCRIPT] run=Notepad.exe Untitled - Notepad=Hello World run=calc.exe Calculator=999*9= REM Just a simple calculation
This example starts an instance of Notepad and sends the text "Hello World" to the Notepad window. It then starts an instance of the Calculator, and sends the keystrokes "999*9" to the Calculator.
Example 2
[SCRIPT] runwait=%comspec% /c echo close me >sample.txt runwait=Notepad.exe sample.txt run=calc.exe Calculator=111 run=calc.exe Calculator=999 Calculator+999=*9=
In this example, line one identifies the [SCRIPT] section.
Line two, "runwait=%comspec% /c echo close me >sample.txt," expands the ComSpec environment variable and calls the result with the /c parameter so that the internal echo command can be used to create the sample.txt file. The use of runwait (rather than run) instructs ScriptIt to wait until the command shell has finished processing before it proceeds to line three.
Line three, "runwait=Notepad.exe sample.txt," starts Notepad and opens the Sample.txt file created in line two. Because this instance of Notepad is launched with runwait, the script does not proceed until the Notepad window closes.
Line four, "run=calc.exe," starts the Calculator.
Line five sends the keys "111" to a window that matches the Calculator window.
Line six, "run=calc.exe," starts another instance of Calculator.
Line seven, "Calculator=999," sends the keystrokes "999" to the entry field of the calculator instance created in line six.
Line eight, "Calculator+999=*9=," demonstrates how ScriptIt can use a combination of the window title and the text properties of controls on the window to help uniquely identify a window before sending keystrokes to it. In this case, ScriptIt differentiates between the first instance of Calculator (which has 111 in the display window) and the second instance (which has 999). When ScriptIt finds a window titled Calculator that has 999 on one of the controls, it sends the keys *9= to that window, which results in the value 8991. The other instance remains unchanged.
The [ADLIB] Section
While the [SCRIPT] section contains the functionality necessary for automating interactive installations and configuration tasks that follow the script, each script should also be able to handle unforeseen events and error conditions gracefully. This is the purpose of the optional [ADLIB] section. The [ADLIB] section only recognizes title lines and uses the same title line syntax as that used in the [SCRIPT] section. Its primary purpose is to allow the script to identify certain error or exception conditions and have it respond with the appropriate keystrokes. The important thing to remember about the [ADLIB] section is that the title lines that appear in this section are only processed if a matching window title happens to appear sometime during the course of the script; otherwise, lines in the [ADLIB] section are ignored.
Sample Script with [ADLIB] Section
The following example shows a script with both [SCRIPT] and [ADLIB] sections.
[SCRIPT]
run=C:\WINDOWS\Profiles\joesmith\Desktop\DCOM\ads95.exe
Active Directory+Welcome=!y
Active Directory+Please read=!y
Active Directory+done!=~
[ADLIB]
Active Directory+Setup could not={ESC}#`report %computename%#~exit
In this example, line one identifies the [SCRIPT] section.
Line two, run=C:\WINDOWS\Profiles\joesmith\Desktop\DCOM\ads95.exe, starts the Active Directory Service Interfaces (ADSI) installation program. (Note that the complete path is provided.)
Line three, Active Directory+Welcome=!y, responds to the first prompt in the installation program's Welcome screen by sending the keystrokes that click the Yes button (Alt+Y).
Line four, Active Directory+Please read=!y, responds to the second prompt by sending the keystrokes that click the Yes button (Alt+Y).
Line five, Active Directory+done!=~, responds to the finished dialog by sending an Enter keystroke (a tilde) for the OK button
Line six marks the beginning of the [ADLIB] section.
Line seven, Active Directory+Setup could not={ESC}#`report.bat %computename%#~exit, tells the script how to respond to an insufficient disk space error reported by the ADSI setup program. In this case, the script exits the installation program by sending an Esc key, and then runs a batch file called Report.bat with %computername% as the first command line parameter. Finally, the script exits by using the ~exit command.
sample SCRIPTs
This section provides additional script file examples that you may find useful when preparing your own ScriptIt scripts. These samples include scripts that:
Install Microsoft FrontPage® 97 Web site creation and management tool server extensions
Install Active Server Pages (ASP)
Install Microsoft Index Server
Install a Compaq Support Software Diskette (SSD)
Install Web Administration
Installing FrontPage97 Server Extensions
[SCRIPT] run=%upgroot%\post4\iis30\frontpg\fpsetup.bat Welcome=~ License=!y Destination=~ Installed Servers=~ Select Program=~ Start Copying=~ Administrator Setup=~ Server Administrator=~ Server Administrator+Enable Basic=~ Setup Complete=~#~winwaitclose
Installing Active Server Pages
[SCRIPT] run=%upgroot%\post4\iis30\asp\aspsetup.bat License Agreement=~ Active Server Pages=~ Stop Internet=~ Select Options=~ Select Paths=~ Warning=~ Setup is Complete=~ Information=~ Start Internet=~#~winwaitclose
Installing Index Server
[SCRIPT] run=%upgroot%\post4\iis30\index11\issetup.bat Microsoft Index+Do you wish=!y Microsoft Index+Please read the foll=!y Microsoft Index+Welcome to Setup=!c Microsoft Index+IIS scripts=~ Microsoft Index+IIS virtual root=~ Microsoft Index+path to the directory=~ Microsoft Index+now installed=!w#~winwaitclose
Installing Compaq's Support Software Diskette (SSD)
[SCRIPT] run=%upgroot%\post3\ssd1.20\setup.exe Setup Installation Options=!e Setup - Express=!u Setup Session Complete=!r Restart System=~
Installing Web Administration
[SCRIPT]
run=%upgroot%\post2\webadmin\webadmin.exe
Web based+Please read={TAB}#~
Web based+Welcome to Setup=~
Web based+Please exit to Windows NT=~
ReadMe=!f#x
For More Information
For the latest information on Windows NT Server, check out our World Wide Web site at https://www.microsoft.com/ntserver, or the Windows NT Server Forum on the Microsoft Network (GO WORD: MSNTS).