MdsMigrateTable

MdsMigrateTable is a command-line utility for migrating Btrieve (Actian) table structures and data to an SQL backend. It can create tables, copy row data, generate INT files, prepare databases, produce SQL scripts, or perform a full end-to-end migration — making it the primary tool for scripted and automated migration workflows.

MdsMigrateTable can be used instead of the GUI Migration Utility.

Important

MdsMigrateTable requires access to the Actian (Pervasive) server and the Actian client DLLs in order to read the source Btrieve data during migration.

Command-line Syntax

Run MdsMigrateTable from a command prompt. The easiest way is to use the Btr2SQL Command Prompt shortcut from the Windows Start menu, which opens a prompt with the bin directory already on the PATH.

MdsMigrateTable <operation> <scope> /ddf <DDF Folder> [options]

The command takes an operation that determines what work to perform, a scope that determines which tables to include, the /ddf parameter pointing to the Data Definition Files, and any additional options. Different operations accept different combinations of parameters — see each section below for details.

Operation (Required)

The first parameter tells the tool what steps to perform.

Value

Description

Migrate

Create tables, indexes, and INT files, then copy all row data. This is the most common operation for a first-time migration.

CreateTable

Create tables, indexes, and INT files on the server only (no data copy).

CopyData

Copy Btrieve row data to existing SQL tables. Errors will be generated if the rows being copied already exist in the target table. If the intent is to replace the target data, use the /overwrite option to drop the contents of the target table first.

CreateInt

Create INT files only (no server connection needed).

CreateScript

Generate an SQL script for creating the tables (no server connection needed).

Verify

Validate that the data already on the SQL backend matches the source Btrieve files. This operation skips the migration and only validates existing data. Requires the /validate-data option. Useful for scripted workflows or verifying an existing migration.

PrepareDB

Prepare the target database by installing stored procedures that BTR2SQL uses at runtime. PrepareDB is automatically called when you migrate for the first time using any other operation, but it is also available as a standalone operation because it requires elevated database privileges. In environments where the migration user does not have sufficient privileges, a DBA can run PrepareDB separately with a privileged account before the migration user runs the actual migration. PrepareDB does not require the /ddf parameter or a scope — only connection details. Returns an exit code of 0 on success and non-zero on failure, which is useful for scripting.

Note

INT files are created in the same location as the data files unless redirected by the INT-Folder setting in the mds.ini file.

Scope (Required except for PrepareDB)

The second parameter tells the tool which tables to include.

Value

Description

AllUserTables

Migrate all user tables defined in the DDFs, excluding the hidden x$ system tables. This is normally the scope you should use unless you specifically intend to migrate the x$ tables.

AllTables

Migrate all tables defined in the DDFs, including the hidden x$ system tables. Use this only if you need the x$ tables migrated to the SQL backend.

OneTable

Migrate a single table. Use /table to specify the table name.

AllConfig

Migrate tables defined in an XML configuration file. Use /config to specify the file.

DDF Path (Required except for PrepareDB)

/ddf <DDF Path> — specifies where to find the Data Definition Files (DDFs). This can be:

  • A folder path (full, relative, or . for the current directory) — when a folder is given, the tool assumes the DDFs use the default filename file.ddf.

  • A file path — if your database uses v2 DDFs (pvfile.ddf), you must pass the explicit path to the DDF file rather than the folder.

Options

All options are optional unless otherwise noted. Different operations accept different subsets of these options.

Connection Options

Option

Description

/server <server name>

Destination SQL server and optional port number.

/database <database name>

Destination database.

/schema <schema name>

Destination database schema.

/user <user name>

User name for server login.

/password <password>

Password for server login.

/trustedConnection

Use Windows authentication instead of username/password. When specified, /user and /password are discarded. MS SQL only.

/dll <dll>

Full path to the migration DLL (sql_btr.dll, ora_btr.dll, or pgs_btr.dll). Defaults to sql_btr.dll. If the full path is not specified, the DLL is loaded from the system PATH.

Important

The migration process must use these migration-specific DLLs. It cannot use the version of the Mertech DLLs that your application runs with.

Note

If the server, target database, and/or login credentials are not provided, the mds.ini file, registry settings, or Login dialog box provide these details.

Table Selection Options

Option

Description

/table <table name>

Name of the table to migrate (as listed in the DDFs). Required when scope is OneTable.

/owner <owner name>

The Btrieve file owner name (what Btrieve calls a “password” on a file). If the owner name contains special characters, enclose it in quotes (e.g., /owner "my owner").

/overwrite

Overwrite existing SQL tables during migration. For CopyData, this drops the contents of the target table before copying.

/config <xml config filename>

XML document defining migration configuration. Required when scope is AllConfig. See XML Config File below.

Data Copy Options

These options control behavior during the CopyData and Migrate operations.

Option

Description

/numThreads <n>

Number of worker threads to use when copying data. By default, multiple threads are used to speed up migration. Pass /numThreads 1 to disable multithreading.

/startAt <record position>

Begin migration from this record position.

/endAt <record position>

End migration at this record position.

/maxRows <num rows>

Maximum number of records to copy during data migration.

/recordsList <filename>

File containing a list of records to be copied again.

/outputFailed <filename>

File to store the list of records that failed to save.

/strict

Do not migrate a row that fails for any reason. Without this flag, failing rows may be skipped while migration continues.

Validation Options

These options validate migrated data by reading it back from the SQL backend and comparing it to the original Btrieve source. Validation can be combined with a migration operation or run on its own.

Option

Description

/validate-data

Read back the migrated data from the SQL backend and compare it to the original Btrieve file. Any mismatches are reported. Can be combined with any operation that copies data (e.g. Migrate or CopyData). Required when the operation is Verify.

/outputValidate <filename>

File to receive any validation discrepancies found when comparing Btrieve and SQL data. Requires /validate-data.

Diagnostics Options

Option

Description

/trace <trace filename>

Path and filename for trace output.

/level <trace level>

Level of tracing (-3 through 6). See Trace Levels below.

/nopause

Do not wait for a key press at the end.

Trace Levels

Level

Name

Description

-3

Error

Only messages generated because of an error situation. Messages are preceded by ERROR: or WARNING:.

-2

Btrieve

Btrieve operation information and errors only.

-1

Performance

Performance warnings. Messages are preceded by Performance:.

0

Debug

Basic output — flow of application. Shows begin/end transactions, locks gained/released, record reads.

1

Detail 1

Field values in records read/written. Btrieve input/output buffers.

2

Detail 2

The main debugging level — fills in more details above level 1 to help track down a problem.

3

Detail 3

Extra information along the way, usually only needed for debugging. Includes MemState, field values during Insert, and index saves.

4

Detail 4

Includes XML doc during migration, column info for bindings, some extra LOB and GetNext output.

5

Detail 5

Strictly for function Begin/End markers.

6

Detail 6

Strictly for handles and other frequently changing information — highly detailed debugging info.

Examples

Migrate all user tables to MS SQL using Windows authentication:

MdsMigrateTable Migrate AllUserTables /ddf . /server DEV-PC\SQLEXPRESS /database MyAppDB /trustedConnection /dll sql_btr.dll

Performs a complete migration — creates tables, indexes, INT files, and copies all row data. Uses the current directory (.) as the DDF folder. Connects to the SQL Express instance on DEV-PC using Windows authentication, so no username or password is needed. AllUserTables excludes the hidden x$ system tables. The user must have appropriate permissions on the SQL server to create tables and insert data.

Migrate all user tables to PostgreSQL with explicit credentials:

MdsMigrateTable Migrate AllUserTables /ddf "C:\Data\DDFs" /server pgserver /database myappdb /user postgres /password secret123 /dll pgs_btr.dll

Same as above but targets PostgreSQL. The /dll parameter specifies the PostgreSQL migration DLL. Credentials are provided explicitly.

Migrate a single table:

MdsMigrateTable Migrate OneTable /ddf . /table Billing /server DEV-PC\SQLEXPRESS /database MyAppDB /user sa /password secret123 /dll sql_btr.dll

Migrates only the Billing table. The /table parameter is required when the scope is OneTable. The /dll parameter specifies the SQL Server migration DLL.

Copy data only, overwriting existing rows:

MdsMigrateTable CopyData AllUserTables /ddf . /server DEV-PC\SQLEXPRESS /database MyAppDB /trustedConnection /overwrite /dll sql_btr.dll

Copies Btrieve row data into existing SQL tables, dropping the target table contents first because /overwrite is specified. Useful when re-running a data copy after a previous migration has already created the table structures. The /dll parameter specifies the SQL Server migration DLL.

Copy data with multiple workers and tracing:

MdsMigrateTable CopyData AllUserTables /ddf . /server DEV-PC\SQLEXPRESS /database MyAppDB /trustedConnection /numThreads 4 /trace migration.log /level -3 /dll sql_btr.dll

Uses 4 worker threads to copy data in parallel, with Detail -3 (errors/warnings only) tracing written to migration.log for debugging. The /dll parameter specifies the SQL Server migration DLL.

Generate INT files only (no server needed):

MdsMigrateTable CreateInt AllUserTables /ddf "C:\Data\DDFs" /dll pgs_btr.dll

Creates INT files for all user tables without connecting to any SQL server. Useful for preparing a deployment before the target database is available. The /dll parameter specifies the PostgreSQL migration DLL.

Generate an SQL script (no server needed):

MdsMigrateTable CreateScript AllUserTables /ddf . /dll sql_btr.dll

Produces an SQL script for creating the tables. No server connection or credentials are required. The /dll parameter specifies the SQL Server migration DLL.

Validate data after migration:

MdsMigrateTable Migrate AllUserTables /ddf . /server DEV-PC\SQLEXPRESS /database MyAppDB /trustedConnection /validate-data /dll sql_btr.dll

Performs a migration and then reads back every row from the SQL backend to compare against the original Btrieve data. Any mismatches are reported.

Validate an existing migration without re-migrating:

MdsMigrateTable Verify AllUserTables /ddf . /server DEV-PC\SQLEXPRESS /database MyAppDB /trustedConnection /validate-data /dll sql_btr.dll

Skips the migration entirely and only validates that the data already on the SQL backend matches the source Btrieve files. Useful for verifying a previous migration or as a scheduled check.

Prepare the database separately with elevated privileges:

MdsMigrateTable PrepareDB /server DEV-PC\SQLEXPRESS /database MyAppDB /user sa /password adminpass /dll sql_btr.dll

A DBA runs this once with elevated privileges to install the stored procedures BTR2SQL needs at runtime. Afterwards, the migration user can run the actual migration with lower-privilege credentials. The /dll parameter specifies the SQL Server migration DLL. PrepareDB returns an exit code (ERRORLEVEL) of 0 on success and non-zero on failure, so it can be checked in batch scripts or CI pipelines.

Migrate from an XML config file (no DDFs or Btrieve DLLs needed):

MdsMigrateTable CreateTable AllConfig /config tables.xml /server DEV-PC\SQLEXPRESS /database MyAppDB /trustedConnection /dll sql_btr.dll

Creates SQL tables from the data definitions in tables.xml instead of from DDFs. See XML Config File below for details. The /dll parameter specifies the SQL Server migration DLL.

XML Config File

The /config parameter accepts an XML file that contains complete table and field definitions in place of — or in addition to — the information normally read from DDFs and Btrieve data files. When used with the AllConfig scope, the XML config file replaces the /ddf parameter entirely.

This makes the XML config file useful in several scenarios:

  • Setting up a new system without source Btrieve files — the XML file contains the full data definitions needed to create SQL tables and INT files. No Btrieve files, DDFs, or Actian DLLs are required on the machine.

  • Overriding DDF definitions — when the structure of the Btrieve files cannot be rendered correctly in the DDFs, the XML config file provides a way to define the correct structure for migration.

  • Keeping a structure template — the XML file can serve as a reusable template for dynamically creating tables later, independent of the original Btrieve environment.

  • Fine-tuning migration settings — the XML file can also adjust migration behavior per table or globally, such as whether to overwrite existing tables, Oracle tablespace settings, or field nullability.

When used alongside DDFs (with the AllTables or OneTable scope), the XML config file acts as an override — you only need to include the pieces you want to change. When used with the AllConfig scope, the XML file is the sole source of table definitions.

For the complete XML format specification — including all elements, attributes, data types, and worked examples — see the Migration XML Configuration Reference.

Note

Sample XML files and the DTD (which describes the legal building blocks for the XML config file) can be found in <Program Files>\Mertech Data Systems\DB Drivers\Btrieve\sdk\samples\migration.

See Also