RTG data conversion

Migrating Your Data to FairCom RTG COBOL

Before your application is ready to use FairCom RTG COBOL, the data must be converted to a format that can be used by FairCom RTG. This is a one-time process that must be done before you can use FairCom RTG.

FairCom RTG provides a GUI tool to aid in migration, RTG Migrate, as well as a command-line utility, ctmigra.

SQL Access

If you will be accessing your data using SQL, you will need to see FairCom RTG SQL Access.

Configuring Your System

You can create a basic configuration file when you migrate your data with the RTG Migrate tool. This is done in the final step of the wizard, as described in RTG Migrate.

Much of the information you need for configuring your system is entered when you migrate your data, so the configuration file you create may handle your environment with no changes. If you have additional considerations that dictate a more complex configuration file, such as files that need to be treated specially, multiple clients, servers, etc., you will need to edit the resulting configuration file as described in Editing a Configuration File.

Convert AcuCOBOL Vision Data to FairCom RTG COBOL

This walkthrough describes how to convert existing COBOL data created with the ACUCOBOL Vision file system to FairCom RTG COBOL data.

If your COBOL program performs OPEN OUTPUT operations, set the file system to CTREE (see Runtime Configuration) before running your program to create files in c-tree format.

If you cannot create files with your COBOL application, ctutil can use your XFD files to create a new empty file having the same structure described by the XFD files.

The following steps are used to convert ACUCOBOL Vision files into c-tree files. If you have already created the c-tree files you can jump directly to step 2:

1. To create an empty file using FairCom RTG COBOL, execute ctutil -make passing the new file name and the XFD file containing its definition:

   1. ctutil -make myctdata mydata.xfd 

   2. This command will create a file named myctdata using the image string obtained from the mydata.xfd.
2. Dump the existing data from the existing mydata data file created using Vision by using the vutil32 -unload functionality:

   1. vutil32 -unload mydata mydata.dmp 

   2. This command will dump the entire contents of the mydata file to a plain text file called mydata.dmp
3. Load the dumped data into the file created in step 1 using the ctutil -load functionality:

   1. ctutil -load myctdata mydata.dmp A 

   2. This command loads the data from the plain text file called mydata.dmp and writes it to the mydata FairCom RTG COBOL data file.
4. Now the new FairCom RTG COBOL data file mydata can be read through the FairCom RTG COBOL SQL engine by running the following command:

   1. ctutil -sqlize myctdata mydata.xfd ADMIN ctreeSQL

   2. This command parses the mydata.xfd file and generates an XDD schema definition on the fly to be used by the FairCom RTG COBOL engine to import the data file as part of a SQL database.

Direct Conversion

There is example code in drivers/ctree.cobol/samples/acucobol/visionconvert for a direct conversion utility. This can be compiled under any AcuCOBOL environment. It will extra data from a native Vision format table and write into an RTG table.

Convert Microfocus ExtFH C-ISAM Tables with ctmigra

ctmigra is a general purpose data migration utility for converting non-c-tree data for use with FairCom RTG/ISAM. 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 FairCom RTG/ISAM files. Supported interfaces include ExtFH (for access to Micro Focus COBOL files) and ISAM (for access to Btrieve files). It also supports other file handlers.

ctmigra is located in the tools\cmdline directory of your FairCom RTG/ISAM 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/ISAM installation.

Example

Note: This example is appropriate for Btrieve tables and C-ISAM COBOL tables.

To copy and covert data from Micro Focus COBOL tables into FairCom RTG/ISAM, 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

See Also

ctmigra - Conversion Utility

Convert RM/COBOL Format Data to FairCom RTG COBOL

This walkthrough describes how to convert existing COBOL data created with the RM/COBOL file formats to FairCom RTG COBOL data.

If you cannot create files with your COBOL application, ctutil can use your XFD (or XDD) files to create a new empty file having the same structure described by the XFD (or XDD) files.

The following steps are used to convert RM/COBOL files into RTG files. If you have already created the RTG files you can jump directly to step 2:

1. To create an empty file using FairCom RTG COBOL, execute ctutil -make passing the new file name and the XFD or XDD file containing its definition:

   1. ctutil -make myctdata mydata.xfd 

   2. This command will create a file named myctdata using the image string obtained from the mydata.xfd.
2. Dump the existing data from the existing mydata data file created using Vision by using the RM/COBOL recover2 utility. This is a menu driven utility. Be sure to select the NOSUB option for most cases. This utility unloads data into a sequential line format.
3. Load the dumped data into the file created in step 1 using the ctutil -load functionality:

   1. ctutil -load -r2 myctdata mydata.dmp A

   2. This command loads the data from the line sequential file called mydata.dmp and writes it to the mydata FairCom RTG COBOL data file. The -r2 is required and specific to RM/COBOL line sequential format.
4. Now the new FairCom RTG COBOL data file mydata can be read through the FairCom RTG COBOL SQL engine by running the following command:

   1. ctutil -sqlize myctdata mydata.xfd ADMIN ctreeSQL

   2. This command parses the mydata.xfd file and generates an XDD schema definition on the fly to be used by the FairCom RTG COBOL engine to import the data file as part of a SQL database.

RTG Migrate

The RTG Migrate tool provides a graphical interface to help you migrate data into FairCom RTG/ISAM applications by reading records from an external database and writing them to FairCom RTG/ISAM files. This tool provides functionality similar to the command-line version, ctmigra.

The RTG Migrate tool, RTGMigrate.jar, is located in the Tools\guitools.java\ directory. Use the RTGMigrate.bat batch file to run this utility.

Note: This utility requires a FairCom RTG/ISAM DLL located in the driver directories (for example, Driver\ctree.cobol\extfh or Driver\ctree.ISAM). If you know the path to this directory, you can add it to your PATH environment variable. On Windows platforms, the RTGMigrate.bat batch file correctly sets the path for you and runs the utility.

You will see four tabs in the RTG Migrate tool, which correspond to the four steps in migration:

• One - Source Environment - Allows you to prepare for the migration.
• Two - Source Files - Indicates the source of the data you will be migrating to FairCom RTG/ISAM.
• Three - Destination - Indicates the destination of the migrated data, which must be accessible to the FairCom RTG/ISAM system.
• Four - Migrate - Begins the migration process.

 One - Source Environment

The first tab of the RTG Migrate tool (shown above) is where you prepare for the migration.

Migration Origin

• Select original environment - Select ExtFH for Micro Focus and other COBOL compilers that use this file system or select PSQL / ISAM for Btrieve files. The Check Library button tests the presence of the native library to convert data from the original format to the FairCom RTG/ISAM format.
• Select the source base directory of the source files - Enter the directory that contains the source files or click the three dots to navigate to it.
• Optional Btrieve owner name - If you are migrating from Btrieve files (PSQL / ISAM) to indicate the owner.

After entering the information in the fields, click the Next button to advance to the next tab.

Two - Source Files

Use this tab to select the data files to be migrated. The data will be read out of these files and copied to the destination you specify in the next tab. The original files will not be altered in the process.

Do not specify index files because they will be created as part of the migration.

The file system is shown in the tree view on the left. Click to the notes to expand them and click on the files to select the ones to be migrated.

File Filter

The field labeled File Filter allows you to specify a mask using wildcards. Click Apply to apply changes to the mask.

Click the Next button to advance to the next tab.

Three - Destination

Destination

• Index Filename Extension - Enter the suffix of the destination index file name (default: .idx).
• Index Filename Extension Mode - Select Append to if you want the extension entered to be appended to the file name or select Replace to have it replace an extension already in the file name.
• Replace Existing Files - Select whether or not to overwrite existing files.
• Destination Base Path - Enter the path to the destination root directory. Migrated files and directories will be placed under this directory on the destination host. This path can be relative to the FairCom RTG/ISAM LOCAL_DIRECTORY or it can be an absolute path.
• Encryption, Compression, Transaction - You can also set these parameters.

Resulting Directory

The Resulting Directory layout shows indexes with their names and it highlights conflicts.

FairCom RTG/ISAM Server Connection Information

The destination server is the server to which the migrated files will be copied.

• Server Name, User Name, Password - Enter the login information for the destination server.
• Test Connection - The Test Connection button in the FairCom RTG RTG Migrate tool allows you to check the configuration by pinging the server.

Note: If you see an error message "Could not find RTG library" it is because the proper driver directory (e.g., Driver\ctree.cobol\extfh or Driver\ctree.ISAM) is not in the path. A batch file, RTGMigrate.bat, is provided so you run the utility without having to set the PATH environment variable in Windows environments.

Click the Next button to advance to the next tab.

Four - Migrate

Migration

• Batch Size - Enter the number of records to read/write in batches. This setting may affect the speed of the conversion by grouping the records into batches that will be inserted into the database together. Increasing the size of the batches reduces the number of inserts and speeds performance, as long as system resources (e.g., memory) permit.
• Log File - Enter the name of the file to log additional information. To redirect log to stderr, enter a dash (‑).
• Script Name - If you want to create a script that can be run later, enter a file name for the script here and click the Create Script button.
• Create Script - Click this button if you want to create a file containing a script that can be run later. The file name will be the name entered in Script Name. The script will contain the ctmigra command with the appropriate command-line parameters based on the options you have entered in this tool.
• Configuration Filename - If you want to create a basic configuration file containing the information you have entered in this wizard, enter a file name in this field and click the Create Conf. File button. This file can be used by the ctmigra command-line utility.
• Create Conf. File - Click this button if you want to create a basic configuration file containing the information you have entered in this wizard. The file name will be the name entered in Configuration Filename. This configuration file can be edited in the RTG Config tool if you need to further refine your configuration for your environment. It can be used by the ctmigra command-line utility.

 
Click Migrate to begin migration. Alternatively, you can use the Create Script button to create a script that can be used later with the ctmigra utility.

You can click Stop Migration at any time to halt the operation.