Instructions for using the Database Template Library

  1. Contents
    1. When you unpack dtl.zip it should create the following directories:
    2. \docs: Documentation and examples on how to use the Database Template Library. To read, open the main file called index.htm.
    3. \lib: This is the main code for the DTL.
    4. \example_db: Table definitions and sample data for the code in the "example" and "tests" directories.
    5. \example: Example code for using the DTL.
    6. \tests: Regression tests for the DTL / further examples.
  2. Getting Started:
    1. Take a look at the docs files. Be sure to read "Introduction to the DTL" as this gives a good overview of the capabilities of the library.
    2. Go into the lib directory. Build the library file (DTL.lib in Windows, dtl.a in UNIX). To compile from Visual Studio 6.0 open DTL.dsw. To compile from UNIX type "make" which will run the "Makefile" in this directory. (To compile under UNIX you will need to have unixODBC installed).
    3. Create the sample database from the example_db directory.
      1. If you have a copy of Access97 there is nothing to do here. We have a sample Access database in the example_db directory.
      2. If you are using Oracle perform the following steps from SQL*PLUS:
        1. >create user example identified by example;
        2. >grant dba to example; -- actually we need less than this, but it's easier to grant dba
        3. >connect example/example;
        4. >@e:\dtl\example_db\tables.sql -- run the tables script to create the example tables
        5. >@e:\dtl\example_db\data.sql -- insert sample data into the example tables
      3. If you are using MySQL perform the following steps:
        1. create a user called "example" with password "example".
        2. >mysql <database_name> -u example < tables.sql -- run the tables script to create the example tables
        3. >mysql <database_name> -u example < data_mysql.sql -- insert sample data into the example tables
    4. Create an ODBC data source called "example" from the ODBC Data Source Administrator tool in the control panel:
      1. The example code uses the following ODBC connect string: "UID=example;PWD=example;DSN=example;"; Therefore it connects as user "example", password "example" to the ODBC data source named "example". We assume that the user and password are already set up as explained above & show how to set up the data source name.
      2. Choose the tab labeled "System DSN". Choose "Add --> Microsoft Access Driver (*.mdb)". For the data source name enter "example" and choose the file called example.mdb in the example_db directory. (If you prefer to use Oracle choose the Oracle ODBC driver and enter your SQL*NET connect string etc.)
    5. Build and run the example code.
      1. Go to the directory called \example. Open the file example.dsw and build from VC++ 6.0 to create the example executable. (Or run "make" from the example directory if you are working under UNIX).
  3. Using the library in your own code:
    1. To use the library in your own code you will need to do two things:
      1. Include the \lib directory in the include (\I) path for your compiler.
      2. Include the library file (DTL.lib or dtl.a) in the set of files that you link to in producing your executable.
  4. Release Notes
    1. Version 2.0
      1. Added support for SGI's STLPort implementation of the Standard Template Library.
      2. Successfully ported code to Red Hat Linux 7 under gcc 2.95 running unixODBC and a MySQL 3.23.33 database.
      3. Corrected constness throughout DTL.
      4. Rewrote the code to make it exception safe.
      5. Added error handling support for all DTL iterator classes, DBView, and IndexedDBView in the form of IOHandler.
      6. Iterator refinements:
        1. DB_select_iterator::operator*() now returns a const DataObj & to make that operation truly read-only.
        2. All output iterators now use proxies to emulate *it = value to enforce their write-only quality.
        3. Also fixed prefix/postix implementation for operator++() on all iterators.
      7. Enhanced DBConnection class to use ODBC connection pooling.
      8. Added Julian date support through the jtime_c class.
  5. Notes for Linux.
    1. The MySQL ODBC driver version 2.50.36-1 on Linux does not work correctly with SQLPrepare(). Current workaround involves calling SQLExecDirect() rather than SQLPrepare(). To compile with this workaround define the symbol MYODBC_BUG as described in the makefile. (Another alternative is to download the source for MyODBC and re-compile. On the test machine we used this also seemed to fix the problem.)
    2. MySQL 3.23.33 does not support COMMIT or ROLLBACK. Therefore the "range transaction" examples will not work under this version MySQL.
    3. When you run the executable for the first time under unixODBC you may get a message like "error while loading shared libraries: libodbc.so.1: cannot open shared object file: No such file or directory". The problem in this case is not having your environment variables set up correctly for unixODBC.

      From: "Nick Gorham" <nick@lurcher.org>
      To: <cjoy@houston.rr.com>
      Subject: unixODBC


      > Hi,
      >
      > Your problem is not finding the lib at compile time, but at run time,
      > either add /usr/local/lib to LD_LIBRARY_PATH
      >
      > LD_LIBRARY_PATH=$LD_LIBRARY_PATH:/usr/local/lib
      > export LD_LIBRARY_PATH
      >
      > (the above assumes linux, if some other OS, it's much the same, mail me
      > if you can't find the variable)
      >
      > Or in linux, as root you can add /usr/local/lib to /etc/ld.so.conf, and
      > then run ldconfig (often in /sbin/ldconfig), to add it to all users lib
      > search paths.