_BtInsert() Function


<< Click to Display Table of Contents >>

Navigation:  Low Level Functions >


_BtInsert() Function


Previous pageReturn to chapter overviewNext page





Inserts a record into an open Btrieve File







FUNCTION _BtInsert ( hFile AS PTR, PtrData AS PTR, nRecLen AS WORD, ptrKey AS PTR, nKeyNum AS BYTE )  AS LOGIC







<hFile>File handle that was returned by _BtOpen
<ptrData>Pointer to the data structure.
<nRecLen>Length of the data structure. This value must be at least as long as the fixed-length portion of the record.
<ptrKey>Pointer to Key Buffer, that receives the new key buffer information after the insert is finished. See below
<nKeyNum>the key number that Btrieve uses to establish positioning information (currency) in the ptrKey buffer
Specify 0xFF for the key number for no currency change to occur. (NCC)








LOGIC                Was the insert operation succesful.







With this function you can insert records into a file.

The file must be open.

The record to be inserted must be the proper length, and the key values must conform to        the keys defined for the file.


If the Insert operation is successful, the MicroKernel places the new record in the file, updates the B-trees for the keys to reflect the new record, and (except for Insert operations specifying the NCC option) returns the value of the specified key in the key buffer.


An Insert operation that does not specify the NCC option establishes the complete logical and physical currencies and makes the inserted record the current one. The logical currency is based on the specified key.


An Insert operation that does specify the NCC option establishes physical currency without affecting logical currency. This means that an application, having performed an NCC Insert operation, has the same logical position in the file as it had prior to the Insert operation. In such a situation, operations that follow an NCC Insert -such as Get Next, Get Next Extended , Get Previous and Get Previous Extended - returns values based on the application's logical currency prior to the NCC Insert.


When an error occurs inserting the record , the return value is FALSE and the Bt_Error() function returns one of the following values:

02 I/O Error
03 File Not Open
05 Duplicate Key Value
14 Pre-Image Open Error
15 Pre-Image I/O Error
18 Disk Full
21 Key Buffer Too Short
22 Data Buffer Length





See Also