Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

ISAM File Relationships

ISAM parameters specify characteristics of data and index files used in your application. Parameters are stored in IFIL structures, C language based structures containing all the information needed to relate the data, indexes and key segments. These are collectively the IFIL, IIDX, and ISEG structures. These are stored as a file resource in the data file such that they persist. This means all information needed to create indexes for a data file is contained directly in that file.*

ISAM routines assume a hierarchical relationship among data and index files in the sense that each data file may have many indexes, while each index relates to only one data file. For example, an accounts payable system may define a vendor data file indexed by vendor name and number, and an invoice data file indexed by vendor number and invoice number. In this case, each of the data files has two indexes. Though each of the data files is indexed by vendor number, there is a separate vendor number index for each data file.

ISAM routines also assume that key values for each index can be derived from the contents of data records of an associated data file. As described below, the Key Segment parameter specifies how to extract a key value from a data record. See ctixmg.c for an ISAM structure example of variable-length records and their associated key values.

With only two exceptions, c-tree requires key values to be well formed up to the full length of the key (including the optional duplicate suffix). The exceptions are:

  • FirstInSet() and LastInSet() for which you explicitly indicate the number of bytes of the target key which are significant, so a complete key is not necessary.
  • Key segments located in varying length fields in the latter portion of a variable-length data record. In this case, c-tree automatically pads the key segment to the full segment length. Again, this is only applicable to the ISAM routines.

When using functions such as GetGTERecord(), a complete key is necessary in the sense that the bytes at the end of the target that you are not concerned about still must be set to an appropriate (padded) value. In these functions, ensure that the trailing insignificant bytes of the target are consistent with the padding used when the key value was added (typically an ASCII space or NULL (zero bytes).

When a low-level index function requires both an input key, target, and an output key, idxval, be sure that target and idxval DO NOT point to the same location.

The AddRecord() and AddVRecord() ISAM routines automatically form complete key values from the contents of the data records passed to them. The low level AddKey() function must be passed a complete key.

c-tree makes no assumptions about the individual bytes comprising a key value. In particular, a NULL byte IS NOT interpreted as the end of a key value. However, the varying length field concept supported for variable-length data records under ISAM control requires the concept of a field delimiter. The field delimiter separates fields in the variable-length portion of a variable-length data record. Therefore, a key value located in a varying-length field cannot contain the field delimiter byte.

Key Segment Modes (Key Segment Modes, /doc/ctreeplus/30863.htm) are very important for proper record retrieval. Be sure to review this section very carefully when designing your retrieval methods.

Legacy Note: Legacy ISAM support allowed for ASCII text files termed ISAM parameter files. FairCom recommends using Incremental ISAM Structures (IFILs) over the Parameter File approach for modern ISAM applications. Incremental structures provide individual file open/close/rebuild control and offer advanced features (i.e., file definitions automatically stored at file creation time, etc.), not available with the ISAM Parameter File.

Conversion utilities exist for migrating legacy parameter files to embedded IFIL resources.