[ruby-oci8-commit] [272] trunk/ruby-oci8: * ext/oci8/stmt.c: (1) add rdoc comments.

nobody at rubyforge.org nobody at rubyforge.org
Sun Jul 13 06:07:11 EDT 2008


Revision: 272
Author:   kubo
Date:     2008-07-13 06:07:10 -0400 (Sun, 13 Jul 2008)

Log Message:
-----------
* ext/oci8/stmt.c: (1) add rdoc comments. (2) OCI8::Cursor#type
    returns a Fixnum when the type is not undocumented value instead
    of raising an exception.
* lib/.document, lib/oci8/.document: add new files for rdoc.
* lib/oci8/metadata.rb: fix OCI8::Metadata::Scheme#inspect.
* lib/oci8/object.rb: don't put OCI8::BindArgumentHelper, which is
    not used by users, to rdoc.
* lib/oci8/oci8.rb: (1) fix rdoc comments. (2) change the return
    value of OCI8#exec when the SQL statement is a PL/SQL block.
    (3) change the method of customize the bind type for NUMBER
    without precision and scale to same with ruby-oci8 1.0 as follows
      OCI8::BindType::Mapping[:number_unknown_prec] = ...
      OCI8::BindType::Mapping[:number_no_prec_setting] = ...

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/ext/oci8/stmt.c
    trunk/ruby-oci8/lib/oci8/metadata.rb
    trunk/ruby-oci8/lib/oci8/object.rb
    trunk/ruby-oci8/lib/oci8/oci8.rb

Added Paths:
-----------
    trunk/ruby-oci8/lib/.document
    trunk/ruby-oci8/lib/oci8/.document

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2008-07-12 13:41:38 UTC (rev 271)
+++ trunk/ruby-oci8/ChangeLog	2008-07-13 10:07:10 UTC (rev 272)
@@ -1,3 +1,18 @@
+2008-07-13  KUBO Takehiro  <kubo at jiubao.org>
+	* ext/oci8/stmt.c: (1) add rdoc comments. (2) OCI8::Cursor#type
+	    returns a Fixnum when the type is not undocumented value instead
+	    of raising an exception.
+	* lib/.document, lib/oci8/.document: add new files for rdoc.
+	* lib/oci8/metadata.rb: fix OCI8::Metadata::Scheme#inspect.
+	* lib/oci8/object.rb: don't put OCI8::BindArgumentHelper, which is
+	    not used by users, to rdoc.
+	* lib/oci8/oci8.rb: (1) fix rdoc comments. (2) change the return
+	    value of OCI8#exec when the SQL statement is a PL/SQL block.
+	    (3) change the method of customize the bind type for NUMBER
+	    without precision and scale to same with ruby-oci8 1.0 as follows
+	      OCI8::BindType::Mapping[:number_unknown_prec] = ...
+	      OCI8::BindType::Mapping[:number_no_prec_setting] = ...
+
 2008-07-12  KUBO Takehiro  <kubo at jiubao.org>
 	* lib/oci8/oci8.rb: add OraNumber#to_json and OraDate#to_json.
 	* lib/oci8/metadata.rb: define char_used?, char_size, fsprecision

Modified: trunk/ruby-oci8/ext/oci8/stmt.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/stmt.c	2008-07-12 13:41:38 UTC (rev 271)
+++ trunk/ruby-oci8/ext/oci8/stmt.c	2008-07-13 10:07:10 UTC (rev 272)
@@ -17,7 +17,6 @@
 static VALUE oci8_sym_alter_stmt;
 static VALUE oci8_sym_begin_stmt;
 static VALUE oci8_sym_declare_stmt;
-static VALUE oci8_sym_other;
 static ID id_at_column_metadata;
 static ID id_at_actual_array_size;
 static ID id_at_max_array_size;
@@ -94,33 +93,6 @@
     return Qnil;
 }
 
-/*
-=begin
---- OCIStmt#defineByPos(position, type [, length [, mode]])
-     define the datatype of fetched column.
-     You must define all column's datatype, before you fetch data.
-
-     :position
-        the position of the column. It starts from 1.
-     :type
-        the type of column.
-        ((|String|)), ((|Fixnum|)), ((|Integer|)), ((|Float|)), ((|Time|)),
-        ((<OraDate>)), ((<OraNumber>)), or ((|OCI_TYPECODE_RAW|))
-     :length
-        When the 2nd argument is
-        * ((|String|)) or ((|OCI_TYPECODE_RAW|)),
-          the max length of fetched data.
-        * otherwise,
-          its value is ignored.
-     :mode
-        ((|OCI_DEFAULT|)), or ((|OCI_DYNAMIC_FETCH|)). But now available value is
-        ((|OCI_DEFAULT|)) only. Default value is ((|OCI_DEFAULT|))
-     :return value
-        newly created ((<define handle|OCIDefine>))
-
-     correspond native OCI function: ((|OCIDefineByPos|))
-=end
- */
 static VALUE oci8_define_by_pos(VALUE self, VALUE vposition, VALUE vbindobj)
 {
     oci8_stmt_t *stmt = DATA_PTR(self);
@@ -499,7 +471,7 @@
 }
 
 /*
- * gets the type of SQL statement. Its value is one of the follows.
+ * gets the type of SQL statement as follows.
  * * OCI8::STMT_SELECT
  * * OCI8::STMT_UPDATE
  * * OCI8::STMT_DELETE
@@ -507,10 +479,14 @@
  * * OCI8::STMT_CREATE
  * * OCI8::STMT_DROP
  * * OCI8::STMT_ALTER
- * * OCI8::STMT_BEGIN
- * * OCI8::STMT_DECLARE
- * For PL/SQL statement, it returns OCI8::STMT_BEGIN or
- * OCI8::STMT_DECLARE.
+ * * OCI8::STMT_BEGIN (PL/SQL block which starts with a BEGIN keyword)
+ * * OCI8::STMT_DECLARE (PL/SQL block which starts with a DECLARE keyword)
+ * * Other Fixnum value undocumented in Oracle manuals.
+ *
+ * <em>Changes between ruby-oci8 1.0 and 2.0.</em>
+ *
+ * [ruby-oci8 2.0] OCI8::STMT_* are Symbols. (:select_stmt, :update_stmt, etc.)
+ * [ruby-oci8 1.0] OCI8::STMT_* are Fixnums. (1, 2, 3, etc.)
  */
 static VALUE oci8_stmt_get_stmt_type(VALUE self)
 {
@@ -534,10 +510,8 @@
         return oci8_sym_begin_stmt;
     case OCI_STMT_DECLARE:
         return oci8_sym_declare_stmt;
-    case 0:
-        return oci8_sym_other;
     default:
-        rb_bug("unexcepted statement type %d in OCIStmt#stmt_type", FIX2INT(stmt_type));
+        return stmt_type;
     }
 }
 
@@ -558,9 +532,10 @@
  *   cursor.exec
  *   cursor.rowid # => the inserted row's rowid
  *
- * The return value is a String in ruby-oci8 2.0 or later.
+ * <em>Changes between ruby-oci8 1.0 and 2.0.</em>
  *
- * It is an OCIRowid object in ruby-oci8 1.0.
+ * [ruby-oci8 2.0] The return value is a String.
+ * [ruby-oci8 1.0] It returns an OCIRowid object which is available only as a bind value.
  */
 static VALUE oci8_stmt_get_rowid(VALUE self)
 {
@@ -573,6 +548,9 @@
 }
 
 /*
+ * call-seq:
+ *   [key]
+ *
  * Gets the value of the bind variable.
  *
  * In case of binding explicitly, use same key with that of
@@ -618,6 +596,9 @@
 }
 
 /*
+ * call-seq:
+ *   [key] = val
+ *
  * Sets the value to the bind variable. The way to specify the
  * +key+ is same with OCI8::Cursor#[]. This is available
  * to replace the value and execute many times.
@@ -667,6 +648,9 @@
 }
 
 /*
+ * call-seq:
+ *   keys -> an Array
+ *
  * Returns the keys of bind variables as array.
  */
 static VALUE oci8_stmt_keys(VALUE self)
@@ -689,6 +673,16 @@
     return Qfalse;
 }
 
+/*
+ * call-seq:
+ *   prefetch_rows = aFixnum
+ *
+ * Set number of rows to be prefetched.
+ * This can reduce the number of network round trips when fetching
+ * many rows. The default value is one.
+ *
+ * FYI: Rails oracle adaptor uses 100 by default.
+ */
 static VALUE oci8_stmt_set_prefetch_rows(VALUE self, VALUE rows)
 {
     oci8_stmt_t *stmt = DATA_PTR(self);
@@ -756,6 +750,11 @@
 
 void Init_oci8_stmt(VALUE cOCI8)
 {
+#if 0
+    cOCIHandle = rb_define_class("OCIHandle", rb_cObject);
+    cOCI8 = rb_define_class("OCI8", cOCIHandle);
+    cOCIStmt = rb_define_class_under(cOCI8, "Cursor", cOCIHandle);
+#endif
     cOCIStmt = oci8_define_class_under(cOCI8, "Cursor", &oci8_stmt_class);
 
     oci8_sym_select_stmt = ID2SYM(rb_intern("select_stmt"));
@@ -767,7 +766,6 @@
     oci8_sym_alter_stmt = ID2SYM(rb_intern("alter_stmt"));
     oci8_sym_begin_stmt = ID2SYM(rb_intern("begin_stmt"));
     oci8_sym_declare_stmt = ID2SYM(rb_intern("declare_stmt"));
-    oci8_sym_other = ID2SYM(rb_intern("other"));
     id_at_column_metadata = rb_intern("@column_metadata");
     id_at_actual_array_size = rb_intern("@actual_array_size");
     id_at_max_array_size = rb_intern("@max_array_size");

Added: trunk/ruby-oci8/lib/.document
===================================================================
--- trunk/ruby-oci8/lib/.document	                        (rev 0)
+++ trunk/ruby-oci8/lib/.document	2008-07-13 10:07:10 UTC (rev 272)
@@ -0,0 +1 @@
+oci8

Added: trunk/ruby-oci8/lib/oci8/.document
===================================================================
--- trunk/ruby-oci8/lib/oci8/.document	                        (rev 0)
+++ trunk/ruby-oci8/lib/oci8/.document	2008-07-13 10:07:10 UTC (rev 272)
@@ -0,0 +1,3 @@
+oci8.rb
+object.rb
+metadata.rb

Modified: trunk/ruby-oci8/lib/oci8/metadata.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/metadata.rb	2008-07-12 13:41:38 UTC (rev 271)
+++ trunk/ruby-oci8/lib/oci8/metadata.rb	2008-07-13 10:07:10 UTC (rev 272)
@@ -1739,7 +1739,7 @@
       end
 
       def inspect # :nodoc:
-        "#<#{self.class.name}:(#{obj_id}) #{obj_name}>"
+        "#<#{self.class.name}:(#{obj_id}) #{obj_schema}>"
       end
     end
 

Modified: trunk/ruby-oci8/lib/oci8/object.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/object.rb	2008-07-12 13:41:38 UTC (rev 271)
+++ trunk/ruby-oci8/lib/oci8/object.rb	2008-07-13 10:07:10 UTC (rev 272)
@@ -59,7 +59,7 @@
     OCI8::TDO.new(self, metadata, klass)
   end
 
-  class BindArgumentHelper
+  class BindArgumentHelper # :nodoc:
     attr_reader :arg_str
     def initialize(*args)
       if args.length == 1 and args[0].is_a? Hash

Modified: trunk/ruby-oci8/lib/oci8/oci8.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/oci8.rb	2008-07-12 13:41:38 UTC (rev 271)
+++ trunk/ruby-oci8/lib/oci8/oci8.rb	2008-07-13 10:07:10 UTC (rev 272)
@@ -8,13 +8,13 @@
   # Executes the sql statement. The type of return value depends on
   # the type of sql statement: select; insert, update and delete;
   # create, alter and drop; and PL/SQL.
-  # 
+  #
   # When bindvars are specified, they are bound as bind variables
   # before execution.
-  # 
-  # In case of select statement with no block, it returns the
-  # instance of OCI8::Cursor.
-  # 
+  #
+  # == select statements without block
+  # It returns the instance of OCI8::Cursor.
+  #
   # example:
   #   conn = OCI8.new('scott', 'tiger')
   #   cursor = conn.exec('SELECT * FROM emp')
@@ -24,9 +24,9 @@
   #   cursor.close
   #   conn.logoff
   #
-  # In case of select statement with a block, it acts as iterator and
-  # returns the processed row counts. Fetched data is passed to the
-  # block as array. NULL value becomes nil in ruby.
+  # == select statements with a block
+  # It acts as iterator and returns the processed row counts. Fetched
+  # data is passed to the block as array. NULL value becomes nil in ruby.
   #
   # example:
   #   conn = OCI8.new('scott', 'tiger')
@@ -36,37 +36,60 @@
   #   puts num_rows.to_s + ' rows were processed.'
   #   conn.logoff
   #
-  # In case of insert, update or delete statement, it returns the
-  # number of processed rows.
-  # 
+  # == PL/SQL block (ruby-oci8 1.0)
+  # It returns the array of bind variables' values.
+  #
   # example:
   #   conn = OCI8.new('scott', 'tiger')
-  #   num_rows = conn.exec('UPDATE emp SET sal = sal * 1.1')
-  #   puts num_rows.to_s + ' rows were updated.'
+  #   conn.exec("BEGIN :str := TO_CHAR(:num, 'FM0999'); END;", 'ABCD', 123)
+  #   # => ["0123", 123]
   #   conn.logoff
   #
-  # In case of create, alter or drop statement, it returns true.
+  # Above example uses two bind variables which names are :str
+  # and :num. These initial values are "the string whose width
+  # is 4 and whose value is 'ABCD'" and "the number whose value is
+  # 123". This method returns the array of these bind variables,
+  # which may modified by PL/SQL statement. The order of array is
+  # same with that of bind variables.
   #
+  # If a block is given, it is ignored.
+  #
+  # == PL/SQL block (ruby-oci8 2.0)
+  # It returns the number of processed rows.
+  #
   # example:
   #   conn = OCI8.new('scott', 'tiger')
-  #   conn.exec('CREATE TABLE test (col1 CHAR(6))')
+  #   conn.exec("BEGIN :str := TO_CHAR(:num, 'FM0999'); END;", 'ABCD', 123)
+  #   # => 1
   #   conn.logoff
   #
-  # In case of PL/SQL statement, it returns the array of bind
-  # variables.
+  # If a block is given, the bind variables' values are passed to the block after
+  # executed.
   #
+  #   conn = OCI8.new('scott', 'tiger')
+  #   conn.exec("BEGIN :str := TO_CHAR(:num, 'FM0999'); END;", 'ABCD', 123) do |str, num|
+  #     puts str # => '0123'
+  #     puts num # => 123
+  #   end
+  #   conn.logoff
+  #
+  # FYI, the following code do same on ruby-oci8 1.0 and ruby-oci8 2.0.
+  #   conn.exec(sql, *bindvars) { |*outvars| outvars }
+  #
+  # == Other SQL statements
+  # It returns the number of processed rows.
+  #
   # example:
   #   conn = OCI8.new('scott', 'tiger')
-  #   conn.exec("BEGIN :str := TO_CHAR(:num, 'FM0999'); END;", 'ABCD', 123)
-  #   # => ["0123", 123]
+  #   num_rows = conn.exec('UPDATE emp SET sal = sal * 1.1')
+  #   puts num_rows.to_s + ' rows were updated.'
   #   conn.logoff
   #
-  # Above example uses two bind variables which names are :str
-  # and :num. These initial values are "the string whose width
-  # is 4 and whose value is 'ABCD'" and "the number whose value is
-  # 123". This method returns the array of these bind variables,
-  # which may modified by PL/SQL statement. The order of array is
-  # same with that of bind variables.
+  # example:
+  #   conn = OCI8.new('scott', 'tiger')
+  #   conn.exec('CREATE TABLE test (col1 CHAR(6))') # => 0
+  #   conn.logoff
+  #
   def exec(sql, *bindvars)
     begin
       cursor = parse(sql)
@@ -75,22 +98,24 @@
       when :select_stmt
         if block_given?
           cursor.fetch { |row| yield(row) }   # for each row
-          rv = cursor.row_count()
-          cursor.close
-          rv
+          ret = cursor.row_count()
         else
           ret = cursor
           cursor = nil # unset cursor to skip cursor.close in ensure block
           ret
         end
       when :begin_stmt, :declare_stmt # PL/SQL block
-        ary = []
-        cursor.keys.sort.each do |key|
-          ary << cursor[key]
+        if block_given?
+          ary = []
+          cursor.keys.sort.each do |key|
+            ary << cursor[key]
+          end
+          yield(*ary)
+        else
+          ret
         end
-        ary
       else
-        ret
+        ret # number of rows processed
       end
     ensure
       cursor.nil? || cursor.close
@@ -149,7 +174,7 @@
         if scale == -127
           if precision == 0
             # NUMBER declared without its scale and precision. (Oracle 9.2.0.3 or above)
-            klass = OCI8::Cursor.instance_eval do ::OCI8::Cursor.bind_default_number end
+            klass = OCI8::BindType::Mapping[:number_no_prec_setting]
           else
             # FLOAT or FLOAT(p)
             klass = OCI8::BindType::Float
@@ -159,7 +184,7 @@
             # NUMBER whose scale and precision is unknown
             # or
             # NUMBER declared without its scale and precision. (Oracle 9.2.0.2 or below)
-            klass = OCI8::Cursor.instance_eval do ::OCI8::Cursor.bind_unknown_number end
+            klass = OCI8::BindType::Mapping[:number_unknown_prec]
           else
             # NUMBER(p, 0)
             klass = OCI8::BindType::Integer
@@ -244,38 +269,15 @@
   # calling OCI8#exec or OCI8#parse.
   class Cursor
 
-    # number column declared without its scale and precision. (Oracle 9.2.0.3 or above)
-    @@bind_default_number = OCI8::BindType::OraNumber
-    # number value whose scale and precision is unknown
-    # or
-    # number column declared without its scale and precision. (Oracle 9.2.0.2 or below)
-    @@bind_unknown_number = OCI8::BindType::OraNumber
-
-    def self.bind_default_number
-      @@bind_default_number
-    end
-
-    def self.bind_default_number=(val)
-      @@bind_default_number = val
-    end
-
-    def self.bind_unknown_number
-      @@bind_unknown_number
-    end
-
-    def self.bind_unknown_number=(val)
-      @@bind_unknown_number = val
-    end
-
     # explicitly indicate the date type of fetched value. run this
     # method within parse and exec. pos starts from 1. lentgh is used
     # when type is String.
     # 
     # example:
     #   cursor = conn.parse("SELECT ename, hiredate FROM emp")
-    #  cursor.define(1, String, 20) # fetch the first column as String.
-    #  cursor.define(2, Time)       # fetch the second column as Time.
-    #  cursor.exec()
+    #   cursor.define(1, String, 20) # fetch the first column as String.
+    #   cursor.define(2, Time)       # fetch the second column as Time.
+    #   cursor.exec()
     def define(pos, type, length = nil)
       __define(pos, make_bind_object(:type => type, :length => length))
       self
@@ -348,19 +350,14 @@
     # true. In contrast with OCI8#exec, it returns true even
     # though PL/SQL. Use OCI8::Cursor#[] explicitly to get bind
     # variables.
-    # 
-    # Pass a "nil" to "__execute" to specify the statement isn't 
-    # an Array DML 
     def exec(*bindvars)
       bind_params(*bindvars)
-      __execute(nil)
+      __execute(nil) # Pass a nil to specify the statement isn't an Array DML
       case type
       when :select_stmt
         define_columns()
-      when :update_stmt, :delete_stmt, :insert_stmt
-	row_count
       else
-	true
+        row_count
       end
     end # exec
 
@@ -444,10 +441,31 @@
       @names ||= @column_metadata.collect { |md| md.name }
     end # get_col_names
 
+    # call-seq:
+    #   column_metadata -> column information
+    #
+    # (new in 1.0.0 and 2.0)
+    #
+    # Gets an array of OCI8::Metadata::Column of a select statement.
+    #
+    # example:
+    #   cursor = conn.exec('select * from tab')
+    #   puts ' Name                                      Type'
+    #   puts ' ----------------------------------------- ----------------------------'
+    #   cursor.column_metadata.each do |colinfo|
+    #     puts format(' %-41s %s',
+    #                 colinfo.name,
+    #                 colinfo.type_string)
+    #   end
     def column_metadata
       @column_metadata
     end
 
+    # call-seq:
+    #   fetch_hash
+    #
+    # get fetched data as a Hash. The hash keys are column names.
+    # If a block is given, acts as an iterator.
     def fetch_hash
       if iterator?
         while ret = fetch_a_hash_row()
@@ -711,6 +729,32 @@
 # SMALLINT         SQLT_NUM     22   38    0
 OCI8::BindType::Mapping[:number] = OCI8::BindType::Number
 
+# mapping for calculated number values.
+#
+# for example:
+#   select col1 * 1.1 from tab1;
+#
+# For Oracle 9.2.0.2 or below, this is also used for 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
+
+# mapping for number without precision and scale.
+#
+# for example:
+#   create table tab1 (col1 number);
+#   select col1 from tab1;
+#
+# 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
+
 if defined? OCI8::BindType::BinaryDouble
   OCI8::BindType::Mapping[:binary_float] = OCI8::BindType::BinaryDouble
   OCI8::BindType::Mapping[:binary_double] = OCI8::BindType::BinaryDouble




More information about the ruby-oci8-commit mailing list