CdbDBEngine Object

The CdbDBEngine object is the top level object in the DAO object model.

Remarks

The CdbDBEngine object contains and controls all other objects in the hierarchy of DAO objects. You can't create additional CdbDBEngine objects, and the CdbDBEngine object isn't an element of any collection.

Note When you reference an ODBC data source directly through DAO, it is called an "ODBCDirect workspace." This is to distinguish it from an ODBC data source that you reference indirectly through the Microsoft Jet database engine, using a "Microsoft Jet workspace." Each method of accessing ODBC data requires one of two types of CdbWorkspace object; you can set the DefaultType property to choose the default type of CdbWorkspace object that you will create from the CdbDBEngine object. The CdbWorkspace type and associated data source determines which DAO objects, methods, and properties you can use.

With any type of database or connection, you can:

Use the Version property to obtain the DAO version number.
Use the LoginTimeout property to obtain or set the ODBC login timeout and the RegisterDatabase method to provide ODBC information to the Microsoft Jet database engine. You can use these features the same way, regardless of whether you connect to the ODBC data source through Microsoft Jet or through an ODBCDirect workspace.
Use the DefaultType property to set the default type of database connection that subsequently created CdbWorkspace objects will use — either Microsoft Jet or ODBCDirect.
Use the DefaultPassword and DefaultUser properties to set the user identification and password for the default CdbWorkspace object.
Use the CreateWorkspace method to create a new CdbWorkspace object. You can use optional arguments to override the settings of the DefaultType, DefaultPassword, and DefaultUser properties.
Use the OpenDatabase method to open a database in the default CdbWorkspace, and use the BeginTrans, Commit, and Rollback methods to control transactions on the default CdbWorkspace.
Use the Workspaces collection to reference specific CdbWorkspace objects.
Use the Errors collection to examine data access error details.

Other properties and methods are only available when you use DAO with the Microsoft Jet database engine. You can use them to control the Microsoft Jet database engine, manipulate its properties, and perform tasks on temporary objects that aren't elements of collections. For example, you can:

Use the CreateDatabase method to create a new Microsoft Jet CdbDatabase object.
Use the Idle method to enable the Microsoft Jet database engine to complete any pending tasks.
Use the CompactDatabase and RepairDatabase methods to maintain database files.
Use the IniPath and SystemDB properties to specify the location of Microsoft Jet Windows Registry information and the Microsoft Jet workgroup information file, respectively. The SetOption method allows you to override the Windows Registry settings for the Microsoft Jet database engine.

After you change the DefaultType and IniPath property settings, only subsequent CdbWorkspace objects will reflect these changes.

To refer to a collection that belongs to the CdbDBEngine object, or to refer to a method or property that applies to this object, use this syntax:

[CdbDBEngine.][collection method property]

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

CONSTRUCTORCdbDBEngine(const CdbDBEngine &);

Type	Description
const CdbDBEngine &	Reference to an object.

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

CONSTRUCTORCdbDBEngine(DAODBEngine *peng,

BOOL bAddRef = FALSE);

Type	Argument	Description
DAODBEngine *	peng	A DAO Automation interface pointer corresponding to this DAO class.
BOOL	bAddRef =FALSE	Optional. A Boolean. If TRUE, the DAO Automation interface AddRef function is called.

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.

CONSTRUCTORCdbDBEngine(BOOL bPrivate = FALSE,

BOOL bStart = TRUE,

LPCTSTR pstrIniPath = Null,

LPCTSTR pstrDefUser = Null,

LPCTSTR pstrDefPW = Null,

LONG lType = dbUseJet);

Type	Argument	Description
BOOL	bPrivate =FALSE	Optional. Determines whether the Microsoft Jet engine is private or shared. Each private engine is a new instance of DAO. A private engine is one way to create secure access to data. A shared engine is common across all instances, enabling shared workspaces and databases, for example. If TRUE, then private.
BOOL	bStart =TRUE	Optional. A Boolean. TRUEThe Microsoft Jet engine is started when this object is created. FALSEThe Microsoft Jet engine must be started explicitly with the Start method.
LPCTSTR	pstrIniPath =Null	Optional. A pointer to a string that is a user-supplied portion of the Windows registry key containing Microsoft Jet database engine settings or parameters needed for installable ISAM databases.
LPCTSTR	pstrDefUser =Null	Optional. A pointer to a string that is the user name used to create the default Workspace when it is initialized.
LPCTSTR	pstrDefPW =Null	Optional. A pointer to a string that is the password used to create the default Workspace when it is initialized.
LONG	lType =dbUseJet	Optional. A value that determines whether the Workspace will be Microsoft Jet or ODBC (that is, dbUseJet or dbUseODBC).

This constructor creates an instance of the CdbDBEngine class.

This constructor is typically specified without parameters (that is, using all defaults) which makes it look like other DAO object constructors that take no parameters.

One reason to specify parameters is to create the Microsoft Jet Database Engine but postpone starting it. This enables you to acquire run-time information or avoid run-time conflicts when starting DAO from a user DLL. Another common reason to specify parameters is to create an ODBCDirect workspace.

Usage

#include <afxole.h>
#include <dbdao.h>

// Example 1:
CdbDBEngine   dben1a;             // Create an instance using defaults.
CdbDBEngine   dben1b( dben1a );   // Copy an existing instance.

// Example 2:
/* Create an instance of CdbDBEngine without using defaults.
   Specify: a private engine; don't start it when constructed; no IniPath, DefaultUser, or password, yet; explicitly request a Microsoft Jet workspace. 
*/

CdbDBEngine dben2(TRUE,FALSE,NULL,NULL,NULL,dbUseJet);

// After getting IniPath, DefaultUser, and DefaultPassword from the // user, set the CdbDBEngine object with those values.

   dben2.SetIniPath(lpctstrIniPath);
   dben2.SetDefaultUser(lpstrDefaultUser);
   dben2.SetDefaultPassword(lpctstrPassword);

// Now, start the engine.   
   dben2.Start();