LogNTEvent

(Engine-Level Function)

Description Logs events to the system event log.
Returns Nothing
Usage Script or steady state.
Function Groups Log
Related to:
Format: LogNTEvent(Severity, Strings [, Source, Category, EventID, DataSize, Data, UNCServerName])
Parameters  
Severity  
Required. A numeric code indicating the type of event to log. Severity can be one of:

Severity

Event

0

Informational

1

Warning

2

Error

3

Audit Success (Security Event)

4

Audit Failure (Security Event)
String 
Required. A single string or an array of strings to pass to the event as parameters.
Source
An optional parameter indicating the name of the source program. The default value for Source is "VTScada" (see comments section).
Category  
An optional parameter indicating the numeric ID of event category. The default value for Category is "0", indicating "none" (see comments section).
EventID
An optional parameter indicating the numeric event code. The default value for EventID is "1001" (see comments section).
DataSize
An optional parameter indicating the size of binary data in bytes (see comments section).
Data
An optional parameter indicating the binary data to store with the event (see comments).
UNCServerName
An optional string specifying the UNC server name for Source (see comments).
Comments Event logs store important events for applications running on Windows. Because the logging function is designed to be general purpose, you must decide what information is appropriate to log. As a general rule, you should only log information that could be useful in diagnosing a hardware or software problem. The event logging facility is not intended to be used as a tracing tool.
Event logging consumes system resources such as disk space and processor time. The amount of disk space that an event log requires depends on how much information you choose to log. For this reason, it is important to log only essential information.
Following, are some Microsoft guidelines regarding the types of events you may wish to log for each severity

Informational Information events indicate significant successful operations that occur infrequently. It is not generally considered appropriate for an application to log an event each time it starts.

Warning Warning events indicate problems that are not immediately significant, but that may indicate conditions that could cause problems in the future. Generally, if an application can continue or recover from an event without loss of functionality or data, it can classify the event as a warning.

Error Error events indicate significant problems about which the user should know. Error events usually result in or from the loss of functionality or data.

Audit Failure When a security access attempt fails, it is considered an audit failure. A failed logon attempt is a failure audit event.

Audit Success When a security access attempt succeeds, then it is a success audit event. For example, a successful logon attempt is a success audit event.

For more information on NT Event Logging, please see the Microsoft MSDN documentation.

The only required parameters for LogNTEvent are the severity code (Severity) and the string or array of strings to log with the event (Strings)

You may optionally specify:
  • The application event Source (the default value is "VTScada").
  • The Category (numeric starting at "1", where "0" is the "none" category). The default is "0" (none).
  • The EventID (numeric, generally starting at 1000 or so to not conflict with the category numbers. The first and only defined EventID for source "VTScada" is "1001", which simply displays the passed-in string).
  • Data and Datasize (used to store binary data with the event). DataSize should be the size, in bytes, of the Data array. Data is any array of binary data to be stored along with the event. And
  • UNCServerName, which is the machine to which to log the event (the default is Invalid, which results in the event being logged on the local machine. Otherwise, you may specify the UNC name for the machine to which you would like the event logged ).

Note that specifying values other than the defaults for Source or EventID will result in the event log displaying the event improperly, unless a custom DLL is written to handle the case. However, this does not prevent the event from being logged, and a custom DLL can be added at a later time.

Example:

databuff = MakeBuff(10, 65);
textstring = "RTU 0015 is offline";
res = LogNTEvent(1, 
                 textstrings, 
                 Invalid {source}, 
                 Invalid {category}, 
                 Invalid {EventID}, 
                 10, 
                 databuff);

This example will log a warning event under the source name "VTScada", with default category ("none"), and default event ID (1001). The details of the event will be the string "RTU 15 is offline, and attached to the event is 10 bytes of binary data - an array of 10 letter A's.