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 ( <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 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 | |
CursorType | 0 for block cursor, 1 for underline cursor. |
CursorVisible | 0 for invisible, 1 for visible. |
DarkScreen | 0 for light screen, 1 for dark screen |
CursorBlink | 0 for not blink, 1 for blink |
LineDraw | 0 for using line draw characters in font, 1 for drawing the line by KoalaTerm |
FontName | Name of the display font |
FontSize | Point size of the display font |
FontBold | 0 for non-bold, 1 for bold display font |
FontName132 | Name of the display font (for 132 columns) |
FontSize132 | Point size of the display font (for 132 columns) |
FontBold132 | 0 for non-bold, 1 for bold display font (for 132 columns) |
FontUse80 | 0: use differnt font for 132 columns; 1: use same font |
* Printing settings | |
FFNeeded | 0 for no FF, 1 for FF appended to each print job |
Redirect | 0 for using host's printing control, 1 for using Windows printing control |
DriverName | Driver name of the printer |
PrinterName | Name of the printer |
DefaultPrinter | 0 for using specified printer, 1 for using default printer |
PrintFontName | Name of printing font |
PrintFontSize | Pointer size of printing font |
PrintFontBold | 0 for non-bold, 1 for bold printing font |
* Terminal settings | |
Interpret | 0 for displaying the control sequeces, 1 for interpreting them |
AutoWrap | 0 for no autowrap, 1 for autowrap |
8BitChars | 0 for 7 bits control characters, 1 for 8 bits |
TermID | Terminal ID. 0-5 for VT420, VT320, VT220, VT102, VT101,VT100 respectively. |
AnswerBack | Answer back string for VT terminal |
HideABM | If 1, KoalaTerm will hide the answer back in KoalaTerm Settings |
Columns | Number of columns in a terminal line |
Lines | Number of lines in a terminal page |
Pages | Total numbe of pages for terminal buffer |
SaveLines | Maximum number of saved history lines |
* Tab settings | |
TabList | An 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 | |
NewLine | 0 for no newline, 1 for new line. In new line mode, the return key will generate both <CR> and <LF> characters. |
NumericKeypad | Keypad mode: 0 for application mode, 1 for numeric mode |
CusorKeys | Cursor keys mode: 0 for application mode, 1 for normal mode |
MarginBell | 0 for margin bell disabled, 1 for enabled |
WarningBell | 0 to disable and 1 to enable |
BackArrow | If 0, send <Backspace> code for backspace key, if 1, send <Delete> code instead |
NumLock | If 1, use NumLock key to change keypad mode, if 0, use NumLock key as PF1 |
* Communication settings | |
HostName | Name of the connected host |
Proxy | Name of the telnet proxy |
HostType | 0 for telnet, 1 for comm port, 2 for local echo, 3 for modem. |
Port | Port number. Telnet: telnet port; comm: 0 for com1, 1 for com2...; modem: ID of modem. |
Speed | Comm port: baud rate. Telnet: proxy port number |
Parity | 0: No Parity 1: Even 2: Odd 3: Mark 4: Space |
StopBits | 0: 1 bit 1: 1.5 bits 2: 2 bits |
DataLength | 0: 6 bits 1: 7 bits 2 : 8 bits |
LocalEcho | 0: Local echo off. 1: Local echo on |
Local | 0: Online. 1: Local |
FlowControl | 0: 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 |
UPSS | User preferred supplemental charset |
PrimarySet | Primary supplemental charset |
SecondarySet | Secondary supplemental charset |
NRC | National 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 | |
Palette | Array of 64 integers for 16 colors. Each color uses 4 integers: R, G, B and flag. |
BackColor | Background color for color mapping. Array of 16 integers for 16 possible combination of attributes. Each combination uses a color index 0 -15. |
ForeColor | Foreground color for color mapping. Array of 16 integers for 16 possible combination of attributes. Each combination uses a color index 0-15. |
Mapped | Mapped flag for color mapping. Array of 16 integers for 16 possible combination of attributes. 1 for mapped, 0 for not mapped. |
* General settings | |
Maximize | 1 for maximize terminal window when created |
CopySpace | 1 for copying spaces when copied to clipboard |
AutoClose | 1 for automatically closing terminal window when disconnected |
AutoExit | 1 for automatically exit KoalaTerm when a window closed |
History | 1 for display scroll history buffer |
FitFont | 1 for automatically change font to fit in window |
LoginScript | 1 for automatically executing login script after connected |
UserID | User ID for login script |
Password | Password for login script |
Script | The login script |
CaptureDebug | 1 for capturing debug information |
AutoCopy | 1 for automatically copy to clipboard after text selected |
Title | The 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 | |
ButtonCaption | Array for captions of 32 buttons. |
ButtonString | Array for strings of 32 buttons. |
ButtonAction | Array 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 |
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.
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 tagHow to Invoke KoalaScript Scripts
Overview of KoalaScript Language