isutl -p

Patch an ISAM file to another version

isutl -p [rev] -y [-qfile=patch_option] filename[ ...]

Options

rev

(optional) The ISAM revision to patch to. The default is 6 or the value of ISAMC_REV, if set. (See the Discussion for more information.)

-y

Answer “y” to all query prompts.

patch_option

(optional) One or more of the following options, separated by commas:

convert | noconvert

Force large files to be converted or small files to be patched. (By default, small files will be converted and large files will be patched. A patched file can later be patched back to the original revision, whereas a file that has been converted cannot be patched back.)

fullresilient

Make an existing Revision 6 or higher ISAM file FULLRESILIENT or add FULLRESILIENT during conversion from a lower revision to Revision 6. FULLRESILIENT is the same as RESILIENT, except it also causes the data file channel to automatically flush data on a write (STORE, WRITE, or DELETE).

hc[=numkeys]

Turn an existing Revision 6 or higher ISAM file into a high-cooperative file so you can use it with the hcutl utility. The optional numkeys specifies the number of virtual keys to allow when patching the file to high cooperative.

network_encrypt | nonetwork_encrypt

Set or unset the network encryption flag on the specified file.

resilient

Make an existing Revision 6 or higher ISAM file RESILIENT or add RESILIENT during conversion from a lower revision to Revision 6.

If you are patching to a higher version, you can also specify any of the -qfile options from isutl -r, and isutl will both perform the specified option and patch/convert the file to Revision 6. For example. if your file is Revision 4 and you specified “-p -qfile=compress,” isutl would both add compression and patch/convert the file to Rev 6.

virtual_keys=numkeys

The number of virtual keys to allow in an existing high-cooperative file.

filename

The name of the ISAM file(s) you want to patch. The default extension is .ism.

Discussion

Isutl -p patches one ISAM file revision to another revision (or to high-cooperative with -hc). By default (if rev is not specified), isutl -p patches Revision 2, 3, 4, or 5 files to Revision 6. For example, the following automatically patches all ISAM files with a .ism extension in the current directory to Revision 6:

isutl -p *.ism

If you specify a rev value of 6.5, the file will be patched to Revision 6.5 without being converted to high-cooperative. This could be useful if you want to add a non-qualified duplicate key to the file using isutl -ka. However, patching to Revision 6.5 will also prevent earlier runtimes from accessing the file. Therefore, if you specify a rev value of 6.5, you'll be prompted to confirm that you want to continue. You can suppress this prompt by specifying the -y option.

If you need to support Synergy versions prior to 10, set ISAMC_REV=4. This will ensure that your ISAM files remain compatible with your pre-v10 Synergy. (When ISAMC_REV=4, isutl -p patches Revision 2 or 3 files to Revision 5, which is a Revision 2 or 3 file structure in a Revision 4 format. Then the file can be used with isutl. Note that a Revision 5 file can only be accessed by Synergy version 7.5 or higher. Revision 2 and 3 files are no longer supported.)

If rev is specified, isutl will attempt to patch the file to that revision.

If -p is specified without the -qfile=convert option, a revision-only patch (to rev or the default revision if rev is not specified) occurs. The following files are implicitly converted to the new revision:

Files that contain 10,000 or fewer records whose record size is 4K or less.
Files that contain 1,000 or fewer records whose record size is greater than 4K.

Any files larger than these are patched to an intermediate revision (5r6 for Revision 2, 3, or 5 files and 4r6 for Revision 4 files). An intermediate revision file occupies the same footprint as the original file, but it’s a newer representation whose header contains structural differences for Revision 6. Over time, intermediate revision files are automatically converted to Revision 6 either after being cleared or after being rebuilt using isutl -ro. Alternatively, at a time when it’s convenient, you can issue the isutl -p -qfile=convert command to convert all of the large files to Revision 6.

When -p is specified with the -qfile=hc option, it patches a file to become high-cooperative. If the file has 10 million records or fewer, all the data is converted to high-cooperative automatically. However, if the patched file has more than 10 million records, patching with -qfile=hc puts the file in an intermediate state with just the file header updated. Then, you can run hcutl to finish converting the file. To prevent data conversion regardless of file size, you can specify -qfile=hc,noncovert.

Files with a page size of 512 or 1024 and no compression can't be converted to HC mode using hcutl, so isutl will refuse to patch them to intermediate HC mode unless it can fully convert them in a single operation.

To force data conversion regardless of file size, you can specify -qfile=hc,convert, but keep in mind that data conversion through isutl will require exclusive access to the file until the operation is complete, and it may take a long time. To avoid downtime, we recommend abiding by the default behavior and finishing data conversion using hcutl rather than isutl.

The numkeys setting for -qfile=hc and -qfile=virtual_keys allows you to set a non-standard number of virtual keys when patching a file to high-cooperative (for example, (isutl -p -qfile=hc=5 filename.ism) or modify the number of virtual keys in an existing HC ISAM file (for example, isutl -p -qfile=virtual_keys=10 filename.ism), respectively.

After patching a file to high-cooperative, you can check to see if it’s in an intermediate state by running hcutl -i.

When -p is specified with the -qfile=network_encrypt option, a revision patch (if rev was specified) occurs first and then the network_encrypt option is applied. If rev is not specified, the file revision is not changed; only the network_encrypt option is applied.

When the -qfile=resilient (or fullresilient) option is specified, re-indexing happens automatically to ensure the file is synchronized. However, if the file is known to be valid, specifying -qfile=resilient,noconvert will suppress automatic re-indexing with the warning “File has not been synchronized; initial state of the file is unknown. Running isutl -s or -r is recommended.” Running ipar on the file will display a similar message until the file is re-indexed or resynchronized. Until then, the file will operate as if it’s fully synchronized, even if it is not.