FairCom RTG BTRV User Guide

ctcbtran

The ctutil utility can be renamed to ctcbtran. In this case, it functions as an ad-hoc utility to turn on/off transaction processing. The parameter is the name of a file that contains a list of files to modify (one file name per line).

Notice that the utility functions similar to ctutil -tron except that the parameter is the name of a file listing the files to modify instead of the name of the table to modify.

Usage

ctcbtran list_file T|P|F|W

• list_file - specify the name of a file that contains a list of files to be modified, one file name per line. Specify the file names as you would when passing a file name to ctuitl -tron.
• T - Enable full transaction processing control (ctTRNLOG c-tree file mode). This mode is recommended for most applications and it is required to take full advantage of FairCom RTG/ISAM advanced features.
• P - Enable logical transaction processing control without logging (ctPREIMG c-tree file mode). This is the default mode and is indicated where both transaction atomicity and high performance are required. By suppressing transaction logging it is possible to achieve high data throughput at the expense of data recoverability. This mode is recommended in environments protected from system crashes or cases in which data integrity/recoverability is not an issue.
• F - Asynchronous writes. This mode should only be used on files which data integrity is not critical as data recovery is not guaranteed in case of a system crash.
• W - Synchronous writes (ctWRITETHRU c-tree file mode). This mode is indicated where transaction processing is not suitable yet data safety is still critical.

Example

ctcbtran myfiles

The myfiles file would list the files to be modified with one file name on each line, for example:

datafile01

datafile02

datafile03

See also -tron.

ctmigra - Conversion Utility

Convert C-ISAM or Btrieve tables to FairCom RTG/ISAM.

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

Usage

ctmigra ISAM|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/ISAM 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 ISAM 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 ISAM, 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:

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

If you are using FairCom DB ISAM:

ctmigra.exe ISAM -s wISAM32.dll -n FAIRCOMS@localhost -r C:\mydata\abc-ISAM.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/ISAM configuration file, use the following command:

ctmigra ISAM|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/ISAM configuration file.

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

Potential Errors and Troubleshooting

ISAM 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.
ISAM Error: 53	Attempted to open a non-ISAM file via a ISAM interface. This can possibly happen when you load a 32-bit ISAM 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.

In This Section Standalone Support for ctmigra

Standalone Support for ctmigra

FairCom RTG supports the FairCom Standalone operational model for specific use cases. This differs from the default client/server model by not using the FairCom RTG Database Server (faircom.exe, or ctreesql.exe in versions prior to V3). By not going through the FairCom RTG 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 FairCom RTG Standalone library where library is a FairCom RTG 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 FairCom RTG 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 FairCom RTG 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:

• -n (or -N) used for specifying the FairCom RTG Server name
• -u (or -U) for specifying the user ID
• -p (or -P) used for specifying the user ID password

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 FairCom RTG Server. The SECT setting provides a dynamic method for setting the matching FairCom RTG Server PAGE_SIZE setting. Note this equation: SECT*128 bytes = PAGE_SIZE. The default PAGE_SIZE for FairCom RTG 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 FairCom RTG < V3
128	16384
256	32768	Default FairCom RTG 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 FairCom RTG 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.