Working with Transactions

Go Up to API Guide

This chapter describes how to perform the following actions:

• Set up a transaction parameter buffer (TPB) that contains parameters
• Set up and initialize transaction handles
• Use the API functions that control transactions
• Retrieve a transaction ID

Each data definition and data manipulation in an application takes place in the context of a transaction: one or more statements that work together to complete a specific set of actions that must be treated as an atomic unit of work.

InterBase allows a connection to open more than one transaction at a time. These simultaneous transactions are independent of each other, and can conflict. Multiple concurrent transactions within a connection are useful for applications that use a database in several independent ways.

The following table summarizes the API functions most commonly used when working with transactions. Functions are listed in the order they typically appear in an application.

Function	Purpose
isc_start_transaction()	Starts a new transaction against one or more databases; use a previously declared and populated TPB.
isc_commit_retaining()	Commits changes of a transaction, and preserves the transaction context for further transaction processing.
isc_commit_transaction()	Commits changes of a transaction, and ends the ­transaction
isc_dpb_transaction()	This is used to send in a starting transaction ID when creating or restoring a database. This transaction ID can be as large as a 64-bit Integer type. 1 byte represents the length of a data type of a value, short/integer/int64 type represents the transaction ID value.
isc_rollback_transaction()	Rolls back changes of a transaction, and ends the ­transaction.
isc_spb_res_starting_trans()	This is for Services API; it has a similar function as isc_dpb_transaction but it is not as flexible. It requires an int64 data type value only. int64 type representing transaction ID value.

In addition to these functions, the following table lists less frequently used API transaction functions in the order they typically appear when used:

Function	Purpose
isc_start_multiple()	Starts a new transaction against one or more databases; used instead of isc_start_transaction() for programming languages such as FORTRAN, that do not support variable numbers of arguments to functions.
isc_prepare_transaction()	Performs the first phase of a two-phase commit, prior to calling isc_commit_transaction(); used to coordinate a two-phase commit with some external event.
isc_prepare_transaction2()	Performs the first phase of a two-phase commit, prior to calling isc_commit_transaction(); used to coordinate a two-phase commit with some external event. This call accepts a message describing the external event.
isc_rollback_retaining()	Rolls back changes of a transaction but maintains transaction context.

Topics

• Starting Transactions
• Ending Transactions
• Use of Commit/Rollback with Multidatabae Transactions