BTRV Edition User's Guide

ctmigra

ctmigra is a general purpose data migration utility for converting non-c-tree data for use with FairCom RTG. It can be used with multiple external data types, including Btrieve data files. (For certain data types, such as Btrieve, this also requires access to your original external libraries used to access incoming source files in their native format, and ctmigra has ability to link with these libraries as required.)

The ctmigra utility migrates data by reading records from existing external tables and writing them to FairCom RTG files. Supported interfaces include ExtFH (for access to Micro Focus COBOL files) and BTRV (for access to Btrieve files). It also supports other file handlers.

ctmigra is located in the tools\cmdline directory of your FairCom RTG installation. A graphical interface version RTG Migrate is also available providing similar functionality in an easy to view window. You'll find this in your tools/guitools.java of your FairCom RTG installation.

The next sections provide a description of the command and its usage.

In This Section Using the ctmigra utility BTRV Conversion Example Micro Focus COBOL Migration Example

Using the ctmigra utility

Usage of FairCom RTG ctmigra depends on your native data file types and your platform.

Usage

ctmigra btrv|extfh [OPTIONS] SOURCE DEST

where:

• SOURCE - name of the file to be copied.
• DEST - name of the file to which it will be copied.

Options for FairCom RTG Files

• -n SERVERNAME or --dest-server=SERVERNAME where SERVERNAME is the name of the destination FairCom DB Server
• -u USERID or --dest-user=USERID where USERID is the user name of the destination FairCom DB Server
• -p PASSWORD or --dest-password=PASSWORD where PASSWORD is the user password of the destination FairCom DB Server
• -I STRING or --dest-idx-suffix=STRING where STRING is the suffix of destination index file name
• -N SERVERNAME or --source-server=SERVERNAME where SERVERNAME is the name of the source FairCom DB Server
• -U USERID or --source-user=USERID where USERID is the user name of the source FairCom DB Server
• -P PASSWORD or --source-password=PASSWORD where PASSWORD is the user password of the source FairCom DB Server
• -i STRING or --source-idx-suffix=STRING where STRING is the suffix of source index file name
• -l FILE or --log=FILE where FILE is the name of the file to log additional information. To redirect log to stderr use ‑ as FILE
• -b RECORDS or --batch-size=RECORDS where RECORDS is the number of records to read / write in batches
• -a (--append-ext) appends index extension instead of replacing data extension.
• -o OWNER (--owner=OWNER) specifies the BTRV file owner (can be used if you encountered an error 51 when attempting to migrate).
• -r (--replace) instructs ctmigra to replace the existing destination file (V11 and later).
• -e, --encrypt=CIPHER - Encrypt destination file with CIPHER algorithm.
• -z, --datacompress=TYPE[;LEV][;STR] - Compress destination data file with TYPE algorithm.
• -t, --transaction=no|yes|logging - Create destination data file with or without transaction support.

  The last three options enable the following configuration options on the destination file (corresponding to -e, -z, and -t respectively):

<encrypt type="CIPHER">

<datacompress type="TYPE"= level="LEV" strategy="STR">

<transaction logging="no|yes">

See usage examples in the next topics. Notice that the Micro Focus COBOL Migration Example can be useful for Btrieve users.

External Library Configuration for Native File Access

For certain data types, such as BTRV, original external libraries are required to access native data formats.

• -s LIBRARY!FUNCTION or --source-lib=LIBRARY!FUNCTION where LIBRARY is the external dynamically loadable library and FUNCTION is the interface entry-point function to handle the source file
• -d LIBRARY!FUNCTION or --dest-lib=LIBRARY!FUNCTION where LIBRARY is the external dynamically loadable library and FUNCTION is the interface entry-point function to handle the destination file

Note: Current usage options are always available when no command-line options are supplied.

Examples

If you are using FairCom RTG COBOL Edition:

ctmigra.exe extfh -s MFFH.DLL -n FAIRCOMS@localhost -r C:\mydata\abc-btrv.dat abc-ctree.dat

If you are using FairCom RTG BTRV Edition:

ctmigra.exe btrv -s wbtrv32.dll -n FAIRCOMS@localhost -r C:\mydata\abc-btrv.dat abc-ctree.dat

For more examples, see Micro Focus COBOL Migration Example.

 

ctmigra --quiet and --verbose options to select output information

These options for the ctmigra command-line utility suppress all output (--quiet or -q) or select the information to be sent to stdout (--verbose=LEVEL or -v). The --verbose parameter is a bitmask which can combine the following values:

1 - show message about final result

2 - show percentage progress

4 - show time spent in migration phases (read, write, finalize)

For example, to display everything, use --verbose=7, which is 1+2+4. If not specified, the --verbose level is 3 (1+2).

The --quiet option is identical to --verbose=0.

Alternative Usage

Most of the information you need for migration can be entered using the command-line parameters listed above. If you have additional considerations that dictate a more complex configuration, such as files that need to be treated specially, multiple clients, servers, etc., you can create a local configuration file (ctree.conf) for use during migration. (It can be edited as described in Editing a Configuration File.)

Note: The recommended best practice is to run ctmigra using the parameters listed above. If you must use the "alternative" approach described in this section, use the bulkaddition option in ctree.conf, which will greatly improve performance and it will optimize the index.

To use ctmigra with a local FairCom RTG configuration file, use the following command:

ctmigra btrv|extfh -c CONFIG_FILE SOURCE DEST

where:

• SOURCE - name of the file to be copied
• DEST - name of the file to which it will be copied
• -c CONFIG_FILE or --config=CONFIG_FILE where CONFIG_FILE is a valid FairCom RTG configuration file.

Be sure to include the bulkaddition option in ctree.conf.

Potential Errors and Troubleshooting

BTRV Error: -7	Your native source library is likely not available. Check the path to your native data file handling library and be sure it is specified with the --source-lib= option.
BTRV Error: 53	Attempted to open a non-BTRV file via a BTRV interface. This can possibly happen when you load a 32-bit BTRV DLL with a 64-bit version of the tool, or vice versa.

In FairCom RTG V2, error messages displayed by the ctmigra utility have been enhanced as follows:

• It now displays actual file names instead of $SOURCE$ and $DEST$.
• It now displays an error message if the source or destination c-tree Servers are not running (c-tree error 133).
• It now displays an error message if the user/password is not correct (c-tree error 450/451) or GUEST logon is disabled (c-tree error 470).
• It now displays an error message if c-tree Server is not valid due to OEM version incompatibility (c-tree error 530).
• It now displays an error message if the specified external library cannot be loaded.

Behavior Change: This modification changes the behavior of the ctmigra tool.