Migrating Magic uniPaaS Applications¶

MagicIni¶

uniPaaS variable configuration information is entered in the Studio and stored in the magic.ini file. This includes a definition for all the data files used in the project.

Figure 25 Data File Definitions

This also includes logical names, which provide a way to specify the location of physical files.

Figure 26 Logical Names

At runtime, when the user logs into a certain customer (for example, FL), the %CurrentCust% variable in the magic.ini file is updated to reflect the exact location (for example, FLstore). Future access to a customer table (for example, Customers.btr) is then directed to the FLstore directory (c:\SampleMultiCompanyLayout\FLstore\Customer.btr).

During migration, MigrateUniPaasData reads the %CurrentCust% variable and uses this information to identify the location for a folder being migrated. Since the runtime information is not available during migration, the %CurrentCust% variable must be properly set in the magic.ini file prior to migrating each folder.

Alternatively, you can provide this value in the [Logical Names] section of the MigrateUniPaasData.ini. See example below.

[Logical Names]¶

MigrateUniPaasData resolves logical names using the magic.ini file. However some names are determined at runtime (see example in the MagicIni section) and therefore are not available during the migration. Those values can instead be placed in the [Logical Names] section of the MigrateUniPaasData.ini file. For example:

[Logical Names]

CurrentCust = FLstore

When a value appears in both the magic.ini file and the MigrateUniPaasData.ini file, the value in the MigrateUniPaasData.ini file overrides the value in magic.ini.

[Temp Tables]¶

The [Temp Tables] section is where you list the tables to be omitted from the migration. This includes tables to skip when migrating a specific directory, for example, when migrating the CORPORATE directory you want to skip all of the regional tables. This also includes temporary tables that don’t need to be migrated. Enter the table ID, followed by an optional comment to help you identify the table. For example:

[Temp Tables]

100 = Temp Table1

Creating the migration files¶

You can specify the configuration settings for MigrateUniPaasData:

• Using command-line arguments

• In an mds.ini file

• In an MigrateUniPaasData.ini file

NOTE: Settings entered on the command-line override settings in the ini files

For our examples, we provide all the settings in the mds.ini and MigrateUniPaasData.ini files. Placing settings in the mds.ini file means they can be used by the drivers at runtime.

The diagram below shows our starting layout on the left. In order to perform the migration, we will create several batch files and several ini files in each directory.

Creating the MigrateUniPassData batch files

Two batch files are created in each of the CORPORATE, FLstore and GAstore directories. One performs the migration and the other verifies that the migration was successful. The content of the batch files is the same in all three directories.

\_DoMigrate.bat

Runs the MigrateUniPassData migration utility and outputs results to Migration.log.

set path=C:\Program Files (x86)\Mertech Data Systems\DB Drivers\Btrieve\bin;%path%

MigrateUniPaasData full . >_Migration.log

cmd /k

\_DoValidate.bat

Runs the MigrationValidator_uniPaas verification utility after the migration is complete and outputs results to Validation.log.

set path=C:\Program Files (x86)\Mertech Data Systems\DB Drivers\Btrieve\bin;%path%

MigrationValidator_uniPaas . >_Validation.log

cmd /k

Creating the MigrateUniPassData mds.ini files¶

An mds.ini file is also created in each data directory. Settings in the mds.ini files control how tables are created and accessed on the SQL server. The mds.ini file is the key to successfully migrating a multi-directory layout.

• For a description of the mds.ini file tokens see mds.ini file

Example mds.ini files are shown below. These files demonstrate the use of the INT_Folder token to consolidate the INT files in two folders, one for corporate tables and one for the regional store tables. These files also show the settings to be used for each of the migration options. Settings in the example files are listed under the [SQL_BTR] heading meaning they are specific to Microsoft SQL Server.

Select the mds.ini files settings for the migration option that best suits your environment.

NOTE: Instead of creating CORPORATE, FLstore and GAstore directories for the mds.ini files as shown in the examples, you can use the MdsSetSetting API to create virtual mds.ini file in memory for each directory. For example:

MdsSetSetting("C:\SampleMultiCompanyLayout\CORPORATE","INT_Folder", "..\intfiles_corporate")

MdsSetSetting("C:\SampleMultiCompanyLayout\CORPORATE","Server", "sqlsrv1\sql2012")

• See also Setting global and folder specific values programmatically

Option 1: Migrate each directory to a different server¶

PROs

• An easy way to perform load balancing by distributing the data across multiple computers, CPUs, hard disks, etc.

• You can assign different user credentials to the different servers.

CONs

• Transactions will not cross multiple “customers” since the driver will have a unique connection to the database for each data directory.

• There is more administrative overhead associated with backing up and maintaining the additional hardware and software.

mds.ini files in:

Option 2: Migrate each directory to a different database¶

PROs

• An easy way to perform load balancing by distributing the data across multiple computers, CPUs, hard disks, etc.

• You can assign different user credentials to the different databases.

CONs

• Transactions will not cross multiple “customers” since the driver will have a unique connection to the database for each data directory.

• There is more administrative overhead associated with backing up and maintaining the additional hardware and software.

• When tables are migrated to multiple databases, the driver must have a separate set of connection(s) open for each database and must switch context each time a file from a different database is accessed. This can have an impact on the server. The context switching can also add performance overhead on the client depending on the order of calls and how frequently the switch is made.

mds.ini files in:

Option 3: Migrate each directory to a different schema (user on Oracle)¶

PROs

• There is a clean distinction between “sets” of data.

• You can assign different user credentials to each schema.

• The list of tables in each schema is as small as possible.

CONs

• There is a little more administrative overhead maintaining the additional schemas.

mds.ini files in:

Option 4: Choose a unique table prefix (or postfix) for each directory¶

PROs

• This option is the easiest to implement.

• The same approach works in all backends.

CONs

• The table list can become very large.

• It is harder to assign separate user access control.

• Oracle’s 30 character limit on identifiers can severely hinder this option.

mds.ini files in:

Creating the MigrateUniPaasData.ini files¶

A MigrateUniPaasData.ini file is also created in each data directory. Settings in the MigrageUniPaasData.ini file help to determine how definitions in the application source files are interpreted. A sample MigrateUniPaasData.ini file is installed in the <Programfiles>Mertech Data Systems\DB Drivers\Btrieve\bin\directory.

• For a description of settings see MigrateUniPaasData.ini File

MigrateUniPaasData.ini files in:

Creating the MigrationValidator_uniPaas.ini files¶

The MigrationValidator_uniPaas.ini file in each directory contains settings used during the validation. Settings should be the same as those in the MigrateUniPaasData.ini file.

• See also Migration Validator Tool for uniPaaS Applications

One more IMPORTANT consideration¶

A key factor to the success of the migration is the existence of ALL the data files to be migrated.  While the migration utility can determine most of the file structure from the application XML files, the utility needs to examine the actual data file to get it right.

Since Magic creates files on the fly, there are often lots of data files that are missing from the project directories. To ensure all files are present, you might want to create a script that accesses each file, causing Magic to create an empty data file if the file does not exist.

Migrating and deploying your UniPaaS application

Follow these steps to migrate and deploy your application.

1. Run the \_DoMigrate_.bat file to perform the migration. Examine the Migration.log file.

2. Run \the_DoValidate_.bat file to confirm that the migration was successful. Examine the Validation.log file.

3. Copy the deployment directory to the production site.

The deployment directory structure from our example should look like this.

• The batch files (_DoMigrate.bat and \_DoValidate.bat) are no longer needed.

• The migration ini files (MigrateUniPaasData.ini and MigrationValidator_uniPaas.ini) are no longer needed.

• The data files (.btr) are no longer needed.

• The INT files are in dedicated directories, one for corporate (intfiles_corporate) and one for regional stores (intfiles_regions). The driver uses these files at runtime to determine the structure of migrated tables.

• Each data directory has an mds.ini file that contains the location of the INT files, target server, database, schema, login information and (optional) table prefix. The drivers use the mds.ini files (along with global settings in the mds_global.ini file) at runtime.

  NOTE: Alternately, instead of creating data directories to store the mds.ini files, you can create the mds.ini files in memory using the MdsSetSetting API.

4. Replace the Btrieve access dlls, wbtrv32.dll and/or w3btrv7.dll that currently reside in the PVSW\BIN directory with the Mertech drivers in the C:\Program Files\Mertech Data Systems\DB Drivers\Btrieve\deploy\ <subdirectory> directory.

NOTE: Save a copy of the original Pervasive dlls before you replace them. Many of the Pervasive tools require these dlls. For instance, if the table definitions need to be corrected, the original Pervasive dlls must be restored.

Creating tables on the fly¶

If your application creates tables on the fly, the Mertech driver will automatically handle this without any need to modify your source code. When a B_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.

• See also B_CREATE API

Deleting tables¶

Magic programmers 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 Magic programmers 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. These commands are implemented using the CallDLLS function, described at:

http://ftp.magicsoftware.com/www/help/MG9/expres_1/HDK3B9C3A80.htm

B_DROP_FILE¶

#define B_DROP_FILE (B_OPEN + 3000)

Drops the SQL table and removes the INT file. The XML definition remains in the application source files.

Parameters

Example

CallDLLS ('w3btrv7.BTRCALL','2444A112',3000,0,0,0,Trim([table_name]), ASCIIChr(Len(Trim([table_name]))), ASCIIChr(0)) = 0

NOTE: To prevent an INT file from being deleted when a table is dropped, you can set the PERMANENT_INT token in the INT file to YES (the default setting is NO). This is useful if for example, you want to drop and then later recreate a file using the same structure. Refer to the BTR2SQL User’s Guide of additional information.

B_TRUNCATE_FILE¶

#define `B_TRUNCATE_FILE <file:///C:\Program%20Files%20(x86)\Mertech%20Data%20Systems\DB%20Drivers\Btrieve\sdk\docs\group___mds_header.html#gb7d407fd5c937f583f9c5814ac6e230d>`__  (B_OPEN + 2000)

Deletes all the records in the file.

Parameters

Example

CallDLLS ('w3btrv7.BTRCALL','2444A112',2000,0,0,0,Trim([table_name]), ASCIIChr(Len(Trim([table_name]))), ASCIIChr(0)) = 0

• See also Additional Btrieve APIs

Creating a new regional store¶

It is likely that your UniPaaS application will add new directories (regional stores) as time goes by. Take the following steps to do this.

Using a table-prefix¶

1. Create the directory for the new store (for example, NYstore).

2. Create an mds.ini file in that directory.

[SQL_BTR]

INT-Folder=..\intfiles_regions

Server= sqlsrv1\sql2012

Database=SQLDB

Schema=dbo

UseTrustedConnection=no

User=mydomain\me

Password=4c8fe10aad3

Table-Prefix=NY

3. Now, accessing the tables will cause uniPaaS to issue a Btrieve B_CREATE:

B_CREATE(NYstore\Customers)

B_CREATE(NYstore\Orders)

The driver reads the mds.ini file in the NYstore data directory and uses the INT_Folder token to locate the INT files. The driver uses the table template in the INT file to create the new tables with the NY_ prefix.

NOTE: In the example above, the mds.ini file is stored on disk in a separate directory for each store. Instead, you can use the MdsSetSetting API to create virtual mds.ini files. For example:

MdsSetSetting("C:\SampleMultiCompanyLayout\NYstore","INT_Folder", "..\intfiles_regions")

MdsSetSetting("C:\SampleMultiCompanyLayout\NYstore","Server", "sqlsrv1\sql2012")

MdsSetSetting("C:\SampleMultiCompanyLayout\NYstore","Database", SQLDB")

MdsSetSetting("C:\SampleMultiCompanyLayout\NYstore","Schema", "dbo")

MdsSetSetting("C:\SampleMultiCompanyLayout\NYstore","UseTrustedConnection", "no")

MdsSetSetting("C:\SampleMultiCompanyLayout\NYstore","User", "mydomain\me")

MdsSetSetting("C:\SampleMultiCompanyLayout\NYstore","Password", "0x4c8fe10aad3")

MdsSetSetting("C:\SampleMultiCompanyLayout\NYstore","Table-Prefix", "NY")

• See also Setting global and folder specific values programmatically

In a separate database¶

1. Create a new SQL database (for example, SQLDBNY). This can be done using SQL modeling tools or in your application by calling the BTRV/BTRCALL api B_SQL_EXECUTE (documented in the SDK) to execute a CREATE DATABASE command.

strcpy(query, "CREATE DATABASE SQLDBNY");

bStat= BTRCALL(B_SQL_EXECUTE,&cursor1,&query,&(dataLen=(BTI_WORD)strlen(query)),NULL,0,0);

• Examples to show how to use Embedded SQL to create and drop databases and users are provided in <Program Files>\Mertech Data SystemsDB Drivers\Btrieve\sdk\Samples\MdsApis\C

2. Create the directory for the new store (for example, NYstore).

3. Create an mds.ini file in that directory.

[SQL_BTR]

INT-Folder=..\\intfiles_regions

Server= sqlsrv1\\sql2012

Database=SQLDBNY

Schema=dbo

UseTrustedConnection=no

User=mydomain\\me

Password=4c8fe10aad3

4. Now, accessing the tables will cause uniPaaS to issue a Btrieve Create the new tables using B_CREATE:

B_CREATE(NYstore\Customers)

B_CREATE(NYstore\Orders)

The driver reads the mds.ini file in the NYstore data directory and uses the INT_Folder token to locate the INT files. The driver uses the table template in the INT file to create the new tables in the SQLDBNY database.