Run Program action

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.

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:

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:

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

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:

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

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.