TeSSH

While the TeSSH User Interface is nice and easy to use, most users are drawn to TeSSH because of it's powerful scripting system. By creating scripts you can automate many normal server tasks, whether it is parsing log files, managing version control systems, checking server or router status, or any other task that can benefit from automation.

Many tasks currently performed by server-based shell scripts can often be converted into client-based scripts in TeSSH.  The advantage of having the scripts within the client are that you can use these scripts across multiple servers, or even on servers that do not support shell-based scripting.  Instead of scripts written in many different languages, you can consolidate them into TeSSH scripts.  You can also create simple user interfaces for your scripts via buttons, macros, and menus within TeSSH.  Client-side scripts can more easily prompt you for information, access local files and databases, and much more.

Scripting Basics

Writing a script is similar to writing a computer program. TeSSH tries to make this easier than most programming languages and is specifically designed for common server tasks.

The most important part of scripting to remember is that you are writing instructions for TeSSH to carry out some sort of task. These instructions need to be written in a way that TeSSH can understand them. Try to be careful to learn the correct "syntax" for scripts. Most scripting errors are caused by being sloppy and forgetting a punctuation character.

You can create scripts in two different ways: (1) via the Package Editor, and (2) via the command line. The Package Editor is a visual editor that allows you to create and edit your scripts. It provides some color syntax highlighting and syntax checking. Novice users should start with the Package Editor.

Because scripts can also be entered directly into the command line, TeSSH needs some way to distinguish script text from normal server text. TeSSH does this by using some special punctuation characters:

#

This is the "command character". It is always used to indicate the name of a TeSSH Command that you want to execute. For example, to use the #ECHO command to display a message on the screen, you would type something like this:

#ECHO "Hello World"

%

This is the "function character". Sometimes called the "parameter character". It is used to indicate the name of a TeSSH Function that you want to execute. For example, to display a random number from 0 to 100, you can type this:

#ECHO %random

This calls the #ECHO command to display a message, but instead of a message we call the %random function to return a random number.

;

This is the "separator character". It is used to separate multiple commands on a single command line. For example, if you wanted to send two commands to the server: "cd .." followed by "ls", then you could type this:

cd ..;ls

It's important to never put any spaces around the ; character. Also, putting some punctuation after the ; might cause TeSSH to think you are sending a "smiley" to the server such as ;).

@

This is the "variable character". It is used to retrieve the value of a Variable that you have defined. A Variable is a container for a value, just like variables in other programming languages. It's important to remember that you only use the @ character when you are trying to retrieve the value stored in the variable. For example, @A will retrieve the value stored in the "A" variable.

Quotes and Strings

Unlike many programming language, you do not always need to put quotes around string values.  However, it is probably still a good idea.  The reason for this difference stems from the fact that zScript is optimized to work within a Telnet/SSH session and the most common task is just sending commands to the server.  For example, if you want to send the "ls" command to the server, you don't need to put any quotes around it, nor do you need to use any special command.  You just type "ls" on the command line (without the quotes) and it is sent to the server.

However, while the Command Line is somewhat forgiving about the lack of quotes, within your scripts you should be a bit more strict to avoid confusion and errors.  When sending text to the server within a script, you should get into the habit of using the #SEND command and placing the command in quotes, such as:

#SEND "ls"

This will send the "ls" command to the server without the quotes and is easier for zScript to compile and easier to read and support.

Text enclosed within the " double-quote is considered "literal text".  It is always treated verbatim, just as it is written.  To include a " quote character within the quotes, just double it.  TeSSH supports a second kind of "quotes" that allow embedded variable and function references.  To include a variable or function reference within a string, enclose it within {} braces instead of " quotes.

You can also evaluate an expression by placing () parenthesis around something instead of using quotes or braces.  Here are some simple examples to understand which quotes you should use in which situations:

a = 123
b = @a+1 // 124 assigned to @b
b = (@a+1) // same as above
b = "@a+1" // assigns the literal string "@a+1" to @b
b = {@a+1} // assigns the string "123+1" to @b

Notice that the {} allows the @a reference to be expanded, but the result is still treated as a string and not a numeric expression.  However, when using () the @a is expanded and the math expression is evaluated properly.

To compare this with other programming languages, the " double-quotes in TeSSH are like the single ' quotes in PHP for literal strings, and the {} braces in TeSSH are like the double " quotes in PHP that allow variable expansion.

Implicit Concat

A commonly used (and often misunderstood) feature of zScript is "Implicit Concat".  Concat stands for concatentation and is the process of appending two string values together.  The %concat function can be used to perform this operation normally.  However, zScript allows you to avoid the function call in many cases.  When performing concatentation without actually using the %concat function is called "Implicit Concat".

Implicit Concat works in most cases, but not all.  When in doubt, or when having a problem, you can always use the %concat function directly.  Here are some examples that work:

a = 123
b = @a"ms"  // same as b = %concat(@a,"ms")
b = "Time: "@a"ms"  // same as b = %concat("Time: ",@a,"ms")
b = %random(100)"ms"  // same as b = %concat( %random(100), "ms")
b = %random(100)ms  // same as b = %concat( %random(100), "ms")
b = @{a}ms  // same as b = %concat(@a,"ms")

This works but is not recommended:

a = 123
b = Time:@a  // special characters such as : should always be placed in " quotesHere are some examples that do not work:

a = 123
b = (@a+1)"ms"  // () expressions not allowed with Implicit Concat
b = {Time: }@a"ms"  // {} are not allowed with Implicit Concat