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.