- Read Me First
- Embedded Event Manager Overview
- Writing Embedded Event Manager Policies Using the Cisco IOS CLI
- Writing Embedded Event Manager Policies Using Tcl
- Signed Tcl Scripts
- EEM Action Tcl Command Extension
- EEM CLI Library Command Extensions
- EEM CLI Library XML-PI Support
- EEM Context Library Command Extensions
- EEM Event Registration Tcl Command Extensions
- EEM Event Tcl Command Extensions
- EEM Library Debug Command Extensions
- EEM Multiple Event Support Tcl Command Extensions
- EEM SMTP Library Command Extensions
- EEM System Information Tcl Command Extensions
- EEM Utility Tcl Command Extensions
Contents
EEM Event Tcl Command Extensions
The following conventions are used for the syntax documented on the Tcl command extension pages:
[type ?]
A question mark ? represents a variable to be entered.
Choices between arguments are represented by pipes, for example:
priority low|normal|high
 Note | For all EEM Tcl command extensions, if there is an error, the returned Tcl result string contains the error information. |
Note | Arguments for which no numeric range is specified take an integer from -2147483648 to 2147483647, inclusive. |
event_completion
Sends a notification to the EEM server that the policy is done servicing the event that triggered it. The event only takes a single argument which is the return_code of this event instance.
Syntax
event_completion status ?
Arguments
|
status |
(Mandatory) Exit status (return_code) of this event instance. A value of zero indicates no error and any other integer value indicates an error. |
Result String
None
Set _cerrno
No
event_completion_with_wait
The event_completion_with_wait command combines the two commands event_completion and event_wait into a single command for ease of use.
The event_completion command sends a notification to the EEM server that the policy is done servicing the event that triggered it. The event only takes a single argument which is the return_code of this event instance.
The event_wait places the Tcl policy into a sleep state. When the Tcl policy receives a new signal announcing a new event, the policy is placed into a wake state and again returns to a sleep state. This loop continues. If event_wait policy is invoked before event_completed policy, an error results and the policy exits.
Syntax
event_completion_with_wait status ? [refresh_vars]
Arguments
|
status |
(Mandatory) exit_status (return_code) of this event instance. A value of zero indicates no error. Any other integer value indicates an error. |
|
refresh_vars |
(Optional) Indicates whether built-in and environment variables should be updated (refreshed) from the EEM Policy Director during this event instance. |
Result String
None
Set _cerrno
Yes
Sample Usage
Here is a similar example as above using this single command:
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
set i 1
while {1 == 1} { # Start high performance policy loop
array set arr_einfo [event_reqinfo]
if {$_cerrno != 0} {
set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \
$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]
error $result
}
action_syslog msg "event $i serviced" priority info
if {$i == 5} {
action_syslog msg "Exiting after servicing 5 events" priority info
exit 0
}
incr i
array set _event_state_arr [event_completion_with_wait status 0 refresh_vars 1]
if {$_event_state_arr(event_state) != 0} {
action_syslog msg "Exiting: failed event_state " \
" $event_state_arr(event_state)" priority info
exit 0
}
}
Note | The running configuration output is the same as the event_publishTcl command. |
event_publish
Publishes an application-specific event.
Syntax
event_publish sub_system ? type ? [arg1 ?] [arg2 ?] [arg3 ?] [arg4 ?]
Arguments
|
sub_system |
(Mandatory) Number assigned to the EEM policy that published the application-specific event. Number is set to 798 because all other numbers are reserved for Cisco use. |
|
type |
(Mandatory) Event subtype within the specified component. The sub_system and type arguments uniquely identify an application event. Must be an integer between 1 and 4294967295, inclusive. |
|
[arg1 ?]-[arg4 ?] |
(Optional) Four pieces of application event publisher string data. |
Result String
None
Set _cerrno
Yes
(_cerr_sub_err = 2) FH_ESYSERR (generic/unknown error from OS/system)
This error means that the operating system reported an error. The POSIX errno value that is reported with the error should be used to determine the cause of the operating system error.
Sample Usage
This example demonstrates how to use the event_publish Tcl command extension to execute a script n times repeatedly to perform some function (for example, to measure the amount of CPU time taken by a given group of Tcl statements). This example uses two Tcl scripts.
Script1 publishes a type 9999 EEM event to cause Script2 to run for the first time. Script1 is registered as a none event and is run using the Cisco IOS CLI event manager run command. Script2 is registered as an EEM application event of type 9999, and this script checks to see if the application publish arg1 data (the iteration number) exceeds the EEM environment variable test_iterations value. If the test_iterations value is exceeded, the script writes a message and exits; otherwise the script executes the remaining statements and reschedules another run. To measure the CPU utilization for Script2, use a value of test_iterations that is a multiple of 10 to calculate the amount of average CPU time used by Script2.
To run the Tcl scripts, enter the following Cisco IOS commands:
configure terminal event manager environment test_iterations 100 event manager policy script1.tcl event manager policy script2.tcl end event manager run script1.tcl
The Tcl script Script2 will be executed 100 times. If you execute the script without the extra processing and derive the average CPU utilization, and then add the extra processing and repeat the test, you can subtract the former CPU utilization from the later CPU utilization to determine the average for the extra processing.
Script1 (script1.tcl)
::cisco::eem::event_register_none
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
# Query the event info.
array set arr_einfo [event_reqinfo]
if {$_cerrno != 0} {
set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \
$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]
error $result
}
action_syslog priority info msg "EEM application_publish test start"
if {$_cerrno != 0} {
set result [format \
"component=%s; subsys err=%s; posix err=%s;\n%s" \
$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]
error $result
}
# Cause the first iteration to run.
event_publish sub_system 798 type 9999 arg1 0
if {$_cerrno != 0} {
set result [format \
"component=%s; subsys err=%s; posix err=%s;\n%s" \
$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]
error $result
}
Script2 (script2.tcl)
::cisco::eem::event_register_appl sub_system 798 type 9999
# Check if all the required environment variables exist.
# If any required environment variable does not exist, print out an error msg and quit.
if {![info exists test_iterations]} {
set result \
"Policy cannot be run: variable test_iterations has not been set"
error $result $errorInfo
}
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
# Query the event info.
array set arr_einfo [event_reqinfo]
if {$_cerrno != 0} {
set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \
$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]
error $result
}
# Data1 contains the arg1 value used to publish this event.
set iter $arr_einfo(data1)
# Use the arg1 info from the previous run to determine when to end.
if {$iter >= $test_iterations} {
# Log a message.
action_syslog priority info msg "EEM application_publish test end"
if {$_cerrno != 0} {
set result [format \
"component=%s; subsys err=%s; posix err=%s;\n%s" \
$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]
error $result
}
exit 0
}
set iter [expr $iter + 1]
# Log a message.
set msg [format "EEM application_publish test iteration %s" $iter]
action_syslog priority info msg $msg
if {$_cerrno != 0} {
set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \
$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]
error $result
}
# Do whatever processing that you want to measure here.
# Cause the next iteration to run. Note that the iteration is passed to the
# next operation as arg1.
event_publish sub_system 798 type 9999 arg1 $iter
if {$_cerrno != 0} {
set result [format \
"component=%s; subsys err=%s; posix err=%s;\n%s" \
$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]
error $result
}
event_wait
Places the Tcl policy into a sleep state. When the Tcl policy receives a new signal announcing a new event, the policy is placed into a wake state and again returns to a sleep state. This loop continues. If event_wait policy is invoked before event_completed policy, an error results and the policy exits.
Syntax
event_wait [refresh_vars]
Arguments
|
refresh_vars |
(Optional) Indicates whether built-in and environment variables should be updated (refreshed) from the EEM Policy Director during this event instance. |
Result String
None
Set _cerrno
No
Sample Usage
The event_wait event detector returns an array type value with a single element named event_state. Event_state is a value sent back from the EEM Server indicating whether or not an error has occurred in processing the event. An example of an error here would be if the user configured event_wait before configuring event_completion when handling the event instance.
The following sample output shows the use of both event_completion and event_waitTcl commands:
::cisco::eem::event_register_syslog tag e1 occurs 1 pattern CLEAR maxrun 0
namespace import ::cisco::eem::*
namespace import ::cisco::lib::*
set i 1
while {1 == 1} { # Start high performance policy loop
array set arr_einfo [event_reqinfo]
if {$_cerrno != 0} {
set result [format "component=%s; subsys err=%s; posix err=%s;\n%s" \
$_cerr_sub_num $_cerr_sub_err $_cerr_posix_err $_cerr_str]
error $result
}
action_syslog msg "event $i serviced" priority info
if {$i == 5} {
action_syslog msg "Exiting after servicing 5 events" priority info
exit 0
}
incr i
event_completion status 0
array set _event_state_arr [event_wait refresh_vars 0]
if {$_event_state_arr(event_state) != 0} {
action_syslog msg "Exiting: failed event_state " \
" $event_state_arr(event_state)" priority info
exit 0
}
}
Here is an example of the running configuration:
Device# 01:00:44: %SYS-5-CONFIG_I: Configured from console by consoleclear counters Clear "show interface" counters on all interfaces [confirm] Device# 01:00:49: %CLEAR-5-COUNTERS: Clear counter on all interfaces by console 01:00:49: %HA_EM-6-LOG: high_perf_example.tcl: event 1 serviced Device# Device#clear counters Clear "show interface" counters on all interfaces [confirm] Device# Device# 01:00:53: %CLEAR-5-COUNTERS: Clear counter on all interfaces by console 01:00:53: %HA_EM-6-LOG: high_perf_example.tcl: event 2 serviced Device#clear counters Clear "show interface" counters on all interfaces [confirm] Device# Device# 01:00:56: %CLEAR-5-COUNTERS: Clear counter on all interfaces by console 01:00:56: %HA_EM-6-LOG: high_perf_example.tcl: event 3 serviced Device# Device# Device#clear counters Clear "show interface" counters on all interfaces [confirm] Device# 01:00:59: %CLEAR-5-COUNTERS: Clear counter on all interfaces by console Device# 01:00:59: %HA_EM-6-LOG: high_perf_example.tcl: event 4 serviced 01:00:59: %HA_EM-6-LOG: high_perf_example.tcl: Exiting after servicing 5 events Device# Device# Device#copy tftp disk1: Address or name of remote host [dirt]? Source filename [user/eem_scripts/high_perf_example.tcl]? Destination filename [high_perf_example.tcl]? %Warning:There is a file already existing with this name Do you want to over write? [confirm] Accessing tftp://dirt/user/eem_scripts/high_perf_example.tcl... Loading user/eem_scripts/high_perf_example.tcl from 192.0.2.19 (via FastEthernet0/0): ! [OK - 909 bytes] 909 bytes copied in 0.360 secs (2525 bytes/sec) Device# Device#configure terminal Enter configuration commands, one per line. End with CNTL/Z. Device(config)#no event manager policy high_perf_example.tcl Device(config)#event manager po high_perf_example.tcl Device(config)#end Device# Device# Device# Device# 01:02:19: %SYS-5-CONFIG_I: Configured from console by consoleclear counters Clear "show interface" counters on all interfaces [confirm] Device# 01:02:23: %CLEAR-5-COUNTERS: Clear counter on all interfaces by console Device# Device# 01:02:23: %HA_EM-6-LOG: high_perf_example.tcl: event 1 serviced Device# Device#clear counters Clear "show interface" counters on all interfaces [confirm] Device# Device# 01:02:26: %CLEAR-5-COUNTERS: Clear counter on all interfaces by console 01:02:26: %HA_EM-6-LOG: high_perf_example.tcl: event 2 serviced Device# Device#clear counters Clear "show interface" counters on all interfaces [confirm] Device# Device# 01:02:29: %CLEAR-5-COUNTERS: Clear counter on all interfaces by console 01:02:29: %HA_EM-6-LOG: high_perf_example.tcl: event 3 serviced Device# Device#clear counters Clear "show interface" counters on all interfaces [confirm] Device# Device# 01:02:33: %CLEAR-5-COUNTERS: Clear counter on all interfaces by console Device# 01:02:33: %HA_EM-6-LOG: high_perf_example.tcl: event 4 serviced Device# Device#clear counters Clear "show interface" counters on all interfaces [confirm] Device# Device# Device# 01:02:36: %CLEAR-5-COUNTERS: Clear counter on all interfaces by console 01:02:36: %HA_EM-6-LOG: high_perf_example.tcl: event 5 serviced 01:02:36: %HA_EM-6-LOG: high_perf_example.tcl: Exiting after servicing 5 events Device#
Also while an event has been serviced and is waiting for the next event to come in show event manager policy active command will display the following output:
Device#show event manager policy active
Key: p - Priority :L - Low, H - High, N - Normal, Z - Last
s - Scheduling node :A - Active, S - Standby
default class - 1 script event
no. job id p s status time of event event type name
1 11 N A wait Mon Oct20 14:15:24 2008 syslog high_perf_example.tcl
In the above example the status is wait. This indicates that the policy is waiting for the next event to come in.