Quick Start Guide. Prerequisites

Transcription

1 Quick Start Guide Thank you for trying Mertech s Btrieve to SQL database application drivers. By now you have either downloaded a demonstration version or purchased the product and you have installed it. This Quick Start guide is a summary of the BTR2SQL User s Guide located in the Mertech ISDBC Drivers for Btrieve program group, which you can access by using your Start button. This Quick Start Guide lets you know where to go from here or how to get started Prerequisites Btrieve 6.15 or Pervasive.SQL 7.0 (or greater) You need a Btrieve engine during data migration to read the original data. This may be the workgroup engine, a server engine, or a client with the server engine hosting the data on another computer. See the Pervasive documentation for information on installation and configuration. Btrieve data files with schema defined in Pervasive.SQL DDFs Data Definition Files (DDFs) define the layout, or schema, of the tables in the Pervasive.SQL database. Without the DDFs, the data cannot be efficiently migrated to SQL. See the Pervasive documentation and many other resources and tools available online for further information on building DDFs if they are not included in your database. Microsoft SQL, MySQL, Oracle, PostgreSQL MS SQL Server, MySQL, Oracle, and PostgreSQL are the four SQL back-ends currently supported by the ISDBC for Btrieve drivers. One of these back-ends must be installed and running. The client software must be configured on the computer where the migration and the application are run. Refer to your database server documentation for details. MS SQL Server The DB_OWNER role should be set for the User ID identified for the migration process. For the fullest support of data types, the SQL Server 2012 Native Client should be used. Alternatively, the 2008 or 2005 Native Client can be used. (Download the Native Client from the Feature Pack available here: MySQL The User ID used during migration must have SUPER rights; or the MySQL server must be or above. Oracle Using Oracle's Security Manager, add the Select Any Table privilege to the user ID used for the migration process.

2 PostgreSQL The server must be 9.1 or above. PostgreSQL does not support storing Zero (null) bytes in a string. If your data needs to include a Zero byte, you must include the Binary flag on the field in the DDFs (bit 12 / 0x1000 on field flags). The PostgreSQL citext module provides the case-insensitive character string type CITEXT, which allows for case insensitive fields without the need for inverse key columns. The version 5 migration tool was rewritten to use the.net framework resulting in an improved interface. The version 5 migration tool requires.net Framework 3.5. The installation automatically installs.net 3.5 if it is not already installed,.net Framework 3.5 except on Windows 8. NOTE: Windows 8 includes.net 4, but not the required 3.5 version. When you run an application that requires an older.net version, Windows 8 displays a dialog box asking you to download it. Licensing If you have already purchased the ISDBC drivers, then you have received a registration file in a ZIP file along with instructions. If you are evaluating the product, a limited 30-day license is already installed. If you want to request a fully functional 30-day license file, contact by the sales@mertechdata.com or by the phone number +1 (954) Please include your company name and some information about how you intend to use the drivers. The ZIP file you receive also contains a license file: sql_btr.cfg for MS SQL Server, mys_btr.cfg for MySQL, ora_btr.cfg for Oracle, pgs_btr.cfg for PostgreSQL. The file must be in the Windows PATH. The license is needed by the Btr2SQL migration utility, so place a copy of the CFG file in the installation folder (<programfiles>\mertech Data Systems\DB Drivers\Btrieve\bin). The license file is also needed at runtime by your application. See 3 - Substitute the Btrieve Access dlls for information to replace the Pervasive dlls we recommend that you place a copy of the license file in the same folder with the access dll and your application exe.

3 Your First Migration Pre-Migration: Validate Data Definition Files using DDF Validator Application Mertech s DDF Validation Tool has been developed to make sure that the DDFs have been defined accurately. It searches for common mistakes, such as the total length of fields that do not match the Btrieve record size for the file, and for files that have not been defined. It also checks for anomalies in the names of the columns, indexes, etc. After checking for table and column level issues, it reads every row from each table in the database and examines each field. When an error is detected, a message displays providing the error code and a suggestion to help you fix the problem. Optimally, you should run the DDF Validation Tool prior to migrating your data to SQL. If you have already migrated the tables, you can convert them again if problems are encountered with the DDFs. We recommend that you run a validation even if you have had DDFs for years. The validation does not take long to run, but you may want to limit the row scanning to save some time. Refer to the DDF Validator Command-line, for details. Any time that you make changes to the DDFs, we recommend that you run the DDF Validation Tool on the affected tables. Step 1: Migrate data to SQL back-end using Btr2SQL In order to run your application with the target database, you must first migrate your database to the target database using the Btr2SQL Database Migration tool. The database migration tool 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 Btr2Sql migration process on the Pervasive.SQL machine. This splits up the processing requirements of SQL and the data conversion.

4 Step 2: Verify the migration Run Mertech s Migration Validator to validate the migration process. The Migration Validator uses the standard Btrieve API to read rows from Btrieve and from SQL simultaneously and compare the data buffer returned. A message displays in the output if any mismatch has been found. Step 3: Substitute the Btrieve Access dlls A 32-bit Windows application accessing Btrieve data uses either wbtrv32.dll or w3btrv7.dll. The Mertech drivers are provided as a replacement for these two dlls. In the installation folder %ProgramFiles(x86)%\Mertech Data Systems\DB Drivers\Btrieve\deploy\ are subfolders, depending on the SQL back-end being targeted and on which dll your application uses. If you are not sure which dll is used, then replace 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 version of wbtrv32.dll or w3btrv7.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 order of search: 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. Important: The license file also must be found in the system PATH. We recommend that you place the sql_btr.cfg or ora_btr.cfg file in the same folder as the access dll. For example, if your application executable file is located in c:\myapp\bin and you will be accessing data in Oracle: Copy C:\Program Files\Mertech Data Systems\DB Drivers\Btrieve\deploy\oracle\w3btrv7.dll and ora_btr.cfg to c:\myapp\bin.

5 Replace the dlls that currently reside in the PVSW\BIN folder. This ensures that the Mertech dll is used. However, many of the Pervasive tools will no longer function. For instance, if the table definitions need to be corrected, the original Pervasive dlls must be restored. Be sure that you save a copy of the original dlls before you replace them. Step 4: Run Your Application Once the correct dll is substituted, run your application. The Server Login dialog box displays and indicates that the program is now accessing the new back-end. At this point, the application, without modification, should be sending and receiving data from the newly chosen back-end. 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 uses the B_OPEN API to open c:\pvsw\demodata\billing.mkd. The Mertech dll is loaded and used for the B_OPEN because it is located in the application's folder. It finds the.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 back-end. If this dialog box does not display, either the Mertech dll was not found or the user chose to save the user id and password previously. 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. You may now test the application with the knowledge that your customers will have highly scalable and reliable database access. Step 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 or wbtrv32) 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 (MS SQL Server Native client, MySQL client, Oracle OCI client, or PostgreSQL client) must be installed on the system running the application.

6 The.INT files will be installed. 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. The BTR2SQL User s Guide, section on Data Directory Configuration File, gives an example of a typical deployment directory structure. Hardware considerations Utilize RAID offers the best balance of performance and data integrity. Defragment the server drives If you have never defragmented a drive, you will be amazed at the improvement in access speed. Have at least 2G of RAM More memory means better performance. The usual amount of data often accessed should fit in the server's cache with room to spare for optimal performance. Turn off the Mertech driver trace When initially testing the application, you may have used the driver trace. Be sure to turn this off when you are finished. Leaving this turned on causes slowdown in performance. Place Data Index and Transaction Logs on different physical hard drives Place Data Index and Transaction Logs on different physical hard drives on the server to balance the drive access. Pre-allocate database or tablespace Pre-allocate database or tablespace according to the current size of the Pervasive.SQL database if the back-end allows it. Leave room for growth and once again, defragment the drive. Both of these steps help ensure that the tables are not fragmented across the hard disk. Set the Recovery Model to BULK LOGGED Set the Recovery Model to BULK LOGGED for Microsoft SQL Server. Changes to my.ini Configuring MySQL to utilize as much memory on the server as possible will usually boost performance. There are many resources available on optimizing MySQL. One entry of particular impact is query_cache_size; depending on the initial configuration chosen, the default for this value might be very low. Also, set innodb_flush_log_at_trx_commit = 0

7 Utilizing Function Executor Whatever language your application is written in and whether it utilizes a high-level COM object, a class wrapper, or the BTRV function directly, each operation eventually is funneled into the BTRCALL (or BTRCALLID) function exported from w3btrv7.dll or wbtrv32.dll. Pervasive provides a low-level tool for executing Btrieve commands called Function Executor. Since the tool runs directly off of w3btrv7.dll calling the standard BTRCALLID function, it is a good troubleshooting tool when an application is receiving an unexpected error or you would like to experiment with a particular scenario. A simple technique to discern the difference between Btrieve and SQL behavior is to create two disk folders. In one, place wbexec32.exe (from pvsw\bin) and the original w3btrv7 dll. In the second folder, place another copy of the wbexec32 along with the Mertech w3btrv and sql_btr.cfg (or ora_btr.cfg). Then create shortcuts to each of these and you can selectively execute Btrieve API calls against Btrieve and against SQL. Note, Function Executor is just like any Btrieve application and will thus require the SQL client to be install and on the system PATH (see Before You Begin Prerequisites for more info). Using the History window, you can save a sequence of API calls and then play them back later or ask it to repeat them any number of times. During playback, there is a small arrow in the lower right of the dialog box which will access a record of time to execute the calls. This can be used for quick performance comparisons.