FairCom ISAM for C

FirstInSet

Read the first data record in the set defined by target.

Short Name

FRSSET()

Type

ISAM function

Declaration

COUNT FirstInSet(FILNO keyno, pVOID target, pVOID recptr, COUNT siglen)

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

FirstInSet() reads the first data record in the set of data records whose keys match the target key in the first siglen bytes. If successful, this record becomes the current ISAM record for the associated data file. A successful FirstInSet() defines a current key value set, and subsequent calls to NextInSet() and PreviousInSet() will read the other records in the set (i.e., those records whose keys also match the first siglen bytes of target). If an error occurs or no key value matches the target, the current ISAM record is not updated, and no key value set is defined.

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

In a 'bound' model (either standalone or if using the server DLL in your process), the TFRMKEY() call operates on the buffer that you pass to FirstInSet(), so the target buffer must be initialized to the full length of the key to avoid memory corruption when the target is transformed to match the key.
In client/server mode the FairCom Server will perform the TFRMKEY on the Server side using a buffer sized for the key value.

FirstInSet() can be used to perform an equality search for duplicate keys. Set target to the key value and siglen to the key length less the 4 bytes of the suffix.

You do not directly identify the data file number involved. The ISAM parameter file described in ISAM Functions contains the correspondence 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 get lock on data record. No data file read performed.
101	INOT_ERR	No active entries.

See FairCom DB Error Codes for a complete listing of valid FairCom DB error values.

Example

FILNo keyfil;

TEXT target[24],recbuf[320];

printf("\nEnter set value:");

scanf("%23s",target);

FirstInSet(keyfil,target,recbuf,strlen(target));

while (isam_err == NO_ERROR) {

process_data();

NextInSet(keyfil,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.