rdoEnvironment Object

An rdoEnvironment object defines a logical set of connections and transaction scope for a particular user name. It contains both open and allocated but unopened connections, provides mechanisms for simultaneous transactions, and provides a security context for data manipulation language (DML) operations on the database.

Remarks

Generally, an rdoEnvironment object corresponds to an ODBC environment that can be referred to by the rdoEnvironment object's hEnv property. However, if the Name argument is not provided when the rdoEnvironment object is created by the rdoCreateEnvironment method, a stand-alone rdoEnvironment is created that is not added to the rdoEnvironments collection. Stand-alone rdoEnvironment objects are not exposed to other in-process DLLs unless specifically designated as public. If the reference count for any private rdoEnvironment is reduced to zero, all rdoConnections associated with the rdoEnvironment are closed.

Once you set the properties of an rdoEnvironment object, you can use the Add method to append it to the rdoEnvironments collection or the Remove method to detach and deallocate the object. The Name property is read-only and is determined by the specific remote data object.

The default rdoEnvironment is created automatically when the RemoteData control is initialized, or the first remote data object is referenced in code. The Name property of rdoEnvironments(0) is "Default_Environment". The user name and password for rdoEnvironments(0) are both "".

rdoEnvironment objects can be created with the rdoCreateEnvironment method of the rdoEngine object which automatically appends the new object to the rdoEnvironments collection. All rdoEnvironment objects created in this manner are assigned properties based on the default properties set in the rdoEngine object.

The user name and password information from the rdoEnvironment is used to establish the connection if these values are not supplied in the connect argument of the OpenConnection method, or in the Connect property of the RemoteData control.

All rdoEnvironment objects share a common hEnv value that is created on an application basis. Use the rdoEnvironment object to manage the current ODBC environment, or to start an additional connection. In an rdoEnvironment, you can open multiple connections, manage transactions, and establish security based on user names and passwords. For example, you can:

• Create an rdoEnvironment object using the Name, Password, and UserName properties to establish a named, password-protected environment. The environment creates a scope in which you can open multiple connections and conduct one instance of coordinated transactions.
  
  
• Use the CursorDriver property to determine which cursor driver library is used to build rdoResultset objects. You can choose one of four types of cursors, or set the CursorDriver property to rdUseNone to indicate that no cursor is to be used to manage result sets.
  
  
• Use the OpenConnection method to open one or more existing connections in that rdoEnvironment.
  
  
• Use the LoginTimeout property to determine how long the ODBC drivers should wait before abandoning the connection attempt.
  
  
• Use the BeginTrans, CommitTrans, and RollbackTrans methods to manage transaction processing within an rdoEnvironment across several connections.
  
  
• Use several rdoEnvironment objects to conduct multiple, simultaneous, independent, and overlapping transactions.
  
  
• Use the Close method to terminate an environment and the connection and remove the rdoEnvironment object from the rdoEnvironments collection. This also closes all connections associated with the object.

Managing Transactions

The rdoEnvironment also determines transaction scope. Committing an rdoEnvironment transaction commits all open rdoConnection databases and their corresponding open rdoResultset objects. This does not imply a two-phase commit operation — simply that individual rdoConnection objects are instructed to commit any pending operations — one at a time.

For Microsoft SQL Server databases, the Distributed Transaction Coordinator (DTC) can be used to manage blocks of transactions simply by introducing the SQL query with the BEGIN DISTRIBUTED TRANSACTION statement. DTC facilitates the creation of network-wide database updates through its own two-phase commit protocol. Whenever SQL Server commits a transaction, the DTC ensures all related resources also commit the transaction. If any part of the transaction fails, the DTC ensures that the entire transaction is rolled back across all enlisted servers.

When you use transactions, all databases in the specified rdoEnvironment are affected – even if multiple rdoConnection objects are opened in the rdoEnvironment. For example, suppose you use a BeginTrans method against one of the databases visible from the connection, update several rows in the database, and then delete rows in another rdoConnection object's database. When you use the RollbackTrans method, both the update and delete operations are rolled back. To avoid this problem, you can create additional rdoEnvironment objects to manage transactions independently across rdoConnection objects. Note that transactions executed by multiple rdoEnvironment objects are serialized and are not atomic operations. Because of this, their success or failure is not interdependent. This is an example of batched transactions.

You can execute nested transactions only if your data source supports them. For example, on a single connection, you can execute a BEGIN TRANS SQL statement, execute several UPDATE queries, and another BEGIN TRANS statement. Any operations executed after the second BEGIN TRANS SQL statement can be rolled back independently of the statements executed after the first BEGIN TRANS. This is an example of nested transactions. To commit the first set of UPDATE statements, you must execute a COMMIT TRANS statement, or a ROLLBACK TRANS statement for each BEGIN TRANS executed.

rdoEnvironment Events

The following events are fired as the rdoEnvironment object is manipulated. These can be used to micro-manage RDO transactions associated with the rdoEnvironment or to synchronize some other process with the transaction.

Addressing rdoEnvironment Objects

The Name property of rdoEnvironment objects is set from the name argument passed to the rdoCreateEnvironment method. You can refer to any other rdoEnvironment object by specifying its Name property setting using this syntax:

rdoEnvironments("MyEnvName")

or simply:

rdoEnvironments!MyEnvName

You can also refer to rdoEnvironment objects by their position in the rdoEnvironments collection using this syntax (where n is the nth member of the zero-based rdoEnvironments collection):

rdoEngine.rdoEnvironments(n)

or simply:

rdoEnvironments(n)