KoalaScript supports some built-in objects. Each object has its own methods and properties. You can call object methods to carry out tasks, get object properties to get information about the object, or set object properties to change status of the object.
Right now KoalaScript provide the following built-in objects:
When a script is started, KoalaScript creates a global variable "term". The value of the variable is a terminal object. This object represents the functionality of a KoalaTerm session. It supports the following methods:
1. Wait ( <wait string>, <timeout>, <callback> );This function waits for specified string(s). You can wait for multiple strings separated by "|". The <timeout> is in seconds, and the <callback> is name of a function which will be called each time a character received. <timeout> and <callback> parameters are optional. And if <timeout> is zero, it’s considered as infinite waiting.
For example, the following statement:
term.Wait("login:|name:");
will wait for "login:" or "name:". Either one of this received from the host, this waiting ends.
The return value of this function is the string received. You can check the returned value to verify what you have actually received. The following example examine the received string and give different response message:
str = term.Wait("continue|exit", 10);
if (str == "continue")
sys.MessageBox("Continue...");
else if (str == "exit")
sys.MessageBox("Want to exit...");
else
sys.MessageBox("Nothing received.");
Note: the function will return empty string when timeout.
The <callback> function can be used to provide customized process to every received character during waiting. The callback function has a single parameter, when it’s called, the value of this parameter will be a string consisting the character received. The following example shows a simple use of this mechanism:
function OnReceive(char)
{
sys.MessageBox("Received: " + char);
}
term.Wait("E", 0, OnReceive);
The above example first declare the callback function, it simply displays every single received character with a message box. In the body of the script, a term.Wait method call waits until an "E" character received. During waiting, all characters will be displayed, including the terminator "E" character.
2. Send ( <sequence> );
This function sends a string to host. The syntax for special characters in <sequence> is the same as used in key mapping sequence. For example, the following statement sends a "Carriage Return" to the host:
term.Send("<CR>");
3. Get ( <number of characters>, <timeout> )
This function gets specified number of characters from the host. <timeout> is in seconds and is optional.
The return value of this function is the received string. When timeout happens, the received string may not contains specified number of characters. You need check the Length property of the string in that case. See the following sample:
str = term.Get(40, 10);
if (str.Length != 40)
MessageBox("Receiving timout.
The actually number of characters received:" + str.Length);
4. DoMenu ( <menu item name> )
This function simulate the user action of selecting a menu item. The <menu item name> is composed by menu name and menu item name separated by ":".
For example, the following statement cause the session to be terminated:
term.DoMenu("Connection:Exit");
5. MapKey ( <PC key code>, <modifiers>, <VT key code>, <string> )
This function set mapping for a key.
<PC key code>: Windows standard virtual key code (VK code). To identify this code for a key, you can use the Key Map page of KoalaTerm Setting dialog, click on a key, the VK code will be shown along with the key name;
<modifiers>: a combination of flags for modifiers: ALT (1), CTRL (2), or SHIFT (4);
<VT key code>: a Midasoft assigned code for VT key you are mapping to. Click here for code list. This code is also used to specify mapping type if you aren't mapping to VT key: 252 for mapping to "Run Script File"; 253 for mapping to "Execute Script"; 254 for mapping to "Menu Item"; 255 for mapping to "Send Sequence";
<string>: If you aren't mapping to VT key, then you need to use the parameter to specify mapping. For different type of mapping (described above), the parameter serves as file name, script statements, menu item name, or code sequence.
6. Clear ()
This function clears the terminal screen, and resets terminal status as well.
7. SendLocal ( <sequence> )
This function sends the sequence to the terminal itself, without going out to the host. This allows you to control the terminal like from a host. The syntax of "sequence" string is the same as used in key mapping and "Send" function.
Terminal object also has many properties you can get and set. The properties are actually corresponding to available KoalaTerm settings. Here is a complete list of supported properties:
A complete listing of terminal settings
When a script is started, KoalaScript creates a global variable "sys". The value of the variable is a system object. This object provides functionality of Windows system. It supports the following methods right now:
1. MessageBox ( <message> )
Display a message box with specified message.
2. PlaySound ( <file name> )
Play a wav sound file.
3. Sleep ( <number of milliseconds> )
Wait for a period of time.
4. OpenFile ( <file name>, <open mode> )
Open a file. This function returns a file object for you to perform further operations on the file. The <open mode> parameter is a string including one or more open mode tags: "r" for read, "w" for write, "b" for binary.
Note: This function is protected. If the script is invoked from the host, and "Allow host to access protected script functions" option in "General" page of "KoalaTerm Settings" dialog is disabled, calling to this function will cause the script execution to be terminated.
5. System ( <command> )
Execute a Windows command.
Note: This function is protected. If the script is invoked from the host, and "Allow host to access protected script functions" option in "General" page of "KoalaTerm Settings" dialog is disabled, calling to this function will cause the script execution to be terminated.
6. LoadSession ( <file name> )
Load a KoalaTerm session file and start connection.
Note: The file name should be full path including extension name. This function may be used in login script of a session to start another session. By this way, you can open multiple sessions by just loading one file.
7. InputBox ( <prompt>, <default value> ) (Available since version 3.12)
Give user a chance to input a string. Parameter <default value> can be optional. This function returns the inputed string as result. If user pressed "Cancel" button, the result will be null string.
A file object needs be created by sys.OpenFile method first. Right now file object supports the following methods:
1. Write ( <string> )
Write a string to the file.
2. Close ()
Close the file. When script ends, all open files will be automatically closed even if you did’t call Close function.
3. ReadLine () (Available since version 3.12)
Read a line from the file. Maximum 255 characters. This function returns the read string as result. Line feed character will be also included in the result string.
4. Read ( <number of bytes> ) (Available since version 3.12)
Read specified number of bytes (mostly used with binary files). This function returns the read string as result.
The following example shows a file logging procedure. The host first sends file header record starting with a tag, then unlimited number of records in file, at last it transmits a file trailer record starting with another tag, following the trailer tag there’re fixed number (40) of characters in the trailer record.
// First, we need a wait callback function to do the file logging
// during waiting for the trailer record tagHow to Invoke KoalaScript Scripts
Overview of KoalaScript Language