StarQuest Technical Documents

Troubleshooting Tips for StarSQL for UNIX

Last Update: 1 June 2022
Product: StarSQL
Version: All
Article ID: SQV00SU003

Abstract

This article provides troubleshooting and configuration hints for StarSQL for UNIX.

For additional information, see How to Report a StarSQL ODBC Driver for UNIX Problem for instructions on capturing ODBC and DRDA traces. Also see Common StarSQL Error Messages for error messages that may occur when using either StarSQL for Windows or StarSQL for UNIX.

Solution

• Confirming bitwidth of application, ODBC driver manager, and driver
• Viewing the environment of a running process
  
• Viewing the shared library dependencies of an application or shared library
  
• Identifying processes using a shared library
  
• Configuring system-wide LD_LIBRARY_PATH
• Driver's SQLAllocHandle on SQL_HANDLE_DBC failed
  
• Disabling SELinux
• Testing with isql and iusql
• Issues related to unknown locale
• Conversion problems: UTF-8 and SQLBindParameter()/SQL_C_CHAR

Confirming bitwidth of application, ODBC driver manager, and driver

StarSQL (64-bit) and StarSQL (32-bit) can be installed on the same system and are independent of each other. Be sure that bitwidth of the ODBC application and any shared libraries that it uses, including the ODBC driver manager and the StarSQL driver itself, are all of the same bitwidth. You can use the file command to display the bitwidth of a binary.

Viewing the environment of a running process

Identify the PID of the process you are interested in, then use ps e (as root) to display the environment for that process. Pipe the output to more or to a file so that long lines are wrapped instead of truncated. This is useful in troubleshooting ODBC problems involving a service; of particular interest is the value for LD_LIBRARY_PATH (Linux & Solaris).

$ su
# ps -eaf | grep <process-name> or <user-id>
# ps e -p <pid> | more

Viewing the shared library dependencies of an application or shared library

Often a failure to load a dependent shared library results in a misleading error message, identifying a file that is known to exist (e.g. libSWODBC.so) rather than the missing or unloadable shared library.

Another common issue is due to the presence of multiple versions of ODBC driver managers - for example, a system may include the version of unixODBC installed with StarSQL, an older version of unixODBC installed by the Linux distribution, and a copy of the DataDirect driver manager installed with a commercial application. It is important to understand exactly which copy of libodbc.so, libodbcinst.so, etc. is being used by your application, and be careful to use one and only one driver manager.

On Linux and Solaris, use the ldd command to identify the dependencies of the ODBC application or a shared library. On AIX, a freeware version of ldd is available, or you can use dump -H. On HP-UX, use /usr/ccs/bin/ldd (part of the developer tools). On MacOS, use otool -L ( part of the developer tools).

$ ldd /usr/share/starsql64/bin/simpleconn
$ ldd /usr/share/starsql64/lib/libSWODBC.so

Identifying processes using a shared library

Use the lsof (list open files) command to identify processes using a shared library or other binary. Run this command as root.

Example: the following commands will identify any processes currently using the branded DataDirect Driver Manager or the StarSQL driver:

$ su
# /usr/sbin/lsof /opt/IBM/InformationServer/Server/branded_odbc/lib/libodbc.so
# /usr/sbin/lsof /usr/share/starsql64/lib/libSWODBC.so

Configuring system-wide LD_LIBRARY_PATH

This section is of less relevance than in the past, as we now recommend using the unixODBC package available from Microsoft or the distro (in the case of Red Hat/Oracle 8.x), which installs to /usr/lib64.

Configuring the system-wide LD_LIBRARY_PATH (Linux & Solaris) may be useful when experiencing ODBC problems with a service.

On all systems: Edit /etc/profile or create a custom.sh shell script in /etc/profile.d/

Linux: Add the path to shared libraries (e.g. /usr/share/starsql64/odbc/lib) to /etc/ld.so.conf or file with a .conf extension in /etc/ld.so.conf.d/, and execute the ldconfig command as root.

FreeBSD: Use ldconfig -m /usr/share/starsql64/odbc/lib
Solaris: Use crle
HP-UX: Edit /etc/SHLIB_PATH
AIX: no equivalent

Driver's SQLAllocHandle on SQL_HANDLE_DBC failed

The error Driver's SQLAllocHandle on SQL_HANDLE_DBC failed can be the result of several causes, most having to do with failing to load a dependent shared library.

• When running on Red Hat/Oracle 8.x or later, be sure to install the compatibility package for OpenSSL 1.0.x. This is required whether or not you plan to use SSL.

ldd /usr/share/starsql64/lib/libSWTCP32.so may show a missing dependency.

Solution: Install the package with:yum install compat-openssl10

On Red Hat Enterprise Linux 9.x and compatible distributions, it may be necessary to obtain the RPM package from the 8.x repository and use rpm -i to install it.

• When using the unixODBC 2.3.9 package supplied with Red Hat 9.x and compatible distributions, you may need to create a symbolic link for /usr/lib64/libodbcinst.so. This problem was diagnosed by setting the environment variable $_STARSQL64, resulting in the more useful message
  symbol lookup error: /usr/share/starsql64/lib/libSWODBC.so: undefined symbol: SQLGetPrivateProfileString.

# cd /usr/lib64
# ls -l libodbcinst.so*
If libodbcinst.so does not exist:
# ln -s libodbcinst.so.2.0.0 libodbcinst.so

• When using the Data Direct Driver Manager, failing to specify the ODBCINST environment variable.
• Any other failure to locate the StarSQL or StarSQL64 entry in odbcinst.ini, which the driver uses to identify the installation location. For instance, in the case of multiple ODBC driver managers, StarSQL may have placed its entry into another copy of odbcinst.ini than the one being used by the active driver manager. Or a user may have inadvertently renamed, deleted, or otherwise damaged the odbcinst.ini entry. Note that if you wish to use the driver name StarSQL (64-bit) to match StarSQL/Windows, either install StarSQL 6.44 or later, or create a new entry rather than renaming the existing StarSQL64 entry.

A workaround for the odbcinst.ini failures (or to determine if that is the cause), is to set the environment variable _STARSQL or _STARSQL64 to the installation location.

Disabling SELinux

Some applications may experience issues if SELinux (Security-Enhanced Linux) is enabled. SELinux is often enabled by default on Red Hat and related distributions such as Oracle Linux, Fedora, CentOS, and Scientific Linux.

Use the command sestatus to display the current state of SELinux.

To verify whether SELinux is the source of connectivity problems, temporarily configure permissive mode by changing the contents of /selinux/enforce from 1 to 0:

# echo 0 > /selinux/enforce

or using the command setenforce 0

Disable SELinux permanently by editing /etc/selinux/config:
SELINUX=DISABLED

Testing with isql and iusql

You can verify operation with isql (part of unixODBC). Edit $HOME/.odbc.ini or /etc/odbc.ini with a text editor to create ODBC data sources; ODBCConfig (the GUI equivalent of Windows' ODBC Admin) is no longer supported. You can also use a connection string.

- Using isql with a DSN
$ isql -v DSN myuser mypasswd

-Using isql with a connection string
$ isql -v -k "DRIVER=StarSQL (64-bit);Server=SQDRC;HostName=127.0.0.1;port=50000;UID=myuser;PWD=mypasswd;PkgColID=STARSQL"

-Using iusql (Unicode version of isql) with a connection string. Note that iusql doesn't recognize the -k parameter; instead start the connection string with a semicolon.
$ iusql -v ";DRIVER=StarSQL (64-bit);Server=SQDRC;HostName=127.0.0.1;port=50000;UID=myuser;PWD=mypasswd;PkgColID=STARSQL"

Issues related to unknown locale

Symptom: A connection attempt failed with an error message consisting of 2 square brackets without any content.

[]
[ISQL]ERROR: Could not SQLDriverConnect

Solution: This can happen when StarSQL can’t find its message catalogs because the locale differs from what StarSQL knows how to handle.

Enter the command
$ echo $LANG

and compare the result with the names of directories in the $STARSQL/nls directory.

For example, this issue affected a user who was using the locale C.utf8, rather than the expected en_US.UTF-8.

The issue can be resolved either by:

• Change the locale to one known by StarSQL
  $ export LANG=en_US.UTF-8
• Or create a symbolic link in the nls directory:
  # cd /opt/StarQuest/starsql64/nls
  # ln -s en_US.UTF-8 C.utf8

Conversion problems: UTF-8 and SQLBindParameter()/SQL_C_CHAR (StarSQL 6.38 & earlier)

Symptom: When using SQLBindParameter() with SQL_C_CHAR to insert UTF-8 characters such as the Euro sign ('€'), the data sent to the host is incorrect. The issue does not occur when using literals in an INSERT statement.

This issue has been addressed in StarSQL 6.39.

Solution:

• Edit /usr/share/starsql64/etc/conf/ccsid.csv and insert the following line (between 1200 & 1208):

1202,U,G,UTF-16LE

• Add the following to your ODBC data source:

ICONV4UTF8=Y