CHAPTER 5	USING BTRIEVE UTILITIES (continued)

SINDEX

The SINDEX command creates an additional index for an
existing Btrieve file.  The key number of the new
index is one higher than the previous highest key
number for the Btrieve file.  An exception is if a
DROP command previously removed an index without
renumbering the remaining keys, thus producing an
unused key number; in this case, the new index
receives the first unused number.

Before you can use the SINDEX command, you must create
a description file to define key specifications for
the index.  For more information on description files,
see Appendix A.

Format

  LOAD BUTIL -SINDEX btrvFile descriptionFile
     [/Oowner]

  btrvFile	  The full pathname of the Btrieve file
		  for which you are creating the index.

  descriptionFile The full pathname of the description
		  file containing the description of the
		  index you want to create.

  owner 	  The owner name for the Btrieve file, if
		  required.

Examples

The following example adds an index to the
PATIENTS.DTA file.  The name of the description file
is SUPPIDX.DES.

   LOAD BUTIL -SINDEX
      sys:\nwsql\demodata\patients.dta
      sys:\nwsql\suppidx.des


STARTBU

The STARTBU command places a file or set of files into
continuous operation for backup purposes.

To back up files using continuous operation, first
issue the LOAD BUTIL -STARTBU command, followed by the
Btrieve file or set of Btrieve files.  Next, run your
backup program.  Then, issue the LOAD BUTIL -ENDBU
command to stop continuous operation.  For more
information on the ENDBU command, see "ENDBU." For
more information on continuous operation, see
"Continuous Operation."

SUGGESTION:  When you place a Btrieve file into
continuous operation mode, Btrieve creates a temporary
file with the same name as the data file, but with a
.^^^ extension.  Therefore, do not create multiple
Btrieve files with the same names but different
extensions.  For example, do not use a naming scheme
such as INVOICE.HDR and INVOICE.DET for your Btrieve
files.

Format

  LOAD BUTIL -STARTBU <btrvFile | @filename>

  btrvFile  The full pathname of the Btrieve file on
	    which to begin continuous operation for
	    backup.

  @filename The name of a text file containing the full
	    pathnames of files on which to begin
	    continuous operation.  Separate these
	    pathnames with a space or a carriage
	    return/line feed.

This command begins continuous operation only on the
files you specify.  You cannot use wildcards with the
STARTBU command.

Example

The following example starts continuous operation on
the PATIENTS.DTA file.

   LOAD BUTIL -STARTBU
      sys:\nwsql\demodata\patients.dta


STAT

The STAT command reports the defined characteristics
of a Btrieve file and statistics about the file's
contents.

Format

  LOAD BUTIL -STAT btrvFile [/Oowner]

  btrvFile The full pathname of the Btrieve file for
	   which you want to display statistics.

  owner    The owner name for the Btrieve file, if
	   required.

Example

The following example retrieves the file statistics
for the PATIENTS.DTA file.  The Btrieve file does not
have an owner name.

   LOAD BUTIL -STAT
      sys:\system\515\patients.dta

The following illustration shows the resulting output
screen:

This example shows that the file called PATIENTS.DTA
was defined with a record length of 104 bytes, does
not allow variable-length records, has 3 keys, and has
a page size of 2,048 bytes.  Sixteen records have been
inserted into the file.  The file does not use data
compression and is using all its preallocated pages.

The Btrieve file version is 6.0.  (If you created the
Btrieve file with VATs or multiple alternate collating
sequences, the STAT command displays file version
6.1.  Otherwise, it displays file version 6.0.)

NOTE:  The STAT command designates case-insensitive
keys and key segments with the letter I, descending
keys with the symbol <, manual keys with the letter M,
alternate collating sequence keys with an asterisk
(*), and repeating-duplicatable keys with the letter
R.  Indexes created with SINDEX are also designated
with the letter R by default unless you specified the
Reserved Duplicate Pointer element.

The remainder of the screen provides information about
specific keys.  For example, the screen shows that Key
0 allows duplicates, is modifiable, and consists of
two segments:

o The first segment starts in position 21, is 20
  characters long, allows duplicates, is modifiable,
  and will be sorted as a string type.  The dashes
  indicate that a null value was not defined.  The
  Total column indicates that 16 unique key values were
  inserted for this key.

o The second segment starts in position 7, is 12
  characters long, allows duplicates, is modifiable,
  and will be sorted as a string type.  Sixteen unique
  key values were inserted for this key.

Key 1 consists of one segment.  It starts in position
1, is 6 characters long, does not allow duplicates, is
modifiable, and will be sorted as a string type.
Sixteen unique key values were inserted for this key.

Key 2 consists of one segment.  It starts in position
83, is 10 characters long, allows duplicates, is
modifiable, and will be sorted as a string type.
Seven unique key values were inserted for this key.

NOTE:  The STAT command handles indexes the same
whether they were created by the Btrieve Create
Supplemental Index operation (in Btrieve v6.x) or the
Btrieve Create operation.  The information displayed
by the STAT command does not differentiate between
these indexes.


VER

The VER command returns the version number of the Btrieve NLM
loaded at the server.

Format

  LOAD BUTIL -VER

Remarks

When you run the VER command, the utility displays
messages similar to the following:

   Btrieve Version is 6.1 NLM.
   Operation completed successfully.


Roll Forward Utility

The Roll Forward utility is a workstation utility that
recovers 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.

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

o BROLLFWD.EXE - The Roll Forward utility for the DOS
  operating environment.  You run BROLLFWD from the
  command line.

o PBROLL.EXE - The Roll Forward utility for the OS/2
  environment.  You run PBROLL interactively.

o WBROLL.EXE - The Roll Forward utility for the Windows
  environment.  You run WBROLL interactively.

NOTE:  The procedure for running PBROLL and WBROLL is
the same.


Setting Up Files for Logging

To take advantage of BtrieveÕs logging feature and the
Roll Forward utility, you must first set up your
Btrieve files for logging, as follows:

1.  Activate BtrieveÕs logging configuration option
(using the Setup utility, BSETUP.NLM).

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

3.  Back up your data files before the logging
begins.  The following sections explain each step.


Activating the Btrieve Logging Option

You can activate 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
Btrieve, complete the following steps to activate
Btrieve logging:

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 the Escape key.

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.


Creating the Log Configuration File

BLOG.CFG is the log configuration file.  It specifies
all 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 that contains 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 the BLOG.CFG file.

2.  Open the BLOG.CFG file.

3.  For each Btrieve file for which you want to log
operations, create an entry using the following format:

  \directory1\btrvFile[=\directory2\logFile]

  directory1 The path to the Btrieve file to be logged.
	     Do not include server names, volume names,
	     or DOS drive letters.

  btrvFile   The name of the Btrieve file to be logged.

  directory2 The path to the log file.	If the log file
	     and the Btrieve file are on the same volume,
	     you can omit the server and volume names.
	     If they are on different volumes, you must
	     include the server and volume names.

	     NOTE:  When including the server name, place
	     a double backslash (\\) before it.

  logFile    The name of the log file.	Although the log
	     file and the Btrieve file can be on
	     different volumes, they cannot be on
	     different servers.

Make sure each entry fits completely on one line.  You
can place multiple entries on the same line, but they
must be separated by at least one space.  Each line
can contain a maximum of 256 characters.

If you do not provide a log name, Btrieve (at the time
the file is first opened) assigns the original
filename to the log file and gives it a .LOG
extension.  For example, if you did not specify a log
name for the Btrieve file TEST01.DAT in the directory
TEST, Btrieve would assign the full name
\TEST\TEST01.LOG to the associated log file.  In this
case, the default log file shares the same directory
as the Btrieve file.

The next three examples show sample entries in the file
\BLOG\BLOG.CFG on the SYS:  volume of the CORP
server.  Each of these entries 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.

   \data\b.btr
   \data\b.btr=\data\b.log
   \data\b.btr=\\corp\sys:\data\b.log

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.

   \data\b.btr=\\corp\vol1:\data\b.log


Backing Up Data Files

Be sure to make a backup copy of your Btrieve data
files before logging begins.  When logging is
activated for a given file, Btrieve records (in the
corresponding log file) all the operations that change
that file.  Btrieve continues appending subsequent
operations to the end of this log file until the log
file is deleted.  Consequently, it is important to
perform periodic maintenance to reduce the size of the
log files.

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


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:

   btrvFile  Specifies the name of a single Btrieve file
	     to be recovered.

   @listFile Specifies the name of a text file that
	     contains a list of Btrieve filenames
	     separated by one or more spaces.  Use a list
	     file to recover multiple files.

   /A	     Specifies that you want to recover all the
	     Btrieve files in the BLOG.GFG file.

   /D:	     Specifies the data buffer size (in kilobytes)
	     that the Roll Forward utility allocates for
	     Btrieve log operations.  /D:  is optional.
	     The default size is 8 KB, the minimum is 1
	     KB, and the maximum is 64 KB.
	     You can specify the length in increments of 1
	     KB.

   /T:	     Specifies the length of the data (in bytes)
	     that will be printed in the list file for
	     each operation that is rolled forward.  /T:
	     is optional.  Valid data lengths range from 1
	     through the value of the data
	     buffer size specified with the /D:  option.
	     The default value is 40 bytes.

   /K:	     Specifies the length of the key (in bytes)
	     that will be printed in the list file for
	     each operation that is rolled forward.  /K:
	     is optional.  Valid lengths for printing keys
	     range from 1 through 255 bytes.  The default
	     value is 10 bytes.

   /H	     Specifies that the Btrieve operations in the
	     list file will be printed in hexadecimal
	     format.  The default prints the data and key
	     in decimal numbers. /H is optional.

   /V	     Specifies that for each logged file in the
	     list file, the utility will add the time
	     stamps of the Roll Forward operation and log
	     file creation.  For each logged operation, it
	     adds the name of the user who performed the
	     operation, the internetwork address of the
	     source workstation, the time stamp indicating
	     when the operation was performed, and the
	     record length and key number used in the
	     operation.  /V is optional.

   /L	     Specifies that you want only to list the
	     logged operations.  The logged operations
	     will not be executed.  The operations will be
	     listed to the standard output device.  /L is
	     optional.

   /O:	     Specifies an owner name.  If the backup copy
	     of the Btrieve file you want to recover has a
	     Btrieve owner name, you must provide this
	     option.  This protects the owned files from
	     being changed inadvertently.  Typically,
	     all owned files in an application have the
	     same owner name.  Therefore,
	     the utility assumes that all Btrieve files
	     listed in the file list have the same owner
	     name.

	     However, some Btrieve files in a file list
	     may have different owners.  If a Btrieve
	     file has an owner name, that
	     file has only one owner name.  In that case,
	     the utility prompts you to enter the owner
	     name.  Similarly, if you do not specify /O
	     and the utility encounters a Btrieve file
	     that requires an owner name,
	     BROLLFWD prompts you for that owner name.

   ownerName Specifies the owner name of the Btrieve
	     files to be accessed.  When you use /O, you
	     must specify an owner name.


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

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

   From This Position	       Do This

   OS/2 command line	       Type PBROLL
   Presentation Manager        Double click on the Roll Forward icon
   Windows		       Double click on the Roll Forward icon,
			       or choose Run... from the
			       File pulldown menu and type
			       WBROLL

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

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

1.  Set the Roll Forward utilityÕs program options.

2.  Place in the utilityÕs queue all the items you
intend to roll forward.

3.  Start rolling forward the items in the queue.
Following a brief description of the Roll Forward
utility's pulldown menus, subsequent sections describe
each of these steps in detail.


Using the Roll Forward Pulldown Menus

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

SUGGESTION:  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:

   Add...
   Generates a dialog box in which you can specify items
   to be placed in the queue.

   View...
   Generates a dialog box in which you can view the
   queued items.  If no items are in the queue, this
   selection is disabled.

   Start
   Begins the process of rolling forward all items
   in the queue.  Like the View...  selection, this
   selection is disabled if no items are in the queue.

   Exit
   Exits the utility.  In the Windows and OS/2
   environments, you can also press F3 to exit.

Options Menu

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

   Options...
   Generates a dialog box that lets you set the data
   buffer length and the list options.

   About...
   Displays the version of the Roll Forward utility that
   you are running.


Setting Options for the Roll Forward Utility

You should set program options for the Roll Forward
utility before using the utility to roll forward
changes.  These options control the following:

o Size of the data buffer used to retrieve records
o Multitasking operation
o Contents of the list file (BROLL.LST)

Table 5-5 describes each of these options in detail.
Subsequent sections describe the two methods you can
use to set the program options:

o By using the Options pulldown menu.
o By editing the initialization file.  (The NOVDB.INI
  file for OS/2 cannot be edited.)

Table 5-5
Roll Forward
Program 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:

            Windows    Windows v3.x emulates multitasking and
                       lets you run more than one
                       application concurrently. If
                       you select Exclusive Operation,
                       the Roll Forward utility uses
                       the CPU time exclusively. If you
                       do not select this option, the
                       utility shares CPU time with
                       other applications.

                       If you plan to run recorder-type
                       programs or batch execution
                       programs with Roll Forward,
                       check this box to ensure correct
                       operation. Selecting Exclusive
                       operation also enhances
                       performance slightly.

               OS/2    OS/2 provides true multitasking;
                       the Roll Forward utility can
                       always run concurrently with
                       other applications.
                       You can, however, vary the
                       priority of the Roll Forward
                       thread to accommodate other
                       threads that are running. The
                       following priorities are
                       available:

                       Idle - Runs only when no other
                         tasks are waiting for the CPU
                       Low - Lower priority than normal
                       Normal - The default thread
                         priority
                       High - Higher priority than
                         normal

List Files             Specifies the listing options
                       for the list file BROLL.LST.
                       You can select one of the
                       following:

            Verbose    For each logged file, this
                       option adds the time stamps of
                       the Roll Forward operation and
                       log file creation to the list
                       file. For each logged operation,
                       it adds the name of the user who
                       performed the operation, the
                       internetwork address of the
                       source workstation, the time
                       stamp indicating when the
                       operation was performed, and the
                       user-defined lengths of data and
                       key numbers used in the
                       operation.

       Data to list    Specifies the length of the data
                       buffer that will be printed in
                       the list file for each operation
                       that is rolled forward.

        Key to list    Specifies the length of the key
                       buffer that will be printed in
                       the list file for each operation
                       that is rolled forward.

              ASCII    Lists the Btrieve operation
                       values in ASCII mode.

                Hex    Lists the Btrieve operation values in
                       hexadecimal mode.


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 following dialog box:

3.  Set the options using the guidelines provided in
Table 5-5.

4.  After setting the options, select one of the
following:

o Save - accepts and saves the changes you have made
  to the .INI file.

o OK - accepts the changes but does not save them to
  the .INI file.

o CANCEL - cancels the changes and returns to the
  previous screen.


Setting Options in the Initialization File

You can also change the setting of the Roll Forward
utilityÕs program options by editing the
initialization file NOVDB.INI (for Windows).  These
settings are specified under [wbroll] in NOVDB.INI.
An example specification for [wbroll] follows:

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


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 do the following:

o Add items to the queue
o Delete items from the queue
o Change list options for a queued item
o View 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:

o An individual Btrieve file
o A text file listing several Btrieve files
o 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 the following) appears:

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

o To select the entire volume, click on the Entire
  Volume check box.

o To select a particular file, scroll the Directories
  list box (the list box on the right) to find your
  directory or drive.  Double click on the directory
  name and then choose the filename from the Files list
  box (the list box on the left).

o To enter 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,
  you can enter a wildcard character for the filename,
  followed by the extension.  Then, press Enter.

NOTE:  To select the parent directory from the
Directories list box, set "show dots=on" in your
NET.CFG file.  Refer to your NetWare documentation for
more information on NET.CFG.

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

o If you want only to list the Btrieve operations to be
  rolled forward (without actually rolling the logged
  operations forward), click on the List Only and List
  File check boxes.  The operations will be listed in
  the file BROLL.LST in the BLOG directory.

o If you want to list the operations in BROLL.LST and
  roll forward the operations, click on the List File
  check box.

o If you do not want to list the operations that are
  rolled forward but you do want to roll the operations
  forward, do not click on either the List Only or List
  File checkbox.

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

5.  Click on the Add button to add the item to the
queue.

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,
click on the Queue...  button.  The items selected
appear on a screen similar to the following:

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, your choices regarding the
List Only and List File check boxes) for a given queue
item:

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

o 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:

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

o 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 process.
Select Start from the Queue pulldown menu.

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

After you select Start, the utility lists each Btrieve
file being rolled forward and specifies the number of
logged entries for each file.  (The number of logged
entries is shown to the left of the filename.)