ruby-oci8 2.1.0 → 2.1.1

data/README.md

@@ -0,0 +1,38 @@
+What is ruby-oci8
+=================
+
+Ruby-oci8 is a ruby interface for Oracle Database. The latest version
+is available for all Oracle versions after Oracle 9i including Oracle
+Instant Client.
+
+If you need to use Oracle 8, use ruby-oci8 2.0.6.
+
+As for Oracle7, use Oracle7 Module for Ruby by Yoshida Masato.
+
+What's new
+==========
+
+See {file:NEWS}.
+
+Sample one-liner
+================
+
+Connect to scott/tiger, select `emp` and print as CSV format.
+
+    ruby -r oci8 -e "OCI8.new('scott', 'tiger').exec('select * from emp') do |r| puts r.join(','); end"
+
+If you install a ruby-oci8 gem package, you may need to add `-rubygems` before `-r oci8`.
+
+Installation
+============
+
+* {file:docs/install-full-client.md}
+* {file:docs/install-instant-client.md}
+* {file:docs/install-binary-package.md}
+
+Report issues
+=============
+
+* {file:docs/report-installation-issue.md}
+* [The issues page on github](https://github.com/kubo/ruby-oci8/issues)
+* [The ruby-oci8 help forum on rubyforge](http://rubyforge.org/forum/forum.php?forum_id=1078)

data/VERSION

@@ -1 +1 @@
-2.1.0
+2.1.1

data/dist-files

@@ -1,18 +1,19 @@
+.yardopts
 ChangeLog
 Makefile
 NEWS
-README
+README.md
 VERSION
 dist-files
 metaconfig
 pre-distclean.rb
 ruby-oci8.gemspec
 setup.rb
-doc/api.en.html
-doc/api.en.rd
-doc/api.ja.html
-doc/api.ja.rd
-doc/manual.css
+docs/install-binary-package.md
+docs/install-full-client.md
+docs/install-instant-client.md
+docs/platform-specific-issues.md
+docs/report-installation-issue.md
 ext/oci8/.document
 ext/oci8/MANIFEST
 ext/oci8/apiwrap.c.tmpl

data/docs/install-binary-package.md

@@ -0,0 +1,40 @@
+# @title Install Binary Package
+
+Windows 32-bit (mingw32 ruby)
+=============================
+
+Run the following command:
+
+    gem install ruby-oci8
+
+Windows 32-bit (mswin32 ruby)
+=============================
+
+Run the following command:
+
+    gem install --platform x86-mingw32 ruby-oci8
+
+Ruby-oci8 gem for x86-mingw32 works on mswin32 ruby.
+If it doesn't work, see {file:docs/install-instant-client.md} or {file:docs/install-full-client.md}.
+
+Other platforms
+===============
+
+We doesn't make binary gems for other platforms.
+If you need to distribute a binary gem, compile ruby-oci8 and run the following command.
+
+    gem build ruby-oci8.gemspec -- current
+
+Note that you need to compile it on the oldest versions of the platform you support
+and for the oldest versions of the Oracle databases.
+
+If you could not fix the Oracle versions, compile ruby-oci8 and make a gem as follows:
+
+    gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
+    cd ruby-oci8-VERSION
+    ruby setup.rb config -- --with-runtime-check
+    make
+    gem build ruby-oci8.gemspec -- current
+
+When the option `--with-runtime-check` is set, ruby-oci8 checks the Oracle version
+and available OCI functions at runtime.

data/docs/install-full-client.md

@@ -0,0 +1,116 @@
+# @title Install for Oracle Full Client
+
+Introduction
+============
+
+This page explains the way to install ruby-oci8 for Oracle Full Client
+installations.
+
+For Oracle Instant Client, look at {file:docs/install-instant-client.md}.
+For Windows, look at {file:docs/install-binary-package.md} unless you
+have a special need to compile ruby-oci8 by yourself.
+
+Check the environment
+=====================
+
+Oracle installation
+-------------------
+
+Run the following command and confirm it works fine. If it doesn't
+work well, you need to ask to your database administrator.
+
+    sqlplus USERNAME/PASSWORD
+
+ruby installation
+-----------------
+
+Run the following command. If it ends with "can't find header files
+for ruby" or "ruby: no such file to load -- mkmf (LoadError)", you need
+to install ruby-devel(redhat) or ruby-dev(debian/ubuntu).
+
+    ruby -r mkmf -e ""
+
+development tools
+-----------------
+
+You need a C compiler and development tools such as make or nmake.
+Note that they must be same with ones used to compile the ruby.
+For example, you need Oracle Solaris Studio, not gcc, for ruby
+compiled by Oracle Solaris Studio.
+
+Installation
+============
+
+If you get a problem in the following steps, look at {file:docs/platform-specific-issues.md}
+and {file:docs/report-installation-issue.md}.
+
+Set the library search path
+---------------------------
+
+### UNIX
+
+Set the library search path, whose name depends on the OS, to point to
+$ORACLE\_HOME/lib. If the database is 64-bit and the ruby is 32-bit,
+use $ORACLE\_HOME/lib32 instead.
+
+<table style="border: 1px #E3E3E3 solid; border-collapse: collapse; border-spacing: 0;">
+<thead>
+  <tr><th> OS                        </th><th> library search path                   </th></tr>
+</thead>
+<tbody>
+  <tr><td> Linux                     </td><td> LD_LIBRARY_PATH                       </td></tr>
+  <tr><td> Solaris 32-bit ruby       </td><td> LD_LIBRARY_PATH_32 or LD_LIBRARY_PATH </td></tr>
+  <tr><td> Solaris 64-bit ruby       </td><td> LD_LIBRARY_PATH_64 or LD_LIBRARY_PATH </td></tr>
+  <tr><td> HP-UX PA-RISC 32-bit ruby </td><td> SHLIB_PATH                            </td></tr>
+  <tr><td> HP-UX PA-RISC 64-bit ruby </td><td> LD_LIBRARY_PATH                       </td></tr>
+  <tr><td> HP-UX IA64                </td><td> LD_LIBRARY_PATH                       </td></tr>
+  <tr><td> Mac OS X                  </td><td> DYLD_LIBRARY_PATH                     </td></tr>
+  <tr><td> AIX                       </td><td> LIBPATH                               </td></tr>
+</tbody>
+</table>
+
+Do not forget to export the variable as follows:
+
+    $ LD_LIBRARY_PATH=$ORACLE_HOME/lib
+    $ export LD_LIBRARY_PATH
+
+### Windows(mswin32, mingw32, cygwin)
+
+If sqlplus runs correctly, library search path has no problem.
+
+gem package
+-----------
+
+Run the following command.
+
+    gem install ruby-oci8
+
+tar.gz package
+--------------
+
+### Download the source code
+
+Download the latest tar.gz package such as ruby-oci8 2.1.0.tar.gz,
+which is the latest version at the time of writing, from [rubyforge][].
+
+### Run make and install
+
+#### UNIX or Windows(mingw32, cygwin)
+
+    gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
+    cd ruby-oci8-VERSION
+    make
+    make install
+
+note: If you use '`sudo`', use it only when running '`make install`'.
+'`sudo`' doesn't pass library search path to the executing command for security reasons.
+
+#### Windows(mswin32)
+
+
+    gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
+    cd ruby-oci8-VERSION
+    nmake
+    nmake install
+
+[rubyforge]: http://rubyforge.org/frs/?group_id=256

data/docs/install-instant-client.md

@@ -0,0 +1,167 @@
+# @title Install for Oracle Instant Client
+
+Introduction
+============
+
+This page explains the way to install ruby-oci8 for Oracle Instant Client.
+
+For Oracle Full Client, look at {file:docs/install-full-client.md}.
+For Windows, look at {file:docs/install-binary-package.md} unless you
+have a special need to compile ruby-oci8 by yourself.
+
+Install Oracle Instant Client Packages
+======================================
+
+Donwload Instant Client Packages
+--------------------------------
+Download the following packages from [Oracle Technology Network](http://www.oracle.com/technetwork/database/features/instant-client/index-097480.html).
+
+* Instant Client Package - Basic or Basic Lite
+* Instant Client Package - SDK
+* Instant Client Package - SQL*Plus
+
+Note: use 32-bit packages for 32-bit ruby even though the OS is 64-bit.
+
+UNIX zip packages
+-----------------
+
+Unzip the packages as follows:
+
+    mkdir /opt
+    mkdir /opt/oracle
+    cd /opt/oracle
+    unzip path/to/instantclient-basic-OS-VERSION.zip
+    unzip path/to/instantclient-sdk-OS-VERSION.zip
+    unzip path/to/instantclient-sqlplus-OS-VERSION.zip
+
+If /opt/oracle/instantclient10_1/libclntsh.so is not found, make
+a symbolic link to link the library.
+
+    cd /opt/oracle/instantclient10_1
+    ln -s libclntsh.so.10.1 libclntsh.so
+
+Note:
+
+* use libclntsh.sl instead of libclntsh.so on HP-UX PA-RISC.
+* use libclntsh.dylib instead of libclntsh.so on Mac OS X.
+* skip this step for AIX.
+
+Set the library search path, whose name depends on the OS, to point to
+the installed directory.
+
+<table style="border: 1px #E3E3E3 solid; border-collapse: collapse; border-spacing: 0;">
+<thead>
+  <tr><th> OS                        </th><th> library search path                   </th></tr>
+</thead>
+<tbody>
+  <tr><td> Linux                     </td><td> LD_LIBRARY_PATH                       </td></tr>
+  <tr><td> Solaris 32-bit ruby       </td><td> LD_LIBRARY_PATH_32 or LD_LIBRARY_PATH </td></tr>
+  <tr><td> Solaris 64-bit ruby       </td><td> LD_LIBRARY_PATH_64 or LD_LIBRARY_PATH </td></tr>
+  <tr><td> HP-UX PA-RISC 32-bit ruby </td><td> SHLIB_PATH                            </td></tr>
+  <tr><td> HP-UX PA-RISC 64-bit ruby </td><td> LD_LIBRARY_PATH                       </td></tr>
+  <tr><td> HP-UX IA64                </td><td> LD_LIBRARY_PATH                       </td></tr>
+  <tr><td> Mac OS X                  </td><td> DYLD_LIBRARY_PATH                     </td></tr>
+  <tr><td> AIX                       </td><td> LIBPATH                               </td></tr>
+</tbody>
+</table>
+
+For example:
+    $ LD_LIBRARY_PATH=/opt/oracle/instantclient_10_2
+    $ export LD_LIBRARY_PATH
+
+Linux rpm packages
+------------------
+
+Install the downloaded packages as follows:
+
+    rpm -i path/to/oracle-instantclient-basic-VERSION-ARCH.rpm
+    rpm -i path/to/oracle-instantclient-devel-VERSION-ARCH.rpm
+    rpm -i path/to/oracle-instantclient-sqlplus-VERSION-ARCH.rpm
+
+Set LD_LIBRARY_PATH to point to the directory where libclntsh.so is installed.
+
+For example:
+    $ LD_LIBRARY_PATH=/usr/lib/oracle/10.2.0.3/client/lib
+    $ export LD_LIBRARY_PATH
+
+Windows
+-------
+
+Unzip the packages and set PATH to point to the directory where OCI.DLL is installed.
+
+Check the environment
+=====================
+
+Oracle installation
+-------------------
+
+Run the following command and confirm it works fine. If it doesn't
+work well, check LD\_LIBRARY\_PATH or PATH.
+
+    sqlplus USERNAME/PASSWORD
+
+ruby installation
+-----------------
+
+Run the following command. If it ends with "can't find header files
+for ruby" or "ruby: no such file to load -- mkmf (LoadError)", you need
+to install ruby-devel(redhat) or ruby-dev(debian/ubuntu).
+
+    ruby -r mkmf -e ""
+
+development tools
+-----------------
+
+You need a C compiler and development tools such as make or nmake.
+Note that they must be same with ones used to compile the ruby.
+For example, you need Oracle Solaris Studio, not gcc, for ruby
+compiled by Oracle Solaris Studio.
+
+Installation
+============
+
+If you get a problem in the following steps, look at {file:docs/platform-specific-issues.md}
+and {file:docs/report-installation-issue.md}.
+
+gem package
+-----------
+
+Run the following command.
+
+    gem install ruby-oci8
+
+If you get a problem, look at {file:docs/platform-specific-issues.md}
+and {file:docs/report-installation-issue.md}.
+
+tar.gz package
+--------------
+
+### Download the source code
+
+Download the latest tar.gz package such as ruby-oci8 2.1.0.tar.gz,
+which is the latest version at the time of writing, from [rubyforge][].
+
+Note: if you are using Windows and you have no special need to compile
+it by yourself, look at {file:docs/install-binary-packge.md}.
+
+### Run make and install
+
+#### UNIX or Windows(mingw32, cygwin)
+
+    gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
+    cd ruby-oci8-VERSION
+    make
+    make install
+
+note: If you use '`sudo`', use it only when running '`make install`'.
+'`sudo`' doesn't pass library search path to the executing command for security reasons.
+
+#### Windows(mswin32)
+
+
+    gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
+    cd ruby-oci8-VERSION
+    nmake
+    nmake install
+
+[rubyforge]: http://rubyforge.org/frs/?group_id=256

data/docs/platform-specific-issues.md

@@ -0,0 +1,209 @@
+# @title Platform Specific Issues
+
+Linux
+=====
+
+Ubuntu 11.10 (Oneiric Ocelot)
+-----------------------------
+
+If the following error occurs even though libc6-dev is installed,
+
+    Do you install glibc-devel(redhat) or libc6-dev(debian)?
+    You need /usr/include/sys/types.h to compile ruby-oci8.
+
+You need to use ruby-oci8 2.1.0 or upper. Otherwise, run the following command and re-install ruby-oci8.
+
+    $ sudo ln -s /usr/include/linux/ /usr/include/sys
+
+General Linux
+-------------
+
+Use the same bit-width of libraries with ruby. For example, x86\_64
+instant client for x86\_64 ruby and 32-bit instant client for 32-bit
+ruby. It depends on the ruby but not on the OS. As for full client,
+x86\_64 ruby cannot use with 32-bit full client, but 32-bit ruby can
+use with 64-bit full client because 32-bit libraries are in
+$ORACLE\_HOME/lib32.
+
+To check which type of ruby do you use:
+
+    file `which ruby`
+
+Note: "`" is a back quote.
+
+Mac OS X
+========
+
+OS X 10.7 Lion
+--------------
+
+64-bit instant client doesn't work. Use 32-bit ruby and instant client or jruby.
+
+See:
+
+* {http://rubyforge.org/forum/forum.php?thread\_id=49548&forum\_id=1078}
+* {https://forums.oracle.com/forums/thread.jspa?threadID=2187558}
+
+Intel Mac (64-bit)
+------------------
+
+See [How to setup Ruby and Oracle Instant Client on Snow Leopard](http://blog.rayapps.com/2009/09/06/how-to-setup-ruby-and-oracle-instant-client-on-snow-leopard/).
+Note that setting the environment variable RC\_ARCHS=x86\_64 instead of ARCHFLAGS="-arch x86\_64" will work fine also.
+
+Intel Mac (32-bit)
+------------------
+
+See [How to setup Ruby and Oracle Instant Client on Snow Leopard](http://blog.rayapps.com/2009/09/06/how-to-setup-ruby-and-oracle-instant-client-on-snow-leopard/). Note that you need to replace x86\_64 with i386 in the blog.
+
+The Intel Instant client is for Mac OS X 10.5 Leopard. If you are using 10.4 Tiger,
+use one of the following workarounds.
+
+* compile ruby as ppc. (look at [How to setup Ruby and Oracle client on Intel Mac](http://blog.rayapps.com/2007/08/27/how-to-setup-ruby-and-oracle-client-on-intel-mac/))
+* use [ruby-odbc|http://www.ch-werner.de/rubyodbc/] and a third party ODBC driver ([Actual Technologies](http://www.actualtechnologies.com) or [OpenLink Software](http://uda.openlinksw.com/)).
+* use JRuby and Oracle JDBC driver.
+
+PowerPC Mac
+-----------
+
+See [How to setup Ruby and Oracle Instant Client on Snow Leopard](http://blog.rayapps.com/2009/09/06/how-to-setup-ruby-and-oracle-instant-client-on-snow-leopard/). Note that you need to replace x86\_64 with ppc in the blog.
+
+Solaris
+=======
+
+You need a same compiler which is used to make ruby itself.
+
+There are two ruby packages.
+
+* [Sunfreeware.com](http://www.sunfreeware.com/)
+* [Blastwave.org](http://www.blastwave.org/)
+
+The former is compiled by gcc. The latter is compiled by
+[Sun Studio](http://developers.sun.com/sunstudio/).
+The both compilers are freely available.
+
+If you use Blastwave.org's ruby and want not to install Sun Studio,
+you can edit rbconfig.rb by your self. [(look at here)](http://forum.textdrive.com/viewtopic.php?id=12630)
+
+If you use Sunfreeware.com's ruby and 
+
+    $ ruby -r rbconfig -e "p Config::CONFIG['GNU_LD']"
+
+prints "yes", you may need to edit rbconfig.rb distributed with the ruby
+as follows:
+
+   from: CONFIG["LDFLAGS"] = "-L.  -Wl,-E"
+   to:   CONFIG["LDFLAGS"] = "-L. "
+
+FreeBSD
+=======
+
+There are two ways.
+
+* use ruby and instant client on linux emulator
+* use oracle8-client port
+
+linux emulator
+--------------
+
+I have not run ruby-oci8 on linux emulator, but I guess it will
+run as follows. If it works, please tell me.
+
+If FreeBSD has a cross-compiler which can generate linux binaries,
+use it to compile ruby and ruby-oci8.
+
+If FreeBSD doesn't have such a compiler, install a linux distribution
+which FreeBSD can emulate to a PC machine, make ruby and ruby-oci8 in
+the linux box and copy them to the FreeBSD box as follows.
+
+On linux:
+
+    # make ruby
+    tar xvfz ruby-1.8.x.tar.gz
+    cd ruby-1.8.x
+    ./configure --prefix=/usr/local/ruby-1.8.x --enable-pthread
+    make
+    make install
+    # setup instant client
+      ....
+    # make ruby-oci8
+    PATH=/usr/local/ruby-1.8.x/bin:$PATH
+    tar xvfz ruby-oci8-1.0.x.tar.gz
+    cd ruby-oci8-1.0.x
+    make
+    make install
+    cd /usr/local/
+    tar cvfz ruby-1.8.x-linux.tar.gz ruby-1.8.x
+ 
+Copy ruby-1.8.x-linux.tar.gz to the FreeBSD box.
+ 
+On freebsd:
+
+    cd /compat/linux/usr/local
+    tar xvfz ruby-1.8.x-linux.tar.gz
+
+oracle8-client port
+-------------------
+
+I don't recommend this because of the following two reasons.
+
+* The oracle8-client port is made from Oracle 8.1.7.1 static library for Linux. Oracle have not supported the connectivity between 8.1.7.1 and Oracle 10g.
+* It is very unstable. When it fails to connect to an Oracle server, it is down by segmentation fault on FreeBSD 7.0 not only when using ruby-oci8, but also by a very simple test code written by C.
+
+If you try to use oracle8-client port, compile and install as follows.
+
+* install oracle8-client
+
+    cd /usr/ports/databases/oracle8-client
+    make
+    make install
+
+* set an environment variable ORACLE\_HOME
+
+    export ORACLE_HOME=/usr/local/oracle8-client
+
+The rest steps are described at {file:docs/install-full-client.md}.
+
+note: You have no need to set LD\_LIBRARY\_PATH because 
+Oracle libraries in oracle8-client port are static ones.
+
+HP-UX
+=====
+
+You need a ruby which is linked with ''libpthread'' and ''libcl''.
+
+Run `configure`.
+
+    tar xvfz ruby-1.9.x.tar.gz
+    cd ruby-1.9.x
+    ./configure
+
+Then open `Makefile` to add '-lpthread -lcl' to `LIBS` and run `make`
+and `make install`.
+
+    make
+    make install
+
+The rest steps are described at {file:docs/install-full-client.md}.
+
+Windows
+=======
+
+On some machines using a slow disk, you may get the following error.
+
+    Permission denied - conftest.exe
+
+Edit mkmf.rb for a workaround.
+
+    def try_run(src, opt="")
+      if try_link0(src, opt)
+        xsystem("./conftest")
+      else
+        nil
+      end
+    ensure
+      # add the following one line.
+      sleep 1 if /mswin32|cygwin|mingw32|bccwin32/ =~ RUBY_PLATFORM
+      rm_f "conftest*"
+    end
+
+See also: {http://abstractplain.net/blog/?p=788}.