Rebuild an ISAM file (Revision 4 or higher)
|
WTSupported in traditional Synergy on Windows
|
WNSupported in Synergy .NET on Windows
|
USupported on UNIX
|
|
isutl -r [reload_options] [-c] [-h|-?] [-mlevel#] [-t directory] [-%] filename[ ...]
Arguments
reload_options
(optional) One or more of the following options for rebuilding the index:
Apply suggested database file corrections.
|
Improper use of the -a option can result in loss of data. Read the Discussion before using this option. |
Order database file by the specified key (or by primary key if a key is not specified) during the reload operation.
Pack index blocks to the specified percentage for each defined key during the reload operation. Note that -p does not change the file density setting.
Convert file using the specified options. Valid opt values are compress, tbyte, static_rfa, page=page_size, and density=density. (See the Discussion.)
Convert file to use static RFAs. (This option is ignored on Revision 6 ISAM files.)
-c
(optional) Convert file to compressed data.
-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.
-t directory
(optional) Specify a temporary file directory. See Temporary files for isutl -r 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 reload. The default extension is .ism.
Isutl -r recovers Revision 4 and higher ISAM files. Rebuilding an ISAM file can take several forms: re-indexing only, ordering data with re-index, converting data with re-index, and recovering data with re-index.
Re-indexing causes index blocks to be packed and arranged adjacent to related index blocks to enhance ISAM lookup performance. If index density is not defined, the following default packing percentages are used:
|
Page size |
Packing percentage |
|---|---|
|
512 |
80% |
|
1024 |
80% |
|
2048 |
90% |
|
4096 |
95% |
|
8192 |
97% |
|
16384 |
97% |
|
32768 |
97% |
If at least three key entries cannot fit into the space that’s left, the default percentage is reduced to 80% for all page sizes. If more (or less) empty index space is desired, specify the packing density explicitly with -p or change the density setting for the file with -qfile=density=density. See ISAM index density for more information about density.
In addition, the data file can be ordered by a preferred key to maximize sequential read performance. As a file grows, the speed of sequential access via any one particular key can become greatly reduced due to large disk seeks produced by the randomness of the inserted data. The -o option orders the data in key# order (or by primary key if key# is not specified) for the best sequential access for that key, making it more efficient. Key# must be a valid key number defined by the file.
|
|
When ordering data (isutl -ro filename), isutl generates a sort temporary file called filename_is1.257. (For example, if your .is1 file is named armast.ms1, the temporary file is armast_ms1.257.) If this file is left on your system due to abnormal termination of isutl, do not remove it. If isutl was in the process of writing data records to the .is1 file when termination occurred, the .257 file is required to completely restore your data. All other temporary files created by isutl (having the same filename with the extensions .000 – .256 or .258) are short-lived. Assuming these files are not in use, they can be removed without consequences. To resume the sort, run isutl -r again. |
|
|
xfODBC always assumes the primary key is the most optimal key by which to read the data. Therefore, xfODBC performance is affected if you reorder your data on an alternate key. |
Using this utility on a pre-Revision-4 file generates an error, unless isutl -p is used to convert the file to an appropriate revision first. See isutl -f for more information.
The -c and -s options will convert ISAM data to compressed and/or static RFA respectively. Once converted, these file attributes cannot be reversed using isutl. (To reverse the attributes, see fconvert.) Subsequent use of these options on the same file is ignored. If the compressed data option (-c), data reorganization option (-o key#), or data correction option (-a) is not specified, a new index file is created without altering the existing data file.
|
|
Static RFAs for a file may no longer be valid after altering the ISAM data file. The following reload options alter the data file: -c, -o, or -s. |
When converting (-c or -s) or ordering (-o) data, all unused RFA space and free space due to record deletions is reclaimed. To explicitly reclaim this space and reduce data file size, we suggest ordering the data periodically.
If the index packing density option (-p density) is not specified, the density defined for that key (or the default density if none is defined) is used.
The -qfile option enables you to set a string of file options in the format -qfile=opt[,opt,...], where each opt is one of the following:
Convert file to compressed data. (This is identical to the -c option.)
Convert to a terabyte file.
Convert file to use static RFAs. (This is identical to the -s option. It is ignored on Revision 6 ISAM files.)
Change the file’s index page block size. Valid page_size values are 512, 1024, 2048, 4096, 8192, 16384, and 32768.
Change the file density and pack the file, where density is the density percentage. (This differs from the -p density option in that it permanently sets the file density for all keys.)
Rebuilding an ISAM file always corrects existing index errors; however, errors in the data file may not be completely recoverable. Use of the -a option may be useful in these situations.
|
|
Isutl instructs you to use the -a option when necessary. This option causes isutl to recover as much data as possible, but to do so, it must alter the original data file. Once -a is performed, lost data cannot be recovered, so we highly recommend that you back up the file before using it. An alternative method of recovery is fconvert. Unless you are prompted to do so, we do not advise using -a. An exception file may be produced containing the unrecognized data removed from the file. Specifying multiple filenames is not allowed. Do not automate this process. |
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.
|
Writing temporary files to a secondary disk may improve overall performance. |
|
|
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) |
|---|---|
|
Re-index only (-r) |
2 * (size of largest key * #records) |
|
Order data (-ro) |
1.2 * size of in-use data |
|
Convert data (-rc or -rs) |
size of in-use data |
When re-indexing, the total disk space occupied (ISAM file plus temporary files) will not exceed the original size of the ISAM file (unless the packing density is reduced).
Running status
When the -% (display running status) option is specified, the numbers displayed indicate the percentage of the overall reload 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. |
When the file is successfully processed, the current date is written to the index control record to indicate the last recover. This information can be accessed using the ipar utility.
|
|
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. |
Isutl generates a log file named isutl.log that records its operations and results. Each log file entry specifies the ISAM filename, the operation performed, the date and time the operation was performed, the command line options supplied to isutl, the exit status, and the amount of time the operation took. The log file is created in the TEMP directory. (We recommend always using ISUTLLOG to specify the log file location on these systems.) The maximum size of the log file defaults to 1 megabyte, unless the ISLOGMAX environment variable defines a different maximum. To disable logging, set ISLOGMAX to 0.
