TISAM

Define Thoroughbred ISAM File

This directive is used to create a new, multiple key data file (Thoroughbred ISAM) that is structurally compatible with C-ISAM, in a logical disk directory. Refer to the REMARKS section for information on specific compatibility issues: Not all C-ISAM files can be used under Thoroughbred Basic.

Syntax

TISAM file-name, sortdef1 [ :mode1 ] [, sortdef2 [ :mode2 ]
[, ... sortdefn [ :moden ]]] , num-records, record-size, disk-num,
sector-num [,ERR=line-ref|,ERC=error-code]

file-name: is any string of 8 characters or fewer used to name this file.
sortdef1,2,n: define the sort keys. There may be from 1 to 16 sort keys defined, and the first sort key defined constitutes the primary key. All sort keys must be unique.
:mode1,2,n: is any string whose first character is "U" or "u" signifying that this sort key sequence must have unique keys; "D" or "d", indicating that this sort key sequence may have duplicate keys. "U" is the default for the first sort key sequence defined; "D" is not valid for the first sort key sequence (it must be unique). "D" is the default for all other sort key sequences if not specified. The colon (:) is required in the syntax.
num-records: is a positive integer, required in the syntax, but ignored by TISAM. The actual number of records is limited only by physical disk storage space.
record-size: is an integer in the range of 1 to 32600 indicating the number of bytes in each record in this file.
disk-num: specifies the logical disk directory that contains this file. Valid values are 0 through 35.
sector-num: is the number 0 (zero) or a positive, even integer in the range of 128 to 65536. If 0 (zero), then the Index Blocking Factor for the .idx file is 1024 bytes. If a positive, even integer in the range of 128 to 65536 is specified, then that actual value is then used as the index blocking factor.
line-ref: is the program line number or label to branch to if this directive produces an error.
error-code: is a programmer-defined error code. Valid values are positive or negative whole numbers.

Remarks

This directive is generally available starting with release level 8.1.

Sort key sequences are defined with the sortdef1,2,n parameters indicated in the above syntax. Each sort key sequence may contain multiple segments (up to 8 segments) and those segments may overlap one another. Syntax for a sort key sequence is shown by:

[ segdef1 [ + segdef2 [ ... + segdefn ]] ]

segdef1,2,n: is composed of field, offset, length, and ordering data, so that expanding a segdef looks like:

offset-num:key-length[:sort-order]

offset-num: is an integer from 1 to the length of the record in bytes signifying the beginning byte position within the record for this key segment.
key-length: is an integer from 1 to 144 specifying the length, in bytes, of this key segment. If a length is specified that is longer than the record length, the remaining byte positions are set to null or binary zero. Each key-length must not exceed a length of 144, and the sum of all key-lengths must not exceed 144.

Note: Any key-length greater than 120 characters will not be accepted by the INFORMIX C-ISAM product line.

sort-order: is any valid string whose first character designates the sorting order for this key segment: "D" or "d" indicates descending order; "A" or "a" indicates ascending order. The default is ascending order.

The first sort key sequence defined is the primary sort key. Each data record must have a unique primary key. Secondary keys may contain duplicates unless their mode is “U”.

A TISAM file can have multiple sort key sequences. Each sort key sequence can be made up of multiple segments (up to 8 each). Unlike DIRECT files, the segments that make up all keys must be contained within the actual data record.

The TISAM directive need only define a single sort key sequence. The ADDSORT directive provides for the addition of more sort key sequences, and the REMSORT directive provides for the deletion of specific sort key sequences.

The key structure that is used for all input/output operations is specified by the SRT= I/O option with [P]READ and [P]EXTRACT directives. If not specified, the default SRT is the first, or primary, sort key sequence.

An attempt to WRITE a record to a TISAM file whose primary key is not unique results in an ERR=11 (Duplicate Key). An attempt to WRITE a record to a TISAM file with a secondary key specified as unique results in an ERR=11 (Duplicate Key) if the secondary key is not unique.

Starting with release level 8.3.1, TISAM files support the ability to access and update files that contain compressed duplicate keys. This feature enables support of Informix SE version 4.x.

Examples

TISAM "TEST",[2:5]+[16:6]+[3:2:"D"], [1:6] :"U", 1000, 256, 3, 0

creates a TISAM file with 1000 records, 256 bytes each, on logical disk directory number 3 with a default block size of 1024 bytes for the index file. The primary sort definition is described by the following three segments:

Segment 1 starts at the second byte of the record and is 5 bytes long, with an ascending sort

order as default.

Segment 2 starts at the 16th byte of the record and is 6 bytes long, with an ascending sort

order as default.

Segment 3 starts at the third byte of the record, is 2 bytes long, with a descending sort order.

The secondary sort definition starts at the first byte of the record for 6 bytes and has unique keys.

TISAM

Syntax

Remarks

Examples

See also