CdbDatabase Object

See Also    Example    Methods    Properties

A CdbDatabase object represents an open database.

Remarks

Use the CdbDatabase object and its methods and properties to manipulate an open database. In any type of database, you can:

• Use the Execute method to run an action query.
  
  
• Set the Connect property to establish a connection to an ODBC data source.
  
  
• Set the QueryTimeout property to limit the length of time to wait for a query to execute against an ODBC data source.
  
  
• Use the RecordsAffected property to determine how many records were changed by an action query.
  
  
• Use the OpenRecordset method to execute a select query and create a Recordset object.
  
  
• Use the Version property to determine which version of a database engine created the database.

With a Microsoft Jet database (.mdb file), you can also use other methods, properties, and collections to manipulate a CdbDatabase object, as well as create, modify, or get information about its tables, queries, and relationships. For example, you can:

• Use the CreateTableDef and CreateRelation methods to create tables and relations, respectively.
  
  
• Use the CreateProperty method to define new CdbDatabase properties.
  
  
• Use the CreateQueryDef method to create a persistent or temporary query definition.
  
  
• Use MakeReplica, Synchronize, and PopulatePartial methods to create and synchronize full or partial replicas of your database.
  
  
• Set the CollatingOrder property to establish the alphabetic sorting order for character-based fields in different languages.

In an ODBCDirect workspace, you can use the CdbConnection property to obtain a reference to the CdbConnection object that corresponds to the CdbDatabase object.

Use the CreateDatabase method to create a persistent CdbDatabase object that is automatically appended to the Databases collection, thereby saving it to disk.

You don't need to specify the CdbDBEngine object when you use the OpenDatabase method.

Opening a database with linked tables doesn't automatically establish links to the specified external files or Microsoft Jet-connected ODBC data sources. You must either reference the table's CdbTableDef or CdbField objects or open a CdbRecordset object. If you can't establish links to these tables, a trappable error occurs. You may also need permission to access the database, or another user might have the database opened exclusively. In these cases, trappable errors occur.

You can also use the OpenDatabase method to open an external database (such as Microsoft Visual FoxPro, dBASE, and Paradox) directly instead of opening a Microsoft Jet database that has links to its tables.

Note Opening a CdbDatabase object directly on a Microsoft Jet-connected ODBC data source, such as Microsoft SQL Server, is not recommended because query performance is much slower than when using linked tables. However, performance is not a problem with opening a CdbDatabase object directly on an external ISAM database file, such as Visual FoxPro, Paradox, and so forth.

When a procedure that declares a CdbDatabase object has executed, local CdbDatabase objects are closed along with any open CdbRecordset objects. Any pending updates are lost and any pending transactions are rolled back, but no trappable error occurs. You should explicitly complete any pending transactions or edits and close CdbRecordset objects and CdbDatabase objects before exiting procedures that declare these object variables locally.

When you use one of the transaction methods (BeginTrans, CommitTrans, or Rollback) on the CdbWorkspace object, these transactions apply to all databases opened on the CdbWorkspace from which the CdbDatabase object was opened. If you want to use independent transactions, you must first open an additional CdbWorkspace object, and then open another CdbDatabase object in that CdbWorkspace object.

Note You can open the same data source or database more than once, creating duplicate names in the Databases collection. To avoid confusion, assign CdbDatabase objects to object variables and refer to them by variable name.

CdbDatabase 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.

CONSTRUCTORCdbDatabase(VOID);

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

CONSTRUCTORCdbDatabase(const CdbDatabase &);

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

CONSTRUCTORCdbDatabase(DAODatabase *pdb,

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 when 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.