Documentation

Introduction to Triggers

Triggers can be tricky, but are also the most powerful feature of TeSSH. Triggers (sometimes called "actions") allow you to execute a command whenever a particular string of text is received from the server. While this sounds simple, it has powerful implications.

To define a trigger, you use the #TRIGGER (or #ACTION) command. The syntax is: #TRIGGER {pattern} {command}. Whenever the pattern text is received from the server, the command is executed. You can also define and edit triggers using the View/Triggers menu command to display the Trigger editor in the Package Editor.

Let's start with a simple example. When checking the status of servers, it is important to see any line that contains an error. To ensure you don't miss this important information, let's change the color of the line to red using the #COLOR red command. Thus, you would type:

#TRIGGER {error} {#COLOR red}.

That was easy, and triggers like this can really enhance your server tasks. Here's another useful example:

#TRIGGER {error} {#CAPTURE Errors}.

This trigger will "capture" the line matching the trigger to a separate window called "Errors".  So no matter how many lines scroll past your window, each line containing the word "error" will be pulled out and displayed in a separate error-log window.

You can create triggers on the command line, or you can create and edit triggers in the Package Editor Triggers screen.

Extracting text from the server

Patterns can contain more complicated expressions and wildcard characters, and parts of the matched pattern can be stored in special arguments for use in the command string. Arguments were introduced when Aliases were discussed. The way you store part of the pattern into an argument is by surrounding the part of the pattern with parenthesis. One of the wild-card strings for a pattern is %w which matches any word. So, for example:

#TRIGGER {Status: (%w)} {#IF (%1 = "error") {#COLOR red}}

will match any string from the server that has the text "Status:" followed by any word. The word after "Status:" is saved to the %1 argument. Thus, when you receive the string Status: error, TeSSH will color the line red.

Here's another one:

#TRIGGER {Error (%d)} {#IF (%1 = 401) {#COLOR red;#CAPTURE Errors}}

Since %d matches any set of numeric digits, whenever you receive a line containing "Error 401" the line will be colored in red and also captured to the "Errors" window.

As with Aliases, you can used Named Arguments with triggers. Simple place the name of the argument (beginning with the $ character) after the parenthesis, and followed by a colon. For example:

#TRIGGER {Error ($code:%d)} {#IF ($code = 401) {#COLOR red;#CAPTURE Errors}}

Many times you just want to extract the text from the server and put it into a variable. For example, you might want to capture the last error code and use it as a variable in another script:

#TRIGGER {Error (%d)} {LastError = %1}

When the server displays

Error 401

the trigger will store 401 into the @LastError variable.

However, there is an even easier way to do this using the &VarName syntax in the trigger patter:

#TRIGGER {Error &LastError}

No action is needed...the captured values are automatically stored into the specified variables if the pattern matches.

By default, the &VarName syntax uses a wildcard pattern of * to match the text. To change the wildcard that is used, specify it just after the & character. Or, if you want to use the square brackets [] to define your own wildcard range, put it after the & character. For example, to only capture digits into a variable, you would do:

#TRIGGER {Error: &%dLastError}

If you need to capture something where there are alphabetic characters just after the value you want, you need to enclose the variable name in {} characters. For example, if the server displays:

Ping time 100ms

You might want to create a trigger to capture this number into the @Ping variable. But, if you do:

#TRIGGER {Ping time &Pingms}

IT WON'T WORK! Because it will be using a variable name of "Pingms" instead of just "Ping". To get around this, use the {}:

#TRIGGER {Ping time &{Ping}ms}

and now it will set the @Ping variable properly.

Trigger Classes

You might not want the above triggers to be active all of the time. To assign the trigger to a class folder, provide the class name as the optional third parameter to the #TRIGGER command. For example:

#TRIGGER {Error (%d)} {LastError = %1} "ErrorLog"

Then you can turn the trigger on with #T+ ErrorLog, or turn it off with #T- ErrorLog. Assign these two commands to macro keys or buttons and you have full control over when you capture errors and when you don't.

Instead of placing the trigger into a class folder, you can give the trigger itself a unique name (called an ID name). By assigning an ID name to a trigger, you can refer to it by name instead of by pattern. For example:

#TRIGGER ErrorTrig {Error (%d)} {LastError = %1}

Just as with the previous example, you can enable and disable this trigger using #T+ ErrorTrig or #T- ErrorTrig. The difference is that you have not created a class folder...you've just assigned a new name to the trigger.

Regular Expressions

Instead of using the normal TeSSH trigger syntax, you can use Perl Regular Expressions instead. See the #REGEX command for details on regular expressions. Regular Expressions provide a lot of power, but can also be a bit complex to learn.  All TeSSH Triggers are converted to Regular Expressions internally, so there is no performance difference using a zScript trigger pattern vs a regular expression pattern.

One example of where zScript patterns are a bit easier to understand than Regular Expressions is with the simple * wildcard.  Most computer users have used * when dealing with listing files.  For example, "ls *.txt" will list all files that end with the ".txt" extension.  The * in this case matches any text before the ".txt" string.  This is exactly how zScript handles the * wildcard.  However, the * character in Regular Expressions is used differently.  To match any text in a regular expression, you need to use ".*" instead of just "*"

Add comment

Login or register to post comments