fcompare

Compare database files to system catalog or repository

fcompare [-system_catalog_option]  |  [-repository_option] [-output_option]

Options

system_catalog_option

(optional) One or more of the following options, which cause fcompare to compare database file definitions with system catalog definitions.

g connect_file

Specify the name and path of the connect file.

t table

Specify a system catalog table name to check.

repository_option

(optional) One or more of the following options, which cause fcompare to compare database file definitions with repository file definitions.

r rpsmain rpstext

Specify the repository main and text files to use when comparing repository metadata against a database file.

f file_def_name

Specify a specific repository file definition name to check. Fcompare checks all structures assigned to the file described by that file definition.

c convert_setup_file

Override the conversion setup file specified by the SODBC_CNVFIL environment variable, and specify the name and path of the file to use in its place.

output_option

(optional) One or more of the following options:

Turn on data verification mode to compare ISAM file data with system catalog or repository metadata and generate verification output. This option can only be used if -t or -f is also being used.

l log_file

Specify the name of a log file that will contain the output from the fcompare program.

Generate error, warning, and informational messages. (Do not use with -v.)

Generate error and warning messages. (Do not use with -i.)

Discussion

The Synergy File Compare utility (fcompare) can be used to debug synchronization problems between repository or system catalog metadata and an ISAM, RMS, relative, or text file definition. It can also compare ISAM, RMS, relative, or text file data against repository or system catalog metadata. Fcompare does not compare metadata between a repository and a system catalog. For relative files, fcompare verifies record size and number of records only.

When discrepancies are found, fcompare produces either an error or a warning (if -v is specified). An error or warning indicates that the specified attribute, as defined in the repository or system catalogs, doesn’t match the “actual” attribute of the database file. Both the defined and the actual values are displayed, along with the name of the attribute being compared. Error messages are designed to assist xfODBC users. If you are using fcompare to compare file definitions to a repository, you should use the -v option to also output warning messages. See Errors and warnings for a list of possible discrepancies.

On OpenVMS, the fcompare utility is set up as a verb, which means you cannot pass more than eight parameters. Each option counts as one parameter, and each path specification counts as one parameter. If you have more than eight parameters, you must work around the limitation by enclosing the entire set of parameters in double quotation marks. For example:

fcompare "-r RPSDAT:rpsmain.ism RPSDAT:rpstext.ism -f customer -dv 
-l compare.log -v"

If neither -g nor -r is specified, fcompare compares repository definitions with database files. If both system_catalog_options and repository_options are specified, an error message is generated and processing is terminated.

System catalog comparisons

You can perform a comparison of all tables in the system catalog by specifying -g without -t, or you can limit the comparison to a single table by using the -t option. With the single table comparison, you can request that the data in the database file be verified against the catalog definitions by using the -dv option.

We recommend that ODBC users run fcompare using the repository option first, so that any discrepancies can be resolved before the system catalogs are generated.

For fcompare to access the database files for the system catalog option, any logicals used must be defined in the connect file or in the environment. If connect_file doesn’t include a path, fcompare looks for the file in the directory specified by the GENESIS_HOME environment variable.

Repository comparisons

You can perform a comparison of all file definitions in the repository by specifying -r without -f, or you can limit the comparison to a single file by using the -f option. (Keep in mind that -f expects a specific repository file definition name, not the repository “open filename.”) With the single file comparison, you can request that the data in the database file be verified against the definitions by using the -dv option.

If -r is not specified (assuming -g is not specified either), fcompare uses the environment variables RPSMFIL and RPSTFIL. If they are not set, fcompare looks for rpsmain.ism and rpstext.ism in the directory specified by the environment variable RPSDAT.

Fcompare reads data logicals from the environment, the synergy.ini file, or an environment setup file whose name and location are specified by the SODBC_INIFIL environment variable. Any logicals used in the repository “open filename” must be defined in one of these places.

If a conversion setup file is being used to specify filenames during conversion to system catalogs, fcompare can read the conversion setup file. When using the repository option (-r), set the SODBC_CNVFIL environment variable to the location and name of the conversion setup file, and fcompare will read the filenames from there. To use a different setup conversion file than that specified by SODBC_CNVFIL, use the -c option and specify the path and file you want to use.

To eliminate the errors detected by fcompare, you must examine the repository and the database file definition to resolve the discrepancies. The ipar utility (see ipar) can help you view the definition of the database file. (On OpenVMS, you can use the Analyze Utility.)

If you define a key as having two segments in the ISAM file but only set up the first segment in your repository, fcompare will not report an error, just a warning.

Output options

The data verification option (-dv) must be used in combination with -t or -f. When data verification mode is on, fcompare reads through all records in the database file and verifies that date and decimal fields contain valid values for their field types—in other words, that the date fields contain valid dates and the decimal fields contain numbers. (The SYNCENTURY environment variable is used to determine the default century for two-digit years.) Using the -dv option significantly increases the amount of time it takes to run fcompare, which is why its usage is limited to one file or table at a time.

Fcompare ignores fields set to “Excluded by ReportWriter.”

Output goes to the console unless the -l option is specified.

Informational messages (for example, the record size and number of keys) are only displayed if you specify the -i option. Warning messages are displayed if you specify -i or -v. Error messages are displayed in all cases, even if no options are specified.

Errors and warnings

Errors indicate fixes necessary to prevent potentially incorrect data from being returned from xfODBC. Warnings identify fixes required to prevent performance problems due to loss of optimization opportunities. Synergex recommends that all errors and warnings be fixed. Synergy/DE Developer Support will require that errors be fixed before providing assistance with xfODBC optimization.

If fcompare finds discrepancies between repository or system catalog metadata and the ISAM, RMS, relative, or text file definition, it generates one or more of the following errors to indicate which attributes do not match and what the unmatched values are:

Error message	Description
Boolean field [x] contains spaces	With the -dv option in use, a Boolean field was found to contain a space rather than a 1 or a 0.
Boolean field [x] contains values other than 1 or 0 [x]	With the -dv option in use, a Boolean field was found to contain a value that was not a 1 or a 0.
Cannot open file	The database file for this table cannot be located.
Cannot retrieve information	There is a problem retrieving column, index, or tag information from the system catalogs. Contact Synergy/DE Developer Support.
Cannot retrieve key information for krf	The defined krf number doesn’t exist in the file.
Collation (seg n) defined as [x], actual [x]	The sort direction (ascending/descending) of the key segment does not match.
Defined date length is not [n]	With the -dv option in use, the data length defined for the field does not match the user-defined date specification.
Defined record length [n], bytes read [n]	With the -dv option in use, a read of a variable-length record exceeds the defined record size.
Defined segment collation does not match actual segment collation	Fix the key definition.
Defined segment positions do not match actual segment positions	Fix the key definition.
Duplicates defined as [x], actual [x]	A key is defined as “unique,” but the file is not using a unique key.
Foreign key	All access keys must be defined before any foreign keys.
Hour field [n] is greater than 23	With the -dv option in use, a time field has an invalid hours value.
Invalid date field value	With the -dv option in use, a date field contains an invalid value.
Invalid decimal field value	With the -dv option in use, a decimal field contains an invalid character.
Invalid relative file	The relative file record size does not match.
Key length (seg n) defined as [x], actual [x]	The length of the field used as the key segment is larger than the key on the file.
Key of reference number n used more than once	The key of reference number is not unique.
Minute field [n] is greater than 59	With the -dv option in use, a time field has an invalid minutes value.
Non-numerical data in date field	With the -dv option in use, a date field contains nonnumeric data.
Non-numerical data in time field	With the -dv option in use, a time field contains nonnumeric data.
Not null autotime field [x] is null	Null data was detected in a non-nullable autotime field.
Not null date field [x] is null	Null data was detected in a non-nullable date field.
Not null field [x] is null	Null data was detected in a non-nullable field.
Null defined as [x], actual [x]^a	For keys defined to allow null, the replication type (replicating, nonreplicating, or short) does not match.
Number of access keys defined as [x], actual [x]	More access keys are defined in the repository than on the physical file. (Foreign keys are not included in the count.)
Offset (seg n) defined as [x], actual [x]	The starting location of the field used as the key segment does not match.
Record size	The length of fixed-length records does not match. Variable-length records are only checked with the -dv option.
Repository file not found^a	Fcompare could not find one or more repository files. See Repository comparisons.
Unsigned field [x] contains signed data	With the -dv option and either -r or -g in use, a field that is designated as unsigned contains signed data.

a. With repository_options only.

If a verbose option (-v or -i) is specified, one or more of the following warnings may be generated:

Warning message	Description
Data type (seg n) defined as [x], actual [x]	The data type of the field used as the key segment does not match, or a signed decimal field without a positive range is defined in the repository when the actual key in the ISAM data file is defined as alpha.
Duplicates defined as [x], actual [x]	The key is defined with duplicates. Better performance occurs if the repository is changed to say duplicates not allowed, as the file does.
Key n, Key length defined as [n]	A key is defined smaller than the file’s physical key.
Modifiable defined as [x], actual [x]^a	Whether keys are defined as modifiable or nonmodifiable does not match.
No access keys defined for structure x^a	The structure definition has no access key defined. xfODBC optimization is impossible!
Number of access keys defined as [x], actual [x]	Fewer access keys are defined in the repository than on the physical file. (Foreign keys are not included in the count.)

a. With repository_options only.

Examples

The following example compares the database file cust (-f option) to its repository definition (-r option), including verification of data (-dv option). Errors and warnings (-v option) are written to a log file called compare.log (-l option).

fcompare -r RPSDAT:rpsmain RPSDAT:rpstext -f cust -dv -l compare.log -v

Using the database defined by the connect file sodbc_sa (-g option), the example below compares the database file containing the table customers (-t option) to its system catalog definition, including verification of the data (-dv option). The errors, warnings, and informational messages (-i option) are written to the log file compare.log (-l option) in the location defined by RPSDAT.

fcompare -g sodbc_sa -t customers -dv -l RPSDAT:compare.log -i

Using the database defined by the connect file sodbc_sa (-g option), the example below compares all database files to the system catalog definitions. Errors and warnings (-v option) are output to the screen.

fcompare -g sodbc_sa -v