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 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 Mertech MS SQL Mertech Oracle Mertech MySQL Mertech PostgreSQL Btrieve or Pervasive.SQL MS SQL Server Oracle MySQL PostgreSQL Note: The Btrieve Engine is contained in 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. - 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. - 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. - 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. - 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>\. 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. - 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. - 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>\ 2. Copy the replacement Mertech driver from C:\Program Files\Mertech Data Systems\DB Drivers\Btrieve\deploy\<mssql mysql oracle pgsql>\ 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. - 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 - 8 -