isc_start_transaction()

From InterBase

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

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.

db_handle

isc_db_handle *

Pointer to a database handle set by a previous call to ­isc_attach_database(); the handle identifies the database against which the events are expected to be posted.

db_handle returns an error in status_vector if it is NULL.

tpb_length

unsigned short

Length of the transaction parameter buffer (TPB)

tpb_address

char *

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 of isc_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

Advance To: