Setting Oracle language parameters for DG4ODBC

In response to customer queries, this document describes how to set the HS_LANGUAGE and HS_NLS_NCHAR parameters when using DG4ODBC.

If you are using a Unicode^* ODBC driver such as the SQL Server ODBC driver, ensure these parameters and values are present in your DG4ODBC init file:

HS_LANGUAGE = language_territory.code_page
HS_NLS_NCHAR = UCS2

Replace language, territory, and code_page with the Oracle language, territory and code page that correspond with your databases's language, locale and code page.

For example, if your database is SQL Server, and its language and code page are English (United States) and 1252, your HS_LANGUAGE parameter would look like this:

HS_LANGUAGE = ENGLISH_AMERICA.WE8MSWIN1252

The HS_NLS_NCHAR parameter value tells DG4ODBC to pass UCS-2 encoded data to the Unicode ODBC APIs, which is the character encoding the ODBC standard states should be used and is therefore the one that the unixODBC Driver Manager expects.

Ensure also that you have set NLS_LANG before starting your Oracle application. NLS_LANG lets Oracle know what character set your client machine is using. For example:

$ echo $LANG
en_US.UTF-8
$ NLS_LANG=AMERICAN_AMERICA.AL32UTF8 ./sqlplus

If you are using an ANSI ODBC driver (which does not support wide ODBC API calls), you need to specify a non UTF-8 character set in the HS_LANGUAGE value. For example, HS_LANGUAGE = AMERICAN_AMERICA.WE8ISO8859P1. If you do not do this and your Oracle database's NLS_CHARACTERSET value is set to a UTF-8 encoding, for example AL32UTF8, DG4ODBC:

• Uses the Unicode ODBC APIs, for example, SQLDriverConnectW, which the unixODBC Driver Manager maps to their ANSI equivalent (or if your HS_FDS_SHAREABLE_NAME parameter points to the ODBC driver shared object, causes the connection to fail with an "undefined symbol" error).
• Passes UTF-8 encoded data to the ODBC APIs, which the unixODBC Driver Manager does not support. The connection fails because DG4ODBC passes a UTF-8 encoded connection string to SQLDriverConnectW, which the unixODBC Driver Manager is unable to handle.

Unicode ODBC Drivers^*

Unicode ODBC drivers support the wide ODBC APIs, which are of the form SQLxxxW. To check whether your ODBC driver supports wide ODBC APIs, either check with your driver vendor, or, enable ODBC driver logging, connect with DG4ODBC and examine the resultant log file. For example:

$ more /etc/odbc.ini
[SQLSERVER_SAMPLE]
.
.
.
Logging=Yes
LogFile=/tmp/mssql.log

$ ./sqlplus / as sysdba
$ select * from mytable@mssqllink;
$ exit
$ more /tmp/mssql.log
.
.
.
ENTRY:   SQLGetInfoW: connection_handle...