FairCom ISAM for C

AllocateRange

Establishes a new index range for ISAM record retrieval.

Short Name

ALCRNG()

Type

ISAM function

Declaration

COUNT AllocateRange(FILNO keyno, NINT segcount, pVOID lrange, pVOID urange, pNINT operators)

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

An index range is defined by specifying a range of values for one or more key segments.

AllocateRange() allocates buffer space and establishes a new range based on the segment values passed for the lower bound, upper bound and operators for each segment. keyno identifies the index file that should be used to establish the range. segcount indicates the number of index segment values for the range, and implicitly, the number of operators. lRange is a buffer with the lower range segment values, while uRange is a buffer with the upper range segment values. operators is an array of operators for each segment value.

The operators CTIX_EQ, CTIX_NE, CTIX_GT, CTIX_GE, CTIX_LE, CTIX_LT are open ended and use only the lRange buffer for range values. The uRange buffer is ignored and may be set to NULL for these operators.

The operators CTIX_BET, CTIX_BET_IE, CTIX_BET_EI, CTIX_BET_EE and CTIX_NOTBET use both lRange and uRange buffers to establish the lower and upper bound key values. The range is set for all index entries that are situated between the lower bound and upper bound values.

Segment values are stored in lRange and uRange buffers in the same order and type as the index segment definition.

If a previous range exists for this index, the previous range is released and the new range is established.

Return

Value	Symbolic Constant	Explanation
0	CTDBRET_OK	Successful operation.
10	SPAC_ERR	Could not allocate memory for range definition.
48	FMOD_ERR	Operation incompatible with type of file. The specifics vary by function: The specified keyno is not an index file number. The file is not a data file or it does not contain an IFIL resource (ctFILBLK in ctFBisam mode). One or more associated file (data and index files) is not TRANDEP (using RENIFIL / RENIFILX).
614	HMAP_ERR	Could not find ISAM map from specified index file to a data file. Is the specified index file opened at the ISAM level?
749	PBAD_ERR	Bad parameter value. Can be caused by any of these conditions: a) segcount is less than or equal to zero. b) lrange is NULL. c) invalid operator specified. d) between operator specified but urange is NULL.

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

Example

/*
** 3 segment example for keyno 12
*/
NINT ops[3] = {CTIX_LT,CTIX_BET,CTIX_NE};
TEXT lbuf[22];
TEXT ubuf[22];
COUNT rc;

memcpy(lbuf,"TUVWXYZ ",10);
memcpy(lbuf + 10,"00001000",8);
memcpy(lbuf + 18,"AX00",4);

memset(ubuf,0,22);
memcpy(ubuf + 10,"00001999",8);

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