Chapter 4. The WindowsEventLog Class

Table of Contents
Using WindowsEventLog
new (Class method)
minimumReadMin (Attribute)
minimumReadMax (Attribute)
minimumReadBuffer (Attribute)
events (Attribute)
open
close
read (deprecated)
readRecords
write
clear
minimumRead
minimumRead=
isFull
getNumber
getLogNames
getLast
getFirst

The WindowsEventLog class provides functionaliy to interact with the Windows system event log.

The WindowsEventLog class is not a built-in class. It is defined in the file winSystm.cls. To use the class, place a ::requires statement in the program file:

::requires "winSystm.cls"

A sample program eventLog.rex is provided in the samples\winsystem directory.

Methods:

The WindowsEventLog class implements the class and instance methods listed in the following table.

Table 4-1. WindowsEventLog Methods

MethodCategory
newClass method
eventsAttribute
minimumReadBufferAttribute
minimumReadMinAttribute
minimumReadMaxAttribute
clearInstance method
closeInstance method
getFirstInstance method
getLastInstance method
getLogNamesInstance method
getNumberInstance method
isFullInstance method
minimumReadInstance method
minimumRead=Instance method
openInstance method
Deprecated readDeprecated instance method
readRecordsInstance method
writeInstance method

Using WindowsEventLog

In Windows the Event Log service provides a central facility for both the operating system and applications to log important events. The primary purpose for logging an event is to give administrators a way to determine the cause of errors and to prevent future errors. The Event Log service provides several standard logs: Application, Security, and System. The service also allows for applications to register and create Custom logs. Each event is logged as a single event log record in a single log.

The ooRexx WindowsEventLog class has methods that allow the programmer to query, read from, write to, back up, and clear event logs. The class can access logs on both the local machine and on remote machines accessed through the network. Full access to any log is governed by the security settings of the system. Therefore an ooRexx program that interacts with the Event Log service will be restricted to the privilege level of the user running the program.

The Event Log service uses information stored registry. This information controls how the service operates. The following list discusses some of the event logging elements to help the programmer better understand the methods and method arguments of the WindowsEventLog class:

Eventlog key

The Eventlog key is the key in the registry where all information for the Event Log service is stored. There are several subkeys under the EventLog key. Each subkey names an event log. The following shows the structure of the Eventlog key. The Application, Security and System subkeys below name the standard logs provided by the system. The actual name(s) and the number of Custom logs are dependent on the system.

HKEY_LOCAL_MACHINE
  System
    CurrentControlSet
      Services
      EventLog
        Application
        Security
        System
        CustomLog

Server

Many of WindowsEventLog instance methods have a server argument. This argument indentifies which machine contains the desired event log. The argument is always optional, with the default server being the local machine. In all cases, using the empty string is the same as omitting the argument.

To work with a log on a remote system, the server name must be in Universal Naming Convention (UNC) format. For instance, \\Osprey.

Note that if there is an open event log, the server argument is ignored.

Event Source

The event source is the name of the software or driver that logs the event. Event source names are usually the name of the application, or a component of the application if the application is large, or the driver name. Applications normally use the Application log, while drivers normally use the System log. Event source names are stored in the registry as subkeys of the log they are used in. Take the following registry example:

HKEY_LOCAL_MACHINE
  System
    CurrentControlSet
      Services
      EventLog
        Application
          WinApp1
          LoadPerf
        Security
          Security
        System
          Dhcp
          atapi
WinApp1, LoadPerf, Security, Dhcp, and atapi are all event sources.

Like the server argument, many of the WindowsEventLog instance methods have a source argument. This argument specifies the event source and therefore determines exactly which event log is used. The argument is always optional, the default is Application, and the empty string is the same as omitting the argument. In the same manner as the server argument, if there is an open event log, the source argument is ignored.

Note that if the Event Log service can not find the event source name in the registry, then the service also uses Application for the source.

When opening, querying, or reading event logs, using an event source name is no different than using the log name itself. For the above registry example, using:

eventLog~open( , "WinApp1")
or:
eventLog~open( , "LoadPerf")
is exactly the same as:
eventLog~open( , "Application")

However, when writing to an event log, the event source is included as part of the event log record. Therefore:

eventLog~open( , "WinApp1")
produces a different result than using:
eventLog~open( , "LoadPerf")
Although both event records will be written to the System log, the records will show the event source as WinApp1 in the first record and LoadPerf for the source in the second record.

Event Log Record

Each event is stored in an event log as a single record. The information in the record includes things like: time, type, category, record number, etc.. Each record contains the same fields, although some fields, like the binary data field, are not always filled in.

Each record has a record number. The first record written to a log is number 1 and records are then written consecutively. This makes the record with the lowest record number the oldest record. Likewise the highest record number makes that record the youngest record. The user can set a property for an event log to overwrite records when the maximum log size is reached. Because of this, the oldest record is not always record number 1. The getFirst() and getLast() methods can be used to get the absolute record numbers of the oldest and youngest records.

Record numbers can be used in the readRecords() method to read portions of the event log rather than the entire log.

When the readRecords() method reads a record it converts the information in the record to a string with a defined format that makes it easy to parse. The parts (fields) of the string are as follows, in order:

Table 4-2. Event Record Fields

FieldDescriptionFormat
typeThe event typeSingle word
dateThe date the event was writtenSingle word
timeThe time the event was writtenSingle word
sourceThe The event sourceEnclosed in single quotes
idThe event IDSingle word
userIDThe user ID, if applicableSingle word
computerThe machine generating the eventSingle word
descriptionA descripiton of the eventEnclosed in single quotes
dataBinary data associated with the eventEnclosed in single quotes

Assuming that rec is the event record string, the following shows how to parse the string into its component fields:

parse var rec type date time "'" source "'" id userID computer "'" description "'" "'" data "'"
Event Type

Each event recorded in an event log is a single type. There are five types of events that can be logged. Each event type has well-defined common data and some optional data that is specific to the event. When an event is logged the event type is included.

When the WindowsEventLog instance reads a record, the event type is indicated by a keyword. When the programmer writes to the event log using a WindowsEventLog object, she specifies the event type with its numeric value. The following table contains information on the five event types and shows the event type keywords and numeric values.

Table 4-3. Event Types

TypeDescriptionKeywordValue
Error An event that indicates a significant problem such as loss of data or loss of functionality. For example, if a service fails to load during startup, an Error event is logged.Error1 (0x01)
Warning An event that is not necessarily significant, but may indicate a possible future problem. For example, when disk space is low, a Warning event is logged. If an application can recover from an event without loss of functionality or data, it can generally classify the event as a warning event.Warning2 (0x02)
Information An event that describes the successful operation of an application, driver, or service. For example, when a network driver loads successfully, it may be appropriate to log an Information event. Note that it is generally inappropriate for a desktop application to log each time it starts.Information4 (0x04)
Information* * The Windows API allows the numeric value of 0. This is not a separate event type, but rather a mapping of 0 to the Infomation event type. The WindowsEventLog also allows the use of 0 for the numeric value of an event type and maps it to Information.Information0 (0x00)
Success Audit An event that records an audited security access attempt that is successful. For example, a user's successful attempt to log on to the system is logged as a Success Audit event.Success8 (0x08)
Failure Audit An event that records an audited security access attempt that fails. For example, if a user tries to access a network drive and fails, the attempt is logged as a Failure Audit event.Failure16 (0x10)
Event ID

The event identifier value is specific to the event source for the event. It is used with source name to locate a description string in the message file for the event source.

Opened event log

When an event log has been opened using the open() method, that opened log is always used until it has been closed. The log can be closed using the close() method, or by another call to the open() method. This means that if there is an open log, the server and source arguments are always ignored. The only exception to this is the write() method. Each time a record is written to a log, the log is specifically opened for writing and then closed.

Note that when there is not an open event log, then all the instance methods behave as the write() method. That is, methods like readRecords, isFull, etc., will open the log specified in the method call and then explicitly close the log before returning.

Event Category

Categories are used to organize events so that an event viewer can filter them. Each event source can define its own numbered categories and the text strings to which they are mapped.

The categories must be numbered consecutively, beginning with the number 1. The categories themselves are defined in a message file and the category number maps to a text string in the message file.