ODBC: Data Source Configuration

Windows

Once installed, the Recital ODBC Driver appears in the list of drivers in the 'Windows ODBC Data Source Administrator', accessible from 'Control Panel | Administrative Tools'.

The installer also creates the 'Recital Southwind' datasource to access the Recital southwind database on the local machine.

To add a new datasource, click the Add button:

Select the Recital ODBC Driver from the list of drivers.

Then fill in the details as follows:

Field	Description
DSN	A unique name for the data source
Description	A brief description for the data source. Clicking on the '…' button pops up an editor window.
Server	The server node hostname or IP address. A Recital Database Server must be installed and running on the target server in order to connect.
User	The login name for the remote server.
Password	The password for the specified login
Database or Directory	The database name or directory where the tables reside

Client logging (client <-> server communications) and tracing (ODBC trace) can be switched on for testing purposes if required:

64 bit Windows

Note: The Recital Universal ODBC Driver is a 32 bit implementation, so is not listed in the 64 bit ODBC Data Source Administrator, which is the default administrator accessed from Control Panel | Administration Tools.

So, to create and configure Recital ODBC datasources, you need to use the Window 32 bit ODBC Data Source Administrator or Recital's own Recital Universal ODBC Manager (32-bit).

The Window 32 bit ODBC Data Source Administrator is %windir%\SysWOW64\odbcad32.exe. The Recital Universal ODBC Manager (32-bit) can be accessed from the Control Panel (icon view).

Linux

To determine the location of the configuration files:

# odbcinst -j

Will return output similar to the following:

unixODBC 2.2.11
DRIVERS............: /etc/odbcinst.ini
SYSTEM DATA SOURCES: /etc/odbc.ini
USER DATA SOURCES..: /root/.odbc.ini

The Recital Driver information can be seen in the 'odbcinst.ini' file:

[Recital]
Description		= Recital ODBC Driver
Driver		= /opt/recital/drivers/libodbc_recital.so
Setup		= /opt/recital/drivers/libodbc_recital.so
FileUsage		= 1
UsageCount	= 1

The Recital installer also adds the following DSN to the system 'odbc.ini' file:

[Recital ODBC test]
Driver	= Recital 
DATABASE	= ODBC:RECITAL:SERVERNAME=?;USERNAME=?;PASSWORD=?;DATABASE=odbc_test;

Additional datasources can be added by editing the 'odbc.ini' text file directly, using the following format:

[<unique DSN>]
Description = <informative text>
Driver = Recital
Database = <URL>

Where the <URL> is in the following format:

ODBC:RECITAL:SERVERNAME=<node>;USERNAME=<user>;PASSWORD=<password>;DATABASE=<database>;

or

ODBC:RECITAL:SERVERNAME=<node>;USERNAME=<user>;PASSWORD=<password>;DIRECTORY=<directory>;

The following may also be included:

CLIENTLOGGING=TRUE;CLIENTLOGFILE=<filename>;

For example

[southwind]
Driver	= Recital
DATABASE	= ODBC:RECITAL:SERVERNAME=192.168.1.3;USERNAME=user;PASSWORD=password;DATABASE=southwind;CLIENTLOGGING=TRUE;CLIENTLOGFILE=trace.txt;

[dir_test]
Driver	= Recital
DATABASE	= ODBC:RECITAL:SERVERNAME=192.168.1.3;USERNAME=user;PASSWORD=password;DIRECTORY=/opt/recital/data/od1;

Notes

• As an alternative to manually editing the files, the same format can be used to create template files for installation by odbcinst:

$ odbcinst -i -s <-l|-h> -f template_file

Running 'odbcinst' with no parameters gives usage instructions.

• The <node> can be the hostname or IP address. A '?' can be used to signify the local host.
• Storing the user and password details in the DSN is optional and careful consideration should be given to security implications. A '?' can be used in place of the user and password for local host connections where the environment variable DB_LOCAL_LOGIN is set to true in the recital.conf file.
• The DB_TMPDIR environment variable must be set to a valid writeable directory on the server.
• To test that the ODBC Driver is successfully installed and configured, use the dbodbc test program in <recital>/examples/odbc:

# make
# ./dbodbc