Verify the integrity of an ISAM file (Revision 4 or higher)
|
WSupported on Windows
|
USupported on Unix
|
|
NSupported in Synergy .NET
|
isutl -v [verify_option] [-c] [-h|-?] [-mlevel#] [-t directory_list] [-%] filename[ ...]
Options
verify_option
(optional) One or more of the following options for verifying the ISAM file(s):
Report bucket usage statistics and freelist usage.
Run deep scan of database file. (See the Discussion for more information.)
-f
Display the number of file fragments in both index (.ism) and data (.is1) files. (Windows only)
Launch the information advisor to provide a full analysis of file organization and content. (See isutl -i for more information.)
Verify using coordinated locking without requiring exclusive access. (default)
Verify with exclusive access locking.
Verify files that don’t allow locking (e.g., read-only files).
Bypass use of the data file and verify only the index during the verify operation. Do not use this option when file integrity is in question.
Scan using alternate linear algorithm. (See the Discussion for warnings about this option.)
-c
(optional) Report expected compression savings.
-h or -?
(optional) Display help screen.
-mlevel#
(optional) Specify a message level that defines the amount of information displayed during an operation, where level is one of the following values:
0 = No output is generated. All errors generated are returned in the form of an exit status. (See Exit status in the Discussion.)
1 = Only errors and necessary output are displayed. (default)
2 = Process information is displayed, in addition to errors and necessary output. (See Message level in the Discussion.)
3 = Verbose key information is displayed.
-t directory_list
(optional) Specify one or two directories (separated by a comma) to store temporary files. (See Temporary files for isutl in the Discussion.)
-%
(optional) Display a running status (0 to 100) to indicate the percentage completed by the operation. (See Running status in the Discussion.)
filename
The name of the ISAM file(s) whose index structure you want to verify. The default extension is .ism.
Isutl -v verifies the integrity of a Revision 4 or higher ISAM file. By default, the verify option uses the fastest optimized methods to assure file integrity. If isutl detects something that would result in a Synergy data access failure, it generates an error and stops the verify operation. With the -z option, a more linear scan is performed and all errors are displayed in context, which may reveal the entire severity. However, the -z option can degrade performance significantly.
|
We recommend that you do not use the -z option unless directed by Synergy/DE Developer Support. |
The -d option explicitly performs low-level checking and validation of database file components. It is typically used only for diagnostic purposes when data corruption is detected. As a result of the additional overhead, running isutl will take longer with -d.
By default, the -l option is enabled, which turns on coordinated locking. Coordinated locking means other processes can have the file open, but processes attempting to read or write to the file may be suspended until the verify is complete. The -le option turns on exclusive access locking, which requires that the file not be open by any other process, and it cannot be opened by any other process while the verify is running. The -ln option allows verification of files that don’t support locking, such as read-only files or files on a CD-ROM.
|
|
Be careful when using -l on very large files on live systems, especially those without SSD drives. Processes may hang for minutes to hours and can cause potential web application timeouts. |
Isutl -vb provides output that looks something like this:
Bucket Allocation:
slen #inuse %free #free lhead
1: 563 750 0 2031 0xdb95d
Unusable: 1 segments, 563 bytes
Segment bytes: total = 1566266, unused = 563 (0%)
Freelist use:
2031 data segments (73% free)
70 index blocks (68% free)
The sample output above tells us several things: This is a fixed-length record file (because there’s only one bucket), the record size is probably around 550 bytes, and the attrition of records seems to outweigh their increase. Since there’s only one bucket, and #free is nonzero, all STOREs are going to take a freelist entry. The fact that there even is a freelist tells us DELETEs outweigh STOREs. The amount of space being taken up by free space is only around 1 MB. Additionally, 1 unusable segment tells us that we have a high amount of segment reuse and that this file probably has static RFAs, which limits the number of times a segment can be reused and still maintain a unique RFA.
A high freelist percentage indicates that a large number of records have been deleted without being replaced with new records. In most cases, having a positive free list is a good thing, because storing new records doesn’t cause the file to grow any bigger. The information advisor (-vi) reports an excess on files exceeding 10 MB when more than half the file is taken up by the freelist. If you need to reduce the freelist size and/or reclaim unusable segments (which also reduces the overall file size), you can run isutl -ro to initialize the freelist (in both the data and the index).
To measure the degree of a file’s optimization, specify the -m2 flag. For each key, a line will be displayed that indicates, as a percentage, the optimization level as well as the sequential order of the data file. For example:
Primary key, 751406 blocks (728570 leaf), 19416428 records Index density 50%, leaf 50%, separator 50% Optimization: index 44%, data 95%
The index percentage indicates the percentage of on-disk index blocks for the target key that can be accessed quickly from a previous index block with the least amount of disk overhead. The data percentage indicates the percentage of data records in a sorted order giving the least amount of disk overhead when reading sequentially by that key. The effectiveness of these percentages vary depending on file size and hardware configuration. They tend to become more significant as the file size exceeds the available file cache memory on a system. No additional overhead is consumed as a result of getting this information.
|
To get this optimization information quickly and accurately on a large file, you can also specify the -n verify flag. However, you shouldn’t rely on the verification results, because only the index is verified. |
|
|
Isutl does not support loading records with binary data from sequential files (excluding counted files). Attempting to do so can cause some records to split into two records in the ISAM file. To load a relative file that contains binary data into an ISAM file, use the fconvert utility. |
The -t (temporary file directories) option specifies one or two directories, separated by a comma, for temporary work files used by isutl. The directory specifications must be valid path specifications or logicals that reference a local or network drive (although we do not recommend network locations except as a way to provide enough space). An xfServer remote file specification is not supported. The default location for temporary files is the current directory.
If only the first directory is specified, it is the directory in which to place all temp files (all_tempfilesdirectory). If two directories are specified, the first is the directory in which to place all key files (key_tempfilesdirectory). The directory specified after the comma (regardless of whether or not a first directory is specified) is the directory in which to place all sort files (sort_tempfilesdirectory).
Using -t is useful in managing disk usage, but it can also be used to improve performance. Using temp directories for better performance is accomplished by isolating I/O operations to separate physical disks (especially on SSD drives). Here are some options:
-
Performance will be better if both keys and sort files are located on separate disks from the target file: -tall_tempfilesdirectory.
-
Performance may improve even more if the sort files are located on a different disk to separate the input files from the output sort files during the key sorts: -t key_tempfilesdirectory,sort_tempfilesdirectory.
-
On files with multiple keys and only a single secondary disk available, offloading just the key sorts and leaving the key files on the current disk may improve performance by specifying just the sort directory preceded by a comma: -t ,sort_tempfilesdirectory.
|
The use of temporary files to enhance performance is only beneficial when the specified directories reside on a different physical disk or LUN, not just different directories or file systems on the same drive. |
For very large files, if you have access to more than one physical disk, we recommend using the -t option for better performance as well as space management.
|
|
Make sure sufficient disk space is available for temporary work files, especially when processing large ISAM files. The amount of disk space required for temporary files varies with each file and operation being performed. |
When the -% (display running status) option is specified, the numbers displayed indicate the percentage of the overall verify operation completed for each file. When message level 2 (-m2) is also specified, an individual process percentage as well as a total overall percentage is displayed for each file.
Isutl generates an exit status, which can be especially useful if you’ve used the -m0 option. Possible return values are as follows:
|
Exit status |
Meaning |
|---|---|
|
0 |
Isutl was successful. |
|
A Synergy DBMS error number |
Isutl failed as a result of the specified error. (See Synergy DBMS errors for the message text that maps to each error number.) |
|
-1 |
More than one file was specified on the command line, and at least one file failure occurred. |
If you use the -z option on a corrupted file, the exit status reflects the first error only.
When the file is successfully processed, the current date is written to the index control record to indicate the last verify. This information can be accessed using the ipar utility.
