LoadKey

Add key value to index file in presorted order.

Short Name

LOADKEY()

Type

Low-level index file function

Declaration

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

Description

LoadKey() inserts the key value pointed to by target and the associated data record position recbyt into index file number keyno. Repeated calls to LoadKey() provide an exceptionally fast method to add key values which have already been sorted. The sorted keys must be added to an empty index or all of the sorted keys must be greater than the existing entries.

Calls to LoadKey() should not be intermixed for different indices.

typadd signals the beginning, middle and end of the calls to LoadKey() as shown below:

typadd Value	Symbolic Constant	Sequence
0	FRSADD	The first call to LoadKey() for a given index must have typadd set to zero.
1	NXTADD	Subsequent calls to LoadKey() must have typadd set to one.
2	BLDADD	After all the key values have been added, one additional call is made to LoadKey() with typadd set to two. This last call causes LoadKey() to complete the b-tree structure for the index. target and recbyt should be NULL.

LoadKey() is used by the RebuildIFile() to quickly build the indices associated with a data file.

Return

Value	Symbolic Constant	Explanation
0	NO_ERROR	Successful key value insertion.
48	FMOD_ERR	LoadKey() called for a data file instead of index file.
58	KLOD_ERR	LoadKey() called for index without initial FRSADD() call, or an attempt to mix calls for different indices.
59	KLOR_ERR	Key value is out of order and has not been added to index: target is less than previous entry or not greater than existing key values. Identical duplicate keys must be presented in record position order. It is permissible to continue calling LoadKey() after a KLOR_ERR.

See c-tree Plus Error Codes for a complete listing of valid c-tree Plus error values.

Example

TEXT         target[11];

LONG         recbyt,trials;

COUNT        name_key,mode;

FILE      *fp;


trials = 0L;

mode   = FRSADD;

while (fscanf(fp,"%s %ld",target,&recbyt) == 2) {

    if (LoadKey(name_key,target,recbyt,mode))

        break;

    if (trials++)

        mode = NXTADD;


if (uerr_cod || LoadKey(name_key,NULL,0L,BLDADD))

    printf("\nerror during LoadKey (%d) on trial #%ld", uerr_cod,trials);

Limitations

LoadKey() does not pad key values. Therefore, if you pass a key value which is not completely specified to its full length, LoadKey() will effectively pad the value with whatever “garbage” follows the key value in memory.

Key values added to an index which supports 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.