LogOpenEventNotification
LogOpenEventNotification registers a consumer with the Logging Service, so that the consumer will receive notification when specific log records have been created. Consumers specify which log records they will be notified about by providing filtering information. If no filter data structure is provided, all events that are logged to the specified log file will cause event notifications to be forwarded to the consumer. LogOpenEventNotification returns an ID used to reference this notification request.
Notifications will be sent for only those records placed in the error log by the FFSTProbe API.
Syntax
LogOpenEventNotification(service, pOpenEventNotification);
Parameters
- service (ULONG) - input
- The class of Logging Service:
- Error logging
- All other values are reserved for future use.
- pOpenEventNotification (PVOID) - in/out
- A pointer to the LogOpenEventNotification parameter packet.
- For Error Logging, this is a pointer to a LOENREQUEST structure.
Returns
- rc (APIRET) - returns
- Return code.
LogOpenEventNotification returns the following values:
- 0 No error
- 523 Error LF invalid service
- 524 Error LF general failure
- 1703 Invalid data pointer
- 1701 RAS invalid LF log file id
- 1702 Invalid LF packet revision number
- 1706 RAS invalid parm packet ptr
- 1751 RAS invalid flag
- 1757 RAS invalid log notify ptr
- 1761 RAS invalid packet size
Remarks
The event-notification filter is a flexible data structure that is used to specify the class of events whose notifications will be received through the event-notification mechanism. It is available to event consumers (through LogOpenEventNotification and LogChangeEventFilter) and to log file readers (through LogReadEntry). This provides a common search criteria when waiting for events and reading selected entries within a log file.
EVENT NOTIFICATION FILTER STRUCTURE
______________________ _______________________ _______________________ _ SELECTION CRITERIA _ _ SELECTION CRITERIA _ _ SELECTION CRITERIA _ _ BLOCK ____>_ BLOCK ___>_ BLOCK _ _ _ _ _ _ _ ______________________ _______________________ _______________________
The event-notification filter consists of an array of one or more selection criteria blocks. Each selection criteria block contains a small header block that specifies the revision of the filter and points to the next selection criteria block.
Each selection criteria block consists of an array of selection criteria subblocks. Each selection criteria subblock contains three pieces of information:
- The ID of an attribute that is contained within this class of log entry.
- For more information see the entry_attribute_ID parameter.
- A comparison operator that is to be applied against the specified log entry attribute.
- For more information see the comparison_operator_ID parameter.
- A pointer to a data that can be either ASCII or UniCode data. The data type is determined by the packet_revision_number
The following diagram summarizes the structure of a selection criteria block:
____________________ _ _ _ HEADER _ _ BLOCK _ ____________________ _ LOG ENTRY _ SELECTION _ ATTRIBUTE ID _ CRITERIA ____________________ BLOCK _ COMPARISON _ STRUCTURE _ OPERATOR ID _ ____________________ _ POINTER TO _ _COMPARISON DATA _ ____________________ _ _ _ _ _ _ _ _ _ _ ____________________------------------------- _ LOG ENTRY _ _ ATTRIBUTE ID _ _ ____________________ SELECTION _ COMPARISON _ CRITERIA _ OPERATOR ID _ SUBBLOCK ____________________ _ _ POINTER TO _ _ _COMPARISON DATA _ ____________________--------------------------
Each selection criteria subblock specifies a comparison with respect to an attribute within a log entry. The result of the comparison is a Boolean value. The Boolean value of the array of selection criteria subblocks (within a selection criteria block) is the logical AND of the Boolean values for each subblock.
If an event-notification filter contains more than one selection criteria block, the entire chain of selection criteria blocks is considered to resolve to the logical OR of the Boolean values of the individual blocks. In this manner, a consumer can construct appropriately complex event-discrimination filters.
The following diagram illustrates the logical representation of an event-notification filter:
EVENT NOTIFICATION FILTER STRUCTURE
____________ ______________ _______________ _______________
_ HEADER _ _ _ _ _
_ _ BLOCK _ ___> _ _______> _ _
_ ______________ _ _ _ _
LOGICAL _ _ _ _ _ _
AND _SELECTION _ _ SELECTION _ _ SELECTION _
_ _ CRITERIA _ _ CRITERIA _ _ CRITERIA _
_ _ SUBBLOCK _ _ BLOCK _ _ BLOCK _
_ ______________ _ _ _ _
_ _ _ _ _ _ _
_ _ . _ _ _ _ _
_ _ . _ _ _ _ _
_ _ . _ _ _ _ _
_ ______________ _ _ _ _
_ _ SELECTION _ _ _ _ _
_ _ CRITERIA _ _ _ _ _
_ _ SUBBLOCK _ _ _ _ _
_ _ _ _ _ _
___________ ______________ _______________ _______________
_ _
_ <________________ LOGICAL ________________> _
_ OR _
_ _
The library LFAPI.LIB must be linked with object files that use LogOpenEventNotification
Example Code
#define INCL_LOGGING #include <os2.h> #include <lfdef.h> ULONG service; PVOID pOpenEventNotification; APIRET rc; rc = LogOpenEventNotification(service, pOpenEventNotification);
The following example opens error-logging event notification. It will initialize an event-notification filter that specifies any Error Log entry that has a product manufacturer named "IBM" and a severity less than 4.
#define INCL_LOGGING
#include <unidef.h>
#include <os2.h>
#include <stdio.h>
#include <lfdef.h>
#define ERROR_LOG_FILE_ID 1
ULONG service;
ULONG severity = 4;
ULONG entry_id = 12;
LOENREQUEST open_event_packet;
HLOGNOTIFY log_notify;
SUBBLOCK subblock1, subblock2, subblock3;
HEADERBLOCK headerblock1, headerblock2;
FILTERBLOCK filter;
UniChar *manufacturer_name = L"IBM";
service = ERROR_LOGGING_SERVICE;
/* Construct an event notification filter with 2 header blocks. */
/* The first header block points to a single subblock. */
/* The second header block points to a chain of two subblocks. */
filter.packet_size = sizeof(FILTERBLOCK);
filter.packet_revision_number = LF_UNI_API;
filter.header_block = &headerblock1;
/*-------------construct headerblock1---------------------*/
headerblock1.pSubblock = &subblock1;
headerblock1.pNextBlock = &headerblock2;
/*construct subblock1 of headerblock1*/
subblock1.entry_attribute_ID = LOG_ERROR_DMI_VENDOR_TAG;
subblock1.comparison_operator = LOG_ERROR_EQUAL;
subblock1.comparison_data_ptr = &manufacturer_name;
subblock1.next_subblock = NULL;
/*------------construct headerblock2----------------------*/
headerblock2.pSubblock = &subblock2;
headerblock2.pNextBlock = NULL;
/*construct subblock2 of headerblock2*/
subblock2.entry_attribute_ID = LOG_ERROR_SEVERITY;
subblock2.comparison_operator = LOG_ERROR_LESS_THAN;
subblock2.comparison_data_ptr = severity;
subblock2.comparison_data_length = sizeof(ULONG);
subblock2.next_subblock = &subblock3;
/*construct subblock3 of headerblock2*/
subblock3.entry_attribute_ID = LOG_ERROR_ENTRY_ID;
subblock3.comparison_operator = LOG_ERROR_GREATER_THAN;
subblock3.comparison_data_ptr = entry_id;
subblock3.comparison_data_length = sizeof(ULONG);
subblock3.next_subblock = null;
/* Construct the LogOpenEventNotification parameter packet.*/
open_event_packet.packet_size = sizeof(LOENREQUEST);
open_event_packet.packet_revision_number = LF_UNI_API;
open_event_packet.log_file_ID = ERROR_LOG_FILE_ID;
open_event_packet.pLogNotify = &log_notify;
open_event_packet.pFilter = &filter;
open_event_packet.read_flags = 0;
rc = LogOpenEventNotification(service, /*service*/
&open_event_packet); /*parameter packet*/
if (rc |= 0)
{
printf("LogOpenEventNotification error: return code = %d",rc);
return;
}