ODBC driver overview

We implement an ODBC 2.5 driver for Predator. 

Before developing an application using ODBC, you need to read this help file. The help files are under 
doc directory. I suggest you take a brief look at odbc.hlp file. A GUI sample code is under sample\querydemo

The basic architecture of ODBC is the following:

Application
----------------------------------------
ODBC driver manager
-------------------------------------------
Database specific ODBC driver
-------------------------------------------
Data source

The application first calls functions of the ODBC driver manager. The ODBC driver manager then 
calls functions in Predator driver. Then Predator driver contacts Predator server. The driver
has four kinds of handle: environment, connection, statement, and descriptor handle. Enviroment
handle defines the global context such as ODBC version, allocated connection handles. Connection
handle implements the connection with database. Statement handle is the abstraction of SQL statement.
Descriptor handle defines the meta information of a statement. 

DataSource is the abstraction of the database exposed to the application. A data souce is associated with an ODBC driver.
In order to access the predator database, user sould first install the predatore ODBC driver and
its associated data souce. To access data, application first connects to a data source. The driver manager first load
the corresponding driver for the data source (So, we don't need to explicitly load the driver), then all
request to the data source is executed by the driver.

Files included

This package includes the souce code and dll of Predator ODBC driver. 
We also provide a GUI sample application using the driver.

Source Files:
stub.cpp: All ODBC driver functions are implemented in this file.
handle.cpp: Implementation of four kinds of handle.
setup.c: Functions called by setup program.
error.cpp: A simplified version of errorInfo class.
record2.cpp: A simplified version of XxxRecord and XxxRecordSchema.
socket.cpp: socket.
dll.c: Functions called when the driver is loaded.

Installation guide

The driver is testdll.dll. It can be installed by the ODBC 2.5 setup program. 
All setup related files are under odbc\setup.

Step 1: You should first edit the odbc.inf file to add a data source. Now the sample odbc.inf file contains
a predator driver named Predator and a predator data source named merlin. You need to change the data
source name to the name of the machine where the predator server resides. Then you need to change the 
attributes of the data source, including server name and port number.

E.g. in odbc.inf: # is comment

[Predator]
..........
# This is the driver name for predator ODBC driver. 

[Predator-Keys] # This is the attributes of the driver, including data sources
....
CreateDSN=merlin
#Create a data souce with the name oslo. You should change oslo to the server name.

[oslo] # configuration of the data souce, change the name oslo to your server name.
Servername=merlin.cs.cornell.edu # Set the correct server name
Port=6005 # The port number of Predator server
....

Step 2:
Run the setup program under p:\odbc\setup. The driver file (testdll.dll) should be also copied to the setup
directory. Choose the Predator driver in the first screen. Then a window showing all installed data source
appears. You will find your data source showing up if you finish the first step correctly. If not, you need
to repeat the first step. Otherwise, simply click the close button and setup is finished.

Implemented functions

Following are functions already being implemented in our driver.

SQLSetEnvAttr ISO 92 Sets an environment attribute.
SQLGetEnvAttr ISO 92 Returns the value of an environment attribute.
SQLAllocHandle ISO 92 Obtains an environment, connection, statement, or descriptor handle.
SQLConnect Connects to a specific driver by data source name, user ID, and password. 
SQLGetInfo ISO 92 Returns information about a specific driver and data source.
SQLGetFunctions ISO 92 Returns supported driver functions. 
SQLSetStmtAttr ISO 92 Sets a statement attribute.
SQLGetStmtAttr ISO 92 Returns the value of a statement attribute.
SQLExecDirect ISO 92 Executes a statement.
SQLBindCol SQLBindCol binds application data buffers to columns in the result set.
SQLFetch ISO 92 Returns multiple result rows.
SQLDisconnect Closes the connection.
SQLFreeHandle Releases an environment, connection, statement, or descriptor handle. 
SQLGetDiagRec Retrieve error information.

4. Developing an applications using ODBC driver.

There is a GUI sample of application under odbc\bin32. The query.c file includes all function calls
for the driver. You may skip all those GUI stuffs in developing your own applications.

The basic steps of your applications should be:

1. SQLAllocHanle to allocate environment handle.
2. SQLSetEnvAttr to set the ODBC version.
3. SQLAllocHanlde to allocate connection handle.
4. SQLConnect to connect to the data source.
5. SQLAllocHanle to allocate statement handle.
6. SQLBindCol to define how to asscociate result columns to data buffers in applications.
7.SQLFetch to fetch rows in result until no more result is returned.
8. SQLFreeHandle to free statement handle
9. SQLDisconnect to disconnect from data source.
10. SQLFreeHanle to free connection handle.
11. If the application ends, free environment handle.

In case of error, you may call SQLGetDiagRec to retrieve error information returned from 
the Predator server.