FairCom RTG COBOL User Guide

-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.

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.