CdbWorkspace Object

See Also   Methods   Properties

A CdbWorkspace object defines a named session for a user. It contains open databases and provides mechanisms for simultaneous transactions and, in Microsoft Jet workspaces, secure workgroup support. It also controls whether you are going through the Microsoft Jet database engine or ODBCDirect to access external data.

Remarks

A CdbWorkspace is a non-persistent object that defines how your application interacts with data — either by using the Microsoft Jet database engine or ODBCDirect. Use the CdbWorkspace object to manage the current session or to start an additional session. In a session, you can open multiple databases or connections and manage transactions. For example, you can:

• Use the Name, UserName, and Type properties to establish a named session. The session creates a scope in which you can open multiple databases and conduct one instance of nested transactions.
  
  
• Use the Close method to terminate a session.
  
  
• Use the OpenDatabase method to open one or more existing databases on a CdbWorkspace.
  
  
• Use the BeginTrans, CommitTrans, and Rollback methods to manage nested transaction processing within a CdbWorkspace and use several CdbWorkspace objects to conduct multiple, simultaneous, and overlapping transactions.

Further, using a Microsoft Jet database, you can establish security based on user names and passwords:

• Use the Groups and Users collections to establish group and user access permissions to objects in the CdbWorkspace.
  
  
• Use the IsolateODBCTrans property to isolate multiple transactions that involve the same Microsoft Jet-connected ODBC database.

When you first refer to or use a CdbWorkspace object, you automatically create the default workspace, DBEngine.Workspaces(0). The settings of the Name and UserName properties of the default workspace are "#Default Workspace#" and "Admin," respectively. If security is enabled, the UserName property setting is the name of the user who logged on.

To establish an ODBCDirect CdbWorkspace object, and thereby avoid loading the Microsoft Jet database engine into memory, set the DBEngine object's DefaultType property to dbUseODBC, or set the type argument of the CreateWorkspace method to dbUseODBC.

When you use transactions, all databases in the specified CdbWorkspace are affected — even if multiple Database objects are opened in the CdbWorkspace. For example, you use a BeginTrans method, update several records in a database, and then delete records in another database. If you then use the Rollback method, both the update and delete operations are canceled and rolled back. You can create additional CdbWorkspace objects to manage transactions independently across Database objects.

You can create CdbWorkspace objects with the CreateWorkspace method. After you create a new CdbWorkspace object, you must append it to the Workspaces collection if you need to refer to it from the Workspaces collection.

You can use a newly created CdbWorkspace object without appending it to the Workspaces collection. However, you must refer to it by the object variable to which you have assigned it.

To refer to a CdbWorkspace object in a collection by its ordinal number or by its Name property setting, use either of the following syntax forms:

Workspaces[0]

Workspaces["name"]

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

CONSTRUCTORCdbWorkspace(VOID);

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

CONSTRUCTORCdbWorkspace(const CdbWorkspace &);

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

CONSTRUCTORCdbWorkspace(DAOWorkspace *pwrk,

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.