NetWare Btrieve Roll Forward Utility

The NetWare Btrieve Roll Forward utility is an interactive workstation utility that allows you to recover changes made to a Btrieve file between the time of the last backup and a system failure. The changes are stored in a log file.

If a system failure occurs, you can restore the backup copy of your Btrieve file and run the Roll Forward utility. The utility applies the changes stored in the log file to your backup copy.

This section discusses the following topics:

• Using the Roll Forward Utility in Various Environments
• Overview of the Recovery Process
• Setting Up Files for Logging
• Running the Roll Forward Utility in a DOS Environment
• Running the Roll Forward Utility in an OS/2 or MS Windows Environment
• Using the Roll Forward Pulldown Menus
• Setting Options for the Roll Forward Utility
• Placing Items in the Queue
• Viewing Items in the Queue
• Rolling Forward Items in the Queue
• Special Considerations When Using Logging and the Roll Forward Utility
• Example of Restoring a Data File

Using the Roll Forward Utility in Various Environments

Roll Forward utilities are available for DOS, OS/2, and MS Windows operating environments, as follows:

• BROLLFWD.EXE---The Roll Forward utility for the DOS operating environment.

  You run BROLLFWD from the command line. (The Roll Forward utility DBROLL.EXE, which was used in the DOS environment in previous releases, is obsolete.) For more information, see Running the Roll Forward Utility in a DOS Environment.

• PBROLL.EXE---The Roll Forward utility for the OS/2 environment.

  You run PBROLL interactively.

• WBROLL.EXE---The Roll Forward utility for the MS Windows environment.

  You run WBROLL interactively.

  NOTE:  The procedure for running PBROLL and WBROLL is the same. For more information, see Running the Roll Forward Utility in an OS/2 or MS Windows Environment.

Overview of the Recovery Process

In general, use the steps in the following procedure first to enable the NetWare Btrieve logging feature and then, in the event of a system failure, to recover your Btrieve files.

1. Back up your data files (and any current log files, if applicable), enable the logging feature using the Btrieve Setup utility, and create a log configuration file.

   For more information, see Setting Up Files for Logging and Backing Up Data Files, and Example of Restoring a Data File.

   WARNING:  You cannot take advantage of the Roll Forward utility unless you have enabled the logging feature and created a log file before a system failure.

2. Ensure that your system meets the system requirements for running the Roll Forward utility and then start the utility.

   For more information, see Running the Roll Forward Utility in a DOS Environment and Running the Roll Forward Utility in an OS/2 or MS Windows Environment.

3. Set the appropriate Roll Forward utility options in one of the following ways:

   • Activate the program features using the options from the Roll Forward utility's Options menu (described in Setting Options from the Options Menu).
   • Change the Roll Forward utility's options manually by editing the initialization file (described in Setting Options Manually in the MS Windows Initialization File).

     For more information, see Setting Options for the Roll Forward Utility.

4. Select the Btrieve file (or files) you want to recover by adding that item to the Roll Forward utility's queue.

   For more information, see Placing Items in the Queue.

5. Run the Roll Forward utility, which applies the changes stored in the log file to your backup copy of the Btrieve file.

   For more information, see Rolling Forward Items in the Queue.

   NOTE:  For an example of the procedures used to handle data and log files in a roll-forward operation, see Example of Restoring a Data File.

Setting Up Files for Logging

To take advantage of NetWare Btrieve's logging feature and the Roll Forward utility, you must first set up your Btrieve files for logging, as described in the following procedure. Subsequent sections discuss each step in this process.

1. Back up your data files before you activate the logging feature.

   For more information, see Backing Up Data Files.

2. Activate Btrieve's logging configuration option using the Setup utility (BSETUP.NLM).

   For more information, see Activating the Btrieve Logging Option.

3. Create the log configuration file, BLOG.CFG.

   For more information, see Creating the Log Configuration File.

Backing Up Data Files

Be sure to make a backup copy of your Btrieve files before logging begins.

When you activate logging for a given file, NetWare Btrieve uses the corresponding log file to record all the operations that change the specified file. Btrieve continues appending subsequent operations to the end of this log file until you delete the log file. Consequently, it is important to perform periodic maintenance to reduce the size of your log files.

IMPORTANT:  Every time you back up your Btrieve files, delete the associated log files before executing any further operations that could change those log files. Synchronizing the backup data files and the associated log files is critical to recovering operations successfully.

IMPORTANT:  Keep the original copy of the data files and their associated log files until you have successfully rolled the data files forward using the original logged information. Be aware that the Roll Forward operation modifies the log files after each roll forward attempt, so you cannot apply log entries twice to the same data files.

IMPORTANT:  Be aware also that once you have performed a Roll Forward operation, Btrieve does not retain the original logging information. Instead, if you have enabled the logging feature, Btrieve adds to the log file a record of all the operations that affect the specified file subsequent to the last Roll Forward operation.

IMPORTANT:  For an example of the procedures used to handle data and log files in a roll-forward operation, see Example of Restoring a Data File.

Activating the Btrieve Logging Option

You can activate NetWare Btrieve's logging feature by specifying Yes for the Logging of Selected Files configuration option in the Setup utility. The default setting for this option is No.

If you did not specify Yes for this option when you configured NetWare Btrieve, complete the following steps to activate the Btrieve logging feature:

1. Run the Setup utility (BSETUP.NLM).

2. When the Available Options menu appears, select Set Btrieve Configuration.

3. When the Current Btrieve Configuration screen appears, specify Yes for the Logging of Selected Files option.

4. Press Escape.

5. When the Save Configuration Changes? window appears, select Yes.

6. To have your changes take effect, unload Btrieve using the BSTOP command and then reload it using the BSTART command.

   Btrieve reloads with the logging feature activated.

For additional information about this procedure see Logging of Selected Files in Chapter 3, "Installing and Configuring NetWare Btrieve."

Creating the Log Configuration File

The name of the NetWare Btrieve log configuration files is BLOG.CFG. It specifies the names of all the Btrieve files for which you want to log changes on a given volume.

You should create a BLOG directory at the root of each volume containing Btrieve files for which you want to log changes. You can then create a BLOG.CFG file in each BLOG directory and place entries in it, as follows:

1. Create an empty BLOG.CFG file.

   You can use any text editor to create the BLOG.CFG file. Remember that you must create a BLOG.CFG file in the BLOG directory of each volume on which you want to log files.

2. Open the BLOG.CFG file.

3. Create an entry in the BLOG.CFG file for each Btrieve file for which you want to log operations.

Use the following format to create the BLOG.CFG file entries:

\ directory1\ btrvFile[=\ directory2\ logFile]

Make sure each entry fits completely on one line. (Each line can contain a maximum of 256 characters.) If you have room, you can place multiple entries on the same line, but you must separate each entry with at least one space.

NOTE:  A single log entry cannot contain any spaces, although you must separate multiple entries on the same line with at least one space.

If you do not provide a name for the log file, Btrieve assigns the original filename plus a .LOG extension to the file when you first open it.

For example, assume that you did not specify a name for log file associated with the Btrieve file TEST01.DAT located in the directory TEST. Btrieve would assign the full name \TEST\TEST01.LOG to the default log file, which in this case, shares the same directory as the Btrieve file.

The following three examples show sample entries in the file \BLOG\BLOG.CFG on the SYS: volume of the CORP server. Each entry produces the same result: activity in the file \DATA\B.BTR on the CORP server's SYS: volume is logged into the file \DATA\B.LOG on the CORP server's SYS: volume.

The next example (again, a sample entry in \BLOG\BLOG.CFG on the CORP server's SYS: volume) shows how to log activity to a volume other than the Btrieve data file's volume:

This entry directs Btrieve to log activity in the file \DATA\B.BTR on the CORP server's SYS: volume into the log file \DATA\B.LOG on the VOL1: volume of the CORP server. You can also use the following syntax to achieve the same result:

Running the Roll Forward Utility in a DOS Environment

To run the Roll Forward utility in a DOS environment, enter the BROLLFWD command using the following format:

BROLLFWD < btrvFile | @listFile | /A> [/D: nn] [/T: nn] [/K: nn] [/H] [/V] [/L] [/O: ownerName]

The following list describes the BROLLFWD command syntax:

Running the Roll Forward Utility in an OS/2 or MS Windows Environment

The following list shows a few ways you can run the Roll Forward utility:

NOTE:  The following information applies to both OS/2 and MS Windows operating environments, but the screen examples show MS Windows screens only.

To use the Roll Forward utility in the OS/2 and MS Windows environments, complete the following steps:

1. Back up your data and log files.

   For more information, see Backing Up Data Files.

2. Set the Roll Forward utility's program options.

   For more information, see Setting Options for the Roll Forward Utility.

3. Place in the utility's queue all the items you intend to roll forward.

   For more information, see Placing Items in the Queue.

4. Start rolling forward the items in the queue.

   For more information, see Rolling Forward Items in the Queue.

Following is a brief description of the Roll Forward utility's pulldown menus. Subsequent sections describe each step in the Roll Forward recovery procedure in detail.

Using the Roll Forward Pulldown Menus

After starting the Roll Forward utility, you can access two pulldown menus: Queue and Options.

HINT:  If you are not using a mouse, you can access the menus by pressing and holding the Alt key while typing the letter highlighted in the menu selection. For example, to select the Queue pulldown menu, hold down the Alt key and press Q. To move between fields in the dialog boxes, use the Tab key.

Queue Menu

When you select Queue from the main menu, a pulldown menu offers the following:

Options Menu

When you select Options from the main menu, a pulldown menu offers the following:

Setting Options for the Roll Forward Utility

Set the desired program options for the Roll Forward utility before using the utility to apply the logged changes to the specified Btrieve file or files. These options control the following:

• The size of the data buffer used to retrieve records
• Whether the Roll Forward procedure is an exclusive operation
• The contents and format of the list file (BROLL.LST)

Table 7, describes each option in detail. Subsequent sections describe the two methods you can use to set these options:

• Setting Options from the Options Menu
• Setting Options Manually in the MS Windows Initialization File. (You cannot edit the OS/2 initialization file.)

  
  Table 7. Roll Forward Options

  Program Option	Description
  Data Length	Specifies the number of kilobytes allocated for the data buffer that the utility uses to process the logged entries. This number should be at least as large as the largest record to be rolled forward. The default is 4 KB.
  Exclusive Operation	Runs in one of two ways, depending on your operating system:
  	MS Windows
  	OS/2
  List Files	Specifies the listing options for the list file BROLL.LST. You can select one of the following:
  	Verbose
  	Data to list (bytes)
  	Key to list (bytes)
  	ASCII
  	Hex

Setting Options from the Options Menu

To set Roll Forward options using the Options pulldown menu, complete the following steps:

1. Select Options from the Roll Forward main menu.

2. Select Options from the Options pulldown menu to display the Btrieve Roll Forward dialog box, shown in Figure 23.

   Figure 23
   Roll Forward Utility: Options Dialog Box
   

3. Using the guidelines provided in Table 7, set the options you want to activate for logging your selected files.

4. After setting the options, select one of the following buttons to execute your choice:

   • Save---Accepts and saves the changes you have made to the NOVDB.INI file.
   • OK---Accepts the changes but does not save them to the NOVDB.INI file.
   • CANCEL---Cancels the changes and returns to the previous screen.

Setting Options Manually in the MS Windows Initialization File

You can also change the setting of the Roll Forward utility's options by manually editing the MS Windows initialization file, NOVDB.INI. (You cannot edit the OS/2 initialization file).

These settings are specified under [wbroll] in NOVDB.INI. The following is an example specification for [wbroll]:

[wbroll] datalength=4 exclusive=no outputmode=ASCII listverbose=yes datalist=32 keylist=16

See Table 7, for an explanation of these options.

Placing Items in the Queue

The Roll Forward utility works on a queued-job basis. When you specify the Btrieve files that are to be rolled forward, the utility places them in the queue.

This section discusses the Roll Forward utility's queue and explains how to perform the following tasks:

• Adding Items to the Queue
• Deleting Items from the Queue
• Changing List Options for a Queued Item
• Viewing Items in the Queue

Adding Items to the Queue

The queue can hold a maximum of 32 items. Any of the following represents one item:

• An individual Btrieve file
• A text file listing several Btrieve files
• All files from a specified volume

To add items to the queue, complete the following steps:

1. Select Add from the Queue pulldown menu.

   The Add dialog box, similar to that shown in Figure 24, appears:

   Figure 24
   Roll Forward Utility: Add File Dialog Box
   

2. Select the Btrieve file or files to be rolled forward, as follows:

   • To select all the files from a specified volume, select the Entire Volume check box.
   • To select a particular file, scroll the Directories list box (the list box on the right) to find your directory or drive. Select the directory name and then choose the filename from the Files list box (the list box on the left).

     NOTE:  Setting show dots=on in your NET.CFG file makes the . and .. directory notation visible, allowing you to select the previous directory or root directory from the Directories list box. Refer to your NetWare documentation for details about modifying the NET.CFG file.

   • To select a text file containing a list of files, enter the filename in the Filename text box.
   • To select all available files with a certain extension, enter a wildcard character for the filename, followed by the extension, and press Enter.

3. Specify the list option for the queue item you are adding, as follows:

   • List Only ---If you want only to list the Btrieve operations to be rolled forward without actually performing the procedure, select both the List Only and List File check boxes. Btrieve then lists the operations in the BROLL.LST file in the BLOG directory.
   • Roll Forward Only---If you do not want to list the operations that are rolled forward but you do want to perform the roll forward procedure itself, do not select either the List Only or List File check box; leave them both unchecked.
   • Both List and Roll Forward---If you want to list the operations in BROLL.LST and perform the roll forward procedure, select only the List File check box.

4. If the Btrieve file has an owner name, specify the owner name in the optional [Owner] text box.

5. Select the Add button to add the item to the queue.

   Notice that the Queue button, which has been dimmed until now, becomes available after you select the Add button.

6. Repeat Steps 2 through 5 to add each additional item to the queue.

7. To review the items you have placed in the queue, select the Queue button.

   The items selected appear on a screen similar to that shown in Figure 25.

   Figure 25
   Roll Forward Utility: Items in the Queue List
   

8. When you are finished, click on the OK button.

   NOTE:  At any time, you can click on the CANCEL button to cancel your changes and return to the previous screen.

Deleting Items from the Queue

If you need to delete an item from the queue, complete the following steps:

1. Select View from the Queue pulldown menu.

2. Select the item you want to delete.

3. Click on the Delete button to remove the item from the queue.

4. Click on the OK button.

   NOTE:  If you change your mind and want to cancel your deletion, click on the CANCEL button instead of OK.

Changing List Options for a Queued Item

You can use either of the following methods to change the list options (that is, to change your choices regarding the List Only and List File check boxes) for a given queue item:

• Select Add from the Queue menu and then select the Add button. Next, select the relevant item and choose the list option you prefer.
• Select View from the Queue menu, select the relevant item, and choose the list option you prefer.

Viewing Items in the Queue

You can use either of the following methods to view items in the queue:

• From the Queue pulldown menu, select View to display a dialog box that lists the queued items. (You can select this option only if the queue has one or more items in it.) The View dialog box, shown in Figure 26, appears.
• While you are adding items to the queue, click on the Queue button to list the files in the queue.

Rolling Forward Items in the Queue

Once the queue contains all the items for which you want to roll forward changes, you are ready to start the roll forward procedure. Before you begin, however, back up your data and log files, as explained in Backing Up Data Files.

1. Select Start from the Queue pulldown menu.

   The Queue Menu, with the Start command highlighted, appears.

   Figure 26
   Roll Forward Utility: View Queue Contents Dialog Box
   

   NOTE:  The Roll Forward utility allows a maximum of 250 concurrent transactions per Btrieve file during the roll forward process.

2. After you select Start, the utility lists each Btrieve file being rolled forward and specifies the number of logged entries for each file.

   The Roll Forward utility displays a screen similar to that shown in Figure 27. The number of logged entries is shown to the left of the filename.

   Figure 27
   Roll Forward Utility: Roll Forward List Screen
   

Special Considerations When Using Logging and the Roll Forward Utility

When using NetWare Btrieve's logging feature and the Roll Forward utility, consider the following:

• NetWare Btrieve does not allow a log file to contain log entries created by different versions of NetWare Btrieve. That is, all entries in a log file must be logged under the same version of NetWare Btrieve. Otherwise, NetWare Btrieve displays a system error message on the server console and ignores logging for the specified Btrieve file.
• If you need to restart NetWare Btrieve, specify the same index balancing setting that was used when you first loaded NetWare Btrieve (after a backup) and performed logging. Otherwise, you may receive a Status Code 43 (The specified record is invalid) when you run the Roll Forward utility.
• If you need to run the Roll Forward utility (for example, after a system crash), load the same version of Btrieve and specify the same index balancing setting that was used during logging. Otherwise, you may receive a Status Code 43 (The specified record is invalid).

  NOTE:  If you want to switch to a different version of NetWare Btrieve, or you want to change the index balancing setting, first create a backup of the Btrieve files to be logged and then delete the corresponding log files.

• If you attempt to create a log file for a Btrieve file that contains records larger than 57 KB, you may receive a Status Code 43 (The specified record is invalid) when you run the Roll Forward utility.

Example of Restoring a Data File

This section includes instructions for handling data and log files so you can restore a lost or corrupted logged Btrieve file. It includes the following subsections:

• Making a Backup Copy and Enabling Logging
• Restoring a Logged File from a Backup Copy

Making a Backup Copy and Enabling Logging

The following procedure explains how to handle a Btrieve file called X.BTR to prepare it for logging.

1. Make a copy of the Btrieve file X.BTR called (for example) X.BAK.

   For additional information about this process, see the section Backing Up Data Files.

2. Turn on the logging feature.

   For additional information about this process, see the section Activating the Btrieve Logging Option.

After you have enabled logging and restarted Btrieve, Btrieve writes operations to both the data file (X.BTR) and to the log file, which is called X.LOG.

NOTE:  To keep X.LOG from becoming too large, you may periodically want to make a new backup copy of the logged Btrieve file. Then delete the existing X.LOG file because the new copy of X.BAK already contains all the changes to the X.BTR file that were logged in the existing copy of X.LOG. If logging is enabled, Btrieve will create a new copy of X.LOG when you next work with the X.BTR file.

Restoring a Logged File from a Backup Copy

If you lose a Btrieve file or if, for some reason, a data file becomes corrupted, follow this procedure to restore that file:

1. Copy the backup file, X.BAK, to the Btrieve file (X.BTR).

2. Copy the logging file, X.LOG, to a new file called (for example) X.LLL.

3. Use the Roll Forward utility to apply the operations logged in X.LOG to X.BTR.

   For detailed information about this process, see the section Rolling Forward Items in the Queue.

   If the roll forward operation is successful, proceed to Step 4. If for some reason the first roll forward procedure does not complete successfully, proceed to Step 5.

   NOTE:  One reason the roll forward process might fail is that Btrieve is configured differently during a roll forward operation than it is during the original logged operations.

4. If the roll forward operation completes successfully, follow these steps:

   1. Copy X.BTR to X.BAK to make a new backup copy of the restored Btrieve file.

   2. Delete X.LOG and X.LLL.

5. If the roll forward operation did not complete successfully, follow these steps:

   1. Copy X.BAK to X.BTR.

   2. Copy X.LLL to X.LOG

   3. Perform the roll forward operation again.

   4. Make a new backup copy of the data file and delete the old log file and X.LLL.