isc_start_multiple()

Begins a new transaction against multiple databases.

Syntax

 ISC_STATUS isc_start_multiple(
 ISC_STATUS *status_vector,
 isc_tr_handle *trans_handle,
 short db_handle_count,
 void *teb_vector_address);

Parameter	Type	Description
`status_vector`	`ISC_STATUS` `*`	Pointer to the error status vector
`trans_handle`	`isc_tr_handle *`	Pointer to a transaction handle whose value has been set by a previous `isc_start_transaction()` call; `trans_handle` returns an error if `NULL`.
`db_handle_count`	`short`	Number of database handles passed in this call via transaction existence buffers (TEBs).
`teb_vector_address`	`void *`	Pointer to the TEB

Description

Call isc_start_multiple() if you:

Are using a language that does not support a variable number of arguments in a function call.
Do not know how many databases you want to attach to when coding the start transaction function.

isc_start_multiple() passes information about each target database to InterBase. That information is stored in an array of transaction existence blocks (TEBs) pointed to by the teb_vector parameter.

teb_vector is a pointer to a byte array that consists of consecutive TEBs, one TEB for each database to connect to. Each TEB consists of three items: a pointer to the database handle for a database against which the transaction should run; the length, in bytes, of the transaction parameter buffer (TPB) for the database, and a pointer to the TPB. The items in a TEB correspond to the items passed directly as parameters in calls to isc_start_transaction(). C programmers should use isc_start_transaction() instead of isc_start_multiple() whenever possible because it does not require setting up TEBs.

For more information about establishing TEBs and calling isc_start_multiple(), see Calling isc_start_multiple().

Example

The following program starts a multiple-database transaction:

#include <ibase.h>

/* Define the ISC_TEB structure. */
typedef struct {
int *dbb_ptr;
long tpb_len;
char *tpb_ptr;
} ISC_TEB;

ISC_TEB teb_vec[2]; /* Declare the TEB vector. */

ISC_STATUS isc_status[20]; /* Status vector. */
long *db0, *db1; /* Database handle. */
long *trans; /* Transaction handle. */

/* Declare the first transaction parameter buffer. */
static char isc_tpb_0[] = {
isc_tpb_version3, /* InterBase version. */
isc_tpb_write, /* Read-write access. */
isc_tpb_consistency, /* Serializable. */
isc_tpb_wait, /* Wait on lock. */
isc_tpb_lock_write, 3, /* Reserving IDS for update. */
'I','D','S',
isc_tpb_protected /* Don't allow other transactions to
};  * write to the table. */

/* Declare the second transaction parameter buffer. */
static char isc_tpb_1[] = {
isc_tpb_version3, /* InterBase version. */
isc_tpb_write, /* Read-write access. */
isc_tpb_consistency, /* Serializable. */
isc_tpb_wait, /* Wait on lock. */
isc_tpb_lock_write, 3, /* Reserving table OZS for update. */
'O','Z','S',
isc_tpb_protected /* Don’t allow other transactions to
};  * write to the table. */

main() {
db0 = db1 = 0;
trans = 0;

/* If you can't attach to test_0 database, attach to test_1. */

isc_attach_database(isc_status, 0, "test_0.ib", &db0, 0,0);
if (isc_status[0] == 1 && isc_status[1])
isc_attach_database(isc_status, 0, "test_1.ib", &db1, 0,0);

if (db0 && db1) {
/* Assign database handles, tpb length, and tbp handle to the teb vectors. */
teb_vec[0].dbb_ptr = &db0;
teb_vec[0].tpb_len = sizeof (isc_tpb_0);
teb_vec[0].tpb_ptr = isc_tpb_0;
teb_vec[1].dbb_ptr = &db1;
teb_vec[1].tpb_len = sizeof (isc_tpb_1);
teb_vec[1].tpb_ptr = isc_tpb_1;
if (isc_start_multiple(isc_status, &trans, 2, teb_vec))
isc_print_status(isc_status);
}

if (trans)
isc_commit_transaction(isc_status, &trans);
if (db0 && !trans)
isc_detach_database(isc_status, &db0);
if (db1 && !(trans && db0))
isc_detach_database(isc_status, &db1);
if (isc_status[0] == 1 && isc_status[1])
isc_print_status(isc_status);
}

Return value

isc_start_multiple() returns the second element of the status vector. Zero indicates success. A nonzero value indicates an error. For InterBase errors, the first element of the status vector is set to 1, and the second element is set to an InterBase error code.

To check for an InterBase error, examine the first two elements of the status vector directly. For more information about examining the status vector, see Handling Error Conditions.

For more information about transaction handles, see Creating Transaction Handles. For more information about creating and populating a TPB, see Creating a Transaction Parameter Buffer. For more information on TEBs, see Calling isc_start_multiple().

Advance To:

isc_start_transaction()