ctutil

ctutil provides functionality to perform maintenance tasks on indexed files. (Users of Vision COBOL will recognize it as the FairCom RTG/ISAM counterpart of the Vision vutil utility.) It can be useful for importing data.

ctutil allows you to examine files, extract data records, change the maximum record size, and rebuild corrupted indexes. The functions are designed to allow you to specify all possible task parameters up front, such that the utility can run unattended or with a minimum of user interaction.

Beyond the functionality mentioned above, ctutil is important in many aspects of FairCom RTG/ISAM operation, including preparing data for SQL access and importing ISAM data. See ctutil Commands for a listing of ctutil commands organized by type.

Usage

ctutil [-c config_file] [-s] [-l] [-o owner_name] command ...
  • -c config_file - specify a c-tree configuration file to bypass default CTREE_CONF
  • -s - superuser mode allows the utility to open a file marked as corrupted (ctOPENCRPT c-tree file mode)
  • ‑l (lower case "L") - dump the configuration in XML format before the actual ctutil output (V2 and later).
  • -o owner_name - specify the owner name (file password) required to fully access the file.
    • For instance, the following command creates a new file with a password: ctutil -o secretword -make file file.xdd
    • To open and get info on the same file: ctutil -o secretword -info file

Return Code

The ctutil command returns 0 if the operation was successful or a positive number if it failed.

 

ctutil Notes

CTUTIL uses stdout to output data and stderr to output the program status. If you do not want to see the status message "Operation completed successfully" you can redirect the stderr stream:

$ ctutil >/tmp/output.txt 2>/tmp/error.txt

In the example below, if you want to redirect both stdout and stderr you could use the following:

$ ctutil -info /usr/tree/r1/sc0001/LP/LNFILE >/usr/tmp/km.txt 2>&1

Please notice that “2>&1” means “redirect stderr (stream 2) to stdout (stream 1).” ctutil uses stdout to output data and stderr to output the program status.

If you want to know if the ctutil command was successful despite the output, you can check the return value of ctutil.

Unix:

$ ctutil >/tmp/output.txt 2>/tmp/error.txt
$ [ $? -eq 0 ] && echo OK

Windows:

C:\> ctutil >/tmp/output.txt 2>/tmp/error.txt
C:\> @if errorlevel 0 echo OK

 

ctutil Commands

Available ctutil commands are listed in the following sections.

Information options

  • -info file [-x]
  • -param file
  • -profile file
  • -exist path

Maintenance options

  • -make file xdd_file
  • -alter file iss_file [-hot | -full]
  • -copy source_file dest_file (-copy, ctutil -copy)
  • -clone source_file dest_file
  • -filecopy source_file dest_file [-overwrite]
  • -rename source_file dest_file
  • -remove file
  • -upgrade source_file [dest_file]

Consistency options

  • -check file [-x] [-k=index]
  • -rebuild file [-purgedups] [-delidx]
  • -compact file [-purgedups] [-delidx]

Definition options

  • -setpath file
  • -tron file T|P|F|W
  • -maxsize file max_file_size
  • -segment file max_file_size max_segments
  • -conv file convention_ID
  • -compress file
  • -uncompress file

Import/export options

  • -load file seq_file [-b|t|p] [-v[2|4|8][n|x]] [-r|s] [-rs=recsiz]
  • -unload file seq_file [-b|t|p] [-v[2|4|8][n|x]] [-k=index]

SQL options

  • -sqlinfo file [xdd_file [convention_ID]]
  • -sqllink file admin_password database_name [-symb=table_name] [-prefix=table_prefix] [-owner=user_name] [-public[=ro]]
  • -sqlunlink file admin_password database_name [-symb=table_name] [-prefix=table_prefix] [-owner=user_name]
  • -sqlize file xdd_file admin_password database_name [-symb=table_name] [-prefix=table_prefix] [-owner=user_name] [-public[=ro]] [-conv=convention_ID] [-rule=rules_file]
  • -applyrules iss_file rules_file
  • -sqlcheck file xdd_file [-conv=convention_ID] [-show=show_type]
  • -xfd2xdd xfd_file [-rule=rules_file]

Miscellaneous options

  • -cryptconf config_file output_file
  • -run
  • -test [config|connect]

 

-alter

Changes the record schema of an existing file using RTG XDD definitions.

Usage

ctutil -alter  file xdd_file [-hot | -full]

where:

  • file is the name of the file without extension
  • xdd_file is the path to an xdd file
  • -full forces full alter schema
  • -hot forces hot (on-the-fly) alter schema

The -full and -hot options are optional and mutually exclusive. If not specified, a full alter table is performed only if a hot alter table is not available.

The new xdd_file must specify a default value using the defaultValue attribute or error 4187 is returned.

4FCC5C00> 20240805T124932 core:08190:cts_alter    ERROR 19:4187:0 default value is mandatory on new fields) ctutil:altertest

The following is an example new field definition with the default value included.

<field name="CM_CUSTCTRY" size="47" type="Alphanum" digits="47" scale="0" defaultValue="USA"/>

On success, the new record length is displayed in ctutil output. If there are errors, a detailed message will be logged to RTG logging when enabled.

Hot Alter Table Considerations

A hot alter table (HAT) requires the table to be capable of hot alter. The <flexrec> file attribute enables this option. HAT is default for RTG created tables as of RTG version 4.5.0. For prior versions, upgrade the files to apply the ctFLEXREC file mode by using ctutil -upgrade and enabling the <ctflexrec> configuration option.

Alter requires the record schema to be already stored in the file. The record schema can be stored in the file with a 'ctutil -sqlinfo <info.xdd>' command or via a sqlize operation ('ctutil -sqlize' or file creation with <sqlize> enabled).

For tables previously without HAT support, a first alter table from -full will include the <ctflexrec> mode such that future alters will be HAT capable. To prevent this, include <ctflexrec>no<ctflexrec> in your RTG configuration.

Note: The command allows only to append new fields to the end of the record schema. It is like the SQL ‘ALTER TABLE’ statement, except it does not support removing fields from the record schema.

See Also

<ctflexrec>

<recordcheck>

<maxlencheck>

 

-applyrules

Applies rules to an XFD or XDD file, producing an XDD file that can be used by -sqlinfo or -sqlize.

Usage

ctutil -applyrules  xdd_file rules_file

where:

  • xdd_file - Path to an XFD/XDD file
  • rules_file - Path to rules file

 

-augment

Used to increase the max record size of existing files

Usage

ctutil -augment  path size

where:

  • path - File/Directory path without extension
  • size - New maximum record length in bytes

Note: The command fails if the new maximum record length is not equal to or greater than the current minimum record length. If the new specified size is equal to the current minimum record length, the file is changed from variable length to fixed length. Likewise, if the file is fixed length (minlen = maxlen) and the new specified maximum record length is greater than the current maximum record length, the file is transitioned from fixed length to variable length.

 

-check

Tests a file for internal consistency.

Usage

ctutil -check  file_name [-x] [-k=index]

where:

  • file_name - File name without extension
  • -x - Perform extended tests matching records with keys
  • -k=index - Perform tests only on specified index

For very large files with many indexes, you may want to consider using the -k option to validate only a single index.

 

-clone

Create an empty copy of an existing file.

Usage

ctutil -clone  source_file dest_file

where:

  • source_file - Source file name without extension
  • dest_file - Destination file name without extension

 

-compact

Removes the deleted records from a file.

Certain attributes, such as PAGE_SIZE, are automatically applied on compact.

Usage

ctutil -compact file_name [-purgedups] [-delidx]

where:

  • file_name - File name without extension
  • -purgedups - Purge duplicate records from data file
  • -delidx - Force the deletion of the index file before rebuilding

 

-compress

The ctutil -compress command adds data compression to an existing file. The compression type, level, and strategy are retrieved from settings documented for the <datacompress> option in the FairCom RTG/ISAM configuration file. Reports a message at the conclusion of the operation indicating if the file was successfully compressed or uncompressed.

Usage

To compress the contents of file:

ctutil -compress  file_name

where:

  • file_name - File name without extension.

See Also

-uncompress

 

-conv

Stores or retrieves numeric storage conventions of a file.

Usage:

ctutil -conv  file [convention_ID]

where:

  • file - File name without extension
  • convention_ID - (optional) Numeric storage convention ID. See -sqlinfo convention_ID values.

 

-copy

Copies a file record-by-record creating a new file based on the configuration settings.

Usage

ctutil -copy  source_file  dest_file

where:

  • source_file - Source file name without extension
  • dest_file - Destination file name without extension

Notes:

-copy vs -filecopy

The -copy option creates a copy of a file by building it record-by-record, which creates a new file based on the configuration settings. The -filecopy option makes an exact copy of the source file, which can be faster than the -copy option.

The difference between these options is that the -copy option creates the destination file based on the configuration setting while the -filecopy option creates an exact copy of the source file.

Both approaches have limitations and advantages:

  • -filecopy is faster than -copy and provides an exact copy of the file.
  • -copy may be helpful when you need to change file characteristics.

For example, suppose you use <keycompress> in your ctree.conf file to compress keys and you need to disable it for a specific file. You could add a specific <file> section in your ctree.conf that removes the <keycompress> setting from the destination file and then simply run ctutil -copy. The ctree.conf would look as shown below:

<config>
 <instance>
  <file> <!--default rule matching all files-->
   <keycompress>yes</keycompress>
  </file>
  <file name="*_nocompress"> <!--rule matching file names ending with "_nocompress"-->
   <keycompress>no</keycompress>
  </file>
 </instance>
</config>

Run ctutil -copy making sure to use the correct ctree.conf:

ctutil -c ctree.conf -copy myfile myfile_nocompress

The resulting destination file myfile_nocompress will have all data records from the source file but its keys will be not compressed.

ctutil -copy vs Dynamic Dump

The recommended alternative to the ctutil -copy operation is the "Dynamic Dump" backup and restore option using the ctdump utility. (See the Database Backup Guide for more info).

If your files are under transaction processing control (TRNLOG), the Dynamic Dump utility, ctdump, is preferable because the ctdump utility uses transaction processing control if the data file is TRNLOG enabled. This has the advantage that the data file and any associated indexes are guaranteed to be in a consistent state, even if the file is updated during the backup process.

The ctutil -copy operation is not under TRNLOG control, therefore it is possible to end up with an index file that is inconsistent with the data file (for example, if a file is updated during the copy operation).

If a data file is not under TRNLOG control, the Dynamic Dump offers one advantage over ctutil -copy: The !PROTECT and !PROTECT_LOW keywords can be used in a Dynamic Dump backup script to instruct the system not to allow any file updates while each non-TRNLOG file is being backed up. (See the Database Backup Guide for more info).

See also:

  • -filecopy
  • -fileid

 

-cryptconf

Encrypt the ctree.conf configuration file.

Usage:

ctutil -cryptconf  config_file output_file

where:

  • -cryptconf - Encrypt the ctree.conf configuration file
  • config_file - Name of the configuration file to be encrypted (typically ctree.conf)
  • output_file - Name of the encrypted output file

See

 

-exist

Checks to see if a path exists.

Usage

ctutil -exist path

where:

  • path - File/Directory path without extension.

Upon successful completion, it returns one of the following:

  • Path does not exist
  • File does exist
  • Directory does exist

 

-filecopy

Perform a physical file copy.

Usage:

ctutil -filecopy source_file dest_file [-overwrite].

Notes:

The command is not dependent on the configuration file, thus a ctutil -filecopy command will always perform a physical file copy independently from the configuration settings (as opposed to the -copy option).

The ctutil -filecopy command does not overwrite existing files unless the -overwrite option is specified.

Note: The ctutil -filecopy command requires an exclusive open of the file. c-tree attempts to open the file in exclusive mode while allowing other connections read access. If the file is already open, c-tree flushes updates to disk and sets the update flag to zero to indicate that the file is in a clean, consistent state. If c-tree cannot open the file in exclusive mode, the copy operation fails.

See also:

  • <filecopy>
  • -copy 
  • -fileid

 

-fileid

Reset the unique file ID of a file that has been copied at the system level.

Usage

ctutil -fileid file

Best Practices for Copying c-tree Server Files

Note: Copying files is against FairCom’s recommended best practices. However, because copying files is fairly common in many industries, FairCom has the following provisions:

  1. ctutil -filecopy and -copy options - Use the ctutil -filecopy and -copy options to copy files.
  2. Restamp file ID after copying using the operating system - The ctutil -fileid option is for restamping the file ID after a file is copied using the operating system facilities.
    The ctfileid Update File ID utility performs this same function. It is located in tools\cmdline. See the Command-Line Tools documentation: ctfileid - Update File IDs.

if run against a server that does not support the ctUNIQIDhdr mode, ctutil fails with error message "Client/server incompatibility" and the following error message is logged: "ERROR 37:-4:0 server does not support fileid reset".

See also

 

-info

Displays information about a file, including the file's WRITETHRU file mode and the Max Length for variable-length files.

Also displays Index node size. RTG v3 and later use a 32768 byte node size while prior versions used a 8192 byte node size.

Usage

ctutil -info  file_name [ -x ][ -f ]

where:

  • file_name - File name without extension
  • -x - Display extended information. (optional)
  • -f - Open the file even if it is corrupted (i.e., file open returns c-tree error 14 FCRP_ERR). (Deprecates the generic ctutil option -s that was doing the same thing and was used only by -info and -unload commands.)

 

-make

Creates a file using XDD definitions.

Usage

ctutil -make file xdd_file

where:

  • file - File name to create without extension
  • xdd_file - Path to XDD file containing file definitions

Note: The XDD file definition resource is stored within the table file. If the <sqlize> configuration is enabled, the file is also automatically sqlized. If the XDD file is passed as a parameter in the 'ctutil -make' command, it overrides the <sqlize xdd> configuration.

 

-makeidx

Add new indices to an existing file.

Usage

ctutil -makeidx file xdd_file

where:

  • file - File name to create without extension
  • xdd_file - Path to XDD file containing file definitions

NOTE: The XDD file must specify all the desired indices at the end of the operation including those that already exist in the file.

 

-maxsize

Sets the maximum file size limit of an existing file.

If you attempt to set a maximum file size limit that is less than the size of your file, it will fail with the following error message in the RTG log: "ERROR 51:667:0 file size exceeds specified limit."

Usage

ctutil -maxsize  file max_file_size

where:

  • file - Name of a file without extension
  • max_file_size - Desired maximum file size limit in MB

See also

  • <maxsize>

 

-load

Imports data from a sequential file. The ctutil -load command reads a sequential file and writes the records in it to a c-tree file.

Usage

ctutil -load file_name seq_file [-b|t|p|r2] [-v[2|4|8][n|x]] [-n] [-r|-s] [-rs=recsiz]

where:

  • file_name - File name without extension.
  • seq_file - Path to the source file.
  • -b - Indicates a binary sequential format is used.
  • -t - Indicates a line sequential format (records separated by new-line character).
  • -p - Indicates an ASCII file created by the ISAM BUTIL -save command.
  • -r2 - Specifies that the binary sequential input file was created with the Recover2 utility.
  • -v - Indicates variable-length format (record data is preceded by record length) and is optionally followed by a 2 or 4 or 8 that indicates the size of the record length field that precedes the record data and by an n or x to indicate if the record length is represented in native (n) or big-endian (x) format.
  • -n - "New file": any data in the destination file is eliminated before the records are loaded from the source file.
  • -r - Replace any existing record that returns 'duplicate key' error.
  • -s - Skip any existing record that returns 'duplicate key' error.
  • -rs=recsiz - Record size of the sequential file (required only if the record size of the destination file differs from that of the sequential file).

The command assumes that the record size of the sequential file is the same as the c-tree file. If they differ, the -rs option is used to specify the record size of the sequential file.

See Also:

  • -unload

 

-partition

Converts an existing RTG file to a partitioned file. Partitioned files are great for bulk data purging or archiving. See Partitioned Files for detailed information regarding this unique RTG feature.

Usage

ctutil -partition file rule index

where:

  • file - is the file name without extension.
  • rule - is the partition expression rule string.
  • index - is the partition index number where 0 is the primary index.

The index must already exist and the record schema must already exist in the file. The record schema can be stored in the file with a 'ctutil -sqlinfo' command or using a sqlize operation such as 'ctutil -sqlize' or file creation with <sqlize> enabled.

It is possible to display the partition rule of an existing partitioned file with the 'ctutil -sqlinfo' command.

See also ctpartadmin utility for partitioned file management.

 

-rebuild

Rebuilds the indexes of a file.

Usage

ctutil -rebuild file_name [-purgedups]

where:

  • file_name - File name without extension
  • -purgedups - Purge duplicate records from data file
  • -delidx - Force the deletion of the index file before rebuilding

 

-remove

Removes a file.

Usage

ctutil -remove  file_name

where:

  • file_name - File name without extension

 

-rename

Renames or moves a file.

Usage

ctutil -rename  source_file  dest_file

where:

  • source_file - Source file name without extension
  • dest_file - Destination file name without extension

 

-run

This command provides the ability to execute multiple ctutil commands in a single run to avoid program initialization overhead.

Usage

ctutil -run  command_list_file

where:

  • command_list_file is a text file that contains one ctutil command on each line followed by all its required parameters. The ctutil commands start with a dash character, therefore each line that does not begin with a dash (excluding any leading space character) is considered a comment and is ignored.

Example

ctutil -run  commands

The text file commands contains the following commands to create a file called custmast using definitions found in custmast.xdd, add records to it from custmast.txt, and link it to SQL. The final line in the file is a comment because it does not begin with a dash:

-make custmast custmast.xdd
-load custmast custmast.txt
-sqlize custmast custmast.xdd ADMIN ctreeSQL
These commands create a file, add records to it, and link it to SQL

Return

The value returned by the ctutil -run if an error occurs executing one of the listed commands is the line number of the command list file containing the failed command.

The return value is 0 if all operations listed in the command list file are completed successfully.

 

-segment

Enables file segmentation on a file.

Usage

ctutil -segment  file_name  max_file_size  max_segments

where:

  • file_name - File name without extension
  • max_file_size - Maximum file size for single file segment
  • max_segments - Maximum number of file segments

Note: Keep max_segments as low as possible to optimize performance.

 

-setowner

Specifies the password (also known as the owner name) of a file in order to restrict access to the file. This password can be removed using -clrowner.

Usage

ctutil -setowner file password 0|1

where:

  • file - File name (without extension)
  • password - File password
  • 0 - Password is required for any access mode
  • 1 - Permits read-only access if password is not specified

The password parameter is mandatory. The maximum password name length is 10 bytes. In order to remove an existing file password, the -clrowner command must be used to specify the password with the -o option.

 

-setpath

Updates the path of a file. The c-tree files contain information about the file including the path location of the file itself. After copying a file to a location other than the creation directory, it is necessary to reset the file path information according to the new file location.

Usage

ctutil -setpath  file_name

where:

  • file_name - File name without extension

 

-sign

The -sign option is synonymous with the -conv option to store the sign-storage convention ID in a file.

See:

  • -conv

 

-sqlcheck

This ctutil option verifies that the data is correct in sqlized tables. The -sqlcheck option is used to verify that data in a file is compatible with SQL definitions. The command scans all records of the given file using the primary key index and stops at the first conversion error encountered showing an error message, the record number, schema and field name of the incorrect data.

Usage:

ctutil -sqlcheck  file xdd_file [-conv=convention_ID] [-show=show_type]

The -sqlcheck option checks SQL definitions against data in a file. Valid parameters are:

  • file - File name without extension
  • xdd_file - Path to a data definition file in XML format
  • convention_ID - COBOL Users Only: Optional numeric storage convention ID; see -sqlinfo convention_ID values.
  • show_type - level of errors to show:

all - show all errors in the table

first - show the first error in the table

firstrec - show all errors in the first problematic record in the table

Example:

The usage and output of the command is as follows:

C:\>ctutil -sqlcheck filecompa filecompa.xdd -conv=A
ctutil Version 11.2.0.5893-160315
Initialized from (ctree.conf)
 
Checking filecompa...
 
ascii value is not a digit. Record#: 8 Schema#: 0 Field: NS
 
Operation completed successfully.

Example:

This example reveals numeric sign issues

>ctutil  -sqlcheck  CUSTOMER.DAT  CUSTOMER.xdd   -show=all
ctutil
Version 6.0.0.324-250123 - ACUCOBOL Edition
Initialized from 'ctree.conf'
 
Checking CUSTOMER.DAT...
 
Record#: 0000002 Schema#: 005 Field: keycharcnt Error: unexpected value for sign [8c] valid values [0d|0f] (last nibble only)
Record#: 0000002 Schema#: 005 Field: elecharcnt Error: unexpected value for sign [0c] valid values [0d|0f] (last nibble only)
Record#: 0000002 Schema#: 005 Field: maxelecnt Error: unexpected value for sign [0c] valid values [0d|0f] (last nibble only)
Record#: 0000008 Schema#: 005 Field: keycharcnt Error: unexpected value for sign [0c] valid values [0d|0f] (last nibble only)
Record#: 0000008 Schema#: 005 Field: elecharcnt Error: unexpected value for sign [0c] valid values [0d|0f] (last nibble only)
Record#: 0000008 Schema#: 005 Field: maxelecnt Error: unexpected value for sign [0c] valid values [0d|0f] (last nibble only)
Record#: 0000019 Schema#: 005 Field: keycharcnt Error: unexpected value for sign [0c] valid values [0d|0f] (last nibble only)
Record#: 0000019 Schema#: 005 Field: elecharcnt Error: unexpected value for sign [0c] valid values [0d|0f] (last nibble only)
Record#: 0000019 Schema#: 005 Field: maxelecnt Error: unexpected value for sign [0c] valid values [0d|0f] (last nibble only)
 
Operation completed successfully.

 

-sqlinfo

Stores or retrieves SQL definitions of a file.

Usage

ctutil -sqlinfo  file [xdd_file -conv=[convention_ID]] [-rule=rules_file]

where:

  • file - File name without extension
  • xdd_file - Path to a data definition file in XML format
  • convention_ID - COBOL Users Only: Optional numeric storage convention ID; see -sqlinfo convention_ID values.
  • -rule=rules_file - Optional path to rules file - see Define External Rules
  • Note: Output from this command goes to the console and it is recommended to pipe this utility into a text file to capture the output.

 

convention_ID values

Values for convention_ID:

A ACUCOBOL-GT (default)

B MBP COBOL

D Data General

I IBM (Also applies to many RM COBOL numeric types)

M Micro Focus

N NCR COBOL

R Realia COBOL

V VAX COBOL

 

Makes an existing file accessible from SQL by linking the file name to the FairCom DB SQL dictionaries.

Usage

ctutil -sqllink file_name database_name 
 [-symb=table_name] [-prefix=table_prefix] [-owner=user_name] [-public[=ro]]

where:

  • file_name - File name without extension
  • database_name - Database name to be associated with the file
  • symb=table_name - Optional table name to use when adding file to a database
  • prefix=table_prefix - Optional prefix for table or symbolic name
  • owner=user_name - Optional user name to assign table ownership
  • public[=ro] - Optionally grant public access permissions, read-only when =ro is used

Note: This is an administrative operation and therefore must be performed with caution. Do not attempt to use this operation on a file that is open. The <instance user> associated with the file for a sqllink operation must have either DBA or RESOURCE SQL privileges in order for the operation to succeed or a c-treeRTG error 456 (group access denied) is returned. While strongly discouraged, backward compatibility is provided with this configuration option: COMPATIBILITY SQLIMPORT_ADMIN_PASSWORD.

Error Logging

When the ctutil -sqllink or ctutil -sqlize procedures (or an automatic "sqlize" by the COBOL driver) fail, the logic logs error messages that could help identifying issues. The ctsqlcbk.FCS file on the client will have information about the nature of the error.

 

Removes a file from the FairCom DB SQL dictionaries such that it is no longer accessible from SQL.

Usage

ctutil -sqlunlink file_name database_name 
 [-symb=table_name] [-prefix=table_prefix] [-owner=user_name]

where:

  • file_name - File name without extension
  • database_name - Database name to remove the file (table) from
  • symb=table_name - Optional table name to use when adding file to a database
  • prefix=table_prefix - Optional prefix for table or symbolic name
  • owner=user_name - Optional user name to assign table ownership

Note: This is an administrative operation and therefore must be performed with caution. Do not attempt to use this operation on a file that is open. The <instance user> associated with the file for a sqlunlink operation must have either DBA or RESOURCE SQL privileges in order for the operation to succeed or a c-treeRTG error 456 (group access denied) is returned. While strongly discouraged, backward compatibility is provided with this configuration option: COMPATIBILITY SQLIMPORT_ADMIN_PASSWORD.

 

-sqlize

Performs all necessary operations to make a file accessible from FairCom DB SQL. In fact it groups a number of operations which can be executed separately helping the user to make the file accessible from FairCom DB SQL using only one command. The sqlize option accepts XDD files as input.

Usage

ctutil -sqlize file xdd_file database_name
  [-symb=table_name] [-prefix=table_prefix]
  [-owner=user_name] [-public[=ro]]
  [-conv=convention_ID] [-rule=rules_file]

where:

  • file - File name without extension
  • xdd_file - Path to an XDD file
  • database_name - Database name to add the file to
  • -symb=table_name - Optional table name to link file to database
  • -prefix=table_prefix - Optional prefix for table name
  • -owner=user_name - Optional user name to assign table ownership
  • -public[=ro] - Optionally grant public access permissions; read-only when =ro is used
  • -conv=convention_ID - COBOL Only: Optional numeric storage convention ID. COBOL users see -sqlinfo convention_ID values.
  • -rule=rules_file - Optional path to rules file - see Define External Rules

Note: This is an administrative operation and therefore must be performed with caution. Do not attempt to use this operation on a file that is open. The <instance user> associated with the file for a sqlize operation must have either DBA or RESOURCE SQL privileges in order for the operation to succeed or a c-treeRTG error 456 (group access denied) is returned. While strongly discouraged, backward compatibility is provided with this configuration option: COMPATIBILITY SQLIMPORT_ADMIN_PASSWORD.

 

Error Logging

When the ctutil -sqllink or ctutil -sqlize procedures (or an automatic "sqlize" by the COBOL driver) fail, the logic logs error messages that could help identifying issues. The ctsqlcbk.FCS file on the client will have information about the nature of the error.

 

-sqlrefresh

Preserves existing information about the table (synonyms, grants, etc.) when relinking into SQL.

Usage:

   -sqlrefresh file xfd_file database_name
               [-symb=table_name] [-prefix=table_prefix]
               [-owner=user_name] [-conv=convention_ID]
               [-rule=rules_file]

Description:

The ctutil -sqlrefresh command is very similar to the -sqlize command. The -sqlrefresh command has these properties:

  1. It can be used only if the table was already sqlized.
  2. It refreshes the table structure maintaining the existing grants and synonyms.
  3. It does not support the "public" option available in -sqlize since authorizations are kept from the original sqlize and grant occurred in SQL.

Note: This is an administrative operation and therefore must be performed with caution. Do not attempt to use this operation on a file that is open. The <instance user> associated with the file for a sqlrefresh operation must have either DBA or RESOURCE SQL privileges in order for the operation to succeed or a c-treeRTG error 456 (group access denied) is returned. While strongly discouraged, backward compatibility is provided with this configuration option: COMPATIBILITY SQLIMPORT_ADMIN_PASSWORD.

 

-test

Check the configuration and connection to servers. The syntaxes are:

ctutil -test config [file] 
ctutil -test connect
ctutil -test filerules
  • Running ctutil -test config option checks the configuration. If file is specified, it also checks which configuration instance matches the specified file.
  • Running ctutil -test connect checks that all servers defined in the configuration (with the <instance server> attribute) are reachable.
  • Running ctutil -test filerules will print the file rules in the order they will be considered by FairCom RTG/ISAM at runtime when matching a filename:
ctutil -test filerules
Initialized from (ctree.conf)
 
<file name="*" dir="mydir" casesensitive="yes" type="*"/>
<file name="myfil" dir="*" casesensitive="yes" type="*"/>
<file name="*" dir="*" casesensitive="yes" priority="-32767" type="*"/>
 
Operation completed successfully.

Note: Running the -test command with no additional specifications will run the -test config command by default.

 

-tron

Sets the file mode for a file. Displays a message at the conclusion of the requested operation indicating success or an error message in the case of a failed operation.

Usage

ctutil -tron file_name T|P|F|W

where:

  • file_name - File name without extension.
  • 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.

Note: By default, FairCom RTG/ISAM files are created as ctPREIMG. When enabling full transaction control on these default files, no rebuild of the indexes is necessary.

It is necessary to also adjust the ctree.conf file to enable full transaction logging for the file(s) affected. For example,

<file name="CUSTMAST" dir=".">

    <transaction logging="yes">yes</transaction>

</file>

  • 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 may not be suitable yet data safety remains critical.

See Also

  • ctcbtran

Notes

FairCom RTG is transaction-ready and supports ROLLBACK out of the box. There is no need to enable <transaction logging> if you need ROLLBACK.

By default, FairCom RTG files are created as c-tree PREIMG files (an intermediate level of transaction processing supported by FairCom DB). This provides full atomicity of transactions including rollback with the best of performance. However, this model of transaction processing does not log transactions to disk, thus does not provide durability and recovery of transactions in case of system failure. Full transaction processing, provided by write-ahead logs on disk, provides complete ACID protection of data.

In addition, FairCom RTG allows working without any transaction capability. This is useful when you need extreme performance such as very large batch loads, etc.

ctutil provides for switching COBOL tables between these various modes. Be cautious when switching modes, as data loss can occur if an appropriate mode is not appropriately applied for specific usage patterns.

ACUCOBOL and Micro Focus programs support transaction processing in slightly different ways, as described below:

ACUCOBOL

ACUCOBOL has START TRANSACTION, so a transaction is explicitly started using a START TRANSACTION directive.

COMMIT TRANSACTION and ROLLBACK TRANSACTION directives are supported by both ACUCOBOL and Micro Focus.

An ACUCOBOL program allows you to rollback updates only if a file has been defined as WITH ROLLBACK. See the ACUCOBOL documentation.

Micro Focus

Micro Focus does not have START TRANSACTION. A transaction is automatically started first time you update a file that has been opened with the openwithrollback option.

COMMIT TRANSACTION and ROLLBACK TRANSACTION directives are supported by both ACUCOBOL and Micro Focus.

 

-uncompress

The ctutil ‑uncompress command removes data compression from an existing file. Reports a message at the conclusion of the operation indicating if the file was successfully compressed or uncompressed.

Usage

ctutil -uncompress file_name

where:

  • file_name - File name without extension.

See Also

-compress

 

-unload

Exports data from a COBOL data file to a sequential or ASCII file. If the COBOL file is encrypted, ctutil returns error 33: Operation not allowed. File is encrypted.

Usage

ctutil -unload file_name seq_file [-b|t|p] [-v[2|4|8][n|x]] [-k=index][-f]

where:

  • file_name - File name without extension.
  • seq_file - Path to the destination file.
  • -b - Indicates a binary sequential format is used.
  • -t - Indicates a line sequential format (records separated by new-line character).
  • -p - Indicates an ASCII file to be used by the ISAM BUTIL -load command.
  • -v - Destination file has variable-length records

[2|4|8] - record data is preceded by record length and is optionally followed by a 2 or 4 or 8 that indicates record length is stored in 2 or 4 (default) or 8 bytes

[n|x] - record length is stored in native COMP-N (default) or big-endian COMP-X format

  • -k=index - Reads and writes records in specified index order (-k=1 for the primary key)
  • -f - Open the file even if it is corrupted (i.e., file open returns c-tree error 14 FCRP_ERR). (Deprecates the generic ctutil option -s that was doing the same thing and was used only by -info and -unload commands.)

See Also:

  • -load

 

-upgrade

Note: If you are upgrading to FairCom RTG V2 from prior releases, you will need to run the ctutil -upgrade command.

ctutil ‑upgrade

This option upgrades the table format to the current RTG configuration. The upgrade switch rewrites the the entire table using the definitions in the currently active RTG configuration file. With this switch it is possible to take an existing data file and upgrade it to the current RTG configuration.

Usage:

ctutil -upgrade  source_file [dest_file] [-ctattr]
  • source_file - Source file name without extension.
  • dest_file - Destination file name without extension.

This capability gives the customer a tool to upgrade an existing file to match the current settings in ctree.conf and/or the current FairCom RTG file format. This switch makes it possible to upgrade an existing data file to the latest format. For example, it would be used if a revision changed the file's physical layout (e.g., altering the header). FairCom RTG logic attempts to handle files in older formats, however it may be necessary to upgrade files after installing a new revision to take advantage of new features or to correct bad behavior.

If no destination file is included, the file will be upgraded in place to include the ctFlexRec attribute.

Caution: For large tables, this operation can take significant time as all table records are read, reformatted and then written into a new table. You will also need to ensure you have enough space on your storage device to hold at least twice the size of the original file and indexes.

Note: After a successful operation, all information about a file will be displayed as if you had run -info, unless -ctattr is included in which case only the RTG resource version will be displayed.

Upgrade specific attributes

  • -ctattr - This option was introduced in RTG V5, and allows a table to participate in hot alter table operations and other features requiring complete schema information. This attribute forces an existing RTGI resource to be upgraded to the latest RTGI v2, which is required for this advanced support. When the -ctattr option is specified, the file is not re-created to match the current configuration. Instead, only its RTG resource is converted to the <ctattr> format. This is faster than re-creating the file, especially if the file has large amount of data records. Existing RTG tables from prior versions remain compatible with current RTG versions. However, they will lack certain capabilities until their internal resources (such as RTGI) are updated.

 

-xfd2xdd

Transforms an XFD file version 4, 5, and 6 into c-tree XDD files, which contain SQL information.

Usage

ctutil -xfd2xdd  xfd_file  [-rule=rules_file]

where:

  • xfd_file - Path to an XFD file
  • rule=rules_file - Optional path to rules file

The ctutil -xfd2xdd utility (as well as the COBOL xddgen utility) mark the first index as the primary in the XDD definition so that this key becomes the primary key for SQL.

Note: The SQL Information will be written to standard output. Redirect standard output to a new file to obtain the XDD file.

 

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

 

ctaddrtgi - Add SQL indexes over existing COBOL tables

For existing tables created prior to FairCom RTG V2 (for tables created with FairCom DB versions prior to V11), an internal RTGI resource must be added to the table. This RTGI resource is automatically added with FairCom RTG V2 and newer (with FairCom DB V11 and newer).

The ctutil utility can be renamed to ctaddrtgi and used to add new FairCom RTG indexes. When renamed, it functions as an ad-hoc utility that can be run over old data files to give them the necessary information to add indexes through FairCom RTG.

The utility requires one parameter, which is the file name (without the file extension).

Note: It is safe to run this utility on a file that already has an RTGI resource (e.g., it is safe to run this utility on a file that does not need it). In this case the utility will simply return success and do nothing.

Once the ctaddrtgi utility has been executed over a data file, the process discussed here can be followed to add new SQL indexes: SQL Indexes on COBOL Files

Usage:

ctaddrtgi filename

where:

  • filename - The file name without extension.

 

Was this article helpful?

Give feedback about this article

Related Articles