BeginTrans, CommitTrans, Rollback Methods

See Also      Applies To

The transaction methods manage transaction processing during a session defined by a CdbWorkspace object as follows:

• BeginTrans begins a new transaction.
  
  
• CommitTrans ends the current transaction and saves the changes.
  
  
• Rollback ends the current transaction and restores the databases in the CdbWorkspace object to the state they were in when the current transaction began.

Syntax

VOIDBeginTrans(VOID);

VOIDCommitTrans (LONG lOptions = -1);

VOIDRollback(VOID);

Parameters

Remarks

You use these methods with a CdbWorkspace object when you want to treat a series of changes made to the databases in a session as one unit.

Typically, you use transactions to maintain the integrity of your data when you must both update records in two or more tables and ensure changes are completed (committed) in all tables or none at all (rolled back). For example, if you transfer money from one account to another, you might subtract an amount from one and add the amount to another. If either update fails, the accounts no longer balance. Use the BeginTrans method before updating the first record, and then, if any subsequent update fails, you can use the Rollback method to undo all of the updates. Use the CommitTrans method after you successfully update the last record.

In a Microsoft Jet workspace, you can include the dbForceOSFlush constant with CommitTrans. This forces the database engine to immediately flush all updates to disk, instead of caching them temporarily. Without using this option, a user could get control back immediately after the application program calls CommitTrans, turn the computer off, and not have the data written to disk. While using this option may affect your application’s performance, it is useful in situations where the computer could be shut off before cached updates are saved to disk.

Caution Within one CdbWorkspace object, transactions are always global to the CdbWorkspace and aren't limited to only one CdbConnection or CdbDatabase object. If you perform operations on more than one connection or database within a CdbWorkspace transaction, resolving the transaction (that is, using the CommitTrans or Rollback method) affects all operations on all connections and databases within that workspace.

After you use CommitTrans, you can't undo changes made during that transaction unless the transaction is nested within another transaction that is itself rolled back. If you nest transactions, you must resolve the current transaction before you can resolve a transaction at a higher level of nesting.

If you want to have simultaneous transactions with overlapping, non-nested scopes, you can create additional CdbWorkspace objects to contain the concurrent transactions.

If you close a CdbWorkspace object without resolving any pending transactions, the transactions are automatically rolled back.

If you use the CommitTrans or Rollback method without first using the BeginTrans method, an error occurs.

Some ISAM databases used in a Microsoft Jet workspace may not support transactions, in which case the CdbTransactions property of the CdbDatabase object or CdbRecordset object is False. To make sure the database supports transactions, check the value of the CdbTransactions property of the CdbDatabase object before using the BeginTrans method. If you are using a CdbRecordset object based on more than one database, check the CdbTransactions property of the CdbRecordset object. If a CdbRecordset is based entirely on Microsoft Jet tables, you can always use transactions. CdbRecordset objects based on tables created by other database products, however, may not support transactions. For example, you can't use transactions in a CdbRecordset based on a Paradox table. In this case, the CdbTransactions property is False. If the CdbDatabase or CdbRecordset doesn't support transactions, the methods are ignored and no error occurs.

You can't nest transactions if you are accessing ODBC data sources through the Microsoft Jet database engine.

Notes

• You can often improve the performance of your application by breaking operations that require disk access into transaction blocks. This buffers your operations and may significantly reduce the number of times a disk is accessed.
  
  
• In a Microsoft Jet workspace, transactions are logged in a file kept in the directory specified by the TEMP environment variable on the workstation. If the transaction log file exhausts the available storage on your TEMP drive, the database engine triggers a run-time error. At this point, if you use CommitTrans, an indeterminate number of operations are committed, but the remaining uncompleted operations are lost, and the operation has to be restarted. Using a Rollback method releases the transaction log and rolls back all operations in the transaction.

Usage

#include <afxole.h>
#include <dbdao.h>

CdbWorkspace      ws;
BOOL            error;
...
ws.BeginTrans();      // Start working.
...                  // Make some changes.
if (error)
   ws.Rollback();   // Reject changes.
else
   ws.CommitTrans();    // Accept changes.
ws.Close();         // Close the workspace.