#include <tcl.h> Tcl_AddObjErrorInfo(interp, message, length) Tcl_AddErrorInfo(interp, message) Tcl_SetObjErrorCode(interp, errorObjPtr) Tcl_SetErrorCode(interp, element, element, ... (char *) NULL) Tcl_SetErrorCodeVA(interp, argList) char * Tcl_PosixError(interp) void Tcl_LogCommandInfo(interp, script, command, commandLength)
Ces procédures sont utilisées pour manipuler deux variables globales de Tcl qui mémorisent l'information liée aux erreurs. La variable errorInfo mémorise une trace de la pile des opérations qui étaient en cours de réalisation quand une erreur est survenue. Elle est destinée à être lisible par l'utilisateur. La variable errorCode mémorise une liste de codes qui ne sont pas destinés à être lisibles par l'utilisateur mais plutôt à être utilisés par l'interpréteur. Le premier élément de la liste errorCode contient la classe de l'erreur qui est survenue (i.e. POSIX signifiera par exemple que l'erreur est survenue dans un appel système POSIX). Le reste des éléments de la liste errorCode concerne des informations additionnelles qui dépendent de la classe de l'erreur. Pour plus d'information sur les différents formats de errorCode, il convient de lire le manuel relatif au panorama de Tcl.
La variable errorInfo est construite de manière incrémentale lorsqu'une erreur intervient dans une imbrication de commandes. À chaque fois qu'un code d'erreur est transmis à Tcl_EvalObjEx (ou à Tcl_Eval, qui appelle Tcl_EvalObjEx), cette procédure appelle la fonction Tcl_AddObjErrorInfo pour ajouter un texte à errorInfo afin de décrire la commande qui était en cours d'exécution lorsque l'erreur est intervenue. Quand l'erreur sera remontée jusqu'au niveau le plus élevé de l'application, errorInfo contiendra une trace complète de ce qui était en cours d'exécution.
Il est parfois utile de placer des informations supplémentaires dans errorInfo afin d'aller au delà de ce qui est produit automatiquement par Tcl_EvalObjEx. À cette fin, l'utilisateur peut se servir de Tcl_AddObjErrorInfo : les arguments message et length décrivent une chaîne de caractères destinée à être ajoutée à errorInfo. Ainsi, la commande source appelle Tcl_AddObjErrorInfo pour mémoriser le nom du fichier qui est en cours d'interprétation ainsi que le numéro de la ligne dans laquelle est intervenue l'erreur ; pour les scripts Tcl, le nom de la procédure ainsi que le numéro de la ligne au sein de la procédure seront mémorisés, etc. Il est tout à fait judicieux d'appeler Tcl_AddObjErrorInfo au moment où l'on détecte que Tcl_EvalObjEx retourne TCL_ERROR. Lors d'un tel appel, le champ errorLine de l'interpréteur vous sera probablement d'une certaine utilité (consulter les pages de manuel relatives à Tcl_Interp pour de plus amples informations).
Tcl_AddErrorInfo est semblable à Tcl_AddObjErrorInfo. La différence tient dans la façon dont est réalisée l'initialisation de errorInfo à partir de la chaîne de caractères représentant le résultat de l'interpréteur, quand l'erreur est mémorisée pour la première fois. Cette fonction n'utilise pas le résultat de l'interpréteur comme un objet Tcl mais comme une chaîne de caractères. Ainsi, l'apparition d'un caractère nul au sein de la chaîne entraînera une perte de l'information. Cette fonction utilise aussi une chaîne de caractères au sens conventionnel du langage C dans message plutôt qu'une chaîne de longueur connue comme c'est le cas dans Tcl_AddObjErrorInfo.
La fonction Tcl_SetObjErrorCode est utilisée pour instancier la variable errorCode. errorObjPtr contient un objet « liste » construit par la fonction appelante. errorCode est instancié selon cette valeur. L'appel à Tcl_SetObjErrorCode intervient typiquement juste avant de renvoyer une erreur dans un objet « commande ». Si fonction renvoie une erreur sans pour autant appeler Tcl_SetObjErrorCode ou Tcl_SetErrorCode, l'interpréteur Tcl attribuera automatiquement la valeur NONE à errorCode.
On peut aussi utiliser la fonction Tcl_SetErrorCode pour instancier la variable errorCode. Toutefois, cette fonction prend comme argument une ou plusieurs chaînes de caractères au lieu d'un objet. Elle est cependant similaire à Tcl_SetObjErrorCode dans son comportement.
Tcl_SetErrorCodeVA est identique à Tcl_SetErrorCode si ce n'est dans le fait de prendre en argument une liste d'argument (au sens va_list du langage C) plutôt qu'un nombre variable d'arguments.
Tcl_PosixError instancie la variable errorCode après la venue d'une erreur lors d'un appel système POSIX. Cette fonction lit le contenu de la variable C errno et elle appelle Tcl_SetErrorCode pour instancier errorCode à la valeur qui convient dans le format POSIX. La fonction appelante doit avoir appelé au préalable Tcl_SetErrno pour instancier errno ; ceci est rendu nécessaire sur certaines plates-formes (i.e. Windows) au sein desquelles Tcl est lié à une application par l'intermédiaire d'une librairie partagée, où lorsque l'erreur intervient dans une extension chargée de manière dynamique. Consulter les pages de manuel relatives à Tcl_SetErrno pour plus d'information.
Tcl_PosixError renvoie un message de diagnostique lisible par l'utilisateur pour une erreur donnée (il s'agira de la même valeur que celle contenue dans le troisème champ de la structure errorCode). Il peut être commode d'inclure cette chaîne comme faisant partie du message d'erreur renvoyé à l'application par l'intermédiaire du résultat de l'interpréteur.
La fonction Tcl_LogCommandInfo est invoquée après qu'une erreur est survenue dans un interpréteur. Cette fonction ajoute à la variable errorInfo, des informations relatives aux commandes en cours d'exécution lors de l'apparition d'une erreur. Elle instancie également le numéro de ligne enregistré de manière interne par l'interpréteur. Lors du premier appel à Tcl_LogCommandInfo ou Tcl_AddObjErrorInfo depuis l'apparition de la dernière erreur, les anciennes informations contenues dans errorInfo sont détruites.
Il est important d'utiliser les fonctions décrites ci-avant plutôt que d'instancier errorInfo ou errorCode directement à l'aide de Tcl_ObjSetVar2. En effet, l'interpréteur Tcl garde une trace de l'utilisation de ces fonctions. Ainsi lors du premier emploi de Tcl_AddObjErrorInfo pour gérer une certaine erreur, la variable errorInfo (relative à une ancienne erreur) est effacée et les messages d'erreur contenus dans le résultat de l'interpréteur seront placés dans cette variable avant que la fonction n'y place message ; dans les appels ultérieurs relatifs à cette erreur, la fonction se contentera d'ajouter le nouveau message. Lorsque la fonction Tcl_SetErrorCode est appelée, celle-ci met à jour un drapeau indiquant que la variable errorCode a été instanciée ; cela autorise l'interpréteur Tcl à placer NONE dans la variable errorCode s'il reçoit une erreur sans pour autant que la fonction Tcl_SetErrorCode n'ait été appelée.
Lors d'un appel à la fonction Tcl_ResetResult, l'état associé à errorInfo et errorCode est effacé (sans pour autant modifier ces variables). Si une erreur était intervenue, l'appel à cette fonction modifierait l'état associé de manière à le rendre identique à celui associé à une absence d'erreur.