FairCom ISAM for C

GetLTERecord

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

Short Name

LTEREC()

Type

ISAM function

Declaration

COUNT GetLTERecord(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

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

GetLTERecord() 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 GetLTERecord() is LastInSet(), which reads the last data record whose key value matches the significant bytes in a target key; it is not necessary to pad the target when using LastInSet(). The main difference between GetLTERecord() and LastInSet() is that GetLTERecord() 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 GetLTERecord(). 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 (GetLTERecord(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.