FairCom ISAM for C

PreviousRecord

Read the preceding data record.

Short Name

PRVREC()

Type

ISAM function

Declaration

COUNT PreviousRecord(FILNO filno, 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

PreviousRecord() retrieves the previous data record found. If filno designates an index file, PreviousRecord() reads the previous active data record based on the key sequential order of entries in index file number filno. If filno designates a data file, PreviousRecord() reads the previous active data record, in physical sequential order. If successful, the previous 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.

Note: filno cannot be a data file number, and the error FMOD_ERR (48) will be returned, if any of the following are true:

The data file is set up for variable-length records;
The data file is a member of a Superfile;
The data file has Resources enabled (the default state).

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 PreviousRecord(). Note that ReReadVRecord() requires the size of the buffer area so that it can check if sufficient space is available.

If PreviousRecord() is called with an index number, the data file number involved is not directly described. The ISAM parameters described in ISAM Functions (ISAM Database Technology, /doc/ctreeplus/30841.htm) of the c-tree Programmer’s Reference Guide contain the correspondence between the index number and the associated data file.

PreviousRecord() can move sequentially through a data file based on one index then switch to another index. For example, moving through an inventory file in part number order before switching to part name order by changing the keyno parameter in the PreviousRecord() call.

As of c-tree V8.14, c-tree sets the current ISAM position after a record is added such that the next or previous record can be read without having to re-read the record just added. Prior to V8.14, the current ISAM position was not set to a newly-added record and an INOT_ERR (101) error would result if you tried to read either the next or previous record.

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.
48	FMOD_ERR	PreviousRecord() called with a data file number of a variable-length data file or superfile member, or RESOURCES are enabled.
100	ICUR_ERR	No current ISAM record.
101	INOT_ERR	No active entries.

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

Example

FILNO acct_idx, test;

TEXT recbuf[320];

test = LastRecord(acct_idx,recbuf);

while (test == NO_ERROR) {

post_interest(recbuf);

test = PreviousRecord(acct_idx,recbuf);

}

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.