The PREIMG (“pre-image”) transaction mode supports transaction atomicity but not transaction recoverability. PREIMG files may be updated only within an active transaction. The server stores PREIMG file updates in memory known as ‘preimage space’ until the transaction is committed or aborted. This 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 state of a PREIMG file at a point in time is stored in a combination of the following locations:
Only the disk file contents are persistent and unlike TRNLOG transaction file updates (discussed below), PREIMG file updates are not logged to the server’s transaction logs. For this reason, PREIMG files are not recoverable in the event of an abnormal server termination. In such a situation a PREIMG file is in an unknown state because an unknown number of updates may have not yet been written to disk at the time of the abnormal server termination. Also, because automatic recovery does not process PREIMG files, a PREIMG file rebuilt after an abnormal server termination is not guaranteed to be in a consistent transaction state. In such a situation, PREIMG files could contain data that was in the process of being committed but for which the commit had not yet been completed.
Backup copies of PREIMG files can be made using the following approaches:
Online backup using dynamic dump
Although automatic recovery is not available to PREIMG files, it is possible to perform periodic dynamic backups of PREIMG files using FairCom DB’s dynamic dump feature. Using the PREIMAGE_DUMP dynamic dump script option promotes PREIMG files to full TRNLOG files during the dynamic dump process. The promotion to a TRNLOG file means that a full transaction log is maintained during the dump process. This process guarantees that any changes made to the files during the backup are saved in these specially maintained transaction logs. The ability to dynamically back up user data files minimizes the loss of the automatic recovery feature with this mode. The dynamic dump produces a dump stream file containing the disk contents of the PREIMG files and the changes made during the dynamic dump. If it becomes necessary to restore the backup copy of the PREIMG files, the ctrdmp utility can be used to extract the PREIMG files from the dump stream file, restoring them to their state at the time of the backup.
Offline backup using file copy
An offline backup of PREIMG 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.
The benefit of PREIMG is that it avoids the overhead associated with writing to and flushing the transaction logs. If atomicity is required for a file but recoverability is not, PREIMG may be an appropriate choice. Some specific cases in which PREIMG may be appropriate include:
To minimize loss of unwritten cached PREIMG file updates in the event of an abnormal server termination, consider using WRITETHRU for PREIMG files or periodically calling the FairCom DB API function CtreeFlushFile() to flush PREIMG data and index cache pages to disk.
To create a PREIMG data or index file, include the PREIMG filemode in the filemode value specified when creating the file.
FairCom DB allows updates to PREIMG files only within an active transaction. To start a transaction, call the FairCom DB API function Begin() with a transaction mode of either PREIMG or TRNLOG. A PREIMG file may participate in either a PREIMG or a TRNLOG transaction. Regardless of which transaction type is specified, updates to PREIMG files are not logged to the server’s transaction logs. An update on a PREIMG file that is attempted outside a transaction fails with FairCom DB error TTYP_ERR (99, transaction type/filmod conflict).