[ruby-oci8-commit] [551] trunk/ruby-oci8: Fix comments for yard and update the version to 2.1. 4.

nobody at rubyforge.org nobody at rubyforge.org
Sun Jan 6 12:39:47 UTC 2013


Revision: 551
Author:   kubo
Date:     2013-01-06 12:39:46 +0000 (Sun, 06 Jan 2013)
Log Message:
-----------
Fix comments for yard and update the version to 2.1.4.

Modified Paths:
--------------
    trunk/ruby-oci8/ChangeLog
    trunk/ruby-oci8/NEWS
    trunk/ruby-oci8/VERSION
    trunk/ruby-oci8/docs/platform-specific-issues.md
    trunk/ruby-oci8/ext/oci8/connection_pool.c
    trunk/ruby-oci8/ext/oci8/encoding.c
    trunk/ruby-oci8/ext/oci8/metadata.c
    trunk/ruby-oci8/ext/oci8/oci8.c
    trunk/ruby-oci8/lib/oci8/metadata.rb
    trunk/ruby-oci8/lib/oci8/oci8.rb
    trunk/ruby-oci8/lib/oci8/oracle_version.rb
    trunk/ruby-oci8/lib/oci8/properties.rb
    trunk/ruby-oci8/lib/oci8.rb.in
    trunk/ruby-oci8/test/test_clob.rb

Modified: trunk/ruby-oci8/ChangeLog
===================================================================
--- trunk/ruby-oci8/ChangeLog	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/ChangeLog	2013-01-06 12:39:46 UTC (rev 551)
@@ -1,3 +1,13 @@
+2013-01-06  KUBO Takehiro  <kubo at jiubao.org>
+	* NEWS: add changes between 2.1.4 and 2.1.3
+	* VERSION: change the version to 2.1.4.
+	* docs/platform-specific-issues.md: update solaris-specific document.
+	* ext/oci8/connection_pool.c, ext/oci8/encoding.c, ext/oci8/metadata.c,
+	  ext/oci8/oci8.c,lib/oci8.rb.in, lib/oci8/metadata.rb, lib/oci8/oci8.rb,
+	  lib/oci8/oracle_version.rb, lib/oci8/properties.rb: update comments for yard.
+	* test/test_clob.rb: change a lob size when ORA-24817 is raised to
+	    pass tests on Windows.
+
 2013-01-03  KUBO Takehiro  <kubo at jiubao.org>
 	* ext/oci8/oci8.c, lib/oci8/properties.rb: add OCI8.properties[:events_mode]
 	    to support Fast Application Notification (FAN).

Modified: trunk/ruby-oci8/NEWS
===================================================================
--- trunk/ruby-oci8/NEWS	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/NEWS	2013-01-06 12:39:46 UTC (rev 551)
@@ -1,5 +1,46 @@
 # @markup markdown
 
+2.1.4
+=====
+
+New Features
+------------
+
+### Fast Application Notification (FAN) support
+
+Look at {http://php.net/manual/en/oci8.connection.php} to know what is FAN.
+[oci8.events](http://php.net/manual/en/oci8.configuration.php#ini.oci8.events) in PHP
+corresponds to {OCI8.properties  OCI8.properties[:events_mode]} in ruby-oci8.
+
+Note: You need to set `OCI8.properties[:events_mode]` after `"require 'oci8'"` and before
+any methods which call Oracle OCI functions.
+
+Fixed Issues
+------------
+
+-   fix SEGV when a temporary LOB is freed when `OCILobRead` returns `OCI_NEED_DATA`.
+    See: [github issue #20](https://github.com/kubo/ruby-oci8/issues/20)
+
+    (reported by Edgars Beigarts)
+
+-   use `RUBY_VERSION` instead of `RbConfig::CONFIG['ruby_version']` to know the
+    ruby ABI version. The latter may be changed by the configure option
+    --with-ruby-version.
+    See: [github issue #24](https://github.com/kubo/ruby-oci8/issues/24)
+
+    (reported by suhrawardi)
+
+-   add a script encoding magic comment for ruby 2.0.0 preview2.
+    See: [github issue #25](https://github.com/kubo/ruby-oci8/issues/25)
+
+    (reported by aboltart)
+
+-   fix {OCI8#describe_table} not to follow synonyms until stack overflow.
+    Now the recursive level is limited to 20.
+    See: [github issue #26](https://github.com/kubo/ruby-oci8/issues/26)
+
+    (reported by Brian Henderson)
+
 2.1.3
 =====
 

Modified: trunk/ruby-oci8/VERSION
===================================================================
--- trunk/ruby-oci8/VERSION	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/VERSION	2013-01-06 12:39:46 UTC (rev 551)
@@ -1 +1 @@
-2.1.3
+2.1.4

Modified: trunk/ruby-oci8/docs/platform-specific-issues.md
===================================================================
--- trunk/ruby-oci8/docs/platform-specific-issues.md	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/docs/platform-specific-issues.md	2013-01-06 12:39:46 UTC (rev 551)
@@ -71,16 +71,24 @@
 =======
 
 You need a same compiler which is used to make ruby itself.
+For example, if the ruby is compiled by gcc, you need gcc. If it is compiled by Oracle Solaris Studio
+(formerly called as Sun Studio), you need Oracle Solaris Studio.
 
-There are two ruby packages.
+If ruby is compiled by gcc and "require 'oci8'" raises "OCI Library Initialization Error",
+you may need to recompile ruby as follows:
 
-* [Sunfreeware.com](http://www.sunfreeware.com/)
-* [Blastwave.org](http://www.blastwave.org/)
+    $ bzip2 -dc ruby-1.9.3-pxxx.tar.bz2 | tar xvf -
+    $ cd ruby-1.9.3-pxxx
+    $ vi main.c   # <- Add RUBY_FUNC_EXPORTED just before "int main(..)" as follows:
+    -------------
+    RUBY_FUNC_EXPORTED  /* Add this line */
+    int
+    main(int argc, char **argv)
+    -------------
+    $ ./configure
+    $ make
+    $ make install
 
-The former is compiled by gcc. The latter is compiled by
-[Sun Studio](http://developers.sun.com/sunstudio/).
-The both compilers are freely available.
-
 If you use Blastwave.org's ruby and want not to install Sun Studio,
 you can edit rbconfig.rb by your self. [(look at here)](http://forum.textdrive.com/viewtopic.php?id=12630)
 
@@ -91,8 +99,8 @@
 prints "yes", you may need to edit rbconfig.rb distributed with the ruby
 as follows:
 
-   from: CONFIG["LDFLAGS"] = "-L.  -Wl,-E"
-   to:   CONFIG["LDFLAGS"] = "-L. "
+    from: CONFIG["LDFLAGS"] = "-L.  -Wl,-E"
+    to:   CONFIG["LDFLAGS"] = "-L. "
 
 FreeBSD
 =======

Modified: trunk/ruby-oci8/ext/oci8/connection_pool.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/connection_pool.c	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/ext/oci8/connection_pool.c	2013-01-06 12:39:46 UTC (rev 551)
@@ -174,9 +174,9 @@
  * call-seq:
  *   pool_name -> string
  *
- * <b>internal use only</b>
+ * Retruns the pool name.
  *
- * Retruns the pool name.
+ * @private
  */
 static VALUE oci8_cpool_pool_name(VALUE self)
 {

Modified: trunk/ruby-oci8/ext/oci8/encoding.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/encoding.c	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/ext/oci8/encoding.c	2013-01-06 12:39:46 UTC (rev 551)
@@ -229,6 +229,7 @@
  * are passed to Oracle, they are converted to +OCI8.encoding+
  * in advance.
  *
+ * @example
  *   # When OCI8.encoding is ISO-8859-1,
  *   conn.exec('insert into country_code values(:1, :2, :3)',
  *             'AT', 'Austria', "\u00d6sterreichs")
@@ -249,6 +250,7 @@
  * @return [Encoding]
  * @since 2.0.0 and ruby 1.9
  * @private
+ * @see OCI8.client_charset_name
  */
 static VALUE oci8_get_encoding(VALUE klass)
 {

Modified: trunk/ruby-oci8/ext/oci8/metadata.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/metadata.c	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/ext/oci8/metadata.c	2013-01-06 12:39:46 UTC (rev 551)
@@ -159,6 +159,19 @@
     return oci8_metadata_create(parmhp, self, obj);
 }
 
+/*
+ * call-seq:
+ *   __describe(name, klass, check_public)
+ *
+ * @param [String] name  object name
+ * @param [subclass of OCI8::Metadata::Base] klass
+ * @param [Boolean] check_public  +true+ to look up the object as a public synonym when
+ *                                the object does not exist in the current schema and
+ *                                the name includes no dots.
+ * @return [subclass of OCI8::Metadata::Base]
+ *
+ * @private
+ */
 static VALUE oci8_describe(VALUE self, VALUE name, VALUE klass, VALUE check_public)
 {
     OCI8SafeStringValue(name);

Modified: trunk/ruby-oci8/ext/oci8/oci8.c
===================================================================
--- trunk/ruby-oci8/ext/oci8/oci8.c	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/ext/oci8/oci8.c	2013-01-06 12:39:46 UTC (rev 551)
@@ -285,6 +285,7 @@
  *   "scott/tiger at oradb.example.com" -> ["scott", "tiger", "oradb.example.com", nil]
  *   "sys/change_on_install as sysdba" -> ["sys", "change_on_install", nil, :SYSDBA]
  *
+ * @private
  */
 static VALUE oci8_parse_connect_string(VALUE self, VALUE conn_str)
 {
@@ -396,9 +397,9 @@
  * call-seq:
  *   logon2(username, password, dbname, mode) -> connection
  *
- * <b>internal use only</b>
+ * Creates a simple logon session by the OCI function OCILogon2().
  *
- * Creates a simple logon session by the OCI function OCILogon2().
+ * @private
  */
 static VALUE oci8_logon2(VALUE self, VALUE username, VALUE password, VALUE dbname, VALUE mode)
 {
@@ -448,10 +449,10 @@
  * call-seq:
  *   allocate_handles()
  *
- * <b>internal use only</b>
- *
  * Allocates a service context handle, a session handle and a
  * server handle to use explicit attach and begin-session calls.
+ *
+ * @private
  */
 static VALUE oci8_allocate_handles(VALUE self)
 {
@@ -488,9 +489,9 @@
  * call-seq:
  *   server_attach(dbname, mode)
  *
- * <b>internal use only</b>
+ * Attachs to the server by the OCI function OCIServerAttach().
  *
- * Attachs to the server by the OCI function OCIServerAttach().
+ * @private
  */
 static VALUE oci8_server_attach(VALUE self, VALUE dbname, VALUE attach_mode)
 {
@@ -530,9 +531,9 @@
  * call-seq:
  *   session_begin(cred, mode)
  *
- * <b>internal use only</b>
+ * Begins the session by the OCI function OCISessionBegin().
  *
- * Begins the session by the OCI function OCISessionBegin().
+ * @private
  */
 static VALUE oci8_session_begin(VALUE self, VALUE cred, VALUE mode)
 {
@@ -798,9 +799,9 @@
  *
  * Returns a numerical format of the Oracle server version.
  *
- * See also: #oracle_server_version
- *
+ * @see OCI8#oracle_server_version
  * @since 2.0.1
+ * @private
  */
 static VALUE oci8_oracle_server_vernum(VALUE self)
 {
@@ -1177,7 +1178,6 @@
     rb_define_method(cOCI8, "module=", oci8_set_module, 1);
     rb_define_method(cOCI8, "action=", oci8_set_action, 1);
     rb_define_method(cOCI8, "client_info=", oci8_set_client_info, 1);
-    rb_define_attr(cOCI8, "last_error", 1, 1);
     *out = cOCI8;
 }
 

Modified: trunk/ruby-oci8/lib/oci8/metadata.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/metadata.rb	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/lib/oci8/metadata.rb	2013-01-06 12:39:46 UTC (rev 551)
@@ -1985,22 +1985,34 @@
 =end
   end # OCI8::Metadata
 
-  # return a subclass of OCI8::Metadata::Base
-  # which has information about _object_name_.
-  # OCI8::Metadata::Table, OCI8::Metadata::View,
-  # OCI8::Metadata::Procedure, OCI8::Metadata::Function,
-  # OCI8::Metadata::Package, OCI8::Metadata::Type,
-  # OCI8::Metadata::Synonym or OCI8::Metadata::Sequence
+  # Returns object information.
+  #
+  # The return type is depends on the object type.
+  #
+  # Oracle type:: Ruby type
+  # Table::       {OCI8::Metadata::Table}
+  # View::        {OCI8::Metadata::View}
+  # Procedure::   {OCI8::Metadata::Procedure}
+  # Function::    {OCI8::Metadata::Function}
+  # Package::     {OCI8::Metadata::Package}
+  # Type::        {OCI8::Metadata::Type}
+  # Synonym::     {OCI8::Metadata::Synonym}
+  # Sequence::    {OCI8::Metadata::Sequence}
+  #
+  # @param [String] object_name
+  # @return [a subclass of OCI8::Metadata::Base]
   def describe_any(object_name)
     __describe(object_name, OCI8::Metadata::Unknown, true)
   end
-  # returns a OCI8::Metadata::Table or a OCI8::Metadata::View. If the
-  # name is a current schema's synonym name or a public synonym name,
-  # it returns a OCI8::Metadata::Table or a OCI8::Metadata::View which
+  # Returns table or view information. If the name is a current schema's synonym
+  # name or a public synonym name, it returns table or view information which
   # the synonym refers.
   #
-  # If the second argument is true, this returns a
-  # OCI8::Metadata::Table in the current schema.
+  # If +table_only+ is true, it checks tables in the current schema.
+  #
+  # @param [String] table_name
+  # @param [Boolean] table_only (default: false)
+  # @return [OCI8::Metadata::Table or OCI8::Metadata::View]
   def describe_table(table_name, table_only = false)
     if table_only
       # check my own tables only.
@@ -2022,39 +2034,66 @@
       raise OCIError.new(36, recursive_level) # ORA-00036: maximum number of recursive SQL levels (%s) exceeded
     end
   end
-  # returns a OCI8::Metadata::View in the current schema.
+  # Returns view information
+  #
+  # @param [String] view_name
+  # @return [OCI8::Metadata::View]
   def describe_view(view_name)
     __describe(view_name, OCI8::Metadata::View, false)
   end
-  # returns a OCI8::Metadata::Procedure in the current schema.
+  # Returns procedure information
+  #
+  # @param [String] procedure_name
+  # @return [OCI8::Metadata::Procedure]
   def describe_procedure(procedure_name)
     __describe(procedure_name, OCI8::Metadata::Procedure, false)
   end
-  # returns a OCI8::Metadata::Function in the current schema.
+  # Returns function information
+  #
+  # @param [String] function_name
+  # @return [OCI8::Metadata::Function]
   def describe_function(function_name)
     __describe(function_name, OCI8::Metadata::Function, false)
   end
-  # returns a OCI8::Metadata::Package in the current schema.
+  # Returns package information
+  #
+  # @param [String] package_name
+  # @return [OCI8::Metadata::Package]
   def describe_package(package_name)
     __describe(package_name, OCI8::Metadata::Package, false)
   end
-  # returns a OCI8::Metadata::Type in the current schema.
+  # Returns type information
+  #
+  # @param [String] type_name
+  # @return [OCI8::Metadata::Type]
   def describe_type(type_name)
     __describe(type_name, OCI8::Metadata::Type, false)
   end
-  # returns a OCI8::Metadata::Synonym in the current schema.
+  # Returns synonym information
+  #
+  # @param [String] synonym_name
+  # @return [OCI8::Metadata::Synonym]
   def describe_synonym(synonym_name, check_public_also = true)
     __describe(synonym_name, OCI8::Metadata::Synonym, check_public_also)
   end
-  # returns a OCI8::Metadata::Sequence in the current schema.
+  # Returns sequence information
+  #
+  # @param [String] sequence_name
+  # @return [OCI8::Metadata::Sequence]
   def describe_sequence(sequence_name)
     __describe(sequence_name, OCI8::Metadata::Sequence, false)
   end
-  # returns a OCI8::Metadata::Schema in the database.
+  # Returns schema information
+  #
+  # @param [String] schema_name
+  # @return [OCI8::Metadata::Schema]
   def describe_schema(schema_name)
     __describe(schema_name, OCI8::Metadata::Schema, false)
   end
-  # returns a OCI8::Metadata::Database.
+  # Returns database information
+  #
+  # @param [String] database_name
+  # @return [OCI8::Metadata::Database]
   def describe_database(database_name)
     __describe(database_name, OCI8::Metadata::Database, false)
   end

Modified: trunk/ruby-oci8/lib/oci8/oci8.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/oci8.rb	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/lib/oci8/oci8.rb	2013-01-06 12:39:46 UTC (rev 551)
@@ -26,8 +26,10 @@
 #              value_for_the_second_parameter)
 class OCI8
 
-  # call-seq:
-  #   new(username, password, dbname = nil, privilege = nil)
+  # @return [OCIError]
+  attr_accessor :last_error
+
+  # @overload initialize(username, password, dbname = nil, privilege = nil)
   #
   # Connects to an Oracle database server by +username+ and +password+
   # at +dbname+ as +privilege+.
@@ -337,14 +339,14 @@
     end
   end
 
+  # @private
   def inspect
     "#<OCI8:#{username}>"
   end
 
-  # Returns an OCI8::OracleVersion of the Oracle server version.
+  # Returns the Oracle server version.
   #
-  # See also: OCI8.oracle_client_version
-  #
+  # @see OCI8.oracle_client_version
   # @return [OCI8::OracleVersion]
   def oracle_server_version
     unless defined? @oracle_server_version
@@ -365,7 +367,7 @@
     @oracle_server_version
   end
 
-  # Returns the Oracle database character set name.
+  # Returns the Oracle database character set name such as AL32UTF8.
   #
   # @since 2.1.0
   # @return [String] Oracle database character set name
@@ -373,10 +375,12 @@
     charset_id2name(@server_handle.send(:attr_get_ub2, OCI_ATTR_CHARSET_ID))
   end
 
-  # Returns the client-side Oracle character set name.
+  # Returns the client-side Oracle character set name such as AL32UTF8.
   #
   # @since 2.1.0
   # @return [String] client-side character set name
+  # @private
+  # @see OCI8.encoding
   def self.client_charset_name
     @@client_charset_name
   end

Modified: trunk/ruby-oci8/lib/oci8/oracle_version.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/oracle_version.rb	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/lib/oci8/oracle_version.rb	2013-01-06 12:39:46 UTC (rev 551)
@@ -122,7 +122,7 @@
     #   oraver = OCI8::OracleVersion.new('11.2.0.3')
     #   oraver.to_s          # => '11.2.0.3.0'
     #
-    # @return [Integer]
+    # @return [String]
     def to_s
       format('%d.%d.%d.%d.%d', @major, @minor, @update, @patch, @port_update)
     end

Modified: trunk/ruby-oci8/lib/oci8/properties.rb
===================================================================
--- trunk/ruby-oci8/lib/oci8/properties.rb	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/lib/oci8/properties.rb	2013-01-06 12:39:46 UTC (rev 551)
@@ -5,6 +5,7 @@
 #
 class OCI8
 
+  # @private
   @@properties = {
     :length_semantics => :byte,
     :bind_string_as_nchar => false,
@@ -17,11 +18,13 @@
     @@properties[:statement_cache_size] = nil
   end
 
+  # @private
   def @@properties.[](name)
     raise IndexError, "No such property name: #{name}" unless @@properties.has_key?(name)
     super(name)
   end
 
+  # @private
   def @@properties.[]=(name, val)
     raise IndexError, "No such property name: #{name}" unless @@properties.has_key?(name)
     case name

Modified: trunk/ruby-oci8/lib/oci8.rb.in
===================================================================
--- trunk/ruby-oci8/lib/oci8.rb.in	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/lib/oci8.rb.in	2013-01-06 12:39:46 UTC (rev 551)
@@ -123,6 +123,7 @@
   # OCIClientVersion().
   #
   # @return [OCI8::OracleVersion] Oracle client version
+  # @see OCI8#oracle_server_version
   def self.oracle_client_version
     @@oracle_client_version
   end

Modified: trunk/ruby-oci8/test/test_clob.rb
===================================================================
--- trunk/ruby-oci8/test/test_clob.rb	2013-01-03 08:08:21 UTC (rev 550)
+++ trunk/ruby-oci8/test/test_clob.rb	2013-01-06 12:39:46 UTC (rev 551)
@@ -78,8 +78,15 @@
   # https://github.com/kubo/ruby-oci8/issues/20
   def test_github_issue_20
     lob1 = OCI8::CLOB.new(@conn, ' '  * (1024 * 1024))
-    lob2 = OCI8::CLOB.new(@conn, ' '  * (128 * 1024 * 1024))
-
+    begin
+      lob2 = OCI8::CLOB.new(@conn, ' '  * (128 * 1024 * 1024))
+    rescue OCIError
+      raise if $!.code != 24817
+      # ORA-24817: Unable to allocate the given chunk for current lob operation
+      GC.start
+      # allocate smaller size
+      lob2 = OCI8::CLOB.new(@conn, ' '  * (16 * 1024 * 1024))
+    end
     lob1 = nil  # lob1's value will be freed in GC.
     lob2.read   # GC must run here to reproduce the issue.
   end



More information about the ruby-oci8-commit mailing list