FairCom ISAM for C

AddKey

Add key value to index file.

Short Name

ADDKEY()

Type

Low-Level index file function

Declaration

COUNT AddKey(FILNO keyno, pVOID target, LONG recbyt, COUNT typadd)

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 TypeDef Change

AddKey() inserts the key value pointed to by target and the associated data record position recbyt into index file number keyno. typadd determines how a full B-Tree node is split. The symbolic constants defined in ctport.h, REGADD, INCADD, and DECADD, represent the three node splitting options:

typadd Value	Symbolic Constant	Action
0	REGADD	Split nodes in half. This is the ordinary mode for random key value insertions.
1	INCADD	Uneven node split to accommodate insertions made in ascending key value order. For example, if the key values are already sorted in ascending order, using INCADD creates more compact B-Trees.
2	DECADD	Uneven node split to accommodate insertions made in descending key value order.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful key value insertion.
2	KDUP_ERR	Target key value already in index. No insertion performed.
28	ZDRN_ERR	recbyt is zero. No insertion performed.
39	FULL_ERR	No more B-Tree nodes available. It is necessary to rebuild index.

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

Example

TEXT target[11];

LONG recbyt;

COUNT name_key;

if (AddKey(name_key,target,recbyt,REGADD))

printf("\nAddKey error = %d",uerr_cod);

Limitations

AddKey() does not pad key values. If passed a key value which is not completely specified to its full length, AddKey() uses whatever “garbage” follows the key value in memory up to the key length.

Key values added to an index allowing duplicate keys, (keydup = 1 in CreateIndexFile() or CreateIndexMember()), have their last 4 bytes overwritten by the associated data record position. In this way, identical key values become distinguishable.

The recbyt parameter in this function is a 4-byte value capable of addressing at most 4 gigabytes. If your application supports HUGE files (greater than 4 gigabytes), you must use the ctSETHGH() and ctGETHGH() functions to set or get the high-order 4 bytes of the file offset. See Record Offsets Under Huge File Support.