IJetCompact

The IJetCompact interface exposes maintenance operations on the OLE DB Provider for Microsoft Jet. Compact is the only supported method on this interface. It does both database compaction and repair.

This interface is defined under the DataSource cotype in Appendix D of the OLE DB Programmer's Reference, "Cotypes, Structures, and Enumerated Types."

When to Implement

IJetCompact is implemented only in version 4.0 and later.

IJetCompact::Compact

Compacts or repairs a database, creating a new database. The old database is retained unchanged.

Syntax

HRESULT IJetCompact::Compact(
   ULONG       cPropertySets,
   DBPROPSET   rgPropertySets[]);

Parameters

• cPropertySets
  [in] The number of DBPROPSET structures in rgPropertySets. If this is zero, the provider ignores rgPropertySets and the method does nothing.

• rgPropertySets
  [in/out] An array of DBPROPSET structures containing properties and values to be set. If the data source object or enumerator is uninitialized, the properties specified in these structures must belong to the Initialization property group. If the data source object is initialized, the properties must belong to the Data Source property group. If the enumerator is initialized, it is an error to call this method. If the same property is specified more than once in rgPropertySets, the value used is provider-specific. If cPropertySets is zero, this parameter is ignored.

Return Code

• S_OK
  The method succeeded.

• E_INVALIDARG
  cPropertySets was not equal to zero and rgPropertySets was a null pointer. In an element of rgPropertySets, cProperties was not zero and rgProperties was a null pointer.

• DB_E_OBJECTOPEN
  The database cannot be opened exclusively.

• DB_SEC_E_PERMISSIONDENIED
  User does not have sufficient rights to compact the database.

• DB_E_DUPLICATEDATASOURCE
  A destination database with the same name already exists.

• DB_S_ERRORSOCCURRED
  One or more properties were not set. Properties not in error remain set. The consumer checks dwStatus in the DBPROP structures to determine which properties were not set. Please refer to IDBProperties::SetProperties for the complete description of this return code.

• E_FAIL
  An error occurred during compaction.

Comments

Compact is called to copy a database and remove extraneous space. The original database is left unchanged. This routine also will repair corruption in the database if possible. This routine will work only for Red ISAM databases ? other IISAMs are not supported. This routine will not work if the database is already opened with permissions to write to the database.

Before calling Compact, the user should ensure that adequate space exists for the newly created database and that the data source object has been initialized.

The initialization properties from the data source object are used as the source for this method. Furthermore, the current values of these properties are used as a template for this routine ? the caller needs to set only those properties that are important to distinguish the new database. Usually this means that only DBPROP_INIT_DATASOURCE needs to be passed to this routine to specify the new name for the compacted database. Unneeded properties are ignored by this method.

Several OLE DB Provider for Microsoft Jet?specific properties affect how this method operates:

• DBPROP_JETOLEDB_COMPACT_DONTCOPYLOCALE (Boolean) ? Use the database sort order, overriding any per-column locale settings.

• DBPROP_JETOLEDB_COMPACT_NORELATIONSHIPS (Boolean) ? Do not copy relationships to the new database.

• DBPROP_JETOLEDB_COMPACT_NOREPAIRREPLICAS (Boolean) ? Do not try to find other replicas to repair damaged replicated databases.

These properties are ignored on all other methods that take data source object properties. Therefore, you can either specify these on the data source object or pass values to this method. Values passed to this method override any previously set values.

Additionally, a database can be compacted to be encrypted or nonencrypted. This is controlled by the DBPROP_JETOLEDB_ENCRYPTDATABASE (Boolean) property.

By default, Compact will create a new database of the same version as the original database. If you want to compact to a newer file format, specify the DBPROP_JETOLEDB_ENGINETYPE (enumeration) property. Values for this property are defined in Msjetoledb.h. You cannot compact databases to a previous Jet format.