To help you detect and resolve potential problems in your installation project, you can perform several types of validation before you run the installation on a target system. The types of validation discussed in this white paper include: • Build warnings and errors • Internal Consistency Evaluator (ICE) validation • Update and patch validation Addressing these types of design-time validation errors will help you avoid errors. This white paper also shows you how InstallShield® helps you with design-time validation.

1. W H I T E PA P E R
Fixing Design-Time
Validation Errors
by Robert Dickau
Principal Technical Training Writer, Flexera Software

2. Fixing Design-Time Validation Errors
Introduction It is also assumed you are familiar with some of the wizards
To help you detect and resolve potential problems in your installation available with InstallShield, such as the Release Wizard and
project, you can perform several types of validation before you run Component Wizard.
the installation on a target system. The types of validation discussed
in this white paper include: • The Release Wizard, available under the Build menu and also
from the Releases view, lets you describe the properties—
• Build warnings and errors media type, compression settings, and so forth—of a release,
• Internal Consistency Evaluator (ICE) validation and then builds the specified release image.
• Update and patch validation • The Component Wizard, available by right-clicking a feature
in the Setup Design view, lets you create special types of
Addressing these types of design-time validation errors will help components, such as components for COM servers, fonts,
you avoid errors. This white paper also shows you how and Windows services.
InstallShield® helps you with design-time validation.
The InstallShield Help Library contains information about using
Using the InstallShield Environment every view and wizard in the InstallShield environment. The
This white paper frequently refers to the InstallShield development InstallShield Help Library is available when you press F1 with
environment. It is assumed you are familiar with the general layout any view selected; you can also select Contents from the Help
of the InstallShield interface, which contains a list of views with menu to view the help library.
which you can modify different portions of your installation project.
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.
For example, the General Information view is where you set general
product and project properties; the Setup Design view enables you Learn More about InstallShield
to edit the features, components, and component data used by your If you wish to learn more about the capabilities of
project; the Registry view enables you to modify the registry data InstallShield, please visit the Flexera Software Web site
installed by your installation program; and the Direct Editor view at www.flexerasoftware.com/installshield
gives you access to the raw MSI database tables.
2 Flexera Software: InstallShield White Paper Series

3. Validat ing MSI Updates and Patches
Build Warnings and Errors the locations of source files on the development system. Whenever
As InstallShield builds your project, status messages are displayed in you add a file to a component, InstallShield by default creates a
the output window at the bottom of the development environment. path variable or reuses an existing path variable to represent that
file’s location. If you move the source file, instead of having to
reestablish the file link, you can simply assign the path variable
a new value in the Path Variables view of the InstallShield
environment. (The InstallShield help library also describes registry-
based and environment variable–based path variables, with
which you can modify path variable values without having to
For a command-line build using IsCmdBld.exe, status messages are modify the project file.)
displayed at the command prompt.
In addition, if you have source directories that contain lists of files
If any errors or warnings occur, they are displayed in the Build tab that are continually changing, you can use dynamic file linking.
of the output window, as well as in the Tasks tab. The Tasks tab With dynamic linking, you specify a directory and optional file
contains links to the InstallShield Knowledge Base for the latest name masks for inclusion and exclusion. Each build process
information about resolving these warnings. (This requires a live then copies all of the matching files in the dynamic link into the
Internet connection.) corresponding component.
An important consideration regarding file linking is that a
dynamically linked file cannot be the key file of its component.
However, a component can contain any combination of static and
dynamic links, and therefore a solution is to set a statically linked
file as the key file, additionally marking the key file as an exclusion
to the dynamic link.
Addressing Build Errors and Warnings
Build errors and warnings typically refer to missing or unexpected Moreover, when using dynamic file linking, it is important to
source files or merge modules, but can refer to any condition that specify a “previous package” in the build settings to ensure File,
prevents a build from completing. For example, the build process Component, and Media table keys are synchronized between
reports error –1014 (“Cannot rename directory…”) if an installation builds. For more information, see the InstallShield help topic
inside the build folder is running, or if Windows Explorer or a “Upgrade Considerations”.
command prompt is pointing to the build folder.
Another error related to missing data on the build system is –1024
In addition, the InstallShield environment will prevent you from (“File not found. Cannot stream the file into the Binary file.”), which
entering some project settings that would cause the package to fail occurs if a file used by a custom action or dialog box (such as
at deployment time. For example, a project cannot use DATABASE a DLL or bitmap file) has been moved or deleted. Similarly, build
or PATCH as an internal Directory-table identifier—the way error –7017 occurs if your project includes merge modules or other
INSTALLDIR or SystemFolder is a Directory identifier—as these are redistributables that are not present on your build system. Other
reserved identifiers used by Windows Installer. If you try to define errors sometimes related to missing source files are –6271 (“File
a component destination folder with internal identifier DATABASE, file not found. An error occurred building the MsiFileHash table
the environment will rename the identifier to a valid value such as record…”) and –1501 (“Could not compress file into file.cab”).
DATABASE_DIR1. (If, however, you use the Direct Editor to define a
Directory called DATABASE or PATCH, the build process will report Design Issues and Build Warnings
error –6262.) In addition to issues related to source files, some build warnings
address design issues in your project.
TIP: When you manually search the InstallShield Knowledge Base
for a particular build warning or error number, omit the minus sign A deferred custom action must be placed between InstallInitialize
in the search. For example, instead of searching for “–1014”, and InstallFinalize in the Execute sequence of an installation. To
search for “1014”. help detect problems with improper placement of deferred actions,
the build process generates warning –6524 if it detects a deferred
Errors Regarding Missing Source Files custom action outside the range of InstallInitialize and InstallFinalize.
If the build process cannot find a source file, because it has
been renamed or deleted, the build process returns error –6103 TIP: By default, the build process will continue to completion even
(“Could not find file file”) and –1007 (“Cannot copy source file if any build errors occur. To cancel a build, you can click the Stop
to target directory”). Build toolbar button, or press Ctrl+Break. To specify always to stop
a build if an error occurs, you can pull down the Tools menu and
Two features of InstallShield that can help you work with source select Options; in the General tab, select the check box labeled
files are path variables and dynamic file linking. Path variables “Stop build process when first error is encountered”.
are variables used by the InstallShield build process to represent
Flexera Software: InstallShield White Paper Series 3

4. Validat ing MSI Updates and Patches
If you use the command-line build tool IsCmdBld, the -x switch To perform ICE validation using the command-line build tool
enables you to stop the build when the first error occurs, and the IsCmdBld, you can pass it the -m switch, followed by the path
-w switch lets you specify that build warnings should be treated to the validation file (.cub file) to use. The Microsoft .cub files are
as errors. stored in the Support subdirectory of the InstallShield distribution:
ICE Validation IsCmdBld -p ProjectName.ism -a FullBuild -r cdrom
Internal Consistency Evaluator (ICE) validation tests your MSI -m “C:Program FilesInstallShieldSupportdarice.cub”
database records for different types of data that can lead to
undesirable or unpredictable run-time behavior. There are over NOTE: There are separate merge module validation rules for merge
100 predefined ICE rules, testing for such conditions as duplicated module (.msm) projects. In the InstallShield environment, you can
component codes, missing properties and dialog boxes, and invalid select Build > Validate > Merge Module Validation Suite. From the
scheduling for various types of built-in and custom actions. (The command line, you can validate the database using the validation
graphical editors and referential integrity features of the InstallShield file mergemod.cub.
environment ensure that many types of ICE failures do not occur.)
Because ICE validation is performed on an MSI database and not You can specify that InstallShield should perform ICE validation
an ISM project file, your project must build successfully before you whenever you perform a build by pulling down the Tools menu,
can perform this type of validation. selecting Options, and then selecting the Validation tab. In the
Validation tab, select the check box labeled “Perform validation
You perform ICE validation in the InstallShield environment by using”, and then select the desired validation suite.
pulling down the Build menu, selecting Validate, and then selecting
Full MSI Validation Suite.
As with build errors and warnings, ICE errors and warnings appear
in the Tasks tab of the output window.
(The output window in InstallShield displays only ICE warnings and
errors. If you use another tool such as Orca to perform validation, Using the Customize button, you can additionally select rules within
you might see additional informational messages regarding the ICE a validation suite to skip.
validation process.)
The Windows Installer Help Library contains a summary of ICE
The Validate tab also lists any ICE warnings or errors that occur, messages in the topic “ICE Reference”; and also provides a specific
and provides a hyperlink to a text log file that contains the page for each ICE error, describing typical scenarios in which the
validation results. Validation log files are saved in a subdirectory error occurs and how to address the error.
called ValidationFiles, relative to the release folder.
In addition, the Direct Editor view highlights tables, records, and
fields related to the validation error or warning.
TIP: You can right-click an error or warning in the Tasks tab of the
output window and select “Go to Direct Editor”, which selects the
corresponding record in the Direct Editor view.
4 Flexera Software: InstallShield White Paper Series

5. Validat ing MSI Updates and Patches
ICE Warnings You Can Ignore ICE33 warnings can often be safely ignored, especially if you
The following paragraphs describe some ICE warnings that can be intend not to use Windows Installer advertisement functionality.
safely ignored.
Common ICE Errors
ICE36 and ARPPRODUCTICON The following sections describe some of the most common ICE
An advertised Windows Installer installation is one that installs warnings and errors.
application “entry points”, such as shortcuts, COM information, and
file-extension information on a user’s system, but does not install any ICE09 and SystemFolder Components
application files or registry information until the user invokes one of In legacy installation programs, application libraries (DLLs and
these entry points. Because the targets of these entry points will not other files) were commonly installed to the System folder during
initially be installed, Windows Installer requires any icon resources installation. Two problems with this behavior are: One of these
used by these entry points to be extracted and stored separately libraries would sometimes be installed over a newer version of
inside the MSI database. To this end, the Icon table is used to the library, and sometimes the library would inadvertently be
store icons used by advertiseable shortcuts, COM classes, and removed during uninstallation while other applications still
file extensions. required the library.
ICE36 warns if any icons in the Icon table appear to be unused, The Windows Installer file-overwrite rules (along with System
which means the MSI database is larger than necessary. However, File Protection) help prevent the first problem from occurring. To
some ICE validation suites overlook the possibility that resources avoid the problem of system libraries being removed when other
in the Icon table can refer to the ARPPRODUCTICON property, applications need them, a requirement is that any component
which specifies the icon to appear in the application’s Add or having a destination of [SystemFolder] be marked as Permanent.
Remove Programs entry. Therefore, ICE36 errors that refer to That is, any files installed to the System folder will permanently
ARPPRODUCTICON can safely be ignored. remain there. If a file needs to be removed during uninstallation,
it should be installed to a vendor-specific folder in the Common
ICE17 and InstallShield SQL Dialog Boxes Files folder.
ICE17 tests various characteristics of user-interface controls,
including checking that PushButton controls have associated control ICE09 verifies that a component with [SystemFolder] as its
events; icons used for controls are available in the Binary table; destination is marked permanent. To fix ICE09 errors, select the
and that ComboBox, ListBox, and RadioButton controls have referenced component in the Components view or Setup Design
corresponding data in the respective tables. view and set its Permanent property to Yes.
With InstallShield projects, validation will report an ICE17 ICE57 and Per-User Data
warning for the SQL dialog boxes SQLBrowse and SQLLogin, Some Windows Installer Directory properties can resolve to different
which create their data dynamically at run time. These warnings locations based on the type of installation being performed. For
can safely be ignored. example, the ProgramMenuFolder and DesktopFolder properties
resolve to a location available to all users of a system for a per-
ICE33 and the Registry Table machine installation, and to a location available only to the current
The self-registration process for COM servers—commonly called self- user for a per-user installation. Similarly, registry data you place
registering DLLs and OCXs—places the registration information in under the root key HKEY_USER_SELECTABLE is installed to either
the target system’s registry. COM information is typically written to HKEY_LOCAL_MACHINE or HKEY_CURRENT_USER based on
the keys HKCRCLSID{CLSID} and HKCRCom.Prog.Id when the the type of installation being performed. Whether a per-machine
DllRegisterServer entry point of the COM library is invoked. Calling or per-user installation is taking place depends on the value of
the DllRegisterServer function in a COM library is often called the ALLUSERS property, which is typically set by the Customer
“legacy self-registration”. Information dialog box.
For reasons related to various Windows Installer features (such A single Windows Installer component should not contain both
as advertisement, rollback, and per-user installations), it is per-machine and per-user data, because doing so can result in an
recommended that you use the COM-related MSI tables (Class, incomplete installation for other user accounts on the target system.
ProgId, and AppId) instead of registering the COM server directly. Instead, a single component should contain only per-machine
Even so, there is some COM information that does not fit into the data or only per-user data. ICE57 reports an error if a component
MSI COM-table schema (such as threading model information) that contains both types of data.
must be placed in the Registry table. ICE33 warnings appear for
this type of information. (These warnings often occur in projects that NOTE: ICE57 is related to ICE38, which validates that every
use Microsoft merge modules.) component installed to the user’s profile has a key path in
HKEY_CURRENT_USER; and is also related to ICE91, which
The same applies to file-extension information: On a target system, reports a warning for resources are being installed to a per-user-only
file-association information is ultimately written to the keys HKCR. location (such as AppDataFolder), which can cause errors for a
ext and HKCRExt.Prog.Id, but for MSI advertisement should be per-machine installation.
placed in the Extension, Verb, and ProgId tables.
Flexera Software: InstallShield White Paper Series 5

6. Validat ing MSI Updates and Patches
ICE44 and Deleted Dialog Boxes Tools menu, select Options, select the Preferences tab, and clear
The flow of dialog boxes in a Windows Installer project is handled the check box labeled “Uninstall before installing”.
by the NewDialog control events on the Next and Back buttons of
each dialog box. To reorder dialog boxes, you should adjust the For a complete list of errors and their descriptions, see the
arguments of the NewDialog control events for the Back and Next InstallShield Help Library topic “Validators”.
buttons for the affected dialogs. If you simply delete a dialog box
from the Dialogs view, the validation process will return an ICE44 Summary
error, which indicates that the target of a NewDialog control event This white paper discusses types of validation you can perform
does not exist in the project. Fixing ICE44 errors avoids Windows before you run the installation on a target system. Addressing
Installer run-time error 2803. these types of design-time validation errors will help you avoid
errors. This white paper also shows you how InstallShield helps
For other ICE warnings and errors, you should consult the Windows you with design-time validation.
Installer Help Library and the InstallShield Knowledge Base, as ICE
failures tend to be very specific.
Begin a Free Evaluation of InstallShield
TIP: You can search your project for a particular string in the Direct You can download a free trial version of InstallShield from
Editor view. Pressing Ctrl+F opens a standard Find panel, with which the Flexera Software Web site at:
you can search the currently selected table or all tables for a given www.flexerasoftware.com/installshield/eval
string.
An advanced technique is to create custom ICE validation rules.
Want to learn more best practices for building quality
Upgrade and Patch Validation installations?
Another type of validation performed by the InstallShield build Join an InstallShield training class – visit
process is validation that tests for common errors in authoring an www.flexerasoftware.com/training for available classes.
update installation. The errors and warnings displayed differ for
major upgrades, minor upgrades, and patches. Also, if you have a critical installation project but are short
on developer bandwidth or expertise, Flexera Software’s
TIP: A first step for addressing many problems related to updates Professional Services team can help. Learn more at:
and patches is to use the Patch Optimization setting in the Release www.flexerasoftware.com/services/consulting/software-
Wizard. In the Advanced Settings panel of the Release Wizard, in installations.htm.
the “Previous package” field, enter the path to the MSI database for
the previous release of your project. Using this setting ensures that
certain types of dynamic data in the File, Component, and Media
tables is compatible between builds.
Some of the common upgrade and patch validation failures are:
• Val004: Displays an error if a change to an existing
component’s files will prevent the component from being
updated in a minor upgrade.
• Val006: Displays an error if a minor upgrade is being
performed when a major upgrade should be; for example,
because a component has been deleted or moved in the
product tree.
• Val008: Displays an error if a record in the Upgrade table for a
major upgrade contains invalid data.
By default, upgrade and patch validation is performed each time
you build your project. You can also manually perform this type of
validation by pulling down the Build menu, selecting Validate, and
then selecting Upgrade Validation Wizard.
When you test an update project from the InstallShield environment,
by default clicking the Run toolbar button causes any version of the
product already on the system to be uninstalled. To properly test
update installations from the InstallShield environment, pull down the
6 Flexera Software: InstallShield White Paper Series

7. Flexera Software LLC Schaumburg United Kingdom (Europe, Japan (Asia, For more office locations visit:
1000 East Woodfield Road, (Global Headquarters): Middle East Headquarters): Pacific Headquarters): www.flexerasoftware.com
Suite 400 +1 800-809-5659 +44 870-871-1111 +81 3-4360-8291
Schaumburg, IL 60173 USA +44 870-873-6300
Copyright © 2011 Flexera Software LLC. All other brand and product names mentioned herein may be the trademarks and registered trademarks of their respective owners.
IA_WP_Time-Validation_Oct11