FairCom ISAM for C

All the incremental ISAM functions require a pointer to an IFIL structure as their input parameter. The IFIL structure defines the characteristics of the data file and includes a pointer to a structure that defines the associated indexes.

The formal type definition for IFIL follows:

typedef struct ifil {

pTEXT pfilnam, /* file name (w/o ext) */

FILNO dfilno, /* data file number */

UCOUNT dreclen, /* data record length */

UCOUNT dxtdsiz, /* data file ext size */

COUNT dfilmod, /* data file mode */

COUNT dnumidx, /* number of indexes */

UCOUNT ixtdsiz, /* index file ext size */

COUNT ifilmod, /* index file mode */

pIIDX ix, /* index information */

pTEXT rfstfld, /* r-tree 1st fld name */

pTEXT rlstfld, /* r-tree last fld name */

FILNO tfilno /* temporary file number */

} IFIL;

Note: pTEXT is a c-tree data type that equates to TEXT *. For example, pTEXT pfilnam is the same as TEXT *pfilnam. The same holds true for all ‘p’ data types, i.e., pISEG = ISEG *.

In V12 the file number typedef was formally changed from COUNT, a two-byte value to FILNO, a four-byte value. Refer to this link for compatibility details. Four Byte File Numbering

Each index is described by an IIDX structure. If a data file has associated indexes, the ix member of the IFIL structure must point to an array of IIDX structures. In particular, there must be dnumidx elements (i.e., IIDX structures) in the array.

Each IIDX structure defined over a given data file receives a unique file number assigned sequentially from the data file number tfilno. For example, if tfilno is file number 5, and this data file has 3 indexes, they receive file numbers 6, 7 and 8. 6 is assigned to the IIDX structure pointed to by the IFIL element ix, 7 is assigned to the next IIDX structure, and 8 to the last IIDX structure for this particular data file. Since each IIDX structure gets its own file number, there is no difference in performance between placing all IIDX definitions for a particular data file in the same physical file or in individual physical files.

The formal type definition for IIDX follows:

typedef struct iidx {

COUNT ikeylen, /* key length */

ikeytyp, /* key type */

ikeydup, /* duplicate flag */

inulkey, /* NULL key flag */

iempchr, /* empty character */

inumseg, /* number of segments */

pISEG seg, /* segment information */

pTEXT ridxnam, /* r-tree symbolic name */

pTEXT aidxnam, /* optional index file name */

pCOUNT altseq, /* optional alternate sequence */

pUTEXT pvbyte /* optional pointer to pad byte */

} IIDX;

The following text provides additional information about select IIDX elements:

ikeylen - The sum of the segment lengths (defined below). If duplicates are allowed, the last 4 bytes of the key value are reserved for the 4 bytes of the associated data record offset. For example, a key length of 12 bytes allowing duplicates has 8 bytes of actual key value and 4 bytes for the tie-breaking data record offset. DropIndex() marks a transaction-controlled index for deletion by setting keylen to -keylen until the drop is committed. A GetIFile() call after the DropIndex() call, but before the Commit() or Abort() will return this interim setting.

ikeytyp - Valid key types are listed below. For additional information, consult Alternative Key Types.

See also Alternative Key Types.

Note: Key compression imposes a significant performance impact, especially when deleting records. Use this feature only when absolutely necessary to keep index space requirements to a minimum.

ikeydup - Duplicate flag. A parameter value of one indicates the index supports duplicates, add 4 bytes to the key length (see ikeylen above). A parameter value of zero indicates the index will NOT support duplicates, making all key values unique. Zero and even numbered values indicate unique indexes, odd values allow duplicates key values.

inulkey - Determines if NULL or missing key values are detected. After concatenating the key segments according to the ISEG array, the NULL key flag parameter determines whether or not to test for a missing value. If the key value matches the null key value definition according to the index's inulkey setting, as described below, it is considered NULL or missing and not entered into the index file.

iempchr - The empty character is expressed in the decimal equivalent of the character. For example, an ASCII space (0x20) is specified with a value of 32. A NULL byte (0x00) is specified with a value of zero.

inumseg - The number of segments concatenated to form a key value from the data record contents.

ridxnam - If r-tree or d-tree is used with this application, define this arbitrary index name. It must start with an alphabetic character and may include upper and lower case letters, numbers, and underscores. It may not include embedded blanks. Symbolic names are not necessary for the data files because each has a unique name.

aidxnam - (Optional) Permits Incremental ISAM files to have more than one index file and to locate an index file independently from the data file. The index file name must agree with the operating system file naming conventions. If not NULL for the first member of the IIDX array, this file name is used instead of being derived from the IFIL pfilnam parameter. This allows the index to be located in a different path or a different device. If not NULL for subsequent members of the IIDX array, this name is used to create additional host index files. All following member indexes will be located in the new index file.

Each key value is composed of one or more segments. A segment is simply a sequence of bytes from a specified offset within the data record. Each key segment is described by an ISEG structure. The seg member of each index IIDX structure must point to an array of ISEG structures. In particular, there must be inumseg elements (i.e., ISEG structures) in the array. The formal type definition for ISEG follows:

typedef struct iseg {

COUNT soffset, /* segment position (offset) */

slength, /* segment length */

segmode /* segment mode */

} ISEG;

Segment Position

The segment position specifies the location of the key segment within the data record. This can be specified in one of three ways, as determined by the segment mode value (see Key Segment Modes):

1. Absolute byte offset. The number of bytes from the beginning of the data record to the first byte of the key segment. The smallest offset, zero, means that the segment begins with the first byte of the record. If a segment begins with the nth byte of the record, its offset value should be n minus one.
   This option works with fixed length fields, which have known offsets.
2. Relative field number. The segment position is treated as a field number, not a byte offset. This applies only to variable-length data records. With variable-length records, all of the fields in the variable-length portion are variable-length fields terminated with a delimiter. This delimiter is typically the NULL character, unless the default is changed by SetVariableBytes(). A segment position of zero corresponds to the first variable-length field, beginning at the first byte beyond the variable-length file’s fixed-length portion. When a variable-length file is created, the record length parameter is treated as the minimum record length, which corresponds to the fixed-length portion of the record.
   This option works with variable-length string types using NULL terminators.
   The following schematic demonstrates how varying-length fields are numbered. The delimiter is shown as a NULL byte, but can be any delimiter you set:

   

3. Record Schema field number. When using a Record Schema, (Record Schemas), use a schema segment type and specify the segment position by the field number in the record schema. The first field in the schema is field zero.

   This option works with any type of data in any part of the record, allowing key segments on non-variable-length data types in the variable-length portion of the record. All fields in the variable-length portion must be packed as opposed to aligned. No padding bytes are allowed between fields.

Though segoffset is a COUNT field, since a fixed length file or the fixed length portion of a variable-length file may exceed 32767 bytes, segment offsets exceeding 32767 bytes, but less than 65535 bytes, are supported. The internal logic deals with segment offsets that “go negative”. A minus one for a segment offset (equivalent to 65535 for a UCOUNT) still signifies the “end of segments” so that segment offsets can now range from 0 to 65534. If a value greater than 32767 is stored in a COUNT field, it appears as a negative value; but its unsigned integer value correctly corresponds to the original value. For example, storing 65534 into a COUNT results in a value of -2 when expressed as a COUNT, but -2 cast to a UCOUNT corresponds to 65534.

Segment Length

The segment length specifies the number of bytes that this key segment will take in the key itself. The sum of the segment lengths for an index file must equal the key length unless duplicate keys are allowed. In this case, the segments should sum to the key length less 4 bytes. If the sum of the segment lengths does not match the key length, CreateISAM(), OpenISAM(), CreateIFile(), or OpenIFile() return error ISLN_ERR (115).

For variable-length fields, segment modes 4 and 5, c-tree automatically pads a key segment to the full segment length using the padding byte. The padding byte defaults to an ASCII space (0x20), but can be changed using SetVariableBytes(). When using a field other than a variable-length field, make the segment length less than or equal to the actual size of the field.

Segment Mode

The segment mode determines what transformations, if any, must be made to the key segment. In addition, it determines which of the three methods of determining the segment position will be used.

Detailed information on key segment modes is presented in the Key Segment Modes section. When using a Record Schema to manage the building of keys, refer to Record Schemas for more information.