FirstRecord

Read the first data record.

Short Name

FRSREC()

Type

ISAM function

Declaration

COUNT FirstRecord(COUNT filno, pVOID recptr)

Description

FirstRecord() retrieves the first data record found. If filno designates an index file, FirstRecord() reads the first data record based on the key sequential order of entries in index file number filno. If filno designates a data file, FirstRecord() reads the first active data record, in physical sequential order. If successful, the first record becomes the current ISAM record for the associated data file. If an error occurs or there are no entries, the current ISAM record is not updated.

If filno designates a data file that is a member of a Superfile, FirstRecord() may not reliably return the FIRST physical active data record, though it will retrieve a record.

If the data file has variable-length records, 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 FirstRecord(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

If FirstRecord() is called with an index number, the data file number involved is not directly described. The ISAM parameters described in “ISAM Functions” in the c-tree Plus Programmer’s Reference Guide contain the correspondence between the index 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 get lock on data record. No data file read performed.
101	INOT_ERR	No active entries.

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

Example

COUNT     keyfil,datfil;

TEXT      recbuf[320];


if (FirstRecord(keyfil,recbuf)

    printf("\nError %d retrieving first record.", isam_err);

else if (ReReadVRecord(datfil,recbuf,320))

    printf("\nError %d retrieving variable portion.", isam_err);

else

    printf("\nSuccessful FirstRecord.");

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. When reading in physical sequential order, FirstRecord() may not retrieve the first possible record position if records have been deleted and the space is currently unused.