MsiDatabaseMergeW function (msiquery.h)
The MsiDatabaseMerge function merges two databases together, which allows duplicate rows.
Syntax
UINT MsiDatabaseMergeW(
[in] MSIHANDLE hDatabase,
[in] MSIHANDLE hDatabaseMerge,
[in] LPCWSTR szTableName
);
Parameters
[in] hDatabase
The handle to the database obtained from MsiOpenDatabase.
[in] hDatabaseMerge
The handle to the database obtained from MsiOpenDatabase to merge into the base database.
[in] szTableName
The name of the table to receive merge conflict information.
Return value
The MsiDatabaseMerge function returns one of the following values:
| Return code | Description |
|---|---|
|
Row merge conflicts were reported. |
|
An invalid or inactive handle was supplied. |
|
An invalid table was supplied. |
|
The function succeeded. |
|
Schema difference between the two databases. |
Remarks
The MsiDatabaseMerge function and the Merge method of the Database object cannot be used to merge a module that is included in the installation package. They should not be used to merge Merge Modules into a Windows Installer package. To include a merge module in an installation package, authors of installation packages should follow the guidelines that are described in the Applying Merge Modules topic.
MsiDatabaseMerge does not copy over embedded Cabinet Files or embedded transforms from the reference database into the target database. Embedded data streams that are listed in the Binary Table or Icon Table are copied from the reference database to the target database. Storage embedded in the reference database are not copied to the target database.
The MsiDatabaseMerge function merges the data of two databases. These databases must have the same code page. MsiDatabaseMerge fails if any tables or rows in the databases conflict. A conflict exists if the data in any row in the first database differs from the data in the corresponding row of the second database. Corresponding rows are in the same table of both databases and have the same primary key in both databases. The tables of non-conflicting databases must have the same number of primary keys, same number of columns, same column types, same column names, and the same data in rows with identical primary keys. Temporary columns however don't matter in the column count and corresponding tables can have a different number of temporary columns without creating conflict as long as the persistent columns match.
If the number, type, or name of columns in corresponding tables are different, the schema of the two databases are incompatible and the installer stops processing tables and the merge fails. The installer checks that the two databases have the same schema before checking for row merge conflicts. If ERROR_DATATYPE_MISMATCH is returned, you are guaranteed that the databases have not been changed.
If the data in particular rows differ, this is a row merge conflict, the installer returns ERROR_FUNCTION_FAILED and creates a new table named szTableName. The first column of this table is the name of the table having the conflict. The second column gives the number of rows in the table having the conflict. The table that reports conflicts appears as follows.
| Column | Type | Key | Nullable |
|---|---|---|---|
| Table | Text | Y | N |
| NumRowMergeConflicts | Integer | N |
This function cannot be called from custom actions. A call to this function from a custom action causes the function to fail.
If the function fails, you can obtain extended error information by using MsiGetLastErrorRecord.
Note
The msiquery.h header defines MsiDatabaseMerge as an alias that automatically selects the ANSI or Unicode version of this function based on the definition of the UNICODE preprocessor constant. Mixing usage of the encoding-neutral alias with code that is not encoding-neutral can lead to mismatches that result in compilation or runtime errors. For more information, see Conventions for Function Prototypes.
Requirements
| Requirement | Value |
|---|---|
| Minimum supported client | Windows Installer 5.0 on Windows Server 2012, Windows 8, Windows Server 2008 R2 or Windows 7. Windows Installer 4.0 or Windows Installer 4.5 on Windows Server 2008 or Windows Vista. Windows Installer on Windows Server 2003 or Windows XP |
| Target Platform | Windows |
| Header | msiquery.h |
| Library | Msi.lib |
| DLL | Msi.dll |