ruby-oci8 2.2.4.1 → 2.2.5

data/ChangeLog

@@ -1,7 +1,57 @@
+2017-10-21  Kubo Takehiro <kubo@jiubao.org>
+	* NEWS: Add changes between 2.2.4.1 and 2.2.5
+	* lib/oci8/version.rb: Update to 2.2.5
+	* docs/number-type-mapping.md: minor fix
+	* dist-files: Add files.
+
+2017-10-18  Kubo Takehiro <kubo@jiubao.org>
+	* docs/number-type-mapping.md, README.md, dist-files: Add document
+	    about the mapping between Oracle number types and Ruby classes.
+
+2017-10-17  Kubo Takehiro <kubo@jiubao.org>
+	* lib/oci8/check_load_error.rb: Check error reason when loading
+	    failed with 'The specified module could not be found' on Windows.
+
+2017-10-17  Kubo Takehiro <kubo@jiubao.org>
+	* lib/oci8/check_load_error.rb: Fix LoadError while trying to check
+	    errors in "require 'oci8lib_230.so'" on cygwin 2.8 or later.
+	    (related to github issue #176)
+
+2017-10-17  Kubo Takehiro <kubo@jiubao.org>
+	* ext/oci8/ocinumber.c, test/test_oranumber.rb:
+	    Add OraNumber#has_fractional_part?.
+
+2017-10-01  Kubo Takehiro <kubo@jiubao.org>
+	* ext/oci8/plthook_elf.c: Update plthook to use prelinked
+	    libclntsh.so on Linux.
+	    (github issue #172)
+
+2017-09-27  Kubo Takehiro <kubo@jiubao.org>
+	* ext/oci8/oci8lib.c: Change order to load libclntsh when runtime
+	    api check is enabled on Unix.
+
+2017-09-24  Kubo Takehiro <kubo@jiubao.org>
+	* ext/oci8/oci8lib.c: Try to load $ORACLE_HOME/lib/libclntsh.so also
+	    when runtime api check is enabled on Unix.
+
+2017-09-23  Kubo Takehiro <kubo@jiubao.org>
+	* lib/oci8/cursor.rb: Don't call unnecessary __paramGet(i) when a
+	    cursor is executed more than once.
+	    (pointed by OMOTO Kenji at github issue #171)
+
+2017-07-09  Kubo Takehiro <kubo@jiubao.org>
+	* ext/oci8/apiwrap.yml, ext/oci8/oci8.c, lib/oci8/oci8.rb:
+	    Delete unused code using OCILogon2 and OCILogoff.
+
+2017-07-09  Kubo Takehiro <kubo@jiubao.org>
+	* ext/oci8/error.c: Delete OCIError#initialize defined by C code
+	    to suppress warning: method redefined; discarding old initialize.
+	    (github issue #168)
+
 2017-06-17  Kubo Takehiro <kubo@jiubao.org>
 	* NEWS: Add changes between 2.2.4 and 2.2.4.1
 	* lib/oci8/version.rb: Update to 2.2.4.1
-	* lib/oci8/version.rb: Fix URL links
+	* lib/oci8/properties.rb: Fix URL links
 	* docs/hanging-after-inactivity.md: Revised
 
 2017-06-16  Kubo Takehiro <kubo@jiubao.org>

data/NEWS

@@ -1,5 +1,63 @@
 # @markup markdown
 
+2.2.5
+=====
+
+New Features
+------------
+
+### Try to load $ORACLE_HOME/lib/libclntsh.so also when runtime api check is enabled on Unix.
+
+When ruby-oci8 is configured with `--with-runtime-check`, it loads Oracle client
+library and checks available functions in the library at runtime. This feature was
+added to release Windows binary gems which cannot know Oracle version at compile time.
+This is available also on Unix. However it tries to load libraries in LD_LIBRARY_PATH only.
+From this version, it tries to load $ORACLE_HOME/lib/libclntsh.so also.
+
+### Check error reasons when loading failed with 'The specified module could not be found' on Windows.
+
+The error messages are same when OCI.DLL isn't found and when Visual
+C++ runtime library depended on by OCI.DLL isn't found. From this
+version, ruby-oci8 distinguishes the difference and prints other message
+for the latter case.
+
+Fixed issue
+-----------
+
+### Fix segmentation fault when Oracle client library is prelinked.
+
+When Oracle instant client rpm package is used on RHEL5 or RHEL6,
+Oracle client library is modified by [prelink][] and ruby-oci8 crashed
+with segmentation fault. This is not due to Oracle, but due to
+plthook used by ruby-oci8. The plthook was fixed to work with
+prelinked libraries.
+(github issue #172)
+
+[prelink]: https://en.wikipedia.org/wiki/Prelink#Linux
+
+### Fix not to hide the original error message of LoadError on recent cygwin.
+
+Ruby-oci8 tries to check error messages when `require 'oci8lib_xxx.so` fails.
+However the message was hidden by an exception while checking on cygwin.
+(github issue #176)
+
+### Don't call unnecessary __paramGet(i) when a cursor is executed more than once.
+
+pointed by OMOTO Kenji
+(github issue #171)
+
+### Suppress warning: method redefined; discarding old initialize.
+
+(github issue #168)
+
+Other Changes
+-------------
+
+### Add document about the mapping between Oracle number types and Ruby classes.
+
+See {file:docs/number-type-mapping.md Number Type Mapping between Oracle and Ruby}.
+(github issue #173)
+
 2.2.4.1
 =======
 

data/README.md

@@ -24,7 +24,9 @@ See {file:NEWS}.
 Sample one-liner
 ----------------
 
-Connect to scott/tiger, select `emp` and print as CSV format.
+When you have an Oracle database server to which `sqlplus scott/tiger` can connect
+and `scott` user has `emp` table, you can select `emp` and print rows
+as CSV by the followig one liner.
 
     ruby -r oci8 -e "OCI8.new('scott', 'tiger').exec('select * from emp') do |r| puts r.join(','); end"
 
@@ -50,6 +52,7 @@ Report issues
 Other documents
 ---------------
 
+* {file:docs/number-type-mapping.md Number Type Mapping between Oracle and Ruby}
 * {file:docs/timeout-parameters.md Timeout Parameters}
 * {file:docs/conflicts-local-connections-and-processes.md Conflicts between Local Connections and Child Process Handling on Unix}
 * {file:docs/hanging-after-inactivity.md Hanging After a Long Period of Inactivity}

data/dist-files

@@ -11,12 +11,14 @@ pre-distclean.rb
 ruby-oci8.gemspec
 setup.rb
 docs/bind-array-to-in_cond.md
+docs/conflicts-local-connections-and-processes.md
+docs/hanging-after-inactivity.md
 docs/install-binary-package.md
 docs/install-full-client.md
 docs/install-instant-client.md
 docs/install-on-osx.md
-docs/conflicts-local-connections-and-processes.md
-docs/hanging-after-inactivity.md
+docs/ldap-auth-and-function-interposition.md
+docs/number-type-mapping.md
 docs/osx-install-dev-tools.png
 docs/platform-specific-issues.md
 docs/report-installation-issue.md
@@ -81,10 +83,12 @@ lib/ruby-oci8.rb
 test/README
 test/config.rb
 test/setup_test_object.sql
+test/setup_test_package.sql
 test/test_all.rb
 test/test_appinfo.rb
 test/test_array_dml.rb
 test/test_bind_array.rb
+test/test_bind_boolean.rb
 test/test_bind_raw.rb
 test/test_bind_string.rb
 test/test_bind_time.rb

data/docs/bind-array-to-in_cond.md

@@ -27,7 +27,7 @@ The above code is rewritten as follows:
 
     ids = [ ... ] # an arbitrary-length array containing user IDs.
     
-    in_cond = OCI8::in_cond(:id, ids)]
+    in_cond = OCI8::in_cond(:id, ids)
     cursor = conn.exec("select * from users where id in (#{in_cond.names})", *in_cond.values)
 
 or

data/docs/ldap-auth-and-function-interposition.md

@@ -0,0 +1,123 @@
+# @title LDAP Authentication and Function Interposition
+
+LDAP Authentication and Function Interposition
+==============================================
+
+Problems
+--------
+
+The following code may trigger segmentation faults or unexpected behaviours.
+
+    require 'pg' # or any modules using LDAP such as ActiveLdap
+    require 'oci8'
+    
+    conn = OCI8.new('username/password@dbname.example.com')
+    ...
+
+It happens when all the following conditions are satisfied.
+
+* The platform is Unix
+* The PostgreSQL client library, which `pg` depends, was compiled with LDAP support.
+* LDAP authentication is used to connect to an Oracle server.
+
+It is caused by function interposition as follows:
+
+* The ruby process loads `pq` and its depending libraries such as
+  `libpq.so`(PostgreSQL client library) and `libldap_r.so`(LDAP library).
+* Then it loads `oci8` and its depending libraries such as
+  `libclntsh.so`(Oracle client library).
+* When LDAP authentication is used, `libclntsh.so` tries to use
+  LDAP functions in the library.
+* However it uses LDAP functions in `libldap_r.so` because the function
+  in the firstly loaded library is used when more than one library exports
+  functions whose names are same.
+* It triggers segmentation faults or unexpected behaviours because
+  implementations of LDAP functions are different even though their names
+  are same.
+
+The reverse may cause same results by the following code.
+
+    require 'oci8'
+    require 'pg'
+    
+    ... connect to PostgreSQL using LDAP ...
+
+### Note for macOS
+
+Libraries in two-level namespaces are free from function interposition on macOS.
+See the second paragraph of [this document][mach-o]. If `TWOLEVEL` is
+found in the output of `otool -hV /path/to/library`, it is in a
+two-level namespace. Otherwise it is in a single-level (flat) namespace.
+
+Oracle client library (`libclntsh.dylib.12.1`) is in a flat namespace.
+It suffers from function interposition.
+
+    $ otool -hV libclntsh.dylib.12.1
+    Mach header
+          magic cputype cpusubtype  caps    filetype ncmds sizeofcmds      flags
+    MH_MAGIC_64  X86_64        ALL  0x00       DYLIB    19       2360 DYLDLINK NO_REEXPORTED_DYLIBS MH_HAS_TLV_DESCRIPTORS
+
+PostgreSQL client library (`libpq.5.dylib`) installed by [brew][] depends on an OS-supplied LDAP library.
+
+    $ otool -L libpq.5.dylib 
+    libpq.5.dylib:
+        /usr/local/opt/postgresql/lib/libpq.5.dylib (compatibility version 5.0.0, current version 5.9.0)
+        /usr/local/opt/openssl/lib/libssl.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
+        /usr/local/opt/openssl/lib/libcrypto.1.0.0.dylib (compatibility version 1.0.0, current version 1.0.0)
+        /System/Library/Frameworks/Kerberos.framework/Versions/A/Kerberos (compatibility version 5.0.0, current version 6.0.0)
+        /System/Library/Frameworks/LDAP.framework/Versions/A/LDAP (compatibility version 1.0.0, current version 2.4.0)
+        /usr/lib/libSystem.B.dylib (compatibility version 1.0.0, current version 1238.0.0)
+
+The OS-supplied LDAP library is in a two-level namespace.
+
+    $ otool -hV /System/Library/Frameworks/LDAP.framework/Versions/A/LDAP
+    Mach header
+          magic cputype cpusubtype  caps    filetype ncmds sizeofcmds      flags
+    MH_MAGIC_64  X86_64        ALL  0x00       DYLIB    22       2528   NOUNDEFS DYLDLINK TWOLEVEL NO_REEXPORTED_DYLIBS APP_EXTENSION_SAFE
+
+As a result, the PostgreSQL client library is free from function interposition.
+
+Solution 1
+----------
+
+If you don't connect to PostgreSQL using LDAP, use the following code.
+
+    require 'oci8'  # This must be before "require 'pg'".
+    require 'pg'
+    
+    conn = OCI8.new('username/password@dbname.example.com')
+    ...
+    ... connect to a PostgreSQL server ...
+
+Oracle client library uses LDAP functions in `libclntsh.so` because `libclntsh.so`
+is loaded before `libldap_r.so`.
+
+Don't connect to PostgreSQL using LDAP because `libpq.so` tries to use
+LDAP functions in `libldap_r.so` but faultily uses functions in `libclntsh.so`.
+
+Note for macOS: This fixes all function interposition issues if the LDAP library
+in a two-level namespace.
+
+Solution 2
+----------
+
+If LDAP is used to connect to both Oracle and PostgreSQL and the platform
+is Linux or macOS, use ruby-oci8 2.2.4 or later and use the following code.
+
+    require 'pg'
+    require 'oci8' # This must be after "require 'pg'".
+    
+    conn = OCI8.new('username/password@dbname.example.com')
+    ...
+    ... connect to a PostgreSQL server using LDAP ...
+
+PostgreSQL client library uses LDAP functions in `libldap_r.so` because `libldap_r.so`
+is loaded before `libclntsh.so`.
+
+Oracle client library uses LDAP functions in `libclntsh.so` because ruby-oci8
+forcedly modifies PLT (Procedure Linkage Table) entries to point to
+functions in `libclntsh.so` if they point to functions in other libraries.
+(PLT is equivalent to IAT (Import Address Table) on Windows.)
+
+[mach-o]: https://developer.apple.com/library/content/documentation/DeveloperTools/Conceptual/MachOTopics/1-Articles/executing_files.html
+[brew]: http://brew.sh/

data/docs/number-type-mapping.md

@@ -0,0 +1,79 @@
+# @title Number Type Mapping between Oracle and Ruby
+
+Number Type Mapping between Oracle and Ruby
+===========================================
+
+Default mapping
+---------------
+
+Oracle numbers in select statements are fetched as followings by default:
+
+| Oracle Data Type | Ruby Class |
+|---|---|
+| NUMBER(prec) or NUMBER(prec, 0) | Integer |
+| NUMBER(prec, scale) where prec < 15 and scale != 0 | Float |
+| NUMBER(prec, scale) where prec >= 15 and scale != 0 | BigDecimal |
+| FLOAT or FLOAT(prec) | Float |
+| NUMBER without precision and scale | BigDecimal |
+| number type returned by functions or calculated number | BigDecimal |
+| BINARY_FLOAT | Float |
+| BINARY_DOUBLE | Float |
+
+When the data type is within Integer or Float class, it is fetched
+as Integer or Float. Otherwise, BigDecimal.
+
+Note that the mapping is determined by the column definition in
+select statements, not by the actual value fetched.
+For example the column in `select count(*) from table_name` is
+fetched as BigDecimal because it is returned from `count` function.
+
+The mapping is customizable by `OCI8::BindType::Mapping`.
+The default values of Oracle number data type mapping are:
+
+    # NUMBER or FLOAT data type, used for the first six rows in the above table
+    OCI8::BindType::Mapping[:number] = OCI8::BindType::Number
+    # BINARY_FLOAT data type, used for the seventh row in the above table
+    OCI8::BindType::Mapping[:binary_float] = OCI8::BindType::BinaryDouble
+    # BINARY_DOUBLE data type, used for the eighth row in the above table
+    OCI8::BindType::Mapping[:binary_double] = OCI8::BindType::BinaryDouble
+
+`OCI8::BindType::Number` checks precision and scale to determine
+ruby class. The first four rows in the above table are hard-coded.
+The fifth and sixth rows are, however, customizable by
+`OCI8::BindType::Mapping[:number_no_prec_setting]` and
+`OCI8::BindType::Mapping[:number_unknown_prec]` respectively.
+
+The default values are:
+
+    OCI8::BindType::Mapping[:number_no_prec_setting] = OCI8::BindType::BigDecimal
+    OCI8::BindType::Mapping[:number_unknown_prec] = OCI8::BindType::BigDecimal
+
+The mapping may be changed as follows in future.
+
+| Oracle Data Type | Ruby Class |
+|---|---|
+| NUMBER(prec) or NUMBER(prec, 0) | Integer |
+| other NUMBER  | OraNumber |
+| BINARY_FLOAT | Float |
+| BINARY_DOUBLE | Float |
+
+Customize mapping
+-----------------
+
+Add the following code to fetch all number or float columns as {OraNumber}.
+
+    OCI8::BindType::Mapping[:number] = OCI8::BindType::OraNumber
+
+Otherwise, add the following code to customize the fifth and sixth rows only
+in the above table.
+
+    OCI8::BindType::Mapping[:number_no_prec_setting] = OCI8::BindType::OraNumber
+    OCI8::BindType::Mapping[:number_unknown_prec] = OCI8::BindType::OraNumber
+
+If you want to fetch numbers as Integer or Float by its actual value, use
+the following code:
+
+    # Fetch numbers as Integer when their fractional part is zero.
+    # Otherwise, Float. For example when a column contains 10 and
+    # 10.1, they are fetched as Integer and Float respectively.
+    OCI8::BindType::Mapping[:number] = OCI8::BindType::BasicNumberType

data/ext/oci8/apiwrap.yml

@@ -321,13 +321,6 @@ OCILobLocatorIsInit:
             - CONST OCILobLocator *locp
             - boolean *is_initialized
 
-# round trip: 1
-OCILogoff:
-  :version: 800
-  :args:
-            - OCISvcCtx *svchp
-            - OCIError *errhp
-
 # round trip: 0
 OCINumberAbs:
   :version: 800
@@ -1149,21 +1142,6 @@ OCIIntervalSetYearMonth:
             - sb4 mnth
             - OCIInterval *result
 
-# round trip: 1
-OCILogon2_nb:
-  :version: 900
-  :args:
-            - OCIEnv *envhp
-            - OCIError *errhp
-            - OCISvcCtx **svchp
-            - CONST text *username
-            - ub4 uname_len
-            - CONST text *password
-            - ub4 passwd_len
-            - CONST text *dbname
-            - ub4 dbname_len
-            - ub4 mode
-
 # round trip: 0 (not docmented. I guess.)
 OCIRowidToChar:
   :version: 900

data/ext/oci8/error.c

@@ -75,6 +75,21 @@ retry:
     return rb_external_str_new_with_enc(errbuf, len, oci8_encoding);
 }
 
+/*
+ * Don't call rb_class_new_instance() with more than one argument in this function.
+ * This may be called before OCIError#initialize is defined in lib/oci8/oci8.rb.
+ */
+static VALUE oci_exception_new(VALUE klass, VALUE msg, VALUE code, VALUE sql, VALUE parse_error_offset)
+{
+    VALUE obj = rb_class_new_instance(NIL_P(msg) ? 0 : 1, &msg, klass);
+    if (rb_obj_is_kind_of(obj, eOCIError)) {
+        rb_ivar_set(obj, oci8_id_at_code, code);
+        rb_ivar_set(obj, oci8_id_at_sql, sql);
+        rb_ivar_set(obj, oci8_id_at_parse_error_offset, parse_error_offset);
+    }
+    return obj;
+}
+
 static VALUE oci8_make_exc(dvoid *errhp, sword status, ub4 type, OCIStmt *stmthp, const char *file, int line)
 {
     VALUE exc;
@@ -84,24 +99,19 @@ static VALUE oci8_make_exc(dvoid *errhp, sword status, ub4 type, OCIStmt *stmthp
     VALUE parse_error_offset = Qnil;
     VALUE sql = Qnil;
     int rv;
-    VALUE args[4];
-    int numarg = 1;
 
     switch (status) {
     case OCI_ERROR:
         exc = eOCIError;
         msg = get_error_msg(errhp, type, "Error", &errcode);
-        numarg = 4;
         break;
     case OCI_SUCCESS_WITH_INFO:
         exc = eOCISuccessWithInfo;
         msg = get_error_msg(errhp, type, "Error", &errcode);
-        numarg = 4;
         break;
     case OCI_NO_DATA:
         exc = eOCINoData;
         msg = get_error_msg(errhp, type, "No Data", &errcode);
-        numarg = 4;
         break;
     case OCI_INVALID_HANDLE:
         exc = eOCIInvalidHandle;
@@ -138,11 +148,7 @@ static VALUE oci8_make_exc(dvoid *errhp, sword status, ub4 type, OCIStmt *stmthp
             sql = rb_external_str_new_with_enc(TO_CHARPTR(text), size, oci8_encoding);
         }
     }
-    args[0] = msg;
-    args[1] = INT2FIX(errcode);
-    args[2] = sql;
-    args[3] = parse_error_offset;
-    exc = rb_class_new_instance(numarg, args, exc);
+    exc = oci_exception_new(exc, msg, INT2FIX(errcode), sql, parse_error_offset);
     return set_backtrace(exc, file, line);
 }
 
@@ -172,22 +178,6 @@ 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;
@@ -217,9 +207,6 @@ 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)
@@ -278,11 +265,9 @@ VALUE oci8_get_error_message(ub4 msgno, const char *default_msg)
 void oci8_do_raise_by_msgno(ub4 msgno, const char *default_msg, const char *file, int line)
 {
     VALUE msg = oci8_get_error_message(msgno, default_msg);
-    VALUE args[2];
-    args[0] = msg;
-    args[1] = INT2FIX(-1);
+    VALUE exc = oci_exception_new(eOCIError, msg, INT2FIX(-1), Qnil, Qnil);
 
-    rb_exc_raise(set_backtrace(rb_class_new_instance(2, args, eOCIError), file, line));
+    rb_exc_raise(set_backtrace(exc, file, line));
 }
 
 void oci8_check_error_(sword status, oci8_base_t *base, OCIStmt *stmthp, const char *file, int line)