MsiOpenDatabase Function

Windows Installer

MsiOpenDatabase Function

The MsiOpenDatabase function opens a database file for data access. This function returns a handle that should be closed using MsiCloseHandle.

Syntax

C++UINT MsiOpenDatabase(
  __in   LPCTSTR szDatabasePath,
  __in   LPCTSTR szPersist,
  __out  MSIHANDLE *phDatabase
);

Parameters

szDatabasePath [in]

Specifies the full path or relative path to the database file.

szPersist [in]

Receives the full path to the file or the persistence mode. You can use the szPersist parameter to direct the persistent output to a new file or to specify one of the following predefined persistence modes.

Value Meaning
MSIDBOPEN_CREATEDIRECT

Create a new database, direct mode read/write.

MSIDBOPEN_CREATE

Create a new database, transact mode read/write.

MSIDBOPEN_DIRECT

Open a database direct read/write without transaction.

MSIDBOPEN_READONLY

Open a database read-only, no persistent changes.

MSIDBOPEN_TRANSACT

Open a database read/write in transaction mode.

MSIDBOPEN_PATCHFILE

Add this flag to indicate a patch file.

 

phDatabase [out]

Pointer to the location of the returned database handle.

Return Value

The MsiOpenDatabase function returns the following values:

ERROR_CREATE_FAILED

The database could not be created.

ERROR_INVALID_PARAMETER

One of the parameters was invalid.

ERROR_OPEN_FAILED

The database could not be opened as requested.

ERROR_SUCCESS

The function succeeded.

Remarks

To make and save changes to a database first open the database in transaction (MSIDBOPEN_TRANSACT), create (MSIDBOPEN_CREATE or MSIDBOPEN_CREATEDIRECT), or direct (MSIDBOPEN_DIRECT) mode. After making the changes, always call MsiDatabaseCommit before closing the database handle. MsiDatabaseCommit flushes all buffers.

Always call MsiDatabaseCommit on a database that has been opened in direct mode (MSIDBOPEN_DIRECT or MSIDBOPEN_CREATEDIRECT) before closing the database's handle. Failure to do this may corrupt the database.

Because MsiOpenDatabase initiates database access, it cannot be used with a running installation.

Note that it is recommended to use variables of type PMSIHANDLE because the installer closes PMSIHANDLE objects as they go out of scope, whereas you must close MSIHANDLE objects by calling MsiCloseHandle. For more information see Use PMSIHANDLE instead of HANDLE section in the Windows Installer Best Practices.

Note  When a database is opened as the output of another database, the summary information stream of the output database is actually a read-only mirror of the original database, and, thus, cannot be changed. Additionally, it is not persisted with the database. To create or modify the summary information for the output database, it must be closed and reopened.

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 namesMsiOpenDatabaseW (Unicode) and MsiOpenDatabaseA (ANSI)

See Also

General Database Access Functions
A Database and Patch Example

Send comments about this topic to Microsoft

Build date: 8/13/2009

© 2009 Microsoft Corporation. All rights reserved.