Logmessages - overview

Logmessages represent messages being prepared for output in a (output) logchannel. From creation on it is connected to a (primary) logchannel; if you don’t give one, the default channel "StdLog" is used. The typical cycle looks as follows:

·      create logmessage

·      modify logmessage properties
The most important property is the property "Text" containing the actual logmessage text, and the most common operation is to append text to this property.

·      send logmessage to the logchannel -- or cancel it to prevent output

A logmessage is sent to its logchannel(s)

·      when you call ITLogMsgSend

or, if you forgot that,

·      when you deinitialize the ITLogLib.

Logmessages are represented by HLOGMSG handles, provided or wanted by several functions.

All functions concerning a special logmessage are prefixed with ITLogMsg and receive a HLOGMSG handle at its first parameter.

Creating logmessages

These are the ways to create a logmessage:

·      using one of the ITLogMsgCreate methods

·      using one of the ITOutputLogChannelCreateLogMsg method

To create the object, besides the logchannel name you give the name of the Module and the name of the Case under which to message is to be logged. These names are displayed in the ITLogBook application and can be used there to define display filters.

Module and Case are also be used as the basis for the write-out filter mechanism. This mechanism allows you to suppress the output of certain logmessages. Write-out filters are defined on a per-log-channel basis. They are stored in the configuration file and can be modified at run-time.

Besides the logchannel, the Module and the Case at logmessage creation time you can also set the initial Loglevel. The meaning of the loglevel is explained in ITLogLevel enum and its connection to the log level of a log message.

The logmessage also automatically gets a time-stamp, which can be queried using ITLogMsgGetTimeAsString().

To summarize, the properties of the logmessage set at creating time are (in the order as displayed in the ITLogBook application):

·      logchannel

·      loglevel

·      time stamp

·      Module and Case name

·      logmessage text: set to "".

Modifying logmessages

The properties that can still be modified after the creation of the logmessage object are

·      the loglevel
Use ITLogMsgSetLogLevel() and ITLogMsgAddLogLevel() to modify it and ITLogMsgGetLogLevel() to query it.

and

·      the logmessage text.
Use the ITLogMsgAddText functions to add text to it and ITLogMsgGetText() to get the current text.

Sending or canceling logmessages

This is done calling ITLogMsgSend() or ITLogMsgCancel().