|
|
|
ctmigra is a general purpose data migration utility for converting non-c-tree data for use with c-treeRTG. It can be used with multiple external data types, including COBOL 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 c-treeRTG 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 c-treeRTG 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 c-treeRTG installation.
The next sections provide a description of the command and its usage.
|
|
|
Usage of c-treeRTG ctmigra depends on your native data file types and your platform.
Usage
ctmigra btrv|extfh [OPTIONS] SOURCE DEST
where:
Options for c-treeRTG Files
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.
Note: Current usage options are always available when no command-line options are supplied.
Examples
If you are using c-treeRTG COBOL Edition:
ctmigra.exe extfh -s MFFH.DLL -n FAIRCOMS@localhost -r C:\mydata\abc-btrv.dat abc-ctree.dat
If you are using c-treeRTG 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 c-treeRTG configuration file, use the following command:
ctmigra btrv|extfh -c CONFIG_FILE SOURCE DEST
where:
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 c-treeRTG V2, error messages displayed by the ctmigra utility have been enhanced as follows:
Behavior Change: This modification changes the behavior of the ctmigra tool.
|
|
|
Note: This example can be useful for Btrieve users as well as COBOL users.
To copy and covert data from Micro Focus COBOL tables into c-treeRTG, use ctmigra as follows:
ctmigra extfh -s C:\MICROFOCUS\lib\MFFH.DLL!MFFH S:\Data.MF\MYFILE D:\Data.RTG\MYFILE.dat
To use ctmigra with Unix-based Micro Focus libraries, be sure to pre-load them with the LD_PRELOAD environment variable or an alternative mechanism.
For example, on an AIX 64-bit platform (this is all on a single command line):
LDR_PRELOAD64=libcobrts64.3.so:libcobcrtn64.3.so:libcobmisc64.3.so ctmigra extfh -s libcobrts64.3.so!EXTFH /data/mf/myfile /data/rtg/myfile.dat
For example, on a Linux 32-bit platform (this is all on a single command line):
LD_PRELOAD=libcobrts.so:libcobcrtn.so:libcobmisc.so ctmigra extfh -s libcobrts.so!EXTFH /data/mf/myfile /data/rtg/myfile.dat
|
|
|
c-treeRTG now supports the FairCom Standalone operational model. This differs from the default client/server model by not using the c-treeRTG Database Server (faircom.exe, or ctreesql.exe in versions prior to V3). By not going through the c-treeRTG Database Server, the database I/O can at times be faster, typically when there is only a single instance performing database I/O. If you are using multiple versions of ctmigra to migrate several files at the same time, then we don’t recommend using the Standalone model.
ctmigra --local=LIBRARY Option
The new ctmigra option --local=LIBRARY allows setting the c-treeRTG Standalone library where library is a c-treeRTG Standalone library.
The --local switch instructs ctmigra to work in the Standalone operational model. When this switch is set, the following switches are all disabled:
-n (or -N) used for specifying the c-treeRTG Server name
-u (or -U) for specifying the user ID
-p (or -P) used for specifying the user ID password
ctmigra --local-sect Option
This modification introduces a new option in ctmigra to set the number of node sectors when using the option --local. The new option is --local-sect=SECT where SECT is the number of node sectors to use in the <localinstance sect> attribute of the ctmigra auto-generated c-treeRTG configuration file.
The option --local-sect is indicated when the file migrated by the local engine (ctmigra option --local) will be open by a c-tree Server configured with a PAGE_SIZE set to a higher value then the default 8192 (8KB).
If --local-sect is not specified, the default value of <localinstance sect> is used, which is 64 resulting in a node of 8192 bytes (64 * 128 bytes) matching the default PAGE_SIZE of the c-tree Server.
If, for example, the c-tree Server has a PAGE_SIZE of 32768, the ctmigra --local command should also include --local-sect=256 so the local engine will create files that can be open by c-tree Server.
When this option is set, the following are all disabled:
The option --local-sect=SECT where SECT is the number of node sectors can be used to specify the node size used to create the c-tree file.
The number of node sectors to use when performing data migration is important to ensure the data file created during the ctmigra process are of the same PAGE_SIZE being used by the c-treeRTG Server. The SECT setting provides a dynamic method for setting the matching c-treeRTG Server PAGE_SIZE setting. Note this equation: SECT*128 bytes = PAGE_SIZE. The default PAGE_SIZE for c-treeRTG V3 is now 32,768, therefore the default SECT value is 256. Here are SECT values for setting the more common PAGE_SIZE settings:
SECT |
PAGE_SIZE |
|
|---|---|---|
64 |
8192 |
Default c-treeRTG < V3 |
128 |
16384 |
|
256 |
32768 |
Default c-treeRTG V3 |
512 |
65536 |
|
If --local-sect is not specified, the default value of <localinstance sect> is used, which is 256 for V3, and 64 for c-treeRTG versions prior to V3.
If, for example, the c-tree Server has a PAGE_SIZE of 16384, the ctmigra --local command should also include --local-sect=128 so the local engine will create files that can be opened by c-tree Server.
|
|
|
The attributes bufs and dbufs allow setting c-tree standalone index and data number of cache buffers respectively. The maximum acceptable value is 32,767.
The sect attributes set the table node size (which should match the server PAGE_SIZE). The maximum is 512.
