reformat - reformat existing data to match amended record layout¶
reformat |
Reformat existing data to match amended record layout |
SYNTAX
reformat [-bcdehilqsvy][-F tempfile] oldfile newfile
Reformats existing data in a file whose record layout has been altered, such that the data matches the new layout. Secondary indexes are rebuilt automatically. It is recommended that the Sculptor File Manager program ( Keyed file->Reformat menu option), which greatly simplifies the process, is used to reformat files.
When a keyed file is created from a data dictionary (.d extension) with the newkf program, the key and record lengths are fixed, and the record layout permanently set for that file. If changes are made to an existing data dictionary with the ddeditor program, one of three situations must arise:
1 |
No keyed file has yet been created (with the newkf program) for the data dictionary. Changes do not matter, as the data dictionary has not yet been used. |
2 |
A keyed file has been created but is either empty, or contains records which may safely be destroyed. Run the newkf program to create a new, empty keyed file which matches the new record layout. |
3 |
The existing file contains records which are to be preserved. It is in this case that the reformat program is required. The newkf program would destroy the data in the file. |
WARNING: After using reformat, all programs which declare the reformatted file must be recompiled.
See Changing an existing data dictionary for detailed information on whether a change requires a reformat.
It is not necessary to reformat a file unless the main index is altered. To change a secondary index’s record layout, edit the index with the ddeditor program and then use kfri or kfbuild to rebuild the index.
oldfile, newfile |
oldfile is the old version of the file, which has been saved under a temporary name (oldfile) and can be deleted after the reformat is complete. newfile is the destination file. This is the name of the edited data dictionary - the original file name, and the name that oldfile bore before the renaming procedure. No extensions should be included in either name. |
||||||||||||||||||||||
[-bcdehilqsvy]
-F tempfile
|
Command line options.
|
How reformat works¶
The reformat program requires that the old data dictionary be preserved under another name. After the necessary changes have been made to the data dictionary, reformat compares the old data dictionary to the new one, and assumes that only those fields which have the same name are to be retained. If the type and/or size of such fields has been changed, then a suitable type conversion is performed.
Fields which exist in the old file but not in the new file are deleted; any new fields or array elements are initialised to spaces or zero, according to the field type.
Records are copied according to these rules from the old index and data files, which must also have been preserved under a temporary name, to the destination file. This file bears the same name as the newly edited data dictionary. The file will generally not exist at the time reformat is run, and will be created afresh. However, it is possible to run the reformat program even if the destination file has been created from the edited data dictionary (using newkf), and records already existing in the destination file can be retained. If any duplicate key values are encountered while records are being copied from the old file, these records are discarded.
Error messages¶
x: Unknown option
The option -x is not valid for reformat. A help message is displayed specifying the valid command line syntax.
The specified data dictionary file (.d extension) does not exist, or could not be read due to file access permissions.
Can’t open filename - operating system error number nnn
The named file could not be opened, due to the operating system error with the number specified. Check your operating system manual for further details. Frequent causes of this event are lack of disk space and incorrect access permissions.
Duplicate key
A duplicate key has been encountered. Normally this event only occurs if the -e switch has been used, instructing reformat to add records to those already existing in newfile. The reformat program issues this warning that an insert into newfile has failed because a record with the key already existed, and then continues processing.
If this error occurs when the -e switch has not been used, it indicates that the new key fields are not unique. This might of course happen naturally if the key structure has been changed when the data dictionary was edited with ddeditor, either by removing key fields or by changing the type of the existing ones.
If the key structure was not changed in any way when the data dictionary was edited, the old file must be damaged. Rebuild the old index (oldfile) using the kfri program, and then repeat the reformat operation.
File oldfile is empty
This message is a warning that there were no records in the data file oldfile. Empty data and index files (newfile and newfile.k) are nonetheless created.
Filename too long
The file name exceeds the program’s limits for file and/or path names.
The key and/or record length of the original data dictionary file (oldfile.d) does not match the actual length encountered in the data file. Ensure that the original, renamed data dictionary is present in the current working directory when running reformat.
Insufficient memory!
There is not enough free memory available for reformat to work properly.
INTERRUPT - reformat incomplete!
The reformatting process was interrupted, and the new file is not complete.
EXAMPLE
Simple reformat of old, renamed file “tempdata” to new file “members”:
reformat tempdata members
Reformat displaying count:
reformat -c tempfile stock
Step by step guide to the reformatting procedure¶
Note that this procedure is vastly simplified by use of the Sculptor File Manager, which performs all the file copying, renaming and deleting operations automatically. Under UNIX systems reformats must be done from the command line, and the list below details the steps required. An example is also given.
Make a full backup of all files: the data dictionary, index file, data file and all secondary index files.
Make a copy of the data dictionary, giving it a temporary name such as “temp.d”, “olddata.d”. The name chosen (without the .d extension) is that which is referred to as oldfile in this documentation.
Rename the existing data file (currently named newfile) to the name oldfile, and the existing index file (currently named newfile.k) to the name oldfile.k.
If secondary indexes exist, rename the secondary index directory (currently named newfile.x) to the name oldfile.x. On some systems it is not permitted to rename a directory. In this case it is necessary to create a new directory with the name oldfile.x, and to copy all the secondary index files from the original directory newfile.x into this directory.
Edit the data dictionary file newfile.d, using the Data Dictionary Editor program ddeditor, and make any changes required. Remember not to alter the names of any fields which are to be preserved.
Reformat the old data using the command syntax shown above. The changes you have made are listed, and you are asked to confirm that you wish to proceed. reformat then commences reading data from oldfile.
Delete the files oldfile, oldfile.k, oldfile.d and (if present) the directory oldfile.x unless you wish to keep them for backup purposes.
EXAMPLE
Reformat of a file and secondary indexes on a UNIX system
cp marbles.d temp.d
mv marbles.k temp.k
mv marbles temp
mv marbles.x temp.x
describe marbles
reformat temp marbles
rm temp temp.k temp.d
rm -r temp.x
RELATED TOPICS |