Download Run Magic apps with Oracle, MS SQL, MySQL and PostgreSQL

PAINLESS MULTI-DBMS STRATEGY
For Magic Developers
Contents

Mertech’s ISAM to SQL Database
Connectivity Drivers for Btrieve

BTR2SQL Support for Magic

Getting Started!

Contact Information
Copyright © 2014 Mertech Data Systems, Inc. All Rights Reserved. This document is for informational purposes only.
Mertech makes no warranties, expressed or implied, in this document.
BTR2SQL and ISDBC are trademarks of Mertech Data Systems, Inc.
Btrieve is a registered trademark and Pervasive.SQL is a trademark of Pervasive Software Inc.
Magic is a registered trademark of Magic Software Enterprises Ltd.
MySQL is a registered trademark of MySQL AB.
PostgreSQL is a registered trademark of PostgreSQL Inc.
Oracle is a trademark of Oracle Corporation.
SQL Server and Windows are registered trademarks of Microsoft Corporation.
Other trademarks and trade names mentioned herein are the property of their respective owners.
Mertech’s ISAM to SQL Database Connectivity Drivers for Btrieve
Mertech Data Systems has been the leading provider of ISAM to SQL Database
Connectivity drivers for over 17 years. The Mertech BTR2SQL product provides the Btrieve
community an easy way to switch from a Btrieve-based ISAM database to an SQL
database in a matter of hours without a costly, time-consuming source code rewrite. The
result is a seamless interface with existing applications.
The BTR2SQL product bundle consists of a GUI Migration Utility and database driver dll.
The Migration Utility takes an existing Btrieve or Pervasive.SQL database and migrates it
to a Microsoft SQL Server, Oracle, MySQL or PostgreSQL database. The Mertech database
driver dll replaces the Btrieve Engine and functions with the application to execute existing
database operations on the new SQL backend.
Application opens a table
Magic runtime loads the driver dll and calls Btrieve API “B_OPEN”
Btrieve
wbtrv32.dll
Btrieve or
Pervasive.SQL
Mertech
MS SQL
wbtrv32.dll
Mertech
Oracle
wbtrv32.dll
Mertech
MySQL
wbtrv32.dll
Mertech
PostgreSQL
wbtrv32.dll
MS SQL Server
Oracle
MySQL
PostgreSQL
Note: The Btrieve Engine is contained in wbtrv32.dll or a later version called w3btrv7.dll.
Mertech provides replacements for both dlls.
The Mertech database drivers use the native APIs, OLEDB for MS SQL Server, OCI for
Oracle, and C programming interface for MySQL and PostgreSQL to provide the fastest
possible access to the respective database servers.
Mertech’s BTR2SQL product provides a very compelling value proposition for companies
looking to quickly adopt an RDBMS into their IT infrastructure. The BTR2SQL driver:

Alleviates the costs associated with migrating applications working against existing
Btrieve data sources to MS SQL Server, Oracle, MySQL, and PostgreSQL
databases.

Provides developers with an efficient, platform-independent solution using existing
code.

Creates the opportunity for the developer to immediately leverage existing
applications with an MS SQL Server, Oracle, MySQL, or PostgreSQL backend.

Accomplishes all of these tasks without compromising the stability or speed of the
application and without requiring any source code changes.
Copyright © 2014 Mertech Data Systems, Inc. All Rights Reserved.
-1-
BTR2SQL Support for Magic
Magic developers, or Magicians, are able to rapidly develop complex, scalable, enterprise,
client-server, business applications utilizing the powerful Magic development framework.
The Magic application platform supports a variety of databases including Btrieve
(Pervasive ISAM) and Pervasive.SQL.
In order to support Magic’s way of developing software applications, Mertech made
changes to the BTR2SQL product to provide the best possible integration with Magic.
Database Migration
Mertech provides two ways to migrate Magic Btrieve and Persasive SQL data to an SQL
backend.
The first option is to use the Mertech Migration Utility that automatically creates tables and
indexes, and copies records to the newly created table. The Migration Utility uses the
Pervasive data dictionary files (DDFs) to determine field types, field names and field size
along with index structures.
The second option is to use MigrateUniPaasData, the Mertech command-line migration tool
that works with Magic uniPaaS applications where the source code is stored in XML format.
MigrateUniPaasData reads the application source files directly to create a snapshot of the
database, eliminating the need for DDFs.
During migration, Mertech stores the SQL table schema (derived either from the DDFs or
XML source) in an INT file that allows the Mertech driver to connect to and open the
converted SQL tables.
Dynamic Table Creation and Deletion
Another consideration for Magicians is creating and deleting tables on the fly during
program execution. Magicians know that when they want a table it will be in the database
and when they want to delete a table it will be removed. The Magic runtime handles table
creation through the Btrieve Engine, allowing the Mertech driver to trap create commands.
When a create command is issued, the Mertech driver reads the data definition from the
corresponding INT file and creates the empty table on the server based on this definition.
If your application creates tables on the fly, the Mertech driver will automatically handle
this without any need to modify your source code.
Magicians usually issue a DBDEL command to delete a file. The Magic runtime processes
DBDEL by issuing a file delete command through the Windows operating system and not
through the Btrieve API. This means that the Mertech drivers are not able to trap DBDEL
calls. Mertech created an SDK and exposed driver functionality including commands that
allow Magicians to easily remove tables from the SQL backend. If your application deletes
files on the fly through the OS, you will need to modify that code to use the B_DROP_FILE
or B_TRUNCATE_FILE commands instead.
Note: Documentation is available for the SDK. Contact Mertech Technical Support for
additional information.
Copyright © 2014 Mertech Data Systems, Inc. All Rights Reserved.
-2-
Handling Multi-Directory Database Structure
Some applications create the same table structures in different directories as a way to
differentiate between data for different companies or different years. For example, data for
Company A might be stored in directory \App\CompanyA and for Company B in
\App\CompanyB. This is similar to "partitioning" in some databases.
Mertech provides for an easy way to handle such deployments through the use of an INI
file created specifically for Magic. The INI file allows Magic developers to handle multiple
directory deployment, to automate SQL logins and to easily handle multiple data
directories. The INI file also contains the necessary information to deploy tables to
different databases and even a different server.
Note: For additional information refer to the sections titled Sample INI and Segregating
Tables in the Database in the BTR2SQL User’s Guide.
Dealing with Database Security
Once the tables are migrated to an SQL backend, the application needs to log in to the
server before it can gain access to the tables. Mertech provides an automatic popup login
dialog box that displays when a table is accessed. Access is granted once the correct user
id and password are provided.
The user id and password can also be encrypted and stored in the INT or INI file so logins
are automated.
Automatic Magic to SQL Data Mapping
All Magic data types are automatically mapped to appropriate SQL data types, with the
flexibility to change some ASCII types through the Migration Utility.
Handling Reserved Table/Field Names And Special Characters
All Mertech drivers employ "quoted identifiers" to ensure that reserved words and special
characters in tables continue to work without requiring changes. Table names containing
invalid characters (such as ‘?’ in Oracle), can be automatically mapped to valid table
names.
Handling Unique Keys
Tables without a unique key pose a problem for Magicians looking to move to an SQL
backend. This is because in Btrieve or Pervasive, a record can always be accessed by the
record offset, which serves as unique identifier for the record. Moving a table without an
explicitly declared unique key can lead to problems.
Mertech drivers provide a way to uniquely find a record through an auto-increment column
that is added to the table during migration.
Copyright © 2014 Mertech Data Systems, Inc. All Rights Reserved.
-3-
Locking and Transactions
If you are using Btrieve or Pervasive engines with Magic, it does not matter how you
handle transactions and rollback. However in the SQL world, all applications are written
with transaction support. The locking mechanism in SQL depends on the “isolation level” of
the transaction. In general, one cannot lock a record outside of a transaction in SQL
databases, but in Pervasive/Btrieve you can.
Mertech developed special techniques to allow record locking outside of a transaction.
However, it is our recommendation that you turn on transactions when using SQL
databases for the best performance.
Existing SQL calls in Pervasive.SQL
Btrieve is a record-oriented transactional database based on ISAM. Btrieve interfaces with
the MicroKernel Database Engine (MKDE). Pervasive.SQL (PSQL) was developed on top of
the MKDE. The PSQL architecture consists of two database engines: a) the storage engine,
MKDE, and b) a relational database engine. So, an application using a PSQL database can
use either the Btrieve APIs and the MKDE or use standard SQL.
Note: Mertech’s BTR2SQL drivers replace the Btrieve Engine. If your application is using
the relational database engine, you will need to use the appropriate SQL server gateway
and most likely modify your SQL commands in order to migrate to new SQL backend.
Copyright © 2014 Mertech Data Systems, Inc. All Rights Reserved.
-4-
Getting Started!
Preparing your Environment
1. Install the Mertech BTR2SQL product, selecting the defaults during the installation.
2. If you have previously run your application with Mertech drivers, restore the
original Btrieve Access dll to C:\Program Files\Magic\<version>\wbtrv32.dll.
The Btrieve Access dll is required to read existing Btrieve files.
3. Make sure that all the Btrieve files exist before continuing.
Magic is capable of generating Btrieve files on the fly at runtime so it is
common to not deploy all of the files. However, the migration process
needs to extract information from all the Btrieve files.
Option 1: Migrating Your Existing Data Using DDFs
1. Select a target folder where you plan to store the DDFs.
2. If there are old DDFs in the location you selected, delete them.
3. Create the DDFs using the Magic DDF Maker Wizard.
a.
Start the Magic development environment.
b.
Select DDF Maker from the Tools menu to start the DDF Maker Wizard.
c.
Follow the prompts to select the files you want to create DDFs for, and the
location where you want the DDF files stored.
d.
Exit Magic.
Copyright © 2014 Mertech Data Systems, Inc. All Rights Reserved.
-5-
4. Select Mertech’s ISDBC Drivers for Btrieve | Migration Utility from the
Window’s Start menu to launch the Migration Utility. The login dialog box displays.
5. Select the target backend (MS SQL Server, MySQL, Oracle, or PostgreSQL) and
login.
6. The first time the Migration Utility is run, the File Open dialog box displays allowing
you to browse to the location where you generated the DDFs. Alternately, select
File | Select File.DDF… and open your DDF file.
7. The File Selection dialog box displays, listing all of your Btrieve files.
8. Click All to select all files in the list.
9. Right-click to display the File Selection popup menu then select Convert to
driver. The Convert Data Files dialog box displays.
10. Review the options in the dialog box.
11. Click OK to begin migrating the files. The Migration Utility creates the tables,
associated indexes and copies the records into the table on the SQL server.
12. Select Exit from the File menu to exit The Migration Utility. Your data has now
been copied to the SQL backend.
Option 2: Migrating Your Existing Data Using XML format
MigrateUniPaasData is a new command-line tool to migrate an existing Btrieve application
to work with an SQL server. Unlike The Migration Utility, MigrateUniPaasData does not
require DDFs to perform the migration. MigrateUniPaasData is designed to work with
uniPaaS applications where the source code is stored in XML format.
NOTE: If your uniPaaS application is not stored in XML format, export the DDFs and use
the Migration Utility or the command-line tool MdsMigrateTable to perform the migration.
MigrateUniPaasData allows full migrations as well as maintenance tasks like exporting new
INT files. MigrateUniPaasData can also generate the SQL script used to define a new
database on the SQL server.
Copyright © 2014 Mertech Data Systems, Inc. All Rights Reserved.
-6-
1. Select Mertech’s ISDBC Drivers for Btrieve | Migrate UniPaas Data from the
Window’s Start menu to open a Command Prompt window.
2. Run the Migrate UniPaas Data script by typing the following at the command
prompt:
MigrateUniPaasData [operation] [configuration parameters] source
where:

operation determines whether a full migration, simple table creation or
data copy is performed

configuration parameters specify settings used during the migration

source names the folder containing the application source file
Running Your Application
1.
Save a backup copy of the Btrieve Access dll C:\Program
Files\Magic\<version>\wbtrv32.dll
2. Copy the replacement Mertech driver wbtrv32.dll from C:\Program Files\Mertech
Data Systems\DB Drivers\Btrieve\deploy\<mssql | mysql | oracle | pgsql>\
wbtrv32.dll to C:\ProgramFiles\Magic\<version>\ overwriting the existing Btrieve
Access dll.
All database calls from Magic will now be routed through Mertech’s driver
instead of the Btrieve Engine.
3. Start your Magic application.
A login box displays.
4. Login to the target server.
5. Continue running your Magic application.
Copyright © 2014 Mertech Data Systems, Inc. All Rights Reserved.
-7-
Contact Information
If you would like to know more about Mertech’s products, please visit our website
www.mertechdata.com or contact us at:
Corporate Head Office
Mertech Data Systems, Inc.
18503 Pines Boulevard, Suite 312
Pembroke Pines, FL 33029
USA
Tel: +1 (954) 585 9016
Fax: +1 (866) 228 1213
California Office
Mertech Data Systems, Inc.
114 East Shaw Avenue, Suite 100
Fresno, CA 93710
USA
Copyright © 2014 Mertech Data Systems, Inc. All Rights Reserved.
-8-