Windows Installer SDK Orca Documentation

Purpose

Orca is a Windows Installer package editor provided as part of the Windows Installer SDK and designed to provide full access to the database tables that compose a Windows Installer package. While Orca provides powerful access to all features of the Windows Installer, it is not intended to replace a full-featured package-authoring environment.

Where Applicable

Windows Installer enables the efficient installation and configuration of your products and applications. Orca can be used to create and edit Windows Installer databases. These include installation databases (.msi files), merge modules (.msm files), database patches (.msp files), database transforms (.mst files), validation modules (.cub files), and patch creation (.pcp files.) This document describes features available in Orca 3.0, provided as part of the Windows Installer SDK for the Windows Installer version 3.0. It is capable of creating and editing databases designed to use the new features of Windows Installer version 3.0. Other versions of Orca may differ in appearance, functionality, and behavior. You can use Orca 3.0 to edit packages created with earlier versions of the Windows Installer.

Developer Audience

This documentation is intended for software developers who want to make applications that use Windows Installer. Orca can be obtained by downloading and installing the Windows Installer SDK. It is not possible to download Orca separately. Setup developers that do not require full access to all the features of the Windows Installer should consider using one of the commercially available Windows Installer creation tools available from independent software vendors. In many cases it can be easier to create typical installations using one of these tools than with Orca.exe and the SDK tools.

Run-Time Requirements

The run-time requirements for Orca are the same as for the Windows Installer.

Windows Installer version 2.0 is contained in Microsoft Windows Server 2003 family and Windows XP. This technology is available as a redistributable for Windows Installer version 2.0, from the SDK Update site (http://www.microsoft.com/msdownload/platformsdk/sdkupdate/). Two packages are available at this site. One is for installing or upgrading to Windows Installer version 2.0 on Windows ME, Windows 98, and Windows 95. The other package is for installing or upgrading to Windows Installer version 2.0 on Windows 2000 and Windows NT 4.0. These packages should not be used to install or upgrade Windows Installer version 2.0 on Windows Server 2003 family and Windows XP.

Windows Installer version 3.0 requires Windows Server 2003, Windows XP, or Windows 2000 with Service Pack 3. Windows Installer version 3.0 is planned to be available as a free download shortly after the release of Software Update Services version 2.0.

Introduction to Orca

A description of the Orca editor.

Basic Editing Operations

Basic database editing.

Validating Packages

Validate installation databases.

Working with Transforms and Patches

Edit a patch or transform.

Using Dialog Preview

Inspect user interface dialog boxes without an installation.

Working with Merge Modules

Create and edit merge modules.

Customizing Orca

Customization options.


Introduction to Orca

This document describes features available in Orca 3.0, provided as part of the Platform SDK. Other versions of Orca may differ in appearance, functionality, and behavior.

Important Information

Orca provides direct access to the raw database tables and data streams that collectively define the installation logic for an application. For most editing operations, Orca performs little or no error checking and allows modifications to the database that are not logically consistent or are erroneous. Directly modifying an MSI or MST file using Orca without fully understanding the potential effects and side-effects of a change may result in an MSI or MST file that does not perform correctly.

While Orca allows the modification of all aspects of the package by direct editing or creation of a transform, the installation packages for some products are designed to work only with a specific subset of all possible customizations or only with transforms generated by a product-specific customization tool. Customizing a package designed in this manner by means of Orca may result in unexpected or erroneous behavior.


The Orca Window

A. Database Name.
The name of the database being edited is indicated in the window title.
B. Transform\Patch Name.
The name of the transform, patch or patches applied to the current database is indicated in the window title.
C. Menu.
The menu for Orca provides access to all Orca functionality.
D. Toolbar.
The toolbar provides quick access to a variety of commonly used options. A ToolTip provides a brief description of each button's functionality.
E. Table List Window.
The table list window shows a list of all tables in the database, tables added or dropped by a transform or patch, and tables that do not exist in the database but are listed as required by a validation error or warning.
F. Table Error Indicator.
A red bar in the table list window indicates a table that contains a validation error or warning.
G. Current Table Indicator.
A blue or yellow background in the table list indicates the currently selected table. The background is yellow if the table list window is active and the table has focus, otherwise the background is blue. Data from the currently selected table is displayed in the table view window. The colors used are configurable and may differ from the colors indicated here.
H. Modified Table Indicator.
A green bar in the table list window indicates a table that has been modified by a transform or patch.
I. Shadow Table.
A table that is required by validation but does not actually exist in the database is indicated by faded colors. When selected, no data appears in the view pane.
J. Validation Pane.
The validation pane lists errors from the most recent validation run and can be used to quickly change the table list window and table view window to indicate the location of a specific validation error.
K. Current Validation Error.
The selected row in the validation pane indicates the most recently chosen validation error.
L. Status Bar.
The status bar provides statistics about the currently selected objects in Orca.
M. Table View Window.
The table view window displays the contents of a table.
N. Added Row.
A row surrounded by a green box indicates a row added by a transform or patch.
O. Selected Row.
A row with a blue background indicates a currently selected row. The colors used are configurable and may differ from the colors indicated here.
P. Validation Error.
A cell in orange or red indicates a cell with a validation error. Orange text indicates a validation warning, red indicates a validation error.
Q. Active Cell.
The active cell (cell with input focus) is indicated by a yellow background. The colors used are configurable and may differ from the colors indicated here.
R. Table Count.
This portion of the status bar indicates the number of tables in the database.
S. Row Count.
This portion of the status bar indicates the number of rows in the current table.
T. Column Schema.
This portion of the status bar indicates the name and type of the current or most-recently selected column.


Navigating in Orca

Selecting a Table

To select a table, click on the table name in the left pane, or use the cursor keys while the table list is active to select a new table. The TAB button can be used to switch the active window between the table list and the table view.

As the selected table changes, the view in the table view window changes to reflect the contents of the currently selected table.

Only one table can be selected at a time.

Moving Between Cells

To change the focused cell in a table, use the cursor keys to move the focus indicator, or click on the desired cell.

To move the focused cell indicator without changing the selection state of any row, hold down the CTRL key while using the cursor keys to move to the new cell.

Selecting Rows

To select a row, click any cell in the row or use the cursor keys to move the focus indicator to the row in question.

To select a range of rows, select the first row. Then hold down the Shift key and use the cursor keys to expand or contract the range of selected rows, or hold down the Shift key and click on the last row in the range to be selected.

To select a set of non-contiguous rows, select the first row, then hold down the CTRL key while selecting additional rows.

Sorting Tables

Tables can be sorted in Orca by clicking the column header of a column to indicate the column to use as the basis for sorting.

Numeric columns are sorted in ascending numeric value, string columns in ascending string value. The string sort used by Orca is not locale-aware.

The case sensitivity of the sort operation can be changed by choosing Options… from the Tools menu and checking the Case-sensitive sort in table view option in the Display tab.

It is not possible to sort a table based on a binary data column.

Viewing Numeric Values in Hex

To view numeric values in a column in hexadecimal format, right-click on any cell in the column (or on the column header itself) and choose View in Hexadecimal. To view numeric values in the column in decimal again, right-click on any cell in the column (or on the column header itself) and choose View in Decimal.

Jumping to Error Locations

If there are validation errors in the database, click on a row in the Issue Pane to jump immediately to the location of the error. If a row is already selected in the Issue Pane, you can use the arrow keys to change which error is selected.

Only one error can be selected at a time.

Showing and Hiding Toolbars and Panes

To show or hide the toolbar, status bar and Issue Pane, choose Toolbar, Status Bar, or Issue Pane from the View menu. Hiding the Issue Pane does not delete any data from the pane.

Determining the Orca Version

To determine the version of Orca, choose About from the Help menu.


Basic Editing Operations

The following topics cover the basic editing operations in Orca:

  • Opening a Database
  • Editing Data
  • Manipulating Rows
  • Manipulating Tables
  • Editing the Summary Information Stream
  • Changing the Database Code Page
  • Searching For Data
  • Adjusting the Schema of a Table
  • Special Considerations when editing Databases


Opening a Database

To open a database in Orca, provide the database name on the command line:

Orca.exe <Database File>

A database can be opened once Orca is started by choosing Open… from the File menu, or by dragging a database file onto the Orca window.

Databases can be opened for write access or for read-only access. If the file being opened does not allow write access, the file is automatically opened read-only. Otherwise, the file can be opened read-only by selecting the Read Only option in the Open dialog box.

Merge modules can be opened and edited using the same techniques, however transforms cannot be opened using this method. Other types of files based on the MSI database format can also be edited in Orca. For example, PCP files (“Patch Creation Properties” files) and CUB Files (validation packages) are based on the MSI database format and can be edited in Orca.

When working with patch files, the metadata that describes the patch can be edited in the same manner as other database files. The actual changes to the product made by the patch can be viewed but cannot be edited using Orca. See Working with Transforms and Patches for more information about viewing a patch.


Editing Data

If a file is open for write access, a number of editing operations are possible.

  1. Editing a Cell

    To edit a cell in a database opened with write access, select the cell with the mouse or keyboard and press the Enter key to begin editing the cell. Alternately, you can double-click on the cell. You can then edit, cut or paste data from the clipboard into the cell.

    Once modifications are complete, choose another cell with the mouse or press the Enter key to finish editing the cell. Press the ESC key to abort the change.

    Orca does not support editing multiline string values in any cell.

  2. Editing Binary Data

    To edit a binary data column, select the cell with the mouse or keyboard, then press Enter Alternately, double-click on the cell.

    To read data from a file into the database cell, click Read binary from filename and enter the path to the file in the Filename text box. The Browse… button allows browsing of the file system to locate the file.

    To write data from the database to a file, click Write binary to filename and enter the path to the file in the Filename text box.

  3. Cut, Copy and Paste

    You can copy or paste data into a cell without having to edit the cell. Simply select the cell with the mouse or keyboard and choose Cut, Copy or Paste from the Edit menu.

    If data currently in the clipboard can not be pasted into the current cell, the Paste command is disabled.

    If the data in the clipboard is the wrong type for the cell (for example, pasting a string into a numeric cell), or if pasting clipboard data into the cell would result in a duplicate primary key, an error message appears and the paste operation fails.


Manipulating Rows

Several operations in Orca can affect an entire row of cells at the same time. Rows can be added, removed and duplicated. They can also be copied from table to table.

  1. Adding a Row

    To add a row to a table, choose Add Row… from the Tables menu, right-click anywhere in the table view, and choose Add Row, or double-click any empty space in the table view window. A dialog appears listing all columns in the table and the values for each column. The initial values are all empty. Primary key columns are indicated by a key icon to the left of the column name.

    The selected column can be edited by entering a value in the edit box. For binary data columns, the Browse button can be used to locate a binary file that contains the data for the column.

    Pressing Enter in the edit box, selects the next column in order and the up and down arrow keys can be used to move between columns. Clicking a row in the column list jumps directly to that row.

    Pressing Enter while editing the last column value for the row causes the row to be added to the table, or click the OK button to immediately add the row to the table.

    If the row cannot be added to the table, an error message is displayed and no change is made to the table.

  2. Dropping a Row

    To drop one or more rows, select the rows to be dropped and choose Drop Row(s) from the Tables menu, or select the rows and press the Delete key.

    To drop a single row, select the row and press the Delete key, or right-click on the row and choose Drop Row.

    Once a row has been dropped from the database, the data in that row is unrecoverable.

  3. Cut, Copy and Paste Rows

    To cut one or more rows from the database and place the row data on the clipboard, select the rows in the table view and choose Cut Row(s) from the Edit menu. The selected rows are removed from the database and placed on the clipboard.

    To copy one or more rows from the database onto the clipboard, select the rows in the table view and choose Copy Row(s) from the Edit menu. The selected rows are placed on the clipboard but not removed from the database.

    To paste rows from the clipboard, click any location in the table view and choose Paste Row(s) from the Edit menu. Rows are placed in the table based on data in the clipboard.

    If the rows to be pasted in the table have primary keys that collide with existing rows, a numeric value is appended to the value in the first primary key column to generate a unique primary key value before inserting the row into the database. If the primary key column is numeric, the numeric value is incremented until a unique primary key value is found.

    If the data in the clipboard is not in a format that can be pasted into the current table, the Paste Row(s) command is disabled.


Manipulating Tables

Several operations in Orca operate at the level of an entire table. These operations can often have significant effect on the database being edited and should be used with caution.

  1. Adding Tables from the Schema Database

    To add one or more tables, choose Add Table… from the Tables menu, or right-click anywhere in the table list and choose Add Table….

    A dialog box appears with a list of all tables that can be added to the database. Any table that already exists in the database does not appear in the list. The set of available tables is based on the schema database used by Orca. The default schema database contains the set of Windows Installer tables current at the time the version of Orca was released. Custom schema files can be used.

    Select the tables to create by placing a check mark in the box next to the name of the tables. Multiple tables can be created at once. Click OK to create the tables.

  2. Dropping Tables

    To drop a table from the database, select the table in the table list and choose Drop Table… from the Tables menu, or right-click on a table in the table list and choose Drop Table….

    Once a table has been dropped from the database, all data contained in the table is unrecoverable.

  3. Exporting Tables

    To export one or more tables to a text file in the standard IDT file format, choose Export Tables… from the Tables menu, or right-click on a table in the table list and choose Export Tables… from the shortcut menu.

    When the Export Tables dialog box appears, select the tables to export by placing a check next to each table to be exported. You can select all tables for export by clicking the Select All button, or deselect all tables by pressing the Clear All button. To invert the selection state of the tables, so that all selected tables become unselected, and all unselected tables become selected, click the Invert button.

    To specify a directory in which to place the IDT files, enter a path in the Output Directory text box. You can browse the system for a directory by clicking the Browse… button.

    Once the tables have been selected, click the OK button to export the tables. Each table is exported to an IDT file in the specified directory. If the table contains binary data from a binary data column, the binary data from the rows is exported to binary IBD files in a subdirectory of the specified path. The subdirectory derives its name from the name of the table being exported, and the IDT file for the table references the binary data files.

    Important: Orca exports tables to files named using the Short File Name (8.3) naming convention. If some of the tables selected are not unique within the first 8 characters, data from one table may overwrite the data file from other tables.

  4. Importing Tables

    Orca allows tables to be imported from IDT files into the current database. To import one or more IDT files, choose Import Tables… from the Tables menu, or right-click on a table in the table pane and choose Import Tables… from the shortcut menu.

    • Selecting Files for Import

      In the File dialog box, choose one or more IDT files to import into the current database. Multiple IDT files can be selected for simultaneous import. For best results, the code page of an imported IDT file must be compatible with the existing code page of the database. If the code pages are not compatible, the import operation fails.

      Important: Orca does not support changing the database codepage by importing the _ForceCodepage table.

    • Choosing the Action for Each Table

      Once the set of files to be imported has been chosen, Orca evaluates each of the IDT files and builds a list of tables to be imported into the current database, along with a default import action for each table.

      There are four possible actions to take for each table:

      Import
      The specified table is imported into the database in its entirety. This is the default action when the database does not already contain an existing table with the same name.
      Replace
      The specified table is imported into the database in its entirety, replacing an existing table. This is the default action when the database already contains an existing table with the same name and there is a conflict between the existing data and the data to be imported.
      Merge
      The specified table is imported into the database in its entirety, coexisting with an existing table. This is the default action when the database already contains an existing table with the same name, but there is no conflict between the existing data and the data to be imported.
      Skip
      The table is not imported into the database.

      To change the action taken for each table, select the table name from the list and choose the desired action for the table from the available options to the right of the table list. Actions that are not possible for a particular table due to existing data in the database are disabled.

      Important: MSI analyzes and imports files based on the table name encoded in the IDT file. If multiple files attempt to import to the same database table, the resulting state of the table is undefined.

      To import additional IDT files as part of the import operation, click Browse… and select the additional files to import.

      Once the desired action has been chosen for each table, click OK to import the tables into the database.

  5. Create Custom Tables

    Orca can create custom tables that are not a part of the standard MSI database schema. To add a custom table, choose Add Custom Table… from the Tables menu or right click anywhere in the table list and choose Add Custom Table….

    Each table must have at least one column and at least one primary key column. A new column can be added by pressing the New button. This generates a new column with a default name and column type. The Remove button removes the currently selected column. The order of columns can be changed by selecting a column and using the Move Up and Move Down buttons to adjust the column's position in the list.

    The name and schema of a column can be changed by selecting the column in the column list and editing the schema values.

    Note The width of Integer columns is not configurable.

    To create a string column with no length limit, enter 0 for the length value.

    Select the number of primary keys in the table using the Primary Keys field. A table must have at least one primary key column. Primary key columns must come before any non-primary key columns.

    Note When the order of columns is modified, a column can change from primary key to non-primary key based on its new position in the column order.


Editing the Summary Information Stream

To edit the Summary Information Stream for a database, choose Summary Information… from the View menu.

Orca does not list a platforms possibility that is not allowed by the current schema value. To select the Alpha platform, the schema of the database must be 100 or less. To select the Intel64 or AMD64 platforms, the schema must be 150 or greater. If the platform appears blank, the database is marked with an invalid combination of platform and schema and should be corrected.

To generate a new package code for the database, press the New GUID button. If Orca is set to automatically generate a unique package code each time the database is saved, this button is disabled. See "Automatic Package Code Generation" on the Database Settings page.


Changing the Database Code Page

To change the code page of the database, choose Tools… and Code Page… from the menu. The current code page is shown. To change the code page, enter the numeric code page ID and click OK.

Orca validates that all strings in the database can be represented in the new code page and changes the code page of the database to the new value. To skip the validation and force the database to a particular code page, select the Force the change without validating option. If you force the database to a code page Orca cannot detect strings in the database that cannot be represented in the specified code page. This can prevent the installation package from working correctly.

Note Not all code page values work with MSI. Orca prevents the database from using a code page that cannot be used with MSI.

For more information on localizing MSI files, see the Windows Installer SDK documentation.


Searching for Data

To search for data in a cell, choose Find from the Edit menu and enter the search string. Orca searches for the specified data beginning at the currently selected table, row, and cell (or the beginning of the database if no table is selected).

When matching data is found, the Table List and Table View windows automatically shift to display the correct cell.

To specify an exact match for the data in the cell, choose the Match whole word only option. If this option is not set, Orca flags any cell that contains the search string even if other data exists in the cell.

Orca does not search numeric cells or cells that contain binary data.


Adjusting the Schema of a Table

To modify the schema of an existing table, select the table in the table list and choose Adjust Schema… from the Table menu, or right click on the table and choose Adjust Table….

The order of columns in the table can be changed by selecting a column and modifying its position by pressing the Move Up or Move Down buttons. New columns can be added to the table by selecting the New button. Existing columns can be removed by selecting the column and pressing the Remove button.

Note When deleting a column, the original column and its values are marked for deletion and cannot be retrieved, even if a column with the same name and schema is created before pressing OK. If a column is accidentally removed from the table the schema editing operation should be cancelled before the changes are saved to the database.

The schema of a column can be changed by selecting the column in the column list and changing the name or type of the column in the Column Schema section. When modifying the schema of an existing table that contains data rows, not all changes to the table schema are possible if the table is not empty. For example, it is not possible to change a column from a string column to an integer column if there are rows that already contain string values. Similarly, columns that are currently nullable may not be changed to disallow 'null' values if there are rows in the table that contain 'null' in the column.

The number of primary keys in the table can be changed by increasing or decreasing the key column count. A table must have at least one primary key column. Columns are assigned as primary keys in the listed column order, beginning with the first column, and all primary key columns must be placed before non-primary key columns.

Note Although primary key columns can be added to a table at any time. Removing primary key columns by removing the entire column, decreasing the number of key columns in the table, or by shifting the order of columns in the table such that a primary key column is no longer a primary key column can lose data if the new key columns are no longer sufficient to guarantee uniqueness of the rows in the table. In this case, Orca detects the potential data loss and asks for the correct action to take.

  • Choose Cancel the schema change to cancel the operation and return the database table to its original schema.
  • Choose Generate new primary keys for the colliding rows to modify the primary key values for each row to ensure unique values. Modified rows are flagged in the table view for later analysis.
  • Choose Pick a row from each set and discard the extra rows, select one row from each set of colliding rows and discard any rows that are not unique in the new table schema.


Special Considerations when editing Databases

When editing a database in Orca, there are several considerations to keep in mind.

  • Database Size

    Much like a file system, an MSI database is subject to fragmentation. As a database is repeatedly edited, the size of the database file increases. To eliminate the fragmentation and generate a smaller MSI file, use the Save As… command to generate a new MSI file.

  • Embedded Streams and Storages

    When a database is saved using the Save As… or Save Transformed As… command, embedded binary streams (such as embedded cabinet files) are not saved to the new database unless they are part of a data row. Embedded sub-storages (nested install files) are never saved to the new database.

  • Language and Codepage Issues

    Orca is capable of editing databases in a variety of languages, however the system must support the codepage required. Therefore, using Orca with the Windows 95, Windows 98 and Windows Me systems may limit the functionality of Orca when editing some databases that contain localized strings.

    When displaying table data, Orca does not detect when the selected font does not support characters encoded in the database. Selecting a font that does not support the language or character set of a database may result in Orca displaying the data incorrectly.

    When editing a database or importing data files, Orca does not detect strings that are incompatible with the current codepage of the database. Entering or importing strings that cannot be represented in the codepage of the current database may result in incorrect package behavior.


Validating Packages

Orca provides a graphical interface to the package validation functionality available as part of the MSI SDK and in several third-party tools. Validation can flag many common problems in MSI packages by analyzing package data for invalid cells or combinations of cells that are not consistent.

Validation is performed by one or more Internal Consistency Evaluators (ICE)s, that are organized into CUB files. Several standard validators and CUB files are provided as part of the Platform SDK. Orca can also use custom validators and CUB files.

  • Choosing a CUB File

    You can select a CUB file for use during the validation run in three ways:

    • Select a CUB file from the drop-down list. The list contains all CUB files registered on the system for use in validation.
    • Type a full path to the CUB file in the edit control.
    • Click the "Browse" button and locate a CUB file.

    The default value for validation can be changed by choosing Options… from the Tools menu and changing the Default ICE File value on the Validation tab.

  • Selecting ICEs to Run

    You can limit the set of ICE validators that run from a particular CUB file by changing the value in the ICEs to Run field of the validation dialog. The set of validators to run can be specified in two ways:

    • Specifying no value selects the default set of ICEs from the CUB file.
    • A set of individual ICEs can be selected by specifying the ICE names, separated by a colon character (':'). The set of ICEs available depends on the CUB file selected.

    The default value for this field can be changed by choosing Options… from the Tools menu and changing the ICEs to Run value on the Validation tab.

  • Running Validation

    To run validation, click the Go button. Orca executes the specified validators in the selected CUB file, validating the current database, including any changes to the database that have not been saved.

  • Filtering Information Messages

    To not place information messages from the validators in the list of results, uncheck the Show "INFO" Messages option. This option can be toggled while validation is running, in which case, it affects messages generated from that time on but not messages that have already been generated.

    Warning and information messages can be filtered by default by selecting the appropriate options in the Tools\Options configuration dialog box on the Validation tab.

  • Placing Results on the Clipboard

    To copy the results of a validation run to the clipboard for pasting in another application, click the Copy Results button.

  • Using the Validation Pane

    When the validation dialog box is closed, all warnings and errors in the validation window are copied to the validation pane at the bottom of the Orca window. To show or hide the validation pane, choose Validation Pane from the View menu. Hiding the validation pane does not erase the contents.

    To jump to the location of an error, select the error by clicking on it or using the arrow keys in the window to move to the desired error. The table list and table view immediately jump to the exact location of the error that was reported by the validator.

    If a table or row that contains an error is deleted, any validation errors associated with that row are deleted from the validation pane.

    The data in the validation pane is replaced each time the database is validated.

  • Examining Table and Cell Errors

    To examine the errors associated with a specific cell, right-click on the cell and choose Errors…. The error information associated with the cell appears in a small dialog. If more than one error is associated with the cell, you can click the Previous and Next buttons to switch between the different errors.

    To examine the errors associated with a table but not a specific cell, right-click on the table name in the table list and choose Errors…. The error information associated with the table appears in a small dialog. If more than one error is associated with the table you can click the Previous and Next buttons to switch between the different errors.

    The information presented in the Errors dialog box is the same information available in the validation pane.

    If a table does not exist in the database but contains a validation warning or error (such warnings and errors usually indicate that the table or a value within the table is required but not present), a Shadow Table appears in the table list. This table is used to provide access to the validation errors or warnings associated with the table, but does not indicate the presence of the table in the database. When a shadow table is selected, the table view pane that normally displays the contents of the table does not contain any table information and indicates that the table does not exist in the database.

    If there are no errors associated with the cell or table, the Errors… option is disabled.

  • Cancelling Validation

    To cancel the validation, press the Cancel button. No additional validators run and a cancel request is sent to the currently running validator. Some ICE validators acknowledge the cancel request and stop immediately. Other validators run to completion before accepting the cancel request.


Working with Transforms and Patches

Transforms and patches provide a structure to represent the differences between two databases (for transforms) or between product installations (for patches).

For more information on working with transforms and patches, see:

  • Basic Patch and Transform Concepts
  • Understanding Database Changes
  • Working With Patches
  • Viewing and editing Transforms
  • Editing Patch SummaryInformation


Basic Patch and Transform Concepts

Transforms and patches require a base database for use as the starting point for the changes contained in the transform or patch. You must have a database open in Orca before you can work with a transform or patch. If no changes to the original database are required before working with the transform or patch, the base database can be opened read-only.

Once you have opened a transform or patch in Orca, the database becomes read-only and can no longer be edited. Changes to the database that have not been saved are not lost and can be saved at any point, but no additional changes can be made. Once the transform or patch has been closed, the database can be edited again unless it was originally opened read-only.


Understanding Database Changes

When working with a transform or patch, Orca indicates changes made by the transform or patch in both the table list and the views of each individual table. The way a change is indicated varies based on the type of change:

  • Single Cell Changes

    Changes to a single cell are indicated by a heavy green box around the modified cell. A table that contains a modified cell is indicated by a green bar in the table list.

    Hovering over a cell creates a ToolTip window that indicates the value of the cell in the original database. If the cell has been modified by multiple patches, only the original and final values are available—the intermediate values after each patch are not visible.

  • Added Rows

    Rows added to a table are indicated by a heavy green box around the new row. A table that contains an added row is indicated by a green bar in the table list.

  • Dropped Rows

    A row that has been dropped is indicated by a heavy green strikethrough line across the row. A table that contains a row that has been dropped is indicated by a green bar in the table list.

  • Added Tables

    A table that has been added by a transform is indicated by a heavy green box in the table list, as well as a heavy green box around each new row in the table.

  • Dropped Tables

    A table that has been dropped from the database is indicated by a heavy green strikethrough line across the table name in the table list as well as each row in the table.

  • Added Columns

    Columns that have been added to an existing table by a transform are indicated by green bars on either side of the column, spanning all rows of data. Adding columns to a table does not currently cause the table to be marked as modified in the table list.

  • Schema Changes

    Transforms do not allow dropping existing columns in a table. Instead, the table's schema must be redefined by dropping the existing table and adding a new table with the desired schema. When this action is performed, it is represented in Orca as a split table. A split table is a table that exists in both the base and transformed databases with the same name, but that must be represented in Orca as a combination of a table drop and table add because the schema differences are too significant to represent the changes in a single table.

    A split table is represented by two entries in the table list. One entry represents the original database table, contains data from the original database and is marked as a dropped table. The other table entry with the same name represents the modified data and is marked as an added table.

    Only the added table can be edited.

    Important: Although you can create a split table by editing the MSI file in Orca, split tables cannot be represented in a transform file. Attempting to generate a transform that contains a split table generates an error and does not create the transform.


Working With Patches

Use Orca to view the changes to a database made by a patch or multiple patches. Orca can also be used to edit the metadata that describes a patch. Orca cannot be used to create a patch or to edit the actual changes to a database made by a patch.

  • Editing a Patch

    To edit the metadata of a patch, open the patch by the same method used for an MSI database by choosing Open… from the File menu. Note that Orca can view but not edit the actual changes to the product made by the patch.

  • Viewing a Patch

    To view a patch, choose View Patch… from the Transform menu and select the patch to view.

    The patch is validated against the application requirements embedded in the patch. If the patch does not apply, an error is generated and the database is not modified.

  • Viewing Multiple Patches

    Multiple patches can be viewed simultaneously. To view multiple patches, repeatedly choose View Patch… from the Transform menu and select the next patch to view. Because the order of patch application is critical when validating the applicability rules of the patch, it is not possible to select multiple patches to apply simultaneously. Instead, choose View Patch… once for each patch to apply.

    Each patch is validated against the current state of the database (including any former patches) and applied if the application requirements are met.

    If multiple patches modify the same database cell, only the final result is shown in the Table View. The intermediate values (values after the application of each individual patch) are not shown.

  • Closing Patches

    To close all patches opened using View Patch…, choose Close Patch… from the Transform menu. All patches are closed and the database reverts to its state before any patches were applied. To close a patch opened to view, import, or export tables in a patch choose Close from the File Menu.


Editing Patch SummaryInformation

To edit the Summary Information Stream for a patch, open the patch for editing by choosing Open… from the File menu. Then choose Summary Information… from the View menu.

To automatically generate a new patch code for the patch, press the New GUID button.

To change the minimum version of the Windows Installer required to apply the patch, select the appropriate patch type from the Patch Type list.


Viewing and editing Transforms

Unlike patches, only one transform can be applied to a database at a time. However, Orca can be used to create and edit transform files.

Transforms in Orca can only be viewed and edited in conjunction with a base database, never independently. Thus, you must have a database open before you can view or edit a transform.

Once you have created a new transform or applied an existing transform, any edits made in Orca apply to the transformed version of the database and do not change the original database. You can make additional changes to the original database only after closing the transform.

  • Creating a new Transform

    To generate a new transform, choose New from the Transform menu. An empty, untitled transform is created for the current database.

    Any subsequent changes in Orca apply to the transform and do not affect the current database.

  • Opening an Existing Transform

    To open an existing transform, choose Apply Transform… from the Transform menu or drag and drop a transform file onto the Orca window. Any subsequent changes in Orca apply to the transform and do not affect the current database. Transforms themselves can be opened for read-only access as well, in which case editing operations in Orca are disabled.

    If the selected transform cannot be applied to the current database due to the transform's validation or error-handling flags, the transform is not opened. Orca can be set to ignore validation checks and errors during transform application by choosing Options… from the Tools menu and selecting the desired behavior on the Transform pane.

    Important: If Orca is set to ignore errors during transform application, portions of the transform are ignored during application because they do not apply to the current database. For example, the transform may contain instructions to modify a row that does not exist. If the transform is subsequently saved, the ignored portions of the original transform are lost and are not saved as part of the new transform.
  • Editing the Transform

    To edit a transform, simply make changes to the database. Modifications are automatically applied to the transform instead of the original database. It is not necessary to have write access to the original database when editing a transform.

    Important: While Orca allows the modification of all aspects of the package by direct editing or creation of a transform, the installation packages for some products are designed to work only with a specific subset of all possible customizations or only with transforms generated by a product-specific customization tool. Customizing a package designed in this manner with Orca can result in unexpected or erroneous behavior.
  • Transform Flags

    To change the validation and error behavior of the transform, choose Transform Properties from the Transforms menu and select the desired transform behavior.

    For information on the meaning of transform error and validation flags, please see the MSI documentation.

  • Generating the MST File

    To generate a transform file, choose Generate Transform... from the Transform menu and enter a file name. The transform file is created and contains any modifications to the base database.

    Validation and error flags for the transform are set using the options specified in the Transform Properties dialog box.

    Important: When generating a transform, the transform is based on the current state of the open MSI file. If the MSI file was modified in Orca since it was opened and has not been saved, the transform is generated using the modified database as the base for the transform, not the original copy on disk.
    Important: If Orca is set to ignore errors during transform application, portions of the transform are ignored during application because they do not apply to the current database. For example, the transform may contain instructions to modify a row that does not exist. If the transform is subsequently saved, the discarded portions of the original transform are lost and are not saved as part of the new transform.
  • Saving the Results of a Transform

    To save the results of applying a transform to a database, choose the Save Transformed As… option from the File menu.

    Saving the results of a transformed application does not open the new file. The original base database and transform remain open.


Using Dialog Preview

Dialog preview uses the dialog box preview functionality of MSI to allow inspection of the user interface dialog boxes from a package without performing an installation.

To launch the Dialog Preview window, choose Dialog Preview from the Tools menu. The Dialog Preview window appears, listing all dialog boxes authored in the database and indicating which buttons or controls trigger events that lead to other authored dialog boxes. Controls that do not result in the creation of a new dialog box are not listed.

To preview a dialog box, select the desired dialog box from the list and click the Preview button. You cannot preview an individual control. The dialog box appears as authored in the various Windows Installer user interface tables.

The controls in the Dialog Preview are inactive and do not function. It is not possible to follow a wizard sequence through the preview functionality available in Orca.

To close the dialog box, select a different dialog box and click the Preview button again. The original dialog box closes and the new dialog box appears. Click the Done button to close the authored dialog box and the preview window.


Working with Merge Modules

The following topics discuss the use of merge modules:

  • Merging a MSM Through the User Interface
  • Merging a MSM From the Command Line


Merging a MSM Through the User Interface

To merge a MSM into a database by using the interface, open the target database for write access and choose Merge Module… from the Tools menu or click the Merge Module… button on the toolbar.

  • Selecting a Merge Module and Language

    To select a merge module, enter a path in the edit box or click the Browse… button to locate a module. Write access to the module is not required.

    All modules must be opened in a specific language. Some modules support multiple languages and dialects, while others support more generic languages that encompass many dialects, and still other modules are language neutral. To specify the language used in opening the module, enter the numeric language ID in the Language field.

  • Specifying the Directory Layout

    The root directory for a merge specifies the location in the directory tree of the target database that becomes the root of the directory tree from the module. If no directory table is available, you cannot choose a root directory.

    To specify a root directory for the merge, select one of the provided directories. All directories currently in the Directory table of the merge module are available as a root directory.

    For information on the interaction of the directory tables of the merge module and target database, see the Platform SDK documentation.

  • Binding the MSM to the Feature Tree

    When merging a merge module into a target database, the module components must be associated with at least one feature. The installation actions on the selected feature control the installation of the components and thus resources from the module. Additionally, all advertisement information in the module (such as Shortcuts or CLSIDs) is associated with a feature.

    To specify the feature used for the target of advertisement data and to control the installation actions of the module's components, select a feature from the Primary Feature drop-down list. All features currently available in the Feature table are present in this list.

    In addition to the primary feature, components from the module can be associated with an arbitrary number of additional features. These additional features contribute to the decisions about when to install the resources from the module, but are not the target of any advertisement data from the module. To select additional features, check the box next to the feature name in the Additional Features list. All features currently available in the Feature table are present in this list.

    Selecting a feature as an additional feature when it has already been selected as the Primary has no additional effect on the merge process.

  • Specifying Options for Configurable Merge Modules

    Some modules expose additional configuration options through Configurable Merge Module options. The options provide the ability for the module user to more tightly bind the module to the target database or to further control aspects of the module's behavior.

    To use advanced configuration options, select the Edit Advanced Configuration Properties in this merge module.

    • Choosing Items to Configure

      Advanced configuration properties for the module are listed at the top of the window. To work with an item, select a property to configure by clicking on the entry in the list, or by using the cursor keys to select the item.

      Once an item is selected, details of the item appear in the lower portion of the window. The information provided is defined by the merge module and varies based on the type of item being configured.

      Orca does not provide functionality for accessing advanced help information contained in the item description.

    • Changing an Item Value

      To change the value for an item, uncheck the Use the Default Value for this item option and enter the desired value. Depending on the type of item being edited, selecting the value may involve entering text into the edit box, selecting an option from a list defined by the module or selecting a row from a table in the target database.

    • Continuing with the Merge

      To continue with the merge process after selecting the desired values for all items, click the OK button. To cancel the merge, click the Cancel button.

    • Remembering Previously Selected Options

      Orca remembers the options chosen for the most recently used merge modules. Orca pre-populates the configuration dialog with the options selected the last time the module was used. If a previously selected option is no longer valid due to changes in the database, the option uses the default value from the module.

      Options are remembered on a per-module basis, based on the module file name. The number of modules for which Orca remembers the options selected can be configured by choosing Options from the Tools menu and clicking the Merge Modules tab.

  • Handling Merge Conflicts and Errors

    If there are problems during the merge, Orca lists the problems encountered after the merge is complete. Orca lists:

    • Merge Conflicts
    • Language Errors
    • Module Exclusion Errors
    • Sequence Table Conflicts
    • File Extraction Problems
    • Invalid Configuration Parameters

    To accept the results of the merge despite the errors, click Accept. Otherwise, click Cancel to abort the merge.

    Important: Accepting the results of a failed merge may result in a database that does not function correctly.

    If Orca is set to display log output in a window during the merge process, errors and conflicts are indicated in the log and not in a conflict dialog box. After reviewing the log information, the merge can be accepted or canceled.

  • Extracting Files from a Merge Module

    Orca supports three different methods for extracting files contained in a merge module. Orca can extract the individual CAB file, extract the files into a module tree, and extract the files into a source image once it has been merged into a target database.

    Important: Orca does not import the CAB from a merge module into the database. The source layout and format must be determined based on the requirements of the product and the appropriate changes made to the database independently.

    • Extracting a CAB

      To extract the CAB file from a merge module, select the Extract Module CAB option and enter a file name in the Extract To: text box. The Browse… button can be used to search the system for a target file.

    • Extracting Files

      To extract the distinct files from a merge module, select the Extract Individual Files option and enter a path in the Extract To: text box. The Browse… button can be used to search the system for a target path.

      The target path is used as the root path for the extracted files. All files are extracted from the CAB file embedded in the module and placed in the specified path. The directory layout for the extracted files is based on the directory tree of the merge module.

    • Creating a Source Image

      To extract the distinct files from a merge module into an installable source image, select the Extract Source Image option and enter a path in the Extract To: text box. The Browse… button can be used to search the system for a target path.

      The target path is used as the root path for the extracted files, and should specify the root directory for the source image of the entire product, rather than the root of the merge module. All files are extracted from the CAB file embedded in the module and placed in the specified path. The directory layout for the extracted files is based on the directory tree of the product database once the merge is complete.

    • Using Long File Names

      To use long file names, check the Use Long File Names box. If this box is not checked, short file names are used for both directory names and file names from the module.

      Important: Using long file names when you create an installable image may limit the media formats or distribution methods for that image.
    • Adjusting the Media Table

      When you merge a merge module into a database by using the user interface, Orca does not update the Media table to reflect any new files added to the database.


Merging a MSM From the Command Line

Orca can merge a merge module from the command line, either integrated with the act of opening a database for editing or in silent mode for unattended operation.

Many merge module options can be specified from the command line.

Orca.exe [-q] -m <ModulePath> [-g <LangId>] [-c | -!]-f <Feature>[:Feature2…] [-r <Directory>] [-l <LogFile>] [-x <Path>] [-i <Path>] [-cab <CABPath>] [-lfn] [-configure <ResponseFile>] <DatabasePath>

  • Selecting a Database and UI Mode

    To specify the database that is the target of the merge, provide the file on the command line.... <DatabasePath>

    The database path must be the last option on the command line. To specify silent mode, use the

    ... -q ...

    option. If the merge operation is not performed in quiet mode, Orca prompts the user whether or not to open the resulting database for editing after completing the merge. The user is prompted only if the resultant database is saved in silent mode. See "Saving the Results of a Merge" below.

  • Selecting a Merge Module and Language

    To specify the module to merge into the target database, use the

    ... -m <ModulePath> ...

    option.

    All modules must be opened in a specific language. Some modules support multiple languages and dialects, while others support more generic languages that encompass many dialects, and still other modules are language neutral. To specify the language used in opening the module, use the

    ... -g <LangId> ...

    command-line option. If no language is specified, Orca attempts to determine the appropriate language by examining the SummaryInformation stream of the target database.

  • Specifying the Directory Layout

    The root directory for a merge specifies the location in the directory tree of the target database that becomes the root of the directory tree from the module.

    To specify the directory in the database used as the root for the directory structure of the module, use the

    ... -r <Directory> ...

    command-line option, where <Directory> is the primary key value from the Directory table.

    When merging a module through the command-line interface, the directory specified on the command line is not validated against the list of directories in the database. Specifying a directory that does not exist in the database does not generate an error but may result in incorrect behavior of the resultant MSI file.

    For information on the interaction of the directory tables of the merge module and target database, see the Platform SDK documentation.

  • Binding the MSM to the Feature Tree

    When merging a merge module into a target database, the module components must be associated with at least one feature. The installation actions on the selected feature controls the installation of the components and thus resources from the module. Additionally, all advertisement information in the module (such as Shortcuts or CLSIDs) is associated with a feature.

    To specify the feature used for the target of advertisement data and to control the installation actions of the module's components, use the

    ... -f <Feature> ...

    command-line option, where <Feature> is the primary key from the Feature table of the database.

    In addition to the primary feature, components from the module can be associated with an arbitrary number of additional features. These additional features contribute to the decisions about when to install the resources from the module, but are not the target of any advertisement data from the module. To specify secondary features on the command line, append the additional feature primary key values to the key for the main feature. All feature names are delimited by a colon (':') character.

    ... -f <Feature>[:<Feature2>...] ...

    When merging a module through the command-line interface, the features specified on the command line are not validated against the list of features in the database. Specifying a feature that does not exist in the database does not generate an error but may result in incorrect behavior of the resultant MSI file.

    For example, to connect the merge module to the feature "Orca" as the primary target of advertisement data and to the features "FullCUBFile" and "LogoCUBFile" as secondary features, use the following option:

    ... -f Orca:FullCUBFile:LogoCUBFile ...
  • Specifying Options for Configurable Merge Modules

    Some modules expose additional configuration options through configurable merge module options. The options provide the ability for the module user to more tightly bind the module to the target database or to further control aspects of the module's behavior. Configurable options can be specified from the command line by means of a text response file.

    To indicate the response file, use the

    ... -configure <ResponseFile> ...

    option on the command line.

    The response file is a text file that contains one or more lines with names and values separated by an equals sign ('='). The names are the item identifiers from the ModuleConfiguration table of the merge module. The valid values for each name vary based on the type of item being configured.

    Password=0SampleText=This is replacement text for this item.

    For more information on determining the type of an item and the valid values for each type of item, see the MSI documentation on configurable merge modules.

    Important: When merging a merge module from the command line, Orca performs a few checks on the values specified in the response file. If the values specified in the response file are invalid, it may result in a database that does not function correctly.
  • Extracting Files from a Merge Module

    Orca supports three different methods for extracting files contained in a merge module. Orca can extract the individual CAB file, extract the files into a module tree and extract the files into a source image once it has been merged into a target database.

    Important: Orca does not import the CAB from a merge module into the database. The source layout and format must be determined based on the requirements of the product and the appropriate changes made to the database independently.

    • Extracting a CAB

      To extract the CAB file from a merge module, use the

      ... -cab <FilePath> ...

      option on the command line, where <FilePath> is the desired path to the extracted CAB file.

    • Extracting Files

      To extract the individual files from a merge module, use the

      ... -x <Path> ...

      option on the command line, where <Path> is the desired path to the new directory tree.

      The specified path is used as the root path for the extracted files. All files are extracted from the CAB file embedded in the module and placed in the specified path. The directory layout for the extracted files is based on the directory tree of the merge module.

    • Creating a Source Image

      To extract the files from the module into an installable image, use the

      ... -i <Path> ...

      option on the command line, where <Path> is the desired path to the directory tree of the product.

      The specified path is used as the root path for the extracted files, and should specify the root directory for the source image of the entire product, rather than the root of the merge module. All files are extracted from the CAB file embedded in the module and placed in the specified path. The directory layout for the extracted files is based on the directory tree of the product database once the merge is complete.

    • Using Long File Names

      To specify the use of long file names during the extraction of files, use the

      ... -lfn ...

      option on the command line.

      If this option is not used short file names are used for both directory names and file names from the module.

      Important: Using long file names when you create an installable image may limit the media formats or distribution methods for that image.
    • Adjusting the Media Table

      When merging a merge module into a database from the command line, Orca attempts to adjust the Media table to include any added files by updating a row's LastSequence value to include the sequence numbers of any files added by the module.

      The Media table update is designed for simple applications with little or no complexity in media layout. The update assumes that the added files are contained in the same source layout and location as any other files in the package, and that there is only one Media table row for the package.

      Because of these assumptions, the changes made by Orca may be inappropriate for some packages with multiple Media entries. Package authors should always examine the Media table after a merge and adjust it as appropriate.

  • Saving the Results of a Merge

    To save the results of the merge, use the

    ... -c ...

    option to save the file only if there were no errors or merge conflicts during the merge. Use the

    ... -! ...

    option to save the results of a merge even if there were errors or conflicts during the merge process.

    Important: Saving the file even if there were errors during the merge process may result in incorrect behavior when installing the resultant file.
  • Writing a Log File

    To write a log file of the merge process, use the

    ... -l <LogFile> ...

    option on the command line, where <LogFile> is the desired log file path. Information from the merge operation is appended to any existing data in the log file.


Customizing Orca

Orca can be extensively customized by choosing Options from the Tools menu. Customization options are grouped by functionality on several different tabs.

For more information about customizing Orca, see:

  • Changing Display Options
  • Default Directories
  • Validation Settings
  • Merge Module Options
  • Transform Settings
  • Database Settings


Changing Display Options

The options Orca uses when displaying data can be changed from the Display tab of the Options dialog box.

  • Colors

    The colors used for normal text, a selected object and an object with focus can be modified by choosing the solid square box under either Foreground or Background for the desired type of text. A sample of text displayed using the selected colors is provided for each type of text.

  • Font

    The font used in the table list and table view windows can be modified by clicking the Change Font… button. The font selected is remembered for future sessions of Orca.

    Orca does not detect when the selected font does not support characters encoded in the database. Selecting a font that does not support the language or character set of a database may result in Orca displaying the data incorrectly.

  • Sorting Options

    To use a case-sensitive sort when sorting a table, select the Case Sensitive sort option. With a case sensitive sort, lowercase letters sort to a different location than uppercase letters. If this box is not checked, a case insensitive sort is used, where lowercase and uppercase letters are treated equivalently and are placed together after sorting.

  • Column Widths

    When a table is first displayed, Orca assigns a default column width in the user-interface to each column based on the data contained in that column. To restrict the total of the assigned column widths to the width of the table view window, select the Restrict initial column widths option. If this option is not selected, expanding the column widths to display all data in the column is preferred over having all columns fit in the window without a horizontal scroll bar. The assigned widths are used in the user-interface windows only and do not change the widths encoded in the database schema.

    Once the column widths of a table have been customized by manually dragging the column divider in the header to a specific width, Orca no longer adjusts the column widths for that table.


Default Directories

Default directories and file paths used by Orca can be configured in the Directories tab of the Options dialog box.

  • Default IDT Directory

    To specify a default directory when importing and exporting IDT files, enter the directory path in the Default IDT Import/Export Directory text box. The associated Browse… button can be used to browse the system for a directory.

  • ORCA.DAT File

    To specify a default table schema catalog, enter the directory path in the ORCA.DAT File text box. The associated Browse… button can be used to browse the system for a file. If no value is provided, Orca searches for an Orca.dat file in the directory that contains Orca.exe, the current directory, the system directory and the system PATH. The exact order in which directories are searched varies by system, but is equivalent to the order used by the SearchPath function.

    A schema database specified on the command line overrides the default value specified in this field.


Validation Settings

The behavior of Orca when running validation on a package can be customized on the Validation tab of the Options dialog box.

  • Default Validation Options

    The default ICE file and ICE set to run can be customized. For the default ICE file, a registered CUB file can be selected from the dropdown list, or a full path can be entered.

    For the default set of ICEs to run, any ICE, or set of ICEs can be specified. Separate multiple ICEs with a colon (':') character. If no value is specified, the default behavior is to execute the default set of ICEs from the selected CUB file.

  • Filtering Validation Messages

    Informational and warning messages from validators can be hidden by checking the two Suppress Message checkboxes. Warning and informational messages can be independently selected for filtering.

  • Resetting Results on Each Run

    If the Clear Results checkbox is checked, the results from a validation run are deleted before any subsequent run begins.

    If the Clear Results checkbox is not checked, the results from each validation run are appended to the results currently in the list.


Merge Module Options

The behavior of Orca when working with merge modules can be modified on the Merge Module tab.

  • Watching the MSM Log

    For troubleshooting purposes, it is sometimes advantageous to watch the process of merging the module into the database to gain detailed information about the location of failures. To cause Orca to show the merge process log in a window during the merge, select the Watch MSM log during merge process option.

    Due to limitations of the operating system, Orca does not provide the ability to watch the MSM log on Windows 95, Windows 98, or Windows Me.

  • Configurable MSM

    Select the Always configure Merge Modules when possible option to default to editing configurable merge module properties during a merge.

  • Configurable Module History

    To save the options selected during the merge of a configurable merge module for future merges that use the same module, enter the number of distinct modules for which to retain options.


Transform Settings

The validation and error handling behavior used when applying a transform to a database can be controlled on the Transform tab.

  • Transform Errors

    When applying a transform, some operations can fail due to differences between the base database used when generating the transform and the base database to which the transform is applied. A transform includes flags that indicate the transform author's desired behavior when an error is encountered.

    If the Ignore option is selected, Orca ignores the author's requested behavior and applies the transform regardless of any errors that might occur.

    If the Respect option is selected, Orca generates an error when applying the transform if a transform failure is detected and the transform author has indicated by way of the transform's embedded flags that the type of error encountered is fatal.

  • Transform Validation

    A transform includes a set of conditions that must be met before the transform can be successfully applied to a package. The conditions include checks on the product version, product code, upgrade code or product language. Orca's behavior when a validation check fails can be controlled from the Transform page.

    If the Ignore option is selected, Orca ignores any validation problems encountered when validating the transform against the current database.

    If the Prompt option is selected, Orca notifies the user when a validation check fails during transform application. The user can then choose whether or not to apply the transform to the database.

    If the Respect option is selected, Orca always generates an error when a validation check fails.


Database Settings

Some additional database settings can be customized on the Database tab of the Options dialog box.

  • Automatic Package Code Generation

    Select Generate a unique Package Code each time a database is saved. and Orca automatically generates a new GUID in the SummaryInformation stream of the database each time the file is saved.

  • Saving Embedded Streams

    By default, when saving a database to a new file with File and Save As…, Orca does not copy streams that are embedded in the database but not a member of any table. Select Copy embedded streams during 'Save As' to save streams to the new file when saving a database using the File with the Save As… option.

  • Database Security

    Databases can be marked with "read-only recommended" or "read-only enforced" security flags. By default, Orca ignores these security flags when opening a database. You can use the Database tab to choose the desired action Orca takes for each type of security flag:

    • Select Open Read/Write anyway to ignore the security flag and open the file.
    • Select Open and clear flag to open the database for read and write and clear the security flag.
    • Select Ask which Action to take to prompt each time a marked database is opened.
    • Select Open read-only to respect the security flag and open the database read-only.


Extending Orca

Using Custom Validation CUB Files

The list of CUB files listed in the validation dialog can easily be extended to include custom CUB files. The set of CUB files presented to the user is determined by enumerating an MSI qualified component category. The Qualifier column contains a unique string identifying the CUB file, which is not displayed to the user, and the AppData column contains a short descriptive text string for the CUB file that is used as the string in Orca's user-interface. The ComponentId (category) used to publish the components varies based on the platform targeted by the CUB file.
Platform | ComponentID (Category)
X86 | {DC441E1D-3ECB-4DCF-B0A5-791F9C0F4F5B}
IA64 | {17C2BAD5-F32B-4A0D-B5E1-813FF88DA1C5}
AMD64 | {519A931E-8E59-4425-9299-6449A938B8F1}

For more information on creating and installing a qualified component using the PublishComponent table, see the help topics "Using Qualified Components" and "PublishComponent Table".

Using a Custom Schema Database

To specify a custom schema database, use the ... -s <SchemaFile> ... option. A schema file can be used as the default schema file by choosing Options from the Tools menu and entering the file name in the Orca.dat text box of the Directories tab.


Orca Glossary

configurable merge module
A merge module that exposes a set of extended configuration options in a standard format. Orca reads the extended configuration options and allows selection of allowable values during the merge process.
internal consistency evaluator (ICE)
A DLL or script used to validate the consistency or correctness of a database as part of the package validation functionality.
merge module
A file based on an MSI database format that contains both installation information for a component and the resources for the component itself. Merge modules are not installable and are primarily used to distribute components to other setup packages.
split table
The system used in Orca to represent a table that exists in both the base database and resultant (transformed or patched) database with the same name, but with schemas so divergent that they can not be represented in a transform or patch. Split tables are represented by a pair of tables in the table list, one being the dropped table, the other the added table.
schema database
An MSI file used by Orca to define the tables and associated schemas that can be added with the Add Table command. Each version of Orca ships with a schema database file for the current version of MSI at the time that version was shipped. Custom schema catalogs can be specified.
shadow table
A table that appears in the Table List window, even though it does not exist in the database, to show that a validation error or warning indicates that the table (or row in the table) is required but is missing.
Table List window
The left pane of the Orca window that lists all tables in the database, all tables added or dropped by a transform and all tables that do not exist in the database but are listed as required by a validation error.
Table View window
The right pane of the Orca window that lists the data in the currently selected table.
transform
Template of the differences between two installer databases that can be applied to produce similar changes in other databases.
validation pane
The optional window at the bottom of the main Orca window that lists all validation errors for the current database and allows navigation to the database location of each error.


Topic Not Found

Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

    Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

    Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

    Remedy: Insert the MSDN Library CD into the CD-ROM drive.