BltIx4Insert


< Prev  TOC  Next >

TBLT_RETC TBLT_ENTRY BltIx4Insert(TBLT_KH *khPtr,
                                  VOID *keyBufferPtr,
                                  ULONG *recNoPtr,
                                  VOID *recordPtr,
                                  ULONG *actionPtr);


 khPtr          I:index file control structure
 keyBufferPtr   O:key stored
 recNoPtr       O:recNo of record data added
 recordPtr      I:record data to add
 actionPtr      O:action taken

This routine adds the data record, builds a key for it, and stores that key and recNo into the index file.

A single index file and a single data file are accessed. To perform more complex inserts see BltIx4InsertEx().

On a successful insert, the index is re-positioned to this key automatically.

If the key store operation failed, for whatever reason, the data record add operation that preceded it will be backed out automatically, thereby restoring the database to its original state.

ActionPtr is set to one of the following values:

  0 = nothing done (error encountered)
  3 = added record and stored key (normal)
 16 = key build or key store failed, but could not remove record added


If KH.tagMarks is not zero Bullet performs exclusion testing based on the following:

If the low-byte of the low word of KH.tagMarks is non-zero and matches the delete tag of the record (the first byte of the data record), then the insert fails with a WRN_RECORD_EXCLUDE return code. This is mainly used for reindexing (records whose keys are excluded do not get their keys put in the index file), but is also used by BltIx4Insert(), BltIx4InsertEx() and BltIx4Update(), BltIx4UpdateEx(), where such a match is considered an error.

If the high-byte of the low word of KH.tagMarks is non-zero and does not match the delete tag of the record, then the insert fails with a WRN_RECORD_EXCLUDE return code. In other words, for an insert to succeed, the first byte of the record must match this byte. This is also used by the routines listed above, and by the reindex routine.

The high word of KH.tagMarks is reserved and should be set to 0.

Here is the program logic used by Bullet, in its build key routine, to determine if this code should be returned (trecordPtr points to the delete tag of the data record):

  // check tag byte for marker matches
  // if (tagMarks & 255) then match means to return exclude warning
  // if (tagMarks >> 8) & 255 then NO match means to return exclude warning
  // this allows both an exclude and an include tag to be used at the same time

  if (khPtr->tagMarks != 0) {
     UCHAR tLo = khPtr->tagMarks & 255;
     UCHAR tHi = (khPtr->tagMarks >> 8) & 255;
     if (tLo != 0 && tLo == *trecordPtr) rc = WRN_RECORD_EXCLUDE;
     if (tHi != 0 && tHi != *trecordPtr) rc = WRN_RECORD_EXCLUDE;
  }

Return: Non-zero indicates an error, otherwise the data record is added and its key stored.


All content Copyright © 1999 Cornel Huth. All rights reserved.