The MsiDatabaseMerge function merges two databases together, which allows duplicate rows.

Syntax

C++UINT MsiDatabaseMerge(
  __in  MSIHANDLE hDatabase,
  __in  MSIHANDLE hDatabaseMerge,
  __in  LPCTSTR szTableName
);

Parameters

hDatabase [in]

The handle to the database obtained from MsiOpenDatabase.

hDatabaseMerge [in]

The handle to the database obtained from MsiOpenDatabase to merge into the base database.

szTableName [in]

The name of the table to receive merge conflict information.

Return Value

The MsiDatabaseMerge function returns one of the following values:

Return code	Description
ERROR_FUNCTION_FAILED	Row merge conflicts were reported.
ERROR_INVALID_HANDLE	An invalid or inactive handle was supplied.
ERROR_INVALID_TABLE	An invalid table was supplied.
ERROR_SUCCESS	The function succeeded.
ERROR_DATATYPE_MISMATCH	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.

Requirements

Version	Windows Installer 5.0 on 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, Windows XP, and Windows 2000
Header	Msiquery.h
Library	Msi.lib
DLL	Msi.dll
Unicode and ANSI names	MsiDatabaseMergeW (Unicode) and MsiDatabaseMergeA (ANSI)

See Also

Column Definition Format

Database Management Functions

Send comments about this topic to Microsoft

Build date: 8/13/2009