CScript Built In Function Reference

CScript Built In Function Reference

1 Overview

The CScript scripting language provides a library of functions that enable you to interact with the operating system and includes utility functions to make developing scripts for the TinyTERM emulator easier. This document describes the commands available and how to use these built in functions.

2 Document Conventions

The CScript Builtin Function Reference describes commands using the following format:

Return_value Command

syntax

Description

Example

Values passed to script functions are categorized by the first letter of their names. The category letters are all lower-case, and follow the convention listed below. The category names also apply to the values returned by the functions.

Category Name Implementation Code

============= ============== ====

Time 32-bit integer t

Integer 32-bit i

String 64k max length s

Floating point IEEE 64-bit f

Boolean 0/non-zero True/false b

Handle (Win32) 32-bit h

Object 32-bit o

Void No parameter or return value

Variable Name String v

3 Command Reference

The following sections contain quick explanations of programming syntax, keywords, and commands for the built in functions available in the CScript language. These commands are organized into the following categories:

· Primitive Commands

· Operating System and File I/O Commands

· User Interface Commands

· Utility Commands

· Win32 Commands

· TinyTERM Applications Commands

3.1 Primitive Commands

Boolean AxRegisterEvent

AxRegisterEvent(oObject,str,str2)

Registers call back function

AxRegisterEvent(ft,"EndBatchReceive","ft_EndBatchReceive");

Object CreateObject

CreateObject( sObjName, sObjClass, iExStyle, iStyle, iX, iY, iW, iH, sTitle, iID, oParentObject )

Creates an object based on a Win32 window class

ObjFrame = CreateObject( "TE_Frame", "[FRAME]", 0, WS_OVERLAPPEDWINDOW, 0, 0, 0, 0, "TinyTERM", 0, 0 );

Void DestroyObject

DestroyObject(oObj)

Deletes and deallocates an object

DestroyObject(ft);

Void Dprintln

Dprintln(sArg0[[[,sArg1],sArg2],sArg3]...)

Prints to debug screen in debug mode

dprintln("Hello");

3.2 File I/O Commands

Boolean Chdir

Chdir( sPath )

Changes the current directory.

chdir( "C:\temp" );

Integer Copy

Copy(sSrcFile, sDestFile)

Copies one file to another. Returns 0 on success.

copy("default.tpx", "newtpx.tpx");

Integer Erase

Erase(sFile)

Erases file. Returns 0 on success.

erase("default.tpx");

Boolean Exists

Exists(sFileName)

Returns true if passed file exists

b = exists("d:\\century\\default.tpx");

Void Fclose

Fclose(iFileID)

Closes a file opened with Fcreate or Fopen

fclose(1);

String Fconcat

Fconcat(sPath,sFile,sExt)

Returns a full pathname from path, file and extension. Note: this function will automatically concatenate a "\" character to the end of sPath unless sPath ends with a "\" or contains a drive designation, such as "c:".

str = fconcat("c:\\century","default","tpx");

Boolean Fcreate

Fcreate(iFileID, sFile)

Creates a new file. Overwrites an existing file

fcreate(iFIleID, "default.tpx");

Boolean Feof

Feof(iFileID)

Returns true if at end of file

b = feof(fileno);

String Fext

Fext(sPathFile)

Returns extension from passed file string

str = fext("c:\\century\\default.tpx");

String Fhead

Fhead(sNamePath)

Gets file head

fileh = fhead("d:\\century\\default.tpx");

Time Value FileDate

FileDate(sFileName)

Gets file date of filename as a time value

tim = filedate("default.tpx");

Integer Fopen

Fopen( iFileID, sFile, sMode )

Opens a file sFile, sets the file ID for that file to iFileID, and opens the file read/write mode according to sMode.

iMode

=====

RA Read only, ASCII mode

RB Read only, Binary mode

WA Write to new file, ASCII mode (overwrites

an existing file)

WB Write to new file, Binary mode (overwrites

an existing file)

UA Append to an existing file, ASCII mode

UB Append to an existing file, Binary mode

Note that opening a text file with Unix-style line breaks in ASCII mode can lead to some unexpected behavior, including ftell() returning negative values and fseek() not moving the file pointer predictably. Use Binary mode for files with Unix-style line breaks.

fopen( 19, "default.tpx", "RB" );

String Fname

Fname(sNamePath)

Returns stripped filename only from passed full pathname

str = fname("d:\\century\\default.tpx");

String Fpath

Fpath(sNamePath)

Returns stripped path only from passed full path and filename

path = fpath("d:\\century\\default.tpx");

String Fread

Fread( iFileID, iByte )

Reads iByte bytes from file referred to by iFileID. If iByte = -1, reads to end of line or file, whichever comes first.

str = fread( 1, -1 );

String Freadln

Freadln( iFileID, iByte)

Reads a line from a file referred to by iFileID, either to end of line or a maximum of iByte bytes, whichever comes first.

str = freadln( 1, -1 );

Integer Fseek

Fseek(iFileID, iOffset, iOrigin)

Moves file pointer for file iFileID to location iOffset from the location set by iOrigin.

iOrigin

=======

0 Beginning of file

1 Current position

2 End of file

fseek(1,3,0);

Integer Ftell

Fwrite( iFileID )

Gets the current position of the file pointer in the file refered to by iFileID.

nPosition = ftell( 2 );

Void Fwrite

Fwrite( iFileID, sText, iByte )

Writes sText to file associated with iFileID, with iBytes maximum number of bytes written. If iBytes is negative, Fwrite writes the all of sText.

fwrite( 2, "Hello", -1 );

String GetCommandLine

GetCommandLine( )

Gets the command line, including all parameters, used to launch this session of the TinyTERM emulator.

cmdline = GetCommandLine( );

String GetPath

GetPath(sFile,sType)

Gets the path of a file. sType can be "U" (user), "S" (system) or both. The first listed has precedence

path = GetPath("system.ini", "S");

Boolean IsDir

IsDir(sPath)

Returns true if path specified is a directory.

b = isdir("d:\\century");

Integer Mkdir

Mkdir(sDirName)

Creates new directory sDirName in the current directory. Returns 0 on success and an error code on failure.

mkdir("century");

String MkTempNam

MkTempNam(iFhead,iFext)

Returns a name for a temporary file

filename = mktempname("temp","tpx"); // creates file name similar to

// "temp037e9085412.tmp"

Void Spawn

Spawn( iWait, sCmdString, sArguments )

Passes sCmdString to the operating system to be run with the arguments sArguments. Note that the command name, without an extension, must always be the first argument in sArguments. Note that you cannot use quotes as part of sCmdString or sArguments, so if you must launch an application with a space in its Windows filename, you must use DOS 8.3 filenames to refer to that application with the spawn command.

iWait

=====

0 Wait until spawned process ends before running

next command

1 No wait

2 Detach spawned process from the console

3 Wait for spawned process to complete its startup

procedures before continuing with the next command

spawn( 0, "notepad.exe", "notepad untitled.txt" );

String StdDirectory

StdDirectory(sStartDir,sCaption)

Shows standard file open dialog for directories

dpath = StdDirectory("d:\\century","TPX FILES");

String StdOpen

StdOpen(sDir,sMask,sExten,sCaption);

Opens a Windows standard file browser, returns selected path and filename.

filepath = StdOpen("d:\\century","exe files|*.exe|","exe","Exe Files");

String StdOpenButton

StdOpenButton( sDir, sMask, sExten, sCaption, sButton, iType)

Opens a Windows standard file browser with an additional button titled sButton. The browser dialog box will show an Open or Save button based on the iType.

iType

=====

0 Open dialog box

1 Save dialog box

Returns *button if the user clicks on the additional button, otherwise StdOpenButton returns the path and filename the user selected.

file = StdOpenButton( "d:\\century", "exe files|*.exe|All Files (*.*)|*.*|", "exe",

"Select an Executable","Button Text", 1);

String StdPreview

StdPreview( sDir, sTitle )

Runs StdOpen and also displays previews of graphics files

file = StdPreview( "d:\\century", "Images" );

String StdSave

StdSave( sPath, sDesc, sExt, sTitle )

Opens a Windows save browser. Returns the path and filename the user selected, or an empty string if the user chooses Cancel.

StdSave( "c:\\temp\\Century", "Text file (*.txt)|*.txt|All Files (*.*)|*.*|", "", "Save As" );

3.3 User Interface Commands

Boolean AddResFile

AddResFile(sFileName)

Adds a resource file to the internal list of files searched for resource data

AddResFile("ttdlgus.res");

Handle CreateForm

CreateForm( iFormNum, oParentObject, iDefPage )

Finds DIALOG or CENTABDLG resource from resource list and creates a modeless dialog whose parent is oParentObject. If the form is a tabbed dialog and iDefPage is nonzero, that page is selected. Returns zero on error.

hwnd = CreateForm( 1500, ObjFrame, 0);

Void EnableToolTips

EnableToolTips(bBool)

Enables or disables tooltips

EnableToolTips(0);

Object GetObject

GetObject(sObjectName)

Gets the object of string

obj = GetObject("CS103");

Object GetObjectFromHWND

GetObjectFromHWND(hWnd)

Returns an object from window handle

obj = GetObjectFromHWND(hwnd);

Handle GetObjectHWND

GetObjectHWND(oObject)

Gets hwnd from an object

hwnd=GetObjectHWND(object);

String LoadString

LoadString(iID,iLanguage)

Gets a string resource from resource list.

str = LoadString(200,0);

Integer ModalForm

ModalForm(iFormNum,oParentObj,iDefPage)

Reads DIALOG or CENTABDLG resource and runs modal dialog.

nIDCloseButton = ModalForm(1300,DlgObj,0);

Void ObjectRegisterFormTooltips

ObjectRegisterFormTooltips(hWnd)

Re-registers a form's tooltips. Normally this occurs automatically

ObjectRegisterFormTooltips(hwnd);

Object ResLoadMenu

ResLoadMenu(sStr)

Finds menu resource from resource list and creates a Win32 menu handle.

pmenu = ResLoadMenu("#400");

Void sl_FormExit

sl_FormExit( sObjName, iExitCode )

Causes a return from ModalForm with iExitCode as the return value.

sl_FormExit( DlgObj, IDOK );

3.4 Utility Commands

Void _Abort

_abort()

Abort script language execution

_abort();

String _Chr

_Chr(iAsciiVal)

Converts integer ASCII value to single character string

str = _chr(42);

Integer _sizeOf

_sizeOf(sStr)

Returns length of string

n = _sizeOf("12345");

String _str

_str(iVal)

Returns string from numeric value iVal

a = _str(12);

String _ToLowerC

_ToLowerC(sStr)

Returns string with all lower case

str = _tolowerC("aBaB");

String _ToUpperC

_ToUpperC(sStr)

Returns string with all upper case

str = _toupperC("aBaB");

Integer _Val

_Val(sStr)

Returns integer from a string

a = _val("123");

Time Value Atod

Atod(sDateTime)

Converts ASCII time string sDateTime to internal time value

tim = atod("03/15/1999.01:23:45");

String Cdate

Cdate(tTime)

Converts internal time value to ASCII date string

str = cdate(time());

String Chname

Chname(iNum,iType)

Converts ASCII character value to string for display as mnemonic, control or dump

iType

=====

2 Numeric hex values 0d

3 Mnemonic ASCII values <CR>

4 Control characters ^M

5 Keystroke names ENTER

str = chname(13,0);

String Ctime

Ctime(tTime)

Returns clock time string from time value

hour = ctime(time());

String Decrypt

Decrypt(sString)

Decrypts an encrypted string

str = decrypt(password);

String Encrypt

Encrypt(sStr)

Encrypts a passed string

str = encrypt(password);

String Field

Field( sList, iPosNum, iSeparator )

Gets a string from a delineated list

str = field( "a|b|c|d|e", 2, _asc( "|" ) );

String GetEnv

GetEnv(sLABEL)

Gets value of environmental variable

name = getenv("HOME");

String GetSysDir

GetSysDir()

Returns directory TinyTERM is installed in

sdir = GetSysDir();

String GetUserDir

GetUserDir()

Returns user's TinyTERM locally installed directory, if different from system installed directory

path = GetUserDir();

Void Help

Help(sTopic)

Runs Windows help system on topic

Help("");

Void IniDeleteSection

IniDeleteSection( sFile, sSection )

Deletes a section from an .ini file

IniDeleteSection( "user.ini", "keyboard" );

Void IniDelStr

IniDelStr(sSection,sKeyName)

Deletes a key from an ini-format file

IniDelStr("colors","fgcolor");

String IniEnumSections

IniEnumSections( sFile1, sMatch )

Returns a "|" delimited list of all sections in the .ini file that match the pattern. (Note that the returned strings in the list have the matched suffixes removed.)

list = inienumsections( "log.dat", "*.login" );

String IniGetStr

IniGetStr(sSection,sKeyName,sDefault)

Gets data from an ini-format file. Returns default if key does not exist

str = inigetstr("log",key, " ");

String IniListKeys

IniListKeys(sFile,sSection)

List keys defined in an ini-format file

list = IniListKeys("tt.ini","section");

Void IniMerge

IniMerge(sSect,sFile,sSect2,sFile2)

Merges sSect from file sFile into sSect2 in sFile2.

inimerge("login","tt.ini","login","ftp.ini");

Void IniReplaceKeys

IniReplaceKeys(sFile,sSection,sList)

Replaces keys in an ini-format file

IniReplaceKeys("tt.ini",section,keylist);

Void IniSetFile

IniSetFile(sFile)

Sets default filename for most IniXXX functions

inisetfile("tt.ini");

Void IniSetStr

IniSetStr(sSec,sName,sStr)

Writes sName with sStr in section sSec

inisetstr(sect, name, "data");

Void IniSync

IniSync(sFile,iSize)

Flushes file buffer. The iSize argument sets the size of the RAM buffer.

iSize

=====

-1 Standard buffer size (8k)

0 Normal sync

>0 New buffer size in kilobytes. (Maximum value 63.)

inisync("",0);

String Left

Left(sStr,iLen)

Returns leftmost iLen characters of string sStr

a = left("12345",2);

String MidStr

MidStr(sStr,iPos,iLen)

Returns string starting at iPos of length iLen

str = midstr("12345",2,3);

Integer Pos

Pos(sStr1,sStr2,iStart)

Returns position of string 1 within string 2, beginning at character number iStart. You must set the iStart parameter to 1 or higher; values less than 1 will always return 0.

a = pos("23",1123334445,1);

Integer Quit

Quit(iExitCode)

Exits TinyTERM application. Note that in this version of CScript, you must follow quit commands with a return command.

Quit(0);

Return 1;

String Right

Right(sStr,iLen)

Returns the rightmost iLen characters of sStr

a = right("123456",3);

Boolean SetHelpFile

SetHelpFile(sFileName)

Sets name of default help file.

SetHelpFile("tt.hlp");

Void SetUserDir

SetUserDir(sPath)

Sets user search directory

SetUserDir("\\Century");

Void Sleep

Sleep(nMilliseconds)

Pauses for nMilliseconds.

Sleep( 10000 ); // Pauses execution for 10 seconds

String StrConv

StrConv( sStr, iType )

Converts raw ASCII strings to strings with caret-prefixed control characters and hexidecimal character codes for doublequotes ("\x22"), quotes("\x27"), and dollar signs ("\x24"). Will also convert converted string back to raw ASCII.

iType

=====

0 Convert strings with converted characters to ASCII

1 Convert control characters to caret-prefixed

characters

2 Convert control characters to caret-prefixed

characters and convert double quotes, quotes, and

dollar signs to hexidecimal sequences

str = strconv("Line one^M^M^MLineTwo^M",0);

String StrHex

StrHex(iInt,iLen)

Gets hex number of length iLen from integer iInt

a = strhex(12,2);

Integer Sum

Sum( sString, iType, iStartVal )

Calculates integer checksum of string starting with iStartValu as the beginning checksum value.

iType

=====

0 Adds all characters together

1 Xors all characters together

2 Returns the CRC checksum of the string

i = sum( "string", 0, 0 );

Integer Time

Time()

Returns current time as an internal time value. This is the number of seconds since 01/01/1970.00:00:00 GMT.

tim = time();

String Trim

Trim(sStr)

Returns string without trailing spaces

str = trim(s);

3.5 Win32 Commands

Void CheckMenuItem

CheckMenuItem( hMenu, iItemID, iFlag )

Calls Win32 CheckMenuItem to check or uncheck a menu item.

iFlag

=====

0 Uncheck menu item iItemID

8 Check menu item iItemID

1024 Uncheck the menu item at the zero-based relative

position iItemID

1032 Check the menu item at the zero-based relative

position iItemID

CheckMenuItem( GetFrameMenu(Frame), 7048, 8 );

Void DestroyMenu

DestroyMenu(hMenu)

Calls Win32 DestroyMenu function. Used to destroy menu loaded with ResLoadMenu

DestroyMenu(hmenu);

Void DrawMenuBar

DrawMenuBar(hWnd)

Draws the Menu Bar

DrawMenuBar(Frame);

Void EnableMenuItem

EnableMenuItem(hMenu,iItem,iTag)

Calls Win32 EnableMenuItem function

EnableMenuItem(hMenu,700,MF_DISABLED);

Void EnableWindow

EnableWindow(hWnd,iInt)

Calls Win32 EnableWindow function

EnableWindow(hwnd,0);

Handle FindWindow

FindWindow( sClassName, sWindowName )

Retrieves a handle to the top-level window that matches the class name and window name specified.

FindWindow( "dbMon", NULL );

Object GetDlgItem

GetDlgItem(hWnd,iSessID)

Calls Win32 GetDlgItem function

object = GetDlgItem(Frame,1);

Object GetFrameMenu

GetFrameMenu(hWnd)

Returns the frame object's menu handle.

hmenu = GetFrameMenu(hFrame);

Object GetSubMenu

GetSubMenu(hWnd,iInt)

Calls Win32 GetSubMenu function

hmenu = GetSubMenu(hmenu,0);

Object GetSystemMenu

GetSystemMenu(hWnd,bBool)

Calls Win32 GetSystemMenu function

hmenu = GetSystemMenu(Frame,0);

Integer GetSystemMetrics

GetSystemMetrics(iHW)

Calls Win32 GetSystemMetrics function.

n = GetSystemMetrics(SM_CXSCREEN);

String GetTapiNames

GetTapiNames()

Returns names of installed modems

list = GetTapiNames();

Void InsertMenuItem

InsertMenuItem(hMenu,iInt1,iItemPos,iMenuNum,sLabel)

Calls Win32 InsertMenuItem function

InsertMentItem(GetFrameMenu(Frame,4),0,MF_BYPOSITION,MENU_NUMBER,"About");

Void MoveWindow

MoveWindow( hWnd, iX, iY, iW, iH bRepaint )

Calls Win32 MoveWindow function.

MoveWindow( hFrame, x, y, w, h, 1 );

Integer MsgBox

MsgBox(sMsg,sCaption,iType)

Display message box

iType

=====

0 OK button

1 OK and Cancel buttons

2 Yes and No buttons

3 Yes, No and Cancel buttons

msgbox("bad entry","ERROR",0);

Void RemoveMenuItem

RemoveMenuItem(hMenu,iMenuItem,iInt)

Calls Win32 RemoveMenu to remove a menu item

RemoveMenuItem(GetSystemMenu(Frame,0),MENU_DISCONNECT,0);

Void SetDragMode

SetDragMode(hWnd)

Capture move and release

SetDragMode(hwnd);

Boolean SetFocus

SetFocus(hWnd)

Calls Win32 SetFocus to set window focus to hWnd

target = SetFocus(hwnd);

Boolean SetForegroundWindow

SetForegroundWindow( hWnd )

Calls Win32 SetForegroundWindow to bring the window specified in hWnd to the foreground and made the active window.

SetForegroundWindow( hwnd );

Void SetFrameMenu

SetFrameMenu(hWnd,iMenuID)

Attach a menu to a frame window

SetFrameMenu(hFrame,MenuID);

Void ShowWindow

ShowWindow(hWnd,iCmdShow)

Calls Win32 ShowWindow function

ShowWindow(hwnd,SW_SHOW);

Void TrackPopupMenu

TrackPopupMenu(hMenu,bBool,iHPos,iVPos,hWnd)

Calls Win32 TrackPopupMenu function

TrackPopupMenu(GetSubMenu(pmenu,0),0,x,y,Frame);

3.6 TinyTERM Commands

Void AppRedraw

AppRedraw()

Redraws application user interface.

AppRedraw();

String ConfigureDevice

ConfigureDevice(iIndex,sDeviceName,hWnd)

Gets modem configuration.

dconfig = ConfigureDevice(1,cdevice,HWND);

String GenerateURL

GenerateURL( sSystem, sUsername, sPassword, sStr, iInt, iInt2, iInt3 )

Generates URL using operator entries.

str = GenerateURL( "www.censoft.com", "anonymous", pword, "", 0, 0, 0 );

String GetCountryList

GetCountryList()

Gets countries supported by modem location list

list = GetCountryList();

String GetDefaultBrowser

GetDefaultBrowser()

Gets default browser name and path

filename = GetDefaultBrowser();

String GetDefaultBrowserAppName

GetDefaultBrowserAppName()

Gets only default browser filename

file = GetDefaultBrowserAppName();

String GetLocationList

GetLocationList()

Gets locations supported by modem

list = GetLocationList();

Boolean IsDebugMode

IsDebugMode()

Returns true if "-debug" is set in command line.

b = IsDebugMode();

Void Menu_Draw

MenuDraw()

Redraws the Menu Bar if enabled

menu_draw();

Void Script_Login

Script_Login()

Callback function called after login completes. Note: when using any of the Script_ commands, you should avoid using dialog boxes if you will be running from within a browser.

script_login();

Void Script_Logout

Script_Logout()

Callback function called before logout begins

script_logout();

Void Script_SessConnect

Script_SessConnect()

Callback function called after connecting to the host

script_sessConnect();

Void Script_SessDiscon

Script_SessDiscon()

Callback function called before disconnecting from the host

script_sessDiscon();

Void Script_SessDown

Script_SessDown()

Callback function called before the session is closed

script_sessdown();

Void Script_SessUp

Script_SessUp()

Callback function called after the session is opened

script_sessup();

Void Script_ShutDown

Script_ShutDown()

Callback function called before shutdown

script_shutdown();

Void Script_StartUp

Script_StartUp()

Callback function called after startup

script_startup();

Void SessDel

SessDel( oSession )

Deletes session with object oSession.

SessDel( CSESS );

Void SessionNew

SessionNew(sTpxFile);

Starts a new session

SessionNew("c:\\tmp\\default.tpx");

Void StatusBar_Draw

StatusBar_Draw()

Redraws Status Bar if enabled

StatusBar_Draw();

Void SwitchSess

SwitchSess(nSessNum,iSave)

Switches to session nSessNum. iSave is currently non-functional

SwitchSess(3,0);