From InterBase

Go Up to API Function Reference

Commits an active transaction and retains the transaction context after a ­commit.


 ISC_STATUS isc_commit_retaining(
 ISC_STATUS *status_vector,
 isc_tr_handle *trans_handle);
Parameter Type Description



Pointer to the error status vector


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.


isc_commit_retaining() commits an active transaction and immediately clones itself. This means that the function retains the transaction name, system resources associated with the transaction, and the current state of any open cursors in the transaction. Although the function is actually initiating a new transaction, by assigning the new transaction the active transaction handle it is, in effect, keeping the transaction open across commits. This results in improved performance by allowing an application to minimize the overhead of initiating additional transactions. isc_commit_retaining() allows you to commit updates while keeping a cursor open.

You can initiate a rollback within the active transaction but the rollback only affects uncommitted updates. In other words, a rollback is legal, even after the transaction context has been passed to the cloned transaction, but, in that case, the rollback will only affect the updates your application has made to the database since the last commit.

To audit the commits made by your calls to this function, check the first element in the status vector to see if the call was successful. If this element contains a zero, the call was successful.

The transaction ends when you commit or roll back without using the retention feature, with a call to isc_commit_transaction() or isc_rollback_transaction().


The following C/C++ code commits a transaction, prints a message, and starts a new transaction with the same handle within the same request:

if (!isc_commit_retaining(status, &retained_trans)) {
fprintf(stderr, "Committed and retained\n");

The following call commits a transaction, prints a confirmation message, starts a new transaction with the same handle within the same request, or, if the commit fails, prints an error message and rolls back.

isc_commit_retaining(status, &retained_trans);
if (status[0] == 1 && status[1]) {
fprintf(stderr, "Error during commit, rolling back.\n");
rb_status = isc_rollback_transaction(status, &retained_trans);
else {
fprintf(stderr, "Commit successful.\n");
tr_count++; /*Increments the number of recycles. */

Return value

isc_commit_retaining() 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: