Calling isc_start_multiple()
Go Up to Starting Transactions
An alternate method for starting a transaction against multiple databases is to use isc_start_multiple(). Using isc_start_multiple() is not recommended unless:
- You are using a language that does not support a variable number of arguments in a function call.
- The number of required database attachments is not known until runtime
C programmers should seldom need to use this function.
isc_start_multiple() passes information about each target database to InterBase through an array of transaction existence blocks (TEBs). There must be one TEB for each database against which a transaction runs. A TEB is a structure you must declare in your applications as follows:
typdef struct {
long *db_ptr;
long tpb_len;
char *tpb_ptr;
} ISC_TEB;
db_ptr is a pointer to a previously declared, initialized, and populated database handle. tpb_len is the size, in bytes, of the transaction parameter buffer (TPB) to use for the database, and tpb_ptr is a pointer to the TPB itself. For information about declaring, initializing, and populating a database handle, see Creating Database Handles. For more information about creating and populating a TPB, see Creating a Transaction Parameter Buffer.
To use a TEB structure in an application, declare an array variable of type ISC_TEB. The number of array dimensions should correspond to the number of databases that the transaction runs against. For example, the following declaration creates an array of two TEBs, capable of supporting two databases:
ISC_TEB teb_array[2];
Once an array of TEBs is declared, and corresponding TBPs are created and populated for each database, values may be assigned to the appropriate fields in the TEBs. For example, the following code illustrates how two TEBs are filled:
. . .
ISC_STATUS status_vector[20];
isc_db_handle db1, db2;
isc_tr_handle trans;
ISC_TEB teb_array[2];
. . .
db1 = db2 = 0L;
trans = 0L;
/* Code assumes that two TPBs, isc_tpb1, and isc_tpb2, are created here. */
/* Code assumes databases are attached here. */
/* Assign values to TEB array */
teb_array[0].db_ptr = &db1;
teb_array[0].tpb_len = sizeof(isc_tpb1);
teb_array[0].tpb_ptr = isc_tpb1;
teb_array[1].db_ptr = &db2;
teb_array[1].tpb_len = sizeof(isc_tpb2);
teb_array[1].tpb_ptr = isc_tpb2;
. . .
After the TEBs are loaded with values, isc_start_multiple() can be called using the following syntax:
ISC_STATUS isc_start_multiple(
ISC_STATUS *status_vector,
isc_tr_handle *trans_handle,
short db_handle_count,
void *teb_vector_address);
For example, the following statements starts a two-database transaction:
. . .
ISC_STATUS status_vector[20];
isc_db_handle db1, db2;
isc_tr_handle trans;
ISC_TEB teb_array[2];
. . .
db1 = db2 = 0L;
trans = 0L;
/* Code assumes that two TPBs, isc_tpb1, and isc_tpb2, are created here. */
/* Code assumes databases are attached here. */
/* Assign values to TEB array */
teb_array[0].db_ptr = &db1;
teb_array[0].tpb_len = sizeof(isc_tpb1);
teb_array[0].tpb_ptr = isc_tpb1;
teb_array[1].db_ptr = &db2;
teb_array[1].tpb_len = sizeof(isc_tpb2);
teb_array[1].tpb_ptr = isc_tpb2;
/* Start the transaction */
isc_start_multiple(status_vector, &trans, 2, teb_array);
. . .