DoInstall
InstallShield 2024 » InstallScript Language Reference
Project:
| • | InstallScript |
| • | InstallScript MSI |
The DoInstall function launches another InstallShield installation that has a valid setup executable file (.exe). The second installation is executed immediately when this function is called. The third parameter, nOptions, specifies various options, including whether the installation should wait until the launched application terminates before continuing.
Note:DoInstall cannot be used directly to launch a .msi file. In addition, because DoInstall adds command-line parameters that are specific to InstallShield installations, DoInstall should not be used to launch a non-InstallShield installation. To launch a non-InstallShield installation, use the LaunchAppllication function.
Syntax
DoInstall ( byval string szSetupExe, byval string szCmdLine, byval number nOptions );
Parameters
|
Parameter |
Description |
||||||||||||||||||
|
szSetupExe |
Specifies the fully qualified name—including a drive designation and complete path—of the setup executable file to be launched. Alternatively, you can specify the compiled script file of the installation to be launched. For InstallScript MSI installations, you can specify the installation’s .msi package. Note that in order to be able to use DoInstall, your installation must include a valid setup executable file named Setup.exe, or an alternative name, as described in Additional Information. |
||||||||||||||||||
|
szCmdLine |
Specifies the command line for the launched installation. You can specify any valid startup InstallShield command line for this parameter. Note that DoInstall automatically adds some command-line switches, depending on the nOptions specified. Note:Unlike with previous versions of InstallShield, if you are passing command-line parameters to a child InstallScript MSI installation, you must pass these options through the /z parameter (as when launching the installation directly). |
||||||||||||||||||
|
nOptions |
Specifies options for launching the installation. You can specify any valid LaunchApplication option, including:
You can also specify some additional options that apply only to DoInstall:
If this option is not specified, DoInstall automatically hides the initialization user interface of the child installation by using the /hide_progress option.
By default, DoInstall adds the /l switch to szCmdLine so that the launched installation runs in the same language as the launching installation. Note that if the child installation does not support the language in which the parent installation is running (as determined by calling Is(LANGUAGE_SUPPORTED)), the /l switch is not added.
By default, DoInstall automatically uses the LAAW_OPTION_SET_BATCH_INSTALL option. You can combine these constants by using the bitwise OR operator ( | ). Note that combining DOINSTALL_OPTION_NOSETBATCHINSTALL with LAAW_OPTION_SET_BATCH_INSTALL may lead to unexpected results. |
Return Values
|
Return Value |
Description |
|
0 |
If DoInstall was called with LAAW_OPTION_WAIT as the third argument, the installation launched by DoInstall terminated successfully. 0 is always returned when DoInstall is called with LAAW_OPTION_NOWAIT as the third argument. Control resumes in the calling installation with the statement that follows the DoInstall function. |
|
ISERR_SETUP_CANCELED |
The InstallScript installation launched by DoInstall with LAAW_OPTION WAIT as the third argument exited with the abort keyword. This usually indicates that the user canceled the installation. |
|
-3 |
The InstallScript MSI installation launched by DoInstall with LAAW_OPTION WAIT as the third argument exited with the abort keyword. This usually indicates that the user canceled the installation. |
|
All other negative values |
An unspecified error has occurred. You can obtain the error message text associated with a large negative return value—for example, -2147024891 (0x80070005)—by calling FormatMessage. |
| • | By default, DoInstall automatically attempts to launch the specified setup executable file. If a non-executable file name is specified in szSetupExe, the function attempts to launch Setup.exe in the specified folder. If the installation’s executable file has a name other than Setup, the launched installation’s Setup.ini file must have the new name of Setup.exe in the [Startup] section’s LauncherName key. |
Project:If you specify a value for the Setup File Name setting for a release in the Releases view of an InstallScript MSI project and then build the release, InstallShield automatically adds file name value to Setup.ini. If you rename the setup launcher executable file in an InstallScript project, you must add the name to the Setup.ini file manually.
| • | 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, DoInstall 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.
See Also