event_query()

Return a list of events in the PATROL Event Manager (PEM) repository that match specified filter criteria.

Syntax

event_query(maxcount, delimiter, format,[start-time],
[stop-time],[status],[type],[node],[origin],
[pattern],[IDrange],[class],[severity])

Parameters

Parameter

Definition

maxcount

string that is the maximum number of events that will be returned in the event query Specifying "" (null string) causes maxcount to default to 100.

delimiter

string that is used to separate each event in the list of events returned by the event query*Valid Values*

  • "" indicating that a newline character \n will separate the entries.
  • any valid characters including PSL string literals. For more information, see PSL-String-Literals.

format

format string used to present each event entry*Default* 
"" is equivalent to the string "%s %s %s %s %s %s %s %s\n" where the eight strings are returned in the following order:

  • event ID assigned by the PEM
  • event status
  • event type
  • event timestamp
  • host name that produced the event
  • application class or instance that produced the event
  • text string from the event description field
  • text string from the event diary field

For details, see Specifying the event_query() Output Format .

FILTER:

start-time

time endpoint that specifies the oldest event timestamp that is valid for the event query*Valid Values*

  • " " indicating January 1, 1970 at 00:00:00
  • PSL backward compatible: MMddhhmm [ yy ]
  • RFC-822: day date month year hh:mm:ss
  • Unix: day month date hh:mm:ss year
  • PSL date(): day month date hh:mm:ss year

The variables have the following values: 
day --Sun Mon Tue Wed Thu Fri Sat 
MM --01 to 12 
month --Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec 
dd or date --01 to 31 
hh --00 to 23 
mm and ss --00 to 59 
year --1902 to 2037 
[ yy ]--00 to 99 (19 yy is assumed) In the PSL compatibility format the current year is used when yy is omitted.

stop-time

time endpoint that specifies the most recent event timestamp that is valid for the event query Valid Values

  • " " indicating all event timestamps in the repository
  • PSL backward compatible: MMddhhmm [ yy ]
  • RFC-822: day date month year hh:mm:ss
  • Unix: day month date hh:mm:ss year
  • PSL date(): day month date hh:mm:ss year

The variables have the following values: 
day --Sun Mon Tue Wed Thu Fri Sat 
MM --01 to 12 
month --Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec 
dd or date --01 to 31 
hh --00 to 23 
mm and ss --00 to 59 
year --1902 to 2037 
[ yy ]--00 to 99 (19 yy is assumed) In the PSL compatibility format the current year is used when yy is omitted.

status

event statuses to be matched for the event query. 

Valid Values 
O OPEN 
A ACKNOWLEDGED 
C CLOSED 
E ESCALATED 
D DELETED*Examples*

  • "O,A,C,D" matches all statuses except ESCALATED
  • "O,A,C,E,D" or " " matches all statuses
  • "O,C" matches only statuses OPEN and CLOSED

type

event types to be matched for the event query

*Valid Values* 
I INFORMATION 
S CHANGE_STATUS 
E ERROR 
W WARNING 
A ALARM 
R RESPONSE*Example*

  • "S,E,W,A,R" matches all event types except INFORMATION
  • "I,S,E,W,A,R" or "" matches all event types
  • "W,A" matches only event types WARNING and ALARM

node

computer system name to be matched by the event query. Because events in the Agent's repository all apply to the local node, the node argument is ignored.

Valid Values

  • "" or any character string (value will be ignored)

origin

application instance or class name that is valid for the event query

Valid Values

  • "" for all application classes
  • character string or expression indicating the object to be matched (application class, application instance, and/or parameter). In some cases, events do not originate from a namespace object, and the origin listed is the hostname of the machine. The origin may be matched by object match, wildcard, or regular expression. See Matching Strings in Event Queries

description

character string within the event description field that is valid for the event query*Valid Values*

  • "" indicating any description
  • character string or expression indicating description to be matched. The description may be matched by substring, wildcard, or regular expression. See Matching Strings in Event Queries.

IDrange

string that defines the range of PATROL event IDs that are valid for the event query

*Valid Values* 

x event ID x
x/y event IDs between and including x and y
-/y event IDs less than and including y
x/- event IDs greater than and including x
-/- all events
x and y are integers in the following ranges:
0 ≤ x ≤ y ≤ 2,147,483,647

class

event class that is valid for the event query

*Valid Values*

  • "" indicating all event classes
  • character string specifying a specific event class. The pattern may be matched by substring, wildcard, or regular expression. See Matching Strings in Event Queries.

severity

lowest event severity that is valid for the event archival

*Valid Values*

  • string containing an integer between 1 and 5 with 5 being the most severe
  • " " indicating that events with a severity of 2, 3, 4, and 5 are returned, and events with a severity of 1 are not returned

Note

When the two digit year, yy, is specified with the PSL compatible time format for the start-time and stop-time parameters, the function assumes the year is 19 yy. You should either omit the year when using this format, or use a different date format if you need to specify the year.

Description

The event_query() function returns a list of up to maxcount events found in the PATROL Agent PATROL Event Manager repository that matched the filter criteria. The returned list is formatted as specified by format . 

The event_query() function returns the NULL string if no events were found in the event repository that match the filter criteria.

Matching Strings in Event Queries

Several methods may be used to specify string matches for event queries.

Substring Match

For the description and class fields, the specified query string will match if it is contained in the corresponding field of the event. For example, query string "App"would match "RegApp", "UpdAppState", "WorstApp", etc.

Note

 

Including a wildcard character means that the match will be treated as a wildcard match, and thus any unmatched characters must be accounted for by wildcards. So for example, while either "App" or "App" will match"UpdAppState", the query strings "App*" or "*App" will not.

Object Match

When specifying and exact object name, subordinate objects will also be matched. This applies to the origin field. The origin field does not perform other sorts of substring matches. For example, query string "APPLICATION" would match"APPLICATION","APPLICATION.Instance","APPLICATION.Instance.Parameter", etc. However "APPL" will match none of these, because the entire name of the parent object is not provided.

Wildcard Match

The description, class, and origin fields allow matches based on simple wildcards using the wildcard character "". This character will match 0 or more characters of any kind in determining the match. When performing a wildcard match, wildcards must account for all characters that are not found in the correspoding event field. For example, "*App" will match "UpdAppState", but"App*" or "*App" will not.

Note

 

Wildcard matches are retained for compatibility reasons, but may become deprecated at some time in the future. BMC Software recommends using the more powerful and flexible regular expression matches instead.

Regular Expression Match

The description, class, and origin fields allow matching by regular expressions. To indicate that a regular expression is being used, the search string is surrounded by "/" characters.

 

/regular_expression/

To negate a regular expression, that is, to return items that do not match the regular expression, the search string is surrounded by "/" characters and preceded by the character "^".

 

^/regular_expression/

To avoid substring matching, specify a regular expression with the standard beginning-of-line ( "^" ) and end-of-line ( "$" ) metacharacters. For example, to match class 9 but not class 39 or 91, use the expression:/^9$/

Specifying More than One String to Match

The description, class, and origin fields may supply more than one string to be matched. Fields that match any of the of the supplied strings will be included with the query set. To separate the strings, use an escaped newline character, "\n".

 

string1\nstring2\nstring3

Specifying the event_query() Output Format

The event_query() function format parameter is similar to the specification string used for the standard C library printf() function. The format parameter can contain alphanumeric characters for use as titles and field names, and string literals for spacing, tabbing, and carriage control. 

PATROL macro variables within the format parameter identify the fields that the event_query() function returns. The following table describes the macro variables available to the event_query() function.

 event_query() Function Macro Variables 

PEM Macro

Definition

%{EV_ACK_TEXT}

text string from the acknowledge command of this event catalog and class

%{EV_ARG1}

PATROL Event Manager first dynamic argument

%{EV_ARG2}

PATROL Event Manager second dynamic argument

%{EV_ARGS}

character string that presents the event arguments separated by tab characters ( \t )

%{EV_CATALOG}

name of the PATROL event catalog to which the event belongs

%{EV_CLASS_NAME}

name of the PATROL event class within the PATROL event catalog to which the event belongs

%{EV_CTG_DESC}

text string from the description of this event catalog and class

%{EV_DESC}

text string description that was produced for the event

%{EV_DIARY}

text string that was entered into the diary for the event

%{EV_ESCL_TEXT}

text string from the escalation command of this event catalog and class

%{EV_EXPECTANCY}

life expectancy and disposition of the event.

Valid Values 
STORED 
DEL_IF_CLOSED 
DEL_IF_INFO 
DO_NOT_STORE

%{EV_EXPERT_ADVICE}

text string from the expert advice of this event catalog and class

%{EV_HANDLER}

user ID of the person who performed the last acknowledge, close, or delete action on the event

%{EV_ID}

sequential integer identifier assigned by the PATROL Event Manager upon receipt of the event

%{EV_NAME}

name of the event within the PATROL event class

%{EV_NODE}

host name that produced the event

%{EV_NOTIFY_TEXT}

text string from the notification command of this event catalog and class

%{EV_NSEVERITY}

numeric severity of the event. Event severity is predefined for all event classes in the STANDARD catalog

%{EV_ORIGIN}

application instance or class that produced the event.

%{EV_OWNER}

user ID that owns the event

*Default* 
PATROL account user ID.

%{EV_SNMP_SUPPORT}

text string from the SNMP support of this event catalog and class

*Valid Values* 
NO_TRAP 
SEND_TRAP

%{EV_STATUS}

event status

*Valid Values* 
OPEN 
ACKNOWLEDGED 
CLOSED 
ESCALATED 
DELETED

%{EV_TIME}

time stamp indicating the system clock time at the moment the event was produced 
The timestamp is a 24-character string with the following format: 
Sun Sep 16 01:03:52 1973

%{EV_TYPE}

event type

*Valid Values* 
INFORMATION 
STATE_CHANGE 
ERROR 
WARNING 
ALARM 
RESPONSE

Example

The following is an example of the event_query() function:

print("The result of the query\n\n" .
event_query(
"100", # return a maximum of 100 events
"\n\n", # use two newline characters to separate each event
# return ID, type, and description
"event id: %{EV_ID}\nevent type: %{EV_TYPE}\nevent
description: %{EV_DESC}\n",
# filter definition starts here:
"", # any start time
"", # any stop time
"O", # only OPEN status
"A,W", # only ALARM and WARNING types
"", # any node
"", # any origin
"", # match any description text
"-/-", # match any event ID
"", # match any event class
"" # match any event severity
)
. "\n"
);