Bookstore Manager Software
Technical Support: VUTIL
QUESTION: What is vutil, why is it important, and how do I use it?
ANSWER: BSMGR uses AcuCobol’s Vision indexed file system to manage its indexed data files. BSMGR comes with AcuCobol’s indexed file utility program called "vutil" that contains several useful functions. It can be used to examine files, extract data records, and rebuild corrupted indexes. Each one of these functions is indicated by an initial keyword on the command line (preceded by a hyphen). This keyword may be abbreviated to its first letter.
NOTE: Three phrases are referenced below that need defining.
Testing File Integrity (-check)
Examining File Information (-info)
Loading from a Binary Sequential File (-load)
Rebuilding Files (-rebuild)
Unloading Vision to Binary Sequential Format (-unload)
Determining vutil's Version (-version)
The "check" option of vutil tests a file for internal consistency.
vutil -check [-afk] [files]
With no options, it reads a list of files from the standard input and tests each one for a non-zero user count and other quickly-tested errors. Only files with errors or non-zero user count are listed.
The "-f" (full) option will read every record in the file(s) in an attempt to see if the file is broken. Any problems that are detected are printed. The check is run even if the user count is zero.
Note that although the "check" option is a good test of a file, it is possible for a file to be corrupt and still pass the test. If you’re processing an indexed file outside of vutil and you recieve a file error "98", that file is corrupt even if it passed the "vutil -check" test.
BSMGR usage: You may use the * symbol to check all files in a directory. (This should only be done with everyone out of BSMGR.) The following example will check the entire BOOK directory.
cd /bsmgr/book (UNIX)
--OR--
CD \BOOK (DOS)
vutil -c -f * <Enter>
All files that are listed should be rebuilt. With top priority given to any "marked as broken".
The "info" function of vutil returns some basic information about Vision indexed files.
vutil -info [files]
If no files are specified on the command line, then vutil reads file names from the standard input. The "-x" option causes vutil to report additional (extended) information. The basic information provided by the "info" function consists of:
If you request extended information with the -x option, your will also see:
A value of note is the "user count". This value starts at zero, and is incremented each time the file is opened for I/O. This number is decremented when the file is subsequently closed. Under normal circumstances, the user count indicates the number of users who are currently updating the file. Should the program be exited improperly, then this number will not be decremented. Thus, if the user counter is ever non-zero when there are no users active, then it indicates a sudden program failure and suggests that corrective action may need to be taken. At the very least, the file should be checked for integrity, but depending on the program that died, perhaps more significant action should be taken.
Basically a non-zero user count indicates that someone knowledgeable about the system should intervene and ensure that everything is okay. This can be used as an early warning system to head off some problems before they surface in a more serious form.
BSMGR usage: when used, we will normally check for information on a given file after changing to the directory. For example,
cd /bsmgr/book (UNIX)
--OR--
CD \BOOK (DOS)
vutil -i IVMAST
will return the extended information on the store’s inventory masterfile (IVMAST)
Loading from a Binary Sequential File
The "load" option will create an indexed file from a binary sequential one. The command is:
vutil -load source destination
The source file is the name of the binary sequential file to read. The destination file is the name of the Vision file receiving the source information. This file must already exist.
BSMGR usage: This option is not used very often by the customer, either. In the examples above, the customer will use the load command to get the information they "unloaded" into the existing Vision file. Another use is when a new customer has us convert an existing inventory or mailing list. The information is normally "unloaded" here and sent to them. They then "load" it into their existing file(s). Again, we first change to the appropriate directory. For example,
cd /bsmgr/book (UNIX)
--OR--
CD \BOOK (DOS)
vutil -l filename.SEQ filename
The "rebuild" option is used to rebuild or recreate an indexed file. You should rebuild a file that has become corrupt, or one that contains a large number of deleted or lost records that you want to remove from the file. The command (as mainly used) is:
vutil -rebuild [-a] [-k keynum] [files]
When a file is rebuilt, a temporary file is created and each record from the original file is written to it. The temporary file’s name begins with "vtmp..." The rebuilding process reports the number of records found and the number of deleted records that were skipped. After the rebuild is complete, you are given the option of replacing the original file with the new one. If you don’t replace it, you can examine the temporary file for correctness and replace it manually later. This is recommended if you suspect any difficulties.
The "-a" (automatic) option may be used to specify automatic replacement of the original file by the newly created one. This option causes automatic replacement only if no records are skipped. If any records are skipped, you are prompted before file replacement takes place.
The "-k" (key number) option specifies that you want to rebuild the file in key order. The -k must be followed (as the next separate argument) by the number of the key that you want to use, with zero indicating the primary key, one indicating the first alternate key, and so forth. For example, to rebuild file1 in primary key order, you would type:
vutil -r -k 0 file1
A situation in which the -k option is valuable is when the default rebuild method fails to recover a file fully. This can occur if the chain of data records has been corrupted. When -k is specified, vutil will use the index you provide to try to locate the records, and will often find more records this way.
BSMGR usage: we first change to the appropriate directory then try a to rebuild using the "-r -a" flags. If that fails, you can use "vutil -i filename" to find out the number of keys and attempt successive rebuilds on each key until you are successful. If the "-r" reports 10 keys, you can use "-k 0", "-k 1", ..., "-k 9". For example,
cd /bsmgr/book (UNIX)
--OR--
CD \BOOK (DOS)
vutil -r -a IVMAST <Enter>
When a file begins the rebuild process, the filename and number of records will be shown, then it will go through the percentage of completion as it rebuilds. Once the rebuild is finished, it will tell you the number of records recovered, the number of deleted records removed, and then will say "Renaming temporary file..."; if you have lost records or a broken file, it will not rename the file, but will give you the option of deciding what to do. You will probably want to use the -k option and try again.
vutil -r -k 0 -a IVMAST <Enter>
Note: The character following the -k is a number, not a letter.
Unloading Vision to Binary Sequential Format
The "unload" option will create a binary sequential file from a Vision file. The command is:
vutil -unload source destination
The source file is the Vision file to unload, the destination is the name of the file to create. If this file already exists, it is eliminated first. The records in the binary sequential file will be ordered by their primary key. This can be used to export data to other applications.
BSMGR usage: This option is not used very often by the customer. One example for its use is a multi-store setup where the smaller store wants to put all the items from the main store in their inventory with zero quantities without overwriting their own inventory, or copy all the names in the mailing list from one store to the other without overwriting that store’s mailing list. You first change to the appropriate directory, the type in the unload command. For example,
cd /bsmgr/book (UNIX)
--OR--
CD \BOOK (DOS)
vutil -u filename filename.SEQ <Enter>
The "version" option will display the version of vutil being used. The command is:
vutil -version
BSMGR usage: This option is not used very often by the customer. BSMGR support personnel may need to determine the version of vutil if you are experiencing difficulties with the other vutil command options. For example,
vutil -v <Enter>