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

Parameter	Definition
Filter:
start-time	time endpoint that specifies the oldest event timestamp that is valid for the remote event queryValid 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 queryValid 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 queryValid Values O OPEN A ACKNOWLEDGED C CLOSED E ESCALATED D DELETEDExamples "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 queryValid Values I INFORMATION S CHANGE_STATUS E ERROR W WARNING A ALARM R RESPONSEExamples "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"
);