The first step to getting WACS to work with Oracle is to download a suitable set of client side applications and libraries - these are typically provided by Oracle Instant Client or a package of a similar name. Of course this does not include the database itself but when using the likes of Oracle, it would be quite normal (but not required) to have separate web servers and database engines. Wacs works just fine on multiple front end web servers with a single Oracle backend. Similarly collection administration and straightforward use can be performed on a separate workstation from hosting the database.

Generally doing a full install of instant client will provide all the libraries you need. If you are downloading these from the Oracle OTN web site, you will need the following packages either as zip files or rpms if that is the package manager on the distribution you are using.

The next step is to establish the necessary ORACLE_HOME environment variables and check that the Oracle stack is running by connecting to the server using the sqlplus client (sometimes called sqlplus64 on the older x86_64 versions) provided as part of the instant client package. If this reports that the necessary shared libraries are not found, this may be because the dynamic library caching configuration files have not been created as needed. For RedHat based distros like Fedora, this is achieved by creating a file in /etc/ld.so.conf.d/ called something like oracle-19-installclient.conf which simply contains a single line pointing to where the files like libsqlplus.so are to be found. For the x86_64 version of instantclient installed from the RPMs, this should be /usr/lib/oracle/19.6/client64/lib assuming the RPM was installed into it's default locations. Once this file has been created, you just need to run ldconfig as root to rebuild the /etc/ld.so.cache to include the files in this path.

If you get the message sqlplus64: error while loading shared libraries: libnnz11.so: cannot enable executable stack as shared object requires: Permission denied that means that SELinux is still active on your host and has barred access to the Oracle libraries. The quick fix is to disable SELinux by running setenforce permissive as root on your machine and editing the file /etc/selinux/config to set the mode to permissive on subsequent system boots.

Once you've actually got the sqlplus program to run, that is unfortunately not usually the end of the story as it has to be configured to find the database server, etc. There are two parts to this task - firstly to create a suitable tnsnames.ora file to describe how to contact your server - place this into a newly-made /etc directory within the oracle instant client directory. Secondly you need to set environment variables that tell instant client what to look up within that tnsnames.ora file. This is done by establishing four environment variables, ideally globally for the system - these are:

In many ways the best way to establish these environment variables is to create the appropriate files in the global profiles directory, which is to be found in /etc/profile.d. Typically it's best to create two files called something like oracle11g-instantclient.sh with commands for sh/bash shells, and oracle19-instantclient.csh with commands for csh/tcsh shells. The shell (.sh) file should look something like this:

export ORACLE_HOME=/usr/lib/oracle/19.6/client64
export ORACLE_SID=yourdbname
export TWO_TASK=yourdbname
export TNS_ADMIN=/usr/lib/oracle/19.6/client64/etc

You may also wish to alias sqlplus64 to sqlplus if you're using one of the old versions of the instant client that used this name.

It should then be a fairly simple matter of using cpan DBD::Oracle to download, compile and install the necessary database driver for Perl DBI. Once that's done, you just need to follow the installation instructions for Oracle in the appropriate chapters of this guide.

The conventional install of Php5's pear DB routines actually does include the first line of support for Oracle in the form of the oci8.php file in /usr/share/pear/DB but this itself needs oci8.so which normally lives in /usr/lib64/php/modules. To make this module, you will need the full set of SQL*Net libraries as provided by either a full database installation or Oracle's instant client product. You will also need the C compiler and the php-devel package (this contains the command phpize so if trying to invoke phpize gives Command not found you almost certainly don't have the necessary development package installed.

Since WACS currently uses the now-obsolete Pear DB module for database access, it appears to be a bit of a challenge to find the correct source code. We do also support using the PDO interface as from Wacs 1.0.0. We have not yet re-written the WACS sample programs to use PDO but may well do in due course.

While we were preparing this document (March 2011, revised May 2018 and June 2020), the source code for the OCI8 driver could be found at the PECL web site. If you down load this with something like wget and save it locally, running the following (assuming you have ORACLE_HOME set correctly) as root produced a successful install: pecl install oci8. You then need to enable the extension in php itself; in some distros this is done by simply adding extension=oci8 into the /etc/php.ini file, while in more recent distros it is now convention to create a file called oci8.ini in the directory /etc/php.d containing this line. Once this configuration change has been made, you will need to restart your web server to make the new settings live. All that then remains to be done is to configure the phpdbconnect string in the main wacs configuration file with the correct database specification and things should start to work.

Building support for the PDO - PHP Data Objects - module is rather more complex unfortunately. The good news is that it is a fully integrated part of PHP itself and it's source code is part of the main PHP sources. The bad news is that many Linux distributions turn it off when they are building php (as being proprietory code); others are at least building the hooks and putting it in a package. If you can't find a suitable package, you may well be able to build one quite easily.

Here are the steps to take to do this - you may need to install the necessary packages for building packages such as php-devel (Fedora, RedHat, CentOS) or php7.3-dev (Debian, Ubuntu).:

RPM-based distros:
% cd rpmbuild/SRPMS
% dnf download --source php
% rpm -iv php-7.4.6-1.fc32.src.rpm
% cd ../SOURCES
% tar -xJf php-7.4.6.tar.xz
% cd php-7.4.6/ext/pdo_oci
% mkdir -p ~/src/php/pdo_oci
% cp -r * ~/src/php/pdo_oci
% cd ~/src/php/pdo_oci
% phpize
% ./configure --with-pdo-oci=shared,instantclient,\
/usr/lib/oracle/1.9.6/client64/lib,19.6.0.0.0
% make
% sudo make install
%
DEB-based distros:
% cd debuild
% aptitude source php7.3
% cd php7.3-7.3.11/ext/pdo_oci
% mkdir -p ~/src/php/pdo_oci
% cp -r * ~/src/php/pdo_oci
% cd ~/src/php/pdo_oci
% phpize
% ./configure --with-pdo-oci=shared,instantclient,\
/usr/lib/oracle/1.9.6/client64/lib,19.6.0.0.0
% make
% sudo make install
%

This alternative solution is essentially to download the source packages for PHP for your distribution and rebuild the piece of them that we need by enabling the --with-pdo-oci flag. If you are using the Oracle Instant Client distribution, you specify this with --with-pdo-oci=instantclient,/usr,19.6.0.0.0 as an option to the configure script where the /usr is where it is installed and 19.6.0.0.0 is the exact Oracle DB version number. Do remember that the php version will be updated from time to time and you may need to update the driver to match the current version.

	Note
	For PHP7 or PHP8, you will need a minimum of oci8-2.1.8 which should be available from pecl as before. See the sectiona above for details of how to install it.

Some distributions have now moved over to using php-fpm to provide PHP functionality from within the Web Server. Generally this is a good idea as it stops the web server having to start up a new PHP interpreter each time. Unfortunately it stops the method we've used previously and in other languages to set the essential ORACLE_HOME environment variable needed for the oci8 and PDO oci drivers to work. These instead now have to be set in /etc/php-fpm.d/www.conf where you have to add a line of the form env[ORACLE_HOME] = /usr/lib/oracle/19.6/client64 to it. Of course you need to change the path to the actual install location of your Oracle database software. Once added you need to do a systemctl restart php-fpm.service to make your changes active.