fireruby 0.3.2-mswin32 → 0.4.0-mswin32

data/doc/CVS/Entries

@@ -1,3 +1,4 @@
-/README/1.6/Fri Jun 10 12:17:53 2005//
 /license.txt/1.1/Tue Mar 15 13:40:26 2005//
-D
+D/classes////
+D/files////
+/README/1.7/Sat Oct 29 17:30:46 2005//

data/doc/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/doc
+fireruby/doc

data/doc/README

@@ -1,27 +1,65 @@
-== FireRuby Version 0.3.2
-FireRuby is an extension to the Ruby language that provides access to the C API
-functionality of the Firebird relational database management system.
-
-This release expands upon the functionality provided by the Database and
-Connection classes to provide extended support for connection options and, in
-particular, database character sets.
-
-Once again I would like to thank Ken Kunz for his support and input to the
-FireRuby project. Ken performs the unit testing and creates the gem file for the
-Linux version of the FireRuby library. Thanks also to Art Fedorov for input on
-handling and testing character sets.
+== FireRuby Version 0.4.0
+Its been a while but I'm glad to release version 0.4.0 of the FireRuby library.
+FireRuby is an extension for the Ruby programming language that provides access
+to the Firebird open source RDBMS. There aren't a great deal of changes for this
+release but some of the alterations may have an impact on existing code, so
+please read the enhancements and alterations section to see what has been done.
 
 == Enhancements & Alterations
 
-The Database class has been expanded to incorporate the concept of character
-sets. The Connection class has been extended to allow for the specification of
-a set of connection options. Both of these classes have also been altered to
-support the accessing of databases using the system user details (on POSIX
-systems).
+This release contains some changes that are part of a suite of suggestion put
+forward by Ken Kunz to enhancement support for the Firebird ActiveRecord 
+adapter he developed. The first of these changes involved switching the keying
+of Row objects away from using the column name to using the column alias. This
+is a logical change as the alias is more likely to be unique. I realise that
+change has the potential to break existing code so I've included a work around
+that can be used to have the library behave as it used to. To use keying on
+columns insert the following line into your code after you've loaded the
+FireRuby library and before you've done any database work...
+
+   $FireRubySettings[:ALIAS_KEYS] = false
+   
+This will cause the library to use column names as keys on rows. A second change
+I've made that could impact existing code is for the retrieval of data from
+columns of SQL type DATE. These were being returned as a Time object but are now
+being returned as a Date object, again a fairly logical change. If this causes
+problems for your code then you can add the following line to get the library to
+return Times by adding the following line...
+
+   $FireRubySettings[:DATE_AS_DATE] = false
+   
+The final change I've made for this release from Ken's wish list is that I have
+incorporated Enumerable into the Row and ResultSet classes. Your code may
+already do this and, unfortunately, I'm not providing any sort of work around
+other than you remove this from your own code.
+
+I've also added functionality to the library to aid in determining type
+information in relation to database tables and query results. As far as I can
+determine the Firebird data structures used to return data from the database
+provide no means of determining exact type specifics (please correct me if I'm
+wrong). This means that for queries all I can return are details of the
+underlying type but not the specifics (so I can tell you that a result column is
+NUMERIC but I can't give you the precision and scale for example).
+
+I have provided a new class called SQLType. This defines constants for the basic
+types supported by FireRuby. It also allows for querying of table types. In this
+case, as I'm referring to the actual database, I can provide more specific
+details (so I can tell you that a column is NUMERIC, has a precision of 5 and a
+scale or 2 for example). See the API documentation for this class for more
+information.
+
+Finally I have added some new unit tests and updated existing ones to cover the
+changes I have made.
 
 == Bug Fixes
 
-There are no outstanding project bugs.
+I've made a few cosmetic and minor bug fixes that were unlikely to have had an
+impact on anyone (but its nice that they're fixed anyway).
+
+I received some feedback with regards to FireRuby not working with Firebird
+database aliases but, as this has been successfully tested via the use of the
+Rails adapter based on FireRuby, I have to assume that this was a user set up
+problem.
 
 == Issues
 
@@ -35,7 +73,21 @@ exist as of this release.
   know.
 
 - The library currently does not support array columns. This may be implemented
-  for a later release depending on demand.
+  for a later release depending on demand. No-one has asked for this so far so
+  I'm starting to think that people don't make much use of array columns.
+  
+- The library can be a bit touchy if you don't clean up after yourself. This
+  can result in a segmentation violation whenever your program stops if you've
+  left a ResultSet or Statement object unclosed. Check through your code to
+  insure that this isn't the case before contacting me about problems in this
+  line.
+  
+- The unit tests are currently set up on the assumption that the password for
+  your sysdba account is 'masterkey'. If this is not the case, or if you wish
+  to use an alternative user for testing, edit the TestSetup.rb file in the
+  unit test directory and update the entries there as appropriate. I should also
+  note that you may need to alter permissions on the test directory to run the
+  actual unit tests on Linux/Unix.
   
 == Installation & Usage
 
@@ -45,32 +97,32 @@ the Ruby Gems package to be installed. Assuming that these installation criteria
 have been met the library can be installed on Windows by executing a command
 such as the following...
 
-   gem install fireruby-0.3.0-mswin32.gem
+   gem install fireruby-0.4.0-mswin32.gem
    
 On the Mac OS X platform you may require super user privilege if your Ruby is
 installed to the default location (i.e. /usr/local/lib). In this case you can
 use the sudo command to make the installation like this...
 
-   sudo gem install fireruby-0.3.0-powerpc-darwin.gem
+   sudo gem install fireruby-0.4.0-powerpc-darwin.gem
    
 Once the gem installation is complete the FireRuby functionality can be accessed
 in code with the usual gem style requires...
 
    require 'rubygems'
-   require_gem 'fireruby'
+   require 'fireruby'
   
 == Build Details
 
-The FireRuby library is an extension of the Ruby language written in C. For Mac
-OS X the library is built on version 10.3 of the OS and against Firebird
-installed as a framework, version 1.5.1, and with Ruby version 1.8.2. For the
-Windows platform the library is built on Windows XP and against a Ruby
-installation created using the one-click installer, version 1.8.2. The Windows
-build was created using the freely available Microsoft compilers and SDKs and
-built against a standard installation of Firebird, version 1.5.2. On Linux the
-library (I believe) has been linked against the Firebird shared object. This
-being the case then your LD_LIBRARY_PATH environment variable will have to be
-set to include the Firebird lib directory if you want to use it.
+The FireRuby library is an extension of the Ruby language written in C. The Mac
+OS X version was built by my brother John (thanks!) using Mac OS X  10.4.3
+against Firebird installed as a framework, version 1.5.1, and with Ruby version
+1.8.2. For the Windows platform the library is built on Windows XP and against
+a Ruby installation created using the one-click installer, version 1.8.2. The
+Windows build was created using the freely available Microsoft compilers and
+SDKs and built against a standard installation of Firebird, version 1.5.2. On
+Linux the library is built using an Ubuntu system (Breezy Badger release) using
+Firebird installed through the Synaptic package manager and version 1.8.2 of
+Ruby installed using the same tool.
 
 == So How Do I Use It?
 
@@ -90,7 +142,7 @@ and connecting to database instances. For example, to obtain a connection to a
 database you would use something like the following...
 
    require 'rubygems'
-   require_gem 'fireruby'
+   require 'fireruby'
    
    include FireRuby
    
@@ -322,7 +374,7 @@ database administrator you might do the following...
    
 Assuming that this succeeds you are now ready to execute tasks through your
 ServiceManager object. Within the FireRuby library individual task are broken
-out into separate classes. For this release (0.3.0) there are four task classes
+out into separate classes. For this release (0.4.0) there are four task classes
 provided in the library - Backup, Restore, AddUser and RemoveUser. I think the
 class names are relatively self explanatory but if you want more information
 consult the API documentation for a class.

data/doc/classes/CVS/Entries

@@ -1 +1 @@
-D
+D/FireRuby////

data/doc/classes/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/doc/classes
+fireruby/doc/classes

data/doc/classes/FireRuby/CVS/Entries

@@ -1 +1,7 @@
-D
+D/Connection.src////
+D/Database.src////
+D/FireRubyError.src////
+D/Generator.src////
+D/ResultSet.src////
+D/Statement.src////
+D/Transaction.src////

data/doc/classes/FireRuby/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/doc/classes/FireRuby
+fireruby/doc/classes/FireRuby

data/doc/classes/FireRuby/Connection.src/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/doc/classes/FireRuby/Connection.src
+fireruby/doc/classes/FireRuby/Connection.src

data/doc/classes/FireRuby/Database.src/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/doc/classes/FireRuby/Database.src
+fireruby/doc/classes/FireRuby/Database.src

data/doc/classes/FireRuby/FireRubyError.src/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/doc/classes/FireRuby/FireRubyError.src
+fireruby/doc/classes/FireRuby/FireRubyError.src

data/doc/classes/FireRuby/Generator.src/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/doc/classes/FireRuby/Generator.src
+fireruby/doc/classes/FireRuby/Generator.src

data/doc/classes/FireRuby/ResultSet.src/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/doc/classes/FireRuby/ResultSet.src
+fireruby/doc/classes/FireRuby/ResultSet.src

data/doc/classes/FireRuby/Statement.src/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/doc/classes/FireRuby/Statement.src
+fireruby/doc/classes/FireRuby/Statement.src

data/doc/classes/FireRuby/Transaction.src/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/doc/classes/FireRuby/Transaction.src
+fireruby/doc/classes/FireRuby/Transaction.src

data/doc/files/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/doc/files
+fireruby/doc/files

data/examples/CVS/Entries

@@ -1,2 +1,2 @@
-/example01.rb/1.1/Mon Mar 21 10:34:57 2005//
+/example01.rb/1.2/Tue Jun 14 09:50:30 2005//
 D

data/examples/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/examples
+fireruby/examples

data/examples/example01.rb

@@ -5,6 +5,11 @@ require_gem 'fireruby'
 
 include FireRuby
 
+# Database details constants.
+DB_FILE      = "localhost:#{File.expand_path('.')}#{File::SEPARATOR}example.fdb"
+DB_USER_NAME = "sysdba"
+DB_PASSWORD  = "masterkey"
+
 # SQL constants.
 CREATE_TABLE_SQL = 'CREATE TABLE TESTTABLE (TESTID INTEGER NOT NULL PRIMARY '\
                    'KEY, TESTTEXT VARCHAR(100), TESTFLOAT NUMERIC(6,2), '\
@@ -16,16 +21,16 @@ SELECT_SQL       = 'SELECT * FROM TESTTABLE'
 begin
    # Check if the database file exists.
    db = nil
-   if File.exist?('./example.fdb') == false
+   if File.exist?(DB_FILE) == false
       # Create the database file.
-      db = Database.create('./example.fdb', 'sysdba', 'masterkey', 1024, 'ASCII')
+      db = Database.create(DB_FILE, DB_USER_NAME, DB_PASSWORD, 1024, 'ASCII')
    else
       # Create the databse object.
-      db = Database.new('./example.fdb')
+      db = Database.new(DB_FILE)
    end
    
    # Obtain a connection to the database.
-   db.connect('sysdba', 'masterkey') do |cxn|   
+   db.connect(DB_USER_NAME, DB_PASSWORD) do |cxn|   
       # Create the database table.
       cxn.execute_immediate(CREATE_TABLE_SQL)
       

data/lib/CVS/Entries

@@ -1,4 +1,6 @@
 /fireruby.bundle/1.3/Fri Jun 10 12:20:22 2005//
 /mkdoc/1.2/Mon Mar 21 08:53:22 2005//
-/src.rb/1.5/Fri Jun 10 12:20:22 2005//
+/src.rb/1.6/Sat Oct 29 17:06:07 2005//
+/SQLType.rb/1.1/Thu Oct 27 19:16:36 2005//
+/fireruby.rb/1.1/Tue Oct 25 19:45:08 2005//
 D

data/lib/CVS/Repository

@@ -1 +1 @@
-/var/cvs/fireruby/fireruby/lib
+fireruby/lib

data/lib/SQLType.rb

@@ -0,0 +1,228 @@
+#-------------------------------------------------------------------------------
+# SQLType.rb
+#-------------------------------------------------------------------------------
+# Copyright � Peter Wood, 2005
+#
+# The contents of this file are subject to the Mozilla Public License Version
+# 1.1 (the "License"); you may not use this file except in compliance with the
+# License. You may obtain a copy of the License at
+#
+# http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS IS" basis,
+# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
+# the specificlanguage governing rights and  limitations under the License.
+#
+# The Original Code is the FireRuby extension for the Ruby language.
+#
+# The Initial Developer of the Original Code is Peter Wood. All Rights
+# Reserved.
+
+module FireRuby
+   # This class is used to represent SQL table column tables.
+   class SQLType
+      # A definition for a base SQL type.
+      BIGINT                           = :BIGINT
+
+      # A definition for a base SQL type.
+      BLOB                             = :BLOB
+
+      # A definition for a base SQL type.
+      CHAR                             = :CHAR
+
+      # A definition for a base SQL type.
+      DATE                             = :DATE
+
+      # A definition for a base SQL type.
+      DECIMAL                          = :DECIMAL
+
+      # A definition for a base SQL type.
+      DOUBLE                           = :DOUBLE
+
+      # A definition for a base SQL type.
+      FLOAT                            = :FLOAT
+
+      # A definition for a base SQL type.
+      INTEGER                          = :INTEGER
+
+      # A definition for a base SQL type.
+      NUMERIC                          = :NUMERIC
+
+      # A definition for a base SQL type.
+      SMALLINT                         = :SMALLINT
+
+      # A definition for a base SQL type.
+      TIME                             = :TIME
+
+      # A definition for a base SQL type.
+      TIMESTAMP                        = :TIMESTAMP
+
+      # A definition for a base SQL type.
+      VARCHAR                          = :VARCHAR
+
+      # Attribute accessor.
+      attr_reader :type, :length, :precision, :scale, :subtype
+
+
+      # This is the constructor for the SQLType class.
+      #
+      # ==== Parameters
+      # type::       The base type for the SQLType object. Must be one of the
+      #              base types defined within the class.
+      # length::     The length setting for the type. Defaults to nil.
+      # precision::  The precision setting for the type. Defaults to nil.
+      # scale::      The scale setting for the type. Defaults to nil.
+      # subtype::    The SQL sub-type setting. Defaults to nil.
+      def initialize(type, length=nil, precision=nil, scale=nil, subtype=nil)
+         @type      = type
+         @length    = length
+         @precision = precision
+         @scale     = scale
+         @subtype   = subtype
+      end
+
+
+      # This class method fetches the type details for a named table. The
+      # method returns a hash that links column names to SQLType objects.
+      #
+      # ==== Parameters
+      # table::       A string containing the name of the table.
+      # connection::  A reference to the connection to be used to determine
+      #               the type information.
+      #
+      # ==== Exception
+      # FireRubyException::  Generated if an invalid table name is specified
+      #                      or an SQL error occurs.
+      def SQLType.for_table(table, connection)
+         # Check for naughty table names.
+         if /\s+/ =~ table
+            raise FireRubyException.new("'#{table}' is not a valid table name.")
+         end
+
+         types     = {}
+         begin
+            sql = "SELECT RF.RDB$FIELD_NAME, F.RDB$FIELD_TYPE, "\
+                  "F.RDB$FIELD_LENGTH, F.RDB$FIELD_PRECISION, "\
+                  "F.RDB$FIELD_SCALE * -1, F.RDB$FIELD_SUB_TYPE "\
+                  "FROM RDB$RELATION_FIELDS RF, RDB$FIELDS F "\
+                  "WHERE RF.RDB$RELATION_NAME = UPPER('#{table}') "\
+                  "AND RF.RDB$FIELD_SOURCE = F.RDB$FIELD_NAME"
+
+            connection.start_transaction do |tx|
+               tx.execute(sql) do |row|
+                  sql_type = SQLType.to_base_type(row[1], row[5])
+                  type     = nil
+                  case sql_type
+                     when BLOB
+                        type = SQLType.new(sql_type, nil, nil, nil, row[5])
+
+                     when CHAR, VARCHAR
+                        type = SQLType.new(sql_type, row[2])
+
+                     when DECIMAL, NUMERIC
+                        type = SQLType.new(sql_type, nil, row[3], row[4])
+
+                     else
+                        type = SQLType.new(sql_type)
+                  end
+                  types[row[0].strip] = type
+               end
+
+            end
+         end
+         types
+      end
+
+
+      # This method overloads the equivalence test operator for the SQLType
+      # class.
+      #
+      # ==== Parameters
+      # object::  A reference to the object to be compared with.
+      def ==(object)
+         result = false
+         if object.instance_of?(SQLType)
+            result = (@type      == object.type &&
+                      @length    == object.length &&
+                      @precision == object.precision &&
+                      @scale     == object.scale &&
+                      @subtype   == object.subtype)
+         end
+         result
+      end
+
+
+      # This method generates a textual description for a SQLType object.
+      def to_s
+         if @type == SQLType::DECIMAL or @type == SQLType::NUMERIC
+            "#{@type.id2name}(#{@precision},#{@scale})"
+         elsif @type == SQLType::BLOB
+            "#{@type.id2name} SUB TYPE #{@subtype}"
+         elsif @type == SQLType::CHAR or @type == SQLType::VARCHAR
+            "#{@type.id2name}(#{@length})"
+         else
+            @type.id2name
+         end
+      end
+
+
+      # This class method converts a Firebird internal type to a SQLType base
+      # type.
+      #
+      # ==== Parameters
+      # type::     A reference to the Firebird field type value.
+      # subtype::  A reference to the Firebird field subtype value.
+      def SQLType.to_base_type(type, subtype)
+         case type
+            when 16  # BIGINT, DECIMAL, NUMERIC
+               if subtype
+                  subtype == 1 ? SQLType::NUMERIC : SQLType::DECIMAL
+               else
+                  SQLType::BIGINT
+               end
+
+            when 261 # BLOB
+               SQLType::BLOB
+
+            when 14  # CHAR
+               SQLType::CHAR
+
+            when 12  # DATE
+               SQLType::DATE
+
+            when 27  # DOUBLE, DECIMAL, NUMERIC
+               if subtype
+                  subtype == 1 ? SQLType::NUMERIC : SQLType::DECIMAL
+               else
+                  SQLType::DOUBLE
+               end
+
+            when 10  # FLOAT
+               SQLType::FLOAT
+
+            when 8   # INTEGER, DECIMAL, NUMERIC
+               if subtype
+                  subtype == 1 ? SQLType::NUMERIC : SQLType::DECIMAL
+               else
+                  SQLType::INTEGER
+               end
+
+            when 7   # SMALLINT, DECIMAL, NUMERIC
+               if subtype
+                  subtype == 1 ? SQLType::NUMERIC : SQLType::DECIMAL
+               else
+                  SQLType::SMALLINT
+               end
+
+            when 13  # TIME
+               SQLType::TIME
+
+            when 35  # TIMESTAMP
+               SQLType::TIMESTAMP
+
+            when 37  # VARCHAR
+               SQLType::VARCHAR
+         end
+      end
+   end # End of the SQLType class.
+end # End of the FireRuby module.

data/lib/fireruby.rb

@@ -0,0 +1,22 @@
+#-------------------------------------------------------------------------------
+# fireruby.rb
+#-------------------------------------------------------------------------------
+# Copyright � Peter Wood, 2005
+#
+# The contents of this file are subject to the Mozilla Public License Version
+# 1.1 (the "License"); you may not use this file except in compliance with the
+# License. You may obtain a copy of the License at
+#
+# http://www.mozilla.org/MPL/
+#
+# Software distributed under the License is distributed on an "AS IS" basis,
+# WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License for
+# the specificlanguage governing rights and  limitations under the License.
+#
+# The Original Code is the FireRuby extension for the Ruby language.
+#
+# The Initial Developer of the Original Code is Peter Wood. All Rights
+# Reserved.
+
+require 'fr_lib'
+require 'SQLType'