eXode database manager documentation

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.

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 
  #include 

  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 : must be replaced by the type of the variable : Int, Real, Bool, Ident or String. is the corresponding C datatype.

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

4.6.1. read a value

NAME

  eXdbmGetVar()

SYNOPSIS

  int eXdbmGetVar (DBID dbid, DB_LIST list, char *entryname, * 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  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()

SYNOPSIS

  int eXdbmCreateVar(DBID dbid, DB_LIST list, char *entryname, char *comment,  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 ()

SYNOPSIS

  int eXdbmChangeVar(DBID dbid, DB_LIST list, char *entryname,  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.orig

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.