Embedded Event Manager Configuration Guide, Cisco IOS XE Release 3SE (Catalyst 3850 Switches)
EEM 3.2 Event Tcl Command Extensions
Downloads: This chapterpdf (PDF - 89.0KB) The complete bookPDF (PDF - 1.9MB) | The complete bookePub (ePub - 1.1MB) | Feedback

EEM 3.2 Event Tcl Command Extensions

EEM Event Tcl Command Extensions

Last Updated: December 29, 2012

The following conventions are used for the syntax documented on the Tcl command extension pages:

  • An optional argument is shown within square brackets, for example:

[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:

Router#
01:00:44: %SYS-5-CONFIG_I: Configured from console by consoleclear counters
Clear "show interface" counters on all interfaces [confirm]
Router#
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
Router#
Router#clear counters
Clear "show interface" counters on all interfaces [confirm]
Router#
Router#
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
Router#clear counters
Clear "show interface" counters on all interfaces [confirm]
Router#
Router#
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
Router#
Router#
Router#clear counters
Clear "show interface" counters on all interfaces [confirm]
Router#
01:00:59: %CLEAR-5-COUNTERS: Clear counter on all interfaces by console
Router#
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
Router#
Router#
Router#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)
Router#
Router#configure terminal
Enter configuration commands, one per line.  End with CNTL/Z.
Router(config)#no event manager policy high_perf_example.tcl
Router(config)#event manager po high_perf_example.tcl
Router(config)#end
Router#
Router#
Router#
Router#
01:02:19: %SYS-5-CONFIG_I: Configured from console by consoleclear counters
Clear "show interface" counters on all interfaces [confirm]
Router#
01:02:23: %CLEAR-5-COUNTERS: Clear counter on all interfaces by console
Router#
Router#
01:02:23: %HA_EM-6-LOG: high_perf_example.tcl: event 1 serviced
Router#
Router#clear counters
Clear "show interface" counters on all interfaces [confirm]
Router#
Router#
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
Router#
Router#clear counters
Clear "show interface" counters on all interfaces [confirm]
Router#
Router#
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
Router#
Router#clear counters
Clear "show interface" counters on all interfaces [confirm]
Router#
Router#
01:02:33: %CLEAR-5-COUNTERS: Clear counter on all interfaces by console
Router#
01:02:33: %HA_EM-6-LOG: high_perf_example.tcl: event 4 serviced
Router#
Router#clear counters
Clear "show interface" counters on all interfaces [confirm]
Router#
Router#
Router#
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
Router#

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:

Router#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.

© 2012 Cisco Systems, Inc. All rights reserved.