BeginTransaction Method

Applies To

OSession, OConnection

Description

This method begins a database transaction.

Usage

oresult BeginTransaction(void)

Remarks

A database transaction is a way to group database operations so that they all either succeed or fail together. Please see Transactions for more information. You start a transaction with BeginTransaction. You terminate a transaction either with a Commit or a Rollback. It is an error to call BeginTransaction when a transaction is already in progress.

Note that If Update or Delete methods fail on a given row in a dynaset in a global transaction (that is once you issue a BeginTransaction), locks will remain on those rows on which you called Update or Delete. These locks will persist until you call CommitTransaction or Rollback.

Return Value

An oresult indicating whether the operation succeeded (OSUCCESS) or not (OFAILURE).

Example

This example starts a transaction and begins a long sequence of operations. If an error occurs along the way, all the changes are discarded with a Rollback. If they all succeed, all the changes are made permanent with a Commit.

// routine to give all employees the same bonus
void Transfer(ODynaset empdyn, double bonus)
{
// get the session of this dynaset
OSession empsess = empdyn.GetSession();
// start a transaction
empsess.BeginTransaction();
// edit every record (with StartEdit, SetFieldValue, Update)
empdyn.MoveFirst();
while (!empdyn.IsEOF())
{
if (empdyn.StartEdit() != OSUCCESS)
break;
if (empdyn.SetFieldValue("bonus", bonus) != OSUCCESS)
break;
if (empdyn.Update() != OSUCCESS)
break;
empdyn.MoveNext(); // go to the next record
}
if (!empdyn.IsEOF())
{ // we got out of the loop early. Get rid of any changes we made
empsess.Rollback();
}
else
{ // everything worked. Make it all permanent
empsess.Commit();
}
return;
}