SYNOPSIS

#include <agar/core.h>

DESCRIPTION

AG_Db provides a simple interface for accessing databases of key/value pairs. Various database backends are implemented, such as "hash", "btree" and "mysql". Different backends may support different key types (e.g., raw data, C strings or record numbers).

Many of the functions described below accept Berkeley DB style AG_Dbt arguments. This structure is defined as:

typedef struct ag_dbt {
	void   *data;		/* Pointer to key or data */
	AG_Size size;		/* Key/data size (bytes) */
} AG_Dbt;

INHERITANCE HIERARCHY

AG_Object(3)-> AG_Db.

INTERFACE

AG_Db * AG_DbNew (const char *backend)

int AG_DbOpen (AG_Db *db, const char *path, Uint flags)

void AG_DbClose (AG_Db *db)

int AG_DbExists (AG_Db *db, const AG_Dbt *key)

int AG_DbDel (AG_Db *db, const AG_Dbt *key)

int AG_DbGet (AG_Db *db, const AG_Dbt *key, AG_Dbt *val)

int AG_DbPut (AG_Db *db, const AG_Dbt *key, const AG_Dbt *val)

int AG_DbSync (AG_Db *db)

The AG_DbNew() function creates a new AG_Db object instance. The backend argument specifies the database backend to use. Available backends include:

hash	Extended Linear Hashing (Berkeley DB)
btree	Sorted, Balanced Tree Structure (Berkeley DB)
mysql	MySQL database storage

The AG_DbOpen() function opens the database for further access. The path argument is backend-specific. With "hash" and "btree, it may be a file name. With "mysql", it may be set to a database name (or set to NULL to use the default database settings).

The AG_DbClose() function closes the database.

The AG_DbExists() function returns 1 if the given key matches an entry in the database, or 0 if no match was found.

The AG_DbDel() function deletes the named entry associated with key.

The AG_DbGet() function retrieves the database entry referenced by the specified key. The data is returned as newly-allocated memory in val, and must be freed after use. It is not necessary to initialize the supplied val argument.

The AG_DbPut() function writes the specified database entry.

AG_DbSync() synchronizes the actual contents of db with any associated database files.

EXAMPLES

The following code creates a new database or accesses the existing database my.db, checks whether a record exists under "mykey" and if not, create one containing the string "myval".

AG_Db *db;
AG_Dbt dbtKey, dbtVal;
char key[8];

if ((db = AG_DbNew("btree")) == NULL)
	AG_FatalError(NULL);

if (AG_DbOpen(db, "my.db", 0) != 0)
	AG_FatalError(NULL);

dbtKey.data = "mykey";
dbtKey.size = 5;
if (!AG_DbExists(db, &dbtKey)) {
	dbtVal.data = "myval";
	dbtVal.size = 5;
	if (AG_DbPut(db, &dbtKey, &dbtVal)) != 0)
		AG_Verbose("Put failed (%s)\n", AG_GetError());
}

AG_DbClose(db);
AG_ObjectDestroy(db);

HISTORY

The AG_Db interface first appeared in Agar 1.5.0.