isutl ‑v

Verify the integrity of an ISAM file (Revision 4 or higher)

WTSupported in traditional Synergy on Windows
WNSupported in Synergy .NET on Windows
USupported on UNIX

 

isutl ‑v [verify_options] [‑c] [‑h|‑?] [‑mlevel#] [‑t directory] [‑%] filename[ …]

Arguments

verify_options

(optional) One or more of the following options for verifying the ISAM file(s):

‑b

Report bucket usage statistics and freelist usage.

‑i

Launch the information advisor to provide a full analysis of file organization and content. (See isutl ‑i for more information.)

‑l

Verify using cooperative locking without requiring exclusive access. If a locked record is encountered, isutl waits for the record to become available. (default)

‑le

Verify with exclusive access locking.

‑ln

Verify files that don’t allow locking (e.g., read‑only files).

‑n

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.

‑z

Scan for all problems, rather than stopping at the first detected problem.

‑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 value.

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 for more information.

3 = Verbose key information is displayed.

‑t directory

(optional) Specify a temporary file directory. See Temporary files for isutl ‑v in the Discussion for more information.

‑%

(optional) Display a running status (0 to 100) to indicate the percentage completed by the operation.

filename

The name of the ISAM file(s) whose index structure you want to verify. The default extension is .ism.

Discussion

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. By using the ‑z option, a more linear scan is performed and all errors are displayed in context, which may reveal the entire severity. The ‑z option, however, can be more time consuming, especially with very large nonoptimized files. In other words, regardless of how many problems a file contains, isutl ‑v stops at the first problem detected and generates an error, while isutl ‑vz detects all the problems that it can but might be somewhat slower.

Tip

We recommend running without ‑z first, and then using ‑z only on files that show problems.

By default, the ‑l option is enabled, which turns on cooperative locking. Cooperative 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.

Message level

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.

Tip

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.

Temporary files for isutl ‑v

The ‑t (temporary file directory) option specifies a directory for all temporary work files files. The directory specification must be a valid path specification or logical that references a local or network drive. An xfServer remote file specification is not supported. The default location for temporary files is the current directory.

Tip

Writing temporary files to a secondary disk may improve overall performance.

Important

When processing large ISAM files, make sure sufficient disk space is available for the temporary work files.

The amount of disk space required for temporary files varies with the operation. In general, you can assume the following:

Operation

Maximum temporary file size (approximate)

Verify (‑v)

(overall index density * size of index file) + (size of largest key * #records) or ~ 80% size of index file

Verify linear (‑vz)

No temporary files used

Running status

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 exit statuses are as follows:

This status

Indicates

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.

Important

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.