Documentation PostgreSQL 15.15 » Interfaces client » ECPG -- SQL embarqué en C » Exécuter des Commandes SQL

Précédent | Niveau supérieur | Suivant
36.2. Gérer les Connexions à la Base de Données | Sommaire | 36.4. Utiliser des Variables Hôtes

## 36.3. Exécuter des Commandes SQL

Toute commande SQL peut être exécutée à l'intérieur d'une application SQL embarquée. Voici quelques exemples montrant comment le faire.

### 36.3.1. Exécuter des Ordres SQL

Créer une table :

    EXEC SQL CREATE TABLE truc (nombre integer, ascii char(16));
    EXEC SQL CREATE UNIQUE INDEX num1 ON truc(nombre);
    EXEC SQL COMMIT;

Insérer des lignes :

    EXEC SQL INSERT INTO truc (nombre, ascii) VALUES (9999, 'doodad');
    EXEC SQL COMMIT;

Supprimer des lignes :

    EXEC SQL DELETE FROM truc WHERE nombre = 9999;
    EXEC SQL COMMIT;

Mettre à jour des lignes :

    EXEC SQL UPDATE truc
        SET ascii = 'trucmachin'
        WHERE nombre = 9999;
    EXEC SQL COMMIT;

Les ordres `SELECT` qui retournent un seul enregistrement peuvent aussi être exécutés en utilisant `EXEC SQL` directement. Pour traiter des jeux de résultats de plusieurs enregistrements, une application doit utiliser un curseur; voyez Section 36.3.2 plus bas. (Exceptionnellement, une application peut récupérer plusieurs enregistrements en une seule fois dans une variable hôte tableau; voyez Section 36.4.4.3.1.)

Select mono-ligne :

    EXEC SQL SELECT truc INTO :trucmachin FROM table1 WHERE ascii = 'doodad';

De même, un paramètre de configuration peut être récupéré avec la commande `SHOW` :

    EXEC SQL SHOW search_path INTO :var;

Les tokens de la forme `:`quelquechose`` sont des variables hôtes, c'est-à-dire qu'ils font référence à des variables dans le programme C. Elles sont expliquées dans Section 36.4.

### 36.3.2. Utiliser des Curseurs

Pour récupérer un résultat contenant plusieurs enregistrements, une application doit déclarer un curseur et récupérer chaque enregistrement de ce curseur. Les étapes pour déclarer un curseur sont les suivantes: déclarer le curseur, l'ouvrir, récupérer un enregistrement à partir du curseur, répéter, et finalement le fermer.

Select avec des curseurs :

    EXEC SQL DECLARE truc_machin CURSOR FOR
        SELECT nombre, ascii FROM foo
        ORDER BY ascii;
    EXEC SQL OPEN truc_machin;
    EXEC SQL FETCH truc_machin INTO :TrucMachin, MachinChouette;
    ...
    EXEC SQL CLOSE truc_machin;
    EXEC SQL COMMIT;

Pour plus de détails sur la déclaration d'un curseur, voir DECLARE ; Pour plus de détails sur la récupération des enregistrements depuis un curseur, voir FETCH.

### Note

La commande `DECLARE` ne déclenche pas réellement l'envoi d'un ordre au serveur PostgreSQL. Le curseur est ouvert dans le processus serveur (en utilisant la commande `DECLARE`) au moment où la commande `OPEN` est exécutée.

### 36.3.3. Gérer les Transactions

Dans le mode par défaut, les ordres SQL ne sont validés que quand `EXEC SQL COMMIT` est envoyée. L'interface SQL embarquée supporte aussi l'auto-commit des transactions (de façon similaire au comportement de psql) via l'option de ligne de commande `-t` d'`ecpg` (voyez ecpg) ou par l'ordre `EXEC SQL SET AUTOCOMMIT TO ON`. En mode auto-commit, chaque commande est validée automatiquement sauf si elle se trouve dans un bloc explicite de transaction. Ce mode peut être explicitement désactivé en utilisant `EXEC SQL SET AUTOCOMMIT TO OFF`.

Les commandes suivantes de gestion de transaction sont disponibles :

`EXEC SQL COMMIT`

  Valider une transaction en cours.

`EXEC SQL ROLLBACK`

  Annuler une transaction en cours.

`EXEC SQL PREPARE TRANSACTION` `transaction_id`

  Préparer la transaction courante pour une transaction en deux phases.

`EXEC SQL COMMIT PREPARED` `transaction_id`

  Valide une transaction qui est dans un état préparé.

`EXEC SQL ROLLBACK PREPARED` `transaction_id`

  Annule une transaction qui est dans un état préparé.

`EXEC SQL SET AUTOCOMMIT TO ON`

  Activer le mode auto-commit.

`EXEC SQL SET AUTOCOMMIT TO OFF`

  Désactiver le mode auto-commit. C'est la valeur par défaut.

### 36.3.4. Requêtes préparées

Quand les valeurs à passer à un ordre SQL ne sont pas connues au moment de la compilation, ou que le même ordre SQL va être utilisé de nombreuses fois, les requêtes préparées peuvent être utiles.

L'ordre est préparé en utilisant la commande `PREPARE`. Pour les valeurs qui ne sont pas encore connues, utilisez le substitut « `?` »:

    EXEC SQL PREPARE stmt1 FROM "SELECT oid, datname FROM pg_database WHERE oid = ?";

Si un ordre retourne une seule ligne, l'application peut appeler `EXECUTE` après `PREPARE` pour exécuter l'ordre, en fournissant les vraies valeurs pour les substituts avec une clause `USING` :

    EXEC SQL EXECUTE stmt1 INTO :dboid, :dbname USING 1;

Si un ordre retourne plusieurs enregistrements, l'application peut utiliser un curseur déclarés en se servant d'une requête préparée. Pour lier les paramètres d'entrée, le curseur doit être ouvert avec une clause `USING` :

    EXEC SQL PREPARE stmt1 FROM "SELECT oid,datname FROM pg_database WHERE oid > ?";
    EXEC SQL DECLARE foo_bar CURSOR FOR stmt1;

    /* Quand la fin du jeu de résultats est atteinte, sortir de la boucle while */
    EXEC SQL WHENEVER NOT FOUND DO BREAK;

    EXEC SQL OPEN foo_bar USING 100;
    ...
    while (1)
    {
        EXEC SQL FETCH NEXT FROM foo_bar INTO :dboid, :dbname;
        ...
    }
    EXEC SQL CLOSE foo_bar;

Quand vous n'avez plus besoin de la requête préparée, vous devriez la désallouer :

    EXEC SQL DEALLOCATE PREPARE nom;

Pour plus de détails sur `PREPARE`, voyez PREPARE. Voyez aussi Section 36.5 pour plus de détails à propos de l'utilisation des substituts et des paramètres d'entrée.