When you call db_update(), the current transaction is written to the transaction log file as well as to the database, (assuming you have enabled transaction logging). The transaction log file is a record of transactions written to the database that can be used for recovery if there are problems with the database. Records may also have been locked during the transaction when they were read from the database (see Record Locking ).
The function db_update() has one parameter, which specifies a set of possible actions to perform in addition to updating the database.
You can choose to unlock all the records that were logged during the transaction, or to leave them locked. You can also choose only to unlock records if the transaction succeeded.
You can choose to checkpoint, or secure, the changes made by the transaction or not.
The COMMIT flag guarantees that the database is updated in the sense that the changes are visible to other users, but not necessarily that they have been made permanently. In the event of a power failure or similar catastrophe the recovery process that the database then undergoes may cause the transaction to be rolled back and hence lost. If this happens the transaction will be lost completely - it is not possible for partial transactions to remain, or for other transactions that were not rolled back to reflect updates made by the lost transaction.
In the absence of other flags locked records remain locked when the COMMIT flag is used.
db_update(COMMIT)
is equivalent to
db_commit()
.
You can force the transaction to be written permanently if you pass the FLUSH_LOG flag to db_update(). Once db_update(FLUSH_LOG) returns, the transaction is secure even if the database needs to be recovered because of a subsequent system or power failure.
Flushing records is slower than committing them to a database, but it is safer because it allows you to recover a database if you need to.
db_update(CHECKPOINT)
is similar to
db_update(FLUSH_LOG)
in that it secures
the transaction. In addition it unlocks any records that the program had locked.
db_update(CHECKPOINT)
is equivalent to
db_checkpoint()
.
You should take care to write critical transactions securely, but avoid indiscriminate use of CHECKPOINT or FLUSH_LOG commits. These operations are expensive, particularly prior to release 4.620, and using them excessively is a common cause of poor performance.