Single File Database Library

The C Interface

Compiling and Linking with ofdl

All ofdl functions and macros are defined in <db/db.h> . If you want errors to terminate your application with a SIGSEGV, then don't

  #include <db/error.h>
  ..
  main() {
  	...
  	errstream= memsopen();
  	...
  }

To link with ofdl, just adding libdb.a to your objects should be enough. ofdl doesn't depend on anything else.

Queries

Queries may be composed of three different elements: string literals that generally contain the code to execute, C values that contain the values to be passed to ofdl, and addresses of variables in which you expect values to be returned. The latter two have to be rewritten in special forms which allows ofdl functions to identify them. Since ofdl is only a library and not a preprocessor system, these conventions must be followed.

A query is a list of elements mentioned above seperated by commas. This structure makes it possible to define ofdl functions that take a query argument as variadic functions and to make the C compiler pass the values to the functions, as opposed to translating the query to another form before the C compiler gets its hands on the code. Here are the rules for writing a valid query:

• If you just want to write some code, you write it as a C string literal. Example:

   db_insert(db,"into items itemno=55;"); 

  Note that you must use C lexemes for all code you are going to execute. So, all identifiers (table and colum names), string literals, character constants and integers must be valid C lexemes of the corresponding kind. The keywords 'from' , 'into' and 'where' are only recognized when they are expected. Since the SQL part of the syntax is basicly an r.e. a column called say, 'where' is perfectly valid.

  Expressions in a query can use almost all C operators. The only ones left out are the array-reference operator [] and the ternary operator ?: . Only C forms of logical operators && || and ! are recognized. 'and' or 'or' are just identifiers.

• When you want to pass a C value to be used in an expression, you must pass it through the cv() macro. Example usage:

  db_delete(db,"from employee where empid==",cv(empid),";"); 

  There is no difference between using int and char * values. Arithmetic and comparision operators are defined for string values as well.

• If you want a value to be returned in a C variable, you just write the assignment as you would do in C, but you must take care to pass the variable's name through the ca() macro. Example usage:

  char *name;
  ..
  db_select(db, ca(name),"=name ,", 
                ca(id),"=id from employee where salary>=", 
                                            cv(5000),";"); 

  There are two ways to fetch string values into C variables. One of them, using the ca() macro as shown above, creates a fresh copy of the string and stores the address of the new string in the given variable. Although this a dynamically allocated string, you should not try to de-allocate or to resize it: ofdl manages that string.

  The other method is better suited to fetching strings that have a fixed maximum length. If the name field had a maximum size, the above code would look like:

  char name[40];
  ..
  db_select(db, cv(name),"=name ,", 
                ca(id),"=id from employee where salary>=", 
                                            cv(5000),";"); 

  This method of using the cv() macro copies the contents of the field named 'name' into the buffer pointed by the C variable 'name'. Actually the ca() macro is defined as

  #define ca(x) "*",cv(&(x)) 

  Note the use of the pointer reference operator in this definition.

• Every query must end with a string literal element which contains a semicolon (;) character as its last non-whitespace character. Above examples all demonstrate this rule.

Expressions in a query can also contain function calls. A function called from ofdl can take any number and type of arguments but each argument must be 32-bits long when promoted for function call. When used as a boolean expression, a function must return an integer value. If an arithmetic operator is to be applied to the return value, then it should return a value matching the other operands of the operator. Example usage of a function call:

int isgood(char *name,int salary) {
	if ..some_condition..
		return 1;
	else
		return 0;
}
char *strtoupper(char *txt, allocator *context) {
	char *r = context_alloc(strlen(txt)+1,context);
	..uppercase txt into r..
	return r;
}

...
db_select(db,ca(upname),"=",cv(strtoupper), "(name,",cv(context),")",
              "from employee where", cv(isgood),"( name, salary );");
...

All this probably looks like gibberish, but it's the easiest way I could think of, without resorting to a preprocessor.

Data Types

Functions

• DB db_read( char * filename );

  Reads a database from the given file and returns the handle for it. Returns NULL if it fails for some reason.

• int db_write(DB db, char *filename);

  Writes the db to the given file.

• DBCURSOR db_select(DB db, <QUERY>);

  Returns a cursor handle that can be used to iterate the given query over the db. QUERY has the form :

    <expression> from <tablename> [ where <where-expr> ] ;
  

  When iterated, a cursor returned from db_select will calculate <expression> for each record that match the where expression (or for each record in the table if it is missing). <expression> may be any valid C expression. You may use it to assign values to C variables, call functions, access values through pointers etc.

  An iteration of the select statement terminates when a record that matches the where expression is found. So, you should use it in a loop like

   while (db_iterate(cursor)) ; 

  in order to make it operate on all records.

• DBCURSOR db_update(DB db, <QUERY>);

  Returns a cursor handle that can be used to update the db using the given query. The query has the form:

   <tablename> set <expr> [ where <where-expr> ] ; 

  When iterated, a cursor returned from db_update will calculate <expr> for each record that matches the where expression.

  An iteration of the update statement updates all records in the database. See the discussion in the delete function below.

• DBCURSOR db_delete(DB db, <QUERY>);

  Returns a handle that can be used to delete records from the db using the given query. The query has the form:

   from <tablename> [ where <where-expr> ] ; 

  When iterated, a cursor returned by this function will delete all records in the table that matches the where expression. An iteration deletes all records as opposed to each iteration deleting one matching record. In general, only select needs a cursor, since it may return multiple rows that must be processed seperately. Other operations are not generally expected to return any values. However, having cursors for other operations may also be handy: you could run the same query multiple times with different C values without the need for re-compiling the query. This is both faster (doesn't matter much though) and more convenient to use. You would have one instance of the cursor for all operations that do the same thing, which is easier to maintain.

• DBCURSOR db_insert(DB db, <QUERY>);

  Returns a cursor handle that can be used to insert new records into the specified table. The query has the form:

   into <tablename> <expr> 

  When iterated, a cursor returned by this function will insert a record in to the specified table and evaluate <expr> on that record.

• int db_iterate(DBCURSOR c);

  This function will execute the action associated with the cursor. For a cursor created by db_select, the return value is 1 if a record matching the where clause was found, otherwise it is zero. For a cursor created by db_insert, the return value is nonzero unless there was a run time error. For cursors created by db_delete or db_update, the return value is the number of records that matched the where clause.

• int db_close(DBCURSOR c);

  This function will close the cursor and deallocate all memory associated with it. Return value is 1, unless the cursor is NULL in which case the return value is 0.

• int db_once(DBCURSOR c);

  This function iterates the given cursor once and then closes it. It's primarily intended for use with the db_insert, db_update and db_delete functions. In order to execute a query and not deal with the cursor stuff at all, one could write:

    db_once(db_insert(db,"into employee name=",cv(name),", 
                                       "department= ",cv(dept),";"));
  

  If the cursor is NULL, the return value is zero. Otherwise the return value is the return value of db_iterate(c).

Error Handling

There are 5 classes of errors that can occur while using ofdl:

• Parse errors: These result from queries that don't obey the syntax.
• Database errors: Reference to a table or field that does not exist generates these errors.
• Type Errors:Type mismatch between operands to an operator will generate these errors.
• Run Time Errors: Division by zero, stack overflow, dereferencing an invalid pointer and similar are in this class. These errors do not get caught at all.
• Environment Errors:Memory allocation failure and unhandled conditions during I/O are in this class. These errors simply terminate the program. However, they can be handled by the user if he wishes to use the exception mechanism, which is a bit cumbersome to be honest.

When an error is caught, the reason for it is written to the global variable FSTREAM *errstream, using the functions in io.h. Also, the called ofdl function will return a zero. This will change in the future to return a negative numeric constant identifying the error.

Compiling and Linking

void db_register_lua_functions(lua_State *l);

For a function used as a where clause, the prototype is:

function (R)

function (R) return 1 end

Lua Functions