ruby-oci8 2.2.10-x64-mingw-ucrt

data/README.md

@@ -0,0 +1,66 @@
+Ruby-oci8
+=========
+
+[![Gem Version](https://badge.fury.io/rb/ruby-oci8.svg)](http://badge.fury.io/rb/ruby-oci8)
+[![Tests](https://github.com/kubo/ruby-oci8/actions/workflows/tests.yml/badge.svg)](https://github.com/kubo/ruby-oci8/actions/workflows/tests.yml)
+
+What is ruby-oci8
+-----------------
+
+Ruby-oci8 is a ruby interface for Oracle Database. The latest version
+is available for all Oracle versions after Oracle 10g including Oracle
+Instant Client.
+
+Use ruby-oci8 2.0.6 for Oracle 8 or use ruby-oci8 2.1.8 for Oracle 9i.
+
+Note that ruby 1.8 support was dropped in ruby-oci8 2.2.0.
+Use ruby-oci8 2.1.8 for ruby 1.8.
+
+What's new
+----------
+
+See {file:NEWS}.
+
+Sample one-liner
+----------------
+
+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"
+
+Homepage
+--------
+
+* http://www.rubydoc.info/github/kubo/ruby-oci8
+
+Installation
+------------
+
+* {file:docs/install-full-client.md Install for Oracle Full Client}
+* {file:docs/install-instant-client.md Install for Oracle Instant Client}
+* {file:docs/install-binary-package.md Install Binary Package}
+* {file:docs/install-on-osx.md Install on OS X}
+
+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/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}
+* {file:docs/bind-array-to-in_cond.md Bind an Array to IN-condition}
+* {file:docs/ldap-auth-and-function-interposition.md LDAP Authentication and Function Interposition}
+
+License
+-------
+
+* {file:COPYING 2-clause BSD-style license} from ruby-oci8 2.1.3
+* {file:COPYING_old old Ruby license} until 2.1.2

data/dist-files

@@ -0,0 +1,112 @@
+.yardopts
+COPYING
+COPYING_old
+ChangeLog
+Makefile
+NEWS
+README.md
+dist-files
+metaconfig
+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/ldap-auth-and-function-interposition.md
+docs/number-type-mapping.md
+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
+ext/oci8/apiwrap.h.tmpl
+ext/oci8/apiwrap.rb
+ext/oci8/apiwrap.yml
+ext/oci8/attr.c
+ext/oci8/bind.c
+ext/oci8/connection_pool.c
+ext/oci8/encoding.c
+ext/oci8/env.c
+ext/oci8/error.c
+ext/oci8/extconf.rb
+ext/oci8/hook_funcs.c
+ext/oci8/lob.c
+ext/oci8/metadata.c
+ext/oci8/object.c
+ext/oci8/oci8.c
+ext/oci8/oci8.h
+ext/oci8/oci8lib.c
+ext/oci8/ocidatetime.c
+ext/oci8/ocihandle.c
+ext/oci8/ocinumber.c
+ext/oci8/oraconf.rb
+ext/oci8/oradate.c
+ext/oci8/oranumber_util.c
+ext/oci8/oranumber_util.h
+ext/oci8/plthook.h
+ext/oci8/plthook_elf.c
+ext/oci8/plthook_osx.c
+ext/oci8/plthook_win32.c
+ext/oci8/post-config.rb
+ext/oci8/stmt.c
+ext/oci8/thread_util.c
+ext/oci8/thread_util.h
+ext/oci8/util.c
+ext/oci8/win32.c
+lib/.document
+lib/oci8.rb
+lib/dbd/OCI8.rb
+lib/oci8/.document
+lib/oci8/bindtype.rb
+lib/oci8/check_load_error.rb
+lib/oci8/compat.rb
+lib/oci8/connection_pool.rb
+lib/oci8/cursor.rb
+lib/oci8/datetime.rb
+lib/oci8/encoding-init.rb
+lib/oci8/encoding.yml
+lib/oci8/metadata.rb
+lib/oci8/object.rb
+lib/oci8/oci8.rb
+lib/oci8/ocihandle.rb
+lib/oci8/oracle_version.rb
+lib/oci8/properties.rb
+lib/oci8/version.rb
+lib/ruby-oci8.rb
+test/README.md
+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
+test/test_bind_integer.rb
+test/test_break.rb
+test/test_clob.rb
+test/test_connection_pool.rb
+test/test_connstr.rb
+test/test_encoding.rb
+test/test_datetime.rb
+test/test_dbi.rb
+test/test_dbi_clob.rb
+test/test_error.rb
+test/test_metadata.rb
+test/test_object.rb
+test/test_oci8.rb
+test/test_oracle_version.rb
+test/test_oradate.rb
+test/test_oranumber.rb
+test/test_package_type.rb
+test/test_properties.rb
+test/test_rowid.rb

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

@@ -0,0 +1,38 @@
+# @title 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,98 @@
+# @title Conflicts between Local Connections and Child Process Handling on Unix
+
+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/hanging-after-inactivity.md

@@ -0,0 +1,63 @@
+# @title Hanging After a Long Period of Inactivity
+
+Hanging After a Long Period of Inactivity
+=========================================
+
+When a database connection hangs after a long period of inactivity,
+this document may help you.
+
+When a firewall or a NAT proxy resides between Oracle database server
+and client, it sometimes drops inactive connections as dead ones. If a
+client connects to an Oracle server and tries to use the connection
+after a long sleep (> 1 hour), the client may hang in an effort to use the
+dropped connection. This issue will be solved by setting TCP keepalive
+packets whose keepalive time parameter is smaller than the inactive
+connection timeout.
+
+TCP keepalive is enabled by [(ENABLE=broken)][] in a connect
+descriptor. If you use easy connect naming such as `//hostname/service_name`,
+ruby-oci8 sets the parameter on behalf of you when the `tcp_keepalive`
+property is set. (This is available since ruby-oci8 2.2.4.)
+
+    OCI8.properties[:tcp_keepalive] = true
+    conn = OCI8.new(username, password, '//hostname/service_name')
+
+This is equivalent to the following:
+
+    connect_descriptor = "(DESCRIPTION=(ENABLE=broken)(ADDRESS=(PROTOCOL=tcp)(HOST=hostname)(PORT=1521))(CONNECT_DATA=(SERVICE_NAME=service_name)))"
+    conn = OCI8.new(username, password, connect_descriptor)
+
+The default TCP keepalive time is two hours, which may be larger
+than the inactive connection timeout. The default
+value in the system is configurable via [procfs and sysctl on Linux][]
+or [registry parameters on Windows][]. If you have no privilege to
+customize the system, you can change per-connection keepalive time
+by the `tcp_keepalive_time` property.
+
+    OCI8.properties[:tcp_keepalive_time] = 600 # 10 minutes
+
+It is supported on the following platforms since ruby-oci8 2.2.4.
+
+* Linux i386 and x86_64
+* macOS
+* Windows x86 and x64
+* Solaris x86_64
+
+When it is set on unsupported platforms, you get `NotImplementedError`.
+
+This feature is implemented with hackish way. When
+`tcp_keepalive_time` is set, Oracle client library's
+procedure linkage table is modified to intercept [setsockopt][] system
+call. When Oracle client library issues the system call which enables
+TCP keepalive, [ruby-oci8 changes][] the per-connection TCP keepalive time
+immediately.
+
+I hope that Oracle adds a new OCI handle attribute to support this
+feature natively in the future.
+
+[(ENABLE=broken)]: https://docs.oracle.com/database/121/NETRF/tnsnames.htm#CHDCDGCE
+[procfs and sysctl on Linux]: http://tldp.org/HOWTO/TCP-Keepalive-HOWTO/usingkeepalive.html
+[registry parameters on Windows]: https://blogs.technet.microsoft.com/nettracer/2010/06/03/things-that-you-may-want-to-know-about-tcp-keepalives/
+[plthook]: https://github.com/kubo/plthook
+[setsockopt]: http://pubs.opengroup.org/onlinepubs/9699919799/functions/setsockopt.html
+[ruby-oci8 changes]: https://github.com/kubo/ruby-oci8/blob/ruby-oci8-2.2.4/ext/oci8/hook_funcs.c#L302-L318

data/docs/install-binary-package.md

@@ -0,0 +1,44 @@
+# @title Install Binary Package
+
+Install Binary Package
+======================
+
+Windows
+-------
+
+You need to install Oracle client in advance.
+If you don't have installed Oracle client, install {file:docs/install-instant-client.md#Install_Oracle_Instant_Client_Packages instant client}. Only the Basic or Basic Lite package is needed to use ruby-oci8.
+However it is better to install SQL*Plus also because it is usable to check whether
+a problem is in Oracle setting or in ruby-oci8.
+
+Run the following command to install ruby-oci8.
+
+    gem install ruby-oci8
+
+If you uses mswin32 ruby, use the following command instead.
+
+    gem install --platform x86-mingw32 ruby-oci8
+      or
+    gem install --platform x64-mingw32 ruby-oci8
+
+Other platforms
+---------------
+
+We doesn't make binary gems for other platforms.
+If you need to distribute a binary gem, compile ruby-oci8 and run the following command.
+
+    gem build ruby-oci8.gemspec -- current
+
+Note that you need to compile it on the oldest versions of the platform you support
+and for the oldest versions of the Oracle databases.
+
+If you could not fix the Oracle versions, compile ruby-oci8 and make a gem as follows:
+
+    gzip -dc ruby-oci8-VERSION.tar.gz | tar xvf -
+    cd ruby-oci8-VERSION
+    ruby setup.rb config -- --with-runtime-check
+    make
+    gem build ruby-oci8.gemspec -- current
+
+When the option `--with-runtime-check` is set, ruby-oci8 checks the Oracle version
+and available OCI functions at runtime.

data/docs/install-full-client.md

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