CDaoWorkspace Class

Article
01/08/2013

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