ruby-oci8 2.2.1-x86-mingw32 → 2.2.2-x86-mingw32

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

data/lib/oci8/connection_pool.rb

@@ -13,17 +13,88 @@ class OCI8
   #
   # This is equivalent to Oracle JDBC Driver {OCI Connection Pooling}[http://docs.oracle.com/cd/E11882_01/java.112/e16548/ociconpl.htm#JJDBC28789].
   #
-  # Usage:
+  # Note that this is different with generally called connection pooling.
+  # Generally connection pooling caches connections in a pool.
+  # When an application needs a new connection, a connection is got from
+  # the pool. So that the amount of time to establish a connection is
+  # reduced. However connection pooling in ruby-oci8 is different with
+  # above.
+  #
+  # One Oracle connection is devided into two layers: One is physical
+  # connection such as TCP/IP. The other is logical connection which
+  # is used by an application. The connection pooling in ruby-oci8
+  # caches physical connections in a pool, not logical connections.
+  # When an application needs a new connection, a logical connection
+  # is created via a physical connection, which needs time to
+  # establish a connection unlike generally called connection pooling.
+  # When an application sends a query via a logical connection, a
+  # physical connection is got from the pool. The physical connection
+  # returns to the pool automatically when the query finishes.
+  # As long as logical connections are used sequentially, only one
+  # physical connection is used. When an application sends
+  # queries at a time, it needs more than one physical connection
+  # because one physical connection cannot transmit more then one
+  # query at a time.
+  #
+  # Example:
   #   # Create a connection pool.
+  #   # The number of initial physical connections: 1
+  #   # The number of maximum physical connections: 5
+  #   # the connection increment parameter: 2
   #   # username and password are required to establish an implicit primary session.
   #   cpool = OCI8::ConnectionPool.new(1, 5, 2, username, password, database)
   #   
-  #   # Get a session from the pool.
+  #   #   The number of physical connections: 1
+  #   #   The number of logical connections: 0
+  #   
+  #   # Create a session.
   #   # Pass the connection pool to the third argument.
   #   conn1 = OCI8.new(username, password, cpool)
   #   
-  #   # Get another session.
+  #   # One logical connection was created.
+  #   #   The number of physical connections: 1
+  #   #   The number of logical connections: 1
+  #   
+  #   # Create another session.
   #   conn2 = OCI8.new(username, password, cpool)
+  #   
+  #   # Another logical connection was created.
+  #   #   The number of physical connections: 1
+  #   #   The number of logical connections: 2
+  #   
+  #   # Use conn1 and conn2 sequentially
+  #   conn1.exec('...')
+  #   conn2.exec('...')
+  #   
+  #   # Both logical connections use one physical connection.
+  #   #   The number of physical connections: 1
+  #   #   The number of logical connections: 2
+  #   
+  #   thr1 = Thread.new do
+  #      conn1.exec('...')
+  #   end
+  #   thr2 = Thread.new do
+  #      conn2.exec('...')
+  #   end
+  #   thr1.join
+  #   thr2.join
+  #   
+  #   # Logical connections cannot use one physical connection at a time.
+  #   # So that the number of physical connections is incremented.
+  #   #   The number of physical connections: 3
+  #   #   The number of logical connections: 2
+  #   
+  #   conn1.logoff
+  #
+  #   # One logical connection was closed.
+  #   #   The number of physical connections: 3
+  #   #   The number of logical connections: 1
+  #   
+  #   conn2.logoff
+  #   
+  #   # All logical connections were closed.
+  #   #   The number of physical connections: 3
+  #   #   The number of logical connections: 0
   #
   class ConnectionPool
 

data/lib/oci8/cursor.rb

@@ -384,12 +384,19 @@ class OCI8
       attr_set_ub4(11, rows) # OCI_ATTR_PREFETCH_ROWS(11)
     end
 
-    # Returns the number of processed rows.
-    #
-    # @return [Integer]
-    def row_count
-      # http://docs.oracle.com/cd/E11882_01/appdev.112/e10646/ociaahan.htm#sthref5498
-      attr_get_ub4(9) # OCI_ATTR_ROW_COUNT(9)
+    if OCI8::oracle_client_version >= ORAVER_12_1
+      # Returns the number of processed rows.
+      #
+      # @return [Integer]
+      def row_count
+        # https://docs.oracle.com/database/121/LNOCI/ociaahan.htm#sthref5774
+        attr_get_ub8(457) # OCI_ATTR_UB8_ROW_COUNT(457)
+      end
+    else
+      def row_count
+        # http://docs.oracle.com/cd/E11882_01/appdev.112/e10646/ociaahan.htm#sthref5498
+        attr_get_ub4(9) # OCI_ATTR_ROW_COUNT(9)
+      end
     end
 
     # Returns the text of the SQL statement prepared in the cursor.

data/lib/oci8/object.rb

@@ -78,7 +78,8 @@ EOS
   #
   # @private
   def get_tdo_by_typename(typename)
-    tdo = @name_to_tdo && @name_to_tdo[typename]
+    @name_to_tdo ||= {}
+    tdo = @name_to_tdo[typename]
     return tdo if tdo
 
     metadata = describe_any(typename)
@@ -383,8 +384,10 @@ EOS
 
       case metadata.typecode
       when :named_type
+        @is_final_type = metadata.is_final_type?
         initialize_named_type(con, metadata)
       when :named_collection
+        @is_final_type = true
         initialize_named_collection(con, metadata)
       end
     end

data/lib/oci8/oci8.rb

@@ -63,9 +63,9 @@ class OCI8
   #
   # === connecting as a privileged user
   #
-  # Set :SYSDBA or :SYSOPER to +privilege+, otherwise
-  # "username/password as sysdba" or "username/password as sysoper"
-  # as a single argument.
+  # Set :SYSDBA, :SYSOPER, :SYSASM, :SYSBACKUP, :SYSDG or :SYSKM
+  # to +privilege+, otherwise "username/password as sysdba",
+  # "username/password as sysoper", etc. as a single argument.
   #
   #   OCI8.new('sys', 'change_on_install', nil, :SYSDBA)
   # or
@@ -96,29 +96,15 @@ class OCI8
   #
   def initialize(*args)
     if args.length == 1
-      username, password, dbname, mode = parse_connect_string(args[0])
+      username, password, dbname, privilege = parse_connect_string(args[0])
     else
-      username, password, dbname, mode = args
+      username, password, dbname, privilege = args
     end
 
     if username.nil? and password.nil?
       cred = OCI_CRED_EXT
     end
-    case mode
-    when :SYSDBA
-      mode = OCI_SYSDBA
-    when :SYSOPER
-      mode = OCI_SYSOPER
-    when :SYSASM
-      if OCI8.oracle_client_version < OCI8::ORAVER_11_1
-        raise "SYSASM is not supported on Oracle version #{OCI8.oracle_client_version}"
-      end
-      mode = OCI_SYSASM
-    when nil
-      # do nothing
-    else
-      raise "unknown privilege type #{mode}"
-    end
+    auth_mode = to_auth_mode(privilege)
 
     stmt_cache_size = OCI8.properties[:statement_cache_size]
     stmt_cache_size = nil if stmt_cache_size == 0
@@ -128,6 +114,12 @@ class OCI8
       @pool = dbname # to prevent GC from freeing the connection pool.
       dbname = dbname.send(:pool_name)
       attach_mode |= 0x0200 # OCI_CPOOL and OCI_LOGON2_CPOOL
+    else
+      tcp_connect_timeout = OCI8::properties[:tcp_connect_timeout]
+      connect_timeout = OCI8::properties[:connect_timeout]
+      if tcp_connect_timeout || connect_timeout
+        dbname = to_connect_descriptor(dbname, tcp_connect_timeout, connect_timeout)
+      end
     end
     if stmt_cache_size
       # enable statement caching
@@ -148,7 +140,11 @@ class OCI8
         @session_handle.send(:attr_set_string, 424, "ruby-oci8 : #{OCI8::VERSION}")
       end
       server_attach(dbname, attach_mode)
-      session_begin(cred ? cred : OCI_CRED_RDBMS, mode ? mode : OCI_DEFAULT)
+      if OCI8.oracle_client_version >= OCI8::ORAVER_11_1
+        self.send_timeout = OCI8::properties[:send_timeout] if OCI8::properties[:send_timeout]
+        self.recv_timeout = OCI8::properties[:recv_timeout] if OCI8::properties[:recv_timeout]
+      end
+      session_begin(cred ? cred : OCI_CRED_RDBMS, auth_mode)
     else
       # logon by the OCI function OCILogon2().
       logon2(username, password, dbname, attach_mode)
@@ -389,6 +385,10 @@ class OCI8
     # Zero means no timeout.
     # This is equivalent to {http://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF228 SQLNET.SEND_TIMEOUT} in client-side sqlnet.ora.
     #
+    # If you need to set send timeout while establishing a connection, use {file:docs/timeout-parameters.md timeout parameters in OCI8::properties} instead.
+    #
+    # Note that the connection becomes unusable on timeout.
+    #
     # If you have trouble by setting this, don't use it because it uses
     # {http://blog.jiubao.org/2015/01/undocumented-oci-handle-attributes.html an undocumented OCI handle attribute}.
     #
@@ -417,6 +417,10 @@ class OCI8
     # Zero means no timeout.
     # This is equivalent to {http://docs.oracle.com/database/121/NETRF/sqlnet.htm#NETRF227 SQLNET.RECV_TIMEOUT} in client-side sqlnet.ora.
     #
+    # If you need to set receive timeout while establishing a connection, use {file:docs/timeout-parameters.md timeout parameters in OCI8::properties} instead.
+    #
+    # Note that the connection becomes unusable on timeout.
+    #
     # If you have trouble by setting this, don't use it because it uses
     # {http://blog.jiubao.org/2015/01/undocumented-oci-handle-attributes.html an undocumented OCI handle attribute}.
     #
@@ -442,6 +446,138 @@ class OCI8
       raise NotImplementedError, 'revc_timeout= is unimplemented in this Oracle version'
     end
   end
+
+  # A helper class to bind an array to paramters in IN-condition.
+  #
+  # See {file:docs/bind-array-to-in_cond.md Bind an Array to IN-condition}
+  class InCondBindHelper
+    def initialize(bind_name_prefix, array, type = nil, length = nil)
+      bind_name_prefix = bind_name_prefix.to_s
+      if bind_name_prefix !~ /^\w+$/
+        raise ArgumentError, "The first argument doesn't consist of alphanumeric characters and underscores."
+      end
+      if array.empty?
+        # This doesn't match anything.
+        # However in-condition requires at least one value.
+        @bind_names = ":#{bind_name_prefix}_0"
+        @bind_values = [[nil, type.nil? ? String : type, length]]
+      else
+        @bind_names = Array.new(array.length) do |index|
+          ":#{bind_name_prefix}_#{index}"
+        end.join(', ')
+        first_non_nil = array.find do |e|
+          !e.nil?
+        end
+        first_non_nil = '' if first_non_nil.nil?
+        @bind_values = array.collect do |elem|
+          if elem.nil? and type.nil?
+            [elem, first_non_nil.class]
+          else
+            [elem, type, length]
+          end
+        end
+      end
+    end
+
+    def names
+      @bind_names
+    end
+
+    def values
+      @bind_values
+    end
+  end
+
+  # Creates a helper object to bind an array to paramters in IN-condition.
+  #
+  # See {file:docs/bind-array-to-in_cond.md Bind an Array to IN-condition}
+  #
+  # @param [Symbol]  bind_name_prefix prefix of the place holder name
+  # @param [Object]  array an array of values to be bound.
+  # @param [Class]   type data type. This is used as the third argument of {OCI8::Cursor#bind_param}.
+  # @param [Integer] length maximum bind length for string values. This is used as the fourth argument of {OCI8::Cursor#bind_param}.
+  # @return [OCI8::InCondBindHelper]
+  def self.in_cond(bind_name_prefix, array, type = nil, length = nil)
+    InCondBindHelper.new(bind_name_prefix, array, type, length)
+  end
+
+  private
+
+  # Converts the specified privilege name to the value passed to the
+  # fifth argument of OCISessionBegin().
+  #
+  # @private
+  def to_auth_mode(privilege)
+    case privilege
+    when :SYSDBA
+      0x00000002 # OCI_SYSDBA in oci.h
+    when :SYSOPER
+      0x00000004 # OCI_SYSOPER in oci.h
+    when :SYSASM
+      if OCI8.oracle_client_version < OCI8::ORAVER_11_1
+        raise "SYSASM is not supported on Oracle version #{OCI8.oracle_client_version}"
+      end
+      0x00008000 # OCI_SYSASM in oci.h
+    when :SYSBACKUP
+      if OCI8.oracle_client_version < OCI8::ORAVER_12_1
+        raise "SYSBACKUP is not supported on Oracle version #{OCI8.oracle_client_version}"
+      end
+      0x00020000 # OCI_SYSBKP in oci.h
+    when :SYSDG
+      if OCI8.oracle_client_version < OCI8::ORAVER_12_1
+        raise "SYSDG is not supported on Oracle version #{OCI8.oracle_client_version}"
+      end
+      0x00040000 # OCI_SYSDGD in oci.h
+    when :SYSKM
+      if OCI8.oracle_client_version < OCI8::ORAVER_12_1
+        raise "SYSKM is not supported on Oracle version #{OCI8.oracle_client_version}"
+      end
+      0x00080000 # OCI_SYSKMT in oci.h
+    when nil
+      0 # OCI_DEFAULT
+    else
+      raise "unknown privilege type #{privilege}"
+    end
+  end
+
+  @@easy_connect_naming_regex = %r{
+    ^
+    (//)?                  # preceding double-slash($1)
+    (?:\[([\h:]+)\]|([^\s:/]+)) # IPv6 enclosed by square brackets($2) or hostname($3)
+    (?::(\d+))?            # port($4)
+    (?:
+      /
+      ([^\s:/]+)?          # service name($5)
+      (?::([^\s:/]+))?     # server($6)
+      (?:/([^\s:/]+))?     # instance name($7)
+    )?
+    $
+  }x
+
+  # Parse easy connect string as described in https://docs.oracle.com/database/121/NETAG/naming.htm
+  # and add TRANSPORT_CONNECT_TIMEOUT or CONNECT_TIMEOUT.
+  #
+  # @private
+  def to_connect_descriptor(database, tcp_connect_timeout, connect_timeout)
+    if @@easy_connect_naming_regex =~ database && ($1 || $2 || $4 || $5 || $6 || $7)
+      connect_data = []
+      connect_data << "(SERVICE_NAME=#$5)"
+      connect_data << "(SERVER=#$6)" if $6
+      connect_data << "(INSTANCE_NAME=#$7)" if $7
+      desc = []
+      desc << "(CONNECT_DATA=#{connect_data.join})"
+      desc << "(ADDRESS=(PROTOCOL=TCP)(HOST=#{$2 || $3})(PORT=#{$4 || 1521}))"
+      if tcp_connect_timeout
+        desc << "(TRANSPORT_CONNECT_TIMEOUT=#{tcp_connect_timeout})"
+      end
+      if connect_timeout
+        desc << "(CONNECT_TIMEOUT=#{connect_timeout})"
+      end
+      "(DESCRIPTION=#{desc.join})"
+    else
+      database
+    end
+  end
 end
 
 class OCIError

data/lib/oci8/ocihandle.rb

@@ -425,22 +425,6 @@ class OCIHandle
   # @private
   OCI_CRED_EXT                =   2
 
-  #################################
-  #
-  # Authentication Modes
-  #
-  #################################
-
-  # for SYSDBA authorization
-  # @private
-  OCI_SYSDBA                  = 0x0002
-  # for SYSOPER authorization
-  # @private
-  OCI_SYSOPER                 = 0x0004
-  # for SYSASM authorization
-  # @private
-  OCI_SYSASM                  = 0x8000
-
   #################################
   #
   # OCI Parameter Types

data/lib/oci8/properties.rb

@@ -13,6 +13,10 @@ class OCI8
     :statement_cache_size => 0,
     :events_mode => ((OCI8.__get_prop(2) & 4) != 0), # 4 <- OCI_EVENTS in oci.h
     :cancel_read_at_exit => false,
+    :tcp_connect_timeout => nil,
+    :connect_timeout => nil,
+    :send_timeout => nil,
+    :recv_timeout => nil,
   }
 
   # @private
@@ -53,6 +57,11 @@ class OCI8
     when :cancel_read_at_exit
       val = val ? true : false
       OCI8.__set_prop(3, val)
+    when :tcp_connect_timeout, :connect_timeout, :send_timeout, :recv_timeout
+      if !val.nil?
+        val = val.to_i
+        raise ArgumentError, "The property value for :#{name} must be nil or a positive integer." if val <= 0
+      end
     end
     super(name, val)
   end
@@ -132,6 +141,30 @@ class OCI8
   #
   #     *Since:* 2.1.8
   #
+  # [:tcp_connect_timeout]
+  #
+  #     See {file:docs/timeout-parameters.md}
+  #
+  #     *Since:* 2.2.2
+  #
+  # [:connect_timeout]
+  #
+  #     See {file:docs/timeout-parameters.md}
+  #
+  #     *Since:* 2.2.2
+  #
+  # [:send_timeout]
+  #
+  #     See {file:docs/timeout-parameters.md}
+  #
+  #     *Since:* 2.2.2
+  #
+  # [:recv_timeout]
+  #
+  #     See {file:docs/timeout-parameters.md}
+  #
+  #     *Since:* 2.2.2
+  #
   # @return [a customized Hash]
   # @since 2.0.5
   #

data/lib/oci8/version.rb

@@ -1,3 +1,3 @@
 class OCI8
-  VERSION = "2.2.1"
+  VERSION = "2.2.2"
 end

data/lib/ruby-oci8.rb

@@ -0,0 +1,4 @@
+if caller[0] !~ /\/bundler\/runtime\.rb:\d+:in `require'/
+  warn "Don't requie 'ruby-oci8'. Use \"require 'oci8'\" instead. 'ruby-oci8.rb' was added only for 'Bundler.require'."
+end
+require 'oci8'

data/ruby-oci8.gemspec

@@ -37,7 +37,7 @@ EOS
   s.has_rdoc = 'yard'
   s.authors = ['Kubo Takehiro']
   s.platform = gem_platform
-  s.license = '2-clause BSD-style license'
+  s.license = 'BSD-2-Clause'
   files = File.read('dist-files').split("\n")
   if gem_platform == Gem::Platform::RUBY
     s.extensions << 'ext/oci8/extconf.rb'

data/test/setup_test_object.sql

@@ -10,6 +10,10 @@ drop type rb_test_obj_elem_array
 /
 drop type rb_test_obj_elem
 /
+drop type rb_test_obj_sub
+/
+drop type rb_test_obj_base
+/
 create type rb_test_obj_elem as object (
   x integer,
   y integer
@@ -116,7 +120,7 @@ create or replace type body rb_test_obj is
 
   static function test_object_version return integer is
   begin
-    return 2;
+    return 3;
   end;
 
   static function class_func(n number) return rb_test_obj is
@@ -167,5 +171,21 @@ begin
   end loop;
 end;
 /
-commit
+
+create type rb_test_obj_base as object (
+   id varchar2(30)
+) not final
+/
+create type rb_test_obj_sub under rb_test_obj_base (
+   subid varchar2(30)
+) final
+/
+create or replace function rb_test_obj_get_object(get_base integer) return rb_test_obj_base is
+begin
+  if get_base = 0 then
+    return rb_test_obj_base('base');
+  else
+    return rb_test_obj_sub('sub', 'subid');
+  end if;
+end;
 /

data/test/test_all.rb

@@ -5,6 +5,7 @@ require "#{srcdir}/config"
 
 require "#{srcdir}/test_oradate"
 require "#{srcdir}/test_oranumber"
+require "#{srcdir}/test_bind_array.rb"
 require "#{srcdir}/test_bind_string"
 require "#{srcdir}/test_bind_time"
 require "#{srcdir}/test_bind_raw"

data/test/test_connstr.rb

@@ -75,4 +75,130 @@ class TestConnStr < Minitest::Test
       end
     end
   end
+
+  # https://docs.oracle.com/database/121/NETAG/naming.htm#BABJBFHJ
+  DESC_TEST_CASE =
+    [
+     # Cannot distinguish net service names from easy connect strings in this case.
+     ["sales-server", nil, nil, "sales-server"],
+     # Easy Connect string with host.
+     ["//sales-server", nil, nil, <<EOS],
+(DESCRIPTION=
+   (CONNECT_DATA=
+       (SERVICE_NAME=))
+   (ADDRESS=
+       (PROTOCOL=TCP)
+       (HOST=sales-server)
+       (PORT=1521)))
+EOS
+     # Easy Connect string with host and port.
+     ["sales-server:3456", nil, nil, <<EOS],
+(DESCRIPTION=
+   (CONNECT_DATA=
+       (SERVICE_NAME=))
+   (ADDRESS=
+       (PROTOCOL=TCP)
+       (HOST=sales-server)
+       (PORT=3456)))
+EOS
+     # The host name is sales-server and the service name is sales.
+     ["sales-server/sales", nil, nil, <<EOS],
+(DESCRIPTION=
+  (CONNECT_DATA=
+     (SERVICE_NAME=sales))
+  (ADDRESS=
+     (PROTOCOL=TCP)
+     (HOST=sales-server)
+     (PORT=1521)))
+EOS
+     # Easy Connect string with IPv6 address.
+     ["[2001:0db8:0:0::200C:417A]:80/sales", nil, nil, <<EOS],
+(DESCRIPTION=
+  (CONNECT_DATA=
+      (SERVICE_NAME=sales))
+  (ADDRESS=
+      (PROTOCOL=TCP)
+      (HOST=2001:0db8:0:0::200C:417A)
+      (PORT=80)))
+EOS
+     # Easy Connect string with IPv6 host address.
+     ["sales-server:80/sales", nil, nil, <<EOS],
+(DESCRIPTION=
+  (CONNECT_DATA=
+      (SERVICE_NAME=sales))
+  (ADDRESS=
+      (PROTOCOL=TCP)
+      (HOST=sales-server)
+      (PORT=80)))
+EOS
+     # Easy Connect string with host, service name, and server.
+     ["sales-server/sales:dedicated/inst1", nil, nil, <<EOS],
+(DESCRIPTION=
+  (CONNECT_DATA=
+      (SERVICE_NAME=sales)
+      (SERVER=dedicated)
+      (INSTANCE_NAME=inst1))
+  (ADDRESS=
+      (PROTOCOL=TCP)
+      (HOST=sales-server)
+      (PORT=1521)))
+EOS
+      ["sales-server//inst1", nil, nil, <<EOS],
+(DESCRIPTION=
+   (CONNECT_DATA=
+      (SERVICE_NAME=)
+      (INSTANCE_NAME=inst1))
+   (ADDRESS=
+      (PROTOCOL=TCP)
+      (HOST=sales-server)
+      (PORT=1521)))
+EOS
+     # 
+     ["sales-server/sales", 20, nil, <<EOS],
+(DESCRIPTION=
+  (CONNECT_DATA=
+     (SERVICE_NAME=sales))
+  (ADDRESS=
+     (PROTOCOL=TCP)
+     (HOST=sales-server)
+     (PORT=1521))
+  (TRANSPORT_CONNECT_TIMEOUT=20))
+EOS
+     # 
+     ["sales-server/sales", nil, 30, <<EOS],
+(DESCRIPTION=
+  (CONNECT_DATA=
+     (SERVICE_NAME=sales))
+  (ADDRESS=
+     (PROTOCOL=TCP)
+     (HOST=sales-server)
+     (PORT=1521))
+  (CONNECT_TIMEOUT=30))
+EOS
+     #
+     ["sales-server/sales", 20, 30, <<EOS],
+(DESCRIPTION=
+  (CONNECT_DATA=
+     (SERVICE_NAME=sales))
+  (ADDRESS=
+     (PROTOCOL=TCP)
+     (HOST=sales-server)
+     (PORT=1521))
+  (TRANSPORT_CONNECT_TIMEOUT=20)
+  (CONNECT_TIMEOUT=30))
+EOS
+    ]
+
+  def test_connect_descriptor
+    obj = OCI8.allocate # create an uninitialized object.
+    DESC_TEST_CASE.each do |test_case|
+      easy_connect_string = test_case[0]
+      tcp_connnect_timeout= test_case[1]
+      outbound_connnect_timeout = test_case[2]
+      expected_result = test_case[3].gsub(/\s/, '')
+      # use instance_eval to call a private method to_connect_descriptor
+      result = obj.instance_eval { to_connect_descriptor(easy_connect_string, tcp_connnect_timeout, outbound_connnect_timeout) }
+      assert_equal(expected_result, result, easy_connect_string)
+    end
+  end
 end

data/test/test_object.rb

@@ -22,7 +22,7 @@ begin
 
   begin
     version = RbTestObj.test_object_version(conn)
-    error_message = "Invalid test object version" if version != 2
+    error_message = "Invalid test object version" if version != 3
   rescue NoMethodError
     raise unless $!.to_s.include?('test_object_version')
     error_message = "rb_test_obj.test_object_version is not declared."
@@ -48,6 +48,12 @@ EOS
 class RbTestIntArray < OCI8::Object::Base
 end
 
+class RbTestObjBase < OCI8::Object::Base
+end
+
+class RbTestObjSub < RbTestObjBase
+end
+
 class TestObj1 < Minitest::Test
   Delta = 0.00001
 
@@ -456,4 +462,23 @@ EOS
       assert_equal(ary ? ary[2] : nil, csr[:out3])
     end
   end
+
+  def test_get_subtype
+    csr = @conn.parse("BEGIN :result := rb_test_obj_get_object(:1); END;")
+    csr.bind_param(1, nil, RbTestObjBase)
+    csr.bind_param(2, nil, Integer)
+
+    csr[2] = 0
+    csr.exec
+    val = csr[1]
+    assert_instance_of(RbTestObjBase, val)
+    assert_equal(val.id, 'base')
+
+    csr[2] = 1
+    csr.exec
+    val = csr[1]
+    assert_instance_of(RbTestObjSub, val)
+    assert_equal(val.id, 'sub')
+    assert_equal(val.subid, 'subid')
+  end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: ruby-oci8
 version: !ruby/object:Gem::Version 
-  hash: 5
+  hash: 3
   prerelease: false
   segments: 
   - 2
   - 2
-  - 1
-  version: 2.2.1
+  - 2
+  version: 2.2.2
 platform: x86-mingw32
 authors: 
 - Kubo Takehiro
@@ -15,7 +15,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2015-11-01 00:00:00 +09:00
+date: 2016-04-24 00:00:00 +09:00
 default_executable: 
 dependencies: []
 
@@ -42,13 +42,16 @@ files:
 - 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
 - lib/.document
 - lib/oci8.rb
 - lib/dbd/OCI8.rb
@@ -68,6 +71,7 @@ files:
 - 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
@@ -96,12 +100,13 @@ files:
 - test/test_rowid.rb
 - lib/oci8lib_220.so
 - lib/oci8lib_191.so
+- lib/oci8lib_230.so
 - lib/oci8lib_200.so
 - lib/oci8lib_210.so
 has_rdoc: true
 homepage: http://www.rubydoc.info/github/kubo/ruby-oci8
 licenses: 
-- 2-clause BSD-style license
+- BSD-2-Clause
 post_install_message: 
 rdoc_options: []