Troubleshooting Btrieve Driver Deployment

A Windows application accessing Btrieve data uses either wbtrv32.dll or w3btrv7.dll. When migrating Btrieve to SQL and deploying your migrated application, you must provide the Mertech drivers as a replacement for these two DLLs.  If your application cannot locate the Mertech version of the driver or one of its dependencies, the application will not load or execute properly.

Locating the Mertech drivers

There are several locations where you can put the Mertech drivers, but the application must be able to find the Mertech version of the DLL using the standard Windows DLL Search Order. Typically the Mertech version of wbtrv32.dll or w3btrv7.dll is placed in the directory with the application executable. Windows searches here for dependencies first, so this guarantees that the correct version is located. If the driver DLL is not placed in the directory with the application, it must be found by Windows DLL search. This is slightly different on each version of Windows, but in general, this is the order of search:

• The application's executable directory
  
  
• The system directory (%windir%\system32, or %windir%\SysWOW64)
  
  
• The 16-bit system directory (%windir%\system)

• The Windows directory (%windir%)

• The current directory
  
  
• The directories that are listed in the PATH environment variable. Note that this does not include the per-application path specified by the App Paths registry key. The App Paths key is not used when computing the DLL search path.

Other dependencies

The Mertech driver DLLs depend on other DLLs such as oci.dll from the Oracle client. Some of the server-specific dependencies are listed below.

• Oracle - The Mertech driver links to oci.dll. oci.dll and all its dependencies must be found on the search path. Note: The 32-bit Oracle client must be installed and functioning, 64-bit will not work.

• MSSQL - You must have SQL Native Client 2005, 2008 or 2012 installed. Note: only Version 5 (and above) of the Mertech driver supports the 2012 client.

• MySQL - The 32-bit version of libmysql.dll and its dependencies must be found on the search path.

• PostgreSQL - libpq.dll and its dependencies must be found on the search path.

Dependency Walker

You can download and use the free Dependency Walker utility to troubleshoot missing dlls and other dependency errors.

1. Start Dependency Walker and set the View | Full Paths option.
2. Select your 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

A successful analysis is shown below. Notice W3BTR7.DLL is successfully loaded.

A failed analysis is shown here. W3BTR7.DLL could not be found in the application directory or on the Windows search path.

Another failed analysis is shown below. Although W3BTR7.DLL was found, one of its dependencies, the libmysql.dll component, was not.

Startup Trace

Once you know that the application dll is loaded properly, you can use Mertech’s startup trace to troubleshoot any remaining issues. The startup trace is automatically turned on and then turned off after successful driver connection.

The startup trace file is named "mds_<drivername>.log" (for example, mds_ora_btr.log, mds_sql_btr.log, mds_mys_btr.log, mds_pgs_btr.log) and is always written to %temp%.

Refer to Migration Reports and Driver Traces in the BTR2SQL User's Guide  for information on setting up runtime driver tracing.