ClapLog - Utilisation

Le composant propose deux séries de fonctions :

• les surcharges de fonctions standard
• les fonctions de mesure de temps d'exécution

Initialiser les fonctions de Log

Pour pouvoir utiliser correctement le composant, il est nécessaire non seulement d'initialiser le composant (avec bComposantInit) mais aussi d'initialiser les fonctions de Log. Pour cela, utiliser, avant tout appel, la fonction bLogInit(). Elle permet, notamment, de donner le nom du répertoire final où sera mis le fichier de Log (alimenté par les fonctions ci-dessous).

Il est également possible de préciser, dans cette fonction, des informations relatives à un serveur SMTP de sorte à ce que le développeur soit prévenu en cas d'erreur (par exemple : si le fichier de Log ne peut être déplacé vers son répertoire de destination). Le développeur peut alors corriger le programme et/ou aller chercher les fichiers de Log sur le poste de l'utilisateur. Ainsi, rien n'est oublié quand on veut faire une analyse exhaustive des Logs. Dans le cas où le nom du serveur reste vide, aucun courriel ne peut évidemment être envoyé par le composant.

Les surcharges des fonctions standard

Comme précisé dans le texte d'introduction de ce composant, ce dernier va surcharger une série de fonctions standard pour loguer les impressions. Les liens proposés ouvrent la documentation de PC SOFT. En effet, la surcharge ne fait qu'intercepter l'appel mais lance, à la fin, la fonction standard. Le comportement de ces fonctions ne change donc pas par rapport aux fonctions standard :

• iImprimeEtat
• iFinImprime

Les fonctions de mesure de temps d'exécution

Il est aussi possible d'utiliser des fonctions permettant de personnaliser l'appel (par exemple en début et fin d'une procédure, d'une boucle, ...). Pour cela, il suffit d'appeler la fonction LogDébut(). Cette fonction renvoie un identifiant unique qui devra être réutilisé dans la fonction LogFin(). Pour placer une mesure intermédiaire, il suffit d'utiliser LogÉtape() avec le même identifiant.

Ces trois fonctions utilisent la fonction standard Chrono (ChronoDébut, ChronoFin et ChronoValeur. Pour éviter de perturber le fonctionnement normal de votre logiciel (car les numéros de chrono sont globaux au projet), les numéros de chronomètre utilisés dans ce composant commencent à 1.000.000 . Par contre, dans le fichier de Log, le numéro de chronomètre aura sa valeur normale (1, 2, 3, ...). Exemple : en utilisant LogDébut(), la fonction renvoie l'entier "1". Il faut ensuite utiliser la fonction LogFin(1). A l'intérieur du composant, le numéro de compteur qui sera géré, dans ce cas, sera le 1000001. Vous pouvez donc, si nécessaire, accéder à ce chronomètre dans votre programmation (en dehors des fonctions livrées dans ce composant) pour connaître la valeur du chronomètre en temps réel. Il est par contre déconseillé de faire un ChronoFin sur ce chrono : vous perdriez le bénéfice de ce composant ! Il est également déconseillé d'utiliser un ChronoDébut avec une valeur de plus de 1.000.000 car il est possible que le composant réutilise ce chrono et son utilisation ultérieure vous donnera une valeur fausse.

Le fichier de sortie

Le fichier de sortie est alimenté soit par les fonctions surchargées, soit par LogFin. En effet, les instructions LogDébut et LogÉtape mémorisent des informations qui seront ensuite utilisées dans LogFin.

Le fichier de sortie est un fichier texte avec séparateur point-virgule (CSV). Sa structure est la suivante :

• En utilisant les fonctions LogDébut,LogÉtape et LogFin : ID;DateEtHeureCouranteAuMomentDeLappel;DuréeDuProcessus;CodeAppelant:NoLigne;MessagePersonnalisé
• Pour l'ouverture et la fermeture des fenêtres : ID;DateEtHeureCouranteAuMomentDeLappel;DuréeDuProcessus;TypeDAppel;NomDeFenêtre

Le ID correspond à la séquence d'appel (soit d'une fenêtre, soit d'un état, soit d'un appel personnalisé) dans le programme depuis bLogInit().

Le MessagePersonnalisé est du texte que l'on peut mettre en paramètre de la fonction LogArrête() pour identifier le processus dans lequel il est appelé. Ce message ne peut pas comporter de TAB, de RC et de point-virgule ( ; ).

Le NomDeFenêtre peut contenir le nom de l'alias le cas échéant. Dans ce cas, il apparaîtra tel que NomDeFenêtre = NomAlias.

Le TypeDAppel contient soit "Fenêtre ouverte" soit "Fenêtre fermée".

Le CodeAppelant est le résultat de dbgInfo(dbgElément,dbgTraitementAppelant)+":"+dbgInfo(dbgLigne,dbgTraitementAppelant). Dans le cas où l'appel est fait par un événement (et que ces fonctions renvoient "vide"), le CodeAppelant est remplacé par "Appel par evénement".

Si un LogDébut() a été appelé sans qu'un LogFin() ne suit, le fichier de Log sera complété, tout à la fin, par les appels qui n'ont pas été arrêtés. Vous pouvez ainsi corriger votre code pour pouvoir utiliser les données de Log entièrement.

Gestion du fichier de sortie

Ce fichier de sortie est créé dans le répertoire temporaire de Windows et ensuite Zippé pour aller dans le répertoire de destination. Un fichier est créé à chaque exécution du programme qui contient le composant. Le nom du fichier Log est donc Log_NomUsager_NumProcessusDuProgramme_DateHeure. Le NomUsager est personnalisable dans l'instruction bLogInit(). S'il reste vide, la variable d'environnement "COMPUTERNAME" est utilisé. Si cette dernière est également vide, le nom "DefaultLogUser" sera utilisé. La DateHeure sont la date et l'heure d'ouverture du programme.

Pour créé physiquement le fichier de sortie et ensuite l'envoyer dans sa destination, il est nécessaire d'utiliser les fonctions suivantes :

1. Au début du projet, il faut utiliser bLogInit() et à la fin du code, utiliser LogTermine(). Par l'appel de la fonction bLogInit() au début, le composant vérifie si il n'y a pas de fichiers Log qui traînent. Si tel est le cas, le composant va tenter de les déplacer dans leur répertoire de destination. En cas d'échec, un courriel peut être envoyé (voir la fonction bLogInit() pour paramétrer le serveur de courriel).
2. À la fin du projet, la fonction LogTermine() ferme le fichier de log et tente de l'envoyer dans son répertoire de destination.

Si une compression est demandé dans la fonction bLogInit(), l'archive utilisée par ce composant s'appelle "clapLogArchive". Cette information vous est donnée pour éviter que vous utilisiez le même nom d'archive dans les fonctions ZIPxxx de votre programme WinDev.

Exemple d'utilisation

sSQL est une chaîne
sdClients est une Source de Données

sSQL = "SELECT * FROM CLIENT WHERE TypeClient=1"

nIDLog est un entier=LogDebut()

SI PAS HExécuteRequêteSQL(sdClients,sSQL) ALORS
	Info("erreur sql")
	RETOUR
FIN
HLitPremier(sdClients)
SI PAS HEnDehors(sdClients) ALORS
	TANTQUE PAS HEnDehors(sdClients)	
		TableAjouteLigne(TABLE_CLIENT,sdClients.Nom,sdClients.Prénom,sdClients.Adresse,sdClients.CodePostal,sdClients.Ville,sdClients.Pays)
		HLitSuivant(sdClients)
	FIN
SINON
	Info("Aucun client trouvé.")
FIN
HAnnuleDéclaration(sdClients)

LogFin(nIDLog)

Astuces

• Pour que la fonction LogTermine() soit exécutée, mettez-le avant une instruction FinProgramme(). En effet, si l'on met cette instruction dans la fenêtre principale et le LogTermine() en fin du projet, ce dernier n'est jamais exécuté. Dans ce cas, aucun problème mais il faut attendre que le programme soit relancé pour que le fichier de Log soit envoyé dans sa destination.

• Pour également logguer la fenêtre principale, il est nécessaire d'initialiser le log par bLogInit() dans le code d'initialisation de projet. En effet, si bLogInit() est appelé dans l'initialisation de la fenêtre principale, cette dernière est forcément déjà ouverte et le log n'aura pas "vu" cette ouverture.

Liens utiles

Les entrées/sorties du composant

Téléchargement et licence