Introduction to the NetWare Btrieve RECPLAY Utility

Novell's Btrieve Developer's Kits contain tools such as BUTIL and BTRTOOLS to make Btrieve application development a smoother process. Additional tools and toolsets are also available to developers and network administrators through Novell Developer Support and Novell's NOVLIB forum on CompuServe (Library 7, BTOOLS.EXE) for troubleshooting Btrieve applications. This article provides an introduction to one of these toolsets, RECPLAY.

RECPLAY gives developers and system administrators a specialized set of tools for troubleshooting NetWare Btrieve v6.x applications. Specifically, RECPLAY allows you to:

Isolate Btrieve or NetWare SQL problems by looking at the sequence of Btrieve operations that take place before the failure.
Isolate network and hardware related issues by replaying the history file on a different file server or network.
Resolve timing related problems and facilitate testing and debugging by replaying the history file.
Isolate performance issues by recording the start and end time of every operation. This allows the user to recognize which Btrieve operations take longer to execute.

RECPLAY contains four separate tools:

BRECORD.NLM
DUMPTR.EXE
CRDUMP.EXE
BREPLAY.NLM

This article provides a general description of each tool in the RECPLAY toolset and how they can be used together. Specific details on the various options available for each tool are documented in a text file that is supplied with the RECPLAY toolset.

General Usage

In some environments, it is useful to see what Btrieve calls are being made by an application. For example, NetWare SQL users may wish to find out which Btrieve calls are made as a result of running a particular SQL statement. To record Btrieve calls for viewing:

Load BRECORD at the file server.
Run the application.
Unload BRECORD.
Run the DUMPTR utility on a DOS workstation.

For debugging purposes, it may be helpful to record Btrieve calls and then replay the calls on the same or a different server. To do this:

Load BRECORD at the file server.
Run the application.
Unload BRECORD.
Run DUMPTR to create a script file out of the history file that was created by BRECORD. You may make modifications to the script file if you wish.
Run CRDUMP to convert the script file to a binary file. This step is unnecessary if you did not make any changes to the script file created in step 4.
Load BREPLAY and specify the binary file from either:
- Step 5, if you have made changes to the script file, or
- Step 1, if you simply want to replay exactly what your application did.

Tool Usage: BRECORD.NLM

BRECORD.NLM records all Btrieve calls into a history file. Any workstation executable or other NLM can make these calls. BRECORD.NLM can be configured to only record the calls for specific Btrieve files or all files.

BRECORD.NLM creates the history file immediately after you load it. However, it will be 0 (zero) bytes in size until BRECORD is unloaded. This history file is stored in binary format and can be viewed with the DUMPTR utility.

BTRIEVE.NLM v6.x must be loaded before you can run BRECORD.NLM.

The following command will record all Btrieve operations made to a file called PATIENT.DTA located in SYS:\DATA into a binary file called BREC.DMP in the same directory. Btrieve will create BREC.DMP or overwrite it if it already exists in SYS:\DATA.

LOAD BRECORD /f=sys:\data\brec.dmp /n=sys:\data\patient.dta

Tool Usage: DUMPTR.EXE

DUMPTR.EXE is a DOS workstation utility that displays readable output from the history file to the screen. You can redirect this output to a file using the DOS redirection operator. DUMPTR.EXE also creates a script file which can be edited and formatted back to a new history file.

As an example, the command below will read the binary file BREC.DMP created by BRECORD.NLM and display all the Btrieve operations that were recorded, including the key and data buffer of each call. The resulting output will be redirected to the BREC.TXT file.

DUMPTR /f=\data\brec.dmp /k /s >brec.txt

Figure 3 shows an example of the output created by the previous DUMPTR command. The Btrieve operation being performed is shown in the "opcode" column, and the resulting status of this operation is listed in the "stat" column (0 indicates that the Open operation was successful). The "cursor ID" represents a handle to a file for operations that access a file (i.e., Open or Get Equal). This column will be blank for non-file operations such as Version or Reset. The cursor ID specified on the Open is used to identify the file on subsequent operations. For example, if you see a Get Equal on cursor ID 2, you will know it is reading the PATIENT.DTA file.

FIGURE 3: Example output file format redirected to BREC.TXT 

                                                         System
  opCode        stat cursor client ID  key    start t.  end time   exec.t.
                     ID                number       (0.1 ms)
------------------------------------------------------------------------
  Open           0   2      0200400a   0            24        63     39
key  buffer:41 55 53 2d 54 45 4b 33-31 31 2f 53 59 53 3a 44   SERVER10/SYS:...
            41 54 41 2f 50 41 54 49-45 4e 54 2e 44 41 54 00   DATA/PATIENT....
data buffer:00 00 00 00 00 00 00 00-00 56 00 da 84 56 00 00   .........V...V..
            00 57 00 84 20 00 00 00-00 00 00 00 00 00 00 00   .W..............
            00 00 00 00 00 00 00 00-00 00 00 00 00 00 00 00   ................

END of FIGURE 3

The "client ID" references the user who made the Btrieve call. All calls from the same user will have the same client ID. The "key number" column will show the key number used on the call, or will be blank for operations that do not use a key number.

The system times ("start t.," "end time," and "exec.t.") represent the system start time, end time, and execution time for that operation. In the example in Figure 3, the Open operation took 3.9 milliseconds.

The key buffer and data buffer information shows what is being sent in to Btrieve for the particular call. The buffers are shown both in hex and in ASCII. Again, these parameters will only show when appropriate. For example, the key buffer is required for an Open, Get Equal, Get Next, Create, etc. The data buffer is required for an Open, Get Next Extended, Get Direct, etc.

You can also enter a command to create a script file. The following command generates as scriptfile called, SCRIPT.TXT, and dumps the Btrieve operations recorded by BRECORD.NLM from BREC.DMP to this text file.

DUMPTR /f=\data\brec.dmp /r=script.txt

Tool Usage: CRDUMP.EXE

CRDUMP.EXE is a DOS workstation utility that formats a script file to a binary file. Script files created with DUMPTR.EXE can be edited for troubleshooting purposes and reformatted in binary format using CRDUMP.EXE. This binary file can be used by BREPLAY.NLM to re-execute all of the operations.

The following example command converts the script file, SCRIPT.TXT, created by the DUMPTR utility with the /r option, into a binary file that can be used by BREPLAY.NLM.

CRDUMP script.txt brec.fil

Tool Usage: BREPLAY.NLM

BREPLAY.NLM executes Btrieve calls previously recorded by BRECORD.NLM. To run BREPLAY.NLM, BTRIEVE.NLM v6.x must be loaded.

The following example command replays every operation that has been previously recorded by BRECORD.NLM or created from a script file with CRDUMP.EXE. It also writes a status report to a list file named BRECLST.OUT after every 200 operations are played.

LOAD BREPLAY /f=sys:\data\brec.dmp /p=200 /l=sys:\data\breclst.out

RECPLAY is an in-house utility made available to developers and network administrators as a courtesy. This utility is provided as is and it is not an official Novell product. Novell is not responsible for maintaining or enhancing this product.

For more information on this toolset, contact Novell at 1-800-NETWARE (1-800-638-9273) or 1-801-429-5588.