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.