D Eloquence Library

The ROLLBACK Function

The ROLLBACK function undoes any pending (sub-) transaction . The syntax is as follows: 

   idb_rollback(id,mode,status)

   int id;
   int mode;
   int status[10]
The parameters are:

id
Transaction id, used with mode 2.
mode
See below.
status
A pointer to an array of a least 10 elements used to indicate the success or failure of the function call (see below).

IDBROLLBACK Modes

Mode 1: Rollback current (sub-)transaction

The idb_rollback function is used to undo a pending transaction. If this is a top level transaction, all pending database modifications are reverted. If applied to a subtransaction all modifications including the enclosing idb_begin are reverted.

Mode 2: Rollback specified transaction

idb_rollback can be directed to rollback all transaction until the specified one. The transaction id is returned by the idb_begin function.

Mode 3: Rolback top level transaction

idb_rollback can be directed to rollback the toplevel transaction and any currently active subtransaction.

Description

Database modifications made in a transaction are not saved in the database until the enclosing is commited. The idb_rollback reverts any pending modification.

As you probably have noticed, idb_rollback does not take a database argument. Transactions are global for all databases even if they are executed on different servers.

Return value

Returns 0 if successful, or error number if an error was encountered.

Status codes

If idb_rollback was successfully executed, the status array will contain the following values:

Status codes
ElementMeaning
0S_OK
10
20
30
40
50
60
70
80
90

Example 

   /* begin transaction */
   if(idb_begin(NULL, 1,status))
      error_handler();
   
   if ( modify_database() ) {
      /* something went wrong, revert changes */
      if(idb_rollback(0, 1,status))
         error_handler();
      return -1;
   }
   
   /* commit changes */
   if(idb_commit(1,status))
      error_handler();
This will rollback any modifications in case the function modify_database indicates a failure. Otherwise the transaction is commited.

Eloquence Database Manual - 19 DEC 2002