Rebuilding a keyed file index¶
kfri |
Rebuild a keyed file index |
SYNTAX
kfri [-chmpqsvxy] [-F tempfile] filename [filename]… | -iname [-iname]… filename
Rebuilds a keyed file index and/or secondary indexes from the data file. If an index file is damaged or missing, a new one can be created from the data file, because the key data is stored at the front of every data record. The program may be run from the command line or by the Sculptor File Manager program ( Keyed file->Rebuild menu option).
The kfri program rebuilds the main index by reading the records in the data file, one by one, and creating a new main index entry for each record. If duplicate key values are found, they are ignored, as this usually indicates some corruption of the data file. When the rebuild is complete, the total number of keys inserted in the index is displayed, along with the number of duplicate key values encountered. Secondary indexes are then built if requested. The main index is named filename.k; a secondary index file is called name.k and is stored in a directory called filename.x.
If a file was created as index-only (by using the newkf -i switch) the kfri utility may nonetheless be used to rebuild the index. It does this by renaming the index file, building a new index from it by treating it as a special data file, and, finally, deleting the renamed file.
filename |
The file to be rebuilt. kfri accepts multiple filenames for rebuilding provided that the -i option is not used. This option is for the purpose of specifying a particular secondary index or indexes to be rebuilt, and may only be used if a single filename is specified. Each filename should be the name of a Sculptor index file. The path should be included if the file is not located in the current working directory. The files are rebuilt one by one in the order listed. Inclusion of the .k extension is optional. |
[-chmpqsvxy]
-F tempfile
-iname
|
Key and record length¶
In order to rebuild the index of a keyed file successfully, kfri must know the number of bytes in the file’s key fields, and the number of bytes in a whole record. These are displayed on the File Manager screen as Key Length and Record Length, or can be obtained from the data dictionary file by using the pdes utility.
If kfri is run from the command line, and the old main index file is present, the key and record length values are displayed for confirmation. If the main index file is not present, kfri prompts you to enter the key and record length of the file to be rebuilt. Once the key and record lengths have been confirmed, the index rebuild commences.
Note that if the -F, -q, -s or -y option was used, kfri does not issue prompts.
Deleted records¶
Deleted records occupy space in the data file until or unless that space is reused for newly inserted records. The kfri program detects deleted records in the data file by assuming that all records which are completely null except for the first three bytes are deleted (the first three bytes being pointers in the deleted record chain). It is therefore possible that a file with a very small data size and no alphanumeric data after the first three bytes could have some genuine records mistaken for deleted ones. In practice, there are only a very few cases where kfri cannot rebuild the index perfectly.
Command line options¶
Option flags may be combined into a single flag string (-pc) or listed separately (-p -c)
-c |
Displays a count every 1000 records processed. |
-h |
Displays a help screen listing these options. No other action is taken, even if filenames and other flags are present. |
-F tempfile |
Places all messages that would normally be displayed on the terminal in the named file and suppresses all questions. |
-iname |
Specifies a secondary index to be rebuilt, in addition to the main index. This option is only available if a single filename is specified. However, several different indexes for the specified file may be selected in this way, by repeating the -i option: kfri -iname -iname … filename The main index is not rebuilt unless the -m option is also specified. |
-m |
This option is only relevant if some or all secondary indexes are being rebuilt. It causes kfri to rebuild the main index as well. |
-p |
Controls the way that kfri packs the index. Records are physically stored on the disk in the order in which they were inserted. If this order is fairly random with regard to the key - that is to say, the records were not created in ascending key order - the index will be evenly packed. However, if the records were created in ascending key order, the index file created would be only half full, although its efficiency would be only marginally affected. If you are absolutely certain that the keys were inserted in ascending key order, use the -p option. This tells kfri to pack entries into the leftmost page first, resulting in a smaller index file. Note, however, that if the -p option is used on a file where the data was not inserted in key sequence, the resulting file may be larger than it would have been without the -p option. |
-q | -s |
Suppress the output of all messages. -q is the preferred form, -s being provided for upward compatibility only. |
-v |
Outputs version information. No other action is taken. |
-x |
Causes kfri to rebuild all secondary index files. The main index is not rebuilt unless the -m option is also specified. |
-y |
Suppresses all prompts. kfri proceeds on the assumption that it has the correct key and record lengths. All progress and error messages are output as usual. |
Error messages¶
Cannot build a good index as data file is badly damaged.
Options:-
1
Reload file from last backup
2
Use kfcopy to copy available data
The data file is too severely damaged for the main index to be rebuilt. Some data retrieval is required. This can in most cases be done by recovering the data file from the most recent backup, or by copying the good records from the damaged file with the kfcopy program, thus ensuring that as much data as possible is retrieved. Then run kfri again.
The index file could not be created or deleted, due to the operating system error with the number specified. Check your operating system manual for further details. Frequent causes of this event are permissions, file is read-only, or disk full.
Duplicate keys ignored
Duplicate keys were encountered and ignored in the data file. This message is a warning that the data file is likely to have been corrupted.
Filename too long
The file name exceeds the program’s limits for file and/or path names.
Illegal option ’x’
The option -x is not valid for kfri. Check the Options section above for valid options.
Index “name” is not an alternate index for this file
The secondary index “name” specified in a -i option was not found.
Insufficient memory!
There is not enough free memory available for kfri to work properly.
Multiple main files not allowed when “-i” option is used
Multiple main file names have been specified along with a -i option. The -i option may only be used in conjunction with a single filename.
Please provide index name when using “-i” option
The name is missing following the -i option.
Record length not a divisor of file length - continue (y/n)?
The record length shown does not divide evenly into the data file length. The record length may be incorrect or the data file may be badly corrupted. If the reply is “y”, kfri adds null bytes to the data file to make it the correct length. Some data has probably been lost.
WARNING: Data file may be original index file
The kfri process was interrupted during the main index rebuild of an index-only file. The data file may actually be the previous version of the index file which is to be rebuilt, because the index file is renamed and used as a special temporary data file when kfri is run on index-only files. Ensure you have a backup of the data and the index files. Then rename the data file (currently named filename, no extension) as the index file (filename.k) and try running kfri again.
EXAMPLE
Rebuild two named files and secondary indexes:
kfri -mx fred wilmaRebuild single file and two named indexes, showing count:
kfri -mc -ibarney -ibetty rubble
Display help screen of kfri options:
kfri -h
RELATED TOPICS |