JetAttachDatabase Function

Applies to: Windows | Windows Server

JetAttachDatabase Function

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
    );

Parameters

sesid

The database session context to use for the API call.

szFilename

The name of the database to attach.

grbit

A group of bits that specify zero or more of the following options.

Return Value

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.

Remarks

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.

The database file is detached using JetDetachDatabase or JetDetachDatabase2.

Index-checking parameters

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.

Requirements

See Also

Extensible Storage Engine Files
JET_ERR
JET_GRBIT
JET_SESID
JET_TABLEID
JetAttachDatabase2
JetCreateDatabase
JetDetachDatabase
JetDetachDatabase2
JetOpenDatabase
JetSetSystemParameter