Modifying Keys in an Existing File

Restriction: You can only modify keys in Vision files of version 6 or later, and that are not encrypted.

The -key option enables you to add, delete, or modify keys in a Vision file. The command is:

vutil -key [-q] ([ -a # kdesc] | [-d #] | [-m # kdesc]) file-name

The arguments are:

`-q`	This optional argument suppresses the warning message that is generated informing you that the file is modified in place.
`-a # kdesc`	This argument adds a key at the position indicated by `#`. (Keys range from 0 (the primary key) to 120.) If keys already exist at and beyond the specified number, they are incremented to accommodate the new key. `kdesc` is the key description, and must take the following format: A,B,C,D[,C,D]... where: `A` is the number of segments in the key. A key may have from 1 to 16 segments. Each segment must be described with a size, offset pair (see `C` and `D`). `B` indicates whether the key allows duplicates or not. 0 indicates that it does not allow duplicates; 1 indicates that it does. `C` and `D` indicate the size and offset of a key segment. One such pair must occur for each key segment indicated in `A`. This option is mutually exclusive of options `-d` and `-m`.
`-d #`	This argument deletes the key indicated by `#`. If any keys follow the deleted key, they are decremented to fill the gap left by the deleted key. This option is mutually exclusive of options `-a` and `-m`. Note: When a key is deleted, the index blocks that made up the deleted key are marked as free for future use, but the space is not reclaimed from the file. The file will size will not shrink unless you then rebuild the Vision file, which removes any extra space in the file.
`-m # kdesc`	This argument modifies the key at the position indicated by `#`. `kdesc` is the new description for the key, and takes the same format as for the `-a` argument. This option is mutually exclusive of options `-a` and `-d`.
`file-name`	This argument is the name of the Vision data file to be modified in place.

Comments:

Due to the nature of these operations, you should not perform them on a Vision file without backing it up beforehand. Any failure during the modification of the key structure could leave the file in an unrecoverable state, and requiring you to revert to a backup.

Before performing any of the modification operations, the Vision file is marked as broken, with a 97 sub-code (98,97 file status). Upon successful completion of the operation, this code is removed.

New and modified keys will always allow duplicates; the B value in the key description is currently ignored.

When altering the key structure of a file to allow duplicate key values, be aware that data may not be retrieved in the order that you expect when using that key. To distinguish duplicate key values, a unique value is assigned to each record containing the duplicate data. Usually, this happens as the record is written to the file, and so records can be retrieved using this data, in chronological order. By introducing duplicate keys on an existing file, the unique values must be assigned en masse, in the order that the records currently sit in the file; therefore, retrieving records using the key will not necessarily return them in the order in which they were written.