Validating Key Buffers with Btrieve for Windows & OS/2

The client version of Btrieve for Windows will validate pointers when using the "tracefile= " line in the [Btrieve]paragraph of WIN.INI. When using NetWare Btrieve and the requester for Windows, setting "chkparms=yes" in the [BrequestDPMI] paragraph will validate pointers. Client versions of Btrieve for OS/2 will validate pointers when the environment variable, "BTRPARMSCHK," is set equal to "YES."

Btrieve validates the pointer parameters passed in for read/write access over certain ranges. If the pointers passed to Btrieve do not have access to memory specified by the pointers, a status 1015 will be returned. If you are using the "tracefile=" method, Btrieve for Windows will return "INVALID POINTER parameter #?" in your tracefile, where "?" would be one to four referring to the position block, data buffer, data buffer length, and key buffer respectively.

The key buffer parameter is always evaluated for the maximum number of bytes (255) regardless of what is specified in the key buffer length parameter. So, to use pointer validation effectively,allocate the key buffer parameter as a pointer to a block of 255 bytes.

TTS & Pre-Imaging

If TTS is disabled at the server and the Btrieve data files to be accessed with the NetWare Btrieve v5.15 are flagged "transactional" (T), Btrieve will return a status 15 (Pre-image I/O Error) on all updates (Insert, Update and Delete operations) to the data files between Begin Transaction (19) and End Transaction (20) operations.

The status 15 is not returned when:

• The update is performed outside of a Btrieve transaction
• Before the update is performed inside of a Btrieve transaction, a successful update has occurred outside of a transaction
• with the current instance of Brequest. This case is reinitialized once Brequest is unloaded and loaded again on the workstation.

If Btrieve data files are flagged transactional, TTS must be enabled at the server for pre-imaging to be performed. When TTS is disabled, flag all Btrieve files non-transactional (-T).

Windows, TBMI, VIPX.386, & DOS Applications

Within Windows, running Brequest and a DOS application in a DOS box requires different setups depending on which version of Windows you use and whether or not you run Windows in standard mode or enhanced mode.

• If you run Windows v3.0 in standard mode, load TBMI.COM before starting Windows. In the DOS box, load TASKID.COM, BREQUEST.EXE, and the DOS application (in that order). TBMI.COM and TASKID.COM are currently available on Novell's CompuServe forum, NetWiresm (NOVLIB, LIB 1 or 5, WINUP6.ZIP).
• If you run Windows v3.1 in standard mode, load TBMI2.COM before starting Windows. In the DOS box, load BREQUEST.EXE and then the DOS application. TBMI2.COM is provided with Windows v3.1.
• If you run either Windows v3.0 or v3.1 in enhanced mode, then you should use VIPX.386. Modify the SYSTEM.INI file under the [386Enh] header by adding the line: "network=VIPX.386."

If a Windows application (not DOS) requires BREQUEST.EXE, then load BREQUEST.EXE before you start Windows.

Pre-imaging in NetWare Btrieve v6.0

NetWare Btrieve v6.0 creates a pre-image file when writing to a Btrieve file created with an earlier version of Btrieve. However, the format of this pre-image file is different from the format of a pre-image file created by earlier versions of Btrieve. Earlier versions of Btrieve cannot accurately interpret a pre-image file created by NetWare Btrieve v6.0 and vice versa.

If you need to interchange the Btrieve engine that will be accessing the pre-v6.0 Btrieve file, all pre-image files must be cleaned up prior to swapping engines. Use the following procedure to clean up these pre-image files:

1. Check to see if a .PRE file exists for any Btrieve files
2. If a .PRE file exists with a pre-v6.0 version of Btrieve:
   • open the Btrieve file in Exclusive mode
   • perform a Get First operation
   • perform an Update operation
   • close the Btrieve file (this should cause the .PRE file to be deleted)
3. Switch engines

NetWare Btrieve v6.0 & Patch311.NLM

When using BTRIEVE.NLM v6.0 with NetWare v3.11, make sure that PATCH311.NLM (the patch file for the version of CLIB.NLM released with NetWare v3.11) is in the SYS:\SYSTEM directory before you attempt to load BTRIEVE.NLM, regardless of which version of CLIB.NLM the networkuses. BTRIEVE.NLM v6.0 always attempts to automatically load this patch file. PATCH311.NLM will only load if the released CLIB.NLM is running. If the system uses a newer version of CLIB.NLM, PATCH311.NLM will detect it and do nothing. As long as the Btrieve NLM can locate the patch file, it will load whether PATCH311.NLM successfully loads or not.

Using Brequest in Multiple Desqview Sessions

With Desqview v2.40, if you have multiple sessions running Btrieve applications using the NetWare Btrieve requester (BREQUEST.EXE), Btrieve may return a status 79 (Programming Error). The Desqview v2.40 configuration option, "Network Buffers," can be increased to resolve this status code.

From a Desqview window, run the program DVSETUP. Then, select the advanced setup procedure. From the advanced menu, select the Network option. One of the network options is called "Network Buffers." The default for this parameter is 8. Raising this value to 16 will usually resolve the status 79.

Status 2001 with WBTRCALL

With the Windows Btrieve requester, WBTRCALL.DLL v5.17a (date: 6-28-91), Btrieve returns a status 2001 (Insufficient Memory) on any Btrieve call issued after a WBTRVSTOP call. The status 2001 only occurs within a single task or program. If an application that makes Btrieve calls is running and that application, or any other application calls WBTRVSTOP, the NetWare Btrieve NLM will return a status 2001 on each successive Btrieve call in all Btrieve applications that are running until the applications are restarted.

This situation has been resolved in the version of WBTRCALL.DLL (NetWare Btrieve v6.0) that ships with NetWare SQL (NLM) v3.0. If you use the v6.0 WBTRCALL.DLL, you also need WBTRVRES.DLL (also included with NetWare Btrieve v6.0).

Status 84 and Insert Operations

A status 84 (Record in Use) is a valid status code on an Insert operation. Insert operations occasionally return this status code when a stress test is conducted with several PCs. NetWare Btrieve returns this status code because it is locking the key page for a brief period of time to update key information. At this time, if a user tries to insert records that are indirectly accessing the key page, the Insert operation will result in a status 84.

To avoid this situation, design your applications to trap for status 84s and retry the Insert operation.

Btrieve v6.0 Page Size & NetWare v3.11

If the page size of a Btrieve data file is not evenly divisible into 4096 (is NOT 512, 1024, 2048 or 4096), the file may become corrupted. The NetWare v3.11 patch, ASNCRDFX.NLM (Async Read Fix), fixes this problem. This patch is available on NetWire (NOVLIB, 311PT9.ZIP).

Rolling-Forward with Btrieve v5.x & v6.0

Log files created with Btrieve v5.x can only be rolled-forward with Btrieve v6.0 under certain circumstances. The following list describes each possibility.

1. Log files created with Btrieve v5.x can be applied to v5.x files with the v6.0 xBROLL utilities (DBROLL, PBROLL, WBROLL).
2. Log files created with Btrieve v6.0 are not compatible with the v5.x roll-forward utilities (BROLLFWD and WBROLL 5.x) and cannot be used with the 5.x utilities.
3. If a single log file contains entries that were created by both Btrieve v5.x and Btrieve v6.0 (using the xBROLL v6.0 utilities), if the first entry was created by Btrieve v5.x, only the v5.x entries in the log file will be applied. If the first entry in the log file is created by Btrieve v6.0, the xBROLL v6.0 utilities will only apply to the v6.0 entries.
4. If a log file is created with Btrieve v5.x, the changes in the log file can be applied to a Btrieve file with the xBROLL utilities multiple times. If a log file is created by Btrieve v6.0, (even if the data file is a v5.x format file), once xBROLL is used to apply the changes to a Btrieve file, the entries in the log file are marked as "used" and cannot be applied again to a data file using xBROLL.

Btrieve for DOS and Btrieve for Windows manage handles differently. Btrieve for DOS v5.10a allocates its own Program Segment Prefix (PSP) with a file handle table of size (/f parameter * 2) entries (with patch #99 applied). Btrieve for DOS does not use the calling application's file handles. This means that when a DOS application has opened 20 Btrieve files, the application still has 15 handles (20 DOS default handles minus 5 standard handles) available for use to issue DOS Open calls to non-Btrieve files.

Btrieve for Windows manages handles using the calling application's file handle table. When the application's available handles are exhausted, WBTRCALL will "rotate" the handles as in versions of Btrieve for DOS prior to v5.10. Once 15 Btrieve files are open, there are no handles available to the calling application for DOS Open calls to non-Btrieve files, since DOS will not rotate handles.

At this point, if another Btrieve Open call is issued, WBTRCALL will close one of its open files and use the handle to open the new file. This process occurs invisibly to the application and WBTRCALL can handle up to its current "/f:" parameter of rotating files at one time.

WBTRCALL will use whatever application handles are available. If DOS Open calls to non-Btrieve files are needed along with more than 15 Btrieve Opens, one solution is to open the DOS files before the Btrieve files. Otherwise, you could increase the number of handles available to the application at compile time. The process of increasing the number of open files to more than the default 20 varies depending on which compiler you use.

BSPXCOM & SPX Sessions

BSPXCOM.NLM appears to hang after running out of sessions if users continuously try to obtain an SPX session with Btrieve after exceeding the limit. The workstation receives either a status 95 (Session No Longer Valid) or a status 91 (Server Error). This situation occurs in both the NetWare Btrieve v5.x and NetWare Btrieve v6.0 environments. Once BSPXCOM.NLM hangs, Btrieve must be unloaded and reloaded.

To avoid this situation, apply the NetWare patch, SPXFIX1.NLM which is available on NetWire with the NetWare operating system patches (LIB 5, filename 311PT9.ZIP).

Creating Btrieve Quick Libraries for Visual Basic for DOS

When developing Btrieve applications using the Microsoft Visual Basic for DOS interpreter environment (VBDOS), you must create a Quick Library that includes the required Btrieve interface. To create this Quick Library, use the following link command:

Link /q BC7RBTRV.OBJ, BC7.QLB,, VBDOSQLB.LIB;

where BC7RBTRV.OBJ is the Btrieve interface, BC7.QLB is the name of the Quick Library, and VBDOSQLB.LIB is the name of the required library. To load the Visual Basic for DOS environment to include the newly created Quick Library execute the following command:

VBDOS /L BC7

Get Next Extended Operation after Get Key

If you use the GetKey bias (+50) when establishing positioning before a Get Next Extended (38) operation, the extended operation will not function properly, returning either a status 19 (Unrecoverable Error) or erroneous information in the databuffer. This situation occurs with Btrieve for DOS v5.10a and NetWare Btrieve v5.15.

Patch #57, available on Novell's NetWire forum on CompuServe (NOVLIB, LIB 7), resolves the situation for NetWare Btrieve v5.15. There is currently no patch for Btrieve for DOS v5.10a, so avoid using the GetKey bias before Get Next Extended operations. Instead, use a Get First (12), Get Equal (5), or some other operation to establish positioning without the +50 bias.

NetWare Btrieve & New Intel NE3200 Driver

File corruption can occur when you use Intel's NE3200.COM driver (09-03-91, 19242 bytes) in conjunction with Intel's EtherExpress 32bit card on workstations running Btrieve applications. Intel describes the situation as:

"... a problem with the Ether-Express 32 and applications that use extended memory or memory managers (i.e. MicroSoft Windows 3.x). Previous versions of this driver would not protect memory regions from the above mentioned applications. This could cause files that the EtherExpress 32 stored in memory to be overwritten (corrupted) if an application wrote to that address space."

Intel has a new NE3200.COM driver (date: 05-04-92, size: 25967) which fixes these problems through the use of the keyword "DOUBLE BUFFER" in the NET.CFG file. This driver is still in Beta and has not completed certification. This driver defaults to an 802.2 frame type; if you need a different frame type, include a "FRAME" statement in the NET.CFG file. Figure 5 contains a sample NET.CFG file. Note that this file requires the NE3200.COM driver to be in the same directory as itself.

FIGURE 5: Sample NET.CFG file for NE3200.COM driver LINK DRIVER NE3200 SLOT 5 DOUBLE BUFFER FRAME ETHERNET_802.3 PROTOCOL IPX 0 ETHERNET_802.3 PROTOCOL IPX BIND NE3200 END of FIGURE 5

Correct Usage of Btrieve Operation 42

The new NetWare Btrieve v6.0 operation 42, used to place Btrieve files into Continuous Operation mode (and return them to normal mode), can only be called from an NLM application. It cannot be called from a workstation application. If a workstation attempts to perform a Btrieve operation 42, NetWare Btrieve v6.0 returns a status 20 (Btrieve Not Loaded). NetWare Btrieve v5.x will return a status 1 (Invalid Operation).

Brequest v6.0 /L Option

In Brequest v6.0x, an new undocumented load option, /L, allows you to load another instance of Brequest even if Brequest is already loaded. This option is useful if you want to run Windows applications utilizing the Btrieve requester while running DOS VM applications that use Brequest.

To run Windows applications that use the Btrieve requester, Brequest must be loaded before starting Windows. In order to run DOS applications in Windows, Brequest must be loaded in each DOS session. However, if Brequest is loaded outside of Windows, it cannot be loaded again in a DOS session.

For Windows applications utilizing the Btrieve requester, load Brequest outside of Windows. In each Windows DOS session that will be running a Btrieve application, load Brequest with the /L option. Doing so will load another instance of Brequest that is only available to the DOS session. Doing so provides the DOS session with its own copy of Brequest and prevents the DOS session from using the instance of Brequest that was loaded before Windows was started.

File Level Access with Brequest v5.16 & v6.0

With Brequest v5.16, users are allowed to write to a Btrieve file if the user has "Write" access to the directory, even if the user does not have "Write" access to the file.

This situation does not occur with Brequest v6.0, since Brequest v6.0 uses file-level access rather than directory- level access. If a user has "RWCEMFA" access to a directory but only "RF" (read and file scan) access to a file, Brequest v6.0 returns a status 94 (Permission Error) on the Open operation.

"Supervisor" access to a directory works differently. If a user has "Supervisor" access, any file can be opened regardless of which requester is in use. "Supervisor" rights override all inherited rights masks in subdirectories and files.

Btrieve Programmer's Manual Correction

The Btrieve Programmer's Manual for the v6.0 SDK incorrectly documents the Filter Portion for the Get Next Extended (36) operation, Get Previous Extended (37) operation, and Step Next Extended (operation 38) operations.

On page 4-69 and 4-83 the Get Next Extended and Get Previous Extended operation Filters are documented as:

1 Byte Data type of field 2 Byte Length of field 1 Byte Comparison code

On page 4-131, the Step Next Extended operation Filter is documented as:

1 Byte Data type of field 2 Byte Offset of field 1 Byte Comparison code

Each of the extended retrieval operations should specify a filter as on page 4-141 for the Step Previous Extended operation Filter:

1 Byte Data type of field 2 Byte Length of field 2 Byte Offset of field 1 Byte Comparison code

Matching Btrieve Requester and DLLs

Btrieve can return status 97 (Data Message Too Small) on Create operations with a Windows application if improper versions of the Btrieve Requesters and DLLs are used. However, this status code will not be returned at all workstations; some workstations will run the application without problems.

This situation results from leaving different versions of WBTRCALL.DLL in directories or having an inappropriate DLL in the default drive. If you have several DLLs in your path statement, Windows will search for DLLs in the following order:

• Application-specific directory specified in an INI file
• Current directory
• Windows directory (e.g. C:\win31)
• Windows system directory (e.g., C:\win31\system)
• Application directory (i.e., path from which the program is retrieved (only Windows v3.1))
• Directories specified in path
• Mapped network directories

Open Btrieve Files & Non-Btrieve Apps

If Btrieve v6.0 opens files, they can still be accessed by a non-Btrieve application (like a DOS v5.0 COPY) without generating a Sharing Violation error. This situation does not arise with pre-6.0 versions of Btrieve and is not the result of a bug.

BTRIEVE.NLM v6.0 opens files differently than earlier versions of Btrieve. With Btrieve v6.0, files are first opened in Shared Read mode by the foreground process and, when data is written to the files, they are reopened by the Background Writer in exclusive Write, Shared Read mode. Versions of Btrieve before v6.0 opened the files with one exclusive Read/Write handle.

If you use BTRIEVE.NLM v5.x, the following scenario applies:

• Backups fail if the Btrieve file is open.
• A Sharing Violation Error is returned on any attempt to use a non-Btrieve application to open a Btrieve file that is already opened by Btrieve v5.x.

• Make sure all the Btrieve files are closed before running the backup.
• Use Continuous Operations.
• Use a backup utility that opens the files in exclusive write mode. Even though the backup utility is only going to read from the file, it has to open the file in a mode that will prevent other processes from writing to it. Exclusive Write mode guarantees this. Make sure the backup utility can get exclusive rights to the file.

When using the NetWare Btrieve NLM v5.15, a status 96 (Communications Environment Error) means that the SPX connection table is full. This status can usually be prevented by increasing the Number of Sessions configuration option through BSETUP. However, Windows workstations that run multiple Btrieve applications simultaneously require more than one session per workstation. In this case, NetWare Btrieve can return a status 96 when the Number of Sessions is set to the maximum of 250 and BCONSOLE shows only 225 sessions being used. BCONSOLE only shows one session per Windows workstation even if multiple Btrieve applications are running on that workstation.

The June 1990 Bullets article, "Btrieve NLM Parameters," shows that the maximum setting for the Btrieve "-s" (number of sessions) parameter is 500. This number is twice the maximum setting for the BSPXCOM "-s" (number of concurrent sessions) parameter. In reality, the Btrieve "-s" parameter can be increased even more to prevent a status 96 when using Windows workstations. The Btrieve "-s" parameter can be modified in the BSTART.NCF file. The maximum setting is approximately 35,000, and the memory consumption is approximately 100 bytes for each session. After making any changes to BSTART.NCF, be sure to unload the Btrieve NLM (type "BSTOP" at the server console) and reload the Btrieve NLM (type "BSTART") for the changes to take effect.

Configuring NetWare Lite for Btrieve

With NetWare Lite, there are two ways to access files from the server while ensuring you are using the same drive letter that the other clients are using. One method is to execute a "DOS SUBST" command at the server. For example:

SUBST F: C:\

After executing this command, when you access the F: drive, the files actually being accessed are at the root of the C: drive. This command can be performed from the command line or inside a batch file. This can be done before or after loading the server/client software. The clients will then NET MAP their F: drives to the root of the server, and will be looking at the same files as the server.

In this situation, all I/O requests sent from the server for files are being handled by DOS and NOT the NetWare Lite redirector (the CLIENT.EXE software). As a result, NetWare Lite file sharing mechanisms are not being used, which may produce a Btrieve status 2 (I/O Error), or situations where incorrect data is returned to the application. For example, while the server was inserting data into a Btrieve file, and another client was attempting to read this data, the other client would occasionally be returned a partial record, as if it was reading the record that was still in the process of being inserted.

To make sure all file sharing is handled properly by the NetWare Lite redirector, there are two alternatives:

• Avoid using the SUBST command. After loading SERVER.EXE and CLIENT.EXE at the server, use the NET MAP command to set up the drive letter to match the other clients. This is the preferred method in this case.
• Use the SUBST command as described above, but insert the statement "NETWORK SHARING=ON" in NET.CFG in the server's \NWLITE directory. This solution produces side effects which make it less preferable: if network sharing is enabled this way, Windows v3.x cannot run on the server, and the server will not be able to attach any CDROM devices as shared devices. Attempting either of these will produce errors in opening files at the server.

If a Btrieve data file is flagged "read-only," performing an Open operation on the file with NetWare Btrieve (NLM) v5.15 will return a status 94 (Permission Error). This status will return even if the user has all rights in the directory and the file is opened in "read-only" mode through Btrieve.

When using NetWare Btrieve (NLM) v5.15, do not flag Btrieve data files "RO." To prevent "write" access to the files, use directory level rights of Read and File Scan.

With NetWare Btrieve (NLM) v6.x, the status 94 will not be returned if the file is flagged "RO." A "read-only" Open operation on the file will succeed, while a status 46 (Access to File Denied) will be returned when a user attempts to write to the file.

Calling Btrieve from 32-bit Applications (Btrieve for OS/2 v5.10)

The current Btrieve for OS/2 engine, v5.10, is a 16-bit DLL. In order to access this DLL from a 32-bit OS/2 application, the Btrieve entry points have to be "thunked." Some aspects of this process depend on which compiler you use. Figure 6 illustrates the process when using Borland's 32-bit OS/2 compiler. Figure 7 demonstrates the process for IBM's C-Set/2 OS/2 compiler.

FIGURE 6: "Thunking" Btrieve entry points with Borland's 32-bit OS/2 compiler #include ... #define FPSZ char __far16 * /* Far pointer to null-terminated string */ #define FPUSHORT USHORT __far16 * /* Far pointer to unsigned short */ extern USHORT __far16 __pascal BRQSHELLINIT (FPSZ); extern USHORT __far16 __pascal BTRVINIT (FPSZ); extern USHORT __far16 __pascal BTRVSTOP (void); extern USHORT __far16 __pascal BTRCALL (USHORT, FPSZ, FPSZ, FPUSHORT, FPSZ, BYTE, CHAR);

USHORT BTRV (USHORT, PSZ, PSZ, PUSHORT, PSZ, SHORT); void main() { . . . } /* Borland C++ interface to the Btrieve OS/2 dynamic link library */ USHORT BTRV (USHORT operation, PSZ posblock, PSZ databuf, PUSHORT datalen, PSZ keybuf, SHORT keynum) { BYTE keylen = 255; CHAR ckeynum = keynum;

return (BTRCALL (operation, posblock, databuf, datalen, keybuf, keylen, ckeynum)); } END of FIGURE 6

FIGURE 7: "Thunking" Btrieve entry points with the C-Set/2 32-bit OS/2 compiler #include ... extern USHORT _Far16 _Pascal BTRCALL (USHORT, PSZ, PSZ, PUSHORT, PSZ, BYTE, CHAR); extern USHORT _Far16 _Pascal BTRVINIT (PSZ); extern USHORT _Far16 _Pascal BTRVSTOP (void); extern USHORT _Far16 _Pascal BRQSHELLINIT (PSZ); USHORT BTRV(USHORT, PSZ, PSZ, PUSHORT, PSZ, SHORT); main() { . . . } /* IBM C-Set/2 interface to Btrieve OS/2 DLL */ USHORT BTRV (USHORT operation, PSZ posblock, PSZ databuf, SHORT datalen, PSZ keybuf, SHORT keynum) { BYTE keylen = 255; CHAR ckeynum = keynum;

return (BTRCALL (operation, posblock, databuf, datalen, keybuf, keylen, ckeynum)); } END of FIGURE 7

Defining UPPER.ALT ACS with Microsoft PDS BASIC v7.x

Using PDS BASIC 7.X, if you want to define an alternate collating sequence to a particular key, then in the Btrieve Create operation, you must allocate 265 bytes at the end of the File Specification structure after all of the file and key specifications variables. The code segment in Figure 8 demonstrates one method for performing this allocation.

FIGURE 8: Defining UPPER.ALT alternate collating sequence with PDS BASIC v7.x DEFINT A-Z REM **** GLOBAL CONSTANTS Const BCreate = 14 Const BString = 0 Const Duplicates = 1 Const Modifiable = 2 Const Sequence = 32 Const ExtendedType = 256 TYPE KeySpec KeyPos AS INTEGER KeyLen AS INTEGER KeyFlags AS INTEGER KeyTot AS LONG KeyType AS STRING * 1 Reserved AS STRING * 5 END TYPE TYPE FileSpec RecLen AS INTEGER PageSize AS INTEGER IndxCnt AS INTEGER NotUsed AS STRING * 4 FileFlags AS INTEGER Reserved AS STRING * 2 Allocation AS INTEGER KeyBuf AS KeySpec AltColSeq AS STRING * 265 END TYPE DIM FileBuf AS FileSpec FileName$ = "SAMPLE.BTR " PosBlk$ = SPACE$(128) REM ************* SET UP FILE SPECS ************* FileBuf.RecLen = 20 FileBuf.PageSize = 1024 FileBuf.IndxCnt = 1 FileBuf.FileFlags = 0

REM ************* SET UP KEY SPECS *************** FileBuf.KeyBuf(0).KeyPos = 1 FileBuf.KeyBuf(0).KeyLen = 20 FileBuf.KeyBuf(0).KeyFlags = ExtendedType + Modifiable + Duplicates + Sequence FileBuf.KeyBuf(0).KeyType = MKI$(BString) REM **** COPY 265 BYTES OF UPPER.ALT TO STRUCTURE VARIABLE OPEN "UPPER.ALT" FOR BINARY AS #1 LEN = 265 GET #1,1,FileBuf.AltColSeq CLOSE #1 BufLen = LEN(FileBuf) CALL BTRVFAR(BCreate, STATUS, PosBlk$, VARPTR(FileBuf), VARSEG(FileBuf), BufLen, FileName$, 0) IF STATUS <> 0 THEN PRINT"Error Creating File. Status = ";STATUS%;" Press a key to continue" DO LOOP WHILE INKEY$="" END ELSE PRINT"File SAMPLE.BTR Created Successfully!" END IF END END of FIGURE 8

BTRIEVE.NLM & ELRDFX.NLM

NetWare v3.11 server performance degrades severely or hangs during heavy read/write Btrieve operations. This issue has been resolved with the NetWare patch, ELRDFX.NLM. This patch was previously provided in the NetWare v3.11 patch kit (311PTx), but has been removed to call attention to the fact that if VREPAIR is run while this patch is loaded, data corruption can result. The patch is now available on NetWire in the NSD area (ELRDFX.ZIP).

There is also a third-party companion NLM called ELRDCK.NLM that can be found in NOVLIB, LIB16, in the file ELRDCK.ZIP. If this NLM is loaded, it will issue a warning and sound a beep if there is an attempt to run VREPAIR with ELRDFX loaded.

Set Directory Operation Fails To Change Drive

After a Btrieve Set Directory (17) operation is issued to change the current drive and directory, the current directory is left unchanged.

The Set Directory (17) operation is documented as having the ability to change the current drive and directory at the same time in one call. With all 5.x versions of client Btrieve and all versions of NetWare Btrieve through v6.10, Set Directory does not function as documented. If you attempt to change the drive and directory to a drive and directory other than the current one, a status 0 (Successful) is returned, but the current drive and directory will be left unchanged. The operation functions correctly if there is no attempt to change the current drive, but only the current directory.

To change the current drive and directory with the Set Directory operation, you must call the operation twice. First, issue the function only specifying the DRIVE:. Doing so will change the current drive to the drive specified on the call. Then, issue the Set Directory operation once again specifying the desired path.

Btrieve v5.x Status 109 (Transaction Too Complex)

NetWare Btrieve (NLM) v5.15 (patches applied only through #93) may return a status 18 (Disk Full) within an explicit Begin Transaction loop if the preimage file grows larger than 32 MB. When the preimage file exceeds 32MB, the Btrieve file is corrupted.

The latest set of patches for NetWare Btrieve (NLM) v5.15 introduces a new status code, status 109 (Transaction Too Complex) added by patch #95. This status code was created to compensate for applications inserting large numbers of records into their files while inside an explicit Begin Transaction loop and receiving status 18s.

The status 18 is returned because NetWare Btrieve uses a two-byte or 16-bit counter for pages in the preimage file. This counter has now been changed to allow a preimage file of 64 MB to be created before the new error 109 is returned. When the error occurs, the application may either end or abort the transaction without file corruption. Operations on other Btrieve files (not the file whose preimage file has exceeded 64 MB) can still be performed successfully.

New Btrieve Status 130 (Ran Out Of System Locks)

NetWare Btrieve (NLM) v6.x may abend or otherwise malfunction if it runs out of system locks. Beginning with patch release v6.10b (scheduled for release September '93), NetWare Btrieve will return a new status code, 130 (Ran Out of System Locks).

With any version of Btrieve before v6.10b, the abend may occur when NetWare Btrieve runs out of system locks and either the system is under heavy use, or a certain combination of start-up parameters are used. The September patch release will ensure that NetWare Btrieve monitors its supply of system locks and returns a status 130 to applications trying to perform operations requiring system locks if none are available.

NetWare Btrieve uses system locks to lock pages in v6.x files that are changed during Insert, Update and Delete operations. These locks are held for the duration of the operation or until the transaction, if any, ends or aborts.

The number of system locks Btrieve can use depends on two of its start-up parameters:

LocksPerClient ("Number of Locks" in BSETUP, "l" on the BTRIEVE.NLM command line) and MaxClients (not directly set by BSETUP, "s" on the BTRIEVE.NLM command line -not the BSPXCOM.NLM command line). The maximum number of system locks Btrieve can allocate is: #systemLocks = 65,536 - ( l * s ).

The higher the values for "s" and "l," the fewer system locks are available. This pool of system locks is shared by all users. Two factors cause heavy usage of system locks and increase the likelihood of generating a status 130:

1. A very large transaction (e.g., thousands of records inserted),
2. Many users performing large transactions concurrently.

If you are in a transaction and receive a status 130, you should end or abort the transaction. You could then retry the operation; other users may have exhausted NetWare Btrieve's system locks and may have ended or aborted their transactions.

NetWare Btrieve v5.x Step Operations

With NetWare Btrieve v5.x, the Step Next and Step Previous operations can skip over records if all the bytes in the record except the first four are set to binary zero, and the first four bytes are either all binary zero or -1 (0xff). Other patterns may also be found in the first four bytes. Btrieve identifies records with these patterns as deleted records and skips them.

This situation only occurs if Btrieve 6.x or 5.x engines are used with files in 5.x format; it does not occur with NetWare Btrieve v6.x files.

Converting the NetWare Btrieve files from v5.x to v6.x format will resolve the situation. If, however, you wish to leave the files in NetWare Btrieve v5.x format, there are three possible workarounds:

• Alter your program to devote at least one byte (beyond the fourth byte) in the record to hold a non-zero value.
• Create the Btrieve file using the compression option.
• Create the Btrieve file using the variable-length record option.

If two separate files have different alternate collating sequences (ACSs) but the two sequences have the same name, status 4 may be returned when you attempt an UPDATE or DELETE operation. Btrieve will not read an alternate collating sequence into memory if one with the same name is already in memory. Thus, if a user is working with one file and then switches to work with the other file, the ACS associated with the latter file will not load, resulting in an improper sorting of the keys.

When using different ACSs for separate files, make sure that the names for each ACS are different.

Status 36 on Begin Transaction

If a workstation running a Btrieve application call Begin Transaction (19) with BREQUEST.EXE loaded, Btrieve may return a status 36 (Transaction Error). To prevent the status 36, all servers to which the workstation is attached and that are running Btrieve must have the Btrieve NLM configured for transactions.

In addition, if the workstation is configured for local and requester access, a Begin Transaction operation will also fail with a status 36 if the client (local) copy of Btrieve is not configured for transactions as well. This is true even if no local data file has been or will be accessed.

To prevent the status 36 from being returned on a workstation configured for both client and requester access, also configure the local engine for transactions. To accomplish this in the DOS environment, load BTRIEVE.EXE with /t:.In the Microsoft Windows environment, specify options= /t: in the WIN.INI file's [btrieve] paragraph.

If no local data files will be accessed, you can also resolve the situation in the DOS environment by not loading BTRIEVE.EXE or in the Microsoft Windows environment specifying local=no in the [brequestDPMI] paragraph of NOVDB.INI.

Using BASIC FIELD statements with Btrieve for Windows

FIELD statements may be used with Microsoft QuickBasic to initialize the random file buffer area for subsequent Btrieve calls. However when assigning values to these data areas with the LET assignment statement, the record's data is not inserted on the Btrieve Insert call. Instead, garbage characters are inserted.

Do not use LET or INPUT statements to assign values to FIELD variables. Instead, use the LSET or RSET operator. Once a variable name is fielded, it points to the correct place in the random file buffer. If a subsequent INPUT or LET statement with that variable name is executed, the variable's pointer is moved to string space, therefore no longer pointing to the random file buffer.

LSET left justifies the string and pads with blanks to the indicated FIELD length. RSET right justifies the string and pads with blanks to the indicated FIELD length. FIELD statements work only with string variables.

Changing Btrieve 5.10a Interrupt (Btrieve for DOS v5.10a)

When you attempt to change the 7b interrupt which is used by Btrieve, you will discover more than one occurrence of it. For this reason, you must be careful which address you change: the first address should not be edited, while the third address should. The "25h-7bh" found in the first address are just bytes in the offset to another call, and only coincidentally contain these values.

Under Btrieve for DOS v5.10x, change the code as shown in Figure 15.

FIGURE 15: Changing Btrieve v5.10a interrupt ren btrieve.exe btrieve debug btrieve -r ;get the value of the cx register. -s 0L[cx] 7b 25 ;search for "set interrupt" where [cx] is value ;of cx register obtained above. ; ;the search returns THREE addresses ssss:zzzz ;DO NOT EDIT THE FIRST ADDRESS !!! ssss:xxxx ; ssss:yyyy ; ; -e ssss:xxxx ;edit first address to change interrupt ssss:xxxx 7b. ;address one is returned showing value of 7b. ;Prompt is waiting for the new interrupt value. __ ;Enter the value of the new interrupt. -e ssss:yyyy ;edit second address to change interrupt ssss:yyyy 7b. ;address two is returned showing value of 7b. ;Prompt is waiting for the new interrupt value. __ ;Enter the value of the new interrupt. -s 0L[cx] 7b 35 ;search for "check interrupt" where [cx] is value ;of cx register obtained above. ssss:xxxx ;the search returns ONE address -e ssss:xxxx ;edit that address to change interrupt ssss:xxxx 7b. ;that address is returned showing value of 7b. ;Prompt is waiting for the new interrupt value. __ ;Enter the value of the new interrupt. -w ;write changes to disk -q ;quit debug ren btrieve btrieve.exe END of FIGURE 15

Microsoft QuickBasic & Btrieve Status 76

Btrieve applications compiled with Microsoft QuickBasic may return a BASIC run-time error 76 (Path Not Found) when run on peer-to-peer networks. The error occurs when executing the OPEN "NUL" statement in applications that use fielded variables rather than type structures.

To resolve this error, change each OPEN "NUL" statement to:

OPEN "\DEV\NUL".

By default, Microsoft QuickBasic appends path names to files opened with the OPEN statement. The \DEV\ added to the OPEN statement prevents Microsoft QuickBasic from assigning a file path to the device and enables the statement to succeed.

Btrieve Overwrites Key Buffer with Status 22

Btrieve will overwrite the Key Buffer parameter on a Get Equal (5) operation if a status 22 (Data Buffer Length Too Short) is returned. NetWare Btrieve (NLM) v6.x and the Btrieve v5.x client versions overwrite the Key Buffer parameter with extraneous characters on a Get Equal (5) operation if a status 22 (Data Buffer Length Too Short) is returned from the call. This situation occurs only if the data buffer length specified is less than the offset and length of the key specified in the Key Number parameter.

This situation occurs because the return key value is extracted from the data buffer itself. An incomplete Data Buffer results in an incomplete (thus invalid) key value.

Status 22 is an informative status code indicating that there is more data in the record than Btrieve was able to return. When using variable-length records, many developers intentionally set the Data Buffer Length parameter to a number that is less than needed to return the entire record. Doing so can improve performance by preventing a variable- page read when only the fixed-length data is needed. This is an acceptable method of data retrieval. The Key Buffer overwrite problem described above only occurs if the Data Buffer Length parameter specified is shorter than the fixed- length portion of the record, and specifically the offset of the key specified in the Key Number parameter.

Loading Brequest from Login Scripts

When loading BREQUEST.EXE from a NetWare login script, the TSR fragments memory, so it appears to take 200K of space. This memory loss is attributed to the fact that the LOGIN program is still in memory when the TSR is loaded. It gets trapped between whatever was in memory prior to logging in (most likely the network shell) and the newly loaded TSR.

To avoid this situation, do not load TSRs from login scripts. If you need to load any TSRs at login time, use the "EXIT" statement in a login script to call a DOS batch file. Batch files can load the TSRs without this memory penalty.

Ensuring Btrieve Transaction Recovery (Btrieve for DOS v5.10a)

The documentation for Btrieve for DOS v5.10a states that, when using Btrieve in a networked environment, all users who start Btrieve with a "/T" option should specify the same physical location for the transaction control file. This rule ensures that, when a data file is shared by two workstations, both of the stations will be able to recover from a server failure during an End Transaction (20) operation, regardless of which station is recovered first.

This rule should be applied, but it is not foolproof. The full logical path of the data files used in a transaction are stored in the transaction control file. If the first station to start Btrieve after a server failure does not have the same logical mappings to the files as the station that was processing an End Transaction operation during server failure, Btrieve will not be able to access the files described in the transaction file and will report the error "Unable to access Btrieve file for transaction recovery."

To insure transaction recovery after a server failure, all stations should share the same transaction file (/T), and should also access the data files with the same logical mappings.

IBM LAN Server Reports Sharing Violation with Btrieve

IBM LAN Server reports a "Sharing Violation" when an application issues a Close (1) operation on a Btrieve file if at least two stations have a data file open and have both modified the data file.

The error occurs when Btrieve for DOS performs its Close test to determine if it is the last instance accessing the data file. During the Close operation, Btrieve tries to open the preimage file in exclusive mode. If the Open operation succeeds, then Btrieve knows that this is the last handle to the data file and can erase the preimage file. Unlike DOS, LAN Server interprets this test as a critical error.

To prevent this "Sharing Violation" error from occurring, load Btrieve with a "/O." This load parameter tells Btrieve to override the critical error handler so that Btrieve handles critical errors instead of the operating system.

Btrieve Clients & SHARE.EXE

SHARE.EXE needs to be loaded on Btrieve for DOS and Btrieve for Windows client workstations under the following conditions:

• If your application accesses the files that reside on your hard disk and applies any record locks, whether single or multiple.
• If your application uses multiple cursors (multiple position blocks) to access the same file on the hard disk.

SHARE, by default, allows up to 20 concurrent locks. To increase locks, use the SHARE "L" command line parameter. The "F" parameter may have to be used to make SHARE allocate more work space if many files are locked, or if the files are in "deep" subdirectories, (for example, c:\path1\path2...\path6\FILE.EXT).

Btrieve NLM Allows Duplicate Records

Btrieve NLM v6.10b will insert duplicate records into a Btrieve v5.x format file under the following circumstances:

• If each page holds only one record
• If the Btrieve file is in v5.x format
• If an Insert operation returns a status 5 (Duplicate Key Value), and then a subsequent Insert is successful.

To avoid this situation, rebuild files in Btrieve v6.x format or use a page size that can hold more than one record.

NetWare Btrieve in Primary I/O Engine

With Btrieve v6.10b, BROUTER and BTRVSTUB.NLM are provided to allow NetWare SFTIII users to run Btrieve from the I/O engine. These components do not work if run from the Primary I/O engine. However, they do work if they are run in the Secondary I/O engine. Only run Brouter/Btrvstub in the Secondary I/O engine.

When Does Btrieve Delete Delta Files?

With Btrieve NLM 6.10b, Delta files are deleted as soon as the End Continuous Operations command is executed. Upon executing this operation, Btrieve writes the updates from the Delta files to the corresponding Btrieve files and deletes the Delta files.

Versions of Btrieve before v6.10b delete Delta files created during continuous operations after the last user closes the corresponding Btrieve files. When End Continuous Operations is executed, updates are made to the Btrieve files and the size of the Delta files is changed to zero.However, the Delta files are not deleted until the last user closes the actual Btrieve files.

Ascending Order & Autoincrement Keys

Btrieve returns a status 5 (Duplicate Key Value) when you attempt to insert a record with an autoincrement field value of zero. Btrieve returns this status code when the autoincrement key has the descending attribute set. Then, when the insert is executed, Btrieve finds the highest value for the autoincrement key equal to "1" and increments it by one to get "2." Since the value "2" already exists in the file, Btrieve returns the duplicate key value error.

Autoincrement keys should always be defined as Ascending.

Status 95 & NetWare SFT III

When the primary NetWare SFT III server is disabled and resynchronization is taking place, Btrieve may return a status 95 (Session not valid) while NetWare SQL may return status 2103 (NetWare SQL is not active on the requested server).

To prevent these status messages, increase the "IPX Retry Count" parameter in NET.CFG to a value of 40 or more. Raising this parameter prevents workstations from timing out and NetWare from terminating their IPX connections. In addition, always use the latest VLM drivers, (see "Current Shell and Requester Versions).

Null Key Path & Status 44

With pre-6.x versions of Btrieve, the record manager returns a status 82 (Lost Postioning) when you attempt to perform a Get Direct (23) operation on a key with a null value in the record at the provided position. NetWare Btrieve v6.10b and v6.10c may return a status 44 (Null Key Path), instead.

Status 44 can occur when you define the key attribute to be manual or null ("all-segment" and "any-segment"). If your existing Btrieve application checks for status 82, consider rewriting your Btrieve application to check for status 44, as well.

New Btrieve NLM Configuration Option for 6.10x

NetWare Btrieve v6.10x includes a new configuration option: "Perform Index Balancing." Index balancing results in Btrieve files that have more entries on individual key pages, increasing access time. However, it may decrease performance on Insert, Update and Delete operations due to the extra work required to balance the indexes.

The NetWare Btrieve v6.10 Setup Utility (BSETUP.NLM) allows you to set this option if you want all newly created files to have balanced indexes.

However, the Btrieve configuration option of the NetWare SQL Setup Utility (NDBSETUP.NLM) does not include this new option. NetWare SQL should use BSETUP to configure Btrieve rather than NDBSETUP to enable the Index Balancing option.

Configuring Btrieve for Windows

Any configurations or initialization parameters for WBTRCALL.DLL v5.10 and WBTRLOCL.DLL must be set in WIN.INI. Although NOVDB.INI file contains a section for Btrieve, this configuration is never used by Btrieve for Windows.

Using Visual Basic Controls with Btrieve

When using data-aware controls in a Visual Basic application with Btrieve for Windows, Visual Basic uses a file called BTRV110.DLL. A section of the VB.INI file tells Visual Basic where to find this file, for example:

Using Visual Basic Controls with Btrieve (Btrieve for Windows v5.10)

When using data-aware controls in a Visual Basic application with Btrieve for Windows, Visual Basic uses a file called BTRV110.DLL. A section of the VB.INI file tells Visual Basic where to find this file, for example:

[Installable ISAMs]
btrieve=c:\windows\system\btrv110.dll

This section in the VB.INI file is only used when running the application in the Visual Basic development environment. When compiling the application into an executable file and running it outside the Visual Basic environment, the following error may be returned:

Couldn't find installable ISAM

When running the executable, an .INI file with the same name as the executable must exist in the Windows directory, and it must contain a section pointing to the BTRV110.DLL, just like the entry in VB.INI. For example, if the application is called BTRDATA.EXE, a BTRDATA.INI file must exist in the Windows directory with the appropriate [Installable ISAMs] section.

Data Buffer Length & Get Next Extended

The documentation for NetWare Btrieve v6.x states that the length of the Data Buffer should be set to:

max(sizeof(in-going structure),sizeof(out-going structure))

This description refers to the Data Buffer Length parameter sent on the Btrieve call, not the first two bytes of the descriptor in the Data Buffer.

Set the first two bytes of the descriptor in the Data Buffer to the exact length of the in-going structure. Set the Data Buffer Length parameter to the larger of the in-going structure length and the out-going structure length.

UC Option on Btrieve Extended Operations

Btrieve v5.1x and above now support the UC option on the Get Next Extended (36) and Get Previous Extended (37) operations. This option tells Btrieve to begin searching for records that match the provided filter (if defined) with the current record instead of the Next/Previous record. The application still must establish positioning with a Get First (12), Get Equal (5) or some other operation before using this option in the extended call.

UC functionality is automatically provided in the 5.15 and 6.x versions of the NetWare Btrieve NLM. All other current versions of Btrieve must be patched in order for the UC option to be functional, including:

• NetWare Btrieve VAP (BSERVER.VAP v5.15),
• Btrieve for DOS (BTRIEVE.EXE v5.10a)
• Btrieve for MS Windows (WBTRCALL.DLL v5.10)
• Btrieve for OS/2 (BTRCALLS.DLL v5.10)

The UC functionality is also available with the Step Next Extended (38) and Step Previous Extended (39) operations, but only with the Btrieve NLM (v5.15 and all 6.x versions). The UC option can not be used on the Extended Step operations when using the client versions of Btrieve or the Btrieve VAP. Any attempt to do so will return a successful status code, but no records will be returned in the data buffer.

NetWare OS/2 Requester Produces Status 95

NETX must be loaded and the LOGIN process must be executed in every Private DOS session. Even though the MAP command may display drive mappings, those resources actually are not available to the DOS session. Use the LOGIN command to allocate resources to the DOS box. Otherwise, a Btrieve status 95 (Session No Longer Valid) may be returned if you use a Private DOS box with OS/2 v2.1 and the NetWare OS/2 requester v2.01.

When using Private DOS sessions with the 2.01 version of the NetWare OS/2 requester and the Btrieve OS/2 requester v6.1x, always verify that NETX is loaded and that the LOGIN procedure described above has been followed.

Erroneous Status 82s and 2s (Btrieve for DOS 5.10a)

When a user attempts to read a Btrieve file that is being modified, the file may actually be busy. This situation may result in the read operation receiving incomplete data, causing an erroneous status 82 (Lost Position) or status 2 (I/O Error).

Currently, there is no solution for the client Btrieve engines, except to retry the operation. The status messages are in error and disappear when the write operation completes. The status messages result from a timing window problem.

No erroneous status is returned when using transactions. Also, this situation does not exist with the Btrieve NLM or VAP, since only one engine handles the writes and reads for all users.

Establishing Multiple Btrieve Sessions Triggers Status 91

Versions of NetWare Btrieve prior to v6.10c may return a status 91 (Server Error) if many users attempt to establish a session simultaneously.

NetWare Btrieve returns this status because BSPXCOM.NLM has posted only one Listen-For-Connection Event Control Block (ECB). BSPXCOM.NLM v6.10b, which is included with NetWare Btrieve v6.10c, now posts five Listen-For-Connection ECBs for establishing sessions with workstations.

NetWare Btrieve v6.10c is available for downloading from Novell's NOVLIB forum on CompuServe (Library 7, BTR61.EXE), or from Novell Developer Support.

Synchronize logging and continuous ops