root/trunk/sdbo/odbc.d

/********************************************************
 *                                                      *
 * Copyright (c) 2004 Wolfgang Borgsmüller (wb@sapo.pt) *
 *                                                      *
 * Usage of the works is permitted provided that this   *
 * instrument is retained with the works, so that any   *
 * entity that uses the works is notified of this       *
 * instrument.                                          *
 *                                                      *
 * DISCLAIMER: THE WORKS ARE WITHOUT WARRANTY.          *
 *                                                      *
 * [2004, Fair License: rhid.com/fair]                  *
 ********************************************************/

/*! \if never
*/
 
module sdbo.odbc;


import sdbo.odbc_env;
import sdbo.odbc_dbc;
import sdbo.odbc_stmt;
import sdbo.odbc_etc;

version(linux) {
    version = bundled_headers;
}

version(bundled_headers) {
    import sdbo._odbc_headers.sql;
    import sdbo._odbc_headers.sqlext;
    import sdbo._odbc_headers.sqltypes;
    version(Windows)
        import sdbo._odbc_headers.odbc32dll;
    
} else {
    import std.c.windows.sql;
    import std.c.windows.sqlext;
    import std.c.windows.sqltypes;
    import std.c.windows.odbc32dll;
}

public alias sdbo.odbc_env.OdbcEnvironment   OdbcEnvironment;
public alias sdbo.odbc_dbc.OdbcConnection    OdbcConnection;
public alias sdbo.odbc_stmt.SqlResult        SqlResult;
public alias sdbo.odbc_etc.ColumnSpec        ColumnSpec;
public alias sdbo.odbc_etc.SqlException      SqlException;
public alias sdbo.odbc_etc.OdbcMessage       OdbcMessage;


/*! \brief Shortcut for faster typing
*/
public alias OdbcEnvironment DBEnv;

/*! \brief Shortcut for faster typing
*/
public alias OdbcConnection  DBCon;

/*! \endif
*/

 
 
/*! \mainpage
 *
 * \section intro_sec Introduction
 *
 * The sdbo library is a set of helper classes for use with ODBC database drivers. Runs on Windows and Linux platforms.
 
 \subsection needodbc What can I use this library for?
 
 You can use it for any database driven application. First of all, you need to decide 
 if you want to use ODBC for your application. There are many articles about this,
 and lots of discussion going on. The main argument is portability: An application that 
 talks to the odbc driver manager can talk to every databases with an odbc driver.
 An application that talks to a specific database's native API will need 
 a rewrite to talk to another database.
 
 So, if you decide to use ODBC, this package might be interesting for you if you are familiar with SQl but not with ODBC,
 and you just want to connect to a database and execute query statements, without caring about
 odbc handles, data types, and API calls.
 
 On the other hand, if you need to access the raw odbc api you can still use the classes to hide away
 bulk operations:
 
 <pre>
 SqlResult r = (new OdbcConnection).connect("someserver").execDirect("select something from somewhere");
 HSTMT hstmt = r.handle();
 </pre>
 
 
 *
 * 
 * \subsection examples_sec Examples
 
 This is the Hello world example for sdbo:

 \include test0.d
    
More \ref examples ...

\section problems Problems

- This is a 0.1 alpha. Use at your own risk. Don't blame me for nothing.
- Cleanup: Handles and memory malloc'd for column bindings are free'd in the
  class destructors. Needs more testing.
- Not enough documentation; author (that's me:) not a native english speaker.

\section install Installation


\subsection req Requirements:


Version Windows
- odbc32.dll required (may also work with another driver manager).

Version Linux
- ODBC Driver Manager (I am testing with iODBC, http://www.iodbc.org)

All Versions
- D Language compiler http://www.digitalmars.com/d/
- ODBC Drivers. You need MySQL's MyODBC driver to run the samples in the linux version: 
  http://www.mysql.com/products/connector/odbc/. If you want to run the MySQL samples in the windows version
  get the MyODBC windows version and change the samples/test*.d files to fit.

  
\subsection odbchead ODBC Headers

- This library requires MKoD's ODBC32.DLL Win32 APIs converted for D. 
Get it here: http://spottedtiger.tripod.com/D_Language/D_Support_Projects_XP.html

- std.c.windows.sql;
- std.c.windows.sqlext;
- std.c.windows.sqltypes;
- std.c.windows.odbc32dll;

Actually I had to do some modifications in the odbc headers for sdbo.lib and libsdbo.a to compile,
and MKoD's declaration files are not finished yet, so I bundled a copy of them that
works with this project. If the samples wonŽt compile, 
use -version=bundled_headers which causes the std.c.windows.* modules to be ignored 
and the bundled headers to be used. The bundled headers are going to disappear as soon 
as the MKoD headers are in a stable release.

The linux version always compiles with the bundled headers.

\subsection inst Install:

All Versions
- Install the sdbo directory in your include path.

Version Windows
- Copy sdbo.lib into your library path.

Version Linux
- Copy libsdbo.a into your library path.


\subsection cmp Compile test:

Version Windows

- On a command line, do:
<pre>
ECHO import sdbo.odbc; void main() { (new OdbcEnvironment).connect("foobar"); } > odbc_test.d
dmd odbc_test.d sdbo.lib
odbc_test
</pre>
- If that won't compile, use 
<pre>
dmd -version=bundled_headers odbc_test.d sdbo.lib
odbc_test
</pre>

Version Linux

- On a command line, do:
<pre>
echo "import sdbo.odbc; void main() { (new OdbcEnvironment).connect(\"foobar\"); }" > odbc_test.d
dmd -c odbc_test.d [-I/path/to/simple]
gcc -o odbc_test odbc_test.o -lsdbo -lphobos -lpthread -lm -lodbc
</pre>

- Or
<pre>
dmd -c odbc_test.d [-I/path/to/simple]
gcc -o odbc_test odbc_test.o /path/to/libodbc.a -lphobos -lpthread -lm -lodbc
</pre>

- "-lphobos -lpthread -lm" are the libraries dmd would have passed to gcc if not called with -c
- "-lodbc" is the odbc driver manager. The package is being tested for the iODBC manager.
- Link the sdbo library before the phobos library.


\subsection versions Versions:

The version of this package is 0.1. 

0.1 just means it is not finished yet.
The package release is a zip file in the project's svn at dsource.org.
The zip is called "sdbo-0.1.*.zip, being * an incremental number idicating changes to the 0.1 package. 
I am trying to maintain the zip file synchronized with the trunk.
Compare the last digit of the file you downloaded and the file available here:
http://svn.dsource.org/svn/projects/sdbo/downloads/ 
If they differ, your package is not up to date.

Starting from 0.1.6, there is now a package sdbo-0.1.*.tar.gz. The content is identical.


\section todo Todo:

- Finish the existing classes and expose more funcionality like parameter bound query execution, etc.
  At this time, you have to use the handles to do that.
  
- If you are using or testing this set of classes, I would be glad to hear your suggestions.
  Use the project forum at http://dsource.org - suggestions, criticism, anything.

\section links Links:

- This project is hosted at http://dsource.org
 *
 */
 
/*!
 \page examples Examples
 
 \section test1 test1.d
 
 \include test1.d
  
 \section test2 test2.d
 
 \include test2.d
 
 \section test3 test3.d
 
 \include test3.d
 
 \section test4 test4.d
 
 \include test4.d
 
 \section test5 test5.d
 
 \include test5.d
 
 
 */