Content

KoalaScript Object Reference

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 provides the following built-in objects:

Terminal Object

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 is 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>");

• Click here for a list of code sequences for standard VT function keys.

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.  Screen (<starting row>, <starting column>, <ending row>, <ending column>) (Available since version 3.14)

• This function gets displayed characters from a rectangle area on the terminal screen. <starting row> must be less than or equal to <ending row>, and <starting column> must be less than or equal to <ending column>. Row numbers and column numbers start from 1 (the upper-left corner of the screen).

• When getting characters from more than one rows (i.e. <ending row> is greater than <starting row>), <LF><CR> are inserted between two rows.

5.   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");

6.   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.

7.   Clear ()

This function clears the terminal screen, and resets terminal status as well.

8.   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.

9.   SendBreak ()

This function sends a break signal (only effective for serial connections).

10.   Capture ( <File Name> ) (Available since version 3.3 build 1625)

This function start or stop capturing terminal content (from the host) into a file. When you start capturing, the <File Name> parameter is required for the path and name of the captured file. When you stop the capturing, do not specify file name.

11.   Disconnect () (Available since version 3.3 build 1701)

This function disconnect the session immediately.

Terminal Settings

Terminal object also has many properties you can get and set. The properties are actually corresponding to available KoalaTerm settings. You can also get terminal status like current cursor position using some of the properties. Here is a complete list of supported properties:

A complete listing of terminal settings

System Object

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>, <title>, <style>)

Display a message box with specified message.

• The <title> and <style> parameters can be omitted. Default title will be "KoalaTerm".

• The <style> parameter is a number, can be combined from the following values:

  
  

  * Buttons * Icon * Default button 0 OK 16 Hand sign, error sign, stop sign 0 Button 1 1 OK, Cancel 32 question sign 256 Button 2 2 Abort, Retry, Ignore 48 Exclamation sign, warning sign 512 Button 3 3 Yes, No, Cancel 64 Asterisk sign, information sign     4 Yes, No 128 User icon     5 Retry, Cancel

  For example, if you want to display Yes/No/Cancel button with "Cancel" as default button, and a question sign, the style should be 3 + 32 + 512 = 547.

• This function returns a number indicating which button is pressed by the user to dismiss the message box. 1 for "OK", 2 for "Cancel", 3 for "Abort", 4 for "Retry", 5 for "Ignore", 6 for "Yes", 7 for "No".

2. PlaySound ( <file name> )

Play a wave 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>, <style> ) (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.

Since version 3.15: <style>: 1 for password input, 2 for file save as, 3 for open file. Default or zero for normal input.

File Object

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.

String Type

KoalaScript supports several operations on strings:

1. Length

This property get the string length (number of bytes).

2. Mid ( <start position>, <byte count> ) (Available since version 3.15)

This method returns a substring. The "start position" counts from zero for the first byte.

3. MakeUpper () (Available since version 3.15)

This method returns the string with all letters in upper case.

4. MakeLower () (Available since version 3.15)

This method returns the string with all letters in lower case.

5. Find ( <substring>, <start position> ) (Available since version 3.15)

This method finds the "substring" in the string from the "start position" (counting from zero for the first byte) and returns the first appearing position. If not found, -1 is returned. The "start position" can be omitted, default is zero.

KoalaScript Sample

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 are 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 tag
function OnRecv( char )
{
    // write every character in file
    file.Write( char );
}
// Start of script
// Wait for the file header tag first
str = term.Wait ( "[HEADER ]", 30 );
// Check if we actually get the header tag in 30 seconds or not
if ( str == "" ) {
    sys.MessageBox ( "Cannot detect the file header." );
    return;
}
// Open the file for writing
file = sys.OpenFile ( "MyLog.txt", "w" );
// Write the header tag into file since it’s also a part of the file
file.Write ( str );
// Wait for the file trailer tag, and log every character into file
term.Wait ( "[TRAILER]", 0, OnRecv );
// Finally, get fixed number of characters in the trailer record
str = term.Get(40);
// And write to the file
file.Write ( str );
// We are done. Close the file
file.Close ( );

How to Invoke KoalaScript Scripts

Overview of KoalaScript Language

Content