NAME

/precompiled/gdbm - database interface

DESCRIPTION

This is the an interface to the gdbm library. This module might or might not be available in your uLPC depending on weather gdbm was available when uLPC was compiled.

A gdbm database has essentially the same functionality as a mapping, except the syntax is different, and it is located on disk, not in memory. Each gdbm database is one file which contains a set of key-value pairs. Both keys and values are strings and all keys are unique.

NAME

create - open database

SYNTAX

int gdbm->create();
or
int gdbm->create(string file);
or
int gdbm->create(string file, string mode);

DESCRIPTION

Without arguments, this function does nothing. With one argument it opens the given file as a gdbm database, if this fails for some reason, an error will be generated. If a second argument is present, it specifies how to open the database using one or more of the follow flags in a string:

r
open database for reading
w
open database for writing
c
create database if it does not exist
t
overwrite existing database
f
fast mode

The fast mode prevents the database from syncronizing each change in the database immediately. This is dangerous because the database can be left in an unusable state if uLPC is terminated abnormally.

The default mode is "rwc".

NOTA BENE

The gdbm manual states that it is important that the database is closed properly. Unfortunately this will not be the case if uLPC calls exit() or returns from main(). You should therefore make sure you call close or destruct your gdbm objects when exiting your program. This will probably be done automatically in the future.

NAME

close - close database

SYNTAX

void gdbm->close();

DESCRIPTION

This closes the database.

NAME

store - store a value in the database

SYNTAX

int gdbm->store(string key, string data);

DESCRIPTION

Associate the contents of 'data' with the key 'key'. If the key 'key' already exists in the database the data for that key will be replaced. If it does not exist it will be added. An error will be generated if the database was not open for writing.

NAME

fetch - fetch a value from the databse

SYNTAX

string gdbm->fetch(string key);

DESCRIPTION

Return the data associated with the key 'key' in the database. If there was no such key in the database, zero is returned.

NAME

delete - delete a value from the database

SYNTAX

int gdbm->delete(string key);

DESCRIPTION

Remove a key from the database. Note that no error will be generated if the key does not exist.

NAME

firstkey - get first key in database

SYNTAX

string gdbm->firstkey();

DESCRIPTION

Return the first key in the database, this can be any key in the database.

NAME

nextkey - get next key in database

SYNTAX

string gdbm->nextkey(string key);

DESCRIPTION

This returns the key in database that follows the key 'key' key. This is of course used to iterate over all keys in the database.

EXAMPLE

/* Write the contents of the database */
for(key=gdbm->firstkey(); k; k=gdbm->nextkey(k))
write(k+":"+gdbm->fetch(k)+"\n");

NAME

reorganize - reorganize database

SYNTAX

int gdbm->reorganize();

DESCRIPTION

Deletions and insertions into the database can cause fragmentation which will make the database bigger. This routine reorganizes the contents to get rid of fragmentation. Note however that this function can take a LOT of time to run.

NAME

sync - synchronize database

SYNTAX

void gdbm->sync();

DESCRIPTION

When opening the database with the 'f' flag writings to the database can be cached in memory for a long time. Calling sync will write all such caches to disk and not return until