Workspace Object

Description

A Workspace object defines a session for a user. It contains open databases and provides mechanisms for simultaneous transactions and for a secure workgroup.

Remarks

Use the Workspace object to manage the current session or to start an additional session. In a session, you can open multiple databases, manage transactions, and establish security based on user names and passwords. For example, you can:

Create a Workspace object using the Name and UserName properties to establish a named, password-protected 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 that Workspace.
Use the BeginTrans, CommitTrans, and Rollback methods to manage nested transaction processing within a Workspace and use several Workspace objects to conduct multiple, simultaneous, and overlapping transactions.
Use the IsolateODBCTrans property to isolate multiple transactions that involve the same ODBC database.

When you start the Microsoft Jet database engine, 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. If you use the OpenDatabase method without specifying a Workspace object, the default DBEngine.Workspaces(0) is used.

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

Workspace objects are created using the CreateWorkspace method of the DBEngine object. After you create a new Workspace object, you must appended it to the Workspaces collection if you need to refer to it from the Workspaces collection. You can, however, use a newly created Workspace object without appending it to the Workspaces collection.

You can refer to any other Workspace object that you create and append to the collection by its Name property setting using this syntax:

Workspaces("name")

You can also refer to appended Workspace objects by their position in the Workspaces collection using this syntax (where n is the nth member of the Workspaces collection):

DBEngine.Workspaces(n)

Properties

IsolateODBCTrans Property, Name Property, UserName Property.

Methods

BeginTrans, CommitTrans, Rollback Methods; Close Method; CreateDatabase Method; CreateGroup Method; CreateUser Method; OpenDatabase Method.

See Also

CreateWorkspace Method; Transactions Property; Appendix, "Data Access Object Hierarchy."

Example

This example creates a new Workspace and appends it to the Workspaces collection. It assumes that the user JustAUser with a password of Secret has already been created. The example enumerates the collections of each Workspace object and finally closes the new Workspace. See the methods and properties of the Workspace object or Workspaces collection for additional examples.

Function EnumerateWorkspace () As Integer
    Dim wrkEnum As Workspace, wrkNew As Workspace
    Dim I As Integer, J As Integer
    ' Create new workspace and add it to collection.
    Set wrkNew = DBEngine.CreateWorkspace("NewWorkspace", "JustAUser", _
        "")
    DBEngine.Workspaces.Append wrkNew
    ' Enumerate all workspaces.
    For J = 0 To DBEngine.Workspaces.Count - 1
        Set wrkEnum = DBEngine.Workspaces(J)
        Debug.Print
        Debug.Print "Enumeration of Workspaces("; J; "): "; wrkEnum.Name
        Debug.Print
        ' Enumerate databases.
        Debug.Print "Databases: Name"
        For I = 0 To wrkEnum.Databases.Count - 1
            Debug.Print "  "; wrkEnum.Databases(I).Name
        Next I
        ' Enumerate all user accounts.
        Debug.Print "Users: Name"
        For I = 0 To wrkEnum.Users.Count - 1
            Debug.Print "  "; wrkEnum.Users(I).Name
        Next I
        Debug.Print
        ' Enumerate all group accounts.
        Debug.Print "Groups: Name"
        For I = 0 To wrkEnum.Groups.Count - 1
            Debug.Print "  "; wrkEnum.Groups(I).Name
        Next I
        Debug.Print
    Next J
    Debug.Print
    ' Enumerate built-in properties of wrkNew.
    Debug.Print "wrkNew.Name: "; wrkNew.Name
    Debug.Print "wrkNew.UserName: "; wrkNew.UserName

    Debug.Print
    wrkNew.Close
    EnumerateWorkspace = True
End Function