INSTALL

1. Introduction
===============

  ROracle has been built and tested with R versions 2.15 through 3.2.0 and with
  Oracle Instant Client and Oracle Database Client versions 10.2 to 12.1.0.1 on
  both the 32 and 64-bit versions of the Linux and Windows operating systems.

2. Requirements
===============

  Linux
  -----

  For compiling on Linux, ROracle needs either the Oracle Instant Client or
  the Oracle Database Client part of the Oracle Database distribution
  (ORACLE_HOME-based client). If using an Oracle Instant Client, you need
  either the Basic or Basic Lite packages in addition to the SDK package. You
  can use either the RPM or ZIP package. You can simplify the ROracle
  installation process by using Instant Client RPM packages.

  NOTE: Basic Lite is geared toward applications that require English-only
    error messages and use either US7ASCII, WE8DEC, or a Unicode characterset.
    It also has no restrictions on the TERRITORY field of the NLS_LANG setting.
    As a result, an application that meets these characterset and territory
    criteria can significantly reduce its footprint if it uses the Basic Lite
    package.

  Mac OS X
  --------

  For compiling on Linux, ROracle needs the Oracle Instant Client. Then you need
  either the Basic or Basic Lite packages in addition to the SDK package.

  NOTE: Basic Lite is geared toward applications that require English-only
    error messages and use either US7ASCII, WE8DEC, or a Unicode characterset.
    It also has no restrictions on the TERRITORY field of the NLS_LANG setting.
    As a result, an application that meets these characterset and territory
    criteria can significantly reduce its footprint if it uses the Basic Lite
    package.

  Windows
  -------

  For compiling on Windows, ROracle needs either an Oracle Instant Client or
  Oracle Database Client. If using Oracle Instant Client, you need either
  a Basic or Basic Lite package in addition to the SDK package of Instant
  Client. If you are not using Oracle Instant Client, you only need the Oracle
  Database Client part of the Oracle Database distribution (ORACLE_HOME-based
  client). When building on a 64-bit platform, you can build both the 32-bit and
  64-bit packages. If you need both, you need to install both the 32 and
  64-bit versions of Oracle Instant Client or Oracle Database Client. 

  NOTE: Basic Lite is geared toward applications that require English-only
    error messages and use either US7ASCII, WE8DEC, or a Unicode characterset.
    It also has no restrictions on the TERRITORY field of the NLS_LANG setting.
    As a result, applications that meet these characterset and territory
    criteria can significantly reduce its footprint if they use the Basic Lite
    package.

  TimesTen
  --------
  
  For TimesTen connection support, ROracle should be compiled using the Oracle
  Instant Client included in the local TimesTen installation directory. For 
  more information on TimesTen see http://www.oracle.com/technetwork/database/
  timesten/documentation/.

  Instant Client
  --------------

  For more information on Oracle Instant Client see http://www.oracle.com/
  technetwork/database/features/instant-client/index-100365.html.

3. Installation
===============

  Linux - Instant Client
  ----------------------

  The ROracle build depends on Oracle Client libraries and header files. To
  build with 11.2 client version, you can get Instant Client 11.2 from 
  an RPM. It has both the Basic and the SDK packages. It places the files in
  standard locations that the ROracle configure script can find. For example,
  on a 32-bit system, Oracle Instant Client is installed in 
  /usr/lib/oracle/11.2/client/lib. On a 64-bit system, it is installed in
  /usr/lib/oracle/11.2/client64/lib. After installing the Oracle Instant
  Client, change LD_LIBRARY_PATH as follows:

  export LD_LIBRARY_PATH=/usr/lib/oracle/11.2/client64/lib:$LD_LIBRARY_PATH
  R CMD INSTALL ROracle_1.3-1.tar.gz
 
  Alternatively, you can extract Oracle Instant Client from a zip package. In
  this case, a symbolic link libclntsh.so needs to be created manually before
  proceeding to install ROracle.

  Change directories to the directory where Oracle Instant Client is 
  installed and then issue the following command:
  ln -s libclntsh.so.11.1   libclntsh.so

  Next, set the LD_LIBRARY_PATH environment variable. Additionally, specify 
  the location of Oracle Client libraries and header files via either the 
  environment variable OCI_LIB or the configure option --with-oci-lib. 
 
  For example, if Oracle Instant Client was installed in
  /scratch/instantclient_11_2, then you need to do the following:
  
  export OCI_LIB=/scratch/instantclient_11_2
  export LD_LIBRARY_PATH=/scratch/instantclient_11_2:$LD_LIBRARY_PATH
  R CMD INSTALL ROracle_1.3-1.tar.gz

  Alternatively, if using the --with-oci-lib configure option, you can do 
  the following:

  export LD_LIBRARY_PATH=/scratch/instantclient_11_2:$LD_LIBRARY_PATH
  R CMD INSTALL --configure-args='--with-oci-lib=/scratch/instantclient_11_2' ROracle_1.3-1.tar.gz

  Both methods assume that the Basic and SDK packages were unzipped into the 
  same directory and Oracle Client headers are located under 
  $OCI_LIB/sdk/include. If this is not the case, then set either the OCI_INC 
  environment variable or the --with-oci-inc configure option appropriately.

  Linux - Oracle Client (Oracle home installation)
  ------------------------------------------------

  As in the previous section, set LD_LIBRARY_PATH  to include the path to
  the Oracle Client libraries. Additionally, set ORACLE_HOME. Then install the
  ROracle package by running

  R CMD INSTALL ROracle_1.3-1.tar.gz


  Mac OS X - Instant Client
  -------------------------

  The ROracle build depends on Oracle Client libraries and header files. To
  build with 11.2 client version, you can get Instant Client 11.2 from zip
  package. It has both the Basic and the SDK packages. 
  You can extract Oracle Instant Client from a zip package. In this case, 
  a symbolic link libclntsh.so needs to be created manually before
  proceeding to install ROracle.

  To Install Oracle Instant Client and ROracle package, do the following:
  1. Download Instant Client from:
     http://www.oracle.com/technetwork/topics/intel-macsoft-096467.html
     into (for example):
     /path/to/dnlds/
  2. Extract Oracle Instant Client from zip packages:
     cd /path/to/dnlds
     unzip -o instantclient-basic-macos.x64-12.1.0.2.0.zip     -d /opt/ora12
     unzip -o instantclient-sdk-macos.x64-12.1.0.2.0.zip       -d /opt/ora12
  3. Change directories to the directory where Oracle Instant Client is
     installed and then issue the following command: 
     cd /opt/ora12/instantclient_12_1
     ln -s libclntsh.dylib.12.1 libclntsh.dylib
  4. Download the ROracle source package (ROracle_1.3-1.tar.gz) from CRAN
     into (for example):
     /path/to/pkg/
  5. Install ROracle package by issuing following command:
     cd /path/to/pkg
     R CMD INSTALL --configure-args='--with-oci-lib=/opt/ora12/instantclient_12_1' ROracle_1.3-1.tar.gz
     Or, within R, using the modified package:
     install.packages('ROracle_1.3-1.tar.gz', repos=NULL, configure.args='--with-oci-lib=/opt/ora12/instantclient_12_1')


  Windows
  -------

  For compiling on Windows, ROracle needs either the Oracle Instant Client or
  only the Oracle Database Client part of the Oracle Database distribution
  (ORACLE_HOME-based client).
  When using Oracle Instant Client you need either the Basic or Basic Lite
  package in addition to the SDK package. Once ROracle is built with any
  supported version of Oracle Client, at run-time you can use an appropriate
  supported version of Oracle Instant Client or ORACLE_HOME-based client
  without requiring a re-build of ROracle.

  Once ROracle is built and installed, the 64-bit version of R uses the 
  64-bit version of Oracle Client and the 32-bit version of R uses the 
  32-bit  version of Oracle Client. If there are multiple versions of Oracle
  Client in the PATH, the first one in the PATH that corresponds to the R 
  architecture is loaded by ROracle.
  For example, if the PATH has
  c:\temp\i386\instantclient_10_2;c:\temp\x64\instantclient_11_1;c:\temp\i386\instantclient_11_2;c:\temp\x64\instantclient_11_2;%PATH%, then R 32-bit uses instantclient_10_2 and R 64-bit uses
  instantclient_11_1; the rest of the PATH is ignored. The version that is 
  required must be in the PATH first, Oracle recommendeds that you have only one
  version for each architecture in the PATH. Refer to item 8 of the 
  Troubleshooting section to determine the architecture of Oracle Client being 
  used.

  For process interoperability on Windows, refer to
  http://msdn.microsoft.com/en-us/library/windows/desktop/aa384231%28v=vs.85%29.aspx

  Windows - Instant Client
  ------------------------

  To use the 64-bit version of instant Client, do the following:
  1. Create an installation directory for the Oracle R Enterprise client 
     components. 
     For example: c:\oreclient_install_dir 
  2. Go to the Oracle Database Instant Client page on the Oracle Technology 
     Network at: 
     http://www.oracle.com/technetwork/database/features/instant-client/ 
  3. Select See Instant Client downloads for all platforms.
  4. On the Instant Client Downloads page, select Instant Client for Microsoft 
     Windows (x64).
  5. On the Instant Client Downloads for Microsoft Windows (x64) page, accept 
     the license agreement.
  6. Select the Basic or Basic Lite Instant Client Package for your version of
     Oracle Database.
  7. Save the file in the installation directory that you created in Step 1. 
     For example: 
     c:\oreclient_install_dir\instantclient-basic-windows.x64-11.2.0.1.0.zip 
  8. Unzip the file. The files are extracted into a subdirectory named
     instantclient_version, where version is your version of Oracle Database. 
     For example: 
     c:\oreclient_install_dir\instantclient_11_2 
  9. Return to the Instant Client Downloads for Microsoft Windows (x64) page at:
     http://www.oracle.com/technetwork/topics/winx64soft-089540.html.
  10.Accept the license agreement and select Instant Client Package - SDK for 
     your version of Oracle Database. 
  11.Save the file in the installation directory that you created in Step 1. 
     The directory should now contain the file 
     instantclient-sdk-windows.x64-11.2.0.1.0.zip.
  12.Unzip the file. The files are extracted into the instantclient_version 
     subdirectory. 
  13.Add the full path of the Instant Client to the environment variables 
     OCI_LIB64 and PATH. 

     The following steps set the variables to the PATH used in this example, 
     c:\myoreclient\instantclient_11_2. 
  1. In Windows Control Panel, select System, then click Advanced system 
     settings.
  2. On the Advanced tab, click Environment Variables. 
  3. Under System variables, create OCI_LIB64 if it does not already exist. 
  4. Set the value of OCI_LIB64 to c:\oreclient\instantclient_11_2. 
  5. Under System variables, edit PATH to include 
     c:\oreclient\instantclient_11_2.
  
  To use 32-bit version of instant Client, 
  1. Create an installation directory for the Oracle R Enterprise client 
     components.
     For example: c:\oreclient_install_dir
  2. Go to the Oracle Database Instant Client page on the Oracle Technology
     Network at:
     http://www.oracle.com/technetwork/database/features/instant-client/
  3. Select See Instant Client downloads for all platforms.
  4. On the Instant Client Downloads page, select Instant Client for Microsoft
     Windows (i386).
  5. On the Instant Client Downloads for Microsoft Windows (i386) page, accept 
     the license agreement.
  6. Select the Basic or Basic Lite Instant Client Package for your version
     of Oracle Database.
  7. Save the file in the installation directory that you created in Step 1. 
     The directory should now contain the file 
     instantclient-basic-windows.i386-11.2.0.1.0.zip.
  8. Unzip the file.The files are extracted into a subdirectory named
     instantclient_version, where version is your version of Oracle Database. 
     For example:
     c:\oreclient_install_dir\instantclient_11_2
  9. Return to the Instant Client Downloads for Microsoft Windows (i386) page 
     at:
     http://www.oracle.com/technetwork/topics/wini386soft-089540.html.
  10.Accept the license agreement and select Instant Client Package - SDK for 
     your version of Oracle Database.
  11.Save the file in the installation directory that you created in Step 1.
     The directory should now contain the file 
     instantclient-sdk-windows.i386-11.2.0.1.0.zip.
  12.Unzip the file. The files are extracted into the instantclient_version
     subdirectory.
  13.Add the full path of the Instant Client to the environment variables
     OCI_LIB32 and PATH.

     The following steps set the variables to the PATH used in this example,
     c:\myoreclient\instantclient_11_2.
  1. In Windows Control Panel, select System, then click Advanced system 
     settings. On the Advanced tab, click Environment Variables.
  2. Under System variables, create OCI_LIB32 if it does not already exist. Set
     the value of OCI_LIB32 to c:\oreclient\instantclient_11_2.
  3. Under System variables, edit PATH to include 
     c:\oreclient\instantclient_11_2.

  Windows - Oracle Client (ORACLE_HOME-Based Client)
  --------------------------------------------------

  As in the previous section, PATH should be set to include the path to the 
  Oracle Client libraries. Oracle Universal Installer should have set the 
  PATH and ORACLE_HOME environment varibles in the registry database.

  Set OCI_LIB32 or OCI_LIB64 depending on your current platform architecture
  for Windows.

  For example, if user "xyz" has installed the Oracle Client version 11.2 using
  the default location in the Oracle Universal Installer on 64-bit Windows,
  set OCI_INC and OCI_LIB64 as follows:

  set OCI_INC=C:/app/xyz/product/11.2.0/client_1/oci/include
  set OCI_LIB64=C:/app/xyz/product/11.2.0/client_1/bin

  Build the ROracle package using:

  R CMD INSTALL ROracle_1.3-1.tar.gz

  To build both 32-bit and 64-bit versions of ROracle, add both the 32-bit and
  64-bit versions of Oracle Client to the PATH environment variable before
  building ROracle. Once ROracle is built and installed, 64-bit version of R
  will use the 64-bit version of Oracle Client and 32-bit the 32-bit version of
  Oracle Client.

  To build both the 32-bit and 64-bit versions of ROracle, execute the following 
  commands:

  set OCI_INC=C:/app/xyz/product/11.2.0/32_bit_client_1/oci/include
  set OCI_LIB32=C:/app/xyz/product/11.2.0/32_bit_client_1/bin
  set OCI_LIB64=C:/app/xyz/product/11.2.0/64_bit_client_1/bin
  R CMD INSTALL --build --merge-multiarch ROracle_1.3-1.tar.gz

  When mixing Oracle Instant Client and ORACLE_HOME-based client, above
  environment variables must be set carefully to point to the specific Client
  installation. To simplify administration, Oracle recommends that you have only
  one version of the client.


  TimesTen
  --------
  
  When building ROracle for TimesTen connection support on Windows or Linux, the 
  Instant Client included in the local TimesTen installation directory should 
  be used. For example, if TimesTen 64-bit is installed on Windows in the 
  c:/TimesTen/tt1122_64 directory, then issue the following commands:
  
  set OCI_LIB64=c:/TimesTen/tt1122_64/ttoracle_home/instantclient_11_2
  R CMD INSTALL --build ROracle_1.3-1.tar.gz
  
  At runtime the directories for both the TimesTen Instant Client shared 
  libraries and the TimesTen database shared libraries must be present on the
  system's shared library search path (PATH on Windows or LD_LIBRARY_PATH on 
  Linux) in order to establish a TimesTen database connection. An easy way to 
  do this is to run the ttenv script located in the bin directory of the local 
  TimesTen installation directory.
  
  For example, if TimesTen 64-bit is installed on Windows in the 
  c:/TimesTen/tt1122_64 directory, issue the following command:
  to set the system's shared library search path for TimesTen connections
  
  c:/TimesTen/tt1122_64/bin/ttenv.bat
  
  For more information on TimesTen, see http://www.oracle.com/technetwork/
  database/timesten/documentation/.
 
  Installing ROracle on Windows Directly from Binary File
  -------------------------------------------------------

  1. Download the binary from oracle: http://www.oracle.com/technetwork/
     database/database-technologies/r/roracle/downloads/index.html
  2. Run the following command in R, substituting the file path:
     setwd('xxxxx')   # set to path of download
     install.packages('ROracle_1.3-1.zip', repos = NULL)
  3. Load the library and use the package; you may have to change DBNAME to the
     one listed in your tnsnames.ora file, as in the following example:
     library('ROracle')
     drv <- dbDriver("Oracle")
     con <- dbConnect(drv, "USERNAME", "PASSWORD", dbname='DBNAME')
  4. Test connection:
     dbReadTable(con, 'DUAL')

  Installing ROracle on AIX and Solaris platforms
  -----------------------------------------------

  The requirements and installation instructions for AIX and Solaris platforms
  are the same as those for Linux platforms with the following exceptions:
  - For AIX, use the LIBPATH environment variable instead of LD_LIBRARY_PATH.
  - For Solaris, use LD_LIBRARY_PATH_64 instead of LD_LIBRARY_PATH.


4. Troubleshooting:
-------------------

  Linux
  -----

  If you see an error about opening an Oracle Client library libclntsh.so
  when issuing the library(ROracle) command, you probably did not add the path
  to Oracle Client libraries to LD_LIBRARY_PATH environment variable.

  > library(ROracle)
  Loading required package: DBI
  Error in dyn.load(file, DLLpath = DLLpath, ...) : 
   unable to load shared object '.../library/ROracle/libs/ROracle.so':
  libclntsh.so.11.1: cannot open shared object file: No such file or directory
  Error: package/namespace load failed for 'ROracle'
 
  See the Installation section above for details on setting LD_LIBRARY_PATH.

  Windows
  -------

1. If you see the following error during the build of ROracle, then the oci.dll
   loaded from the PATH environment variable by R does not correspond to the 
   same architecture as R.

    ** testing if installed package can be loaded
    Error in inDL(x, as.logical(local), as.logical(now), ...) :
      unable to load shared object '.../library/ROracle/libs/i386/ROracle.dll':
        LoadLibrary failure:  %1 is not a valid Win32 application.

   To resolve this, set PATH to include 32-bit version of Oracle Client
   when the 32-bit version of R is used and 64-bit version of Oracle Client when
   the 64-bit version of R is used. You cannot build the 64-bit version of 
   ROracle using the 32-bit version of R and vice versa.

2. You may also see the error message 
   ".../i686-w64-mingw32/bin/ld.exe: i386:x86-64 architecture of input file
     `.../oci.dll' is incompatible with i386 output"
   when installing a 32-bit version of ROracle with a 64-bit version of
   oci.dll. This error is followed by undefined references to OCI functions
   as shown below:

    rooci.o:rooci.c:(.text+0x9d): undefined reference to `OCIDescriptorAlloc'
    rooci.o:rooci.c:(.text+0x17e): undefined reference to `OCIDateTimeFromText'
    ...
    rooci.o:rooci.c:(.text+0x22a4): undefined reference to `OCIDateTimeConvert'
    collect2: ld returned 1 exit status
    ERROR: compilation failed for package 'ROracle'
 
   The above errors may also be seen when oci.dll is missing in the directory
   specified by the OCI_LIB32 or OCI_LIB64 environment variables.

3. The following error occurs during installation of ROracle when the oci.dll
   not compatible with the R architecture:
     collect2: ld returned 5 exit status
     ERROR: compilation failed for package 'ROracle'

   Solution: Set OCI_LIB32 to point to the 32-bit version of the client and
                     OCI_LIB64 to point to the 64-bit version of the client.

4. If you see a dialog box with the title "Rterm.exe - System Error" with the
   the message "OCI.dll missing from your system, try installing it"
   followed by the error below when issuing the library(ROracle) command or 
   during the installation, then the Oracle Client libraries were not found in
   the PATH environment variable.

    Error in inDL(x, as.logical(local), as.logical(now), ...) :
      unable to load shared object '.../library/ROracle/libs/.../ROracle.dll':
      LoadLibrary failure:  The specified module could not be found.

5. If you see an error about oci.dll not being found, then either the OCI_LIB32
   or the OCI_LIB64 environment variable points to a location that does not have
   the Oracle Client installed.

     gcc.exe: error: .../oci.dll: No such file or directory
     ERROR: compilation failed for package 'ROracle'

6. If you see one of the following error messages when building ROracle, then
   oci.dll is not compatible with the R architecture. One of the messages
   below will be displayed with 11.X or higher version of Oracle Instant Client
   or ORACLE_HOME-based client instead of the messages listed in 1, 2, or 3 above.

    Client Shared Library 32-bit - ... cannot be used to install with 64-bit R.
    Client Shared Library 64-bit - ... cannot be used to install with 32-bit R.

7. If you see the following error when loading the ROracle library, then the 
   oci.dll loaded from PATH by R does not correspond to the same architecture 
   as R.

   > library(ROracle)
   Loading required package: DBI
   Error in inDL(x, as.logical(local), as.logical(now), ...) :
     unable to load shared object '.../library/ROracle/libs/.../ROracle.dll':
     LoadLibrary failure:  %1 is not a valid Win32 application.

   Error: package/namespace load failed for 'ROracle'

   To resolve this, set PATH to include the 32-bit version of Oracle Client
   when using the 32-bit version of R and the 64-bit version of Oracle Client 
   when using the 64-bit version of R. You cannot build or run the 64-bit 
   version of ROracle using the 32-bit version of R and vice versa.

8. Determining the architecture of Oracle Client:

   Oracle Instant Client provides BASIC_README and BASIC_LITE_README files
   showing the architecture they were built on.

   For ORACLE_HOME-based Client, inspect the registry. A 32-bit home will be
   located in HKEY_LOCAL_MACHINE->Software->WOW6432Node->Oracle, and a 64-bit
   home will be in HKEY_LOCAL_MACHINE->Software->Oracle. Inspect the path to
   the home to try to infer whether it is 32-bit or 64-bit based on the
   location of dlls.

   If the PATH environment variable includes paths to both the 32-bit and 64-bit
   clients, then Oracle depends on the operating system to load the 32-bit DLLs 
   for the 32-bit R process and the 64-bit DLLs for the 64-bit R process.