ruby-oci8 1.0.2

data/Makefile

@@ -0,0 +1,51 @@
+VERSION = `cat VERSION`
+RUBY = ruby
+GEM = gem
+CONFIG_OPT = 
+
+all: build
+
+build: config.save setup
+
+config.save: lib/oci8.rb.in
+	$(RUBY) setup.rb config $(CONFIG_OPT)
+
+setup:
+	$(RUBY) setup.rb setup
+
+check: build
+	$(RUBY) setup.rb test
+
+clean:
+	$(RUBY) setup.rb clean
+
+distclean:
+	$(RUBY) setup.rb distclean
+
+install:
+	$(RUBY) setup.rb install
+
+site-install:
+	$(RUBY) setup.rb install
+
+gem:
+	$(GEM) build ruby-oci8.gemspec
+
+binary_gem: build
+	$(GEM) build ruby-oci8.gemspec -- current
+
+# internal use only
+dist: ruby-oci8.spec
+	-rm -rf ruby-oci8-$(VERSION)
+	mkdir ruby-oci8-$(VERSION)
+	tar cf - `cat dist-files` | (cd ruby-oci8-$(VERSION); tar xf - )
+	tar cfz ruby-oci8-$(VERSION).tar.gz ruby-oci8-$(VERSION)
+
+dist-check: dist
+	cd ruby-oci8-$(VERSION) && $(MAKE) RUBY="$(RUBY)"
+	cd ruby-oci8-$(VERSION) && $(MAKE) RUBY="$(RUBY)" check
+	cd ruby-oci8-$(VERSION)/src && $(MAKE) RUBY="$(RUBY)" sitearchdir=../work sitelibdir=../work site-install
+	cd ruby-oci8-$(VERSION)/test && $(RUBY) -I../work -I../support test_all.rb
+
+ruby-oci8.spec: ruby-oci8.spec.in
+	$(RUBY) -rerb -e "open('ruby-oci8.spec', 'w').write(ERB.new(open('ruby-oci8.spec.in').read).result)"

data/NEWS

@@ -0,0 +1,322 @@
+1.0.2:
+
+1. add a gemspec file.
+   (Thanks to Jesse Hu)
+
+   To make a pure ruby gems package:
+     gem build ruby-oci8.gemspec
+
+   To make a binary gems package:
+     gem build ruby-oci8.gemspec -- current
+
+
+2. [BUG FIX] fix a segv bug in gc mark.
+   (Thanks to authorNari)
+
+1.0.1:
+
+1. [SPEC CHANGE] OCI8#exec and OCI8::Cursor#exec's return value is changed
+   for statement except select, insert, update and delete statement.
+
+   It had been true. But now it is the number of rows processed for all
+   non-select statements.
+
+   For example:
+
+     # 1.0.0 or before
+     conn = OCI8.new('user/pass')
+     conn.exec('rename FOO_TABLE to BAR_TABLE') # => true
+
+     # 1.0.1
+     conn = OCI8.new('user/pass')
+     conn.exec('rename FOO_TABLE to BAR_TABLE') # => 0
+
+2. fix a bug that OraDate.new made a core dump on x86_64 linux.
+  (reported by Alun Eyre)
+
+3. fix OCI8#non_blocking = false problem.
+  Once the connection became non-bocking mode, it could
+  not be reset to blocking mode. Now it can be reset.
+  (reported by Cagdas Gerede)
+
+4. support cursors in a result set.
+   (contributed by Randy Gordon)
+
+   For example:
+      conn = OCI8.new('ruby/oci8')
+      sql = 'SELECT CURSOR(SELECT * FROM foo where foo.c1 = bar.c1 ) FROM bar'
+      conn.exec(sql) do |row|
+        cursor_in_result_set = row[0]
+        cursor_in_result_set.fetch do |row|
+          puts row.join(',')
+        end
+      end
+
+5. fix oraconf.rb for official x86_64 linux rpms.
+   (contributed by Pat)
+
+1.0.0:
+
+1. fix a BUG when binding a Bignum. This bug was added in
+   ruby-oci8 1.0.0-rc2. (reported by Daniel Berger)
+
+2. add OCI8#describe_table(table_name), OCI8::Cursor#column_metadata,
+   OCI8::Metadata::Table, OCI8::Metadata::View and OCI8::Metadata::Column.
+
+   table information:
+     con = OCI8.new('username/password')
+     table_info = con.describe_table('table_name') #=> OCI8::Metadata::Table
+     table_info.columns #=> an array of OCI8::Metadata::Column.
+
+   query information:
+     con = OCI8.new('username/password')
+     csr = con.exec('select * from table_name')
+     csr.column_metadata #=> an array of OCI8::Metadata::Column.
+
+5. add OCI8::BindType::BinaryDouble if oci8lib.so is compiled for
+   Oracle 10g client. You can fetch exactly same values in Oracle.
+
+   You could fetch the values in previous version by adding the
+   following line.
+
+     OCI8::BindType::Mapping[101] = OCI8::BindType::Float
+     (This is default in ruby-oci8 1.0.0-rc2.)
+
+   But a fetched value may not be exactly same with the value in
+   Oracle. That's because OCI8::BindType::Float's network
+   representation is Oracle NUMBER data type. A BINARY_DOUBLE
+   value in Oracle become NUMBER on the network and is converted
+   to Float on the client side. It makes a bit difference by
+   round-off error.
+
+   In addition, Oracle NUMBER doesn't have NaN, +Infinity and -Infinity.
+   You cannot fetch the values by older versions.
+
+   Note: When you bind a Float value, it is bound by
+   OCI8::BindType::Float by default. You have two ways to bind
+   it by OCI8::BindType::BinaryDouble.
+
+   a. bind explicitly.
+
+      con = OCI8.new('ruby/oci8')
+      csr = con.parse('insert into table_name values (:1)')
+      csr.bind_param(1, 10.5, OCI8::SQLT_IBDOUBLE)
+      csr.exec
+
+   b. change the default behaviour if and only if you are sure that
+      the Oracle client version and Oracle server version are both
+      10g or upper.
+
+      # use OCI8::BindType::BinaryDouble for ruby's Float values.
+      OCI8::BindType::Mapping[Float] = OCI8::BindType::BinaryDouble
+      con = OCI8.new('ruby/oci8')
+      csr = con.exec('insert into table_name values (:1)', 10.5)
+
+4. OCI8::Cursor#fetch_hash accepts a block as a iterator.
+
+5. [dbi] support external OS authentication.
+   (contributed by Dan Fitch)
+
+     dbh = DBI.connect('dbi:OCI8', nil, nil)
+
+6. [dbi] add DatabaseHandle#columns and improve StatementHandle#column_info
+   (suggested by Venkat Pa)
+
+7. [bug] fix a problem when binding ''(empty string) via dbi.
+
+1.0.0-rc3:
+
+1. support external OS authentication.
+   (suggested by Dan Fitch)
+
+      conn = OCI8.new('/')
+   or
+      conn = OCI8.new(nil, nil)
+
+2. incompatible change on connect string.
+
+   You need to pass only one argument to OCI8.new to parse the
+   first argument as a SQL*Plus-like connect string.
+
+   For example, OCI8.new('scott/tiger', nil) was parsed as the
+   username is 'scott' and the password is 'tiger' in 1.0.0-rc2.
+   But from now on, it is treated as the username is 'scott/tiger'
+   and the password is nil because it has two arguments. You need
+   to use OCI8.new('scott/tiger') instead.
+
+3. fix NCLOB support on Oracle 9i.
+   (reported by Matthew Noble)
+
+   1.0.0-rc2's NCLOB support worked on Oracle 10g only.
+
+4. fix a problem to compile with a third-party x86_64 rpm package.
+   (contributed by Jeff Abbott)
+
+   The x86_64 source rpm packages are found on the following URLs.
+     http://freshrpms.net/docs/oracle/
+     http://remi.collet.free.fr/index.php?2007/01/22/279-oracle-instant-client-10203-on-x86_64
+
+5. '--with-instant-client' option become obsolete and is ignored.
+
+   Use LD_LIBRARY_PATH(Linux), PATH(Windows), etc. to indicate
+   the instant client's location.
+
+6. fix some other minor problems.
+
+1.0.0-rc2:
+
+1. support SQL*Plus-like connect strings.
+   (contributed by Oracle Corporation)
+
+     require 'oci8'
+     conn = OCI8.new('username/password@tns_name')
+     # instead of OCI8.new('username', 'password', 'tns_name')
+
+2. Add a rpm spec file.
+   (contributed by Brian Candler)
+
+     rpmbuild -tb ruby-oci8-x.y.z.tar.gz
+
+     /usr/src/redhat/RPMS/i386/ruby-oci8-x.y.z-1.i386.rpm
+
+3. support BINARY_FLOAT and BINADY_DOUBLE columns.
+   (This problem is reported by Duncan McCaffery.)
+
+4. support NCLOB columns.
+   (This problem is reported by Dmitry Zadvornykh.)
+
+     cursor = conn.exec('select nclob_column from nclob_table')
+     cursor.fetch # => [ instance of OCI8::NCLOB ]
+
+5. add new CLOB/NCLOB/BLOB insert method.
+   (This is available on Oracle 8.1.5 or later.)
+
+     cursor = conn.parse("INSERT INTO clob_table VALUES (:1)")
+     cursor.bind_param(1, OCI8::CLOB.new(conn, lob_data))
+     cursor.exec
+
+     cursor = conn.parse("INSERT INTO nclob_table VALUES (:1)")
+     cursor.exec(OCI8::NCLOB.new(conn, lob_data))
+
+     conn.exec("INSERT INTO blob_table VALUES (:1)",
+               OCI8::BLOB.new(conn, lob_data))
+
+   This is added to insert CLOB as a SDO_GEOMETRY's parameter
+   to solve a problem reported by Pete Schwamb.
+
+6. add an error location in C code to OCIException's backtrace.
+   This is for debug information.
+
+1.0.0-rc1:
+
+1. support BFILE columns.
+
+2. check whether Full Client or Instant Client by checking load library
+   path on configuration to compile.
+
+3. raise an OCIError with "OCI Library Initialization Error" message if
+   no message can not be retrieved when requiring oci8lib.so.
+
+4. raise "OCI Library Initialization Error" when first connect instead
+   of requiring oci8lib.so. This is a workaround to prevent Rails from
+   being stopped on invalid Oracle environment.
+
+0.1.16:
+
+1. Add LONG and LONG RAW support longer than 65535 bytes.
+
+   Use OCI8#long_read_len and OCI8#long_read_len= to set max long length.
+   The default value is 65535.
+
+2. OraDate and OraNumber can be serialized by Marshal now.
+
+3. OraDate and OraNumber can be serialized by YAML now.
+
+4. Fix bug on OraDate#dup, OraDate#clone, OraNumber#dup and OraNumber#clone.
+   (reported by Daniel Berger.)
+
+   These methods had not duplicated their contents, which caused segmentation
+   fault. Now they duplicate their contents also by adding initialize_copy
+   method.
+
+5. Add a workaround code on cygwin environment variables problem.
+
+   Cygwin manages environment variables by itself. They don't synchroize
+   with Win32's ones. When setting Oracle's environment variables, they
+   are set to cygwin's environment. But Oracle client library read
+   Win32's. Now Oracle-related variables are forcedly set to Win32.
+
+6. Accept all Fixnum values when binding as a Fixnum on 64-bit ruby.
+
+   A Fixnum is a 31-bit integer on 32-bit ruby, 63-bit integer on 64-bit
+   ruby. But it had been bound to 32-bit integer on ruby-oci8. Now it is
+   bound to integer whose bit width is same with ruby.
+
+0.1.15:
+
+1. no new features. :-<
+
+2. suppress memory usage when binding a placeholder which is already bound.
+
+     require 'oci8'
+     conn = OCI8.new('ruby', 'oci8')
+     cursor = conn.parse('select * from foo where key = :key')
+     0.upto(10000) do |key|
+       # bind values had not freed until cursor.close.
+       # Now they are freed when GC is run.
+       cursor.bind_param('key', key)
+       cursor.exec
+       .... fetch ....
+     end
+
+3. fix potentially segmentation fault while exiting process.
+   When exiting process, ruby's objects are GCed with unexpectable
+   order. If an OCIEnv instance was GCed in prior to OCIRowid objects,
+   it caused segmentation fault. 
+
+4. add a workaround code when setting $0.
+   The following code made enviroment variables empty strings on
+   Unix when using ruby 1.8.4, ruby-oci8 0.1.14 and Oracle 10.1.0.
+   (Oracle 10.2.0 and ruby 1.8.2 doesn't have this problem.)
+
+     require 'oci8'
+     ENV['HOME'] # --> valid value
+     $0 = 'foo'
+     ENV['HOME'] # --> ''
+
+5. fix registry search path on compilation.
+   (OracleXE Windows version)
+
+0.1.14:
+
+1. add OCI8#prefetch_rows=.
+    
+   This specifies the number of rows in a single round trip.
+   See: http://www.easysoft.com/products/data_access/odbc_oracle_driver/performance_tuning_guide.html#multiple_rows 
+   In addition, setting zero may become a workaround
+   of some Oracle internal problems.
+   The default value is one.
+
+2. fix bug when binding a Bignum.
+3. (low-level API) add attrSet(OCI_ATTR_DESC_PUBLIC, -1).
+4. (low-level API) add a constant OCI_PTYPE_UNK.
+5. (internal) use OCIEnv.logon when no priviledge login.
+6. (internal) delete code to register malloc/realloc/free callbacks to OCI.
+
+0.1.13:
+
+1. fix a memory leak.
+   (fixed by Nathaniel Talbott.)
+
+   It is recommended to update to 0.1.13 if a program executes many
+   queries. That's bacause 0.1.12 cause 70-byte memory leak per a
+   query.
+
+2. ruby's DateTime support is added.
+   (suggested by Daniel Berger.)
+
+   To fetch Oracle's DATE datatype as ruby's DateTime by default, add
+   the following code to your program.
+
+     OCI8::BindType::Mapping[OCI8::SQLT_DAT] = OCI8::BindType::DateTime
+     OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP] = OCI8::BindType::DateTime

data/README

@@ -0,0 +1,415 @@
+= How to make
+
+== Oracle Full Client (not Oracle Instant Client)
+
+1. check the followings:
+   - ruby and make (or nmake on MSVC) are in the environment variable PATH.
+   - sqlplus runs correctly.
+
+2. check library search path.
+
+   If sqlplus runs correctly, the environments variables are okay in general.
+   But if Oracle is 64-bit and ruby is 32-bit, make sure $ORACLE_HOME/lib32
+   in 32-bit library search path. (LD_LIBRARY_PATH_32 on Solaris, SHLIB_PATH
+   on HP-UX PA-RISC.)
+
+3. make and install
+   gzip -dc ruby-oci8-0.1.xx.tar.gz | tar xvf -
+   cd ruby-oci8-0.1.xx
+   make          # or nmake on MSVC.
+   make install
+
+== Oracle Instant Client
+
+1. donwload "Instant Client Package - Basic" and "Instant Client Package - SDK".
+
+   OTN (Oracle Technology Network):
+     URL:http://otn.oracle.com/
+   Instant Client Donload Page:
+     http://www.oracle.com/technology/software/tech/oci/instantclient/index.html
+
+   note:
+     download 32-bit packages for 32-bit ruby even though your OS is 64-bit.
+
+2. install Oracle Instant Client Packages.
+
+   zip packages:
+
+     mkdir /opt
+     mkdir /opt/oracle
+     cd /opt/oracle
+     unzip path/to/instantclient-basic-XXXX-10.1.0.X.zip
+     unzip path/to/instantclient-sdk-XXXX-10.1.0.X.zip
+
+   rpm packages:
+
+     rpm -i path/to/oracle-instantclient-basic-10.1.0.X-X.XXX.rpm
+     rpm -i path/to/oracle-instantclient-devel-10.1.0.X-X.XXX.rpm
+
+     note for Debian user:
+       convert rpm packages to deb packages by alien.
+         alien path/to/oracle-instantclient-basic-10.1.0.X-X.XXX.rpm
+         alien path/to/oracle-instantclient-devel-10.1.0.X-X.XXX.rpm
+         dpkg -i oracle-instantclient-basic_10.1.0.X-X_XXX.deb
+         dpkg -i oracle-instantclient-devel_10.1.0.X-X_XXX.deb
+
+3. check installed libraries. (UNIX zip packages only)
+
+   If /opt/oracle/instantclient10_1/libclntsh.so not found,
+   make a symbolic link.
+
+     cd /opt/oracle/instantclient10_1
+     ln -s libclntsh.so.10.1 libclntsh.so
+
+   note:
+     libclntsh.sl for HP-UX PA-RISC
+     libclntsh.dylib for Mac OS X
+
+4. set library search path.
+
+   Windows:
+     add c:\oracle\instantclient10_1 to PATH.
+
+   AIX:
+     add /opt/oracle/instantclient10_1 to LIBPATH.
+
+   HP-UX PA-RISC 32-bit ruby:
+     add /opt/oracle/instantclient10_1 to SHLIB_PATH.
+
+   SPARC/Solaris 32-bit ruby:
+     add /opt/oracle/instantclient10_1 to LD_LIBRARY_PATH_32.
+
+   SPARC/Solaris 64-bit ruby:
+     add /opt/oracle/instantclient10_1 to LD_LIBRARY_PATH_64.
+
+   Mac OS X:
+     add /opt/oracle/instantclient10_1 to DYLD_LIBRARY_PATH.
+
+   Others:
+     add /opt/oracle/instantclient10_1 to LD_LIBRARY_PATH.
+
+5. make and install.
+
+   zip packages:
+     gzip -dc ruby-oci8-0.1.xx.tar.gz | tar xvf -
+     cd ruby-oci8-0.1.xx
+     ruby setup.rb config -- --with-instant-client=/opt/oracle/instantclient10_1
+     make
+     make install
+
+   rpm packages:
+     gzip -dc ruby-oci8-0.1.xx.tar.gz | tar xvf -
+     cd ruby-oci8-0.1.xx
+     ruby setup.rb config -- --with-instant-client
+     make
+     make install
+
+== On compilation failure
+
+  Please report the following information to kubo@jiubao.org.
+
+  * last 100 lines of 'ext/oci8/mkmf.log'.
+  * the results of the following commands:
+      ruby --version
+      ruby -r rbconfig -e "p Config::CONFIG['host']"
+      ruby -r rbconfig -e "p Config::CONFIG['CC']"
+      ruby -r rbconfig -e "p Config::CONFIG['CFLAGS']"
+      ruby -r rbconfig -e "p Config::CONFIG['LDSHARED']"
+      ruby -r rbconfig -e "p Config::CONFIG['LDFLAGS']"
+      ruby -r rbconfig -e "p Config::CONFIG['DLDLAGS']"
+      ruby -r rbconfig -e "p Config::CONFIG['LIBS']"
+      ruby -r rbconfig -e "p Config::CONFIG['GNU_LD']"
+  * if you use gcc:
+      gcc --print-prog-name=ld
+      gcc --print-prog-name=as
+  * on platforms which can use both 32bit/64bit binaries:
+      file $ORACLE_HOME/bin/oracle  # Full Client only
+      file `which ruby`
+      echo $LD_LIBRARY_PATH
+      echo $LIBPATH              # AIX
+      echo $SHLIB_PATH           # HP-UX PA-RISC
+      echo $DYLD_LIBRARY_PATH    # Mac OS X
+      echo $LD_LIBRARY_PATH_32   # Solaris
+
+= How to run
+
+== Oracle Full Client (not Oracle Instant Client)
+
+1. set environmet variables.
+
+   The follwing environmet variables are required:
+
+     * ORACLE_HOME
+       UNIX only. This variable is set on registry on Windows.
+
+     * NLS_LANG
+       UNIX only. This variable is set on registry on Windows.
+
+     * library serach path
+
+       Windows:
+         add %ORACLE_HOME%\bin to PATH.
+
+       AIX:
+         add $ORACLE_HOME/lib to LIBPATH.
+
+       HP-UX PA-RISC 32-bit ruby:
+         add $ORACLE_HOME/lib32 to SHLIB_PATH.
+         If $ORACLE_HOME/lib32 doesn't exist, add $ORACLE_HOME/lib instead.
+
+       SPARC/Solaris 32-bit ruby:
+         add $ORACLE_HOME/lib32 to LD_LIBRARY_PATH_32.
+         If $ORACLE_HOME/lib32 doesn't exist, add $ORACLE_HOME/lib instead.
+
+       SPARC/Solaris 64-bit ruby:
+         add $ORACLE_HOME/lib to LD_LIBRARY_PATH_64.
+
+       Mac OS X:
+         add $ORACLE_HOME/lib to DYLD_LIBRARY_PATH.
+
+       Other 32-bit ruby:
+         add $ORACLE_HOME/lib32 to LD_LIBRARY_PATH.
+         If $ORACLE_HOME/lib32 doesn't exist, add $ORACLE_HOME/lib instead.
+
+       Other 64-bit ruby:
+         add $ORACLE_HOME/lib to LD_LIBRARY_PATH.
+
+   To connect the local database:
+
+     * ORACLE_SID
+
+2. enjoy.
+
+   sample one-liner:
+     ruby -r oci8 -e 'OCI8.new("scott", "tiger", nil).exec("select * from emp") do |r| puts r.join(","); end'
+
+== Oracle Instant Client
+
+1. set environmet variables.
+
+   The follwing environmet variables are required:
+
+     * NLS_LANG
+
+     * library serach path
+
+       Windows:
+         add %ORACLE_HOME%\bin to PATH.
+
+       AIX:
+         add $ORACLE_HOME/lib to LIBPATH.
+
+       HP-UX PA-RISC 32-bit ruby:
+         add $ORACLE_HOME/lib32 to SHLIB_PATH.
+         If $ORACLE_HOME/lib32 doesn't exist, add $ORACLE_HOME/lib instead.
+
+       SPARC/Solaris 32-bit ruby:
+         add $ORACLE_HOME/lib32 to LD_LIBRARY_PATH_32.
+         If $ORACLE_HOME/lib32 doesn't exist, add $ORACLE_HOME/lib instead.
+
+       SPARC/Solaris 64-bit ruby:
+         add $ORACLE_HOME/lib to LD_LIBRARY_PATH_64.
+
+       Mac OS X:
+         add $ORACLE_HOME/lib to DYLD_LIBRARY_PATH.
+
+       Other 32-bit ruby:
+         add $ORACLE_HOME/lib32 to LD_LIBRARY_PATH.
+         If $ORACLE_HOME/lib32 doesn't exist, add $ORACLE_HOME/lib instead.
+
+       Other 64-bit ruby:
+         add $ORACLE_HOME/lib to LD_LIBRARY_PATH.
+
+   ORACLE_HOME and TNS_ADMIN are optional:
+     see: http://www.oracle.com/technology/tech/oci/instantclient/ic-faq.html#A4428
+
+2. enjoy.
+
+   sample one-liner:
+     ruby -r oci8 -e 'OCI8.new("scott", "tiger", "//HOSTNAME_OR_IP/SID").exec("select * from emp") do |r| puts r.join(","); end'
+
+== Platform specific topics
+
+=== HP-UX
+
+1. I was reported that it doesn't work with 64-bit ruby. :-<
+
+2. link the libraries which contain thread local storages to ruby itself.
+
+   ruby 1.8.1 or later:
+     gzip -dc ruby-1.8.2.tar.gz | tar xvf -
+     cd ruby-1.8.2
+     ./configure --enable-pthread
+     vi Makefile     # add "-lcl" to LIBS manually.
+     make
+     make install
+
+   ruby 1.8.0 or 1.6.x:
+     gzip -dc ruby-1.x.x.tar.gz | tar xvf -
+     cd ruby-1.x.x
+     ./configure
+     vi Makefile     # add "-lpthread -lcl" to LIBS manually.
+     make
+     make install
+
+   If you can't recompile ruby, LD_PRELOAD may solve the problem.
+
+     LD_PRELOAD=/usr/lib/libpthread.1:/usr/lib/libcl.2
+     export LD_PRELOAD
+
+=== Intel Mac
+
+Oracle intant client is still, when I write this, pcc.
+
+1. check whether the ruby is ppc bianry.
+
+     file `which ruby`
+
+   If it is universal bianry, use ditto to extract ppc binary.
+
+      http://blog.sven-tissot.de/daylist_html?year=2006&month=4&day=12
+
+   If it is i386 binary, compie it as ppc.
+
+2. fix compilation flags.
+
+      ruby -r rbconfig -e "p Config::CONFIG['CFLAGS']"
+      ruby -r rbconfig -e "p Config::CONFIG['DLDLAGS']"
+
+   If they have '-arch i386', delete it from:
+      /usr/lib/ruby/1.8/powerpc-darwin8.0/rbconfig.rb
+   or
+      /usr/lib/ruby/1.8/universal-darwin8.0/rbconfig.rb
+
+   If haven't '-arch ppc', add it.
+
+3. config, make and install
+
+     ruby setup.rb config -- --with-instant-client=/opt/oracle/instantclient10_1
+     make
+     make install
+
+4. rollback the changes in 2.
+
+***************************
+in progress.
+
+
+= How to run unit tests
+
+1. see "How to run"
+
+2. create user and tables on Oracle.
+
+   - connect to Oracle as system:
+
+      $ sqlplus system/<password_of_system>
+
+   - create user ruby:
+
+      SQL> CREATE USER ruby IDENTIFIED BY oci8;
+    or
+      SQL> CREATE USER ruby IDENTIFIED BY oci8
+         2 DEFAULT TABLESPACE users TEMPORARY TABLESPACE temp;
+
+   - grant the privilege to connect and execute.
+
+      SQL> GRANT connect, resource, create synonym TO ruby;
+
+   - If the Oracle version is 8i or later:
+
+      SQL> CREATE TABLE ruby.test_clob (filename VARCHAR2(40), content CLOB);
+
+   - connect to Oracle as sys
+
+      $ sqlplus 'sys/<password_of_sys> as sysdba'
+
+   - grant the privilege for the unittest of blocking-mode.
+
+      SQL> GRANT EXECUTE ON dbms_lock TO ruby;
+
+3. set $dbname in test/config.rb.
+
+   for instant client, or full client which connect the remote server.
+
+4. run.
+
+     $ make check
+   or
+     $ nmake check   (If your compiler is MS Visual C++.)
+
+
+= How to customize fetched datatypes.
+
+== OCI8::BindType::Mapping
+
+OCI8::BindType::Mapping is available to change the mapping of Oracle
+datatypes and ruby datatypes.
+
+Examples:
+  fetch a Timestamp value as a OraDate:
+    OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP] = OCI8::BindType::OraDate
+  fetch a Timestamp value as a String:
+    OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP] = OCI8::BindType::String
+
+Bind-types are:
+  OCI8::BindType::String
+  OCI8::BindType::RAW
+  OCI8::BindType::OraDate
+  OCI8::BindType::Time
+  OCI8::BindType::Date
+  OCI8::BindType::DateTime (ruby 1.8.0 or upper)
+  OCI8::BindType::Float
+  OCI8::BindType::Fixnum
+  OCI8::BindType::Integer
+  OCI8::BindType::OraNumber
+  OCI8::BindType::Number
+  OCI8::BindType::OCIRowid
+  OCI8::BindType::BLOB
+  OCI8::BindType::CLOB
+  OCI8::BindType::Cursor
+
+== Number datatype.
+
+OCI8::BindType::Number is a special bindtype. The actual bindtype
+depends on the precision and scale.
+  Fixnum or Integer for NUMBER(p, 0). (prec is positive).
+  Float for NUMBER(prec, scale). (prec is less then 15).
+  OraNumber for NUMBER(prec, scale). (prec equals or is greater then 15).
+
+If fetched value is defiend as NUMBER or calculated value, it is
+fetched as a Float by default. To customize this behavior, you can
+use OCI8::BindType::Mapping[:number_unknown_prec] and
+OCI8::BindType::Mapping[:number_no_prec_setting].
+
+Oracle 9.2.0.2 or earlier:
+  OCI8::BindType::Mapping[:number_unknown_prec] changes both behaviors.
+
+Oracle 9.2.0.3 or later:
+  OCI8::BindType::Mapping[:number_no_prec_setting] changes the former.
+  OCI8::BindType::Mapping[:number_unknown_prec] changes the latter.
+
+Examples:
+
+  CREATE TABLE tab1 (col1 NUMBER, col2 NUMBER(10));
+  SELECT col1 AS col FROM tab1:
+  SELECT col2 * 1.0 AS cal2 FROM tab1;
+  # col : NUMBER whose precision and scale are not defined explicitly.
+  # cal : calculated NUMBER value.
+
+  Oracle 9.2.0.2 or earlier:
+    OCI8::BindType::Mapping[:number_unknown_prec] = OCI8::BindType::Integer
+      ==> col is fetched as an Integer.
+          cal is fetched as an Integer.
+    :number_unknown_prec changes the both behaviors.
+
+  Oracle 9.2.0.3 or later:
+    OCI8::BindType::Mapping[:number_unknown_prec] = OCI8::BindType::Integer
+      ==> col is fetched as a Float.
+          cal is fetched as an Integer.
+    :number_unknown_prec changes the latter only.
+
+    OCI8::BindType::Mapping[:number_no_prec_setting] = OCI8::BindType::Integer
+      ==> col is fetched as an Integer.
+          cal is fetched as a Float.
+    :number_no_prec_setting changes the former only.