Defining User Events

An Execute command output or a device session to configured test devices can be monitored for the occurrence of specified messages. When a matching message is received by either an Execute or a Watch script step, an event is triggered and processing for the event can be configured.

  • Local user events: Local events, which are only available inside a script step (local), can have an associated procedure (local or shared) that is executed when the event occurs.
  • Global user events: Global events, which are available to all script steps, are those defined in the User Events Catalog. Each global event can be configured with an associated procedure (local or shared) and an additional action that is performed when the event occurs – such as for example continuing with the current script step or advancing the execution to the next one.

A local procedure is a procedure that is defined within the script body. A shared procedure is an external procedure resource stored in the plugin's resources database.

Defining global user events and associating them with executed procedures and additional actions is done using the User Events Catalog.

To define global user events:

  1. Click the User Events button from the Test ribbon.
  2. In the User Events Catalog window that appears, click the button. A new global event definition entry is added.
  3. Click into the Procedure to Run column and select a procedure – local or shared – that is executed when the event occurs.
  4. If the procedure has parameters, each parameter can be assigned a predefined portion of the received message that triggered the event.

    To assign parameters:

    1. Click the button.
    2. In the window that appears, the Parameter name and Type fields are automatically populated with the appropriate value from the procedure definition.
    3. For the Value field select a predefined portion of the matching message, or a constant string:
      • <value of message>: The entire message string is assigned to the parameter.
      • <search result>: The matched expression is assigned to the parameter.
      • <constant value>: A constant user-defined value is assigned to the parameter.
  5. Define an additional action that is executed when the event occurs:
    • Continue with Current Step: If an associated procedure is configured, the procedure is launched and the script execution continues with the script step that triggered the event.
    • Proceed to Next Step: If an associated procedure is configured, the procedure is launched, a device terminator is sent, the event-triggering step is stopped, and the execution advances to the next script step.

    A device terminator is a control character sequence that is sent to a configured device in order to stop a continuous device output, such as for example that of a ping -t or tcpdump command. For information on configuring a device terminator, refer to Defining Terminal Settings.

  6. Define an event processing mode as either of the following:
    • Scheduled: When queued, processing of the current event is done as scheduled.
    • Prioritary: When queued, processing of the current event is done prioritary.

  The Execute (see Execute) and Watch (see Watch) steps, which monitor session and a command outputs respectively, are capable of triggering user events when a specified device output pattern is received. The triggered events are placed in a global (script-level) events queue, whose processing is done sequentially, in a separate thread.

  For each event processed, first a configured additional action is performed and then an event-associated procedure is executed. Upon completion of the procedure execution, the next event from the queue is processed.

  When configuring user events, pay special attention to select associated procedures that execute reasonably rapidly, such as to not excessively delay the processing of subsequent queued events. In the opposite case, for example when configuring a long procedure, the processing of subsequent queued events would be blocked for the procedure execution time and the script could possibly terminate before all queued events have had a chance of being processed.

  Special attention is also required for avoiding inconsistent device output monitoring, such as that illustrated by the case below:

  Assuming, for example, that we have an Execute command that generates continuous, multi-portion output, and that the command output is monitored for multiple expressions triggering multiple events, say E1 and E2.

  Given the continuous nature of the output, it could happen that at one moment an output portion matches one of the specified expressions and that the corresponding event, say E1, is triggered by this occurrence.

  Now, assuming that E1 is configured with the "Proceed with Next Step" additional action, it could happen that, while E1 is being processed, and before the Device Terminator is sent, another event, E2, is triggered. This would result in both events, E1 and E2, being processed, irrespective of E1's configured "Proceed with Next Step" option.