RC/21

Fundamental C Database Objects and Types

DB        A database object
DBTAB     A table object
DBCOL     A column object
DBERROR   An error code
DBREAL    A double object
DBINTEGER A long integer
DBSTRING  A char* object
DBBLOB    A void* object
DBUSER    A user-defined object
COLATTRIBS  A column attribute long
DBROWID   A table-row identifier
DBSIZE    A size object

Column Attributes (COLATTRIBS) Constants and (Mask)

Integer, Real, String, Blob, Eblob, User, USTRING, Null (TypeMask)
Indexed, NonIndexed (IndexMask)
KeyLen (GetKeyLen)
NoNulls, Nulls (NullsMask)
Unique, NonUnique (UniqueMask)
NonShared, Shared (ShareMask)
NOATTRIBS - default all

Database Functions

DBERROR DB_Create (char *path, unsigned pagesize,
unsigned nhash);
DB DB_Open (char *Path, char *Access, int MaxPages);
int DB_AutoCommit (DB db, int AutoCommit);
int DB_Changed (DB db);
int DB_CachePages (DB db);
DBERROR DB_Close (DB db);
char *DB_GetPath (DB db);
char *DB_GetVersion (DB db);
unsigned DB_GetPageSize (DB db);
unsigned long DB_GetHashSize (DB db);
DBERROR DB_CopyDB (DB from, DB to);
DBERROR DB_SetDB (DB db);
DBERROR DB_Remove (char *path);

Table Functions

DBERROR DB_AddTable (DB db, char *name,
char *description, char *view);
DBTAB DB_Table (DB db, char *view);
char *DB_GetTableName (DBTAB table);
DBROWID DB_GetTableID (DBTAB table);
char *DB_GetTableDescription (DBTAB table);
char *DB_GetTableView (DBTAB table);
DBERROR DB_EmptyTable (DBTAB table);
unsigned long DB_CountColumns (DBTAB table);
unsigned long DB_CountRows (DBTAB table);
DBERROR DB_ChangeTableName (DBTAB table, char *newname);
DBERROR DB_ChangeTableDescription (DBTAB table,
char *description);
DBERROR DB_ChangeTableView (DBTAB table, char *view);
int DB_TableExists (DB database, char *tabname);
DBERROR DB_CopyTable (DBTAB source, char *dest);
DBERROR DB_ClearFilters (DBTAB table);
DBERROR DB_DeleteTable (DBTAB table);
DBERROR DB_Filter (DBTAB table, char *filter, ...);
DBERROR DB_vFilter (DBTAB table, char *filter, va_list _ap);
DBERROR DB_SetFilterArg (char t, void *arg);
DBERROR DB_SetFilterBlob (void *blob, size_t bloblen);

Column Functions

DBERROR DB_AddColumn (DBTAB table, char *name,
char *description, char *format, DBCOL reference,
COLATTRIBS attribs);
DBERROR DB_AddKey (DBTAB table, char *name,
char *keynames, COLATTRIBS attribs);
DBCOL DB_Column (DBTAB table, char *name);
DBERROR DB_DeleteColumn (DBCOL column);
char *DB_GetColumnName (DBCOL column);
DBROWID DB_GetColumnID (DBCOL col);
char *DB_GetColumnDescription (DBCOL column);
char *DB_GetColumnFormat (DBCOL column);
DBCOL DB_GetColumnReference (DBCOL column);
COLATTRIBS DB_GetColumnAttributes (DBCOL column);
DBERROR DB_ChangeColumnName (DBCOL column, char *name);
DBERROR DB_ChangeColumnDescription (DBCOL column,
char *description);
DBERROR DB_ChangeColumnFormat (DBCOL column,
char *format);
DBERROR DB_ChangeColumnAttributes (DBCOL column,
COLATTRIBS attribs);
int DB_ColumnExists (DBTAB tab, char *colname);
DBERROR DB_CopyColumn (DBCOL from, char *newname);
DBTAB DB_ColTab (DBCOL col);
int DB_HasAnyValues (DBCOL column);
COLATTRIBS DB_EncodeAttributes (char *string);
char *DB_DecodeAttributes (COLATTRIBS attribs);

Object Functions

DBERROR DB_Free (void *object);

Row Functions

DBERROR DB_AddRow (DBTAB table);
DBERROR DB_DeleteRow (DBTAB table);
DBROWID DB_CurrentRow (DBTAB table);
DBERROR DB_OrderBy (DBCOL column);
DBERROR DB_Unordered (DBTAB table);
DBERROR DB_FirstRow (DBTAB table);
int DB_NextRow (DBTAB table, int direction);
DBERROR DB_GotoRow (DBTAB table, DBROWID rowid);
int DB_Find (DBTAB table, char *filter, ...);
int DB_vFind (DBTAB table, char *filter, va_list _ap);
int DB_RowExists (DBTAB table, char *filter, ...);
int DB_vRowExists (DBTAB table, char *filter, va_list _ap);
int DB_IsaRow (DBTAB table);
int DB_PassesFilter (DBTAB table, char *filter, ...);
int DB_vPassesFilter (DBTAB table, char *filter, va_list ap);
DBERROR DB_CopyRow (DBTAB from, DBTAB to);

Field Functions

DBERROR DB_PutInteger (DBCOL column, DBINTEGER i);
DBERROR DB_PutReal (DBCOL column, DBREAL x);
DBERROR DB_PutFloat (DBCOL column, DBREAL x);
DBERROR DB_PutString (DBCOL column, DBSTRING string);
DBERROR DB_PutBlob (DBCOL column, DBBLOB value, size_t size);
DBERROR DB_PutNull (DBCOL column);
DBERROR DB_PutUser (DBCOLcolumn, DBUSER value, size_t size);
DBINTEGER DB_GetInteger (DBCOL column);
DBREAL DB_GetReal (DBCOL column);
DBSTRING DB_GetString (DBCOL column);
DBBLOB DB_GetBlob (DBCOL column, volatile size_t *size);
DBUSER DB_GetUser (DBCOL column, volatile size_t *size);
COLATTRIBS DB_GetType (DBCOL column);
size_t DB_GetSize (DBCOL column);
DBERROR DB_CopyValue (DBCOL from, DBCOL to);

Error Functions

DBERROR DB_GetError (void);
DBERROR DB_ClearError (void);
char *DB_ErrorString (DBERROR);
char *DB_ErrorMnemonic (DBERROR);
void DB_PrintError (char *prefix);
#define DB_ErrorPrint DB_PrintError

Wildcard Functions

int DB_MatchWild (char *pattern, char *string);
int DB_IsWild (char *string);

Miscellaneous Functions

char *DB_BlobToString (DBBLOB blob, size_t length,
char *buf, size_t limit);
void DB_PrintBlob (DBBLOB blob, size_t length);
DBERROR DB_GetIOCounts (volatile long *NumReads,
volatile long *NumWrites);
void (*DB_SetErrorFunc(void (*arg)(void)))(void);
void DB_SetUserExit (void (*UserExit) (char *msg));
void DB_FinishTask (void);

Functions for looking at ALL Tables, Colums, Rows

DBERROR DB_FirstTable (DB db);
int DB_NextTable (DB db);
DBTAB DB_CurrentTable (DB db);
DBERROR DB_FirstColumn (DBTAB tab);
int DB_NextColumn (DBTAB tab);
DBCOL DB_CurrentColumn (DBTAB tab);
DB_ForAllTables (DB db) { .. }
DB_ForAllColumns (DBTAB tab) { .. }
DB_ForAllRows (DBTAB tab) { .. }

Commit/RollBack

DBERROR DB_Finish (DB db);
DBERROR DB_FinishRow (DBTAB table);
DBERROR DB_Commit (DB db);
DBERROR DB_RollBack (DB db);
DBERROR DB_CommitStatus (DB db, unsigned long *dbsize,
unsigned long *tempsize);

Client Functions

int DB_Connect (char *servername);
void DB_Disconnect (void);
typedef enum {LockWait, LockNoWait} LockMode;
typedef enum {LockOK, LockTryAgain} LockReturn;
LockReturn DB_LockRow (DBTAB t, LockMode m);
LockReturn DB_LockTable (DBTAB t, LockMode m);
LockReturn DB_LockDB (DB db, LockMode m);
LockReturn DB_LockSchema (DB db, LockMode m);

Simple Classes, Typedefs

DBVALUE     A container class for numbers, string, and blobs
CDBSTRING   const char*
DB          class Database*
DBTAB       class Table*
DBCOL       class Column*

Nonmember Functions

char* ErrorString ();
char* ErrorMnemonic ();
DBERROR GetError ();
void PrintError (char* prefix);
DBERROR Create (char* path, unsigned pagesize=512, unsigned nhash=512);

class Database

Database ();
Database (char* dbname, char* access="rw",int npages=20);
Database (char* dbname, int npages);
int Changed(void);
int CachePages(void);
CDBSTRING Path(void);
CDBSTRING Name(void);
CDBSTRING Version(void);
unsigned PageSize(void);
unsigned long HashSize(void);
FILEADDR PageMask(void);
DBERROR AddTable(CDBSTRING name, CDBSTRING
description="no description", CDBSTRING view = "");
DBERROR DeleteTable(CDBSTRING name);
void Finish(void);
DBERROR Commit(void);
int AutoCommit(int onoff);
int AutoCommit(void);
DBERROR RollBack(void);
DBTAB CurrentTable(void);
void FirstTable(void);
int NextTable(void);
DBERROR Copy(DB to);
DBERROR CommitStatus(unsigned long &dbsize, unsigned long &tempsize);
Database& operator=(Database& fromdb);
class Table& operator[](CDBSTRING tablename);

class Table

Table (DB db, CDBSTRING tablename);
Table (CDBSTRING tablename);
Table (void);
Table& operator=(Table& table);
Table(Column&c);
int IsInternal(void);
operator DBTAB(void);
operator DB(void);
DBERROR Erase(void);
CDBSTRING Name(void);
DBERROR Name(CDBSTRING newname);
CDBSTRING Description(void);
DBERROR Description(CDBSTRING description);
CDBSTRING View(void);
DBERROR View(CDBSTRING newview);
DBERROR AddColumn(CDBSTRING name, COLATTRIBS
attr=NOATTRIBS, CDBSTRING description=(CDBSTRING)"no
description",CDBSTRING format=(CDBSTRING)"", const DBCOL
reference=NULL);
int ColumnExists(CDBSTRING colname);
DBERROR AddKey(CDBSTRING name, CDBSTRING keys, COLATTRIBS
attr=NOATTRIBS);
DBERROR DeleteColumn(CDBSTRING name);
FIELDID ID(void);
DBROWID CountColumns(void);
DBROWID CountRows(void);
DBERROR Copy(CDBSTRING newtab);
DBERROR CopyRow(DBROWID);
DBERROR CopyRow(DBTAB);
DBERROR DuplicateRow(void);
void Empty(void);
DBERROR Zap(void);
DBERROR OrderBy(CDBSTRING colname);
DBERROR Unordered(void);
void ClearFilters(void);
DBERROR vFilter(CDBSTRING filter, va_list ap);
DBERROR Filter(CDBSTRING filter ...);
int Find(CDBSTRING filter ...);
int vFind(CDBSTRING filter, va_list ap);
int RowExists(CDBSTRING filter ...);
int vRowExists(CDBSTRING filter, va_list ap);
int PassesFilter(CDBSTRING filter ...);
int vPassesFilter(CDBSTRING filter, va_list ap);
int IsaRow(void);
DBERROR FirstRow(void);
DBROWID CurrentRow(void);
int NextRow(int inc=1);
int PrevRow(void);
DBERROR GotoRow(DBROWID r);
DBERROR AddRow(void);
DBERROR DeleteRow(void);
CDBSTRING GetRow(CDBSTRING column_list, char sep);
void FirstColumn(void);
int NextColumn(void);
DBCOL CurrentColumn(void);
DBERROR FinishRow(void);
row operator=(row r);
void operator++(void);
Column& operator[](CDBSTRING colname);

class ColumnAttributes

ColumnAttributes(Column&);
ColumnAttributes(CDBSTRING);
ColumnAttributes(COLATTRIBS);
operator CDBSTRING(void);

class Column

Column(DBTAB table, FIELDID f);
Column(DBTAB table, CDBSTRING cname);
Column(void);
Column(DBCOL q);
Column& operator=(DBCOL X);
operator DBCOL(void);
operator DBTAB(void);
operator DB(void);
void Zap(void);
int HasAnyValues(void);
DBBOOL KeyExists(DBSEARCH dbsearch);
CDBSTRING Name(void);
CDBSTRING Description(void);
CDBSTRING Format(void);
COLATTRIBS Attributes(void);
DBCOL Reference(void);
DBTAB Tab(void);
FIELDID ID(void);
DBERROR Name(CDBSTRING name);
DBERROR Description(CDBSTRING newdescription);
DBERROR Format(CDBSTRING fmt);
DBERROR Copy(CDBSTRING newcol);
DBERROR Copy(DBCOL);
DBERROR PutNull(void);
DBERROR PutReal(DBREAL x);
DBERROR PutInteger(DBINTEGER i);
DBERROR PutString(CDBSTRING s);
DBERROR PutSTRING(CDBSTRING s);
DBERROR PutBLOB(CDBBLOB b,DBSIZE s);
DBERROR PutUser(const DBUSER b,DBSIZE s);
DBERROR PutUser(USER *u);
DBERROR PutEBLOB(FILEADDR f)
DBERROR PutNULL(void);
DBERROR Put(DBINTEGER i);
DBERROR Put(DBREAL x);
DBERROR Put(CDBSTRING s);
DBERROR Put(CDBBLOB b,DBSIZE s);
DBERROR Put(const DBUSER b,DBSIZE s);
DBERROR Put(const DBVALUE&);
DBINTEGER operator <<(DBINTEGER x);
int operator <<(int);
DBREAL operator <<(DBREAL);
CDBSTRING operator <<(CDBSTRING);
DBERROR AddRow(void);
DBERROR Attributes(COLATTRIBS);
void Erase(void);
DBINTEGER GetInteger(void);
DBREAL GetReal(void);
CDBSTRING GetString(void);
cpBLOB GetBLOB(void);
cpUSER GetUser(void);
COLATTRIBS GetType(void);
DBSIZE GetSize(void);
DBSIZE Size(void);
DBVALUE Get(void);
DBERROR OrderBy(void);
operator int(void);
operator long(void);
operator const char*(void);
operator double(void;
operator float(void);
long operator=(long);
CDBSTRING operator=(CDBSTRING);
double operator=(double);
blob& operator=(blob&);
void operator=(DBVALUE);
int Find(DBSEARCH);
DBBOOL FindNext(DBSEARCH dbsearch, int direction);
class Eblob
FILEADDR size();
eblob(DBCOL cc);
int seek(FILEADDR f, int fromwhere);
int tell();
size_t read(void* buf, size_t len);
size_t write(void* buf, size_t len);
FILEADDR inject(void* buf, FILEADDR len);
FILEADDR extract(FILEADDR len);

Filter Examples:

DB_Filter (emp, "jobcode == 16"); // C
emp->Filter("jobcode == 16"); // C++
DB_Find  ("PhoneList", "Lastname == %s && Firstname ==  %s", lastname, firstname); // C
db["PhoneList"].Find ("Lastname == %s && Firstname  ==  %s", lastname, firstname); // C++
DB_AddTable (db, "newtab", "Example of view",
   "basetable:  (col1  ==  5 || col2  ==  7)  &&  col3  == `abcde'"); // C
db->AddTable ("newtab", "Example of view",
   "basetable:  (col1  ==  5 || col2  ==  7)  &&  col3  == `abcde'");  // C++
tab = DB_Table (db, "table: col7 > 55 && col7 < 81"); // c
DBTAB  tab = new Table(db, "table: col7 > 55 && col7 < 81"); // C++
DB_ForAllRows ("table: col7 > 55 && col7 < 81")  {...} // C
ForAllRows ("table: col7 > 55 && col7 < 81")  {...} // C++

Free Text Search:

"chapter ?? `horses && (cows || pigs) && !donkeys'"

Regular Expression (Wildcard) Matching

• Any non-null character except asterisk (*), question mark (?), left brace ([), left bracket ({), or circumflex (^). These ordinary characters are matched literally.
• An asterisk to match an arbitrary string.
• A question mark to match any single character.
• A list of wildcard patterns enclosed within braces and separated by commas. This matches any of those wildcard patterns.
• A list of characters or ranges of characters (like "a-z" for "a" to "z") enclosed within square brackets and with no separators except a hyphen between the two characters of a range. The list may be preceeded with a circumflex (^) to match any character BUT the specified ones.

Wildcard Examples:

1. Create a database with one table in it.
2. Add some rows to the table and put some data in the rows.
3. List the contents of the database table.
4. Query the table.

Creating A Database

The following is a script that could be run through the utility, rc21.exe to create an empty phone list database. The database could also be created using RC/21 function calls.

remove fonelist.db
create fonelist.db
addtab * PhoneList "Phone List"
addcol * * Last "Last Name" "%s" NULL "String NoNulls"
addcol * * First "First Name" "%s" NULL "String NoNulls"
addkey * * LastFirst +Last+First Unique
addcol * * Address "Address" "%s" NULL String
addcol * * Phone "Phone Number" "%s" NULL "String NoNulls"
exit

#include "rc21.h"
void errorfunc(void)
   {
   PrintError("WHOOPS");
   exit (-1);
   }

void main (void)
   {
   SetErrorFunc(errorfunc);

   Remove ("fonelist.db");
   Create ("fonelist.db");
   Database db ("fonelist.db");
   db.AddTable ("PhoneList");
   Table fonelist (db, "PhoneList");
   fonelist.AddColumn ("Last", String);
   fonelist.AddColumn ("First", String);
   fonelist.AddColumn ("Address", String);
   fonelist.AddColumn ("Phone", String);
   fonelist.AddKey ("LastFirst", "+Last+First", Unique);
   db.Commit();
   }

Storing Data in the Database

#include <iostream.h>
#include <string.h>
#include "rc21.h"

void errorfunc(void)
   {
   PrintError("WHOOPS");
   exit (-1);
   }
   
void main (void)
   {
   SetErrorFunc(errorfunc);
   
   Database db ("fonelist.db");
   Table Fonelist (db, "PhoneList");
   Column
      Last (Fonelist, "Last"), First (Fonelist,
          "First"),
      Address (Fonelist, "Address"),
      Phone (Fonelist, "Phone");
   
   for (;;)   // exit on ctl-c
      {
      Fonelist.AddRow();
      cout << "\nLast Name: ";
      cin >> Last;
      cout << "First Name: ";
      cin >> First;
      cout << "Address: ";
      cin >> Address;
      cout << "Phone: ";
      cin >> Phone;
      db.Commit ();
      }
   }

Listing Contents of a Table

#include <iostream.h>
#include <stdlib.h>
#include "rc21.h"
   
void errorfunc(void)
   {
   PrintError("WHOOPS");
   exit (-1);
   }
   
void main (void)
   {
   SetErrorFunc(errorfunc);   /* register our error-handler */
   Database x ("fonelist.db", "r", 20);
   Table fonelist (x,"PhoneList");
   Column
      lastfirst (fonelist, "LastFirst"),
      last (fonelist, "Last"),
      first (fonelist, "First"),
      address (fonelist, "Address"),
      phone (fonelist, "Phone");

   lastfirst.OrderBy();
   
   cout << "\n\nPhone List:\n";
   ForAllRows (fonelist)
      cout << last << ", " << first << ": "
         << address << " " << phone << '\n';
   }

Querying a Table

   
#include <iostream.h>
#include <stdlib.h>
#include "rc21.h"
   
void errorfunc(void)
   {
   PrintError("WHOOPS");
   exit (-1);
   }
   
int main (void)
   {
   char firstname[81], lastname[81], c;
   
   SetErrorFunc(errorfunc);
   Database x ("fonelist.db", "r", 20);
   Table fonelist (x, "PhoneList");
   Column
      last (fonelist, "Last"),
      first (fonelist, "First"),
      address (fonelist, "Address"),
      phone (fonelist, "Phone");
   
   for (;;)
      {
      cout << "\nEnter firstname lastname: ";
      cin >> firstname >> lastname;
      if (fonelist.Find("Last == %s && First == %s", lastname, firstname))
         cout << last << ", " << first << ": "
            << address << " " << phone << endl;
      else
         cout << "Couldn't find.\n";
      }
   
   return 0;
   }