System rollback restores the system to its status as of a specified point in time. For example, if company payroll processing was started at 1:00 PM and something went awry later in the afternoon, a system rollback can reset the system to the way it was at 1:00 PM, so processing could start again. If other applications using transaction processing files were running while the payroll processing was under way, these other files would also be rolled back to their 1:00 PM state. The Administrator should be aware of all files and related data that will be affected before starting a rollback to avoid interfering with multiple, unrelated systems sharing a FairCom DB Server.
A rollback, like recovery, involves a backup/restore script with different options to control how the rollback is to be done.
Running the Rollback Utility
The ctrdmp utility performs a system rollback as well as dynamic dump recovery. ctrdmp checks the first keyword in the script file. If the first line is !ROLLBACK the script is used for a rollback. If it isn’t, the script is considered a dynamic dump script and used for a dump or a recovery.
Note: As in dump recovery, be sure the particular FairCom Server undergoing the rollback is not running when ctrdmp starts, since ctrdmp is a FairCom Server and the two FairCom DB Servers operating simultaneously interfere with each other. Typically, error TCOL_ERR (537, transaction log collision) is observed under these conditions.
Perform a rollback as follows:
- Collect ctrdmp, the transaction log files covering the period from the target time to present, and the current log files into a working directory.
- Start ctrdmp the same way as any program in the environment.
- When prompted, enter the name of the rollback script file to be used.
The rollback begins automatically and produces a series of messages reporting recovery progress. A message returns when the utility completes a successful rollback.
A successful ctrdmp completion outputs the following message to CTSTATUS.FCS:
DR: Successful Dump Restore Termination
A failed ctrdmp outputs the following to CTSTATUS.FCS:
DR: Dump Restore Error Termination...: <cterr>
where <cterr> is a c-tree error code number.
If for some reason ctrdmp terminates prematurely (for example, a fatal error causes ctrdmp to terminate abnormally), the “Dump Restore Error Termination...” message may not be written to CTSTATUS.FCS. In that case, ctrdmp may have written error messages to standard output or to CTSTATUS.FCS before terminating that explains the premature termination.
Script File for Rollback
The format of the Rollback script is the same as a dynamic dump script. Accepted rollback options are as follows:
!COMMENT
Default: Off
Informs the FairCom Server that the remainder of the script file is for documentation purposes only and is not to be evaluated. Do not place keywords after this keyword.
!DATE <mm/dd/yyyy>
Date to perform the dynamic dump or rollback. If the date has already passed, the !FREQ interval is applied to find the next scheduled time. If no !DATE or !DAY is specified, today is assumed.
!#FCB <number of files>
Default: 30000 files
When restoring a large number of files from a dynamic dump backup with ctrdmp, the dump restore can possibly fail with error FNUM_ERR (22, file number out of range). Should you encounter this error with a very large number of restored files, consider the !#FCB option in your ctrdmp script file to increase this value.
Prior to V9, the default was 100, which could lead to error 22 in situations where this number was too low for ctrdmp.
!FILES
The !FILES keyword is followed by names of files to include in the dynamic dump or rollback. This must be the next to last keyword in the script file and it takes no arguments.
Filenames must begin following the !FILES keyword line with one line for each file. File names should not be listed on the same line as the !FILES keyword. The !END keyword terminates the list of files on a single line.
We strongly suggest that FAIRCOM.FCS be included in your list.
Members of a superfile cannot be individually “dumped.” The entire superfile must be dumped; that is, the name of the host superfile, not a superfile member, is placed in the list of files.
The * and ? wildcards are supported.
See !RECURSE for other options.
See also:
- Wildcard Support for File Names
- Files NOT to Include in Your Dynamic Dump Backup
- Non-ctree Files Included in a Dynamic Dump
- !COPY_NONCTREE
- !NONCTREEFILES
!ROLLBACK
!ROLLBACK must be the first entry in the script. It takes no argument. If !ROLLBACK is not the first entry, the script is interpreted as a dynamic dump script.
!SKIP
Default: !SKIP
Skip recovery for any file listed under the !FILES keyword if the file already exists.
Note: Be aware of the differences between using !SKIP with a recovery and with a rollback (see System Rollback (FairCom Database Rollback Guide, FairCom Database Rollback Guide)) where it must be used with caution.
Note: Only the files specified by the !FILES keyword will be restored. It is not necessary to restore all files contained in the dump.
!TIME <hh:mm:ss>
Time of day, on a 24-hour clock, to perform the dynamic dump or rollback. If the time has already passed, then the !FREQ interval is used to find the next scheduled time. If a !DATE or !DAY is specified without a time, then the time defaults to 23:59:59.
The script requires the use or leading zeros for the hour, minute, and second so that each contains two digits. For example, the valid entry for 6:00 is:
!TIME 06:00:00
The following is not a valid entry (notice the single digit, "6", for hours):
!TIME 6:00:00
If no time, day, or date is specified the dump begins immediately.
FairCom Database Forward Roll Guide
The forward dump utility, ctfdmp, can be used to recover from a catastrophic failure following the successful execution of a dynamic dump or from a full backup made after a safe, clean, controlled shutdown of the system.
Note: If you perform a rebuild or a compact on a data file that has transaction logging enabled, you will not be able to roll that file forward past the time of the rebuild/compact operation until a new backup has been completed. The act of compacting or rebuilding a file causes changes to the file that are not stored in the transaction logs. Attempting to roll forward will fail with “FWD: Roll-Forward Error Termination...12” unless the !SKIP option is enabled, and the forward roll operation will then proceed, excluding the affected files, which will be listed in CTSTATUS.FCS.
Preparing to Use the Forward Dump Utility
To prepare for using the forward dump utility, ctfdmp, follow these guidelines:
- Set the KEEP_LOGS configuration option to retain all log files. This setting causes log files no longer required for automatic recovery to be renamed instead of deleted. The extensions of log files are changed from .FCS to .FCA, which changes the transaction log files from “active” to “inactive”. These “old” log files may be needed to roll forward.
- Make periodic, complete backups using a dynamic dump or offline backup. The following files must be included in a complete backup:
- All data and index files.
- The file FAIRCOM.FCS.
- The S*.FCS files (automatically included in dynamic dump).
- Once all the necessary files have been backed up, the transaction log files (L*.FCS) may be deleted with one exception: DO NOT DELETE the most recent active transaction log file, which is the file of the form L<seven-digit number>.FCS with the highest valued seven-digit number.
- Following a safe, complete backup, save all transaction log files created until the next complete backup. Active transaction log files have names of the form L<log number>.FCS, with the number incremented by 1 for each new active transaction log. As specified in the KEEP_LOGS configuration value, when the FairCom Server creates a new active log it renames the active log being replaced from L<log number>.FCS to L<log number>.FCA and saves it as an inactive transaction log file.
Normally, when archiving all the logs, you would reestablish your forward roll starting point on a regular basis by means of a new dynamic dump. This could be done on a weekly basis keeping the previous week's dump and accumulation of logs as a further backup (a "grandfather" approach). It is easy to automate the archiving since their server automatically renames inactive logs to *.FCA and once renamed, the server is not going to access them so they can be archived without causing problems for the server.
Running the Forward Dump Utility for System Recovery
If the system has a catastrophic failure and preparations have been made as recommended above, the data can be recovered as follows:
- Restore the contents of the most recent backup, which can be a dynamic dump or a standard backup, provided it includes the files listed in step 2 above.
- If the restore is from a dynamic dump, be sure to include the !FORWARD_ROLL keyword in the dump recovery script. This keyword causes creation of a transaction start file for the recovered logs. The transaction start file will be named S*.FCA. After the restore is complete, rename S*.FCA to S*.FCS.
- Load all transaction log files saved between the time of that backup and the time of the catastrophic failure and rename all inactive transaction files in this group (i.e., log files with the extension .FCA) to give them the extension of an active transaction log file (i.e., extension .FCS).
- The following files should be present: the S*.FCS file created by ctrdmp, the data and index files restored from the dynamic dump, and all L*.FCS and L*.FCA (renamed to L*.FCS) files that have been archived in the default directory.
- Start the forward dump utility, ctfdmp, as any other program in the environment. See below for command-line arguments and other considerations. The ctfdmp utility can be used only when the FairCom Server is stopped unless you follow the guidelines listed later in this section.
The forward dump will proceed without any further instructions.
Note: Only transaction-processed files will be updated beyond the state they held when the backup was made.
Command-Line Arguments
ctfdmp accepts the command line arguments shown below. The first two arguments need to be used only if the application uses more than the default number of #FCB or the PAGE_SIZE is larger than default. If either of the first two command line arguments is used, they both must be specified as illustrated below. !SKIP is optional and does not cause an error termination if a file required during the forward roll is not accessible. Extreme care must be exercised if !SKIP is used, since the forward roll has no way of ensuring the integrity of data for files that are skipped.
CTFDMP [!#FCB <number of files>]
[!PAGE_SIZE <bytes per buffer page>]
[!SKIP]Using ctfdmp while FairCom Server is Running
It is recommended that the ctfdmp utility should be used only when the FairCom Server is stopped. The utility can be used when the FairCom Server is running only if:
- the utility is run in a directory other than the directory in which the server stores its transaction logs
and
- the files being rolled forward are not in use by the server.
Note: If the dynamic dump data was encrypted with Advanced Encryption (for example, AES), then the ctsrvr.pvf password file must be present with the master key information to decrypt and play back this data.
Directories
This utility does not read the script or the ctsrvr.cfg file.
If local_directory is used in the ctsrvr.cfg file, the local_directory path supplied is not part of the file name stored in the transaction logs, and therefore ctfdmp would expect to find the data and index files in the process working directory. For example, references to the file “foo.dat” in the transaction logs will not contain the relative path “data” so all the data, index, and *.FCS files would need to be in the same directory.
See Also:
ctfdmp - Forward Roll Utility
Operational Model:
- Standalone
ctfdmp
Used to restore data to a given time following a ctrdmp restore.
ctfdmp takes an optional !RP <name> argument to set the point in time to stop the forward roll. This argument is also used by the ctrdmp script option, as described in Rollback to New Restore Points with ctrdmp. To incrementally roll forward from there, rename the previous RSTPNT_CHKPNT*.FCS to S0000001.FCS (the start point for the ctfdmp), and supply a new !RP and transaction logs. More information on the !RP <name> can be found here: ctfdmp - Forward Roll Utility
Note: The ! prefix needs to be escaped when using the Unix Bash shell.
Environment Variable for Advanced Encryption Password
If this utility has advanced encryption enabled, it can read an encrypted password file instead of being prompted to enter the master password. To enable this, set the environment variable CTREE_MASTER_KEY_FILE to the name of the encrypted master password file.
ctfdmp accepts !RECOVER_DETAILS for additional progress notifications diagnostic output.
See also
- Maintaining Database Integrity in the c-tree Server Administrator's Guide
- ctrdmp - Dynamic Dump Recovery or System Rollback
- Rollback to New Restore Points with ctrdmp
Forward Roll Path Redirection
While restoring from a backup with the forward roll utility, ctfdmp supports applying file name redirection rules to the file names that appear in the transaction logs. To use this feature, run ctfdmp with the !REDIRECT option, specifying the name of a text file that contains the redirection rules. For example, the following command indicates that the file redir.txt contains redirection rules:
ctfdmp !REDIRECT redir.txt
Each line in the file contains the portion of the file name to replace and its replacement. Place double quotation marks around a string if it contains spaces. A line that begins with a semicolon is ignored.
Examples
To replace an empty path with output\:
;Replace empty path with output\
"" output\To replace Program Files(x86) with Program Files:
"Program Files(x86)" "Program Files"To replace production\ with test\:
production\ test\