Skip to main content

This is documentation for Caché and Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

Please read this important announcement about the future of Caché and Ensemble maintenanceOpens in a new tab. Contact your account team to migrate to InterSystems IRIS.

ODBC Installation and Validation on UNIX® Systems

This chapter provides detailed information about ODBC installation and validation on UNIX® and related operating systems. It discusses the following topics:

Note:

The sample ODBC initialization file and test files may include the _SYSTEM/SYS or _system/sys username-password pair in unencrypted form. It is recommended that you remove this data before deployment; it is also recommended that you remove the _SYSTEM account before deployment.

Testing the InterSystems ODBC Configuration

You should test the ODBC configuration to make sure that the InterSystems ODBC driver and the driver manager have been installed and configured correctly. In addition to tests provided with the unixODBC driver manager, you can run the InterSystems Select Test program, which provides specific tests for the InterSystems ODBC driver. The program allows you to specify a DSN and execute a SELECT statement on that connection.

Note:

There is also a specific test program for the SQL Gateway. For details, see “Using the UNIX® Gateway Test Program” in the SQL Gateway chapter.

Using the Select Test Program

The InterSystems select test program consists of files in the directory install-dir/dev/odbc/samples/select

  • select.sh — The shell script that runs the test. This script defines the ODBCINI environment variable (so that the ODBC initialization file can be found), sets up the search path to find the driver manager, and executes the following SELECT statement:

    select * from sample.person where ID < 11

    It then executes the select program using a DSN named sampleodbc. This DSN is defined in the sample ODBC initialization file and points to the InterSystems SAMPLES namespace.

  • select — The executable built from select.c. This is a sample ODBC program already linked with the iODBC driver manager.

  • select.c — This is the source code for the select program. This source is provided in case you want to make change and compile and link it yourself.

Modifying the Shell Script for the SELECT Test

You may need to modify the shell script (select.sh), depending on your configuration:

  • The shell script is designed to work with InterSystems login or unauthenticated modes and in Minimal or Normal security installations. It may need modification in other cases.

  • By default, the shell script sets up the search paths to find the iODBC driver manager. You would change this if you use the unixODBC driver manager or if you install iODBC in a non-default way.

  • The script also assumes that the ODBC initialization file is in the install-dir/mgr directory. You should adjust the script as needed to find the ODBC initialization file on your system.

Running the SELECT Test

To use the test program:

  1. Go to the directory install-dir/dev/odbc/samples/select.

  2. Execute the test script by typing the following:

    ./select dsn

    where dsn is the name of the DSN that you want to use in the test.

This test works as follows:

  1. The shell script calls the select program.

  2. The select program is linked to a driver manager, which reads the ODBC initialization file to get connection information for the given DSN.

  3. The driver manager determines the location of the InterSystems ODBC client driver and loads it into memory.

  4. The client driver then establishes a TCP/IP connection to the port specified in the ODBC initialization file and is connected to the given namespace using the DSN definition from the ODBC initialization file.

  5. Once the connection is established, the client application executes your SELECT statement against the InterSystems database.

Troubleshooting for Shared Object Dependencies

After installing, you should validate dependencies on other shared objects and correct any problems. The process is as follows:

  1. Use the appropriate command to list the dynamic dependencies of the InterSystems ODBC driver.

    For example, on Unix® and other platforms, the command is ldd:

    # ldd install-dir/bin/libcacheodbc.so

    Here install-dir is the InterSystems installation directory. If no dependencies are found, you will see a message like the following:

    libstlport_gcc.so => not found

  2. If there are no errors, then all dependencies are valid; if there are errors, run the following commands to force the shared object loader to look in the current directory:

    # sh
# cd install-dir/bin
# LD_LIBRARY_PATH=`pwd`:$LD_LIBRARY_PATH
# export LD_LIBRARY_PATH

    The sh command starts the Bourne shell; the cd command changes to the appropriate directory; and the export command sets the path to look up shared objects.

    Note that on AIX®, you would use LIBPATH instead of LD_LIBRARY_PATH.

  3. Once you have added the current directory to the path, run ldd again and check for missing dependencies. If any shared objects cannot be found, add them to the same directory as the ODBC client driver.

Performing a Stand-alone Installation

By default, a full ODBC installation is performed with a standard InterSystems installation. If you perform a custom installation (as described in the Installation Guide), you can select the “SQL client only” option to install only the client access components (ODBC client driver).

In addition, however, a stand-alone installer is provided for InterSystems ODBC. To use this installer:

  1. Create the directory where you wish to install the client, such as /usr/cacheodbc/.

  2. Copy the appropriate zipped tar file into the directory that you just created.

    The ./dist/ODBC/ directory contains zipped tar files with names like the following:

    ODBC-release-code-platform.tar.Z

    where release-code is a release-specific code (that varies among InterSystems versions and releases) and platform specifies the operating system that the ODBC client runs on.

  3. Go to the directory you created and manually unpack the .tar file, as follows:

    # gunzip ODBC-release-code-platform.tar.Z
# tar xvf ODBC-release-code-platform.tar

    This creates bin and dev directories and installs a set of files.

  4. Run the ODBCInstall program, which will be in the directory that you created. This program creates several sample scripts and configures cacheodbc.ini under the mgr directory. For example:

    # pwd
/usr/cacheodbc
# ./ODBCInstall
Note:
Identifying the correct platform name

In some releases, the ./dist/ODBC/ directory contains the following command to display the platform name that identifies the file you need:

# ./cplatname identify

This command is not present in releases where it is not required.

Custom Installation and Configuration for iODBC

If you want to build your own iODBC driver manager to operate under custom conditions, you can do so. The iODBC executable and include files are in the directory install-dir/dev/odbc/redist/iodbc/. You need to set LD_LIBRARY_PATH (LIBPATH on AIX®) and the include path in order to use these directories to build your applications.

If you want to customize the iODBC driver manager, you can also do that. Download the source from the iODBC Web site (www.iodbc.orgOpens in a new tab) and follow the instructions.

Configuring PHP with iODBC

You can use InterSystems ODBC functionality in conjunction with PHP (PHP: Hypertext Processor, which is a recursive acronym). PHP is a scripting language that allows developers to create dynamically generated pages. The process is as follows:

  1. Get or have root privileges on the machine where you are performing the installation.

  2. Install the iODBC driver manager. To do this:

    1. Download the kit.

    2. Perform a standard installation and configuration, as described earlier in this chapter.

    3. Configure the driver manager for use with PHP as described in the iODBC+PHP HOWTOOpens in a new tab document on the iODBC web site (www.iodbc.orgOpens in a new tab).

    Note that LD_LIBRARY_PATH (LIBPATH on AIX®) in the iODBC PHP example does not get set, due to security protections in the default PHP configuration. Also, copy libiodbc.so to /usr/lib and run ldconfig to register it without using LD_LIBRARY_PATH.

  3. Download the PHP source kit from https://www.php.netOpens in a new tab and un-tar it.

  4. Download the Apache HTTP server source kit from http://httpd.apache.org/Opens in a new tab and un-tar it.

  5. Build PHP and install it.

  6. Build the Apache HTTP server, install it, and start it.

  7. Test PHP and the Web server using info.php in the Apache root directory, as specified in the Apache configuration file (often httpd.conf). The URL for this is http://127.0.0.1/info.php.

  8. Copy the InterSystems-specific initialization file, cacheodbc.ini to /etc/odbc.ini because this location functions better with the Apache Web server if the $HOME environment variable is not defined.

  9. Configure and test the libcacheodbc.so client driver file.

  10. Copy the sample.php file from the InterSystems ODBC kit to Apache root directory (that is, the directory where info.php is located), and tailor it to your machine for the location of your InterSystems installation directory.

  11. You can then run the sample.php program, which uses the SAMPLES namespace, by pointing your browser to http://127.0.0.1/sample.php

Key File Names

Depending on your configuration needs, it may be useful to know the specific file names of some of the installed components. In the following lists, install-dir is the InterSystems installation directory (the path that $SYSTEM.Util.InstallDirectory() returns on your system).

ODBC driver managers

The install-dir/bin/ directory contains the following driver managers:

  • libiodbc.so — The iODBC driver manager, which supports both 8-bit and Unicode ODBC APIs.

  • libodbc.so — The unixODBC driver manager, for use with the 8-bit ODBC API.

Note:
ODBC on 64-bit UNIX® platforms

Between releases of the ODBC specification, various data types such as SQLLen and SQLULen changed from being 32-bit values to 64-bit values. While these values have always been 64-bit on iODBC, they have changed from 32-bit to 64-bit on unixODBC. As of unixODBC version 2.2.14, the default build uses 64-bit integer values. InterSystems drivers are available for both 32-bit and 64-bit versions of unixODBC.

InterSystems ODBC client drivers

InterSystems ODBC client drivers are provided for both ODBC 2.5 and ODBC 3.5. The ODBC 3.5 versions will convert 3.5 requests to the older 2.5 automatically, so in most cases either driver can be used. The install-dir/bin/ directory contains the following versions (*.so or *.sl):

iODBC-compliant drivers

  • libcacheodbc — default driver for 8-bit ODBC 2.5

  • libcacheodbc35 — supports 8-bit ODBC 3.5

  • libcacheodbciw — supports Unicode ODBC 2.5

  • libcacheodbciw35 — supports Unicode ODBC 3.5

  • libcacheodbciw.dylib — supports Unicode ODBC for MAC OS

unixODBC-compliant drivers

  • libcacheodbcu. — default driver for 8-bit ODBC 2.5

  • libcacheodbcu35 — supports 8-bit ODBC 3.5

  • libcacheodbcur64 — supports 8-bit ODBC 2.5 for 64-bit unixODBC

  • libcacheodbcur6435 — supports 8-bit ODBC 3.5 for 64-bit unixODBC

InterSystems SQL Gateway drivers

The install-dir/bin/ directory contains the following versions of the shared object used by the InterSystems SQL Gateway. This enables you to connect from Caché to other ODBC client drivers. These files are not installed if you perform a stand-alone installation.

linked against iODBC

  • cgate.so — supports 8-bit ODBC.

  • cgateiw.so — supports Unicode ODBC.

linked against unixODBC

  • cgateu.so — supports 8-bit ODBC.

  • cgateur64.so — supports 8-bit ODBC for 64-bit unixODBC

Other files

The install-dir/mgr/cacheodbc.ini file is a sample ODBC initialization file.

The files for the test programs are discussed in “Testing the InterSystems ODBC Configuration”.

Next sectionUsing the SQL Gateway with ODBC
Previous sectionUsing an InterSystems Database as an ODBC Data Source on UNIX®
FeedbackOpens in a new tab