README for the IBM_DB Adapter (2.5.7) and Driver (2.5.7) (2011/09/18) For ActiveRecord Version >= 1.15.5 (and Rails >= 1.2.5)

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 Fixpak15 or 9 Fixpak2 and above
- 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
- Informix Dynamic Server 11.10 and beyond.
  Please ensure that the IBM DataServer Viper 2 client is installed.

Installing the IBM_DB adapter and driver as a Ruby gem

The IBM_DB gem is an ActiveRecord adapter. Installing the IBM_DB adapter and driver as a gem enables any application in the Ruby environment, including Rails, to interact with IBM data servers.

Note : - 1) If using activerecord version below 2.0 then it requires that the ibm_db adapter be registered with the list of connection adapters by manually adding ibm_db at line 77 (approx) in the file activerecord.rb (GEM_HOMEactiverecord-<version>lib).

2) The IBM_DB driver can also be built separately (from source) and used in direct API calls.

  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 1.0.0 (mswin32)
  2. ibm_db 1.0.0 (ruby)
  3. ibm_db 0.10.0 (mswin32)
  4. ibm_db 0.10.0 (ruby)

Running gem install ibm_db you are presented with two choices for each release 
(mswin32 or ruby)choose mswin32. This will install the IBM_DB gem containing 
the pre-built binary file of the driver which is a C-extension of Ruby.

TEST (simple gem install verification)
 Note: The manual step after install if using activerecord version below 2.0:
       add ibm_db into GEM_HOME\1.8\gems\activerecord-1.15.3\lib\active_record.rb (Line 77)
 D:\rails NewApp
 D:\cd NewApp      
 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
  1. 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_INCLUDE=DB2HOME/include (eg. /home/db2inst1/sqllib/include or /opt/ibm/db2/v9.5/include)
 $ export IBM_DB_LIB=DB2HOME/lib     (eg. /home/db2inst1/sqllib/lib or /opt/ibm/db2/V9.5/lib32)
 $ gem install ibm_db
   Select which gem to install for your platform (i686-linux)
   1. ibm_db 1.0.0 (mswin32)
   2. ibm_db 1.0.0 (ruby)
   3. ibm_db 0.10.0 (ruby)
   4. ibm_db 0.10.0 (mswin32)
   ...
   Running gem install ibm_db you are presented with two choices for each release
   (mswin32 or ruby) choose ruby. This will build the native extension (ibm_db driver) and installs the ibm_db gem.
   ...
   > 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: The manual step after install, if using activerecord version below 2.0 is:
       add ibm_db into GEM_HOME\1.8\gems\activerecord-1.15.3\lib\active_record.rb (Line 77)
 $ irb
   irb(main):001:0> gem 'ibm_db'
   irb(main):002:0> require 'ibm_db'    // notice the library path (different on win32, use require 'mswin32/ibm_db')
   irb(main):003:0> IBM_DB.connect 'sample', 'db2admin', 'secret'
 $ 

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

Instructions for building and installing the IBM_DB driver from source

Building the driver manually as described below is not required if the install process above has been pursued. This manual procedure is in fact automated on Linux and UNIX platforms by the IBM_DB gem 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_INCLUDE=DB2HOME/include (eg. /home/db2inst1/sqllib/include or /opt/ibm/db2/v9.5/include)
      $ export IBM_DB_LIB=DB2HOME/lib     (eg. /home/db2inst1/sqllib/lib or /opt/ibm/db2/V9.5/lib32)

 Windows platforms:
   - Install Visual C++ 2005, Platform SDK (latest), .Net SDK (latest)
   - Set environment:
     CALL "C:\Program Files\Microsoft Platform SDK for Windows Server 2005\SetEnv.Cmd"
     CALL "C:\Program Files\Microsoft Visual C++ Toolkit 2005\vcvars32.bat"
     SET LIB=%LIB%;C:\Program Files\Microsoft Visual Studio .NET 2005\Vc8\lib
   - To configure database connection parameters edit config.yml

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_CtlgConn.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 with ibm_db gem < 0.9.5 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 and Informix Dynamic Server because of missing native XML support. If you want to
  make use of the native XML features in DB2, please upgrade to version 9 or later
   - 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.
- If you see connectivity issues with Informix Dynamic Server, please ensure that the server is configured to accept DRDA connections.
  Please refer to http://publib.boulder.ibm.com/infocenter/idshelp/v111/index.jsp?topic=/com.ibm.admin.doc/admin154.htm for more information.
- The following tests from the ActiveRecord 1.15.3 test suite with ibm_db gem < 0.9.5 are expected to fail on Informix Dynamic Server
   - test_quote
   - test_to_xml
   - test_should_calculate_grouped_by_function
   - test_should_calculate_grouped_by_function_with_table_alias
   - test_inserts_with_pre_and_suffix
   - test_add_table_with_decimals
   - test_no_limits_datatypes_IBM_DB
   - test_instance_update_should_quote_pkey
   - test_integer_columns
   - test_arguments_line_up
   - test_no_dump_errors
   - test_schema_dump_includes_decimal_options
- 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.
- Query caching feature of ActiveRecord-2.0 not supported 
- When using ActiveRecord-2.1.0 it requires that ActiveRecord be patched, with the patch in the link below:
		http://rails.lighthouseapp.com/attachments/26975/association_preloading.diff
	The patch is required because, ActiveRecord 2.1.0 generates a non-standard SQL identifier,while preloading has_and_belongs_to_many associations,
	which standard compliant databases like DB2 do not support. The bug report, against ActiveRecord, can be found in the link below
		http://rails.lighthouseapp.com/projects/8994/tickets/394-patch-fixed-non-standard-sql-generated-by-preloading-has_and_belongs_to_many-associations
- ActiveRecord-2.1.0 test suite changes appropriate for DB2/IDS will be updated in the next release of the gem.(Updated in release 0.10.0)
- The following tests from the ActiveRecord 2.1.0 test suite with ibm_db gem 0.10.0 are expected to fail on DB2 LUW
	- test_read_attributes_before_type_cast_on_datetime
	- test_to_xml
	- test_native_types
	- test_counting
	- test_counting_with_column_name_and_hash
	- test_counting_with_empty_hash_conditions
	- test_counting_with_single_conditions
	- test_counting_with_single_hash
	Note :- 1)	The test cases from HasManyAssociations (4-8) above are found failing only when run as part of
			the complete suite. However they pass when run standalone.
		2)	Also there are two test cases (test_validate_uniqueness_with_non_standard_table_names, test_update_all_with_non_standard_table_name)which run against table with non-standard name. Given that DB2/IDS is standard compliant these test cases are expected to fail.
			To have these test cases passing rename the fixtures file warehouse-things to warehouse_things.
- The following tests from the ActiveRecord 2.1.0 test suite with ibm_db gem 0.10.0 are expected to fail on Informix Dynamic Server
	- test_attributes_on_dummy_time
	- test_quote
	- test_read_attributes_before_type_cast_on_datetime
	- test_save_for_record_with_only_primary_key
	- test_save_for_record_with_only_primary_key_that_is_provided
	- test_to_xml
	- test_utc_as_time_zone
	- test_should_calculate_grouped_by_function
	- test_should_calculate_grouped_by_function_with_table_alias
	- test_include_query
	- test_binary_in_fixtures
	- test_inserts_with_pre_and_suffix
	- test_create
	- test_add_column_with_precision_and_scale
	- test_add_table_with_decimals
	- test_native_types
	- test_schema_dump_includes_decimal_options
- Usage with Rails-3.0.3/Rails-3.0.4

- To use with Rails-3.0.3/4 patch latest Arel with the patch available at gist.github.com/814491 Unicode Support

- Available only with Ruby version 1.9 and above
- Data returned from the driver will be in UTF8 encoding format.
- The input data to the driver can be in any Ruby supported encoding format.

To Do

- 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