GetGTRecord

Read the record with key greater than target.

Short Name

GTREC()

Type

ISAM function

Declaration

COUNT GetGTRecord(COUNT keyno, pVOID target, pVOID recptr)

Description

GetGTRecord() reads the first data record whose key value in keyno is greater than the key value pointed to by target into the buffer area pointed to by recptr. If successful, the record becomes the current ISAM record for the data file associated with keyno.

GetGTRecord() is frequently used to search for the next value greater than target. If index file keyno accepts duplicate entries, pad the target key value with null bytes to ensure that the entry with the smallest suffix is found. See the example for GetGTEKey().

If the associated data file has variable length records, then only the fixed-length portion (defined by dreclen in the original call to CreateIFile()) is actually read into the buffer pointed to by recptr. If you wish to read the entire variable-length record into the same or a different buffer, call ReReadVRecord() after GetGTRecord(). ReReadVRecord() requires the specific size of the buffer area so that it can check if sufficient space is available.

Notice that the data file number involved is not directly identified. The ISAM structure definition described in “ISAM Functions” of the c-tree Plus Programmer’s Reference Guide, contains the relationship between the index file number and the associated data file.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful retrieval of current ISAM record.
33	DNUL_ERR	recptr is NULL. No data file read performed.
42	DLOK_ERR	Could not lock data record. No data file read performed.
101	INOT_ERR	No match for target key value found.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

Example

LONG      cust_number;

COUNT     keyno;

pTEXT     recptr;


scanf("%ld",cust_number);

if (GetGTRecord(keyno,&cust_number,recptr))

    printf("\nUnsuccessful search. Code = %d on file %d.",

           isam_err,isam_fil);

Limitations

No check is made to determine if recptr points to a region sufficiently large to accept a data record. If the area is too small, either code or data will be clobbered.