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
- For instance, the following command creates a new file with a password:
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.txtIn 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>&1Please 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 OKWindows:
C:\> ctutil >/tmp/output.txt 2>/tmp/error.txt
C:\> @if errorlevel 0 echo OK
ctunload407 to unload data of files affected by error 407
Support has been added to the FairCom RTG/ISAM ctutil utility to open files affected by error 407 so it can export data from a file that has a damaged resource chain. This support requires ADMIN permission and the OPENCRPT file mode. To use this functionality, ctutil must be renamed to ctunload407. The ctunload407 utility functions similar to ctutil ‑unload except that it automatically connects as ADMIN (with the default ADMIN password) and enables the <allowcorrupt> setting.
ctutil Commands
Available ctutil commands are listed in the following sections.
Information options
- -info file [-x]
- -param file
- -profile file
Maintenance options
- -make file xdd_file
- -alter file iss_file [-hot | -full]
- -copy source_file dest_file (-copy, ctutil -copy)
- -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
- -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]] [-rule=rules_file]
- -sqlcheck file xdd_file [-show=show_type]
- -applyrules iss_file rules_file
- -xfd2xdd xfd_file [-rule=rules_file]
- -ddf2xdd
Miscellaneous options
- -cryptconf config_file output_file
- -run
- -test [config|connect]
-alter
Changes the record schema of an existing file using FairCom RTG/ISAM 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:altertestThe 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 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/ISAM 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/ISAM 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 (in ISAM settings elements):
<ctflexrec>
<recordcheck>
<maxlencheck>
-augment
Used to increase the max record size of existing files
Usage
ctutil -augment path sizewhere:
- 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.
-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_filewhere:
- xdd_file - Path to an XFD/XDD file
- rules_file - Path to rules file
-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.
-clrowner
Removes a password/owner name that has been assigned to a file using -setowner.
Usage
ctutil -o password -clrowner fileWhere:
- file - File name (without extension)
- password - File password
-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_namewhere:
- 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 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_filewhere:
- 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_nocompressThe 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 Dynamic Dump in the FairCom DB Server Administrator's Guide).
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 Dump Files Without Transaction Control in the FairCom DB Server Administrator's Guide).
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
-ddf2xdd
Transforms Btrieve Data Dictionary Files (DDFs) into c-tree XDD files, which contain schema information about the data and index structures.
You must first generate .sav files from file.ddf, field.ddf, and index.ddf using the btutil command as follows:
butil -save FILE.DDF file.sav
butil -save FIELD.DDF field.sav
butil -save INDEX.DDF index.savYou are now ready to use ctutil to create the XDD files, as shown in Usage.
Usage
ctutil -ddf2xdd DDF_directory [-rule=rules_file] [-tablename]Where:
- DDF_directory is the name of the directory that contains the .sav files you created using butil.
- -rule=rules_file is an optional path to a rules file.
- -tablename (optional) uses the table name instead of the file name to determine the output file names.
When exporting DDF files, a naming problem can occur if multiple tables in different directories have the same physical data file name. The -tablename parameter avoids naming conflicts by using table names instead of DDF file physical names to determine the XDD output file names.
One XDD file will be created for each file contained in file.sav. XDD files will be saved in the current working directory.
-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. ISAM, and 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.)
-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
-make
Creates a file using XDD definitions.
Usage
ctutil -make file xdd_filewhere:
- 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/ISAM log: "ERROR 51:667:0 file size exceeds specified limit."
Usage
ctutil -maxsize file max_file_sizewhere:
- file - Name of a file without extension
- max_file_size - Desired maximum file size limit in MB
See also
-partition
Converts an existing RTG/ISAM 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/ISAM 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
-o word
The ctutil program accepts a global command line argument to specify the file password: ‘-o word’.
For instance, the following command creates a new file with password:
ctutil -o secretword -make file file.xdd
To open and get info of the same file:
ctutil -o secretword -info file
-remove
Removes a file.
Usage
ctutil -remove file_namewhere:
- file_name - File name without extension
-rename
Renames or moves a file.
Usage
ctutil -rename source_file dest_filewhere:
- 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_filewhere:
- 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 commandsThe 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 SQLReturn
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_segmentswhere:
- 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
Sets the password (also known as the owner name) of a file in order to restrict access to that file.
Usage
ctutil -setowner file password 0|1where:
- file - File name (without extension)
- password - File password (maximum length: 10 bytes)
- 0 - Password is required for any access mode
- 1 - Permits read-only access if password is not specified
The password parameter is mandatory. Once set, accessing the file requires using the -o option to provide the password.
If the <instance user> attribute is set to a user that is part of the ADMIN group, the file will be accessible regardless of what password is provided.
If <instance user> is not set, or is set to a user that is not part of the ADMIN group, then the password provided must match the one set by -setowner to access the file.
In order to remove an existing file password, the -clrowner command must be used to specify the password with the -o
-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_namewhere:
- file_name - File name without extension
-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 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 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.
-sqllink
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 for the operation to succeed or 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 identify issues. The ctsqlcbk.FCS file on the client will have information about the nature of the error.
-sqlunlink
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 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 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 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 identify issues. The ctsqlcbk.FCS file on the client will have information about the nature of the error.
-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|Wwhere:
- 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/ISAM 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/ISAM 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/ISAM 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. See the ACUCOBOL documentation.
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_namewhere:
- file_name - File name without extension.
See Also
-compress
-unload
Exports data from a Btrieve data file to a sequential or ASCII file. If the Btrieve 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.
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 myfilesThe myfiles file would list the files to be modified with one file name on each line, for example:
datafile01
datafile02
datafile03See also
-tron