isc_commit_retaining()
Go Up to API Function Reference
Commits an active transaction and retains the transaction context after a commit.
Syntax
ISC_STATUS isc_commit_retaining(
ISC_STATUS *status_vector,
isc_tr_handle *trans_handle);
| Parameter | Type | Description |
|---|---|---|
|
|
|
Pointer to the error status vector |
|
|
|
Pointer to a transaction handle whose value has been set by a previous |
Description
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().
Examples
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");
isc_print_status(status);
}
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.