isc_prepare_transaction2()

Performs the first phase of a two-phase commit for multi-database transactions.

Syntax

 ISC_STATUS isc_prepare_transaction2(
 ISC_STATUS *status_vector,
 isc_tr_handle *trans_handle,
 unsigned short msg_length,
 char *message);

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`
`msg_length`	`unsigned short`	Length of message in bytes
`message`	`char *`	Transaction description buffer

Description

isc_prepare_transaction2() performs the first phase of a two-phase commit, just as isc_prepare_transaction() does, but isc_prepare_transaction2() expects you to provide two additional arguments:

An information message to write to the RDB$TRANSACTION_DESCRIPTION column in the RDB$TRANSACTIONS system table that describes the transaction to commit, so that recovery is possible in the event a system crash occurs during the completion of the commit.
The length, in bytes, of the information message.

By electing to use isc_prepare_transaction2(), you are, in effect, disabling the automatic recovery functions inherent in the two-phase commit. It is your responsibility to deal with recovery issues that might occur during failure of the two-phase commit. Normally, InterBase automatically writes to the RDB$TRANSACTION_DESCRIPTION column in the RDB$TRANSACTIONS system table information that makes it possible to reconnect following a system crash during the commit. You can manually write a message string into RDB$TRANSACTIONS, by using the message parameter in this function.

At the risk of preventing recovery in the event of a system crash, you might choose to avoid writing a message to RDB$TRANSACTION altogether if you determine that there is too much overhead associated with this extra action every time your application commits.

Example

The following example executes the first phase of a two-phase commit and includes a rollback in case of failure:

isc_prepare_transaction2(status_vector, &trans, msg_len, msg);
if (status_vector[0] == 1 && status_vector[1])
rb_status = isc_rollback_transaction(status_vector, &trans);

Return value

isc_prepare_transaction2() 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.

Advance To:

isc_print_sqlerror()