|
|
|
Restore Points are created using the ctQUIET() API function. A Restore Point can be either a Lightweight Restore Point (RSTPNT) or a Restore Point with a full Checkpoint Restore Point (CHKPNT).
Lightweight Restore Point
To establish a Lightweight Restore Point, call:
ctQUIET(NULL,timeout,ctQTlog_restorepoint)
This call blocks new transactions from starting and waits for up to timeout seconds before aborting pending transactions.
The timeout parameter indicates the number of seconds ctQUIET() will wait for transactions to complete before aborting active transactions. If all the active transactions complete before timeout seconds, then no transactions will be aborted and the Restore Point will be written as soon as possible. When ctQUIET() is called, new transactions are immediately blocked, and ctQUIET() will not write the Restore Point in the log until all transactions complete or are aborted.
When all transactions have been committed or aborted, it writes a log entry with transaction type of RSTPNT. The log entry contains the time of the Restore Point and the name of the file that contains the log number and offset of the Restore Point entry. The formatting and naming of the Restore Point file is explained in Restore Point Files.
FairCom Server guarantees that each Restore Point has its own unique timestamp by ensuring that successive Restore Points have a minimum interval of at least 5 seconds. As a matter of efficiency, we would expect the actual interval between Restore Points to be much longer than a few seconds; more likely an interval on the order of 5 minutes or longer. The interval is under the control of the application.
The advantage of creating a Restore Point using ctQTlog_restorepoint without ctQTlog_checkpoint is that there is much less overhead writing a short RSTPNT log entry compared to creating and writing an entire checkpoint.
Checkpoint Restore Point
To create a Restore Point with a full checkpoint, call ctQUIET() with both ctQTlog_restorepoint and ctQTlog_checkpoint:
ctQUIET(NULL,timeout,ctQTlog_restorepoint | ctQTlog_checkpoint)
As with a lightweight Restore Point, this call blocks new transactions from starting and waits for up to timeout seconds for existing transactions to complete, after which it aborts all transactions that are still pending. Then it writes a checkpoint (with a mode of RESTORE_CHECK) to the transaction log instead of writing a RSTPNT entry and creates a Checkpoint file. The formatting and naming of the Checkpoint file is explained in Restore Point Files.
Note: ctQTlog_restorepoint and ctQTlog_checkpoint cannot be used with any other blocking modes.
Permitting New Transactions
After the ctQUIET() call returns successfully (after either a Lightweight Restore Point or a full Checkpoint Restore Point), call ctQUIET() with an action of either ctQTunblockLogRestore or ctQTunblockALL to permit new transactions:
ctQUIET(NULL,timeout,ctQTunblockLogRestore)
Before calling ctQUIET() a second time to unblock new transactions, it may be desirable to start an external (i.e., separate from FairCom Server) activity log managed by the application. This log can be used to recover updates made after the Restore Point.
Notes
A ctQUIET() call to establish a Restore Point cannot be mixed with any other blocking actions. An application that attempts a TRANBEG after ctQUIET() has been called to establish a Restore Point will be blocked: the TRANBEG will not return from the server until the second call to ctQUIET() is made. An application whose transaction is aborted by the first ctQUIET() call will receive an error return of QTAB_ERR.
Note: A minimum interval of 1 second is enforced between calls to establish a Restore Point. While it is very unlikely that anyone would make calls to establish Restore Points with a frequency even approaching 1 second, the ctQUIET() logic ensures the interval will be at least 1 second. A call to ctdefer() sleeps the ctQUIET thread if necessary to enforce the time interval.
Note: Unless COMPATIBILITY NONADMIN_QUIET is in the configuration file, a Restore Point can only be established by a client in the ADMIN group.
Note: If a client successfully calls ctQUIET() to establish a Restore Point and then terminates without unblocking new TRANBEG calls through a second call to ctQUIET(), the server will force a second call. Ordinarily the ctQUIET blocks (for other types of block requests) persist when the blocking thread terminates without issuing an unblock request.
Active Restore Points
The configuration option KEEP_RESTORE_POINTS N, which defaults to 1, specifies the number of Restore Points that FairCom Server considers to be active Restore Points for the purpose of determining which transaction log files must remain active in order to be able to roll back to the Nth most recent Restore Point. When a new Restore Point is created, the oldest Restore Point is no longer considered active.
Note: To be able to roll back to a particular Restore Point, c‑tree must keep the transaction log that contains the checkpoint preceding that Restore Point, plus all subsequent transaction logs. Therefore, if you create a Restore Point and never create another Restore Point, all transaction logs from that point forward will be kept as active logs. So when using Restore Points, it is advisable to periodically establish new Restore Points so that FairCom Server can delete older transaction log files.
