Creating new index and data files from a data dictionary¶
newkf |
Create new index and data files from a data dictionary |
SYNTAX
newkf [-bhilsv] [-F tempfile] [-rnrecs] filename [filename]…
Creates new, empty index and data files with the record layout defined in the data dictionary filename.d. The files are placed in the same directory as the data dictionary file. They are required at run time by every Sculptor program that uses the files, unless the file is declared with create mode (see ![o]file).They are not necessary at compile time. The program may be run from the command line or by the Sculptor File Manager program ( Keyed file->New menu option).
If the files already exist, any data in them is destroyed. Empty files are also created in the directory filename.x for any secondary indexes associated with the file.
The data dictionary, which defines the key and record structure of the file, and which also specifies the name and structure of any secondary indexes to be associated with it, is created using the ddeditor program. newkf must then be run to create empty data and index files using the layout specified, before the file structure can be used in a Sculptor program.
The index file holds the index to the data records. The index file has the same name as the data dictionary file, but with a .k extension instead of .d.
The data file contains all the data, both key fields and data fields, for every record contained in the file. It is not sorted into order. The index file is used to access the records in the data file. The data file bears the same name as the data dictionary, but without any extension.
Each new secondary index file is given the name name.k, where name is the name that was assigned to the index in the data dictionary, and placed in a directory called filename.x. This directory is automatically created if it does not exist.
WARNING: The newkf program creates new, empty index and data files. If the files already exist, any data they contain is irretrievably lost. If an existing data dictionary is altered by adding or subtracting fields, or by changing their order, size or type in any way, new index and data files must be created. Records already existing in the file may, however, be reformatted to match the new file structure. Use the reformat program to do this. Note that the reformat process requires files to be copied and renamed before the data dictionary is changed. See reformat for full details of this procedure.
filename |
The file to be created. Each filename should be the name of a data dictionary file. The path should be included if the file is not located in the current working directory. The files are created one by one in the order listed. The .d extension may, optionally, be included in the filename. This allows the form newkf *.d to be used in order to create empty files for all the data dictionary files in the current directory. |
[-bhilv]
-F tempfile]
[-rnrecs]
|
Command line options¶
-b, -s |
Specifies either a big or a standard file. If newkf is being used to recreate an existing file, the default is the size of the existing file; otherwise the default is to create a standard file. A big file can be up to 128Gb in size with up to 134,217,727 records. The maximum for a standard file is 16,777,215 records. See Maximum number of records; creating big files. |
-h |
Display a help screen listing these options. |
-i |
Prevents creation of the data file, so that newkf creates an index-only file. This option is only applicable to record layouts which consist entirely of key fields. If the file has any data fields defined, then the -i option is ignored. |
-F tempfile |
Places all messages that would normally be displayed on the terminal in the named file and suppresses all questions. |
-l |
Turn transaction logging off. Unless this option is used, versions 4.2 or later of newkf update the transaction log file if it is present in the directory $SCULPTOR/recover. Any scripts that reinitialise files by calling newkf before they run the transaction recovery program should use this option. |
-rnrecs |
This option is for use on systems which benefit from pre-extended files. It creates index and data files which are pre-extended to the number of records indicated by nrecs. This should be an integer value set to the maximum number of records the file is ever expected to hold. |
-v |
Outputs version information. |
Error messages¶
x: Unknown option
The option x is not valid for newkf. Check the Options section above.
x ignored (not available with ‘-v’)
The option -x is not valid if used with -v and has been ignored.
Cannot create directory name (operating system error nnn)
The newkf program cannot create the directory for the secondary index specified.
Can’t create filename (key length zero)
Sculptor keyed files must have a key length of at least one byte. Use ddeditor to amend the data dictionary and try again.
Can’t create filename (key length >nnn)
The maximum key length has been exceeded. Use ddeditor to amend the data dictionary and try again.
Can’t create filename (record length <3)
The minimum record length, including both key and data fields, is 3 bytes. Use ddeditor to amend the data dictionary and try again.
Can’t create filename (system error nnn)
Operating system error number nnn occurred when trying to create the file. Check your operating system manual for further details. Frequent causes of this event are incorrect permissions, file is read-only, or lack of disk space.
Filename too long
The file name exceeds the program’s limits for file and/or path names.
-r option not available in restricted version
Pre-extension of data files is only available in the full version of newkf, not in the evaluation version.
EXAMPLES
Create two new keyed files:
newkf bubble squeak
Create three new index-only files. No data files will be created:
newkf -i axref bxref cxrefCreate a file pre-extended to the size of 10,000 records:
newkf -r10000 suppliesCreate a big file:
newkf -b vastfile
RELATED TOPICS |