Configuring an MS Windows Workstation for Btrieve

Since MS Windows allows you to run both DOS and MS Windows applications, there are many different combinations of workstation configurations from which to choose, depending on the application. For example, you may want to run a DOS-based Btrieve application in an MS Windows DOS session using a local engine, or an MS Windows-based Btrieve application using the requester while running a DOS-based application that uses the local engine, BTRIEVE.EXE.

This article explores each of the possible configurations for running DOS- and MS Windows-based Btrieve applications on an MS Windows workstation. There are two types of Btrieve workstation programs that can be configured either separately or in combination on an MS Windows workstation:

Local (client-only)
Requester (client/server)

The Local Implementation of Btrieve

The local configuration of Btrieve is a multiuser version that allows multiple access to Btrieve data files on a standalone workstation or multiple access to Btrieve data files residing on a DOS 3.1 compatible network. The DOS version of local Btrieve is implemented as a TSR called BTRIEVE.EXE and is used by DOS applications. The MS Windows implementation of local Btrieve is a DLL called WBTRCALL.DLL and is used by MS Windows applications. This client DLL has a size of approximately 51K. Initialization parameters for the local WBTRCALL.DLL are specified in the WIN.INI file in the [btrieve] paragraph.

The Requester Implementation of Btrieve

The NetWare Btrieve requester configuration enables multiple workstations to access Btrieve data files that reside on NetWare servers running the Btrieve NLM or VAP. This configuration provides a simple and efficient client/server environment for client applications. The DOS version of the Btrieve requester is implemented as a TSR called BREQUEST.EXE.

The MS Windows implementation of the Btrieve requester is composed of three files:

BREQUEST.EXE (the DOS requester)
WBTRCALL.DLL (approximate DLL size is 13K)
WBTRVRES.DLL (resource-only DLL)

Initialization parameters for the Btrieve requester for MS Windows are specified in the NOVDB.INI file in the [brequestDPMI] paragraph. Because both the local and the requester Windows DLLs are named WBTRCALL.DLL, changing between the two configurations is invisible to the Btrieve Windows application running on the workstation. With no changes to the application and without having to recompile, you can change the environment from local to client/server and vice versa.

TSR vs. DLL

Because MS Windows provides an environment for executing both native MS Windows applications and DOS applications, some users become confused about which Btrieve executable provides services to their application. Btrieve DOS applications running in an MS Windows DOS session always access only the Btrieve TSR (either BREQUEST.EXE or BTRIEVE.EXE). Native MS Windows applications always access WBTRCALL.DLL (either the requester or the local DLL).

Six Different Configurations

On an MS Windows workstation, when running both DOS and MS Windows Btrieve applications, the local and requester configurations of Btrieve can be combined into several different configurations. The following sections detail each of these configurations.

DOS applications in an MS Windows DOS session using local BTRIEVE.EXE OR the requester, BREQUEST.EXE

When running DOS Btrieve applications in an MS Windows DOS session that use either BTRIEVE.EXE or BREQUEST.EXE, the desired TSR should be loaded in each DOS session. Do not load either TSR before starting MS Windows. Running in this environment, if you exit a DOS session that has BREQUEST.EXE loaded, the workstation hangs. This problem is caused by the VIPX.386 driver that shipped with MS Windows v3.1. To correct this problem, a new VIPX.386 driver can be obtained from Novell via CompuServe in the MS Windows Client Update Kit. Currently, this kit is available in the NOVFILES forum in the file, WINUP8.EXE. If using BTRIEVE.EXE and the Btrieve data files reside on a local drive rather than a network drive, install SHARE.EXE before starting MS Windows if:

More than one application will be accessing the data files simultaneously
A single application will be accessing a data file with more than one position block simultaneously.

In either case, if SHARE.EXE is not installed before starting MS Windows, data file corruption may result.

MS Windows applications using local WBTRCALL.DLL

If you are running an MS Windows application and want to use the client Btrieve engine, place the 51K client WBTRCALL.DLL in a directory accessible by MS Windows. MS Windows searches for DLLs in the following order:

The current directory
The \WINDOWS directory
The MS Windows system directory
The directories in the PATH environment variable
Network search drives

As with the DOS client version of Btrieve, you should install SHARE.EXE in the same cases when using local WBTRCALL.DLL for the same reason.

MS Windows applications using the requester WBTRCALL.DLL

The Btrieve requester for MS Windows consists of a DOS portion and Windows portion. To configure the workstation to use the Btrieve Windows requester:

Load BREQUEST.EXE before starting MS Windows.
Place the 13K requester DLL, WBTRCALL.DLL in a directory accessible by MS Windows, along with WBTRVRES.DLL.
WBTRVRES.DLL is a resource-only DLL that is used by the requester WBTRCALL.DLL, not by your application. Btrieve will return a status 1017 to your application if WBTRVRES.DLL is not available to MS Windows when using the requester DLL.
MS Windows applications using requester & local DLLs

You can configure the workstation to use both the local DLL and the requester DLL. In this environment, you access local data files (files that reside on a drive physically located at your workstation) through the local DLL. Data files residing remotely on a NetWare server drive are accessed through the requester DLL. To configure the workstation for both local and requester access:

Load BREQUEST.EXE before starting MS Windows.
Place the 13K requester DLL, WBTRCALL.DLL, and resource DLL, WBTRVRES.DLL, in a directory accessible by MS Windows.
Run the MS Windows utility, WNDBCNVT.EXE, against the local 51K WBTRCALL.DLL. WNDBCNVT.EXE renames the local WBTRCALL.DLL to "WBTRLOCL.DLL" and changes the DLL name internally to "WBTRLOCL." Do not rename the local DLL manually. If WNDBCNVT is not used to rename the DLL, the internal name conversion is not performed and the configuration will not operate properly.
Place WBTRLOCL.DLL from step 3 in a directory that is accessible by MS Windows.
In the NOVDB.INI file in the Windows directory, add the line: local=yes to the [brequestDPMI] paragraph.

MS Windows apps using the requester while running DOS applications with the DOS requester, BREQUEST.EXE

When using the MS Windows Btrieve requester DLL, BREQUEST.EXE is loaded before going into MS Windows. When DOS applications that will be accessing the requester are run in MS Windows DOS sessions, BREQUEST.EXE must be loaded in the DOS session. This situation creates a conflict when both run simultaneously; when BREQUEST.EXE tries to load in the DOS session, the message "Brequest already loaded" is generated. To resolve this situation, BREQUEST.EXE v6.0 and later have implemented a new load parameter, "/L." "BREQUEST /L" makes it possible to load BREQUEST.EXE again in an MS Windows DOS session even though it was already loaded before starting MS Windows. This command loads another instance of Brequest that is only available to the DOS session. Thus, the DOS session has its own copy.

To configure the workstation for this operating environment, BREQUEST.EXE should be loaded as usual before starting MS Windows and then in each DOS session that will be running a Btrieve application, "BREQUEST /L" should be loaded. MS Windows applications will run as described previously.

MS Windows apps using the requester while running DOS applications using the local engine, BTRIEVE.EXE

While using the MS Windows Btrieve requester, DOS applications in MS Windows DOS sessions may want to simultaneously use BTRIEVE.EXE. This situation also presents a problem, since BREQUEST.EXE must be loaded before MS Windows for use with the MS Windows requester DLL, and BTRIEVE.EXE must be loaded in each MS Windows DOS session. If you do not resolve this conflict, BTRIEVE.EXE reports, "Btrieve already loaded," and BTRIEVE.EXE will not load. BTRIEVE.EXE does not have a special load option like the BREQUEST.EXE "/L" parameter.

To enable this configuration, load BREQUEST.EXE before MS Windows by using the WINSTART.BAT file feature provided by MS Windows. WINSTART.BAT is a batch file that MS Windows runs automatically when it is started in 386 enhanced mode. The programs that are started from within the WINSTART.BAT file are loaded in enhanced mode and are available to MS Windows applications, but not to DOS sessions started in MS Windows. If Brequest is loaded in WINSTART.BAT, BTRIEVE.EXE can then be loaded in a DOS session. To load BREQUEST.EXE in this manner, create the WINSTART.BAT file in the MS Windows directory and add a line specifying the BREQUEST.EXE program name followed by the parameters that your application requires for Brequest. For example:

    BREQUEST /d:8192

The only drawback to this solution is that MS Windows v3.1 may sometimes hang on exit if TSRs are loaded with the WINSTART.BAT file. So, if the chance of hanging on exit from MS Windows must be prevented, or if you need to run MS Windows in standard mode, this configuration is not an option.

Stay Up-To-Date

The latest Btrieve requesters, WNDBCNVT.EXE, and a sample NOVDB.INI are posted on CompuServe in NOVLIB, Library 1, in the file BTRREQ.EXE. After 30 days without an update this file will be moved to Library 7. In addition, the latest patches for the current local Btrieve engines (BTRIEVE.EXE v5.10a and WBTRCALL.DLL v5.10) are available on CompuServe in NOVLIB, Library 7, in the file BTR510.EXE. These files can also be requested by mail by contacting Novell Developer Support.