Novell is now a part of Micro Focus

Btrieve in the NetWare Server Environment

Articles and Tips: article

MARCUS WILLIAMSON
Managing Director, Connectotel, Ltd.
London, U.K.

01 Feb 1999


Thanks to David Brightman for his assistance in the preparation and review of this AppNote.

If you're wondering what ever happened to Btrieve, wonder no more. This AppNote brings you up to date in the ongoing saga of Btrieve and NetWare.

Introduction

Btrieve is a low-level database record manager which is used within the Novell NetWare environment to provide database functionality for use by server-based and client-based applications. Btrieve started life in 1982 when Doug and Nancy Woodward founded the company Softcraft in Austin, Texas. In 1987 Softcraft was acquired by Novell. In 1994 Novell sold its Btrieve division back to its original owners who, together with Ron Harris, formed Btrieve Technologies Incorporated (BTI). In 1996 BTI became Pervasive Software Incorporated.

Btrieve has a long history of association with Novell. Btrieve was first used in the NetWare server environment as a Value Added Process (VAP) on NetWare 2.15 in 1987. It was later ported to NetWare 3.0, released in 1989, as a NetWare Loadable Module (NLM). From then on Btrieve has continued to be supplied with NetWare, and continues to be used in core areas of the latest NetWare 4.x and NetWare 5 products.

The main advantages of Btrieve in the NetWare server environment are that it provides high performance and has low server resource requirements compared with other relational database solutions which normally require large amounts of memory and disk space on the server. Such alternative solutions would not be suitable for providing low-level record access for the functions we shall describe in this AppNote.

This AppNote covers the following topics:

  • Novell software which uses Btrieve on the server

  • Btrieve configuration and data access

  • Tips for using Btrieve, including common problems encountered when using Btrieve on the server, with solutions

This AppNote was written in the U.K.; therefore it retains the original British spelling used by the author.

Novell Software Which Uses Btrieve on the Server

Let's take a look at some of the Novell software which uses Btrieve in the server environment.

INSTALL.NLM

The INSTALL.NLM program maintains a Btrieve file named SYS:SYSTEM\ PRODUCTS.DAT which contains a list of the products that have been installed on the NetWare server (see Figure 1).

Figure 1: The information stored in the PRODUCTS.DAT file is displayed in the Currently Installed Products screen of INSTALL.NLM.

The contents of the PRODUCTS.DAT file are manipulated by scripts written in the CDWare language. For more information, download the file CDWARE1.EXE from http://support.novell.com/search/ff_index.htm.

ManageWise Inventory Server

The Novell ManageWise Inventory Server (LDINV.NLM) receives incoming inventory data from workstations which run LDISCAN.EXE, WLDISCAN.EXE or LDISCNNT.EXE as part of the login script. The data is stored in the Btrieve files named MACHINES.DAT, TYPES.DAT, FILES.DAT, and VALUES.DAT.

These files are normally located in the SYS:MW\LDT directory on the server. The data stored in this location is retrieved by the Desktop Manager section of the ManageWise Console software.

NetWare Connect

NetWare Connect maintains a log file known as CSAUDIT.LOG, which is located in the SYS:SYSTEM\CSLIB directory. Access to this audit log file is controlled by the CSAUDIT.NLM module.

NetWare for SAA

NetWare for SAA also maintains a log file known as CSAUDIT.LOG, which is located in the SYS:SYSTEM\CSLIB directory. Access to this audit log file is controlled by the CSAUDIT.NLM module.

BorderManager

BorderManager maintains a number of logs, some of which exist in ASCII text format in directories beneath SYS:ETC\PROXY\COMMON and SYS:ETC\ PROXY\EXTENDED. The other, indexed, log file known as CSAUDIT.LOG is located in the SYS:SYSTEM\CSLIB directory. Access to this audit log file is controlled by the CSAUDIT.NLM module in conjunction with the CSATPXY.NLM module.

NetWare/IP

The NetWare/IP Domain SAP/RIP Service (DSS) is a distributed Btrieve database which holds SAP/RIP information for a NetWare/IP domain. It is used by NetWare/IP servers/clients to locate services and routes, and to propagate IPX SAP/RIPs across IP-only links. The files containing this information are:


SYS:ETC\NWIPRIP.BTR

(RIP database)

SYS:ETC\NWIPSAP.BTR

(SAP database)

These files are maintained by the NetWare/IP DSS.NLM.

Domain Name System (DNS)

Prior to the new DNS/DHCP services included with NetWare 5 (which uses NDS), the DNS database information in NetWare 4.11 was stored in these Btrieve database files:


SYS:\ETC\DNS\HOSTS.DB

(Master DNS database)

SYS:\ETC\DNS\HOSTSREV.DB

(PTR record database)

These files are accessed by the Name Server NLM (NAMED.NLM) and their contents are managed through the UNICON.NLM utility.

Btrieve Components

The Btrieve components running on NetWare are the same whether you are running NetWare 4.10, NetWare 4.11, or NetWare 5.0. Each of these versions of NetWare ships with Btrieve 6.10c.

The names and functions of each of the Btrieve components can be seen in the following table.


NLM Name
Function

BTRIEVE.NLM

Btrieve record manager database engine

BSPXCOM.NLM

Btrieve communications engine

BROUTER.NLM

Btrieve Novell Directory Services support in a NetWare 4/ NetWare 5 environment.

BSETUP.NLM

Btrieve setup utility

BTRMON.NLM

Btrieve monitoring utility

ABSTART.NCF

NCF file to start Btrieve

BSTOP.NCF

NCF file to stop Btrieve

You can view the versions of the Btrieve core components currently running on your NetWare 4.11 or NetWare 5 server using the MODULES command, as shown in the sample display below.

C_SERVER2:modules b*

BTRIEVE.NLM

 Btrieve NLM

 Version 6.10f May 3, 1996

BSPXCOM.NLM

 BSPXCOM

 Version 6.10b November 24, 1993

BROUTER.NLM

 BROUTER v6.10e

 Version 6.10e November 3, 1994

Of these, only BTRIEVE.NLM is required for the operation of server-based software which uses Btrieve. BSPXCOM.NLM handles incoming SPX traffic from the Btrieve "requester" software running on client workstations. BROUTER.NLM provides support for Novell Directory Services (NDS) in the NetWare 4.11 and NetWare 5 environments.

You may find that Btrieve version 6.15 has been installed as part of the installation of another piece of software, such as Cheyenne Arcserve. In this case the components could be, for example:


BTRIEVE.NLM

6.15.451 - 13 March 1998

BSPXCOM.NLM

6.15.824 - 29 August 1995

BTRMON.NLM

6.15.451 - 13 March 1998

The exact versions in use will depend on the patch revision of Btrieve which has been installed. Patches for Btrieve 6.15 components may be obtained from the Pervasive Software Web site.

The latest release of the Btrieve database engine is known as "Pervasive.SQL 7". This new release allows the following mechanisms for providing access to Btrieve data:

  • Transactional - traditional low level access to Btrieve files

  • Relational or Structured Query Language (SQL) - high level access using SQL commands

  • Open DataBase Connectivity (ODBC) - access from any database product which supports ODBC

Further information about Pervasive.SQL may be obtained from the Pervasive Software Web site at http://www.pervasive.com/.

Btrieve Configuration

Btrieve is configured using the BSETUP.NLM utility. To use this program, type LOAD BSETUP at the system console (see Figure 2).

Figure 2: The BSETUP.NLM utility initially displays the current Btrieve configuration.

BSETUP reads and writes the file BSTART.NCF which starts the BTRIEVE NLM, BSPXCOM NLM and BROUTER NLM and contains the configuration parameters for these modules as command line switches.

For example, BSTART.NCF might contain these commands:

LOAD BTRIEVE -p=4096 -f=20 -h=60 -l=20 -t=15 -u=0 -s=30 -m=256 LOAD BSPXCOM -d=8192 -s=15 -w=3 LOAD BROUTER

The relationship between the parameters shown in BSETUP and those seen on the commandline of LOAD BTRIEVE in BSTART.NCF is shown in the following table.


Parameter Name
Command Line
Default Line

Number of Files Open

-f

20

Number of Handles

-h

60

Number of Locks

-l

20

Number of Transactions

-t

15

Largest Compressed Record Size

-u

0 (no compression)

Largest Record Size

-d

8192

Largest Page Size

-p

4096

Number of Remote Session

-s

15

Cache Allocation

-m

256

Perform Index Balancing

-c

No

Create Files as Transactional

-i

No

Logging of Selected Files

-a

No

Create Btrieve Files in pre v6.x format

-d

No

Configure BSTART.NCF to Load BRouter

LOAD BROUTER

No

Accessing Btrieve Data

Btrieve files do not contain information about the format of the data contained within the files. It is therefore necessary to use external Dictionary Definition Files (DDFs) if you want to access the data from an application using, for example, Open DataBase Connectivity (ODBC).

However, statistics on Btrieve files may be obtained using the BUTIL NLM utility, which is located in the server SYS:SYSTEM directory. To obtain information about the use of BUTIL type:

LOAD BUTIL

This command will display help information as shown in Figure 3.

Figure 3: The BUTIL.NLM utility provides help information and statistics on Btrieve files.

The purpose of each of these commands is summarised in the table below.


BUTIL COMMAND
Description

- CLONE

Creates a new Btrieve file based on the structure of an existing file

- CLROWNER

Clears the Owner information (password) for a file

- COPY

Copies data from a source Btrieve file to a destination file

- CREATE

Creates a new Btrieve file based on the supplied description file

- DROP

Removes a supplemental index file

- ENDBU

Signals the end of a backup session

- INDEX

Adds an index to a file

- LOAD

Loads new data into a Btrieve file

- RECOVER

Recovers Btrieve data into an output file

- SALVAGE

Attempts to repair a damaged Btrieve file

- SAVE

Saves Btrieve file data into an output file

- SETOWNER

Sets new Owner information (password) for a file

- SINDEX

Creates a new supplemental index for a file

- STARTBU

Signals the start of a backup session

- STAT

Provides status information on an existing Btrieve file

- VER

Displays version information for the loaded Btrieve NLM

To obtain statistics on a particular Btrieve file, use the command:

LOAD BUTIL -STAT filename

For example:

LOAD BUTIL -STAT SYS:SYSTEM\PRODUCTS.DAT

This will display statistics for the file which contains details about products installed on the server. An example is shown in Figure 4.

Figure 4: Here is the BUTIL output you might see when using the -STAT option on the PRODUCTS.DAT file.

BUTIL.NLM may also be used to retrieve Btrieve data as ASCII files. For example, to save the contents of the PRODUCTS.DAT file to a data file, use the following command (typed all on one line):

LOAD BUTIL -SAVE SYS:SYSTEM\PRODUCTS.DAT SYS:SYSTEM\PRODUCTS.TXT

The resulting PRODUCTS.TXT file may be viewed using any text editor, such as EDIT.NLM, or using the FILER utility (see Figure 5). Note that any numeric data stored in binary format will not be visible when viewing the saved text file.

Figure 5: This is an example of the PRODUCTS.TXT file produced by BUTIL -SAVE when viewed in FILER.

The figures shown to the left side of the screen in the PRODUCTS.TXT file have been created by the BUTIL -SAVE command. They indicate the length of each of the lines which follows.

As indicated above, Btrieve data may also be retrieved using ODBC. In order to use an ODBC database, you will need the Dictionary Definition Files (DDFs) for the Btrieve database. These will usually be available from the vendor who supplies the Btrieve-based product. Alternatively, you can use a utility, such as BtSearch (described below) to create the DDF files.

Assuming that you have already installed the ODBC drivers for Btrieve data (available from Pervasive Software) and have the necessary DDF files, you will then be able to access Btrieve data using any ODBC capable database or spreadsheet, such as MS Access or MS Excel.

Determining the Format of Btrieve Files with BtSearch

BtSearch is a Windows utility which allows a user to create DDF files for an existing Btrieve file. In order to use BtSearch you will need knowledge of the format of the Btrieve data. Typically you would create a file filled with known data, then use BtSearch to determine where the data physically exists within the file.

The BtSearch utility is available from:

Nelson Software Solutions 15411 Via La Gitano Poway, CA 92064 USA E-mail: gr_nelson@compuserve.com Web: http://ourworld.compuserve.com/homepages/gr_nelson

Monitoring Btrieve Activity

Btrieve activity on your server can be monitored using the BTRMON.NLM utility. After loading BTRMON.NLM, you will be presented with the following options:

  • Active Resources

  • User Information

  • Resource Usage

  • Communication Statistics

Each of these options is discussed briefly below.

Active Resources

This option allows display of the files which are currently open. Figure 6 is an example screen showing the file SYS:SYSTEM\PRODUCTS.DAT opened by Btrieve when viewing the "Currently installed products" option in INSTALL.NLM.

Figure 6: BTRMON.NLM displays currently open Btrieve files.

User Information

This option allows display of the "users" who are currently accessing Btrieve files (see Figure 7). In the case of server-based programs, the name shown will be the name of the NLM program which is using Btrieve to access files.

Figure 7: The Active Btrieve Users screen shows currently active Btrieve files.

Resource Usage

This option allows the server administrator to determine if the Btrieve configuration parameters should be adjusted to allow, for example, a larger number of Btrieve files to be opened on the server (see Figure 8).

Figure 8: This option allows the display of important Btrieve resource parameters including the current, peak, and configured maximum values.

See the section above on Btrieve Configuration for information about each of these parameters.

Tips for the Use of Btrieve in the Server Environment

This section presents hints on how to use Btrieve in the server environment. It also describes some common errors which may be encountered when using Btrieve.

Starting Btrieve

Btrieve should always be started using the BSTART.NCF command. If Btrieve is autoloaded, as it will do if it is not already loaded in the AUTOEXEC.NCF file or by the administrator, it will only load with "default" configuration parameters, as would be obtained by typing LOAD BTRIEVE NLM at the server.

It is therefore recommended that the BSTART command be placed in your server AUTOEXEC.NCF immediately after the mounting of volumes, so that Btrieve will be loaded under the control of BSTART.NCF and will not autoload with default parameters. This is particularly important if you are using a combination of programs which use Btrieve as their database engine.

File Attributes

You should ensure that the files BSTART.NCF and BSTOP.NCF are flagged read/write. This will allow the BSETUP NLM to write changes to the files.

Also make sure that the files PRODUCTS.DAT and BTRIEVE.TRN (the Btrieve transaction control file) are flagged read/write.

Maximum Files and Handles

The maximum files and handles settings shown in the Btrieve Configuration section above should be configured to the sum of all the maximum number of files and handles for all Btrieve applications being used on your server.

For example, if you are using PRODUCTS.DAT, ManageWise Inventory and Cheyenne Arcserve, you will need to increase the maximum files to the value recommended by Novell for ManageWise Inventory plus the value required by Cheyenne Arcserve. For information regarding the recommended values for ManageWise, see Novell TID #2932850. For information regarding the recommended values for Cheyenne Arcserve, contact Cheyenne technical support. (Cheyenne is now a subsidiary of Computer Associates.)

In all cases, the BTRMON.NLM utility should be used to determine whether any maximum file or handle settings have been reached. If the maximum values have been reached, these maximums should be adjusted and Btrieve should be reloaded using this new configuration.

Common Problems and Solutions

In the event that any changes are required to Btrieve configuration, the following procedure should be adopted:

  • Unload all applications which use Btrieve.

  • Type BSTOP at the server console.

  • Type LOAD BSETUP at the server console and make the necessary configuration parameter changes.

  • Type BSTART at the server console.

Btrieve error 2. This error indicates that a Btrieve file is damaged, that insufficient files or handles are available, or that you are using the wrong version of Btrieve to access the file. If the file is only partially damaged you may be able to use the BUTIL utility -RECOVER option to retrieve the majority of the data which has not been damaged.

Btrieve error 12. This error indicates that the specified file could not be found. In the NetWare server environment make sure you specify the filename including the full path where the file is located. For example:

LOAD BUTIL -STAT SYS:SYSTEM\CSLIB\CSAUDIT.LOG

Btrieve error 20. This indicates that Btrieve is not loaded. To correct the problem, switch to the server system console prompt and type:

BSTART

This will load the BTRIEVE NLM and BSTART NLM modules with the correct configuration parameters.

Btrieve error 87. This error indicates that insufficient handles are available for Btrieve operations. To remedy this problem, use BSETUP to change the maximum file handles parameter as described in the Btrieve Configuration section above.

Btrieve error 91. This error may indicate that you have exceeded the available Btrieve resources configured in BSETUP for this server. To determine whether this is, in fact, the problem, use BTRMON NLM as described above to check the number of files and handles being used. If the maximums have been reached, carry out the following steps:

  • Unload all applications which use Btrieve.

  • Type BSTOP.

  • Type LOAD BSETUPand make the necessary configuration parameter changes.

  • Type BSTART.

Btrieve error 94 This error usually indicates a problem with file rights. To troubleshoot this problem, determine whether the user or program attempting to access the Btrieve data has the required rights for the database files being used. If not, use the NWAdmin utility to give the relevant directory or file trustee rights to the file.

The problem may also be caused by a user being limited to one login. In this case, increase the number of simultaneous logins allow to at least two.

Btrieve error 95. This error indicates that the communication session is no longer valid. An error of this type is usually caused by an SPX session had been established but terminated due to network delays or network communication problems. If the problem is due to delays in receiving a response from the server, it may be advisable to increase the SPX timeout parameters using the server SPXCONFG NLM program.

Summary

This AppNote has described the use of Btrieve in the NetWare server environment, including details of useful tools, tips and common problems and solutions which may be encountered when using Btrieve. Further information can be found from the Novell Support Connection Web site at http://support.novell.com/ and at the Pervasive Software Web site at http://www.pervasive.com/.

Future AppNotes developing on this theme will cover the use of Btrieve and ODBC for extracting ManageWise Console and Inventory data, as well as the extraction of data from the BorderManager Btrieve-based, indexed log files.

* Originally published in Novell AppNotes

Disclaimer

The origin of this information may be internal or external to Novell. While Novell makes all reasonable efforts to verify this information, Novell does not make explicit or implied claims to its validity.

© Copyright Micro Focus or one of its affiliates