FairCom ISAM for C

GetGTEKey

Search index file for entry equal to or greater than target.

Short Name

GTEKEY()

Type

Low-Level index file function

Declaration

LONG GetGTEKey(FILNO keyno, pVOID target, 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

GetGTEKey searches index file keyno for the first entry which is equal to, or greater than, the key value pointed to by target. If such an entry exists, it is copied into the area pointed to by idxval.

GetGTEKey() is frequently used to start searching an index file that accepts duplicate keys. GetKey() cannot be used since the index entries have suffixes appended. If index file keyno accepts duplicate entries, pad the target key value with null bytes to ensure the entry with the smallest suffix is found.

Return

If GetGTEKey() is successful, it returns the data record position associated with the entry found in the index. If an error occurs or no such entry exists, (either the index is empty or the target key value exceeds all entries in the index), GetGTEKey() returns a zero. When GetGTEKey() returns a zero, check the value of uerr_cod: if uerr_cod is non-zero, an error condition was detected; otherwise, no key value satisfied the search. See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNO keyno;

TEXT target[24],*idxval;

pLONG suffix;

/* Key length = 23. Assuming duplicates are allowed, the last

* four bytes are for the suffix. */

scanf("%19s",target);

suffix = target + 20; /* pointer to the last four bytes */

*suffix = 0L; /* set suffix to zero. */

/* Assumes no alignment restrictions. */

idxval = "12345678901234567890123";/*reserve space for idxval*/

if (GetGTEKey(keyno,target,idxval))

printf("\nthe key value >= %.19s is %.19s",target,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.

Note: 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 this presents is if binary key values will be displayed on a LOW_HIGH machine, it will be necessary to reverse any numeric segments.

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.