Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic


Find the first entry in an index file.

Short Name



Low-Level index file function


LONG FirstKey(FILNO keyno, pVOID idxval)


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

FirstKey() searches index file keyno for the first entry in the index. If successful, it copies the first index entry into the space pointed to by idxval.


FirstKey() returns the data record position associated with the first entry in the index file. If the index is empty or an error is detected, FirstKey() returns zero. If FirstKey() 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 FairCom DB Error Codes for a complete listing of valid FairCom DB error values.


TEXT idxval[10];

FILNO keyno;

if (FirstKey(keyno,idxval))

printf("\nFirst index entry = %.10s", idxval);

else {

printf("\nEither index is empty or an error occurred.");

if (uerr_cod)

printf("\Error = %d",uerr_cod);


printf("\Index is empty.);



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. The Key Segment Modes (Key Segment Modes, /doc/ctreeplus/30863.htm) topic contains suggestions for manipulating the key value.

See also

GetCtFileInfo(), LastKey(), NextKey()