*I;Berkeley DB Reference Guide: Simple Tutorial[P5

Berkeley DB Reference Guide: Simple Tutorial



3

Adding elements to a database



cThe simplest way to add elements to a database is the DB->putAinterface. This interface is accessed through a function pointerethat is an element of the database handle returned by db_open.M(All Berkeley DB handles contain function pointers you must use to operate on(the objects to which the handles refer.)

QThe DB->put interface takes five arguments:

\

db
The database handle returned by db_open.!

txnid
A transaction ID.EIn our simple case, we aren't expecting to recover the database afterFapplication or system crash, so we aren't using transactions, and will leave this argument unspecified.U

key
The key item for the key/data pair that we want to add to the database.W

data
The data item for the key/data pair that we want to add to the database.u

flags
Optional flags modifying the underlying behavior of the DB->put interface.


VHere's what the code to call DB->put looks like:(



DThe first thing to notice about this new code is that we're clearingNthe structures that we're about to pass as arguments to Berkeley DB functions.GThis is very important, and being careful to do so will result in fewersubtle errors in your programs.KAll structures specified to Berkeley DB interfaces should be cleared beforeuse, without exception.HThe reason that this is necessary is that future versions of Berkeley DB,may add additional fields to the structures.BIf applications are careful to clear the structures before use, itMwill be possible for Berkeley DB to change those structures without requiring>that the applications be rewritten to be aware of the changes.

CNotice also that we're storing the trailing nul byte found in the CBstrings "fruit" and "apple" in both the key and dataDitems, that is, the trailing nul byte is part of the stored key, andItherefore has to be specified in order to access the data item. There isHno requirement to store the trailing nul byte, it simply makes it easierGfor us to display strings that we've stored using programming languages(that use nul bytes to terminate strings.

DIn many databases, it is important not to overwrite already existing@data. For example, we might not want to store the key/data pair>fruit/apple if it already existed, e.g., if someone had@previously stored the key/data pair fruit/cherry into the database.

5This is easily accomplished using the following code:



jTo accomplish this task, we've specified a flag to the DB->put call:EDB_NOOVERWRITE, which causes the underlying database functions to notFoverwrite any previously existing key/data pair. (Note that the valueGof the previously existing data doesn't matter for this case. The onlyHissue is if a key/data pair already exists where the key matches the keythat we are trying to store.)

GSpecifying DB_NOOVERWRITE opens the possibility of a new error return, 'DB_KEYEXIST, which means we were unableHto add the key/data pair to the database because the key already existedin the database.

QAMÿÿ