Unit implementing system log class

The EventLog unit implements the component, which is a component that can be used to send log messages to the system log (if it is available) or to a file.

Exception and string formatting support. TComponent and other classes support. Type of event TEventType determines the type of event. Depending on the system logger, the log event may end up in different places, or may be displayed in a different manner. A suitable mapping is shown for each system. In the case of Windows, the formatting of the message is done differently, and a different icon is shown for each type of message. Custom event type. Informational event Warning event Error event Debug event Type of log

TLogType determines where the log messages are written. It is the type of the property. It can have 2 values:

ltFile: This is used to write all messages to file. if no system logging mechanism exists, this is used as a fallback mechanism.
ltSystem: This is used to send all messages to the system log mechanism. Which log mechanism this is, depends on the operating system.

Use the system log Write to file Callback type to retrieve custom event codes TLogCodeEvent is the event type for the OnGetCustomEvent and OnGetCustomEventID event handlers. It should return a OS system log code for the etCustom log event or event ID type in the Code parameter. TEventLog instance that triggered the event Code to return Callback type to return custom category code TLogCategoryEvent is the event type for the event handler. It should return a OS event catagory code for the etCustom log event type in the Code parameter. TEventLog instance that triggered the event OS category code Event logging class TEventLog is a component which can be used to send messages to the system log. In case no system log exists (such as on Windows 95/98 or DOS), the messages are written to a file. Messages can be logged using the general Log call, or the specialized Warning, Error, Info or Debug calls, which have the event type predefined. Log Warning Error Info Debug Clean up TEventLog instance Destroy cleans up the TEventLog instance. It cleans any log structures that might have been set up to perform logging, by setting the Active property to False. Active Create a string representation of an event type EventTypeToString converts the event type E to a suitable string representation for logging purposes. It's mainly used when writing messages to file, as the system log usually has it's own mechanisms for displaying the various event types. String representation of E Event type to convert to string Register message file

RegisterMessageFile is used on Windows to register the file AFileName containing the formatting strings for the system messages. This should be a file containing resource strings. If AFileName is empty, the filename of the application binary is substituted.

When a message is logged to the windows system log, Windows looks for a formatting string in the file registered with this call.

There are 2 kinds of formatting strings:

Category strings these should be numbered from 1 to 4

1: Should contain the description of the etInfo event type.
2: Should contain the description of the etWarning event type.
4: Should contain the description of the etError event type.
4: Should contain the description of the etDebug event type.

None of these strings should have a string substitution placeholder.

The second type of strings are the message definitions. Their number starts at EventIDOffset (default is 1000) and each string should have 1 placeholder.

Free Pascal comes with a fclel.res resource file which contains default values for the 8 strings, in english. It can be linked in the application binary with the statement


{$R fclel.res}

This file is generated from the fclel.mc and fclel.rc files that are distributed with the Free Pascal sources.

If the strings are not registered, windows will still display the event messages, but they will not be formatted nicely.

Note that while any messages logged with the event logger are displayed in the event viewern Windows locks the file registered here. This usually means that the binary is locked.

On non-windows operating systems, this call is ignored.

If AFileName is invalid, false is returned. True if the call was succesful, False if not. Filename with messages as resource strings. Log a message to the system log.

Log sends a log message to the system log. The message is either the parameter Msg as is, or is formatted from the Fmt and Args parameters. If EventType is specified, then it is used as the message event type. If EventType is omitted, then the event type is determined from DefaultEventType.

If EventType is etCustom, then the OnGetCustomEvent, OnGetCustomEventID and OnGetCustomCategory.

The other logging calls: Info, Warning, Error and Debug use the Log call to do the actual work.

Info Warning Error Debug OnGetCustomEvent OnGetCustomEventID OnGetCustomCategory Event type to use. Complete log message Format string for Args Arguments to be formatted with Fmt Log a warning message. Warning is a utility function which logs a message with the etWarning type. The message is either the parameter Msg as is, or is formatted from the Fmt and Args parameters. Log Info Error Debug Complete warning message Formatting string for Args Arguments to format message with Log an error message to Error is a utility function which logs a message with the etError type. The message is either the parameter Msg as is, or is formatted from the Fmt and Args parameters. Log Info Warning Debug Complete error message Formatting string for Args Arguments to format message with Log a debug message Debug is a utility function which logs a message with the etDebug type. The message is either the parameter Msg as is, or is formatted from the Fmt and Args parameters. Log Info Warning Error Complete debug message Formatting string for Args Arguments to format message with Log an informational message Info is a utility function which logs a message with the etInfo type. The message is either the parameter Msg as is, or is formatted from the Fmt and Args parameters. Log Warning Error Debug Complete information message Formatting string for Args Arguments to format message with Identification string for messages Identification is used as a string identifying the source of the messages in the system log. If it is empty, the filename part of the application binary is used. Active TimeStampFormat Log type LogType is the type of the log: if it is ltSystem, then the system log is used, if it is available. If it is ltFile or there is no system log available, then the log messages are written to a file. The name for the log file is taken from the FileName property. FileName Activate the log mechanism

Active determines whether the log mechanism is active: if set to True, the component connects to the system log mechanism, or opens the log file if needed. Any attempt to log a message while the log is not active will try to set this property to True. Disconnecting from the system log or closing the log file is done by setting the Active property to False.

If the connection to the system logger fails, or the log file cannot be opened, then setting this property may result in an exception.

Log Default event type for the Log call. DefaultEventType is the event type used by the Log call if it's EventType parameter is omitted. Log File name for log file FileName is the name of the log file used to log messages if no system logger is available or the LogType is ltFile. If none is specified, then the name of the application binary is used, with the extension replaced by .log. The file is then located in the /tmp directory on unix-like systems, or in the application directory for Dos/Windows like systems. LogType Format for the timestamp string TimeStampFormat is the formatting string used to create a timestamp string when writing log messages to file. It should have a format suitable for the FormatDateTime call. If it is left empty, then yyyy-mm-dd hh:nn:ss.zzz is used. Custom log type ID CustomLogType is used in the EventTypeToString to format the custom log event type string. EventTypeToString Offset for event ID messages identifiers

EventIDOffset is the offset for the message formatting strings in the windows resource file. This property is ignored on other platforms.

The message strings in the file registered with the RegisterMessageFile call are windows resource strings. They each have a unique ID, which must be communicated to windows. In the resource file distributed by Free Pascal, the resource strings are numbered from 1000 to 1004. The actual number communicated to windows is formed by adding the ordinal value of the message's eventtype to EventIDOffset (which is by default 1000), which means that by default, the string numbers are:

1000: Custom event types
1001: Information event type
1002: Warning event type
1003: Error event type
1004: Debug event type

RegisterMessageFile Event to retrieve custom message category OnGetCustomCategory is called on the windows platform to determine the category of a custom event type. It should return an ID which will be used by windows to look up the string which describes the message category in the file containing the resource strings. OnGetCustomEventID OnGetCustomEvent Event to retrieve custom event ID OnGetCustomEventID is called on the windows platform to determine the category of a custom event type. It should return an ID which will be used by windows to look up the string which formats the message, in the file containing the resource strings. OnGetCustomCategory OnGetCustomEvent Event to retrieve custom event Code OnGetCustomEvent is called on the windows platform to determine the event code of a custom event type. It should return an ID. OnGetCustomCategory OnGetCustomEventID Exception raised on errors in the TEventLog component ELogError is the exception used in the component to indicate errors. Informational message name Warning message name Error message name Debug message name Custom message formatting string Message used to format an error when an error exception is raised. Determines whether logging errors are reported or ignored RaiseExceptionOnError determines whether an error during a logging operation will be signaled with an exception or not. If set to False, errors will be silently ignored, thus not disturbing normal operation of the program. Unregister the message file (needed on windows only) UnRegisterMessageFile can be used to unregister a message file previously registered with . This function is usable only on windows, it has no effect on other platforms. Note that windows locks the registered message file while viewing messages, so unregistering helps to avoid file locks while event viewer is open. True if the message file was successfully unregistered, false if an error occurred. Control whether output is appended to an existing file AppendContent determines what is done when the log type is ltFile and a log file already exists. If the log file already exists, then the default behaviour (AppendContent=False) is to re-create the log file when the log is activated. If AppendContent is True then output will be appended to the existing file. LogType FileName Pause the sending of log messages.

Pause temporarily suspends the sending of log messages. the various log calls will simply eat the log message and return as if the message was sent.

The sending can be resumed by calling .

Resume sending of log messages if sending was paused Resume resumes the sending of log messages if sending was paused through . Is the message sending paused ? Paused indicates whether the sending of messages is temporarily suspended or not. Setting it to True has the same effect as calling , setting it to False has the same effect as calling .