GetGTKey

Search index file for entry greater than target.

Short Name

GTKEY()

Type

Low-level index file function

Declaration

LONG GetGTKey(COUNT keyno, pVOID target, pVOID idxval)

Description

GetGTKey() searches index file keyno for the first entry that is strictly greater than the key value pointed to by target. If such an entry exists, then it is copied into the area pointed to by idxval.

Return

If GetGTKey() 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), then GetGTKey() returns a zero. When GetGTKey() returns a zero check the value of uerr_cod: if uerr_cod is non-zero, an error was detected; otherwise, no key value satisfied the search. See “c-tree Plus Error Codes” in the c-tree Plus Programmer’s Reference Guide for a complete listing of valid c-tree Plus error values.

Example

COUNT   keyno;

TEXT    target[24],idxval[23];

LONG    recbyt;


ctsfill(target,0,24);

ctsfill(idxval,0,23);

scanf("%23s",target);

recbyt = GetGTEKey(keyno,target,idxval);

while (recbyt) {

    printf("\nIndex entry = %23s Record # = %ld",

           idxval,recbyt);

    cpybuf(target,idxval,23);

    recbyt = GetGTKey(keyno,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.

The key value returned 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.