|
|
|
There are two major aspects to transaction processing, atomicity and automatic recovery. These are related yet different aspects of transaction processing, and not all products supply both. FairCom DB API provides a set of functions and file modes that cover both aspects of transaction processing.
|
|
|
Often, when updating a table, you perform several functions in a group. For instance, when creating an invoice, you update several tables: the account balance in the customer file, the invoice file, an invoice detail file, inventory records, and others. It is important that all of these actions take place to keep the files synchronized. If some of the actions take place, but not all, your files may be out of sync, and it can be difficult to correct the problem later. If one action cannot take place, it would be best to not let any take place. We call this atomicity. The FairCom DB API API provides functions that provide this feature. You can mark a set of operations so that none will take place unless they can all take place. The API goes beyond this, allowing you to create "savepoints" where you can partially back out a group of operations, and "roll back" transactions to a given point, so that you can restore your data back to a state that it was in sometime in the past.
|
|
|
Once you establish full transaction processing by creating tables using the CTCREATE_TRNLOG mode, you can take advantage of the automatic recovery feature. Atomicity will generally prevent problems of files being partially updated. However, there are still situations where a system crash can cause data to be lost. Once you have signaled the end of a transaction, there is still a "window of vulnerability" while the application is actually committing the transaction updates to disk. In addition, for speed considerations some systems buffer the data files and indexes, so that updates may not be flushed to disk immediately. If the system crashes, and one of these problems exists, the recovery logic detects it. If you set up the system for automatic file recovery, the recovery logic automatically resets the table back to the last, most complete, state that it can. If any transaction sets have not been completed, or "committed", they will not affect the table.
Error During Automatic Recovery
An error 14, FCRP_ERR, indicates that FairCom Server detected that files appear corrupt at open. This occurs if files have been updated but not properly closed. They were not processed by automatic recovery so they are in an unknown (inconsistent) state.
If your transaction logs are corrupted, preventing automatic recovery from occurring, you can either:
or
|
|
|
Only tables created with the create modes CTCREATE_PREIMG and CTCREATE_TRNLOG will participate in a transaction. This means that the ctdbBegin(), ctdbCommit(), and ctdbAbort() functions provide transaction atomicity when used with records from these two types of tables. This also means that these three functions do NOT provide atomicity when used with records from other types of tables, such as CTCREATE_NORMAL tables. Record operations (and locks) on NORMAL tables are handled as if there was no transaction running. For CTCREATE_PREIMG and CTCREATE_TRNLOG tables to provide the promised protections, all operations that add, modify, and delete records in these tables must be done inside a transaction (between calls to ctdbBegin() and ctdbCommit() / ctdbAbort()). This is enforced by FairCom DB API; attempting to modify records outside of a transaction for these tables will generate an error.
Tables created with CTCREATE_PREIMG mode will participate in a transaction, and will benefit from transaction atomicity, but will not have automatic recovery, because the transaction log files needed for automatic recovery will not be generated. This saves disk space and gives speed gains, at the cost of more difficult recovery in case of a crash.
Tables created with CTCREATE_TRNLOG have all the positive attributes of CTCREATE_PREIMG but will also generate the transaction logs necessary for automatic recovery.
|
|
|
Using our example from above, you don’t want to have the transaction group involve more than one invoice. You also don’t want it to involve less than a whole invoice.
Record locks are held on updated records for the duration of the transaction, so you don’t want to make the transaction group too large or it will consume the system resources and cause delays. On the other hand, you may not want to make the transaction group too small or the effect of grouping actions is lost.
ctdbBegin() starts a new transaction. You will need to decide on logical groups of file updates that can be delimited as transactions.
/* start a new transaction */
if (ctdbBegin(hAnyHandle) != CTDBRET_OK)
{
printf("Begin transaction failed\n");
}
|
|
|
When all update operations have been completed, terminate a transaction by calling ctdbCommit() to commit all changes.
/* commit transaction */
if (ctdbCommit(hAnyHandle) != CTDBRET_OK)
{
printf("Commit transaction failed\n");
}
Call ctdbAbort() to terminate the transaction and abort all changes done since the start of the transaction.
/* abort transaction */
if (ctdbAbort(hAnyHandle) != CTDBRET_OK)
{
printf("Abort transaction failed\n");
}
|
|
|
There are times when you want to abort only a portion of a transaction. You may be processing several optional paths of a program, going down one branch, then backing out and trying another branch. It may be possible that you don't want any of the updates to occur until you are completely finished, but you want the flexibility to back out part of the updates. Another possibility would be if you have run into some form of update error, such as an add record failing due to a duplicate key. You would want to back up to a prior point, correct the problem, and continue. The FairCom DB API API allows you to implement this by using savepoints.
A savepoint is a temporary spot in the transaction that you may want to roll back to without having to abort the entire transaction. During a transaction, when you want to put a place mark in the process, issue a ctdbSetSavePoint() call. This does not commit any of the updates. The function returns a savepoint number, which you should keep track of. You can make as many ctdbSetSavePoint() calls as you wish during a transaction, and each time you will be given a savepoint number, which is unique to the current transaction.
When you decide that you want to roll back to a savepoint previously saved by a call to ctdbSetSavePoint(), issue a ctdbRestoreSavePoint() call, passing in the desired savepoint number. This returns your data to the state it was at the point you issued the specified ctdbSetSavePoint() call, without aborting the entire transaction.
