'" '" Copyright (c) 1989-1993 The Regents of the University of California. '" Copyright (c) 1994-1997 Sun Microsystems, Inc. '" '" See the file "license.terms" for information on usage and redistribution '" of this file, and for a DISCLAIMER OF ALL WARRANTIES. '" '" RCS: @(#) $Id: AddErrInfo.3,v 1.4.2.1 2000/08/07 21:29:36 hobbs Exp $ '" '" The definitions below are for supplemental macros used in Tcl/Tk '" manual entries. '" '" .AP type name in/out ?indent? '" Start paragraph describing an argument to a library procedure. '" type is type of argument (int, etc.), in/out is either "in", "out", '" or "in/out" to describe whether procedure reads or modifies arg, '" and indent is equivalent to second arg of .IP (shouldn't ever be '" needed; use .AS below instead) '" '" .AS ?type? ?name? '" Give maximum sizes of arguments for setting tab stops. Type and '" name are examples of largest possible arguments that will be passed '" to .AP later. If args are omitted, default tab stops are used. '" '" .BS '" Start box enclosure. From here until next .BE, everything will be '" enclosed in one large box. '" '" .BE '" End of box enclosure. '" '" .CS '" Begin code excerpt. '" '" .CE '" End code excerpt. '" '" .VS ?version? ?br? '" Begin vertical sidebar, for use in marking newly-changed parts '" of man pages. The first argument is ignored and used for recording '" the version when the .VS was added, so that the sidebars can be '" found and removed when they reach a certain age. If another argument '" is present, then a line break is forced before starting the sidebar. '" '" .VE '" End of vertical sidebar. '" '" .DS '" Begin an indented unfilled display. '" '" .DE '" End of indented unfilled display. '" '" .SO '" Start of list of standard options for a Tk widget. The '" options follow on successive lines, in four columns separated '" by tabs. '" '" .SE '" End of list of standard options for a Tk widget. '" '" .OP cmdName dbName dbClass '" Start of description of a specific option. cmdName gives the '" option's name as specified in the class command, dbName gives '" the option's name in the option database, and dbClass gives '" the option's class in the option database. '" '" .UL arg1 arg2 '" Print arg1 underlined, then print arg2 normally. '" '" RCS: @(#) $Id: man.macros,v 1.3 1999/04/16 00:46:35 stanton Exp $ '" '" # Set up traps and other miscellaneous stuff for Tcl/Tk man pages. .if t .wh -1.3i ^B .nr ^l n(.l .ad b '" # Start an argument description .de AP .ie !"$4"" .TP $4 .el { . ie !"$2"" .TP
()Cu . el .TP 15 .ta
()Au
()Bu .ie !"$3"" { &$1 fI$2fP ($3) .el { .ie !"$2"" { &$1 fI$2fP .el { &fI$1fP .. '" # define tabbing values for .AP .de AS .nr )A 10n .if !"$1"" .nr )A w'$1'u+3n .nr )B
()Au+15n .if !"$2"" .nr )B w'$2'u+
()Au+3n .nr )C
()Bu+w'(in/out)'u+2n .. .AS Tcl_Interp Tcl_CreateInterp in/out '" # BS - start boxed text '" # ^y = starting y location '" # ^b = 1 .de BS .mk ^y .nr ^b 1u .if n .nf .if n .ti 0 .if n l'
(.lu(ul' .if n .fi .. '" # BE - end boxed text (draw box now) .de BE .nf .ti 0 .mk ^t .ie n l'
(^lu(ul' .el { .ie !
(^b-1 { h'-1.5n'L'|
(^yu-1v'l'
(^lu+3n(ul'L'
(^tu+1v-
(^yu'l'|0u-1.5n(ul' .el } h'-1.5n'L'|
(^yu-1v'h'
(^lu+3n'L'
(^tu+1v-
(^yu'l'|0u-1.5n(ul' .fi .nr ^b 0 .. '" # VS - start vertical sidebar '" # ^Y = starting y location '" # ^v = 1 (for troff; for nroff this doesn't matter) .de VS .if !"$2"" .br .mk ^Y .ie n 'mc s12(brs0 .el .nr ^v 1u .. '" # VE - end of vertical sidebar .de VE .ie n 'mc .el { .ev 2 .nf .ti 0 .mk ^t h'|
(^lu+3n'L'|
(^Yu-1v(bv'v'
(^tu+1v-
(^Yu'h'-|
(^lu+3n' -1 .fi .ev .nr ^v 0 .. '" # Special macro to handle page bottom: finish off current '" # box/sidebar if in box/sidebar mode, then invoked standard '" # page bottom macro. .de ^B .ev 2 'ti 0 'nf .mk ^t .if
(^b { .ie !
(^b-1 h'-1.5n'L'|
(^yu-1v'l'
(^lu+3n(ul'L'
(^tu+1v-
(^yu'h'|0u'c .el h'-1.5n'L'|
(^yu-1v'h'
(^lu+3n'L'
(^tu+1v-
(^yu'h'|0u'c .if
(^v { .nr ^x
(^tu+1v-
(^Yu kxh'-
xu'h'|
(^lu+3n'kyL'-
(^xu'v'
(^xu'h'|0u'c .bp 'fi .ev .if
(^b { .mk ^y .nr ^b 2 .if
(^v { .mk ^Y .. '" # DS - begin display .de DS

.nf .. '" # DE - end display .de DE .fi

.. '" # SO - start of list of standard options .de SO

Options

 
  .nf .ta 4c 8c 12c .ft B .. '" # SE - end of list of standard options .de SE .fi .ft R
 
  See the fBoptionsfR manual entry for details on the standard options. .. '" # OP - start of full description for a single option .de OP
 
  .nf .ta 4c Command-Line Name: fB$1fR Database Name: fB$2fR Database Class: fB$3fR .fi
[/col][/row][/table]
.BS

Nom

Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo - gestion de l'information relative aux erreurs

Résumé

.nf #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)

Arguments

.AS Tcl_Interp *message .AP Tcl_Interp *interp in L'interpréteur dans lequel l'information sera enregistrée. .AP char *message in En ce qui concerne Tcl_AddObjErrorInfo, cette variable pointe sur le début d'un tableau d'octets contenant une chaîne de caractères destinée à être enregistrée dans la variable errorInfo. Cette chaîne de caractères peut contenir des caractères nuls à différents endroits pour peu que length soit positif. Dans le cas de Tcl_AddErrorInfo, il s'agit d'une chaîne de caractères traditionnelle, au sens du langage C, qui sera copiée dans la variable errorInfo. .AP int length in Le nombre d'octets à copier de message vers la variable errorInfo lors de l'instanciation de cette dernière. Si ce nombre est négatif, tous les octets placés avant le premier caractère nul seront utilisés. .AP Tcl_Obj *errorObjPtr in La variable errorCode sera instanciée à la valeur associée à ce pointeur. .AP char *element in Une chaîne de caractères à copier dans la variable errorCode. Le dernier element doit être être égal à NULL. .AP va_list argList in Une liste d'arguments qui doit avoir été créée en utilisant TCL_VARARGS_START, et libérée par va_end. .AP char *script in Un pointeur sur la chaîne de caractères représentant le script dans lequel ce trouve la commande qui a provoqué l'erreur (ce pointeur doit être <= à « command »). .AP char *command in Un pointeur vers la chaîne de caractères représentant la commande génératrice d'erreur. Ce pointeur référence une position dans le script. .AP int commandLength in Le nombre d'octets de « command ». Si ce nombre est égal à -1 cela signifie qu'il faut utiliser tous les caractères jusqu'au premier caractère NULL pour obtenir la chaîne. .BE

Description


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.

Voir aussi

Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno

Mots clÉs

error, object, object result, stack, trace, variable