F.4 AddKey

---

Add key value to index file.

SHORT NAME

ADDKEY

TYPE

Low level index file function

DECLARATION

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

DESCRIPTION

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 Appendix A "c-tree Plus Error Codes" of the c-tree Plus Programmer's Reference Guide for a complete listing of valid c-tree Plus 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 ALSO

CreateIndexFile and CreateIndexMember specify the key value characteristics of length, type, and allowance for duplicate values at index file creation.