FairCom ISAM for C

NextKey

Find the next entry in an index file.

Short Name

NXTKEY()

Type

Low-Level index file function

Declaration

LONG NextKey(FILNO keyno, pVOID idxval)

Description

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

NextKey() searches index file keyno for the next entry in the index. If successful, it copies the index entry into the space pointed to by idxval. NextKey() fails if it is the first index search routine called after the index is opened, or if the entry found before the call to NextKey() is the last entry in the index. Repeated calls to NextKey() move through the index in ascending key value order.

Return

NextKey() returns the data record position associated with the next entry in the index file. If the index is empty or an error is detected, NextKey() returns zero. If NextKey() returns zero, check uerr_cod to see if an error occurred: if uerr_cod is also zero, then the index is empty; otherwise, an error condition was detected. See c-tree Error Codes in the c-tree Programmer’s Reference Guide for a complete listing of valid c-tree error values.

Example

LONG recbyt;

TEXT idxval[10]; /* 10 byte key, no duplicates */

FILNO keyno;

recbyt = FirstKey(keyno,idxval);

while (recbyt) {

printf("\nIndex Entry %.10s found in record #%ld",

idxval,recbyt);

recbyt = NextKey(keyno,idxval);

}

Limitations

No check is made to determine if idxval points to a region sufficiently large to accept a key value from the index file. If the area is too small, either code or data will be clobbered. Use GetCtFileInfo() to determine the key length.

The key value returned by this function will be a properly formatted key value (i.e., HIGH_LOW order, forced to upper case, etc.). The main issue is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments. Key Segment Modes (Key Segment Modes, /doc/ctreeplus/30863.htm) in the c-tree Programmer’s Reference Guide contains suggestions for manipulating the key value.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See also Record Offsets Under Huge File Support.