vutil -gen [-234] [ -q ] list directory
The non-interactive version of "gen" allows you to specify a file (list) that contains the attributes for one or more new files. The format of list is described below.
The directory parameter names the directory in which the new files are to be created. Each file is tested to see if it exists before it is created. If it does exist, and it is a Vision file, then it is left untouched. Thus, you can use the "gen" function to generate missing files from a directory without having to first save the ones that are there.
The file list consists of one or more file entries, one per line. Each entry pertains to exactly one file and consists of a series of fields.
Four entry formats are supported: one for relative and sequential files, and three different formats for indexed files. The three indexed file formats support (respectively) the current Vision conventions (Version 4), and versions 2 and 3 of the Vision format. The formats for versions 2 and 3 are supplied for compatibility and are not described here.
For indexed files, the fields are divided into five groups, separated with semicolons. Fields within each group are separated with commas.
For relative and sequential files, the fields are all separated with commas.
Indexed format
The fields for the indexed format are listed here and then described below.
filename,
blocking factor,
number of blocks to pre-allocate,
number of blocks for extension,
compression factor,
Enable record encryption?;
maximum record size,
minimum record size,
number of keys;
For primary key:
number of segments,
Duplicates allowed?, (always zero) segment size,
segment offset, (repeat the segment size and offset pair for each segment)
For each alternate key:
number of segments,
Duplicates allowed?,
segment size,
segment offset, (repeat the segment size and offset pair for each segment);
translation table filename;
file comment
In the indexed format, the first field is the (physical) file name. The second field is the blocking factor. This currently may be either one or two. All I/O to the disk is done in blocks of one or two sectors. Depending on the file and the underlying disk architecture, performance can be affected by this. Although performance is difficult to predict, files that have large keys (40 bytes or more) are usually best set with a blocking factor of two. Otherwise, one should be used.
The third field is the number of blocks to allocate to the file initially. This is usually set to one. If you want to pre-allocate some disk to the file, then this can be set to a higher number. Pre-allocation in no way limits the file, but may help performance by reducing disk fragmentation.
The fourth field is the number of blocks for extension. This determines how many blocks are allocated each time space needs to be added to the file. This helps keep fragmentation to a minimum.
The fifth field is the compression factor. A compression factor of 0 means no compression. A compression factor of 1 is equivalent to the default compression. For factors from 2 through 100, the factor is considered to be a percentage. It specifies how much of the space saved by compression is actually to be removed from the record. For example, suppose an 80-byte record is compressed to 30 bytes. Then the compression factor is used to determine how much of the 50 bytes of saved space is actually to be removed from the record. A compression factor of 70 would mean that 70% of the 50 bytes (35 bytes total) will be removed. This leaves 15 bytes for future expansion, and results in a compressed record size of 45 bytes (30 compressed size plus 15 extra for growth). The larger the compression factor, the more of the saved space is removed. A compression factor of 100 removes all saved space and is advisable only if the file is rarely updated.
The sixth field is a flag that determines whether record encryption is enabled. A value of "1" enables encryption. A value of "0" disables encryption. A semicolon should follow the encryption flag.
The next two fields specify maximum and minimum record size. If the two numbers are identical, the records are fixed-length. If the two numbers are not identical, records are variable-length. The maximum record size cannot exceed 32767.
The ninth field is the number of keys in the file, to a maximum of 120. A semicolon should follow the number of keys.
Next, you describe the primary key by at least four entries. The first entry is the number of segments in the key. The second entry is always "0". For each segment, you must then specify the segment size in bytes, and the segment offset from the start of the record, in bytes. If there are no alternate keys, a semicolon should follow the final segment offset. Otherwise, a comma should be used.
If there are any alternate keys, describe each one by a series of at least four entries. The first entry is the number of segments in the key. The second entry is a "1" if duplicate values are allowed, or a "0" if they are not. For each segment, you must then specify the segment size in bytes, and the segment offset from the start of the record, in bytes. A semicolon should follow the final segment entry of the last alternate key.
After the keys have been specified, enter the name of a file containing the translation table (collating sequence), if you want anything other than standard ASCII sorting. If the name is empty, ASCII sorting is assumed. The format of the translation file is given in the preceding section. A semicolon should follow the name of the translation file.
Finally, you may provide up to 30 bytes of comment. This comment is printed by vutil when the "info" option is used.
Here's a sample file entry. Suppose a file containing G/L account descriptions has a record size of 80 and two keys. The primary key is at the start of the record and is 15 bytes long. The alternate key has two segments; the first is at record offset 40 and is 30 bytes long. The second segment of the alternate key is at record offset 20 and is 5 bytes long (duplicates allowed). A compression factor of 30 and ASCII sorting are desired. The corresponding entry is:
glactfil,1,1,0,30,0;80,80,2;1,0,15,0,2,1,30,40,5,20; ;G/L account master
Sequential and Relative Files
For convenience, the non-interactive "gen" option can also create empty sequential and relative files if they are missing. The entry contains only three fields. The first field is the file name. The second field is the record size, and the final field is an "S" for a sequential file or an "R" for a relative file. The record size field is only comment, so it can be set to any numeric value.
Whether to use "gen" or a COBOL program to create the data files for an application depends on which is more convenient. Creating the file list can be painstaking, but the symbol table listing of the compiler can help to compute the size information. Once the files are created, however, it is easier to replace missing files this way than with a program that must explicitly test for a file's existence before creating it.