Initialisierung und Deinitialisierung in Konsolen-Applikationen
iTech Logging
Die Logging-Lösung der 2. Generation
ITLogLib
|
|
|
|
|
|
|
|
Initialisierung und Deinitialisierung in Konsolen-Applikationen |
|
|
|
|
|
ITLogMsg
|
|
|
|
|
|
|
|
Definition von Operatoren für die einheitliche Protokollierung eigener Klasseninstanzen (empfohlen) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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 muß 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. Dieser kann nicht explizit geschlossen werden.
Falls zusätzliche Logkanäle benötigt werden, sollten diese ebenfalls in der InitInstance()-Funktion geöffnet werden. Siehe dazu auch ITLogLib - Öffnen zusätzlicher logischer Logkanäle.
#include
<ITLogLib2.h>
BOOL
CMyApp::InitInstance()
{
// Initialize the global ITLogLib object (for evaluation
use empty LicenceKey string)
if ( !GetITLogLib().Initialize("MyApplication",
"ConfigFileName.icf", "LicenceKey"))
{
MessageBox(NULL, GetITLogLib().GetLastErrorDescription(), "Error", MB_OK);
GetITLogLib().Deinitialize();
return FALSE;
}
return TRUE;
}
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.
int
CMyApp::ExitInstance()
{
// Deinitialize the global ITLogLib object (forces
writing out buffered logmessages)
GetITLogLib().Deinitialize();
return
CWinApp::ExitInstance();
}
ITLogLib - Initialisierung und Deinitialisierung in Konsolen-Applikationen
siehe
auch:
ITLogLib
- Initialisierung in Windows-Anwendungen
ITLogLib - Deinitialisierung in Windows-Anwendungen
#include
<ITLogLib2.h>
#include <ostream.h>
// only for 'cerr'
int main(int argc, char* argv[])
{
//
Initialize the global ITLogLib object (for evaluation use empty LicenceKey
string)
if ( !GetITLogLib().Initialize("MyApplication", "MyConfigFile.icf",
"LicenceKey"))
{
cerr << "Starting without iTech Logging :-(";
cerr << "\n";
cerr << GetITLogLib().GetLastErrorDescription();
}
...
// Deinitialize the global ITLogLib object (forces
writing out buffered logmessages)
GetITLogLib().Deinitialize();
return 0;
}
ITLogLib - Öffnen zusätzlicher logischer Logkanäle
Neben dem Standard-Logkanal können weitere anwendungsspezifische logische Logkanäle geöffnet werden. Zu jedem Logkanal muß 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 innerhalb der InitInstance()-Funktion (in Windows-Anwendungen) oder der main()-Funktion (in Konsolen-Anwendungen) zu öffnen.
// Open
additional logchannel 'DeveloperLog'
if ( GetITLogLib().OpenLogChannel ("DeveloperLog") == 0 )
{
ITLogMsg LogMsg("Application", "Initialize", LEVEL_WARNING);
// StdLog
LogMsg << "Can't open logchannel 'DeveloperLog'";
LogMsg << "\n";
LogMsg << GetITLogLib().GetLastErrorDescription();
}
ITLogLib - Schließen logischer Logkanäle
Das Schließen eines logischen Logkanals sorgt dafür, daß 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
( !GetITLogLib().CloseLogChannel("DeveloperLog") )
{
QuickLog("Application",
"Deinitialize", "Can't close logchannel 'DeveloperLog'",
LEVEL_WARNING);
}
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", LEVEL_INFO,
"DeveloperLog");
ITLogMsg - Standardprotokollierung
Logmeldungen
können an beliebigen Stellen im System erzeugt, als Parameter von Funktionen
weitergereicht und innerhalb der Aufrufhierarchien ergänzt werden. Die
Logmeldungen stellen eine Reihe von Stream-Operatoren für Basistypen zur
Verfügung, die eine komfortable Erweiterung des Logmeldungs-Texts gestatten.
Darüber hinaus können auch eigene
Stream-Operatoren definiert und verwendet werden. 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.
bool bVal = false;
char cVal = 'c';
float fVal = 1.5;
int iVal = 42;
double dVal = 99.99;
char strVal[] =
"logmessage text string";
// Create the logmessage
ITLogMsg LogMsg("MyModule", "MyCase", /*optional*/
LEVEL_INFO, /*optional*/ "DeveloperLog");
// Add logmessage text
LogMsg << "bool: " << bVal << " char: " << cVal;
LogMsg << " float: " << fVal << " int: " << iVal << " double: " << dVal;
LogMsg << "\n" << strVal;
// Add loglevel
LogMsg.AddLogLevel(LEVEL_ERROR);
// LogMsg will be sent automatically to its logchannel
when destructor is called
ITLogMsg - Definition von Operatoren für die einheitliche Protokollierung eigener Klasseninstanzen
Die Definition von Stream-Operatoren dient der komfortablen und vor allem einheitlichen Protokollierung von Objekten einer Klasse. Die Einheitlichkeit der Protokollmeldungen vereinfacht die spätere Definition von Filtern innerhalb der Analysen im ITLogBook.
// Define an operator for easy and homogenous logging
ITLogMsg& operator<< (ITLogMsg&
LogMsg, CMyClass& MyObj)
{
LogMsg << "Color=" << MyObj.GetColor();
LogMsg << " (Index=" << MyObj.GetIndex()
<< ")";
return LogMsg;
}
// Use the userdefined operator
CMyClass MyObj("RED", 1);
ITLogMsg LogMsg("MyModule", "MyCase");
LogMsg << MyObj;
LogMsg.Send();
ITLogMsg - Protokollierung in einen variablen Logkanal
Logmeldungen können direkt an einem Logkanal-Objekt erzeugt werden.
// Logging to variable logchannel
void LogState (ITOutputLogChannel& LogChannel)
{
ITLogMsg LogMsg = LogChannel.CreateLogMsg("Statistics",
"State");
LogMsg << "State=" << 42;
}
//
Call the function
ITOutputLogChannel* pLogChannel =
GetITLogLib().GetLogChannel("DeveloperLog");
if ( pLogChannel != 0 )
{
LogState(*pLogChannel);
}
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.
// Conditional creation of logmessages
ITLogMsg ErrorLogMsg;
// The ITLogMsg interface can be used at this
stage, but changes to ErrorLogMsg will be ignored.
if ( !CheckState() )
{
ErrorLogMsg.Create("Statistics",
"State", LEVEL_ERROR);
ErrorLogMsg << "Check failed ";
}
// ErrorLogMsg will only be sent, if above
CheckState function failed.
ErrorLogMsg.Send();
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.
// Explicite sending of logmessages
ITLogMsg LogMsg("Statistics", "State");
if ( !CheckState() )
{
LogMsg << "Check failed";
LogMsg.AddLogLevel(LEVEL_ERROR);
LogMsg.Send();
}
// Additional changes to LogMsg will be
ignored, if above CheckState function failed.
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.
// Cancelling Logmessages
ITLogMsg LogMsg("Statistics", "State");
if ( CheckState() )
{
LogMsg.Cancel();
}
// Additional changes to LogMsg will be
ignored, if above CheckState function failed.
ITLogMsg - Laufzeitoptimierung bei aktivierter Ausgabe-Filterung
Die Ausführung laufzeitintensiver Protokollierungsfunktionen kann durch Verwendung des IF_LOG Makros verhindert werden, z.B. wenn die Logmeldung aufgrund der Konfiguration ohnehin herausgefiltert wird (WriteOut-Filter). Gleiches gilt bei erfolgter Unterdrückung der Ausgabe durch LogMsg.Cancel() oder bei bereits versendeten Logmeldungen nach Aufruf von LogMsg.Send().
Bemerkung: Das Makro IF_LOG muß mit END_LOG abgeschlossen werden, ELSE_LOG ist optional.
// Using the IF_LOG macro
ITLogMsg LogMsg("Statistics", "ObjectDump");
IF_LOG (LogMsg)
{
LogMsg << MyObject.FullDump(); //
expensive function
}
ELSE_LOG
{
...
}
END_LOG
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 muß 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. Das wiederum ist abhängig von der WriteOut-Period und dem WriteOut-Filter des entsprechenden Logkanals in der Konfigurationsdatei.
#include <windows.h>
#include <ostream.h>
// only for 'cerr'
//
Open ITLogBook with current logfile
ITOutputLogChannel* pLogChannel = GetITLogLib().GetLogChannel("DeveloperLog");
if ( pLogChannel == 0 )
{
cerr << "Can't open
ITLogBook - Logchannel 'DeveloperLog' not open";
}
else if (pLogChannel->GetCurrentLogFile()
== 0)
{
cerr << "Can't open
ITLogBook - Logchannel 'DeveloperLog'
still empty";
}
else
{
ShellExecute(0, "open", pLogChannel->GetCurrentLogFile(), 0, 0, SW_SHOWNORMAL);
}
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 muß iTech Logging auf dem Zielsystem installiert oder zumindest die Dateiendung "icf" mit ITConfigManager verknüpft worden sein.)
#include <windows.h>
//
Open ITConfigManager with application's current configfile
if ( GetITLogLib().IsInitialized() )
{
ShellExecute(0, "open", GetITLogLib().GetConfigFile(), 0, 0, SW_SHOWNORMAL);
}
Copyright © 1999 - 2004 iTech Software GmbH