isc_start_transaction()
Go Up to API Function Reference
Starts a new transaction against one or more databases.
Syntax
ISC_STATUS isc_start_transaction(
ISC_STATUS *status_vector,
isc_tr_handle *trans_handle,
short db_handle_count,
isc_db_handle *db_handle,
unsigned short tpb_length,
char *tpb_address
[, isc_db_handle *db_handle,
unsigned short tpb_length,
char *tpb_address ...]);
Parameter | Type | Description |
---|---|---|
|
|
Pointer to the error status vector |
|
|
Pointer to a transaction handle whose value has been set by a previous |
|
|
Number of database handles passed in this call. |
|
|
Pointer to a database handle set by a previous call to
|
|
|
Length of the transaction parameter buffer (TPB) |
|
|
Pointer to the TPB |
Description
isc_start_transaction()
starts a new transaction against one or more databases specified as database handles.
- Note: If you have a variable number of databases to update, or are using a language that does not support a variable number of arguments in a function call, use
isc_start_multiple()
instead ofisc_start_transaction()
.
A single transaction can access multiple databases. This function passes information about each database it accesses and the conditions of access for that database in a transaction parameter buffer
(TPB). The TPB is a variably-sized vector of bytes declared and populated by the program. It contains information describing intended transaction behavior such as its access and lock modes.
isc_start_transaction()
can start a transaction against up to 16 databases. You must pass a database handle and a TPB for each referenced database. If you want to use defaults for the transaction, set tpb_length
to zero. In this case, tpb_vector
is a NULL pointer.
Example
The following program includes a call to the start transaction function:
#include <ibase.h> long isc_status[20], /* Status vector. */ *db, /* Database handle. */ *trans; /* Transaction handle. */ static char isc_tpb_0[] = { isc_tpb_version3, /* InterBase version. */ isc_tpb_write, /* Read-write access. */ isc_tpb_consistency, /* Consistency-mode transaction. */ isc_tpb_wait, /* Wait on lock. */ isc_tpb_lock_write, 3, /* Reserving IDS table for update. */ "I","D","S", isc_tpb_protected /* Don't allow other transactions to }; * write against this table. */ main() { db = trans = 0; isc_attach_database(isc_status, 0, "test.ib", &db, 0,0); if (db) { isc_start_transaction(isc_status, &trans, 1, &db, sizeof(isc_tpb_0), isc_tpb_0); if (isc_status[0] == 1 && isc_status[1]) isc_print_status(isc_status); } if (trans) isc_commit_transaction(isc_status, &trans); if (db && !trans) isc_detach_database(isc_status, &db); if (status_vector[0] == 1 && status_vector[1]) isc_print_status(isc_status); }
Return value
isc_start_transaction()
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.
See Also
- isc_commit_transaction()
- isc_prepare_transaction()
- isc_prepare_transaction2()
- isc_rollback_transaction()
- isc_start_multiple()