ruby-oci8 2.0.2 → 2.0.3

data/ext/oci8/oraconf.rb

@@ -353,8 +353,10 @@ EOS
       end
       print <<EOS
 ---------------------------------------------------
-error messages:
-#{$!.to_s}
+Error Message:
+  #{$!.to_s.gsub(/\n/, "\n  ")}
+Backtrace:
+  #{$!.backtrace.join("\n  ")}
 ---------------------------------------------------
 See:
  * http://ruby-oci8.rubyforge.org/#{lang}/HowToInstall.html
@@ -383,15 +385,16 @@ EOS
     # get library load path names
     oci_basename = 'libclntsh'
     oci_glob_postfix = '.[0-9]*'
-    ocidata_basename = ['libociei', 'libociicus']
+    nls_data_basename = ['libociei', 'libociicus']
     @@ld_envs = %w[LD_LIBRARY_PATH]
     so_ext = 'so'
+    nls_data_ext = nil
     check_proc = nil
     case RUBY_PLATFORM
     when /mswin32|cygwin|mingw32|bccwin32/
       oci_basename = 'oci'
       oci_glob_postfix = ''
-      ocidata_basename = ['oraociei11', 'oraociicus11', 'oraociei10', 'oraociicus10']
+      nls_data_basename = ['oraociei11', 'oraociicus11', 'oraociei10', 'oraociicus10']
       @@ld_envs = %w[PATH]
       so_ext = 'dll'
     when /i.86-linux/
@@ -434,6 +437,7 @@ EOS
       oci_glob_postfix = ''
       @@ld_envs = %w[LIBPATH]
       so_ext = 'a'
+      nls_data_ext = 'so'
     when /hppa.*-hpux/
       if [0].pack('l!').length == 4
         @@ld_envs = %w[SHLIB_PATH]
@@ -529,8 +533,9 @@ EOS
     end
 
     if ld_path
-      ocidata_basename.each do |basename|
-        if File.exist?(File.join(ld_path, "#{basename}.#{so_ext}"))
+      nls_data_ext ||= so_ext # nls_data_ext is same with so_ext by default.
+      nls_data_basename.each do |basename|
+        if File.exist?(File.join(ld_path, "#{basename}.#{nls_data_ext}"))
           puts "  #{file} looks like an instant client."
           return ld_path
         end
@@ -613,6 +618,7 @@ You need /usr/include/sys/types.h to compile ruby-oci8.
 EOS
     end
     puts "ok"
+    $stdout.flush
   end # check_ruby_header
 
   def try_link_oci
@@ -860,10 +866,33 @@ EOS
     def get_home
       oracle_home = ENV['ORACLE_HOME']
       if oracle_home.nil?
-        raise <<EOS
+        msg = <<EOS
 Set the environment variable ORACLE_HOME if Oracle Full Client.
 Append the path of Oracle client libraries to #{OraConf.ld_envs[0]} if Oracle Instant Client.
 EOS
+
+        # check sudo environment
+        sudo_command = ENV['SUDO_COMMAND']
+        if /\w*make\b/ =~ sudo_command
+          msg += <<EOS
+
+The 'sudo' command unset some environment variables for security reasons.
+Use it only when running 'make install' as follows
+     make
+     sudo make install
+EOS
+        end
+        if /\w+\/gem\b/ =~ sudo_command
+          msg += <<EOS
+
+The 'sudo' command unset some environment variables for security reasons.
+Pass required varialbes as follows
+     sudo env #{OraConf.ld_envs[0]}=$#{OraConf.ld_envs[0]} #{sudo_command}
+  or 
+     sudo env ORACLE_HOME=$ORACLE_HOME #{sudo_command}
+EOS
+        end
+        raise msg
       end
       oracle_home
     end
@@ -953,10 +982,10 @@ EOS
 
         # monkey patching!
         Object.module_eval do
-          alias :orig_link_command :link_command
-          def link_command(ldflags, opt="", libpath=$DEFLIBPATH|$LIBPATH)
-            opt = "" if opt == $libs
-            orig_link_command(ldflags, opt, libpath)
+          alias :link_command_pre_oci8 :link_command
+          def link_command(*args)
+            args[1] = "" if args[1] == $libs
+            link_command_pre_oci8(*args)
           end
         end
 

data/ext/oci8/oradate.c

@@ -3,7 +3,7 @@
  *  oradate.c
  *
  * $Author: kubo $
- * $Date: 2009-05-17 22:07:16 +0900 (Sun, 17 May 2009) $
+ * $Date: 2009-10-21 22:50:01 +0900 (Wed, 21 Oct 2009) $
  *
  * Copyright (C) 2002-2008 KUBO Takehiro <kubo@jiubao.org>
  *

data/lib/.document

@@ -1,2 +1 @@
 oci8
-oci8.rb

data/lib/oci8.rb.in

@@ -19,7 +19,7 @@ if RUBY_PLATFORM =~ /cygwin/
 end
 
 case RUBY_VERSION
-when /^1\.9\.1/
+when /^1\.9/
   require 'oci8lib_191'
 when /^1\.8/
   require 'oci8lib_18'

data/lib/oci8/.document

@@ -1,5 +1,5 @@
-oci8.rb
+datetime.rb
 object.rb
 metadata.rb
 oracle_version.rb
-
+oci8.rb

data/lib/oci8/bindtype.rb

@@ -24,6 +24,28 @@ class OCI8
       end
     end
 
+    class BigDecimal < OCI8::BindType::OraNumber
+      @@bigdecimal_is_required = false
+      def get()
+        unless @@bigdecimal_is_required
+          require 'bigdecimal'
+          @@bigdecimal_is_required = true
+        end
+        (val = super()) && val.to_d
+      end
+    end
+
+    class Rational < OCI8::BindType::OraNumber
+      @@rational_is_required = false
+      def get()
+        unless @@rational_is_required
+          require 'rational'
+          @@rational_is_required = true
+        end
+        (val = super()) && val.to_r
+      end
+    end
+
     # get/set Number (for OCI8::SQLT_NUM)
     class Number
       def self.create(con, val, param, max_array_size)
@@ -54,8 +76,8 @@ class OCI8
           if precision < 15 # the precision of double.
             klass = OCI8::BindType::Float
           else
-            # use BigDecimal instead?
-            klass = OCI8::BindType::OraNumber
+            # use BigDecimal instead
+            klass = OCI8::BindType::BigDecimal
           end
         end
         klass.new(con, val, nil, max_array_size)
@@ -156,6 +178,8 @@ end
 # bind or explicitly define
 OCI8::BindType::Mapping[String]       = OCI8::BindType::String
 OCI8::BindType::Mapping[OraNumber]    = OCI8::BindType::OraNumber
+OCI8::BindType::Mapping['BigDecimal'] = OCI8::BindType::BigDecimal
+OCI8::BindType::Mapping['Rational']   = OCI8::BindType::Rational
 OCI8::BindType::Mapping[Fixnum]       = OCI8::BindType::Integer
 OCI8::BindType::Mapping[Float]        = OCI8::BindType::Float
 OCI8::BindType::Mapping[Integer]      = OCI8::BindType::Integer
@@ -263,9 +287,9 @@ OCI8::BindType::Mapping[:number] = OCI8::BindType::Number
 # datatypes that have no explicit setting of their precision
 # and scale.
 #
-# The default mapping is Float for ruby-oci8 1.0. It is OraNumber
-# for ruby-oci8 2.0.
-OCI8::BindType::Mapping[:number_unknown_prec] = OCI8::BindType::OraNumber
+# The default mapping is Float for ruby-oci8 1.0, OraNumber for 2.0.0 ~ 2.0.2,
+# BigDecimal for 2.0.3 ~.
+OCI8::BindType::Mapping[:number_unknown_prec] = OCI8::BindType::BigDecimal
 
 # mapping for number without precision and scale.
 #
@@ -276,9 +300,9 @@ OCI8::BindType::Mapping[:number_unknown_prec] = OCI8::BindType::OraNumber
 # note: This is available only on Oracle 9.2.0.3 or above.
 # see:  Oracle 9.2.0.x Patch Set Notes.
 #
-# The default mapping is Float for ruby-oci8 1.0. It is OraNumber
-# for ruby-oci8 2.0.
-OCI8::BindType::Mapping[:number_no_prec_setting] = OCI8::BindType::OraNumber
+# The default mapping is Float for ruby-oci8 1.0, OraNumber for 2.0.0 ~ 2.0.2,
+# BigDecimal for 2.0.3 ~.
+OCI8::BindType::Mapping[:number_no_prec_setting] = OCI8::BindType::BigDecimal
 
 if defined? OCI8::BindType::BinaryDouble
   OCI8::BindType::Mapping[:binary_float] = OCI8::BindType::BinaryDouble

data/lib/oci8/compat.rb

@@ -105,4 +105,9 @@ class OCI8
     # add alias compatible with 'Oracle7 Module for Ruby'.
     alias getColNames get_col_names
   end
+
+  module BindType
+    # alias to Integer for compatibility with ruby-oci8 1.0.
+    Fixnum = Integer
+  end
 end

data/lib/oci8/datetime.rb

@@ -4,23 +4,44 @@ class OCI8
 
   module BindType
 
+    # call-seq:
+    #   OCI8::BindType.default_timezone -> :local or :utc
+    #
+    # Returns the default time zone when using Oracle 8.x client.
+    # The value is unused when using Oracle 9i or upper client.
+    #
+    # See also: OCI8::BindType::Time
+    def self.default_timezone
+      OCI8::BindType::Util.default_timezone
+    end
+
+    # call-seq:
+    #   OCI8::BindType.default_timezone = :local or :utc
+    #
+    # Sets the default time zone when using Oracle 8.x client.
+    # The value is unused when using Oracle 9i or upper client.
+    #
+    # See also: OCI8::BindType::Time
+    def self.default_timezone=(tz)
+      OCI8::BindType::Util.default_timezone = tz
+    end
+
     module Util # :nodoc:
 
       @@datetime_fsec_base = (1 / ::DateTime.parse('0001-01-01 00:00:00.000000001').sec_fraction).to_i
-      @@time_offset = ::Time.now.utc_offset
-      @@datetime_offset = ::DateTime.now.offset
 
       @@default_timezone = :local
+      begin
+        Time.new(2001, 1, 1, 0, 0, 0, '+00:00')
+        @@time_new_accepts_timezone = true  # after ruby 1.9.2
+      rescue ArgumentError
+        @@time_new_accepts_timezone = false # prior to ruby 1.9.2
+      end
+
       def self.default_timezone
         @@default_timezone
       end
 
-      # Determines default timezone of Time and DateTime retrived from Oracle.
-      # This accepts :local or :utc. The default is :local.
-      #
-      # This parameter is used when both or either of Oracle server and client
-      # version is Oracle 8i or lower. If both versions are Oracle 9i or upper,
-      # the default timezone is determined by the session timezone.
       def self.default_timezone=(tz)
         if tz != :local and tz != :utc
           raise ArgumentError, "expected :local or :utc but #{tz}"
@@ -31,6 +52,8 @@ class OCI8
       private
 
       def datetime_to_array(val, full)
+        return nil if val.nil?
+
         # year
         year = val.year
         # month
@@ -100,9 +123,16 @@ class OCI8
       end
 
       def ocidate_to_datetime(ary)
+        return nil if ary.nil?
+
         year, month, day, hour, minute, sec = ary
         if @@default_timezone == :local
-          offset = @@datetime_offset
+          if ::DateTime.respond_to? :local_offset
+            offset = ::DateTime.local_offset # Use a method defined by active support.
+          else
+            # Do as active support does.
+            offset = ::Time.local(2007).utc_offset.to_r / 86400
+          end
         else
           offset = 0
         end
@@ -110,8 +140,10 @@ class OCI8
       end
 
       def ocidate_to_time(ary)
+        return nil if ary.nil?
+
         year, month, day, hour, minute, sec = ary
-        if year >= 139
+        if @@time_new_accepts_timezone || year >= 139 || year < 0
           begin
             return ::Time.send(@@default_timezone, year, month, day, hour, minute, sec)
           rescue StandardError
@@ -123,6 +155,8 @@ class OCI8
       if OCI8.oracle_client_version >= ORAVER_9_0
 
         def ocitimestamp_to_datetime(ary)
+          return nil if ary.nil?
+
           year, month, day, hour, minute, sec, fsec, tz_hour, tz_min = ary
           if sec >= 59 and fsec != 0
             # convert to a DateTime via a String as a last resort.
@@ -143,168 +177,159 @@ class OCI8
           end
         end
 
-        def ocitimestamp_to_time(ary)
-          year, month, day, hour, minute, sec, fsec, tz_hour, tz_min = ary
+        if @@time_new_accepts_timezone
+
+          # after ruby 1.9.2
+          def ocitimestamp_to_time(ary)
+            return nil if ary.nil?
 
-          if tz_hour == 0 and tz_min == 0
-            timezone = :utc
-          elsif @@time_offset == tz_hour * 3600 + tz_min * 60
-            timezone = :local
+            year, month, day, hour, minute, sec, fsec, tz_hour, tz_min = ary
+
+            sec += fsec / Rational(1000000000)
+            utc_offset = tz_hour * 3600 + tz_min * 60
+            return ::Time.new(year, month, day, hour, minute, sec, utc_offset)
           end
-          if timezone and year >= 139
-            begin
-              # Ruby 1.9 Time class's resolution is nanosecond.
-              # But the last argument type is millisecond.
-              # 'fsec' is converted to a Float to pass sub-millisecond part.
-              return ::Time.send(timezone, year, month, day, hour, minute, sec, fsec / 1000.0)
-            rescue StandardError
+
+        else
+
+          # prior to ruby 1.9.2
+          def ocitimestamp_to_time(ary)
+            return nil if ary.nil?
+
+            year, month, day, hour, minute, sec, fsec, tz_hour, tz_min = ary
+
+            if year >= 139 || year < 0
+              begin
+                if tz_hour == 0 and tz_min == 0
+                  return ::Time.utc(year, month, day, hour, minute, sec, fsec / Rational(1000))
+                else
+                  tm = ::Time.local(year, month, day, hour, minute, sec, fsec / Rational(1000))
+                  return tm if tm.utc_offset == tz_hour * 3600 + tz_min * 60
+                end
+              rescue StandardError
+              end
             end
+            ocitimestamp_to_datetime(ary)
           end
-          ocitimestamp_to_datetime(ary)
+
         end
       end
     end
 
-    class DateTimeViaOCIDate < OCI8::BindType::OCIDate
+    class DateTimeViaOCIDate < OCI8::BindType::OCIDate # :nodoc:
       include OCI8::BindType::Util
 
       def set(val) # :nodoc:
-        val &&= datetime_to_array(val, false)
-        super(val)
+        super(datetime_to_array(val, false))
       end
 
       def get() # :nodoc:
-        val = super()
-        val ? ocidate_to_datetime(val) : nil
+        ocidate_to_datetime(super())
       end
     end
 
-    class TimeViaOCIDate < OCI8::BindType::OCIDate
+    class TimeViaOCIDate < OCI8::BindType::OCIDate # :nodoc:
       include OCI8::BindType::Util
 
       def set(val) # :nodoc:
-        val &&= datetime_to_array(val, false)
-        super(val)
+        super(datetime_to_array(val, false))
       end
 
       def get() # :nodoc:
-        val = super()
-        val ? ocidate_to_time(val) : nil
+        ocidate_to_time(super())
       end
     end
 
     if OCI8.oracle_client_version >= ORAVER_9_0
-      class DateTimeViaOCITimestamp < OCI8::BindType::OCITimestamp
+      class DateTimeViaOCITimestamp < OCI8::BindType::OCITimestamp # :nodoc:
         include OCI8::BindType::Util
 
         def set(val) # :nodoc:
-          val &&= datetime_to_array(val, true)
-          super(val)
+          super(datetime_to_array(val, true))
         end
 
         def get() # :nodoc:
-          val = super()
-          val ? ocitimestamp_to_datetime(val) : nil
+          ocitimestamp_to_datetime(super())
         end
       end
 
-      class TimeViaOCITimestamp < OCI8::BindType::OCITimestamp
+      class TimeViaOCITimestamp < OCI8::BindType::OCITimestamp # :nodoc:
         include OCI8::BindType::Util
 
         def set(val) # :nodoc:
-          val &&= datetime_to_array(val, true)
-          super(val)
+          super(datetime_to_array(val, true))
         end
 
         def get() # :nodoc:
-          val = super()
-          val ? ocitimestamp_to_time(val) : nil
+          ocitimestamp_to_time(super())
         end
       end
     end
 
-
     #--
     # OCI8::BindType::DateTime
     #++
-    # This is a helper class to bind ruby's
-    # DateTime[http://www.ruby-doc.org/core/classes/DateTime.html]
-    # object as Oracle's <tt>TIMESTAMP WITH TIME ZONE</tt> datatype.
+    # This is a helper class to select or bind Oracle data types such as
+    # <tt>DATE</tt>, <tt>TIMESTAMP</tt>, <tt>TIMESTAMP WITH TIME ZONE</tt>
+    # and <tt>TIMESTAMP WITH LOCAL TIME ZONE</tt>. The retrieved value
+    # is a \DateTime.
+    #
+    # === How to select \DataTime values.
+    #
+    # <tt>DATE</tt>, <tt>TIMESTAMP</tt>, <tt>TIMESTAMP WITH TIME ZONE</tt>
+    # and <tt>TIMESTAMP WITH LOCAL TIME ZONE</tt> are selected as a \Time
+    # by default. You change the behaviour by explicitly calling
+    # OCI8::Cursor#define as follows:
+    #
+    #   cursor = conn.parse("SELECT hiredate FROM emp")
+    #   cursor.define(1, nil, DateTime)
+    #   cursor.exec()
+    #
+    # Otherwise, you can change the default mapping for all queries.
     #
-    # == Select
+    #   # Changes the mapping for DATE
+    #   OCI8::BindType::Mapping[OCI8::SQLT_DAT] = OCI8::BindType::DateTime
+    #   
+    #   # Changes the mapping for TIMESTAMP
+    #   OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP] = OCI8::BindType::DateTime
+    #   
+    #   # Changes the mapping for TIMESTAMP WITH TIME ZONE
+    #   OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP_TZ] = OCI8::BindType::DateTime
+    #   
+    #   # Changes the mapping for TIMESTAMP WITH LOCAL TIME ZONE
+    #   OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP_LTZ] = OCI8::BindType::DateTime
     #
-    # The fetched value for a <tt>DATE</tt>, <tt>TIMESTAMP</tt>, <tt>TIMESTAMP WITH
-    # TIME ZONE</tt> or <tt>TIMESTAMP WITH LOCAL TIME ZONE</tt> column
-    # is a DateTime[http://www.ruby-doc.org/core/classes/DateTime.html].
-    # The time zone part is a session time zone if the Oracle datatype doesn't
-    # have time zone information. The session time zone is the client machine's
-    # time zone by default.
+    # === Note for default time zone
     #
-    # You can change the session time zone by executing the following SQL.
+    # The retrieved value's time zone is determined by the session time zone
+    # if its data type is <tt>DATE</tt>, <tt>TIMESTAMP</tt> or <tt>TIMESTAMP
+    # WITH LOCAL TIME ZONE</tt>.
+    #
+    # The session time zone is same with local machine's by default.
+    # It is changed by the following SQL.
     #
     #   ALTER SESSION SET TIME_ZONE='-05:00'
     #
-    # == Bind
-    #
-    # To bind a DateTime[http://www.ruby-doc.org/core/classes/DateTime.html]
-    # value implicitly:
-    #
-    #   conn.exec("INSERT INTO lunar_landings(ship_name, landing_time) VALUES(:1, :2)",
-    #             'Apollo 11',
-    #             DateTime.parse('1969-7-20 20:17:40 00:00'))
-    #
-    # The bind variable <code>:2</code> is bound as <tt>TIMESTAMP WITH TIME ZONE</tt> on Oracle.
-    #
-    # To bind explicitly:
-    #
-    #   cursor = conn.exec("INSERT INTO lunar_landings(ship_name, landing_time) VALUES(:1, :2)")
-    #   cursor.bind_param(':1', nil, String, 60)
-    #   cursor.bind_param(':2', nil, DateTime)
-    #   [['Apollo 11', DateTime.parse('1969-07-20 20:17:40 00:00'))],
-    #    ['Apollo 12', DateTime.parse('1969-11-19 06:54:35 00:00'))],
-    #    ['Apollo 14', DateTime.parse('1971-02-05 09:18:11 00:00'))],
-    #    ['Apollo 15', DateTime.parse('1971-07-30 22:16:29 00:00'))],
-    #    ['Apollo 16', DateTime.parse('1972-04-21 02:23:35 00:00'))],
-    #    ['Apollo 17', DateTime.parse('1972-12-11 19:54:57 00:00'))]
-    #   ].each do |ship_name, landing_time|
-    #     cursor[':1'] = ship_name
-    #     cursor[':2'] = landing_time
-    #     cursor.exec
-    #   end
-    #   cursor.close
-    #
-    # On setting a object to the bind variable, you can use any object
-    # which has at least three instance methods _year_, _mon_ (or _month_)
-    # and _mday_ (or _day_). If the object responses to _hour_, _min_,
-    # _sec_ or _sec_fraction_, the responsed values are used for hour,
-    # minute, second or fraction of a second respectively.
-    # If not, zeros are set. If the object responses to _offset_ or
-    # _utc_offset_, it is used for time zone. If not, the session time
-    # zone is used.
-    #
-    # The acceptable value are listed below.
-    # _year_:: -4712 to 9999 [excluding year 0]
-    # _mon_ (or _month_):: 0 to 12
-    # _mday_ (or _day_):: 0 to 31 [depends on the month]
-    # _hour_:: 0 to 23
-    # _min_:: 0 to 59
-    # _sec_:: 0 to 59
-    # _sec_fraction_:: 0 to (999_999_999.to_r / (24*60*60* 1_000_000_000)) [999,999,999 nanoseconds]
-    # _offset_:: (-12.to_r / 24) to (14.to_r / 24) [-12:00 to +14:00]
-    # _utc_offset_:: -12*3600 <= utc_offset <= 24*3600 [-12:00 to +14:00]
-    #
-    # The output value of the bind varible is always a
-    # DateTime[http://www.ruby-doc.org/core/classes/DateTime.html].
-    #
-    #   cursor = conn.exec("BEGIN :ts := current_timestamp; END")
-    #   cursor.bind_param(:ts, nil, DateTime)
-    #   cursor.exec
-    #   cursor[:ts] # => a DateTime.
-    #   cursor.close
+    # === Note for Oracle 8.x client
+    #
+    # Timestamp data types and session time zone are new features in
+    # Oracle 9i. This class is available only to fetch or bind <tt>DATE</tt>
+    # when using Oracle 8.x client.
+    #
+    # The retrieved value's time zone is determined not by the session
+    # time zone, but by the OCI8::BindType.default_timezone
+    # The time zone can be changed as follows:
+    #
+    #  OCI8::BindType.default_timezone = :local
+    #  # or
+    #  OCI8::BindType.default_timezone = :utc
+    #
+    # If you are in the regions where daylight saving time is adopted,
+    # you should use OCI8::BindType::Time.
     #
     class DateTime
       if OCI8.oracle_client_version >= ORAVER_9_0
-        def self.create(con, val, param, max_array_size)
+        def self.create(con, val, param, max_array_size) # :nodoc:
           if true # TODO: check Oracle server version
             DateTimeViaOCITimestamp.new(con, val, param, max_array_size)
           else
@@ -312,15 +337,78 @@ class OCI8
           end
         end
       else
-        def self.create(con, val, param, max_array_size)
+        def self.create(con, val, param, max_array_size) # :nodoc:
           DateTimeViaOCIDate.new(con, val, param, max_array_size)
         end
       end
     end
 
+    #--
+    # OCI8::BindType::Time
+    #++
+    # This is a helper class to select or bind Oracle data types such as
+    # <tt>DATE</tt>, <tt>TIMESTAMP</tt>, <tt>TIMESTAMP WITH TIME ZONE</tt>
+    # and <tt>TIMESTAMP WITH LOCAL TIME ZONE</tt>. The retrieved value
+    # is a \Time.
+    #
+    # === How to select \Time values.
+    #
+    # <tt>DATE</tt>, <tt>TIMESTAMP</tt>, <tt>TIMESTAMP WITH TIME ZONE</tt>
+    # and <tt>TIMESTAMP WITH LOCAL TIME ZONE</tt> are selected as a \Time
+    # by default. If the default behaviour is changed, you can select it
+    # as a \Time by explicitly calling OCI8::Cursor#define as follows:
+    #
+    #   cursor = conn.parse("SELECT hiredate FROM emp")
+    #   cursor.define(1, nil, Time)
+    #   cursor.exec()
+    #
+    # === Note for ruby prior to 1.9.2
+    #
+    # If the retrieved value cannot be represented by \Time, it become
+    # a \DateTime. The fallback is done only when the ruby is before 1.9.2
+    # and one of the following conditions are met.
+    # - The timezone part is neither local nor utc.
+    # - The time is out of the time_t[http://en.wikipedia.org/wiki/Time_t].
+    #
+    # If the retrieved value has the precision of fractional second more
+    # than 6, the fractional second is truncated to microsecond, which
+    # is the precision of standard \Time class.
+    #
+    # To avoid this fractional second truncation:
+    # - Upgrade to ruby 1.9.2, whose \Time precision is nanosecond.
+    # - Otherwise, change the defalt mapping to use \DateTime as follows.
+    #    OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP] = OCI8::BindType::DateTime
+    #    OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP_TZ] = OCI8::BindType::DateTime
+    #    OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP_LTZ] = OCI8::BindType::DateTime
+    #
+    # === Note for default time zone
+    #
+    # The retrieved value's time zone is determined by the session time zone
+    # if its data type is <tt>DATE</tt>, <tt>TIMESTAMP</tt> or <tt>TIMESTAMP
+    # WITH LOCAL TIME ZONE</tt>.
+    #
+    # The session time zone is same with local machine's by default.
+    # It is changed by the following SQL.
+    #
+    #   ALTER SESSION SET TIME_ZONE='-05:00'
+    #
+    # === Note for Oracle 8.x client
+    #
+    # Timestamp data types and session time zone are new features in
+    # Oracle 9i. This class is available only to fetch or bind <tt>DATE</tt>
+    # when using Oracle 8.x client.
+    #
+    # The retrieved value's time zone is determined not by the session
+    # time zone, but by the OCI8::BindType.default_timezone
+    # The time zone can be changed as follows:
+    #
+    #  OCI8::BindType.default_timezone = :local
+    #  # or
+    #  OCI8::BindType.default_timezone = :utc
+    #
     class Time
       if OCI8.oracle_client_version >= ORAVER_9_0
-        def self.create(con, val, param, max_array_size)
+        def self.create(con, val, param, max_array_size) # :nodoc:
           if true # TODO: check Oracle server version
             TimeViaOCITimestamp.new(con, val, param, max_array_size)
           else
@@ -328,7 +416,7 @@ class OCI8
           end
         end
       else
-        def self.create(con, val, param, max_array_size)
+        def self.create(con, val, param, max_array_size) # :nodoc:
           TimeViaOCIDate.new(con, val, param, max_array_size)
         end
       end
@@ -339,20 +427,26 @@ class OCI8
       # OCI8::BindType::IntervalYM
       #++
       #
-      # This is a helper class to bind ruby's
-      # Integer[http://www.ruby-doc.org/core/classes/Integer.html]
-      # object as Oracle's <tt>INTERVAL YEAR TO MONTH</tt> datatype.
+      # This is a helper class to select or bind Oracle data type
+      # <tt>INTERVAL YEAR TO MONTH</tt>. The retrieved value is
+      # the number of months between two timestamps.
+      #
+      # The value can be applied to \DateTime#>> to shift months.
+      # It can be applied to \Time#months_since if activisupport has
+      # been loaded.
+      #
+      # === How to select <tt>INTERVAL YEAR TO MONTH</tt>
       #
-      # == Select
+      # <tt>INTERVAL YEAR TO MONTH</tt> is selected as an Integer.
       #
-      # The fetched value for a <tt>INTERVAL YEAR TO MONTH</tt> column
-      # is an Integer[http://www.ruby-doc.org/core/classes/Integer.html]
-      # which means the months between two timestamps.
+      #   conn.exec("select (current_timestamp - hiredate) year to month from emp") do |hired_months|
+      #     puts "hired_months = #{hired_months}"
+      #   end
       #
-      # == Bind
+      # == How to bind <tt>INTERVAL YEAR TO MONTH</tt>
       #
-      # You cannot bind as <tt>INTERVAL YEAR TO MONTH</tt> implicitly.
-      # It must be bound explicitly with :interval_ym.
+      # You cannot bind a bind variable as <tt>INTERVAL YEAR TO MONTH</tt> implicitly.
+      # It must be bound explicitly by OCI8::Cursor#bind_param.
       #
       #   # output bind variable
       #   cursor = conn.parse(<<-EOS)
@@ -399,51 +493,43 @@ class OCI8
       # OCI8::BindType::IntervalDS
       #++
       #
-      # This is a helper class to bind ruby's
-      # Rational[http://www.ruby-doc.org/core/classes/Rational.html]
-      # object as Oracle's <tt>INTERVAL DAY TO SECOND</tt> datatype.
+      # (new in 2.0)
       #
-      # == Select
+      # This is a helper class to select or bind Oracle data type
+      # <tt>INTERVAL DAY TO SECOND</tt>. The retrieved value is
+      # the number of seconds between two typestamps as a \Float.
       #
-      # The fetched value for a <tt>INTERVAL DAY TO SECOND</tt> column
-      # is a Rational[http://www.ruby-doc.org/core/classes/Rational.html]
-      # or an Integer[http://www.ruby-doc.org/core/classes/Integer.html].
-      # The value is usable to apply to
-      # DateTime[http://www.ruby-doc.org/core/classes/DateTime.html]#+ and
-      # DateTime[http://www.ruby-doc.org/core/classes/DateTime.html]#-.
+      # Note that it is the number days as a \Rational if
+      # OCI8::BindType::IntervalDS.unit is :day or the ruby-oci8
+      # version is prior to 2.0.3.
       #
-      # == Bind
+      # == How to bind <tt>INTERVAL DAY TO SECOND</tt>
       #
-      # You cannot bind as <tt>INTERVAL YEAR TO MONTH</tt> implicitly.
-      # It must be bound explicitly with :interval_ds.
+      # You cannot bind a bind variable as <tt>INTERVAL DAY TO SECOND</tt>
+      # implicitly. It must be bound explicitly by OCI8::Cursor#bind_param.
       #
-      #   # output
-      #   ts1 = DateTime.parse('1969-11-19 06:54:35 00:00')
-      #   ts2 = DateTime.parse('1969-07-20 20:17:40 00:00')
+      #   # output bind variable
       #   cursor = conn.parse(<<-EOS)
       #     BEGIN
-      #       :itv := (:ts1 - :ts2) DAY TO SECOND;
+      #       :interval := (:ts1 - :ts2) DAY TO SECOND(9);
       #     END;
       #   EOS
-      #   cursor.bind_param(:itv, nil, :interval_ds)
-      #   cursor.bind_param(:ts1, ts1)
-      #   cursor.bind_param(:ts2, ts2)
+      #   cursor.bind_param(:interval, nil, :interval_ds)
+      #   cursor.bind_param(:ts1, DateTime.parse('1969-11-19 06:54:35 00:00'))
+      #   cursor.bind_param(:ts2, DateTime.parse('1969-07-20 20:17:40 00:00'))
       #   cursor.exec
-      #   cursor[:itv] # == ts1 - ts2
+      #   cursor[:interval] # => 10492615.0 seconds
       #   cursor.close
       #
-      #   # input
-      #   ts2 = DateTime.parse('1969-07-20 20:17:40 00:00')
-      #   itv = 121 + 10.to_r/24 + 36.to_r/(24*60) + 55.to_r/(24*60*60)
-      #   # 121 days, 10 hours,    36 minutes,       55 seconds
+      #   # input bind variable
       #   cursor = conn.parse(<<-EOS)
       #     BEGIN
-      #       :ts1 := :ts2 + :itv;
+      #       :ts1 := :ts2 + :interval;
       #     END;
       #   EOS
       #   cursor.bind_param(:ts1, nil, DateTime)
-      #   cursor.bind_param(:ts2, ts2)
-      #   cursor.bind_param(:itv, itv, :interval_ds)
+      #   cursor.bind_param(:ts2, DateTime.parse('1969-07-20 20:17:40 00:00'))
+      #   cursor.bind_param(:interval, 10492615.0, :interval_ds)
       #   cursor.exec
       #   cursor[:ts1].strftime('%Y-%m-%d %H:%M:%S') # => 1969-11-19 06:54:35
       #   cursor.close
@@ -453,6 +539,32 @@ class OCI8
         @@minute = @@hour / 60
         @@sec = @@minute / 60
         @@fsec = @@sec / 1000000000
+        @@unit = :second
+
+        # call-seq:
+        #   OCI8::BindType::IntervalDS.unit -> :second or :day
+        #
+        # (new in 2.0.3)
+        #
+        # Retrieves the unit of interval.
+        def self.unit
+          @@unit
+        end
+
+        # call-seq:
+        #   OCI8::BindType::IntervalDS.unit = :second or :day
+        #
+        # (new in 2.0.3)
+        #
+        # Changes the unit of interval. :second is the default.
+        def self.unit=(val)
+          case val
+          when :second, :day
+            @@unit = val
+          else
+            raise 'unit should be :second or :day'
+          end
+        end
 
         def set(val) # :nodoc:
           unless val.nil?
@@ -462,10 +574,17 @@ class OCI8
             else
               is_minus = false
             end
-            day, val = val.divmod 1
-            hour, val = (val * 24).divmod 1
-            minute, val = (val * 60).divmod 1
-            sec, val = (val * 60).divmod 1
+            if @@unit == :second
+              day, val = val.divmod 86400
+              hour, val = val.divmod 3600
+              minute, val = val.divmod 60
+              sec, val = val.divmod 1
+            else
+              day, val = val.divmod 1
+              hour, val = (val * 24).divmod 1
+              minute, val = (val * 60).divmod 1
+              sec, val = (val * 60).divmod 1
+            end
             fsec, val = (val * 1000000000).divmod 1
             if is_minus
               day = - day
@@ -483,7 +602,12 @@ class OCI8
           val = super()
           return nil if val.nil?
           day, hour, minute, sec, fsec = val
-          day + (hour * @@hour) + (minute * @@minute) + (sec * @@sec) + (fsec * @@fsec)
+          if @@unit == :second
+            fsec = fsec / 1000000000.0
+            day * 86400 + hour * 3600 + minute * 60 + sec + fsec
+          else
+            day + (hour * @@hour) + (minute * @@minute) + (sec * @@sec) + (fsec * @@fsec)
+          end
         end
       end # OCI8::BindType::IntervalDS
     end