Last modified: March 09, 2015
Applies to: Windows | Windows Server
The JetAttachDatabase function attaches a database file for use with a database instance. In order to use the database, it will need to be subsequently opened with JetOpenDatabase.
JET_ERR JET_API JetAttachDatabase( __in JET_SESID sesid, __in const tchar* szFilename, __in JET_GRBIT grbit );
The database session context to use for the API call.
The name of the database to attach.
A group of bits that specify zero or more of the following options.
If JET_paramEnableIndexChecking has been set, all indexes over Unicode data will be deleted. See the Remarks section for more details.
All indexes over Unicode data will be deleted, regardless of the setting of JET_paramEnableIndexChecking. See the Remarks section for more details.
Obsolete. Do not use.
Prevents modifications to the database.
This function returns the JET_ERR datatype with one of the following return codes. For more information about the possible ESE errors, see Extensible Storage Engine Errors and Error Handling Parameters.
The operation completed successfully.
Attaching a database is not allowed during a backup.
The database file specified by szFilename must be writable. The Read-Only attribute must not be set, and the running process must have sufficient privileges to write to the file.
The database file is already opened by another process.
An invalid path was given in szFilename. szFilename must be non-NULL and refer to a valid path.
The database file has already been attached by a different session.
The database engine cannot open the database file. The file may be in use by another process or the caller may not have sufficient privileges to open the file.
The file given in szFilename does not exist.
There is an error with the primary index. This may be from physical corruption (such as disk or memory corruption). It may also be returned when attaching a database last modified on an older operating system and the primary index is over a column with Unicode data. See the remarks for more information on indexes over Unicode data.
There is an error with a secondary index. This may be from physical corruption (such as disk or memory corruption). It may also be returned when attaching a database last modified on an older operating system and a secondary index is over a column with Unicode data. See the remarks for more information on indexes over Unicode data. Secondary indexes are completely rebuilt when a database is defragmented with an offline utility using the following command: esentutl -d.
Only a finite number of databases can be attached per instance. The limit is currently seven databases per instance.
A nonfatal warning indicating that the database file has already been attached by this session.
Calling JetAttachDatabase is equivalent to calling JetAttachDatabase2 and passing a value of zero, meaning there is no limit, for the cpgDatabaseSizeMax parameter.
Attaching a writable database (that is, if JET_bitDbReadOnly was not specified in the grbit parameter) will open the file exclusively at the operating system level. No other process will be able open the file. It is possible for multiple processes to attach a single database by opening them in read-only mode.
Different versions of Windows normalize Unicode text in different ways. That means indexes built under one version of Windows may not work on other versions.
Prior to Windows Server 2003, when the operating system version changed (including installation of a Service Pack), every index over Unicode data was in a potentially corrupt state.
Indexes created in Windows Server 2003 and later are flagged with the version of Unicode normalization with which they were built. Older indexes contain no version information. Most Unicode normalization changes consist of adding new characters, code points which were previously undefined are now defined and normalize differently. Thus, if binary data is stored in a Unicode column, it will normalize differently as new code points are defined.
As of Windows Server 2003, the ESE database engine tracks Unicode index entries that contain undefined code points. These can be used to fix an index when the set of defined Unicode characters changes.
These parameters control what happens when the ESE database engine attaches to a database that was last used under a different build of the operating system. The operating system version is stamped in the database header.
If JET_paramEnableIndexChecking is set to TRUE, and the database contains potentially corrupt indexes:
JetAttachDatabase will delete the potentially corrupt indexes if grbit contains JET_bitDbDeleteCorruptIndexes
JetAttachDatabasewill return an error if grbit does not contain JET_bitDbDeleteCorruptIndexes and there are indexes which need deletion.
If JET_paramEnableIndexChecking is set to FALSE:
JetAttachDatabase will ignore potentially corrupt indexes, and return JET_errSuccess (assuming there were no other errors).
Windows Server 2003 and later: If JET_paramEnableIndexChecking has not been reset, the internal fixup table will be used to fixup index entries. This may not fix all index corruptions but will be transparent to the application.
If the database was attached as read-only the index cannot be fixed or deleted. In this case, the API will instead return an error, such as JET_errSecondaryIndexCorrupted or JET_errPrimaryIndexCorrupted.
Requires Windows Vista, Windows XP, or Windows 2000 Professional.
Requires Windows Server 2008, Windows Server 2003, or Windows 2000 Server.
Declared in Esent.h.
Implemented as JetAddColumnW (Unicode) and JetAddColumnA (ANSI).