Creating Transaction Handles
Go Up to Starting Transactions
Contents
Every transaction that is used in an application must be associated with its own transaction handle, a pointer to an address that is used by all API transaction functions. The ibase.h header file contains the following C typedef declaration for transaction handles:
typedef void ISC_FAR *isc_tr_handle;
To use this typedef for declaring transaction handles in an application, include ibase.h in each source file module:
#include <ibase.h>
Declaring Transaction Handles
To establish transaction handles for use, declare a variable of type isc_tr_handle for each simultaneously active transaction. The following code declares two handles:
#include <ibase.h>
. . .
isc_tr_handle tr1;
isc_tr_handle tr2;
Once a transaction is committed or rolled back, its handle can be assigned to a different transaction in a subsequent call to isc_start_transaction(). If an application uses several transactions, but only starts a subset of transactions at the same time, it is only necessary to declare as many handles as there will be simultaneously active transactions. For example, if an application starts a total of three transactions, but only runs two of them at the same time, only two transaction handles need be declared.
Initializing Transaction Handles
Before a transaction handle can be used to start a new transaction, it must be set to zero. The following code illustrates how two transaction handles are set to zero:
#include <ibase.h>
. . .
isc_tr_handle tr1;
isc_tr_handle tr2;
. . .
/* Set transaction handles to zero before starting a transaction. */
tr1 = 0L;
tr2 = 0L;
Once a transaction handle is initialized to zero, it can be used in a call to isc_start_transaction() to establish a new transaction. If a nonzero transaction handle is passed to isc_start_transaction(), the startup fails and an error code is returned.