Share via


CDaoWorkspace Class

Manages a named, password-protected database session from login to logoff, by a single user.

class CDaoWorkspace : public CObject

Members

Public Constructors

Name

Description

CDaoWorkspace::CDaoWorkspace

Constructs a workspace object. Afterwards, call Create or Open.

Public Methods

Name

Description

CDaoWorkspace::Append

Appends a newly created workspace to the database engine's Workspaces collection.

CDaoWorkspace::BeginTrans

Begins a new transaction, which applies to all databases open in the workspace.

CDaoWorkspace::Close

Closes the workspace and all of the objects it contains. Pending transactions are rolled back.

CDaoWorkspace::CommitTrans

Completes the current transaction and saves the changes.

CDaoWorkspace::CompactDatabase

Compacts (or duplicates) a database.

CDaoWorkspace::Create

Creates a new DAO workspace object.

CDaoWorkspace::GetDatabaseCount

Returns the number of DAO database objects in the workspace's Databases collection.

CDaoWorkspace::GetDatabaseInfo

Returns information about a specified DAO database defined in the workspace's Databases collection.

CDaoWorkspace::GetIniPath

Returns the location of the Microsoft Jet database engine's initialization settings in the Windows registry.

CDaoWorkspace::GetIsolateODBCTrans

Returns a value that indicates whether multiple transactions that involve the same ODBC data source are isolated via forced multiple connections to the data source.

CDaoWorkspace::GetLoginTimeout

Returns the number of seconds before an error occurs when the user attempts to log in to an ODBC database.

CDaoWorkspace::GetName

Returns the user-defined name for the workspace object.

CDaoWorkspace::GetUserName

Returns the user name specified when the workspace was created. This is the name of the workspace owner.

CDaoWorkspace::GetVersion

Returns a string that contains the version of the database engine associated with the workspace.

CDaoWorkspace::GetWorkspaceCount

Returns the number of DAO workspace objects in the database engine's Workspaces collection.

CDaoWorkspace::GetWorkspaceInfo

Returns information about a specified DAO workspace defined in the database engine's Workspaces collection.

CDaoWorkspace::Idle

Allows the database engine to perform background tasks.

CDaoWorkspace::IsOpen

Returns nonzero if the workspace is open.

CDaoWorkspace::Open

Explicitly opens a workspace object associated with DAO's default workspace.

CDaoWorkspace::RepairDatabase

Attempts to repair a damaged database.

CDaoWorkspace::Rollback

Ends the current transaction and does not save the changes.

CDaoWorkspace::SetDefaultPassword

Sets the password that the database engine uses when a workspace object is created without a specific password.

CDaoWorkspace::SetDefaultUser

Sets the user name that the database engine uses when a workspace object is created without a specific user name.

CDaoWorkspace::SetIniPath

Sets the location of the Microsoft Jet database engine's initialization settings in the Windows registry.

CDaoWorkspace::SetIsolateODBCTrans

Specifies whether multiple transactions that involve the same ODBC data source are isolated by forcing multiple connections to the data source.

CDaoWorkspace::SetLoginTimeout

Sets the number of seconds before an error occurs when the user attempts to log in to an ODBC data source.

Public Data Members

Name

Description

CDaoWorkspace::m_pDAOWorkspace

Points to the underlying DAO workspace object.

Remarks

In most cases, you will not need multiple workspaces, and you will not need to create explicit workspace objects; when you open database and recordset objects, they use DAO's default workspace. However, if needed, you can run multiple sessions at a time by creating additional workspace objects. Each workspace object can contain multiple open database objects in its own Databases collection. In MFC, a workspace is primarily a transaction manager, specifying a set of open databases all in the same "transaction space."

Note

The DAO database classes are distinct from the MFC database classes based on Open Database Connectivity (ODBC). All DAO database class names have a "CDao" prefix. In general, the MFC classes based on DAO are more capable than the MFC classes based on ODBC. The DAO-based classes access data through the Microsoft Jet database engine, including ODBC drivers. They also support Data Definition Language (DDL) operations, such as creating databases and adding tables and fields via the classes, without having to call DAO directly.

Capabilities

Class CDaoWorkspace provides the following:

  • Explicit access, if needed, to a default workspace, created by initializing the database engine. Usually you use DAO's default workspace implicitly by creating database and recordset objects.

  • A transaction space in which transactions apply to all databases open in the workspace. You can create additional workspaces to manage separate transaction spaces.

  • An interface to many properties of the underlying Microsoft Jet database engine (see the static member functions). Opening or creating a workspace, or calling a static member function before open or create, initializes the database engine.

  • Access to the database engine's Workspaces collection, which stores all active workspaces that have been appended to it. You can also create and work with workspaces without appending them to the collection.

Security

MFC does not implement the Users and Groups collections in DAO, which are used for security control. If you need those aspects of DAO, you must program them yourself via direct calls to DAO interfaces. For information, see Technical Note 54.

Usage

You can use class CDaoWorkspace to:

  • Explicitly open the default workspace.

    Usually your use of the default workspace is implicit — when you open new CDaoDatabase or CDaoRecordset objects. But you might need to access it explicitly — for example, to access database engine properties or the Workspaces collection. See "Implicit Use of the Default Workspace" below.

  • Create new workspaces. Call Append if you want to add them to the Workspaces collection.

  • Open an existing workspace in the Workspaces collection.

Creating a new workspace that does not already exist in the Workspaces collection is described under the Create member function. Workspace objects do not persist in any way between datababase engine sessions. If your application links MFC statically, ending the application uninitializes the database engine. If your application links with MFC dynamically, the database engine is uninitialized when the MFC DLL is unloaded.

Explicitly opening the default workspace, or opening an existing workspace in the Workspaces collection, is described under the Open member function.

End a workspace session by closing the workspace with the Close member function. Close closes any databases you have not closed previously, rolling back any uncommitted transactions.

Transactions

DAO manages transactions at the workspace level; hence, transactions on a workspace with multiple open databases apply to all of the databases. For example, if two databases have uncommitted updates and you call CommitTrans, all of the updates are committed. If you want to limit transactions to a single database, you need a separate workspace object for it.

Implicit Use of the Default Workspace

MFC uses DAO's default workspace implicitly under the following circumstances:

  • If you create a new CDaoDatabase object but do not do so through an existing CDaoWorkspace object, MFC creates a temporary workspace object for you, which corresponds to DAO's default workspace. If you do so for multiple databases, all of the database objects are associated with the default workspace. You can access a database's workspace through a CDaoDatabase data member.

  • Similarly, if you create a CDaoRecordset object without supplying a pointer to a CDaoDatabase object, MFC creates a temporary database object and, by extension, a temporary workspace object. You can access a recordset's database, and indirectly its workspace, through a CDaoRecordset data member.

Other Operations

Other database operations are also provided, such as repairing a corrupted database or compacting a database.

For information about calling DAO directly and about DAO security, see Technical Note 54.

Inheritance Hierarchy

CObject

CDaoWorkspace

Requirements

Header: afxdao.h

See Also

Reference

CObject Class

Hierarchy Chart

CDaoDatabase Class

CDaoRecordset Class

CDaoTableDef Class

CDaoQueryDef Class

CDaoException Class