Filename:   README.BTR
Product:    NetWare Btrieve v6.1 for NetWare v3.12
Date:       June 1993

   This Readme document pertains to NetWare Btrieve v6.1 for 
   NetWare v3.12. It provides installation and upgrade 
   information and descriptions of the NetWare Btrieve v6.1 
   program files for NetWare v3.12. 


================================================================
Disclaimer
==========

   Novell, Inc. makes no representations or warranties with 
   respect to any NetWare software, and specifically disclaims 
   any express or implied warranties of merchantability, 
   title, or fitness for a particular purpose.

   Distribution of any NetWare software is forbidden without 
   the express written consent of Novell, Inc.  Further, 
   Novell reserves the right to discontinue distribution of 
   any NetWare software. 

   Novell is not responsible for lost profits or revenue, loss 
   of use of the software, loss of data, costs of re-creating 
   lost data, the cost of any substitute equipment or program, 
   or claims by any party other than you.  Novell strongly 
   recommends a backup be made before any software is 
   installed.  Technical Support for this software may be 
   provided at the discretion of Novell. 


================================================================
Contents
========

   Btrieve v6.x Upgrade Information
      Btrieve v6.x File Format
      Btrieve v6.x Operations
      Btrieve v6.x Utilities
      Btrieve v6.x Requesters
      Btrieve v6.x Status Codes
   Btrieve v6.x Program Files
   Associated Documents


================================================================
Btrieve v6.x Upgrade Information
================================

   For a description of the enhancements to NetWare Btrieve v6.1,
   refer to Chapter 1 of the "Btrieve Installation and Operation"
   manual.

   Before you start NetWare Btrieve v6.1, read the following 
   sections in this document.

   - Btrieve v6.x File Format -- Addresses some of the 
     differences between the Btrieve v6.1, v6.0, and v5.x file 
     formats. 

   - Btrieve v6.x Operations -- Highlights the new Btrieve v6.1
     chunk operations and the restrictions that apply when using
     Btrieve v6.0 to operate on records larger than 64 KB.

   - Btrieve v6.x Utilities -- Provides important notes on
     Btrieve's logging feature.

   - Btrieve v6.x Requesters -- Highlights the new Btrieve v6.1
     configuration options for the DOS and OS/2 Requesters.

   - Btrieve v6.x Status Codes -- Discusses error conditions 
     specific to different versions of Btrieve.


Btrieve v6.x File Format
------------------------

   When creating files, Btrieve v6.x uses a new file format 
   that allows faster data access than possible with versions 
   of Btrieve prior to v6.0.  This new file format, first 
   introduced in Btrieve v6.0, has been slightly modified in 
   Btrieve v6.1.  For more information on the Btrieve v6.x 
   file format, refer to the "Btrieve Programmer's Manual" 
   included in the NetWare Btrieve v6.1 Developer's Kit 
   Supplement, which is available through the Professional 
   Developer's Program (PDP). 

   When working with Btrieve files created with different 
   versions of Btrieve, consider the following.

   - New file features supported by Btrieve v6.1 include:  
     multiple alternate collating sequences (ACSs), 
     locale-specific ACSs, Variable-tail Allocation Tables 
     (VATs), and the ability to mark a file as using index 
     balancing. 

     Btrieve v6.1 returns a file version of 6.1 if the file 
     specified in a Btrieve Stat operation or BUTIL -STAT 
     command was created with multiple ACSs, locale-specific 
     ACSs, VATs, or the index balancing option.

     NOTE:  Files created with any of these features are 
     created in the Btrieve v6.1 file format.  If Btrieve v6.1 
     creates a file without any of these features, it creates 
     the file in the Btrieve v6.0 file format by default.  You 
     can override the v6.0 default and create Btrieve v5.x 
     files by using the Setup Utility.  Refer to Chapter 3, 
     "Installing and Configuring Btrieve" in the "Btrieve 
     Installation and Operation" manual for more information 
     on the Setup utility. 

   - Btrieve v6.0 operates on a file created by Btrieve v6.1, 
     unless the file uses multiple ACSs, locale-specific ACSs, 
     VATs, or the balanced index flag.  That is, Btrieve v6.0 
     cannot open a file that uses the Btrieve v6.1 file format.

     NOTE:  Btrieve v6.0 returns a Status Code 30 (The file 
     specified is not a Btrieve file) when you attempt to open 
     a file created in the Btrieve v6.1 file format.  (This is 
     generally true whenever you use an earlier Btrieve 
     version to open a file that has a more recent Btrieve 
     file format.) 

   - Btrieve v6.x can open files that were created with earlier
     versions of Btrieve.  For example, Btrieve v6.0 can open 
     files created with Btrieve v5.x, and Btrieve v6.1 can open 
     files created with Btrieve v5.x or v6.0.  Additionally, 
     Btrieve v6.x can write to files using the existing file 
     format.  In other words, Btrieve v6.x writes to v5.x 
     files using the v5.x file format and writes to v6.x files 
     using the v6.x file format. 

     NOTE:  When Btrieve v6.x opens files from earlier versions,
     it does not convert them automatically to the v6.x file 
     format.  For example, if you use Btrieve v6.1 to open a 
     v6.0 file, Btrieve v6.1 does not convert the v6.0 file to 
     a v6.1 file format.  However, if an application uses 
     Btrieve v6.10a on a v6.0 file and creates an index which 
     uses a second ACS or a locale-specific ACS, the file 
     format will be upgraded to a version 6.1, thus preventing 
     the file from being opened by an earlier Btrieve version, 
     which would not recognize these features. 

     If your database contains files created with versions of 
     Btrieve prior to v6.x, you may want to upgrade them to 
     take advantage of the Btrieve v6.x features.  The Btrieve 
     Rebuild utility converts Btrieve data files to the v6.x 
     file format.  Refer to Chapter 3, "Installing and 
     Configuring Btrieve" in the "Btrieve Installation and 
     Operation" manual for information on how to rebuild your 
     existing Btrieve files. 

   - Btrieve v5.x cannot open files that have a v6.x file format.

     NOTE:  If you are using Btrieve v6.x and you need backward
     compatibility with Btrieve v5.x, use the Btrieve Setup 
     option Create Btrieve Files in Pre v6.x Format.  This 
     option allows you to create files with Btrieve v6.x and 
     use them with Btrieve v5.x.  (Keep in mind, however, that 
     many of the Btrieve v6.x features require the Btrieve 
     v6.x file format.)  Refer to Chapter 3, "Installing and 
     Configuring Btrieve" in the "Btrieve Installation and 
     Operation" manual for more information on the Setup utility.

   - Btrieve v6.1 supports a longer STS data type than NetWare SQL.

     NOTE:  Make sure that the length of the STS data type does 
     not exceed 15 bytes if you plan to use the Btrieve v6.1 
     files with NetWare SQL.

   - Btrieve v6.1 allows the creation of an STS data type index
     in files using the Btrieve v6.0 file format.

     IMPORTANT:  If you use Btrieve v6.00d or an earlier Btrieve
     version to access a file with an STS data type index, a
     server abend may occur.


Btrieve v6.x Operations
-----------------------

   Btrieve v6.1 supports the following new Btrieve operations.  
   For more information about these new operations, refer to 
   the "Btrieve Programmer's Manual" included in the NetWare 
   Btrieve v6.1 Developer's Kit Supplement, which is available 
   through the Professional Developer's Program (PDP).

   - Find Percentage and Get By Percentage -- Window-oriented
     applications can use these new operations for implementing
     scroll bars.

   - Get Direct/Chunk and Update Chunk -- Btrieve v6.1 allows
     applications to operate on portions of a record, called 
     "chunks," rather than on the entire record.  Through the 
     new Get Direct/Chunk and Update Chunk operations, Btrieve 
     v6.1 supports records larger than 64 KB.

     NOTE:  Applications can use the new chunk operations to 
     build records larger than 64 KB in files that use the 
     Btrieve v6.0 file format.  When Btrieve v6.0 operates on 
     files containing records larger than 64 KB, however, the 
     following restrictions apply:

     - If you use an Update Chunk operation in a file that
       uses the Btrieve v6.0 file format, one of the file's Free
       Space Lists may be left in a state that can cause Btrieve
       v6.00d or an earlier Btrieve version to overwrite its own
       cache; a server abend may occur.

     - Btrieve v6.0 does not recognize the Get Direct/Chunk or
       Update Chunk operations, and therefore can only perform
       operations that update or retrieve entire records.  Those
       "entire record" operations can only retrieve or update
       up to 64 KB of a record because the operations' data
       buffer length parameter, which specifies the amount of
       data to update or retrieve, can contain a maximum value
       of 64 KB.

     - If you use an Update Chunk operation to create a record
       larger than 64 KB in a file that uses the Btrieve v6.0
       file format, Btrieve v6.0 (which can only use operations
       to update or retrieve entire records) cannot retrieve
       more than the first 64 KB of the record.

       Btrieve v6.0 returns a Status Code 22 (The data buffer
       parameter is too short) or a Status Code 97 (The
       communications buffer is too small) to indicate that
       there is more data to be retrieved.

     - Because Btrieve v6.0 does not recognize the Update Chunk
       operation, you cannot use Btrieve v6.0 to modify a record 
       that is larger than 64 KB and still have the resulting 
       record be larger than 64 KB.  You can use the Update 
       operation to shorten such a record.  The length of the 
       resulting record of a successful Update operation is 
       defined by the operation's data buffer length 
       parameter, which has a maximum value of 64 KB. 


Btrieve v6.x Utilities
----------------------

   Btrieve Monitor utility (BTRMON.NLM) -- The Btrieve v6.x 
       Monitor utility (BTRMON.NLM) replaces the Btrieve v5.x 
       Console utility (BCONSOLE.NLM).

       IMPORTANT:  NLM applications that call Btrieve must 
       issue a Btrieve Reset before unloading.  Failure to do 
       so may lead to a server abend when you try to use the 
       Btrieve Monitor utility to monitor the NLM 
       application's activity. 

   Rebuild utility (BREBUILD.NLM) -- This new Btrieve v6.x 
       utility allows you to upgrade files created with 
       versions of Btrieve prior to v6.x.  Use this utility to 
       upgrade your files to take advantage of the Btrieve 
       v6.x features.  For more information about rebuilding 
       your existing files, refer to "Rebuilding Existing 
       Btrieve Files" in Chapter 3 of the "Btrieve 
       Installation and Operation" manual. 

       NOTE:  Before running the Rebuild utility (either from 
       the command line or through the Setup utility), you 
       must start Btrieve v6.x.

   Roll Forward utilities (BROLLFWD.EXE, PBROLL.EXE, and 
       WBROLL.EXE) --  When using Btrieve's logging feature 
       and the Roll Forward utility, consider the following:

       - Btrieve does not allow a log file to contain log 
         entries created by different versions of Btrieve.  
         That is, all entries in a log file must be logged 
         under the same version of Btrieve.  Otherwise, 
         Btrieve displays a system error message on the server 
         console and ignores logging for the Btrieve file. 

       - If you need to restart Btrieve, specify the same 
         index balancing setting that was used when you first 
         loaded 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
         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.

       The Btrieve v6.1 BROLLFWD.EXE file replaces the Btrieve 
       v6.0  DBROLL.EXE.


Btrieve v6.x Requesters
-----------------------

   Btrieve Requester for UnixWare -- This Requester is a new 
       component of NetWare Btrieve v6.1 for NetWare v3.12.  
       This Requester provides UnixWare clients with access to 
       Btrieve data residing on a NetWare Btrieve server.  For 
       detailed information about this Requester, refer to the 
       separate Readme document, BTRUNIX.DOC.

   Btrieve Requester for DOS -- This Requester has three new
       configuration options.  For detailed information about 
       this Requester, refer to Chapter 4 in the "Btrieve 
       Installation and Operation" manual.

       - NetWare Runtime Server Support (/C) -- Enables or 
         disables NetWare Runtime support.

       - DOS Session Load (/L) -- Allows you to load another 
         instance of the Btrieve DOS Requester even if it is 
         already loaded.  This option is useful if you want to 
         run MS Windows applications using the Btrieve DOS 
         Requester while running DOS VM applications that are 
         also using the Requester. 

       - Real-Time Data Compression (/O) -- Helps reduce network
         traffic by reducing the number of packets required to
         complete a request to Btrieve.

   Btrieve Requester for OS/2 -- This Requester also provides 
       Runtime Server support.  For detailed information about 
       the Btrieve OS/2 Requester, refer to Chapter 4 in the 
       "Btrieve Installation and Operation" manual.


Btrieve v6.x Status Codes
-------------------------

   Status Code 11 (The specified filename is invalid) --  If you
       receive this status code when you open a Btrieve file 
       using the Btrieve OS/2 Requester (BTRCALLS.DLL), make 
       sure that you are using the latest NetWare OS/2 Requester.

   Status Code 30 (The file specified is not a Btrieve file) -- 
       Btrieve v6.0 returns this status code when you attempt 
       to open a file that has a Btrieve v6.1 file format.  
       (This is generally true whenever you use an earlier 
       Btrieve version to open a file that has a more recent 
       file format.) 

   Status Code 43 (The specified record address is invalid) -- 
       The Btrieve Roll Forward utility receives this status 
       code when the address acquired from the Free Space List 
       of the Btrieve file during an Insert operation at roll 
       forward time is different from the one received at 
       logging time. 

       The synchronization problem with Free Space Lists occurs
       when you use different versions of Btrieve or the same 
       Btrieve version but with a different index balancing 
       setting. 

       The following is a summary of the specific conditions for
       which Status Code 43 can be returned:

       - During logging, you loaded Btrieve multiple times and
         did not specify the same index balancing setting each 
         time.

       - You inserted or updated a record larger than 57 KB.

       - At roll forward time, you loaded a different version of
         Btrieve or the same Btrieve version but with a different
         index balancing setting from what you used at logging 
         time.  To correct the synchronization problem with 
         Free Space Lists, load the proper version of Btrieve 
         with the proper index balancing setting.

   Status Code 44 (The specified key path is invalid) -- 
       Btrieve v6.1 returns this code for some situations, in 
       which earlier versions of Btrieve returned Status Code 
       82 (The application lost positioning).  These 
       situations can occur when you define the key attribute 
       to be manual or null (all-segment and any-segment).  If 
       you have an existing Btrieve application that checked 
       for Status Code 82, you may want to rewrite the 
       application to check for Status Code 44 as well. 

       Refer to Chapter 2 in the "Btrieve Programmer's Manual" 
       for more information about all-segment and any-segment 
       null keys.  The "Btrieve Programmer's Manual" is 
       included in the NetWare Btrieve v6.1 Developer's Kit 
       Supplement, which must be purchased separately. 

   Status Code 102 (Insufficient stack space is available) -- 
       Btrieve v6.1 requires 3 KB of stack space. If your NLM 
       application receives this status code, try increasing 
       the size of your stack space.  You may need more than 3 
       KB of stack space if you are accessing files defined by 
       NetWare SQL as being under referential integrity (RI) 
       constraints.  Because Btrieve uses recursion when 
       enforcing the constraints, you will need 3 KB of stack 
       space at the deepest level of recursion.


================================================================
Btrieve v6.x Program Files
==========================

   The NetWare Btrieve v6.1 program files can be grouped into the
   following categories:

   - Files related to server operations
   - Files related to DOS workstation operations
   - Files related to MS Windows workstation operations
   - Files related to OS/2 workstation operations
   - Files related to UnixWare workstation operations

   The following lists describe the NetWare Btrieve v6.1 
   program files in each category.

   - Files related to server operations:

     BREBUILD.NLM    Rebuild utility that lets you convert 
                     existing Btrieve v5.x files to Btrieve 
                     v6.x format. 

     BROUTER.NLM     NLM that allows server-based Btrieve 
                     applications to access Btrieve databases 
                     on remote servers. 

     BSETUP.NLM      Btrieve installation and configuration 
                     utility. 

     BSETUP.HLP      Help file for BSETUP.NLM.

     BSPXCOM.NLM     SPX communications agent.

     BSPXSTUB.NLM    NLM that allows you to use the Btrieve 
                     Monitor utility (BTRMON.NLM) when 
                     BSPXCOM.NLM is not loaded.

     BSTART.NCF      Batch file executed to start Btrieve.  
                     This file also loads BSPXCOM.NLM and 
                     BROUTER.NLM (if Btrieve is configured to 
                     do so). 

     BSTOP.NCF       Batch file executed to stop Btrieve.  
                     This file also unloads BSPXCOM.NLM and 
                     BROUTER.NLM (if loaded).

     BTRIEVE.NLM     Btrieve Record Manager (database engine).

     BTRIEVE.ORG     BTRIEVE NLM to which you can apply any 
                     future patches.

     BTRMON.NLM      Btrieve Monitor utility that lets you 
                     monitor the activity of Btrieve files, 
                     users, and communications resources.  

     BTRMON.HLP      Help file for BTRMON.NLM.

     BUTIL.NLM       Btrieve Maintenance utility, which is a 
                     command line utility that allows you to 
                     create, manipulate, and recover Btrieve 
                     data files.  

     RSPXSTUB.NLM    Module that resolves external references 
                     for the Btrieve Monitor utility 
                     (BTRMON.NLM) when BSPXCOM.NLM is not 
                     loaded.  If you want to use the Btrieve 
                     Monitor utility to monitor outgoing 
                     requests generated by the Btrieve Message 
                     Router (BROUTER.NLM) to another server 
                     and you do not want to load BSPXCOM.NLM, 
                     load RSPXSTUB.NLM instead of BSPXSTUB.NLM 
                     at the server. 


   - Files related to DOS workstation operations:

     BREQUEST.EXE    Btrieve Requester for DOS.

     BREQUTIL.EXE    Btrieve Requester utility that allows you to
                     stop the Requester and to obtain the 
                     Requester's version number at a DOS 
                     workstation. 

     BREQUTIL.MSG    Message file for BREQUTIL.EXE.

     BROLLFWD.EXE    Roll Forward utility for the DOS operating
                     environment.  This utility recovers changes
                     made to a Btrieve file between the time of
                     the last backup and a system failure.

     BROLLFWD.MSG    Message file for BROLLFWD.EXE.


   - Files related to MS Windows workstation operations:

     WBROLL.EXE      Roll Forward utility for the MS Windows 
                     operating environment.  This utility 
                     recovers changes made to a Btrieve file 
                     between the time of the last backup and a 
                     system failure. 

     WBROLLRS.DLL    Resource file for WBROLL.EXE.

     WBTRCALL.DLL    Btrieve Requester for MS Windows.

     WBTRVRES.DLL    Resource file for the Btrieve MS Windows 
                     Requester.

     WNDBCNVT.EXE    MS Windows Conversion utility that converts
                     the client-based Btrieve DLL (WBTRCALL.DLL)
                     to WBTRLOCL.DLL.

     NOVDB.INI       Btrieve initialization file for the Btrieve
                     MS Windows Requester.


   - Files related to OS/2 workstation operations:

     PBROLL.EXE      Roll Forward utility for the OS/2 operating
                     environment.  This utility recovers changes
                     made to a Btrieve file between the time of
                     the last backup and a system failure.

     PBTRVRES.DLL    Resource file for PBROLL.EXE.

     BTRCALLS.DLL    Btrieve Requester for OS/2.

     NDBCOMM.DLL     Communications handler for the Btrieve
                     Requester for OS/2.

     NDBCNVT.EXE     OS/2 Conversion utility that converts the
                     client-based Btrieve DLL (BTRCALLS.DLL) to
                     BTRLOCL.DLL.


   - Files related to UnixWare workstation operations:

     LIBBTRV.A       Archive Btrieve Interface Library.

     LIBCOMM.A       Archive Communications Interface Library.

     LIBBTRV.SO      Shared-object Btrieve Interface Library.

     LIBCOMM.SO      Shared-object Communications Interface 
                     Library.

     UNXCBTRV.O      C interface object file.

     BTRUNIX.DOC     Readme document that describes the 
                     Btrieve Requester for UnixWare.


================================================================
Associated Documents
====================

   Btrieve Programmer's Manual -- This manual is a component of 
   the NetWare Btrieve v6.1 Developer's Kit Supplement, which 
   is available through the Professional Developer's Program 
   (PDP).  For information about the Btrieve v6.x file format 
   and Btrieve operations, refer to this manual.

