
              NOVELL TECHNICAL INFORMATION DOCUMENT

TITLE:              Btrieve Requesters v6.1x
DOCUMENT ID:        TID000065
DOCUMENT REVISION:  A
DATE:               20SEP93
ALERT STATUS:       Yellow
INFORMATION TYPE:   Issue
README FOR:         BTRREQ.EXE

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
THE ORIGIN OF THIS INFORMATION MAY BE INTERNAL OR EXTERNAL TO NOVELL. 
NOVELL MAKES EVERY EFFORT WITHIN ITS MEANS TO VERIFY THIS INFORMATION. 
HOWEVER, THE INFORMATION PROVIDED IN THIS DOCUMENT IS FOR YOUR INFORMATION
ONLY.  NOVELL MAKES NO EXPLICIT OR IMPLIED CLAIMS TO THE VALIDITY OF THIS
INFORMATION.
_________________________________________________________________


Contents
========

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


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

Self-Extracting File Name:  BTRREQ.EXE      Revision:  A

Files Included     Size     Date      Time

\
  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 **

