ruby-oci8 2.2.3 → 2.2.4

data/docs/install-instant-client.md

@@ -1,7 +1,10 @@
 # @title Install for Oracle Instant Client
 
+Install for Oracle Instant Client
+=================================
+
 Introduction
-============
+------------
 
 This page explains the way to install ruby-oci8 for Oracle Instant Client.
 
@@ -13,10 +16,10 @@ have a special need to compile ruby-oci8 by yourself.
 Look at {file:docs/install-on-osx.md} for OS X.
 
 Install Oracle Instant Client Packages
-======================================
+--------------------------------------
+
+### Donwload 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
@@ -25,8 +28,7 @@ Download the following packages from [Oracle Technology Network](http://www.orac
 
 Note: use 32-bit packages for 32-bit ruby even though the OS is 64-bit.
 
-UNIX zip packages
------------------
+### UNIX zip packages
 
 Unzip the packages as follows:
 
@@ -79,8 +81,7 @@ Though many instant client pages indicate that the environment varialbe
 configuration files such as `tnsnames.ora` and `sqlnet.ora` are in
 `$ORACLE_HOME/network/admin/`.
 
-Linux rpm packages
-------------------
+### Linux rpm packages
 
 Install the downloaded packages as follows:
 
@@ -95,24 +96,43 @@ For example:
     $ LD_LIBRARY_PATH=/usr/lib/oracle/12.1/client/lib
     $ export LD_LIBRARY_PATH
 
-Windows
--------
+### Windows
+
+Unzip the packages and set `PATH` to point to the directory where `OCI.DLL` is installed.
+
+If `require "ruby-oci8"` raises a load error such as "OCI.DLL: 126(The
+specified module could not be found. )", either `OCI.DLL` or a DLL depended
+by `OCI.DLL` could not be found in `PATH`.
+
+If `OCI.DLL` is surely in `PATH`, the missing module is a Visual C++ runtime
+library in most cases. You need to install "Microsoft Visual C++ Redistributable
+Package" or copy a runtime library to the directory where `ruby.exe` resides.
+
+| Oracle Version | Package | Runtime Library|
+|---|---|---|
+| 12.2.0.x | [Microsoft Visual C++ 2013 Redistributable Package][2013] | MSVCR120.DLL |
+| 12.1.0.x | [Microsoft Visual C++ 2010 Redistributable Package][2010] | MSVCR100.DLL |
+| 11.2.0.x | Microsoft Visual C++ 2005 SP1 Redistributable Package ([x86][2005SP1_x86], [x64][2005SP1_x64]) | MSVCR80.DLL(The file version must be 8.0.50727.762.) |
+| 11.1.0.x | [No separate redistributable package][2003] | MSVCR71.DLL |
+| 10.2.0.x | [No separate redistributable package][2003] | MSVCR71.DLL |
 
-Unzip the packages and set PATH to point to the directory where OCI.DLL is installed.
+[2013]: https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads
+[2010]: http://www.microsoft.com/en-us/download/details.aspx?id=26999
+[2005SP1_x86]: https://www.microsoft.com/en-us/download/details.aspx?id=5638
+[2005SP1_x64]: https://www.microsoft.com/en-us/download/details.aspx?id=18471
+[2003]: http://stackoverflow.com/questions/1596167/where-to-download-microsoft-visual-c-2003-redistributable#6132093
 
 Check the environment
-=====================
+---------------------
 
-Oracle installation
--------------------
+### 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
------------------
+### 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
@@ -120,8 +140,7 @@ to install ruby-devel(redhat) or ruby-dev(debian/ubuntu).
 
     ruby -r mkmf -e ""
 
-development tools
------------------
+### 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.
@@ -129,13 +148,12 @@ 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
------------
+### gem package
 
 Run the following command.
 
@@ -144,19 +162,18 @@ Run the following command.
 If you get a problem, look at {file:docs/platform-specific-issues.md}
 and {file:docs/report-installation-issue.md}.
 
-tar.gz package
---------------
+### tar.gz package
 
-### Download the source code
+#### Download the source code
 
 Download the latest tar.gz package from [download page][].
 
 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
+#### Run make and install
 
-#### UNIX or Windows(mingw32, cygwin)
+##### UNIX or Windows(mingw32, cygwin)
 
     gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
     cd ruby-oci8-VERSION
@@ -166,7 +183,7 @@ it by yourself, look at {file:docs/install-binary-packge.md}.
 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)
+##### Windows(mswin32)
 
     gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
     cd ruby-oci8-VERSION

data/docs/install-on-osx.md

@@ -1,12 +1,15 @@
 # @title Install ruby-oci8 on OS X
 
+Install ruby-oci8 on OS X
+=========================
+
 This page explains the way to install ruby-oci8 os OS X.
 
 Look at {file:docs/install-full-client.md}, {file:docs/install-instant-client.md}
 or {file:docs/install-binary-package.md} for other platforms.
 
 Install C compiler
-==================
+------------------
 
 You need to install the command line developer tools or the Xcode.
 (The latter includes the former.)
@@ -28,10 +31,9 @@ please re-run as root via sudo."` is printed, you need to run
 and type `"agree"`.
 
 Install Oracle Instant Client Packages
-======================================
+--------------------------------------
 
-Download Oracle Instant Client Packages
---------------------------------
+### Download Oracle Instant Client Packages
 
 Download the following packages from [Oracle Technology Network][]
 
@@ -39,8 +41,7 @@ Download the following packages from [Oracle Technology Network][]
 * Instant Client Package - SDK (`instantclient-sdk-macos.x64-12.1.0.2.0.zip`)
 * Instant Client Package - SQL*Plus (`instantclient-sdk-macos.x64-12.1.0.2.0.zip`) (optionally) 
 
-Install Oracle Instant Client Packages via Homebrew
----------------------------------------------------
+### Install Oracle Instant Client Packages via Homebrew
 
 To install `Oracle Instant Client Basic` via [Homebrew][]
 
@@ -78,8 +79,7 @@ To install `Oracle Instant Client Basic Lite` via [Homebrew][]
 
         export OCI_DIR=$(brew --prefix)/lib
 
-Install Oracle Instant Client Manually
----------------------
+### Install Oracle Instant Client Manually
 
 If you don't use [Homebrew][], do the following:
 
@@ -104,25 +104,23 @@ Set the environment variable OCI_DIR while performing the following installation
     export OCI_DIR=/opt/oracle/instantclient_12_1
 
 Installation
-============
+------------
 
 If you get a problem in the following steps, look at {file:docs/report-installation-issue.md}.
 
-gem package
------------
+### gem package
 
 Run the following command.
 
     gem install ruby-oci8
 
-tar.gz package
---------------
+### tar.gz package
 
-### Download the source code
+#### Download the source code
 
 Download the latest tar.gz package from [download page][].
 
-### Run make and install
+#### Run make and install
 
     tar xvfz ruby-oci8-VERSION.tar.gz
     cd ruby-oci8-VERSION

data/docs/platform-specific-issues.md

@@ -1,10 +1,12 @@
 # @title Platform Specific Issues
 
+Platform Specific Issues
+========================
+
 Linux
-=====
+-----
 
-Ubuntu 11.10 (Oneiric Ocelot)
------------------------------
+### Ubuntu 11.10 (Oneiric Ocelot)
 
 If the following error occurs even though libc6-dev is installed,
 
@@ -15,8 +17,7 @@ You need to use ruby-oci8 2.1.0 or upper. Otherwise, run the following command a
 
     $ sudo ln -s /usr/include/linux/ /usr/include/sys
 
-General Linux
--------------
+### 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
@@ -32,21 +33,18 @@ To check which type of ruby do you use:
 Note: "`" is a back quote.
 
 Mac OS X
-========
+--------
 
-OS X 10.7+
-----------
+### OS X 10.7+
 
 Use the latest 64-bit instant client. The older 64-bit (10.2.0.4) instant client [doesn't work](https://forums.oracle.com/forums/thread.jspa?threadID=2187558). The older 32-bit instant client will work but only with 32-bit ruby or jruby (using JDBC).
 
-Intel Mac (64-bit)
-------------------
+### 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)
-------------------
+### 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.
 
@@ -57,13 +55,12 @@ use one of the following workarounds.
 * 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
------------
+### 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.
 For example, if the ruby is compiled by gcc, you need gcc. If it is compiled by Oracle Solaris Studio
@@ -83,15 +80,10 @@ as follows:
     to:   CONFIG["LDFLAGS"] = "-L. "
 
 FreeBSD
-=======
-
-There are two ways.
+-------
 
-* use ruby and instant client on linux emulator
-* use oracle8-client port
-
-linux emulator
---------------
+Oracle8-client port isn't available because it is too old.
+You need to use 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.
@@ -129,33 +121,8 @@ 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''.
 
@@ -174,7 +141,7 @@ and `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.
 

data/docs/report-installation-issue.md

@@ -1,5 +1,8 @@
 # @title Report Installation Issues
 
+Report Installation Issues
+==========================
+
 Look at {file:docs/platform-specific-issues.md} and [the issues page on github][github] to check whether your issue is fixed or not.
 
 If it is a new one, post the following information to [github][].

data/docs/timeout-parameters.md

@@ -30,6 +30,9 @@ The next two parameters `send_timeout` and `recv_timeout` are available on Oracl
 or upper. Use these parameters to prevent a ruby process from being blocked by poor quality network.
 Otherwise, the ruby process may be blocked until TCP keepalive time (2 hours).
 
+See {file:docs/hanging-after-inactivity.md Hanging After a Long Period of Inactivity}
+for TCP keepalive time.
+
 tcp_connect_timeout
 -------------------
 

data/ext/oci8/encoding.c

@@ -23,7 +23,7 @@ rb_encoding *oci8_encoding;
  * Returns the Oracle character set name from the specified
  * character set ID if it is valid. Otherwise, +nil+ is returned.
  *
- * @param [Fixnum] charset_id   Oracle character set id
+ * @param [Integer] charset_id  Oracle character set id
  * @return [String]             Oracle character set name or nil
  * @since 2.2.0
  */
@@ -48,7 +48,7 @@ VALUE oci8_s_charset_id2name(VALUE klass, VALUE csid)
  * character set name if it is valid. Othewise, +nil+ is returned.
  *
  * @param [String] charset_name   Oracle character set name
- * @return [Fixnum]               Oracle character set id or nil
+ * @return [Integer]              Oracle character set id or nil
  * @since 2.2.0
  */
 static VALUE oci8_s_charset_name2id(VALUE klass, VALUE name)
@@ -71,7 +71,7 @@ static VALUE oci8_s_charset_name2id(VALUE klass, VALUE name)
  * internal buffer size of a string bind variable whose nls length
  * semantics is char.
  *
- * @return [Fixnum]  NLS ratio
+ * @return [Integer] NLS ratio
  * @since 2.1.0
  * @private
  */
@@ -150,7 +150,7 @@ static VALUE oci8_set_encoding(VALUE klass, VALUE encoding)
  * character set name if it is valid. Othewise, +nil+ is returned.
  *
  * @param [String] charset_name   Oracle character set name
- * @return [Fixnum]               Oracle character set id or nil
+ * @return [Integer]              Oracle character set id or nil
  * @since 2.0.0
  * @deprecated Use {OCI8.charset_name2id} instead.
  */
@@ -167,7 +167,7 @@ static VALUE oci8_charset_name2id(VALUE svc, VALUE name)
  * Returns the Oracle character set name from the specified
  * character set ID if it is valid. Otherwise, +nil+ is returned.
  *
- * @param [Fixnum] charset_id   Oracle character set id
+ * @param [Integer] charset_id  Oracle character set id
  * @return [String]             Oracle character set name or nil
  * @since 2.0.0
  * @deprecated Use {OCI8.charset_id2name} instead.

data/ext/oci8/env.c

@@ -14,11 +14,17 @@ OCIEnv *oci8_global_envhp;
 OCIEnv *oci8_make_envhp(void)
 {
     sword rv;
+    OCIEnv *envhp = NULL;
 
-    rv = OCIEnvCreate(&oci8_global_envhp, oci8_env_mode, NULL, NULL, NULL, NULL, 0, NULL);
+    rv = OCIEnvCreate(&envhp, oci8_env_mode, NULL, NULL, NULL, NULL, 0, NULL);
     if (rv != OCI_SUCCESS) {
-        oci8_raise_init_error();
+        if (envhp != NULL) {
+            oci8_env_free_and_raise(envhp, rv);
+        } else {
+            oci8_raise_init_error();
+        }
     }
+    oci8_global_envhp = envhp;
     return oci8_global_envhp;
 }
 

data/ext/oci8/error.c

@@ -172,6 +172,22 @@ sb4 oci8_get_error_code(OCIError *errhp)
     return errcode;
 }
 
+/* This is overwritten by lib/oci8/oci8.rb. */
+static VALUE oci8_error_initialize(int argc, VALUE *argv, VALUE self)
+{
+    VALUE msg;
+    VALUE code;
+    VALUE sql;
+    VALUE parse_error_offset;
+
+    rb_scan_args(argc, argv, "04", &msg, &code, &sql, &parse_error_offset);
+    rb_call_super(argc ? 1 : 0, &msg);
+    rb_ivar_set(self, oci8_id_at_code, code);
+    rb_ivar_set(self, oci8_id_at_sql, sql);
+    rb_ivar_set(self, oci8_id_at_parse_error_offset, parse_error_offset);
+    return Qnil;
+}
+
 void Init_oci8_error(void)
 {
     errbufsiz = ERRBUF_EXPAND_LEN;
@@ -201,6 +217,9 @@ void Init_oci8_error(void)
     rb_define_attr(eOCIError, "sql", 1, 0);
     rb_define_attr(eOCIError, "parse_error_offset", 1, 0);
     rb_define_alias(eOCIError, "parseErrorOffset", "parse_error_offset");
+
+    /* This is overwritten by lib/oci8/oci8.rb. */
+    rb_define_method_nodoc(eOCIError, "initialize", oci8_error_initialize, -1);
 }
 
 void oci8_do_raise(OCIError *errhp, sword status, OCIStmt *stmthp, const char *file, int line)
@@ -208,9 +227,13 @@ void oci8_do_raise(OCIError *errhp, sword status, OCIStmt *stmthp, const char *f
     rb_exc_raise(oci8_make_exc(errhp, status, OCI_HTYPE_ERROR, stmthp, file, line));
 }
 
-void oci8_do_env_raise(OCIEnv *envhp, sword status, const char *file, int line)
+void oci8_do_env_raise(OCIEnv *envhp, sword status, int free_envhp, const char *file, int line)
 {
-    rb_exc_raise(oci8_make_exc(envhp, status, OCI_HTYPE_ENV, NULL, file, line));
+    VALUE exc = oci8_make_exc(envhp, status, OCI_HTYPE_ENV, NULL, file, line);
+    if (free_envhp) {
+        OCIHandleFree(envhp, OCI_HTYPE_ENV);
+    }
+    rb_exc_raise(exc);
 }
 
 void oci8_do_raise_init_error(const char *file, int line)