Troubleshooting Migration Utility Initialization Errors

Sometimes an error occurs (Error loading driver! in the screenshot below) when you select the target server in the BTR2SQL Migration Utility Login dialog box or the Migration Utility closes unexpectedly.

The Cause

The most likely cause is that a BTR2SQL driver is not in the expected location, or there is a problem with the SQL client installation.

When you make a server selection, the BTR2SQL Migration Utility loads one of four migration drivers (sql_btr.dll, mys_btr.dll, ora_btr.dll, or pgs_btr.dll). By default, the Migration Utility looks for these dlls in the installation folder (typically <Program Files>\Mertech Data Systems\DB Drivers\Btrieve\bin). The Migration Utility also expects to find a valid license file (sql_btr.cfg, mys_btr.cfg, ora_btr.cfg, or pgs_btr.cfg) in that same folder.

Additionally, the Migration Utility requires a 32-bit client driver that matches your selected SQL server and the client driver may have other dependencies such as the C runtime libraries.

If any of these items are not found on the system PATH, Windows fails to load the Mertech dll.

Resolving the Problem

First and foremost, be sure the appropriate 32-bit client is installed and that the client and server version numbers match and are supported by BTR2SQL. You can develop 64-bit applications, and if so 64-bit libraries are available from Mertech. However, the Migration Utility requires the 32-bit client to be installed. If a 64-bit client is installed the Migration Utility may close unexpectedly when you attempt to login.

Note: Missing Oracle dependencies may be resolved by installing the Visual C++ 2010 Redistributable package. (https://www.microsoft.com/en-US/download/details.aspx?id=8328)

Below are several options to help identify the exact cause of the problem.

Enable the Migration Trace File and examine the output

1. Start the BTR2SQL Migration Utility.
   
   
2. Choose File | Preferences from the Migration Utility menu bar to open the Preferences dialog box.
   
   
3. Enable the Miration Trace File to a location of your choice and set this for Detail Level 2.
   
   
4. Click OK to close the Preferences dialog box.
   
   
5. Choose File | Login and try to reproduce the error.
   
   
6. Close the Migration Utility so the trace buffer is written to disk.

Note: Be sure to turn off tracing otherwise you will experience performance degradation.

Check for the trace file that you specified earlier. If it exists, it will be small and should have information about the cause of the failure. If the trace file was not created, the driver was not loaded, most likely because a dependency is missing.

An extract from a trace file is shown below. Lines highlighted in blue show where dlls were successfully loaded. Lines highlighted in red show an attempt to locate the license file first in the installation\bin directory and then in each directory listed in the Windows PATH.

Use the Dependency Walker

A good tool to locate a missing dependency is Dependency Walker, which can be downloaded from www.dependencywalker.com. Since the Mertech driver and migration application are 32-bit, make sure to install the 32-bit version of Dependency Walker.

1. Open the downloaded ZIP file.
   
   
2. Create an extract folder and extract all the files.
   
   
3. (Optional) drag a shortcut to your desktop or quick launch toolbar.
   
   
4. Start Dependency Walker.
   
   
5. 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.
   
   
6. Choose sql_btr.dll for MS SQL, mys_btr.dll for MySQL, ora_btr.dll for Oracle or pgs_btr.dll for PostgreSQL.

Missing or mismatched dependencies appear in yellow or red. The most common dlls to be missing are libmysql.dll and oci.dll (as shown in the screenshot below).

Try the Process Monitor

Process Monitor can also be used to do identify statically and dynamically loaded dlls. Download Process Monitor from https://technet.microsoft.com/en-us/sysinternals/processmonitor.

1. Open the downloaded ZIP file.
   
   
2. Create an extract folder and extract all the files.
   
   
3. (Optional) drag a shortcut to your desktop or quick launch toolbar.
   
   
4. Start Process Monitor.
   
   
5. Select File from the menu bar and make sure Capture Events IS NOT checked.
   
   
6. Select Edit | Clear Display.
   
   
7. Select Filter and add Process Name btr2sql.exe to the list of events to be captured.
   
   

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

9. Start the BTR2SQL Migration Utility and reproduce the error.

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

11. Examine the output, looking in particular for NAME NOT FOUND.

12. In the example below, OCI.dll is not found in the BTR2SQL bin folder, nor can it be located anywhere on the system PATH.

Examine the Startup Trace

There is also a startup trace file to record errors detected during the early stages of driver initialization. The startup trace is automatically turned on and then turned off after successful driver connection.

The startup trace file is named "mds_.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%.

Note: Always use Windows Start | Run "%temp%" to navigate to the temp folder rather than manually going to what you *think* is the temp folder. Look for error messages in the trace file. The type of errors captured includes:

• unhandled exceptions

• assertions

• memory allocation errors during init

• error opening performance trace output

• error opening runtime trace output

• bad value given for trace level

• errors in some of the initial OCI calls