CdbIndex Object

See Also   Methods   Properties

CdbIndex objects specify the order of records accessed from database tables and whether or not duplicate records are accepted, providing efficient access to data. For external databases, CdbIndex objects describe the indexes established for external tables (Microsoft Jet workspaces only).

Remarks

The Microsoft Jet database engine uses indexes when it joins tables and creates CdbRecordset objects. Indexes determine the order in which table-type CdbRecordset objects return records, but they don't determine the order in which the Microsoft Jet database engine stores records in the base table or the order in which any other type of CdbRecordset object returns records.

With a CdbIndex object, you can:

• Use the Required property to determine whether the Field objects in the index require values that are not Null, and then use the IgnoreNulls property to determine whether the Null values have index entries.
  
  
• Use the Primary and Unique properties to determine the ordering and uniqueness of the CdbIndex object.

The Microsoft Jet database engine maintains all base table indexes automatically. It updates indexes whenever you add, change, or delete records from the base table. Once you create the database, use the CompactDatabase method periodically to bring index statistics up-to-date.

When accessing a table-type CdbRecordset object, specify the order of records using the object's CdbIndex property. Set this property to the Name property setting of an existing CdbIndex object in the Indexes collection. This collection is contained by the CdbTableDef object underlying the CdbRecordset object that you're populating.

Note You don't have to create indexes for a table, but for large, unindexed tables, accessing a specific record or processing joins can take a long time. Conversely, having too many indexes can slow down updates to the database as each of the table indexes is amended.

The Attributes property of each CdbField object in the index determines the order of records returned and, consequently, determines which access techniques to use for that index.

Each CdbField object in the Fields collection of a CdbIndex object is a component of the index. To define a new CdbIndex object, set its properties before you append it to a collection, making the CdbIndex object available for subsequent use.

Note You can modify the Name property setting of an existing CdbIndex object only if the Updatable property setting of the containing CdbTableDef object is TRUE.

When you set a primary key for a table, the Microsoft Jet database engine automatically defines it as the primary index. A primary index consists of one or more fields that uniquely identify all records in a table in a predefined order. Because the primary index field must be unique, the Microsoft Jet database engine automatically sets the Unique property of the primary CdbIndex object to TRUE. If the primary index consists of more than one field, each field can contain duplicate values, but the combination of values from all the indexed fields must be unique. A primary index consists of a key for the table and is always made up of the same fields as the primary key.

Important Make sure your data complies with the attributes of your new index. If your index requires unique values, make sure that there are no duplicates in existing data records. If duplicates exist, the Microsoft Jet database engine can't create the index; a trappable error results when you attempt to use the Append method on the new index.

When you create a relationship that enforces referential integrity, the Microsoft Jet database engine automatically creates an index with the Foreign property, set as the foreign key in the referencing table. After you've established a table relationship, the Microsoft Jet database engine prevents additions or changes to the database that violate that relationship. If you set the Attributes property of the CdbRelation object to allow cascading updates and cascading deletes, the Microsoft Jet database engine updates or deletes records in related tables automatically.

To create a new CdbIndex object

1. Use the CreateIndex method on a CdbTableDef object.
   
   
2. Use the CreateField method on the CdbIndex object to create a CdbField object for each field (column) to be included in the CdbIndex object.
   
   
3. Set CdbIndex properties as needed.
   
   
4. Append the CdbField object to the Fields collection.
   
   
5. Append the CdbIndex object to the Indexes collection.

Note The Clustered property is ignored for databases that use the Microsoft Jet database engine, which doesn't support clustered indexes.

CdbIndex Constructor Syntax

Use any one of the following three constructors. The qualifier 'CONSTRUCTOR' in the syntax models is provided to help readability. It has no syntactic value.

CONSTRUCTORCdbIndex(VOID);

This constructor creates an instance of the class. There are no parameters.

CONSTRUCTORCdbIndex(const CdbIndex &);

This constructor creates a copy of the object referenced in the parameter.

CONSTRUCTORCdbIndex(DAOIndex *pidx,

BOOL bAddRef = FALSE);

DAO functionality is presented through pointers to DAO Automation interfaces. This constructor makes a DAO interface available in the form of a DAO class object that provides additional functionality.

This constructor is not required for typical use. It is provided to enable you to easily create a DAO class object if you have access to the corresponding DAO interface.

When the destructor for the DAO object is invoked, the underlying Automation interface's Release member is called. If Release decrements the interface's reference count to zero, the pointer to the Automation interface can be deleted. If you don't want this to happen (for example, because you want to discard the DAO object but continue using the Automation interface), specify TRUE for the second parameter. The underlying Automation interface's AddRef member is called, which counterbalances the eventual call to Release.