ruby-oci8 2.2.1 → 2.2.2

data/.yardopts

@@ -11,9 +11,4 @@
 NEWS
 COPYING
 COPYING_old
-docs/install-full-client.md
-docs/install-instant-client.md
-docs/install-binary-package.md
-docs/install-on-osx.md
-docs/platform-specific-issues.md
-docs/report-installation-issue.md
+docs/*.md

data/ChangeLog

@@ -1,3 +1,101 @@
+2016-04-24  Kubo Takehiro  <kubo@jiubao.org>
+	* mkpkg-win32.rb: Added to compile mingw32 packages.
+	* dist-files: Updated to include docs/report-installation-issue.md.
+
+2016-04-24  Kubo Takehiro  <kubo@jiubao.org>
+	* NEWS: Add changes between 2.2.1 and 2.2.2.
+	* lib/oci8/version.rb: update to 2.2.2.
+
+2016-04-24  Kubo Takehiro  <kubo@jiubao.org>
+	* docs/report-installation-issue.md: Use RbConfig::CONFIG instead of
+	   deprecated Config::CONFIG.
+
+2016-04-24  Kubo Takehiro  <kubo@jiubao.org>
+	* lib/oci8/oci8.rb: Add OCI8::in_cond and OCI8:InCondBindHelper.
+	* test/test_all.rb, test/test_bind_array.rb: Add test of OCI8::in_cond.
+	* README.md, docs/bind-array-to-in_cond.md: Add document of OCI8::in_cond.
+
+2016-04-10  Kubo Takehiro  <kubo@jiubao.org>
+	* lib/oci8/connection_pool.rb: update document.
+
+2016-03-27  Kubo Takehiro  <kubo@jiubao.org>
+	* lib/oci8/object.rb: Suppress warning: instance variable
+	    @name_to_tdo not initialized.
+
+2016-03-27  Kubo Takehiro  <kubo@jiubao.org>
+	* ext/oci8/apiwrap.yml, ext/oci8/metadata.c, ext/oci8/object.c,
+	  ext/oci8/oci8.h, lib/oci8/object.rb, test/setup_test_object.sql,
+	  test/test_object.rb: Check object type from each object instance
+	    when an Oracle object is got from a bind parameter.
+	    (github issue #119)
+
+2016-03-27  Kubo Takehiro  <kubo@jiubao.org>
+	* lib/ruby-oci8.rb: Added for 'Bundler.require'.
+	    (github issue #114)
+	* dist-files: Add lib/ruby-oci8.rb.
+
+2016-03-27  Kubo Takehiro  <kubo@jiubao.org>
+	* README.md, docs/timeout-parameters.md, lib/oci8/oci8.rb:
+	    Update documents about timeout parameters.
+
+2016-03-18  Kubo Takehiro  <kubo@jiubao.org>
+	* ext/oci8/oraconf.rb: Fix for mswin64.
+
+2016-03-15  Kubo Takehiro  <kubo@jiubao.org>
+	* docs/conflicts-local-connections-and-processes.md: Add a document
+	    about conflicts between local connections and child process
+	    handling on Unix.
+	* README.md: Add a link to a newly added file.
+
+2016-03-13  Kubo Takehiro  <kubo@jiubao.org>
+	* ruby-oci8.gemspec: Change the license name in gemspec to suppress the
+	   following warning.
+	     WARNING: license value '2-clause BSD-style license' is invalid.
+	     Use a license identifier from http://spdx.org/licenses or 'Nonstandard'
+	     for a nonstandard license.
+
+2016-01-29  Kubo Takehiro  <kubo@jiubao.org>
+	* lib/oci8/oci8.rb, lib/oci8/properties.rb: Rename outbound_connect_timeout in
+	   OCI8::properties to connect_timeout.
+	* docs/timeout-parameters.md: Revise document.
+
+2015-12-20  Kubo Takehiro  <kubo@jiubao.org>
+	* lib/oci8/cursor.rb: Use OCI_ATTR_UB8_ROW_COUNT to get the number of processed rows
+	    if Oracle client version is 12c or upper.
+
+2015-12-20  Kubo Takehiro  <kubo@jiubao.org>
+	* lib/oci8/oci8.rb, lib/oci8/properties.rb, test/test_connstr.rb:
+	    Support tcp_connect_timeout, connect_timeout, send_timeout and
+	    recv_timeout in OCI8::properties.
+	* .yardopts, dist-files, docs/timeout-parameters.md: Add document
+	    about timeout parameters.
+
+2015-12-19  Kubo Takehiro  <kubo@jiubao.org>
+	* lib/oci8/oci8.rb, lib/oci8/ocihandle.rb: Support SYSBACKUP, SYSDG
+	    and SYSKM privileges.
+	    (github issue #110)
+
+2015-12-19  Kubo Takehiro  <kubo@jiubao.org>
+	* ext/oci8/plthook_win32.c: Fix bug introduced by the previous commit
+	    for mingw32 64-bit compiler.
+	    (github issue #113)
+
+2015-12-18  Kubo Takehiro  <kubo@jiubao.org>
+	* ext/oci8/plthook_win32.c, ext/oci8/extconf.rb: Import the latest
+	    plthook_win32.c for cygwin. Ruby-oci8 had not been compiled on
+	    cygwin since 2.1.8.
+	    (github issue #113)
+
+2015-12-18  Kubo Takehiro  <kubo@jiubao.org>
+	* ext/oci8/oraconf.rb: Fix a linkage error on cygwin and mingw32
+	    when installing without `--with-runtime-check`.
+	    This bug was introduced in ruby-oci8 2.2.1.
+	    (github issue #113)
+
+2015-11-28  Kubo Takehiro  <kubo@jiubao.org>
+	* ext/oci8/oraconf.rb: Check the default value of DYLD_FALLBACK_LIBRARY_PATH
+	    after checking OCI_DIR. (OS X only)
+
 2015-11-01  Kubo Takehiro  <kubo@jiubao.org>
 	* NEWS: Add changes between 2.2.0.2 and 2.2.1.
 	* lib/oci8/version.rb: update to 2.2.1.

data/NEWS

@@ -1,5 +1,52 @@
 # @markup markdown
 
+2.2.2
+=====
+
+New Features
+------------
+
+### Add OCI8::in_cond
+
+This is a helper method to bind an array to parameters in IN-conditions.
+See {file:docs/bind-array-to-in_cond.md  Bind an Array to IN-condition}
+
+### Add timeout parameters in OCI8::properties
+
+See {file:docs/timeout-parameters.md Timeout Parameters}
+
+### Support SYSBACKUP, SYSDG and SYSKM privileges.
+
+For example:
+
+    OCI8.new(username, password, database, :SYSBACKUP)
+
+(github issue #110)
+
+### Support {OCI8::Cursor#row_count} over 4G (Oracle 12c client only)
+
+Fixed Issues
+------------
+
+### Fix type mapping of subtypes of Oracle object
+
+github issue #119
+
+### Fix compile error on cygwin since ruby-oci8 2.1.8.
+
+github issue #113
+
+### Fix compile error when the ruby was compiled by Visual Studio 64bit.
+
+Other Changes
+-------------
+
+-   Suppress warning: instance variable @name_to_tdo not initialized.
+
+
+-   Check the default value of DYLD_FALLBACK_LIBRARY_PATH after checking OCI_DIR on installation. (OS X only)
+
+
 2.2.1
 =====
 
@@ -9,7 +56,7 @@ New Features
 ### Add OCI8::Metadata::Boolean
 
 Support boolean type binding. This feature requires Oracle 12c client and server.
-This doens't work when either Oracle server or client is 11g or lower.
+Binding a boolean value fails when either Oracle server or client is 11g or lower.
 
 Fixed Issues
 ------------

data/README.md

@@ -41,6 +41,13 @@ Report issues
 * {file:docs/report-installation-issue.md Report Installation Issues}
 * [The issues page on github](https://github.com/kubo/ruby-oci8/issues)
 
+Other documents
+===============
+
+* {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/bind-array-to-in_cond.md Bind an Array to IN-condition}
+
 License
 =======
 

data/dist-files

@@ -10,13 +10,16 @@ metaconfig
 pre-distclean.rb
 ruby-oci8.gemspec
 setup.rb
+docs/bind-array-to-in_cond.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/osx-install-dev-tools.png
 docs/platform-specific-issues.md
 docs/report-installation-issue.md
+docs/timeout-parameters.md
 ext/oci8/.document
 ext/oci8/MANIFEST
 ext/oci8/apiwrap.c.tmpl
@@ -73,6 +76,7 @@ lib/oci8/ocihandle.rb
 lib/oci8/oracle_version.rb
 lib/oci8/properties.rb
 lib/oci8/version.rb
+lib/ruby-oci8.rb
 test/README
 test/config.rb
 test/setup_test_object.sql

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

@@ -0,0 +1,38 @@
+@ Bind an Array to IN-condition
+
+Bind an Array to IN-condition
+=============================
+
+Binding an arbitrary-length array to IN-condition is not simple.
+You need to create an SQL statement containing a comma-separated
+list whose length is same with the input data.
+
+Example:
+
+    ids = [ ... ] # an arbitrary-length array containing user IDs.
+    
+    place_holder_string = Array.new(ids.length) {|index| ":id_#{index}"}.join(', ')
+    # place_holder_string is:
+    #   ":id_0" if ids.length == 1
+    #   ":id_0, :id_1" if ids.length == 2
+    #     ...
+    cursor = conn.parse("select * from users where id in (#{place_holder_string})")
+    ids.each_with_index do |id, index|
+      cursor.bind_param("id#{index}", id) # bind each element
+    end
+    cursor.exec()
+
+However this is awkward. So {OCI8.in_cond} was added in ruby-oci8 2.2.2.
+The above code is rewritten as follows:
+
+    ids = [ ... ] # an arbitrary-length array containing user IDs.
+    
+    in_cond = OCI8::in_cond(:id, ids)]
+    cursor = conn.exec("select * from users where id in (#{in_cond.names})", *in_cond.values)
+
+or
+
+    ids = [ ... ] # an arbitrary-length array containing user IDs.
+    
+    in_cond = OCI8::in_cond(:id, ids, Integer) # set the data type explicitly
+    cursor = conn.exec("select * from users where id in (#{in_cond.names})", *in_cond.values)

data/docs/conflicts-local-connections-and-processes.md

@@ -0,0 +1,95 @@
+# @title Conflicts between Local Connections and Child Process Handling on Unix
+
+Background
+==========
+
+When a local (not-TCP) Oracle connection is established on Unix,
+Oracle client library changes signal handlers in the process to reap
+all dead child processes. However it conflicts with child process
+handling in ruby.
+
+Problem 1: It trashes child process handling of Open3::popen.
+==========
+
+    require 'oci8'
+    require 'open3'
+    
+    Open3::popen3('true') do |i, o, e, w|
+      p w.value
+    end
+    
+    conn = OCI8.new(username, password)
+    puts "establish a local connection"
+    
+    Open3::popen3('true') do |i, o, e, w|
+      p w.value
+    end
+
+The above code outputs the following result:
+
+    #<Process::Status: pid 19236 exit 0>
+    establish a local connection
+    nil
+
+`w.value` after a local connection doesn't work because Oracle reaps
+the child process on the process termination before ruby detects it.
+
+Problem 2: It creates defunct processes after disconnection if signal handlers are reset.
+==========
+
+The `system` function overwrites signal handlers.
+It fixes the problem 1 as follows.
+
+    require 'oci8'
+    require 'open3'
+    
+    Open3::popen3('true') do |i, o, e, w|
+      p w.value
+    end
+    
+    conn = OCI8.new(username, password) # Signal handlers are changed here.
+    puts "establish a local connection"
+    system('true') # Signal handlers are reset here.
+    
+    Open3::popen3('true') do |i, o, e, w|
+      p w.value
+    end
+
+The above code outputs the following result:
+
+    #<Process::Status: pid 19652 exit 0>
+    establish a local connection
+    #<Process::Status: pid 19656 exit 0>
+
+`w.value` after a local connection works.
+
+However it makes another problem.
+
+    require 'oci8'
+    
+    conn = OCI8.new(username, password) # Signal handlers are changed here.
+    # An Oracle server process is created here.
+    puts "establish a local connection"
+    system('true') # Signal handlers are reset here.
+    
+    conn.logoff # The Oracle server process exits and become defunct.
+    
+    # ... do other stuffs...
+
+If a program repeatedly creates a local connection and disconnects it,
+the number of defunct processes increases gradually.
+
+Solution: BEQUEATH_DETACH=YES
+==========
+
+By setting [BEQUEATH_DETACH=YES][] in `sqlnet.ora`, Oracle client library
+doesn't change signal handlers. The above two problems are fixed.
+
+Oracle client library reads `sqlnet.ora` in the following locations:
+
+* `$TNS_ADMIN/sqlnet.ora` if the environment variable `TNS_ADMIN`
+  is set and `$TNS_ADMIN/sqlnet.ora` exists.
+  Otherwise, `$ORACLE_HOME/network/admin/sqlnet.ora`.
+* `$HOME/.sqlnet.ora`
+
+[BEQUEATH_DETACH=YES]: https://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF183

data/docs/report-installation-issue.md

@@ -20,14 +20,14 @@ If it is a new one, post the following information to [github][].
 
          file `which ruby`
          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']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['host']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['CC']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['CFLAGS']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['LDSHARED']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['LDFLAGS']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['DLDLAGS']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['LIBS']"
+         ruby -r rbconfig -e "p RbConfig::CONFIG['GNU_LD']"
          
          # if you use gcc,
          gcc --print-prog-name=ld

data/docs/timeout-parameters.md

@@ -0,0 +1,91 @@
+# @title Timeout Parameters
+
+Timeout Parameters
+==================
+
+The following timeout parameters are available since ruby-oci8 2.2.2.
+
+* tcp_connect_timeout
+* connect_timeout
+* send_timeout
+* recv_timeout
+
+For example:
+
+    OCI8.properties[:tcp_connect_timeout] = 10
+    OCI8.properties[:connect_timeout] = 15
+    OCI8.properties[:send_timeout] = 60
+    OCI8.properties[:recv_timeout] = 60
+
+These parameters are applied only to TCP/IP connections.
+
+The first two parameters `tcp_connect_timeout` and `connect_timeout`
+are applied only to [connect descriptors][connect descriptor] using [Easy Connect Naming Method][EZCONNECT].
+If you use a net service name, you should set [TRANSPORT_CONNECT_TIMEOUT][] and/or
+[CONNECT_TIMEOUT][] in the address descriptor in `tnsnames.ora` instead of these parameters.
+If you use easy connect naming method without any of `port`, `service_name`, `server` and `instance_name`,
+you need to use `//host` to distinguish it from a net service name.
+
+The next two parameters `send_timeout` and `recv_timeout` are available on Oracle 11g client
+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).
+
+tcp_connect_timeout
+-------------------
+
+`tcp_connect_timeout` is equivalent to [TCP.CONNECT_TIMEOUT][] in the client-side `sqlnet.ora` and
+[TRANSPORT_CONNECT_TIMEOUT][] in the address descriptor.
+See description about [TCP.CONNECT_TIMEOUT][] and [TRANSPORT_CONNECT_TIMEOUT][].
+
+connect_timeout
+---------------
+
+`connect_timeout` is equivalent to [SQLNET.OUTBOUND_CONNECT_TIMEOUT][] in the client-side `sqlnet.ora`
+and [CONNECT_TIMEOUT][] in the address description.
+See description about [SQLNET.OUTBOUND_CONNECT_TIMEOUT][] and [CONNECT_TIMEOUT][].
+
+Note: this parameter isn't equivalent to login timeout. It needs the following three
+steps to establish a database connection.
+
+1. Establish a TCP/IP connection.
+2. Establish an [Oracle Net][] connection on the TCP/IP connection.
+3. Authenticate and authorize the database user.
+
+`tcp_connect_timeout` sets the timeout of the first step.
+`connect_timeout` sets the total timeout of the first and the second steps.
+There is no timeout parameter to limit the maximum time of all three steps.
+
+Use `send_timeout` and `recv_timeout` in case that a TCP/IP connection stalls
+in the third step.
+
+send_timeout
+------------
+
+`send_timeout` is equivalent to [SQLNET.SEND_TIMEOUT][] in the client-side `sqlnet.ora`.
+See description about [SQLNET.SEND_TIMEOUT][].
+
+Note that the connection becomes unusable on timeout.
+
+See also {OCI8#send_timeout=}.
+
+recv_timeout
+------------
+
+`recv_timeout` is equivalent to [SQLNET.RECV_TIMEOUT][] in the client-side `sqlnet.ora`.
+See description about [SQLNET.RECV_TIMEOUT][].
+
+Note that the connection becomes unusable on timeout.
+
+See also {OCI8#recv_timeout=}.
+
+Note: This parameter must be larger than the longest SQL execution time in your applications. 
+
+[TCP.CONNECT_TIMEOUT]: http://docs.oracle.com/database/121/NETRF/sqlnet.htm#BIIDDACA
+[SQLNET.OUTBOUND_CONNECT_TIMEOUT]: https://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF427
+[SQLNET.SEND_TIMEOUT]: http://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF228
+[SQLNET.RECV_TIMEOUT]: http://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF227
+[connect descriptor]: https://docs.oracle.com/database/121/NETRF/glossary.htm#BGBEDFBF
+[EZCONNECT]: https://docs.oracle.com/database/121/NETAG/naming.htm#NETAG255
+[CONNECT_TIMEOUT]: https://docs.oracle.com/database/121/NETRF/tnsnames.htm#NETRF666
+[TRANSPORT_CONNECT_TIMEOUT]: https://docs.oracle.com/database/121/NETRF/tnsnames.htm#NETRF1982
+[Oracle Net]: https://en.wikipedia.org/wiki/Oracle_Net_Services#Oracle_Net