Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

EstimateRange

Find the approximate number of entries between two key values.

Short Name

ESTRNG()

Type

ISAM function

Declaration

LONG ESTRNG(FILNO keyno, NINT segcount, pVOID lrange, pVOID urange, pNINT operators, pLONG segconsec)

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

ALCRNG() is used to define a range request on a specified index. A range request consists of a set of Boolean operators defined for each segment of the key value. ESTRNG(), takes almost the same arguments as ALCRNG(), and returns an estimate of how many key values satisfy the range.

ESTRNG() has an additional argument compared to ALCRNG(), segconsec, which points to a 4-byte integer set to the "number of consecutive segments". lrange and urange must be non-NULL and point to full-length key values. segcount and operators are ignored.

ESTRNG() returns a measure of accuracy of the result in the form of a count of how many of the leading segments have consecutive key values that satisfy the range request. If all the segments have consecutive values that satisfy the range, then the result should be very accurate.

Note: A huge file may return values greater than 4 GB. This function returns the low-order 4-byte word of the 8-byte number of keys. To get the high-order 4-byte word, call ctGETHGH(). A return of zero is not necessarily an error if there are exactly a multiple 4 GB worth of key values.

Return

If EstimateRange is successful, it returns the approximate number of entries between the two key values. If an error occurs or the index is empty, EstimateRange returns a zero. When EstimateRange returns zero, check isam_err for an error condition, if any.

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

See also

AllocateRange(), FreeRange(), FirstInRange(), FirstInVRange(), LastInRange(), LastInVRange(), NextInRange(), NextInVRange(), PreviousInRange(), PreviousInVRange()

TOCIndex