MsiDatabaseGenerateTransform Function

Windows Installer

MsiDatabaseGenerateTransform Function

The MsiDatabaseGenerateTransform function generates a transform file of differences between two databases. A transform is a way of recording changes to a database without altering the original database. You can also use MsiDatabaseGenerateTransform to test whether two databases are identical without creating a transform.

Syntax

C++UINT MsiDatabaseGenerateTransform(
  __in  MSIHANDLE hDatabase,
  __in  MSIHANDLE hDatabaseReference,
  __in  LPCTSTR szTransformFile,
  __in  int iReserved1,
  __in  int iReserved2
);

Parameters

hDatabase [in]

Handle to the database obtained from MsiOpenDatabase that includes the changes.

hDatabaseReference [in]

Handle to the database obtained from MsiOpenDatabase that does not include the changes.

szTransformFile [in]

A null-terminated string that specifies the name of the transform file being generated. This parameter can be null. If szTransformFile is null, you can use MsiDatabaseGenerateTransform to test whether two databases are identical without creating a transform. If the databases are identical, the function returns ERROR_NO_DATA. If the databases are different the function returns NOERROR.

iReserved1 [in]

This is a reserved argument and must be set to 0.

iReserved2 [in]

This is a reserved argument and must be set to 0.

Return Value

The MsiDatabaseGenerateTransform function returns one of the following values:

ERROR_NO_DATA

If szTransform is null, this value is returned if the two databases are identical. No transform file is generated.

ERROR_CREATE_FAILED

The storage for the transform file could not be created.

ERROR_INSTALL_TRANSFORM_FAILURE

The transform could not be generated.

ERROR_INVALID_HANDLE

An invalid or inactive handle was supplied.

ERROR_INVALID_PARAMETER

An invalid parameter was passed to the function.

ERROR_SUCCESS

The function succeeded.

NOERROR

If szTransformFile is null, this is returned if the two databases are different.

Remarks

To generate a difference file between two databases, use the MsiDatabaseGenerateTransform function. A transform contains information regarding insertion and deletion of columns and rows. The validation flags are stored in the summary information stream of the transform file.

For tables that exist in both databases, the only difference between the two schemas that is allowed is the addition of columns to the end of the reference table. You cannot add primary key columns to a table or change the order or names or column definitions of the existing columns as defined in the base table. In other words, if neither table contains data and columns are removed from the reference table, the resulting table is identical to the base table.

Because the list delimiter for transforms, sources and patches is a semicolon, this character should not be used for filenames or paths.

This function does not generate a Summary Information stream. Use MsiCreateTransformSummaryInfo to create the stream for an existing transform.

If szTransformFile is null, you can test whether two databases are identical without creating a transform. If the databases are identical, ERROR_NO_DATA is returned, NOERROR is returned if differences are found.

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

VersionWindows 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
HeaderMsiquery.h
LibraryMsi.lib
DLLMsi.dll
Unicode and ANSI namesMsiDatabaseGenerateTransformW (Unicode) and MsiDatabaseGenerateTransformA (ANSI)

See Also

Database Management Functions
Database Transforms

Send comments about this topic to Microsoft

Build date: 8/13/2009

© 2009 Microsoft Corporation. All rights reserved.