ecpg

Pré-traitement pour la compilation

Un fichier source SQL embarqué doit être pré-traité avant compilation :

ecpg [ -d ] [ -o file ] file.pgc

Vous pouvez vouloir rediriger la sortie préprocesseur vers un fichier de log.

Compilation et mise en relation

En supposant que les binaires PostgreSQL soient dans /usr/local/pgsql, vous aurez besoin de compiler et lier votre fichier source pré-traité :

gcc -g -I /usr/local/pgsql/include [ -o file ] file.c -L /usr/local/pgsql/lib -lecpg -lpq

Bibliothèques

Le préprocesseur ajoutera deux directives à la source :

#include <ecpgtype.h>
#include <ecpglib.h>

Déclaration de variable

Les variables déclarées dans le code source ecpg doivent être précédées par :

EXEC SQL BEGIN DECLARE SECTION;

De façon similaire, les sections de déclaration de variable doivent se terminer par :

EXEC SQL END DECLARE SECTION;

Avant la version 2.1.0, devait être déclarée sur un ligne séparée. Depuis la version 2.1.0 de multiples variables peuvent être déclarées sur une seule ligne : char foo[16], bar[16];

Traitement d'erreur

La zone de communication SQL est définie avec :

EXEC SQL INCLUDE sqlca;

Le sqlca est en minuscules. Alors que la convention SQL peut être suivie, i.e., utiliser des majuscules pour séparer le SQL embarqué des instructions en C, sqlca (qui comprend le fichier d'en-têtes sqlca.h) doit être en minuscules. Ceci parce que le préfixe EXEC SQL indique que cette inclusion sera analysée par ecpg. ecpg est sensible à la casse (SQLCA.h ne sera pas trouvé). EXEC SQL INCLUDE peut être utilisé pour inclure d'autres fichiers d'en-têtes tant que la sensibilité à la casse est respectée.

La commande sqlprint est utilisée avec l'instruction EXEC SQL WHENEVER pour activer le traitement d'erreur à travers le programme :

EXEC SQL WHENEVER sqlerror sqlprint;

EXEC SQL WHENEVER not found sqlprint;

Ceci n'est pas un exemple exhaustif de l'usage de l'instruction EXEC SQL WHENEVER. D'autres exemples peuvent être trouvés dans les manuels de SQL (ex., The LAN TIMES Guide to SQL par Groff et Weinberg).

Connection à un serveur de base

On se connecte à une base en utilisant :

EXEC SQL CONNECT TO dbname;

Spécifier un nom de serveur et un port dans l'instruction de connexion est également possible. La syntaxe est :

dbname[@server][:port]

<tcp|unix>:postgresql://server[:port][/dbname][?options]

Requêtes

En général, des requêtes SQL acceptables par les autres applications comme psql peuvent être insérées dans votre code C. Ici, quelques exemples de la façon de faire :

Création de table:

EXEC SQL CREATE TABLE foo (number int4, ascii char(16));
EXEC SQL CREATE UNIQUE index num1 on foo(number);
EXEC SQL COMMIT;

Insertion :

EXEC SQL INSERT INTO foo (number, ascii) VALUES (9999, 'doodad');
EXEC SQL COMMIT;

Suppression :

EXEC SQL DELETE FROM foo WHERE number = 9999;
EXEC SQL COMMIT;

Sélection unitaire :

EXEC SQL SELECT foo INTO :FooBar FROM table1 WHERE ascii = 'doodad';

Sélection en utilisant des curseurs :

EXEC SQL DECLARE foo_bar CURSOR FOR
    SELECT number, ascii FROM foo
    ORDER BY ascii;
EXEC SQL FETCH foo_bar INTO :FooBar, DooDad;
...
EXEC SQL CLOSE foo_bar;
EXEC SQL COMMIT;

Mises à jour :

EXEC SQL UPDATE foo
    SET ascii = 'foobar'
    WHERE number = 9999;
EXEC SQL COMMIT;