Développer une application Oracle en C/C++ avec la librairie OCILIB

Liste des révisions du document :

• 07/01/2008 - Publication (version OCILIB 1.5.1)
• 13/02/2008 - Mise à jour (version OCILIB 2.0.0)
• 21/02/2008 - Mise à jour (paragraphe sur les performances + correction de la génération PDF)
• 07/03/2008 - Mise à jour (correction paragraphe III-E - options du linker sous Linux/Unix)
• 20/03/2008 - Mise à jour (correction paragraphe XIII - Fonctionnalités)
• 29/03/2008 - Mise à jour (correction coquilles code : OCI_Statment -> OCI_Statement + ajouts de commits)
• 01/04/2008 - Mise à jour (version OCILIB 2.3.0 : liste des fonctionnalités)
• 24/04/2008 - Mise à jour (version OCILIB 2.4.0 + diverses modifications du tutoriel)
• 21/07/2008 - Mise à jour (version OCILIB 2.5.0 + diverses modifications du tutoriel)
• 13/10/2008 - Mise à jour (version OCILIB 3.0.0 : mise à jour majeure)
• 28/01/2009 - Mise à jour (version OCILIB 3.1.0)
• 20/04/2009 - Mise à jour (version OCILIB 3.2.0)

OCILIB est un driver Oracle open source et portable qui assure des accès performants et fiables aux bases de données Oracle.

La librairie OCILIB :

• offre une API riche et simple à utiliser ;
• tourne sur toutes les plateformes Oracle ;
• est écrite en pur ISO C avec un support natif Unicode en ISO C ;
• encapsule OCI (Oracle Call interface) ;
• est le wrapper OCI le plus complet disponible.

Oracle Call Interface (OCI)Oracle Call Interface (OCI) est est une API fournie par Oracle permettant aux développeurs de créer des applications en utilisant des appels C/C++ bas niveau afin d'accéder à des bases de données Oracle. OCI permet de contrôler tous les aspects de l'exécution d'ordres SQL tout en supportant les types de données, les conventions d'appel, la syntaxe et la sémantique des langages C, C++.

OCI est une API très puissante (c'est l'API la plus bas niveau fournie par Oracle) et utilisée par beaucoup d'applications et outils (à commencer par Sql*Plus, Sql*Loader et tous les produits Oracle), mais aussi très complexe et lourde à utiliser…

Par exemple, se connecter à Oracle requiert au minimum quasiment 100 lignes de code ! De plus, la plupart des fonctions d'OCI requièrent souvent une liste d'arguments assez conséquente (souvent une dizaine de paramètres) et complexe (manipulation quasi exclusive de pointeurs, pointeurs de pointeurs, etc.).

Finalement, une application OCI est souvent pénible à coder, relire et à maintenir et les « experts » en OCI ne sont pas aussi nombreux que les codeurs Java, .NET ou VB !

OCILIB encapsule OCI afin de fournir une interface beaucoup plus simple à coder, lire et surtout afin de permettre une réutilisabilité du code optimale.

OCILIB est gratuit (open source - license LGPL) et fournit près de 500 fonctions simples et son code source est indépendant de toute plateforme.

Les langages C et C++ sont parmi les plus performants et malgré cela, souvent lors du choix d'un langage pour coder une application Oracle, ils ne sont pas retenus, au profit de frameworks de type JAVA et .NET. Ils sont écartés bien souvent pour des raisons d'accès, car les API C/C++ pour accéder à Oracle (fournies ou non par Oracle) sont complexes à mettre en œuvre.

OCILIB permet de concilier les performances de C/C++ avec une mise en œuvre très simple via une interface la plus pragmatique possible tout en gardant une richesse dans les fonctionnalités.

OCILIB est une des rares librairies C/C++ basées sur OCI apportant un support complet Unicode. Une application OCILIB peut être indifféremment compilée nativement en Ansi ou en Unicode.

Enfin, le code d'OCILIB est 100 % ISO C90 (et C99 pour l'Unicode) ce qui lui permet d'être extrêmement portable !

OCILIB ne nécessite pas de client Oracle pour développer. En effet, une application utilisant OCILIB peut lier les librairies Oracle à la compilation (liaison statique ou dynamique) ou charger dynamiquement ces librairies à l'exécution si l'OS cible supporte le chargement dynamique de modules.

OCILIB fonctionne sur toutes les plateformes supportées par Oracle (Microsoft Windows, Linux, Unixes, Mac…).

Actuellement, OCILIB est très utilisé dans :

• des applications bancaires ;
• des applications industrielles ;
• des frameworks génériques d'accès aux bases de données pour encapsuler l'accès à Oracle.

• Posséder un système Unix like ou Microsoft Windows supporté par Oracle.
• Avoir un client Oracle classique ou Instant (non requis pour la compilation, mais pour l'exécution).

=> Les plateformes suivantes ont été validées (compilation, installation, construction et exécution d'un projet) :

• Microsoft Windows ;
• Linux ;
• Solaris ;
• HP/UX ;
• AIX ;
• Mac OS X ;
• OpenVMS.

Les autres plateformes supportées par Oracle (comme z/OS par exemple) n'ont pas été officiellement « validées », mais au vu des plateformes déjà validées, cela ne devrait pas être trop problématique !

Remarque : si vous validez OCILIB sur une plateforme non listée, merci de me contacter !

=> Les compilateurs suivants ont été validés :

• Microsoft Compilers (VC++, VS200X) ;
• GCC et MinGW ;
• IBM XLC ;
• CC propriétaires (HP, AIX…) ;
• LabView.

=> Les versions d'Oracle suivantes (clients et serveurs) ont été validées :

• Oracle 8i ;
• Oracle 9i ;
• Oracle 10g ;
• Oracle 11g.

OCILIB utilise les outils GNU pour son déploiement et son installation.

• Décompresser l'archive courante (ocilib-x.y.z-gnu.tar.gz).
• $ cd ocilib-x.y.z.
• $ ./configure.
• $ ./make.
• $ ./make install (généralement, il faut passer en root pour l'installation).

Vérifier la variable d'environnement des chemins d'accès des librairies dynamiques (LD_LIBRARY_PATH, LD_PATH, ..) afin que le répertoire des librairies Oracle s'y trouve ainsi que celui où est installé OCILIB (typiquement /usr/local/lib sous Linux).
Typiquement, il suffit de rajouter à son fichier .profile :

• $ export LD_LIBRARY_PATH=$LD_LIBRARY_PATH:$ORACLE_HOME/lib:/usr/local/lib

OCILIB supporte 6 options supplémentaires d'installation :

• --with-oracle-import=(linkage|runtime) ;
• --with-oracle-charset=(ansi|unicode|mixed) ;
• --with-oracle-home=(répertoire oracle) ;
• --with-oracle-headers-path=(chemin d'accès aux headers OCI) ;
• --with-oracle-lib-path=(chemin d'accès aux librairies d'Oracle) ;
• --with-custom-loader=(flag pour le linker indiquant le loader à utiliser pour le chargement dynamique à l'exécution des librairies Oracle (par défaut « -ldl ») si la plateforme utilise un loader particulier).

Les deux options 'headers-path' et 'lib-path' sont à utiliser pour les Instant Clients (packages différents pour les headers et les librairies).
Si le package contenant les librairies ne possède pas de lien symbolique sur la librairie partagée complètement qualifiée avec les numéros de version, il faut en créer un. Par exemple, sous Linux/Oracle 10g R1 :

• $ ln -s $ORALIBPATH/libclntsh.so.10.1 $ORALIBPATH/libclntsh.so.

Remarque : si le compilateur est GCC, par défaut les outils GNU (autoconf et automake) lui passent les flags '-g -O2'. Ce qui ajoute donc des infos pour le débogage dans les librairies générées :

• jusqu'aux versions 2.x.x, cela pouvait augmenter la taille finale de la librairie de 50 % en moyenne (300 Ko sous Linux) ;
• avec la version 3.0.0 et la scission du source principal en plusieurs source, l'augmentation peut être de 300 % ! (650 Ko sous Linux) ;
• donc, il est possible de retirer ces informations en « stripant » les librairies finales libocilib.[ext].x.y.z (ext => 'so', 'a'…) avec la commande strip. Ce qui sous Linux fait passer de 650 Ko à 170Ko.

Sous Microsoft Windows, des DLL sont fournies pour les environnements 32 bits et 64 bits (x86) et peuvent être recompilées aisément.

Remarque : avec la version 3.0.0, le fichier d'entête principal a été déplacé de 'ocilib\src' vers 'ocilib\include\'.

• Décompresser l'archive courante (ocilib-x.y.z-windows.zip).
• Copier ocilib\include\ocilib.h dans un répertoire inclus dans la liste de l'option « fichier d'entêtes » du compilateur.
• Copier ocilib\lib32|64\ocilib[x].lib dans un répertoire inclus dans la liste de l'option « fichier bibliothèques » de l'éditeur de lien.
• Copier ocilib\lib32|64\ocilib[x].dll dans un répertoire inclus dans la variable d'environnement PATH.

[x] représente la version compilée d'OCILIB : « a » pour Ansi, « w » pour Unicode et « m » pour mixed mode.

Pour utiliser OCILIB dans un projet, il faut inclure le header « ocilib.h ».

Certaines options doivent être définies avant l'inclusion du header ocilib.h

=> Mode de liaison Oracle :

• OCI_IMPORT_LINKAGE : pour lier les librairies Oracle (statiques ou partagées) à la compilation (option par défaut sous Unix like) ;
• OCI_IMPORT_RUNTIME : pour charger dynamiquement les librairies Oracle à l'exécution (option par défaut dans les projets MS Windows fournis).
  
  

=> Charsets utilisés :

• OCI_CHARSET_ANSI : toutes les chaines de caractères sont en Ansi (option par défaut) ;
• OCI_CHARSET_UNICODE : toutes les chaines de caractères sont en Unicode (versions de Oracle >= 9i) ;
• OCI_CHARSET_MIXED : Ordres SQL, métadatas en Ansi et données utilisateurs fournies et récupérées des requêtes en Unicode.
  
  

=> Convention d'appel (MS Windows uniquement) :

• OCI_API : non défini (option par défaut) ;
• OCI_API : __sdtcall pour utiliser les dll précompilées.

Sous Windows, pour utiliser OCILIB en ANSI, en utilisant les Dlls fournies, il suffit de créer un nouveau projet et :

• inclure « ocilib.h » ;
• définir OCI_API=__sdtcall dans les options du préprocesseur du projet ;
• si toutes les variantes ocilib[x].lib sont disponibles pour le linker, il faut alors préciser quelle version en insérant #pragma comment(lib, « ocilib[x].lib ») dans un des fichiers du projet.

Remarque : avec la version 3.2.0, des librairies statiques sont aussi fournies pour les portages Windows de GCC : libociliba.a, libocilibm.a et libocilibw.a.

Sous Linux, pour utiliser OCILIB en ANSI et avec une liaison des librairies partagées d'Oracle à la compilation, il faut :

=> Supposons que $USER_LIBS pointe vers le répertoire parent où est installé OCILIB (par défaut : usr/local sous Linux)
=> Inclure « ocilib.h »
=> Ajouter au makefile pour le compilo :

• -I$USER_LIBS/include pour le header ocilib.h ;
• -DOCI_IMPORT_LINKAGE -DOCI_CHARSET_ANSI pour configurer ocilib.

=> Ajouter au makefile pour le linker :

• -L/$ORACLE_HOME/lib -lclntsh pour les librairies Oracle ;
• -L$USER_LIBS/lib -locilib pour la librairie OCILIB.

Avant tout chose, OCILIB doit être initialisée. Pour cela il faut, avant tout appel à une fonction de la librairie, appeler OCI_Initilalize(). Cette fonction initialise la librairie et prend en paramètres :

• [Optionnel] un pointeur sur une fonction de gestion des erreurs ;
• [Optionnel] un répertoire où se trouvent les librairies Oracle (si runtime loading et plusieurs clients Oracle installés) ;
• [Optionnel] le mode d'initialisation.

Les valeurs possibles pour le mode d'initialisation sont :

• OCI_ENV_DEFAULT : mode par défaut ;
• OCI_ENV_THREADED : activation du support multithread ;
• OCI_ENV_CONTEXT : activation de la gestion contextuelle des erreurs par thread.

Toute tentative de création d'un objet OCILIB avant l'initialisation génèrera une erreur qui pourra être récupérée par OCI_GetLastError().

#include "ocilib.h"

int main()
{
    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    /* ... application code here ... */
  
    OCI_Cleanup();

 
    return EXIT_SUCCESS;
}

En fin d'application, un appel à OCI_Cleanup() est nécessaire pour :

• désallouer les objets non explicitement libérés ;
• décharger les librairies Oracle dans le cas d'un runtime loading.

Se connecter à une base de données Oracle s'effectue par la fonction OCI_ConnectionCreate() qui prend en paramètres :

• le nom du service Oracle (alias Oracle, SID… en fonction des paramètres du client Oracle) ;
• le nom du user Oracle sur lequel se connecter ;
• le mot de passe du user Oracle ;
• le mode de session (OCI_SESSION_DEFAULT, OCI_SESSION_SYSDBA, OCI_SESSION_SYSOPER).

Les valeurs possibles pour le mode de session sont :

• OCI_SESSION_DEFAULT mode de session par défaut ;
• OCI_SESSION_SYSDBA : mode de session sysdba Oracle ;
• OCI_SESSION_SYSOPER : mode de session sysoper Oracle.

Cette fonction de charge de se connecter au serveur, créer une session et d'établir une transaction. En cas de succès, elle renvoie un handle de connexion et l'application peut de suite exécuter des ordres SQL.

#include "ocilib.h"
  
int main(void)
{
  OCI_Connection *cn;
  
  if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
    return EXIT_FAILURE;
  
  cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
  
  if (cn != NULL)
  {
    printf(OCI_GetVersionServer(cn));
    
    printf("Server major    version : %i\n", OCI_GetServerMajorVersion(cn));
    printf("Server minor    version : %i\n", OCI_GetServerMinorVersion(cn));
    printf("Server revision version : %i\n", OCI_GetServerRevisionVersion(cn));
    
    printf("Connection      version : %i\n", OCI_GetVersionConnection(cn));

    OCI_ConnectionFree(cn);
  }
  
  OCI_Cleanup();
  
  return EXIT_SUCCESS;
}

Pour fermer la connexion au serveur, il suffit d'appeler OCI_ConnectionFree().

OCILIB propose une gestion avancée des erreurs basée sur deux mécanismes distincts, mais complémentaires :

• erreurs générées par OCI ;
• erreurs OCILIB internes (allocations mémoire, type-checking, etc.) ;
• erreurs applicatives.

Les mécanismes proposés par OCILIB sont :

• gestion globale par callback ;
• gestion contextuelle par thread.

IV-C-1. Gestion globale par callback▲

typedef void (*POCI_ERROR) (OCI_Error *err);

#include "ocilib.h"

void err_handler(OCI_Error *err)
{
  printf("code  : ORA-%05i\n"
         "msg   : %s\n"
         "sql   : %s\n",
         OCI_ErrorGetOCICode(err), 
         OCI_ErrorGetString(err),
         OCI_GetSql(OCI_ErrorGetStatement(err)));
}
  
int main()
{
  OCI_Connection *cn;
  
  if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;
  
  cn = OCI_ConnectionCreate("wrong_db", "wrong_usr", "wrong_pwd", 
                            OCI_SESSION_DEFAULT);
  
  /* ... application code here ... */
  
  OCI_Cleanup();
  
  return EXIT_SUCCESS;
}

IV-C-2. Gestion contexuelle par thread▲

#include "ocilib.h"
  
int main()
{
  OCI_Connection *cn;
  
  if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT | OCI_ENV_CONTEXT))
    return EXIT_FAILURE;
  
  cn = OCI_ConnectionCreate("wrong_db", "wrong_usr", "wrong_pwd", OCI_SESSION_DEFAULT);
  
  if (cn == NULL)
  {
     OCI_Error *err = OCI_GetLastError();
     printf("errcode %d, errmsg %s", OCI_ErrorGetOCICode(err),  OCI_ErrorGetString(err));
  }
  
  OCI_Cleanup();
  
  return EXIT_SUCCESS;
}

OCILIB supporte les mécanismes de transactions (locales et globales) proposées par Oracle via OCI.

Par défaut, une fois que l'application s'est connectée à Oracle, une transaction locale est créée.
Toute modification de données (insert, update, delete) n'est pas visible des autres sessions tant que l'on n’a pas explicitement validé les modifications par un appel à OCI_Commit().

Si l'application ne veut pas valider ses modifications et donc annuler les modifications de données effectuées depuis la dernière validation (ou par défaut depuis la connexion au serveur), elle doit utiliser OCI_Rollback().

Il y a des cas où les simples transactions locales par défaut ne suffisent pas :

• gérer une connexion en lecture seule par exemple ;
• gérer une transaction globale dans un environnement distribué ;
• etc.

Dans ces cas-là, OCILIB propose une gestion explicite des transactions où il est possible de créer une transaction et de l'associer à un handle de connexion.

OCILIB supporte tous les types de données fournis par Oracle

Liste des types supportés :

• tous les types scalaires (strings, numériques, flottants…) : CHAR/NCHAR, VARCHAR2/NVARCHAR2, NUMBER, FLOAT…
• types binaires : RAW, LONG RAW, VARRAW ;
• Larges Objects (LOB et FILE) : BLOB, CLOB, NCLOB, BFILE, CFILE ;
• types LONG : LONG, VAR LONG, LONG RAW… ;
• Date, Timestamps et Intervals : DATE, TIMESTAMP (tous), INTERVAL (tous) ;
• PL/SQL types : Ref cursors, PL/SQL Tables (tableaux) et PL/SQL Nested Tables ;
• Objects (Named Types) : types utilisateurs et types système ;
• Références objects : Type REF ;
• SQL Collections : VARRAYs and Nested Tables ;
• ROWID et UROWID.

Tous ces types supportés peuvent être liés à des statements ou être récupérés d'un select.

Afin d'exécuter des ordres SQL sur la base de données, il faut créer un object SQL statement via la fonction OCI_CreateStatement().

Une fois cet objet créé, il est possible d'exécuter des requêtes par la fonction OCI_ExecuteStmt().

    OCI_Connection *cn;
    OCI_Statement *st;
     
    /* ... */
    
    st = OCI_StatementCreate(cn);
    
    OCI_ExecuteStmt(st, "delete from my_table where code is null");
    
    printf("%d row deleted", OCI_GetAffectedRows(st));
    
    OCI_Commit(cn);
    
    OCI_StatementFree(st);
     
    /* ... */

OCI_ExecuteStmt() a donc préparé et exécuté l'ordre SQL et OCI_GetAffectedRows() a récupéré le nombre de lignes supprimées dans la table.

Une fois que le statement n'est plus utile, un appel à OCI_StatementFree() libère toutes les ressources associées (resultset…).

Un object OCI_Statement peut être réutilisé pour exécuter autant d'ordres SQL que nécessaire.

Dans l'exemple précédent, la requête était simple et ne nécessitait aucune variable d'entrée. Souvent, il est nécessaire de fournir à une requête des valeurs d'entrées non connues à l'avance. De plus, il est utile de pouvoir exécuter plusieurs fois un même ordre SQL avec des valeurs différentes sans pour autant avoir à faire repréparer le SQL par Oracle afin d'optimiser les performances.

Il est donc possible de lier des variables du programme en fournissant leur adresse au statement.

Dans ce cas, il faut :

• préparer le SQL par OCI_Prepare() ;
• lier les variables avec les fonctions OCI_bindXXX() ou XXX est le type de donnée ;
• exécuter le SQL par OCI_Execute() :

    OCI_Connection *cn;
    OCI_Statement *st;
    int code;
    
    /* ... */
    
    st = OCI_StatementCreate(cn);
    
    OCI_Prepare(st, "delete from test_fetch where code = :code");
    OCI_BindInt(st, ":code", &code);
    
    code = 3;
    OCI_Execute(st);
    printf("%d row deleted"; OCI_GetAffectedRows(st));
    
    code = 56;
    OCI_Execute(st);
    printf("%d row deleted"; OCI_GetAffectedRows(st));
         
    OCI_Commit(cn);
    
    /* ... */

Pour faire une insertion de masse, on peut procéder de la manière suivante :

    OCI_Connection *cn;
    OCI_Statement *st;
    int code;
    char name[30];
    char value[20];
    
    /* ... */
    
    st = OCI_StatementCreate(cn);
    
    OCI_Prepare(st, "insert into my_table values(:code, :name, :value)");
    OCI_BindInt(st, ":code", &code);
    OCI_BindString(st, ":name", name, 30);
    OCI_BindString(st, ":value", value, 20);
    
    for (code = 1; code < 1000; code++);
    {
        sprintf(name, "name %i", code);
        sprintf(value, "value %i", code);
    
        OCI_Execute(st);
    }
        
    OCI_Commit(cn);
    
    /* ... */

Néanmoins, Oracle supporte les « bulks operations » (cf. chapitre VI) qui permettent de manipuler des tableaux de variables et donnent des performances incomparables.

Récupérer le résultat d'une requête est très simple. Il suffit une fois le statement exécuté via OCI_Execute() ou OCI_ExecuteStmt() d'appeler la fonction OCI_GetResultSet() qui retourne un handle sur un objet OCI_Resultset.

Ce resultset comprend deux choses :

• la description des colonnes retournées par la requête ;
• les données (lignes de résultats).

Afin d'accéder aux valeurs de chaque colonne du resultset, il faut:

• parcourir le resultset par un appel à OCI_FetchNext() qui retourne TRUE tant qu'il y a des lignes de résultat ;
• appeler une des fonctions OCI_GetXXX() en précisant l'index de la colonne (ou son nom) et où XXX est le type : Int, String, Date…

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement  *st;
    OCI_Resultset  *rs;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn  = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st  = OCI_StatementCreate(cn);

    OCI_ExecuteStmt(st, "select * from products");

    rs = OCI_GetResultset(st);
   
    while (OCI_FetchNext(rs))
        printf("code: %i, name %s\n", OCI_GetInt(rs, 1)  , OCI_GetString(rs, 2));

    printf("\n%d row(s) fetched\n", OCI_GetRowCount(rs));

    OCI_Cleanup();

    return EXIT_SUCCESS;
}

OCI_GetRowCount() donne le nombre de lignes du resultset déjà parcourues.

Le même exemple avec un accès aux colonnes par leur nom :

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement  *st;
    OCI_Resultset  *rs;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn  = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st  = OCI_StatementCreate(cn);

    OCI_ExecuteStmt(st, "select * from products");

    rs = OCI_GetResultset(st);
   
    while (OCI_FetchNext(rs))
        printf("code: %i, name %s\n", OCI_GetInt2(rs, "CODE")  , OCI_GetString2(rs, "NAME"));

    printf("\n%d row(s) fetched\n", OCI_GetRowCount(rs));

    OCI_Cleanup();

    return EXIT_SUCCESS;
}

Un objet statement peut être réutilisé autant de fois que voulu. De plus, il est possible d'en créer plusieurs et de les imbriquer.

    OCI_Connection *cn;
    OCI_Statement *st1, *st2;
    OCI_Resultset *rs;
    
    /* ... */
    
    st1 = OCI_StatementCreate(cn);
    st2 = OCI_StatementCreate(cn);
    
    int code;
    
    OCI_ExecuteStmt(st1, "select code from my_table");
    OCI_Prepare(st2, "delete from my_table2 where code_ref = :code");
    OCI_Bind(st2, ":code", &code);
    
    rs = OCI_GetResultset(st);
    
    while (OCI_FetchNext(rs))
    {
        code = OCI_GetInt(rs, 1);
    
        OCI_Execute(st2);
    } 
    
    /* ... */

Il est possible de récupérer les informations relatives (metadatas) à chaque colonne du resulset (colonnes sélectionnées par la requête). Pour cela :

• un appel à OCI_GetColumnCount() permet de savoir le nombre de colonnes contenues dans le resultset ;
• un appel à OCI_GetColumn() en précisant l'index (position dans le select) permet de récupérer un handle sur un objet OCI_Column ;
• toutes les propriétés de la colonne sont accessibles par une série de fonctions du type OCI_GetColumnXXX() où XXX est la propriété :

#include "ocilib.h"

int main()
{
     OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Resultset *rs;
    
    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", pwd", OCI_SESSION_DEFAULT);   
    st = OCI_StatementCreate(cn);
    
    OCI_ExecuteStmt(st, "select * from my_table");
    
    rs = OCI_GetResultset(st);
    nb = OCI_GetColumnCount(rs);
    
    for(i = 1; i <= nb; i++)
    {
        col = OCI_GetColumn(rs, i);
     
        printf("%-20s%-10s%-8i%-8i%-8i%-s\n",
                OCI_GetColumnName(col),
                OCI_GetColumnSQLType(col),
                OCI_GetColumnSize(col),
                OCI_GetColumnPrecision(col),
                OCI_GetColumnScale(col),
                OCI_GetColumnNullable(col) == TRUE ? "Y" : "N");
    }
    
    OCI_Cleanup();

    return EXIT_SUCCESS;
}

OCILIB supporte les « scrollables cursors » introduits avec Oracle 9i. Ces curseurs (resultsets au sens OCILIB) peuvent être parcourus :

• séquentiellement dans les deux sens (en arrière et en avant) ;
• il est possible de directement se placer sur le premier ou dernier enregistrement ;
• il est possible de directement se placer sur un enregistrement donné.

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Resultset *rs;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
       return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);

    st = OCI_StatementCreate(cn);

    OCI_SetFetchMode(st, OCI_SFM_SCROLLABLE);

    OCI_ExecuteStmt(st, "select int_col1, str_col from my_table");
   
    rs = OCI_GetResultset(st);
  
    /* get resultset row count */
    OCI_FetchLast(rs);
    printf("resultset contains %i rows\n", OCI_GetRowCount(rs));

    /* go to row 1 */
    OCI_FetchFirst(rs);
    printf("%i - %s\n", OCI_GetInt(rs, 1), OCI_GetString(rs, 2));

    /* enumerate from row 2 to row X */
    while (OCI_FetchNext(rs))
        printf("%i - %s\n", OCI_GetInt(rs, 1), OCI_GetString(rs, 2));

    /* enumerate from row X back to row 1 */
    while (OCI_FetchPrev(rs))
        printf("%i - %s\n", OCI_GetInt(rs, 1), OCI_GetString(rs, 2));

    /* print the 30th row */
    OCI_FetchSeek(rs, OCI_SFD_ABSOLUTE,  30);
    printf("%i - %s\n", OCI_GetCurrentRow(rs), OCI_GetInt(rs, 1), OCI_GetString(rs, 2));

    /* fetch next 30 rows */
    while ((OCI_GetCurrentRow(rs) < 60) << OCI_FetchNext(rs))
        printf("%0i - %s\n", OCI_GetInt(rs, 1), OCI_GetString(rs, 2));

    /* move back to the 45th row */
    OCI_FetchSeek(rs, OCI_SFD_RELATIVE,  -15);
    printf("%i - %s\n", OCI_GetInt(rs, 1), OCI_GetString(rs, 2));

   OCI_Cleanup();

   return EXIT_SUCCESS;
}

Des variables peuvent être liées en entrée comme en sortie.

Pour exécuter du PL/SQL, il suffit d'englober le code PL/SQL par un « begin » en début et un « end; » en fin de block.

    OCI_Connection *cn;
    OCI_Statement *st;
   
    /* ... */
    
    st = OCI_StatementCreate(cn);
   
    OCI_Prepare(st, "begin :n := trunc(sysdate+1)-trunc(sysdate-1); end;");
    OCI_BindInt(st, ":n", &n);
    OCI_Execute(st);
     
    printf("Result : %i\n", n);
     
    /* ... */

Exemple de récupération d'un cursor PL/SQL et fetch de son résultat dans le programme C :

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement  *st1; *st2;     
    OCI_Resultset *rs;
    
    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", pwd", OCI_SESSION_DEFAULT);
    
    st1 = OCI_StatementCreate(cn);
    st2 = OCI_StatementCreate(cn);
    
    OCI_Prepare(st1, "begin open :c for select * from my_table; end;");
    OCI_BindStatement(st2, ":c", st2);
    OCI_Execute(st1);
     
    rs = OCI_GetResultset(st2);
    
    while (OCI_FetchNext(rs))
    {
        printf("value %s\n", OCI_GetString(rs, 1));
    }
    
    OCI_Cleanup();

    return EXIT_SUCCESS;
}

Oracle propose une fonctionnalité très intéressante qui est la clause SQL « returning into ».

L'utilisation de cette clause dans un DML (insert/update/delete) permet de combiner deux requêtes en une, réduisant ainsi le nombre d'allers-retours entre le client et le serveur.
L'ajout de cette clause permet de sélectionner les lignes affectées par le DML au sein de la même requête. Ce qui est pratique, notamment dans le cas de delete, car les valeurs supprimées sont ainsi récupérables !

OCILIB implémente cette fonctionnalité en créant un objet OCI_Resultset à partir des colonnes sélectionnées dans la clause RETURNING. Ce resultset est ensuite manipulable comme un resultset classique.
L'Array Interface est également compatible avec cette clause. Dans ce cas, chaque entrée du tableau peut affecter différentes lignes. OCILIB crée alors un resultset pour chaque entrée du tableau.
Par exemple, si le tableau utilisé pour lier des variables au statement contient 100 éléments, l'application commence par récupérer le premier resulset par un appel à OCI_GetResulset(). Une fois ce resultset parcouru, le resultset suivant est récupérable par un appel à OCI_GetNextResultset().

OCILIB ne préparse jamais les requêtes SQL (pour des raisons de performances) et donc ne peut déterminer les champs (ainsi que leur type) utilisés dans la clause RETURNING.
Il faut donc que l'application indique explicitement les colonnes de la clause RETURNING par les fonctions OCI_RegisterXXX() ou XXX est le type de données. OCILIB construit alors les resultsets sur la base des colonnes ainsi déclarées.

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement  *st;
    OCI_Resultset  *rs;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_CreateStatement(cn);

    OCI_Prepare(st, "update products set code = code+10 returning code into :i");
    OCI_RegisterInt(st, ":i");
    OCI_Execute(st);
  
    rs = OCI_GetResultset(st);

    while (OCI_FetchNext(rs))
        printf("%i\n", OCI_GetInt(rs, 1));
 
    printf("count : %i\n", OCI_GetRowCount(rs));
  
    OCI_Commit(cn);
    
    OCI_Cleanup();

    return EXIT_SUCCESS;
}

OCILIB propose une série de fonctions permettant de personnaliser les comportements d'un statement.

Par exemple, il est possible de spécifier :

• le nombre de lignes préfetchées par le client Oracle afin de diminuer le nombre de roundtrips avec le serveur ;
• le nombre de lignes fetchées de manière interne par OCILIB afin de réduire les appels OCI ;
• le mode de liaison des variables : par position ou par nom ;
• le format de date par défaut ;
• etc.

Dans l'exemple précédent, le trafic réseau généré par un nombre important d'exécutions d'une même requête est la source principale de la lenteur finale du traitement.

Oracle propose de minimiser ce trafic en lui fournissant des tableaux de variables. Au lieu de fournir 1 variable et envoyer 1000 fois sa valeur au serveur, on fournit un tableau de 1000 valeurs qui est envoyé en une seule fois.

Ce système permet de réduire le temps de traitement par des facteurs de 3 à 5 chiffres au minimum sur des gros volumes.

OCILIB supporte ce mécanisme et donne la possibilité de lier des tableaux de n'importe quel type supporté par OCILIB (excepté OCI_Long et OCI_Statement).

Les BLOB/CLOB sont stockés dans la base de données. Leur utilisation diffère de celles des autres types de données. En effet, une simple requête SQL ne suffit pas à lire ou écrire dans un champ de plusieurs centaines de Mo.

OCILIB propose toute une série de fonctions permettant de manipuler très simplement ces objets (OCI_Lob *).

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Lob *lob;
    FILE *f;
    unsigned char buffer[1024];
    int size;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_StatementCreate(cn);
        
    f  = fopen("My file", "rb");
    
    if (f != NULL)
    {
        fseek (f , 0 , SEEK_END); 
        size = ftell(f); 
        rewind (f); 
         
        printf("\nTotal bytes to write : %d\n", size);
        
        lob = OCI_LobCreate(cn, OCI_BLOB);
        
        OCI_Prepare(st, "insert into my_blob_table(code, content) values (1, :data)");
        OCI_BindLob(st, ":data", lob);
        OCI_Execute(st);
   
        /* write data into table by chunks of 1024 bytes */ 
        while ((n = fread(buffer, 1, sizeof(buffer), f)))
        {
            OCI_LobWrite(lg, buffer, n);
        }
   
        printf("\nTotal bytes written : %s\n", OCI_LobGetLenght(lob));
        fclose(f);
   
        OCI_Commit(cn);
   
        OCI_LobFree(lob);
    }
    
    OCI_Cleanup();

    return EXIT_SUCCESS;
}

Par exemple, pour lire le contenu d'un fichier texte ANSI stocké dans un champ de type CLOB d'une table :

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Lob *lob1, *lob2;

    int code, n;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_StatementCreate(cn);
 
    OCI_ExecuteStmt(st, "select code, content from test_lob for update");

    rs = OCI_GetResultset(st);
    
    while (OCI_FetchNext(rs))
    {
        code = OCI_GetInt(rs, 1);
        lob1 = OCI_GetLob(rs, 2);
        lob2 = OCI_LobCreate(cn, OCI_CLOB);

        n = OCI_LobWrite(lob1, "Today, ", 7);
        OCI_LOBeek(lob1, n, OCI_SEEK_SET);
       
        n = OCI_LobWrite(lob2, "I'm going to the cinema !", 25);
       
        OCI_LobAppendLob(lob1, lob2);
        OCI_LOBeek(lob1, 0, OCI_SEEK_SET);
        
        n = OCI_LobRead(lob1, temp, 100);
        temp[n] = 0;

        printf("code: %i, action : %s\n", code, temp);
            
        OCI_LobFree(lob2);
    }

    printf("\n%d row(s) fetched\n", OCI_GetRowCount(rs));

    OCI_Cleanup();

    return EXIT_SUCCESS;
}

Les objets de type FILE (OCI_File *) sont des références à des fichiers externes à la DB qui peuvent être ouverts pour lecture par le serveur et dont le contenu peut être récupéré par l'application cliente.

Les objets FILE sont similaires aux LOB et donc leur API est similaire sauf que les FILE sont en lecture seule.

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_File *file;
    char buffer[256];
    int n;

    if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_StatementCreate(cn);

    file = OCI_FileCreate(cn, OCI_CFILE);

    OCI_FILEetName(file, "MYDIR", "MyfileName");

    /* check if faile exists */

    if (OCI_FileExists(file))
    {
         printf("file size : %d\n", OCI_FileGetSize(file));
         printf("file dir  : %s\n", OCI_FileGetDirectory(file));
         printf("file name : %s\n", OCI_FileGetName(file));
    }

    /* bind for inserting into table */

    OCI_Prepare(st, "insert into my_bfile_table(code, value) values (1, :bfile)");
    OCI_BindFile(st, ":bfile", file);
    OCI_Execute(st);
    OCI_Commit(cn);

    /* free local file object */

    OCI_FileFree(file),

    /* fetch bfile data from table */
 
    OCI_ExecuteStmt(st, "select code, value from my_bfile_table");
 
    rs = OCI_GetResultset(st);

    while (OCI_FetchNext(rs))
    {
        file = OCI_GetFile(rs, 2);

        OCI_FileOpen(file);

        printf("file size  %d\n", OCI_FileGetSize(file));
        printf("file dir   %s\n", OCI_FileGetDirectory(file));
        printf("file name  %s\n", OCI_FileGetName(file));
 
        while (n = OCI_FileRead(file, buffer, sizeof(buffer)-1))
        {
            buffer[n] = 0;
            printf(buffer);
        }

        OCI_FileClose(file);
    }

    OCI_Cleanup();

    return EXIT_SUCCESS;
}

OCILIB implémente les « anciens » LONG (OCI_Long *) de manière similaire aux LOB et FILE. Les API de manipulation des champs LONG sont donc très proches de celles des Large Objects.

#include "ocilib.h"

#define FILENAME "data.lst"

int main()
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Long *lg;
    FILE *f;
    char buffer[2048];
    int n;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_StatementCreate(cn);

   /* INSERT LONG  -------------------------------------------- */
 
     /* open the app file */

    f = fopen(FILENAME, "rb");

    if (f)
    {
        fseek (f , 0 , SEEK_END); 
        n = ftell(f); 
        rewind (f);  
  
        printf("\n%d bytes to write\n", n);

        lg = OCI_LongCreate(st, OCI_BLONG);

        OCI_Prepare(st,  "insert into test_long_raw(code, content) values (1, :data)");
        OCI_BindLong(st, ":data", lg, n);
        OCI_Execute(st);

        /* write data into table by chunks of 2048 bytes */       
        while ((n = fread(buffer, 1, sizeof(buffer), f)))
        {
            OCI_LongWrite(lg, buffer, n);
        }

        printf("\n%d bytes written\n", OCI_LongGetSize(lg));
        fclose(f);

        OCI_LongFree(lg);
        OCI_Commit(cn);
    }

    /* FETCHING LONG  -------------------------------------------- */

 
    OCI_ExecuteStmt(st, "select content from test_long_raw where code = 1");
    OCI_SetLongMaxSize(st, 1000000);

    rs = OCI_GetResultset(st);

    /* read data by chunks of 2048 bytes*/       
    while (OCI_FetchNext(rs))
    {
        lg = OCI_GetLong(rs, 1);

        while ((n = OCI_LongRead(lg, buffer, sizeof(buffer)))) {}

        printf("\n%d bytes read\n", OCI_LongGetSize(lg));
    }

    OCI_Cleanup();

    return EXIT_SUCCESS;
}

Afin de créer une instance autonome, il faut récupérer le descripteur du type concerné. Cela se réalise par un appel à OCI_TypeInfoGet().

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Resultset *rs; 
    OCI_Object *prod;
    OCI_Date *date;
    int qte;
    
    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_StatementCreate(cn);
      
    prod = OCI_ObjectCreate(cn, OCI_TypeInfoGet(cn, "t_product", OCI_TIF_TYPE);
    date = OCI_DateCreate(cn);
    
    qte = 356;
    OCI_DateSysDate(date);
    
    OCI_ObjectSetInt(prod, "CODE", 1);
    OCI_ObjectSetString(prod, "LIBELLE", "USB KEY 2go");
    OCI_ObjectSetDouble(prod, "PRIX", 12.99);
    OCI_ObjectSetString(prod, "REFERENCE", "A56547WSAA");

    OCI_Prepare(st, "insert into ventes_produits values(:p, :n, :d)");
    
    OCI_BindObject(st, ":p", prod);
    OCI_BindInt(st, ":n", &qte);
    OCI_BindDate(st, ":d", date);
   
    OCI_Execute(st);

    printf("\n%d row(s) inserted\n", OCI_GetAffectedRows(st));

    OCI_Commit(cn);

    OCI_ObjectFree(obj);
      
    OCI_Cleanup();
 
    return EXIT_SUCCESS;
}

Les objets peuvent être sélectionnés de la même façon que les types de données SQL.

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Resultset *rs; 
    OCI_Object *prod;
    OCI_Date *date;
    int qte;
    
    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_StatementCreate(cn);
   
    OCI_ExecuteStmt(st, "select * from ventes_produits");
  
    rs = OCI_GetResultset(st);
   
    while (OCI_FetchNext(rs))
    {
        prod = OCI_GetObject(rs, 1);
        qte  = OCI_GeInt(rs, 2);
        date = OCI_GetDate(rs, 3);
   
        printf("Produit : %s, Ventes : %i\n", OCI_ObjectGetString(prod, "LIBELLE"), qte);
    }   
    
    OCI_Cleanup();
 
    return EXIT_SUCCESS;
}

Oracle propose une API permettant de charger des données directement dans les tables sans passer par le moteur SQL.

Cette fonctionnalité, disponible dans l'API OCI, est implémentée dans l'outil SQL*Loader (mode direct). Les données sont généralement issues de fichiers textes.

Ce mode de chargement est extrêmement rapide, car les données sont directement converties au format de stockage dans les tables.
OCILIB implémente cette fonctionnalité à l'exception des types de données suivants : objets, refs et string functions. Pour plus de détails, se référer à la documentation d'OCILIB.

OCILIB permet de manipuler les dates Oracle (date/heure) avec facilité.

Exemple où une date est récupérée d'une table, puis affichée, incrémentée de 5 jours et 2 mois et enfin réaffichée :

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Date *dt;
    char str[100];
    int n;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_StatementCreate(cn);
   
    OCI_ExecuteStmt(st, "select mon_champs_date from my_table");
    rs = OCI_GetResultset(st);
   
    while (OCI_FetchNext(rs))
    {
        dt = OCI_GetDate(rs, 1);
   
        OCI_DateToText(dt, "DD/MM/YYYY HH24:MI:SS", sizeof(str)-1, str);
        printf("Date is %s\n", str);
   
        OCI_DateAddDays(dt, 5);
        OCI_DateAddMonths(dt, 2);
   
        OCI_DateToText(dt, "DD/MM/YYYY HH24:MI:SS", sizeof(str)-1, str);
        printf("Date + 5 days and 2 months is %s\n", str);
    }
    
    OCI_Cleanup();
 
    return EXIT_SUCCESS;
}

Les timestamps sont des extensions au type DATE permettant :

• de gérer avec précision les dates grâce à la gestion des fractions de seconde ;
• de gérer les fuseaux horaires.

Exemple où la date/heure courante est récupérée du serveur et affichée avec les fractions de seconde :

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement *st;
    OCI_Timestamp *tm;
    char str[100];
    int n;

    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_StatementCreate(cn);
   
    OCI_ExecuteStmt(st, "SELECT CURRENT_TIMESTAMP FROM dual");
    rs = OCI_GetResultset(st);
   
    OCI_FetchNext(rs);
    tm = OCI_GetTimestamp(rs, 1);
   
    OCI_TimestampToText(tm, "DD/MM/YYYY HH24:MI:SS:FF3\n", 100, str, 3);
    printf(str);
    
    OCI_Cleanup();
 
    return EXIT_SUCCESS;
}

Les intervals sont des périodes de temps exprimées :

• soit en années et mois ;
• soit en jours, heures, minutes et secondes.

Ils permettent d'effectuer des opérations sur les timestamps.

Exemple où la date/heure courante locale est récupérée dans la variable tm, puis incrémentée de 1 jour, 1 heure, 1 minute et 1 seconde puis affichée avec les fractions de seconde :

#include "ocilib.h"
 
#define SIZE_STR 260

int main()
{
    OCI_Timestamp *tm;
    OCI_Interval *itv;
   
    if (!OCI_Initialize(NULL, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    tm  = OCI_TimestampCreate(NULL, OCI_TIMESTAMP);
    itv = OCI_IntervalCreate(NULL, OCI_INTERVAL_DS);

    OCI_TimestampSysTimeStamp(tm);
    OCI_TimestampToText(tm, "DD/MM/YYYY HH24:MI:SS:FF3", SIZE_STR, str, 3);
    printf("%s\n", str);

    OCI_IntervalSetDaySecond(itv, 1,1,1,1,0);
    OCI_IntervalToText(itv, 10, 10, SIZE_STR, str);
    printf("%s\n", str);
   
    OCI_TimestampIntervalAdd(tm, itv);
    OCI_TimestampToText(tm, "DD/MM/YYYY HH24:MI:SS:FF3", SIZE_STR, str, 3);
    printf("%s\n", str);
    
    OCI_TimestampFree(tm);
    OCI_IntervalFree(itv);

    OCI_Cleanup();
 
    return EXIT_SUCCESS;
}

OCILIB supporte totalement Unicode sur toutes les plateformes à travers le type de donnée C wchar_t (UTF16/UTF32 selon les plateformes).

OCILIB, pour les builds Unicode, initialise OCI en mode UTF16, qui est implémenté par Oracle par un encodage à taille fixe sur 2 bytes.

Donc, sur les systèmes implémentant wchar_t sur 2 bytes (comme MS Windows), les chaines de caractères et buffers utilisateurs sont directement passés à Oracle.

Sur les autres systèmes (quasiment tous les Unix et Linux), wchar_t est implémenté sur 4 bytes et UTF32 est usuellement utilisé comme encodage.

Dans ce cas, OCILIB :

• utilise des buffers temporaires pour passer à OCI les chaines de caractères de métadonnées (requêtes, attributs…) ;
• alloue ses buffers sur la taille de wchar_t et exécute une expansion de UTF16 à UTF32 pour les buffers de données.

L'expansion de données est faite « inplace », ce qui a l'avantage de ne pas nécessiter de buffer supplémentaire. Cela permet d'optimiser au mieux la gestion de la taille variable du type wchar_t.

OCILIB propose des fonctions « all in one » qui ont une liste d'arguments variables.

Elles permettent de réduire le nombre de lignes de code au minimum possible !

Par exemple, OCILIB permet d'écrire en 1 seule ligne de code les actions suivantes :

• préparation du SQL ;
• liaison d'une variable ;
• exécution de la requête ;
• fetch du résultat (1 ligne).

Ce qui équivaut au code suivant :

• OCI_Prepare(st, « select article from test_fetch where code = :i ») ;
• OCI_Bind(st, « :code », &code) ;
• OCI_Execute(st) ;
• OCI_GetResultset(st) ;
• OCI_FetchNext(rs) ;
• OCI_GetString(rs, 1).

Qui peut être remplacé par le code suivant :

• OCI_ImmediateFmt(cn, « select article from test_fetch where code = %i », code, OCI_ARG_TEXT, name);

D'autres exemples :

#include "ocilib.h"

int main()
{
    OCI_Connection *cn;
    OCI_Statement  *st;
    OCI_Resultset  *rs;
 
    int code = 1;
    char name[50];
  
    if (!OCI_Initialize(err_handler, NULL, OCI_ENV_DEFAULT))
        return EXIT_FAILURE;

    cn = OCI_ConnectionCreate("db", "usr", "pwd", OCI_SESSION_DEFAULT);
    st = OCI_StatementCreate(cn);
 
    /* sql format with params ----------------------------------------------- */

    OCI_ExecuteStmtFmt(st, "select article from test_fetch where code = %i", code);

    rs = OCI_GetResultset(st);

    while (OCI_FetchNext(rs))
        printf("article : %s\n", OCI_GetString(rs, 1));

    /* sql immediate (parse, exec, one fetch) ------------------------------- */

    OCI_Immediate(cn, "select code, article from test_fetch where code = 1", 
                  OCI_ARG_INT, &code, OCI_ARG_TEXT, name);

    printf("article : %s - code %i\n", name, code);

    /* sql immediate (parse, exec, one fetch) with params ------------------- */

    
    OCI_ImmediateFmt(cn, "select article from test_fetch where code = %i", 
                          code, OCI_ARG_TEXT, name);

    printf("article : %s\n", name);

    OCI_Cleanup();
 
    return EXIT_SUCCESS;
}

• Consulter la documentation en ligneConsulter la documentation en ligne
• La documentation est également incluse dans les distributions de OCILIB