iTech Logging                        Source Code Snippets

      The 2nd generation logging solution

Source code snippets for iTech Logging  (Borland Delphi)

ITLogLib

 

	Initializing your Windows application
	Deinitializing your Windows application
	Initializing and deinitializing your console application
	Opening an additional logical output channel
	Closing a logical output channel

ITLogMsg

 

	The simplest way to protocol
	The standard way to protocol
	Writing to a variable output channel
	Conditional creation of logmessages
	Explicit sending of logmessages
	Explicit cancelling of logmessages
	Optimizing performance with active output filters

Service functions

 

	Opening ITLogBook out of your application with current logfiles
	Opening ITConfigManager out of your application with the current configuration file

ITLogLib - Initializing your Windows application

ITLogLib must be initialized with a configuration file. This file can be created and edited by ITConfigManager, a special editor shipped with iTech Logging. The parameter application name is user-defined and identifies your application. Initialization fails if the configuration file could not be found.

After successful initialization the standard output channel StdLog is opened and ready to receive logmessages. Additional output channels should be opened afterwards. See ITLogLib - Opening an additional logical output channel.

  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, 'ITLogLib init error');
      exit;
    end;
  end;

back

ITLogLib - Deinitializing your Windows application

Before your application exits, ITLogLib should be deinitialized in order to write out all buffered logmessages and close all opened  output channels.

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

back

ITLogLib - Initializing and deinitializing your console application

Using the Delphi IDE you can create console applications by choosing "File \ New \ Other \ Console Application".

Delphi console apps should catch all exceptions in the main block, because in the case of uncaught exceptions Windows will display the unpopular dialog which says that the application has crashed.

See also:

   ITLogLib - Initializing your Windows application

   ITLogLib - Deinitializing your Windows application

  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 - Opening an additional logical output channel

Besides the standard output channel StdLog additional application specific logical output channels can be opened. For each output channel an appropriate set of configuration parameters must exist in the configuration file, otherwise OpenLogChannel() fails. Use ITConfigManager to create or edit the parameter set. (See also:  ITLogLib - Initializing your Windows application). We recommend you to open all required output channels at the start of your application.

  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 - Closing a logical output channel

Closing a logical output channel forces writing out its buffered logmessages. If you deinitialize ITLogLib, all opened output channels will be closed automatically.

  { close additional logchannel 'DeveloperLog' }

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

back

ITLogMsg - The simplest way to protocol

The easiest way to protocol is using the function QuickLog().

  { 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 - The standard way to protocol

ITLogMsg instances can be created anywhere in your application code and passed as parameters to subsequent functions calls. ITLogMsg instances provide Add() procedures for various base types, which allow a comfortable extension of their logmessage texts. The loglevel (info, warning, error and alarm) can be supplemented during the life cycle of a logmessage as well.

A logmessage will be sent automatically to its output channel(s), as far as you didn’t explicitly send it or suppress its output before.

  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 - Writing to a variable output channel

You can create logmessages dynamically using the CreateLogMsg() function of its output channel.

  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 - Conditional creation of logmessages

As soon as a logmessage variable is declared, the complete ITLogMsg interface can be used, without producing runtime errors. Subsequent calls to its interface functions simply will be ignored as long as the object is not created. Thus you have the possibility of conditional creation of logmessages.

  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 - Explicit sending of logmessages

Logmessages can be sent explicitly, e.g. depending on a condition within your program code. Subsequent calls to its interface don’t result in a runtime error but will simply be ignored. 

  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 - Explicit cancelling of logmessages

Logmessages can be suppressed explicitly, e.g. depending on a condition within your program code. Subsequent calls to its interface don’t result in a runtime error but will simply be ignored.

  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 - Optimizing performance with active output filters

Using the property WillBeLogged avoids expensive calls to protocol functions if the logmessage will not be written out later, e.g. if you did set up an appropriate write-out filter, or did explicitly cancel (LogMsg.Cancel) or send (LogMsg.Send) the logmessage before. (‘Expensive’ means collecting lots of information and append it to the logmessage text.)

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

back

Service function - Opening ITLogBook out of your application with current logfiles

You may define a (hidden) button in your applications interface, that opens ITLogBook with the current logfile of a given output channel, thus your developer or end user always have comfortable access to the most recent log information. (Therefore iTech logging must be set up on the target system, in order to attach the “ilf” file extension to the ITLogBook application.

  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 function - Opening ITConfigManager out of your application with the current configuration file

You may define a (hidden) button in your applications interface, that opens ITConfigManager with the current configuration file, thus your developer or end user always have comfortable access to the current parameters, defining the output behavior. (Therefore iTech Logging must be set up on the target system, in order to attach the “icf” file extension to the ITConfigManager application.

  if mITLogLib.IsInitialized then begin

    OpenDoc(mITLogLib.Configfile);

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

back

Copyright © 1999 - 2004  iTech Software GmbH