LaunchApplication

InstallShield 2019 » InstallScript Language Reference

The LaunchApplication function launches and optionally waits for the specified application.

LaunchApplication uses either the Windows API function CreateProcess or the Windows API function ShellExecuteEx (if nOptions includes LAAW_OPTION_USE_SHELLEXECUTE) to launch the specified application. After the application is launched, if the LAAW_OPTION_WAIT or LAAW_OPTION_WAIT_INCL_CHILD options are specified, the installation calls WaitForApplication to wait for the application to terminate; once the process has completed or the specified timeout value has elapsed, the installation continues.

Syntax

LaunchApplication( byval string szProgram, byval string szCmdLine, byval string szDirectory, byval number nShowWindow, byval number nTimeOut, byval number nOptions );

Parameters

LaunchApplication Parameters

Parameter

Description

szProgram

Specifies the complete path and file name of the application to be launched.

If nOptions does not include LAAW_OPTION_USE_SHELLEXECUTE, you can instead specify the file name of the application to be launched in the szCmdLine parameter; if you do so, pass an empty string ("") in the szProgram parameter.

The szProgram parameter supports URLs only if the LAAW_OPTION_USE_SHELLEXECUTE option is used.

szCmdLine

Specifies the command-line parameters to pass to the launched application. To launch the application with no command-line parameters, pass a null string ("").

If nOptions does not include LAAW_OPTION_USE_SHELLEXECUTE, you can also specify the file name of the application to be launched in the szCmdLine parameter; if you do so, be sure to do the following:

•

Separate the path to the application and the command line with a single space.

•

If the fully qualified name of the application includes long folder names and/or a long file name, pass it to LongPathToQuote before adding it to szCmdLine. For example:

szApplicationPath = WINDIR ^ "Notepad.exe";

szApplicationCmdLine = SRCDIR ^ "Readme.txt";

LongPathToQuote( szApplicationPath, TRUE );

szCmdLine = szApplicationPath + " " + szApplicationCmdLine;

szDirectory

Specifies the working directory for the application. Note that if an empty string ("") is specified (and LAAW_OPTION_USE_SHELLEXECUTE is not specified), the function passes NULL to CreateProcess instead of an empty string.

nShowWindow

Specifies the initial window state of the application as passed to CreateProcess in the wShowWindow parameter of the STARTUPINFO structure, or passed to ShellExecuteEx in the nShow parameter of the SHELLEXECUTEINFO structure (if LAAW_OPTION_USE_SHELLEXECUTE is specified). You can specify any documented value for the aforementioned functions; some values are predefined in ISRTWindows.h:

•

SW_FORCEMINIMIZE

•

SW_HIDE

•

SW_MAX

•

SW_MAXIMIZE

•

SW_MINIMIZE

•

SW_NORMAL

•

SW_RESTORE

•

SW_SHOW

•

SW_SHOWDEFAULT

•

SW_SHOWMAXIMIZED

•

SW_SHOWMINIMIZED

•

SW_SHOWMINNOACTIVE

•

SW_SHOWNA

•

SW_SHOWNOACTIVATE

•

SW_SHOWNORMAL

nTimeOut

Specifies the nTimeOut value (in milliseconds) passed to the WaitForApplication function. Note that if you do not specify LAAW_OPTION_WAIT, the specified value is ignored.

nOptions

Specifies various options, including whether the installation should wait for the launched application to terminate before continuing.

Pass one of the following predefined constants in this parameter. You can combine these constants by using the bitwise OR operator ( | ), with the following exceptions: you cannot combine LAAW_OPTION_NOWAIT with LAAW_OPTION_WAIT, and you cannot combine LAAW_OPTION_HIDDEN, LAAW_OPTION_MINIMIZED, and LAAW_OPTION_MAXIMIZED.

•

LAAW_OPTION_USE_SHELLEXECUTE—Indicates that the function should call the Windows API function ShellExecuteEx instead of calling CreateProcess to launch the application.

•

LAAW_OPTION_NOWAIT—Passed through the function to WaitForApplication. Note that using this parameter is equivalent to calling the function LaunchApp.

•

LAAW_OPTION_WAIT—Passed through the function to WaitForApplication.

•

LAAW_OPTION_USE_CALLBACK—Passed through the function to WaitForApplication.

•

LAAW_OPTION_SET_BATCH_INSTALL—Specifies that the function internally sets BATCH_INSTALL to a non-zero value if it detects that the launched application causes a change that requires a reboot, such as updating the RunOnce key. The function attempts to determine this by checking the state of the system before launching the specified application and then comparing the current system state after launching the application (and waiting for the application to complete if LAAW_OPTION_WAIT is specified.) This flag can be used when launching third-party installations that do not return status information indicating that a reboot is needed.

LAAW_OPTION_SET_BATCH_INSTALL is available for InstallScript event–driven code in InstallScript and InstallScript MSI projects. It does not have any effect in InstallScript custom actions.

•

LAAW_OPTION_SHOW_HOURGLASS—Specifies that the cursor changes to an hourglass while the launched application is running.

•

LAAW_OPTION_WAIT_INCL_CHILD—Passed through the function to WaitForApplication.

nOptions (cont.)

Note • When LAAW_OPTION_WAIT_INCL_CHILD is used, the function detects and waits for only direct child processes of the launched process—not for any additional child processes that are launched by child processes of the initially launched process.

For details about using LAAW_OPTION_USE_SHELLEXECUTE with LAAW_OPTION_WAIT_INCL_CHILD, see the Additional Information.

This parameter also supports the following options, but they are no longer recommended:

•

LAAW_OPTION_HIDDEN—Specifies that the launched application's main window is initially hidden.

•

LAAW_OPTION_MINIMIZED—Specifies that the launched application's main window is initially minimized.

•

LAAW_OPTION_MAXIMIZED—Specifies that the launched application's main window is initially maximized.

•

LAAW_OPTION_NO_CHANGEDIRECTORY—This is obsolete. This parameter is ignored.

•

LAAW_OPTION_CHANGEDIRECTORY—Specifies that LaunchApplication should temporarily update the current directory of the installation to that of the application about to be launched. By default, LaunchApplication does not modify the current directory of the installation. Note that LaunchApplication resets the current directory of the installation back to the original value before LaunchApplication returns.

Note • Calling LaunchAppAndWait instead of LaunchApplication automatically includes this option.

•

LAAW_OPTION_FIXUP_PROGRAM —Specifies that LaunchApplication should call LongPathFromShortPath on szProgram in order to ensure that the call to CreateProcess or ShellExecuteEx works correctly. In most cases, this should not be needed.

Note • Calling LaunchAppAndWait instead of LaunchApplication automatically includes this option.

Return Values

LaunchApplication Return Values
Return Value	Description
ISERR_SUCCESS
< ISERR_SUCCESS	Indicates that the application was not launched successfully. Note • If the application cannot be launched, the LAAW_PARAMETERS system variable’s nLaunchResult member contains the result of calling the Windows API function GetLastError after the CreateProcess or ShellExecuteEx call. If the function is successful and the LAAW_OPTION_WAIT option was specified, the LAAW_PARAMETERS system variable’s nLaunchResult member contains the return code of the launched application.

Additional Information

•

If you are not using LAAW_OPTION_USE_SHELLEXECUTE, update the LAAW_STARTUPINFO system variable before calling LaunchApplication to customize the behavior of the application.

If you are using LAAW_OPTION_USE_SHELLEXECUTE, customize the LAAW_SHELLEXECUTEINFO structure to customize the behavior of the application.

If you are using LAAW_OPTION_USE_SHELLEXECUTE on systems running Windows Vista or later and you want to launch the application using the full administrator account (similar to right-clicking the executable file to be run and clicking Run as Administrator), set LAAW_SHELLEXECUTEVERB to runas before using LaunchApplication in your script:

LAAW_SHELLEXECUTEVERB = "runas";

This ensures that the application is always run with full administrator privileges regardless of whether the application to be launched has an application manifest with relevant settings. Note that this may trigger a User Account Control (UAC) prompt for consent or credentials.

On systems running operating systems earlier than Windows Vista, if runas is used, a Run As dialog box is displayed. The behavior is similar to right-clicking the executable file to be run and clicking Run As. This dialog box enables the end user to select the user account that should be used to run the application.

•

To obtain identification information about the launched process, use the LAAW_PROCESS_INFORMATION system variable or the LAAW_SHELLEXECUTEINFO system variable (if you are using LAAW_OPTION_USE_SHELLEXECUTE).

•

Note that if you are using LAAW_OPTION_USE_SHELLEXECUTE, the LAAW_PROCESS_INFORMATION is not used, except for the hProcess member. The hProcess member is updated to the process handle of the launched process (from the LAAW_SHELLEXECUTEINFO.hProcess member).

•

ShellExecuteEx does not return the process ID of the launched process. Thus, if LAAW_OPTION_USE_SHELLEXECUTE is used, the LAAW_OPTION_WAIT_INCL_CHILD option works only if the Windows API GetProcessId is available so that the function can determine the process ID. According to the Windows API documentation, GetProcessId is available on Windows XP SP1 and later and Windows Server 2003 and later. If this API is not available, LAAW_OPTION_WAIT_INCL_CHILD behaves as LAAW_OPTION_WAIT.

•

When the installation is run from any removable media, such as a CD or a DVD, the Setup.exe file on Disk1 may not be available during the entire installation. (If Setup.exe becomes unavailable while it is running, the operating system sometimes displays a prompt to request that the end user insert the correct disk, and this may cause the installation to fail.) Therefore, to avoid this problem, the Setup.exe file is copied to a Temp folder, and the installation is relaunched from there. The original Setup.exe then terminates. However, when this happens, LaunchApplication behaves as if the installation has completed, and it does not wait.

To avoid this issue, you may want to use the /clone_wait parameter when you are launching the child installation; when this occurs, the launched installation keeps the original launched process running, and the parent installation then waits. Note, however, that this may cause problems if the original CD containing Setup.exe is not available throughout the entire installation. This includes multiple-CD installations, where the first CD is not available during some parts of the installation.

The only other way to avoid this problem is to add code that determines the ID of the child processes of the launched process and wait for the child process to complete.

LaunchApplication

InstallShield 2019 Help Library

April 2019