Editer un article - Informaticien.be

Editer un article

Titre
Mots Clés
Texte	'" '" 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 { [b][/b] .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 [b][/b] .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 [b][/b] .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[table][row][col]    [/col][col] .nf .. '" # DE - end display .de DE .fi[/col][/row][/table] .. '" # SO - start of list of standard options .de SO [size=18] [b]Options[/b] [/size]     .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 [size=18] [b]Nom[/b] [/size] Tcl_AddObjErrorInfo, Tcl_AddErrorInfo, Tcl_SetObjErrorCode, Tcl_SetErrorCode, Tcl_SetErrorCodeVA, Tcl_PosixError, Tcl_LogCommandInfo - gestion de l'information relative aux erreurs [size=18] [b]Résumé[/b] [/size] .nf [b]#include[/b] <tcl.h> [b]Tcl_AddObjErrorInfo[/b]([i]interp,[/i] message, length) [b]Tcl_AddErrorInfo[/b]([i]interp,[/i] message) [b]Tcl_SetObjErrorCode[/b]([i]interp,[/i] errorObjPtr) [b]Tcl_SetErrorCode[/b]([i]interp,[/i] element, element, ... [b](char[/b] ) NULL) [b]Tcl_SetErrorCodeVA[/b]([i]interp,[/i] argList) char [b]Tcl_PosixError[/b]([i]interp[/i]) void [b]Tcl_LogCommandInfo[/b]([i]interp,[/i] script, command, commandLength) [size=18] [b]Arguments[/b] [/size] .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 [b]Tcl_AddObjErrorInfo[/b], 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 [b]errorInfo[/b]. Cette chaîne de caractères peut contenir des caractères nuls à différents endroits pour peu que [i]length[/i] soit positif. Dans le cas de [b]Tcl_AddErrorInfo[/b], il s'agit d'une chaîne de caractères traditionnelle, au sens du langage C, qui sera copiée dans la variable [b]errorInfo[/b]. .AP int length in Le nombre d'octets à copier de [i]message[/i] vers la variable [b]errorInfo[/b] 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 [b]errorCode[/b] sera instanciée à la valeur associée à ce pointeur. .AP char element in Une chaîne de caractères à copier dans la variable [b]errorCode[/b]. Le dernier [i]element[/i] doit être être égal à NULL. .AP va_list argList in Une liste d'arguments qui doit avoir été créée en utilisant [b]TCL_VARARGS_START[/b], et libérée par [b]va_end[/b]. .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 [size=18] [b]Description[/b] [/size] Ces procédures sont utilisées pour manipuler deux variables globales de Tcl qui mémorisent l'information liée aux erreurs. La variable [b]errorInfo[/b] 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 [b]errorCode[/b] 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 [b]errorCode[/b] 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 [b]errorCode[/b] concerne des informations additionnelles qui dépendent de la classe de l'erreur. Pour plus d'information sur les différents formats de [b]errorCode[/b], il convient de lire le manuel relatif au panorama de Tcl. La variable [b]errorInfo[/b] 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 à [b]Tcl_EvalObjEx[/b] (ou à [b]Tcl_Eval[/b], qui appelle [b]Tcl_EvalObjEx[/b]), cette procédure appelle la fonction [b]Tcl_AddObjErrorInfo[/b] pour ajouter un texte à [b]errorInfo[/b] 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, [b]errorInfo[/b] 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 [b]errorInfo[/b] afin d'aller au delà de ce qui est produit automatiquement par [b]Tcl_EvalObjEx[/b]. À cette fin, l'utilisateur peut se servir de [b]Tcl_AddObjErrorInfo[/b] : les arguments [i]message[/i] et [i]length[/i] décrivent une chaîne de caractères destinée à être ajoutée à [b]errorInfo[/b]. Ainsi, la commande [b]source[/b] appelle [b]Tcl_AddObjErrorInfo[/b] 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 [b]Tcl_AddObjErrorInfo[/b] au moment où l'on détecte que [b]Tcl_EvalObjEx[/b] retourne [b]TCL_ERROR[/b]. Lors d'un tel appel, le champ [b]errorLine[/b] de l'interpréteur vous sera probablement d'une certaine utilité (consulter les pages de manuel relatives à [b]Tcl_Interp[/b] pour de plus amples informations). [b]Tcl_AddErrorInfo[/b] est semblable à [b]Tcl_AddObjErrorInfo[/b]. La différence tient dans la façon dont est réalisée l'initialisation de [b]errorInfo[/b] à 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 [i]message[/i] plutôt qu'une chaîne de longueur connue comme c'est le cas dans [b]Tcl_AddObjErrorInfo[/b]. La fonction [b]Tcl_SetObjErrorCode[/b] est utilisée pour instancier la variable [b]errorCode[/b]. [i]errorObjPtr[/i] contient un objet « liste » construit par la fonction appelante. [b]errorCode[/b] est instancié selon cette valeur. L'appel à [b]Tcl_SetObjErrorCode[/b] intervient typiquement juste avant de renvoyer une erreur dans un objet « commande ». Si fonction renvoie une erreur sans pour autant appeler [b]Tcl_SetObjErrorCode[/b] ou [b]Tcl_SetErrorCode[/b], l'interpréteur Tcl attribuera automatiquement la valeur [b]NONE[/b] à [b]errorCode[/b]. On peut aussi utiliser la fonction [b]Tcl_SetErrorCode[/b] pour instancier la variable [b]errorCode[/b]. Toutefois, cette fonction prend comme argument une ou plusieurs chaînes de caractères au lieu d'un objet. Elle est cependant similaire à [b]Tcl_SetObjErrorCode[/b] dans son comportement. [b]Tcl_SetErrorCodeVA[/b] est identique à [b]Tcl_SetErrorCode[/b] 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. [b]Tcl_PosixError[/b] instancie la variable [b]errorCode[/b] après la venue d'une erreur lors d'un appel système POSIX. Cette fonction lit le contenu de la variable C [b]errno[/b] et elle appelle [b]Tcl_SetErrorCode[/b] pour instancier [b]errorCode[/b] à la valeur qui convient dans le format [b]POSIX[/b]. La fonction appelante doit avoir appelé au préalable [b]Tcl_SetErrno[/b] pour instancier [b]errno[/b] ; 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 à [b]Tcl_SetErrno[/b] pour plus d'information. [b]Tcl_PosixError[/b] 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 [b]errorCode[/b]). 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 [b]Tcl_LogCommandInfo[/b] est invoquée après qu'une erreur est survenue dans un interpréteur. Cette fonction ajoute à la variable [b]errorInfo[/b], 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 à [b]Tcl_LogCommandInfo[/b] ou [b]Tcl_AddObjErrorInfo[/b] depuis l'apparition de la dernière erreur, les anciennes informations contenues dans [b]errorInfo[/b] sont détruites. Il est important d'utiliser les fonctions décrites ci-avant plutôt que d'instancier [b]errorInfo[/b] ou [b]errorCode[/b] directement à l'aide de [b]Tcl_ObjSetVar2[/b]. En effet, l'interpréteur Tcl garde une trace de l'utilisation de ces fonctions. Ainsi lors du premier emploi de [b]Tcl_AddObjErrorInfo[/b] pour gérer une certaine erreur, la variable [b]errorInfo[/b] (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 [i]message[/i] ; dans les appels ultérieurs relatifs à cette erreur, la fonction se contentera d'ajouter le nouveau [i]message[/i]. Lorsque la fonction [b]Tcl_SetErrorCode[/b] est appelée, celle-ci met à jour un drapeau indiquant que la variable [b]errorCode[/b] a été instanciée ; cela autorise l'interpréteur Tcl à placer [b]NONE[/b] dans la variable [b]errorCode[/b] s'il reçoit une erreur sans pour autant que la fonction [b]Tcl_SetErrorCode[/b] n'ait été appelée. Lors d'un appel à la fonction [b]Tcl_ResetResult[/b], l'état associé à [b]errorInfo[/b] et [b]errorCode[/b] 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. [size=18] [b]Voir aussi[/b] [/size] Tcl_DecrRefCount, Tcl_IncrRefCount, Tcl_Interp, Tcl_ResetResult, Tcl_SetErrno [size=18] [b]Mots clÉs[/b] [/size] error, object, object result, stack, trace, variable
Fichier