unixODBC 2.3.0, compilation et utilisation sous Sun Solaris 10 X86

Introduction

unixODBC est une couche particulièrement intéressante pour accéder par exemple à des bases Microsoft SQL Server avec le pilote ODBC FreeTDS sur des plateformes Unix. Bien d'autres applications de la couche unixODBC sont possibles : interfaçage de moteurs de bases de données (Oracle, Sybase etc...) avec des langages comme PHP ou encore Python via unixODBC etc...

Cet article présente la compilation d'unixODBC 2.3.0 en 64 bits avec SunStudio 12.1 sur une plateforme Solaris 10 x86 64 bits, pour plus d'informations sur l'installation des compilateurs SunStudio 12.1 : Installation de Sun Studio 12 sur Sun Solaris 10 X86 pour les compilations.

L'architecture et l'utilisation d'unixODBC sur une plateforme Solaris sont présentées en seconde partie, parmi les points abordés :

  • Environnement système unixODBC.
  • Pilotes, DSN - Data Source Name - systèmes et utilisateurs : fichiers odbcinst.ini et odbc.ini, variables $ODBCSYSINI et $ODBCINI.
  • Référencement des pilotes ODBC et création des sources de données.
  • Utilisation du binaire iusql pour tester les connexions ODBC.
  • Debug des appels ODBC.
  • Prédéfinition des attributs ODBC.

Les exemples sont réalisés avec le pilote ODBC Oracle 11g R2 libsqora.so.11.1.

Téléchargement et préparation de l'environnement

Téléchargement

unixODBC 2.3.0 est disponible en téléchargement sous la forme d'une archive compressée (unixODBC-2.3.0.tar.gz) à cette adresse : unixODBC > Download.

L'archive compressée unixODBC-2.3.0.tar.gz est transférée avec ftp sur la machine cible dans le répertoire /Software/tools/temp puis décompressée et désarchivée avec les utilitaires gunzip et tar :

% cd /Software/tools/temp
% gunzip -c unixODBC-2.3.0.tar.gz | tar xvf -

Le code source est alors désarchivé avec la commande tar dans le sous répertoire ./unixODBC-2.3.0.

Préparation de l'environnement pour la compilation d'unixODBC 2.3.0 avec SunStudio 64 bits

La variable PATH est mise à jour avant la compilation pour référencer /usr/ccs/bin, répertoire qui contient le binaire ld, indispensable pour la génération des liens.

% PATH=/usr/ccs/bin:$PATH
% export PATH

Si les liens de SunStudio n'ont pas été installés dans /usr/bin lors de l'installation, la variable PATH doit référencer également le répertoire <répertoire de sunstudio 12.1>/bin pour trouver les compilateurs.

% PATH=/opt/sunstudio12.1/bin:$PATH
% export PATH

Comme il s'agit d'une compilation en 64 bits, la variable d'environnement $CFLAGS est créée et mise à jour à -m64 :

% CFLAGS=-m64
% export CFLAGS

Configuration de la compilation

Une fois l'environnement préparé (variables $PATH, $CFLAGS), la configuration de la compilation peut être déclenchée avec le script configure.

L'option --help renvoie les options de configuration (la sortie de l'option --help est allégée pour la lisibilité).

% cd /Software/tools/temp/unixODBC-2.3.0
% ./configure --help
`configure' configures unixODBC 2.3.0 to adapt to many kinds of systems.

Usage: ./configure [OPTION]... [VAR=VALUE]...

 ...

Installation directories:
  --prefix=PREFIX         install architecture-independent files in PREFIX
                          [/usr/local]
  --exec-prefix=EPREFIX   install architecture-dependent files in EPREFIX
                          [PREFIX]

By default, `make install' will install all the files in
`/usr/local/bin', `/usr/local/lib' etc.  You can specify
an installation prefix other than `/usr/local' using `--prefix',
for instance `--prefix=$HOME'.

Fine tuning of the installation directories:
 ...
  --sysconfdir=DIR        read-only single-machine data [PREFIX/etc]

L'option --prefix est spécifiée ici dans cet article afin de délocaliser l'installation d'unixODBC 2.3.0 en dehors des répertoires systèmes /usr. L'installation des binaires et librairies n'est pas réalisée dans son répertoire par défaut /usr/local mais dans le répertoire /Software/tools/unixodbc : --prefix=/Software/tools/unixodbc (DIR).

Une option importante à noter : --sysconfdir=DIR. Le répertoire sysconfdir correspond au répertoire qui stocke les fichiers de configuration odbcinst.ini (pilotes) et odbc.ini (sources DSN). Souvent, ce répertoire est délocalisé dans /etc. Ce n'est pas le cas ici, la configuration est installée dans le répertoire DIR/etc (/Software/tools/unixodbc/etc).

La ligne de configuration de la compilation est donc la suivante dans cet exemple pratique :

% cd /Software/tools/temp/unixODBC-2.3.0

% ./configure --prefix=/Software/tools/unixodbc

La configuration de la compilation n'a pas posé aucun problème.

Compilation et installation

La compilation et l'installation d'unixODBC 2.3.0 sont réalisées avec les commandes make et make install.

% cd /Software/tools/temp/unixODBC-2.3.0
% make 
% make install
...
Making install in samples
touch /Software/tools/unixodbc/etc/odbcinst.ini
touch /Software/tools/unixodbc/etc/odbc.ini
 ...

La compilation et l'installation se déroule sans aucune épine dans le pied !

Architecture d'unixODBC et utilisation

Architecture

Dans la suite de cet article, DIR correspond au répertoire d'installation d'unixODBC 2.3.0 (/Software/tools/unixodbc). À la fin de la compilation, l'arborescence créée pour unixODBC 2.3.0 est la suivante :

  • DIR/lib
  • DIR/bin
  • DIR/etc
  • DIR/include

Le répertoire DIR/include/ contient tous les fichiers d'entête *.h (headers) pour unixODBC : sql.h, odbcinst.h etc... Ce répertoire doit être inclus dans les options de compilation des programmes développés avec la couche ODBC.

Sourcing de l'environnement unixODBC, renommage du binaire isql

Pour utiliser pleinement l'environnement unixODBC, les variables $PATH et $LD_LIBRARY_PATH sont mises à jour pour accéder aux binaires (DIR/bin) et librairies d'unixODBC (DIR/lib) :

% PATH=/Software/tools/unixodbc/bin:$PATH
% export PATH

% LD_LIBRARY_PATH=/Software/tools/unixodbc/lib:$LD_LIBRARY_PATH
% export LD_LIBRARY_PATH
Dans le répertoire DIR/bin, unixODBC a compilé un binaire isql. Afin d'éviter les conflits avec le binaire isql de Sybase par exemple, supprimer ou renommer cet exécutable.

Ici le binaire isql est renommé en odbcisql.

% cd /Software/tools/unixodbc/bin
% mv isql odbcisql

isql peut également être supprimé car un autre binaire iusql, avec les mêmes fonctionnalités, est également créé dans DIR/bin.

Sources de données système et utilisateur (DSN) : odbcinst -j, variables $ODBCSYSINI et $ODBCINI

Le binaire odbcinst avec l'option -j (print info), exécutable créé dans DIR/bin avec la compilation, donne les informations générales sur la configuration :

% odbcinst- j
unixODBC 2.3.0
DRIVERS............: /Software/tools/unixodbc/etc/odbcinst.ini
SYSTEM DATA SOURCES: /Software/tools/unixodbc/etc/odbc.ini
FILE DATA SOURCES..: /Software/tools/unixodbc/etc/ODBCDataSources
USER DATA SOURCES..: /Software/sybase/.odbc.ini
SQLULEN Size.......: 8
SQLLEN Size........: 8
SQLSETPOSIROW Size.: 8
  • Les pilotes (ou drivers) sont définis dans le fichier /Software/tools/unixodbc/etc/odbcinst.ini.
  • Les sources de données DSN systèmes sont définies dans le fichier /Software/tools/unixodbc/etc/odbc.ini.
  • Les sources de données DSN utilisateur sont définies dans le fichier /Software/sybase/.odbc.ini.

Il est possible d'indiquer à unixODBC de rechercher les pilotes et sources de données DSN systèmes dans un autre chemin grâce à la variable $ODBCSYSINI :

% ODBCSYSINI = /etc
% export ODBCSYSINI

De même, le fichier ini des sources de données utilisateur peut être modifié grâce à la variable $ODBCINI:

% ODBCINI = /Software/sybase/odbc.ini
% export ODBCINI

% odbcinst -j
unixODBC 2.3.0
DRIVERS............: /etc/odbcinst.ini
SYSTEM DATA SOURCES: /etc/odbc.ini
FILE DATA SOURCES..: /etc/ODBCDataSources
USER DATA SOURCES..: /Software/sybase/odbc.ini

Pour lister les pilotes disponibles, utiliser les options -d (driver) et -q (query) de l'exécutable odbcinst :

% odbcinst -d -q
[Oracle 11g ODBC driver]

Pour lister les sources de données systèmes et utilisateurs, utiliser les options -s (sources de données) et -q (query) de l'exécutable odbcinst:

% odbcinst -s -q
[SOPHISU]
[RISKD]

Référencement des pilotes ODBC (drivers)

Les pilotes ODBC sont référencés dans le fichier odbcinst.ini avec 2 méthodes possibles

  • odbcinst -d (-d pour driver) avec les options -i (install) et -u (uninstall)
  • Édition directe du fichier odbcinst.ini/

Dans la documentation officielle, la première méthode et la méthode recommandée, mais dans l'usage, le fichier odbcinst.ini est édité directement.

En exemple, le référencement du pilote ODBC Oracle 11g R2 64 bits dans le fichier odbcinst.ini :

/Software/tools/unixodbc/etc/odbcinst.ini
[Oracle 11g ODBC driver]
Description     = Oracle ODBC driver for Oracle 11g
Driver          = /Software/oracle/app/product/11.2.0/lib/libsqora.so.11.1
Setup           =
FileUsage       =
CPTimeout       =
CPReuse         =

Création de sources de données

Comme pour le référencement des pilotes, 2 méthodes sont possibles pour modifier les sources de données DSN systèmes ou utilisateurs :

  • odbcinst -s (-s pour les sources de données) avec les options -i (install) et -u (uninstall). Les options -l et -h spécifient respectivement une source de données DSN système et utilisateur.
  • Édition directe du fichier odbc.ini système ou utilisateur.

Dans l'usage, les fichiers odbc.ini système et utilisateur sont édités manuellement.

En exemple, création d'une source de données DSN système vers l'instance Oracle RISKD avec le pilote ODBC Oracle 11g R2 64 bits dans le fichierodbc.ini (la sortie est allégée pour la lisibilité) :

/Software/tools/unixodbc/etc/odbc.ini
[RISKD]
Driver = Oracle 11g ODBC driver
DSN = RISKD
ServerName = RISKD
BindAsFLOAT = F
CloseCursor = F
DisableDPM = F
DisableMTS = T
 ...

Tests de connexion ODBC avec iusql

unixODBC fournit l'utilitaire iusql dans le répertoire DIR/bin pour tester les connexions et requêtes avec un pilote ODBC sous Unix. Il peut être utilisé en mode interactif ou en mode batch avec un fichier en entrée. La syntaxe du binaire iusql est très simple :

% cd /Software/tools/unixodbc/bin
% iusql 
**********************************************
* unixODBC - isql                            *
**********************************************
* Syntax                                     *
*                                            *
*      isql DSN [UID [PWD]] [options]        *
*                                            *
 ...
* Examples                                   *
*                                            *
*      isql WebDB MyID MyPWD -w < My.sql     *
*                                            *
*      Each line in My.sql must contain      *
*      exactly 1 SQL command except for the  *
*      last line which must be blank (unless *
*      -n option specified).                 *
 ...

Exemple : connexion à l'instance Oracle RISKD avec la source de données DSN système RISKD créée précédemment

% cd /Software/tools/unixodbc/bin
% iusql -v RISKD system ********
+---------------------------------------+
| Connected!                            |
|                                       |
| sql-statement                         |
| help [tablename]                      |
| quit                                  |
|                                       |
+---------------------------------------+

SQL> select sysdate from dual;
+-------------------------------+
| SYSDATE                       |
+-------------------------------+
| 2011-07-15  08:30:30          |
+-------------------------------+

SQLRowCount returns -1
1 rows fetched
SQL> quit
%

L'option -v avec iusql est très pratique pour diagnostiquer les erreurs. Sans cette option, un message très peu parlant est retourné par le binaire iusql :

[ISQL]ERROR: Could not SQLConnect

Exemple : le DSN n'existe pas

% iusql -v RISKE system ********
[IM002][unixODBC][Driver Manager]Data source name not found,
 and no default driver specified
[ISQL]ERROR: Could not SQLConnect

Tracer et debugger les appels ODBC, dltest

Les appels ODBC peuvent être tracés vers un fichier et facilitent le débogage mais avec dégradations des performances. Pour activer une trace, ajouter une section [ODBC] dans le fichier odbcinst.ini si cette section n'existe pas encore et ajouter les propriétés TraceFile et Trace :

/Software/tools/unixodbc/odbcinst.ini
[ODBC]
TraceFile = /Software/tools/unixodbc/trace.log
Trace = Yes

Le fichier de trace est très instructif :

...
 Entry:
   Statement = 5c18b0
   SQL = [select username from dba_users; ][length = 32 (SQL_NTS)]
[ODBC][10062][1313950651.925755][SQLPrepareW.c][340]
                Exit:[SQL_SUCCESS]
[ODBC][10062][1313950651.925844][SQLExecute.c][187]
                Entry:
                        Statement = 5c18b0
[ODBC][10062][1313950651.940682][SQLExecute.c][348]
 ...

unixODBC fournit par ailleurs l'utilitaire dltest dans DIR/bin, utilitaire assez pratique pour vérifier l'existence d'une fonction dans un pilote ODBC.

% dltest librairie fonction

Un exemple avec le pilote Oracle 11g R2 64 bit : recherche de la fonction SQLGetPrivateProfileStringW dans la librairie ODBC Oracle.

% dltest /Software/oracle/app/product/11.2.0/lib/libsqora.so.11.1  SQLGetPrivateProfileStringW
SUCCESS: Loaded /Software/oracle/app/product/11.2.0/lib/libsqora.so.11.1
SUCCESS: Found SQLGetPrivateProfileStringW

Prédéfinir des attributs ODBC pour une source de données

Dans le fichier de configuration des sources de données odbc.ini (ou .odbc.ini), les attributs ODBC (environnement, connexions, commandes...) peuvent être prédéfinis pour une source de données DSN.

DMEnvAttr : attributs d'environnement ODBC

Pour modifier un attribut d'environnement ODBC :

DMEnvAttr = ATTRIBUTE_NAME=value [;ATTRIBUTE_NAME=value...]

Si la valeur contient un espace :

DMEnvAttr = ATTRIBUTE_NAME={value} [;ATTRIBUTE_NAME={value}...]

ATTRIBUTE_NAME est le nom d'un attribut environnement ODBC, par exemple SQL_ATTR_CONNECTION_POOLING.

unixODBC définit également un attribut d'environnement SQL_ATTR_UNIXODBC_ENVATTR pour lui-même. Cet attribut permet de définir des variables d'environnement globales nécessaires au pilote (ORACLE_HOME, DB2INSTANCE...)

DMEnvAttr = SQL_ATTR_UNIXODBC_ENVATTR={envvar=value;envvar=value}

Exemple : modification de la variable d'environnement $ORACLE_HOME pour la source de données RISKD grâce à l'attribut SQL_ATTR_UNIXODBC_ENVATTR.

[RISKD]
 ...
DMEnvAttr = 
      SQL_ATTR_UNIXODBC_ENVATTR=
           {ORACLE_HOME=/Software/oracle/app/product/11.2.0} 
 ...

DMConnAttr : attributs ODBC pour les connexions

Pour modifier un attribut ODBC pour la connexion :

DMConnAttr = CONNECTION_ATTRIBUTE={value} [;CONNECTION_ATTRIBUTE={value}...]

Exemple : pour fixer la connexion avec un timeout de 30 secondes avec l'attribut SQL_ATTR_CONNECTION_TIMEOUT.

[monDSN]
 ...
DMConnAttr = SQL_ATTR_CONNECTION_TIMEOUT=30 
 ...

DMStmtAttr : attributs ODBC pour les commandes SQL

Pour modifier un attribut ODBC pour les commandes SQL :

DMStmtAttr = STATEMENT_ATTRIBUTE={value} [;STATEMENT_ATTRIBUTE={value}...]

Exemple : pour désactiver le scan des clauses d'échappement propriétaires au moteur des requêtes SQL

[monDSN]
 ...
DMStmtAttr = SQL_ATTR_NOSCAN=SQL_NOSCAN_OFF
 ...

Lorsque l'attribut est préfixé d'une astérisque (*SQL_ATTR_NOSCAN=SQL_NOSCAN_OFF), toute tentative de modification de la valeur de cet attribut par l'application est ignorée par unixODBC.