Step by Step Migration using the GUI Migration Utility¶

1. Migrate Data to SQL backend using the Migration Utility¶

In order to run your application with the target database, you must first migrate your database to the target database using the Migration Utility. The database Migration Utility creates the table, copies the data, and creates the required indexes by using the entries in the DDF files. That is why an accurate DDF is essential to the overall application migration process.

Suggestion: Assuming Pervasive.SQL and the data reside on a machine other than the new server, run the migration process on the Pervasive.SQL machine. This splits up the processing requirements of SQL and the data conversion.

An example of migrating tables in the Pervasive.SQL Demodata database to an MS SQL Server backend is given in this section. The migration steps for Oracle and PostgreSQL are similar; only the driver name and the login information are different.

Login to the target database¶

1. Select Mertech’s ISDBC Drivers for Btrieve | Migration Utility from the Windows Start menu.

The Login dialog box appears, as shown in Figure 2.

Figure 2 Login Dialog Box

2. Select the Mertech driver you are using — MS SQL Server, Oracle or PostgreSQL.

Note

If you are using Oracle, the full Oracle client or Oracle Instant Client must be installed and its location included in the system PATH.

3. In the Server Name field, type the name of the server to which you are logging in to. If you are using SQL Server, click the button next to the text box to automatically search for available servers on the network.

4. In the User Name field, type the name of the user. This is only needed if you are using SQL Server Authentication to logon to the server. If you are using Windows authentication, you can click Trusted Connection. Please note that Trusted Connection must be set up properly by your network administrator to allow you access to the SQL Server instance.

5. In the Password field, type the password for the user (not needed for trusted connection).

6. Select the Database you want to connect to. The default database for the user is selected automatically. Click the button next to the text box to display the Select Database dialog box.

7. Click Login to log into the server.

Select and migrate files¶

Note

See Setting Migration Preferences to choose global options for tracing, field mappings, field default values and more.

Important

Oracle users see Oracle-Specific Storage and Loader Options before starting the migration.

1. Select File | Select File.DDF… and open your DDF file. The File Selection dialog box lists all of the entries in your DDF. At this stage, you still need your Btrieve engine to read the database files.

2. Select a single file or multiple files to migrate by highlighting the entries in the dialog box.

3. Right-click> to display the popup menu.

Figure 3 File Selection Dialog Box (with right-click popup menu)

4. Select Convert to driver. The Convert Data Files dialog box appears (the format of the dialog box depends on whether one or more files is selected).

Figure 4 Convert Data Files Dialog Box

5. Click OK to begin migrating the data files.

2. Verify the Migration¶

Use the /validate-data option on the MdsMigrateTable or MdsMigrateFile command to verify that the migrated data matches the original Btrieve files. This can be included as part of the migration command itself — there is no need to run validation as a separate step. After the migration completes, the tool reads back every row from the SQL backend and compares it to the source Btrieve data. Any mismatches are reported. To validate an existing migration without re-migrating, use the Verify operation with /validate-data. See Validation Options for details.

3. Substitute the Btrieve Access dlls¶

In order for the application to access the new data on the SQL database, the Mertech versions of the Btrieve access dlls must be used. For 32-bit applications these are wbtrv32.dll and w3btrv7.dll; for 64-bit applications the equivalents are wbtrv64.dll and w64btrv.dll. The easiest way to do this is to copy the dlls from the installation folder to the location where the application EXE is run. Choose the appropriate installation subfolder depending on your target SQL backend:

• 32-bit: <Program Files>Mertech Data Systems\DB Drivers\Btrieve\deploy\ subfolder

• 64-bit: <Program Files>Mertech Data Systems\DB Drivers\Btrieve\deploy\ subfolder \x64

If you are not sure if your application uses wbtrv32.dll or w3btrv7.dll, then copy both.

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 driver 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 search order:

• 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.

4. Run Your Application¶

Once the correct dll is substituted, run your application. The Server Login dialog box, shown in Figure 5, displays and indicates that the program is now accessing the new backend.

Figure 5 Server Login Dialog Box

At this point, the application, without modification, should be sending and receiving data from the newly chosen backend. The original MicroKernel files, the Pervasive.SQL engine and any Btrieve/DDF tools are no longer needed.

As an example, an application written for the Pervasive Demodata database issues the B_OPEN API to open c:\pvsw\demodata\billing.mkd. The Mertech version of the Btrieve access dll is loaded and used for the B_OPEN because the Mertech dll is located in the application’s folder. The Mertech driver finds the billing_mkd.INT file, reads it, and then displays a login dialog box, which allows the user to input a user id and password for the selected SQL backend. If this dialog box does not display, either the Mertech dll was not found or the user id and password were previously saved.

You may choose to shut down the Pervasive services and stop the workgroup engine. The application should continue running because the data is now being provided by the new SQL server.

5. Deploy the Application¶

If your application will not be accessing Btrieve and SQL data simultaneously when the application is deployed, the Pervasive components, located in the pvsw directory, are no longer needed. Rather than including the entire Pervasive.SQL installation, the Mertech dll (w3btrv7.dll / wbtrv32.dll for 32-bit, or w64btrv.dll / wbtrv64.dll for 64-bit) is installed in the application directory. No registry keys or COM registration is required. The Btrieve data files and DDFs are also not needed.

The SQL client (MSOLEDBSQL, Oracle OCI client, or PostgreSQL client) must be installed on the system running the application. The client libraries must match the bitness of the Mertech driver DLL.

The .INT files must also be copied to the system running the application. The application will continue doing a B_OPEN on billing.mkd, for instance, even though billing.mkd does not exist. The Mertech driver dll will read billing_mkd.int instead.

See Scenarios using the GUI Migration Utility for an example of a typical directory structure

6. Optimize the Application for SQL¶

Mertech provides a rich set of extended SDK and optimization tools designed to enhance application performance, with particular benefits for batch operations and complex reporting. By leveraging embedded SQL and server-side components like stored procedures and functions, you can significantly optimize these intensive workloads.

For large-scale batch processing and data-intensive reporting, using stored procedures and functions allows you to implement complex business logic directly on the server. This reduces network traffic by performing heavy processing on the more powerful database server and transferring only the essential results to the client.

Embedded SQL further empowers your applications by using the full power of SQL (via the Btrieve API) to create highly constrained, optimized data-sets. This can replace hundreds of lines of manual client-side code with just a few lines of efficient SQL, streamlining both development and execution.

To further optimize reporting performance, the SDK allows for the reduction of data read. Rather than reading entire records—which is often inefficient in traditional Btrieve applications—the SDK provides specialized calls to restrict the data returned to only the specific fields required. This field list can be dynamically adjusted to ensure peak performance during time-sensitive reporting tasks.

See Also BTR2SQL SDK