PC-Online 1998 February

home *** CD-ROM | disk | FTP | other *** search

/ PC-Online 1998 February / PCOnline_02_1998.iso / filesbbs / dos / telemate.arj / TMSCRIPT.TXT < prev next >

Wrap

Text File | 1996-09-05 | 156.3 KB | 4,592 lines

▌███████████ ▌█████████▌ ▌██████ ▌█ ▌█ ▌█▌ ▌█▌ ▌█▌ ▌█▌ ▌█▌ ▌█ ▌█▌ ▌█▌ ▌█▌ ▌█▌ ▌█▌ ▌████▌ ▌████ ▌█ ▌██████ ▌█████ ▌█▌ ▌█▌ ▌█▌ ▌█▌ ▌██████ ▌█ ▌█ ▌█ ▌█ ▌█ ▌█ ▌█▌ ▌█▌ ▌█▌ ▌█▌ ▌█ ▌█ ▌█ ▌█ ▌█ ▌█ ▌█ ▌█▌ ▌█▌ ▌█▌ ▌█▌ ▌█ ▌█ ▌█ ▌█ ▌█ ▌█ ▌█ ▌█▌ ▌█▌ ▌█▌ ▌█▌ ▌██████ ▌████▌ ▌█ ▌█ ▌██████ ▌███ ▌█ ▌█ ▌█ Telemate Script Language Version 4.20 By Tsung Hu, White River Software Copyright (c) 1988-1995 White River Software. All rights reserved. TELEMATE SCRIPT TABLE OF CONTENTS i TABLE OF CONTENTS INTRODUCTION 1 Using TMS.EXE, the Script Compiler . . . . . . . . . . . . . . . . 1 To Run a Script . . . . . . . . . . . . . . . . . . . . . . . . . . 2 What Is Your Name . . . . . . . . . . . . . . . . . . . . . . . . . 2 DATA TYPES 3 Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Character . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 Boolean . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 VARIABLES 6 Variable Identifiers . . . . . . . . . . . . . . . . . . . . . . . 6 Variable Declarations . . . . . . . . . . . . . . . . . . . . . . . 6 Predefined Variables . . . . . . . . . . . . . . . . . . . . . . . 6 CONNECTED . . . . . . . . . . . . . . . . . . . . . . . . . . . 7 FOUND . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 SUCCESS . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 LOGGING . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 WIDTH . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 HEIGHT . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10 EXPRESSIONS 11 Rule Of Precedence . . . . . . . . . . . . . . . . . . . . . . . . 11 Arithmetic Operators . . . . . . . . . . . . . . . . . . . . . . . 11 Boolean Operators . . . . . . . . . . . . . . . . . . . . . . . . . 12 Relational Operators . . . . . . . . . . . . . . . . . . . . . . . 12 STATEMENTS 14 Comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 14 Assignment Statement . . . . . . . . . . . . . . . . . . . . . . . 14 If Statement . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 Switch Statement . . . . . . . . . . . . . . . . . . . . . . . . . 16 While Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Repeat Loop . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Exit Statement . . . . . . . . . . . . . . . . . . . . . . . . . . 18 #include Directive . . . . . . . . . . . . . . . . . . . . . . . . 18 PROCEDURES 19 Procedure Declaration . . . . . . . . . . . . . . . . . . . . . . . 19 Parameter Declaration . . . . . . . . . . . . . . . . . . . . . . . 20 Calling Procedure and Parameter Passing . . . . . . . . . . . . . . 20 Nested Procedures and Scope of Variables . . . . . . . . . . . . . 22 Return Statement . . . . . . . . . . . . . . . . . . . . . . . . . 23 TELEMATE SCRIPT TABLE OF CONTENTS ii BUILT IN PROCEDURES BY CATEGORY 24 Console I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Print Statement . . . . . . . . . . . . . . . . . . . . . . . . 24 COM I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24 Put Statement . . . . . . . . . . . . . . . . . . . . . . . . . 25 Waitfor Statement . . . . . . . . . . . . . . . . . . . . . . . 25 File Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . 26 String Handling . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Miscellaneous Routines . . . . . . . . . . . . . . . . . . . . . . 26 BUILT IN PROCEDURES 27 Alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 Append . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27 At . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Atoi . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 ChDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28 Clear COM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Clear Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 Clear Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 ComInCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 ComOutCount . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Concat . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Create . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Date . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31 Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Delete . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 Dial . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 Dos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33 ExitTelemate . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 FileExist . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 FileSize . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35 GetCh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 HangUp . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36 Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 InputCh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Itoa . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Keystroke . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Length . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 LoadFon . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 LoadKey . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 LoadMac . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 LoadPad . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40 LogOff . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 LogOn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 LogPause . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 LogResume . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Open . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43 TELEMATE SCRIPT TABLE OF CONTENTS iii Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44 Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45 Read . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46 ReadCh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48 Rename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Script . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49 Seek . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Send . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50 Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52 Stop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 StrDel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55 StrIns . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 StrPos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 StrSet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 SubStr . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Tell . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 Waitfor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 59 WaitUntil . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 When . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61 WhenIdle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 62 WhereX . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 WhereY . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63 TOOLBOX PROCEDURES 65 Toolbox #1 65 Color Values and ANSI Color Codes . . . . . . . . . . . . . . . 66 EchoToLocal and EchoToRemote . . . . . . . . . . . . . . . . . . 66 Echo and EchoInt . . . . . . . . . . . . . . . . . . . . . . . . 66 EchoBkColor . . . . . . . . . . . . . . . . . . . . . . . . . . 67 EchoBlink . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 EchoBlock . . . . . . . . . . . . . . . . . . . . . . . . . . . 68 EchoBox . . . . . . . . . . . . . . . . . . . . . . . . . . . . 69 EchoClearScreen . . . . . . . . . . . . . . . . . . . . . . . . 69 EchoColor . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 EchoGotoXY . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 EchoHiLite . . . . . . . . . . . . . . . . . . . . . . . . . . . 70 EchoNormal . . . . . . . . . . . . . . . . . . . . . . . . . . . 71 EchoReverse . . . . . . . . . . . . . . . . . . . . . . . . . . 71 Toolbox #2 72 GetN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 72 InputN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 ReadN . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73 isalpha . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 isalnum . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 iscntl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 74 isdigit . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75 TELEMATE SCRIPT TABLE OF CONTENTS iv Toolbox #3 75 ConvertDate . . . . . . . . . . . . . . . . . . . . . . . . . . 75 DiffDate . . . . . . . . . . . . . . . . . . . . . . . . . . . . 76 DiffTime . . . . . . . . . . . . . . . . . . . . . . . . . . . . 77 PhoneDirectory . . . . . . . . . . . . . . . . . . . . . . . . . 78 PhoneFind . . . . . . . . . . . . . . . . . . . . . . . . . . . 78 PhoneRead . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 PhoneSize . . . . . . . . . . . . . . . . . . . . . . . . . . . 79 PhoneWrite . . . . . . . . . . . . . . . . . . . . . . . . . . . 80 APPENDIX A: ERROR MESSAGES 81 Compiler Error Messages . . . . . . . . . . . . . . . . . . . . . . 81 Runtime Error Messages . . . . . . . . . . . . . . . . . . . . . . 83 INDEX 84 TELEMATE SCRIPT INTRODUCTION 1 INTRODUCTION ────────────────────────────────────────────────────────────────────────── TMScript allows you to write procedures to perform repetitive functions, such as a log on script, as well as specific applications, such as the host mode. TMScript is designed to be a easy-to-use language. TMScript looks similar to the Pascal language and the syntax is as loose as that of BASIC language. For most of the users, only the WAITFOR, PUT and maybe the WHEN statements are necessary. For those users who have experience in the other programming language, TMScript is a powerful tool for communication related application. A script file can be created using almost all editors. The source file is a normal ASCII text file which contains a sequence of instructions telling Telemate what to perform next. The source file should use the extension .SCR to indicate that it is a SCRipt file. Using TMS.EXE, the Script Compiler ────────────────────────────────────────────────────────────────────────── Once the source file is written, it must be compiled (translated) to a form that Telemate can load and interpret quickly. To compile a source file, type TMS [/d] filename where <filename> is the filename of the source file. The extension can be omitted if it is .SCR. TMS.EXE compiles the file 'filename.SCR' and produces the compiled script file 'filename.TMS'. For example, typing 'TMS \TM\HOST', TMS compiles '\TM\HOST.SCR' and produces '\TM\HOST.TMS'. If a syntax error is encountered in the source file, the compiler reports the line number and the type of the error. You should edit the source file and recompile until there is no more errors. If the optional /d parameter is specified, the compiler will consider undeclared variable as an error. This option can be used when writing larger script and you want to ensure you declare all the variables and to avoid spelling mistake on the variable name. TELEMATE SCRIPT INTRODUCTION 2 To Run a Script ────────────────────────────────────────────────────────────────────────── There are several ways to run a script. 1. Pressing [Alt S] at the Terminal Window opens the File Dialog and you are asked to identify which script file to be executed. 2. Put the script name in the link-script field of the phone directory. When the BBS is connected, the link-script is executed automatically. Link-scripts are sometimes referred as logon scripts because they perform repetitive logon procedure. 3. Type 'TM <scriptname>' at the DOS command line. For example, C>TM HOST put Telemate in host mode when start. 4. You may assign a function key to execute a script file using the "^\" macro sequence. For example, the function key [Alt 4] is "^\host", when you press [Alt 4], the host script will be executed. 5. The SCRIPT statement allows you run another script in a script program. Please refer the description of the SCRIPT statement. What Is Your Name ────────────────────────────────────────────────────────────────────────── The first example program is a simple logon script. It waits for the logon prompts and sends the response to the remote system. WAITFOR "What is your name?"; wait for the logon prompt PUT "my name" ; send your name to remote system WAITFOR "is your password?" ; wait for the password prompt PUT "my password" ; send your name to remote system A script can be as simple as that and it will help you to logon to the remote system automatically. TELEMATE SCRIPT DATA TYPES 3 DATA TYPES ────────────────────────────────────────────────────────────────────────── TMScript provides two basic data types, integer and string, and four extended data types, character, boolean, date and time. Integer ────────────────────────────────────────────────────────────────────────── Ordinary number notation is used for integers. Decimal and engineering notation (e or E followed by an exponent) is not supported. Integer must within the range from -2147483648 to 2147483647. String ────────────────────────────────────────────────────────────────────────── A string is a sequence of zero or more characters from extended ASCII character set (0-255), enclosed by quotation marks. A string with nothing in it is called a empty string. Two sequential quotation marks in a string denote a single character, an quotation mark. TMScript allows control characters to be embedded in strings. The '^' character followed by a letter (A-Z, a-z), '@' or '[' denotes a character of the ASCII code [Ctrl A] to [Ctrl Z], NULL, or ESC respective. Here are some examples of strings "TELEMATE" "This is a '""'." "^K^D" ; [Ctrl K] [Ctrl D] Character ────────────────────────────────────────────────────────────────────────── Character is represented as a string that contains only one character. For example, "A" is a character. Control codes are often used in script programs and are represented as Code String Description ────── ────── ─────────────── Ctrl-@ "^@" NULL Ctrl-A "^A" ... .. Ctrl-H "^H" Backspace Ctrl-I "^I" TAB Ctrl-J "^J" LF, line feed ... .. TELEMATE SCRIPT DATA TYPES 4 Ctrl-M "^M" CR, Carriage Return, [Enter] ... .. Ctrl-Z "^Z" Ctrl-[ "^[" Escape Boolean ────────────────────────────────────────────────────────────────────────── Boolean (TRUE or FALSE) is represented as a integer. A integer is said to be TRUE if it is not equal to zero, FALSE if it is equal to zero. When testing a boolean condition, you should not use the following code, IF CONNECTED=1 ... ENDIF because the variable CONNECTED may have other values. Instead, you should use IF CONNECTED ... ENDIF to test if CONNECTED is TRUE. And IF NOT CONNECTED ... ENDIF to test if CONNECTED is FALSE. Date ────────────────────────────────────────────────────────────────────────── Date is represented as a string with the format "MM-DD-YY". When a date string is compared with another date string, they are first converted to the internal format "YYMMDD" so that the comparison returns the correct result. Note that the date format option in the main program does not affect the format in the script. For date conversion, see ConvertDate command in toolbox #3. TELEMATE SCRIPT DATA TYPES 5 Time ────────────────────────────────────────────────────────────────────────── Time is also represented as a string but with the format "HH:MM:SS". When two time strings are being compared, they are converted to the internal format "HHMMSS" such that the comparison can the correct result. TELEMATE SCRIPT VARIABLES 6 VARIABLES ────────────────────────────────────────────────────────────────────────── Variable Identifiers ────────────────────────────────────────────────────────────────────────── A variable identifier can contain letters and digits. However, a variable can only start with a letter. Case is not significant, in the other word, the variable <notdone> is the same as <NotDone>. A variable identifier can be of any length, but only the first 8 characters are significant. For examples, the variable identifier <Number12> is the same as <Number123>. Variable Declarations ────────────────────────────────────────────────────────────────────────── A variable declaration embodies a list of identifiers that designate new variables and their type. For example, INTEGER lower,upper,step ; integers STRING message,filename ; strings INTEGER true,false ; boolean STRING ch,letter ; character The variable declaration part should be placed at the beginning of a script or of a procedure. In TMScript, variables need not declared before use if no procedure is defined. Therefore, the variable declaration part can be skipped. Predefined Variables ────────────────────────────────────────────────────────────────────────── TMScript built in procedures do not return value. Several predefined variables are set to the resulting value. They are CONNECTED, FOUND, SUCCESS, LOGGING, WIDTH and HEIGHT. TELEMATE SCRIPT VARIABLES 7 CONNECTED CONNECTED is set to the number of the connected entry (from 1 to 1000). The variable CONNECTED returns to FALSE as soon as the carrier lost. On the other hand, if the state of the carrier changes from OFF to ON, CONNECTED is set to TRUE. IF NOT CONNECTED PRINT "It is not connected to a remote system." STOP ENDIF SWITCH CONNECTED CASE 1: PRINT "connected to #1" CASE 3: PRINT "connected to #3" CASE 6: PRINT "connected to #6" ENDSWITCH The CONNECTED variable is also used in conjunction with the DIAL statement. If the dialing is successful and connect to a remote system, the variable is set to the number of the connected entry. If the DIAL statement aborts without connection, the variable CONNECTED is set to FALSE, indicating that the DIAL statement is aborted by operator or the number of attempt exceeds the dial attempt setting. For example, DIAL "1 3 6" IF NOT CONNECTED PRINT "Dialing process aborted" STOP ENDIF SWITCH connected CASE 1: PRINT "connected to #1" CASE 3: PRINT "connected to #3" CASE 6: PRINT "connected to #6" ENDSWITCH Note that this variable reflects the online status only if your modem reports so. You should check your modem manual to ensure that the modem CD (carrier detect) signal is reflecting the actual online status. Most modems use a "&C1" AT command to set it and you should add it to the modem init string. TELEMATE SCRIPT VARIABLES 8 FOUND This variable is set to resulting value after the WAITFOR statement is executed. It is set to FALSE if time exceeded. Otherwise, it is set to the string number of the matched string. For example, WAITFOR "NO CARRIER","thanks for calling","hang up now",100 SWITCH FOUND CASE 1: PRINT "'NO CARRIER' found" CASE 2: PRINT "'thanks for calling' found" CASE 3: PRINT "'hang up now' found" ENDSWITCH SUCCESS This variable is used by several statements. The resulting values and descriptions is shown in the following table. Statement Value Description ───────── ───── ────────────────────────────────────────── Append TRUE the file is successfully opened or created FALSE cannot create file ChDir TRUE directory changed FALSE invalid path Close TRUE file closed FALSE cannot close file Create TRUE the file is successfully created FALSE cannot create file Delete TRUE the file is successfully deleted FALSE cannot delete file FileSize TRUE the file size is determined successfully FALSE cannot open file InputCh ch TRUE a character is read into <ch> FALSE no character is available LoadFon TRUE the phone directory is successfully opened FALSE the phone directory cannot be opened LoadKey TRUE the keyboard file is successfully opened FALSE the keyboard file cannot be opened LoadMac TRUE the macro table is successfully opened FALSE the macro table cannot be opened TELEMATE SCRIPT VARIABLES 9 LoadPad TRUE the keypad table is successfully opened FALSE the keypad table cannot be opened LogOn TRUE the log file is successfully opened FALSE the log file cannot be created Open TRUE the file is successfully opened FALSE the file does not exist Read str TRUE a line is read into <str> FALSE end of file encountered. ReadCh ch TRUE a character is read into <ch> FALSE end of file encountered. Receive TRUE all files are received successfully FALSE file transfer aborted Rename TRUE the file is successfully renamed FALSE cannot rename file Seek TRUE the file pointer is moved successfully FALSE disk error Send TRUE all files are sent successfully FALSE file transfer aborted Tell pos TRUE the file pointer is stored in <pos> FALSE disk error Write TRUE write successary to file FALSE cannot write to file LOGGING This variable reflects the current file log status and has the values 0 log file close or log file not in use 1 log file open and capturing incoming data 2 log file in pause state WIDTH This variable stored the width of the zoomed terminal window which is equal to the screen width. Possible values are 80 or 132. TELEMATE SCRIPT VARIABLES 10 HEIGHT This variable is the height of the zoomed terminal window which is calculated as HEIGHT = screen height if ( menu bar present ) HEIGHT = HEIGHT - 1 if ( status line present ) HEIGHT = HEIGHT - 1 if ( HEIGHT < 24 ) HEIGHT = 24 For example, on EGA 43 line mode with both menu bar and status line present, HEIGHT is equal to 41. But on 25 line mode, HEIGHT is equal to 24, not 23, because Telemate's terminal has at least 24 lines though only 23 lines may be shown on screen. In this case, terminal will shift up and down to justify the display region. This variable may alter between two instructions if the users press [Alt -] to toggle the menu bar and status line. When programming full screen procedure, you should assume there are 23 lines in the screen and DO NOT scroll the screen by going to the last line and perform a line feed. TELEMATE SCRIPT EXPRESSIONS 11 EXPRESSIONS ────────────────────────────────────────────────────────────────────────── Rule Of Precedence ────────────────────────────────────────────────────────────────────────── Expressions are made up of operators and operands. In complex expressions, rule of precedence clarify the order in which operations are performed. Operators Precedence ────────────── ──────────── *,/ first (high) +,- second =,<>,<,>,<=,>= third not fourth and, or, xor fifth (low) There are the rules of precedence 1. First, an operand between two operators of difference precedence is bound to the operator with higher precedence. 2. Second, an operand between two equal operators is bound to the one on its left. 3. Third, expressions within parentheses are evaluated prior to being treated as a single operand. Arithmetic Operators ────────────────────────────────────────────────────────────────────────── The types of operands for arithmetic operators are shown in the following table. Operators Operation Operand Type ───────── ────────────── ──────────── + addition integer - subtraction integer * multiplication integer / division integer For example, the formula to convert Fahrenheit temperature to Celsius equivalents is celsius = (fahr-32) * 5 / 9 TELEMATE SCRIPT EXPRESSIONS 12 Boolean Operators ────────────────────────────────────────────────────────────────────────── The types of operands for arithmetic operators are shown in the following table. Operators Operation Operand Type ───────── ─────────── ──────────── not negation boolean and logical and boolean or logical or boolean xor logical xor boolean Normal Boolean logic governs the results of these operations. For instance, 'a and b' is TRUE only if both <a> an <b> are TRUE. Relational Operators ────────────────────────────────────────────────────────────────────────── The types of operands for arithmetic operators are shown in the following table. They all have the same precedence. Operators Operation Operand Types ───────── ──────────── ─────────────────────────── = equal to integer, string, date, time <> not equal to integer, string, date, time > greater than integer, string, date, time >= greater or integer, string, date, time equal to < less then integer, string, date, time <= less then or integer, string, date, time equal to When the operands are integer, date or time, the comparison will produce the usual result such as Condition Result Operands Type ─────────────────────── ────── ───────────── 1 > 2 FALSE integer "12-31-89" < "01-01-90" TRUE date "00:00:00" > "23:59:59" FALSE time However, if the operands are strings, the operators "<", ">" and "<>" have another meaning such that you can determine if a string is a sub- string of another string. s1 < s2 if s1 is a sub-string of s2 s3 > s4 if s3 is a super-string of s4 s5 <> s6 if s5 is not a sub-string of s6 and s5 is not a super-string of s6 TELEMATE SCRIPT EXPRESSIONS 13 For example, Condition Result Explanation ──────────────────── ────── ────────────────────────────────── "hello" = "Hello" TRUE TMScript is not case sensitive. "goodbye" < "bye" TRUE "bye" is a sub-string of "goodbye" "dog" <> "car" TRUE The string is not equal "abc" >= "xyz" FALSE "abc" is not a super-string of "xyz" and they are not equal. TELEMATE SCRIPT STRUCTURED STATEMENTS 14 STATEMENTS ────────────────────────────────────────────────────────────────────────── Statements describe algorithmic actions that can be executed. Comment ────────────────────────────────────────────────────────────────────────── Any characters after ";" are ignored by the TMScript compiler. Assignment Statement ────────────────────────────────────────────────────────────────────────── Assignment statements replace the current value of a variable with a new value specified by an expression. The expression must be assignment-compatible with the type of the variable. The program prints the following table of Fahrenheit temperatures and their centigrade or Celsius equivalents. 0 -17 20 -6 40 4 ... ... 280 137 300 148 Here is the program itself. ; Print Fahrenheit-Celsius table ; for f = 0, 20, ... , 300 INTEGER lower,upper,step INTEGER fahr,celsius lower = 0 ; lower limit of temperature table upper = 300 ; upper limit step = 20 ; step size fahr = lower ; first item in the table WHILE fahr <= upper celsius = (fahr-32) * 5 / 9 ; calcuate the values PRINT fahr,"^I",celsius ; print the result fahr = fahr + step ; next item in the table ENDWHILE TELEMATE SCRIPT STRUCTURED STATEMENTS 15 If Statement ────────────────────────────────────────────────────────────────────────── The general form for IF statement is IF condition statements ENDIF The <statements> is executed only if <condition> is TRUE. Another form is IF condition statements-1 ELSE statements-2 ENDIF One and only one of the two statements associated with an <if-else> is done. If the <condition> is true, <statements-1> is executed; if not, <statements-2> is executed. The construction IF condition-1 statements-1 ELSE IF condition-2 statements-2 ELSE IF condition-3 statements-3 ENDIF ENDIF ENDIF occurs so often that it is worth a new keyword ELSEIF. The statement can be re-written as IF condition-1 statements-1 ELSEIF condition-2 statements-2 ELSEIF condition-3 statements-3 ENDIF TELEMATE SCRIPT STRUCTURED STATEMENTS 16 Switch Statement ────────────────────────────────────────────────────────────────────────── The SWITCH statement is a special multi-way decision maker that tests whether an expression matches one of a number of values, an branches accordingly. The syntax for SWITCH statement is SWITCH expression CASE value-1: statements-1 CASE value-2,value-3: statements-2 OTHERWISE: statements-3 ENDSWITCH The SWITCH evaluates the expression and compares its value to all the cases. Each cases must be labeled by the values of the same type as the expression. Several values can be separated by comma. If a case matches the expression value, execution starts at that case and ends at the next case label. The case labeled OTHERWISE is executed if none of the other cases is satisfied. A OTHERWISE is optional; if it isn't there and if none of the cases matches, no action at all takes place. However, OTHERWISE, if exists, must be placed after all the case labels. The program counts digits, blanks, others. nDigit = 0 ; digit nBlank = 0 ; blank nOther = 0 ; others OPEN "MYFILE" ; open the file "MYFILE" READCH ch ; read the first character WHILE success ; if not end of file SWITCH ch CASE "0","1","2","3","4","5","7","8","9": ; is digit nDigit = nDight + 1 CASE " ": ; is blank nBlank = nBlank + 1 OTHERWISE: ; others nOther = nOther + 1 ENDSWITCH READCH ch ; read next character ENDWHILE CLOSE ; close the file PRINT nDigit ; print the results PRINT nBlank PRINT nOther TELEMATE SCRIPT STRUCTURED STATEMENTS 17 While Loop ────────────────────────────────────────────────────────────────────────── The WHILE loop is the most general loop. The syntax is WHILE condition statements ENDWHILE The <condition> is tested. If it is true, the body of the loop (all the statements before the keyword ENDWHILE is executed. Then the condition is re-tested, and if true, the body is executed again. When the test becomes false the loop ends, and execution continues at the statements that follows the loop. For example, to print the value from 1 to 100, you can write i = 1 ; start from 1 WHILE i<=100 ; check if it in the range PRINT i ; print the number i = i + 1 ; increase the counter by 1 ENDWHILE Repeat Loop ────────────────────────────────────────────────────────────────────────── While the WHILE loop test the condition at the top, the REPEAT loop test it at the bottom. It tests at the bottom after making each pass through the loop body; the body is always executed at least once. Consider the loop REPEAT statements UNTIL condition The statements is executed, then the condition is evaluated. If it is false, the statements is evaluated again, and so on. If the condition becomes true, the loop terminates. For example, to print the value from 1 to 100, you can write i = 1 ; start from 1 REPEAT PRINT i ; print the number i = i + 1 ; increase the counter by 1 UNTIL i>100 ; repeat until it is NOT in the range TELEMATE SCRIPT STRUCTURED STATEMENTS 18 Exit Statement ────────────────────────────────────────────────────────────────────────── It is sometimes convenient to be able to control loop exits other than by testing at the top or bottom. The EXIT statement provides an early exit from the loops. A EXIT statement causes the innermost loop to be exited immediately. The following program accept strings from keyboard, using a EXIT to exit from the loop when the string contains an [Esc] ("^["). REPEAT INPUT s IF "^[" <= s ; test if [Esc] is a sub-string of s EXIT ; before printing it ENDIF PRINT s UNTIL s = "" ; repeat until an empty string is entered #include Directive ────────────────────────────────────────────────────────────────────────── This compiler directive allows you to write reusable procedures in a separate file and imports the procedures conveniently. The syntax is #include "includefile" The <includefile> will be inserted as if it is physical appear in this point. The <includefile> must be a pathname with extension. For example, #include "TOOLBOX.SCR" #include "MYLIB.SCR" inserts the TOOLBOX.SCR and MYLIB.SCR into this point. The #include directive can be nested as deep as 10 levels. TELEMATE SCRIPT PROCEDURE 19 PROCEDURE ────────────────────────────────────────────────────────────────────────── In TMScript, a procedure is equivalent to a subroutine or function in Fortran, or procedure in Pascal, C etc. A procedure provides a convenient way to encapsulate some computation in a black box, which can then be used without worrying about its innards. For example, to swap the values of two variables, <i> and <j>, you have to write three lines as follows temp = i ; put <i> into a temporary variable i = j ; put <j> into <i> j = temp ; now put the value of <i> into <j> Suppose in your script there are a lot of swapping, it will be convenient to define a procedure called <swap> to perform the swapping. Then your main program will look like i = 1 j = 2 swap i,j ; now i=2, j=1 PRINT i ; 2 PRINT j ; 1 This is only a small usage of procedure. Imagine if the procedure is very complex, you can use it again and again once it is tested and performs what you need. Procedure Declaration ────────────────────────────────────────────────────────────────────────── The syntax of a procedure definition is PROCEDURE <procname> <parameter declaration> <local variable declaration> <statement part> ENDPROC <procname> is any valid identifier. <parameter declaration> can be omitted if the procedure does not required parameters. See next section for details on parameter declaration. <local variable declaration> made within a given procedure are visible only within that procedure. This part should ALWAYS be included in order to make the program easy to be traced although the declarations may be omitted. <statement part> can be considered as a sub-program of the main program and obeys all the rule described above. TELEMATE SCRIPT PROCEDURE 20 Parameter Declaration ────────────────────────────────────────────────────────────────────────── Parameter declaration is similar to variable declaration. For example, PROCEDURE sample STRING s,t,INTEGER i,j declares the procedure <sample> with two string parameters <s> and <t> and two integer parameters <i> and <j>. You may use any combination of STRING and INTEGER to define parameters. For example, PROCEDURE sample INTEGER i,STRING p,q,r,s,INTEGER j,k,STRING z We can write the <swap> procedure as PROCEDURE swap INTEGER value1,value2 ; swap two integers INTEGER temp ; declare a local variable temp = value1 ; store the first value value1 = value2 ; replace with the second value value2 = temp ; replace with the first value ENDPROC After that, the main program may look like i = 1 j = 2 k = 3 swap i,j ; now i=2, j=1 swap j,k ; now j=3, k=1 PRINT i,j,k ; 2,3,1 Calling Procedure and Parameter Passing ────────────────────────────────────────────────────────────────────────── Once the procedure is defined, it can be called by putting the procedure name in the statement part. In the example, the statements i = 1 j = 2 swap i,j ; now i=2, j=1 PRINT i,j ; 2,1 call the <swap> procedure with the parameters <i> and <j>. In the above example, the method used to pass <i> and <j> to the procedure <swap> is called 'pass by reference' because <i> and <j> can be changed when return. There is another method called 'pass by value' of which the parameter cannot be changed. TELEMATE SCRIPT PROCEDURE 21 Consider the following procedure PROCEDURE countDown INTEGER num ; print from <num> to 1 WHILE num >= 1 ; check if it is in the range PRINT num ; print it num = num-1 ; decrease until num=0 ENDWHILE ENDPROC countDown 100 ; pass by value n = 100 countDown n*2 ; pass by value (200) PRINT n ; n = 100 countDown (n) ; pass by value (100) PRINT n ; n = 100 countDown n ; pass by reference PRINT n ; n = 0 ! If we supply <countDown> with the parameter 100, n*2 or (n), they are 'pass by value'. On the other hand, <n> is 'pass by reference' in the last statement. The general rule of method of passing parameters is: When the parameter is a constant, an expression or surrounded by parentheses, it is 'pass by value'. Otherwise, it is a variable and is 'pass by reference'. The rule applies to string parameter as well. To prevent confusion, we should rewrite the <countDown> procedure by introducing a local variable. PROCEDURE countDown INTEGER num ; print from <num> to 1 INTEGER count ; introduce a local variable count = num ; if neccessary WHILE count >= 1 ; check if it is in the range PRINT count ; print it count = count-1 ; decrease until 0 ENDWHILE ENDPROC ; this does not change <num> TELEMATE SCRIPT PROCEDURE 22 Nested Procedures and Scope of Variables ────────────────────────────────────────────────────────────────────────── TMScript allows nested procedures; you can declare one procedure inside of another. For example, PROCEDURE outer STRING i,j PROCEDURE inner INTEGER i i = 100 PRINT "i = ",i PRINT "j = ",j ENDPROC i = "This is string 'i'." j = "This is string 'j'." inner PRINT "i = ",i PRINT "j = ",j ENDPROC The <outer> procedure declares two string variables, <i> and <j>. These two variables can be accessed by both the <outer> procedure and the <inner> one because they are declared before the <inner> procedure. The <inner> procedure declares an integer variable <i>. Although the two <i>'s share the same name, they are not identical. The inner <i> is visible in the <inner> procedure but not in the <outer> procedure. On the other hand, the outer <i> can no longer be accessible in the <inner> procedure. The statement i = 100 does not affect the outer <i>. This is called the scope rule. The output of the program is i = 100 j = This is string 'j'. i = This is string 'i'. j = This is string 'j'. TELEMATE SCRIPT PROCEDURE 23 Return Statement ────────────────────────────────────────────────────────────────────────── Like the EXIT statement, it is sometimes convenient to be able to return from a procedure at the middle of the procedure. The following procedure accept strings from keyboard and print it, using a RETURN to return from the procedure when the string contains an [Esc] ("^["). PROCEDURE acceptString STRING s INPUT s IF "^[" <= s ; test if [Esc] is a sub-string of s RETURN ; before printing it ENDIF PRINT s ENDPROC TELEMATE SCRIPT BUILT IN PROCEDURES BY CATEGORY 24 BUILT IN PROCEDURES BY CATEGORY ────────────────────────────────────────────────────────────────────────── Console I/O ────────────────────────────────────────────────────────────────────────── There are eight statements in the group of console input and output. Namely, Input, InputCh, Print, AT, Clear Text, Clear Key, WhereX, WhereY PRINT Statement Output is simple, the PRINT statement can print variable or constant of types integer or string to the terminal window. For example, PRINT "hello, world" print the words hello, world to the terminal window. PRINT supplies a newline automatically. However, if a comma "," follows the string, no newline is supplied. The statement above could just as well have been written PRINT "hello, ", PRINT "world", PRINT to produce an identical output. The last PRINT statement supplies a newline. PRINT statement accepts more than one argument. Each two arguments are separated by a comma. For example, PRINT "x = ",x PRINT "My name is ",firstName," ",lastName PRINT COM I/O ────────────────────────────────────────────────────────────────────────── As a communication program, TMScript provides thirteen I/O statements that communicate with the remote system. They are Get, GetCh, Put, Clear COM, ComInCount, ComOutCount HangUp, Receive, Send, Waitfor, When, WhenIdle TELEMATE SCRIPT BUILT IN PROCEDURES BY CATEGORY 25 PUT Statement COM output is as simple as console output, the PUT statement can send variable or constant of types integer or string to the remote system. For example, PUT "first last" send the words first last and a carriage return [Ctrl M] to the remote system. PUT supplies a carriage return automatically. However, if a comma "," follows the string, no carriage return is supplied. The statement above could just as well have been written PUT "first ", PUT "last", PUT to produce an identical output. The last PUT statement supplies a carriage return only. PUT statement accepts more than one argument. Each two arguments are separated by a comma. For example, PUT firstName,";",lastName,";",password WAITFOR Statement The WAITFOR statements waits for specified stirngs from the remote system in a specified time. In TMScript, you can specify more than one string to wait for. If any of them is received, the FOUND variable is set to a non-zero value (TRUE). Combined with the PUT statement, you can tell Telemate when to send a string to the remote system. Syntax Description ────────────────────────── ───────────────────────────────── WAITFOR t Set default waiting time WAITFOR s1,s2, ... , sN Wait until one of the strings is received WAITFOR s1,s2, ... , sN, t Wait until one of the strings is received or waiting time exceeded TELEMATE SCRIPT BUILT IN PROCEDURES BY CATEGORY 26 For example, the following code segment are usally used in a logon script program. WAITFOR "first",30 ; wait for "first" in 30 seconds IF NOT FOUND STOP ; stop if prompt not found ENDIF PUT "my name" ; send the name WAITFOR "password",5 ; wait for "password" in 5 seconds IF NOT FOUND STOP ; stop if prompt not found ENDIF PUT "^&" ; send the password field (^&) in ; in the phone directory File Handling ────────────────────────────────────────────────────────────────────────── One text file is allowed to open at a time. The file is open or created as a read/write file. The file handling procedures are Open, Created, Append, Read, ReadCh, Write, Seek, Tell, Close, ChDir, Delete, Rename, FileExist, FileSize The predefined variable SUCCESS is set to FALSE if there is any error. String Handling ────────────────────────────────────────────────────────────────────────── A string is a sequence of character. The limit of the length of a string is 512 characters. When referring to a character position, the position is counted from 1. The string handling procedures are Atoi, Concat, Itoa, Length, StrDel, StrIns, StrPos, StrSet, SubStr Miscellaneous Routines ────────────────────────────────────────────────────────────────────────── Alarm, Atoi, Date, Delay, Dial, Dos, ExitTelemate, Image, Itoa, Keystroke, LoadFon, LoadKey, LoadMac, LoadPad, LogOff, LogOn, LogPause, LogResume, Query, Script, Set, Time, WaitUntil TELEMATE SCRIPT BUILT IN PROCEDURES 27 BUILT IN PROCEDURES ────────────────────────────────────────────────────────────────────────── Alarm ────────────────────────────────────────────────────────────────────────── Function Pop-up the alarm dialog. Syntax ALARM ALARM message Remarks If the string <message> is specified, it is displayed in the alarm dialog. If the message is too long, it can be split to several lines by putting a "^J" between each line. Return If the operator press [Enter] or click the OK button in the alarm dialog, SUCCESS is set to TRUE (non-zero). If the operator press [Esc] or the alarm time excess, SUCCESS is set to FALSE (zero). See also Set AlarmSound, Set AlarmTime Example RECEIVE "s" IF NOT SUCCESS ALARM "Warning: File transfer aborted" IF NOT SUCCESS ; if timeout, print message on screen PRINT "Warning: File transfer aborted" ENDIF ENDIF ALARM "Alarm:^JThis is a^Jvery long message" Append ────────────────────────────────────────────────────────────────────────── Function Opens a text file, creates it if necessary, and moves the file pointer to the end of the file. Syntax APPEND filename Remark APPEND opens the text file as a read/write file and strip the ending EOF [Ctrl Z]. Return Upon successful completion, SUCCESS is set to TRUE. If the file cannot be created, SUCCESS is set to FALSE. TELEMATE SCRIPT BUILT IN PROCEDURES 28 See also Create, Open At ────────────────────────────────────────────────────────────────────────── Function Positions cursor in terminal window. Syntax AT column,row Remark AT moves the cursor to the position within the terminal window. The upper left corner is (0,0) and the lower right corner is (79,24) if a 25 rows terminal is used. See also Print Atoi ────────────────────────────────────────────────────────────────────────── Function Converts a string to an integer. Syntax ATOI s,i Return <i> contains the converted value or 0 if <s> cannot be converted to a number. See also Itoa ChDir ────────────────────────────────────────────────────────────────────────── Function Changes current directory. Syntax CHDIR path Remark CHDIR causes the directory specified by <path> to become the current working directory. <path> must specify an existing directory. A drive can also be specified in <path> but it changes only the current directory on that drive; it doesn't change the active drive. Return Upon successful completion, SUCCESS is set to TRUE; otherwise, SUCCESS is FALSE. See also Delete, FileExist, Rename TELEMATE SCRIPT BUILT IN PROCEDURES 29 Clear COM ────────────────────────────────────────────────────────────────────────── Function Clears the COM buffer. Syntax CLEAR COM Remark Data being sent and received are placed in a COM buffer, sometimes it is necessary to clear the buffer before processing. See also Get, GetCh, Put Example GET s ; get a string DELAY 50 ; wait for 5 seconds CLEAR COM ; clear the received data in the last 5 seconds GET s ; get another string Clear Key ────────────────────────────────────────────────────────────────────────── Function Clears the keyboard buffer and gives up keyboard control after a INPUT or INPUTCH statement. Syntax CLEAR KEY Remark CLEAR KEY clears the content of the keyboard buffer. Keyboard input before this statement are thrown away. When the INPUT or INPUTCH statement in the script is executed, the following input characters are placed in a keyboard buffer no matter if we want to read the next key or not. As a result, the following characters are NOT sent to the remote system automatically. It is important to give up the control of keyboard whenever no more keyboard input is needed and the clear key statement is built for this purpose. See also Input, InputCh Example PRINT "Input filename:" INPUT filename ; ask the user to input a filename CLEAR KEY ; give up keyboard control such that ; following keys are sent to remote ; system automatically TELEMATE SCRIPT BUILT IN PROCEDURES 30 Clear Text ────────────────────────────────────────────────────────────────────────── Function Clears the terminal window. Syntax CLEAR TEXT Remark CLEAR TEXT clears the terminal window and positions the cursor to the upper-left corner. It sets the display attribute to the initial setup. Close ────────────────────────────────────────────────────────────────────────── Function Closes a file. Syntax CLOSE Return Upon successful completion, SUCCESS is set to TRUE; otherwise, SUCCESS is FALSE. See also Open, Read, Write ComInCount ────────────────────────────────────────────────────────────────────────── Function Gets the number of characters in the incoming COM buffer. Syntax COMINCOUNT count Remark Telemate has an incoming COM buffer of 8000 bytes. Return <count> contains the number of characters in the incoming COM buffer. See also Clear COM ComOutCount ────────────────────────────────────────────────────────────────────────── Function Gets the number of characters in the outgoing COM buffer. Syntax COMOUTCOUNT count Remark Telemate has an outgoing COM buffer of 2000 bytes. Return <count> contains the number of characters in the outgoing COM buffer. TELEMATE SCRIPT BUILT IN PROCEDURES 31 See also Clear COM Concat ────────────────────────────────────────────────────────────────────────── Function Appends one string to another Syntax CONCAT dest,src Remark CONCAT appends a copy of <src> to the end of the string <dest>. If the backspace character "^H" is encountered in <src>, the last character of the concatenating string is erased. Return <dest> contains the concatenated string. See also Length, StrDel, StrIns Example s = "abc" ; s = "abc" CONCAT s,"xyz" ; s = "abcxyz" CONCAT s,"^H" ; s = "abcxy" CONCAT s,"pq" ; s = "abcxypq" Create ────────────────────────────────────────────────────────────────────────── Function Creates a new text file or rewrites an existing one. Syntax CREATE filename Remark CREATE creates the new text file <filename>. If the file already exists, the old file is deleted. Return Upon successful completion, SUCCESS is set to TRUE; otherwise, SUCCESS is FALSE. See also Append, Open Date ────────────────────────────────────────────────────────────────────────── Function Gets system date. Syntax DATE today TELEMATE SCRIPT BUILT IN PROCEDURES 32 Remark DATE fills the string <today> with the current date. Dates can be compared with the usual '<', '>' and '=' relational operator. The date format option in the main program does not affect the format in the script language. Return <today> contains the system current date in MM-DD-YY format. See also Time, ConvertDate Example DATE today IF today>="01-01-91" AND today<"01-05-91" PRINT "Happy New Year!" ENDIF Delay ────────────────────────────────────────────────────────────────────────── Function Suspends script execution for an interval. Syntax DELAY t Remark With a call to DELAY, the script program is suspended from execution for the number of tenth seconds specified by <t>. Example DELAY 15 ; wait for one and a half second Delete ────────────────────────────────────────────────────────────────────────── Function Deletes one or more files Syntax DELETE filename Remark DELETE deletes one or more files specified by <filename>. Wildcards are allowed in <filename>. Return On successful completion, SUCCESS is set to TRUE; otherwise, SUCCESS is FALSE. See also FileExist, Rename TELEMATE SCRIPT BUILT IN PROCEDURES 33 Dial ────────────────────────────────────────────────────────────────────────── Function Dials a list of entries or redials the current list. Syntax DIAL DIAL list Remark DIAL redials the the current list of entries. If <list> is specified, the current list is replaced by <list> and start dialing. The <DialAttempt> option is the maximum of number of dialing attempt. The <DialList> option can be used to specify the current dial list. Return DIAL sets CONNECTED to the number of the connected entry. If the operator press [Esc] to abort the dialing process or the attempts excess the <DialAttempt> option, CONNECTED is set to 0 (FALSE). See also Set AutoRedial, Set DialAttempt, Set DialList, Set DialPause, Set DialTime, Set MultiLine Example SET DialAttempt,3 ; try each entry once SET DialList,"1 3 6" ; set the dial list DIAL ; equivalent to a DIAL "1 3 6" statement IF NOT CONNECTED PRINT "All boards are busy." ELSE SWITCH CONNECTED CASE 1: PRINT "connected to #1" CASE 3: PRINT "connected to #3" CASE 6: PRINT "connected to #6" ENDSWITCH ENDIF SET DialAttempt,0 ; unlimit the maximum attempt Dos ────────────────────────────────────────────────────────────────────────── Function Jumps to DOS or issues a DOS command. Syntax DOS DOS command TELEMATE SCRIPT BUILT IN PROCEDURES 34 Remark The DOS statement invokes the DOS COMMAND.COM file to execute a DOS command, batch file, or other program named by the string <command>. the program must be in the current directory or in one of the directories listed in the PATH environment string. If <command> is not specified, the DOS statement jumps to DOS and return when users enter 'EXIT' in the DOS command line. If the <SwapToEms> or the <SwapToDisk> option is turned on, Telemate swaps part of itself to second storage and, hence, leaves more memory space for the DOS shell. The COMSPEC envirnoment string is used to find the COMMAND.COM file. If your COMMAND.COM is not in the root directory - suppose in the C:\DOS directory, you should include the following in the AUTOEXEC.BAT startup file. SET COMSPEC=C:\DOS\COMMAND.COM See also Set SwapToDisk, Set SwapToEms, Set MaxDosShell Example QUERY SwapToEms,ems ; store the original options QUERY SwapToDisk,disk QUERY MaxDosShell,max SET SwapToEms,on ; provide more working space SET SwapToDisk,on ; for external program SET MaxDosShell,off ; DOS "TMSTAT TM.USE" ; run the TMSTAT.EXE program SET SwapToEms,ems SET SwapToDisk,disk ; restore the original options. SET MaxDosShell,max ExitTelemate ────────────────────────────────────────────────────────────────────────── Function Terminates Telemate's execution. Syntax EXITTELEMATE EXITTELEMATE exitCode Remark EXITTELEMATE terminates Telemate and return to DOS. The file in the Edit window is saved automatically if necessary. If <exitCode> is not specified, Telemate exits to DOS with the error level 0. Otherwise, the error level is set to <exitCode>. Typically a value of 0 is used to indicate a normal exit, and a nonzero value indicates some errors. TELEMATE SCRIPT BUILT IN PROCEDURES 35 FileExist ────────────────────────────────────────────────────────────────────────── Function Determines if a file or directory is exist. Syntax FILEEXIST filename,existFlag Remark FILEEXIST checks the file named by <filename> to determines if it is exists. Wildcards are allowed in <filename>. Return If the file is exist, <existFlag> is set to TRUE; otherwise, <existFlag> is FALSE. See also Delete, Rename FileSize ────────────────────────────────────────────────────────────────────────── Function Gets file size in bytes. Syntax FILESIZE filename,size Remark FILESIZE returns the length, in bytes, of the file specified by <filename>. Return If <filename> exist, <size> is set to the file size and SUCCESS is set to TRUE; otherwise, SUCCESS is set to FALSE. See also Read, Seek Get ────────────────────────────────────────────────────────────────────────── Function Gets a string from remote system. Syntax GET s Remark GET collects a string, terminated by a carriage return, from the remote system. GET does not eliminate the BackSpace character [Ctrl H] from the input, therefore a CONCAT statement should be perform after the GET statement to eliminate the BackSpace character. Return <s> contains the collected string. The ending carriage return is discarded. TELEMATE SCRIPT BUILT IN PROCEDURES 36 See also Clear COM, ComInCount, GetCh Example GET s ; get a string from remote system filename = "" ; prepare the variable CONCAT filename,s ; eliminate the BackSpace GetCh ────────────────────────────────────────────────────────────────────────── Function Gets a character from remote system. Syntax GETCH ch Remark GETCH gets a single character from the remote system. If no character is available, GETCH return immediately. GETCH statement, like the INKEY$ function in BASIC, does not wait. Return If a character is successfully read into <ch>, SUCCESS is set to TRUE; otherwise, SUCCESS is set to FALSE. See also Get Example REPEAT ; to wait for a character, GETCH ch ; repeat the GETCH until UNTIL SUCCESS ; a character is available HangUp ────────────────────────────────────────────────────────────────────────── Function HangUps the modem. Syntax HANGUP Remark HANGUP sends the modem hangup string to modem. If the hangup string is the "^#" macro sequence, Telemate hangs up the modem by dropping DTR. Image ────────────────────────────────────────────────────────────────────────── Function Captures the terminal screen into an image file. Syntax IMAGE IMAGE filename TELEMATE SCRIPT BUILT IN PROCEDURES 37 Remark IMAGE captures the terminal screen into an image file by appending the screen to the file <filename>. If no <filename> is supplied, the last image filename is used. Input ────────────────────────────────────────────────────────────────────────── Function Reads a string from the keyboard. Syntax INPUT s Remark INPUT collects a string, terminated by a [Enter], from the keyboard. When the INPUT statement in the script is executed, the following input characters are placed in a keyboard buffer no matter if they are to be read or not. As a result, they NOT sent to the remote system automatically. It is important to give up the control of keyboard whenever no more keyboard input is needed using the CLEAR KEY statement. INPUT does not eliminate the BackSpace character [Ctrl H] from the input, therefore a CONCAT statement should be perform after the INPUT statement to elimate the BackSpace character. Return <s> contains the collected string. The ending [Enter] is discarded. See also Clear Key, InputCh Example INPUT s ; get a string from remote system filename = "" ; prepare the variable CONCAT filename,s ; eliminate the BackSpace CLEAR KEY ; give up keyboard control such that ; following keys are sent to remote ; system automatically InputCh ────────────────────────────────────────────────────────────────────────── Function Reads a character from the keyboard. Syntax INPUTCH ch TELEMATE SCRIPT BUILT IN PROCEDURES 38 Remark INPUTCH gets a single character from the keyboard. If no character is available, INPUTCH returns immediately. INPUTCH statement, like the INKEY$ function in BASIC, does not wait. When the INPUTCH statement in the script is executed, the following input characters are placed in a keyboard buffer no matter if they are to be read or not. As a result, they are NOT sent to the remote system automatically. It is important to give up the control of keyboard whenever no more keyboard input is needed using the CLEAR KEY statement. Return If a character is successfully read into <ch>, SUCCESS is set to TRUE; otherwise, SUCCESS is set to FALSE. See also Clear Key, Input Example REPEAT ; to wait for a character, INPUTCH ch ; repeat the INPUTCH until UNTIL SUCCESS ; a character is available CLEAR KEY ; give up keyboard control such that ; following keys are sent to remote ; system automatically Itoa ────────────────────────────────────────────────────────────────────────── Function Converts an integer to a string. Syntax ITOA i,s Remark ITOA converts the integer <i> to a string and store it into <s>. Return <s> contains the string representation of the value <i>. See also Atoi Keystroke ────────────────────────────────────────────────────────────────────────── Function Simulates keystrokes. Syntax KEYSTROKE s TELEMATE SCRIPT BUILT IN PROCEDURES 39 Remark KEYSTROKES simulates keystrokes as if they are generated by the keyboard, including [Alt] keys. It is equivalent to the '^-' keystroke simulation macro, except that the string <s> does not include the '^-' symbol. Example KEYSTROKE "`1200`2e00`1400`1900" ; generates [Alt E] [Alt C] [Alt T] [Alt P] which switch to the ; editor, copy the marked text to the clipboard, switch to the ; terminal and paste the content in the clipboard to the remote ; system. Length ────────────────────────────────────────────────────────────────────────── Function Calculates the length of a string. Syntax LENGTH s,len Return <len> is the length of <s>. If <s> is an empty, <len> is 0. LoadFon ────────────────────────────────────────────────────────────────────────── Function Loads a phone directory. Syntax LOADFON phoneDir Remark LOADFON loads the <phoneDir> with extension .FON and the corresponding memo file .MEM into the dial window. If <phoneDir> does not include a directory, the Telemate directory is used. The extension .FON can be omitted. Return Upon successful completion, SUCCESS is set to TRUE; if <phoneDir> does not exist, SUCCESS is FALSE. See also Dial Example LOADFON "LONGDIST.FON" TELEMATE SCRIPT BUILT IN PROCEDURES 40 LoadKey ────────────────────────────────────────────────────────────────────────── Function Loads a keyboard definition table. Syntax LOADKEY keyTable Remark LOADKEY loads the <keyTable> with extension .KEY. If <keyTable> does not include a directory, the Telemate directory is used. The extension .KEY can be omitted. Return Upon successful completion, SUCCESS is set to TRUE; if <keyTable> does not exist, SUCCESS is FALSE. Example LOADKEY "EUROPE.KEY" LoadMac ────────────────────────────────────────────────────────────────────────── Function Loads a macro definition table. Syntax LOADMAC macroTable Remark LOADMAC loads the <macroTable>, with extension .MAC into the macro window. If <macroTable> does not include a directory, the Telemate directory is used. The extension .MAC can be omitted. Return Upon successful completion, SUCCESS is set to TRUE; if <macroTable> does not exist, SUCCESS is FALSE. Example LOADMAC "CIS.MAC" LoadPad ────────────────────────────────────────────────────────────────────────── Function Loads a keypad definition table. Syntax LOADPAD keypadTable TELEMATE SCRIPT BUILT IN PROCEDURES 41 Remark LOADPAD loads the <keypadTable>, with extension .PAD into the macro window. If <keypadTable> does not include a directory, the Telemate directory is used. The extension .PAD can be omitted. Return Upon successful completion, SUCCESS is set to TRUE; if <keypadTable> does not exist, SUCCESS is FALSE. Example LOADPAD "VT102DEL.PAD" LogOff ────────────────────────────────────────────────────────────────────────── Function Closes the log file. Syntax LOGOFF Remark LOGOFF closes a previous opened log file. Return LOGGING is set to 0 (FALSE). See also LogOn, LogPause, LogResume LogOn ────────────────────────────────────────────────────────────────────────── Function Opens a log file and captures incoming data into the file. Syntax LOGON LOGON filename Remark LOGON opens the log file <filename> and starts capturing the incoming data into it. If <filename> is not supplied, the filename specified in the last LOGON statement is used. If there is no prevous LOGON statement, the one in the log file field of the phone directory is used. If this field is empty, "TM.LOG" is used. Return Upon successful completion, SUCCESS is set to TRUE and LOGGING is set to 1 (TRUE); otherwise, SUCCESS is 0 (FALSE). See also LogOff, LogPause, LogResume TELEMATE SCRIPT BUILT IN PROCEDURES 42 LogPause ────────────────────────────────────────────────────────────────────────── Function Pauses capturing incoming data into the log file. Syntax LOGPAUSE Remark LOGPAUSE pauses capturing incoming data. The LOGGING variable should be checked to determine if a log file open. A value of 1 indicates a log file is open. Return LOGGING is set to 2. See also LogOff, LogOn, LogResume LogResume ────────────────────────────────────────────────────────────────────────── Function Resumes capturing incoming data into the log file. Syntax LOGRESUME Remark LOGRESUME resumes capturing incoming data. The LOGGING variable should be checked to determine if the log file is in pause. A value of 2 indicates the log file is in pause. Return LOGGING is set to 1. See also LogOff, LogOn, LogPause Open ────────────────────────────────────────────────────────────────────────── Function Opens a text file for reading or writing. Syntax OPEN filename Remark OPEN opens the text file <filename> for reading and writing and strip the ending EOF [Ctrl Z]. OPEN closes the previously open file automatically if no CLOSE command is issued to that file. Return Upon successful completion, SUCCESS is set to TRUE. If <filename> does not exist, SUCCESS is FALSE. See also Append, Close, Create, FileExist, FileSize, Read, Seek, Tell, Write TELEMATE SCRIPT BUILT IN PROCEDURES 43 Example OPEN "MYFILE" ; open the file "MYFILE" IF NOT SUCCESS ; report if not found PRINT "File not found." STOP ENDIF READ s ; read the first line PRINT s ; print it CLOSE ; close the file OPEN "FILE1" ; open FILE1 OPEN "FILE2" ; close FILE1 and open FILE2 Print ────────────────────────────────────────────────────────────────────────── Function Prints integers or strings to the terminal screen. Syntax PRINT PRINT s PRINT i PRINT s1,s2,i1,i2,s3, ... PRINT s1,s2,i1,i2,s3, ... , Remark PRINT outputs variables or constants of integer or string to the terminal screen. Each two arguments are separated by a comma. PRINT supplies a newline by default. If a comma follows, no newline is supplied. See also At, WhereX, WhereY Example PRINT "hello, world" ; say hello to everyone PRINT "hello, ", ; say that again PRINT "world", PRINT PRINT "x = ",x ; output multiple strings or integers PRINT "My name is ",firstName," ",lastName TELEMATE SCRIPT BUILT IN PROCEDURES 44 Put ────────────────────────────────────────────────────────────────────────── Function Sends strings or integers to the remote system. Syntax PUT PUT s PUT i PUT s1,s2,i1,i2,s3, ... PUT s1,s2,i1,i2,s3, ... , Remark Like the PRINT statement, PUT sends variables or constants of types integer or string to the remote system. Each two arguments are separated by a comma. Integers are converted to their string representation automatically before transmitting to the remote system. PUT supplies a carriage return [Ctrl M] by default. If a comma follows, no carriage return is supplied. Control characters can be sent by using the '^' prefix. For example, "^C" represents the [Ctrl C], "^M" the carriage return [Enter] and "^[" the Escape key [Esc]. The following macro sequences have special meanings. ^^ the character '^' ^~ the character '~' ~ pause 0.5 second ^# drop DTR signal to hangup modem ^% break signal ^$ memo field in phone directory ^& password field in phone directory ^* modem hangup string ^( modem init string ^) modem answer string See also Clear COM, ComOutCount, Waitfor Example PUT "first last" ; transmit first name and last name ; then a carriage return (^M) PUT "first ", ; same as above PUT "last", PUT PUT ; these two lines are PUT "^M", ; equivalent TELEMATE SCRIPT BUILT IN PROCEDURES 45 firstName = "first" ; set first and last name lastName = "last" password = "^&" ; use the password field in TM.FON PUT firstName," ",lastName,"^M~~~~",password ; send name, [Enter], wait for 2 seconds then send ; the password, [Enter] PUT "~^#~~^)", ; wait 0.5 second, drop DTR, ; wait 1 second, then sends the ; modem answer string Query ────────────────────────────────────────────────────────────────────────── Function Queries option value. Syntax QUERY <OPTION>,<VALUE> Remark The QUERY statement gives you the ability to peek most of the system options. All the options that the SET command accept can be queried by the QUERY command. The returning value is the same as that in the SET command. In addition, the following options are accepted by the QUERY command: <OPTION> <VALUE> Description ───────────── ──────── ────────────────────────────────── Board "..." return the board name of the connected entry Phone "..." return the phone number of the connected entry Password "..." return the password of the connected entry Total nnn return the total number of connection of the connected entry LastCall "MM-DD-YY" return the date of the connected entry Memo "..." return the memo of the connected entry This command should be used to store the value of an option before modifying the option and then restore the option to its original before the execution stops. See also Set TELEMATE SCRIPT BUILT IN PROCEDURES 46 Example QUERY zAutoDownload,autoZmodem SET zAutoDownload,off RECEIVE "z" SET zAutoDownload,autoZmodem QUERY board,bbs QUERY password,pw QUERY memo,mm PRINT "#",CONNECTED," ",bbs," ",pw," ",mm QUERY diallist,list PRINT list QUERY connection,conn SWITCH conn CASE 0: PRINT "Modem" CASE 1: PRINT "Computer" CASE 2: PRINT "Fossil" CASE 3: PRINT "BIOS" ENDSWITCH QUERY parity,par SWITCH par CASE 0: PRINT "None" CASE 1: PRINT "Odd" CASE 2: PRINT "Even" CASE 3: PRINT "Space" CASE 4: PRINT "Mark" ENDSWITCH QUERY terminal,term SWITCH term CASE 0: PRINT "TTY" CASE 1: PRINT "ANSI" CASE 2: PRINT "VT52" CASE 3: PRINT "VT102" CASE 4: PRINT "AVATAR" CASE 5: PRINT "PRISM" ENDSWITCH Read ────────────────────────────────────────────────────────────────────────── Function Reads a string from a text file. Syntax READ s TELEMATE SCRIPT BUILT IN PROCEDURES 47 Remark READ reads characters from the file into <s>. READ does not place the newline sequence CR-LF into the string. Return On success, <s> contains the string read and SUCCESS is set to TRUE. SUCCESS is FALSE on end-of-file or error. See also Close, Open, ReadCh, Seek, Tell Example OPEN "MYFILE" ; count lines in the file MYFILE IF NOT SUCCESS PRINT "File not found." STOP ; stop if file not found ENDIF n = 0 ; number of line = 0 READ str ; read a line WHILE SUCCESS ; repeat until end of file n = n + 1 ; increase counter READ str ; read the next string ENDWHILE CLOSE ; close the file PRINT "There are ",n," lines in the file" OPEN "TM.FON" ; read a record from the phone directory recno = 10 ; read the record #10 reclen = 131 ; record length of a entry SEEK recno*reclen ; seek to the record position READ record ; read the record CLOSE ReadCh ────────────────────────────────────────────────────────────────────────── Function Reads a character from a text file. Syntax READCH ch Remark READCH reads a single character from the file into <ch>. In a text file, a CR [Ctrl M] followed by a LF [Ctrl J] indicates end-of-line. Return On success, <ch> contains the character read and SUCCESS is set to TRUE. SUCCESS is FALSE on end-of-file or error. See also Close, Open, ReadCh, Seek, Tell TELEMATE SCRIPT BUILT IN PROCEDURES 48 Receive ────────────────────────────────────────────────────────────────────────── Function Receives (Downloads) one or more files from the remote system. Syntax RECEIVE protocol RECEIVE protocol,filename Remark RECEIVE receives (download) one or more files from the remote system using the protocol <protocol>. <protocol> can be one of the following or the menu key for external protocol. <protocol> Protocol <filename> needed ────────── ──────── ───────────────── "Z" Zmodem No "Y" Ymodem No "G" Ymodem-G No "B" Batch Ymodem No "X" Xmodem Yes "O" Xmodem-1K Yes "R" Relaxed Xmodem Yes "T" Telink No "S" SEAlink No "M" Modem7 No "K" Kermit No "C" CIS Quick B No "A" ASCII Yes For protocols, such as Xmodem, which does not pass the name, <filename> should contains the name being received. Wildcards are not allowed. If <filename> is "" and <GuessFile> option is on, the guessing name is used. Zmodem has the ability to start automatically which is called Zmodem AutoDownload - the <zAutoDownload> option. To prevent the download starts before the command RECEIVE "Z" is issued, the <zAutoDownload> option should be turned off before telling the remote system to start the transfer. Return If the file transfer is successful, SUCCESS is set to TRUE; SUCCESS is FALSE if the transfer abort. For external protocols, SUCCESS is always set to TRUE. See also Send, Set GuessFile, Set zAutoDownload, Waitfor TELEMATE SCRIPT BUILT IN PROCEDURES 49 Example RECEIVE "x","file.zip" ; Xmodem needs the filename RECEIVE "y" ; Ymodem doesn't RECIEVE "x","" ; use the guessing name as filename QUERY zAutoDownload,auto ; store the auto download option SET zAutoDownload,off ; you must turn it off before you tell WAITFOR "command",10 ; the remote system to send the files, PUT "d z *.zip" ; otherwise, the system's AutoDownload RECEIVE "z" ; procedure will take the control and ; the RECEIVE command will return a ; wrong SUCCESS value, after the SET zAutoDownload,auto ; transfer, you may restore it IF SUCCESS PRINT "File received successfully" ELSE PRINT "File transfer aborted" ENDIF Rename ────────────────────────────────────────────────────────────────────────── Function Renames a file. Syntax RENAME oldname,newname Remark RENAME changes the name of a file from <oldname> to <newname>. Directories in <oldname> and <newname> need not be the same, therefore, RENAME can be used to move a file from one directory to another. Wildcards are not allowed. Return On successfully renameing the file, SUCCESS is set to TRUE; otherwise, SUCCESS is FALSE. See also Delete, FileExist Script ────────────────────────────────────────────────────────────────────────── Function Executes another script program. Syntax SCRIPT scriptName TELEMATE SCRIPT BUILT IN PROCEDURES 50 Remark SCRIPT terminates the execution of the current script and executes the script program <scriptName>. <scriptName> may not contain the extension part of a filename. If <scriptName> does not include a path, the Script directory is used. Example SCRIPT "HOST" ; executes the HOST.SCR in the Script directory Seek ────────────────────────────────────────────────────────────────────────── Function Repositions the file pointer. Syntax SEEK filepos Remark SEEK sets the file pointer to the new position <filepos>. At the beginning of a file, the file pointer is 0. If <filepos> is -1, the file pointer is moved to the end of the file. Return If the pointer is successfully moved, SUCCESS is set to TRUE; otherwise, SUCCESS is FALSE. See also Read, ReadCh, Tell, Write Example ; suppose TM.FON is open, to read record #10 without changing ; the file position, the TELL statement should be used TELL filepos ; store file position SEEK 10*131 ; move to record #10, each record is 131 bytes READ record ; read the record SEEK filepos ; move back to previous position Send ────────────────────────────────────────────────────────────────────────── Function Sends (uploads) one or more files to remote system. Syntax SEND protocol,filenames TELEMATE SCRIPT BUILT IN PROCEDURES 51 Remark SEND sends (uploads) one or more files to the remote system using the protocol <protocol>. <protocol> can be one of the following or the menu key for external protocol. <protocol> Protocol Send multiple files ────────── ──────── ─────────────────── "Z" Zmodem Yes "Y" Ymodem No "G" Ymodem-G Yes "B" Batch Ymodem Yes "X" Xmodem No "O" Xmodem-1K No "R" Relaxed Xmodem No "T" Telink Yes "S" SEAlink Yes "M" Modem7 Yes "K" Kermit Yes "C" CIS Quick B Yes "A" ASCII No <filenames> is a list of filenames to be sent, wildcard characters '*' and '?' can be used. If <filename> is "" and <GuessFile> option is on, the guessing name is used. Multiple files are separated by a space. For example, "\TM\TM210-1.ZIP \TM\TM\210-2.ZIP" "*.ZIP \UTIL\*.EXE *.TXT" For protocols, such as Xmodem, which cannot transfer multiple files, only the first file in <filenames>. Return If the file transfer is successful, SUCCESS is set to TRUE; SUCCESS is FALSE if the transfer abort. For external protocols, SUCCESS is always set to TRUE. See also Receive, Set GuessFile, Waitfor Example SEND "z","a:*.zip b:*.zip" ; Zmodem batch upload IF SUCCESS PRINT "File sent successfully" ELSE PRINT "File transfer aborted" ENDIF TELEMATE SCRIPT BUILT IN PROCEDURES 52 Set ────────────────────────────────────────────────────────────────────────── Function Sets option value. Syntax SET <OPTION>,<VALUE> SET <OPTION>,<TOKEN> Remark The SET statement gives you control over many of the system options. The possible options and values are listed below. <OPTION> <VALUE> Description ───────────── ──────── ────────────────────────────────── AddLineFeed 0 / 1 when On, a line feed is supplied after a carriage return [Ctrl M] is received AddReturn 0 / 1 when On, a carriage return is supplied after a line feed is received AlarmSound 0 - 999 in second, amount of time that the alarm music is to be played AlarmTime 0 - 999 in second, amount of time that the alarm window is to be shown AltKeys 0 / 1 when Off, all [Alt] keys, [PgUp], [PgDn], [Ctrl Home] and [Ctrl PrtSc] are disabled AutoRedial 0 / 1 when On, the remaining in the dial list will be dialed upon carrier lost AutoStop 0 / 1 when On, the script will stop automatically upon carrier lost, this setting is reset to Off at the beginning of every script AutoWrap 0 / 1 when On, character after column 80 is wrapped to the new line. Baud 300 - 115200 set baud rate (300,1200,2400,4800, 9600,19200,38400,57600,115200) Bell 0 / 1 when Off, no bell when [Ctrl G] received Capture 0 / 1 when Off, the backscroll buffer stops capturing the incoming data CharPacing 0 - 99 in tenth second, amount of time that the Paste or ASCII upload pause when a character is sent ConfirmHangUp 0 / 1 when On, confirm if required if [Alt H] is pressed Connection 0 - 3 set the connection type Data 7 / 8 set data bits TELEMATE SCRIPT BUILT IN PROCEDURES 53 DateFormat 0 - 8 set the date format, note that this option does not affect the date format in the script language DestBs 0 / 1 set destructive backspace DialAttempt 0 - 999 the number of attempt that the dialing process will perform, 0 to dial until connected DialList "..." set the dial list DialPause 0 - 999 in second, amount of time to be wait between two dials DialTime 0 - 999 in second, amount of time to be wait after a number is dialed DirEdit "..." set the edit directory DirDownload "..." set the download directory DirImage "..." set the image directory DirLog "..." set the log directory DirScript "..." set the script directory DirTelemate "..." set the telemate directory DirUpload "..." set the upload directory DirView "..." set the view directory DirWrite "..." set the write directory ExpandBlankLine 0 / 1 when On, blank lines are expanded to lines containing a space ExtAlarm 0 / 1 when On, external alarm is used ExtendedPacing 0 - 99 in tenth second, amount of time that the Put command or the macro keys pause when a character is sent GuessFile 0 / 1 when On, guessed name is put in the file selection box GuessInitial 0 / 1 when On, guessed initial is put in the quote string Incoming 0 / 1 set incoming translation LinePacing 0 - 99 in tenth second, amount of time that the Paste function pause when a [Ctrl M] is sent LocalEcho 0 / 1 when On, characters are displayed in the terminal LogFilter 0 / 1 when On, terminal emulation control characters are not recorded into the log file LogHeading 0 / 1 when On, a brief heading is inserted into the log file before recording the incoming data MaxDosShell 0 / 1 when On, Telemate swaps most of itself out during a DOS shell TELEMATE SCRIPT BUILT IN PROCEDURES 54 MultiLine 0 / 1 when On, board names similar to the board just connected are discarded from the dial list Music 0 / 1 when Off, the music string is not interpreted Outgoing 0 / 1 set outgoing translation PaceChar 0 - 255 in ASCII, the character to be wait before pasting each line, 0 to disable this function Parity 0 - 4 set parity Port 1 - 8 set COM port number Prefix 1 - 4 set the dialing prefix Printer 0 / 1 when On, received data is sent to printer DOS shell QuoteString "..." set the quote string RtsCts 0 / 1 set RTS/CTS flow control ScreenSaver 0 - 99 set screen saver ScriptEcho 0 / 1 when Off, incoming text are not displayed on the screen Stop 1 / 2 set stop bits StripHighBit 0 / 1 when On, the 8th bit is stripped from the incoming data Suffix 1 - 4 set the dialing suffix SwapToDisk 0 / 1 when On, Telemate swaps part of itself to disk during DOS shell SwapToEms 0 / 1 when On, Telemate swaps part of itself to EMS/XMS during Tag 0 - 2 set the tag separator Terminal 0 - 5 set the terminal type UsageLog 0 / 1 set usage log XonXoff 0 / 1 set XON/XOFF flow control is received zASCII 0 / 1 when On, Zmodem indicates that the upload is a ASCII file zAutoDownload 0 / 1 when Off, Zmodem does not download automatically zRecovery 0 / 1 when Off, Zmodem does not recover aborted transfer Some options allow the use of tokens. Options accept either 0 or 1 can use Off for 0 and On for 1. The following lists the options that tokens and the corresponding value of the token: Connection, Modem(0)/Computer(1)/Fossil(2)/BIOS(3) Parity, None(0)/Odd(1)/Even(2)/Space(3)/Mark(4) Terminal, TTY(0)/ANSI(1)/VT52(2)/VT102(3)/AVATAR(4)/PRISM(5) Tag, Space(0)/Crlf(1)/Comma(2) TELEMATE SCRIPT BUILT IN PROCEDURES 55 See also Alarm, Dial, Dos, Query, Receive, Send Example baudRate = 2400 SET baud,baudRate ; set baud rate to 2400 SET baud,2400 ; same as above SET incoming,on ; turn on incoming translation SET terminal,VT102 ; set terminal type to VT102 Stop ────────────────────────────────────────────────────────────────────────── Function Terminates the execution of the current script program. Syntax STOP Remark STOP is usually used when an error is encountered. See also ExitTelemate Example OPEN "MYFILE" ; open a file IF NOT SUCCESS PRINT "File not found." STOP ; terminate if file not found ENDIF StrDel ────────────────────────────────────────────────────────────────────────── Function Deletes characters from a string. Syntax STRDEL str,pos,count Remark STRDEL deletes <count> characters from the position <pos> of the string <str>. The first character position is 1. Return <str> contains the new string. See also Concat, Length, StrIns, StrPos, SetSet, SubStr TELEMATE SCRIPT BUILT IN PROCEDURES 56 Example str = "abcXYZdef" STRDEL str,4,3 ; delete "XYZ" PRINT str ; "abcdef" StrIns ────────────────────────────────────────────────────────────────────────── Function Inserts a string into another string. Syntax STRINS str,substr,pos Remark STRINS inserts a string <substr> into another string <str> at position <pos>. If <pos> is larger than the length of <str>, the gap is filled with spaces. The first character position is 1. Return <str> contains the new string. See also Concat, Length, StrDel, StrPos, SetSet, SubStr Example str = "abcdef" STRINS str,"XYZ",4 ; insert "XYZ" PRINT str ; "abcXYZdef" str = "abc" STRINS str,"xyz",10 ; <count> is larger than the length of <str> PRINT str ; "abc xyz" StrPos ────────────────────────────────────────────────────────────────────────── Function Scans a string for the occurrence of a given substring. Syntax STRPOS str,substr,pos Remark STRPOS scans <str> for the first occurrence of the substring <substr>. Case is not sensitive. The first character position is 1. Return If <substr> is a substring of <str>, <pos> is the position of the substring; otherwise, <pos> is 0. See also Concat, Length, StrDel, StrIns, SetSet, SubStr TELEMATE SCRIPT BUILT IN PROCEDURES 57 Example STRPOS "abcdef","def",pos PRINT pos ; 4 StrSet ────────────────────────────────────────────────────────────────────────── Function Sets part of a string to a given character. Syntax STRSET str,ch,pos,count Remark STRSET sets the string <str> starting from position <pos> with <count> character <ch>. If <pos> is larger than the length of <str>, the gap is filled with spaces. The first character position is 1. Return <str> contains the new string. See also Concat, Length, StrDel, StrIns, SetPos, SubStr Example str = "abc" STRSET str,"X",3,10 PRINT str ; "abXXXXXXXXXX" SubStr ────────────────────────────────────────────────────────────────────────── Function Returns a substring from a given string. Syntax SUBSTR src,pos,count,dest Remark SUBSTR returns a substring in the string <src> starting at <pos> of length <count> into the string <dest>. The first character position is 1. Return <dest> contains the substring. See also Concat, Length, StrDel, StrIns, SetPos, StrSet Example SUBSTR "abcdef",1,3,dest PRINT dest ; "abc" TELEMATE SCRIPT BUILT IN PROCEDURES 58 Tell ────────────────────────────────────────────────────────────────────────── Function Returns the current file pointer. Syntax TELL filepos Remark TELL returns the current file pointer. <filepos> is measured in bytes from the beginning of the file. At the beginning of the file, <filepos> is 0. Sometime it is neccessary to open more than one file, you can implement it by storing the file position of the original file, then restore it after the other file operation is completed. Return <filepos> is the current file pointer. See also Seek, Read, Write Example i = 1 filepos = 0 ; at at beginning of file WHILE i<=10 OPEN "bbsname" ; open data file SEEK filepos ; move the previous position READ name ; read a bbs name TELL filepose ; store the current position CLOSE ; close the file PhoneFind name,number ; find the board in TM.FON ; suppose the PhoneFind procedure ; open the TM.FON IF number<>0 ; yes, it is in TM.FON PRINT name," found is entry #",number ENDIF ENDWHILE Time ────────────────────────────────────────────────────────────────────────── Function Gets system time. Syntax TIME now Remark TIME fills the string <now> with the current time. Times can be compared with the usual '<', '>' and '=' relational operator. TELEMATE SCRIPT BUILT IN PROCEDURES 59 Return <now> contains the system current date in HH:MM:SS 24 hour format. See also Date Example TIME now IF now>"07:00:00" AND now<="07:59:59" PRINT "Good morning." ENDIF Usage ────────────────────────────────────────────────────────────────────────── Function Puts a string into the usage file. Syntax USAGE <usageString> Remark USAGES puts the string <usageString> into the usage file TM.USE. The current time and date are added to the beginning of the line automatically. Example USAGE "Switching to Host mode" Waitfor ────────────────────────────────────────────────────────────────────────── Function Waits for one of the given strings from the remote system. Syntax WAITFOR t WAITFOR s1,s2, ... , sN WAITFOR s1,s2, ... , sN, t Remark The 'WAITFOR t' format set the default waiting time to <t>, in second. If <t> is 0, no time checking is performed. If <t> is -1, no time checking is performed, but the waiting time is considered to be exceeded when a key is hit. The 'WAITFOR s1,s2, ... , sN' format waits until one of the given string is received from the remote system or the default waiting time exceeded. TELEMATE SCRIPT BUILT IN PROCEDURES 60 The 'WAITFOR s1,s2, ... , sN,t' format set the default waiting time to <t>, in second and waits until one of the given string is received from the remote system or the waiting time exceeded. Case is not sensitive when comparing the given string with the characters received from the remote system. Sometimes the remote system need a slight delay between the prompt and the response, you can use DELAY or the "~" half- second marco before the PUT command. Return If the waiting time exceeded, FOUND is set to 0 (FALSE); otherwise, FOUND is set the string number of the matched string. See also Delay, Put, Receive, Send, WaitUntil, When, WhenIdle Example WAITFOR "first",30 ; wait for "first" in 30 seconds IF NOT FOUND PRINT "Not found." ; if not found, stop STOP ELSE DELAY 5 PUT "my name" ; else send the first and ENDIF ; last names ; The following is usually placed at the end of a script file. ; It waits for disconnection and print which string is found. WAITFOR "NO CARRIER","thanks for calling","hang up now",0 PRINT "Ending connection" ; The following simulates the AutoDownload feature for protocols ; does not support this feature. WAITFOR "Download protocol is",0 WAITFOR "Xmodem","Ymodem","SEAlink",5 IF FOUND SWITCH FOUND CASE 1: RECEIVE "x","" ; Xmodem, use guessing name CASE 2: RECEIVE "y" ; Ymodem download CASE 3: RECEIVE "s" ; SEAlink download ENDSWITCH ENDIF TELEMATE SCRIPT BUILT IN PROCEDURES 61 WaitUntil ────────────────────────────────────────────────────────────────────────── Function Waits until the specified time exceeded. Syntax WAITUNTIL t Remark WAITUNTIL pauses the execution and waits until the time <t>, in HH:MM:SS 24 hour format, exceeded. See also Wait Example WAITUNTIL "23:10:30" ; pause until 11:10:30pm. When ────────────────────────────────────────────────────────────────────────── Function Sends a response string to the remote system whenever a given string is matched. Syntax WHEN <waitString>,<resonseString> WHEN <waitString>,"" Remark The WHEN statement is usually used in the beginning of the script file and it is active until the end of the script file. Whenever the <waitString> is received from the remote system, the <responseString> is transmitted. The response string can be changed. To cancel a WHEN statement, "" should be put in in <responseString>. Case is not sensitive when comparing the <waitString> with the characters received from the remote system. See also Waitfor, WhenIdle Example WHEN "Press ENTER","^M" ; set response strings WHEN "More [y,n]?","y^M" WAITFOR "main menu",0 ; wait for "main menu" WHEN "Press ENTER","" ; cancel response string WHEN "More [y,n]?","n^M" ; change response string REPEAT ; make the WHEN statements UNTIL NOT CONNECTED ; active until disconnected. TELEMATE SCRIPT BUILT IN PROCEDURES 62 WhenIdle ────────────────────────────────────────────────────────────────────────── Function Sends a string to the remote system if there is no COM Input/Output in the specified time. Syntax WHENIDLE t,s Remark WHENIDLE monitors the COM Input/Output and sends the string <s> to the remote system if COM I/O is idle for the specified time <t>, in second. Like the WHEN statement, WHENIDLE is active until the end of the script program. <s> can contain macro sequence, such as "^*", the modem hangup string. If <t> is equal to 0 or <s> is a empty string, the WHENIDLE statement will be cancel. See also Waitfor, When Example WAITFOR "message command",0 ; wait for command prompt PUT "r" ; read message WHENIDLE 30," ^H" ; prevent inactive timeout REPEAT ; make the WHENIDLE statement UNTIL NOT CONNECTED ; active until disconnected ; There are several usages of this command. The above example ; shows the way to prevent inactive timeout. However, it can ; also be used to handle inactive timeout in the host script ; mode. For example, WHENIDLE 180,"Inactive timeout^M^J~^*" ; this command checks if the COM I/O is idle for 3 minuates, ; sends a timeout message to the user and, finally, sends the ; hangup string, the hangup macro sequence "^*", to the modem. ; Sometimes the phone line is too noisy that some characters ; cannot be received correctly. The worst case is that those ; characters appear in the WAITFOR string. To prevent inactive ; timeout or waste of connect time, the WHENIDLE can be used as ; follows. TELEMATE SCRIPT BUILT IN PROCEDURES 63 WHENIDLE 5,"^M" ; send a carriage return if idle ; for 5 seconds WAITFOR "first name" ; now start the log on sequence PUT "first last" WAITFOR "password" ; send password macro PUT "^&" WHENIDLE 0,"" ; cancel the WHENIDLE statement WhereX ────────────────────────────────────────────────────────────────────────── Function Gives the horizontal cursor position within the terminal window. Syntax WHEREX column Remark WHEREX returns the x-coordinate of the terminal window. The left-most column is 0. Return <column> is the horizontal cursor position. See also At, WhereX WhereY ────────────────────────────────────────────────────────────────────────── Function Gives the vertical cursor position within the terminal window. Syntax WHEREY row Remark WHEREY returns the y-coordinate of the terminal window. The top-most row is 0. Return <row> is the vertical cursor position. See also At, WhereY Write ────────────────────────────────────────────────────────────────────────── Function Writes integers or strings to a text file. Syntax WRITE WRITE s WRITE i WRITE s1,s2,i1,i2,s3, ... WRITE s1,s2,i1,i2,s3, ... , TELEMATE SCRIPT BUILT IN PROCEDURES 64 Remark Like the PRINT statement, WRITE sends variables or constants of types integer or string to the remote system. Each two arguments are separated by a comma. Integers are converted to their string representation automatically before transmitting to the remote system. WRITE supplies a carriage return [Ctrl M] and a line feed [Ctrl J] by default. If a comma follows, no carriage return and line feed is supplied. Return Upon successful completion, SUCCESS is set to TRUE; otherwise, SUCCESS is FALSE. See also Read, Seek, Tell Example CREATE "COUNT" ; write a hundred line into "COUNT" counter = 1 ; initiate the counter WHILE counter<=100 ; repeat 100 times WRITE "This is line ",counter ENDWHILE CLOSE ; close the file newname = "New board name " OPEN "TM.FON" ; change the name field of a record recno = 10 ; change the record #10 reclen = 131 ; record length of a entry SEEK recno*reclen ; seek to the record position WRITE newname, ; write the name CLOSE TELEMATE SCRIPT TOOLBOX PROCEDURES 65 TOOLBOX PROCEDURES ────────────────────────────────────────────────────────────────────────── The toolboxes are a collection of useful script procedures. They are written as a supplement of the built-in procedures. You may freely modify the procedures and you are encourage to share your experience with the other users. The first toolbox defines ANSI color codes and supplies useful video procedures. The second one includes three input procedures and four character-type-checking procedures. The third one provides a standard method to access the phone directory and calculates the difference between two date/time string. To use the toolboxes, you should add the lines #include "toolbox1.scr" , #include "toolbox2.scr" and/or #include "toolbox3.scr" at the beginning of your script file. To reduce the size of the compiled script file, you should include only the toolbox(es) that contain the procedures you need. Toolbox #1 ────────────────────────────────────────────────────────────────────────── This toolbox defines video color values, ANSI color codes and a set of video procedures which output to local screen and/or remote system. To use this toolbox, you should add the line #include "toolbox1.scr" ; include the toolbox TRUE = 1 ; define boolean value FALSE = 0 ; for your convenience at the beginning of your script file. This will increase the file size of the compiled script file .TMS by about 4K. To minimum the overhead, you should cut and paste the procedures that you used into your script file. For example, the <EchoBox> and <EchoBlock> procedures may be excluded. TELEMATE SCRIPT TOOLBOX PROCEDURES 66 Color Values and ANSI Color Codes ────────────────────────────────────────────────────────────────────────── The following table shows the colors values and its corresponding foreground and background ANSI codes. Color Symbolic Foreground Background Value Name ANSI code ANSI code ────────────────────────────────────────────────── 0 BLACK FGBLACK BKBLACK 1 BLUE FGBLUE BKBLUE 2 GREEN FGGREEN BKGREEN 3 RED FGRED BKRED 4 CYAN FGCYAN BKCYAN 5 MAGENTA FGMAGENTA BKMAGENTA 6 YELLOW FGYELLOW BKYELLOW 7 WHITE FGWHITE BKWHITE You can use the symbolic names to access a color. For example, the statement PRINT FGYELLOW,BKBLUE to set the local color to yellow on blue. Or you can use the toolbox procedures EchoColor and EchoBkColor to set the color. For example, EchoColor YELLOW EchoBkColor BLUE have similar effect to the above. EchoToLocal and EchoToRemote ────────────────────────────────────────────────────────────────────────── The <EchoToLocol> and <EchoToRemote> variables tell the Echo procedures where the output is to be sent. If <EchoToLocal> is TRUE, the output is sent to the local screen, default is TRUE. If <EchoToRemote> is TRUE, the output is sent to the remote system, default is TRUE. These variables can both be TRUE. Echo and EchoInt ────────────────────────────────────────────────────────────────────────── Function Output a string or an integer to local screen and/or remote system. Syntax Echo s EchoInt i TELEMATE SCRIPT TOOLBOX PROCEDURES 67 Remark ECHO outputs the string <s> while ECHOINT outputs the integer <i> to the local screen and/or remote system according to the the variables <EchoToLocal> and <EchoToRemote>. If <EchoToLocal> is TRUE, the output is sent to the local screen. If <EchoToRemote> is TRUE, the output is sent to the remote system. Both variables can both be TRUE. In this case, the output is sent to both the local screen and the remote system. All the procedures in this toolbox use these two procedures for output. As a result, the output destination depends on the varaibles <EchoToLocal> and <EchoToRemote> too. Example TRUE = 1 ; define boolean value FALSE = 0 EchoToLocal = TRUE ; echo to local screen EchoToRemote = FALSE; but not to remote system Echo "This only display on local screen" EchoToRemoate = TRUE; now echo to remote system too EchoColor YELLOW ; set yellow foreground EchoHiLite ; high intensity EchoBkColor BLUE ; set blue background Echo "Now both local screen and remote system is" Echo "yellow on blue" EchoBkColor ────────────────────────────────────────────────────────────────────────── Function Sets background color. Syntax ECHOBKCOLOR color Remark ECHOBKCOLOR sets the background color to <color> by outputing the corresponding background ANSI color code. <color> can be one of the following: BLACK, BLUE,GREEN, CYAN, RED, MAGENTA, YELLOW AND WHITE. See also EchoColor TELEMATE SCRIPT TOOLBOX PROCEDURES 68 Example EchoBkColor BLUE ; blue background EchoColor BLACK ; black on CYAN EchoBkColor CYAN EchoBlink ────────────────────────────────────────────────────────────────────────── Function Sets blink attribute. Syntax ECHOBLINK See also EchoHiLite, EchoNormal, EchoReverse Example EchoColor GREEN ; green foreground EchoBlink ; blink EchoBlock ────────────────────────────────────────────────────────────────────────── Function Draws a solid block of a character. Syntax ECHOBLOCK left,top,right,bottom,style,fillchar Remark ECHOBLOCK draws a filled-in, rectangular block. The upper left and lower right corners of the rectangle are given by (left,top) and (right,bottom). The top-left corner is (0,0). <style> selects the type of block 0 spaces ' ' 1 widely spaced block '░' 2 spaced block '▒' 3 closely spaced block '▓' 4 solid block '█' 5 user-defined fill character <fillchar> <fillchar> should be set to "" for <style> not equal to 5. See also EchoBox TELEMATE SCRIPT TOOLBOX PROCEDURES 69 Example EchoBlock 5,10,50,15,3,"" ; fill a block with closely spaced ; block '▓' EchoBlock 0,0,79,24,5,"▀" ; fill the screen with thick ; horizontal line '▀▀▀▀▀▀▀▀' EchoBox ────────────────────────────────────────────────────────────────────────── Function Draws a box. Syntax ECHOBOX left,top,right,bottom,style,fillchar,hollow Remark ECHOBOX draws a rectangular box. The upper left and lower right corners of the rectangle are given by (left,top) and (right,bottom). The top-left corner is (0,0). <style> selects the type of block 0 spaces 1 single line 2 double line 3 single vertical line, double horizontal line 4 double vertical line, single horizontal line 5 user-defined fill character <fillchar> <fillchar> should be set to "" for <style> not equal to 5. If <hollow> is TRUE, the inside of the box is cleared. See also EchoBlock Example EchoBox 5,10,50,15,2,"",1 ; draw a double-line box and ; clear the inside of it EchoBox 0,0,79,24,5,"█",0 ; draw a solid border but do not ; clear the center EchoClearScreen ────────────────────────────────────────────────────────────────────────── Function Clears the screen and home cursor. Syntax ECHOCLEARSCREEN TELEMATE SCRIPT TOOLBOX PROCEDURES 70 Remark ECHOCLEARSCREEN clears the screen with the current color and positions cursor to the top-left corner. See also EchoColor, EchoBkColor EchoColor ────────────────────────────────────────────────────────────────────────── Function Sets foreground color. Syntax ECHOCOLOR color Remark ECHOCOLOR sets the foreground color to <color> by outputing the corresponding foreground ANSI color code. <color> can be one of the following: BLACK, BLUE, GREEN, CYAN, RED, MAGENTA, YELLOW AND WHITE. See also EchoBkColor Example EchoColor YELLOW ; yellow foreground EchoColor BLACK ; black on white EchoBkColor WHITE EchoGotoXY ────────────────────────────────────────────────────────────────────────── Function Positions cursor. Syntax ECHOGOTOXY column,row Remark ECHOGOTOXY moves the cursor to the position (column,row). The upper left corner is (0,0) and the lower right corner is (79,24) if a 25 rows terminal is used. EchoHiLite ────────────────────────────────────────────────────────────────────────── Function Sets high intensity. Syntax ECHOHILITE See also EchoBlink, EchoNormal, EchoReverse TELEMATE SCRIPT TOOLBOX PROCEDURES 71 Example EchoColor GREEN ; green foreground EchoHiLite ; light green EchoNormal ────────────────────────────────────────────────────────────────────────── Function Sets normal intensity and reset color to white on black. Syntax ECHONORMAL Remark ECHONORMAL not only set the normal intensity, but also reset the current color to white on black. There is no ANSI code to turn off high intensity. To turn off high intensity only, three statements must be used. You should keep track of the <foreground> and <background> color. EchoNormal EchoColor foreground EchoBkColor background See also EchoBlink, EchoHiLite, EchoReverse EchoReverse ────────────────────────────────────────────────────────────────────────── Function Sets reverse attribute. Syntax ECHOREVERSE See also EchoBlink, EchoHiLite, EchoNormal Example EchoColor YELLOW ; yellow on blue EchoBkColor BLUE EchoReverse ; blue on yellow TELEMATE SCRIPT TOOLBOX PROCEDURES 72 Toolbox #2 ────────────────────────────────────────────────────────────────────────── This toolbox defines three I/O procedures and four character-type- checking procedures. To use this toolbox, you should add the line #include "toolbox2.scr" at the beginning of your script file. This will increase the file size of the compiled script file .TMS by about 2K. To minimum the overhead, you should cut and paste the procedures that you used into your script file. For example, the <InputN> and <ReadN> procedures may be excluded. GetN ────────────────────────────────────────────────────────────────────────── Function Gets one or more characters from remote system. Syntax GETN s,n Remark GETN gets <n> characters from remote system or until CR [Ctrl M] is encountered. The input characters are displayed on local screen. BackSpace character [Ctrl H] deletes the last character of the inputing string. You should leave a space before your input prompt. The CLEAR KEY should be issued if you no longer need keyboard input. Return <s> contains the input string. If the length of <s> is less than <n>, CR is encountered. See also Clear COM, Get, GetCh Example PUT "Press a key to continue" GetN enter,1 ; wait for a key or [Enter] ; Note: a space is required here ------------v for backspace PUT "Enter the filename you want to download: " GetN filename,50 ; let it handle backspace TELEMATE SCRIPT TOOLBOX PROCEDURES 73 InputN ────────────────────────────────────────────────────────────────────────── Function Gets one or more characters from keyboard. Syntax INPUTN s,n Remark INPUTN gets <n> characters from keyboard or until [Enter] is pressed. BackSpace character [Ctrl H] deletes the last character of the inputing string. Return <s> contains the input string. If the length of <s> is less than <n>, [Enter] is pressed. See also At, Clear Key, Input, InputCh Example PRINT "Press a key to continue" InputN enter,1 ; wait for a key or [Enter] PRINT "Enter the filename you want to display: " InputN filename,50 ; let it handle backspace ReadN ────────────────────────────────────────────────────────────────────────── Function Gets one or more characters from a file. Syntax READN s,n Remark READN gets <n> characters from the file or until the CR-LF newline sequence is encountered. The CR-LF is skipped in the file and discarded in the string. BackSpace character [Ctrl H] DOES NOT delete the last character of the inputing string. This procedure is usually used to get a field from a data file. Return <s> contains the input string. If the length of <s> is less than <n>, newline is encountered. See also Read, ReadCh, Seek, Tell TELEMATE SCRIPT TOOLBOX PROCEDURES 74 Example OPEN "TM.FON" ; open the phone directory SEEK 10*131 ; move to entry #10, each entry is 131 bytes ReadN name,30 ; read the name field CLOSE ; close the phone directory isalpha ────────────────────────────────────────────────────────────────────────── Function Determines if a character is a letter. Syntax ISALPHA ch,result Return If <ch> is a letter, <result> is set to TRUE; otherwise <result> is FALSE. See also isalnum, iscntl, isdigit Example InputN ch,1 ; get one character PRINT isalpha ch,result IF result PRINT "yes, it is a letter" ELSE PRINT "no, it is not" ENDIF isalnum ────────────────────────────────────────────────────────────────────────── Function Determines if a character is a letter or a digit. Syntax ISALNUM ch,result Return If <ch> is a letter or a digit, <result> is set to TRUE; otherwise <result> is FALSE. See also isalpha, iscntl, isdigit iscntl ────────────────────────────────────────────────────────────────────────── Function Determines if a character is a control character. Syntax ISCNTL ch,result TELEMATE SCRIPT TOOLBOX PROCEDURES 75 Return If <ch> is a control character ([Ctrl A] to [Ctrl Z]), <result> is set to TRUE; otherwise <result> is FALSE. See also isalpha, isalnum, isdigit isdigit ────────────────────────────────────────────────────────────────────────── Function Determines if a character is a digit. Syntax ISDIGHT ch,result Return If <ch> is a digit, <result> is set to TRUE; otherwise <result> is FALSE. See also isalpha, isalnum, iscntl Toolbox #3 ────────────────────────────────────────────────────────────────────────── This toolbox defines several procedures to access the phone directory and two procedures to calculate the difference between two date/time strings. To use this toolbox, you should add the line #include "toolbox3.scr" at the beginning of your script file. This will increase the file size of the compiled script file .TMS by about 5K. To minimum the overhead, you should cut and paste the procedures that you used into your script file. For example, the <DiffTime> and <DiffDate> procedures may be excluded. ConvertDate ────────────────────────────────────────────────────────────────────────── Function Converts one date format to another date format. Syntax CONVERTDATE format1,date1,format2,date2 Remark CONVERTDATE converts the date string <date1> of data format integer <format1> to <date2> of <format2>. TELEMATE SCRIPT TOOLBOX PROCEDURES 76 Return <date2> is the equivalent date of the <date1> but <date2> is in date format <format2> and <date1> is in date format <format2>. TMScript only recognizes date string in MM-DD-YY format (i.e. format 0). If you change the date format, it is important to convert it back to the MM-DD-YY before passing it into TMScript internal command, for example comparing two date strings. See also Date Example DATE today0 ; MM-DD-YY (date format 0) ConvertDate 0,today0,1,today1 PRINT today1 ; convert it to DD-MM-YY (date format 1) ConvertDate 1,today1,0,today0 PRINT today0 ; back to MM-DD-YY (date format 0) DiffDate ────────────────────────────────────────────────────────────────────────── Function Computes the difference between two dates. Syntax DIFFDATE date1,date2,days Remark DIFFDATE calculates the elapsed days from <date1> to <date2> as if <days> = <date2> - <date1> <date1> and <date2> must be in MM-DD-YY format. Return <days> is the elapsed days from <date1> to <date2>. <days> is always a non-negative integer. If <date1> is equal to <date2>, <days> is equal 0. If <date1> is larger than <date2>, it is assumed that <date2> pass a century and 100 years is added to <date2> before the calculation. See also Date, DiffTime TELEMATE SCRIPT TOOLBOX PROCEDURES 77 Example DiffDate "02-01-88","02-01-89",days PRINT days ; 366 DiffDate "02-01-91","03-01-91",days PRINT days ; 28 DiffDate "12-31-99","01-01-00",days ; 1999 - 2000 PRINT days ; 1 DiffTime ────────────────────────────────────────────────────────────────────────── Function Computes the difference between two times. Syntax DIFFTIME time1,time2,seconds Remark DIFFTIME calculates the elapsed seconds from <time1> to <time2> as if <seconds> = <time2> - <time1> <time1> and <time2> must be in HH:MM:SS format. Return <seconds> is the elapsed seconds from <time1> to <time2>. <seconds> is always a non-negative integer. If <time1> is equal to <time2>, <seconds> is equal 0. If <time1> is larger than <time2>, it is assumed that <time2> pass midnight and 24 hours is added to <time2> before the calculation. See also DiffDate, Time Example DiffTime "12:30:40","12:31:30",seconds PRINT seconds ; 50 DiffTime "23:59:50","00:00:01",seconds ; pass mid-night PRINT seconds ; 11 TELEMATE SCRIPT TOOLBOX PROCEDURES 78 PhoneDirectory ────────────────────────────────────────────────────────────────────────── The <PhoneDirectory> variable tells the Phone's procedures which phone directory is to be access. Default is the "TM.FON". Example PhoneDirectory = "MYPHONE.FON" PhoneFind "South",number,1 ; search the word "South" in ; MYPHONE.FON PhoneFind ────────────────────────────────────────────────────────────────────────── Function Finds a phone directory entry. Syntax PHONEFIND name,number,startPoint Remark PHONEFIND finds an entry by <name> starting from <startPoint>. Return If <name> matches an entry, <number> is set the entry number; otherwise, <number> is 0. <success> is FALSE if the phone directory cannot be open. Caution This procedure will close the formly opened file since the OPEN command is used. You should close the file before issuing this procedure and reopen the file after this procedure. See also PhoneDirectory, PhoneRead, PhoneSize, PhoneWrite Example ; To start from the beginning of the phone directory PhoneFind "South",number,1 IF NOT FOUND PRINT "String not found" STOP ENDIF PhoneRead number,name,password,link,log,phone,total,last PRINT "...." ; To go on search, supply <startPoint> with the next number PhoneFind "South",number,number+1 PRINT "...." TELEMATE SCRIPT TOOLBOX PROCEDURES 79 PhoneRead ────────────────────────────────────────────────────────────────────────── Function Reads a phone directory entry Syntax PHONEREAD number,name,password,linkscript,logfile,phone, total,last Remark PHONEREAD reads the entry # <number> into the variables. <total> is an integer variable. The others are string variables. You must provide a valid entry <number>. The size of the phone directory can be obtained by the PHONESIZE procedure. Return <name> is the name field, <password> is the password field, <linkscript> is the script field, <logfile> is the log file field, <phone> is the phone number, <total> is the total number connected, an integer, <last> is the last logon date. Tailing spaces in each variables are discarded. <success> is FALSE if the phone directory cannot be open. Caution This procedure will close the formly opened file since the OPEN command is used. You should close the file before issuing this procedure and reopen the file after this procedure. See also PhoneDirectory, PhoneFind, PhoneSize, PhoneWrite Example PhoneSize size ; get the size number = 1 ; start the counter WHILE number <= size ; display all entries PhoneRead number,name,password,link,log,phone,total,last PRINT "BBS name:",name," phone:",phone," last on:",last number = number + 1 ; next entry ENDIF PhoneSize ────────────────────────────────────────────────────────────────────────── Function Gets the number of entries in a phone directory. Syntax PHONESIZE size TELEMATE SCRIPT TOOLBOX PROCEDURES 80 Remark PHONESIZE calculated the phone directory size by <size> = <file size of .fon> / 131 Each entries is 131 bytes. Return <success> is FALSE if the phone directory cannot be open. See also PhoneDirectory, PhoneFind, PhoneRead, PhoneWrite PhoneWrite ────────────────────────────────────────────────────────────────────────── Function Writes a phone directory entry Syntax PHONEWRITE number,name,password,linkscript,logfile, phone,total,last Remark PHONEWRITE writes the entry # <number> from the variables. <total> is an integer variable. The others are string. <name> is the name field, <password> is the password field, <linkscript> is the script field, <logfile> is the log file field, <phone> is the phone number, <total> is the total number connected, an integer, <last> is the last logon date. Tailing spaces in each variables should have been discarded. Return <success> is FALSE if the phone directory cannot be open. Caution This procedure will close the formly opened file since the OPEN command is used. You should close the file before issuing this procedure and reopen the file after this procedure. See also PhoneDirectory, PhoneFind, PhoneRead, PhoneSize Example PhoneRead 10,name,password,link,log,phone,total,last total = total+1 ; total is an integer variable DATE last ; get today's date PhoneWrite 10,name,password,link,log,phone,total,last TELEMATE SCRIPT APPENDIX A: ERROR MESSAGES 81 APPENDIX A: ERROR MESSAGES ────────────────────────────────────────────────────────────────────────── Compiler Error Messages ────────────────────────────────────────────────────────────────────────── 'CASE' expected Declaration error A symbol is placed in wrong sequence the declaration part. You may have forgotten the comma between two variables. 'ENDIF' expected 'ENDPROC' expected 'ENDSWITCH' expected 'ENDWHILE' expected Identifier expected An identifier was expected at this point. You may be trying to use a reserved word as an variable. Invalid expression This symbol cannot participate in an expression in the way it does. You may have forgotten to write an operator between two operands. Invalid option You have mistyped the option or forgotten the comma between the option and the value. Invalid parameter Too many or too few parameter in calling a procedure. Invalid sequence An unexpected symbol appears in a statement. Invalid string operation An arithmetic operator is applied to string expression. To concat two strings, use the 'ConCat' function. Misplacing Exit statement The EXIT can only be placed in WHILE and REPEAT loop. You may have put it outside a loop. TELEMATE SCRIPT APPENDIX A: ERROR MESSAGES 82 New line expected Every statement should be in a line. Nested too deep TMScript allows no more than 10 nested procedures. Number out of range Integer must within the range from -2147483648 to 2147483647. Numeric expression expected The preceding expression must be of integer type. Program Incomplete - Unexpected end of file Your source file ends due to unbalanced begins and ends. Check the IF statement, SWITCH statement, WHILE loop, REPEAT loop and procedure definition. Script file not found The include script of the #include directive does not exist. You may have forgotten the extension .SCR or not having the include script in the current directory. String expression expected The preceding expression must be of string type. String incomplete You have most likely forgotten the ending quote in a string constant. Syntax error An illegal character was found in the source file. You may have forgotten the quotes around a string constant. Too many include scripts TMScript allows no more than 10 nested include file. Type mismatch This is due to incompatible types of the variable and the expression in an assignment statement or incompatible types of operands in an expression. TELEMATE SCRIPT APPENDIX A: ERROR MESSAGES 83 'UNTIL' expected ',' expected ':' expected ')' expected '=' expected '"' expected Runtime Error Messages ────────────────────────────────────────────────────────────────────────── Division by zero A number is divided by a expression of zero. Invalid format in script file Make sure the .TMS file is a compiled script file. You should compile the script file using TMS.EXE. If you are using a newer version, you must delete the old .TMS files and re-compile it with the new TMS.EXE. Out of memory This error occurs when TM.EXE is run out of memory and cannot allocate enough memory to the script file. Stack overflow This error is reported on entry to a procedure when there is not enough stack space to allocate the procedure's local variables. Try to reduce the number of varibles or check for infinate recursive procedure. TELEMATE SCRIPT INDEX 84 INDEX ────────────────────────────────────────────────────────────────────────── .SCR file, 1 COM I/O, 24 .TMS file, 1 ComInCount, 30 ComOutCount, 30 A Comment, 14 Comparison, 12 AddLineFeed, 52 Comma, 54 AddReturn, 52 Compiling Script, 1 Alarm, 27 Compiler Error Message, 81 AlarmSound, 52 Computer, 54 AlarmTime, 52 Concat, 21 AltKeys, 52 ConfirmHangUp, 52 ANSI, 54 CONNECTED, 7, 33 ANSI Color Code, 66 Connection, 52 Append, 8, 27 Console I/O, 24 Arithmetic Operators, 11 Control Code, 3 Assignment, 14 ConvertDate, 75 At, 28 Create, 8, 31 Atoi, 28 Crlf, 54 AutoRedial, 52 AutoStop, 52 D AutoWrap, 52 Avatar, 54 Data Type, 3 Data, 52 B Date, 4, 31 DateFormat, 53 Background Color Code, 66 Delay, 32 Baud, 52 Delete, 8, 32 Bell, 52 DestBs, 53 BIOS, 54 Dial, 33 Board, 45 DialAttempt, 53 Boolean, 4 DialList, 53 Boolean Operators, 12 DialPause, 53 Built In Procedures, 24, 27 DialTime, 53 DiffDate, 76 C DiffTime, 77 DirEdit, 53 Calling Procedure, 20 DirDownload, 53 Capture, 52 DirImage, 53 Character, 3 DirLog, 53 CharPace, 52 DirScript, 53 ChDir, 8, 28 DirTelemate, 53 Clear COM, 29 DirUpload, 53 Clear Key, 29 DirView, 53 Clear Text, 30 DirWrite, 53 Close, 8, 30 Dos, 33 Color Code, 66 Download, 48 Color Value, 66 TELEMATE SCRIPT INDEX 85 E H Echo, 66 HangUp, 36 EchoBkColor, 67 Height, 10 EchoBlink, 68 EchoBlock, 68 I EchoBox, 69 EchoClearScreen, 69 If, 15 EchoColor, 70 Image, 36 EchoGotoXY, 70 Incoming, 53 EchoHiLite, 70 Include Directive, 18 EchoNormal, 71 Input, 37 EchoReverse, 71 InputCh, 37 EchoInt, 66 InputN, 73 EchoToLocal, 66 Integer, 3 EchoToRemote, 66 Isalpha, 74 Else, 15 Isalnum, 74 ElseIf, 15 Iscntl, 74 EndIf, 15 Isdigit, 75 EndSwitch, 16 Itoa, 38 EndWhile, 17 Error Messages, 81 K Even, 54 Exit, 18 Keystroke, 38 ExitTelemate, 34 ExpandBlankLine, 53 L Expression, 11 ExtAlarm, 53 LastCall, 45 ExtendedPacing, 53 Length, 39 LinePacing, 53 F LoadFon, 8, 39 LoadKey, 8, 40 FALSE, 4 LoadMac, 8, 40 File Handling, 26 LoadPad, 9, 40 FileExist, 35 LocalEcho, 53 FileSize, 8, 35 LogFilter, 53 Foregound Color Code, 66 Logging, 9, 41, 42 Fossil, 54 LogHeading, 53 FOUND, 8, 25, 60 LogOff, 41 LogOn, 9, 41 G LogPause, 42 LogResume, 42 Get, 35 GetCh, 36 GetN, 72 GuessFile, 53 GuessInitial, 53 TELEMATE SCRIPT INDEX 86 M Q Mark, 54 Query, 45 MaxDosShell, 53 QuoteString, 54 Memo, 45 Miscellaneous Routines, 26 R Modem, 54 MultiLine, 54 Read, 9, 46 Music, 54 ReadCh, 9, 47 ReadN, 73 N Receive, 9, 48 Relational Operators, 12 Nested Procedures, 22 Rename, 49 None, 54 Repeat, 17 Return, 23 O RtsCts, 54 Rule of Precedance, 11 Odd, 54 Running Script, 1 Open, 9, 42 Runtime Error Messages, 83 Otherwise, 16 Outgoing, 54 S P ScreenSaver, 54 Script, 49 PaceChar, 54 ScriptEcho, 54 Parity, 54 Scope of Variables, 22 Parameter Declaration, 20 Seek, 9, 50 Parameter Passing, 20 Send, 9, 50 Password, 45 Set, 52 Phone, 45 Space, 54 PhoneDirectory, 78 Statement, 14 PhoneFind, 78 Stop, 45, 55 PhoneRead, 79 StrDel, 55 PhoneSize, 79 String, 3 PhoneWrite, 80 String Handling, 26 Port, 54 StrIns, 56 Precedence, 11 StripHighBit, 54 Predefined Variables, 6 StrPos, 56 Prefix, 54 StrSet, 57 Print, 24, 43 SubStr, 57 Printer, 54 SUCCESS, 8 Procedure Declaration, 19 Suffix, 54 Procedure, 19 SwapToDisk, 54 Protocol, 48, 51 SwapToEMS, 54 Put, 25, 44 Switch, 16 TELEMATE SCRIPT INDEX 87 T W Tag, 54 Waitfor, 2, 8, 25, 59 Tell, 9, 58 WaitUntil, 61 Terminal, 54 When, 61 Time, 5, 58 WhenIdle, 62 Toolbox Procedures, 65 WhereX, 63 Toolbox #1, 65 WhereY, 63 Toolbox #2, 72 While, 17 Toolbox #3, 75 Width, 9 Total, 45 Write, 9, 63 TRUE, 4 TTY, 54 X U XonXoff, 54 Until, 17 Z Upload, 50 Usage, 59 zASCII, 54 UsageLog, 54 zAutoDownload, 54 Using TMS.EXE, 1 zRecovery, 54 V Variable, 6 Variable Identifier, 6 Variable Declaration, 6 VT52, 54 VT102, 54