ODBC Installation and Validation on UNIX® Systems

Performing a Stand-alone Driver Installation

By default, a full ODBC installation is performed with a local InterSystems IRIS 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/irisodbc/.

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.gz
   

   

   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.gz
   # 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 irisodbc.ini under the mgr directory. For example:

   # pwd
   /usr/irisodbc
   # ./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.

InterSystems ODBC Client Files

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).

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

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

• libodbc.so — The unixODBC driver manager, for use with the 8-bit and 16–bit Unicode ODBC APIs.

InterSystems no longer distributes ODBC 2.5 client drivers, but the ODBC 3.5 versions will convert 3.5 requests to 2.5 automatically. The install-dir/bin/ directory contains the following versions (*.so or *.sl):

SQL Gateway Drivers for UNIX® and Related Platforms

UNIX ODBC drivers are compiled against a specific driver manager (iODBC or unixODBC). For example, the InterSystems ODBC driver comes in versions for each driver manager (see InterSystems ODBC Client Files). These drivers require support libraries that are linked against the same driver manager. InterSystems supplies several odbcgateway libraries that are suitable for different third party drivers. The <install-dir>/bin/ directory contains the following versions of the shared objects used by the InterSystems SQL Gateway. This enables you to connect from InterSystems IRIS to other ODBC client drivers. These files are not installed by default if you perform a stand-alone ODBC installation.

linked against iODBC driver manager

• odbcgateway.so — supports 8-bit ODBC

• odbcgatewayiw.so — supports Unicode ODBC.

linked against unixODBC driver manager

• odbcgatewayu.so — supports 8-bit ODBC.

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

If you are installing a third party database driver compiled with unixODBC support (for example, the MS SQL Server ODBC driver), you must back up odbcgateway.so and rename odbcgatewayur64.so to odbcgateway.so. This change must be made for every upgrade, since the upgrade will overwrite odbcgateway.so.

For more information, see “Using an InterSystems Database as an ODBC Data Source on UNIX®”.

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 (see InterSystems ODBC Client Files).

   For example, on Solaris and other platforms, the command is ldd followed by the full path to the driver you specified in your DSN:

   # ldd my-driver-install-path/my-odbc-driver.so
   

   

   On MacOS, the command is:

   otool -L my-driver-install-path/my-odbc-driver.so
   

   

   Specifying the wrong file may result in dependency-related errors. 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.

iODBC Driver Manager Custom Installation

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® or DYLD_LIBRARY_PATH on MacOS) 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, 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.

   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, irisodbc.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 libirisodbc.so client driver file.

10. Copy the custom.php file (listed below) to the Apache root directory (the directory where info.php is located), and tailor it to your machine for the location of your InterSystems installation directory.

11. Download and install the sample.person database from https://github.com/intersystems/Samples-DataOpens in a new tab, or modify custom.php to use your preferred sample database.

12. You can then run the custom.php program by pointing your browser to http://127.0.0.1/custom.php

custom.php listing

<?php
putenv("LD_LIBRARY_PATH=/usr/local/lib");  //This may be blocked by php security
echo $LD_LIBRARY_PATH;
//putenv("ODBCINSTINI=/path/to/odbcinst.ini"); //this location will be determined by your driver install.
//putenv("ODBCINI=/path/to/odbc.ini"); //odbc.ini contains your DSNs, location determined by your driver install.
$dsn="SAMPLES"; 
$user="_SYSTEM"; 
$password="sys"; 
 
$sql="SELECT * FROM sample.person";   
if ($conn_id=odbc_connect("$dsn","","")){
  echo "connected to DSN: $dsn";
  if($result=odbc_do($conn_id, $sql)) {
    echo "executing '$sql'";
    echo "Results: ";
    odbc_result_all($result);
    echo "freeing result";
    odbc_free_result($result);
  }else{
    echo "can not execute '$sql' ";
  }
  echo "closing connection $conn_id";
  odbc_close($conn_id);
}else{
  echo "can not connect to DSN: $dsn ";
}
?>