isc_rollback_retaining()
Go Up to API Function Reference
Undoes changes made by a transaction and retains the transaction context after the rollback.
Syntax
ISC_STATUS isc_rollback_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_rollback_retaining() rolls back 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 existing transaction handle it is, in effect, keeping the transaction open after the rollback. This results in improved performance by allowing an application to minimize the overhead of initiating additional transactions. isc_rollback_retaining() allows you to roll back 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 or rollback.
To audit the rollbacks 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().
Because the errors that trigger a rollback are frequently in the transaction context, you may find that calling isc_rollback_retaining() leads to a repetition of the original error. Unless you include error detection code for that case, you may inadvertently create an inescapable code loop.
Examples
The following C/C++ code rolls back a transaction, prints a message, and starts a new transaction with the same handle within the same request:
if (!isc_rollback_retaining(status, &retained_trans)) {
fprintf(stderr, "Rolled back and retained\n");
isc_print_status(status);
}
The following C/C++ code rolls back a transaction, prints a confirmation message, starts a new transaction with the same handle within the same request, or, if the rollback fails, prints an error message and rolls back.
isc_rollback_retaining(status, &retained_trans);
if (status[0] == 1 && status[1]) {
fprintf(stderr, "Error retaining; rolling back instead.\n");
rb_status = isc_rollback_transaction(status, &retained_trans);
}
else {
fprintf(stderr, "Rollback retaining successful.\n");
tr_count++; /* Increments the number of recycles. */
}
Return value
isc_rollback_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.