isc_prepare_transaction()

From InterBase
Jump to: navigation, search

Go Up to API Function Reference


Executes the first phase of a two-phase commit against multiple databases.

Syntax

 ISC_STATUS isc_prepare_transaction(
 ISC_STATUS *status_vector,
 isc_tr_handle *trans_handle);
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.

Description

isc_prepare_transaction() initiates the first phase of a two-phase commit under program direction. It alerts InterBase, which polls all database participants and waits for replies. The isc_prepare_transaction() function puts the transaction in limbo.

Because a call to this function indicates that you intend to control all phases of the commit, you must complete the second phase of the commit by explicitly calling the isc_commit_transaction() function.

If a call to isc_prepare_transaction() fails, the application should roll back the transaction with a call to the isc_rollback_transaction() function.

Note: If you want InterBase to automatically perform the two-phase commit, call isc_commit_transaction() without calling isc_prepare_transaction().

Example

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

isc_prepare_transaction(status_vector, &trans);
if (status_vector[0] == 1 && status_vector[1])
rb_status = isc_rollback_transaction(status_vector, &trans)
else {
isc_commit_transaction(status_vector, &trans);
if (!(status_vector[0] == 1 && status_vector[1]))
fprintf(stderr, "Commit successful.\n");
}

Return value

isc_prepare_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.

See Also

Advance To: