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:

Notes

Exit codes

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:

  1. If an error occurs when the program is started, LastExitCode is set to the (nonzero) Windows error code.
  2. Else if the action terminates prematurely due to a time-out, LastExitCode is set to 259 (STILL_ACTIVE).
  3. Else if a secondary process is specified (see Process 2 below), its exit code is stored.
  4. 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.

Note: LastExitCode is overwritten by the next action that runs an external program (including Run Script, Run DLL, Run Program, and Uninstall Product).

Attributes

The following attributes and options are available.

Attribute Description
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.
Target type

Choose the type of the target program or other file that the Run Program action must run.

The following target types are supported:

Target type Description
Installed file

Instructs the installer to run or open a file that is present on the target system, either because it was just installed, or because it was already present there. In the former case, the Run Program action must come after the predefined InstallFiles standard action in the MainInstall action sequence.

For this option, you must specify the desired target file in the Installed path field, below.

Tip: You can also use this option for targets that do not require a disk file, for example to open a URL such as https://installmate.com/

Source file

Instructs the installer to run or open a file that is part of the installer. This file will be stored in the installer package and be available as soon as the installer (or uninstaller) runs. In this case, the Run Program action can be executed at any time during the session.

For this option, you must specify the desired target file in the Source path field, below.

Installed path

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://installmate.com/. You can also enter any other path or protocol that the Windows Shell on the target system knows how to handle.

Source path

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.
Shell verb

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:

  • The target executable has an embedded manifest that requires elevation on Windows Vista and later. In this case, ShellExecute() will handle the required UAC interaction. Without this option, the Run Program action will fail with error code 740 ("Elevation required").
  • The target executable must be run with elevated rights. In this case, use the elevate (recommended) or runas verb.

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:

Verb Description
cplopen Runs the control panel applet indicated by Installed path. In this case, the Installed path field must contain the (unqualified) name of the control panel that you want to open, for example appwiz.cpl or inetcpl.cpl
edit Opens the file indicated by Installed path or Source path in its associated editor. This will fail if the file in question does not have an editor.
elevate

Pseudo-verb that opens the Installed path or Source path file in elevated mode. This verb allows you to run an external program in elevated mode where possible, prompting for the Administrator password only if necessary:

  • If the installer is running with elevated (Administrator) rights, the installer treats this verb as open;
  • If the installer is not running with elevated rights, the verb is converted to runas and the user will be prompted for the name and password of an Administrator account, or to give consent to UAC privilege elevation.

Note: During silent installs (using the /q command line option), the installer treats this verb as open to avoid user interaction. This may cause the action to fail.

explore Opens Windows Explorer to display the folder indicated by Installed path. For non-folder targets, the result depends on the target system.
find Opens Windows Explorer to start a search from the folder indicated by Installed path. For non-folder targets, the result depends on the target system.
open

Opens the Installed path or Source path file according to the Windows Shell rules. For executable programs, this means that the program will be executed; for non-executable files and for other targets such as URLs, the Windows Shell will try to start the associated file or protocol handler and open the target file with that.

Note: On Windows Vista and later, the open verb will prompt the user for UAC-controlled elevation if the target program has an embedded manifest that requires this and UAC is activated on the target system.

print Prints the file indicated by Installed path or Source path with its associated print handler. This will fail if the file in question does not have a print handler.
properties Displays the target path's properties, as per Windows Explorer practice.
runas

Prompts the user to select a different user account (typically the Administrator account) and to enter the associated password, or to give consent to UAC privilege elevation, then executes or opens the Installed path or Source path file with that account's identity and privileges. This verb is typically used to run a program with Administrator rights, but we recommend the use of elevate instead for that purpose.

Note: During silent installs (using the /q command line option), the installer treats this verb as open to avoid user interaction. This may cause the action to fail.

Run as standard user
(unelevate)

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).

Execute

Select the action's execution mode from the drop-down list. The following choices are available:

Execute Description
Immediate Execute the action when encountered in the action sequence. This is the default.
Commit Defer execution until the installation is committed. This option allows you to implement the "Commit" part of a two-phase commit protocol that is only executed if the installation was successful.
Rollback Defer execution until the installation is rolled back. This option allows you to implement the "Rollback" part of a two-phase commit protocol that is only executed if the installation fails and must be rolled back.
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.
Show program

Select the desired visibility of the external program from the drop-down list. The following choices are available:

Show Description
Normal Show the external program normally.
Minimized Show the external program minimized (only on the taskbar).
Maximized Show the external program maximized.
Hidden Hide the external program. Use this option with caution; if the external program requires user input, then the user will not be able to provide it and the process will hang until it is terminated by the user or the system.
Hide installer while
program runs

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.

Time out

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).

Process 2

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.

Exit code

Select the exit code handling from the drop-down list. The following choices are available:

Exit code Description
Ignore Ignore the program's exit code.
Fail if nonzero Terminate the parent action sequence and the fail the installation if the program's exit code is nonzero.
Fail if zero Terminate the parent action sequence and the fail the installation if the program's exit code is zero. This option is not recommended, because the exit code may be zero if the external program runs asynchronously and is started successfully.

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:

  • To terminate the installation if the external program returns a nonzero exit code, insert a MessageBox action immediately after the current Run Program action. Set the MessageBox action's Condition to LastExitCode <> 0 and set its Fail mode to Fail if run. Enter an appropriate error message in its Message field.
  • To execute or skip any subsequent actions depending on the external program's exit code, use the conditional expressions LastExitCode = 0 or LastExitCode <> 0, respectively, in the subsequent actions. Please note that the LastExitCode variable will be overwritten by the next Run DLL, Run Script, Run Program, and Uninstall Product action.
Prompt

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.

Related topics

Actions, Working with attribute panes