FairCom ISAM for C

GetRecord

Get data record with key equal to target value.

Short Name

EQLREC()

Type

ISAM function

Declaration

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

GetRecord() searches index file number keyno for an entry matching the key value pointed to by target. If an exact match is found, GetRecord() reads the associated data record into the buffer area pointed to by recptr, and this record becomes the current ISAM record. If no match is found or an error occurs, the current ISAM record remains unchanged.

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, issue a call to ReReadVRecord() after the call to GetRecord(). Note that ReReadVRecord() requires you to specify the size of the buffer area so that it can check if sufficient space is available.

Notice that you do not directly identify the data file number involved. The IFIL structures described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Reference Guide contain the correspondence between the index file number (keyno) and the associated data file.

Does not support duplicate allowed (non-unique) indexes if 4-byte record offset is not known. Use GetGTERecord(), or a similar function, with duplicate keys.

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 get lock on data record. No data file read performed.
101	INOT_ERR	No match for target key value found.

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

Example

FILNO part_idx;

TEXT part_key[25];

struct invd {

TEXT delflg[4];

LONG part_no;

LONG on_hand;

LONG on_order;

TEXT part_name[60];

} recbuf;

printf("\nEnter part name: ");

scanf("%24s",part_key);

switch (GetRecord(part_idx,part_key,&recbuf)) {

case NO_ERROR:

printf("\nParts on order for %s = %ld",

recbuf.part_name,recbuf.on_order);

break;

case DLOK_ERR:

printf("\nCould not get record lock.");

break;

case INOT_ERR:

printf("\nPart name not on file.");

break;

default:

printf("\nProgramming Error (code = %d 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.

Does not support duplicate allowed (non-unique) indexes if 4-byte record offset is not known. Use GetGTERecord(), or a similar function, with duplicate keys.