Product Documentation

FairCom ISAM for C

Previous Topic

Next Topic

Allocating an Index Range

To allocate an index range using the c-tree ISAM API, call the AllocateRange() c-tree API function. The function prototype is as follows:

ctCONV COUNT ctDECL AllocateRange(COUNT keyno, NINT segcount, pVOID lrange,

pVOID urange, pNINT operators);


  • keyno: Specifies the index file number;
  • segcount: Specifies the number of segments with range specifications;
  • lrange: Points to a buffer containing the limits for the segments;
  • urange: Points to an optional buffer containing upper limits for the segments with between ranges (e.g., CTIX_BET); and
  • operators: Points to an integer array of segment range types.

AllocateRange() returns NO_ERROR (0) on success.

Index ranges are ISAM context safe. That is, each ISAM context initiated via an OpenISAMContext() call can support its own index range.

The lrange and urange buffers must each be long enough to hold the first segcount segments for the index. For example, if segcount is 3, and if the first three segments are 10, 8, and 4 bytes long, then the range buffer(s) must be 22 bytes long.

If between ranges are not used, the urange buffer is ignored and may be passed as NULL. If between ranges are defined, then there must be a urange buffer, and it must be long enough to hold all segcount segments (in our example 22 bytes) even if only one between range segment is defined. For instance, if the first segment, 10 bytes long, does not use a between range, but the second segment does, then urange must hold the upper limit for the second segment starting at 10 bytes from the beginning of urange. Continuing this example, here is some pseudo code that assumes all the segments involved hold ASCII strings:


** 3 segment example for keyno 12



TEXT lbuf[22];

TEXT ubuf[22];


memcpy(lbuf,"TUVWXYZ ",10);

memcpy(lbuf + 10,"00001000",8);

memcpy(lbuf + 18,"AX00",4);


memcpy(ubuf + 10,"00001999",8);

rc = AllocateRange(12,3,lbuf,ubuf,ops);

The index must be part of an ISAM set of files and segcount must be greater than zero and cannot exceed the number of key segments actually defined for the index.