Documentation

Triggers

Trigger exampleA Trigger allows you to execute a script based upon the text received from the server. TeSSH supports a simple pattern matching syntax, along with powerful regular expression patterns. TeSSH also supports multiple trigger states for very advanced scripting. A Trigger Pattern Wizard is included to make it easier to create trigger patterns and test to see what text from the server they match.

Triggers are one of the most powerful and important features within TeSSH. A Trigger contains a Pattern and a Script. When the text received from the server matches the Pattern, then the Script is executed. Triggers are sometimes also called Actions.

Triggers allow you to automate common actions on your server. They can also bring your attention to important text from the server:

#TRIGGER {error} {#COLOR red}

could be used to match the text "error" received from the server and immediately execute the script "#COLOR red"which would highlight the line in red to draw your attention to it.

Wildcards

Just matching specific text from the server is nice, but sometimes the text from the server varies depending upon the situation. For example, let's say you only want to respond to a certain kind of error.  Perhaps the server displays a status message like this:

Status: error

Now, if we had to create a different trigger for every different status, that wouldn't be very efficient. In TeSSH, you can use a variety of Pattern Matching characters within your pattern. For example, the %w wildcard will match any word. So you could create a trigger like this:

#TRIGGER {Status: %w} {do something}

But how do we give the script access to the text that was matched?  Any "subpattern" can be saved to one of the %1..%99 argument variables by simply placing parenthesis around the part of the pattern you want to save. In the above example, we would put parenthesis around the %w to save the matched text into %1 and then use %1 in our script:

#TRIGGER {Status: (%w)} {#IF (%1 = "error") {do something}}

TeSSH counts the ( parenthesis to determine the %1..%99 number that the matched text should be stored. You can even nest () within each other to save complex subpatterns.

You can also save matched text to Named subpatterns. Simply place the $name: just after the (. For example:

#TRIGGER {Status: ($stat:%w)} {#IF ($stat = "error") {do something}}

The named subpattern must start with a $ character (because it actually creates a Local variable). And there must not be any space between the ( and the $ characters.

Instead of using the TeSSH pattern matching wildcard characters, you can also use normal Perl Regular Expressions. Simply select the Regular Expression option in the Advanced panel of the Edit Triggers screen, or use the #REGEX command instead of the #TRIGGER command to define the trigger on the command line. There is an excellent Regular Expressions Information site on the Internet where you can learn about the power of these kinds of patterns. However, in general a TeSSH Pattern will be easier to understand than a Regular Expression. But since TeSSH Patterns are compiled into regular expressions, they both have the same speed within TeSSH.

Temporary Triggers

A Temporary Trigger is only executed once and then deleted.  To create a one-shot temporary trigger from the command line, use the #TEMP command.  For example:

#TEMP {Error} {#CW red}

would fire the first time a line containing "Error" is received from the server, but once it fires the trigger would then be deleted.  Temporary triggers are also not saved to your session settings.

Command Line Triggers

In addition to triggering from text received from the server, you can also create a trigger that matches the text entered into the Command Line.  Using a "prompt" command line trigger you can even intercept the command line before TeSSH attempts to parse it for scripting commands.

To create a Command Line trigger from the command line, use the #ONINPUT command:

#ONINPUT {^lss$} {ls -al}

In a way, Command Line triggers work like Aliases.  However, the powerful regular expression pattern matching available within triggers provides more power than simple aliases can.

Telnet Triggers

The Telnet protocol supports various "telnet options" and a mechanism for sending data via these options.  A Telnet trigger fires when a specific telnet option request (WILL/WONT) or option data (IAC SB) are received.  This allows you to implement server-specific protocols that are not built directly into TeSSH.

Expression Triggers

Rather than matching specific text, an Expression Trigger tests the value of a given boolean expression and executes the script when the expression changes value and becomes true.  Rather than continuously polling an expression, Expression Triggers are optimized to only test the pattern when a variable used within the pattern changes values.

To create an expression trigger on the command line, replace the {pattern} with (expression).  For example:

#TRIGGER (@varname > 0) {do something}

will execute the script when the value of @varname becomes positive.

Timers and Alarms

Using an Alarm pattern allows a trigger to fire at a specific time, or at periodic intervals.  This feature allows you to build an automatted testing package that periodically sends commands to the server and deals with the returned results.

To create an alarm from the command line, replace the normal text pattern with a time pattern.  For example, to execute a set of commands ten seconds from now you could do this:

#ALARM +10 {do this in ten seconds}

Add comment

Login or register to post comments