Performing Archival Logging

The Maintenance utility (GUI or BUTIL command line) provides a way to roll forward archival log files into the data files. See also the chapter Logging, Backup, and Restore.

The BUTIL ROLLFWD command recovers changes made to a data file between the time of the last backup and a system failure. If a system failure occurs, you can restore the backup copy of your data file and then use the BUTIL ROLLFWD command, which applies all changes stored in the archival log to your restored data files. Do not use this command unless you have restored data files from backup.

Note: You cannot take advantage of the ROLLFWD command unless you both enable the MicroKernel’s Archival Logging Selected Files option and back up your files before a system failure occurs.

You can also use the ROLLFWD command to produce an output file of logged operations. The ROLLFWD command can produce the output file either before you roll changes forward or at the same time as the roll forward.

You can roll forward a single file, all data files on a volume, all data files on a drive, or a list of files, volumes, and/or drives.

Using the GUI

Access Maintenance from the operating system Start menu or Apps screen or from the Tools menu in PSQL Control Center.

Within the Maintenance window, click Data > Roll Forward The Roll Forward dialog box appears.

Figure 36 Roll Forward Dialog

Select the specific operation type: single file, list of files, volume name, or drive letter. When you select either volume name or drive letter, you must insert a back slash (\) or forward slash (/) at the end (for example, \\server\vol1\ or D:\).

You can generate a log file, called a dump file, of all the Btrieve operations required to perform the roll forward tasks.

By default, this file is not created. Select the Generate Dump File check box to generate a file. You can also specify the following options.

Table 80

Roll Forward GUI Options

Only Create Dump File

Indicates that only the dump file is to be created, and the roll forward operation is not to be performed.

Dump File Name

Contains the name of the dump file, which must begin with a slash and not contain a drive letter or server/volume name.

Data Buffer Length

Indicates the number of data buffer bytes to write to the dump file for each Btrieve operation.

Key Buffer Length

Indicates the number of key buffer bytes to write to the dump file for each Btrieve operation.

Display Numbers as HEX

If you select this option, the numbers in the dump file output are formatted as hexadecimal. If you do not select this check box, the numbers are displayed in decimal format.

Verbose

Includes additional information like user name, network address, and time stamp in the dump file.

Note: If the key buffer or the data buffer is not an input parameter for the particular Btrieve operation, nothing is written to the dump file.

Click Execute to generate the dump file and/or perform the roll forward operation. If the data is valid, the Roll Forward Status dialog box appears.

Figure 37 Roll Forward Status Dialog Box

As files are processed, they are added to the scrolling list box which displays the file name and the PSQL status code returned from the roll forward operation.

If an error occurs during processing, the Roll Forward Continue on Error dialog box appears. This dialog box allows you to continue without being prompted again, to continue and be prompted again, or to stop processing files.

Figure 38 Roll Forward Continue on Error Dialog Box

Using the Command Line

This section explains the syntax for the command line usage of Roll Forward.


sourceFile	The fully qualified name of a data file for which to roll forward changes. For Windows platforms, you do not need to specify the name of the path if the data file resides in the same directory as your current directory.
drive	A drive letter for which to roll forward changes. End the volume name with a backslash (\) or forward slash (/), as in F:\ or F:/.
listFile	The fully qualified name of a text file containing the paths of files, volumes, or drives for which to roll forward changes. Separate these paths with a carriage return/line feed. If the Maintenance utility encounters an error, the utility stops rolling forward the current file, but does not roll back the changes already made. If you specify the /A option, the utility continues rolling forward with the next file.
/LdumpFile	Produces an output file, but does not roll forward.
/WdumpFile	Rolls forward and produces an output file.
dumpFile	The file name of the output file to which the Maintenance utility writes a list of logged operations. The default is \BLOG\BROLL.LST, relative to the root of the physical drive. The file name cannot contain a drive letter or volume name and must start with a forward slash (/) or backslash (\). The Maintenance utility places the file on the same volume as the BLOG.CFG file.
/TdataLength	Specifies the length of the operation’s data buffer to write to the output file. If you do not specify this option, the utility does not include data buffer contents in the output file.
/EkeyLength	Specifies the length of the operation’s key buffer to write to the output file. If you do not specify this option, the utility does not include key buffer contents in the output file.
/H	Instructs the utility to show numbers in the output file in hexadecimal notation. If you do not specify this option, numbers in the output file are in ASCII format. This option affects the format of the Entry Count, Op Code, Key Number, and Data Length fields.
/V	Instructs the utility to include additional information (such as the user name, network address, and time stamp) in the output file.
/O	Specifies the owner name of the data file, if required. An owner name is required if you request an output file of logged operations and the backup copy of the data file has an owner name for read-only access. If more than one file has an owner name, the respective owner names must be separated by commas. See Owner Names for more information.
/A	Specifies that if you are rolling back more than one file and the Maintenance utility encounters an error, the utility continues rolling forward with the next file. When you do not specify this option, the utility stops rolling forward if it encounters an error. The utility does not roll back the changes already made. Note: When you use the /A option, you might want to redirect output to a file, as described in Redirecting Error Messages and Command Files.
/UID<name> /UIDuname	Specifies the name of the user authorized to access a database with security enabled.
/PWD<word> /PWDpword	Specifies the password for the user who is identified by uname. Pword must be supplied if uname is specified.
/DB<name> /DBdbname	Specifies the name of the database on which security is enabled. If omitted, the default database is assumed.

Note: If the key buffer or the data buffer is not an input parameter for the particular Btrieve operation, nothing is written to the dump file.

Examples

Example A The following example recovers changes to the CLASS.MKD file from the default archival log and log location.

butil -rollfwd file_path\PSQL\Demodata\class.mkd

(For default locations of PSQL files, see Where are the PSQL files installed? in Getting Started With PSQL.)

Example B This example recovers changes and outputs them to all files on the d:\ volume with the following options:

•

use default dump file

•

dump 32 bytes of the data buffer

•

dump 4 bytes of the key buffer

•

dump in hex mode

butil -rollfwd d:\ /W /H /T32 /E4

Example C The following example does not perform roll forward but only outputs the changes to the files listed in files.txt with the following dump options:

•

use d:\temp\files.lst as the dump file

•

use verbose mode

•

data files have owner names: own123 and own321

•

do not dump data or key buffer

butil -rollfwd d:\temp\files.txt /L\temp\files.lst /V /Oown123,own321