XML Deployment for New Installations

When deploying BTR2SQL to a new customer site or a new machine, you need to create the SQL tables, indexes, and INT files on the target system. Rather than running the GUI Migration Utility manually on each machine, you can automate this process using MdsMigrateTable with an XML configuration file.

This approach is especially valuable for software vendors who need a repeatable, scriptable deployment that can be built into an installer.

How It Works

  1. During development, you migrate your tables using the GUI Migration Utility or MdsMigrateTable and verify that everything works.

  2. You create an XML file that describes all the tables, fields, indexes, and migration options for your application. This file can be generated from your existing DDFs/INT files or written by hand.

  3. At install time, your installer runs MdsMigrateTable with the XML file to create the tables on the customer’s SQL backend and generate the INT files needed at runtime.

Example Workflow

A typical installer script might include:

REM Create tables and INT files on the target SQL backend
MdsMigrateTable /config MyApp_Tables.xml /server SQLSERVER01 /database MyAppDB /user sa /password *** /createtable /createint /dll pgs_btr.dll

REM Copy data from Btrieve files if this is a migration (not a fresh install)
MdsMigrateTable /config MyApp_Tables.xml /server SQLSERVER01 /database MyAppDB /user sa /password *** /copydata /dll pgs_btr.dll

For a brand-new installation where there is no existing Btrieve data to migrate, you only need /createtable and /createint. The application starts with empty tables and the INT files are ready for the driver to use.

XML Configuration File

The XML file defines your entire schema. Use the Btrieve2SqlFullMigration variant when DDFs are not present on the target machine (the typical case for a fresh deployment):

<?xml version="1.0" encoding="utf-8"?>
<Btrieve2SqlFullMigration Driver="PGS_BTR">

  <!-- Global defaults -->
  <Table Name="" Schema="public" OverwriteExistingTable="n"
         RememberServerName="y"/>

  <!-- Individual tables -->
  <Table Name="CUSTOMERS" Filename="customers.mkd">
    <Fields>
      <Field Name="CUST_ID" BtrDataType="15" Offset="0" Size="4" />
      <Field Name="CUST_NAME" BtrDataType="0" Offset="4" Size="50" />
      <!-- ... additional fields ... -->
    </Fields>
    <Indices>
      <Index Number="0" Unique="y" PrimaryKey="y">
        <Segment Number="1" Field="CUST_ID" />
      </Index>
    </Indices>
  </Table>

</Btrieve2SqlFullMigration>

For a complete reference of all XML elements and attributes, see the Migration XML Configuration Reference.

If DDFs are available on the target, you can use the simpler Btrieve2SqlMigration variant and let the DDFs supply the base definitions while the XML overrides specific settings.

Key MdsMigrateTable Options

The following options are commonly used during deployment:

Option

Description

/config <file>

Path to the XML configuration file.

/createtable

Creates the SQL tables defined in the XML.

/createint

Generates INT files for runtime use by the driver.

/validate

Validates that the migration completed correctly.

/server, /database, /user, /password

Connection details for the target SQL backend.

For full documentation on all available options, see MdsMigrateTable.

Best Practices

  • Version your XML files alongside your application source code. When your schema changes, update the XML and use it to apply changes at customer sites.

  • Use global defaults (a <Table Name=""> entry) to avoid repeating common settings like schema name, bulk copy parameters, and overwrite behavior across every table.

  • Test the deployment script on a clean machine before shipping to customers. The XML-based deployment should produce the same result as a manual GUI migration.

  • Include the XML file in your installer so it is available for re-running if a customer needs to recreate their database.

See also