=====================================================================
README for the IBM_DB Adapter 0.7.5 and Driver 0.6.0 (2007/04/30)
For ActiveRecord Version 1.15.3 (and Rails 1.2.3)
=====================================================================

Change Log
==============
2007/06/19 (IBM_DB adapter 0.7.5, driver 0.6.0):
  - Driver code (ibm_db.c) remains at the same level: 0.6.0 (no changes)
  - Fixed client attributes initialization on connection setup [11264]
  - Fixed rake db:schema:dump native data types limits incompatible with table create

2007/06/01 (IBM_DB adapter 0.7.0, driver 0.6.0):
  - Driver code (ibm_db.c) remains at the same level: 0.6.0 (no changes)
  - Fixed remaining failure on {:null => true} option for XML data type [#10877]
  - Fixed handling of {:id => false} option during table creation in DB2 for zOS
  - Fixed handle_lobs failures in table creation for has_many/belongs_to [#10701]
  - Fixe db2-i5-zOS.yaml content (removed inadvertent tab) [#11234]

2007/05/10 (IBM_DB adapter 0.6.5, driver 0.6.0):
  - Driver code (ibm_db.c) remains at the same level: 0.6.0 (no changes)
  - Fixed regression for reconnect after being inactive (connection recycle)
  - Fixed rake db:schema:load failures on boolean data type [#10683]
  - Fixed XML default option (:null => true for XML data type) [#10754]
  - Fixed DB2 for zOS version 9 handling of column changes for DEFAULT NULL

2007/04/30 (0.6.0):
  - Support for remote connections to DB2 Universal Database on z/OS version 9
  - Support for result set pagination via ActiveRecord add_limit_offset! method 
    for DB2 Universal Database on z/OS and i5/OS
  - Defect fixes
  - Improved documentation 

2007/04/20 (0.4.6):
  - Fixed XML columns creation default value (NOT NULL)
  - Fixed border case for IS NULL in where clauses
  - Improved documentation (connection attributes)

2007/04/20 (0.4.5):
  - Fixed reconnect problems: driver (IBM_DB::active) and adapter (active)
  - Client connection attribute rename (app_user to replace user)
  - Improved support for ROWID data type (DB2 for zOS version 8 and 9)

2007/03/21 (0.4.0):
  - Support added for remote connectivity to DB2 zOS version 8
  - Support added for remote connectivity to DB2 i5 v5r3 and v5r4
  - Improved migration support (added change_column method)
  - Support for setting and retrieving values for client attributes (user, 
    account, application, workstation)

2006/10/31 (0.2.0):
  - Significant performance improvements
  - Improved stored procedure support at driver level
  - Added support for Large Object data types (LOBs) greater than 32K (BLOB, CLOB, XML) in size
  - Added XML data type support for native storage of XML documents
  - Significant quality improvements, through many bug fixes in the driver and adapter
  - Improved migration support (added add_column and remove_column methods)

2006/06/07 (0.1.0):

  - Fixed compatibility issue with other adapters
  - If a schema is omitted in database.yml, the username is now used as default schema
  - Introduced descriptive CLI error messages when a connection or an execute statement fails
  - Introduced check against schema in method 'indexes'

Supported Operating Systems 
============================
  - Linux 32/64 bit
  - Microsoft Windows 32 bit
  - IBM AIX 32/64 bit
  - HP-UX 32/64 bit
  - Sun Solaris 32/64 bit


Supported Databases
====================
  - IBM DB2 Universal Database on Linux/Unix/Windows versions 8 and 9
  - Remote connections to IBM DB2 Universal Database on i5/OS versions V5R3 and V5R4. 
    Please ensure PTF SI27358 (includes SI27250) is installed in i5/OS version 5R3 and
    and PTF SI27256 is installed while using i5/OS version 5R4.
  - Remote connections to IBM DB2 Universal Database on z/OS version 8 and 9


There are two alternatives for installing the IBM_DB adapter and driver:
  A. Installing as a Ruby gem in the Ruby runtime
  B. Installing as a Rails plugin in a specific Rails application runtime
Note: The IBM_DB driver can also be built separately (from source) and used in direct API calls.

A. Installing the IBM_DB adapter and driver as a Ruby gem
=======================================================
The IBM_DB gem is an ActiveRecord adapter and requires the abstract adapter to register it
in the list of RAILS_CONNECTION_ADAPTERS (active_record.rb) before it can be utilized in
the Rails framework. Once registered, the IBM_DB adapter and its dependencies (ibm_db Ruby
driver and the IBM Driver for ODBC and CLI) are loaded. This enables any application in the
Ruby environment, including Rails, to interact with IBM data servers.

1. Windows platforms:
=====================
  INSTALL (as Ruby gem)
   To remove previous gem version (optionally):
    D:\>gem uninstall ibm_db
    Successfully uninstalled ibm_db version 0.6.0

  Example:
    D:\>gem install ibm_db
    Bulk updating gem source index for: http://gems.rubyforge.org
    Select which gem to install for your platform (i386-mswin32)
    1. ibm_db 0.6.5 (mswin32)
    2. ibm_db 0.6.5 (ruby)
    3. ibm_db 0.6.0 (mswin32)
    4. ibm_db 0.6.0 (ruby)

  Running “gem install ibm_db” you are presented with two choices for each release 
  (mswin32 or ruby). Choose “mswin32” and the native extension (“ibm_db” driver)
  binary file for Windows is installed.

  TEST (simple gem install verification)
   Note: IBM_DB gem requires a manual step after install:
         add “ibm_db” into gems\1.8\gems\activerecord-1.15.3\lib\active_record.rb (Line 77)
   D:\NewApp>dir vendor\plugins
   D:\NewApp>irb
     irb(main):001:0> gem 'ibm_db'
     irb(main):002:0> require 'mswin32/ibm_db'   // notice the [mswin32] in the library path
     irb(main):003:0> IBM_DB::connect 'sample', 'db2admin', 'secret'
   D:\NewApp>ruby script\console

   BUILD (optionally) “ibm_db” gem from sources (ibm_db-x.x.x.tar.gz):
   1. Download source from Rubyforge
      http://rubyforge.org/frs/?group_id=2361
   2. Build gem from specification (IBM_DB.gemspec)
      D:\IBM_DB_Adapter\ibm_db>gem build IBM_DB.gemspec
  

2. Linux and Unix platforms:
============================

  INSTALL (as Ruby gem)
    To remove previous gem version (optionally):
    $ gem uninstall ibm_db
    Successfully uninstalled ibm_db version 0.6.0

   Note: DB2 environment is required while using an arbitrary user account
         (other than the DB2 install user account)
   $ . /home/db2inst1/sqllib/db2profile
   $ export IBM_DB_DIR=/opt/ibm/db2/V9.1
   $ export IBM_DB_LIB=/opt/ibm/db2/V9.1/lib32
   $ gem install ibm_db
     Select which gem to install for your platform (i686-linux)
     1. ibm_db 0.6.5 (mswin32)
     2. ibm_db 0.6.5 (ruby)
     3. ibm_db 0.6.0 (ruby)
     4. ibm_db 0.6.0 (mswin32)
     ...
     Running “gem install ibm_db” you are presented with two choices for each release
     (mswin32 or ruby). Choose “ruby” and the native extension (“ibm_db” driver) is built.
     ...
     > 2
     Building native extensions.  This could take a while...
     Successfully installed ibm_db-0.6.5
     Installing ri documentation for ibm_db-0.6.5...
     Installing RDoc documentation for ibm_db-0.6.5...
     
  TEST (simple gem install verification)
   Note: IBM_DB gem requires a manual step after install:
         add “ibm_db” into /gems/activerecord-1.15.3/lib/active_record.rb (Line 77)
   $ ls -al vendor/plugins/
   $ irb
     irb(main):001:0> gem 'ibm_db'
     irb(main):002:0> require 'ibm_db'    // notice the library path (different on win32)
     irb(main):003:0> IBM_DB::connect 'sample', 'db2admin', 'secret'
   $ ./script/console

  BUILD (optionally) “ibm_db” gem  from sources (ibm_db-x.x.x.tar.gz):
  1. Download source from Rubyforge
     http://rubyforge.org/frs/?group_id=2361
  2. Build gem from specification (IBM_DB.gemspec)
     $ cd IBM_DB_Adapter/ibm_db
     $ gem build IBM_DB.gemspec


B. Installing the IBM_DB adapter and driver as a Rails plugin
=============================================================
IBM_DB adapter and driver install as plugin provides support for IBM data servers
within the scope of a specific and individual Rails application. Rails plugins do
not offer the version management specific to Ruby gems, but does provide an 
initialization mechanism which allows the IBM_DB plugin to self-insert into the
ActiveRecord's list of supported adapters: RAILS_CONNECTION_ADAPTERS. Therefore,
after installing IBM_DB as plugin in your Rails application, no manual step is required
for the Rails framework to load it.

1. Windows platforms
=====================
  Register Repository and Query:

  A. Download and install Subversion (SVN) client from:
      http://subversion.tigris.org/servlets/ProjectDocumentList?folderID=91
     Register rubyibm project as plugin source
      D:\NewApp>ruby script\plugin  source  svn://rubyforge.org/var/svn/rubyibm/trunk/IBM_DB_Adapter/

  B. Accessing RubyForge repository through HTTP (no SVN client required) is NOT YET ENABLED
     D:\NewApp>ruby script\plugin  source  http://rubyibm.rubyforge.org/IBM_DB_Adapter/

  LIST plugin
  D:\NewApp>ruby script\plugin  list

  INSTALL (as Rails plugin)
   D:\NewApp>ruby script\plugin  install  ibm_db

  TEST (simple plugin install verification)
   Note: Make sure there's no ibm_db in gems\1.8\gems\activerecord-1.15.3\lib\active_record.rb (Line 77)
    D:\NewApp>ruby script\console

2. Linux and Unix platforms
===========================
  Register Repository and Query:

  A. Ensure Subversion (SVN) client is installed or download from:
      http://subversion.tigris.org/project_packages.html
     Register rubyibm project as plugin source
      $ ./script/plugin  source  svn://rubyforge.org/var/svn/rubyibm/trunk/IBM_DB_Adapter/

  B. Accessing RubyForge repository through HTTP (no SVN client required) is NOT YET ENABLED
     $ ./script/plugin  source  http://rubyibm.rubyforge.org/IBM_DB_Adapter/

  LIST plugin
   $ ./script/plugin list

  INSTALL (as Rails plugin)
   $ ./script/plugin install  ibm_db

  TEST (simple plugin install verification)
   Note: Make sure there's no ibm_db in /gems/activerecord-1.15.3/lib/active_record.rb (Line 77)
    $ ./script/console


Instructions for building and installing the IBM_DB driver from source
=======================================================================
Building the driver manually as described below is not required if any the install
alternatives above have been pursued. This manual procedure is in fact automated
on Linux and UNIX platforms by the IBM_DB gem and plugin install, but is presented
here only for reference, and also involves running the unit tests.

 Prerequisites:
  Install Ruby from:
    http://rubyforge.org

  Linux and Unix platforms:
   Note: commands may vary depending on the shell used
    - To setup DB2 environment while using an arbitrary user account
      (other than the DB2 install user account):
      Example:
        $ . /home/db2inst1/sqllib/db2profile

    - To configure test database:
      DB2 v9.x: some IBM_DB driver tests require a UTF-8 database:
        $ db2 CREATE DATABASE testdrv USING CODESET UTF-8 \
          TERRITORY US COLLATE USING SYSTEM PAGESIZE 32768 
      DB2 v8.x: driver tests 195 and 52949 requires XML functionality
      only available in DB2 v9.x

    - To configure database connection parameters edit config.yaml
      Example:
        database: testdrv 
        user:     db2inst1
        password: password
        hostname: localhost
        port:     50000

    - To compile and link with DB2 client libraries:
      $ export IBM_DB_DIR=/opt/ibm/db2/V9.1
      $ export IBM_DB_LIB=/opt/ibm/db2/V9.1/lib32

  Windows platforms:
    - Install Visual C++ 2003, Platform SDK (latest), .Net SDK Version 1.1 from:
      http://wiki.tcl.tk/11431
    - Set environment:
      CALL "C:\Program Files\Microsoft Platform SDK for Windows Server 2003 R2\SetEnv.Cmd"
      CALL "C:\Program Files\Microsoft Visual C++ Toolkit 2003\vcvars32.bat"
      SET LIB=%LIB%;C:\Program Files\Microsoft Visual Studio .NET 2003\Vc7\lib
    - To configure database connection parameters edit config.yaml
  
 Build and Execution:
  rake 

 Execution of tests without compilation (must have .so in ibm_db source directory):
  rake onlytests

 Execution of a single test inside the tests directory can be done by the following:
  export SINGLE_RUBY_TEST=test_001.rb
  rake 


Limitations and known problems
==============================
 - ActiveRecord rename_column method is not supported for DB2 LUW, zOS and i5
 - ActiveRecord remove_column method is not supported for DB2 zOS
 - The following tests from the ActiveRecord 1.15.3 test suite are expected to fail
    - test_limited_eager_with_multiple_order_columns
    - test_limited_eager_with_order
    - test_assign_ids_ignoring_blanks
    - test_build_by_new_record
    - test_get_ids
    - test_select_limited_ids_list
    - test_add_index
 - The following tests from the driver test suite are expected to fail on DB2 version 8
   on Linux/Unix/Windows because of missing native XML support. If you want to
   make use of the native XML features in DB2, please upgrade to version 9
    - test_195.rb
    - test_52949.rb
 - The driver returns an error when you try to insert a TIMESTAMP value into a DATE column. 
   To fix this, please ensure that the following configuration keyword PATCH2=58 is set 
   in the COMMON section of your DB2 CLI initialization file (db2cli.ini):
    - set: db2 UPDATE CLI CFG FOR SECTION COMMON USING PATCH2 58
    - verify: db2 GET CLI CFG FOR SECTION COMMON
   Please refer to http://publib.boulder.ibm.com/infocenter/db2luw/v9/topic/com.ibm.db2.udb.apdv.cli.doc/doc/c0007882.htm
   for more information.
 - The behaviour of ActiveRecord::Base.find(:first) without an :order attribute can be unpredictable.
   The first record (i.e. the record with the minimum id) may be not be retrieved. In a relational model,
   the order of the rows returned is unpredictable and independent of the order of insertion.
   This issue may be addressed in a future release. 
 - Rails applications on DB2 9 require the APPLHEAPSZ database configuration parameter to be
   set to or above 1024. You will need to set this parameter for each database for which you will be
   running DB2 on Rails applications. Following is the command syntax for updating the
   applheapsz parameter:
     > db2 update db cfg for <database_name> using APPLHEAPSZ 1024
   To enable this parameter, you need to restart your DB2 instance.
 - IBM_DB is not supported on JRuby. As stated in the JRuby Wiki, "Basics of Getting JRuby Running":
   'You may install other gems, but keep in mind that libraries with C extension dependencies 
   will not work in JRuby.' http://www.headius.com/jrubywiki/index.php/Getting_Started
   The IBM_DB adapter relies on IBM_DB driver (C extension) and the IBM Driver for ODBC and
   CLI to access databases on IBM data servers. Alternatively, you can either use the regular C
   implementation of Ruby, or use ActiveRecord-JDBC adapter to access databases.

To Do
====
 - Support Informix Dynamic Server 11.10
 - Support ActiveRecord remove_column method for DB2 zOS version 9


Feedback
========
  Your feedback is very much appreciated and expected through Rubyforge:
   - rubyibm project:     http://rubyforge.org/projects/rubyibm/
   - rubyibm forum:       http://rubyforge.org/forum/?group_id=2361
   - rubyibm bug reports: http://rubyforge.org/tracker/?group_id=2361
   - IBM_DB developers:   rubyibm-developers@rubyforge.org