Documentation PostgreSQL 14.22 » Interfaces client » ECPG -- SQL embarqué en C » Gestion des Erreurs

Précédent | Niveau supérieur | Suivant
36.7. Utiliser les Zones de Descripteur | Sommaire | 36.9. Directives de Préprocesseur

## 36.8. Gestion des Erreurs

Cett section explique comment vous pouvez traiter des conditions d'exception et des avertissements dans un programme SQL embarqué. Il y a deux fonctionnalités non-exclusives pour cela.

- Des fonctions de rappel (callbacks) peuvent être configurées pour traiter les conditions d'avertissement et d'erreur en utilisant la commande `WHENEVER`.
- Des informations détaillées à propos de l'erreur ou de l'avertissement peuvent être obtenues de la variable `sqlca`.

### 36.8.1. Mettre en Place des Callbacks

Une méthode simple pour intercepter des erreurs et des avertissements est de paramétrer des actions spécifiques à exécuter dès qu'une condition particulière se produit. En général :

    EXEC SQL WHENEVER condition action;

`condition` peut être un des éléments suivants :

`SQLERROR`

  L'action spécifiée est appelée dès qu'une erreur se produit durant l'exécution d'un ordre SQL.

`SQLWARNING`

  L'action spécifiée est appelée dès qu'un avertissement se produit durant l'exécution d'un ordre SQL.

`NOT FOUND`

  L'action spécifiée est appelée dès qu'un ordre SQL récupère ou affecte zéro enregistrement. (Cette condition n'est pas une erreur, mais vous pourriez être intéressé par un traitement spécial dans ce cas).

`action` peut être un des éléments suivants:

`CONTINUE`

  Cela signifie en fait que la condition est ignorée. C'est le comportement par défaut.

`GOTO `label``
`GO TO `label``

  Sauter au label spécifié (en utilisant un ordre `goto` C).

`SQLPRINT`

  Affiche un message vers la sortie standard. C'est utile pour des programmes simples ou durant le prototypage. Le détail du message ne peut pas être configuré.

`STOP`

  Appelle `exit(1)`, ce qui mettra fin au programme.

`DO BREAK`

  Exécuter l'ordre C `break`. Cela ne devrait être utilisé que dans des boucles ou des ordres `switch`.

`DO CONTINUE`

  Exécute l'instruction C `continue`. Ceci doit seulement être utilisé dans les instructions de boucle. Son exécution fait que le flot de contrôle est renvoyé au sommet de la boucle.

`CALL `name` (`args`)`
`DO `name` (`args`)`

  Appelle la fonction C spécifiée avec les arguments spécifiés. (Son utilisation est différente des instructions `CALL` et `DO` dans la grammaire habituelle de PostgreSQL.)

Le standard SQL ne fournit que les actions `CONTINUE` et `GOTO` (and `GO TO`).

Voici un exemple de ce que pourriez vouloir utiliser dans un programme simple. Il affichera un message quand un avertissement se produit et tuera le programme quand une erreur se produit:

    EXEC SQL WHENEVER SQLWARNING SQLPRINT;
    EXEC SQL WHENEVER SQLERROR STOP;

L'ordre `EXEC SQL WHENEVER` est une directive du préprocesseur SQL, pas un ordre SQL. L'action sur erreur ou avertissement qu'il met en place s'applique à tous les ordres SQL embarqués qui apparaissent après le point où le gestionnaire est mis en place, sauf si une autre action a été mise en place pour la même condition entre le premier `EXEC SQL WHENEVER` et l'ordre SQL entrainant la condition, quel que soit le déroulement du programme C. Par conséquent, aucun des extraits des deux programmes C suivants n'aura l'effet escompté :

    /*
     * WRONG
     */
    int main(int argc, char *argv[])
    {
        ...
        if (verbose) {
            EXEC SQL WHENEVER SQLWARNING SQLPRINT;
        }
        ...
        EXEC SQL SELECT ...;
        ...
    }

    /*
     * WRONG
     */
    int main(int argc, char *argv[])
    {
        ...
        set_error_handler();
        ...
        EXEC SQL SELECT ...;
        ...
    }

    static void set_error_handler(void)
    {
        EXEC SQL WHENEVER SQLERROR STOP;
    }

### 36.8.2. sqlca

Pour une gestion plus approfondie des erreurs, l'interface SQL embarquée fournit une variable globale appelée `sqlca` (SQL communication area, ou zone de communication SQL) qui a la structure suivante :

    struct
    {
        char sqlcaid[8];
        long sqlabc;
        long sqlcode;
        struct
        {
            int sqlerrml;
            char sqlerrmc[SQLERRMC_LEN];
        } sqlerrm;
        char sqlerrp[8];
        long sqlerrd[6];
        char sqlwarn[8];
        char sqlstate[5];
    } sqlca;

(Dans un programme multi-threadé, chaque thread récupère automatiquement sa propre copie de `sqlca`. Ce fonctionnement est similaire à celui de la variable C globale `errno`.) `errno`.)

`sqlca` couvre à la fois les avertissements et les erreurs. Si plusieurs avertissements ou erreurs se produisent durant l'exécution d'un ordre, alors `sqlca` ne contiendra d'informations que sur le dernier.

Si aucune erreur ne s'est produite durant le dernier ordre SQL, `sqlca.sqlcode` vaudra 0 `sqlca.sqlstate` vaudra `"00000"`. Si un avertissement ou erreur s'est produit, alors `sqlca.sqlcode` sera négatif `sqlca.sqlstate` sera différent de `"00000"`. Une valeur positive de `sqlca.sqlcode` indique une condition sans gravité comme le fait que la dernière requête ait retourné zéro enregistrements. `sqlcode` et `sqlstate` sont deux différents schémas de code d'erreur ; les détails sont fournis plus bas.

Si le dernier ordre SQL a réussi, alors `sqlca.sqlerrd[1]` contient l'OID de la ligne traitée, si applicable, et `sqlca.sqlerrd[2]` contient le nombre d'enregistrements traités ou retournés, si applicable à la commande.

En cas d'erreur ou d'avertissement, `sqlca.sqlerrm.sqlerrmc` contiendra une chaine qui décrira une erreur. Le champ `sqlca.sqlerrm.sqlerrml` contiendra la longueur du message d'erreur qui est stocké dans `sqlca.sqlerrm.sqlerrmc` (le résultat de `strlen()`, par réellement intéressant pour un programmeur C). Notez que certains messages sont trop longs pour tenir dans le tableau de taille fixe `sqlerrmc`; ils seront tronqués.

En cas d'avertissement, `sqlca.sqlwarn[2]` est positionné à `W`. (Dans tous les autres cas, il est positionné à quelque chose de différent de `W`.) Si `sqlca.sqlwarn[1]` est positionné à `W`, alors une valeur a été tronquée quand elle a été stockée dans une variable hôte. `sqlca.sqlwarn[0]` est positionné à `W` si n'importe lequel des autres éléments est positionné pour indiquer un avertissement.

Les champs `sqlcaid`, `sqlabc`, `sqlerrp`, et les éléments restants de `sqlerrd` et `sqlwarn` ne contiennent pour le moment aucune information utile.

La structure `sqlca` n'est pas définie dans le standard SQL, mais est implémentée dans plusieurs autres systèmes de base de données. Les définitions sont similaires dans leur principe, mais si vous voulez écrire des applications portables, vous devriez étudier les différentes implémentations de façon attentive.

Voici un exemple qui combine l'utilisation de `WHENEVER` et de `sqlca`, en affichant le contenu de `sqlca` quand une erreur se produit. Cela pourrait être utile pour déboguer ou prototyper des applications, avant d'installer un gestionnaire d'erreurs plus « user-friendly ».

    EXEC SQL WHENEVER SQLERROR CALL print_sqlca();

    void
    print_sqlca()
    {
        fprintf(stderr, "==== sqlca ====\n");
        fprintf(stderr, "sqlcode: %ld\n", sqlca.sqlcode);
        fprintf(stderr, "sqlerrm.sqlerrml: %d\n", sqlca.sqlerrm.sqlerrml);
        fprintf(stderr, "sqlerrm.sqlerrmc: %s\n", sqlca.sqlerrm.sqlerrmc);
        fprintf(stderr, "sqlerrd: %ld %ld %ld %ld %ld %ld\n", sqlca.sqlerrd[0],sqlca.sqlerrd[1],sqlca.sqlerrd[2],
                                                              sqlca.sqlerrd[3],sqlca.sqlerrd[4],sqlca.sqlerrd[5]);
        fprintf(stderr, "sqlwarn: %d %d %d %d %d %d %d %d\n", sqlca.sqlwarn[0], sqlca.sqlwarn[1], sqlca.sqlwarn[2],
                                                              sqlca.sqlwarn[3], sqlca.sqlwarn[4], sqlca.sqlwarn[5],
                                                              sqlca.sqlwarn[6], sqlca.sqlwarn[7]);
        fprintf(stderr, "sqlstate: %5s\n", sqlca.sqlstate);
        fprintf(stderr, "===============\n");
    }

Le résultat pourrait ressembler à ce qui suit (ici une erreur due à un nom de table mal saisi) :

    ==== sqlca ====
    sqlcode: -400
    sqlerrm.sqlerrml: 49
    sqlerrm.sqlerrmc: relation "pg_databasep" does not exist on line 38
    sqlerrd: 0 0 0 0 0 0
    sqlwarn: 0 0 0 0 0 0 0 0
    sqlstate: 42P01
    ===============

### 36.8.3. `SQLSTATE` contre `SQLCODE`

Les champs `sqlca.sqlstate` et `sqlca.sqlcode` sont deux schémas qui fournissent des codes d'erreurs. Les deux sont dérivés du standard SQL, mais `SQLCODE` a été marqué comme déprécié dans l'édition SQL-92 du standard, et a été supprimé des éditions suivantes. Par conséquent, les nouvelles applications ont fortement intérêt à utiliser `SQLSTATE`.

`SQLSTATE` est un tableau de cinq caractères. Les cinq caractères contiennent des chiffres ou des lettres en majuscule qui représentent les codes des différentes conditions d'erreur et d'avertissement. `SQLSTATE` a un schéma hiérarchique: les deux premiers caractères indiquent la classe générique de la condition, les trois caractères suivants indiquent la sous-classe de la condition générique. Un état de succès est indiqué par le code `00000`. Les codes `SQLSTATE` sont pour la plupart définis dans le standard SQL. Le serveur PostgreSQL supporte nativement les codes d'erreur `SQLSTATE`; par conséquent, un haut niveau de cohérence entre toutes les applications peut être obtenu en utilisant ce schéma de codes d'erreur. Pour plus d'informations voyez Annexe A.

`SQLCODE`, le schéma d'erreurs déprécié, est un entier simple. Une valeur de 0 indique le succès, une valeur positive indique un succès avec des informations supplémentaires, une valeur négative indique une erreur. Le standard SQL ne définit que la valeur positive +100, qui indique que l'ordre précédent a retourné ou affecté zéro enregistrement, et aucune valeur négative spécifique. par conséquent, ce schéma ne fournit qu'une piètre portabilité et n'a pas de hiérarchie de code d'erreurs. Historiquement, le processeur de SQL embarqué de PostgreSQL a assigné des valeurs spécifiques de `SQLCODE` pour son utilisation propre, qui sont listées ci-dessous avec leur valeur numérique et leur nom symbolique. Rappelez vous qu'ils ne sont pas portables vers d'autres implémentations SQL. Pour simplifier le portage des applications vers le schéma `SQLSTATE`, les valeurs `SQLSTATE` sont aussi listées. Il n'y a pas, toutefois, de correspondance un à un ou un à plusieurs entre les deux schémas (c'est en fait du plusieurs à plusieurs), vous devriez donc consulter la liste globale `SQLSTATE` dans Annexe A au cas par cas.

Voici les valeurs de `SQLCODE` assignées :

0 (`ECPG_NO_ERROR`)

  Indique pas d'erreur. (SQLSTATE 00000)

100 (`ECPG_NOT_FOUND`)

  C'est un état sans danger indiquant que la dernière commande a récupéré ou traité zéro enregistrements, ou que vous êtes au bout du curseur. (SQLSTATE 02000)

  Quand vous bouclez sur un curseur, vous pourriez utiliser ce code comme façon de détecter quand arrêter la boucle, comme ceci:

      while (1)
      {
          EXEC SQL FETCH ... ;
          if (sqlca.sqlcode == ECPG_NOT_FOUND)
              break;
      }

  Mais `WHENEVER NOT FOUND DO BREAK` fait en fait cela en interne, il n'y a donc habituellement aucun avantage à écrire ceci de façon explicite.

-12 (`ECPG_OUT_OF_MEMORY`)

  Indique que votre mémoire virtuelle est épuisée. La valeur numérique est définie comme `-ENOMEM`. (SQLSTATE YE001)

-200 (`ECPG_UNSUPPORTED`)

  Indique que le préprocesseur a généré quelque chose que la librairie ne connait pas. Peut-être êtes vous en train d'utiliser des versions incompatibles du préprocesseur et de la librairie. (SQLSTATE YE002)

-201 (`ECPG_TOO_MANY_ARGUMENTS`)

  Cela signifie que la commande a spécifié plus de variables hôte que la commande n'en attendait. (SQLSTATE 07001 or 07002)

-202 (`ECPG_TOO_FEW_ARGUMENTS`)

  Cela signifie que la commande a spécifié moins de variables hôtes que la commande n'en attendait. (SQLSTATE 07001 or 07002)

-203 (`ECPG_TOO_MANY_MATCHES`)

  Cela signifie que la requête a retourné pluiseurs enregistrements mais que l'ordre n'était capable d'en recevoir qu'un (par exemple parce que les variables spécifiées ne sont pas des tableaux. (SQLSTATE 21000)

-204 (`ECPG_INT_FORMAT`)

  La variable hôte est du type `int` et la donnée dans la base de données est d'un type différent et contient une valeur qui ne peut pas être interprétée comme un `int`. La librairie utilise `strtol()` pour cette conversion. (SQLSTATE 42804).

-205 (`ECPG_UINT_FORMAT`)

  La variable hôte est du type `unsigned int` et la donnée dans la base de données est d'un type différent et contient une valeur qui ne peut pas être interprétée comme un `unsigned int`. La librairie utilise `strtoul()` pour cette conversion. (SQLSTATE 42804).

-206 (`ECPG_FLOAT_FORMAT`)

  La variable hôte est du type `float` et la donnée dans la base de données est d'un type différent et contient une valeur qui ne peut pas être interprétée comme un `float`. La librairie utilise `strtod()` pour cette conversion. (SQLSTATE 42804).

-207 (`ECPG_NUMERIC_FORMAT`)

  La variable hôte est du type `numeric` et la donnée dans la base de données est d'un type différent et contient une valeur qui ne peut pas être interprétée comme un `numeric`. (SQLSTATE 42804).

-208 (`ECPG_INTERVAL_FORMAT`)

  La variable hôte est du type `interval` et la donnée dans la base de données est d'un type différent et contient une valeur qui ne peut pas être interprétée comme un `interval`. (SQLSTATE 42804).

-209 (`ECPG_DATE_FORMAT`)

  La variable hôte est du type `date` et la donnée dans la base de données est d'un type différent et contient une valeur qui ne peut pas être interprétée comme un `date`. (SQLSTATE 42804).

-210 (`ECPG_TIMESTAMP_FORMAT`)

  La variable hôte est du type `timestamp` et la donnée dans la base de données est d'un type différent et contient une valeur qui ne peut pas être interprétée comme un `timestamp`. (SQLSTATE 42804).

-211 (`ECPG_CONVERT_BOOL`)

  Cela signifie que la variable hôte est de type `bool` et que la donnée dans la base n'est ni `'t'` ni `'f'`. (SQLSTATE 42804)

-212 (`ECPG_EMPTY`)

  L'ordre envoyé au serveur PostgreSQL était vide. (Cela ne peut normalement pas arriver dans un programme SQL embarqué, cela pourrait donc laisser supposer une erreur interne.) (SQLSTATE YE002)

-213 (`ECPG_MISSING_INDICATOR`)

  Une valeur null a été retournée et aucune variable d'indicateur null n'a été fournie. (SQLSTATE 22002)

-214 (`ECPG_NO_ARRAY`)

  Une variable ordinaire a été utilisée à un endroit qui nécessite un tableau. (SQLSTATE 42804)

-215 (`ECPG_DATA_NOT_ARRAY`)

  La base a retourné une variable ordinaire à un endroir qui nécessite une variable de tableau. (SQLSTATE 42804)

-216 (`ECPG_ARRAY_INSERT`)

  La valeur n'a pas pu être insérée dans le tableau. (SQLSTATE 42804)

-220 (`ECPG_NO_CONN`)

  Le programme a essayé d'utiliser une connexion qui n'existe pas. (SQLSTATE 08003)

-221 (`ECPG_NOT_CONN`)

  Le programme a essayé d'utiliser une connexion qui existe mais n'est pas ouverte. (C'est une erreur interne.) (SQLSTATE YE002)

-230 (`ECPG_INVALID_STMT`)

  L'ordre que vous essayez d'exécuter n'a pas été préparé. (SQLSTATE 26000)

-239 (`ECPG_INFORMIX_DUPLICATE_KEY`)

  Erreur de clé en doublon, violation de contrainte unique (mode de compatibilité Informix). (SQLSTATE 23505)

-240 (`ECPG_UNKNOWN_DESCRIPTOR`)

  Le descripteur spécifié n'a pas été trouvé. L'ordre que vous essayez d'utiliser n'a pas été préparé. (SQLSTATE 33000)

-241 (`ECPG_INVALID_DESCRIPTOR_INDEX`)

  L'index de descripteur spécifié était hors de portée. (SQLSTATE 07009)

-242 (`ECPG_UNKNOWN_DESCRIPTOR_ITEM`)

  Un objet de descripteur invalide a été demandé. (C'est une erreur interne.) (SQLSTATE YE002)

-243 (`ECPG_VAR_NOT_NUMERIC`)

  Durant l'exécution d'un ordre dynamique, la base a retourné une valeur numeric et la variable hôte n'était pas numeric. (SQLSTATE 07006)

-244 (`ECPG_VAR_NOT_CHAR`)

  Durant l'exécution d'un ordre dynamique, la base a retourné une valeur non numeric et la variable hôte était numeric. (SQLSTATE 07006)

-284 (`ECPG_INFORMIX_SUBSELECT_NOT_ONE`)

  Un résultat de la sous-requête n'était pas un enregistrement seul (mode de compatibilité Informix). (SQLSTATE 21000)

-400 (`ECPG_PGSQL`)

  Une erreur causée par le serveur PostgreSQL. Le message contient le message d'erreur du serveur PostgreSQL.

-401 (`ECPG_TRANS`)

  Le serveur PostgreSQL a signalé que nous ne pouvons pas démarrer, valider ou annuler la transaction. (SQLSTATE 08007)

-402 (`ECPG_CONNECT`)

  La tentative de connexion à la base n'a pas réussi. (SQLSTATE 08001)

-403 (`ECPG_DUPLICATE_KEY`)

  Erreur de clé dupliquée, violation d'une contrainte unique. (SQLSTATE 23505)

-404 (`ECPG_SUBSELECT_NOT_ONE`)

  Un résultat de la sous-requête n'est pas un enregistrement unique. (SQLSTATE 21000)

-602 (`ECPG_WARNING_UNKNOWN_PORTAL`)

  Un nom de curseur invalide a été spécifié. (SQLSTATE 34000)

-603 (`ECPG_WARNING_IN_TRANSACTION`)

  Transaction en cours. (SQLSTATE 25001)

-604 (`ECPG_WARNING_NO_TRANSACTION`)

  Il n'y a pas de transaction active (en cours). (SQLSTATE 25P01)

-605 (`ECPG_WARNING_PORTAL_EXISTS`)

  Un nom de curseur existant a été spécifié. (SQLSTATE 42P03)