SNTT - Installing and configuring ODBC drivers for Domino on Red Hat Enterprise Linux

This has been a long time coming, but I'm finally ready to move my Domino application server to Linux. Nearly every application I've written in Notes uses LC LSX to access data from our iSeries ERP server. My current Domino application server is also an an iSeries, so I can use the native DB2 connectivity built in. For Linux I need to configure ODBC, and I really didn't relish the idea of going through all the previous hell from my proof of concept.

Getting the DataDirect 5.2 drivers

I contacted Lotus support to see if there was a more recent version of the DataDirect ODBC drivers than the 5.1 version and layers of hotfixes I used previously. The good news is there is a newer release! The Lotus OEM branded DataDirect 5.2 drivers are included with Domino 6.5.6, which was released on March 27, 2007. However they are not available as a stand-alone download. You have to install the server to get them, and you must select the Enterprise server. Even then the drivers aren't installed, they're just extracted from the installation image.

Installing the drivers

Now that you've installed Domino 6.5.6 Enterprise you have to track down the drivers. They're in /opt/lotus/notes/6560/linux/, and you install them by executing the file EIODBClinux and following the on screen prompts. The rest of this documentation assumes you accepted all the default values.

Configuration

If you've worked with the Linux ODBC drivers in the past you probably know what to do from here. If you haven't, configuring the drivers means getting your hands a little dirty. First up, environment variables.

Environment variables in RHEL are kept in the file /etc/profile and you have to be logged in as root to modify it. I always log into my RHEL servers with my Notes user account, so I go to a Terminal prompt and use su to switch to the root user. Then I type gedit /etc/profile to open the file in the Gnome Editor, which I like a billion times better than vi. In the profile file you will see a line like this:

export PATH USER LOGNAME MAIL HOSTNAME HISTSIZE INPUTRC

Add the following before this line:

LANG=C
export LANG

ODBCINI = /opt/odbc/odbc.ini
LD_LIBRARY_PATH=/opt/ibm/lotus/notes/latest/linux:/opt/odbc:/opt/odbc/lib
NUI_NOTESDIR=/opt/ibm/lotus
LOTUS=/opt/ibm/lotus/
Notes_ExecDirectory=/opt/ibm/lotus/notes/latest/linux/
LIBPATH=$Notes_ExecDirectory
export ODBCINI LD_LIBRARY_PATH NUI_NOTESDIR LOTUS Notes_ExecDirectory
export LIBPATH

PATH=$PATH:/opt/ibm/lotus/notes/latest/linux/res/$LANG:/$Notes_ExecDirectory
PATH=$PATH:/local/notesdata

I split the export and PATH lines for readability, you can certainly put them all one line if you like. Following the second PATH line above should be the default export line I listed previously. When you're finished, save and close the profile file.

Next up, configuring the ODBC driver. All the configuration is done in the odbc.ini file, which if you were paying attention you might have guessed is in /opt/odbc. Edit the file by using gedit /opt/odbc/odbc.ini . The odbc.ini file is divided into several sections. The [ODBC Data Sources] section lists all the configured system DSN's that can be used. It's generally a good idea to leave all the defaults alone and add what you need. In my case I'm adding a DB2 DSN called LOCAL, so mine looks like this:

[ODBC Data Sources]
LOCAL=IBM Lotus OEM 5.2 DB2 Wire Protocol
DB2 Wire Protocol=IBM Lotus OEM 5.2 Wire Protocol
...

The next step is to configure your DSN. You do this by copying the section for your type of driver, renaming it, then updating the parameters. Since I'm using the DB2 Wire Protocol driver, I copied the [DB2 Wire Protocol] section, then pasted it back into the same file, giving me two copies of the same section. Then I renamed the one I pasted.

[LOCAL]
Driver=/opt/odbc/lib/LOdb222.so
Description=IBM Lotus OEM 5.2 DB2 Wire Protocol
....

Tip: If you're connecting from RHEL to DB2 on an iSeries, make sure you do the following:

add # before the Database= line
IpAddress=your iSeries IP
Location=iSeries DB name from WRKRDBDIRE
TcpPort = 446 (that's the default, check with your iSeries admin if it doesn't work)

Save and close the odbc.ini file when you're finished. From the command prompt you used to edit the file, issue the command source /etc/profile . This will reload /etc/profile, updating the environment variables.

You can test your connection by executing /opt/ibm/lotus/notes/latest/linux/dctest. At the first prompt enter option 3 to select an ODBC connection, then enter the name of your DSN. If you get errors about files not existing you may want to try restarting the server, or at least logging off and back on again.