CHAPTER 3       INSTALLING AND CONFIGURING BTRIEVE (continued)

Unloading the Earlier Version of Btrieve

To unload an earlier version of Btrieve from a
server's memory, enter the following command at the
server console or at a workstation running RCONSOLE:

   BSTOP

The BSTOP command runs a NetWare command file
(BSTOP.NCF) that unloads the following modules in the
order shown:

1. BROUTER.NLM
2. BSPXCOM.NLM
3. BTRIEVE.NLM

NOTE: BSTOP.NCF does not unload BSPXSTUB or RSPXSTUB.  To
unload these modules, type UNLOAD followed by the
module name.


Starting Btrieve v6.x

After installing Btrieve v6.x (as discussed in "Using
the NetWare INSTALL Utility"), you can
start it by entering the following at the server
console or at a workstation running RCONSOLE:

   BSTART


Stopping Btrieve v6.x

To stop Btrieve v6.x, enter the following command at
the server console or at a workstation running
RCONSOLE:

   BSTOP

The BSTOP command runs a NetWare command file
(BSTOP.NCF) that unloads the following modules in the
order shown:

1. BROUTER.NLM
2. BSPXCOM.NLM
3. BTRIEVE.NLM

NOTE: BSTOP.NCF does not unload BSPXSTUB or RSPXSTUB.  To
unload these modules, type UNLOAD followed by the
module name.


Rebuilding Existing Btrieve Files

If your database contains files created with versions
of Btrieve prior to v6.x, you may want to upgrade
these files to take advantage of the Btrieve v6.x
features.  Btrieve v6.x works with v5.x files; however,
it does not implement the v6.x features.

The Btrieve Rebuild utility (BREBUILD.NLM) converts
Btrieve data files to the v6.x format.  You can run
this utility from either the server console or a
workstation running RCONSOLE.  Use either of the
following methods to run the Rebuild utility:

o Interactively through the Setup utility - When you
  run the Rebuild utility interactively, it checks the
  values you enter to ensure they are within the proper
  ranges.

o From the command line - When you use this method, the
  utility checks your entries and displays messages if
  the values you entered are not within the proper
  ranges.  With this method, you can specify a command
  file.  The following sections discuss running the
  utility interactively and from the command line.

IMPORTANT: Before running this utility, make sure you have
unloaded your previous version of Btrieve, started
Btrieve v6.x, and backed up all your data files.
Having a backup copy ensures against data loss if a
power interruption occurs while you are running this
utility.

To ensure that your backup is successful, perform one
of the following:

o Close all Btrieve files before running the backup
  utility.

o Use continuous operations.

o Use a backup utility that opens the Btrieve files in
  exclusive write mode so that other processes cannot
  write to the files.  Ensure that the backup utility
  has exclusive rights to the files.


Running the Rebuild Utility Interactively

You can run the Rebuild utility interactively through
the Set Rebuild Configuration option on the Setup
utilityÕs Available Options menu.  As the following
sections explain, you can use the Set Rebuild
Configuration option to do the following:

o Configure the Rebuild utility
o Execute the Rebuild utility
o Check the utilityÕs error log


Configuring the Rebuild Utility

Complete the following steps to set the configuration
options that apply to rebuilding your Btrieve files:

1.  After starting Btrieve v6.x, load the Setup
utility by entering LOAD BSETUP at the prompt.

2.  When the Available Options menu appears, select
Set Rebuild Configuration to run the Rebuild utility.
A warning appears, indicating you should back up your
Btrieve data files before proceeding.

NOTE:  If you do not have current backups, you should
press Esc three times.  When the Exit Btrieve Setup?
prompt appears, select Yes.  Create backups and then
return to this utility.

3.  Provided you have current backups of your data
files, press Esc to continue to the Rebuild Options
menu.

4.  Select Set Rebuild Configuration to display the
Rebuild Configuration Setup Form screen.

5.  Select the files you want to rebuild, as
follows:

a.  With your cursor at Files To Be Converted,
press Enter and then Insert.

b.  When the list of available volumes appears,
highlight the volume you want and press Enter.  The
utility displays the directories available on the
selected volume.

c.  Highlight the directory you want and press Enter.

d.  Continue highlighting directories (that is,
subdirectories) and pressing Enter until you have
reached the one that contains the file or files you
want to rebuild.  Then, press Esc.

e.  Choose the files you want to rebuild, as follows:

To specify more than one file, enter the filenames
manually, using wildcard characters (* or ?).  For
example, you might enter /*.* to specify all files in
the selected directory, or you could enter /*.BTR to
specify all files in that directory with the extension
.BTR.

To specify an individual file, press Enter to list the
filenames in the specified directory.  Highlight the
filename you want, and press Enter to select it.  (The
input files that are listed are on the local server.)

6.  At Output Directory, specify the location you want
to use for the rebuilt files, as follows.  (The
default location is the directory you specified for
the Files To Be Converted field.)

a.  Press Enter.

b.  Either type the server or directory name manually
and press Enter, or choose from the list of available
directories on the current server by entering a valid
path and pressing Insert.  To select a directory name
from the list, highlight the name and press Enter.

If you want to place the rebuilt files on a different
server, you must type the output server name, volume,
and path manually.  Then, press Enter.

NOTE:  To place rebuilt files on a different server,
Btrieve and the Message Router must be loaded on the
server where the original data files reside, and the
Btrieve and BSPXCOM NLMs must be loaded on the server
that will contain the rebuilt files.  Wherever you
locate the rebuilt files, you will need enough disk
space for the rebuilt files and the temporary files
that the utility creates.  The utility deletes the
temporary files at the end of the conversion process.

Do not use wildcard characters in the pathname that
specifies the location for the rebuilt files.

c.  After specifying the output directory, use the
Down- Arrow key to move to the Page Size field.

7.  At Page Size, type the size manually or choose
from a list of sizes.

To list the available page sizes, press Enter.  In
this list, the AUTO option (the default) means the
utility will choose the optimum page size for the
files.  The EXISTING option means the utility will use
the same page size as that of the original files.  To
select a size from the list, highlight it and press
Enter.

NOTE:  When you use the EXISTING option, the utility
changes the page size if the original size will not
work.  For example, assume you have a Btrieve v5.x
file with a page size of 1,024 and 24 keys.  Since
Btrieve v6.x supports only 23 keys for a file of that
page size, the utility selects a new page size for the
file and displays an informative message on the screen.

8.  At Key Number, specify a number between 0 and 23
on which to sort the records, or specify -1 to sort
the records in physical order; then, press Enter.

IMPORTANT:  If you are using NetWare SQL, you must
specify a key number of 0 when rebuilding the VIEW.DDF
file.

9.  At Preserve TTS Setting, specify Y (for Yes) or N
(for No) to indicate whether you want to preserve the
Transaction Tracking System (TTS) bit during
conversion; then, press Enter.  If you specify Y, the
utility preserves the bit.  If you specify N (the
default), the utility clears the bit when creating
Btrieve v6.x files.

10.  At Conversion Method, select the conversion
method as follows:

a.  Press Enter.

b.  Highlight either PRIMARY (the default) or
SECONDARY, and then press Enter.

The PRIMARY method clones the files, drops the indexes,
copies the records into the new files, and rebuilds the
indexes.  Since this method is faster and creates
smaller files, you should use this method whenever
possible.  However, if you are using NetWare SQL, you
must not use this method when rebuilding the VIEW.DDF
file.

The SECONDARY method clones and copies the files
without dropping and replacing indexes.  This method
may be slower than the Primary method.

IMPORTANT:  If you are using NetWare SQL, you must
specify the SECONDARY method when rebuilding the
VIEW.DDF file.  The SECONDARY method may create a v6.x
file in which the records are in a different physical
order than in the original v5.x file.

11.  At Continue On Error, specify either Y (for Yes)
or N (for No) and press Enter.

If you specify Y, the utility continues if it
encounters an error.  (The utility notifies you of
non-Btrieve files or other errors but continues
rebuilding Btrieve files.) If you specify N, the
utility stops if it encounters an error and aborts the
rebuild process.

12.  At Convert Supplemental Indexes, specify Y (for
Yes) or N (for No) and press Enter.

If you specify Y, the utility converts Btrieve v5.x
supplemental indexes (which allow duplicates) to
Btrieve v6.x indexes with linked duplicates.  Btrieve
v5.x supplemental indexes have, by default, repeating
duplicates.  If you specify N (the default), the
utility does not convert the v5.x supplemental indexes
but preserves them as repeating duplicates.

IMPORTANT:  Do not use the Convert
Supplemental Indexes option if you access your data
files through NetWare SQL.

13.  Press Esc to leave the Rebuild Configuration
Setup Form screen.

14.  When the utility asks whether to save your
changes, select Yes to save them and return to the
Rebuild Options menu or No to abandon the changes.

IMPORTANT:  The utility applies the Btrieve v5.x
file's owner name and level to the Btrieve v6.x file.


Executing the Rebuild Utility

After configuring the Rebuild utility, you are ready
to rebuild your files.  At the Rebuild Options menu,
select Execute Rebuild to run the utility.

The utility executes and also creates a log file.  It then
notifies you that the process has completed.  To
return to the Rebuild Options menu, press Esc.  You
can then check the log file as discussed in the
following section.


Checking the Rebuild Log File

After rebuilding your files, be sure to check the
utility's log file to see if any errors occurred
during the conversion, as follows:

1.  Select View Rebuild Log File from the Rebuild
Options menu.  The utility displays a log of any
errors that occurred while the utility was executing,
similar to the following example:

2.  When you finish viewing the log, press Esc to
return to the Rebuild Options menu.  To exit both the
Rebuild utility and the Setup utility, press Esc twice
more and specify Yes at the Exit Btrieve Setup?
prompt.


Running the Rebuild Utility from the Command Line

Before running the Rebuild utility from the command
line, make sure you have unloaded your previous
version of Btrieve, started Btrieve v6.x, and backed
up all your data files.  Having a backup copy ensures
against data loss if a power interruption occurs while
you are running this utility.

NOTE: After rebuilding your files, be sure to check the
utility's log file to see if any errors occurred
during the conversion.  The log file (BREBUILD.LOG)
that the Rebuild utility creates is an ASCII text
file.  The .LOG file is placed in the SYS:SYSTEM
directory.  You can view it by using a text editor or
by running the Rebuild utility interactively and
selecting View Rebuild Log File from the Rebuild
Options menu (as explained in "Checking the Rebuild
Log File").  To run the Rebuild utility
from the command line, enter the following command at
the prompt:


   LOAD BREBUILD [-option ...] file
   or
   LOAD BREBUILD @commandFile

option
Specifies the configuration options for the utility.
Precede each option letter with a dash (-).  Do not
place a space between the dash and the option letter
and between the option letter and its value.  You can
enter the option letter in uppercase or lowercase.

-B[path]
Specifies an alternate location for the rebuilt
files.  (The default location is the current
directory.) This option lets you rebuild large files
on a different volume or on a different server.  To
locate the files on a different server, the Btrieve
NLM and the Message Router must be loaded on the server
where the original data files reside, and the Btrieve
and BSPXCOM NLMs must be loaded on the server that will
contain the rebuilt files.

IMPORTANT:  Do not use wildcard characters in the
pathname you specify with the ÐB option.

- C
Instructs the utility to continue with the next file
even if an error occurs.  The utility notifies you of
non-Btrieve files or other errors but continues
updating Btrieve files.  This option is useful if you
have specified wildcard characters for the rebuilt
files.

-D
Converts Btrieve v5.x supplemental indexes (which
allow duplicates) to v6.x indexes with linked
duplicates.  (By default, the utility preserves the
indexes as repeating duplicates.) If you access your
data files only through Btrieve and your files have a
relatively large number of duplicate keys, you can use
this option to enhance the performance of the Get Next
and Get Previous operations.

IMPORTANT:  Do not use the -D option if you access
your data files through NetWare SQL.

-M0 | M2
Specifies the converison method, as follows:

M0 Clones and copies the files without dropping and
   replacing indexes. While this method is slower
   than M2, it is available in casy you do not want
   to rebuild your indexes.

IMPORTANT: If you are using NetWare SQL, you must use
the -M0 and -K0 options to rebuild the VIEW.DDF file.

M2 (Default) Clones the files, drops the indexes, copies
   the records into the new files, and rebuilds the
   indexes.  Since this method is faster and creates
   smaller files, you should use it whenever possible.

IMPORTANT: The M2 method may create a v6.x file in which the
records are in a different physical order than in the
original v5.x file.

-P[nnn]
Specifies the page size (in bytes) of the new files.
If you specify -P with no page size, the utility
chooses the optimum page size for your file.

NOTE:  If you do not specify the -P parameter,
the utility will change the page size if the
original size will not work.

For example, assume you have a Btrieve 5.x file
with a page size of 1,024 and 24 keys.  Since Btrieve
v6.x supports only 23 keys for a page size of 1,024,
the utility automatically selects a new page size for
the file and displays an informative message on the
screen.

-K[nn]
Specifies the key by which the utility reads when
rebuilding a file.  If you do not specify this option,
the utility reads the file in physical order.  You
must use the -K0 option when rebuilding NetWare SQL's
VIEW.DDF file.

-T
Does not preserve the Transaction Tracking System
(TTS) bit during conversion.  If you specify this
option, the utility clears the TTS bit (if set) when
converting a Btrieve v5.x file to a Btrieve v6.x
file.  If you do not specify this option, the utility
sets the TTS bit when creating the Btrieve v6.x file if
the v5.x file had the TTS bit set.  file

Specifies the set of files to convert. Use full directory
names, including the volume name.  You may use
wildcards (* and ?) in these filenames.  The Rebuild
utility applies the Btrieve v5.x file's owner name and
level to the Btrieve v6.x file.

@commandFile
Specifies a command file for the utility to execute.
You can include multiple entries in one command file.
Each entry in the command file contains the utility
options (if any) and the set of files to convert,
followed by <end> or [end].  When specifying the files
to convert, be sure to use full directory names,
including the volume name.  You may use wildcards (*
and ?) in these filenames.  The following is an
example of a Rebuild utility command file:

   -C sys:\mydir\*.* <end>
   -C -P1024 dta:\dir\*.* <end>
   -M0 -K0 sys:\nwsql\*.* <end>

Examples
The first example places the rebuilt files on another
server:

   LOAD BREBUILD -Bserv-temp\sys:\newfiles -C -P4096
      sys:\oldfiles\*.btr

The next example places the rebuilt files on the same
server, but on a different volume:

   LOAD BREBUILD -Bvol2:\btrfiles -C -P4096 -M2
      sys:\btrfiles\*.btr


Deleting Temporary Files

By default, the Rebuild utility creates temporary
files in the same directory in which the conversion
takes place.  (You can specify a different directory
by using the -B option when running the Rebuild
utility from the command line, or by using the Output
Directory option on the Setup Form screen when running
the utility interactively.)

You need enough disk space to accommodate the original
file and the new file while the Rebuild utility is
running.

NOTE:  The Rebuild utility deletes the original
file after rebuilding it, even if the new file is in a
different directory.

Normally, the Rebuild utility automatically deletes
temporary files when the conversion is complete.
However, if a power failure or other serious
interruption occurs, the Rebuild utility may not
delete the temporary files.  If this occurs, look for
filenames such as _T-xxxxx.TMP and delete them.


Using Btrieve with NetWare Runtime

The NetWare Runtime serialized NetWare operating system
differs from the other versions of NetWare in that it
grants file service access to only one NetWare login
client connection.  This login is for system
administration purposes.  NetWare Runtime does not
limit the number of SPX or AppleTalk connections
between client applications and NLM-based services.
Consequently, NetWare Runtime does not limit the
number of users that can access Btrieve running on the
Runtime server.

Figure 3-1 illustrates the relationship between
NetWare Runtime and a NetWare configuration that is
not dedicated to database services.

Figure 3-1
NetWare
Configurations

      +----------------+    +----------+	     +----------+
      | File and Print |    | Database |	     | Database |
      |    Services    |    | Services |	     | Services |
      +----------------+    +----------+	     +----------+
   +--------------------------------------+	 +-----------------+
   |		    NetWare		  |	 | NetWare Runtime |
   +--------------------------------------+	 +-----------------+
	  Nondedicated Configuration	       Dedicated Configuration



Reasons to Use NetWare Runtime

Running NetWare Btrieve on a server dedicated to
database management ensures that all the server's
processing power is directed toward database
applications.  If you anticipate heavy file service
activity, a dedicated database server makes that
activity more efficient because it frees the
nondedicated server to devote all its resources to
file services.

Having a dedicated database server is also
particularly effective in preventing slow performance
on the network during periods of heavy file service
activity.  To optimize network performance, you can
configure so as to include a dedicated database server
in addition to other servers offering full NetWare 4.0
services.  Figure 3-2 shows an example installation
for NetWare Runtime.

Figure 3-2
NetWare Runtime
Installation

   Dedicated database +------+	     +------+	Standard NetWare
   server running     |      |...... |	    |	providing file and
   NetWare Runtime    +------+	     +------+	print services
	      . 				      .
	     .	      Database			       .
	    .						.
	   .						 .
    Local Area Network					 .
	    .						 .
	     .						.
	      . 				       .
	       +-------+		       +-------+
	       |       |		       |       |
	       +-------+		       +-------+
	      Workstation		      Workstation
		   .				   .
		    .		+------+	  .
		      . 	|      |	 .
		       .	+------+	.
			 ..... Workstation .....



Installing NetWare Runtime

The installation procedure for NetWare Runtime is
identical to installing the other versions of
NetWare.  Refer to the documentation that accompanies
your NetWare Runtime software for instructions.


Special Notes on NetWare Runtime

NetWare Runtime supplies a facility (NLICLEAR.NLM)
that clears unused connections.  NetWare Runtime
provides only one available client connection.  Even
after the administrator logs out of the application
server, a connection is maintained between the
workstation and the server.  If a second administrator
wants to log on to the application server from a
second workstation, the single connection will be
unavailable.

The NLICLEAR facility is important for NetWare Runtime
because, at intervals, NLICLEAR automatically clears
the unused connections left after an administrator
logs out of the application server, allowing another
administrator to log in to and administer the database
server.


Special Notes on Btrieve

When you load the Btrieve DOS or OS/2 Requester using
the option /C:1, username, password, Btrieve logs in
to the NetWare Runtime server with the specified
username and the corresponding password.  Btrieve also
obtains a temporary connection number, which it uses
to distinguish between users.

Btrieve verifies that the user has the acceptable
rights to open or create a file.  Btrieve then logs
out of the server, using the temporary connection
number.  If the user has the appropriate file access
rights, Btrieve continues; otherwise, it returns an
error.  The administrator must set up file access
rights on the NetWare Runtime server.

When you load the Btrieve DOS or OS/2 Requester using
the /C:1 default option (without specifying a username
and password) and then attempt to read a file on the
NetWare Runtime server, the Requester must determine
what login username Btrieve can use to maintain
NetWare security.  Btrieve then uses that username to
log in temporarily for the client.  In contrast, if
the Requester detects that there is no connection, or
if it cannot find a valid login username, the
Requester returns an error.  For more information
about the NetWare Runtime server support option
available with the DOS and OS/2 Requesters, see
Chapter 4, "Configuring and Using the Requesters."