HP 3000 Manuals HP 3000 Manuals
TurboIMAGE/XL Logging Services
TurboIMAGE/XL provides logging through the following two MPE/iX services:
* Transaction Management (XM) logging
* User logging
XM logging is used to ensure the physical integrity of the database. It
is transparent to the user because it is automatically enabled unless
AUTODEFER is enabled. Dynamic roll-back recovery (explained in chapter
7) works in conjunction with XM and ensures the logical integrity of the
database. Dynamic roll-back uses XM to roll back dynamic transactions
online while other database activity is occurring. Dynamic transactions
are defined later in this chapter. User logging, which is described
below, is not required for dynamic roll-back recovery, but is recommended
to guard against a hard disk crash.
User logging is used to ensure the logical integrity of the database. It
is initiated by the user and can be used for several purposes. For
example, user logging is required to perform roll-forward recovery. It
can also be used to keep a record of individual database transactions
(see the description of the >FILE command of DBRECOV in chapter 8). In
addition, it is sometimes used for audit purposes to keep a record of all
database transactions. Because some user logging considerations are
important to applications, they are discussed below. For a more complete
discussion of TurboIMAGE/XL logging services, refer to chapter 7.
What User Logging Does
The user logging and recovery facility enables all database modifications
to be logged automatically to a tape or disk log file. In the event of a
system failure the log file is read to re-execute transactions or
identify incomplete transactions, depending on what type of recovery
process is being used. In addition, the transaction logging system can
be a useful tool for auditing. The log file is actually a record of all
modifications to the database. The intrinsic DBMEMO, capable of logging
user text, facilitates interpretation of the log files for future
reference.
The database administrator is responsible for enabling or disabling the
logging and recovery processes and generating backup database copies,
thus making logging a global function controlled at the database level
rather than at the individual user level. A process is said to be
logging if all of the following are true:
* The database has been enabled for logging by the database
administrator.
* A logging process has been initiated from the system console.
* The user is accessing the database in one of modes 1 through 4.
How User Logging Works
The following TurboIMAGE/XL intrinsics are automatically logged when the
database is enabled for logging and a user opens the database in a mode
which permits modifications: DBOPEN, DBCLOSE, DBPUT, DBUPDATE, DBDELETE,
DBBEGIN, DBEND, DBMEMO, DBXBEGIN, DBXEND, and DBXUNDO.
TurboIMAGE/XL calls the MPE/iX logging intrinsics OPENLOG, WRITELOG, and
CLOSELOG in order to log information to the log file. When a database is
opened, DBOPEN calls the OPENLOG intrinsic using the log identifier and
password stored in the database root file. If this call succeeds, DBOPEN
calls WRITELOG to log a DBOPEN log record containing information about
the database and the new user. The WRITELOG intrinsic is also used to
log information when the TurboIMAGE/XL intrinsics DBPUT, DBDELETE, and
DBUPDATE are called. WRITELOG is called after all error checks are made,
but before actually modifying the working database. Consequently, a log
record is not written until the TurboIMAGE/XL procedure has committed
itself to succeed. WRITELOG is also used by the TurboIMAGE/XL intrinsics
DBBEGIN, DBEND, DBMEMO, DBXBEGIN, DBXEND, and DBXUNDO.
DBCLOSE (mode 1) calls WRITELOG to log a DBCLOSE log record, and then
calls CLOSELOG to terminate access to the log file. If a transaction
initiated with DBBEGIN fails to call DBEND, or a DBXBEGIN does not have a
matching DBXEND, DBCLOSE causes an abnormal DBEND or DBXEND log record to
terminate access to the log file. DBCLOSE also causes an abnormal DBEND
or DBXEND log record to be written if the program aborts with an
unfinished transaction.
User Logging and Logical Transactions
TurboIMAGE/XL transactions are of two basic types--single and logical. A
single transaction is a single call to an intrinsic. It is not delimited
by begin and end intrinsics. A logical transaction can be considered as
the basic work unit performed against a database. A logical transaction
could consist of a single modification, but more typically consists of
several calls to TurboIMAGE/XL intrinsics which lock, read, modify, and
unlock information. Logical transactions transfer the database from one
consistent state to another, but in the midst of a multiple-step
transaction, the database could be temporarily inconsistent with itself.
(For an example, see "Logical Transactions" in chapter 7.)
TurboIMAGE/XL logical transactions are defined in Table 4-4 .
Table 4-4. Types of Logical Transactions
--------------------------------------------------------------------------------------------
| | |
| Transaction | Definition |
| | |
--------------------------------------------------------------------------------------------
| | |
| Static | A logical transaction that begins with a DBBEGIN call and ends |
| | with a DBEND call. A static transaction spans only one |
| | database. This type of transaction can be recovered with |
| | DBRECOV. |
| | |
--------------------------------------------------------------------------------------------
| | |
| Multiple database | A logical transaction that spans more than one database. A |
| | multiple database transaction begins with a DBBEGIN call and |
| | ends with a DBEND call. This type of transaction is recovered |
| | with DBRECOV. |
| | |
--------------------------------------------------------------------------------------------
| | |
| Dynamic | A logical transaction that begins with a DBXBEGIN call and ends |
| | with a DBXEND call. Unlike non-dynamic transactions (that is, |
| | static and multiple database transactions), dynamic transactions |
| | can be rolled back with a call to the DBXUNDO procedure and are |
| | automatically rolled back in the event of a system failure or |
| | program abort. |
| | |
--------------------------------------------------------------------------------------------
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
necessary 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.