TurboIMAGE/XL Database Management System Reference Manual (30391-90012)

128 Chapter4
Using the Database
TurboIMAGE/XL Logging Services
In the event of a system failure and subsequent recovery, only complete logical
transactions are re-executed, returning the database to a consistent state. Therefore, it is
essential that an application program use the intrinsics DBBEGIN and DBEND, or DBXBEGIN
and DBXEND, to mark the beginning and end of a sequence of calls which constitute a single
logical transaction.
For reasons explained more fully under "Locking Requirements for Logical Transactions"
in chapter 7, the following sequence of operations should be followed as closely as possible
when performing modifications:
1. Call DBLOCK to lock all data which must not be changed by other processes during the
transaction. This includes data to be read and data to be modified.
2. If you wish, read data using DBFIND and DBGET to determine the needed modifications.
3. Call DBBEGIN or DBXBEGIN to declare the beginning of modifications.
4. Make modifications using DBPUT, DBDELETE, or DBUPDATE.
5. If this is a dynamic transaction, call DBXUNDO in the event an error is encountered or
the modifications should be backed out for any other reason.
6. Call DBEND or DBXEND to declare the end of the modifications. However, if this is a
dynamic transaction and DBXUNDO was used to roll back a transaction, your program
logic should ensure that the subsequent call to DBXEND is not processed.
7. Call DBUNLOCK to release all of the locks.
NOTE The call to DBUNLOCK must occur after the call to DBXEND in the case of a
dynamic transaction when the database is opened in access mode 1, because
TurboIMAGE/XL requires strong locking for dynamic transactions.
Transaction Numbers
TurboIMAGE/XL maintains a transaction number for each user accessing the database.
Transaction numbers enable the DBRECOV recovery program to associate one access path's
log records with a particular transaction. This number is initialized by DBOPEN and
incremented each time DBBEGIN or DBXBEGIN is called, or for each single call to DBPUT,
DBUPDATE, or DBDELETE if it is not included in a transaction delimited by DBBEGIN and
DBEND, or DBXBEGIN or DBXEND. Transaction numbers are included in all DBBEGIN,
DBXBEGIN, DBPUT, DBUPDATE, DBDELETE, and DBMEMO log records. The transaction
number is always incremented as described, regardless of whether the user's process is
actually logging. A user's process can determine its transaction count (and whether the
database and user is logging) by calling DBINFO using mode 401.
User Logging and Process Suspension
The MPE/iX logging intrinsics will suspend a calling process if the logging buffers become
full. Consequently, a user's process which calls TurboIMAGE/XL can become suspended,
for example, if a tape log file reaches the end of a reel and logging buffers become full
before a new tape can be mounted.