readRecords

>>--readRecords(-+-----------+-+----------+-+----------+-+---------+-+---------+--)--><
                 +-direction-+ +-,-server-+ +-,-source-+ +-,-start-+ +-,-count-+

Reads the desired event records from the specified event log. Each record is stored in the events array. After a successful read, all records will be contained in the events array in the order there were read. Prior to starting the read opereation the array is emptied.

Details:

This method will raise syntax errors if the start or count arguments are used incorrectly. These arguments, if used, must specify records actually contained in the event log. Use any combination of the getFirst(), getLast(), or getNumber() methods to determine the absolute record numbers contained in the log.

During a read operation, if a single event record is larger than the read buffer an execution error will be raised. The text of the error will read: An event log record is too large (recordSize) for the read buffer (bufferSize.) Where recordSize is the size of the record and bufferSize is the size of the read buffer at the time of the error.

The minimum size of the read buffer can be increased by using the minimumRead= method. If this error occurred, the minimum read buffer should be set larger than the size of the offending record.

Note well: It seems inconceivable that the read buffer could be smaller than a single event record. The minimum possible size of the buffer is 16 KB and the average size of an event record is between 100 and 200 bytes. The ooRexx programmer should not worry about this. This unlikely possibility is simple documented for the sake of completeness.

Arguments:

The arguments are:

direction

Optional. The direction to read the from the event log, forwards or backwards. The default is to read forwards. If this argument is not omitted, it must be exactly one of the keywords, BACKWARDS or FORWARDS. Case is not significant.

server

Optional. The name of the server where the event log resides

source

Optional. The event source.

start

Optional. The starting record number for the read operation. The start and the count arguments must be used together. Either both must be used or neither. If both arguments are omitted, the entire log is read. When both arguments are used, the read begins with the record number specified by start and reads in the direction specified for count records.

count

Optional. The count of records to be read during the read operation. The start and the count arguments must be used together. Either both must be used or neither. If both arguments are omitted, the entire log is read. When both arguments are specified, the read begins with the record number specified by start and reads in the direction specified for count records.

Return value:

This method returns 0 on success, and the operating system error code on failure.

Example:

This example reads the 5 most recent event records in the System event log and displays them to the console. (If there are less than 5 records in the log, then all the records are read.)


  log = .WindowsEventLog~new

  startRec = log~getLast( , "System")
  count = log~getNumber~min(5)

  ret = log~readRecords("BACKWARDS", , "System", startRec, count)

  if ret == 0 then do
    c = displayRecords(log~events)
    say 'Displayed' c 'records'
  end
  else do
    say "Error reading the System event log rc:" ret "-" SysGetErrorText(ret)
  end

::requires 'winSystm.cls'

/* Routine to display the event log records */
::routine displayRecords
  use strict arg records

  do record over records
    say "=========================================================================="
    parse var record type date time "'" sourcename"'" id userid computer "'" string "'" "'" data "'"
    say 'Type     : 'type
    say 'Date     : 'date
    say 'Time     : 'time
    say 'Source   : 'sourcename
    say 'ID       : 'id
    say 'UserId   : 'userid
    say 'Computer : 'computer
    say 'Detail   : 'string
    say 'Data     : 'data
  end
  say "=========================================================================="
return records~items

/* The output (shortened to 2 records) might be:

==========================================================================
Type     : Information
Date     : 02/14/09
Time     : 11:32:21
Source   : WinHttpAutoProxySvc
ID       : 12503
UserId   : N/A
Computer : OSPREY
Detail   : The WinHTTP Web Proxy Auto-Discovery Service has been idle for
15 minutes, it will be shut down.

Data     :
==========================================================================
Type     : Information
Date     : 02/14/09
Time     : 11:15:51
Source   : Service Control Manager
ID       : 7036
UserId   : N/A
Computer : OSPREY
Detail   : The WinHTTP Web Proxy Auto-Discovery Service service entered
the running state.

Data     :
==========================================================================
Displayed 5 records

*/