Ending Transactions

Go Up to Working with Transactions

When a transaction’s tasks are complete, or an error prevents a transaction from completing, the transaction must be ended to set the database to a consistent state. There are two API functions that end transactions:

• isc_commit_transaction() makes a transaction’s changes permanent in the database. For transactions that span databases, this function performs an automatic, two-phase commit to ensure that all changes are made successfully.
• isc_rollback_transaction() undoes a transaction’s changes, returning the database to its previous state, before the transaction started. This function is typically used when one or more errors occur that prevent a transaction from completing successfully.

Both isc_commit_transaction() and isc_rollback_transaction() close the record streams associated with the transaction, reinitialize the transaction name to zero, and release system resources allocated for the transaction. Freed system resources are available for subsequent use by any application or program.

isc_rollback_transaction() is used inside error-handling routines to clean up transactions when errors occur. It can roll back a partially completed transaction prior to retrying it, and can restore a database to its prior state if a program encounters an unrecoverable error.

The API offers four additional functions for controlling transactions:

• isc_commit_retaining() commits a transaction but retains the current transaction’s context—the system resources and cursor states used in the transaction—without requiring the overhead of ending a transaction, starting a new one, and reestablishing cursor states. However, isc_commit_retaining() inhibits garbage collection, a necessary function of the database.
• isc_rollback_retaining() rolls back the transaction’s updates but retains the current context. Often, the cause of a rollback is in the transaction’s context, so retaining the context only guarantees a second rollback. Use this call with great caution.
• isc_prepare_transaction() and isc_prepare_transaction2() enable an application to perform the first phase of an automatic, two-phase commit in its own time, then issue a call to ­isc_commit_transaction() to complete the commit.

Important:
If the program ends before a transaction ends, a transaction is automatically rolled back, but databases are not closed. Open databases should always be closed by issuing an explicit call to isc_detach_database().

For more information about detaching from a database, see Working with Databases.

Topics

• Using isc_commit_transaction()
• Using isc_commit_retaining()
• Working with Savepoints
• Working with the NO SAVEPOINT Option
• Using isc_prepare_transaction()
• Using isc_prepare_transaction2()
• Using isc_rollback_transaction()
• Using isc_rollback_retaining()

Advance To:

• Using isc_commit_transaction()