Editor:
    Fred Pesch, pech@club-internet.fr

Copyright:
    eXode Developers Team

Status of this document
-----------------------

    This is an eXode documentation for review by eXode members and
other interested parties. It is a released document but may be updated,
replaced or obsoleted by other documents in future relases.

Abstract
--------

    This document explains the eXdbm (eXode Database Manager) file
format. This is the configuration file format of the eXode clients
(esp. the core tools). The provided API is also explained here.

Table of contents
-----------------

1. Recent Changes

2. Introduction

3. eXdbm file format
   3.1. general structure
   3.2. special chararcters
   3.3. comments
   3.4. datatypes
   3.5. variables
   3.6. lists
   3.7. keywords

4. Proposed API
   4.1. new types
   4.2. error handling
   4.3. opening & closing a database
   4.4. generic entry management
   4.5. list management
   4.6. variable management

5. Using the library
   5.1. Installation
   5.2. Linking programs with libeXdbm
   5.3. Sample programs

1. Recent changes
-----------------

Dec-27-97:
    - version 1.0beta1 to be released
    - removed keyword concept (too eXode specific)

Dec-10-97:
    - new keyword specification.
    - few changes in the API
    - no more disk media
    - new error code (-1)

Oct-04-97:
    - First draft translated and modified, renamed eXdbm

July-xx-97:
    - First draft (was eXhcl)

2. Introduction
---------------

  The X Resource manager is a normal choice for Motif based
applications configuration but it lacks of high level data structures
like lists or trees. Derived from the fof's configuration file format,
eXdbm is an ASCII-based database format. eXdbm will be used to manage
the configuration files of the eXode clients. The resource files will
also be generated by eXconfig from the eXdbm files. The proposed API
for the eXdbm management follows the description of the format.

The library uses a tree of hash tables structures stored in memory, 
favouring speed upon memory consumption. This is not a general purpose
database library, its efficiency is based on the fact that the databases
managed contain less than a few thousand entries.

Note that eXdbm is a general purpose configuration library, it can be
used in many other applications without relations to the eXode project.

3. eXdbm file format
--------------------

    3.1. general structure
    ----------------------

  The eXdbm files are standard text files. Each line of text is a
definition (the end of line char is a delimiter).

  The possible definitions are :
    - comments
    - variable
    - list header
    - list footer

  An empty line doesn't contain any definition and is simply ignored.


    3.2. special characters
    -----------------------

  The following characters are reserved :
    - #   : starts a comment
    - "   : string definition delimiter
    - =   : variable definition
    - {   : starts a list definition
    - }   : ends a list definition

Exceptions :

  - in a string definition, the only reserved char are %, " and \
  - in a comment, there is no reserved char


    3.3. comments
    -------------

  A comment begins with the reserved char # and continues until the
next end of line character (this is a sh-like behaviour). Each comment is associated to the first entry definition that follows.

Ex.:

# I am a comment

Variable = 12


    3.4. datatypes
    --------------

  The basic datatypes are :
    - Integer :  [+-][0-9]+
    - Real numbers : [+-][0-9]+.[0-9]+[[eE][+-][0-9]+]
    - Booleans : TRUE | FALSE
    - Strings :  "string contents"
    - Identifiers : my_identifier  (string without space)

    3.5. variables
    --------------

  You can declare a variable using the syntax :

    VarName =  Value

Where VarName is a string (no spaces or special chars) and Value is of
type int, real, bool or string.

note : the type of the variable is implicit

Ex.:

DefaultBackgroundColor = "Red"
RefreshInterval = 1000
AlwaysConfirm = TRUE
# according to eXdbm, pi is a variable !
PI = 3.14159265

    3.6. lists
    ----------

  A list definition starts on a new line by the name of the list
followed by a {. Each element of a list is a variable definition or a
sublist. A list is ended with a } on a new line.

note : The variable declared outside a list is called a global variable.

Ex.:

FORMAT_LIST {
 
  TAR_GZ {
    Description = "gzipped tar archive"
    Magic = "\\032\\341"
    Pattern = "*.tar.gz:*.tgz:*_tar.gz"
    ViewCommand = "%DEFAULT"
    EditCommand = "eXtar"
  }

  IMAGE {
    Description = "graphic image"  
    Magic = "%NONE"
    Pattern = "*.gif":"*.jpg":"*.tga"
    ViewCommand = "%DEFAULT"
    EditCommand = "gimp"
  }

  IMAGE_GIF {
    Description = "gif image"
    Magic = "\\0123\\0321"
    Pattern = "*.gif"
    ViewCommand = "%DEFAULT"
    EditCommand = "gimp"
  }
}

   
  4. Provided API
  ---------------

    4.1. new types
    --------------

DB_ID   -> a database identifier
DB_LIST -> a list variable

    4.2. error handling
    -------------------

  The eXdbm functions return 0 on error and 1 on success.

NAME 
  eXdbmGetLastError()
SYNOPSIS
  int eXdbmGetLastError(void);
DESCRIPTION 
  Get the last error code 
RETURN VALUE
  An eXode error code

NAME
  eXdbmGetErrorString()
SYNOPSIS
  const char * eXdbmGetErrorString(int errorcode);
DESCRIPTION
  Get an error message corresponding to the error parameter
RETURN VALUE
  A string containing the error message

NAME
  eXdbmLastLineParsed();
SYNOPSIS
  int eXdbmLastLineParsed(void);
DESCRIPTION
  This function returns the number of the last line parsed while reading the last database file. This is usefull to locate a parsing error.
EXAMPLE
  The following code prints a detailed error message 

  #include <eXdbm.h>
  #include <stdio.h>

  int ret;
  DB_ID dbid;
  int error;
  char *message;
  int last_line;
  ...
  ret = eXdbmOpenDatabse("mydb.cfg", &dbid);
  if(ret == -1) {
    printf("\nAn error has occured\n);
    /* get the error number */  
    error = eXdbmGetLastError();
    /* get the standard error message */
    message = eXdbmGetErrorString(error);
    /* get the last line parsed */
    last_line = eXdbmLastLineParsed();

    /* print a detailed error message */
    printf("Error number %d : %s\n", error, message);
    printf("Last line parsed = %d\n", last_line);
  }
  ...
 
  Example of output :

  An error has occured
  eXdbmOpenDatabase : Cannot parse variable value
  Last line parsed = 25

RETURN VALUE
  -1 on error
  >0 on success

    4.3. opening & closing a databases
    ----------------------------------

NAME
  eXdbmInit()
SYNOPSIS
  int eXdbmInit(void);
DESCRIPTION
  Initialize the database manager. This function must be call before any other eXdbm function call.
RETURN VALUE
  -1 on error
  >0 on success

NAME
  eXdbmOpenDatabase()
SYNOPSIS
  int eXdbmOpenDatabase(char *filename, DBID *dbid);
DESCRIPTION
  Open the filename database file.
  dbid is a pointer to an integer : an unique identifier for the opened database

RETURN VALUE
  -1 on error
  >0 on success

NAME
  eXdbmNewDatabase()
SYNOPSIS
  int eXdbmOpenDatabase(char *filename, DB_ID *dbid);
DESCRIPTION
  Create a new database which will use the file filename.
  dbid is a pointer to an integer : an unique identifier for the opened database
RETURN VALUE
  -1 on error
  >0 on success

NAME
  eXdbmUpdateDatabase()
SYNOPSIS
  int eXdbmUpdateDatabase(DB_ID dbid);
DESCRIPTION
  Save the database identified by dbid. This assure the actual database contents is the same in memory and on disk.
RETURN VALUE
  -1 on error
  >0 on success

NAME 
  eXdbmBackupDatabase()
SYNOPSIS
  int eXdbmBackupDatabase(DB_ID dbid, char *filename);
DESCRIPTION
  Make a backup copy of the database identified by dbid in the file filename. This file must be writeable by the current user.
RETURN VALUE
  -1 on error
  >0 on success

NAME
  eXdbmCloseDatabase()
SYNOPSIS
  int eXdbmCloseDatabase(DBID dbid, int update)
DESCRIPTION
  The function you have to call to close a database. If udate = 1 (defined as TRUE in eXdbm.h), the database file will be updated, see eXdbmUpdateDatabase().
RETURN VALUE
  -1 on error
  >0 on success

    4.4. Generic entry management
    -----------------------------

      4.4.1. get the type of an entry
      -------------------------------

NAME
  eXdbmGetEntryType()
SYNOPSIS
  int eXdbmGetEntryType(DB_ID dbid, DB_LIST list, char *entryname);
DESCRIPTION
  This function returns the type of the entry identified by :
  dbid : the database identifier
  list : the parent's list of the entry (NULL for level 0 entry)
  entryname : the name of the entry
RETURN VALUE
  -1 (DBM_ENTRY_NOT_FOUND) on error
  On succes, the type of the entry :
    - DBM_ENTRY_LIST : a list entry
    - DBM_ENTRY_VAR_INT : an integer variable
    - DBM_ENTRY_VAR_BOOL : a boolean variable
    - DBM_ENTRY_VAR_REAL : a real number variable
    - DBM_ENTRY_VAR_STRING : a string variable
    - DBM_ENTRY_VAR_ID : an identifier variable 

      4.4.2. Comments management
      --------------------------

NAME
  eXdbmGetEntryComment()
SYNOPSIS
  char * eXdbmGetEntryComment(DB_ID dbid, DB_LIST list, char *entryname);
DESCRIPTION
  Returns the associated comment of an entry if it exists, or NULL. The entry is specified by :
  dbid : the database identifier
  list : the parent's list of the entry (NULL for level 0 entry)
  entryname : the name of the entry
RETURN VALUE
  A pointer to the comment string
  or NULL

NAME
  eXdbmChangeEntryComment()
SYNOPSIS
  int eXdbmChangeEntryComment(DB_ID dbid, DB_LIST list, char *entryname, char *comment);
DESCRIPTION
  Changes the associated comment of an entry. The entry is specified by :
  dbid : the database identifier
  list : the parent's list of the entry (NULL for level 0 entry)
  entryname : the name of the entry
  comment is the new comment string
NOTE
  The function allocates the memory needed for the comment and copy the string you provide.
  You must ensure the specifier string starts with a # character. If this is not the case, eXdbm won't be able to parse the database file containing a comment that is not starting with #.

RETURN VALUE
  -1 on error
  >0 on success

      4.4.3 delete an entry
      ---------------------

NAME 
  eXdbmDeleteEntry()
SYNOPSIS
  int eXdbmDeleteEntry(DB_ID dbid, DB_LIST list, char *entryname);
DESCRIPTION
  This function deletes the entry specified by
  dbid : the database identifier
  list : the parent's list of the entry (NULL for level 0 entry)
  entryname : the name of the entry
  if the entry is a list, all the entries is contains are also destroyed, recursively.
RETURN VALUE
  -1 on error
  >0 on sucess

    4.5. list management
    -------------------- 

      4.5.1. get a list identifier
      ----------------------------

NAME
  eXdbmGetList()
SYNOPSIS
  DB_LIST eXdbmGetList(DB_ID dbid, DB_LIST list, char *listname);
DESCRIPTION
  get the identifier of the sublist of name listname in list.
  if list is NULL, sublistname is the name of a first level list
RETURN VALUE
  A pointer to the found DB_LIST structure.
  If the value is NULL, the Sublist doesn't exist (an error is raised,
  the eXdbmGetError returns an error).

NAME
  eXdbmSearchList()
SYNOPSIS
  DB_LIST eXdbmSearchList(DB_ID dbid, DB_LIST list, char *listname);
DESCRIPTION
  search recursively the list of name listname in list and all of its sublists.
  If list is NULL, search in all the lists of the database.
NOTE
  The behaviour of this function is hard to predict if more than one list is of name listname. 
RETURN VALUE
  A pointer to the found LIST structure.
  If the value is NULL, the Sublist doesn't exist (an error is raised,
  the eXdbmGetError returns an error).

NAME
  eXdbmPathList()
SYNOPSIS
  DB_LIST eXdbmPathList(DB_ID dbid, char *path);
DESCRIPTION
  This function returns the list referenced by its full path name in the database. A pathname is a serie of list names separated by colons.
EXAMPLE

list:sublist:susublist

refers to the list of name subsublist defined in sublist which is defined in list.
NOTE 
  The root list (referenced as NULL) is implicit
RETURN VALUE
  A pointer to the found LIST structure.
  If the value is NULL, the list doesn't exist (an error is raised,
  the eXdbmGetError returns an error).

      4.5.2. create an empty list
      ---------------------------

NAME
  eXdbmCreateList()
SYNOPSIS
  int eXdbmCreateList(DBID dbid, LIST *list, char *entryname, char *comment);
DESCRIPTION
  Create an empty list of name entryname
  list is the parent list (NULL is the new list is global)
  comment is a string to comment the new list
RETURN VALUE
  -1 on error
  >0 on success

    4.6. Variable management
    ------------------------

  In the following functions : <TYPE> must be replaced by the type of
the variable : Int, Real, Bool, Ident or String. <CTYPE> is the corresponding
C datatype.

<TYPE>       <CTYPE>
Int          int
Real         double
Bool         int  (0 = FALSE, 1 = TRUE)
Ident        char *
String       char *

      4.6.1. read a value
      -------------------

NAME
  eXdbmGetVar<TYPE>()
SYNOPSIS
  int eXdbmGetVar<TYPE> (DBID dbid, DB_LIST list, char *entryname, <CTYPE>* value);
DESCRIPTION
  Read the value of a variable. 
  dbid is the database ID
  list is the parent's list 
  entry is the name of the variable. V
  Value is a pointer to a variable of the desired C type.
EXAMPLE
  
  ...
  int ival;
  double rval;
  char *sval;
  int bval;
  char *idval;

  int ret;
  ...
  ret = eXdbmGetVarInt(dbid, parent, "intvar", &ival);
  ret = eXdbmGetVarBool(dbid, parent, "boolvar", &bval);
  ret = eXdbmGetVarReal(dbid, parent, "realvar", &rval);
  ret = eXdbmGetVarString(dbid, parent, "stringvar", &sval);
  ret = eXdbmGetVarIdent(dbid, parent, "identvar", &idval);
  ...

NOTE
  If <TYPE> is String or Ident, the value pointer references a copy of the value coded by the variable. You must free() this memory when you don't need it anymore.

RETURN VALUE
  -1 on error
  >0 on success

      4.6.2. create a variable
      ------------------------

NAME
  eXdbmCreateVar<TYPE>()
SYNOPSIS
  int eXdbmCreateVar<TYPE>(DBID dbid, DB_LIST list, char *entryname, char *comment, <CTYPE> value);
DESCRIPTION
  Add a variable to the database. 
  dbid is the database ID
  list is the parent list of the entry (NULL is root for parent)
  entryname is the name of the new variable
  comment is the comment string associated to the variable (or NULL) 
  value is the value of the variable.
NOTE
    The function allocates the memory needed for the comment and copy the string you provide.
RETURN VALUE
  -1 on error
  >0 on success

 
      4.6.3. Modify a variable
      ------------------------

NAME
  eXdbmChangeVar<TYPE> ()
SYNOPSIS
  int eXdbmChangeVar<TYPE>(DBID dbid, DB_LIST list, char *entryname, <CTYPE> newvalue);
DESCRIPTION
  Change the value of a variable in the database. 
  dbid is the database ID
  list is the parent list of the entry (NULL is root for parent)
  entryname is the name of the variable to be modified
  newvalue is the new value of the variable.
NOTE
  Use eXdbmChangeEntryComment() to change the comment associated to a variable.
RETURN VALUE
  -1 on error
  >0 on success


5. Using the library
--------------------

  5.1. Installation instructions
  ------------------------------

First, get the file :

eXdbm-status-version.tar.gz 

where status is : alpha, beta or empty (final)
      version is the version number (1.0b1 is the last version)

Then uncompress the file :

gzip -d eXdbm-status-version.tar.gz
tar xvf eXdbm-status-version.tar

Now, cd to eXdbm-status-version/

Then type :

make

and, as root :

make install

The default installation directories are :

/usr/local/include  : header files
/usr/local/lib : library
/usr/local/doc/eXdbm  : documentation

You can change these defaults by modifying the LIBDIR, INCDIR and DOCDIR make variable in Makefile.ref

  5.2. Linking programs with libeXdbm.a
  -------------------------------------

This is the command line you have to use in order to link your C programs with the eXdbm library :

cc myprogram.c  -I/usr/local/include -L/usr/local/lib -leXdbm -lm

NOTE :
  Don't forget the -lm statement, eXdbm uses a few math functions.

  5.3. Sample programs
  --------------------

The following programs demonstrates the use of the eXdbm library :

- test1  (test1.c)

Basic open/update/close functions

- test2  (test2.c)

Backup function test

- test3  (test3.c)

A console oriented small database manager that uses every functions provided in the eXdbm library.