Rebuild an ISAM file (Revision 4 or higher)
|
WSupported on Windows
|
USupported on Unix
|
|
NSupported in Synergy .NET
|
isutl -r [reload_option] [-c] [-h|-?] [-mlevel#] [-t directory_list] [-%] filename[ ...]
Options
reload_option
(optional) One or more of the following for rebuilding the ISAM file:
Apply suggested database file corrections.
|
Improper use of the -a option can result in loss of data. Read the Discussion before using this option. |
Run deep scan of database file. (See the Discussion for more information.)
Re-index using coordinated locking without requiring exclusive access. (See the Discussion for limitations.)
Re-index with exclusive access locking. (default)
Order database file by the specified key (or by primary key if a key is not specified) during the reload operation. Specify -g to reset stored GRFA GUIDs on files with SGRFAs defined. (Using -g is not recommended unless bad GUIDs are detected. Unnecessary usage will result in performance degradation.)
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, density=density, page=page_size, sgrfa, static_rfa, and tbyte. (See the Discussion.)
Convert file to use static RFAs. Use of this option may reorder data. (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 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.
-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 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. Using isutl -r alone (without any of the reload or other options listed above) just re-indexes the file without modifying the data file in any way (including RFAs).
The -d option explicitly performs low-level checking and validation of data during recovery. It is typically used to enhance recovery when data corruption is known to be present. As a result of the additional overhead, running isutl will take longer with -d.
The -l option 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 re-index is complete. This enables you to rebuild the index of a file that is in use by other users. By default, the -le option is enabled, which turns on exclusive access locking and requires that the file not be open by any other process. The following isutl -r options require exclusive access locking and are not allowed with coordinated locking: -a, -o, -qfile, -s, and -c.
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.
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 option converts ISAM data to compressed data. Once converted, the file attribute cannot be reversed using isutl. (To reverse attributes, see fconvert.) Subsequent use of -c on the same file is ignored. If the compressed data option (-c), data ordering option (-o key#), or data correction option (-a) is not specified, a new index file is created without altering the existing data file.
When converting or ordering 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.
|
|
Converting or reordering the data file using the -a, -c, -o, -s, -qfile (with compress, sgrfa, static_rfa, or tbyte), etc., affects the positioning of records in the file, which in turn alters static RFAs and GRFAs. |
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.)
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.) To remove all defined key density settings on an existing file, set density=0. This may improve the runtime performance of a large file with key density defined on all keys. See ISAM index density for more information about density.
Change the file’s index page block size. Valid page_size values are 512, 1024, 2048, 4096, 8192, 16384, and 32768.
Add stored GRFA to a Revision 6 or greater ISAM file.
Convert file to use static RFAs. (This is identical to the -s option. It is ignored on Revision 6 ISAM files.)
Convert to a terabyte file.
On files whose index depth on any key is greater than 4 or whose index file size is greater than 4 GB, an implied page size conversion (-qfile=page=8192) will occur, raising the size to 8192 if the current page is less than that. Additionally, on files whose current index file size is greater than 4 GB, an implied packing density of 97% will occur. Furthermore, on files with autokeys (SEQUENCE, TIMESTAMP, or CTIMESTAMP), the defined key density for those keys will be set to 100% for optimal space management and performance.
Rebuilding an ISAM file always corrects existing index errors; however, errors in the data file may not be fully recoverable. As of 11.1.1h, rebuilding the file with just isutl -r (without -o, -a, or any file conversion options) will attempt to re-index around bad data, leaving the file with a complete index that can still be accessed without error until more corrective measures can be performed on the file. (This is especially useful when full recovery could result in significant downtime.) As a corrective measure, the -a option may be used to extract bad data.
|
|
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. |
|
|
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. |
|
If you use one or more of the reload options (for example, isutl -ro), you do not need to run isutl -r before or after by itself. |
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 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 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. |
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.
Logging
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, the amount of time the operation took, and whether the number of records processed in the file scan phase differed from the index count.
The log file is created in the c:\ProgramData\Synergex\SynergyDE\dbl directory on Windows and in DBLDIR: on Unix. If these directories are not available, the log file will be created in the tmp directory as a failover location, and you will be notified of the location change. (We recommend always using ISUTLLOG to specify the log file location.) 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.
