Troubleshooting¶

Tracing driver calls using the Mertech Trace Utility¶

The easiest method of enabling a trace is to use the Mertech Trace Utility, which is installed with BTR2SQL and available from the Windows Start menu under Mertech Data Systems.

The utility provides the following controls:

• Product — Select which Mertech driver product to configure. The dropdown lists all installed Mertech products (e.g., BTR2SQL for PostgreSQL v7, BTR2SQL for SQL Server v7, BTR2SQL for Oracle v7). The trace settings are stored per product.

• Enable Trace — Check this box to turn tracing on. Uncheck it to disable tracing. When unchecked, the remaining fields are ignored.

• Output — Choose where trace output is sent. File writes the trace to the path specified in the File field. Debug sends the trace output to the Windows debug output channel, which can be viewed with tools such as DebugView from Sysinternals.

• File / Browse — The full path and filename for the trace output file (e.g., c:\Temp\PGS_BTR_debug.tra). Use the Browse button to select a location. Only applicable when Output is set to File.

• Level — Controls the verbosity of the trace output. The available levels and their numeric equivalents are:

  • Errors Only (level -3) — Captures only error and warning messages. Look for lines preceded by ERROR: or WARNING: in the output.

  • Debug (level 0) — Shows the overall flow of your application’s database activity: transactions starting and ending, locks acquired and released, and records being read.

  • Detailed 1 (level 1) — Adds field values for records being read and written, along with Btrieve input and output buffers.

  • Detailed 2 (level 2) — The recommended level for active troubleshooting. Includes additional context beyond Detailed 1 to help isolate a specific problem.

  • Detailed 3 (level 3) — Maximum verbosity, including field values during inserts and index operations. This level generates very large trace files and may noticeably affect performance — use it only when requested by Mertech Technical Support.

Click Save to apply the settings. The trace takes effect the next time the driver is loaded (i.e., the next time your application starts or opens a Btrieve file). Click Close to exit the utility.

Tracing driver calls with environment variables¶

SET btr2sql_TRACE_ON=<TracefileName>

SET btr2sql_TRACE_LEVEL=<level>

NOTE: There are no spaces after the equals sign.

The environment variables must be active in the system before starting the application. You can add these two variables using the My Computer properties (Advanced tab, Environment Variables button). Or you can do this at a Command Prompt before starting the application.

Figure 30 Setting up a trace file at the command prompt

Tracing driver calls with registry settings¶

HKEY_CURRENT_USER\SOFTWARE\Mertech Data Systems\DB Drivers\BTR\\\ *driver*\\v5

where driver is one of Oracle Driver, SQL Server Driver, or PgSQL Driver

Add the string value TRACE_ON and set its value to the name of the trace file. Add another string value named TRACE_LEVEL with a number between -1 and 3. If the registry keys do not exist, you will need to create each key in the hierarchy before entering the values.

Figure 31 Setting up a trace file using the registry

NOTE: Settings can also be stored under HKEY_LOCAL_MACHINE

Tracing driver calls with mds_global.ini settings¶

The mds_global.ini file provides a persistent way to configure tracing. The key settings are:

• TRACE_ON — specifies the trace file path

• TRACE_LEVEL — controls the verbosity of trace output

• TRACE_FLUSH — determines whether trace data is flushed immediately

For a complete list of trace-related settings, see Trace Settings.

Tracing driver calls using MdsSetSetting¶

You can enable or modify tracing at runtime by calling MdsSetSetting from your application code. This allows you to start or stop tracing without restarting the application.

// Enable tracing programmatically
MdsSetSetting(NULL, "TRACE_ON", "c:\\trace\\sql_btr.tra");
MdsSetSetting(NULL, "TRACE_LEVEL", "2");

For more details, see Setting global and folder specific values programmatically.

Dependency Walker¶

1. Download Dependency Walker from www.dependencywalker.com. Mertech driver and the Migration Utility are 32-bit, make sure to download the 32-bit version of Dependency Walker.

2. Open the downloaded ZIP file.

3. Create an extract folder and extract all the files.

4. (Optional) drag a shortcut to your desktop or quick launch toolbar.

Identifying statically loaded dll dependencies¶

1. Start Dependency Walker.

2. Choose File | Open from the menu bar and browse to the location of the Mertech driver dll. Mertech driver dlls are usually located at <Program Files>\Mertech Data Systems\DB Drivers\Btrieve\bin

3. Choose sql_btr.dll for MS SQL, ora_btr.dll for Oracle or pgs_btr.dll for PostgreSQL.

Missing or mismatched dependencies appear in yellow or red. The most common dll to be missing is oci.dll.

Examining your application at runtime¶

1. Start Dependency Walker and set the View | Full Paths option.

2. Select the application using the File | Open command. The application is scanned for dependencies and a hierarchical diagram of all dependent modules is displayed in the Module Dependency Tree View.

3. Select Profile | Start Profiling.

4. Make sure Use full paths when logging file names is checked.

5. Click OK.

Your application should begin to run. As your application runs, Dependency Walker logs information to the Log View and updates the tree and list views.

Process Monitor¶

Process Monitor can also be used to identify missing dependencies and to troubleshoot other runtime errors.

1. Download Process Monitor from https://technet.microsoft.com/en-us/sysinternals/processmonitor.

2. Open the downloaded ZIP file.

3. Create an extract folder and extract all the files.

4. (Optional) drag a shortcut to your desktop or quick launch toolbar.

5. Start Process Monitor.

6. Select File from the menu bar and make sure Capture Events IS NOT checked.

7. Select Edit | Clear Display.

8. Select Filter and add Process Name btr2sql.exe to the list of events to be captured.

   

9. Enable event capture: select File from the menu bar and select Capture Events so IT IS checked.

10. Start the Btr2SQL Migration Utility or your application and reproduce the error.

11. Disable event capture in the Process Monitor: select File from the menu bar and select Capture Events so it IS NOT checked.

12. Examine the output. NAME NOT FOUND in the Result column can point to a missing dependencies.

Utilizing Function Executor¶

Whatever language your application is written in and whether it utilizes a high-level COM object, a class wrapper, or the BTRV function directly, each operation eventually is funneled into the BTRCALL (or BTRCALLID) function exported from w3btrv7.dll or wbtrv32.dll.

Pervasive provides a low-level tool for executing Btrieve commands called Function Executor. Since the tool runs directly off of w3btrv7.dll calling the standard BTRCALLID function, it is a good troubleshooting tool when an application is receiving an unexpected error or you would like to experiment with a particular scenario.

A simple technique to discern the difference between Btrieve and SQL behavior is to create two folders. In one, place wbexec32.exe (from pvsw\bin) and the original w3btrv7.dll. In the second folder, place another copy of the wbexec32 along with the Mertech w3btrv.dll and sql_btr.cfg, ora_btr.cfg, or pgs_btr.cfg. Then create shortcuts to each of these and you can selectively execute Btrieve API calls against Btrieve and against SQL.

NOTE: Function Executor is just like any Btrieve application and will thus require the SQL client to be installed and on the system PATH (see Prerequisites).

Using the Function Executor History window, you can save a sequence of API calls and then play them back later or ask it to repeat them any number of times. During playback, there is a small arrow in the lower right of the dialog box which will access a record of time to execute the calls. This can be used for quick performance comparisons.

Blog Topics¶

The Mertech Data Website contains white papers and blogs to assist with additional troubleshooting topics. The site search option can help you to find the required topics.