NOVELL TECHNICAL INFORMATION DOCUMENT

TITLE: Btrieve Requesters v6.1x DOS, OS/2, Windows, UnixWare
DATE: 20SEP93
README FOR: BTRREQ.EXE
NOVELL PRODUCT CLASS: Database Products
NOVELL PRODUCT and VERSION: NetWare Btrieve NLM 5.15; 
                            NetWare Btrieve VAP 5.15; 
                            NetWare Btrieve NLM 6.10
ABSTRACT: This file contains the latest Btrieve requesters for use 
          with the 5.x versions of the Btrieve VAP and NLM and the 
          6.x versions of the Btrieve NLM.  Included are the latest 
          requesters for DOS, Windows, OS/2, and UnixWare workstations.


===========================================================================
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
========

   File Information
   Installation & Compatibility
   Upgrade File Descriptions
   Using the Requesters
      DOS Requester
      OS/2 Requester
      Windows Requester

===========================================================================
File Information
================

Filename:  BTRREQ.EXE

Date:      9/29/93

Files Included:
BTRREQ   TXT     This file

\DOS
BREQUEST MSG      1180 08-05-93   2:24p
BREQUEST EXE     58888 08-09-93  10:00a
BREQUTIL EXE     21775 01-30-93  12:32p
BREQUTIL MSG       974 01-30-93  12:32p

\OS2
NDBCNVT  EXE     18192 01-29-93   1:40p
NDBCOMM  DLL     20343 08-25-93   3:40p
BTRCALLS DLL     17944 06-11-93   9:32a
NWLOCALE DLL     34480 05-18-93   1:00p

\UNIXWARE
LIBBTRV  A       21432 02-05-93   6:08p
LIBBTRV  SO      18268 02-05-93   6:08p
LIBCOMM  A       19120 02-05-93   6:08p
LIBCOMM  SO      18596 02-05-93   6:08p
BTRUNIX  DOC     12231 06-23-93  10:08a
UNXCBTRV O        1420 11-30-92  11:40a
BTRUNIX  TXT     12231 06-24-93   2:16p

\WIN
NOVDB    INI      2460 11-06-92  10:48a
WNDBCNVT EXE     30926 01-30-93  12:08p
WBTRVRES DLL     22912 01-30-93  12:16p
WBTRCALL DLL     13131 05-13-93   4:00p
NWLOCALE DLL     38800 05-18-93   1:00p


===========================================================================
Installation & Compatibility
============================

The Btrieve 6.1x Requesters can be used with the following NLMs and VAPs:

        Btrieve NLM v5.15
        Btrieve VAP v5.15
        Btrieve NLM v6.0x
        Btrieve NLM v6.1x

To install the requesters, simply replace the existing requester with the
new requester contained with this update.

===========================================================================
Upgrade File Descriptions
=========================

  BTRREQ.TXT           This README file

   - Files related to DOS workstation operations:

     BREQUEST.EXE    Btrieve Requester for DOS.

     BREQUEST.MSG    Message file for BREQUEST.EXE.

     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.


   - Files related to Windows workstation operations:

     WBTRCALL.DLL    Btrieve Requester for Windows.

     WBTRVRES.DLL    Resource file for the Btrieve Windows Requester.

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

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

     NWLOCALE.DLL    National Language Support DLL for the NetWare v3.11
                     environment. Note that the WIN and the OS2
                     directories each contain a different NWLOCALE.DLL.


   - Files related to OS/2 workstation operations:

     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.
     NWLOCALE.DLL    National Language Support DLL for the NetWare v3.11
                     environment. Note that the WIN and the OS2
                     directories each contain a different NWLOCALE.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.TXT     Readme document that describes the Btrieve Requester
                     for UnixWare.


===========================================================================
Using the Requesters
====================

   Btrieve provides Requesters for DOS, OS/2, and Windows applications.
   This section provides configuration options and instructions for loading
   and unloading the Requester in each operating environment.

   The Btrieve Requesters have changed (primarily in key definition) between
   previous versions and Btrieve v6.x. Therefore, all workstations accessing
   the Btrieve NLM must use the Btrieve v6.x Requesters.


DOS Requester
-------------

   You must load the Btrieve DOS Requester, BREQUEST.EXE, at a workstation
   before that workstation can access network Btrieve files using the Btrieve
   NLM. The DOS Requester loads into a DOS workstation's memory as a Terminate
   and Stay Resident (TSR) program. You can access local as well as remote
   files by running both client-based (local) Btrieve and the Requester at
   your workstation.


DOS Requester Configuration Options

   There are two configuration options for the DOS Requester: Data Message
   Length (/D) and Help (/?). Previous versions of Btrieve supported the /S
   and /R options. Btrieve v6.x accepts the /S and /R options for backwards
   compatibility, but otherwise ignores them.

   Data Message Length (/D)
   Range: 532 through 57,000 bytes
   Default: 4,096 bytes
   Memory Required: 538 bytes + data message length

   This option specifies the length of the largest record you want to
   access through Btrieve. (If you omit this option, the Requester
   uses the default value, 4,096.) The Requester uses this value to
   calculate the length of the data message buffer reserved for passing
   records between Btrieve and your applications. The Requester maintains
   one copy of the data message buffer.

   The value you enter here should not exceed the largest record size
   you configure for Btrieve through the Setup utility since that is the
   maximum message that BSPXCOM can receive.

   NOTE:  Specifying a higher value than you need for the /D option
          does not improve performance.

   Help (/?)
   The /? option lists the only other option that is used, /D, and
   mentions that although the /S and /R options are for backwards
   compatibility, Btrieve v6.x ignores them.


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


Loading the DOS Requester

   Load the DOS Requester at the workstation by entering the following
   command:

      [path] BREQUEST [/D:dataMsgLength]

   path    The pathname to the directory where the DOS Requester is stored.
           You can omit the pathname if the DOS Requester is stored on the
           default drive or if it is located in a directory in your search
           path.

   For example, if the Requester is on the default drive and you want to
   specify a 2,048-byte data message length, enter BREQUEST /D:2048.

   NOTE:  The forward slash (/) before the configuration option is the
          only valid character you can use. If you specify a dash (-) or
          a backslash (\), the Requester may load improperly.

   To ensure that the DOS Requester is always loaded with the /D option set
   to a particular value, place the BREQUEST command in the workstation's
   AUTOEXEC.BAT file.


Unloading the DOS Requester

   At a DOS workstation, you can use two methods to unload the DOS
   Requester:

   - Your application can issue a Stop operation (Btrieve
     operation 25).

   - You can issue the stop command in the BUTIL utility from the
     workstation's command line.


OS/2 Requester
--------------

   The following files must be loaded in a directory listed in an OS/2
   workstation's LIBPATH before a Btrieve application can access the network
   from that workstation:

   BTRCALLS.DLL - the Btrieve dynamic link Requester for OS/2 workstations.
   NDBCOMM.DLL  - the communications Requester for OS/2 workstations.
                  NDBCOMM.DLL provides the necessary data communications between
                  the workstation and the Btrieve NLM.

   You can access local as well as remote files by running both client-based
   (local) Btrieve and the Requester at your workstation. If you want to run
   both client-based Btrieve and the Requester, you must use the OS/2
   conversion utility (NDBCNVT.EXE) to convert BTRCALLS.DLL to BTRLOCL.DLL.
   You must type NDBCNVT on the command line to use this utility.
   (By default, the Requester and the client-based Btrieve have the same
   name.)


OS/2 Requester Configuration Options

   You are not required to specify any configuration options for the OS/2
   Requester. Since the internal tables that control the options are not
   fixed, the tables will grow as needed. However, if you prefer to set
   the initial size of the tables, you can do so using the Data Message
   Length (/D) and the Number of Servers (/S) options.

   Data Message Length (/D)
   Range: 532 through 65,000 bytes
   Default: 4,096 bytes
   Memory Required: 538 bytes + data message length

   The /D option specifies the length of the largest record you want
   to access through Btrieve. The OS/2 Requester uses this value to
   calculate the length of the data message buffer reserved for passing
   records between Btrieve and your applications. The Requester maintains
   one copy of the data message buffer.

   The value you enter here should not exceed the value you specified for
   the Largest Record Size configuration option in the Setup utility.
   The value for this option represents the maximum message length that
   BSPXCOM can receive.

   NOTE:  Specifying a higher value than you need for the /D option
          does not improve performance.

   Number of Servers (/S)
   Range: 1 through 255
   Default: 8
   Memory Required: 27 bytes per server

   The /S option specifies the number of servers that have the Btrieve
   NLM active on the network.

   NOTE:  The forward slash (/) before the configuration option is the only
          valid character you can use. If you specify a dash (-) or a backslash
          (\), the Requester may load improperly.


   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.


Configuring the OS/2 Requester

   Set the Requester configuration options using the following command:

      SET BRQPARMS=/D:dataMsgLength /S:numberOfServers

   Do not include a space between BRQPARMS and the equal sign. You can,
   however, insert a space between each configuration option you specify.


Loading the OS/2 Requester

   An application may load the Btrieve for OS/2 Requester in one of the
   following two ways:

   Implicitly - Your application can implicitly load the OS/2 Requester
   by either linking with the import library BTRCALLS.LIB or by specifying
   imported functions in the application definition file. If your
   application uses this method, the operating system loads the OS/2
   Requester automatically when the application is started.

   Explicitly - Your application can load the OS/2 Requester explicitly
   using the operating system API functions. When the application loads
   the Requester explicitly, the operating system does not load the OS/2
   Requester until notified to do so.


Unloading the OS/2 Requester

   At an OS/2 workstation, the operating system removes the dynamic link
   routines from memory when the application terminates or when the
   application explicitly unloads the OS/2 Requester using the operating
   system API.

   Logging out of one or more servers from a workstation does not close
   Btrieve files or terminate the Btrieve SPX connection to the server.
   To close files and terminate the connection, you must either issue a
   STOP command or reboot the server.


Windows Requester
-----------------

   In the Windows environment, you must load the DOS Requester, BREQUEST.EXE,
   before starting Windows. Windows-based Btrieve applications access the
   Requester by means of a DLL, WBTRCALL.DLL, which uses the DOS Protected
   Mode Interface (DPMI) that Windows provides.

   The Windows Requester (that is, WBTRCALL.DLL) is the Btrieve interface DLL
   for Windows v3.x. The DLL provides the same API as client-based Btrieve
   and requires no modification to the application.

   You can access local as well as remote files by running both client-based
   (local) Btrieve and the Requester at your workstation. If you want to run
   both client-based Btrieve and the Requester, you must run the Windows
   Conversion utility (WNDBCNVT.EXE) to convert WBTRCALL.DLL to WBTRLOCL.DLL.
   You must type WNDBCNVT on the command line to use this utility.

Windows Requester Configuration Options

   The following list describes the available configuration options for
   the Windows Requester. These options should be specified in the NOVDB.INI
   file under [brequestDPMI].

   NOVDB.INI is the Novell initialization file for the Windows Requester.

   Tasks = #            Specifies how many concurrent tasks may use the
                        Windows Requester. The default value for this
                        configuration option is 10.
   Local = Yes/No       Instructs the Windows Requester to use client-based
                        Btrieve for accessing files locally. The default
                        value for this configuration option is No.
   Chkparms = Yes/No    Instructs the Windows Requester to validate pointers
                        passed to it. You should use this option only
                        during development. The default value for this
                        configuration option is No.
   Free Memory = Yes/No Allocates and frees real-mode memory on each
                        request. The Windows Requester uses a buffer of
                        real-mode memory to communicate with the DOS
                        Requester. Since real-mode memory is a scarce
                        resource in Windows, your application should
                        not retain it long term.The default value for this
                        configuration option is No.

                        NOTE:  Specifying Yes to the Free Memory option
                               degrades performance.


Loading the Windows Requester

   The DOS Requester must be loaded before the Windows Requester can load.
   An application may load the Windows Requester in one of the following two
   ways:

   Implicitly - Your application can implicitly load the Btrieve Requester
   by either linking with the import library WBTRCALL.LIB or by specifying
   imported functions in the application definition file. When an
   application loads a DLL implicitly, the operating system automatically
   loads the DLL when the application is started.

   Explicitly - Your application may load the Windows Requester explicitly
   using the operating system API functions. The operating system does not
   load the DLL until notified to do so.


Unloading the Windows Requester

   At a Windows workstation, the operating system removes the dynamic link
   routines from memory when the application terminates or when the
   application explicitly unloads the DLLs using the operating system API.


   NOTE:  Logging out of one or more servers from a workstation does not
          close Btrieve files or terminate the Btrieve SPX connection
          to the server. To close files and terminate the connection,
          you must either issue a STOP command or reboot the server.
          A Reset operation does not terminate the SPX connection.


UnixWare Requester
------------------
For infomormation regarding the Btrieve UnixWare requester, see the
file BTRUNX.TXT.

========================================================================
** End of BTRREQ.TXT **

