The API is written in C++, because we don't have the time to deal with complex a lgorithms in pure C. There is still an optimization to be done. Nevertheless all API calls are pure C, because pure C is 100% mSQL compatibel. The only differe nce between the calls of David Hughes and ours, is that the prefix 'msql' is rep laced by 'jeb'. Old mSQL C-applications are compiled to run under 'jebd' distrib uated control the following way:
1. replace msql.h with jeb.h in all source files 2. Add msql2jeb.h at the line below. 3. compile with libjeb.a:
% c++ -o <programname> <sourcecode> -I ~/Hughes/include -L ~/Hughes/lib -l jeb
The fact that we deal with transactions in the DBMS, gives three extra API calls:
void jebTrBegin(); void JebCommit(); void JebAbort();
It is possible to make jebd applications without using the calls. Every SQL-stat ement is then encapsulated in its own transaction. They are implicit a leading t ransktion begin and trailing commit.
jebTrBegin() signals the start of a (multi sql statement) transaction. Internall y 'jebd' assigns a transaktion-ID, to the transaction which is used in its commu nication to the Lockmanager. JebCommit() or JebAbort() signals the end of the tr ansactions, where commit adds the result of the transactions of sql-statements p ermanent to the database, and abort makes the database untouched, as before the transaction began. The fact that no transaction-ID's exists at application level , implies that only one transaction can be used at a time. But that concerns eve ry single connection made to 'jebd'. Every connection creates a child at 'jebd', who again makes its own connections to the msql2d's administrating the tables i n request. Nested transaction is a useful feature, and in 'jeb' it is entirely u p to the application programmmer to use it sensible, by making multiple connecti ons.
An unavoidible flaw with distributed systems, is the potentiel for deadlocks. In a case with tables, as in our system, any normal use in practice will have to d eal with deadlocks. The (only) cure is to abort some of the deadlock-involved pr ocesses. In the first place it is the Lockmanager, which aborts some of the tran saction beeing involved in the deadlock (using GWFG algorithms). A part of 'jebd ' - the Transactionmanager - recieves the abort, and will try to reclaim the res ources a coupple of times (or in a specified period of time). Perhaps the tables are freed when another application is finished. But the facility to throw the a bort to the application must exist. It is implemented by returning a -1, the nor mal answer of a unexecuteable sql statement. In case of an abort beeing the cource, JebErrMsg contains: "TA: transaction abor ted".
Now it should be a clear, which form of a DBMS we develop. It does not deal with distributed transactions. 'jebd' do not communicate with other sessions of 'jeb d' by any other means than claiming exclusively access to common resouce (table s), at the Lockmanager.
All the other API call have the arguments and funtionality like that of mSQL. On ly the name is changed, replacing the 'msql' prefix wit 'jeb'. The documentation of these calls, when nothing special is mentioned below, can be found in the mS QL installation directory (Huges/doc/manual??). At the time of this writing, the following makes the jeb C++ API.
int jebConnect(char *); int jebSelectDB(int socket,char *dbname) int jebQuery(int socket, char * query) void jebFreeResult(m_result *) m_result *jebStoreResult() m_row jebFetchRow(m_result *res) m_field jebFetchField(m_result *res) void jebDataSeek(m_result *res,pos) void jebFieldSeek(m_result *res,pos) int jebNumRows(m_result *res) imt jebNumFields(m_result *res) m_result *jebListDBs(int socket) m_result *jebListFields(int socket,char *table) m_result *jebListIndex(int socket,char *table, char *index) m_result *jebListTables(int socket) char *jebErrMsg;
JebConnect(); Unlike msqlConnect(char*), it is only possible to connect to a local 'jebd'. The char * is a dummy, for compatibility reasons. Multiple connections can be made.
jebSelectDB(int socket,char *dbname) This call does not involve socket communication at all, and it has the double pu rpose of making the API msql-compatible and check that the soucecode have been e xamined prior to porting to 'jeb'. Attempts to call JebSelectDB with other argument than a valid socket descriptor and the database name: "uocs", returns an error. "uocs" (union of connected site s) contains the union of tables, and the databases that is actually conneted by 'jebd', is one at each site, called site<host>. These priliminary constraints wi ll perhaps be changed in further releases af 'jeb', where site<host> becomes a s ort of metadata describing sets of databases om each site. Conseptually, applica tions will still see one database containing the union of tables from the connec ted sites.
jebQuery(int socket, char * query) As mentioned earlier, returning -1 can, in advance to the mSQL-conditions for th at, be caused by an action, indicated by jebErrMsg containing: "AT abort transac tion"
jebListDBs(int socket) No socket communication is involved. An m_result structure, with the name "jeb C atalog" and single field "uocs" and some appropriate attributes is built an retu rned.
Structures. Jeb C++ API, contains the same structure as mSQL, mainly the m_result and its su bstructures. The same two chains are built, and the odd result from an msqlListI ndex(...) is also maintained.
Source files The msql-addon directory, created when untaring, contains two subdirectories, wh ere the main components and the source code resides.
jeb/ The server part. It contains: classdimp.cxx Implementations of classes globalvars.cpp Global shared variables jebd.cpp Main communication and request parsing query.cpp Query parser s_dtline.cpp Line oriented Communication primitives services.cpp Body parts of API funtionality transfer.cpp Transfering of m_result structures. makefile
/API classimp.cxx Implementation of classes globalvars.cpp Global shared Variables apifunc.cpp The C-API Functions connect.cpp Socket establishing function jebsh.cpp Command interpreter, and API function interface makefile
And a subdirectory containing some common files.
/common jeball.H All declarations for both server and clinet utils.cpp Listing utility, used to dump m_result structures jebutils.h Declarations used by utils
msql-addon1.5 installation directory contains lm1.5.pl The lock manager. Is only started at one site jeb.conf The configuration file, contains info about port numbers and pla cement of Lockmanager startjeb Script to start jebd, and if present, the Lockmanager lm 1.5.pl stopjeb Script to shutdown jebd, and if running and an option is given, the Lock manager too libjeb.a Static C++ library for making c++ jeb-msql applications jeb.h Include file with declarations to make jeb-msql applications jeb2msql.h Include file to recompile old msql application to run uder distr ibuted control Howto-jeb This document. makefile makelinks removelinks
Under installation (when 'make' is done) symbolic links are placed in API/ and j eb/, to files from common/ The jeball.h contains a #define macro, which by use of a compiler directive sele cts the appropriate server and client parts.