Knowledgebase

TRNLOG Transaction Files

The TRNLOG (“tran-log”) transaction mode supports both transaction atomicity and transaction recoverability. TRNLOG files may be updated only within an active transaction. The server stores TRNLOG file updates in memory known as “preimage space” until the transaction is committed or aborted and logs transaction begin and commit operations and file updates to disk-based transaction log files. The use of preimage space guarantees atomicity and isolation of transaction operations: changes are made on an all-or-nothing basis and other clients do not see changes until the transaction is committed. The use of transaction logs guarantees recoverability of transactions in the event of an abnormal server termination.

In This Section Properties of TRNLOG Files Backup and Restore Options for TRNLOG Files When to Use TRNLOG Files Creating and Using TRNLOG Files

Properties of TRNLOG Files

Because FairCom DB logs updates made to TRNLOG files to its transaction logs, TRNLOG files are fully recoverable in the event of an abnormal server termination. The server ensures TRNLOG files are in a consistent state by performing automatic recovery at server startup. The server’s automatic recovery procedure involves scanning the transaction log to determine which transactions must be undone and which must be redone, based on the transaction log entries and the state of the files involved in the transactions.

The state of a TRNLOG file at a point in time is stored in a combination of the following locations:

• Updated buffers held in preimage space. (Pending updates held in server memory: this is volatile storage)
• Updated server data/index cache pages. (Committed updates held in server memory: this is volatile storage)
• Filesystem cache pages. (Committed updates written to filesystem but not flushed to disk held in system memory: this is volatile storage)
• Disk file contents. (Committed updates written to filesystem and flushed to disk: this is non-volatile storage)
• Transaction log contents. (Transaction state entries and file updates flushed to disk: this is non-volatile storage)

Only the disk file and transaction log contents are persistent. FairCom DB can guarantee recoverability of TRNLOG files in the event of an abnormal server termination because it logs to disk the transaction state and updated buffers necessary to guarantee recoverability. At startup, the automatic recovery procedure applies the necessary changes to TRNLOG data and index files to ensure the system is in a consistent transaction state.

Backup and Restore Options for TRNLOG Files

Backup copies of TRNLOG files can be made using the following approaches:

Online backup using dynamic dump

FairCom DB’s dynamic dump feature can be used to make a consistent point in time backup of TRNLOG files. The server maintains a full transaction log during the dump process and produces a dump stream file containing the disk contents of the TRNLOG files and the changes made during the dynamic dump. If it becomes necessary to restore the backup copy of the TRNLOG files, the ctrdmp utility can be used to extract the TRNLOG files from the dump stream file, restoring them to their state at the time of the backup.

Online backup using system disk snapshot

Some systems provide the ability to perform an instantaneous transparent copy of the contents of a disk. This approach can be used to backup TRNLOG files provided that the copy operation produces a point in time image of the disk and the server’s transaction logs are included with the TRNLOG files. If this is done, the TRNLOG files can be restored to a consistent transaction state corresponding to the time the backup was taken by restoring the saved files (transaction logs and TRNLOG files), then starting the server and allowing it to perform automatic recovery on the TRNLOG files. The disk-level snapshot is typically a feature offered by intelligent disk storage subsystems, such as a Storage Area Network (SAN).

Offline backup using file copy

An offline backup of TRNLOG files can be performed using system file copy utilities when the server is shut down or when the server is running and the files to be backed up are closed. It is important to ensure that the server is shut down or the files are closed before making a backup copy of files using a system file copy utility in order to ensure that all updated buffers are flushed to disk. Otherwise, data may be lost and the file may be in an inconsistent state.

When to Use TRNLOG Files

Create data and index files as TRNLOG files when operations on the files must be atomic and updates must be recoverable in the event of an abnormal server termination. If only atomicity is needed, PREIMG may be more appropriate.

The performance impact of TRNLOG due to checkpoint operations, transaction log flushing and transaction file buffer flushing can be minimized using transaction-related server configuration options such as:

CHECKPOINT_FLUSH

CHECKPOINT_INTERVAL

COMMIT_DELAY

LOG_SPACE

LOG_TEMPLATE

TRANSACTION_FLUSH

Creating and Using TRNLOG Files

To create a TRNLOG data or index file, include the TRNLOG filemode in the filemode value specified when creating the file.

• If using an ISAM-level file creation function, include TRNLOG in the dfilmod and ifilmod fields of the IFIL structure supplied to the function.
• If using a low-level file creation function, include TRNLOG in the filemode parameter supplied to the function.

FairCom DB allows updates to TRNLOG files only within an active TRNLOG transaction. To start a TRNLOG transaction, call the FairCom DB API function Begin() with a transaction mode of TRNLOG. An update on a TRNLOG file that is attempted outside a TRNLOG transaction fails with FairCom DB error TTYP_ERR (99, transaction type/filmod conflict).