Quellcode-Schnippsel für iTech Logging  (Borland Delphi)

ITLogLib

	Initialisierung in Windows-Anwendungen
	Deinitialisierung in Windows-Anwendungen
	Initialisierung und Deinitialisierung in Konsolen-Anwendungen
	Öffnen zusätzlicher logischer Logkanäle
	Schließen logischer Logkanäle

ITLogMsg

	Die einfachste Art der Protokollierung
	Standardprotokollierung
	Protokollierung in einen variablen Logkanal
	Bedingtes Erzeugen von Logmeldungen
	Explizites Senden von Logmeldungen
	Explizite Unterdrückung von Logmeldungen
	Laufzeitoptimierung bei aktivierter Ausgabe-Filterung

Service-Funktionen

	Öffnen von ITLogBook aus Ihrer Anwendung heraus mit dem aktuellen Log
	Öffnen von ITConfigManager aus Ihrer Anwendung heraus mit der aktuellen Konfigurationsdatei

ITLogLib – Initialisierung in Windows-Anwendungen

Für die Initialisierung der iTech LogLib muss eine Konfigurationsdatei angegeben werden. Diese kann mit dem zum Lieferumfang von iTech Logging gehörenden ITConfigManager angelegt und bearbeitet werden. Der Anwendungsname kann frei gewählt werden. Die Initialisierung schlägt fehl, wenn die Konfigurationsdatei nicht existiert oder fehlerhafte Einträge enthält.

Nach erfolgreicher Initialisierung steht der Standard-Logkanal StdLog zur Verfügung. Falls zusätzliche Logkanäle benötigt werden, sollten diese anschließend geöffnet werden. Siehe dazu auch ITLogLib - Öffnen zusätzlicher logischer Logkanäle.

  uses ITLogLib2 {ITLogLib2/Delphi};

  var mITLogLib: ITLogLib;

  procedure TMainForm.FormCreate(Sender: TObject);
  begin
    mITLogLib:= ITLogLib.Create();
  end;
 

  procedure TMainForm.btnInitLogLibClick(Sender: TObject);
  begin
    if not mITLogLib.Initialize('MyApplication', 'ConfigFileName.icf', 'LicenceKey')
    then begin
      Application.MessageBox(mITLogLib.LastErrorDescription, 'Error');
      exit;
    end;
  end;

back

ITLogLib – Deinitialisierung in Windows-Anwendungen

Die Deinitialisierung der iTech LogLib sorgt für die Ausgabe aller gepufferten Logmeldungen der verschiedenen Logkanäle, das Schließen aller logischer Logkanäle und die Freigabe des benutzten Speichers.

  procedure TMainForm.FormClose(Sender: TObject; var Action: TCloseAction);
  begin
    if mITLogLib<>nil then begin
      mITLogLib.Deinitialize();
      mITLogLib.Free;
    end;
  end;

back

ITLogLib – Initialisierung und Deinitialisierung in Konsolen-Anwendungen

Innerhalb der Delphi-IDE kann man Konsolen-Anwendungen über "File \ New \ Other \ Console Application" anlegen.

Delphi-Konsolen-Anwendungen sollten im Hauptprogrammblock alle Exceptions abfangen, weil nicht abgefangene Exceptions dazu führen, dass die Anwendung aus Sicht von Windows abgestürzt ist, was zur Anzeige des entsprechenden unbeliebten Dialogs von Windows führt.

Siehe auch:

   ITLogLib - Initialisierung in Windows-Anwendungen

   ITLogLib – Deinitialisierung in Windows-Anwendungen

  program LoggingTestConsoleApp;

  {$APPTYPE CONSOLE}
 

  uses SysUtils, ITLogLib2 {ITLogLib2/Delphi};

  var mITLogLib: ITLogLib;

  var b: WordBool;
  begin

    try   { try-block for deinitialization }
      try   { try-block to prevent GPF faults }
        mITLogLib:= ITLogLib.Create();

        b:= mITLogLib.Initialize('MyApplication', 'ConfigFileName.icf', 'LicenceKey');
        if not b then begin
          writeln('ITLogLib init error: ' + mITLogLib.LastErrorDescription);
          exit;
        end;

        QuickLog('LoggingDemo', 'Initialize', 'Hello, world!');

     
        { ... other application code here ... }

      except
        WriteLn('exception occurred');
      end;

    finally
      { Deinitialize the global ITLogLib object (forces writing out

        buffered logmessages) }

      mITLogLib.Deinitialize();
      mITLogLib.Free;
    end;

  end.

back

ITLogLib – Öffnen zusätzlicher logischer Logkanäle

Neben dem Standard-Logkanal können weitere anwendungsspezifische logische Logkanäle geöffnet werden. Zu jedem Logkanal muss ein Eintrag in der Konfigurationsdatei angelegt werden. Andernfalls kann das Öffnen des Logkanals fehlschlagen (siehe auch  ITLogLib - Initialisierung in Windows-Anwendungen). Es wird empfohlen, alle benötigten Logkanäle bei Start der Anwendung zu öffnen.

  var
    c: ITOutputLogChannel;
 

  begin

    { open additional logchannel 'DeveloperLog' }

    c:= mITLogLib.OpenLogChannel('DeveloperLog');
    if c=nil then begin

      QuickLog('Application', 'Initialize', 'Cannot open logchannel ''DeveloperLog''!');
    end;

  end;

back

ITLogLib – Schließen logischer Logkanäle

Das Schließen eines logischen Logkanals sorgt dafür, dass alle seine gepufferten Logmeldungen ausgegeben werden. Beim Deinitialisieren der ITLogLib werden alle geöffneten Logkanäle automatisch geschlossen.

Der Standard-Logkanal 'StdLog' kann nicht explizit geschlossen werden.

  { close additional logchannel 'DeveloperLog' }

  if not mItLogLib.CloseLogChannel('DeveloperLog') then begin
    QuickLog('Application', 'Deinitialize',
      'Cannot close logchannel ''DeveloperLog''', LEVEL_WARNING);
  end;

back

ITLogMsg – Die einfachste Art der Protokollierung

Die einfachste Art der Protokollierung ist QuickLog. Quicklog kann benutzt werden, wenn der Logmeldungstext bereits vollständig als String vorliegt.

  { Use default loglevel (LEVEL_INFO) and standard logchannel (StdLog) }

  QuickLog('Application', 'Initialize', 'Program started..');

  { Use loglevel WARNING }

  QuickLog('Application', 'Deinitialize', 'Program terminated by user', LEVEL_WARNING);

  { Use logchannel 'DeveloperLog' }

  QuickLog('Application', 'Deinitialize', 'Program terminated by user', LEVEL_INFO, 'DeveloperLog');

back

ITLogMsg - Standardprotokollierung

ITLogMsg-Objekte können an beliebigen Stellen im System erzeugt, als Parameter von Funktionen weitergereicht und innerhalb der Aufrufhierarchien ergänzt werden.  Die ITLogMsg-Objekte stellen eine Reihe von Add()-Prozeduren für Basistypen zur Verfügung, die eine komfortable Erweiterung des Logmeldungs-Texts gestatten. Der Loglevel (Info, Warnung, Error und Alarm) kann ebenfalls während der Lebensdauer einer Logmeldung ergänzt werden.
ITLogMsg-Objekte versenden sich automatisch zum Zeitpunkt ihrer Zerstörung, sofern sie nicht vorher explizit gesendet oder unterdrückt wurden.

  const

    { preinitialized vars, actually }
    cVal: char= 'c';
    iVal: integer= 42;
    sngVal: single= 1.5;
    dblVal: double= 99.99;
    strVal: string= 'logmessage text string';

  var

    LogMsg: ITLogMsg;

  begin
    { create the logmessage }
    LogMsg:= ITLogMsg.Create('MyModule', 'MyCase', {optional} LEVEL_INFO, {optional} 'StdLog');

    { add logmessage text }
    with LogMsgdo begin
      Add('char: ' + cVal);
      Add(', integer: ' + IntToStr(iVal));
      Add(', single: '); Add(sngVal);
      Add(', double: '); Add(dblVal);
      Add(', string: ' + strVal);
    end;

    { add logmessage text }
    LogMsg.AddLogLevel(LEVEL_ERROR);

    { free object, which will automatically sent its contents to the logfile }
    LogMsg.Free;
  end;

back

ITLogMsg – Protokollierung in einen variablen Logkanal

Logmeldungen können direkt an einem Logkanal-Objekt erzeugt werden, durch Aufruf seiner CreateLogMsg()-Methode.

  procedure LogState(LogChannel: ITOutputLogChannel);

  { logs to variable logchannel }
  var LogMsg: ITLogMsg;
  begin
    LogMsg:= LogChannel.CreateLogMsg('Statistics', 'State');
    LogMsg.Add('State= ' + IntToStr(42));
    LogMsg.Free;
  end;

  procedure TestVariableChannel;
  var LogChannel: ITOutputLogChannel;
  begin
    { call the function }
    LogChannel:= mItloglib.LogChannel('DeveloperLog');
    if LogChannel <> nil then begin
      LogState(LogChannel);
    end;
  end;

back

ITLogMsg – Bedingtes Erzeugen von Logmeldungen

Die komplette ITLogMsg-Schnittstelle kann bereits verwendet werden, wenn die Logmeldung nur deklariert, aber (noch) nicht erzeugt wurde. Dadurch besteht die Möglichkeit, Logmeldungen bedingt zu erzeugen, ohne nachfolgende Aufrufe an der Schnittstelle von dieser Bedingung abhängig machen zu müssen. Solange die Logmeldung noch nicht erzeugt wurde, werden diese Aufrufe ignoriert.

  var ErrorLogMsg: ITLogMsg;
  begin
    { Conditional creation of logmessages }
    ErrorLogMsg:= LogMsg.Create;

    { The ITLogMsg interface *can* be used at this stage,
      but changes to ErrorLogMsg will be ignored. }
    ErrorLogMsg.Add('This text will be lost.');

    if not CheckState() then begin
      ErrorLogMsg.Recreate('Statistics', 'State', LEVEL_ERROR);
      ErrorLogMsg.Add('Check failed');
    end;

    { ErrorLogMsg will in fact be sent only if above CheckState function failed. }
    ErrorLogMsg.Free;
  end;

back

ITLogMsg – Explizites Senden von Logmeldungen

Logmeldungen können innerhalb des Programmkodes zum Beispiel aufgrund einer Bedingung kontrolliert abgesendet werden. Nachfolgende Aufrufe an der ITLogMsg-Schnittstelle sind weiterhin möglich, werden aber ignoriert. 

  var LogMsg: ITLogMsg;
  begin
    { explicit sending of logmessages }
    LogMsg:= ITLogMsg.Create('Statistics', 'State');

    if not CheckState() then begin
      LogMsg.Add('Check failed');
      LogMsg.AddLogLevel(LEVEL_ERROR);
      LogMsg.Send();
    end;

    { Additional changes to LogMsg will be ignored,
      if above CheckState function failed. }
    LogMsg.Add('Text for successful case.');

    LogMsg.Free;
  end;

back

ITLogMsg – Explizite Unterdrückung von Logmeldungen

Die Ausgabe von Logmeldungen kann innerhalb des Programmkodes zum Beispiel aufgrund einer Bedingung explizit unterdrückt werde. Nachfolgende Aufrufe an der ITLogMsg-Schnittstelle sind weiterhin möglich, werden aber ignoriert. 

  var LogMsg: ITLogMsg;
  begin
    { cancelling logmessages }
    LogMsg:= ITLogMsg.Create('Statistics', 'State');
    LogMsg.Add('Some info');

    if CheckState() then begin
      LogMsg.Cancel();
    end;

    { Additional changes to LogMsg will be ignored, if the
      CheckState function above failed. }
   
    LogMsg.Free;
  end;

back

ITLogMsg – Laufzeitoptimierung bei aktivierter Ausgabe-Filterung

Durch die Nutzung bzw. Beachtung des Properties WillBeLogged, mit dem man ermitteln kann, ob die betroffene Logmeldung überhaupt ausgegeben wird, können laufzeitintensive Ausführungen von Protokollierungsfunktionen (zur Ermittlung und Ausgabe von Informationen in die Logmeldung) vermieden werden. Gründe für die Nichtausgabe einer Logmeldung sind aktive Dateiausgabefilter (Write-out Filter), das vorangegangene Aufrufen von LogMsg.Cancel sowie LogMsg.Send.

  if LogMsg.WillBeLogged then begin
    LogMsg.Add(GetFullDumpString()); { expensive function }
  end; 

back

Service-Funktion – Öffnen von ITLogBook aus Ihrer Anwendung heraus mit dem aktuellen Log

Empfehlenswert ist die Definition eines - gegebenenfalls versteckten - Buttons in Ihrer Anwendung zum direkten Öffnen von ITLogBook mit dem aktuellen Log eines Logkanals. Entwickler, Service-Mitarbeiter oder auch Endanwender haben damit immer einen schnellen Zugriff auf die neuesten Protokollmeldungen. (Dazu muss iTech Logging auf dem Zielsystem installiert oder zumindest die Dateiendung "ilf" mit ITLogBook verknüpft worden sein.)

Bemerkung: Logdateien werden erst angelegt, wenn die erste Logmeldung tatsächlich ausgegeben wird. Also am besten bei Start (wie üblich) gleich eine Ausgabe machen!

Die Verzögerung der Ausgabe ist im Detail abhängig von der WriteOut-Period (Default 1s). Weiterhin muss diese Meldung natürlich durch den WriteOut-Filter des entsprechenden Logkanals in der Konfigurationsdatei kommen.

  uses ...,ShellAPI {ShellExecute};

  procedure OpenDoc(DocPath: string);
  begin
    ShellExecute({hWnd} 0, {Operation} 'open', {Filename} PChar(DocPath),
      {Parameters} nil, {Directory} nil, SW_SHOW);
  end;

   var

    c: ITOutputLogChannel;
 

  begin
      c:= mITLogLib.LogChannel('StdLog');
      if c=nil then begin
      Application.MessageBox('LogChannel is not open.','Error');
      exit;
    end;

    OpenDoc(c.CurrentLogFile);
    { - works, of course, only on Windows systems were ITLogging is installed
        correctly, which means: The logfile extension 'ILF' is associated with
        the ITLogBook application }

  end;

back

Service-Funktion – Öffnen von ITConfigManager aus Ihrer Anwendung heraus mit der aktuellen Konfigurationsdatei

Empfehlenswert ist die Definition eines - gegebenenfalls versteckten - Buttons in Ihrer Anwendung zum direkten Öffnen von ITConfigManager mit der Konfigurationsdatei. Entwickler, Service-Mitarbeiter oder auch Endanwender haben dadurch immer einen schnellen Zugriff auf die aktuelle Konfiguration der Protokollkomponente. (Dazu muss iTech Logging auf dem Zielsystem installiert oder zumindest die Dateiendung "icf" mit ITConfigManager verknüpft worden sein.)

  if mITLogLib.IsInitialized then begin

    OpenDoc(mITLogLib.Configfile);

    { - opens ITConfigManager with application's current configfile }
  end;

back

Copyright © 1999 - 2004  iTech Software GmbH