readme

一个可以替代windows ODBC驱动程序管理器的通用ODBC数据库引擎

#
#  README
#
#  (C) 1995-2001 OpenLink Software Inc.
#
#  The iODBC driver manager.
#
#  This library is free software; you can redistribute it and/or
#  modify it under the terms of the GNU Library General Public
#  License as published by the Free Software Foundation; either
#  version 2 of the License, or (at your option) any later version.
#
#  This library is distributed in the hope that it will be useful,
#  but WITHOUT ANY WARRANTY; without even the implied warranty of
#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
#  Library General Public License for more details.
#
#  You should have received a copy of the GNU Library General Public
#  License along with this library; if not, write to the Free
#  Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.


iODBC release
Copyright 1995-2001 OpenLink Software and Ke Jin
May be distributed under LGPL or BSD license


1. Introduction

   Welcome to the iODBC driver manager maintained by OpenLink Software
   (http://www.openlinksw.com) This kit will provide you with everything
   you need in order to develop ODBC compliant applications under Unix
   without having to pay royalties to other parties.

   This kit consists of a number of parts:

   o  The iODBC driver manager. This is a complete implementation of
      an ODBC driver manager, released under either the GNU Library
      General Public License or the BSD License. We fully comply with
      these licenses by giving you this product in source form (as well
      as the binary form). You can download the latest version of the
      driver manager from http://www.iodbc.org/

   o  A simple example, odbctest.c, which gives you a command-line
      interface to SQL. You can fit this to your purposes, but at the very
      least this is useful for verification of your ODBC installation.
 
   You can use either part stand-alone, if you wish.
 
   An ODBC driver is still needed to affect your connection
   architecture. You may build a driver with the iODBC components or
   obtain an ODBC driver from a commercial vendor. OpenLink Software
   produces cross-platform commercial drivers as well as maintaining
   the iODBC distribution. Free, non-expiring copies may be obtained
   via download at http://www.openlinksw.com Any ODBC-compliant drivers
   will work with the iODBC Driver Manager.



2. Installation of run-time distribution

   You probably already unpacked this distribution. The next step is
   to make sure that your applications can find all the dynamic link
   libraries. Depending on your system's implementation of dynamic link
   libraries, you have a number of options:

   o  Install the libraries in a directory that is searched by your
      linker by default. Typical locations are /usr/lib and
      /usr/local/lib.

   o  Install the libraries in some other place, and make sure that the
      environment variable your dynamic linker uses to find extra
      locations for dynamic link libraries. Most systems use the
      environment variable LD_LIBRARY_PATH to this end. Exceptions are
      AIX which uses LIBPATH and HP/UX which uses SHLIB_PATH.
 
      If your system has a C compiler, you can verify the installation
      by compiling the odbctest program. Otherwise, you may have ODBC
      applications installed on your system which you can use.
 

 
3. Configuration of run-time distribution
 
   The iODBC driver manager looks for a file ~/.odbc.ini, where the
   tilde stands for the user's home directory. This file only contains a
   default section where you can select which driver library to use. Copy
   the odbc.ini file from the examples directory to ~/.odbc.ini and make
   sure the right path and filename is used for your installation.
 
   A data source is a section (enclosed in square parenthesis), and
   the attributes for a data source are given within this section.
   The most important attribute to iODBC for each datasource is the Driver
   attribute. This must point to the shared library for the ODBC driver
   associated with the data source.
 
   As example, the OpenLink ODBC drivers have a number of attributes
   which can be set for a data source. Here is a description (with ODBC
   connect string tags between parenthesis):

     Host
        The hostname where the database resides (HOST).

     ServerType
        The type of server (see oplrqb.ini on the server, SVT).

     ServerOptions
        Server-specific extra options. See OpenLink server documentation
        for agents which can use this.

     Database
        The database to use (DATABASE).

     Options
        Connect options for the database (OPTIONS).

     UserName
        The name of the user (a password cannot be specified in the
        UDBCINI file, UID/PWD).

     ReadOnly
        A Yes/No value in order to make the connection read-only
        (READONLY=Y/N).

     FetchBufferSize
        The number of records that are transferred in a single call to
        the server. Default is 5; maximum is 99, minimum is 1
        (FBS=value).

     Protocol
        The protocol to use. Leave set to ``TCP'' for this release.


   Apart from these data source-specific settings, you may add a section
   called [Communications], which you may use to tune our driver further:

     ReceiveTimeout
        The time the client application will wait for the database agent
        to finish the request (default is 60 seconds).

     BrokerTimeout
        The time the client application will wait for the request broker
        to accept of reject a database connection (default is 30
        seconds).

     SendSize
        RPC send buffer size. A value of 0 (the default) will cause the
        application to use system-dependent defaults.

     ReceiveSize
        RPC receive buffer size. A value of 0 (the default) will cause
        the application to use system-dependent defaults.

     DebugFile
        If set, the name of a file to which debugging output from the
        driver should be directed.



4. Contribution of changes, patches and updates.

   While not mandated by the BSD license, any patches you make to
   the iODBC may be contributed back into the iODBC project at
   your discretion. Contributions will benefit the Open Source and
   Data Access community as a whole. Submissions may be made at
   http://www.iodbc.org.



5. iODBC driver manager platform availability

    iODBC driver manager has been ported to following Unix platforms: 

	SunOS		4.1.x		Sun Sparc
	HP/UX		9.x, 10.x	HP9000 s700/s800
	HP/UX		9.x 		HP9000 s300/s400		
	IBM AIX		3.x, 4.x 	IBM RS6000, PowerPC
	Sun Solaris	2.x		Sun Sparc, PCx86
	SGI Irix SVR4	5.x, 6.x	IP12 MIPS, IP22 MIPS
	NCR SVR4 	3.x		NCR 3435
	UnixWare SVR4.2 1.x, 2.x	x86
	DEC Unix(OSF/1)	3.x, 4.x	DEC Alpha
	FreeBSD		2.x		x86
	BSDI BSD/OS 	2.x		?
	Linux ELF 	1.2.x, 1.3.x	x86
	SCO OpenServer 	5.x 		x86
	Max/OS SVR4	1.x		Concurrent Maxion 9200 MP
	DG/UX		5.x		Aviion
	OpenVMS		6.x		DEC Alpha
	Windows NT	4.x		x86
	
    
    As the iODBC driver manager uses autoconf/automake/libtool it should
    be portable to most modern UNIX platforms out of the box. However if
    you do need to make changes to the code or the configuration files,
    we would appreciate you share your changes with the rest of the
    internet community by mailing your patches to [e-mail]
    so we can include them for the next build

    Porting of iODBC driver manager to some non-UNIX operating systems
    such as Windows family(3.x, 95, NT), OS/2 and Mac is supported but has
    not been compiled and tested recently. Of cause, you need to supply
    a make/build file and a short LibMain for creating the iodbc.dll.



6. How to build iODBC driver manager:

    step 1. Run configure to adjust to target platform
    step 2. Run make
    step 3. Run make install
   
    Here is an example:

   	$ ./configure --prefix=/usr/local --with-iodbc-inidir=/etc
	...
	...
	...
	$ make
	...
	...
	...
	$ su
	# make install
	...
	...
	...

    The configure program will examine your system for various compiler
    flags, system options etc. In some cases extra flags need to be
    added for the C compiler to work properly.

    E.g. on HP systems you may need:

	$ CFLAGS="-Ae -O" ./configure --prefix=/usr/local ..........


    Note that the path of the system wide odbc.ini file is calculated as 
    follows (based on flags to ./configure):

   	no --prefix			default is /usr/local/etc/odbc.ini 
	--prefix=/usr			/etc/odbc.ini
	--prefix=/xxx/yyy		/xxx/yyy/etc/odbc.ini
	--sysconfdir=/xxx/yyy		/xxx/yyy/odbc.ini
	--with-iodbc-inidir=/xxx/yyy	/xxx/yyy/odbc.ini



7. odbc.ini

    Driver manager and drivers use odbc.ini file or connection string
    when establishing a data source connection. On Windows, odbc.ini is
    located in Windows directory. 
   
    On UNIX, the iODBC driver manager looks for the odbc.ini file in the
    following sequence:

	1. check environment variable ODBCINI 

	2. check $HOME/.odbc.ini

	3. check home in /etc/passwd and try .odbc.ini in there

	4. system wide odbc.ini (settable at configuration time)


    Item 1 is the easiest as most drivers will also look at this variable.



    The format of odbc.ini( or ~/.odbc.ini ) is defined as:

	odbc.ini	  ::= data_source_list

	data_source_list  ::= /* empty */
			   | data_source '\n' data_source_list

	data_source	  ::= '[' data_source_name ']' '\n' data_source_desc

	data_source_name  ::= 'default' | [A-Za-z]*[A-Za-z0-9_]*

	data_source_desc  ::= /* empty */
			   | attrib_desc '\n' data_source_desc

	addrib_desc	  ::= Attrib '=' attrib_value

	Attrib		  ::= 'Driver' | 'PID' | 'UID' | driver_def_attrib

	driver_def_attrib ::= [A-Za-z]*[A-Za-z0-9_]*



    An example of an odbc.ini file:

	;
	;  odbc.ini
	;
	[ODBC Data Sources]
	Myodbc		= Myodbc
	Sample		= OpenLink Generic ODBC Driver
	Virtuoso	= Virtuoso

	[Sample]
	Driver          = /usr/local/openlink/lib/oplodbc.so.1
	Description     = Sample OpenLink DSN
	Host            = localhost
	UserName        = openlink
	Password        = xxxx
	ServerType      = Oracle 8
	Database        = 
	FetchBufferSize = 99
	ReadOnly        = no
	TraceFile       = /tmp/odbc.trace
	Trace           = 1

	[Virtuoso]
	Driver		= /usr/local/virtuoso/lib/virtodbc.so.1
	Address		= localhost:1112
	Database	= Demo

	[Myodbc]
	Driver 		= /home/patrick/src/iODBC/new/myodbc/myodbc.so
	HOST   		= localhost

	[Default]
	Driver 		= /usr/local/openlink/lib/oplodbc.so.1



8. Tracing

    iODBC driver manager traces driver's ODBC call invoked by the driver
    manager. Default tracing file is ./odbc.log. Tracing option (i.e.
    on/off or optional tracing file name) can be set in odbc.ini file
    (under a data source section) as:

	TraceFile = <optional_trace_file>
	Trace = ON | On | on | 1 | OFF | Off | off | 0

    If <optional_trace_file> is stderr or stdout, i.e.
   
        TraceFile = stderr 
   
    or

	TraceFile = stdout

    the tracing message will go to the terminal screen (if it is available).

    iODBC driver manager allows one to tune on/off tracing on selected
    connection(s). Different connections can share one or use different
    tracing file(s). ODBC calls on connections without tuning tracing
    on will not be traced.



9. Further Information Sources:

   http://www.iodbc.org  
	iODBC project home page.  
	Binaries, source, WebCVS, and Discussion Forum.

   http://www.openlinksw.com  
	OpenLink Software.  
	Free non-expiring trials and support for OpenLink's ODBC drivers.

   http://www.microsoft.com/data/odbc/ 
	Microsoft's ODBC pages.