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