FairCom ISAM for C

GetGTERecord

Read the record with key greater than or equal to target.

Short Name

GTEREC()

Type

ISAM function

Declaration

COUNT GetGTERecord(FILNO keyno, pVOID target, pVOID recptr)

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

GetGTERecord() reads the first data record whose key value in keyno is equal to, or 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.

GetGTERecord() is frequently used to start searching a file via an index file that accepts duplicate keys. GetRecord() 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 that the entry with the smallest suffix is found. See the example for GetGTEKey().

An alternative to GetGTERecord() is FirstInSet(), which reads the first data record whose key value matches the significant bytes in a target key; it is not necessary to pad the target when using FirstInSet(). The main difference between GetGTERecord() and FirstInSet() is that GetGTERecord() does not require any match with the target.

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 GetGTERecord(). 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 (ISAM Database Technology, /doc/ctreeplus/30841.htm) 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 FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

LONG cust_number;

FILNO keyno;

pTEXT recptr;

scanf("%ld",cust_number);

if (GetGTERecord(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.