by Robert Dickau, Principal Technical Training Writer, Flexera Software
Because Windows Installer installations do not contain an explicit script, the debugging techniques are different from those generally used with programming languages. The techniques described in this white paper include:
- Investigating Windows Installer error codes
- Generating and interpreting Windows Installer log files
- Using the InstallShield MSI Debugger
This white paper also discusses how InstallShield® helps you with run-time logging and debugging.
Learn More about InstallShield
If you wish to learn more about the capabilities of InstallShield, please visit the Flexera Software Web site at www.flexerasoftware.com/installshield
Using the InstallShield Environment
This white paper frequently refers to the InstallShield development environment. It is assumed you are familiar with the general layout of the InstallShield interface, which contains a list of views with which you can modify different portions of your installation project.
For example, the General Information view is where you set general product and project properties; the Setup Design view enables you to edit the features, components, and component data used by your project; the Registry view enables you to modify the registry data installed by your installation program; and the Direct Editor view gives you access to the raw MSI database tables.
It is also assumed you are familiar with some of the wizards available with InstallShield, such as the Release Wizard and Component Wizard.
- The Release Wizard, available under the Build menu and also from the Releases view, lets you describe the properties—media type, compression settings, and so forth—of a release, and then builds the specified release image.
- The Component Wizard, available by right-clicking a feature in the Setup Design view, lets you create special types of components, such as components for COM servers, fonts, and Windows services.
The InstallShield Help Library contains information about using every view and wizard in the InstallShield environment. The help library is available when you press F1 with any view selected; you can also select Contents from the Help menu to view the help library.
In addition to the graphical environment, InstallShield provides several tools for modifying and building projects from the command line or an external script. For example, to build a project from the command line, batch file, or other automated process, you can use the executable IsCmdBld.exe. The IsCmdBld executable is located in the System subdirectory of the InstallShield distribution directory.
To rebuild a project, you pass IsCmdBld the project file path, the product configuration name, and the release name that you want to rebuild. A sample command appears as follows:
iscmdbld -p C:\ProductName.ism -a BuildConfig -r ReleaseName
In addition, InstallShield provides an Automation interface, with which you can modify the contents of a project file without using the graphical environment.
Windows Installer Run-Time Errors
If Windows Installer encounters a fatal error at deployment time, an error dialog box similar to the following is displayed. The error dialog box displays a numeric error code, along with a description of the error. After the user dismisses the error dialog box, Windows Installer displays the SetupCompleteError dialog box, which informs the user that no system changes have taken place.
In the InstallShield Dialogs view, the error dialog box is called SetupError, and the text of each error message is taken from the Error table of the MSI database. For a complete list of built-in Windows Installer error codes and descriptions, see the Windows Installer Help Library topic “Windows Installer Error Messages”.
The following sections describe the causes and resolutions of some of the most common Windows Installer error codes.
Error 2762 and Deferred Actions
Deferred custom actions must be scheduled between the standard InstallInitialize and InstallFinalize actions, which enclose the Windows Installer script-generation process. (The InstallShield build process reports build warning –6524 for this error, and the ICE validation process reports an ICE77 error.) If you encounter Windows Installer error 2762, you should either move your deferred action somewhere between InstallInitialize and InstallFinalize, or modify it to use immediate execution.
Errors 1720–1723 and Failed Custom Actions
By default, Windows Installer will exit the installation program if a custom action fails. When using executable and DLL custom actions, for example, failure means that the EXE or DLL returned a nonzero value. If a custom action fails, Windows Installer reports one of the error codes from 1720 through 1723.
If you are the author of the custom action executable or DLL, you should modify it to return a zero value (in C code, you can use the constant ERROR_SUCCESS) to indicate success. For a VBScript action function, return the constant IDOK (value 1) to indicate success. To enable the installation and a DLL or script custom action to communicate, you should use properties instead of return values to pass values back and forth.
If you are not the author of the custom action source, you can modify the Return Processing setting in the action properties to ignore the return code.
Error 2732 and the Directory Table
The Directory table contains the values of properties used as component destinations and locations of existing files. The values of Directory-table properties, such as SystemFolder and ProgramFilesFolder, are evaluated during the standard costing operations, which occur when the actions from CostInitialize through CostFinalize run. Because Directory-table property values are unavailable until these actions run, any custom actions that refer to Directory properties will cause the installation to fail with error 2732. For example, if you have a launch-an-executable action that launches Notepad.exe from WindowsFolder, you must schedule the action after the CostFinalize action to avoid error 2732.
Error 1327 and Hard-Coded Drive Letters
As a rule, you should use Windows Installer properties to refer to the locations of special directories on the target system. For example, instead of installing directly to “C:\Program Files\”, you should use the property [ProgramFilesFolder]. In some cases, however, it might be necessary to hard-code the destination for some files used in the installation. At run time, if Windows Installer is unable to find the drive letter, it will return error 1327.
In addition, error 1327 can occur on some systems if the locations of such system folders as MyPicturesFolder are not defined in the target system’s registry, or point to nonexistent directories.
Similarly, error 1606 (“Could not access location…”) can occur if the installation refers to a network resource that is not available when the installation is running.
Error 1406 and the ProductVersion Property
Windows Installer reports error 1406 if the installer is unable to write data to the registry, often because of insufficient privileges or an invalid key being specified. For example, Windows does not allow a subkey to be created directly under HKEY_LOCAL_ MACHINE.
A less obvious cause of error 1406 is an invalid ProductVersion format. Windows Installer expects the product version to be of the form a.b.c, where a, b, and c are all numbers. If the ProductVersion property contains any alphabetic characters, as in the value “1.0.beta”, Windows Installer reports error 1406. In this case, the product version should be modified to a strictly numeric value.
Errors 2727 and the Directory Table
The locations of destination directories—such as INSTALLDIR and SystemFolder—on the target system are defined by entries in the Directory table of the MSI database. If a component’s destination directory does not appear in the Directory table, however, Windows Installer reports error 2727.