CVS update of odbsequoia (7 files)

    Date: Friday, March 24, 2006 @ 15:04:36
  Author: marc
    Path: /cvsroot/carob/odbsequoia

   Added: COPYING (1.1) README (1.1) doc/CREDITS (1.1) doc/DESIGN (1.1)
          doc/INSTALL (1.1) doc/RELNOTES (1.1) doc/UNICODE (1.1)

Added documentation text files (README, doc/INSTALL, etc.)
Some are written in reStructuredText http://docutils.sourceforge.net/rst.html


--------------+
 COPYING      |   17 +++++
 README       |   40 ++++++++++++
 doc/CREDITS  |   11 +++
 doc/DESIGN   |  103 ++++++++++++++++++++++++++++++++
 doc/INSTALL  |  132 +++++++++++++++++++++++++++++++++++++++++
 doc/RELNOTES |  180 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 doc/UNICODE  |   15 ++++
 7 files changed, 498 insertions(+)


Index: odbsequoia/COPYING
diff -u /dev/null odbsequoia/COPYING:1.1
--- /dev/null   Fri Mar 24 15:04:36 2006
+++ odbsequoia/COPYING  Fri Mar 24 15:04:36 2006
@@ -0,0 +1,17 @@
+ODBSequoia: ODBC driver for Sequoia database clustering technology.
+
+Copyright (C) 2006 Continuent, Inc.
+Contact: sequoia-NAAfj4rwCWAYtQj7fl1lsA@xxxxxxxxxxxxxxxx
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+
Index: odbsequoia/README
diff -u /dev/null odbsequoia/README:1.1
--- /dev/null   Fri Mar 24 15:04:36 2006
+++ odbsequoia/README   Fri Mar 24 15:04:36 2006
@@ -0,0 +1,40 @@
+==========
+ODBSequoia
+==========
+
+The ODBC driver for Sequoia database clustering technology.
+
+ http://carob.continuent.org/
+
+For now ODBSequoia is only shipped as source code. See the doc/INSTALL
+file for compilation instructions.
+
+:README:           this file
+:COPYING_:         licence
+
+:`doc/INSTALL`_:   compilation instructions
+:`doc/RELNOTES`_:  current features and limitations
+:`doc/CREDITS`_:   authors
+:`doc/DESIGN`_:    to read before the source (in directory src)
+:doc/BUGS: None! Check our `bug tracker 
<https://forge.continuent.org/jira/browse/CAROB>`_ instead.
+
+
+The two main ODBC references used
+
+- `ODBC Programmer's reference 
<http://msdn.microsoft.com/library/default.asp?url=/library/en-us/odbc/htm/odbcabout_this_manual.asp>`_
 - by Microsoft
+- `Data Management: SQL Call Level Interface (CLI) 
<http://www.opengroup.org/bookstore/catalog/c451.htm>`_ - the X/Open standard
+
+Two good ODBC tutorials
+
+- http://www.easysoft.com/developer/languages/c/odbc_tutorial.html
+- http://www.anaesthetist.com/mnm/sql/odbc.htm
+
+
+
+.. hyperlinks
+
+.. _COPYING: COPYING
+.. _doc/INSTALL: doc/INSTALL.html
+.. _doc/RELNOTES: doc/RELNOTES.html
+.. _doc/CREDITS: doc/CREDITS
+.. _doc/DESIGN: doc/DESIGN.html
Index: odbsequoia/doc/CREDITS
diff -u /dev/null odbsequoia/doc/CREDITS:1.1
--- /dev/null   Fri Mar 24 15:04:36 2006
+++ odbsequoia/doc/CREDITS      Fri Mar 24 15:04:36 2006
@@ -0,0 +1,11 @@
+Marc Herbert designed and wrote the ODBSequoia driver, with the
+constant support of Gilles Rayrat.
+
+The Carob library does most of the work underneath. It was more or
+less designed as a C++ port of the sequoia JDBC driver by Gilles
+Rayrat and Marc Herbert, and mainly implemented by Gilles Rayrat with
+some help from Marc Herbert.  Csaba Simon and Zsolt Simon also brought
+significant contributions to Carob.
+
+
+
Index: odbsequoia/doc/DESIGN
diff -u /dev/null odbsequoia/doc/DESIGN:1.1
--- /dev/null   Fri Mar 24 15:04:36 2006
+++ odbsequoia/doc/DESIGN       Fri Mar 24 15:04:36 2006
@@ -0,0 +1,103 @@
+Read this before hacking some ODBSequoia code.
+
+A minimal knowledge of ODBC is required to understand this document.
+
+Seeing the ODBSequoia driver as an ODBC layer on top of a JDBC driver
+is not far from the truth.  This design is eased by the fact that JDBC
+has been more or less designed after ODBC.
+
+
+Overview
+--------
+
+Despite being designed for C and COBOL, the ODBC API is very
+object-oriented, which fits quite well a C++ implementation.  The main
+objects defined by the ODBC standard, and implemented here are:
+
+- ODBCEnv, ODBCConnection, ODBCStatement,
+- ODBCDescriptors
+
+These 4 classes derive the abstract class ODBCItem defined in file
+abstract_item.hpp.  This main purpose of this base class is to
+implement diagnostics (see below). The 4 derived classes are
+implemented in files env.hpp, connect.hpp, statement.hpp and
+descriptors.hpp respectively. The file explicit_type.cpp implements
+polymorphic ODBC functions, immediately redirecting the call to the
+class explicity specified by the ODBC application.
+
+Below ODBSequoia, JDBC-like classes exported by Carob are:
+
+- Connection, Statement, ResultSet
+
+There is one-to-one mapping between ODBCConnection and Connection as
+well as between ODBCStatement and Statement, the first holding a
+pointer to its underlying Carob implementation. Since in ODBC all
+accesses to result sets goes through an ODBCStatement handle, there is
+no need for an ODBCResultSet class on to of the Carob
+one. ODBStatement just calls carob_stmt->getResultSet() when needed.
+The fact that a Statement can have only one active ResultSet at a time
+makes this easy.
+
+These two ODBCItem unfortunately need to hold a *pointer* to their
+corresponding Carob object (as opposed to a safer reference), because
+they need to support a dirty half-constructed state with a Carob NULL
+pointer inside. That's because ODBC objects are not atomically
+created: you can first create an empty ODBC object using
+SQLAllocHandle() and initialize it only later. Do not forget ODBC is
+just C, not real object-oriented C++.
+
+
+Descriptors
+-----------
+
+Descriptors describe buffers for SQL Data: either rows of ResultSets
+or one row of parameters for (in the future) ParameterStatements. They
+hold all the variables related to memory management, type conversion
+etc. A descriptor is composed by a header and a vector of descriptor
+records, one record for each column/parameter. SQLBindCol() and
+SQLBindParam() are the usual way to configure records before fetching
+data/executing ParamaterStatements.  There are new functions in ODBC
+3.0 to control descriptors more finely; but those fine-tuning functions
+are not yet implemented by ODBSequoia.
+
+
+Diagnostics
+-----------
+
+Errors and warnings are implemented in ODBC using
+diagnostics. According to the specification each ODBCItem holds one
+diagnostic composed of one header and a vector of diagnostics
+records. Each record represents one error/warning, so it is possible
+to attach an arbitrary number of errors/warnings to each ODBCItem (in
+a well defined order).  Diagnostic records are implemented here by the
+class DiagRecord in file abstract_item.hpp.
+
+The java.sql.SQLException chain (and its derived class SQLWarning) has
+been later designed in a way quite similar to ODBC
+diagnostics. CarobException is the Carob equivalent: CarobExceptions
+are used by Carob both to report SQLExceptions coming from the
+Controller and to issue its own errors. So there is a rather
+straight-forward mapping between these three cousins. Internally
+ODBSequoia and Carob makes an intensive use of exceptions, but
+obviously exceptions cannot be thrown by a C interface, so almost each
+ODBC function is implemented like this (simplified a bit):
+
+::
+
+  SQLDoSomething(somehandle, arg1, arg2,...)
+  {
+    try {
+        somehandle->do_something(arg1, arg2,...)
+    } catch (const CarobException& ce_chain) {
+        somehandle->push_diagnostics(ce_chain);
+        return SQL_ERROR;
+    }
+  }
+
+Instead of being thrown, warnings are just returned but they use the
+same classes.
+
+
+--------
+
+$Date: 2006/03/24 14:04:36 $ $Revision: 1.1 $
Index: odbsequoia/doc/INSTALL
diff -u /dev/null odbsequoia/doc/INSTALL:1.1
--- /dev/null   Fri Mar 24 15:04:36 2006
+++ odbsequoia/doc/INSTALL      Fri Mar 24 15:04:36 2006
@@ -0,0 +1,132 @@
+=================================
+Compiling & installing ODBSequoia
+=================================
+
+Buildchain
+==========
+As a build chain you need GNU make and a recent C++ compiler and
+STL. We make intensive use of features added by the C++98 standard,
+as well as of C99 integer types (uint32_t etc.), so you also need some
+<stdint.h/cstdint> C99 header file.
+
+We develop using g++ version 4, but with extra care not to rely on any
+non-standard extensions (please report any to the mailing list).
+
+| news://news.gmane.org/gmane.comp.db.carob.general
+| nntp://news.gmane.org/gmane.comp.db.carob.general
+| https://forge.continuent.org/mail/?group_id=10
+
+
+Operating System
+================
+ODBSequoia and Carob have unfortunately been tested only on linux so
+far, but with standards always in mind, so porting them to other
+unices is hopefully the matter of minutes.
+
+Windows systems will probably require a bit more work. The only
+problematic, low level code should lie in the following files:
+
+-  carob/src/JavaSocket.cpp        (TCP/IP)
+-  carob/src/CriticalSection.hpp   (Thread mutexes; optional)
+-  odbsequoia/src/util.cpp         (Some SQLWCHAR conversion code still TODO)
+
+Trying Cygwin_ or even just MinGW_ is a good bet.
+
+.. _Cygwin: http://www.cygwin.com/
+.. _MinGW: http://www.mingw.org/
+
+Libraries
+=========
+Carob is the workhorse of the driver, which links statically to it. So
+the very first step is to get Carob_ source and compile it.
+To get a Carob version compatible with ODBSequoia, you can either:
+- TODO
+- or use the latest CVS HEAD for both.
+
+
+Most of libraries and headers listed below should be available as
+precompiled and packaged for your platform by your favorite free
+software distributor.
+
+.. _Carob: http://carob.continuent.org/
+
+Carob dependencies
+------------------
+The most noticeable dependency of Carob is GMP_
+
+Another library used by Carob is log4cxx_, but it's optional; if you do
+not link Carob to it logs will go to stderr.
+
+The test suite shipped with Carob needs CppUnit_.  In case of
+unidentified problems with the driver, the first thing to do is to run
+Carob's test-suite.
+
+Check Carob documentation for more details.
+
+.. _GMP: http://swox.com/gmp/
+.. _log4cxx: http://logging.apache.org/log4cxx/
+.. _cppunit: http://cppunit.sourceforge.net/
+
+ODBSequoia
+----------
+
+The only additional dependency of ODBSequoia compared to Carob is
+(quite obviously) an ODBC driver manager. You need an Unicode Driver
+Manager, check the UNICODE_ file about this.
+ODBSequoia has been developed using unixODBC 2.2.11.
+Hopefully using alternatives should not be an issue (did I already
+ask to report any success to the mailing list?).
+
+.. _UNICODE: UNICODE
+
+Compilation
+===========
+Go into carob's main directory and type
+
+::
+
+  make libcarob.a
+
+This will create the only file needed to compile ODBSequoia.
+Then go into odbsequoia "src" directory. You may need to fix the
+CAROB_PATH=../../ at the beginning of GNUmakefile so it can find
+libcarob.a. Now type:
+
+::
+
+   make libodbsequoia.so
+
+
+Installation
+============
+
+Congratulations, this library file you just made is the driver. If you
+did this on a yet unsupported platform, please proudly report this to
+the mailing list. Now you can either:
+
+- copy it into one the directories searched by the library loader of
+  your system ("/lib", "/usr/lib", etc.)
+- install it anywhere else you like, as long as you provide an
+  absolute path to it in the odbcinst.ini configuration file.
+
+
+Configuration
+=============
+Edit the sample odbinst.ini and odbc.ini file provided according to
+your particular configuration, and append them according to the
+documentation of your ODBC driver manager (typically to
+/etc/odbcinst.ini and $HOME/.odbc.ini).  The optional LogLevel setting
+in the .odbc.ini file is based on log4cxx. If you compile carob
+without log4cxx the logs will go to stderr instead.
+
+In the configuration of your ODBC client application, replace the ODBC
+Data Source Name of your database by the DSN of the sequoia
+virtualdatabase you just configured in your odbc.ini file ("seqsource"
+for instance in the sample file provided).
+
+Run your application, and please report what went right or wrong!
+
+--------
+
+$Date: 2006/03/24 14:04:36 $ $Revision: 1.1 $
+
Index: odbsequoia/doc/RELNOTES
diff -u /dev/null odbsequoia/doc/RELNOTES:1.1
--- /dev/null   Fri Mar 24 15:04:36 2006
+++ odbsequoia/doc/RELNOTES     Fri Mar 24 15:04:36 2006
@@ -0,0 +1,180 @@
+=============================
+ODBSequoia 0.5a RELEASE NOTES
+=============================
+
+This file documents the features and limitations of the ODBSequoia
+driver version v0.5a.
+
+The ODBSequoia driver is designed as a thin layer above the Carob
+static library.  Most of the work is actually performed by Carob. To
+simplify the whole thing is called "the driver" below.
+
+
+Features
+========
+
+Basic ODBC support
+------------------
+
+Ability to connect to a sequoia controller, send a write query, get
+the update count, send a read request, browse the resultset,
+disconnect. You can actually do something useful with this
+preview. However no advanced features are implemented yet and your
+usual ODBC application is likely to miss some.
+
+
+Full-featured error reporting
+-----------------------------
+
+Among others that means that not yet implemented features and other
+failures will NOT leave you in the dark wondering what happened. There
+are also no "half-implemented" features that could put the driver in
+an inconsistent state or crash.  Giving a try to this driver will not
+eat your time; if your application has good error reporting then you
+will be able to know right away where this preview stands.
+
+From your ODBC .ini configuration file you can also enable a useful
+log feature (using log4cxx or to a more basic stderr).
+
+
+Unicode
+-------
+
+When some ODBC function has a 'W' (wide char) version, then ODBSequoia
+implements it using the 'W' version, so no worry for you unicode
+application. But this also imply that you need an Unicode Driver
+Manager. Check the UNICODE_ file for more details.
+
+
+.. _UNICODE: UNICODE
+
+
+Active community support
+------------------------
+
+http://carob.continuent.org/
+
+If you report a problem to the `mailing-list`_ and the fix is simple
+enough, it will be committed to CVS in the next days.  Feature wishes
+reported on the mailing-list will always get a higher priority on
+others: we need your feedback to know which are the ODBC features that
+matter. And do not forget to check our JIRA `task/bug tracker
+<https://forge.continuent.org/jira/browse/CAROB>`_.
+
+Obviously patches & other contributions are highly welcome
+(under the Apache 2.0 licence currently used).
+
+.. _`mailing-list`: INSTALL.html
+
+
+Not yet implemented features
+============================
+
+- Only standard SQLConnect() DSN-style connection (using an
+  odbcinst.ini and odbc.ini configuration files) is supported. No fancy
+  Microsoft connect extensions.
+
+- No parametrized statements (no ``SQLBindParam()``)
+
+- No (multi-statements) transactions
+
+- No attributes, only default settings are provided;
+  XXXAttr() and XXXOption() functions are not supported
+
+- Partial support for reading results:
+
+  - no DescribeCol()
+  - missing C types: dates, *unsigned* integers, Microsoft NUMERIC_STRUCT.
+    (All SQL types are supported.)
+  - no fancy resultset features like: scrollable, updatable, block
+    cursors, blobs.
+
+- No ODBC 3.0 explicit descriptors
+
+- No Metadata functions (``Columns()``, ``Tables()``,...)
+
+- Limited tested portability; see INSTALL_ file.
+
+- No garbage-collecting: there will be a small memory leak each time
+  the ODBC application forgets to call SQLFreeHandle()
+
+.. _INSTALL: INSTALL.html
+
+Testing
+-------
+
+Almost every line of this code has been manually tested, meaning it
+has actually run at least once. But the next developement step is
+definitely to implement some exhaustive, automated and regularly run
+non-regression test-suite.
+
+
+Partially implemented functions
+===============================
+
+- SQLFetch
+- SQLBindCol
+- SQLSetEnvAttr (implemented only for SQL_ATTR_APP_ODBC_VER)
+
+
+Not yet implemented functions
+=============================
+
+Calling these functions will simply fail.
+
+- SQLDriverConnect
+- SQLBrowseConnect
+
+- SQLBindParameter
+- SQLNumParams
+
+- SQLSetConnectAttr
+- SQLGetConnectAttr
+- SQLGetEnvAttr
+- SQLSetStmtAttr
+- SQLGetStmtAttr
+
+- SQLNativeSql
+- SQLEndTran
+
+- SQLDescribeCol
+
+- SQLFetchScroll
+- SQLMoreResults
+- SQLSetPos
+- SQLBulkOperations
+- SQLGetCursorName
+- SQLSetCursorName
+- SQLSetScrollOptions
+- SQLParamData
+- SQLPutData
+- SQLGetData
+
+
+- SQLGetDescField
+- SQLGetDescRec
+- SQLSetDescField
+- SQLSetDescRec
+- SQLColAttribute
+- SQLDescribeParam
+- SQLCopyDesc 
+
+- SQLGetInfo
+- SQLGetTypeInfo
+
+- SQLColumnPrivileges
+- SQLColumns
+- SQLForeignKeys
+- SQLPrimaryKeys
+- SQLProcedureColumns
+- SQLProcedures
+- SQLSpecialColumns
+- SQLStatistics
+- SQLTablePrivileges
+- SQLTables
+
+- SQLCancel
+
+--------
+
+$Date: 2006/03/24 14:04:36 $ $Revision: 1.1 $
Index: odbsequoia/doc/UNICODE
diff -u /dev/null odbsequoia/doc/UNICODE:1.1
--- /dev/null   Fri Mar 24 15:04:36 2006
+++ odbsequoia/doc/UNICODE      Fri Mar 24 15:04:36 2006
@@ -0,0 +1,15 @@
+When an ODBC function has a 'W' (wide) version, then ODBSequoia
+implements it using the 'W' version. So ODBSequoia requires an
+Unicode-ready driver manager.
+
+Unicode driver managers
+- iODBC     >= 3.51
+- unixODBC  >= 2.
+- Microsoft Windows  >= 98
+- MacOSX >= 10.4 (Tiger)
+
+When your platform does not ship with a unicode driver manager there
+are a couple of workarounds possible, all along the line: "use a more
+recent driver manager". Either link your application to a newer
+version or even upgrade the driver manager of your whole system.
+