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:

  1. Terminal object
  2. System object
  3. File object

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’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 ( <string> );

This function sends a string to host. The syntax for special characters in <string> 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> are 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");

Terminal Settings

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:

Property Name Description
* Display settings
CursorType0 for block cursor, 1 for underline cursor.
CursorVisible0 for invisible, 1 for visible.
DarkScreen0 for light screen, 1 for dark screen
CursorBlink0 for not blink, 1 for blink
LineDraw0 for using line draw characters in font, 1 for drawing the line by KoalaTerm
FontNameName of the display font
FontSizePoint size of the display font
FontBold0 for non-bold, 1 for bold display font
FontName132Name of the display font (for 132 columns)
FontSize132Point size of the display font (for 132 columns)
FontBold1320 for non-bold, 1 for bold display font (for 132 columns)
FontUse800: use differnt font for 132 columns; 1: use same font
* Printing settings
FFNeeded0 for no FF, 1 for FF appended to each print job
Redirect0 for using host's printing control, 1 for using Windows printing control
DriverNameDriver name of the printer
PrinterNameName of the printer
DefaultPrinter0 for using specified printer, 1 for using default printer
PrintFontNameName of printing font
PrintFontSizePointer size of printing font
PrintFontBold0 for non-bold, 1 for bold printing font
* Terminal settings
Interpret0 for displaying the control sequeces, 1 for interpreting them
AutoWrap0 for no autowrap, 1 for autowrap
8BitChars0 for 7 bits control characters, 1 for 8 bits
TermIDTerminal ID. 0-5 for VT420, VT320, VT220, VT102, VT101,VT100 respectively.
AnswerBackAnswer back string for VT terminal
HideABMIf 1, KoalaTerm will hide the answer back in KoalaTerm Settings
ColumnsNumber of columns in a terminal line
LinesNumber of lines in a terminal page
PagesTotal numbe of pages for terminal buffer
SaveLinesMaximum number of saved history lines
* Tab settings
TabListAn array with 132 elements. Each element represents a flag of tab stop at a column. If the flag is 1, the column is a tab stop.
* Keyboard settings
NewLine0 for no newline, 1 for new line. In new line mode, the return key will generate both <CR> and <LF> characters.
NumericKeypadKeypad mode: 0 for application mode, 1 for numeric mode
CusorKeysCursor keys mode: 0 for application mode, 1 for normal mode
MarginBell0 for margin bell disabled, 1 for enabled
WarningBell0 to disable and 1 to enable
BackArrowIf 0, send <Backspace> code for backspace key, if 1, send <Delete> code instead
NumLockIf 1, use NumLock key to change keypad mode, if 0, use NumLock key as PF1
* Communication settings
HostNameName of the connected host
ProxyName of the telnet proxy
HostType0 for telnet, 1 for comm port, 2 for local echo, 3 for modem.
PortPort number. Telnet: telnet port; comm: 0 for com1, 1 for com2...; modem: ID of modem.
SpeedComm port: baud rate. Telnet: proxy port number
Parity0: No Parity 1: Even 2: Odd 3: Mark 4: Space
StopBits0: 1 bit 1: 1.5 bits 2: 2 bits
DataLength0: 6 bits 1: 7 bits 2 : 8 bits
LocalEcho0: Local echo off. 1: Local echo on
Local0: Online. 1: Local
FlowControl0: No flow control 1: Xon/Xoff 2: Hardware flow control
* Character set settings
* charset codes:0: ASCII
1: DEC supplement graphic
2: DEC special graphic
3: DEC technical
4: ISO Latin 1
5: ISO Latin 2
6: ISO Latin 3
7: ISO Latin 4
8: ISO Cyrillic
9: ISO Greek
10: MS DOS
11: MS 866
12: KOI8r
13: ISO Hebrew
14: ISO Latin 5
15: ISO Arabic
UPSSUser preferred supplemental charset
PrimarySetPrimary supplemental charset
SecondarySetSecondary supplemental charset
NRCNational replacement charset. See the following code table:
* NRC charset codes:0: USASCII
1: ISO UK
2: DEC Dutch
3: DEC Finnish
4: ISO French
5: DEC Frech Canadian
6: ISO German
7: ISO Italian
8: DEC Norweigian Danish
9: ISO Norweigian Danish
10: DEC Portuguese
11: ISO Spanish
12: DEC Swedish
13: DEC Swiss
* Color settings
PaletteArray of 64 integers for 16 colors. Each color uses 4 integers: R, G, B and flag.
BackColorBackground color for color mapping. Array of 16 integers for 16 possible combination of attributes. Each combination uses a color index 0 -15.
ForeColorForeground color for color mapping. Array of 16 integers for 16 possible combination of attributes. Each combination uses a color index 0-15.
MappedMapped flag for color mapping. Array of 16 integers for 16 possible combination of attributes. 1 for mapped, 0 for not mapped.
* General settings
Maximize1 for maximize terminal window when created
CopySpace1 for copying spaces when copied to clipboard
AutoClose1 for automatically closing terminal window when disconnected
AutoExit1 for automatically exit KoalaTerm when a window closed
History1 for display scroll history buffer
FitFont1 for automatically change font to fit in window
LoginScript1 for automatically executing login script after connected
UserIDUser ID for login script
PasswordPassword for login script
ScriptThe login script
CaptureDebug1 for capturing debug information
AutoCopy1 for automatically copy to clipboard after text selected
TitleThe session title to be display on title bar of main window
HostScript
 
1 for allowing host to access protected script functions
Note: this property cannot be altered by script.
* Button settings
ButtonCaptionArray for captions of 32 buttons.
ButtonStringArray for strings of 32 buttons.
ButtonActionArray for action types of 32 buttons. 0: Send sequence. 1: Execute script. 2: Run script file

Here are some examples showing how to change terminal settings:

1. Suppose you want to define a button from the host side, let’s say, define the second button as sending sequence "exit<CR>", you can send the following sequence from the host:

<ESC>P$s term.ButtonCaption[1] = "Exit"; term.ButtonString[1] = "exit<CR>"; term.ButtonAction[1] = 0; <ESC>\

2. Suppose you want to use a larger font:

fontsize = term.FontSize; // get current font size
if (fontsize < 32) // maximum size
    fontsize = fontsize + 1;
term.FontSize = fontsize; // change font size. The screen will be refreshed immediately

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> )

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.

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.

Example: 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 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

Go to Index Page