--- /dev/null
+Notice:
+ Fields and Table names are remapped to:
+ first char Upper case, the rest are lower case
+
+The code generator (x.C) processes limited schema information and
+ creates code which operates a base class Db as schema describes.
+
+ x.C reads from stdin, and has 1 optional parameter (theDb class name)
+ comments are whitespace, form /*comment*/ or -- comment... <cr>
+ ./a.out < schema.txt <class_name=defaults to theDb>
+ this produces a source file s.C containing all
+ * table definitions in the form of: <Tbl>
+ constructed as: Entity Tbl(db);
+ * default locators in the form of <tbl>
+ constructed as: TblLoc tbl(Tbl);
+ <Tbl> = table name, first char capitalized.
+ <tbl> = table name, all lower case
+ * ikey_<Key_name> and rkey_<Key_name> class definitions
+ * key cmpr functions for ikey_<Key_name> and rkey_<Key_name>
+ * EntityObj functions: Allocate, Construct, Destruct, Deallocate;
+ * theDb class definition, with base class Db with
+ constructor and functions create, open, and close
+
+ x.C allowed input data as follow:
+ items in [] are optional
+
+** CREATE TABLE table;
+* table = <table_name> ( <member> [, <member> ...] )
+* member = <field_name> <dtype> [<xtype> ...]
+* dtqual = ( [0-9...] ) | [UNSIGNED | SIGNED | ZEROFILL]
+* dtype0 = BIT | TINYINT | SMALLINT | MEDIUMINT | INT | INTEGER | BIGINT |
+ REAL | DOUBLE | FLOAT | DECIMAL
+* dtype1 = DATE | TIME | TIMESTAMP | YEAR |
+ CHAR | VARCHAR [BINARY] | BINARY | VARBINARY | BLOB | MEDIUMBLOB |
+ LONGBLOB | TINYTEXT | TEXT | MEDIUMTEXT | LONGTEXT | BOOL | BOOLEAN |
+ ENUM ( <enum_value> [, <enum_value> ...] )
+* dtype = <dtype0> [<dtqual>] | <dtype1>
+* xrefer = <table_name> ( <key_field> [, <key_field> ...] )
+ ON [DELETE | UPDATE] [RESTRICT | CASCADE | SET NULL | NO ACTION]
+* def_int = [+|-][0-9...]
+* def_dbl = <def_int>[.[0-9...]]
+* def_str = '[notany(') | \any() ...]' | "[notany(") | \any() ...]"
+* def_value = <def_str> | <def_int> | <def_dbl> | NULL
+* xtype = [NOT] NULL | DEFAULT <def_value> | AUTO_INCREMENT |
+ UNIQUE [PRIMARY] [KEY] | PRIMARY [UNIQUE] [KEY] |
+ REFERENCES xrefer
+
+** CREATE online modifier INDEX index;
+* index = <index_name> ON <table_name> ( <key_field> [, <key_field> ...] );
+* online = [ONLINE | OFFLINE]
+* modifier = [UNIQUE | FULLTEXT | SPATIAL]
+
+
+note: C++ type Schema field type
+ unsigned char: BOOLEAN, BIT, BINARY
+ [unsigned] char: CHAR, TINYINT
+ [unsigned] short: ENUM, SMALLINT
+ [unsigned] int: DECIMAL, MEDIUMINT, INT, INTEGER
+ [unsigned] long: BIGINT
+ double: REAL, DOUBLE
+ float: FLOAT
+ char[n]: DATE[8], TIME[6], YEAR[4] TIMESTAMP[14], DATETIME[14]
+ char[]: VARCHAR, TINYTEXT, TEXT, MEDIUMTEXT, LONGTEXT
+ unsigned char[]: VARBINARY, TINYBLOB, BLOB, MEDIUMBLOB, LONGBLOB
+ not implemented: SET
+
+examples:
+
+CREATE TABLE user_newtalk (
+ user_id int NOT NULL default 0,
+ user_ip varbinary(40) NOT NULL default '',
+ user_last_timestamp varbinary(14) NULL default NULL
+) ;
+CREATE INDEX un_user_id ON user_newtalk (user_id);
+CREATE INDEX un_user_ip ON user_newtalk (user_ip);
+
+CREATE TABLE text (
+ old_id int unsigned NOT NULL PRIMARY KEY AUTO_INCREMENT,
+ old_text mediumblob NOT NULL,
+ old_flags tinyblob NOT NULL
+) MAX_ROWS=10000000 AVG_ROW_LENGTH=10240; (MAX_ROWS,AVG_ROW_LENGTH are ignored)
+
+
+
+To initialize/open a db instance:
+
+#include <cstdio>
+#include "db.h"
+#include "s.C"
+
+theDb db;
+
+int main(int ac, char **av)
+{
+ if( db.create(dfn) ) {
+ fprintf(stderr,"create_db failed\n");
+ exit(1);
+ }
+ if( db.open(dfn) ) {
+ fprintf(stderr,"open failed\n");
+ exit(1);
+ }
+ return 0;
+}
+
+
+Normally, almost everything is done with Key classes and locators.
+There is a default locator for every entity (lower case tbl) in theDb.
+ defined similar to: Entity Tbl(db); TblLoc tbl(Tbl);
+
+Locators provide access to the record member fields:
+ Access is provided by the .member() function.
+ value = tbl.Field(); // read access
+ tbl.Field(value); // write access
+ tbl.size_Field(); // size(value)
+ tbl._Field(); // addr(value)
+ tbl.Field(value,sz); // write access to varObj/blob field
+ tbl.set_wr(); // mark dirty
+
+
+
+To create database records:
+
+void insert()
+{
+ db.tbl.Allocate(); // allocates a Tbl record assigned to tbl locator
+ db.tbl.Field1(value1); // assignes values to new Tbl record fields
+ db.tbl.Field2(value2); // ...
+ db.tbl.Construct(); // runs theDb record constructor
+}
+
+the record constructor is normally generated by x.C and typically:
+ if_err( insertProhibit() ); // run consistancy checks
+ if_err( construct() ); // load id and reference
+ int id = this->id();
+ { rkey_Tbl_Key1 rkey(*this); // add all keys associated to new id
+ if_err( entity->index("Tbl_Key1")->Insert(rkey,&id) ); }
+ if_err( insertCascade() ); // run insert cascade functions
+ return 0;
+
+
+To access database records:
+ The TblLoc::ikey_Field key classes use immediate data for key values
+ The TblLoc::rkey_Field key classes use the current record for key values
+
+The Db::Key class provides:
+ int Find(); // immedate ikey_ only
+ int Locate(int op=keyGE); // immedate ikey_ and relative rkey_
+ int First(); // relative rkey_ only
+ int Last(); // relative rkey_ only
+ int Next(); // relative rkey_ only
+ int First(pgRef &pos); // relative rkey_ only
+ int Next(pgRef &pos); // relative rkey_ only
+
+To Locate/Find a table record (= EntityObj), use:
+
+ theDb db; db.open("/path/the.db");
+ int ret = TblLoc::ikey_Key1(db.tbl, key).Find();
+ if( ret != 0 ) printf(" not found, ret = %d\n",ret);
+ printf(" the record data is now %d\n", ++db.tbl.Data());
+ db.commit();
+ db.close();
+
+** NOTE: <key field parameters> will be automatically constructed from
+ basic types, but for varObj types they should be explicity constructed
+ as in:
+ int ret = TblLoc::ikey_Key1(db.tbl, TblObj::t_Key1Field1(key, ksz)).Find();
+
+Locate may be called with op=keyLT,keyLE,keyEQ,keyGE,keyGT
+ the index will be positioned to the appropriate boundry
+ keyEQ is mapped to keyLE when used with Locate
+
+First/Next have a default cursor position associated to the index.
+First/Next may return/use a cursor position locator which may be
+ used if multiple simultainious cursor positions are needed.
+
+To iterate use Locate/First to set the cursor at a table record
+ then use Next to iterate until need records are exhausted.
+
+ theDb db; db.open("/path/the.db");
+ TblLoc::rkey_KeyField1 key1(db.tbl);
+ if( !(ret=key1.First()) ) do {
+ printf(" the record data is now %d\n", ++db.tbl.Data());
+ } while( !(ret=key1.Next()) );
+ db.commit();
+ db.close();
+
+
+
+To delete database records:
+
+ theDb db; db.open("/path/the.db");
+ while( !db.tbl.Last() ) {
+ db.tbl.Destruct(); // run theDb record destructor
+ db.tbl.Deallocate(); // release db storage assigned to db.tbl
+ }
+
+the record destructor is normally generated by x.C and typically:
+ if_err( deleteProhibit() ); // run consistency checks
+ { rkey_Tbl_Key1 rkey(*this); // remove all keys associated to id
+ if_err( entity->index("Tbl_Key1")->Delete(rkey) ); }
+ if_err( destruct() ); // delete id and reference
+ if_err( deleteCascade() ); // run delete cascade functions
+ return 0;
+
+
+There are also "media" keys, which are bit field key records which
+are organized by total "weight" = unsigned sum of bit fields. The
+weight is recursively subdefined in left/right subfields, so that
+all of the key record is encoded. This usually requires a little
+over 3 times as much storage. This kind of key can index audio/video
+data (and others, biometric, dna, images...). The key data can be:
+built, recovered, and compared for both magnitude and error as sum
+of squared/linear error. The work on this not complete at this time.
+to insert (8 bit fields):
+ int ksz = Db::mediaKey::byte_size(sz, 8);
+ uint8_t *key = db.Tbl._key1(ksz);
+ Db::mediaKey::build(key, dat, 8, sz);
+
+to access (8 bit fields):
+ int ksz = Db::mediaKey::byte_size(len, 8);
+ uint8_t key[ksz];
+ Db::mediaKey::build(key,dat,8,len);
+ PrefixLoc::ikey_Prefix_key_data ikey(db.prefix, key);
+ if( (ret=ikey.Find()) != 0 ) {
+
+
+
+
+
+Example:
+
+Makefile:
+
+CPPFLAGS := -Wall -ggdb $(CFLAGS)
+LDFLAGS :=
+
+all: prog
+
+clean:
+ rm -f *.o xsch prog
+
+prog: prog.o db.o
+ g++ -o $@ $(LDFLAGS) $+
+
+s.C: x.o sch.txt
+ g++ -o xsch x.o
+ ./xsch < sch.txt
+
+db.o: db.C db.h
+prog.o: prog.C prog.h s.C db.h
+x.o: x.C
+
+
+sch.txt:
+
+CREATE TABLE a_tbl (
+ a_id int unsigned NOT NULL PRIMARY KEY AUTO_INCREMENT,
+ a_name varchar(255) binary NOT NULL default '',
+ a_data int
+);
+CREATE UNIQUE INDEX a_names ON a_tbl (a_name);
+CREATE UNIQUE INDEX a_datum ON a_tbl (a_data);
+
+
+prog.C:
+
+#include <cstdio>
+#include <stdlib.h>
+#include <unistd.h>
+#include <fcntl.h>
+
+#include "db.h"
+#include "s.C"
+
+theDb db;
+
+void chk(int ret, const char *msg)
+{
+ fprintf(stderr,"fail %s = %d\n",msg,ret);
+ exit(1);
+}
+
+void insert(const char *nm, int dat)
+{
+ chk( db.a_tbl.Allocate(), "Allocate");
+ chk( db.a_tbl.A_name(nm), "A_name(nm)");
+ chk( db.a_tbl.A_data(dat, "A_data(dat)");
+ chk( db.a_tbl.Construct(), "Construct");
+}
+
+int main(int ac, char **av)
+{
+ const char *dfn = ac > 1 ? av[1] : "the.db";
+ chk( db.create(dfn), "db.create");
+ chk( db.open(dfn), "db.open");
+
+ // insert some data
+ insert("a borrower", 321);
+ insert("nor lendor", 232);
+ insert("be", 123);
+
+ chk( db.commit(), "commit()");
+ chk( db.close(), "close()");
+ chk( db.open(dfn, "db.reopen");
+
+ // lookup at datum using immedate key
+ int dat = 232;
+ A_tblLoc::ikey_A_datum ky(db.a_tbl,dat);
+ chk( ky.Find(), "ky.Find()");
+ printf("Found %d name %s\n",dat,db.a_tbl.A_name());
+
+ // look at datum using relative key
+ int ret = 0;
+ A_tblLoc::rkey_A_datum rky(db.a_tbl);
+ if( !(ret=rky.First()) ) do {
+ printf("Data %d name %s\n",db.a_tbl.A_data(),db.a_tbl.A_name());
+ } while( !(ret=rky.Next()) );
+ if( ret == Db::errNotFound ) ret = 0;
+ chk( ret, "datam");
+
+ // get cursor position using immediate key
+ A_tblLoc::ikey_A_names iky(db.a_tbl,"b");
+ if( !(ret=iky.Locate()) ) {
+ // switch to relative key
+ A_tblLoc::rkey_A_names rky(db.a_tbl);
+ do {
+ printf("Name %s data %d\n",db.a_tbl.A_name(),db.a_tbl.A_data());
+ } while( !(ret=rky.Next()) );
+ }
+ if( ret == Db::errNotFound ) ret = 0;
+ chk( ret, "names");
+ chk( db.commit(1), "commit(1)");
+ db.close();
+ return 0;
+}
+
+
+Traveling db:
+only one process allowed write access, no readers allowed
+ all allowed read lock while not write locked
+to access database, typically:
+int resetDb(int rw)
+{
+ int result = 0;
+ if( access("/path/t.db", F_OK) ) db->create("/path/t.db");
+ if( !result ) result = openDb(rw);
+ return result;
+}
+int openDb(int rw) { return db->access("/path/tdb.db", SHM_KEY, rw); }
+void closeDb() { detachDb(); db->close(); }
+void commitDb() { db->commit(); } // detaches
+void undoDb() { db->undo(); } // detaches
+int attachDb(int rw) { return db->attach(rw); }
+int detachDb() { return db->detach(); }
+
+typical session:
+openDb(); detachDb(); ...
+//typical read access
+attachDb(); do_read(); detachDb(); ...
+//typical write access
+attachDb(1); do_write(); commitDb(); ...
+closeDb();
+
projects / goodguy / history.git / blobdiff