isutl -k

Add or delete a key in an ISAM file

isutl -k[option] -key_command key_spec filename

Options

option

One or more of the following:

h or ?

Display help screen.

mlevel#

Specify a message level that defines the amount of information displayed during an operation, where level is a value from 0 to 2.

-t directory_list

(optional) Specify one or two directories (separated by a comma) to store temporary files. (See Temporary files for isutl.)

Answer “y” to all query prompts.

Display a running status (0 to 100) to indicate the percentage completed by the operation. (See Running status for more information.)

key_command

One of the following:

Indicates that the specified key should be added.

Indicates that the specified key should be deleted.

key_spec

See Key specification below.

filename

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

Discussion

Isutl -k works on Revision 6 or greater files. It enables you to add or delete a key in an ISAM file without converting the entire file to high-cooperative. You can use it for both HC and non-HC files.

Isutl -ka adds a key.

Isutl -kd deletes a key. To avoid deleting a key accidentally, you must specify the key number and the start and length of each segment. For example,

isutl -kd "start=10,length=5,keynum=3" myfile.ism

This process is essentially the same as hcutl -kd, but it has a few drawbacks:

Only the last key in a file can be deleted.
Isutl -k requires exclusive access to the file while deleting the key. If the file is high-cooperative, you'll be prompted that the key can be deleted with hcutl without requiring exclusive access and asked whether you want to continue with isutl. For example,

isutl -ka k=1,s=9,l=2,dups=noqual thatfile.ism

will trigger the following message:

You are about to add a key with exclusive access (hcutl wouldn't require exclusivity). 
Do you wish to continue with isutl (Yes/No)?

If you don't want to get this prompt, you can suppress it by specifying the -y option in your isutl command.

Isutl -k can’t add or delete a key at the same time that hcutl is adding or deleting a key, even if hcutl is interrupted in the middle of the operation. Therefore, isutl -ka can’t complete an interrupted hcutl -ka operation. (Isutl -r can complete an interrupted hcutl -ka operation if it doesn’t encounter any errors.)

Key specification

If key_spec is a single key specification or a dimensioned argument, the number of key_spec arguments or dimensions should be equal to or greater than the number specified by num_keys. A key specification in key_spec should have the following form:

START=pos_1[:pos_n], LENGTH=len_1[:len_n], KEYNUM=key_num
&     [, NAME=key_name][, TYPE=key_type_1[:key_type_n]]
&     [, ORDER=key_order_1[:key_order_n]][, DENSITY=key_density]
&     [, DUPS[=NOQUAL]|NODUPS][, MODIFY|NOMODIFY][, ASCEND|NOASCEND]
&     [, ATEND|NOATEND][, NULL=null_type][, VALUE_NULL=null_val]]

START=pos_1[:pos_n]

The starting position of the key or each segment of the key, starting with the first. You can specify up to eight positions, separated by colons.

LENGTH=len_1[:len_n]

The length of the key or each segment of the key. You can specify up to eight lengths, separated by colons; the number of lengths must match the number of start positions. The combined key can be up to 254 characters, depending on file type and duplicate handling:

Duplicate type	TBYTE file	Non-TBYTE file
No duplicates allowed	254	254
Qualified duplicates	250	251
Non-qualified duplicates	248	250

KEYNUM=key_num

Indicates the number of the specified key (0 for the primary key, 1 for the first alternate key, etc.) for a high-cooperative file.

NAME=key_name

(optional) The named key of reference for Synergy ISAM access. If the name contains spaces, the key name must be enclosed in quotation marks. The maximum key name length is 15 for Synergy ISAM.

TYPE=key_type_1[:key_type_n]

(optional) The type of key or segment. You can define one type for the key and all of its segments, or you can define a type for each segment. If you define the segments individually, you must include a type for every segment. See Key type for detailed information about each type.

ALPHA

Alphanumeric key (default)

NOCASE

Case-insensitive alphanumeric key

DECIMAL

Zoned decimal key

INTEGER

Native integer key

UNSIGNED

Native unsigned integer key

SEQUENCE

Automatically incremented i8 key

TIMESTAMP

i8 time key automatically generated on every record update

CTIMESTAMP

i8 time key automatically generated on a record’s initial STORE

Using integer keys (INTEGER, UNSIGNED, SEQUENCE, TIMESTAMP, and CTIMESTAMP key types) in an ISAM file requires special handling when unloading and loading is performed. Due to the chance that one of these keys contains data that could be interpreted as a record terminator, unloading to a sequential (or text) file is not recommended. Instead, we recommend using the fconvert utility to generate a counted file (-oc). (See fconvert for more information and further restrictions on text files.)

ORDER=key_order_1[:key_order_n]

(optional) Defines the order of the key or the order of each key segment: DESCENDING (or D) or ASCENDING (or A).

You can define one key order for the key and all of its segments, or you can define a key order for each segment. If you define the segments individually, you must include a key order for every segment.

This value overrides the ASCEND | NOASCEND option.

DENSITY=key_density

(optional) Specifes a number between 50 and 100 that represents the density percentage for that key. (See Key density for more information and suggestions about setting the key density.) This value overrides the file density for each key for which it is specified.

DUPS[=NOQUAL] | NODUPS

(optional) Specifies whether duplicate keys are allowed. The default is no duplicates (NODUPS). If the file is Revision 6.5 or higher (e.g.,, a high-cooperative file, a file that was created with another non-qualified duplicate key, or a file that was patched to 6.5 with isult -p), specifying DUPS=NOQUAL allows non-qualified duplicate keys. You’ll get an error if you try to add a non-qualified duplicate to a file with a lower compatability level. (See Non-qualified duplicate keys for more information.)

MODIFY | NOMODIFY

(optional) Specifies whether the key is modifiable. The default is not modifiable (NOMODIFY). The primary key cannot be modified.

ASCEND | NOASCEND

(optional) Specifies whether the key data will be sorted in ascending or descending order. The default is ascending order (ASCEND). This option is overridden by the ORDER option if it is specified.

ATEND | NOATEND

(optional) Specifies whether records that contain duplicate keys will appear at the end or at the beginning of a list of matching records. You can specify this option if you specify DUPS without "=NOQUAL". The default is at the end (ATEND).

NULL=null_type

(optional) Specifies that the key is a null key. In this context, a null key means that when a record is stored, and this key has a null value, no entry is placed in the index, thus saving file space, I/O, and processing. By default, a key is assumed to be null if it is filled with spaces. You can change this assumption using the VALUE_NULL option. The default null value is blank for alpha keys and 0 for numeric keys. You can specify null keys on alternate keys only, not on a primary key.

Null_type can be one of the following types. See Null keys for more information.

REPLICATE

Specifies that null_val is a single character and must match each byte of the specified key.

NOREPLICATE

If the key is alpha, specifies that null_val is a string that must match the key, from the beginning of the key, for the length of the string. If the key is numeric, specifies that null_val must match the numeric key value.

SHORT

Specifies that the key won’t be stored if the record doesn’t include the entire key on a STORE or WRITE. The file must have variable-length records.

VALUE_NULL=null_val

(optional) Indicates the null value for a null key, which can be specified as either a single character or a string. The default null value is a space. Enclosing the value in quotation marks is optional. For example:

"chr"       :       "0", " ", "\0"          ASCII representation
val         :       48,   32,   0           Binary representation
string      :       abc, "abc"              Nonreplicating string
numeric     :       100, "100"              Nonreplicating numeric string

You can abbreviate all key options to their shortest unambiguous length (e.g., "S" for "START" or "DU=NOQ" for "DUPS=NOQUAL"). However, for program clarity and to eliminate confusion with options that may be added in the future, we recommend that you specify the full option name.