Examining File Information

The info function of vutil returns some basic information about Vision indexed files. The command syntax is:

vutil  -info  [ -kpxq ]  [ files ]

If no files are specified on the command line, then vutil reads file names from the standard input. Several options can be specified with -info:

`-p`	This option causes vutil to pause between files and prompt the user for a return key. Otherwise, all the reports are run together.
`-k`	This option prints full details about each key, including the exact layout of a multi-segment, or split, key. Each segment is expressed as a pair of numbers--segment size (sz) and the offset from the beginning of the record (of).
`-q`	This option causes vutil to exit (with status 99) if user interaction is required.
`-x`	This option causes vutil to report additional (extended) information.

The basic information provided by the info function consists of:

text in the comment field (frequently empty)
Vision file format (Version 2, 3, 4, 5, or 6)
total number of records
total number of deleted records
file size of each segment (Version 4 and later)
total size of all segments combined (Version 4 and later)
segment size (maximum possible; Version 4 and later)
record size (min/max)
number of keys
user count

If you request extended information with the -x option, the following additional information is output:

for each key: key size (total size and number of segments, if split); key offsets; whether duplicates are allowed
block size
blocks per granule
tree height (max/min/avg)
number of nodes
number of deleted nodes
total node space
node space used
unique counter (count and progress towards the limit)

The tree height is the number of levels in the B-tree and is directly related to how efficient the file is. If the maximum number exceeds four or five, then the file may benefit from rebuilding with a larger block factor. See Rebuilding Files for more information.

An important piece of information is the user count. The user count is initially set to zero, and is incremented each time the file is opened for I/O. The 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 runcbl terminate abnormally, the user count may not be decremented. Therefore, if the user count is a non-zero value when there are no active users, it indicates that there may have been a sudden runtime failure and that corrective action may be required. At the very least, the file should be checked for integrity, but depending on the program that died, more significant action may need to be taken. A non-zero user count indicates that someone knowledgeable about the system should intervene and ensure that everything is okay. By monitoring the user count, the user count can be used as an early warning system to head off some types of file problems before they surface in a more serious form. Note that because runcbl usually closes all files when it detects an error, it is very unusual that a COBOL coding error will cause a non-zero user count condition. See Testing File Integrity for more information.

Note: Unlike RM/COBOL, a non-zero user count is not automatically an indication of a corrupt file. It merely means that a program has died while it had files open.

The unique counter displayed in the extended file information gives a running count and percentage towards the maximum number of records that can be written to a Vision file. The percentage should give you an indication of when to switch to a new file, as when the limit is reached, the file is marked as broken.