The "gen" function creates empty Vision files. This is equivalent to doing an OPEN OUTPUT on the files from COBOL and is supplied as an alternative to writing a program explicitly to create empty data files. The command syntax is:
vutil -gen [-234]
or
vutil -gen [-234] list directory
The first syntax invokes a prompting program that asks you for the name of the new file and then prompts you for each file attribute. The second syntax shown above allows you to specify all file attributes in advance, and store them in a file.
Whether you store the attributes in a file or respond to prompts at the keyboard, the file attributes you provide are the same.
The "-4" option creates a file with Vision Version 4 dual file format. This is the default. The "-3" option creates a file with Vision Version 3 single file format, and the "-2" option creates a file with Vision Version 2 format.
3.3.6.1 Responding to vutil generated prompts
If you use the interactive version of the "gen" option, you are immediately given the opportunity to store the session in a file, so that your responses can be used again. (In fact, you can use the session file as the list file with the non-interactive version of "gen".) If you indicate that you do want to save the session, you are prompted for a session file name.
Next you are prompted for the name of the new file, and for its attributes. The exact prompts are shown here, and are described in section 3.3.6.2. Default values are enclosed in brackets.
Save this session [Y]? Enter session filename:Enter filename: Enter the blocking factor [1]: Enter the number of blocks to pre-allocate [1]: Enter the # of blocks for extension [0]: Enter the compression factor (0-100) [0]: Enable record encryption [N]? Enter the maximum record size (1-32767): Enter the minimum record size (1-maximum) [maximum]:
Enter the # of keys [1]: -- Primary key -- Enter number of segments (1-6): (For generating Version 2 or 3 files) Enter number of segments (1-16): (For generating Version 4 files) Enter segment size: Enter segment offset: (Segment size and segment offset repeat as a pair for each segment)
-- Alternate key n -- (repeats for each alternate key) Enter number of segments: Duplicates allowed [N]? Enter segment size: Enter segment offset: (Segment size and segment offset repeat as a pair for each segment)
Enter translation table filename: Enter file comment (30 char max):
Generate another file?
Collating Sequence
One of the attributes you may specify is the name of a file containing a translation table. This enables you to create a custom collating sequence for the new file, instead of using the standard ASCII collating sequence. The exact format for the translation table is given here.
All white-space characters (space, tab, new line, etc.) are ignored, so the table can have as many lines and spaces as you desire.
The sequence of the characters in the table determines the collating sequence for keys. For example, a file which looks like this:
Z Y X W V U T S R Q P O N M L K J I H G F E D C B A
would sort keys reverse alphabetically, for the values in the range A to Z.
You may enter special characters by typing a backslash (\) and then the decimal value of the character desired. Thus, "\032" would be used to specify the SPACE character.
Ranges can be specified with a dash (-). The sequence of the starting and ending characters in the range is significant. The reverse-alphabetical table shown above could be specified more concisely as:
Z - A
Finally, you can give two or more characters the same sort value by using an ampersand (&) between them. For example, the file will not distinguish case if you use a translation table with the following format:
a & A b & B c & C d & D e & E f & F g & G h & H i & I j & J k & K l & L m & M n & N o & O p & P q & Q r & R s & S t & T u & U v & V w & W x & X y & Y z & Z
Any characters in the native collating sequence that are not explicitly named in the table assume a position greater than any of the explicitly named characters. The relative order of these unnamed characters remains the same as in the native collating sequence. In the last example, all digits, punctuation, and control characters would be in their usual order, but after all alphabetic characters.
3.3.6.2 Specifying file attributes in advance
vutil -gen [-234] 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.