Copyright copyright 2006 Gene Michael Stover. All rights reserved. Permission to copy, store, & view this document unmodified & in its entirety is granted.

Contents

1 What is this?

Two problems with the Window event log are:

1. It's not a text file.
2. Command line programs for accessing it are few (or non-existent).

I've written programs which solve these problems:

1. print-log dumps the events from the Windows event log. You choose the output format. You can choose tabular (CSV), Lisp, or XML.
2. insert-log allows you to stuff a message into the Windows event log. It's analogous to the initlog program on unix².

These programs are open source. This essay tells where to get them & how to use them.

2 License

One of the source code files, getopt.c, is in the public domain. I downloaded it from the web site of the TEX User's Group.

All other files, both source & executable, are copyrighted by Gene Michael Stover & released under the terms of the GNU General Public License. Here's a copy of the copyright notice & license agreement at the beginning of each source file:

A copy of the GNU General Public License is in the file COPYING⁴.

3 Examples

The full user's manual for print-log is in Section 4.

Here are some examples of using print-log.

Assume the Windows event log contains two items. The first item, inserted at noon, says “12 o'clock & all's well.” The second item, inserted an hour later, says “Superstition brings bad luck.”.

If you run on this event log, “print-log -c,”, it prints:

The first line, which begins with a semicolon (;) because it's effectively a comment, shows the names of the fields.

Each of the other lines is an event log record. They are sorted from oldest to newest. As you can see from the last field of the second & third lines, our two event log records are in this output.

The “(concat)” means that print-log was unable to coax the Windows function FormatMessage to apply a format string to the event log message's string arguments, so print-log is showing you the concatenation of those string arguments. This is common; in fact, it may be the way that event log records are meant to be viewed. I'm not sure at this time, so print-log prints “(concat)” as a reminder. I might remove that later.

Back to our example of two event log messages, if you run “print-log -l” on the event log of two messages, you get:

Again, each event log record is shown in a single item, but this time, each item is Lisp data. Each item is a list whose first is the symbol eventlogrecord & whose rest is an association list.

Finally, you could run “print-log -x” on the same event log of two messages, & you would see:

In fact, print-log's XML output puts each EVENTLOGRECORD on a single line with no characters between fields. I've broken it here for readability.

You'll notice that this output is not valid XML because it does not have a single root element. There are probably other reasons it's not good XML. The idea is that it's close enough to XML that you could add your own root wrapper element.⁷

4User's manual

4.1insert-log

NAME

insert-log.exe – insert a record with a one-line message into the Windows event log

SYNOPSIS

print-log -h

print-log [-c category] [-i eventId] [-s source] [-t eventType]

DESCRIPTION

insert-log.exe is a command line program which inserts a record into the Windows Event Log. It provides only simple control over the record that it inserts.

When you run insert-log, it reads a single line from its standard input. It creates a new event log record using the line it read & the values for the command line options. It inserts that new record into the Windows event log.

OPTIONS

-c category

Specifies a numeric category for the event log record. Category must be an unsigned integer. The default category is 0.

-h

Print brief usage instructions.

-i eventId

Specify a numeric id for the event. EventId must be an unsigned integer. The default eventId is 0.

-s source

Specify the source of the new event log record. Source must be a string, & on the Windows systems I've tried, the only string which will work is “Application”. The default source is “Application”.

-t eventType

Secifies the event type. EventType must be one of these strings:

• EVENTLOG_SUCCESS
• EVENTLOG_AUDIT_FAILURE
• EVENTLOG_AUDIT_SUCCESS
• EVENTLOG_ERROR_TYPE
• EVENTLOG_INFORMATION_TYPE
• EVENTLOG_WARNING_TYPE

EventType is not case-sensitive. For example, “EVENTLOG_SUCCESS” is equivalent to eVEntLog_sUCcess.

The default eventType is EVENTLOG_INFORMATION_TYPE.

AUTHOR

insert-log was created by Gene Michael Stover.

BUGS

SEE ALSO

• Windows Event Log¹¹

4.2 print-log

NAME

print-log.exe – print the messages from the Windows Event Log

SYNOPSIS

print-log -h

print-log [-f]   [ -c tab ]

print-log [-f] -l

print-log [-f] -x

DESCRIPTION

print-log.exe  is a command line program which prints the records from the Windows Event Log It is sort of like the tail program in unix. (Appendix A.)

OPTIONS

-c tab

Requests output in Delimeter Separated Values form with tab (which must be a character) as the field separator. If you use -c, you must specify a character for tab. -c is incompatible with -l & -x.

-f

Tells print-log that it should keep printing new event log messages as they arrive. Use Ctrl-C to end print-log when it is running in this mode. The -f option can be used with the -c, -l, or -x options. The -f option for print-log resembles the -f option for the tail program from unix.

-h

Print brief usage instructions.

-l

Requests output as Lisp data. -l is incompatible with -c & -x.

-x

Requests output as XML. It's not a full XML document because it does not have a single root element; it's a sequence of <EVENTLOGRECORD> …</EVENTLOGRECORD> elements. There may be other ways in which it's not valid XML. The idea is that you can easily wrap this pseudo-XML output to create valid XML. -x is incompatible with -c & -l.

AUTHOR

print-log was created by Gene Michael Stover.

BUGS

• On the Microsoft Windows command line, it is difficult or impossible to specify a tab (“\t”) character, pipe (“|”) character, or backslash (“\”) character as the argument to the -c option.

  I cannot fix it without adding to print-log.c a notation for special characters. Such a notation could be confusing, & has little value (to me), so I have no plan to fix.

• Even when the field separator character is a comma (“,”), the Delimeter Separated Values (DSV) format which print-log produces is not exactly the same as the Comma Separated Values (CSV) format which Excel & other Microsoft applications can read. The difference lies in the details of quote characters & escape characters. See the “ http://www.faqs.org/docs/artu/ch05s02.html#id2901882¹⁵ ” chapter from [?].

  I could fix this by changing the -c command line option to mean CSV & adding a “-d tab” command line option which means DSV.

• You cannot specify the DTD for the XML format. The DTD (if you can call it a DTD at all) is hard-coded.

  No plan to fix.

• Even with the -f option, print-log prints all the entries from the event log. Instead, it could behave more like tail & print only the last N entries from the event log.

SEE ALSO

• Windows Event Log¹⁶

5 Obtaining

5.1 Executables

If you just want the executable files (both for Microsoft Windows), here you go:

• bin/insert-log.exe¹⁷
• bin/print-log.exe¹⁸

Drop them into a directory which is in your path, then run either of them by typing its name on the command line. Detailed user's manuals are in Section 4.

5.2 Sources & executables

If you want the source code & other files which are required to compile the programs yourself, you may download wel.zip¹⁹ or browse them individually in the tree (below).

To build them, make sure you have all the files in the directory tree as I've shown here. (If you unpacked the wel.zip²⁰  archive file, you should have that.) On the command line, cd into the wel directory. Edit the setenv.bat file to work with your environment; you'll probably have to edit the path to the vcvars32.bat file. Then type “.\setdev && .\build”. The new executable files will be in .\bin.

• COPYING²¹
• Makefile.w32²²
• bin/
  • bin/insert-log.exe²³
  • bin/print-log.exe²⁴
  • bin/test0000.exe²⁵
• build.bat²⁶
• lib/
• setdev.bat²⁷
• src/
  • src/getopt.c²⁸
  • src/getopt.h²⁹
  • src/insert-log.c³⁰
  • src/lisp.cpp³¹
  • src/lisp.h³²
  • src/log.c³³
  • src/log.h³⁴
  • src/pl.c³⁵
  • src/pl.h³⁶
  • src/print-log.c³⁷
  • src/tab.cpp³⁸
  • src/tab.h³⁹
  • src/test0000.c⁴⁰
  • src/this.h⁴¹
  • src/types.h⁴²
  • src/xmalloc.c⁴³
  • src/xmalloc.h⁴⁴
  • src/xml.cpp⁴⁵
  • src/xml.h⁴⁶
• tmp/

6 Notes about the code

1. Doesn't use the log module. Should use it or lose it to simplify things.

Appendix AThe tail program

Unix⁴⁷ has a program, called tail which prints some of the final contents of a file or other input stream.

If you give it the “-f” command line option, tail will print the final part of the file, & it won't exit when it reaches the end of the file. As more content is appended to the input, tail will print them.

For more information about tail, see:

• “man tail” at your local unix command line,⁴⁸
• Unix Manual Page for tail⁴⁹,
• “Tail (Unix)⁵⁰” at Wikipedia,
• or search for “unix tail” at your favorite web search engine.