At present this is a short introduction into BDB. You may
get additional information from the tests provided with the distribution. A more
detailed introduction is part of the TODOS.


Creating a Database
===================

Berkeley DB provides certain kinds of databases. Please consult the Berkeley
DB reference manual for information about these types. Also, please consult the
API documentation of BDBDatabaseConfig regarding the configuration of these
types.

The creation of a B-Tree database may look as follows:
  BDBDatabaseConfig *config;
  BDBDatabase *database;
  
  config = [ [ BDBDatabaseConfig alloc ] init ];
  [ config setAllowCreate: YES ];
  [ config setAllocSortedDuplicates: YES ];
  [ config setDatabaseType: BDB_BTREE ];
  
  database = [ BDBDatabase 
    initWithFilename: @"mydb.db" 
    databaseName: @"dbname"
    databaseConfig: config ];


Modifying Content of a Database
===============================

The following example adds 3 entries to the database. Each operation
is somehow comparable to:
  put(key, value)
where key = "Key-<exampleNr>" and value="Value for <exampleNr>"

After adding these entries an iteration tries to fetch the previously 
written entries.

The code looks as follows:
  NSMutableArray *keys, *values;
  
  keys = [[[ NSMutableArray alloc ] init ] autorelease ];
  values = [[[ NSMutableArray alloc ] init ] autorelease ];
  
  for( i=0; i< 3; i++ ) {
    NSString *key, *value; 
	BDBDatabaseEntry *keyEntry, *dataEntry;

	key = [ [ NSString alloc ] initWithFormat: @"Key-%u", i ] ;
	value = [ [ NSString alloc ] initWithFormat: @"Value for %u", i ];
	
	keyEntry = [[[BDBDatabaseEntry alloc] initWithObject: key] autorelease];
	dataEntry = [[[BDBDatabaseEntry alloc] initWithObject: value ] autorelease ];
	
    // add f(keyEntry) <-- dataEntry to the database
    [ database putEntryWithTransaction: nil key: keyEntry value: dataEntry ];
    
    // save values for later comparison
	[ keys addObject: key ];
	[ values addObject: value ];
  }


  for( i = 0; i < 3; i++ ) {
    BDBDatabaseEntry *valueEntry 
	  = [[[BDBDatabaseEntry alloc]init] autorelease ];
    BDBDatabaseEntry *keyEntry;

    BDBOperationStatus operationStatus;
	
	NSLog( @"Reading key=%@", [ keys objectAtIndex: i ] );	
	
	keyEntry  = [[[BDBDatabaseEntry alloc]initWithObject: 
	  [keys objectAtIndex: i ] ] autorelease];
	  
	operationStatus = [ database getEntryWithTransaction: nil
	  key: keyEntry data: valueEntry ];
	
	ECAssertTrue( BDB_STATUS_SUCCESS == operationStatus,
	  @"Value for a key missing!" );
  }


Closing a Database
==================

Closing a database:
  [ database close ];
