fireruby 0.2.2-i586-linux → 0.3.0-i586-linux

data/doc/README

@@ -1,31 +1,57 @@
-== FireRuby Version 0.2.1
-This is a bug fix release for version 0.2.0 of the FireRuby library. FireRuby is
-an extension to the Ruby language that provides access to the functionality of
-the Firebird relational database management system.
+== FireRuby Version 0.3.0
+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 extends the functionality of the Row object to allow it to be used
+as a read only Hash object and adds new funcionality relating to the Firebird
+RDBMS service manager.
+
+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.
 
 == Enhancements & Alterations
 
-No new functionality added for this release.
+The Row class has been extended to include equivalents for all Hash methods that
+do would not alter the contents of the Hash. This effectively allows an instance
+of the Row class to be used as a Hash anywhere that a Hash object can be used
+without the need to change it's contents.
+
+A ServiceManager class and a collection of task related classes have been added
+for this release. The ServiceManager class represents a connection to a Firebird
+service manager instance. Task classes have been provided that allow for the
+backing up and restoration of databases as well as the addition or removal of
+database users.
+
+The Statement and ResultSet classes under went a major rewrite. This was done
+to eliminate a dependency between these two classes (the Statement class was
+using the ResultSet class to execute SQL regardless of whether the statement
+being executed was a query). This was an illogical and ill-consider set up and
+has now been eliminated. An effort was made to minimize changes to the interface
+but there have been some (primarily the constructor for the ResultSet class).
+The ResultSet class has now been restricted for use with queries only and will
+generate and exception if a non-query statement is specified. Queries can still
+be run through the Statement class but, if you know you're executing a query
+statement, it is more efficient to go straight to a ResultSet object.
 
 == Bug Fixes
 
-- Fixed an intermittent bug that was causing an access violation when the Ruby
-  interpreter attempted to clean up at exited. The access violation was
-  occurring in a Firebird function call so I'm not exactly sure why it was
-  happening. The code has been restructured to bypass the issue.
-  
-- Fixed a bug in the code for the Generator object that was leaving an active
-  transaction lying around whenever an exception occurred in a call to fetch a
-  value from the Generator.
-  
-- Fixed a buffer overrun bug were the size of an input string was being used
-  to determine values written rather than the size of an output field.
+The only currently outstanding bug relates to accessing methods on the ResultSet
+class objects that have been created with a non-query SQL statement. This class
+has been fundamentally re-written and no longer allows the use of non-query SQL
+statements. This bug is therefore closed.
 
 == Issues
 
 Nothing is perfect so this section outlines those issues that are known to
 exist as of this release.
 
+- The big new issue for this release (0.3.0) relates to the fact the service
+  manager functionality does not appear to work on the Mac OS X platform. I
+  don't believe that this is a problem in the FireRuby code as I have tested the
+  Firebird gbak utility with the -service option and it gives the same result.
+  If anyone knows this to be untrue or of a work around let me know.
+
 - The library currently does not support array columns. This may be implemented
   for a later release depending on demand.
   
@@ -46,13 +72,13 @@ 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.2.0-mswin32.gem
+   gem install fireruby-0.3.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.2.0-powerpc-darwin.gem
+   sudo gem install fireruby-0.3.0-powerpc-darwin.gem
    
 Once the gem installation is complete the FireRuby functionality can be accessed
 in code with the usual gem style requires...
@@ -63,13 +89,16 @@ in code with the usual gem style requires...
 == Build Details
 
 The FireRuby library is an extension of the Ruby language written in C. For Mac
-OS X the library was built against Firebird installed as a framework, version
-1.5.1, and with Ruby version 1.8.2. For the Windows platform the library was
-built 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. 
-  
+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.
+
 == So How Do I Use It?
 
 This section will provide some examples of usage for the the FireRuby classes.
@@ -196,17 +225,10 @@ this is and you're only using Firebird it's probably safe to use a value of
 3 here. Other values are for backward compatibility. Consult the Firebird and
 Interbase documentation for more details.
 
-Anyway, now that we have our Statement how do we use it. Well, there are two
-approaches to using the Statement object. For statements like the one used
-above, queries that take no parameters, you can use the Statement object to
-build a ResultSet object, like so...
-
-   r = ResultSet.new(s)
-   
-The ResultSet class will be covered in a little more detail below. The other
-means by which a Statement can be used is to call one of it's execute methods.
-The one to be called depends on whether the Statement requires parameters or
-not. What are parameters you ask? Well, look at the following...
+Anyway, now that we have our Statement how do we use it? Well, the answer is
+that we call once of the Statement objects execute methods. The one to be called
+depends on whether the Statement requires parameters or not. What are parameters
+you ask? Well, look at the following...
 
    s = Statement.new(cxn, tx, 'SELECT * FROM MY_TABLE WHERE MYID = ?', 3)
    
@@ -216,25 +238,34 @@ that wraps such a piece of SQL must be provided with the necessary parameters
 to execute properly. Where a Statement object represents SQL that requires a
 parameter then the execute_for method must be called, like this...
 
-   r = s.execute_for([25])
+   s.execute_for([25])
    
 This code executes the SQL substituting the parameters from the array of data
 passed to the function call. If a Statement object represents SQL that does not
 require parameter values a call to the execute method will suffice, such as the
 following...
 
-   r = s.execute
+   s.execute
    
 The execute methods for the Statement class, as with all of the execute methods
-for the FireRuby library, have two potential return values. They will either
-return nil or they will return a ResultSet object. A ResultSet object will only
-be returned for SQL statements that constitute a query, irrespective of whether
-that query returns any data. For all other SQL statements the various execute
-method will return nil.
+for the FireRuby library, have three potential return values. They will either
+return an Integer, a ResultSet object or nil. A ResultSet object will only be
+returned for SQL statements that constitute a query, irrespective of whether
+that query returns any data. For all other SQL statements (inserts, updates and
+deletes) the execute method will return a count of the number of rows affected
+by the statement execution. For any other SQL statements the various execute
+methods will return nil.
 
 A ResultSet object represents a handle by which the data retrieved for a SQL
-query can be accessed. To fetch a row of data from a ResultSet object you call
-the fetch method, like the following...
+query can be accessed. While it's possible to obtain a ResultSet from one of the
+execute methods on the Connection, Transaction or Statement classes it is more
+efficient to create one directly. The constructor for the ResultSet class
+accepts the same arguments as the constructor for the Statement class but will
+throw an exception if the SQL statement specified is not a query.
+
+Once we have obtained a ResultSet we can extract the rows of data for a query
+from it. To fetch a row of data from a ResultSet object you call the fetch
+method, like the following...
 
    row = r.fetch
    
@@ -258,8 +289,9 @@ columns of data within the row like this...
    value = row[1]
    
 The index specified to the array dereference operator specifies the column that
-you want the data for. Column indices start at 0. Alternatively you can use the
-column name to access the data, like this...
+you want the data for. Column indices start at 0. Alternatively you can treat
+the Row object like a read only Hash object and use the column name to access
+the data, like this...
 
    value = row['MYID']
    
@@ -267,9 +299,8 @@ This is beneficial as it frees you from the constraint of knowing the ordering
 of the columns within the row. For more information of the Row class please
 consult the API documentation.
 
-Well that covers the bulk of the classes provided by the FireRuby library. The
-three which haven't been touched upon are the Generator class, the Blob class
-and the FireRubyException class.
+That covers the bulk of the SQL classes provided by the FireRuby library. The
+two which haven't been touched upon are the Generator class and the Blob class.
 
 The Generator class is a wrapper around the Firebird generator facility. A
 generator, also known as a sequence, provides a means of creating a list of
@@ -282,8 +313,76 @@ The Blob class is returned as part of the Row object data obtained from a
 ResultSet. The class wraps the concept of a binary large object stored in the
 database. Consult the API documentation for further information.
 
-The FireRubyException class is the error class used by the FireRuby library
-whenever it hits trouble. If an exception is raised by the FireRuby code then
-its extremely likely that it will be an instance of this class. The class
-provides a means of finding out a little more about what exactly has gone
-wrong. Again, consult the API documentation for more details.
+=== Errors
+
+Whenever a problem occurs within a FireRuby library class then it is likely that
+a FireRubyException will be thrown. The FireRubyException class is the error
+class used by the FireRuby library whenever it hits trouble. The class provides
+a means of finding out a little more about what exactly has gone wrong. Again,
+consult the API documentation for more details.
+
+=== Firebird Service Manager
+
+The FireRuby library provides a set of class that provide for an interaction
+with the Firebird service manager. This interaction allows for the execution of
+tasks, such as the backing up of a database, on the database server. To execute
+such tasks against the service manager for a Firebird instance you first need
+to obtain a ServiceManager class instance. This can be done as follows...
+
+   sm = ServiceManager.new('localhost')
+   
+The constructor for the ServiceManager class takes a single parameter that is
+the host name of the server running the Firebird instance. In the example above
+this would be a local machine but could be any machine that can be reached over
+the network (NOTE: although Firebird supports a number of underlying transport
+protocols in accessing a service manager currently only TCP/IP is supported for
+the FireRuby library).
+
+The next step in executing service manager tasks involves connecting your
+ServiceManager object to the service manager for a Firebird instance. To do this
+you must supply a user name and password. The user name and password used must
+be a user that exists on the Firebird instance. The user you connect as can
+affect the access to services that you receive. For example, to connect as the
+database administrator you might do the following...
+
+   sm.connect('sysdba', 'masterkey')
+   
+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
+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.
+
+To use the task classes you construct a class instance, configure it as you may
+need and then execute it. Here's an example of going through this procedure to
+create a database backup...
+
+   b = Backup.new('c:\database\work.fdb', 'c:\temp\work.bak')
+   b.metadata_only = true
+   b.execute(sm)
+   
+The first list creates the new Backup object. The first parameter passed to this
+call is the path and name of the primary file of the database to be backed up
+(NOTE: All paths are relative to the database server). The second parameter is
+the path and name of the database backup file to be created. The second line
+sets an attribute on the class to indicate that only the metadata (i.e. it's
+schema but not it's data) for the specified database should be included in the
+backup. The final line begins the execution of the backup task on the database
+server. This will block until completion.
+
+Its also possible to execute a batch of tasks against a service manager. To do
+this you would accumulate the tasks to be executed and then pass them all at the
+same time to the ServiceManager#execute method, like so...
+
+   t = Array.new
+   t.push(Backup.new('c:\database\work.fdb', 'c:\temp\work.bak'))
+   ...
+   # Create more tasks here and add them to the array.
+   
+   sm.execute(*t)
+   
+The tasks will be executed in the order they are specified to the ServiceManager
+object. For the example above this would mean in the order they were added to
+the array. For more details on the ServiceManager class and the various task
+classes please consult the API documentation.