ruby-oci8 1.0.7-x86-mswin32-60 → 2.0.1-x86-mswin32-60

data/README

@@ -1,415 +1,86 @@
 = How to make
 
-== Oracle Full Client (not Oracle Instant Client)
+* <tt>ruby</tt> and <tt>make</tt> (or nmake on MSVC) commands in the environment variable <tt>PATH</tt>?
+* <tt>ruby</tt> is 1.8.0 or later? (Use ruby-oci8 0.1.x for ruby 1.6.x.)
 
-1. check the followings:
-   - ruby and make (or nmake on MSVC) are in the environment variable PATH.
-   - sqlplus runs correctly.
+== For OCI installed by Oracle Universal Installer
+make sure the environment variable ORACLE_HOME (or registry on Windows)
+is set correctly. run the the following commands.
 
-2. check library search path.
+  make (or nmake on MSVC)
 
-   If sqlplus runs correctly, the environments variables are okay in general.
-   But if Oracle is 64-bit and ruby is 32-bit, make sure $ORACLE_HOME/lib32
-   in 32-bit library search path. (LD_LIBRARY_PATH_32 on Solaris, SHLIB_PATH
-   on HP-UX PA-RISC.)
+== For OCI installed by Oracle Instant Installer
 
-3. make and install
-   gzip -dc ruby-oci8-0.1.xx.tar.gz | tar xvf -
-   cd ruby-oci8-0.1.xx
-   make          # or nmake on MSVC.
-   make install
+linux:
+  ruby setup.rb config -- --with-instant-client
+  make
 
-== Oracle Instant Client
+others:
+  ruby setup.rb config -- --with-instant-client=/path/to/instantclient10_1
+  make (or nmake on MSVC)
 
-1. donwload "Instant Client Package - Basic" and "Instant Client Package - SDK".
+= On compilation failure
 
-   OTN (Oracle Technology Network):
-     URL:http://otn.oracle.com/
-   Instant Client Donload Page:
-     http://www.oracle.com/technology/software/tech/oci/instantclient/index.html
+Please report the following information to kubo@jiubao.org.
 
-   note:
-     download 32-bit packages for 32-bit ruby even though your OS is 64-bit.
+* last 100 lines of 'ext/oci8/mkmf.log'.
+* the results of the following commands:
+    ruby -r rbconfig -e "p Config::CONFIG['host']"
+    ruby -r rbconfig -e "p Config::CONFIG['CC']"
+    ruby -r rbconfig -e "p Config::CONFIG['CFLAGS']"
+    ruby -r rbconfig -e "p Config::CONFIG['LDSHARED']"
+    ruby -r rbconfig -e "p Config::CONFIG['LDFLAGS']"
+    ruby -r rbconfig -e "p Config::CONFIG['LIBS']"
+    ruby -r rbconfig -e "p Config::CONFIG['GNU_LD']"
+* if you use gcc:
+    gcc --print-prog-name=ld
+    gcc --print-prog-name=as
+* on platforms which can use both 32bit/64bit binaries:
+    file $ORACLE_HOME/bin/oracle
+    file `which ruby`
+    echo $LD_LIBRARY_PATH
 
-2. install Oracle Instant Client Packages.
+= How to run unit test
 
-   zip packages:
+before runing unit test, 
+1. connect to Oracle as system:
 
-     mkdir /opt
-     mkdir /opt/oracle
-     cd /opt/oracle
-     unzip path/to/instantclient-basic-XXXX-10.1.0.X.zip
-     unzip path/to/instantclient-sdk-XXXX-10.1.0.X.zip
+    $ sqlplus system/<password_of_system>
 
-   rpm packages:
+2. create user ruby:
 
-     rpm -i path/to/oracle-instantclient-basic-10.1.0.X-X.XXX.rpm
-     rpm -i path/to/oracle-instantclient-devel-10.1.0.X-X.XXX.rpm
+    SQL> CREATE USER ruby IDENTIFIED BY oci8;
 
-     note for Debian user:
-       convert rpm packages to deb packages by alien.
-         alien path/to/oracle-instantclient-basic-10.1.0.X-X.XXX.rpm
-         alien path/to/oracle-instantclient-devel-10.1.0.X-X.XXX.rpm
-         dpkg -i oracle-instantclient-basic_10.1.0.X-X_XXX.deb
-         dpkg -i oracle-instantclient-devel_10.1.0.X-X_XXX.deb
-
-3. check installed libraries. (UNIX zip packages only)
-
-   If /opt/oracle/instantclient10_1/libclntsh.so not found,
-   make a symbolic link.
-
-     cd /opt/oracle/instantclient10_1
-     ln -s libclntsh.so.10.1 libclntsh.so
-
-   note:
-     libclntsh.sl for HP-UX PA-RISC
-     libclntsh.dylib for Mac OS X
-
-4. set library search path.
-
-   Windows:
-     add c:\oracle\instantclient10_1 to PATH.
-
-   AIX:
-     add /opt/oracle/instantclient10_1 to LIBPATH.
-
-   HP-UX PA-RISC 32-bit ruby:
-     add /opt/oracle/instantclient10_1 to SHLIB_PATH.
-
-   SPARC/Solaris 32-bit ruby:
-     add /opt/oracle/instantclient10_1 to LD_LIBRARY_PATH_32.
-
-   SPARC/Solaris 64-bit ruby:
-     add /opt/oracle/instantclient10_1 to LD_LIBRARY_PATH_64.
-
-   Mac OS X:
-     add /opt/oracle/instantclient10_1 to DYLD_LIBRARY_PATH.
-
-   Others:
-     add /opt/oracle/instantclient10_1 to LD_LIBRARY_PATH.
-
-5. make and install.
-
-   zip packages:
-     gzip -dc ruby-oci8-0.1.xx.tar.gz | tar xvf -
-     cd ruby-oci8-0.1.xx
-     ruby setup.rb config -- --with-instant-client=/opt/oracle/instantclient10_1
-     make
-     make install
-
-   rpm packages:
-     gzip -dc ruby-oci8-0.1.xx.tar.gz | tar xvf -
-     cd ruby-oci8-0.1.xx
-     ruby setup.rb config -- --with-instant-client
-     make
-     make install
-
-== On compilation failure
-
-  Please report the following information to kubo@jiubao.org.
-
-  * last 100 lines of 'ext/oci8/mkmf.log'.
-  * the results of the following commands:
-      ruby --version
-      ruby -r rbconfig -e "p Config::CONFIG['host']"
-      ruby -r rbconfig -e "p Config::CONFIG['CC']"
-      ruby -r rbconfig -e "p Config::CONFIG['CFLAGS']"
-      ruby -r rbconfig -e "p Config::CONFIG['LDSHARED']"
-      ruby -r rbconfig -e "p Config::CONFIG['LDFLAGS']"
-      ruby -r rbconfig -e "p Config::CONFIG['DLDLAGS']"
-      ruby -r rbconfig -e "p Config::CONFIG['LIBS']"
-      ruby -r rbconfig -e "p Config::CONFIG['GNU_LD']"
-  * if you use gcc:
-      gcc --print-prog-name=ld
-      gcc --print-prog-name=as
-  * on platforms which can use both 32bit/64bit binaries:
-      file $ORACLE_HOME/bin/oracle  # Full Client only
-      file `which ruby`
-      echo $LD_LIBRARY_PATH
-      echo $LIBPATH              # AIX
-      echo $SHLIB_PATH           # HP-UX PA-RISC
-      echo $DYLD_LIBRARY_PATH    # Mac OS X
-      echo $LD_LIBRARY_PATH_32   # Solaris
-
-= How to run
-
-== Oracle Full Client (not Oracle Instant Client)
-
-1. set environmet variables.
-
-   The follwing environmet variables are required:
-
-     * ORACLE_HOME
-       UNIX only. This variable is set on registry on Windows.
-
-     * NLS_LANG
-       UNIX only. This variable is set on registry on Windows.
-
-     * library serach path
-
-       Windows:
-         add %ORACLE_HOME%\bin to PATH.
-
-       AIX:
-         add $ORACLE_HOME/lib to LIBPATH.
-
-       HP-UX PA-RISC 32-bit ruby:
-         add $ORACLE_HOME/lib32 to SHLIB_PATH.
-         If $ORACLE_HOME/lib32 doesn't exist, add $ORACLE_HOME/lib instead.
-
-       SPARC/Solaris 32-bit ruby:
-         add $ORACLE_HOME/lib32 to LD_LIBRARY_PATH_32.
-         If $ORACLE_HOME/lib32 doesn't exist, add $ORACLE_HOME/lib instead.
-
-       SPARC/Solaris 64-bit ruby:
-         add $ORACLE_HOME/lib to LD_LIBRARY_PATH_64.
-
-       Mac OS X:
-         add $ORACLE_HOME/lib to DYLD_LIBRARY_PATH.
-
-       Other 32-bit ruby:
-         add $ORACLE_HOME/lib32 to LD_LIBRARY_PATH.
-         If $ORACLE_HOME/lib32 doesn't exist, add $ORACLE_HOME/lib instead.
-
-       Other 64-bit ruby:
-         add $ORACLE_HOME/lib to LD_LIBRARY_PATH.
-
-   To connect the local database:
-
-     * ORACLE_SID
-
-2. enjoy.
-
-   sample one-liner:
-     ruby -r oci8 -e 'OCI8.new("scott", "tiger", nil).exec("select * from emp") do |r| puts r.join(","); end'
-
-== Oracle Instant Client
-
-1. set environmet variables.
-
-   The follwing environmet variables are required:
-
-     * NLS_LANG
-
-     * library serach path
-
-       Windows:
-         add %ORACLE_HOME%\bin to PATH.
-
-       AIX:
-         add $ORACLE_HOME/lib to LIBPATH.
-
-       HP-UX PA-RISC 32-bit ruby:
-         add $ORACLE_HOME/lib32 to SHLIB_PATH.
-         If $ORACLE_HOME/lib32 doesn't exist, add $ORACLE_HOME/lib instead.
-
-       SPARC/Solaris 32-bit ruby:
-         add $ORACLE_HOME/lib32 to LD_LIBRARY_PATH_32.
-         If $ORACLE_HOME/lib32 doesn't exist, add $ORACLE_HOME/lib instead.
-
-       SPARC/Solaris 64-bit ruby:
-         add $ORACLE_HOME/lib to LD_LIBRARY_PATH_64.
-
-       Mac OS X:
-         add $ORACLE_HOME/lib to DYLD_LIBRARY_PATH.
-
-       Other 32-bit ruby:
-         add $ORACLE_HOME/lib32 to LD_LIBRARY_PATH.
-         If $ORACLE_HOME/lib32 doesn't exist, add $ORACLE_HOME/lib instead.
-
-       Other 64-bit ruby:
-         add $ORACLE_HOME/lib to LD_LIBRARY_PATH.
-
-   ORACLE_HOME and TNS_ADMIN are optional:
-     see: http://www.oracle.com/technology/tech/oci/instantclient/ic-faq.html#A4428
-
-2. enjoy.
-
-   sample one-liner:
-     ruby -r oci8 -e 'OCI8.new("scott", "tiger", "//HOSTNAME_OR_IP/SID").exec("select * from emp") do |r| puts r.join(","); end'
-
-== Platform specific topics
-
-=== HP-UX
-
-1. I was reported that it doesn't work with 64-bit ruby. :-<
-
-2. link the libraries which contain thread local storages to ruby itself.
-
-   ruby 1.8.1 or later:
-     gzip -dc ruby-1.8.2.tar.gz | tar xvf -
-     cd ruby-1.8.2
-     ./configure --enable-pthread
-     vi Makefile     # add "-lcl" to LIBS manually.
-     make
-     make install
-
-   ruby 1.8.0 or 1.6.x:
-     gzip -dc ruby-1.x.x.tar.gz | tar xvf -
-     cd ruby-1.x.x
-     ./configure
-     vi Makefile     # add "-lpthread -lcl" to LIBS manually.
-     make
-     make install
-
-   If you can't recompile ruby, LD_PRELOAD may solve the problem.
-
-     LD_PRELOAD=/usr/lib/libpthread.1:/usr/lib/libcl.2
-     export LD_PRELOAD
-
-=== Intel Mac
-
-Oracle intant client is still, when I write this, pcc.
-
-1. check whether the ruby is ppc bianry.
-
-     file `which ruby`
-
-   If it is universal bianry, use ditto to extract ppc binary.
-
-      http://blog.sven-tissot.de/daylist_html?year=2006&month=4&day=12
-
-   If it is i386 binary, compie it as ppc.
-
-2. fix compilation flags.
-
-      ruby -r rbconfig -e "p Config::CONFIG['CFLAGS']"
-      ruby -r rbconfig -e "p Config::CONFIG['DLDLAGS']"
-
-   If they have '-arch i386', delete it from:
-      /usr/lib/ruby/1.8/powerpc-darwin8.0/rbconfig.rb
-   or
-      /usr/lib/ruby/1.8/universal-darwin8.0/rbconfig.rb
-
-   If haven't '-arch ppc', add it.
-
-3. config, make and install
-
-     ruby setup.rb config -- --with-instant-client=/opt/oracle/instantclient10_1
-     make
-     make install
-
-4. rollback the changes in 2.
-
-***************************
-in progress.
-
-
-= How to run unit tests
-
-1. see "How to run"
-
-2. create user and tables on Oracle.
-
-   - connect to Oracle as system:
-
-      $ sqlplus system/<password_of_system>
-
-   - create user ruby:
-
-      SQL> CREATE USER ruby IDENTIFIED BY oci8;
-    or
-      SQL> CREATE USER ruby IDENTIFIED BY oci8
-         2 DEFAULT TABLESPACE users TEMPORARY TABLESPACE temp;
-
-   - grant the privilege to connect and execute.
-
-      SQL> GRANT connect, resource, create synonym TO ruby;
-
-   - If the Oracle version is 8i or later:
-
-      SQL> CREATE TABLE ruby.test_clob (filename VARCHAR2(40), content CLOB);
-
-   - connect to Oracle as sys
-
-      $ sqlplus 'sys/<password_of_sys> as sysdba'
-
-   - grant the privilege for the unittest of blocking-mode.
-
-      SQL> GRANT EXECUTE ON dbms_lock TO ruby;
-
-3. set $dbname in test/config.rb.
-
-   for instant client, or full client which connect the remote server.
-
-4. run.
-
-     $ make check
    or
-     $ nmake check   (If your compiler is MS Visual C++.)
-
-
-= How to customize fetched datatypes.
-
-== OCI8::BindType::Mapping
 
-OCI8::BindType::Mapping is available to change the mapping of Oracle
-datatypes and ruby datatypes.
+    SQL> CREATE USER ruby IDENTIFIED BY oci8
+       2 DEFAULT TABLESPACE users TEMPORARY TABLESPACE temp;
 
-Examples:
-  fetch a Timestamp value as a OraDate:
-    OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP] = OCI8::BindType::OraDate
-  fetch a Timestamp value as a String:
-    OCI8::BindType::Mapping[OCI8::SQLT_TIMESTAMP] = OCI8::BindType::String
+3. grant the privilege to connect and execute.
 
-Bind-types are:
-  OCI8::BindType::String
-  OCI8::BindType::RAW
-  OCI8::BindType::OraDate
-  OCI8::BindType::Time
-  OCI8::BindType::Date
-  OCI8::BindType::DateTime (ruby 1.8.0 or upper)
-  OCI8::BindType::Float
-  OCI8::BindType::Fixnum
-  OCI8::BindType::Integer
-  OCI8::BindType::OraNumber
-  OCI8::BindType::Number
-  OCI8::BindType::OCIRowid
-  OCI8::BindType::BLOB
-  OCI8::BindType::CLOB
-  OCI8::BindType::Cursor
+    SQL> GRANT connect, resource TO ruby;
 
-== Number datatype.
+4. If the Oracle version is 8i or later:
 
-OCI8::BindType::Number is a special bindtype. The actual bindtype
-depends on the precision and scale.
-  Fixnum or Integer for NUMBER(p, 0). (prec is positive).
-  Float for NUMBER(prec, scale). (prec is less then 15).
-  OraNumber for NUMBER(prec, scale). (prec equals or is greater then 15).
+    SQL> CREATE TABLE ruby.test_clob (filename VARCHAR2(40), content CLOB);
 
-If fetched value is defiend as NUMBER or calculated value, it is
-fetched as a Float by default. To customize this behavior, you can
-use OCI8::BindType::Mapping[:number_unknown_prec] and
-OCI8::BindType::Mapping[:number_no_prec_setting].
+5. connect to Oracle as sys
 
-Oracle 9.2.0.2 or earlier:
-  OCI8::BindType::Mapping[:number_unknown_prec] changes both behaviors.
+    $ sqlplus 'sys/<password_of_sys> as sysdba'
 
-Oracle 9.2.0.3 or later:
-  OCI8::BindType::Mapping[:number_no_prec_setting] changes the former.
-  OCI8::BindType::Mapping[:number_unknown_prec] changes the latter.
+6. grant the privilege for the unittest of blocking-mode.
 
-Examples:
+    SQL> GRANT EXECUTE ON dbms_lock TO ruby;
 
-  CREATE TABLE tab1 (col1 NUMBER, col2 NUMBER(10));
-  SELECT col1 AS col FROM tab1:
-  SELECT col2 * 1.0 AS cal2 FROM tab1;
-  # col : NUMBER whose precision and scale are not defined explicitly.
-  # cal : calculated NUMBER value.
+7. change test/config.rb as you like
 
-  Oracle 9.2.0.2 or earlier:
-    OCI8::BindType::Mapping[:number_unknown_prec] = OCI8::BindType::Integer
-      ==> col is fetched as an Integer.
-          cal is fetched as an Integer.
-    :number_unknown_prec changes the both behaviors.
+Then you can run:
+  $ make check
+or
+  $ nmake check   (If your compiler is MS Visual C++.)
 
-  Oracle 9.2.0.3 or later:
-    OCI8::BindType::Mapping[:number_unknown_prec] = OCI8::BindType::Integer
-      ==> col is fetched as a Float.
-          cal is fetched as an Integer.
-    :number_unknown_prec changes the latter only.
+= TODO
 
-    OCI8::BindType::Mapping[:number_no_prec_setting] = OCI8::BindType::Integer
-      ==> col is fetched as an Integer.
-          cal is fetched as a Float.
-    :number_no_prec_setting changes the former only.
+* more proper handling of OCI_SUCCESS_WITH_INFO.
+* more proper handling of NUMBER without its scale values.
+* support Timestamp.