33.11. Gestion des erreurs

Une méthode simple de récupération des erreurs et des avertissements consiste à configurer une action spécifique à exécuter à chaque fois qu'une condition particulière survient. En général :

EXEC SQL WHENEVER condition action;

condition peut prendre une des valeurs suivantes :

action peut prendre une des valeurs suivantes :

Le standard SQL ne définit que les actions CONTINUE et GOTO (et GO TO).

L'exemple suivant est utilisable dans un programme simple. Il affiche un message lorsqu'un avertissement survient et termine le programme quand une erreur se produit :

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

L'instruction EXEC SQL WHENEVER est une directive du préprocesseur SQL, pas une instruction C. Les actions sur erreur ou avertissement qu'elle définit s'appliquent à toutes les instructions SQL embarquées qui apparaissent avant l'endroit où le gestionnaire est défini, à moins qu'une action différente n'ait été définie pour la même condition entre le premier EXEC SQL WHENEVER et l'instruction SQL qui engendre la condition, quelque soit le flux de contrôle du programme C. De ce fait, aucun des deux extraits de programme C qui suivent n'a le comportement désiré :

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

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

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

Pour une gestion plus puissante des erreurs, l'interface du SQL embarqué fournit une variable globale de nom sqlca qui a la structure suivante :

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

(Dans un programme multithreadé, chaque thread obtient automatiquement sa propre copie de sqlca. Ceci fonctionne de façon similaire à la gestion de la variable globale C standard errno.)

sqlca couvre à la fois les avertissements et les erreurs. Si plusieurs avertissements ou erreurs surviennent lors de l'exécution d'une instruction, alors sqlca ne contient que les informations relatives à la dernière.

Si aucune erreur ne survient dans la dernière instruction SQL, sqlca.sqlcode vaut 0 et sqlca.sqlstate vaut "00000". Si un avertissement ou une erreur survient, alors sqlca.sqlcode est négatif et sqlca.sqlstate est différent de "00000". Une valeur positive de sqlca.sqlcode indique une condition sans dommage, telle que « la dernière requête n'a retourné aucune ligne ». sqlcode et sqlstate sont deux schémas de code d'erreur différents ; les détails apparaissent ci-dessous.

Si la dernière instruction 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 de lignes traitées ou renvoyées, si applicable à la commande.

En cas d'erreur ou d'avertissement, sqlca.sqlerrm.sqlerrmc contient une chaîne décrivant l'erreur. Le champ sqlca.sqlerrm.sqlerrml contient la longueur du message d'erreur stocké dans sqlca.sqlerrm.sqlerrmc (le résultat de strlen(), sans réel intérêt pour un programmeur C). Certains messages sont trop longs pour entrer dans le tableau sqlerrmc de taille fixe ; ils sont alors 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 lors de son stockage dans une variable hôte. sqlca.sqlwarn[0] est positionné à W si tout autre élément est positionné pour indiquer un avertissement.

Les champs sqlcaid, sqlcabc, sqlerrp et les éléments restant de sqlerrd et sqlwarn ne contiennent actuellement aucune information utile.

La structure sqlca n'est pas définie dans le standard SQL mais elle est implantée dans plusieurs autres systèmes de bases de données SQL. Leurs définitions sont similaires dans l'esprit, mais l'écriture d'applications portables nécessite une étude attentive des autres implantations.

Les champs sqlca.sqlstate et sqlca.sqlcode sont deux schémas différents fournissant des codes d'erreur. Les deux sont dérivés du standard SQL mais SQLCODE est indiqué comme obsolète dans l'édition SQL-92 du standard et a été supprimé dans les éditions ultérieures. C'est pourquoi il est fortement recommandé que les nouvelles applications utilisent SQLSTATE dans les nouvelles applications.

SQLSTATE est un tableau de cinq caractères. Ces cinq caractères contiennent des chiffres ou des lettres en majuscules représentant les codes de différentes conditions d'erreur ou d'avertissement. SQLSTATE dispose d'un schéma hiérarchique : les deux premiers caractères indiquent la classe générale de la condition, les trois derniers caractères indiquent une sous-classe de la condition générale. Un 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'erreurs SQLSTATE ; de ce fait, un haut degré de cohérence peut être atteint en utilisant ce schéma de code d'erreur dans toutes les applications. Pour plus d'informations, voir l'Annexe A, Codes d'erreurs de PostgreSQL™.

SQLCODE, schéma obsolète de codes d'erreur, est un simple entier. Une valeur 0 indique un 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 la dernière commande n'a renvoyé ou modifié aucune ligne, et aucune valeur négative spécifique. De ce fait, ce schéma n'est que faiblement portable et ne propose pas d'affectation de code hiérarchique. Historiquement, le processeur de SQL embarqué pour PostgreSQL™ a affecté quelques valeurs à SQLCODE spécifiques pour sa propre utilisation. ces valeurs sont listées ci-dessous avec leurs valeurs numériques et leurs noms symboliques. Elles ne sont pas portables vers d'autres implantations SQL. Pour simplifier le portage d'applications vers la schéma SQLSTATE, le code SQLSTATE correspondant est également affiché. Il n'y a toutefois pas de correspondance une-à-une ou une-à-plusieurs entre les deux schémas (en fait, c'est plutôt plusieurs-à-plusieurs). Il est préférable de consulter le schéma SQLSTATE global dans l'Annexe A, Codes d'erreurs de PostgreSQL™ pour chaque cas.

Valeurs affectées à SQLCODE :