Tcl Windows API extension

Most access to the event log requires a handle returned by the eventlog_open command. A handle allows either read or write access, but never both. Events can be written using the eventlog_write command. The eventlog_log command provides an alternate, simpler but less flexible, interface for writing events. Events can be read from an event log through the eventlog_read command. The returned event record can be formatted using eventlog_format_message and eventlog_format_category.

The command eventlog_count returns the number of records in the event log. eventlog_oldest returns the record number of the oldest record. The command eventlog_is_full indicates whether the event log is full.

To monitor the event log in real time, an application can poll at regular intervals. However, a more efficient way is to receive asynchronous notifications through eventlog_monitor_start when new events are logged. These notifications can be turned off using eventlog_monitor_stop.

Event logs can be backed up using eventlog_backup or as a side effect of clearing the log through eventlog_clear. The backup file can be read using the standard eventlog_open and eventlog_read commands.

Commands

eventlog_backup EVENTLOGHANDLE FILENAME

Backs up the specified event log to the file FILENAME. The file may be opened for reading using the eventlog_open command. EVENTLOGHANDLE must be a read handle.

eventlog_clear EVENTLOGHANDLE ?-backup FILENAME?

Clears the specified event log. If the -backup option is specified, the event log is first backed to the file FILENAME. EVENTLOGHANDLE must be a read handle (even though the command actually modifies the event log).

eventlog_close EVENTLOGHANDLE

Closes a handle previously returned by eventlog_open and frees any associated resources.

eventlog_count EVENTLOGHANDLE

Returns the number of records in the specified event log. EVENTLOGHANDLE must be a read handle.

eventlog_format_category EVENT_RECORD ?options?

Returns the text corresponding to the numeric category field in EVENT_RECORD by looking up the appropriate resources. EVENT_RECORD must be an element of the event record list returned from the eventlog_read command.

The following options may be specified with the command:

-langid LANGID	Passed to the format_message command for formatting. See the description of that function for details.
-width MAXLINEWIDTH	Passed to the format_message command for formatting. See the description of that function for details.

eventlog_format_message EVENT_RECORD ?options?

Returns the text corresponding to the message in EVENT_RECORD by looking up the appropriate resources. EVENT_RECORD must be an element of the event record list returned from the eventlog_read command.

The following options may be specified with the command:

-langid LANGID	Passed to the format_message command for formatting. See the description of that function for details.
-width MAXLINEWIDTH	Passed to the format_message command for formatting. See the description of that function for details.

eventlog_is_full EVENTLOGHANDLE

Returns 1 if the specified event log is full, and 0 otherwise. EVENTLOGHANDLE may be either a read or a write handle.

eventlog_log MESSAGE ?options?

Writes a record into the specified event log. This is a wrapper around eventlog_open, eventlog_write, eventlog_close for simple logging needs and should be used for applications that do not have a message file.

The following options may be specified to control the values of the various fields in the event log record:

-system SYSTEMNAME	Specifies the system on which the event log resides. By default, this is the local system.
-source SOURCENAME	Specifies a event log source. The returned handle will refer to the event log to which events from SOURCENAME are logged. This defaults to the filename portion (without the path or extension) of the executable file.
-type EVENTTYPE	Indicates the type or severity of the event. EVENTTYPE should be one of success, error, warning, information (default), auditsuccess or auditfailure.
-category CATEGORY	This should be a integer corresponding to a category id in the event source's category or message file. This value defaults to 1.

eventlog_monitor_start EVENTLOGHANDLE SCRIPT

Registers SCRIPT to be invoked whenever the event log specified by EVENTLOGHANDLE receives a new event. EVENTLOGHANDLE must be a read handle. Windows will invoke SCRIPT only when new events are written to the event log but no more than once every 5 seconds. Note that EVENTLOGHANDLE must not be closed in order for the notifications to be sent.

The command returns an id for the notification. When the application is no longer interested in receiving notifications, it should release the associated resources by passing the id to eventlog_monitor_stop. This is required even if EVENTLOGHANDLE is closed.

eventlog_monitor_stop EVENTNOTIFICATIONID

Stops notifications from the event log. EVENTNOTIFICATIONID is the id returned from a previous call to eventlog_monitor_start.

eventlog_oldest EVENTLOGHANDLE

Returns the record number of the oldest record in the specified event log. EVENTLOGHANDLE must be a read handle.

eventlog_open ?options?

Returns a handle to the specified event log. When no longer required, it should be closed by passing it to eventlog_close. Various options specify the event log to be opened and the read-write mode.

-system SYSTEMNAME	Specifies the system on which the event log resides. By default, this is the local system.
-source SOURCENAME	Specifies a event log source. The returned handle will refer to the event log to which events from SOURCENAME are logged. This defaults to the filename portion (without the path or extension) of the executable file. This option may not be used with the -file option.
-file EVENTLOGBACKUPFILE	Specifies the name of a backed up event log file. This option may not be used with the -source or -file options.
-write	Returns a handle used for writing to the event log. By default, a read handle is returned. Note that event log handles are never read-write. Applications wishing to do both need to open two separate handles. This option may not be used with the -file option as event log backup files cannot be written to.

eventlog_read EVENTLOGHANDLE ?options?

Returns a list of event records read from the specified event log. EVENTLOGHANDLE must be a read handle. The number of records returned may vary depending on the number of records in the event log as well as internal buffering limits. Returns an empty list when no more records can be read. Each eventlog_read command moves the event log read pointer.

The following options may be specified to control the read operation:

-seek RECORDNUMBER	Normally the command returns event log records starting from current read pointer. If this option is specified, the command will return records starting with the one with record number RECORDNUMBER.
-direction backward\|forward	Controls the direction in which the read pointer moves. By default, the commands will return records reading forwards from the current read pointer.

Each element in the returned list corresponds to an event log record and is a list of the form field value .... The following fields are returned in each event record:

-category	This is an integer corresponding to a category id in the event source's category or message file.
-data	Raw binary data stored as part of the event record.
-eventid	The event id that identifies the event type. See eventlog_write for how this may be used.
-params	A list of strings corresponding to the positional %N format specifiers in the format string for the event in the message file.
-sid	The SID of the user account of the thread that logged the event. This may be a null string if this information was not included in the record.
-recordnum	The record number for this record. This may be used with the -seek option to locate a record.
-source	The event source that logged the event.
-system	The name of the system on which the event was generated.
-timegenerated	Contains the time that the event was generated (UTC) expressed as an offset in seconds since 00:00:00 Jan 1, 1970. This can be passed to the clock format command to convert to an absolute time.
-timewritten	Contains the time (UTC) that the event was written into the event log expressed as an offset in seconds since 00:00:00 Jan 1, 1970. This can be passed to the clock format command to convert to an absolute time.
-type	Indicates the type or severity of the event. The value is one of success, error, warning, information, auditsuccess or auditfailure.

eventlog_write EVENTLOGHANDLE EVENTID ?options?

Writes a record into the specified event log. EVENTLOGHANDLE must be a write handle for an event log. EVENTID is a integer that identifies the specific event. If the event source is configured in the registry, this is the message id for the event in the message file for the source. If no message file has been configured, this event id is irrelevant.

The following options may be specified to control the values of the various fields in the event log record:

-type EVENTTYPE	Indicates the type or severity of the event. EVENTTYPE should be one of success, error, warning, information (default), auditsuccess or auditfailure. Note that the last two may only be used when writing to the Security event log.
-category CATEGORY	This should be a integer corresponding to a category id in the event source's category or message file. This value defaults to 1.
-loguser	Specifying this will cause the SID of the user account for this thread to be included in the event record.
-params PARAMLIST	Specifies a list of strings corresponding to the positional %N format specifiers in the format string for the event in the message file. If the source has not been configured with a message file in the registry, event viewers will generally display this as a list of strings.
-data DATA	Raw binary data that should be stored as part of the event record.

Event log

SYNOPSIS

DESCRIPTION

Overview

Commands

COPYRIGHT

TWAPI 3.1.17 Documentation