Knowledgebase

PREIMG Transaction Files

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.

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

Properties of PREIMG Files

The state of a PREIMG 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)

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 and Restore Options for PREIMG Files

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.

When to Use PREIMG Files

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:

• Using TRNLOG data files and PREIMG indexes if you are willing to rebuild the indexes after an abnormal server termination.
• Using PREIMG on files that can be re-created in the event of an abnormal server termination.

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.

Creating and Using PREIMG Files

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

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

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).