Using ISAM-Based Programs with SQL Databases Using Mertech's
Total Page:16
File Type:pdf, Size:1020Kb
Contents PAINLESS MULTI-DBMS STRATEGY For Magic Developers Mertech’s ISAM to SQL Database Connectivity Drivers for Btrieve BTR2SQL Support for Magic Getting Started! Contact Information Copyright © 2016 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” Mertech Mertech Mertech Mertech Btrieve MS SQL Oracle MySQL PostgreSQL wbtrv32.dll wbtrv32.dll wbtrv32.dll wbtrv32.dll wbtrv32.dll Btrieve or MS SQL Server Oracle MySQL PostgreSQL Pervasive.SQL 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 © 2016 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 © 2016 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 © 2016 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 © 2016 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.