Run Program action
The Run Program action runs an external program or opens a document file through its Windows Shell association. You can also use it to open a web page or anything else that the Windows Shell knows how to handle.
Standard output capture
The installer will automatically capture any STDOUT and STDERR output produced by the external program in the LastStdout variable. Note that only programs that are started through CreateProcess() allow output redirection and that STDOUT and STDERR are typically only used by console mode programs. This implies that:
- Any Run Program action that uses the Shell verb option (see below) will not have its STDOUT or STDERR output redirected.
- Any Run Program action that runs a Windows GUI program (i.e., not a console mode program) will not normally produce any STDOUT or STDERR output. (Non-console programs can write to their STDOUT and STDERR handles if those handles are valid, but very few do so.)
- 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 external program'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 program 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 program itself is stored.
For asynchronous actions, LastExitCode is set to 0 if the program was started successfully, or to a nonzero Windows error code if an error occurred while starting the program.
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.|
Choose the type of the target program or other file that the Run Program action must run.
The following target types are supported:
Enter the installation path to the program to run or document file to open, or use the button to browse for a file or compose a target path that uses symbolic variable references.
To open a web page, specify the fully qualified URL including the protocol specifier, for example https://tarma.com/. You can also enter any other path or protocol that the Windows Shell on the target system knows how to handle.
Enter the source path (on your own system) to the program to run or document file to open, or click ... (browse) to open the standard Open dialog box that allows you to select a file.
The file in question will be stored in the installer and is available at any time during installation or removal of your product. If your project contains multiple Run Program actions that all refer to the same source file, then that source file is only included once and is shared by all actions that use it.
|Arguments||Enter the arguments for the program. Be sure to enclose any arguments that contain (or might expand to contain) spaces in quotes, for example "argument with spaces" or "<INSTALLDIR>".|
|Do not log arguments||Check this box to prevent the Arguments from being logged in the installer's log file; clear it to write the arguments to the log file when the action is executed. This option is mainly useful if the Arguments field contains sensitive information such as an embedded password.|
|Start in||Enter folder path from which the program must start, or click ... (browse) to open the Select Installation Folder dialog box that allows you to select a folder.|
Check this box to use the Windows ShellExecute() function to run or open the external program or document file; clear it to run the program directly through CreateProcess().
This option is required if Installed path or Source path specifies a non-executable file or a URL, for example a text file, HTML file, or web page URL. It is optional for executable files; in that case we recommend that you use it if any of the following applies:
If the Shell verb option is checked you must enter the shell verb to execute. These verbs are passed to the Windows ShellExecute() function, so the precise effect of each verb depends on the configuration of the target system.
Note: Some shell verbs are only supported if you use Installed path (i.e., the Target type option is set to Installed file).
The following shell verbs are typically supported on most systems, although not for all file types:
|Run as standard user
Check this box to use the Windows ShellExecute() function to run the program, but in the context of the original (unelevated) user instead of the (elevated) installer context.
This option is useful, for example, to start your application at the end of the installation but run it as the original user (the one who started the installer) instead of the installer's user account, which is usually an Administrator account.
Note: Due to implementation limitations, the Time out option (see below) does not have any effect if you use the Run as standard user option, unless you also specify the name of the program plus extension (not the full path) in the Process 2 field (below).
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 external program from the drop-down list. The following choices are available:
|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 1: If the time-out period expires before the external program terminates, the installer continues with its next action. However, the external program 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.
Note 2: Due to implementation limitations, the Time out option does not have any effect if you use the Run as standard user option (see earlier), unless you also specify the name of the program plus extension (not the full path) in the Process 2 field (below).
Enter the name of a secondary process to wait for, or leave empty to wait only for the Installed path or Source path process. This option only has effect if Time out is checked. It is useful if the external program starts a secondary program that must complete before the installer continues.
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 Installed path or Source path process; after it terminates, it then waits for the remainder of the Time out period until the secondary process terminates or the time out duration is exceeded.
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 program is programmed. It is customary that successful completion of a program is indicated by an exit code of zero, and failure by a nonzero exit code. However, not all programs comply with this convention. Furthermore, the Run Program action itself may set a nonzero exit code if it cannot start the external program or if the time-out period expires before the program terminates (see Exit codes).
Before you use the Exit code option, we recommend that you convince yourself that the external program in question returns an appropriate exit code. If you want to use the program'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.|