remote_event_query()

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

Syntax

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

Parameter

Parameter

Definition

sessionID

identifier of the remote PATROL Agent session to which the remote event query is directed The sessionID is returned by the remote_open() function when you open a remote PATROL Agent session.

maxcount

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

timeout

string that is the maximum time in minutes that the session is willing to wait for the results of the remote event query

delimiter

string that is used to separate each event in the list of events returned by the remote 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 See Specifying the event_query() Output FormatSpecifying the event_query() Output Format .

Default 
" " is equivalent to the string "%s %s %s %s %s %s %s %s\n" where the eight strings returned are (in 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
ParameterDefinition
Filter:
start-time

time endpoint that specifies the oldest event timestamp that is valid for the remote 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 start-time 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 remote 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 start-time 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 status that is valid for the remote 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 type that is valid for the remote event query*Valid Values* 
I INFORMATION 
S CHANGE_STATUS 
E ERROR 
W WARNING 
A ALARM 
R RESPONSE*Examples*

  • "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 that is valid for the remote event query 

Valid Values 
" " indicating all computer systems listed in the PEM repository or a host name character string

origin

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

Valid Values
" " for all application classes or a character string indicating a specific application instance or class

pattern

character string within the event description field that is valid for the remote event query

Valid Values
" " indicating any characters or a character string

IDrange

string that defines the range of PATROL event IDs that are valid for the remote 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 
where x and y are integers such that 
0 ≤ x ≤ y ≤ 2,147,483,647

class

event class that is valid for the remote event query

Valid Values
" " indicating all event classes or a character string specifying a specific event class

severity

string containing the integer event severity that is valid for the remote event query. Optional parameter.

Valid Values 
" " for all event severities or an integer from 1-5 (5 being most severe) indicating a minimum severity

Description

The remote_event_query() function returns a list of up to maxcount events found in the remote PATROL Agent Event Manager repository that match the filter criteria. The session to the remote PATROL Agent is identified by sessionID. The returned events are formatted as specified by format. 

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

 

Specifying the remote_event_query() Output Format

The remote_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 remote_event_query() function returns. The following table describes the macro variables available to the remote_event_query() function.

Example

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

print(
"The result of the remote query\n",
remote_event_query(
mysession, # session handle returned by remote_open
"100", # return a maximum of 100 events
"1", # call will time out in one minute
"\n\n", # separate each event with two newline characters
# event output format
"event ID: %{EV_ID}\nevent type: %{EV_TYPE}\n".description: %{EV_DESC}",
"", # event filter: any start time
"", # event filter: any end time
"O", # event filter: only OPEN status
"A,W", # event filter: only ALARM AND WARNING states
"", # event filter: any node
"ORACLE", # event filter: ORACLE as an originating application
"", # event filter: any pattern in the event description
"-/-", # event filter: all events regardless of ID range
"" # event filter: any event class
)
. "\n"
);


Was this page helpful? Yes No Submitting... Thank you

Comments