Using the Windows Event Log from Visual FoxPro

Transcription

1 Using the Windows Event Log from Visual FoxPro Craig Berntson 3M Health Information Systems Cole Gleave 3M Health Information Systems Overview In this article, you will learn how to use the Windows Event Log from Visual FoxPro. While you can use Windows Scripting Host (WSH) to read and write to the Windows Event Log, WSH could be disabled due to today s security requirements. Therefore, it is necessary to use the Win32 API to access the log. Using several API calls, you will learn how to read, write, and maintain the log. Logging Overview Capturing error conditions is an important part of a robust application. Historically, Visual FoxPro applications have used tables (DBFs) or text files to capture error information. However, other types of logging are available. These include XML files or the Windows Event Log. Using the Windows Event Log is desirable because other file types use proprietary formats, different user interfaces for reporting, and they cannot be merged with logs from other applications. The Windows Event Log is a standard format, stored in a centralized location and single user interface can be used to view log information from a variety of programs. Also, third party software can be purchased that will report on entries stored in the Windows Event Log. In addition to error conditions, the Windows Event Log can be used to store information such as a user logging on, opening a database, starting a file transfer, or other information. The Windows Event Log should not be used as a tracing tool or to record transactional information such as database changes. The Windows Event Log actually contains several types of logs. The standard logs and what they are used for are listed in Table 1. Under Windows 2000 and later you may find User Defined types. I will talk more about these later in this document. Your programs will make registry entries under the Application or a User Defined type. The Windows Event Log is actually a group of files. Each file represents a different log type. The location of these files is specified by Registry entries. Page 1 of 31

2 Table 1. A listing of the standard log types and their locations. Log Type Description File Location Security Security information such as logon, logoff, \WinNT\System32\Config\SecEvent.Evt password changes, etc. This log is reserved by Windows. System Information from Windows. This log is \WinNT\System32\Config\SysEvent.Evt reserved by Windows. Application Information from application software. \WinNT\System32\Config\AppEvent.Evt Each entry in the event log contains the following information: Date Time Username: The user that wrote the entry. Computer: The name of the computer that wrote the error. Generally, you will use the local event log. However, if you have the proper rights, you can log information to a server or other computer. Source: The application, module, or component that wrote the event. Message Type: Can be Success, Error, Warning, Information, Audit Success or Audit Failure. Category: Specified by a message file. Message files are discussed later in this document Event ID: Specified by a message file. Description ID: Specified by a message file. Binary Data The primary way to view information from the event log is the Event Log Viewer (Figure 1). Under Windows 2000 or later, you access the Viewer from the Administrative Tools applet of Windows Control Panel. Page 2 of 31

3 Figure 1. The Event Viewer is used to view and manage the Windows Event Log. When you double-click on an entry, the Event Properties dialog (Figure 2) for that event is displayed. You can see from Figure XX that not all the information is required. For example, the Category and User are not specified. The Description is actually loaded from a message file. Figure 2. You can view properties of a specific event. Using the Event Log There are several things you need to do to use the event log, but by creating generic message files and reusing code, it becomes easier. The three steps to use the Windows Event Log are: 1. Create the Message Files 2. Register the Event Source 3. Call the Event Log API Step three consists of several Win32 API calls and is discussed in detail later in this document. Creating Message Files Message files are resource DLLs that store the Category, Event ID, and Message ID for a particular event. You can use a separate resource DLL for each item or combine all three items into a single file and message files can be shared by multiple event sources. Page 3 of 31

4 To create a resource DLL you will need the Resource Compiler, Message Compiler, and Linker. These tools ship with Visual Studio, the Microsoft Platform SDK, and other developer tools. I did an Internet search and got hits for free tools that may give you the same functionality. The following steps walk you through creating a message file. 1. Create a text file for the messages. This example uses FoxMessages.mc. LanguageNames = ( English = 0x0409:Messages_ENU ) ;//////////////////////////////////////// ;// Eventlog categories ;// ;// These always have to be the first entries in a message file MessageId = 1 SymbolicName = CATEGORY_ONE Severity = Success Language = English First category event. MessageId = 2 SymbolicName = CATEGORY_TWO Severity = Success Language = English Second category event. ;//////////////////////////////////////// ;// Events MessageId = 1000 SymbolicName = HELLO Language = English Hello World!. MessageId = 1001 SymbolicName = GREETING Language = English Hello %1. How are you?. MessageId = 1002 SymbolicName = GENERIC1 Language = English %1. MessageId = 1003 SymbolicName = GENERIC2 Language = English Message 1: %1 Message 2: %2 Page 4 of 31

5 . 2. In the Windows Command Interpreter, compile the message file using the Message Compiler. mc FoxMessages.mc The message compiler outputs the following files: FoxMessages.h: A C++ header file containing the event information FoxMessages.rc: A Resource source file. This will be the input for resource compiler. Messages_ENU.bin: A binary file for US English messages. 3. In the Windows Command Interpreter, compile the resource file using the Resource Compiler. rc FoxMessages.rc The Resource Compiler will create the resource file FoxMessages.res. 4. In the Windows Command Interpreter, link the resource file. link -dll -noentry -out:foxmessages.dll FoxMessages.res The dll parameter tells the linker to create a.dll file (FoxMessages.dll) and noentry says there will not be entry point. This is required because the linker is not creating a Win32 dll, but rather a resource dll. The resource dll is now ready to use. The sample code that accompanies this article includes the batch file Make.bat that does all three steps for you. Updating the Registry Before you can use the resource dll, you need to make a registry entry so that Windows can find it when the event is read and written. You can use the Registry Fox Foundation Class to do this programmatically, make the entry when you install the application, or edit the registry manually using RegEdit. However you do it, the entry goes in HKEY_LOCAL_MACHINE\SYSTEM\ ControlSet001\Services\EventLog\Application. If you want your event information to go under the Application log, use the above location. If you want a custom log, say, MyApps, create a new entry called MyApp at the same level as Application. Next, make an entry for your Page 5 of 31

6 application name. In this example, I m using HKEY_LOCAL_MACHINE\SYSTEM\ ControlSet001\Services\EventLog\Application\FoxMessages. Here are the steps I used: 1. Run Regedit and drill down until you reach the above key (Figure 3) Figure 3. The Registry Editor is used to view and manage entries in the Windows registry. 2. Right-click on Application and select New Key from the context menu. Enter FoxMessages as the key. 3. Right-click on FoxMessages and select New String Value. Enter EventMessageFile. 4. Double-click EventMessageFile. The Edit String dialog (Figure 4) is displayed. Enter the path to your resource dll and click OK. Figure 4. You can add or change an entry in the registry from the Edit String dialog. Page 6 of 31

7 5. Right-click on FoxMessages and select New DWORD Value. Enter TypesSupported. 6. Double-click on TypesSupported. The Edit DWORD Value dialog (Figure 5) is displayed. Enter 7 for Value data so that the log entry can support all types. The types are listed in Table 2. Make sure Hexadecimal is selected, and then click OK. Figure 5. You can add or edit a DWORD in the registry using the Edit DWORD Value dialog. Table 2. The Bitmask values for the TypesSupported registry entry. Description Hex Value Binary Value EVENT_LOG_ERROR_TYPE 0x EVENT_LOG_WARNING_TYPE 0x EVENT_LOG_INFORMATION_TYP E 0x Add an entry for CategoryMessageFile. The Value will be the same path and file name you entered for EventMessageFile. 8. Add another entry for CategoryCount. The Value will be 2, as that is the number of categories in the message file. The Registry Editor should now look like Figure 6. Page 7 of 31

8 Figure 6. The Windows registry after making entries for FoxMessages. 9. Close the registry editor. 10. Reboot your computer. You have completed the registry entries needed for your application. Next, I ll show you how to write to the Windows Event Log. Using the Win32 API Writing to and reading from the event log requires that you declare Win32 API functions. Some of these functions are part of the Event Logging API. Others are supporting functions. It is common when using the Win32 API to make the function call then call another function to check if an error occurred. The function to call is GetLastError( ). Most Win32 API functions set the error condition when they fail. However, some set the error code when they succeed. Because of this, you should always call GetLastError( ) after making a Win32 API call. DECLARE INTEGER GetLastError IN WIN32API Before you can write to an event source, you need to register it. The function returns a handle to the event source or NULL if an error occurs. Pass a NULL or empty string as the first parameter to use the Windows Event Log on the local computer. DECLARE INTEGER RegisterEventSource IN WIN32API ; STRING UNCServerName, ; Page 8 of 31

9 STRING SourceName The parameters for RegisterEventSource( ) are listed in Table 3. Table 3. A listing of the parameters for the RegisterEventSource function. Parameters Description UNCServerName The server name where the event is logged. If logging to the local machine, pass an empty string. SourceName The source name that is saved to the Registry. Earlier, I named the source, FoxMessage. When you finish with log, call DeregisterEventSource( ), which has a single parameter, heventlog. This is the handle that was returned by RegisterEventSource( ). DECLARE INTEGER DeregisterEventSource IN WIN32API ; INTEGER heventlog The ReportEvent( ) function actually records the event into the log. If the message is successfully recorded to the log, the return value is non-zero. If the function fails, a 0 is returned. DECLARE INTEGER ReportEvent IN WIN32API ; INTEGER EventLog, ; INTEGER Type, ; INTEGER Category, ; INTEGER EventID, ; INTEGER UserSid, ; INTEGER NumStrings, ; INTEGER DataSize, ; ; INTEGER RawData The parameters are defined in Table 4. Table 4. A listing of the parameters for the ReportEvent function. Parameters Description EventLog Handle to the event log. This is the handle returned by RegisterEventSource( ). Type Event type to log. Category Event category. The categories are defined in the message file. EventID The event identifier as defined in the message file. UserSid Points to the user s security identifier to log the username. Can be NULL if it is not required. NumStrings The number of strings in parameter. DataSize The number of bytes in the RawData written to the log. If zero, no RawData is As defined in the Win32 API help file, this is an array of NULL terminated strings to be merged into the message. In VFP, a function will be used to create a string that mimics the C++ array. Page 9 of 31

10 RawData Binary data to be stored to the log. The event type (Type parameter) can be one of five values: #DEFINE EVENTLOG_SUCCESS 0 #DEFINE EVENTLOG_ERROR_TYPE 1 #DEFINE EVENTLOG_WARNING_TYPE 2 #DEFINE EVENTLOG_INFORMATION_TYPE 4 #DEFINE EVENTLOG_AUDIT_SUCCESS 8 #DEFINE EVENTLOG_AUDIT_FAILURE 10 When reading the event log, the first thing you need to do is call OpenEventLog( ). DECLARE INTEGER OpenEventLog IN WIN32API ; STRING UNCServerName, ; STRING UNCSourceName If the function succeeds, it returns a handle to the event log. If it fails, it returns NULL. The parameters are listed in Table 5. Table 5. A listing of the parameters for the OpenEventLog function. Parameters Description UNCServerName The server name where the event is logged. If logging to the local machine, pass an empty string. SourceName The source name that is saved to the Registry. Earlier, I named the source, FoxMessage. When you finish using the event log, you should call the CloseEventLog( ) function. DECLARE INTEGER CloseEventLog IN WIN32API ; INTEGER heventlog The single parameter, heventlog, is the handle returned by OpenEventLog( ). CloseEventLog( ) will return a non-zero value if it succeeds or zero if it fails. Once the event log is open, it can be read. The event log API allows you to read a single entry at a time using the ReadEventLog( ) function. DECLARE INTEGER ReadEventLog IN WIN32API ; INTEGER heventlog, ; INTEGER ReadFlags, ; INTEGER RecordOffset, ; ; INTEGER NumberOfBytesToRead, ; ; Page 10 of 31

11 If successful, a non-zero value is returned. Zero is returned if the function fails. The parameters are listed in Table 6. Table 6. A listing parameters for the ReadEventLog function. Parameters Description heventlog The handle to the event log. ReadFlags Specifies how to read the log. See the #DEFINEs bellow. RecordOffset The log entry number where the read operation should A buffer for the data read. NumberOfBytesToRead The size, in bytes, of the The number of bytes actually The number of bytes required for the next log entry. d The values for ReadFlags are listed below. #DEFINE EVENTLOG_SEQUENTIAL_READ 1 #DEFINE EVENTLOG_SEEK_READ 2 #DEFINE EVENTLOG_FORWARDS_READ 4 #DEFINE EVENTLOG_BACKWARDS_READ 8 Now that you ve seen the primary functions in the Event Log API, it s time to see some additional functions you can do in the Windows Event Log. The first tells you how many records are in the event log. DECLARE INTEGER GetNumberOfEventLogRecords IN WIN32API ; INTEGER heventlog, ; The return value will be nonzero if the function succeeds or zero if it fails. Table 7 lists the parameters. Table 7. A listing of parameters for the GetNumberOfEventLogRecords function. Parameters Description heventlog The event log The number of records in the event log. GetOldestEventLogRecord( ) gets the record number for the oldest event in the log. It returns a nonzero value if successful or zero if it fails. Table 8 lists the parameters. DECLARE INTEGER GetOldestEventLogRecord IN WIN32API ; INTEGER heventlog, ; Table 8. A listing parameters for the GetOldestEventLogRecord function. Parameters Description Page 11 of 31

12 The event log handle. The record number of the oldest record in the event log. That completes the actual event log API calls. There are some additional Win32 API functions that you ll need to use. The first of these is GlobalAlloc( ), which allocates memory on the heap. If the function succeeds, it returns a handle to the allocated memory. If it fails, it returns NULL. DECLARE INTEGER GlobalAlloc IN WIN32API ; INTEGER Flags, ; INTEGER Bytes Table 9 defines the parameters. Table 9. A listing of parameters for the GlobalAlloc function. Parameters Description Flags Indicates how to fill the memory being allocated. For the event log, the memory can be filled with zeros, as defined below. Bytes The number of bytes to allocate. The following line defines the value to pass for the Flags parameter: #DEFINE GMEM_ZEROINIT 0x0040 Since memory is allocated, is must also be deallocated. That is the purpose of GlobalFree( ). The single parameter is the handle to the memory, as returned by GlobalAlloc( ). If GlobalFree( ) succeeds in deallocating the memory, it returns NULL. Any other value indicates failure. DECLARE INTEGER GlobalFree IN WIN32API ; INTEGER Mem The strings that are used for parameter of the ReportEvent function need to be copied from Visual FoxPro memory into the allocated memory. Keep in mind that the Event API function requires a C++ array string. By copying the memory and doing some other hocus-pocus that I will explain later, the VFP string will look like a C++ array string. The CopyMemory( ) function will handle this for us. DECLARE RtlMoveMemory IN WIN32API AS CopyMemory ; INTEGER Destination, ; STRING Source, ; INTEGER Length This function has no return value. The parameters are listed in Table 10. Page 12 of 31

13 Table 10. A listing of parameters for the RtlMoveMemory function. Parameters Description Destination The starting address of the copied block s destination. Source The starting address of the block of memory to copy. Length The size, in bytes, of the block of memory to copy. One of the optional parameters of the ReportEvent( ) function is UserSid, which is the User s Security ID. The LookupAccountSid( ) function gets that information for you. DECLARE INTEGER LookupAccountSid IN WIN32API ; STRING SystemName, ; ; ; ; ; ; A nonzero return value indicates success, zero indicates failure. Table 11 lists the parameters. Table 11. A listing of parameters for the LookupAccountSID function. Parameters Description SystemName The server name to query. Pass an empty string to query the local A SID structure for the account information to look The account name corresponding to The number of bytes contained in parameter. If the function fails is too small, this will contain the number of bytes The domain where the account is The number of bytes contained in e parameter. If the function fails is too small, this will contain the number of bytes Contains the type of account when the function returns. The next function, LoadLibraryEx( ) maps an executable module into the address space of the calling process. For the Windows Event Log, it is used to load the message file. Here is the syntax: DECLARE LONG LoadLibraryEx IN WIN32API ; STRING LibFileName, ; INTEGER RESERVED, ; INTEGER Flags If the function call succeeds, the return value is a handle to the mapped executable module. If it fails, NULL is returned. Table 12 lists the parameters. Table 12. A listing of parameters for the LoadLibraryEx function. Page 13 of 31

14 Parameters LibFileName RESERVED Flags Description The name of the executable (DLL or EXE) module. Must be NULL The action to take when loading the module. For event log usage, the only value you need to use here is to load the library as a datafile. #DEFINE LOAD_LIBRARY_AS_DATAFILE 0x After you finish using the library, you need to release it. The FreeLibrary( ) function will do this. It takes a single parameter, hlibmodule, which is the return value of LoadLibraryEx( ). If the function succeeds, it returns a nonzero value. Any other return value indicates failure. DECLARE INTEGER FreeLibrary IN WIN32API ; LONG hlibmodule You will need to format the message string. The FormatMessageString( ) function does this. DECLARE INTEGER FormatMessage IN WIN32API ; INTEGER Flags, ; LONG Source, ; INTEGER MessageId, ; INTEGER LanguageId, ; ; INTEGER BufferSize, ; FormatMessage( ) returns the number of bytes in the output buffer. If it fails, it returns a zero. Table 13 lists the parameters. Table 13. A listing parameters for the FormatMessage function. Parameters Description Flags A series of bit flags that specify aspects of the formatting process and how to interpret the Source parameter. See the FORMAT_MESSAGE constants below. Source Specifies the location of the message definition. This will be the resource file loaded by LoadLibraryEx. MessageId The Message Id from the Message file. LanguageId The language Id. You can use 0 if no language is Used to return the formatted message. BufferSize The maximum number of bytes that can be Values that are used as insert values in the message. #DEFINE FORMAT_MESSAGE_ALLOCATE_BUFFER 256 #DEFINE FORMAT_MESSAGE_IGNORE_INSERTS 512 Page 14 of 31

15 #DEFINE FORMAT_MESSAGE_FROM_HMODULE 2048 #DEFINE FORMAT_MESSAGE_ARGUMENT_ARRAY 8192 The last API function is ExpandEnvironmentStrings( ). This function expands environment variable strings and replaces them with their user-defined values. DECLARE INTEGER ExpandEnvironmentStrings IN WIN32API ; ; ; INTEGER nsize If the function succeeds, the return value is the number of characters stored in the destination buffer. If the number of characters is greater than the size of the destination buffer, the return value is the size of the buffer required to hold the expanded strings. If the function fails, the return value is zero. Table 14 lists the parameters. Table 14. A list of parameters for the ExpandEnvironmentStrings function. Parameters The environment variable string to expand. Must be of the form: The buffer to receive the value specified nsize The maximum number of bytes that can be held That completes the Win32 API functions. However, there is still just a bit more to cover before looking at the full code. I haven t completely showed you how to do the conversion from a VFP string to the C++ array string. The following VFP functions will do this: * Adapted from KB Article ID: Q *-- The following function converts a long integer to an ASCII *-- character representation of the passed value in low-high format. ****************** FUNCTION LongToStr ****************** * Passed : 32-bit non-negative numeric value (lnlongval) * Returns : ascii character representation of passed value in low-high * format (lcretstr) * Example : * m.long = "999999" * m.longstr = long2str(m.long) LPARAMETERS lnlongval LOCAL lni, lcretstr lcretstr = "" FOR lni = 24 TO 0 STEP -8 lcretstr = CHR(INT(lnLongval / (2 ^ lni))) + lcretstr lnlongval = MOD(lnLongval, (2 ^ lni)) NEXT RETURN lcretstr Page 15 of 31

16 *-- The following function converts a string in low-high format to a *-- long integer. ****************** FUNCTION StrToLong ****************** * Passed: 4-byte character string (lclongstr) in low-high ASCII format * Returns: long integer value * Example: * m.longstr = "1111" * m.longval = str2long(m.longstr) LPARAMETERS lclongstr LOCAL lni, lnretval lnretval = 0 FOR lni = 0 TO 24 STEP 8 lnretval = lnretval + (ASC(lcLongstr) * (2 ^ lni)) lclongstr = RIGHT(lcLongstr, LEN(lcLongstr) - 1) NEXT RETURN lnretval Writing to the Event Log Now that you ve seen the functions involved in using the Windows Event Log, it s time to learn how write to the event log. Here is the code. #define EVENTLOG_SUCCESS 0 #define EVENTLOG_ERROR_TYPE 1 #define EVENTLOG_WARNING_TYPE 2 #define EVENTLOG_INFORMATION_TYPE 4 #define EVENTLOG_AUDIT_SUCCESS 8 #define EVENTLOG_AUDIT_FAILURE 10 #define GMEM_ZEROINIT 0x0040 DECLARE INTEGER GetLastError IN WIN32API DECLARE INTEGER RegisterEventSource IN WIN32API ; STRING UNCServerName, ; STRING SourceName DECLARE INTEGER DeregisterEventSource IN WIN32API ; INTEGER heventlog DECLARE INTEGER ReportEvent IN WIN32API ; INTEGER EventLog, ; INTEGER Type, ; INTEGER Category, ; INTEGER EventID, ; INTEGER UserSid, ; INTEGER NumStrings, ; INTEGER DataSize, ; Page 16 of 31

17 ; INTEGER RawData DECLARE INTEGER GlobalAlloc IN WIN32API ; INTEGER Flags, ; INTEGER Bytes DECLARE INTEGER GlobalFree IN WIN32API ; INTEGER Mem DECLARE RtlMoveMemory in WIN32API as CopyMemory ; INTEGER Destination, ; STRING Source, ; INTEGER Length LOCAL lnhandle, lcname, pname, lcstrings, lnretval, ; lcmessage1, lcmessage2, pmessage1, pmessage2, lcmessages lnhandle = RegisterEventSource("", "FoxMessages") IF lnhandle > 0 * No parameter lnretval = ReportEvent(lnHandle, EVENTLOG_SUCCESS, 1, 1000, 0, 0, 0, NULL, 0) IF lnretval = 0 MESSAGEBOX("ReportEvent Error: " + ALLTRIM(STR(GetLastError()))) * Single parameter lcname = "Fred" pname = GlobalAlloc(GMEM_ZEROINIT, LEN(lcName) + 1) CopyMemory(pName, lcname, LEN(lcName)) lcstrings = LongToStr(pName) lnretval = ReportEvent(lnHandle, EVENTLOG_SUCCESS, 2, 1001, 0, 1, 0) IF lnretval = 0 MESSAGEBOX("ReportEvent Error: " + ALLTRIM(STR(GetLastError()))) IF pname > 0 lnret = GlobalFree(pName) * Multiple parameters lcmessage1 = "This is the first message." lcmessage2 = "This is another message!" pmessage1 = GlobalAlloc(GMEM_ZEROINIT, LEN(lcMessage1) + 1) pmessage2 = GlobalAlloc(GMEM_ZEROINIT, LEN(lcMessage2) + 1) CopyMemory(pMessage1, lcmessage1, LEN(lcMessage1)) CopyMemory(pMessage2, lcmessage2, LEN(lcMessage2)) lcmessages = LongToStr(pMessage1) + LongToStr(pMessage2) lnretval = ReportEvent(lnHandle, EVENTLOG_SUCCESS, 1, 1003, 0, 2, 0) IF lnretval = 0 MESSAGEBOX("ReportEvent Error: " + ALLTRIM(STR(GetLastError()))) IF pmessage1 > 0 Page 17 of 31

18 lnret = GlobalFree(pMessage1) IF pmessage2 > 0 lnret = GlobalFree(pMessage2) lnretval = DeregisterEventSource(lnHandle) MESSAGEBOX("RegisterEventSource Error: " ; + ALLTRIM(STR(GetLastError()))) RETURN ****************** * From KB Article ID: Q ****************** FUNCTION LongToStr * The following function converts a long integer to an ASCII * character representation of the passed value in low-high format. * Passed: 32-bit non-negative numeric value (lnlongval) * Returns: ascii character representation of passed value in low-high * format LPARAMETERS lnlongval LOCAL lni, lcretstr lcretstr = "" FOR lni = 24 TO 0 STEP -8 lcretstr = CHR(INT(lnLongval / (2 ^ lni))) + lcretstr lnlongval = MOD(lnLongval, (2 ^ lni)) NEXT RETURN lcretstr ****************** FUNCTION StrToLong * Convert a string in low-high format to a long integer. * Passed: 4-byte character string (lclongstr) in low-high ASCII format * Returns: long integer value LPARAMETERS lclongstr LOCAL lni, lnretval lnretval = 0 FOR lni = 0 TO 24 STEP 8 lnretval = lnretval + (ASC(lcLongstr) * (2 ^ lni)) lclongstr = RIGHT(lcLongstr, LEN(lcLongstr) - 1) NEXT RETURN lnretval As you can see from this example, the actual FoxPro code is fairly simple. The key to using the event log is defining the API calls and converting FoxPro data types to the C++ data types needed for the calls. Page 18 of 31

19 Reading from the Event Log Here s the code to read from the event log. The results are displayed in a Message Box. #DEFINE EVENTLOG_SEQUENTIAL_READ 1 #DEFINE EVENTLOG_SEEK_READ 2 #DEFINE EVENTLOG_FORWARDS_READ 4 #DEFINE EVENTLOG_BACKWARDS_READ 8 #DEFINE ERROR_INSUFFICIENT_BUFFER 122 #DEFINE ERROR_HANDLE_EOF 38 #DEFINE EVENTLOG_SUCCESS 0 #DEFINE EVENTLOG_ERROR_TYPE 1 #DEFINE EVENTLOG_WARNING_TYPE 2 #DEFINE EVENTLOG_INFORMATION_TYPE 4 #DEFINE EVENTLOG_AUDIT_SUCCESS 8 #DEFINE EVENTLOG_AUDIT_FAILURE 10 #DEFINE HKEY_LOCAL_MACHINE && BITSET(0,31)+2 #DEFINE FORMAT_MESSAGE_ALLOCATE_BUFFER 256 #DEFINE FORMAT_MESSAGE_IGNORE_INSERTS 512 #DEFINE FORMAT_MESSAGE_FROM_HMODULE 2048 #DEFINE FORMAT_MESSAGE_ARGUMENT_ARRAY 8192 #DEFINE LOAD_LIBRARY_AS_DATAFILE 0x #DEFINE GMEM_ZEROINIT 0x0040 DECLARE INTEGER GetLastError IN WIN32API DECLARE INTEGER OpenEventLog IN WIN32API ; STRING UNCServerName, ; STRING UNCSourceName DECLARE INTEGER CloseEventLog IN WIN32API ; INTEGER heventlog DECLARE INTEGER GetNumberOfEventLogRecords IN WIN32API ; INTEGER heventlog, ; DECLARE INTEGER GetOldestEventLogRecord IN WIN32API ; INTEGER heventlog, ; DECLARE INTEGER ReadEventLog IN WIN32API ; INTEGER heventlog, ; INTEGER ReadFlags, ; INTEGER RecordOffset, ; ; INTEGER NumberOfBytesToRead, ; ; DECLARE INTEGER LookupAccountSid IN WIN32API ; Page 19 of 31

20 STRING SystemName, ; ; ; ; ; ; DECLARE LONG LoadLibraryEx IN WIN32API ; STRING LibFileName, ; INTEGER RESERVED, ; INTEGER FLAGS DECLARE INTEGER FreeLibrary IN WIN32API ; LONG hlibmodule DECLARE INTEGER FormatMessage IN WIN32API ; INTEGER FLAGS, ; LONG SOURCE, ; INTEGER MessageId, ; INTEGER LanguageId, ; STRING@ BUFFER, ; INTEGER BufferSize, ; STRING@ Arguments DECLARE INTEGER ExpandEnvironmentStrings IN WIN32API ; STRING@ Src, ; STRING@ Dst, ; INTEGER nsize DECLARE INTEGER GlobalAlloc IN WIN32API ; INTEGER FLAGS, ; INTEGER Bytes DECLARE INTEGER GlobalFree IN WIN32API ; INTEGER Mem DECLARE RtlMoveMemory IN WIN32API AS CopyMemory ; INTEGER Destination, ; STRING SOURCE, ; INTEGER LENGTH ************************************** LOCAL lcuncsourcename, loreg, heventlog, lcnumberofrecords, lnretval, ; lcoldestrecord, lcbuffer, lcbytesread, lcminnumberofbytesneeded lcuncsourcename = "C:\" SET PROCEDURE TO (ADDBS(HOME()) + "samples\classes\registry.prg") ADDITIVE loreg = CREATEOBJECT("FileReg") * lpuncsourcename = "3MHIS" heventlog = OpenEventLog(NULL, lcuncsourcename) IF heventlog = 0 MESSAGEBOX("OpenEventLog Error: " + ALLTRIM(STR(GetLastError()))) RETURN Page 20 of 31

21 * Get the number of records in the event log lcnumberofrecords = SPACE(4) lnretval = IF lnretval = 0 MESSAGEBOX("GetNumberOfEventLogRecords Error: " + ALLTRIM(STR(GetLastError()))) MESSAGEBOX("Number of Event Log Records: " + ALLTRIM(STR(StrToLong(lcNumberOfRecords)))) * Get the oldest record lcoldestrecord = SPACE(4) lnretval = IF lnretval = 0 MESSAGEBOX("GetOldestEventLogRecord Error: " + ALLTRIM(STR(GetLastError()))) MESSAGEBOX("Oldest Event Log Record: " + ALLTRIM(STR(StrToLong(lcOldestRecord)))) * Loop through messages DO WHILE.T. lcbuffer = SPACE(1) lcbytesread = SPACE(4) lcminnumberofbytesneeded = SPACE(4) lnretval = ReadEventLog(hEventLog, ; BITOR(EVENTLOG_SEQUENTIAL_READ, ; EVENTLOG_FORWARDS_READ), ; 0, ; LEN(lcBuffer), IF GetLastError() = ERROR_INSUFFICIENT_BUFFER lcbuffer = SPACE(StrToLong(lcMinNumberOfBytesNeeded)) lcbytesread = SPACE(4) lcminnumberofbytesneeded = SPACE(4) lnret = ReadEventLog(hEventLog, ; BITOR(EVENTLOG_SEQUENTIAL_READ, ; EVENTLOG_FORWARDS_READ), ; 0, ; LEN(lcBuffer), IF lnret = 0 MESSAGEBOX("ReadEventLog Error: " + ALLTRIM(STR(GetLastError()))) EXIT Page 21 of 31

22 lcmessage = ParseLogRecord(lcBuffer, lcuncsourcename, loreg) IF MESSAGEBOX(lcMessage, 1) = 2 EXIT IF GetLastError() = ERROR_HANDLE_EOF MESSAGEBOX("End of File") EXIT MESSAGEBOX("ReadEventLog Error: " + ALLTRIM(STR(GetLastError()))) EXIT ENDDO lnretval = CloseEventLog(hEventLog) IF lnretval = 0 MESSAGEBOX("CloseEventLog Error: " + ALLTRIM(STR(GetLastError()))) RETURN **************************************************** FUNCTION ParseLogRecord LPARAMETERS tcbuffer, tcuncsourcename, toreg LOCAL lcmessage, lncounter, lndatalen, pbuffer lcmessage = "Length: " + ALLTRIM(STR(StrToLong(SUBSTR(tcBuffer, 1, 4)))) + CHR(13) + CHR(10) lcmessage = lcmessage + "Record Number: " + ALLTRIM(STR(StrToLong(SUBSTR(tcBuffer, 9, 4)))) + CHR(13) + CHR(10) lcmessage = lcmessage + "Time Generated: " + TTOC({^1969/12/31 18:00:00} + StrToLong(SUBSTR(tcBuffer, 13, 4))) + CHR(13) + CHR(10) lcmessage = lcmessage + "Time Written: " + TTOC({^1969/12/31 18:00:00} + StrToLong(SUBSTR(tcBuffer, 17, 4))) + CHR(13) + CHR(10) lcmessage = lcmessage + "Event ID: " + ALLTRIM(STR(StrToLong(SUBSTR(tcBuffer, 21, 2)))) + CHR(13) + CHR(10) lcmessage = lcmessage + GetEventType(tcBuffer) lcmessage = lcmessage + "Number of Strings: " + ALLTRIM(STR(StrToLong(SUBSTR(tcBuffer, 27, 2)))) + CHR(13) + CHR(10) lcmessage = lcmessage + "Source Name: " lcsource = "" lncounter = 57 DO WHILE SUBSTR(tcBuffer, lncounter, 1) <> CHR(0) lcsource = lcsource + SUBSTR(tcBuffer, lncounter, 1) lncounter = lncounter + 1 ENDDO lcmessage = lcmessage + lcsource lcmessage = lcmessage + CHR(13) + CHR(10) lcmessage = lcmessage + GetEventCategory(tcBuffer, tcuncsourcename, lcsource, toreg) lncounter = lncounter + 1 Page 22 of 31

23 lcmessage = lcmessage + "Computer Name: " DO WHILE SUBSTR(tcBuffer, lncounter, 1) <> CHR(0) lcmessage = lcmessage + SUBSTR(tcBuffer, lncounter, 1) lncounter = lncounter + 1 ENDDO lcmessage = lcmessage + CHR(13) + CHR(10) lcmessage = lcmessage + GetUserInfo(tcBuffer) lcmessage = lcmessage + GetDescription(tcBuffer, tcuncsourcename, lcsource, toreg) lndatalen = StrToLong(SUBSTR(tcBuffer, 49, 4)) IF lndatalen > 0 lcmessage = lcmessage + "Data: " pbuffer = StrToLong(SUBSTR(tcBuffer, 53, 4)) FOR lncounter = 1 TO lndatalen lcmessage = lcmessage + STR(ASC(SUBSTR(tcBuffer, pbuffer + lncounter, lndatalen))) NEXT lcmessage = lcmessage + CHR(13) + CHR(10) RETURN lcmessage ************************************************* FUNCTION GetEventType LPARAMETERS tcbuffer LOCAL lcretval, lneventtype lneventtype = StrToLong(SUBSTR(tcBuffer, 25, 2)) DO CASE CASE lneventtype = EVENTLOG_SUCCESS lcretval = "Success" CASE lneventtype = EVENTLOG_ERROR_TYPE lcretval = "Error" CASE lneventtype = EVENTLOG_WARNING_TYPE lcretval = "Warning" CASE lneventtype = EVENTLOG_INFORMATION_TYPE lcretval = "Information" CASE lneventtype = EVENTLOG_AUDIT_SUCCESS lcretval = "Audit Success" CASE lneventtype = EVENTLOG_AUDIT_FAILURE lcretval = "Audit Failure" ENDCASE lcretval = "Event Type: " + lcretval + CHR(13) + CHR(10) RETURN lcretval ************************************ FUNCTION GetEventCategory LPARAMETERS tcbuffer, tcuncsourcename, tcsource, toreg LOCAL lcretval, lncategory, lclookup, lnkey, lccmf, lnkeyvalue, lccmfx, lnret, ; hresource, lcbuffer, lni lcretval = "" lncategory = StrToLong(SUBSTR(tcBuffer, 29, 2)) Page 23 of 31

24 IF lncategory = 0 lcretval = "None" lclookup = "SYSTEM\CurrentControlSet\Services\EventLog\" + ALLTRIM(tcUNCSourceName) + "\" + tcsource lnkey = toreg.openkey(lclookup, HKEY_LOCAL_MACHINE,.F.) IF lnkey = 0 lccmf = "" lnkeyvalue = IF lnkeyvalue = 0 lccmfx = SPACE(255) lnret = 255) hresource = LoadLibraryEx(ALLTRIM(lcCMFx), 0, LOAD_LIBRARY_AS_DATAFILE) IF hresource > 0 lcbuff = SPACE(100) lnret = FormatMessage(BITOR(FORMAT_MESSAGE_FROM_HMODULE, FORMAT_MESSAGE_IGNORE_INSERTS), ; hresource, ; lncategory, ; 0, ; 100, ; NULL) IF lnret > 0 FOR lni = 1 TO lret IF SUBSTR(tcBuffer, lni, 1) = CHR(13) EXIT lcretval = lcretval + SUBSTR(tcBuffer, lni, 1) NEXT lcretval = lcretval + "(" + ALLTRIM(STR(StrToLong(SUBSTR(tcBuffer, 29, 2)))) + ")" FreeLibrary(hResource) lcretval = lcretval + "(" + ALLTRIM(STR(StrToLong(SUBSTR(tcBuffer, 29, 2)))) + ")" lcretval = lcretval + "(" + ALLTRIM(STR(StrToLong(SUBSTR(tcBuffer, 29, 2)))) + ")" oreg.closekey() lcretval = lcretval + "(" + ALLTRIM(STR(StrToLong(SUBSTR(tcBuffer, 29, 2)))) + ")" lcretval = "Event Category: " + lcretval + CHR(13) + CHR(10) RETURN lcretval Page 24 of 31

25 ************************************************** FUNCTION GetUserInfo LPARAMETERS tcbuffer LOCAL lnusersidlength, lnusersidoffset, lcretval, lcsid, lni, lcname, cbname, ; lcreferenceddomainname, cbreferenceddomainname, peuse, lnret lnusersidlength = StrToLong(SUBSTR(tcBuffer, 41, 4)) lnusersidoffset = StrToLong(SUBSTR(tcBuffer, 45, 4)) lcretval = "" IF lnusersidlength > 0 lcsid = "" FOR lni = 1 TO lnusersidlength lcsid = lcsid + SUBSTR(tcBuffer, lnusersidoffset + lni, 1) NEXT lcname = SPACE(1) cbname = LongToStr(1) lcreferenceddomainname = SPACE(1) cbreferenceddomainname = LongToStr(1) peuse = SPACE(1) lnret = LookupAccountSid("", lnret = GetLastError() IF lnret = ERROR_INSUFFICIENT_BUFFER lcname = SPACE(StrToLong(cbName)) lcreferenceddomainname = SPACE(StrToLong(cbReferencedDomainName)) lnret = LookupAccountSid("", IF lnret = 1 lcretval = lcretval + lcname lcretval = lcretval + "N/A" lcretval = lcretval + "N/A" lcretval = lcretval + "N/A" lcretval = "User: " + lcretval + CHR(13) + CHR(10) RETURN lcretval Page 25 of 31

26 *********************************************** PROCEDURE GetDescription LPARAMETERS tcbuffer, tcuncsourcename, tcsource, toreg LOCAL lclookup, lnret, lcemf, lcemfx, lnnumstrings, pstr, lcptrs, lni, ; hresource, lcbuffer, lneventno, lcmessage, lcretval lclookup = "SYSTEM\CurrentControlSet\Services\EventLog\" + ALLTRIM(tcUNCSourceName) + "\" + tcsource lnret = toreg.openkey(lclookup, HKEY_LOCAL_MACHINE,.F.) IF lnret = 0 lcemf = "" lnret = IF lnret = 0 lnnumstrings = StrToLong(SUBSTR(tcBuffer, 27, 2)) pstr = StrToLong(SUBSTR(cBuffer, 37, 4)) + 1 lcmessage = "" lcptrs = "" FOR lni = 1 TO lnnumstrings DO WHILE.T. IF SUBSTR(tcBuffer, pstr, 1) <> CHR(0) lcmessage = lcmessage + SUBSTR(tcBuffer, pstr, 1) pstr = pstr + 1 lcptrs = lcptrs + LongToStr(GlobalAlloc(GMEM_ZEROINIT, LEN(lcMessage) + 1)) CopyMemory(StrToLong(RIGHT(lcPtrs, 4)), lcmessage, LEN(lcMessage)) pstr = pstr + 1 lcmessage = "" EXIT ENDDO NEXT lcemfx = SPACE(255) lnret = 255) hresource = LoadLibraryEx(ALLTRIM(lcEMFx), 0, LOAD_LIBRARY_AS_DATAFILE) IF hresource > 0 lcbuffer = SPACE(1000) lnret = FormatMessage(BITOR(FORMAT_MESSAGE_FROM_HMODULE, FORMAT_MESSAGE_ARGUMENT_ARRAY, 60), ; hresource, ; StrToLong(SUBSTR(tcBuffer, 21, 2)), ; 0, ; 10000, IF lnret = 0 lneventno = StrToLong(SUBSTR(tcBuffer, 21, 2)) lnret = GetLastError() Page 26 of 31

27 lcretval = ALLTRIM(lcBuffer) FreeLibrary(hResource) FOR lni = 1 TO lnnumstrings lnret = GlobalFree(StrToLong(SUBSTR(lcPtrs, lni * 4-3, 4))) NEXT toreg.closekey() lcretval = IIF(EMPTY(lcRetVal), "", "Description: " + lcretval) RETURN lcretval ****************** * From KB Article ID: Q ****************** FUNCTION LongToStr * The following function converts a long integer to an ASCII * character representation of the passed value in low-high format. * Passed: 32-bit non-negative numeric value (lnlongval) * Returns: ascii character representation of passed value in low-high * format LPARAMETERS tnlongval LOCAL lni, lcretval lcretval = "" FOR lni = 24 TO 0 STEP -8 lcretval = CHR(INT(tnLongVal / (2 ^ lni))) + lcretval lnlongval = MOD(tnLongVal, (2 ^ lni)) NEXT RETURN lcretval ****************** FUNCTION StrToLong * Convert a string in low-high format to a long integer. * Passed: 4-byte character string (lclongstr) in low-high ASCII format * Returns: long integer value LPARAMETERS tclongstr LOCAL lclongstr, lni, lnretval lclongstr = tclongstr lnretval = 0 FOR lni = 0 TO 24 STEP 8 lnretval = lnretval + (ASC(lcLongStr) * (2 ^ lni)) lclongstr = RIGHT(lcLongStr, LEN(lcLongStr) - 1) NEXT RETURN lnretval You can see that the code that actually reads the log is quite small. Most of the code is for formatting the output. Page 27 of 31

28 Managing the Event Log The Windows Event Log requires periodic maintenance. You can schedule this maintenance to occur as needed or manage it yourself. This maintenance is required due to limitations with the Event Log. The Windows Event Log documentation says that the log size for all logs is limited to 4 Gig, but testing at 3M HIS showed that the practical limit is 300 MB. The log size is also limited by memory and other services and applications using the log. The following steps show you how to setup automatic maintenance of the log: 1. Open the Event Viewer (Figure 1). 2. Right-click on Application and select Properties. The Application Properties dialog (Figure 7) is displayed. Figure 7. The Application Properties dialog is used to maintain the Event Log. 3. Use the Log size settings to maintain the size of the Event Log. 4. Click Clear Log to clear all entries from the log 5. Click OK to close the properties dialog. You can also maintain the log programmatically. The following code shows how to backup the log: Page 28 of 31

29 DECLARE INTEGER GetLastError IN WIN32API DECLARE INTEGER OpenEventLog IN WIN32API ; STRING UNCServerName, ; STRING UNCSourceName DECLARE INTEGER BackupEventLog IN WIN32API ; INTEGER heventlog, ; STRING BackupLog DECLARE INTEGER CloseEventLog IN WIN32API ; INTEGER heventlog *************************************** LOCAL heventlog, lcbackuplog, lnret lcuncsourcename = "C:\" lcbackuplog = "C:\Temp\BackupLog.Evt" heventlog = OpenEventLog(NULL, lcuncsourcename) IF heventlog = 0 MESSAGEBOX("OpenEventLog Error: " + ALLTRIM(STR(GetLastError()))) RETURN ERASE (lcbackuplog) lnret = BackupEventLog(hEventLog, lcbackuplog) IF lnret = 0 MESSAGEBOX("BackupEventLog Error: " + ALLTRIM(STR(GetLastError()))) lnret = CloseEventLog(hEventLog) IF lnret = 0 MESSAGEBOX("CloseEventLog Error: " + ALLTRIM(STR(GetLastError()))) The following code shows how to clear the Windows Event Log: DECLARE INTEGER GetLastError IN WIN32API DECLARE INTEGER OpenEventLog IN WIN32API ; STRING UNCServerName, ; STRING UNCSourceName DECLARE INTEGER ClearEventLog IN WIN32API ; INTEGER heventlog, ; STRING BackupLog DECLARE INTEGER CloseEventLog IN WIN32API ; INTEGER heventlog *************************************** Page 29 of 31

30 LOCAL heventlog, lcbackuplog, lnret, lcnewbackup lcuncsourcename = "C:\" lcbackuplog = "C:\Temp\Backup.Evt" lcnewbackup = NULL heventlog = OpenEventLog(NULL, lcuncsourcename) IF heventlog = 0 MESSAGEBOX("OpenEventLog Error: " + ALLTRIM(STR(GetLastError()))) RETURN IF!ISNULL(lcBackupLog) ERASE (lcbackuplog) lnret = ClearEventLog(hEventLog, lcbackuplog) IF lnret = 0 MESSAGEBOX("ClearEventLog Error: " + ALLTRIM(STR(GetLastError()))) lnret = CloseEventLog(hEventLog) IF lnret = 0 MESSAGEBOX("CloseEventLog Error: " + ALLTRIM(STR(GetLastError()))) Summary It may seem that using the Windows Event Log is very complex, but you could create a class that will handle this for you and a generic message file, making the job easier. By using the Windows Event Log, you will centralize event reporting, use a format common to many other applications, and make event reporting easier for the end user. Craig Berntson is a Microsoft Most Valuable Professional (MVP) for Visual FoxPro, a Microsoft Certified Solution Developer, and President of the Salt Lake City Fox User Group. He wrote the book CrysDev: A Developer s Guide to Integrating Crystal Reports, available from Hentzenwerke Publishing. He has also written for FoxTalk and the Visual FoxPro User Group (VFUG) newsletter. He has spoken at Advisor DevCon, Essential Fox, the Great Lakes Great Database Workshop, Southwest Fox, Microsoft DevDays and user groups around the country. Currently, Craig is a Senior Software Engineer at 3M Health Information Systems in Salt Lake City. You can reach him a craig@craigberntson.com or visit his website, Cole Gleave is a Senior Software Engineer at 3M Health Information Systems in Salt Lake City. Previously he was Vice-President of Technology at Convenient Automation, specializing in software for the retail industry. He has worked with FoxPro since version 2.6. You can reach him at cgleave@yahoo.com. Page 30 of 31

31 This document was created with Win2PDF available at The unregistered version of Win2PDF is for evaluation or non-commercial use only.