Important

   

This documentation space contains information about PATROL Agents when deployed in a TrueSight Operations Management environment. If you are a BMC Helix Operations Management user, see PATROL Agent 22.3.01 for BMC Helix Operations Management. Open link

event_archive()

Archive PATROL events that match the specified filter criteria.

Syntax

event_archive(filename,operation,[separator],[format],
[start-time],[stop-time],[status],[type],[node],
[origin],[pattern],[IDrange],[class],
[severity],[max-count])

Parameters

ParameterDefinition
filename

string that is the name of the file where the archived events are written
If the file name begins with a path separator (/ or \ depending on the OS), the event_archive() function assumes that the path name is a full path name.
Otherwise, the event_archive() function assumes that the file name is a file in the $PATROL_HOME/log directory.

operation

string that specifies the file access used for archiving events

*Valid Values* 
W overwrite existing file contents (if any) 
A append to existing file contents (if any)

separatorcharacter string used to separate events in the archive file If " " is specified, the event_archive() function uses the newline character ( \n ) to separate events.
format

format string used to present each event entry See Specifying the event_query() Output Format .Default 
" " equivalent to "%s %s %s %s %s %s %s %s\n" where the following eight strings are returned 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
FILTER:
start-time

time endpoint that specifies the oldest event timestamp that is valid for the
event archival
Valid Values
" " indicating January 1, 1970 at 00:00:00 or one of the following strings:
■ 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
where the valid ranges of the arguments are:
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 (19yy 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 archival

*Valid Values* 
" " indicating all event time stamps in the repository or one of the following strings:

  • 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

where the valid ranges of the arguments are: 
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 event archival

*Valid Values* 
O OPEN 
A ACKNOWLEDGED 
C CLOSED 
E ESCALATED 
D DELETED 
For example:

  • "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 event archival

*Valid Values* 
I INFORMATION 
S CHANGE_STATUS 
E ERROR 
W WARNING 
A ALARM 
R RESPONSE 
For 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 that is valid for the event archival

*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 event archival

*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 event archival

*Valid Values* 
" " indicating any characters or a character string.

IDrange

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

*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
" " (empty string) 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 event archival

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

severity

lowest event severity that is valid for the event archival

*Valid Values* 
A string containing an integer between 1 and 5 with 5 being the most severe or " " indicating that all event severities.

max-count

maximum number of events to write to the file If more events are available than the max-count, the event_archive() function returns the string max count reached instead of the OK string. 

Default 
100

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_archive() function writes PATROL events that match the filter criteria from the PATROL event repository to filename using format and separator. The event_archive() function returns the string OK if successful, or the NULL string if not.

Example

The following example appends events matching the default event filter to the file*/tmp/myarchive* using a new-line separator:

 event_archive("/tmp/myarchive","A","","");



The following example overwrites the existing file $PATROL_HOME/log/myarchive with the event description text for events that match the default event filter, separated by new-line characters.

event_archive("myarchive","W","\n","%{EV_DESC}");

The following example overwrites the existing file $PATROL_HOME/log/myfile with events matching the specified filter. The event_archive() function uses the default separator and format.

event_archive(
"myfile",# archive file $PATROL_HOME/log/myfile
"A",# append events to existing file
"",# default separator
"",# default format
"",# any start time
"",# any stop time
"",# any status
"",# any type
"",# any node
"",# any origin
"",# any event description
"",# all event IDs
"",# any event class
"2"# event severity 2 or greater
);
Was this page helpful? Yes No Submitting... Thank you

Comments