Log Parser COM API Overview

The Log Parser scriptable COM components offer numerous advantages and more flexibility than the command-line executable binary.
For example, with the Log Parser scriptable COM components we can execute a query without providing an output format, retrieve the result output records, and process the output records ourselves.

The Log Parser scriptable COM components are implemented as Automation objects, which means that they can be used from any programming environment supporting automation, including C++, C#, Visual Basic, JScript and VBScript.

Tip: Before using the Log Parser scriptable COM components on a computer, the "LogParser.dll" binary should be registered with the computer's COM infrastructure by executing the following command in the directory containing the "LogParser.dll" binary:
C:\LogParser>regsvr32 LogParser.dll

The Log Parser scriptable COM components architecture is made up of the following objects:

MSUtil.LogQuery object: this is the main COM object in the Log Parser scriptable COM components architecture; it exposes the main API methods and provides access to other objects in the architecture.
Input Format objects: these objects provide programmatic access to the input formats supported by Log Parser; each input format object exposes properties having the same name as the parameters of the corresponding Log Parser input format.
Output Format objects: these objects provide programmatic access to the output formats supported by Log Parser; each output format object exposes properties having the same name as the parameters of the corresponding Log Parser output format.

When writing an application that uses the Log Parser scriptable COM components, the very first step should be the instantiation of the MSUtil.LogQuery COM object.
The following JScript example shows how the MSUtil.LogQuery object is instantiated by a JScript application:

var oLogQuery = new ActiveXObject("MSUtil.LogQuery");

The following VBScript example shows how the MSUtil.LogQuery object is instantiated by a VBScript application:

Dim oLogQuery
Set oLogQuery = CreateObject("MSUtil.LogQuery")

Once the MSUtil.LogQuery COM object has been instantiated, an application would usually proceed by executing a query in either batch mode or interactive mode, depending on the task that needs to be accomplished.

Batch Mode

A query executed in batch mode will have its output records written directly to an output format.
Batch mode works in the same way as the commands used with the Log Parser command-line executable, and it is useful when we want to execute a query and have its results sent to an output format, with no application intervention on the query output records.

A query is executed in batch mode by calling the ExecuteBatch method of the MSUtil.LogQuery object. This method takes three arguments:

The text of the SQL-Like query;
An input format object;
An output format object.

The basic steps of an application using batch mode resemble the commands used with the Log Parser command-line executable:

Instantiate the MSUtil.LogQuery object;
Instantiate the input format object corresponding to the input format chosen for the query;
If needed, set input format object properties to change the default behavior of the input format;
Instantiate the output format object corresponding to the output format chosen for the query;
If needed, set output format object properties to change the default behavior of the output format;
Call the ExecuteBatch method of the MSUtil.LogQuery object, specifying the query text, the input format object, and the output format object.

The following examples show a simple application that creates a CSV file containing selected records from the event log.
After instantiating the main MSUtil.LogQuery object, the application instantiates the MSUtil.EVTInputFormat input format object, which implements the EVT input format, and sets its direction property to "BW", in order to read events from the latest to the earliest.
Then, the application instantiates the MSUtil.CSVOutputFormat output format object, which implements the CSV output format, and sets its tabs property to "ON", in order to improve readability of the CSV file.
Finally, the application calls the ExecuteBatch method of the MSUtil.LogQuery object, specifying the query, the input format object, and the output format object; the method will execute the query, reading from the event log and writing to the specified CSV file, and will return when the query execution is complete.

JScript example:

var oLogQuery = new ActiveXObject("MSUtil.LogQuery");

// Create Input Format object
var oEVTInputFormat = new ActiveXObject("MSUtil.LogQuery.EventLogInputFormat");
oEVTInputFormat.direction = "BW";

// Create Output Format object
var oCSVOutputFormat = new ActiveXObject("MSUtil.LogQuery.CSVOutputFormat");
oCSVOutputFormat.tabs = true;

// Create query text
var strQuery = "SELECT TimeGenerated, EventID INTO C:\\output.csv FROM System";
strQuery +=	" WHERE SourceName = 'Application Popup'";

// Execute query
oLogQuery.ExecuteBatch( strQuery, oEVTInputFormat, oCSVOutputFormat );

VBScript example:

Dim oLogQuery
Dim oEVTInputFormat
Dim oCSVOutputFormat 
Dim strQuery

Set oLogQuery = CreateObject("MSUtil.LogQuery")

' Create Input Format object
Set oEVTInputFormat = CreateObject("MSUtil.LogQuery.EventLogInputFormat")
oEVTInputFormat.direction = "BW"

' Create Output Format object
Set oCSVOutputFormat = CreateObject("MSUtil.LogQuery.CSVOutputFormat")
oCSVOutputFormat.tabs = TRUE

' Create query text
strQuery = "SELECT TimeGenerated, EventID INTO C:\output.csv FROM System"
strQuery = strQuery & " WHERE SourceName = 'Application Popup'"

' Execute query
oLogQuery.ExecuteBatch strQuery, oEVTInputFormat, oCSVOutputFormat

Interactive Mode

Queries executed in interactive mode do not use output formats, but rather return their output records directly to the application.
Interactive mode is useful when we want to execute a query and receive the output records for custom processing.

A query is executed in interactive mode by calling the Execute method of the MSUtil.LogQuery object. This method takes two arguments:

The text of the SQL-Like query;
An input format object.

The Execute method returns a LogRecordSet object. The LogRecordSet object is an enumerator of LogRecord objects; it allows an application to navigate through the query output records.
Each LogRecord object represents a single query output record, and it exposes methods that can be used to retrieve individual field values from the output record.

The basic steps of an application using interactive mode are:

Instantiate the MSUtil.LogQuery object;
Instantiate the input format object corresponding to the input format chosen for the query;
If needed, set input format object properties to change the default behavior of the input format;
Call the Execute method of the MSUtil.LogQuery object, specifying the query text and the input format object, and receiving a LogRecordSet object;
Enter a loop that uses the atEnd, getRecord, and moveNext methods of the LogRecordSet object to enumerate the LogRecord query result objects;
For each LogRecord object, access its field values using the getValue method of the LogRecord object, and process the field values as needed;
When finished, dispose of the LogRecordSet object by calling its close method.

The following examples show a simple application parsing an IIS web site's logs and printing the output records to the console output.
After instantiating the main MSUtil.LogQuery object, the application instantiates the MSUtil.IISW3CInputFormat input format object, which implements the IISW3C input format.
Then, the application calls the Execute method of the MSUtil.LogQuery object, specifying the query and the input format object, and receiving the resulting LogRecordSet object.
The LogRecordSet object is used in a loop to enumerate the LogRecord objects implementing the query output records; the application retrieves the first field from each LogRecord object and prints it to the console output.
Finally, the application disposes of the LogRecordSet object by calling its close method.

JScript example:

var oLogQuery = new ActiveXObject("MSUtil.LogQuery");

// Create Input Format object
var oIISW3CInputFormat = new ActiveXObject("MSUtil.LogQuery.IISW3CInputFormat");

// Create query text
var strQuery = "SELECT c-ip FROM <1> WHERE cs-uri-stem LIKE '%hitcount.asp'";

// Execute query and receive a LogRecordSet
var oRecordSet = oLogQuery.Execute( strQuery, oIISW3CInputFormat );

// Visit all records
while( !oRecordSet.atEnd() )
{
		// Get a record
		var oRecord = oRecordSet.getRecord();

		// Get first field value
		var strClientIp = oRecord.getValue( 0 );

		// Print field value
		WScript.Echo( "Client IP Address: " + strClientIp );

		// Advance LogRecordSet to next record
		oRecordSet.moveNext();
}

// Close LogRecordSet
oRecordSet.close();

VBScript example:

Dim oLogQuery
Dim oIISW3CInputFormat
Dim strQuery
Dim oRecordSet
Dim oRecord
Dim strClientIp

Set oLogQuery = CreateObject("MSUtil.LogQuery")

' Create Input Format object
Set oIISW3CInputFormat = CreateObject("MSUtil.LogQuery.IISW3CInputFormat")

' Create query text
strQuery = "SELECT c-ip FROM <1> WHERE cs-uri-stem LIKE '%hitcount.asp'"

' Execute query and receive a LogRecordSet
Set oRecordSet = oLogQuery.Execute ( strQuery, oIISW3CInputFormat )

' Visit all records
DO WHILE NOT oRecordSet.atEnd

		' Get a record
		Set oRecord = oRecordSet.getRecord

		' Get first field value
		strClientIp = oRecord.getValue ( 0 )

		' Print field value
		WScript.Echo "Client IP Address: " & strClientIp

		' Advance LogRecordSet to next record
		oRecordSet.moveNext

LOOP

' Close RecordSet
oRecordSet.close