
ROracle has been built and tested with R versions 1.3.1 through
2.3.0 (devel) and with Oracle 32-bit versions 8.0.4, 8.1.7, 9.2, 
and 10.2 (a previous version of ROracle was successfully run with 
Oracle 7 on Solaris).  People have reported using ROracle on 64-bit
AIX and Solaris systems.

On Windows 2000, it has been compiled against the Oracle 9.2 client.

Oracle Requirements:
--------------------

  Unix (and Unix-likes):

  For compiling, the R-Oracle interface needs the client part of
  the Oracle distribution (in particular the "programmer" and
  "application user" packages), you don't need the Oracle server.

  Make sure you have the Oracle ProC/C++ properly configure (e.g.,
  $ORACLE_HOME/proc/admin/pcscfg.cfg in Oracle8), otherwise you
  will run into problems either during pre-compilation and/or linking.

  Windows:

  To compile under windows see the Makefile.win in the 'src' directory
  of the ROracle package.  You'll need the Developer's Package from the
  Oracle's client software and Microsoft Visual C++.

  To install the Windows binary, you'll need the Oracle runtime libraries
  (and make sure $ORACLE_HOME/bin is in your PATH).

  NOTE: You may override the Oracle libraries and/or library directories 
  using the PKG_CPPFLAGS and/or PKG_LIBS variables (for details see 
  "Writing R Extensions").

Using library(ROracle):
-----------------------

  If you see an error like the one below when you issue the
  library(ROracle) command, you may need to define or update you
  LD_LIBRARY_PATH.  For instance,

  > library(ROracle)
  Error in dyn.load(x, as.logical(local), as.logical(now)) : 
     unable to load shared library "/usr/dj/linux/R/ROracle/libs/ROracle.so":
  /usr/dj/linux/R/ROracle/libs/ROracle.so: undefined symbol: sqlclu
  Error in library(ROracle) : .First.lib failed
 
  Solution 1:  Update $LD_LIBRARY_PATH *before* invoking R, e.g.,

  $ export LD_LIBRARY_PATH=$ORACLE_HOME/lib:$LD_LIBRARY_PATH
  $ R
  > library(ROracle)
  >
  
  Solution 2: Create a static library (see below).
 
32-bit vs 64-bit Issues (Unix)
------------------------------

  The configuration option --enable-oracle32 allows you to link
  explicitly against Oracle's 32-bit or 64-bit libraries.  The issue
  is most relevant when a machine has an Oracle installation that uses
  64-bit code and R as a 32-bit application -- the 32-bit/64-bit
  mismatched is the problem.  In this case one needs to explicitly
  link ROracle against the non-default (but available) 32-bit Oracle
  libraries.  E.g., 

  R CMD INSTALL --configure-args='--enable-oracle32' ROracle.<version>.tar.gz

  this forces the linking against the libraries under
  $ORACLE_HOME/lib32 and $ORACLE_HOME/network/lib32.  You may set
  --enable-oracle32=no to link against 64-bit libraries.  By default
  ROracle is linked against whatever the Oracle default is. (See the
  configure.in file for the gory details.)


A note of caution for Linux users.
----------------------------------

  I've received comments telling me that Oracle9i on Linux (as of
  03 Nov 2001) created too many problems with the ProC/C++ to be
  able to compile ROracle.  Similarly, another person had problems
  with Oracle 8.0.5 on linux (the oracle precompiler "proc" itself
  core dumped!). 

  [Some of these issues have now been traced to improper/incomplete 
  Oracle installations, where some of the post-installation steps 
  were not properly executed, namely, generating the client shared 
  and static libraries though the Oracle's scripts "genclntsh", 
  "genclntst", etc.]

  Comments on your experience on compiling ROracle on Linux are welcome.

Installation: Non-Windows
-------------------------

  Shell variables:
  
    1. ORACLE_HOME should be set and exported (sh/bash/ksh) 
  
    2. PATH must include the path to Oracle's pre-compiler "proc", e.g.,
       PATH=$PATH:$ORACLE_HOME/bin
  
    3. You may or may not have to include $ORACLE_HOME/lib in your
       LD_LIBRARY_PATH, e.g.,
       LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib
       export LD_LIBRARY_PATH
      
  Simple installation (should work for Oracle9(?) and Oracle10):
  
    R CMD [options] ROracle_<version>.tar.gz
  
  Creating a static library (this is the default):
  
    You may statically link ROracle to the Oracle libs (this creates
    a much bigger executable file) with
  
    R CMD INSTALL --configure-args='--enable-static'  ROracle_<version>.tar.gz
  
  Specifying the Oracle versions (7/8/9/10, version 9 is the default):
  
    R CMD INSTALL --configure-args='--with-oracle=8'  ROracle_<version>.tar.gz
  
  Enabling/disabling Pro C/C++ prefetching (e.g., prefetching 10 rows at a time) 
  
    R CMD INSTALL --configure-args='--enable-prefetch=10' ROracle_<version>.tar.gz
  
Pro C/C++ bugs(?) workarounds
-----------------------------
  
  If you're building ROracle on a system with Oracle 8i, you may need to 
  disable prefetching to prevent core dumps traced back to buggy Pro C/C++ 
  prefetching on Oracle 8i (up to 8.2.7.2) as per 
  http://homepage.internet.lu/dbacomp/9i.html:
    
    R CMD INSTALL --configure-args='--disable-prefetch' ROracle_<version>.tar.gz
  
  or equivalently,
  
    R CMD INSTALL --configure-args='--oracle-version=8' ROracle_<version>.tar.gz
  
  
  Issues on Oracle 9.2 with the sqlgls() incorrectly reporting 
  "cannot retrieve data from non-select" can be handled with
  
    R CMD INSTALL --configure-args='--oracle-version=9' ROracle_<version>.tar.gz
  
  (this defines the C macro RS_ORA_SQLGLS_WORKAROUND and includes appropriate
  C code)
  
