isutl -r

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:

-a

Apply suggested database file corrections.

Important

Improper use of the -a option can result in loss of data. Read the Discussion before using this option.

-l

Re-index using coordinated locking without requiring exclusive access. (See the Discussion for limitations.)

-le

Re-index with exclusive access locking. (default)

-o [key#]

Order database file by the specified key (or by primary key if a key is not specified) during the reload operation.

-p density

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.

-qfile=opt[,opt,...]

Convert file using the specified options. Valid opt values are compress, tbyte, static_rfa, page=page_size, and density=density. (See the Discussion.)

-s

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_list

(optional) Specify one or two directories separated by a comma to store temporary files. 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.

Discussion

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.

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 options require exclusive access locking and are not allowed with coordinated locking: -o, -qfile, -s, -c, and -a.

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.

Important

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.

Important

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.

Important

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:

compress

Convert file to compressed data. (This is identical to the -c option.)

tbyte

Convert to a terabyte file.

static_rfa

Convert file to use static RFAs. (This is identical to the -s option. It is ignored on Revision 6 ISAM files.)

page=page_size

Change the file’s index page block size. Valid page_size values are 512, 1024, 2048, 4096, 8192, 16384, and 32768.

density=density

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.

Important

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.

Temporary files for isutl -r

Tip

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

The -t (temporary file directories) option specifies one or two directories 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). A temporary file location should be a different physical disk or LUN than the ISAM file. An xfServer remote file specification is not supported. The default location for temporary files is the current directory.

For very large files, if you have access to more than one separate physical disk, using the -t option to separate temporary files from the original file can help with disk space management as well as give you better performance.

There are three options:

-t key_tempfilesdirectory,sort_tempfilesdirectory

-t all_tempfilesdirectory

-t ,sort_tempfilesdirectory

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.

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.

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.

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, and the amount of time the operation took. The log file is created in the c:\ProgramData\Synergex\SynergyDE\dbl directory on Windows and in DBLDIR: on UNIX. (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.