Run Script action
The Run Script action runs one of the following script types:
- MS-DOS batch commands; these use the MS-DOS command processor to execute one or more external programs or internal command processor commands as a batch file.
- VBScript code; runs a VBScript program using the wscript.exe script processor.
- JScript code; runs a JScript program using the wscript.exe script processor.
- PowerShell scripts; feeds Windows PowerShell commands to the PowerShell command processor.
This allows you to execute a series of external programs as a single action.
The Run Script action writes the script that you specify to a temporary file, then uses the appropriate program on the target system to execute the script. For Windows 95, 98, and Me, the default command processor for batch commands is COMMAND.COM; for Windows NT4, 2000, XP, and later it is CMD.EXE. However, if the user has an alternate command processor installed, for example TCC from JP Software, it will be used instead. For VBScript and JScript scripts, WSCRIPT.EXE will be used.
- For MS-DOS batch commands, you can use the normal batch file syntax in this action, including input and output redirection (<, >, and >>), piping (|), and command echo suppression (@ at the start of a line).
- All script types can use symbolic variables; they will be resolved when the temporary script file is created. If your script uses < and > characters that are not intended as symbolic references, then make sure that you put a space after the < character to avoid interpretation as a (non-existing) symbolic reference. Alternatively, place `backticks` around the portion of the script containing the < and > characters. For example, write if x `<>` 3 then...; this will pass <> as a literal text to the script processor. See symbolic expressions for further details.
- The script file contents for MS-DOS batch commands will be encoded using the current OEM code page of the target system; the script file contents for all other script types will use the current ANSI code page of the target system. You should bear this in mind when you specify the commands and their arguments. Don't use characters that might not be available in the current OEM or ANSI code page on the target system.
Standard output capture
The STDOUT and STDERR output of the script is captured by the installer and stored in the LastStdOut variable. The actual output depends on the script processor and the script itself; for an MS-DOS style batch script or PowerShell script LastStdOut will usually contain the complete console output of the script.
- To prevent the captured output of MS-DOS style batch scripts from showing extraneous information, use @echo off as the first command line in the script.
- The installer assumes that any output produced by the program on STDOUT or STDERR is encoded in the OEM code page (CP_OEMCP).
- LastStdOut is overwritten by the next Run Script or Run Program action.
For synchronous actions (see the Time out option), the installer stores the script processor's exit code in the LastExitCode variable; you can use this variable in the conditions of subsequent actions. The exit code is one of the following:
- If an error occurs when the script processor is started, LastExitCode is set to the (nonzero) Windows error code.
- Else if the action terminates prematurely due to a time-out, LastExitCode is set to 259 (STILL_ACTIVE).
- Else if a secondary process is specified (see Process 2 below), its exit code is stored.
- Else the exit code of the script processor itself is stored.
For asynchronous actions, LastExitCode is set to 0 if the script processor was started successfully, or to a nonzero Windows error code if an error occurred while starting the process.
The following attributes and options are available.
|Action name||Enter the name of the action. This name is only used in InstallMate and is not visible to the user.|
|Display text||Enter the localizable description of the action. This description is displayed in progress messages in the installer while the action is executing.|
|Localized||Check this box to localize the Display text field and use different descriptions for different languages.|
Select the desired script type from the drop-down list. The following choices are available:
Enter the commands that you want to execute in the script file. The command syntax depends on the script type; see Script type above.
For MS-DOS batch files, you can use internal command processor commands such as COPY and DEL, or any external commands.
Tip: If you want to use input or output redirection (<, >, or >>), be sure to place spaces on both sides of the redirection character to prevent InstallMate from interpreting them as symbolic variable references. Alternatively, surround them by `backticks`; this is also useful in VBScript and JScript expressions that use the <> character sequence: encoding this as `<>` prevents the installer from interpreting the brackets as an empty symbol reference. The backticks are removed before the script is passed to the script processor.
|Edit...||Click this button to open an Edit Text dialog box with the contents of the Commands field. This dialog box offers a larger edit window and more editing options than in-place editing in the Commands field.|
|Start in||Enter folder path from which the script must be run, or click ... (browse) to open the Select Installation Folder dialog box that allows you to select a folder.|
Select the action's execution mode from the drop-down list. The following choices are available:
|Not in silent mode||Check this box to skip the action if the installer is running in silent mode (/q command line option; TsuQuiet > 0); clear it to run the action in all modes.|
Select the desired visibility of the script process from the drop-down list. The following choices are available:
Note: This option only has effect on the script processor's own windows; it does not affect any secondary programs that are started by the script.
|Hide installer while
Check this box to hide the installer's main window while the action runs; clear the box to keep the installer's window visible.
Note: This option only has effect if the action runs synchronously, i.e., with the Time out option selected. During asynchronous actions, the installer remains visible.
Check this box and enter the time-out period in seconds to execute the action synchronously; clear it to execute the action asynchronously. If the action is executed synchronously, the installer will wait for it to complete; for an asynchronous action, the installer starts the action and then immediately continues.
Note: If the time-out period expires before the script processor terminates, the installer continues with its next action. However, the script processor itself is not terminated; it will remain active in the background until it terminates of itself or is forcefully terminated by the user or the system.
Enter the name of a secondary process to wait for, or leave empty to wait only for the script processor. This option only has effect if Time out is checked. It is useful if the script starts a secondary program and the script processor itself does not wait for those programs to terminate (this is the case with batch commands, for example; they only wait for the GUI program to start its message loop and process the initial messages, unless you use the start /wait command).
Note: If you specify a secondary process, then the Time out value applies to the total running time of both processes. InstallMate first waits for the script processor's process; after it terminates, it then waits for the remainder of the Time out period until the secondary process terminates.
Select the exit code handling from the drop-down list. The following choices are available:
The effectiveness of this option depends on the way the external script and its script processor are programmed. It is customary that successful completion of a script is indicated by an exit code of zero, and failure by a nonzero exit code. However, not all scripts or script processors comply with this convention. Furthermore, the Run Script action itself may set a nonzero exit code if it cannot start the external script or if the time-out period expires before the script terminates (see Exit codes).
Before you use the Exit code option, we recommend that you convince yourself that the external script and script processor in question return an appropriate exit code. If you want to use the script's exit code to terminate the installation or control the execution of subsequent actions, we suggest that you set the Exit code option to Ignore and use one of the following alternative approaches:
Check this box and enter the localizable prompt text to have InstallMate prompt the user before the action is run; clear it to run the action without prompting.
If you use this option, then the prompt is displayed in a dialog box with (localized versions of) Yes and No buttons. The action is executed if the user clicks Yes and skipped if No is clicked. You should phrase your prompt accordingly.
|Localized||Check this box to localize the Prompt field and use different prompts for different languages.|
|Condition||Enter the conditional expression that determines if the action will be executed, or leave empty for unconditional execution.|
|Disabled||Check this box to disable the action. A disabled action is not included in the installer and not checked during the build. You can use this option to remove actions temporarily from your installer without permanently deleting them. Disabled actions are shown with a grayed-out icon.|
|Platforms...||Click this button to open the Select Installation Platforms dialog box that allows you to select the Windows versions on which the action must be executed. This platform selection acts as an additional condition for the action.|