home *** CD-ROM | disk | FTP | other *** search
/ Shareware Overload / ShartewareOverload.cdr / comm / tm211_3.zip / TMSCRIPT.DOC < prev   
Text File  |  1990-05-25  |  143KB  |  4,259 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.  
  9.  
  10.  
  11.  
  12.      ▌███████████ ▌█████████▌  ▌██████                 ▌█             ▌█
  13.           ▌█▌     ▌█▌ ▌█▌ ▌█▌  ▌█▌                                    ▌█
  14.           ▌█▌     ▌█▌ ▌█▌ ▌█▌  ▌█▌      ▌████▌  ▌████  ▌█   ▌██████ ▌█████
  15.           ▌█▌     ▌█▌ ▌█▌ ▌█▌  ▌██████  ▌█      ▌█     ▌█   ▌█   ▌█   ▌█
  16.           ▌█▌     ▌█▌ ▌█▌ ▌█▌       ▌█  ▌█      ▌█     ▌█   ▌█   ▌█   ▌█
  17.           ▌█▌     ▌█▌ ▌█▌ ▌█▌       ▌█  ▌█      ▌█     ▌█   ▌█   ▌█   ▌█
  18.           ▌█▌     ▌█▌ ▌█▌ ▌█▌  ▌██████  ▌████▌  ▌█     ▌█   ▌██████   ▌███
  19.                                                             ▌█
  20.                                                             ▌█
  21.                                                             ▌█
  22.  
  23.  
  24.  
  25.  
  26.                            Telemate Script Language
  27.  
  28.                                  Version 2.1
  29.  
  30.  
  31.                                 By   Tsung Hu
  32.  
  33.  
  34.  
  35.  
  36.             Copyright (c) 1988-1990 Tsung Hu.  All rights reserved.
  37.  
  38.  
  39.  TELEMATE SCRIPT                                TABLE OF CONTENTS    i
  40.  
  41.  TABLE OF CONTENTS
  42.  
  43.  INTRODUCTION                                                        1
  44.     Using TMS.EXE, the Script Compiler  . . . . . . . . . . . . . .  1
  45.     To Run a Script . . . . . . . . . . . . . . . . . . . . . . . .  1
  46.     Hello, world  . . . . . . . . . . . . . . . . . . . . . . . . .  2
  47.  
  48.  DATA TYPES                                                          3
  49.     Integer . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  50.     String  . . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  51.     Character . . . . . . . . . . . . . . . . . . . . . . . . . . .  3
  52.     Boolean . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
  53.     Date  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
  54.     Time  . . . . . . . . . . . . . . . . . . . . . . . . . . . . .  4
  55.  
  56.  VARIABLES                                                           5
  57.     Variable Identifiers. . . . . . . . . . . . . . . . . . . . . .  5
  58.     Variable Declarations . . . . . . . . . . . . . . . . . . . . .  5
  59.     Predefined Variables. . . . . . . . . . . . . . . . . . . . . .  5
  60.        CONNECTED  . . . . . . . . . . . . . . . . . . . . . . . . .  5
  61.        FOUND  . . . . . . . . . . . . . . . . . . . . . . . . . . .  6
  62.        SUCCESS  . . . . . . . . . . . . . . . . . . . . . . . . . .  6
  63.        LOGGING  . . . . . . . . . . . . . . . . . . . . . . . . . .  7
  64.        WIDTH  . . . . . . . . . . . . . . . . . . . . . . . . . . .  7
  65.        HEIGHT . . . . . . . . . . . . . . . . . . . . . . . . . . .  7
  66.  
  67.  EXPRESSIONS                                                         8
  68.     Rule Of Precedence  . . . . . . . . . . . . . . . . . . . . . .  8
  69.     Arithmetic Operators  . . . . . . . . . . . . . . . . . . . . .  8
  70.     Boolean Operators . . . . . . . . . . . . . . . . . . . . . . .  8
  71.     Relational Operators  . . . . . . . . . . . . . . . . . . . . .  9
  72.  
  73.  STATEMENTS                                                         10
  74.     Comment . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10
  75.     Assignment Statement  . . . . . . . . . . . . . . . . . . . . . 10
  76.     If Statement  . . . . . . . . . . . . . . . . . . . . . . . . . 10
  77.     Switch Statement  . . . . . . . . . . . . . . . . . . . . . . . 11
  78.     While Loop  . . . . . . . . . . . . . . . . . . . . . . . . . . 11
  79.     Repeat Loop . . . . . . . . . . . . . . . . . . . . . . . . . . 12
  80.     Exit Statement  . . . . . . . . . . . . . . . . . . . . . . . . 13
  81.     #include Directive  . . . . . . . . . . . . . . . . . . . . . . 14
  82.  
  83.  PROCEDURES                                                         15
  84.     Procedure Declaration . . . . . . . . . . . . . . . . . . . . . 15
  85.     Parameter Declaration . . . . . . . . . . . . . . . . . . . . . 16
  86.     Calling Procedure and Parameter Passing . . . . . . . . . . . . 18
  87.     Nested Procedures and Scope of Variables  . . . . . . . . . . . 18
  88.     Return Statement  . . . . . . . . . . . . . . . . . . . . . . . 18
  89.  
  90.  
  91.  TELEMATE SCRIPT                               TABLE OF CONTENTS    ii
  92.  
  93.  
  94.  BUILT IN PROCEDURES BY CATEGORY                                    20
  95.     Console I/O . . . . . . . . . . . . . . . . . . . . . . . . . . 20
  96.        Print Statement  . . . . . . . . . . . . . . . . . . . . . . 20
  97.     COM I/O . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
  98.        Put Statement  . . . . . . . . . . . . . . . . . . . . . . . 21
  99.        Waitfor Statement  . . . . . . . . . . . . . . . . . . . . . 21
  100.     File Handling   . . . . . . . . . . . . . . . . . . . . . . . . 22
  101.     String Handling . . . . . . . . . . . . . . . . . . . . . . . . 22
  102.     Miscellaneous Routines  . . . . . . . . . . . . . . . . . . . . 22
  103.  
  104.  BUILT IN PROCEDURES                                                23
  105.     Append  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
  106.     Alarm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
  107.     At  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
  108.     Atoi  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
  109.     ChDir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
  110.     Clear COM . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
  111.     Clear Key . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
  112.     Clear Text  . . . . . . . . . . . . . . . . . . . . . . . . . . 26
  113.     Close . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
  114.     ComInCount  . . . . . . . . . . . . . . . . . . . . . . . . . . 26
  115.     ComOutCount . . . . . . . . . . . . . . . . . . . . . . . . . . 26
  116.     Concat  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
  117.     Create  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 27
  118.     Date  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
  119.     Delay . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
  120.     Delete  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
  121.     Dial  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
  122.     Dos . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
  123.     ExitTelemate  . . . . . . . . . . . . . . . . . . . . . . . . . 30
  124.     FileExist . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
  125.     FileSize  . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
  126.     Get . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31
  127.     GetCh . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
  128.     HangUp  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
  129.     Image . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
  130.     Input . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
  131.     InputCh . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
  132.     Itoa  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
  133.     Length  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
  134.     LoadFon . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
  135.     LogOff  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
  136.     LogOn . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
  137.     LogPause  . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
  138.     LogResume . . . . . . . . . . . . . . . . . . . . . . . . . . . 36
  139.     Open  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
  140.     Print . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
  141.     Put . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
  142.     Read  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
  143.     ReadCh  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
  144.     Receive . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40
  145.     Rename  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
  146.  
  147.  TELEMATE SCRIPT                              TABLE OF CONTENTS    iii
  148.  
  149.     Script  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
  150.     Seek  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
  151.     Send  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
  152.     Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
  153.     Stop  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
  154.     StrDel  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46
  155.     StrIns  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
  156.     StrPos  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
  157.    StrSet  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
  158.     SubStr  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
  159.     Tell  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
  160.     Time  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49
  161.     Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
  162.     Waitfor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 50
  163.     WaitUntil . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
  164.     When  . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
  165.     WhenIdle  . . . . . . . . . . . . . . . . . . . . . . . . . . . 52
  166.     WhereX  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
  167.     WhereY  . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
  168.     Write . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54
  169.  
  170.  TOOLBOX PROCEDURES                                                 56
  171.     Toolbox #1                                                      56
  172.        Color Values and ANSI Color Codes  . . . . . . . . . . . . . 56
  173.        EchoToLocal and EchoToRemote   . . . . . . . . . . . . . . . 57
  174.        Echo and EchoInt . . . . . . . . . . . . . . . . . . . . . . 57
  175.        EchoBkColor  . . . . . . . . . . . . . . . . . . . . . . . . 58
  176.        EchoBlink  . . . . . . . . . . . . . . . . . . . . . . . . . 59
  177.        EchoBlock  . . . . . . . . . . . . . . . . . . . . . . . . . 59
  178.        EchoBox  . . . . . . . . . . . . . . . . . . . . . . . . . . 60
  179.        EchoClearScreen  . . . . . . . . . . . . . . . . . . . . . . 60
  180.        EchoColor  . . . . . . . . . . . . . . . . . . . . . . . . . 61
  181.        EchoGotoXY . . . . . . . . . . . . . . . . . . . . . . . . . 61
  182.        EchoHiLite . . . . . . . . . . . . . . . . . . . . . . . . . 61
  183.        EchoNormal . . . . . . . . . . . . . . . . . . . . . . . . . 62
  184.        EchoReverse  . . . . . . . . . . . . . . . . . . . . . . . . 62
  185.     Toolbox #2                                                      62
  186.        GetN . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
  187.        InputN . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
  188.        ReadN  . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
  189.        isalpha  . . . . . . . . . . . . . . . . . . . . . . . . . . 64
  190.        isalnum  . . . . . . . . . . . . . . . . . . . . . . . . . . 65
  191.        isaldigit  . . . . . . . . . . . . . . . . . . . . . . . . . 65
  192.        iscntl . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
  193.     Toolbox #3                                                      66
  194.        DiffDate . . . . . . . . . . . . . . . . . . . . . . . . . . 66
  195.        DiffTime . . . . . . . . . . . . . . . . . . . . . . . . . . 67
  196.        PhoneDirectory . . . . . . . . . . . . . . . . . . . . . . . 67
  197.        PhoneFind  . . . . . . . . . . . . . . . . . . . . . . . . . 67
  198.        PhoneRead  . . . . . . . . . . . . . . . . . . . . . . . . . 68
  199.        PhoneSize  . . . . . . . . . . . . . . . . . . . . . . . . . 69
  200.        PhoneWrite . . . . . . . . . . . . . . . . . . . . . . . . . 70
  201.  
  202.  
  203.  TELEMATE SCRIPT                               TABLE OF CONTENTS    iv
  204.  
  205.  APPENDIX A: ERROR MESSAGES                                         71
  206.     Compiler Error Messages . . . . . . . . . . . . . . . . . . . . 71
  207.     Runtime Error Messages  . . . . . . . . . . . . . . . . . . . . 73
  208.  
  209.  INDEX                                                              74
  210.  
  211.  
  212.  TELEMATE SCRIPT                                     INTRODUCTION    1
  213.  
  214.  
  215.  INTRODUCTION
  216.  
  217.  TMScript  allows  you  to  write  procedures  to  perform  repetitive
  218.  functions, such as a log on script, as well as specific applications,
  219.  such as the host mode.
  220.  
  221.  TMScript is designed to  be a easy-to-use  language.  TMScript  looks
  222.  similar to the Pascal language and the syntax is as loose as that  of
  223.  BASIC langugae.   For most of  the users, only  the WAITFOR, PUT  and
  224.  maybe the WHEN statements are neccessary.   For those users who  have
  225.  experience in the other programming language, TMScript is a  powerful
  226.  tool for developping communication related application.
  227.  
  228.  A script file can  be created using almost  all editors.  The  source
  229.  file is  a  normal ASCII  text  file  which contains  a  sequence  of
  230.  instructions telling Telemate what to perform next.  The source  file
  231.  should use the extension .SCR to indicate that it is a SCRipt file.
  232.  
  233.  
  234.  Using TMS.EXE, the Script Compiler
  235.  ─────────────────────────────────────────────────────────────────────
  236.  
  237.  Once the source file is written, it must be compiled (translated)  to
  238.  a form that Telemate  can load and interpret  quickly.  To compile  a
  239.  source file, type
  240.  
  241.       TMS filename
  242.  
  243.  where <filename> is the filename of  the source file.  The  extension
  244.  can  be  omitted  if  it  is   .SCR.    TMS.EXE  compiles  the   file
  245.  'filename.SCR' and produces the compiled script file  'filename.TMS'.
  246.  For example, typing 'TMS  \TM\HOST', TMS compiles '\TM\HOST.SCR'  and
  247.  produces '\TM\HOST.TMS'.
  248.  
  249.  If a syntax  error is encountered  in the source  file, the  compiler
  250.  reports the the line number  and the type of  the error.  You  should
  251.  edit the source file and recompile until there is no more errors.
  252.  
  253.  
  254.  To Run a Script
  255.  ─────────────────────────────────────────────────────────────────────
  256.  
  257.  There are several ways to run a script.
  258.  
  259.  1. Pressing [Alt S] at the Terminal Window opens the File Dialog and
  260.     you are asked to identify which script file to be executed.
  261.  
  262.  2. Put the script name in the link-script field of the phone
  263.     directory.  When the BBS is connected, the link-script is executed
  264.     automatically.  Link-scripts are sometimes refered as logon-
  265.     scripts because they perform repetitive logon procedure.
  266.  
  267.  3. Type 'TM <scriptname>' at the DOS command line.  For example,
  268.       C>TM HOST
  269.     put Telemate in host mode when start.
  270.  
  271.  
  272.  TELEMATE SCRIPT                                     INTRODUCTION    2
  273.  
  274.  
  275.  4. You may assign a function key to execute a script file using the
  276.     "^\" macro sequence.  For example, the function key [Alt 4] is
  277.     "^\host", when you press [Alt 4], the host script will be
  278.     executed.
  279.  
  280.  5. The SCRIPT statement allows you run another script in a script
  281.     program.  Please refer the description of the SCRIPT statement.
  282.  
  283.  
  284.  Hello, world
  285.  ─────────────────────────────────────────────────────────────────────
  286.  
  287.  The first program to write is the same for all languages.  Print  the
  288.  words
  289.  
  290.       hello, world
  291.  
  292.  In TMScript, it can be done in one statement:
  293.  
  294.       print "hello, world"        ; print it to terminal screen
  295.  
  296.  If you would  like to say  hello to  the remote system,  use the  PUT
  297.  statement instead, for example,
  298.  
  299.       put "hello, world"          ; send it to remote system
  300.  
  301.  
  302.  TELEMATE SCRIPT                                       DATA TYPES    3
  303.  
  304.  
  305.  DATA TYPES
  306.  
  307.  TMScript provides two basic data types, integer and string, and  four
  308.  extended data types, character, boolean, date and time.
  309.  
  310.  
  311.  Integer
  312.  ─────────────────────────────────────────────────────────────────────
  313.  
  314.  Ordinary  number  notation  is  used  for  integers.    Decimal   and
  315.  engineering notation  (e  or  E  followed  by  an  exponent)  is  not
  316.  supported.   Integer  must  within  the  range  from  -2147483648  to
  317.  2147483647.
  318.  
  319.  
  320.  String
  321.  ─────────────────────────────────────────────────────────────────────
  322.  
  323.  A string is a sequence of zero or more characters from extended ASCII
  324.  character set (0-255), enclosed  by quotation marks.   A string  with
  325.  nothing in it  is called a  empty string.   Two sequential  quotation
  326.  marks in a string denote a single character, an quotation mark.
  327.  
  328.  TMScript allows control characters  to be embedded  in strings.   The
  329.  '^' character followed by a letter  (A-Z, a-z), '@' or '[' denotes  a
  330.  character  of  the  ASCII  code  Ctrl-a  to  Ctrl-Z,  NULL,  or   ESC
  331.  respective.
  332.  
  333.  Here are some examples of strings
  334.  
  335.       "TELEMATE"
  336.       "This is a '""'."
  337.       "^K^D"              ; Ctrl-K Ctrl-D
  338.  
  339.  
  340.  Character
  341.  ─────────────────────────────────────────────────────────────────────
  342.  
  343.  Character  is  represented  as  a  string  that  contains  only   one
  344.  character.  For example, "A" is a character.  Control codes are often
  345.  used in script programs and are represented as
  346.  
  347.       Code   String Description
  348.       ────── ────── ───────────────
  349.       Ctrl-@  "^@"  NULL
  350.       Ctrl-A  "^A"
  351.        ...     ..
  352.       Ctrl-H  "^H"  Backspace
  353.       Ctrl-I  "^I"  TAB
  354.       Ctrl-J  "^J"  LF, line feed
  355.        ...     ..
  356.       Ctrl-M  "^M"  CR, Carriage Return, [Enter]
  357.        ...     ..
  358.       Ctrl-Z  "^Z"
  359.       Ctrl-[  "^["  Escape
  360.  
  361.  
  362.  TELEMATE SCRIPT                                       DATA TYPES    4
  363.  
  364.  
  365.  Boolean
  366.  ─────────────────────────────────────────────────────────────────────
  367.  
  368.  Boolean (TRUE or FALSE)  is represented as a  integer.  A integer  is
  369.  said to be TRUE if it is not  equal to zero, FALSE if it is equal  to
  370.  zero.   When testing  a boolean  condition, you  should not  use  the
  371.  following code,
  372.  
  373.       if connected=1
  374.          ...
  375.       endif
  376.  
  377.  because the variable CONNECTED may  have other values.  Instead,  you
  378.  should use
  379.  
  380.       if connected
  381.          ...
  382.       endif
  383.  
  384.  to test if CONNECTED is TRUE.  And
  385.  
  386.       if not connected
  387.          ...
  388.       endif
  389.  
  390.  to test if CONNECTED is FALSE.
  391.  
  392.  Date
  393.  ─────────────────────────────────────────────────────────────────────
  394.  
  395.  Date is represented as a string  with the format "MM-DD-YY".  When  a
  396.  date string  is compared  with another  date string,  they are  first
  397.  converted to  the internal  format "YYMMDD"  so that  the  comparison
  398.  returns the correct result.
  399.  
  400.  
  401.  Time
  402.  ─────────────────────────────────────────────────────────────────────
  403.  
  404.  Time is also represented as a string but with the format  "HH:MM:SS".
  405.  When two time strings are being  compared, they are converted to  the
  406.  internal format "HHMMSS"  such that  the comparison  can the  correct
  407.  result.
  408.  
  409.  
  410.  
  411.  TELEMATE SCRIPT                                        VARIABLES    5
  412.  
  413.  
  414.  VARIABLES
  415.  
  416.  
  417.  Variable Identifiers
  418.  ─────────────────────────────────────────────────────────────────────
  419.  
  420.  A variable identifier  can contain  letters and digits.   However,  a
  421.  variable can only start with a  letter.  Case is not significant,  in
  422.  the other word, the variable <notdone>  is the same as <NotDone>.   A
  423.  variable identifier  can be  of  any length,  but  only the  first  8
  424.  characters are significant.    For examples, the variable  identifier
  425.  <Number12> is the same as <Number123>.
  426.  
  427.  
  428.  Variable Declarations
  429.  ─────────────────────────────────────────────────────────────────────
  430.  
  431.  A variable declaration embodies a list of identifiers that  designate
  432.  new variables and their type.  For example,
  433.  
  434.       integer LOWER,UPPER,STEP    ; integers
  435.       string  message,filename    ; strings
  436.       integer TRUE,FALSE          ; boolean
  437.       string  ch,letter           ; character
  438.  
  439.  The variable declaration part should be placed at the beginning of  a
  440.  script or of a  procedure. In TMScript,  variables need not  declared
  441.  before use  if no  procedure  is defined.   Therefore,  the  variable
  442.  declaration part can be skipped.
  443.  
  444.  
  445.  Predefined Variables
  446.  ─────────────────────────────────────────────────────────────────────
  447.  
  448.  TMScript built in procedures do not return value.  Several predefined
  449.  variables are set to the resulting value.  They are CONNECTED, FOUND,
  450.  SUCCESS, LOGGING, WIDTH and HEIGHT.
  451.  
  452.  CONNECTED
  453.  
  454.  When a DIAL statement is executed, CONNECTED is set to the number  of
  455.  the connected entry (from 1 to 1000).   A value of zero, which  means
  456.  FALSE, indicates that the DIAL statement is aborted by operator.  For
  457.  example,
  458.  
  459.       dial "1 3 6"
  460.       if not connected
  461.          print "Dialing process aborted"
  462.          stop
  463.       endif
  464.       switch connected
  465.         case 1: print "connected to #1"
  466.         case 3: print "connected to #3"
  467.         case 6: print "connected to #6"
  468.       endswitch
  469.  
  470.  
  471.  TELEMATE SCRIPT                                        VARIABLES    6
  472.  
  473.  
  474.  In addition, the variable CONNECTED returns  to FALSE as soon as  the
  475.  carrier lost.  On the other hand, if the state of the carrier changes
  476.  from OFF to ON, CONNECTED is set to TRUE.
  477.  
  478.  FOUND
  479.  
  480.  This variable is set to  resulting value after the WAITFOR  statement
  481.  is executed.  It is set to FALSE if time exceeded.  Otherwise, it  is
  482.  set to the string number of the matched string.  For example,
  483.  
  484.       waitfor "NO CARRIER","thanks for calling","hang up now",100
  485.       switch found
  486.          case 1: print "'NO CARRIER' found"
  487.          case 2: print "'thanks for calling' found"
  488.          case 3: print "'hang up now' found"
  489.       endswitch
  490.  
  491.  SUCCESS
  492.  
  493.  This variable is used  by several statements.   The resulting  values
  494.  and descriptions is shown in the following table.
  495.  
  496.  Statement    Value    Description
  497.  ─────────    ─────    ──────────────────────────────────────────
  498.  Append       TRUE     the file is successfully opened or created
  499.               FALSE    cannot create file
  500.  
  501.  ChDir        TRUE     directory changed
  502.               FALSE    invalid path
  503.  
  504.  Close        TRUE     file closed
  505.               FALSE    cannot close file
  506.  
  507.  Create       TRUE     the file is successfully created
  508.               FALSE    cannot create file
  509.  
  510.  Delete       TRUE     the file is successfully deleted
  511.               FALSE    cannot delete file
  512.  
  513.  FileSize     TRUE     the file size is determined successfully
  514.               FALSE    cannot open file
  515.  
  516.  InputCh ch   TRUE     a character is read into <ch>
  517.               FALSE    no character is available
  518.  
  519.  LogOn        TRUE     the log file is successfully opened
  520.               FALSE    the log file cannot be created
  521.  
  522.  Open         TRUE     the file is successfully opened
  523.               FALSE    the file does not exist
  524.  
  525.  Read str     TRUE     a line is read into <str>
  526.               FALSE    end of file encountered.
  527.  
  528.  ReadCh ch    TRUE     a character is read into <ch>
  529.               FALSE    end of file encountered.
  530.  
  531.  TELEMATE SCRIPT                                        VARIABLES    7
  532.  
  533.  
  534.  Receive      TRUE     all files are received successfully
  535.               FALSE    file transfer aborted
  536.  
  537.  Rename       TRUE     the file is successfully renamed
  538.               FALSE    cannot rename file
  539.  
  540.  Seek         TRUE     the file pointer is moved successfully
  541.               FALSE    disk error
  542.  
  543.  Send         TRUE     all files are sent successfully
  544.               FALSE    file transfer aborted
  545.  
  546.  Tell pos     TRUE     the file pointer is stored in <pos>
  547.               FALSE    disk error
  548.  
  549.  Write        TRUE     write successary to file
  550.               FALSE    cannot write to file
  551.  
  552.  LOGGING
  553.  
  554.  This variable reflects the current file log status and has the values
  555.  
  556.       0   log file close or log file not in use
  557.       1   log file open and capturing incoming data
  558.       2   log file in pause state
  559.  
  560.  
  561.  WIDTH
  562.  
  563.  This variable stored the width of the zoomed terminal window which is
  564.  equal to the screen width.  Possible values are 80 or 132.
  565.  
  566.  HEIGHT
  567.  
  568.  This variable is the  height of the zoomed  terminal window which  is
  569.  calculated as
  570.  
  571.       HEIGHT = screen height
  572.       if ( menu bar present )
  573.               HEIGHT = HEIGHT - 1
  574.       if ( status line present )
  575.               HEIGHT = HEIGHT - 1
  576.       if ( HEIGHT < 24 )
  577.               HEIGHT = 24
  578.  
  579.  For example,  on EGA  43 line  mode  with both  menu bar  and  status
  580.  present, HEIGHT is equal to 41.  But on 25 line mode, HEIGHT is equal
  581.  to 24, not  23, because  Telemate's terminal  has at  least 24  lines
  582.  though only 23 lines may be shown on screen.  In this case,  terminal
  583.  will shift up and down to justify the display region.
  584.  
  585.  This variable may alter between  two instructions if the users  press
  586.  [Alt -]  to toggle  the menu bar and  status line.  When  programming
  587.  full screen procedure, you  should assume there are  23 lines in  the
  588.  screen and DO NOT  scroll the screen  by going to  the last line  and
  589.  perform a line feed.
  590.  
  591.  TELEMATE SCRIPT                                      EXPRESSIONS    8
  592.  
  593.  
  594.  EXPRESSIONS
  595.  
  596.  
  597.  Rule Of Precedence
  598.  ─────────────────────────────────────────────────────────────────────
  599.  
  600.  Expressions are  made  up of  operators  and operands.    In  complex
  601.  expressions, rule of precedence clarify the order in which operations
  602.  are performed.
  603.  
  604.       Operators           Precedence
  605.       ──────────────      ────────────
  606.       *,/                 first (high)
  607.       +,-                 second
  608.       =,<>,<,>,<=,>=      third
  609.       not                 fourth
  610.       and, or, xor        fifth (low)
  611.  
  612.  There are the rules of precedence
  613.  
  614.    1. First, an operand between two operators of difference
  615.       precedence is bound to the operator with higher precedence.
  616.    2. Second, an operand between two equal operators is bound to
  617.       the one on its left.
  618.    3. Third, expressions within parentheses are evaluated prior to
  619.       being treated as a single operand.
  620.  
  621.  
  622.  Arithmetic Operators
  623.  ─────────────────────────────────────────────────────────────────────
  624.  
  625.  The types  of operands  for  arithmetic operators  are shown  in  the
  626.  following table.
  627.  
  628.       Operators   Operation        Operand Type
  629.       ─────────   ──────────────   ────────────
  630.           +       addition         integer
  631.           -       subtraction      integer
  632.           *       multiplication   integer
  633.           /       division         integer
  634.  
  635.  For example, the formula to convert Fahrenheit temperature to Celsius
  636.  equivalents is
  637.  
  638.       celsius = (fahr-32) * 5 / 9
  639.  
  640.  
  641.  Boolean Operators
  642.  ─────────────────────────────────────────────────────────────────────
  643.  
  644.  The types  of operands  for  arithmetic operators  are shown  in  the
  645.  following table.
  646.  
  647.  TELEMATE SCRIPT                                      EXPRESSIONS    9
  648.  
  649.  
  650.  
  651.       Operators   Operation     Operand Type
  652.       ─────────   ───────────   ────────────
  653.          not      negation      boolean
  654.          and      logical and   boolean
  655.          or       logical or    boolean
  656.          xor      logical xor   boolean
  657.  
  658.  Normal Boolean logic governs  the results of  these operations.   For
  659.  instance, 'a and b' is TRUE only if both <a> an <b> are TRUE.
  660.  
  661.  
  662.  Relational Operators
  663.  ─────────────────────────────────────────────────────────────────────
  664.  
  665.  The types  of operands  for  arithmetic operators  are shown  in  the
  666.  following table.  They all have the same precedence.
  667.  
  668.       Operators Operation    Operand Types
  669.       ───────── ──────────── ───────────────────────────
  670.          =      equal to     integer, string, date, time
  671.          <>     not equal to integer, string, date, time
  672.          >      greater than integer, string, date, time
  673.          >=     greater or   integer, string, date, time
  674.                 equal to
  675.          <      less then    integer, string, date, time
  676.          <=     less then or integer, string, date, time
  677.                 equal to
  678.  
  679.  When the  operands are  integer, date  or time,  the comparison  will
  680.  produce the usual result such as
  681.  
  682.          Condition          Result   Operands Type
  683.   ───────────────────────   ──────   ─────────────
  684.            1 > 2            FALSE    integer
  685.   "12-31-89" < "01-01-90"   TRUE     date
  686.   "00:00:00" > "23:59:59"   FALSE    time
  687.  
  688.  However, if the operands are strings, the operators "<", ">" and "<>"
  689.  have another meaning  such that you  can determine if  a string is  a
  690.  sub-string of another string.
  691.  
  692.      s1 <  s2    if   s1 is a sub-string of s2
  693.      s3 >  s4    if   s3 is a super-string of s4
  694.      s5 <> s6    if   s5 is not a sub-string of s6 and
  695.                       s5 is not a super-string of s6
  696.  
  697.  For example,
  698.  
  699.         Condition         Result   Explanation
  700.    ────────────────────   ──────   ──────────────────────────────────
  701.      "hello" =  "Hello"   TRUE     TMScript is not case sensitive.
  702.    "goodbye" <  "bye"     TRUE     "bye" is a sub-string of "goodbye"
  703.        "dog" <> "car"     TRUE     The string is not equal
  704.        "abc" >= "xyz"     FALSE    "abc" is not a super-string of
  705.                                    "xyz" and they are not equal.
  706.  
  707.  TELEMATE SCRIPT                           STRUCTURED STATEMENTS    10
  708.  
  709.  
  710.  STATEMENTS
  711.  
  712.  Statements describe algorithmic actions that can be executed.
  713.  
  714.  
  715.  Comment
  716.  ─────────────────────────────────────────────────────────────────────
  717.  
  718.  Any characters after ";" are ignored by the TMScript compiler.
  719.  
  720.  
  721.  Assignment Statement
  722.  ─────────────────────────────────────────────────────────────────────
  723.  
  724.  Assignment statements replace the current value of a variable with  a
  725.  new value  specified  by  an  expression.   The  expression  must  be
  726.  assignment-compatible with the type of the variable.
  727.  
  728.  The program prints the following table of Fahrenheit temperatures and
  729.  their centigrade or Celsius equivalents.
  730.  
  731.       0     -17
  732.       20    -6
  733.       40    4
  734.       ...   ...
  735.       280   137
  736.       300   148
  737.  
  738.  Here is the program itself.
  739.  
  740.       ; Print Fahrenheit-Celsius table
  741.       ;       for f = 0, 20, ... , 300
  742.  
  743.       integer LOWER,UPPER,STEP
  744.       integer fahr,celsius
  745.  
  746.       LOWER = 0       ; lower limit of temperature table
  747.       UPPER = 300     ; upper limit
  748.       STEP  = 20      ; step size
  749.  
  750.       fahr  = LOWER                    ; first item in the table
  751.       while fahr <= UPPER
  752.          celsius = (fahr-32) * 5 / 9   ; calcuate the values
  753.          print fahr,"^I",celsius       ; print the result
  754.          fahr = fahr + STEP            ; next item in the table
  755.       endwhile
  756.  
  757.  
  758.  If Statement
  759.  ─────────────────────────────────────────────────────────────────────
  760.  
  761.  The general form for IF statement is
  762.  
  763.       IF condition
  764.          statements
  765.       ENDIF
  766.  
  767.  TELEMATE SCRIPT                           STRUCTURED STATEMENTS    11
  768.  
  769.  
  770.  
  771.  The <statements> is  executed only  if <condition>  is TRUE.  Another
  772.  form is
  773.  
  774.       IF condition
  775.          statements-1
  776.       ELSE
  777.          statements-2
  778.       ENDIF
  779.  
  780.  One and only one of the  two statements associated with an  <if-else>
  781.  is done.  If the <condition> is true, <statements-1> is executed;  if
  782.  not, <statements-2> is executed.
  783.  
  784.  The construction
  785.  
  786.       IF condition-1
  787.          statements-1
  788.       ELSE
  789.          IF condition-2
  790.             statements-2
  791.          ELSE
  792.             IF condition-3
  793.                statements-3
  794.             ENDIF
  795.          ENDIF
  796.       ENDIF
  797.  
  798.  occurs so often that it is worth a new keyword ELSEIF.  The statement
  799.  can be re-written as
  800.  
  801.       IF     condition-1
  802.             statements-1
  803.       ELSEIF condition-2
  804.             statements-2
  805.       ELSEIF condition-3
  806.             statements-3
  807.       ENDIF
  808.  
  809.  
  810.  Switch Statement
  811.  ─────────────────────────────────────────────────────────────────────
  812.  
  813.  The SWITCH statement is a special multi-way decision maker that tests
  814.  whether an expression matches one of a number of values, an  branches
  815.  accordingly.  The syntax for SWITCH statement is
  816.  
  817.       SWITCH expression
  818.         CASE value-1:
  819.            statements-1
  820.         CASE value-2,value-3:
  821.            statements-2
  822.         OTHERWISE:
  823.            statements-3
  824.       ENDSWITCH
  825.  
  826.  TELEMATE SCRIPT                           STRUCTURED STATEMENTS    12
  827.  
  828.  
  829.  
  830.  The SWITCH evaluates the expression and compares its value to all the
  831.  cases.  Each cases must be labeled by the values of the same type  as
  832.  the expression. Several values can be separated by comma.  If a  case
  833.  matches the expression value, execution starts at that case and  ends
  834.  at the next  case label. The  case labeled OTHERWISE  is executed  if
  835.  none of the other cases is satisfied.  A OTHERWISE is optional; if it
  836.  isn't there and if none of the cases matches, no action at all  takes
  837.  place. However, OTHERWISE, if  exists, must be  placed after all  the
  838.  case labels.
  839.  
  840.  The program counts digits, blanks, others.
  841.  
  842.       nDigit = 0          ; digit
  843.       nBlank = 0          ; blank
  844.       nOther = 0          ; others
  845.       open "MYFILE"       ; open the file "MYFILE"
  846.       readch ch           ; read the first character
  847.       while success       ; if not end of file
  848.          switch ch
  849.            case "0","1","2","3","4","5","7","8","9":  ; is digit
  850.               nDigit = nDight + 1
  851.            case " ":                                  ; is blank
  852.               nBlank = nBlank + 1
  853.            otherwise:                                 ; others
  854.               nOther = nOther + 1
  855.          endswitch
  856.          readch ch        ; read next character
  857.       endwhile
  858.       close               ; close the file
  859.       print nDigit        ; print the results
  860.       print nBlank
  861.       print nOther
  862.  
  863.  
  864.  While Loop
  865.  ─────────────────────────────────────────────────────────────────────
  866.  
  867.  The WHILE loop is  the most general  loop.  The  syntax of the  WHILE
  868.  loop is
  869.  
  870.       WHILE condition
  871.          statements
  872.       ENDWHILE
  873.  
  874.  The <condition> is tested.  If it is true, the body of the loop  (all
  875.  the statements before  the keyword  ENDWHILE is executed.   Then  the
  876.  condition is re-tested, and if true, the body is executed again. When
  877.  the test becomes false the loop ends, and execution continues at  the
  878.  statements that follows the loop.
  879.  
  880.  
  881.  TELEMATE SCRIPT                           STRUCTURED STATEMENTS    13
  882.  
  883.  
  884.  For example, to print the value from 1 to 100, you can write
  885.  
  886.       i = 1               ; start from 1
  887.       while i<=100        ; check if it in the range
  888.          print i          ; print the number
  889.          i = i + 1        ; increase the counter by 1
  890.       endwhile
  891.  
  892.  Repeat Loop
  893.  ─────────────────────────────────────────────────────────────────────
  894.  
  895.  While the WHILE loop test the  condition at the top, the REPEAT  loop
  896.  test it at the bottom.  It tests at the bottom after making each pass
  897.  through the loop  body; the body  is always executed  at least  once.
  898.  Consider the loop
  899.  
  900.       REPEAT
  901.          statements
  902.       UNTIL condition
  903.  
  904.  The statements is executed, then the  condition is evaluated.  If  it
  905.  is false,  the statements  is evaluated  again, and  so on.   If  the
  906.  condition becomes true, the loop terminates.
  907.  
  908.  For example, to print the value from 1 to 100, you can write
  909.  
  910.       i = 1               ; start from 1
  911.       repeat
  912.          print i          ; print the number
  913.          i = i + 1        ; increase the counter by 1
  914.       until i>100         ; repeat until it is NOT in the range
  915.  
  916.  
  917.  Exit Statement
  918.  ─────────────────────────────────────────────────────────────────────
  919.  
  920.  It is sometimes  convenient to be  able to control  loop exits  other
  921.  than by testing at the top or bottom.  The EXIT statement provides an
  922.  early exit from  the loops.   A EXIT statement  causes the  innermost
  923.  loop to be exited immediately.
  924.  
  925.  The following program accept strings  from keyboard, using a EXIT  to
  926.  exit from the loop when the string contains an [Esc] ("^[").
  927.  
  928.       repeat
  929.          input s
  930.          if "^[" <= s     ; test if [Esc] is a sub-string of s
  931.             exit          ;   before printing it
  932.          endif
  933.          print s
  934.       until s = ""        ; repeat until an empty string is entered
  935.  
  936.  
  937.  
  938.  TELEMATE SCRIPT                           STRUCTURED STATEMENTS    14
  939.  
  940.  
  941.  #include Directive
  942.  ─────────────────────────────────────────────────────────────────────
  943.  
  944.  This compiler directive allows you to write reusable procedures in  a
  945.  seperate file and imports the procedures conveniently.  The syntax is
  946.  
  947.       #include "includefile"
  948.  
  949.  The <includefile> will  be inserted as  if it is  physical appear  in
  950.  this point.   The <includefile>  must be a  pathname with  extension.
  951.  For example,
  952.  
  953.       #include "TOOLBOX.SCR"
  954.       #include "MYLIB.SCR"
  955.  
  956.  inserts the TOOLBOX.SCR and MYLIB.SCR into this point.
  957.  
  958.  The #include directive can be nested as deep as 10 levels.
  959.  
  960.  
  961.  
  962.  TELEMATE SCRIPT                                       PROCEDURE    15
  963.  
  964.  
  965.  PROCEDURE
  966.  
  967.  In TMScript, a procedure is equivalent to a subroutine or function in
  968.  Fortran, or  procedure in  Pascal, C  etc.   A procedure  provides  a
  969.  convenient way to encapsulate some computation in a black box,  which
  970.  can then be used without worrying about its innards.
  971.  
  972.  For example, to swap  the values of two  variables, <i> and <j>,  you
  973.  have to write three lines as follows
  974.  
  975.       temp = i       ; put <i> into a temporary variable
  976.       i = j          ; put <j> into <i>
  977.       j = temp       ; now put the value of <i> into <j>
  978.  
  979.  Suppose in  your script  there are  a  lot of  swapping, it  will  be
  980.  convenivent to  define  a  procedure called  <swap>  to  perform  the
  981.  swapping.  Then your main program will look like
  982.  
  983.       i = 1
  984.       j = 2
  985.       swap i,j       ; now i=2, j=1
  986.       print i        ; 2
  987.       print j        ; 1
  988.  
  989.  This is only a small usage of procedure. Imagine if the procedure  is
  990.  very complex, you can use  it again and again  once it is tested  and
  991.  performs what you need.
  992.  
  993.  Procedure Declaration
  994.  ─────────────────────────────────────────────────────────────────────
  995.  
  996.  The syntax of a procedure definition is
  997.  
  998.       PROCEDURE <procname> <parameter declaration>
  999.       <local variable declaration>
  1000.       <statement part>
  1001.       ENDPROC
  1002.  
  1003.  <procname> is any valid identifier.   <parameter declaration> can  be
  1004.  omitted if  the procedure  does not  required parameters.   See  next
  1005.  section for details on parameter declaration.
  1006.  
  1007.  <local variable  declaration>  made  within  a  given  procedure  are
  1008.  visible only  within that  procedure.   This  part should  ALWAYS  be
  1009.  included in order to make the program easy to be traced although  the
  1010.  declarations may be omitted.
  1011.  
  1012.  <statement part>  can be  considered  as a  sub-program of  the  main
  1013.  program and obeys all the rule described above.
  1014.  
  1015.  
  1016.  
  1017.  TELEMATE SCRIPT                                       PROCEDURE    16
  1018.  
  1019.  
  1020.  Parameter Declaration
  1021.  ─────────────────────────────────────────────────────────────────────
  1022.  
  1023.  Parameter declaration  is  similar  to  variable  declaration.    For
  1024.  example,
  1025.  
  1026.       PROCEDURE sample STRING s,t,INTEGER i,j
  1027.  
  1028.  declares the procedure  <sample> with two  string parameters <s>  and
  1029.  <t> and  two  integer  parameters <i>  and  <j>.   You  may  use  any
  1030.  combination of STRING and INTEGER to define parameters.  For example,
  1031.  
  1032.       PROCEDURE sample INTEGER i,STRING p,q,r,s,INTEGER j,k,STRING z
  1033.  
  1034.  We can write the <swap> procedure as
  1035.  
  1036.       procedure swap integer value1,value2 ; swap two integers
  1037.       integer temp        ; declare a local variable
  1038.       temp = value1       ; store the first value
  1039.       value1 = value2     ; replace with the second value
  1040.       value2 = temp       ; replace with the first value
  1041.       endproc
  1042.  
  1043.  After that, the main program may look like
  1044.  
  1045.       i = 1
  1046.       j = 2
  1047.       k = 3
  1048.       swap i,j            ; now i=2, j=1
  1049.       swap j,k            ; now j=3, k=1
  1050.       print i,j,k         ; 2,3,1
  1051.  
  1052.  
  1053.  Calling Procedure and Parameter Passing
  1054.  ─────────────────────────────────────────────────────────────────────
  1055.  
  1056.  Once the  procedure is  defined,  it can  be  called by  putting  the
  1057.  procedure name in the statement part.  In the example, the statements
  1058.  
  1059.       i = 1
  1060.       j = 2
  1061.       swap i,j            ; now i=2, j=1
  1062.       print i,j           ; 2,1
  1063.  
  1064.  call the <swap> procedure with the parameters <i> and <j>.
  1065.  
  1066.  In the above  example, the method  used to  pass <i> and  <j> to  the
  1067.  procedure <swap> is called  'pass by reference'  because <i> and  <j>
  1068.  can be changed when return.  There is another method called 'pass  by
  1069.  value' of which the parameter cannot be changed.
  1070.  
  1071.  
  1072.  TELEMATE SCRIPT                                       PROCEDURE    17
  1073.  
  1074.  
  1075.  Consider the following procedure
  1076.  
  1077.       procedure CountDown integer num ; print from <num> to 1
  1078.       while num >= 1              ; check if it is in the range
  1079.          print num                ; print it
  1080.          num = num-1              ; decrease until num=0
  1081.       endwhile
  1082.       endproc
  1083.  
  1084.       PrintTo 100                 ; pass by value
  1085.       n = 100
  1086.       PrintTo n*2                 ; pass by value (200)
  1087.       print n                     ; n = 100
  1088.       PrintTo (n)                 ; pass by value (100)
  1089.       print n                     ; n = 100
  1090.       PrintTo n                   ; pass by reference
  1091.       print n                     ; n = 0 !
  1092.  
  1093.  If we supply <CountDown> with the parameter 100, n*2 or (n), they are
  1094.  'pass by value'.  On  the other hand, <n>  is 'pass by reference'  in
  1095.  the last statement.
  1096.  
  1097.  The general rule of method of passing parameters is:
  1098.  
  1099.       When the parameter is a constant, an expression or surrounded
  1100.       by parentheses, it is 'pass by value'.  Otherwise, it is a
  1101.       variable and is 'pass by reference'.
  1102.  
  1103.  The rule applies to string parameter as well.  To prevent  confusion,
  1104.  we should rewrite  the <CountDown> procedure  by introducing a  local
  1105.  variable.
  1106.  
  1107.       procedure CountDown integer num ; print from <num> to 1
  1108.       integer count               ; introduce a local variable
  1109.       count = num                 ;  if neccessary
  1110.       while count >= 1            ; check if it is in the range
  1111.          print count              ; print it
  1112.          count = count-1          ; decrease until 0
  1113.       endwhile
  1114.       endproc                     ; this does not change <num>
  1115.  
  1116.  
  1117.  
  1118.  TELEMATE SCRIPT                                       PROCEDURE    18
  1119.  
  1120.  
  1121.  Nested Procedures and Scope of Variables
  1122.  ─────────────────────────────────────────────────────────────────────
  1123.  
  1124.  TMScript allows  nested procedures;  you  can declare  one  procedure
  1125.  inside of another.  For example,
  1126.  
  1127.       procedure outer
  1128.       string i,j
  1129.  
  1130.          procedure inner
  1131.          integer i
  1132.          i = 100
  1133.          print "i = ",i
  1134.          print "j = ",j
  1135.          endproc
  1136.  
  1137.       i = "This is string 'i'."
  1138.       j = "This is string 'j'."
  1139.       inner
  1140.       print "i = ",i
  1141.       print "j = ",j
  1142.       endproc
  1143.  
  1144.  The <outer> procedure  declares two  string variables,  <i> and  <j>.
  1145.  These two variables can be accessed by both the <outer> procedure and
  1146.  the  <inner>  one  because  they  are  declared  before  the  <inner>
  1147.  procedure.
  1148.  
  1149.  The <inner> procedure declares an integer variable <i>.  Although the
  1150.  two <i>'s share the same name, they are not identical.  The inner <i>
  1151.  is visible in the <inner> procedure but not in the <outer> procedure.
  1152.  On the other hand, the outer <i>  can no longer be accessible in  the
  1153.  <inner> procedure.  The statement
  1154.  
  1155.       i = 100
  1156.  
  1157.  does not affect the outer <i>.  This is called the scope rule.
  1158.  
  1159.  The output of the program is
  1160.  
  1161.       i = 100
  1162.       j = This is string 'j'.
  1163.       i = This is string 'i'.
  1164.       j = This is string 'j'.
  1165.  
  1166.  
  1167.  Return Statement
  1168.  ─────────────────────────────────────────────────────────────────────
  1169.  
  1170.  Like the EXIT  statement, it is  sometimes convenient to  be able  to
  1171.  return from a procedure at the middle of the procedure.
  1172.  
  1173.  The following procedure  accept strings from  keyboard and print  it,
  1174.  using a RETURN to return from the procedure when the string  contains
  1175.  an [Esc] ("^[").
  1176.  
  1177.  
  1178.  TELEMATE SCRIPT                                       PROCEDURE    19
  1179.  
  1180.  
  1181.       procedure AcceptString string s
  1182.       input s
  1183.       if "^[" <= s     ; test if [Esc] is a sub-string of s
  1184.          Return        ;   before printing it
  1185.       endif
  1186.       print s
  1187.       endproc
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  TELEMATE SCRIPT                 BUILT IN PROCEDURES BY CATEGORY    20
  1193.  
  1194.  
  1195.  
  1196.  BUILT IN PROCEDURES BY CATEGORY
  1197.  
  1198.  Console I/O
  1199.  ─────────────────────────────────────────────────────────────────────
  1200.  
  1201.  There are eight statements in the group of console input and  output.
  1202.  Namely,
  1203.  
  1204.   Input, InputCh, Print, AT, Clear Text, Clear Key, WhereX, WhereY
  1205.  
  1206.  
  1207.  PRINT Statement
  1208.  
  1209.  Output is simple, the PRINT statement can print variable or  constant
  1210.  of types integer or string to the terminal window.  For example,
  1211.  
  1212.       print "hello, world"
  1213.  
  1214.  print the words
  1215.  
  1216.       hello, world
  1217.  
  1218.  to the terminal window.
  1219.  
  1220.  PRINT supplies  a newline  automatically.   However, if  a comma  ","
  1221.  follows the  string, no  newline is  supplied.   The statement  above
  1222.  could just as well have been written
  1223.  
  1224.       print "hello, ",
  1225.       print "world",
  1226.       print
  1227.  
  1228.  to produce an identical output.  The last PRINT statement supplies  a
  1229.  newline.
  1230.  
  1231.  PRINT statement accepts more than  one argument.  Each two  arguments
  1232.  are separated by a comma.  For example,
  1233.  
  1234.       print "x = ",x
  1235.       print "My name is ",FirstName," ",LastName
  1236.       print
  1237.  
  1238.  
  1239.  COM I/O
  1240.  ─────────────────────────────────────────────────────────────────────
  1241.  
  1242.  As a communication program, TMScript provides thirteen I/O statements
  1243.  that communicate with the remote system.  They are
  1244.  
  1245.       Get, GetCh, Put, Clear COM, ComInCount, ComOutCount
  1246.       HangUp, Receive, Send, Waitfor, When, WhenIdle
  1247.  
  1248.  
  1249.  TELEMATE SCRIPT                 BUILT IN PROCEDURES BY CATEGORY    21
  1250.  
  1251.  
  1252.  PUT Statement
  1253.  
  1254.  COM output is as simple as console output, the PUT statement can send
  1255.  variable or constant of types integer or string to the remote system.
  1256.  For example,
  1257.  
  1258.       put "FIRST LAST"
  1259.  
  1260.  send the words
  1261.  
  1262.       FIRST LAST
  1263.  
  1264.  and a carriage return (Ctrl-M) to the remote system.
  1265.  
  1266.  PUT supplies a carriage  return automatically.   However, if a  comma
  1267.  "," follows  the  string,  no  carriage  return  is  supplied.    The
  1268.  statement above could just as well have been written
  1269.  
  1270.       put "FIRST  ",
  1271.       put "LAST",
  1272.       put
  1273.  
  1274.  to produce an identical  output.  The last  PUT statement supplies  a
  1275.  carriage return only.
  1276.  
  1277.  PUT statement accepts more than one argument.  Each two arguments are
  1278.  separated by a comma.  For example,
  1279.  
  1280.       put FirstName,";",LastName,";",Password
  1281.  
  1282.  
  1283.  WAITFOR Statement
  1284.  
  1285.  The WAITFOR statements  waits for specified  stirngs from the  remote
  1286.  system in a specified time.   In TMScript, you can specify more  than
  1287.  one string  to wait  for.   If any  of them  is received,  the  FOUND
  1288.  variable is set to  a non-zero value (TRUE).   Combined with the  PUT
  1289.  statement, you can tell Telemate when to send a string to the  remote
  1290.  system.
  1291.  
  1292.    Syntax                         Description
  1293.    ──────────────────────────     ─────────────────────────────────
  1294.    WAITFOR t                      Set default waiting time
  1295.    WAITFOR s1,s2, ... , sN        Wait until one of the strings is
  1296.                                   received
  1297.    WAITFOR s1,s2, ... , sN, t     Wait until one of the strings is
  1298.                                   received or waiting time exceeded
  1299.  
  1300.  
  1301.  TELEMATE SCRIPT                 BUILT IN PROCEDURES BY CATEGORY    22
  1302.  
  1303.  
  1304.  For example, the following  code segment are usally  used in a  logon
  1305.  script program.
  1306.  
  1307.       waitfor "first",30        ; wait for "first" in 30 seconds
  1308.       if not found
  1309.          stop                   ; stop if prompt not found
  1310.       endif
  1311.       put "my name"             ; send the name
  1312.  
  1313.       waitfor "password",5      ; wait for "password" in 5 seconds
  1314.       if not found
  1315.          stop                   ; stop if prompt not found
  1316.       endif
  1317.       put "^&"                  ; send the password field (^&) in
  1318.                                 ;  in the phone directory
  1319.  
  1320.  
  1321.  File Handling
  1322.  ─────────────────────────────────────────────────────────────────────
  1323.  
  1324.  One text file  is allowed to  open at a  time.  The  file is open  or
  1325.  created as a read/write file.  The file handling procedures are
  1326.  
  1327.     Open, Created, Append, Read, ReadCh, Write, Seek, Tell, Close,
  1328.     ChDir, Delete, Rename, FileExist, FileSize
  1329.  
  1330.  The predefined  variable SUCCESS  is set  to FALSE  if there  is  any
  1331.  error.
  1332.  
  1333.  
  1334.  String Handling
  1335.  ─────────────────────────────────────────────────────────────────────
  1336.  
  1337.  A string is a sequence  of character.  The limit  of the length of  a
  1338.  string is 512 characters.  When refering to a character position, the
  1339.  position is counted from 1.  The string handling procedures are
  1340.  
  1341.   Atoi, Concat, Itoa, Length, StrDel, StrIns, StrPos, StrSet, SubStr
  1342.  
  1343.  
  1344.  Miscellaneous Routines
  1345.  ─────────────────────────────────────────────────────────────────────
  1346.   Alarm, Atoi, Date, Delay, Dial, Dos, ExitTelemate, Image, Itoa,
  1347.   LoadFon, LogOff, LogOn, LogPause, LogResume, Script, Time,
  1348.   WaitUntil
  1349.  
  1350.  
  1351.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    23
  1352.  
  1353.  
  1354.  BUILT IN PROCEDURES
  1355.  
  1356.  Alarm
  1357.  ─────────────────────────────────────────────────────────────────────
  1358.  
  1359.  Function     Pop-up the alarm dialog.
  1360.  
  1361.  Syntax       ALARM
  1362.               ALARM message
  1363.  
  1364.  Remarks      If the string <message> is specified, it is displayed in
  1365.               the alarm dialog.
  1366.  
  1367.               If the message is too long, it can be splited to several
  1368.               lines by putting a "^J" between each line.
  1369.  
  1370.  Return       If the operator press [Enter] or click the OK button in
  1371.               the alarm dialog, SUCCESS is set to TRUE (non-zero).
  1372.  
  1373.               If the operator press [Esc] or the alarm time excess,
  1374.               SUCCESS is set to FALSE (zero).
  1375.  
  1376.  See also     Set AlarmSound, Set AlarmTime
  1377.  
  1378.  Example
  1379.  
  1380.       receive "s"
  1381.       if not success
  1382.          alarm "Warning: File transfer aborted"
  1383.          if not success  ; if timeout, print message on screen
  1384.             print "Warning: File transfer aborted"
  1385.          endif
  1386.       endif
  1387.  
  1388.       alarm "alarm:^JThis is a^Jvery long message"
  1389.  
  1390.  
  1391.  Append
  1392.  ─────────────────────────────────────────────────────────────────────
  1393.  Function     Opens a text file, creates it if necessary, and moves
  1394.               the file pointer to the end of the file.
  1395.  
  1396.  Syntax       APPEND filename
  1397.  
  1398.  Remark       APPEND opens the text file as a read/write file and
  1399.               strip the ending EOF (Ctrl Z).
  1400.  
  1401.  Return       Upon successful completion, SUCCESS is set to TRUE.
  1402.               If the file cannot be created, SUCCESS is set to FALSE.
  1403.  
  1404.  See also     Create, Open
  1405.  
  1406.  
  1407.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    24
  1408.  
  1409.  
  1410.  At
  1411.  ─────────────────────────────────────────────────────────────────────
  1412.  
  1413.  Function     Positions cursor in terminal window.
  1414.  
  1415.  Syntax       AT column,row
  1416.  
  1417.  Remark       AT moves the cursor to the position within the terminal
  1418.               window. The upper left corner is (0,0) and the lower
  1419.               right corner is (79,24) if a 25 rows terminal is used.
  1420.  
  1421.  See also     Print
  1422.  
  1423.  
  1424.  Atoi
  1425.  ─────────────────────────────────────────────────────────────────────
  1426.  
  1427.  Function     Converts a string to an integer.
  1428.  
  1429.  Syntax       ATOI s,i
  1430.  
  1431.  Return       <i> contains the converted value or 0 if <s> cannot be
  1432.               converted to a number.
  1433.  
  1434.  See also     Itoa
  1435.  
  1436.  
  1437.  ChDir
  1438.  ─────────────────────────────────────────────────────────────────────
  1439.  
  1440.  Function     Changes current directory.
  1441.  
  1442.  Syntax       CHDIR path
  1443.  
  1444.  Remark       CHDIR causes the directory specified by <path> to become
  1445.               the current working direcotry.  <path> must specify an
  1446.               existing directory.
  1447.  
  1448.               A drive can also be specified in <path> but it changes
  1449.               only the current directory on that drive; it doesn't
  1450.               change the active drive.
  1451.  
  1452.  Return       Upon successful completion, SUCCESS is set to TRUE;
  1453.               otherwise, SUCESSS is FALSE.
  1454.  
  1455.  See also     Delete, FileExit, Rename
  1456.  
  1457.  
  1458.  
  1459.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    25
  1460.  
  1461.  
  1462.  Clear COM
  1463.  ─────────────────────────────────────────────────────────────────────
  1464.  
  1465.  Function     Clears the COM buffer.
  1466.  
  1467.  Syntax       CLEAR COM
  1468.  
  1469.  Remark       Data being sent and received are placed in a COM buffer,
  1470.               sometimes it is neccessary to clear the buffer before
  1471.               processing.
  1472.  
  1473.  See also     Get, GetCh, Put
  1474.  
  1475.  Example
  1476.  
  1477.       get s      ; get a string
  1478.       delay 50   ; wait for 5 seconds
  1479.       clear com  ; clear the received data in the last 5 seconds
  1480.                  ;  to filter out unwanted data
  1481.       get s      ; get another string
  1482.  
  1483.  
  1484.  Clear Key
  1485.  ─────────────────────────────────────────────────────────────────────
  1486.  
  1487.  Function     Clears the keyboard buffer and gives up keyboard control
  1488.               after a INPUT or INPUTCH statement.
  1489.  
  1490.  Syntax       CLEAR KEY
  1491.  
  1492.  Remark       CLEAR KEY clears the content of the keyboard buffer.
  1493.               Keyboard input before this statement are thrown away.
  1494.  
  1495.               When the INPUT or INPUTCH statement in the script is
  1496.               executed, the following input characters are placed in a
  1497.               keyboard buffer no matter if we want to read the next
  1498.               key or not.  As a result, the following characters are
  1499.               NOT sent to the remote system automatically. It is
  1500.               important to give up the control of keyboard whenever no
  1501.               more keyboard input is needed and the clear key
  1502.               statement is built for this purpose.
  1503.  
  1504.  See also     Input, InputCh
  1505.  
  1506.  Example
  1507.  
  1508.       print "Input filename:"
  1509.       input filename      ; ask the user to input a filename
  1510.       clear key           ; give up keyboard control such that
  1511.                           ;  following keys are sent to remote
  1512.                           ;  system automatically
  1513.  
  1514.  
  1515.  
  1516.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    26
  1517.  
  1518.  
  1519.  Clear Text
  1520.  ─────────────────────────────────────────────────────────────────────
  1521.  
  1522.  Function     Clears the terminal window.
  1523.  
  1524.  Syntax       CLEAR TEXT
  1525.  
  1526.  Remark       CLEAR TEST clears the terminal window and positions
  1527.               the cursor to the upper-left corner.  It sets the
  1528.               display attribute to the initial setup.
  1529.  
  1530.  See also     Print
  1531.  
  1532.  
  1533.  Close
  1534.  ─────────────────────────────────────────────────────────────────────
  1535.  
  1536.  Function     Closes a file.
  1537.  
  1538.  Syntax       CLOSE
  1539.  
  1540.  Return       Upon successful competion, SUCCESS is set to TRUE;
  1541.               otherwise, SUCCESS is FALSE.
  1542.  
  1543.  See also     Open, Read, Write
  1544.  
  1545.  
  1546.  ComInCount
  1547.  ─────────────────────────────────────────────────────────────────────
  1548.  
  1549.  Function     Gets the number of characters in the incoming COM
  1550.               buffer.
  1551.  
  1552.  Syntax       COMINCOUNT count
  1553.  
  1554.  Remark       Telemate has an incoming COM buffer of 8000 bytes.
  1555.  
  1556.  Return       <count> contains the number of characters in the
  1557.               incoming COM buffer.
  1558.  
  1559.  See also     Clear COM
  1560.  
  1561.  
  1562.  ComOutCount
  1563.  ─────────────────────────────────────────────────────────────────────
  1564.  
  1565.  Function     Gets the number of characters in the outgoing COM
  1566.               buffer.
  1567.  
  1568.  Syntax       COMOUTCOUNT count
  1569.  
  1570.  Remark       Telemate has an outgoing COM buffer of 2000 bytes.
  1571.  
  1572.  
  1573.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    27
  1574.  
  1575.  
  1576.  Return       <count> contains the number of characters in the
  1577.               outgoing COM buffer.
  1578.  
  1579.  See also     Clear COM
  1580.  
  1581.  
  1582.  
  1583.  Concat
  1584.  ─────────────────────────────────────────────────────────────────────
  1585.  
  1586.  Function     Appends one string to another
  1587.  
  1588.  Syntax       CONCAT dest,src
  1589.  
  1590.  Remark       CONCAT appends a copy of <src> to the end of the string
  1591.               <dest>.
  1592.  
  1593.               If the backspace character "^H" is encountered in <src>,
  1594.               the last character of the concatenating string is
  1595.               erased.
  1596.  
  1597.  Return       <dest> contains the concatenated string.
  1598.  
  1599.  See also     Length, StrDel, StrIns
  1600.  
  1601.  Example
  1602.  
  1603.       s = "abc"           ; s = "abc"
  1604.       concat s,"xyz"      ; s = "abcxyz"
  1605.       concat s,"^H"       ; s = "abcxy"
  1606.       concat s,"pq"       ; s = "abcxypq"
  1607.  
  1608.  
  1609.  
  1610.  Create
  1611.  ─────────────────────────────────────────────────────────────────────
  1612.  
  1613.  Function     Creates a new text file or rewrites an existing one.
  1614.  
  1615.  Syntax       CREATE filename
  1616.  
  1617.  Remark       CREATE creates the new text file <filename>.  If the
  1618.               file already exists, the old file is deleted.
  1619.  
  1620.  Return       Upon successful completion, SUCCESS is set to TRUE;
  1621.               otherwise, SUCCESS is FALSE.
  1622.  
  1623.  See also     Append, Open
  1624.  
  1625.  
  1626.  
  1627.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    28
  1628.  
  1629.  
  1630.  Date
  1631.  ─────────────────────────────────────────────────────────────────────
  1632.  
  1633.  Function     Gets system date.
  1634.  
  1635.  Syntax       DATE today
  1636.  
  1637.  Remark       DATE fills the string <today> with the current date
  1638.  
  1639.               Dates can be compared with the usual '<', '>' and '='
  1640.               relational operator.
  1641.  
  1642.  Return       <today> contains the system current date in MM-DD-YY
  1643.               format.
  1644.  
  1645.  See also     Time
  1646.  
  1647.  Example
  1648.  
  1649.       date today
  1650.       if today>="01-01-91" and today<"01-05-91"
  1651.          print "Happy New Year!"
  1652.       endif
  1653.  
  1654.  
  1655.  Delay
  1656.  ─────────────────────────────────────────────────────────────────────
  1657.  
  1658.  Function     Suspends script execution for an interval.
  1659.  
  1660.  Syntax       DELAY t
  1661.  
  1662.  Remark       With a call to DELAY, the script program is suspended
  1663.               from execution for the number of tenth seconds specified
  1664.               by <t>.
  1665.  
  1666.  Example
  1667.  
  1668.       delay 15  ; wait for one and a half second
  1669.  
  1670.  
  1671.  Delete
  1672.  ─────────────────────────────────────────────────────────────────────
  1673.  
  1674.  Function     Deletes a file
  1675.  
  1676.  Syntax       DELETE filename
  1677.  
  1678.  Remark       DELETE deletes a file specified by <filename>. Wildcards
  1679.               are not allowed.
  1680.  
  1681.  Return       On successful completion, SUCCESS is set to TRUE;
  1682.               otherwise, SUCCESS is FALSE.
  1683.  
  1684.  See also     FileExist, Rename
  1685.  
  1686.  
  1687.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    29
  1688.  
  1689.  
  1690.  Dial
  1691.  ─────────────────────────────────────────────────────────────────────
  1692.  
  1693.  Function     Dials a list of entries or redials the current list.
  1694.  
  1695.  Syntax       DIAL
  1696.               DIAL list
  1697.  
  1698.  Remark       DIAL redials the the current list of entries.  If <list>
  1699.               is specified, the current list is replaced by <list> and
  1700.               start dialing.
  1701.  
  1702.               The <DialAttempt> option is the maximum of number of
  1703.               dialing attempt.
  1704.  
  1705.               The <DialList> option can be used to specify the current
  1706.               dial list.
  1707.  
  1708.  Return       DIAL sets CONNECTED to the number of the connected
  1709.               entry.  If the operator press [Esc] to abort the dialing
  1710.               process or the attempts excess the <DialAttempt> option,
  1711.               CONNECTED is set to 0 (FALSE).
  1712.  
  1713.  See also     Set DialAttempt, Set DialList, Set DialPause, Set
  1714.               DialTime
  1715.  
  1716.  Example
  1717.  
  1718.       set DialAttempt,3     ; try each entry once
  1719.       set DialList,"1 3 6"  ; set the dial list
  1720.       dial                  ; equivalent to a DIAL "1 3 6" statement
  1721.       if not connected
  1722.          print "All boards are busy."
  1723.       else
  1724.          switch connected
  1725.            case 1: print "connected to #1"
  1726.            case 3: print "connected to #3"
  1727.            case 6: print "connected to #6"
  1728.          endswitch
  1729.       endif
  1730.       set DialAttempt,0     ; unlimit the maximum attempt
  1731.  
  1732.  
  1733.  
  1734.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    30
  1735.  
  1736.  
  1737.  Dos
  1738.  ─────────────────────────────────────────────────────────────────────
  1739.  
  1740.  Function     Jumps to DOS or issues a DOS command.
  1741.  
  1742.  Syntax       DOS
  1743.               DOS command
  1744.  
  1745.  Remark       The DOS statement invokes the DOS COMMAND.COM file to
  1746.               execute a DOS command, batch file, or other program
  1747.               named by the string <command>. the program must be in
  1748.               the current directory or in one of the directories
  1749.               listed in the PATH string in the environment.
  1750.  
  1751.               If <command> is not specified, the DOS statement jumps
  1752.               to DOS and return when users enter 'EXIT' in the DOS
  1753.               command line.
  1754.  
  1755.               If the <SwapToEms> or the <SwapToDisk> option is turned
  1756.               on, Telemate swaps part of itself to second storage and,
  1757.               hence, leaves more memory space for the DOS shell.
  1758.  
  1759.               The COMSPEC envirnoment string is used to find the
  1760.               COMMAND.COM file.  If your COMMAND.COM is not in the
  1761.               root directory - suppose in the C:\DOS directory, you
  1762.               should include the following in the AUTOEXEC.BAT startup
  1763.               file.
  1764.  
  1765.                     SET COMSPEC=C:\DOS\COMMAND.COM
  1766.  
  1767.  See also     Set SwapToDisk, Set SwapToEms
  1768.  
  1769.  Example
  1770.  
  1771.       set SwapToEms,on    ; provide more working space
  1772.       set SwapToDisk,on   ;  for external program
  1773.       dos "TMSTAT TM.USE" ; run the TMSTAT.EXE program
  1774.  
  1775.  
  1776.  ExitTelemate
  1777.  ─────────────────────────────────────────────────────────────────────
  1778.  
  1779.  Function     Terminates Telemate's execution.
  1780.  
  1781.  Syntax       EXITTELEMATE
  1782.               EXITTELEMATE exitCode
  1783.  
  1784.  Remark       EXITTELEMATE terminates Telemate and return to DOS.  The
  1785.               file in the Edit window is saved automatically if
  1786.               necessary.
  1787.  
  1788.               If <exitCode> is not specified, Telemate exits to DOS
  1789.               with the error level 0.  Otherwise, the error level is
  1790.               set to <exitCode>.  Typically a value of 0 is used to
  1791.               indicate a normal exit, and a nonzero value indicates
  1792.               some errors.
  1793.  
  1794.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    31
  1795.  
  1796.  
  1797.  FileExist
  1798.  ─────────────────────────────────────────────────────────────────────
  1799.  
  1800.  Function     Determines if a file or directory is exist.
  1801.  
  1802.  Syntax       FILEEXIST filename,existFlag
  1803.  
  1804.  Remark       FILEEXIST checks the file or directory named by
  1805.               <filename> to determines if it is exists.
  1806.  
  1807.  Return       If the file or directory is exist, <existFlag> is set to
  1808.               TRUE; otherwise, <existFlag> is FALSE.
  1809.  
  1810.  See also     Delete, Rename
  1811.  
  1812.  
  1813.  FileSize
  1814.  ─────────────────────────────────────────────────────────────────────
  1815.  
  1816.  Function     Gets file size in bytes.
  1817.  
  1818.  Syntax       FILESIZE filename,size
  1819.  
  1820.  Remark       FILESIZE returns the length, in bytes, of the file
  1821.               specified by <filename>.
  1822.  
  1823.  Return       If <filename> exist, <size> is set to the file size and
  1824.               SUCCESS is set to TRUE; otherwise, SUCCESS is set to
  1825.               FALSE.
  1826.  
  1827.  See also     Read, Seek
  1828.  
  1829.  
  1830.  Get
  1831.  ─────────────────────────────────────────────────────────────────────
  1832.  
  1833.  Function     Gets a string from remote system.
  1834.  
  1835.  Syntax       GET s
  1836.  
  1837.  Remark       GET collects a string, terminated by a carriage return,
  1838.               from the remote system.
  1839.  
  1840.               GET does not elimate the BackSpace character (Ctrl H)
  1841.               from the input, therefore a CONCAT statement should be
  1842.               perform after the GET statement to elimate the BackSpace
  1843.               character.
  1844.  
  1845.  Return       <s> contains the collected string.  The ending carriage
  1846.               return is discarded.
  1847.  
  1848.  See also     Clear COM, ComInCount, GetCh
  1849.  
  1850.  
  1851.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    32
  1852.  
  1853.  
  1854.  Example
  1855.  
  1856.       get s               ; get a string from remote system
  1857.       filename = ""       ; prepare the variable
  1858.       concat filename,s   ; elimate the BackSpace
  1859.  
  1860.  
  1861.  
  1862.  GetCh
  1863.  ─────────────────────────────────────────────────────────────────────
  1864.  
  1865.  Function     Gets a character from remote system.
  1866.  
  1867.  Syntax       GETCH ch
  1868.  
  1869.  Remark       GETCH gets a single character from the remote system.
  1870.               If no character is available, GETCH return immediately.
  1871.               GETCH statement, like the INKEY$ function in BASIC, does
  1872.               not wait.
  1873.  
  1874.  Return       If a character is successfully read into <ch>, SUCCESS
  1875.               is set to TRUE; otherwise, SUCCESS is set to FALSE.
  1876.  
  1877.  See also
  1878.  
  1879.  Example
  1880.  
  1881.       repeat         ; to wait for a character,
  1882.          getch ch    ;  repeat the GETCH until
  1883.       until success  ;  a character is available
  1884.  
  1885.  HangUp
  1886.  ─────────────────────────────────────────────────────────────────────
  1887.  
  1888.  Function     HangUps the modem.
  1889.  
  1890.  Syntax       HANGUP
  1891.  
  1892.  Remark       HANGUP sends the modem hangup string to modem.  If the
  1893.               hangup string is the "^#" macro sequence, Telemate
  1894.               hangups the modem by dropping DTR.
  1895.  
  1896.  
  1897.  Image
  1898.  ─────────────────────────────────────────────────────────────────────
  1899.  
  1900.  Function     Captures the terminal screen into an image file.
  1901.  
  1902.  Syntax       IMAGE
  1903.               IMAGE filename
  1904.  
  1905.  Remark       IMAGE captures the terminal screen into an image file by
  1906.               appending the screen to the file <filename>.  If no
  1907.               <filename> is supplied, the last image filename is used.
  1908.  
  1909.  
  1910.  
  1911.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    33
  1912.  
  1913.  
  1914.  Input
  1915.  ─────────────────────────────────────────────────────────────────────
  1916.  
  1917.  Function     Reads a string from the keyboard.
  1918.  
  1919.  Syntax       INPUT s
  1920.  
  1921.  Remark       INPUT collects a string, terminated by a [Enter],
  1922.               from the keyboard.
  1923.  
  1924.               When the INPUT statement in the script is executed, the
  1925.               following input characters are placed in a keyboard
  1926.               buffer no matter if they are to be read or not.  As a
  1927.               result, they are NOT sent to the remote system
  1928.               automatically. It is important to give up the control of
  1929.               keyboard whenever no more keyboard input is needed using
  1930.               the CLEAR KEY statement.
  1931.  
  1932.               INPUT does not elimate the BackSpace character (Ctrl H)
  1933.               from the input, therefore a CONCAT statement should be
  1934.               perform after the INPUT statement to elimate the
  1935.               BackSpace character.
  1936.  
  1937.  Return       <s> contains the collected string.  The ending [Enter]
  1938.               is discarded.
  1939.  
  1940.  See also     Clear Key, InputCh
  1941.  
  1942.  Example
  1943.  
  1944.       input s             ; get a string from remote system
  1945.       filename = ""       ; prepare the variable
  1946.       concat filename,s   ; elimate the BackSpace
  1947.       clear key           ; give up keyboard control such that
  1948.                           ;  following keys are sent to remote
  1949.                           ;  system automatically
  1950.  
  1951.  
  1952.  
  1953.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    34
  1954.  
  1955.  
  1956.  InputCh
  1957.  ─────────────────────────────────────────────────────────────────────
  1958.  
  1959.  Function     Reads a character from the keyboard.
  1960.  
  1961.  Syntax       INPUTCH ch
  1962.  
  1963.  Remark       INPUTCH gets a single character from the keyboard. If no
  1964.               character is available, INPUTCH returns immediately.
  1965.               INPUTCH statement, like the INKEY$ function in BASIC,
  1966.               does not wait.
  1967.  
  1968.               When the INPUTCH statement in the script is executed,
  1969.               the following input characters are placed in a keyboard
  1970.               buffer no matter if they are to be read or not.  As a
  1971.               result, they are NOT sent to the remote system
  1972.               automatically. It is important to give up the control of
  1973.               keyboard whenever no more keyboard input is needed using
  1974.               the CLEAR KEY statement.
  1975.  
  1976.  Return       If a character is successfully read into <ch>, SUCCESS
  1977.               is set to TRUE; otherwise, SUCCESS is set to FALSE.
  1978.  
  1979.  See also     Clear Key, Input
  1980.  
  1981.  Example
  1982.  
  1983.       repeat         ; to wait for a character,
  1984.          inputch ch  ;  repeat the INPUTCH until
  1985.       until success  ;  a character is available
  1986.       clear key      ; give up keyboard control such that
  1987.                      ;  following keys are sent to remote
  1988.                      ;  system automatically
  1989.  
  1990.  
  1991.  Itoa
  1992.  ─────────────────────────────────────────────────────────────────────
  1993.  
  1994.  Function     Converts an integer to a string.
  1995.  
  1996.  Syntax       ITOA i,s
  1997.  
  1998.  Remark       ITOA converts the integer <i> to a string and store it
  1999.               into <s>.
  2000.  
  2001.  Return       <s> contains the string representation of the value <i>.
  2002.  
  2003.  See also     Atoi
  2004.  
  2005.  
  2006.  
  2007.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    35
  2008.  
  2009.  
  2010.  Length
  2011.  ─────────────────────────────────────────────────────────────────────
  2012.  
  2013.  Function     Calculates the length of a string.
  2014.  
  2015.  Syntax       LENGTH s,len
  2016.  
  2017.  Return       <len> is the length of <s>.  If <s> is an empty, <len>
  2018.               is 0.
  2019.  
  2020.  
  2021.  LoadFon
  2022.  ─────────────────────────────────────────────────────────────────────
  2023.  
  2024.  Function     Loads a phone directory.
  2025.  
  2026.  Syntax       LOADFON phoneDir
  2027.  
  2028.  Remark       LOADFON loads the <phoneDir>, with extension .FON and
  2029.               the corresponding memo file, with extension .MEM, into
  2030.               the dial window.
  2031.  
  2032.               If <phoneDir> does not include a directory, the Telemate
  2033.               directory is used.  The extension .FON can be omitted.
  2034.  
  2035.  Return       Upon successful completion, SUCCESS is set to TRUE; if
  2036.               <phoneDir> does not exist, SUCCESS is FALSE.
  2037.  
  2038.  See also     Dial
  2039.  
  2040.  
  2041.  LogOff
  2042.  ─────────────────────────────────────────────────────────────────────
  2043.  
  2044.  Function     Closes the log file.
  2045.  
  2046.  Syntax       LOGOFF
  2047.  
  2048.  Remark       LOGOFF closes a previous opened log file.
  2049.  
  2050.  Return       LOGGING is set to 0 (FALSE).
  2051.  
  2052.  See also     LogOn, LogPause, LogResume
  2053.  
  2054.  
  2055.  
  2056.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    36
  2057.  
  2058.  
  2059.  LogOn
  2060.  ─────────────────────────────────────────────────────────────────────
  2061.  
  2062.  Function     Opens a log file and captures incoming data into the
  2063.               file.
  2064.  
  2065.  Syntax       LOGON
  2066.               LOGON filename
  2067.  
  2068.  Remark       LOGON opens the log file <filename> and starts capturing
  2069.               the incoming data into it.
  2070.  
  2071.               If <filename> is not supplied, the filename specified in
  2072.               the log file field of the phone directory is used.  If
  2073.               this field is empty, "TM.LOG" is used.
  2074.  
  2075.  Return       Upon successful completion, SUCCESS is set to TRUE and
  2076.               LOGGING is set to 1 (TRUE); otherwise, SUCCESS is 0
  2077.               (FALSE).
  2078.  
  2079.  See also     LogOff, LogPause, LogResume
  2080.  
  2081.  
  2082.  LogPause
  2083.  ─────────────────────────────────────────────────────────────────────
  2084.  
  2085.  Function     Pauses capturing incoming data into the log file.
  2086.  
  2087.  Syntax       LOGPAUSE
  2088.  
  2089.  Remark       LOGPAUSE pauses capturing incoming data.  The LOGGING
  2090.               variable should be checked to determine if a log file
  2091.               open.  A value of 1 indicates a log file is open.
  2092.  
  2093.  Return       LOGGING is set to 2.
  2094.  
  2095.  See also     LogOff, LogOn, LogResume
  2096.  
  2097.  
  2098.  LogResume
  2099.  ─────────────────────────────────────────────────────────────────────
  2100.  
  2101.  Function     Resumes capturing incoming data into the log file.
  2102.  
  2103.  Syntax       LOGRESUME
  2104.  
  2105.  Remark       LOGRESUME resumes captureing incoming data. The LOGGING
  2106.               variable should be checked to determine if the log file
  2107.               is in pause.  A value of 2 indicates the log file is in
  2108.               pause.
  2109.  
  2110.  Return       LOGGING is set to 1.
  2111.  
  2112.  See also     LogOff, LogOn, LogPause
  2113.  
  2114.  
  2115.  
  2116.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    37
  2117.  
  2118.  
  2119.  Open
  2120.  ─────────────────────────────────────────────────────────────────────
  2121.  
  2122.  Function     Opens a text file for reading or writing.
  2123.  
  2124.  Syntax       OPEN filename
  2125.  
  2126.  Remark       OPEN opens the text file <filename> for reading and
  2127.               writing and strip the ending EOF (Ctrl Z).
  2128.  
  2129.               OPEN closes the previously open file automatically if no
  2130.               CLOSE command is issued to that file.
  2131.  
  2132.  Return       Upon successful completion, SUCCESS is set to TRUE.  If
  2133.               <filename> does not exist, SUCCESS is FALSE.
  2134.  
  2135.  See also     Append, Close, Create, FileExist, FileSize, Read,
  2136.               Read, Seek, Tell, Write
  2137.  
  2138.  Example
  2139.  
  2140.       open "MYFILE"       ; open the file "MYFILE"
  2141.       if not success      ; report if not found
  2142.          print "File not found."
  2143.          stop
  2144.       endif
  2145.       read s              ; read the first line
  2146.       print s             ; print it
  2147.       close               ; close the file
  2148.  
  2149.       open "FILE1"        ; open FILE1
  2150.       open "FILE2"        ; close FILE1 and open FILE2
  2151.  
  2152.  
  2153.  Print
  2154.  ─────────────────────────────────────────────────────────────────────
  2155.  
  2156.  Function     Prints integers or strings to the terminal screen.
  2157.  
  2158.  Syntax       PRINT
  2159.               PRINT s
  2160.               PRINT i
  2161.               PRINT s1,s2,i1,i2,s3, ...
  2162.               PRINT s1,s2,i1,i2,s3, ... ,
  2163.  
  2164.  Remark       PRINT outputs variables or constants of integer or
  2165.               string to the terminal screen. Each two arguments are
  2166.               separated by a comma.
  2167.  
  2168.               PRINT supplies a newline by default. If a tailing comma
  2169.               follows, no newline is supplied.
  2170.  
  2171.  See also     At, WhereX, WhereY
  2172.  
  2173.  
  2174.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    38
  2175.  
  2176.  
  2177.  Example
  2178.  
  2179.       print "hello, world"   ; say hello to everyone
  2180.       print "hello, ",       ; say that again
  2181.       print "world",
  2182.       print
  2183.  
  2184.       print "x = ",x         ; output multiple strings or integers
  2185.       print "My name is ",FirstName," ",LastName
  2186.  
  2187.  
  2188.  
  2189.  Put
  2190.  ─────────────────────────────────────────────────────────────────────
  2191.  
  2192.  Function     Sends strings or integers to the remote system.
  2193.  
  2194.  Syntax       PUT
  2195.               PUT s
  2196.               PUT i
  2197.               PUT s1,s2,i1,i2,s3, ...
  2198.               PUT s1,s2,i1,i2,s3, ... ,
  2199.  
  2200.  Remark       Like the PRINT statement, PUT sends variables or
  2201.               constants of types integer or string to the remote
  2202.               system.  Each two arguments are separated by a comma.
  2203.               Integers are converted to their string representation
  2204.               automatically before transmitting to the remote system.
  2205.  
  2206.               PUT supplies a carriage return (Ctrl M) by default.  If
  2207.               a tailing comma follows, no carriage return is supplied.
  2208.  
  2209.               Control characters can be sent by using the '^' prefix.
  2210.               For example, "^C" represents the Ctrl-C, "^M" the
  2211.               carriage return [Enter] and "^[" the Escape key [Esc].
  2212.  
  2213.               The following macro sequences have special meanings.
  2214.  
  2215.                    ^^     the character '^'
  2216.                    ^~     the character '~'
  2217.                    ~      pause 0.5 second
  2218.                    ^#     drop DTR signal to hangup modem
  2219.                    ^%     break signal
  2220.                    ^$     memo field in phone directory
  2221.                    ^&     password field in phone directory
  2222.                    ^*     modem hangup string
  2223.                    ^(     modem init string
  2224.                    ^)     modem answer string
  2225.  
  2226.  See also     Clear COM, ComOutCount, Waitfor
  2227.  
  2228.  
  2229.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    39
  2230.  
  2231.  
  2232.  Example
  2233.  
  2234.       put "FIRST LAST"    ; transmit first name and last name
  2235.                           ;  then a carriage return (^M)
  2236.       put "FIRST ",       ; same as above
  2237.       put "LAST",
  2238.       put
  2239.  
  2240.       put                 ; these two lines are
  2241.       put "^M",           ;  equivalent
  2242.  
  2243.       FirstName = "FIRST" ; set first and last name
  2244.       LastName = "LAST"
  2245.       Password = "^&"     ; use the password field in TM.FON
  2246.       put FirstName," ",LastName,"^M~~~~",Password
  2247.              ; send name, [Enter], wait for 2 seconds then send
  2248.              ;  the password, [Enter]
  2249.  
  2250.       put "~^#~~^)",      ; wait 0.5 second, drop DTR,
  2251.                           ;  wait 1 second, then sends the
  2252.                           ;  modem answer string
  2253.  
  2254.  
  2255.  Read
  2256.  ─────────────────────────────────────────────────────────────────────
  2257.  
  2258.  Function     Reads a string from a text file.
  2259.  
  2260.  Syntax       READ s
  2261.  
  2262.  Remark       READ reads characters from the file into <s>.
  2263.  
  2264.               READ does not place the newline sequence CR-LF into the
  2265.               string.
  2266.  
  2267.  Return       On success, <s> contains the string read and SUCCESS is
  2268.               set to TRUE.  SUCCESS is FALSE on end-of-file or error.
  2269.  
  2270.  See also     Close, Open, ReadCh, Seek, Tell
  2271.  
  2272.  
  2273.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    40
  2274.  
  2275.  
  2276.  Example
  2277.  
  2278.       open "MYFILE"       ; count lines in the file MYFILE
  2279.       if not success
  2280.          print "File not found."
  2281.          stop             ; stop if file not found
  2282.       endif
  2283.       n = 0               ; number of line = 0
  2284.       read str            ; read a line
  2285.       while success       ; repeat until end of file
  2286.          n = n + 1        ; increase counter
  2287.          read str         ; read the next string
  2288.       endwhile
  2289.       close               ; close the file
  2290.       print "There are ",n," lines in the file"
  2291.  
  2292.  
  2293.       open "TM.FON"       ; read a record from the phone directory
  2294.       recno = 10          ; read the record #10
  2295.       reclen = 131        ; record length of a entry
  2296.       seek recno*reclen   ; seek to the record position
  2297.       read record         ; read the record
  2298.       close
  2299.  
  2300.  
  2301.  ReadCh
  2302.  ─────────────────────────────────────────────────────────────────────
  2303.  
  2304.  Function     Reads a character from a text file.
  2305.  
  2306.  Syntax       READCH ch
  2307.  
  2308.  Remark       READCH reads a single character from the file into <ch>.
  2309.  
  2310.               In a text file, a CR (Ctrl M) followed by a LF (Ctrl J)
  2311.               indicates end-of-line.
  2312.  
  2313.  Return       On success, <ch> contains the chharacter read and SUCCESS is
  2314.               set to TRUE.  SUCCESS is FALSE on end-of-file or error.
  2315.  
  2316.  See also     Close, Open, ReadCh, Seek, Tell
  2317.  
  2318.  
  2319.  Receive
  2320.  ─────────────────────────────────────────────────────────────────────
  2321.  
  2322.  Function     Receives (Downloads) one or more files from the remote
  2323.               system.
  2324.  
  2325.  Syntax       RECEIVE protocol
  2326.               RECEIVE protocol,filename
  2327.  
  2328.  Remark       RECEIVE receives (download) one or more files from the
  2329.               remote system using the protocol <protocol>.  <protocol>
  2330.               can be one of the following or the menu key for external
  2331.               protocol.
  2332.  
  2333.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    41
  2334.  
  2335.  
  2336.               <protocol>     Protocol        <filename> needed
  2337.               ──────────     ────────        ─────────────────
  2338.                  "Z"         Zmodem                 No
  2339.                  "S"         SEAlink                No
  2340.                  "X"         Xmodem (Xmodem-1K)     Yes
  2341.                  "R"         Relaxed Xmodem         Yes
  2342.                  "Y"         Ymodem                 No
  2343.                  "B"         Batch Ymodem           No
  2344.                  "G"         Ymodem-G               No
  2345.                  "T"         Telink                 No
  2346.                  "M"         Modem7                 No
  2347.                  "A"         ASCII                  Yes
  2348.                  "Q"         CIS Quick B            No
  2349.  
  2350.               For protocols, such as Xmodem, which does not pass the
  2351.               name, <filename> should contains the name being
  2352.               received.  Wildcards are not allowed. If <filename> is
  2353.               "" and <GuessFile> option is on, the guessing name is
  2354.               used.
  2355.  
  2356.               Zmodem has the ability to start automatically which is
  2357.               called Zmodem AutoDownload - the <zAutoDownload> option.
  2358.               To prevent the download starts before the command
  2359.               RECEIVE "Z" is issued, the <zAutoDownload> option should
  2360.               be turned off before telling the remote system to start
  2361.               the transfer.
  2362.  
  2363.  Return       If the file transfer is successful, SUCCESS is set to
  2364.               TRUE; SUCCESS is FALSE if the transfer abort.
  2365.  
  2366.               For external protocols, SUCCESS is always set to TRUE.
  2367.  
  2368.  See also     Send, Set GuessFile, Set zAutoDownload, Waitfor
  2369.  
  2370.  Example
  2371.  
  2372.       receive "x","file.zip"   ; Xmodem needs the filename
  2373.       receive "y"              ; Ymodem doesn't
  2374.  
  2375.       recieve "x",""           ; use the guessing name as filename
  2376.  
  2377.       set zAutoDownload,off    ; you must turn it off before you tell
  2378.       waitfor "command",10     ;  the remote system to send the files,
  2379.       put "d z *.zip"          ;  otherwise, the system's AutoDownload
  2380.       receive "z"              ;  procedure will take the control and
  2381.                                ;  the RECEIVE command will return a
  2382.                                ;  wrong SUCCESS value, after the
  2383.       set zAutoDownload,on     ;  transfer, you may turn it back to on
  2384.       if success
  2385.          print "File received successfully"
  2386.       else
  2387.          print "File transfer aborted"
  2388.       endif
  2389.  
  2390.  
  2391.  
  2392.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    42
  2393.  
  2394.  
  2395.  Rename
  2396.  ─────────────────────────────────────────────────────────────────────
  2397.  
  2398.  Function     Renames a file.
  2399.  
  2400.  Syntax       RENAME oldname,newname
  2401.  
  2402.  Remark       RENAMES changes the name of a file from <oldname> to
  2403.               <newname>.
  2404.  
  2405.               Directories in <oldname> and <newname> need not be the
  2406.               same, therefore, RENAME can be used to move a file from
  2407.               one directory to another.  Wildcardssssssss are not
  2408.               allowed.
  2409.  
  2410.  Return       On successfully renameing the file, SUCCESS is set to
  2411.               TRUE; otherwise, SUCCESS is FALSE.
  2412.  
  2413.  See also     Delete, FileExist
  2414.  
  2415.  
  2416.  Script
  2417.  ─────────────────────────────────────────────────────────────────────
  2418.  
  2419.  Function     Executes another script program.
  2420.  
  2421.  Syntax       SCRIPT scriptName
  2422.  
  2423.  Remark       SCRIPT terminates the execution of the current script
  2424.               and executes the script program <scriptName>.
  2425.  
  2426.               <scriptName> may not contain the extension part of a
  2427.               filename.  If <scriptName> does not include a path, the
  2428.               Script directory is used.
  2429.  
  2430.  Example
  2431.  
  2432.       script "HOST" ; executes the HOST.SCR in the Script directory
  2433.  
  2434.  
  2435.  Seek
  2436.  ─────────────────────────────────────────────────────────────────────
  2437.  
  2438.  Function     Repositions the file pointer.
  2439.  
  2440.  Syntax       SEEK filepos
  2441.  
  2442.  Remark       SEEK sets the file pointer to the new position
  2443.               <filepos>.  At beginning of a file, the file pointer is
  2444.               0.
  2445.  
  2446.               If <filepos> is -1, the file pointer is moved to the end
  2447.               of the file.
  2448.  
  2449.  Return       If the pointer is successfully moved, SUCCESS is set to
  2450.               TRUE; otherwise, SUCCESS is FALSE.
  2451.  
  2452.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    43
  2453.  
  2454.  
  2455.  See also     Read, ReadCh, Tell, Write
  2456.  
  2457.  Example                                  
  2458.  
  2459.       ; suppose TM.FON is open, to read record #10 without changing
  2460.       ; the file position, the TELL statement should be used
  2461.       tell filepos     ; store file position
  2462.       seek 10*131      ; move to record #10, each record is 131 bytes
  2463.       read record      ; read the record
  2464.       seek filepos     ; move back to previous position
  2465.  
  2466.  
  2467.  Send
  2468.  ─────────────────────────────────────────────────────────────────────
  2469.  
  2470.  Function     Sends (uploads) one or more files to remote system.
  2471.  
  2472.  Syntax       SEND protocol,filenames
  2473.  
  2474.  Remark       SEND sends (uploads) one or more files to the remote
  2475.               system using the protocol <protocol>. <protocol> can
  2476.               be one of the following or the menu key for external
  2477.               protocol.
  2478.  
  2479.               <protocol>     Protocol        Send multiple files
  2480.               ──────────     ────────        ───────────────────
  2481.                  "Z"         Zmodem                 Yes
  2482.                  "S"         SEAlink                Yes
  2483.                  "X"         Xmodem (Xmodem-1K)     No
  2484.                  "R"         Relaxed Xmodem         No
  2485.                  "Y"         Ymodem                 No
  2486.                  "B"         Batch Ymodem           Yes
  2487.                  "G"         Ymodem-G               Yes
  2488.                  "T"         Telink                 Yes
  2489.                  "M"         Modem7                 Yes
  2490.                  "A"         ASCII                  No
  2491.                  "Q"         CIS Quick B            Yes
  2492.  
  2493.               <filenames> is a list of filenames to be sent, wildcard
  2494.               characters '*' and '?' can be used.  If <filename> is
  2495.               "" and <GuessFile> option is on, the guessing name is
  2496.               used.  Multiple files are seperated by a space. For
  2497.               example,
  2498.                  "\TM\TM210-1.ZIP \TM\TM\210-2.ZIP"
  2499.                  "*.ZIP \UTIL\*.EXE *.TXT"
  2500.  
  2501.               For protocols, such as Xmodem, which cannot transfer
  2502.               multiple files, only the first file in <filenames>.
  2503.  
  2504.  Return       If the file transfer is successful, SUCCESS is set to
  2505.               TRUE; SUCCESS is FALSE if the transfer abort.
  2506.  
  2507.               For external protocols, SUCCESS is always set to TRUE.
  2508.  
  2509.  See also     Receive, Set GuessFile, Waitfor
  2510.  
  2511.  
  2512.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    44
  2513.  
  2514.  
  2515.  Example                                  
  2516.  
  2517.       send "z","a:*.* b:*.*"      ; Zmodem upload
  2518.       if success
  2519.          print "File sent successfully"
  2520.       else
  2521.          print "File transfer aborted"
  2522.       endif
  2523.  
  2524.  
  2525.  Set
  2526.  ─────────────────────────────────────────────────────────────────────
  2527.  
  2528.  Function     Sets option value.
  2529.  
  2530.  Syntax       SET <OPTION>,<VALUE>
  2531.  
  2532.  Remark       The SET statement gives you control over many of the
  2533.               system options.  The possible options and values are
  2534.               listed below.
  2535.  
  2536.       <OPTION>          <VALUE>     Description
  2537.       ─────────────     ────────    ──────────────────────────────────
  2538.       AddLineFeed       On / Off    when On, a line feed is supplied
  2539.                                     after a carriage return (Ctrl-M)
  2540.                                     is received
  2541.       AddReturn         On / Off    when On, a carriage return is
  2542.                                     supplied after a line feed is
  2543.                                     received
  2544.       AlarmSound        0 - 999     in second, amount of time that
  2545.                                     the alarm music is to be played
  2546.       AlarmTime         0 - 999     in second, amount of time that
  2547.                                     the alarm window is to be shown
  2548.       AutoWrap          On / Off    when On, character after column 80
  2549.                                     is wrapped to the new line.
  2550.       Baud            300 - 115200  set baud rate (300,1200,2400,4800,
  2551.                                     9600,19200,38400,57600,115200)
  2552.       Bell              On / Off    when Off, no bell when Ctrl-G
  2553.                                     received
  2554.       Capture           On / Off    when Off, the backscroll buffer
  2555.                                     stops capturing the incoming data
  2556.       CharPacing        0 - 99      in tenth second, amount of time
  2557.                                     that the Paste or ASCII upload
  2558.                                     pause when a character is sent
  2559.       ConfirmHangUp     On / Off    when On, confirm if required if
  2560.                                     [Alt H] is pressed
  2561.       Connection     Modem/Computer set the connection type
  2562.       Data               7 / 8      set data bits
  2563.       DestBs            On / Off    set destructive backspace
  2564.       DialAttempt       0 - 999     the number of attempt that the
  2565.                                     dialing process will preform,
  2566.                                     0 to dial until connected
  2567.       DialList          "..."       set the dial list
  2568.       DialPause         0 - 999     in second, amount of time to be
  2569.                                     wait between two dials
  2570.       DialTime          0 - 999     in second, amount of time to be
  2571.  
  2572.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    45
  2573.  
  2574.  
  2575.                                     wait after a number is dialed
  2576.       ExpandBlankLine   On / Off    when On, blank lines are
  2577.                                     expanded to lines containing
  2578.                                     a space
  2579.       ExtendedPacing    0 - 99      in tenth second, amount of time
  2580.                                     that the Put command or the macro
  2581.                                     keys pause when a character is
  2582.                                     sent
  2583.       GuessFile         On / Off    when On, guessed name is put in
  2584.                                     the file selection box
  2585.       GuessInitial      On / Off    when On, guessed initial is put
  2586.                                     in the quote string
  2587.       Incoming          On / Off    set incoming translation
  2588.       LinePacing        0 - 99      in tenth second, amount of
  2589.                                     time that the Paste function
  2590.                                     pause when a Ctrl-M is sent
  2591.       LocalEcho         On / Off    when On, characters are
  2592.                                     displayed in the terminal
  2593.       Music             On / Off    when Off, the music string
  2594.                                     is not interpreted
  2595.       Outgoing          On / Off    set outgoing translation
  2596.       PaceChar          0 - 255     in ASCII, the character to be
  2597.                                     wait before pasting each line,
  2598.                                     0 to disable this function
  2599.       Parity          None/Odd/Even set parity
  2600.       Port              1 - 8       set COM port number
  2601.       Prefix            1 - 4       set the dialing prefix
  2602.       Printer           On / Off    when On, received data is
  2603.                                     sent to printer
  2604.                                     DOS shell
  2605.       RtsCts            On / Off    set RTS/CTS flow control
  2606.       Stop               1 / 2      set stop bits
  2607.       StripHighBit      On / Off    when On, the 8th bit is stripped
  2608.                                     from the incoming data
  2609.       Suffix            1 - 4       set the dialing suffix
  2610.       SwapToDisk        On / Off    when On, Telemate swaps part
  2611.                                     of itself to disk during DOS
  2612.                                     shell
  2613.       SwapToEms         On / Off    when On, Telemate swaps part
  2614.                                     of itself to EMS/XMS during
  2615.       Terminal  TTY/ANSI/VT102/VT52 set the terminal type
  2616.       UsageLog          On / Off    set usage log
  2617.       XonXoff           On / Off    set XON/XOFF flow control
  2618.                                     is received
  2619.       zASCII            On / Off    when On, Zmodem indicates that
  2620.                                     the upload is a ASCII file
  2621.       zAutoDownload     On / Off    when Off, Zmodem does not
  2622.                                     download automatically
  2623.       zRecovery         ON / OFF    when Off, Zmodem does not
  2624.                                     recover aborted transfer
  2625.  
  2626.  See also     Alarm, Dial, Dos, Receive, Send
  2627.  
  2628.  
  2629.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    46
  2630.  
  2631.  
  2632.  Example
  2633.  
  2634.       BaudRate = 2400
  2635.       set baud,BaudRate   ; set baud rate to 2400
  2636.       set baud,2400       ; same as above
  2637.       set incoming,on     ; turn on incoming translation
  2638.       set terminal,VT102  ; set terminal type to VT102
  2639.  
  2640.  Stop
  2641.  ─────────────────────────────────────────────────────────────────────
  2642.  
  2643.  Function     Terminates the execution of the current script program.
  2644.  
  2645.  Syntax       STOP
  2646.  
  2647.  Remark       STOP is usally used when an error is encountered.
  2648.  
  2649.  See also     ExitTelemate
  2650.  
  2651.  Example
  2652.  
  2653.       open "MYFILE"               ; open a file
  2654.       if not success
  2655.          print "File not found."
  2656.          Stop                     ; terminate if file not found
  2657.       endif
  2658.  
  2659.  
  2660.  StrDel
  2661.  ─────────────────────────────────────────────────────────────────────
  2662.  
  2663.  Function     Deletes characters from a string.
  2664.  
  2665.  Syntax       STRDEL str,pos,count
  2666.  
  2667.  Remark       STRDEL deletes <count> characters from the position
  2668.               <pos> of the string <str>.
  2669.  
  2670.               The first character position is 1.
  2671.  
  2672.  Return       <str> contains the new string.
  2673.  
  2674.  See also     Concat, Length, StrIns, StrPos, SetSet, SubStr
  2675.  
  2676.  Example
  2677.  
  2678.       str = "abcXYZdef"
  2679.       strdel str,4,3      ; delete "XYZ"
  2680.       print str           ; "abcdef"
  2681.  
  2682.  
  2683.  
  2684.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    47
  2685.  
  2686.  
  2687.  StrIns
  2688.  ─────────────────────────────────────────────────────────────────────
  2689.  
  2690.  Function     Inserts a string into another string.
  2691.  
  2692.  Syntax       STRINS str,substr,pos
  2693.  
  2694.  Remark       STRINS inserts a string <substr> into another string
  2695.               <str> at position <pos>.
  2696.  
  2697.               If <pos> is larger than the length of <str>, the gap is
  2698.               filled with spaces.  The first character position is 1.
  2699.  
  2700.  Return       <str> contains the new string.
  2701.  
  2702.  See also     Concat, Length, StrDel, StrPos, SetSet, SubStr
  2703.  
  2704.  Example
  2705.  
  2706.       str = "abcdef"
  2707.       strins str,"XYZ",4  ; insert "XYZ"
  2708.       print str           ; "abcXYZdef"
  2709.  
  2710.       str = "abc"
  2711.       strins str,"xyz",10 ; <count> is larger than the length of <str>
  2712.       print str           ; "abc      xyz"
  2713.  
  2714.  
  2715.  StrPos
  2716.  ─────────────────────────────────────────────────────────────────────
  2717.  
  2718.  Function     Scans a string for the occurrence of a given substring.
  2719.  
  2720.  Syntax       STRPOS str,substr,pos
  2721.  
  2722.  Remark       STRPOS scans <str> for the first occurence of the
  2723.               substring <substr>.   Case is not sensitive.
  2724.  
  2725.               The first character position is 1.
  2726.  
  2727.  Return       If <substr> is a substring of <str>, <pos> is the
  2728.               position of the substring; otherwise, <pos> is 0.
  2729.  
  2730.  See also     Concat, Length, StrDel, StrIns, SetSet, SubStr
  2731.  
  2732.  Example
  2733.  
  2734.       strpos "abcdef","def",pos
  2735.       print pos                   ;  4
  2736.  
  2737.  
  2738.  
  2739.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    48
  2740.  
  2741.  
  2742.  StrSet
  2743.  ─────────────────────────────────────────────────────────────────────
  2744.  
  2745.  Function     Sets part of a string to a given character.
  2746.  
  2747.  Syntax       STRSET str,ch,pos,count
  2748.  
  2749.  Remark       STRSET sets the string <str> starting from position
  2750.               <pos> with <count> character <ch>.
  2751.  
  2752.               If <pos> is larger than the length of <str>, the gap is
  2753.               filled with spaces.  The first character position is 1.
  2754.  
  2755.  Return       <str> contains the new string.
  2756.  
  2757.  See also     Concat, Length, StrDel, StrIns, SetPos, SubStr
  2758.  
  2759.  Example
  2760.  
  2761.       str = "abc"
  2762.       strset str,"X",3,10
  2763.       print str           ; "abXXXXXXXXXX"
  2764.  
  2765.  
  2766.  SubStr
  2767.  ─────────────────────────────────────────────────────────────────────
  2768.  
  2769.  Function     Returns a substring from a given string.
  2770.  
  2771.  Syntax       SUBSTR src,pos,count,dest
  2772.  
  2773.  Remark       SUBSTR returns a substring in the string <src> starting
  2774.               at <pos> of length <count> into the string <dest>.
  2775.  
  2776.               The first character position is 1.
  2777.  
  2778.  Return       <dest> contains the substring.
  2779.  
  2780.  See also     Concat, Length, StrDel, StrIns, SetPos, StrSet
  2781.  
  2782.  Example
  2783.  
  2784.       substr "abcdef",1,3,dest
  2785.       print dest                  ; "abc"
  2786.  
  2787.  
  2788.  
  2789.  
  2790.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    49
  2791.  
  2792.  
  2793.  Tell
  2794.  ─────────────────────────────────────────────────────────────────────
  2795.  Function     Returns the current file pointer.
  2796.  
  2797.  Syntax       TELL filepos
  2798.  
  2799.  Remark       TELL returns the current file pointer.  <filepos> is
  2800.               measured in bytes from the beginning of the file.  At
  2801.               the beginning of the file, <filepos> is 0.
  2802.  
  2803.               Sometime it is neccessary to open more than one file,
  2804.               you can implement it by storing the file position of the
  2805.               original file, then restore it after the other file
  2806.               operation is completed.
  2807.  
  2808.  Return       <filepos> is the current file pointer.
  2809.  
  2810.  See also     Seek, Read, Write
  2811.  
  2812.  Example
  2813.  
  2814.       i = 1
  2815.       filepos = 0                 ; at at beginning of file
  2816.       while i<=10
  2817.          open "bbsname"           ; open data file
  2818.          seek filepos             ; move the previous position
  2819.          read name                ; read a bbs name
  2820.          tell filepose            ; store the current position
  2821.          close                    ; close the file
  2822.          PhoneFind name,number    ; find the board in TM.FON
  2823.                                   ;  suppose the PhoneFind procedure
  2824.                                   ;  open the TM.FON
  2825.          if number<>0             ; yes, it is in TM.FON
  2826.             print name," found is entry #",number
  2827.          endif
  2828.       endwhile
  2829.  
  2830.  
  2831.  Time
  2832.  ─────────────────────────────────────────────────────────────────────
  2833.  
  2834.  Function     Gets system time.
  2835.  
  2836.  Syntax       TIME now
  2837.  
  2838.  Remark       TIME fills the string <now> with the current time.
  2839.  
  2840.               Times can be compared with the usual '<', '>' and '='
  2841.               relational operator.
  2842.  
  2843.  Return       <now> contains the system current date in HH:MM:SS
  2844.               24 hour format.
  2845.  
  2846.  See also     Date
  2847.  
  2848.  
  2849.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    50
  2850.  
  2851.  
  2852.  Example
  2853.  
  2854.       time now
  2855.       if now>"07:00:00" and now<="07:59:59"
  2856.          print "Good morning."
  2857.       endif
  2858.  
  2859.  
  2860.  Usage
  2861.  ─────────────────────────────────────────────────────────────────────
  2862.  
  2863.  Function     Puts a string into the usage file.
  2864.  
  2865.  Syntax       USAGE <usageString>
  2866.  
  2867.  Remark       USAGES puts the string <usageString> into the usage file
  2868.               TM.USE.  The current time and date are added to the
  2869.               beginning of the line automatically.
  2870.  
  2871.  Example
  2872.  
  2873.       Usage "Switching to Host mode"
  2874.  
  2875.  
  2876.  Waitfor
  2877.  ─────────────────────────────────────────────────────────────────────
  2878.  
  2879.  Function     Waits for one of the given strings from the remote
  2880.               system.
  2881.  
  2882.  Syntax       WAITFOR t
  2883.               WAITFOR s1,s2, ... , sN
  2884.               WAITFOR s1,s2, ... , sN, t
  2885.  
  2886.  Remark       The 'WAITFOR t' format set the default waiting time to
  2887.               <t>, in second.  If <t> is 0, no time checking is
  2888.               performed.
  2889.  
  2890.               The 'WAITFOR s1,s2, ... , sN' format waits until one of
  2891.               the given string is received from the remote system or
  2892.               the default waiting time exceeded.
  2893.  
  2894.               The 'WAITFOR s1,s2, ... , sN,t' format set the default
  2895.               waiting time to <t>, in second and waits until one of
  2896.               the given string is received from the remote system or
  2897.               the waiting time exceeded.
  2898.  
  2899.               Case is not sensitive when comparing the given string
  2900.               with the characters received from the remote system.
  2901.  
  2902.               Sometimes the remote system need a slight delay between
  2903.               the prompt and the response, you can use DELAY or the
  2904.               "~" helf-second marco before the PUT command.
  2905.  
  2906.  
  2907.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    51
  2908.  
  2909.  
  2910.  Return       If the waiting time exceeded, FOUND is set to 0 (FALSE);
  2911.               otherwise, FOUND is set the string number of the matched
  2912.               string.
  2913.  
  2914.  See also     Delay, Put, Receive, Send, WaitUntil, When, WhenIdle
  2915.  
  2916.  Example
  2917.  
  2918.       waitfor "first",30        ; wait for "first" in 30 seconds
  2919.       if not found
  2920.          print "Not found."     ; if not found, stop
  2921.          stop
  2922.       else
  2923.          delay 5
  2924.          put "my name"          ; else send the first and
  2925.       endif                     ;  last names
  2926.  
  2927.       ; The following is usually placed at the end of a script file.
  2928.       ; It waits for disconnection and print which string is found.
  2929.  
  2930.       waitfor "NO CARRIER","thanks for calling","hang up now",0
  2931.       print "Ending connection"
  2932.  
  2933.       ; The following simulates the AutoDownload feature for protocols
  2934.       ; does not support this feature.
  2935.  
  2936.       waitfor "Download protocol is",0
  2937.       waitfor "Xmodem","Ymodem","SEAlink",5
  2938.       if found
  2939.          switch found
  2940.             case 1: receive "x","" ; Xmodem, use guessing name
  2941.             case 2: receive "y"    ; Ymodem download
  2942.             case 3: receive "s"    ; SEAlink download
  2943.          endswitch
  2944.       endif
  2945.  
  2946.  
  2947.  WaitUntil
  2948.  ─────────────────────────────────────────────────────────────────────
  2949.  
  2950.  Function     Waits until the specified time exceeded.
  2951.  
  2952.  Syntax       WAITUNTIL t
  2953.  
  2954.  Remark       WAITUNTIL pauses the execution and waits until the time
  2955.               <t>, in HH:MM:SS 24 hour format, exceeded.
  2956.  
  2957.  See also     Wait
  2958.  
  2959.  Example
  2960.  
  2961.       WaitUntil "23:10:30"  ; pause until 11:10:30pm.
  2962.  
  2963.  
  2964.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    52
  2965.  
  2966.  
  2967.  When
  2968.  ─────────────────────────────────────────────────────────────────────
  2969.  
  2970.  Function     Sends a response string to the remote system whenever a
  2971.               given string is matched.
  2972.  
  2973.  Syntax       WHEN <waitString>,<resonseString>
  2974.               WHEN <waitString>,""
  2975.  
  2976.  Remark       The WHEN statement is usually used in the beginning of
  2977.               the script file and it is active until the end of the
  2978.               script file.
  2979.  
  2980.               Whenever the <waitString> is received from the remote
  2981.               system, the <responseString> is transmitted.  The
  2982.               response string can be changed.  To cancel a WHEN
  2983.               statement, "" should be put in <responseString>.
  2984.  
  2985.               Case is not sensitive when comparing the <waitString>
  2986.               with the characters received from the remote system.
  2987.  
  2988.  See also     Waitfor, WhenIdle
  2989.  
  2990.  Example
  2991.  
  2992.       when "Press ENTER","^M"     ; set response strings
  2993.       when "More [y,n]?","y^M"
  2994.       waitfor "main menu",0       ; wait for "main menu"
  2995.       when "Press ENTER",""       ; cancel response string
  2996.       when "More [y,n]?","n^M"    ; change response string
  2997.       repeat                      ; make the WHEN statements
  2998.       until not connected         ; active until disconnected.
  2999.  
  3000.  
  3001.  WhenIdle
  3002.  ─────────────────────────────────────────────────────────────────────
  3003.  
  3004.  Function     Sends a string to the remote system if there is no COM
  3005.               Input/Output in the specified time.
  3006.  
  3007.  Syntax       WHENIDLE t,s
  3008.  
  3009.  Remark       WHENIDLE monitors the COM Input/Output and sends the
  3010.               string <s> to the remote system if COM I/O is idle for
  3011.               the specified time <t>, in second.
  3012.  
  3013.               Like the WHEN statement, WHENIDLE is active until the
  3014.               end of the script program.
  3015.  
  3016.               <s> can contain macro sequence, such as "^*", the modem
  3017.               hangup string.
  3018.  
  3019.               If <t> is equal to 0 or <s> is a empty string, the
  3020.               WHENIDLE statement will be cancel.
  3021.  
  3022.  See also     Waitfor, When
  3023.  
  3024.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    53
  3025.  
  3026.  
  3027.  Example
  3028.  
  3029.       waitfor "message command",0 ; wait for command prompt
  3030.       put "r"                     ; read message
  3031.       whenidle 30," ^H"           ; prevent inactive timeout
  3032.       repeat                      ; make the WHENIDLE statement
  3033.       until not connected         ; active until disconnected
  3034.  
  3035.       ; There are several usages of this command.  The above example
  3036.       ; shows the way to prevent inactive timeout.  However, it can
  3037.       ; also be used to handle inactive timeout in the host script
  3038.       ; mode.   For example,
  3039.  
  3040.       whenidle 180,"Inactive timeout^M^J~^*"
  3041.  
  3042.       ; this command checks if the COM I/O is idle for 3 minuates,
  3043.       ; sends a timeout message to the user and, finally, sends the
  3044.       ; hangup string, the hangup macro sequence "^*", to the modem.
  3045.  
  3046.       ; Sometimes the phone line is too noisy that some characters
  3047.       ; cannot be received correctly. The worst case is that those
  3048.       ; characters appear in the WAITFOR string.  To prevent inactive
  3049.       ; timeout or waste of connect time, the WHENIDLE can be used as
  3050.       ; follows.
  3051.  
  3052.       whenidle 5,"^M"             ; send a carriage return if idle
  3053.                                   ; for 5 seconds
  3054.       waitfor "first name"        ; now start the log on sequence
  3055.       put "first"
  3056.       waitfor "last name"         ; send first and last name
  3057.       put "last"
  3058.       waitfor "password"          ; send password macro
  3059.       put "^&"
  3060.       whenidle 0,""               ; cancel the WHENIDLE statement
  3061.  
  3062.  
  3063.  WhereX
  3064.  ─────────────────────────────────────────────────────────────────────
  3065.  
  3066.  Function     Gives the horizontal cursor position within the terminal
  3067.               window.
  3068.  
  3069.  Syntax       WHEREX column
  3070.  
  3071.  Remark       WHEREX returns the x-coordinate of the terminal window.
  3072.               The left-most column is 0.
  3073.  
  3074.  Return       <column> is the horizontal cursor position.
  3075.  
  3076.  See also     At, WhereX
  3077.  
  3078.  
  3079.  
  3080.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    54
  3081.  
  3082.  
  3083.  WhereY
  3084.  ─────────────────────────────────────────────────────────────────────
  3085.  
  3086.  Function     Gives the vertical cursor position within the terminal
  3087.               window.
  3088.  
  3089.  Syntax       WHEREY row
  3090.  
  3091.  Remark       WHEREY returns the y-coordinate of the terminal window.
  3092.               The top-most row is 0.
  3093.  
  3094.  Return       <row> is the vertical cursor position.
  3095.  
  3096.  See also     At, WhereY
  3097.  
  3098.  
  3099.  Write
  3100.  ─────────────────────────────────────────────────────────────────────
  3101.  
  3102.  Function     Writes integers or strings to a text file.
  3103.  
  3104.  Syntax       WRITE
  3105.               WRITE s
  3106.               WRITE i
  3107.               WRITE s1,s2,i1,i2,s3, ...
  3108.               WRITE s1,s2,i1,i2,s3, ... ,
  3109.  
  3110.  Remark       Like the PRINT statement, WRITE sends variables or
  3111.               constants of types integer or string to the remote
  3112.               system.  Each two arguments are separated by a comma.
  3113.               Integers are converted to their string representation
  3114.               automatically before transmitting to the remote system.
  3115.  
  3116.               WRITE supplies a carriage return (Ctrl M) and a line
  3117.               feed (Ctrl J) by default.  If a tailing comma follows,
  3118.               no carriage return and line feed is supplied.
  3119.  
  3120.  Return       Upon successful completion, SUCCESS is set to TRUE;
  3121.               otherwise, SUCCESS is FALSE.
  3122.  
  3123.  See also     Read, Seek, Tell
  3124.  
  3125.  Example
  3126.  
  3127.       create "COUNT"      ; write a hundred line into "COUNT"
  3128.       counter = 1         ; initiate the counter
  3129.       while counter<=100  ; repeat 100 times
  3130.          write "This is line ",counter
  3131.       endwhile
  3132.       close               ; close the file
  3133.  
  3134.  
  3135.  TELEMATE SCRIPT                             BUILT IN PROCEDURES    55
  3136.  
  3137.  
  3138.       newname = "New board name                "
  3139.       open "TM.FON"       ; change the name field of a record
  3140.       recno = 10          ; change the record #10
  3141.       reclen = 131        ; record length of a entry
  3142.       seek recno*reclen   ; seek to the record position
  3143.       write newname,      ; write the name
  3144.       close
  3145.  
  3146.  
  3147.  
  3148.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    56
  3149.  
  3150.  
  3151.  TOOLBOX PROCEDURES
  3152.  
  3153.  The toolboxes are a collection of useful script procedures.  They are
  3154.  written as a supplement of the  built-in procedures.  You may  freely
  3155.  modify the procedures and you are encourage to share your  experience
  3156.  with the other users.
  3157.  
  3158.  The first toolbox defines ANSI color codes and supplies useful  video
  3159.  procedures. The second one includes  three input procedures and  four
  3160.  character-type-checking  procedures.    The  third  one  provides   a
  3161.  standard method  to access  the phone  directory and  calculates  the
  3162.  difference between two date/time string.
  3163.  
  3164.  To use the toolboxes, you should add the lines
  3165.  
  3166.       #include "toolbox1.scr"         ,
  3167.       #include "toolbox2.scr"         and/or
  3168.       #include "toolbox3.scr"
  3169.  
  3170.  at the beginning  of your script  file.   To reduce the  size of  the
  3171.  compiled script file,  you should include  only the toolbox(es)  that
  3172.  contain the procedures you need.
  3173.  
  3174.  
  3175.  
  3176.  ─────────────────────────────────────────────────────────────────────
  3177.  Toolbox #1
  3178.  ─────────────────────────────────────────────────────────────────────
  3179.  
  3180.  This toolbox defines video color values,  ANSI color codes and a  set
  3181.  of video  procedures  which  output to  local  screen  and/or  remote
  3182.  system.
  3183.  
  3184.  To use this toolbox, you should add the line
  3185.     #include "toolbox1.scr"       ; include the toolbox
  3186.     TRUE = 1                      ; define boolean value
  3187.     FALSE = 0                     ;  for your convenience
  3188.  at the beginning of  your script file.   This will increase the  file
  3189.  size of the compiled script  file .TMS by about  4K.  To minimum  the
  3190.  overhead, you should cut and paste the procedures that you used  into
  3191.  your script  file.    For  example,  the  <EchoBox>  and  <EchoBlock>
  3192.  procedures may be excluded.
  3193.  
  3194.  
  3195.  
  3196.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    57
  3197.  
  3198.  
  3199.  Color Values and ANSI Color Codes
  3200.  ─────────────────────────────────────────────────────────────────────
  3201.  The following table  shows the  colors values  and its  corresponding
  3202.  foreground and background ANSI codes.
  3203.  
  3204.      Color    Symbolic    Foreground     Background
  3205.      Value    Name        ANSI code      ANSI code
  3206.    ──────────────────────────────────────────────────
  3207.        0      BLACK       FGBLACK        BKBLACK
  3208.        1      BLUE        FGBLUE         BKBLUE
  3209.        2      GREEN       FGGREEN        BKGREEN
  3210.        3      RED         FGRED          BKRED
  3211.        4      CYAN        FGCYAN         BKCYAN
  3212.        5      MAGENTA     FGMAGENTA      BKMAGENTA
  3213.        6      YELLOW      FGYELLOW       BKYELLOW
  3214.        7      WHITE       FGWHITE        BKWHITE
  3215.  
  3216.  You can use the symbolic names to  access a color.  For example,  the
  3217.  statement
  3218.  
  3219.      print FGYELLOW,BKBLUE
  3220.  
  3221.  to set the local color to yellow on blue.  Or you can use the toolbox
  3222.  procedures EchoColor and EchoBkColor to set the color.  For example,
  3223.  
  3224.      EchoColor YELLOW
  3225.      EchoBkColor BLUE
  3226.  
  3227.  have similar effect to the above.
  3228.  
  3229.  
  3230.  EchoToLocal and EchoToRemote
  3231.  ─────────────────────────────────────────────────────────────────────
  3232.  
  3233.  The  <EchoToLocol>  and  <EchoToRemote>   variables  tell  the   Echo
  3234.  procedures where the output is to be sent.  If <EchoToLocal> is TRUE,
  3235.  the output  is  sent  to  the  local  screen,  default  is  TRUE.  If
  3236.  <EchoToRemote> is  TRUE, the  output is  sent to  the remote  system,
  3237.  default is TRUE. These variables can both be TRUE.
  3238.  
  3239.  
  3240.  Echo and EchoInt
  3241.  ─────────────────────────────────────────────────────────────────────
  3242.  Function     Output a string or an integer to local screen and/or
  3243.               remote system.
  3244.  
  3245.  Syntax       Echo s
  3246.               EchoInt i
  3247.  
  3248.  Remark       ECHO outputs the string <s> while ECHOINT outputs the
  3249.               integer <i> to the local screen and/or remote system
  3250.               according to the variables <EchoToLocal> and
  3251.               <EchoToRemote>.
  3252.  
  3253.  
  3254.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    58
  3255.  
  3256.  
  3257.               If <EchoToLocal> is TRUE, the output is sent to the
  3258.               local screen.
  3259.  
  3260.               If <EchoToRemote> is TRUE, the output is sent to the
  3261.               remote system.
  3262.  
  3263.               Both variables can both be TRUE.  In this case, the
  3264.               output is sent to both the local screen and the remote
  3265.               system.
  3266.  
  3267.               All the procedures in this toolbox use these two
  3268.               procedures for output.  As a result, the output
  3269.               destination depends on the varaibles <EchoToLocal> and
  3270.               <EchoToRemote> too.
  3271.  
  3272.  Example
  3273.  
  3274.       TRUE  = 1           ; define boolean value
  3275.       FALSE = 0
  3276.  
  3277.       EchoToLocal = TRUE  ; echo to local screen
  3278.       EchoToRemote = FALSE;  but not to remote system
  3279.       Echo "This only display on local screen"
  3280.  
  3281.       EchoToRemoate = TRUE; now echo to remote system too
  3282.       EchoColor YELLOW    ; set yellow foreground
  3283.       EchoHiLite          ; high intensity
  3284.       EchoBkColor BLUE    ; set blue background
  3285.       Echo "Now both local screen and remote system is"
  3286.       Echo "yellow on blue"
  3287.  
  3288.  EchoBkColor
  3289.  ─────────────────────────────────────────────────────────────────────
  3290.  
  3291.  Function     Sets background color.
  3292.  
  3293.  Syntax       ECHOBKCOLOR color
  3294.  
  3295.  Remark       ECHOBKCOLOR sets the background color to <color> by
  3296.               outputing the corresponding background ANSI color code.
  3297.  
  3298.               <color> can be one of the following: BLACK, BLUE,GREEN,
  3299.               CYAN, RED, MAGENTA, YELLOW AND WHITE.
  3300.  
  3301.  See also     EchoColor
  3302.  
  3303.  Example
  3304.  
  3305.       EchoBkColor BLUE    ; blue background
  3306.  
  3307.       EchoColor BLACK     ; black on CYAN
  3308.       EchoBkColor CYAN
  3309.  
  3310.  
  3311.  
  3312.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    59
  3313.  
  3314.  
  3315.  EchoBlink
  3316.  ─────────────────────────────────────────────────────────────────────
  3317.  
  3318.  Function     Sets blink attribute.
  3319.  
  3320.  Syntax       ECHOBLINK
  3321.  
  3322.  See also     EchoHiLite, EchoNormal, EchoReverse
  3323.  
  3324.  Example
  3325.  
  3326.       EchoColor GREEN     ; green foregound
  3327.       EchoBlink           ; blink
  3328.  
  3329.  
  3330.  EchoBlock
  3331.  ─────────────────────────────────────────────────────────────────────
  3332.  
  3333.  Function     Draws a solid block of a character.
  3334.  
  3335.  Syntax       ECHOBLOCK left,top,right,bottom,style,fillchar
  3336.  
  3337.  Remark       ECHOBLOCK draws a filled-in, rectangular block.
  3338.  
  3339.               The upper left and lower right corners of the rectangle
  3340.               are given by (left,top) and (right,bottom).  The top-
  3341.               left corner is (0,0).
  3342.  
  3343.               <style> selects the type of block
  3344.                     0     spaces                      ' '
  3345.                     1     widely spaced block         '░'
  3346.                     2     spaced block                '▒'
  3347.                     3     closely spaced block        '▓'
  3348.                     4     solid block                 '█'
  3349.                     5     user-defined fill character <fillchar>
  3350.  
  3351.               <fillchar> should be set to "" for <style> not equal to
  3352.               5.
  3353.  
  3354.  See also     EchoBox
  3355.  
  3356.  Example
  3357.  
  3358.       EchoBlock 5,10,50,15,3,""   ; fill a block with closely spaced
  3359.                                   ;  block '▓'
  3360.       EchoBlock 0,0,79,24,5,"▀"   ; fill the screen with thick
  3361.                                   ;  horizontal line '▀▀▀▀▀▀▀▀'
  3362.  
  3363.  
  3364.  
  3365.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    60
  3366.  
  3367.  
  3368.  EchoBox
  3369.  ─────────────────────────────────────────────────────────────────────
  3370.  
  3371.  Function     Draws a box.
  3372.  
  3373.  Syntax       ECHOBOX left,top,right,bottom,style,fillchar,hollow
  3374.  
  3375.  Remark       ECHOBOX draws a rectangular box.
  3376.  
  3377.               The upper left and lower right corners of the rectangle
  3378.               are given by (left,top) and (right,bottom).  The top-
  3379.               left corner is (0,0).
  3380.  
  3381.               <style> selects the type of block
  3382.                     0     spaces
  3383.                     1     single line
  3384.                     2     double line
  3385.                     3     single vertical line, double horizontal line
  3386.                     4     double vertical line, single horizontal line
  3387.                     5     user-defined fill character <fillchar>
  3388.  
  3389.               <fillchar> should be set to "" for <style> not equal to
  3390.               5.
  3391.  
  3392.               If <hollow> is TRUE, the inside of the box is cleared.
  3393.  
  3394.  See also     EchoBlock
  3395.  
  3396.  Example
  3397.  
  3398.       EchoBox 5,10,50,15,2,"",1   ; draw a double-line box and
  3399.                                   ;  clear the inside of it
  3400.       EchoBox 0,0,79,24,5,"█",0   ; draw a solid border but do not
  3401.                                   ;  clear the center
  3402.  
  3403.  
  3404.  EchoClearScreen
  3405.  ─────────────────────────────────────────────────────────────────────
  3406.  
  3407.  Function     Clears the screen and home cursor.
  3408.  
  3409.  Syntax       ECHOCLEARSCREEN
  3410.  
  3411.  Remark       ECHOCLEARSCREEN clears the screen with the current color
  3412.               and positions cursor to the top-left corner.
  3413.  
  3414.  See also     EchoColor, EchoBkColor
  3415.  
  3416.  
  3417.  
  3418.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    61
  3419.  
  3420.  
  3421.  EchoColor
  3422.  ─────────────────────────────────────────────────────────────────────
  3423.  
  3424.  Function     Sets foreground color.
  3425.  
  3426.  Syntax       ECHOCOLOR color
  3427.  
  3428.  Remark       ECHOCOLOR sets the foreground color to <color> by
  3429.               outputing the corresponding foreground ANSI color code.
  3430.  
  3431.               <color> can be one of the following: BLACK, BLUE,GREEN,
  3432.               CYAN, RED, MAGENTA, YELLOW AND WHITE.
  3433.  
  3434.  See also     EchoBkColor
  3435.  
  3436.  Example
  3437.  
  3438.       EchoColor YELLOW    ; yellow foregound
  3439.  
  3440.       EchoColor BLACK     ; black on white
  3441.       EchoBkColor WHITE
  3442.  
  3443.  
  3444.  EchoGotoXY
  3445.  ─────────────────────────────────────────────────────────────────────
  3446.  
  3447.  Function     Positions cursor.
  3448.  
  3449.  Syntax       ECHOGOTOXY column,row
  3450.  
  3451.  Remark       ECHOGOTOXY moves the cursor to the position
  3452.               (column,row). window. The upper left corner is (0,0) and
  3453.               the lower right corner is (79,24) if a 25 rows terminal
  3454.               is used.
  3455.  
  3456.  
  3457.  EchoHiLite
  3458.  ─────────────────────────────────────────────────────────────────────
  3459.  
  3460.  Function     Sets high intensity.
  3461.  
  3462.  Syntax       ECHOHILITE
  3463.  
  3464.  See also     EchoBlink, EchoNormal, EchoReverse
  3465.  
  3466.  Example
  3467.  
  3468.       EchoColor GREEN     ; green foregound
  3469.       EchoHiLite          ; light green
  3470.  
  3471.  
  3472.  
  3473.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    62
  3474.  
  3475.  
  3476.  EchoNormal
  3477.  ─────────────────────────────────────────────────────────────────────
  3478.  
  3479.  Function     Sets normal intensity and reset color to white on black.
  3480.  
  3481.  Syntax       ECHONORMAL
  3482.  
  3483.  Remark       ECHONORMAL not only set the normal intensity, but also
  3484.               reset the current color to white on black.  There is no
  3485.               ANSI code to turn off high intensity.
  3486.  
  3487.               To turn off high intensity only, three statements must
  3488.               be used.  You should keep track of the <foreground> and
  3489.               <background> color.
  3490.                   EchoNormal
  3491.                   EchoColor   foreground
  3492.                   EchoBkColor background
  3493.  
  3494.  See also     EchoBlink, EchoHiLite, EchoReverse
  3495.  
  3496.  
  3497.  EchoReverse
  3498.  ─────────────────────────────────────────────────────────────────────
  3499.  
  3500.  Function     Sets reverse attribute.
  3501.  
  3502.  Syntax       ECHOREVERSE
  3503.  
  3504.  See also     EchoBlink, EchoHiLite, EchoNormal
  3505.  
  3506.  Example
  3507.  
  3508.       EchoColor YELLOW    ; yellow on blue
  3509.       EchoBkColor BLUE
  3510.       EchoReverse         ; blue on yellow
  3511.  
  3512.  
  3513.  
  3514.  ─────────────────────────────────────────────────────────────────────
  3515.  Toolbox #2
  3516.  ─────────────────────────────────────────────────────────────────────
  3517.  
  3518.  This toolbox defines  three I/O procedures  and four  character-type-
  3519.  checking procedures.
  3520.  
  3521.  To use this toolbox, you should add the line
  3522.     #include "toolbox2.scr"
  3523.  at the beginning of  your script file.   This will increase the  file
  3524.  size of the compiled script  file .TMS by about  2K.  To minimum  the
  3525.  overhead, you should cut and paste the procedures that you used  into
  3526.  your script file.  For  example, the <InputN> and <ReadN>  procedures
  3527.  may be excluded.
  3528.  
  3529.  
  3530.  
  3531.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    63
  3532.  
  3533.  
  3534.  GetN
  3535.  ─────────────────────────────────────────────────────────────────────
  3536.  
  3537.  Function     Gets one or more characters from remote system.
  3538.  
  3539.  Syntax       GETN s,n
  3540.  
  3541.  Remark       GETN gets <n> characters from remote system or until CR
  3542.               (Ctrl M) is encountered.
  3543.  
  3544.               The input characters are displayed on local screen.
  3545.  
  3546.               BackSpace character (Ctrl H) deletes the last character
  3547.               of the inputing string.  You should leave a space before
  3548.               your input prompt.
  3549.  
  3550.               The CLEAR KEY should be issued if you no longer need
  3551.               keyboard input.
  3552.  
  3553.  Return       <s> contains the input string.  If the length of <s> is
  3554.               less than <n>, CR is encountered.
  3555.  
  3556.  See also     Clear COM, Get, GetCh
  3557.  
  3558.  Example
  3559.  
  3560.       put "Press a key to continue"
  3561.       getn enter,1        ; wait for a key or [Enter]
  3562.  
  3563.       ; Note: a space is required here ------------v for backspace
  3564.       put "Enter the filename you want to download: "
  3565.       getn filename,50    ; let it handle backspace
  3566.  
  3567.  
  3568.  InputN
  3569.  ─────────────────────────────────────────────────────────────────────
  3570.  
  3571.  Function     Gets one or more characters from keyboard.
  3572.  
  3573.  Syntax       INPUTN s,n
  3574.  
  3575.  Remark       INPUTN gets <n> characters from keyboard or until
  3576.               [Enter] is pressed.
  3577.  
  3578.               BackSpace character (Ctrl H) deletes the last character
  3579.               of the inputing string.
  3580.  
  3581.  Return       <s> contains the input string.  If the length of <s> is
  3582.               less than <n>, [Enter] is pressed.
  3583.  
  3584.  See also     At, Clear Key, Input, InputCh
  3585.  
  3586.  
  3587.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    64
  3588.  
  3589.  
  3590.  Example
  3591.  
  3592.       print "Press a key to continue"
  3593.       inputn enter,1      ; wait for a key or [Enter]
  3594.  
  3595.       print "Enter the filename you want to display: "
  3596.       inputn filename,50  ; let it handle backspace
  3597.  
  3598.  
  3599.  ReadN
  3600.  ─────────────────────────────────────────────────────────────────────
  3601.  
  3602.  Function     Gets one or more characters from a file.
  3603.  
  3604.  Syntax       READN s,n
  3605.  
  3606.  Remark       READN gets <n> characters from the file or until the CR-
  3607.               LF newline sequence is encountered.  The CR-LF is
  3608.               skipped in the file and discarded in the string.
  3609.  
  3610.               BackSpace character (Ctrl H) DOES NOT delete the last
  3611.               character of the inputing string.
  3612.  
  3613.               This procedure is usually used to get a field from a
  3614.               data file.
  3615.  
  3616.  Return       <s> contains the input string.  If the length of <s> is
  3617.               less than <n>, newline is encountered.
  3618.  
  3619.  See also     Read, ReadCh, Seek, Tell
  3620.  
  3621.  Example
  3622.  
  3623.       open "TM.FON"       ; open the phone directory
  3624.       seek 10*131         ; move to entry #10, each entry is 131 bytes
  3625.       readn name,30       ; read the name field
  3626.       close               ; close the phone directory
  3627.  
  3628.  
  3629.  isalpha
  3630.  ─────────────────────────────────────────────────────────────────────
  3631.  
  3632.  Function     Determines if a character is a letter.
  3633.  
  3634.  Syntax       ISALPHA ch,result
  3635.  
  3636.  Return       If <ch> is a letter, <result> is set to TRUE; otherwise
  3637.               <result> is FALSE.
  3638.  
  3639.  See also     isalnum, iscntl, isdigit
  3640.  
  3641.  
  3642.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    65
  3643.  
  3644.  
  3645.  Example
  3646.  
  3647.       inputn ch,1         ; get one character
  3648.       print
  3649.       isalpha ch,result
  3650.       if result
  3651.          print "yes, it is a letter"
  3652.       else
  3653.          print "no, it is not"
  3654.       endif
  3655.  
  3656.  
  3657.  isalnum
  3658.  ─────────────────────────────────────────────────────────────────────
  3659.  
  3660.  Function     Determines if a character is a letter or a digit.
  3661.  
  3662.  Syntax       ISALNUM ch,result
  3663.  
  3664.  Return       If <ch> is a letter or a digit, <result> is set to TRUE;
  3665.               otherwise <result> is FALSE.
  3666.  
  3667.  See also     isalpha, iscntl, isdigit
  3668.  
  3669.  
  3670.  iscntl
  3671.  ─────────────────────────────────────────────────────────────────────
  3672.  
  3673.  Function     Determines if a character is a control character.
  3674.  
  3675.  Syntax       ISCNTL ch,result
  3676.  
  3677.  Return       If <ch> is a control character (Ctrl-A to Ctrl-Z),
  3678.               <result> is set to TRUE; otherwise <result> is FALSE.
  3679.  
  3680.  See also     isalpha, isalnum, isdigit
  3681.  
  3682.  
  3683.  isdigit
  3684.  ─────────────────────────────────────────────────────────────────────
  3685.  
  3686.  Function     Determines if a character is a digit.
  3687.  
  3688.  Syntax       ISDIGHT ch,result
  3689.  
  3690.  Return       If <ch> is a digit, <result> is set to TRUE; otherwise
  3691.               <result> is FALSE.
  3692.  
  3693.  See also     isalpha, isalnum, iscntl
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    66
  3699.  
  3700.  
  3701.  ─────────────────────────────────────────────────────────────────────
  3702.  Toolbox #3
  3703.  ─────────────────────────────────────────────────────────────────────
  3704.  
  3705.  This toolbox defines several procedures to access the phone directory
  3706.  and two procedures to calculate the difference between two  date/time
  3707.  strings.
  3708.  
  3709.  To use this toolbox, you should add the line
  3710.     #include "toolbox3.scr"
  3711.  at the beginning of  your script file.   This will increase the  file
  3712.  size of the compiled script  file .TMS by about  5K.  To minimum  the
  3713.  overhead, you should cut and paste the procedures that you used  into
  3714.  your script  file.    For  example,  the  <DiffTime>  and  <DiffDate>
  3715.  procedures may be excluded.
  3716.  
  3717.  
  3718.  DiffDate
  3719.  ─────────────────────────────────────────────────────────────────────
  3720.  
  3721.  Function     Computes the difference between two dates.
  3722.  
  3723.  Syntax       DIFFDATE date1,date2,days
  3724.  
  3725.  Remark       DIFFDATE calculates the elapsed days from <date1> to
  3726.               <date2> as if
  3727.                   <days> = <date2> - <date1>
  3728.  
  3729.               <date1> and <date2> must be in MM-DD-YY format.
  3730.  
  3731.  Return       <days> is the elapsed days from <date1> to <date2>.
  3732.               <days> is always a non-negative integer.
  3733.  
  3734.               If <date1> is equal to <date2>, <days> is equal 0.
  3735.  
  3736.               If <date1> is larger than <date2>, it is assumed that
  3737.               <date2> pass a century and 100 years is added to <date2>
  3738.               before the calculation.
  3739.  
  3740.  See also     Date, DiffTime
  3741.  
  3742.  Example
  3743.  
  3744.       DiffDate "02-01-88","02-01-89",days
  3745.       print days          ; 366
  3746.  
  3747.       DiffDate "02-01-91","03-01-91",days
  3748.       print days          ; 28
  3749.  
  3750.       DiffDate "12-31-99","01-01-00",days ; 1999 - 2000
  3751.       print days          ; 1
  3752.  
  3753.  
  3754.  
  3755.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    67
  3756.  
  3757.  
  3758.  DiffTime
  3759.  ─────────────────────────────────────────────────────────────────────
  3760.  
  3761.  Function     Computes the difference between two times.
  3762.  
  3763.  Syntax       DIFFTIME time1,time2,seconds
  3764.  
  3765.  Remark       DIFFTIME calculates the elapsed seconds from <time1> to
  3766.               <time2> as if
  3767.                   <seconds> = <time2> - <time1>
  3768.  
  3769.               <time1> and <time2> must be in HH:MM:SS format.
  3770.  
  3771.  Return       <seconds> is the elapsed seconds from <time1> to
  3772.               <time2>.  <seconds> is always a non-negative integer.
  3773.  
  3774.               If <time1> is equal to <time2>, <seconds> is equal 0.
  3775.  
  3776.               If <time1> is larger than <time2>, it is assumed that
  3777.               <time2> pass midnight and 24 hours is added to <time2>
  3778.               before the calculation.
  3779.  
  3780.  See also     DiffDate, Time
  3781.  
  3782.  Example
  3783.  
  3784.       DiffTime "12:30:40","12:31:30",seconds
  3785.       print seconds       ; 50
  3786.  
  3787.       DiffTime "23:59:50","00:00:01",seconds  ; pass mid-night
  3788.       print seconds       ; 11
  3789.  
  3790.  
  3791.  PhoneDirectory
  3792.  ─────────────────────────────────────────────────────────────────────
  3793.  
  3794.  The <PhoneDirectory>  variable  tells the  Phone's  procedures  which
  3795.  phone directory is to be access.  Default is the "TM.FON".
  3796.  
  3797.  Example
  3798.  
  3799.       PhoneDirectory = "MYPHONE.FON"
  3800.       PhoneFind "South",number,1  ; search the word "South" in
  3801.                                   ; MYPHONE.FON
  3802.  
  3803.  
  3804.  PhoneFind
  3805.  ─────────────────────────────────────────────────────────────────────
  3806.  
  3807.  Function     Finds an entry.
  3808.  
  3809.  Syntax       PHONEFIND name,number,startPoint
  3810.  
  3811.  Remark       PHONEFIND finds an entry by <name> starting from
  3812.               <startPoint>.
  3813.  
  3814.  
  3815.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    68
  3816.  
  3817.  
  3818.  Return       If <name> matches an entry, <number> is set the entry
  3819.               number; otherwise, <number> is 0.
  3820.  
  3821.               <success> is FALSE if the phone directory cannot be
  3822.               open.
  3823.  
  3824.  Caution      This procedure will close the formly opened file since
  3825.               the OPEN command is used.  You should close the file
  3826.               before issuing this procedure and reopen the file after
  3827.               this procedure.
  3828.  
  3829.  See also     PhoneDirectory, PhoneRead, PhoneSize, PhoneWrite
  3830.  
  3831.  Example
  3832.  
  3833.       ; To start from the beginning of the phone directory
  3834.       PhoneFind "South",number,1
  3835.       if not found
  3836.          print "String not found"
  3837.          stop
  3838.       endif
  3839.  
  3840.       PhoneRead number,name,password,link,log,phone,total,last
  3841.       print "...."
  3842.  
  3843.       ; To go on search, supply <startPoint> with the next number
  3844.       PhoneFind "South",number,number+1
  3845.       print "...."
  3846.  
  3847.  
  3848.  PhoneRead
  3849.  ─────────────────────────────────────────────────────────────────────
  3850.  
  3851.  Function     Reads an entry
  3852.  
  3853.  Syntax       PHONEREAD number,name,password,linkscript,logfile,
  3854.                         phone,total,last
  3855.  
  3856.  Remark       PHONEREAD reads the entry # <number> into the variables.
  3857.               <total> is an integer variable.  The others are string
  3858.               variables.
  3859.  
  3860.               You must provide a valid entry <number>.  The size of
  3861.               the phone directory can be obtained by the PHONESIZE
  3862.               procedure.
  3863.  
  3864.  
  3865.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    69
  3866.  
  3867.  
  3868.  Return       <name> is the name field,
  3869.               <password> is the password field,
  3870.               <linkscript> is the script field,
  3871.               <logfile> is the log file field,
  3872.               <phone> is the phone number,
  3873.               <total> is the total number connected, an integer,
  3874.               <last> is the last logon date.
  3875.               Tailing spaces in each variables are discarded.
  3876.  
  3877.               <success> is FALSE if the phone directory cannot be
  3878.               open.
  3879.  
  3880.  Caution      This procedure will close the formly opened file since
  3881.               the OPEN command is used.  You should close the file
  3882.               before issuing this procedure and reopen the file after
  3883.               this procedure.
  3884.  
  3885.  See also     PhoneDirectory, PhoneFind, PhoneSize, PhoneWrite
  3886.  
  3887.  Example
  3888.  
  3889.       PhoneSize size              ; get the size
  3890.       number = 1                  ; start the counter
  3891.       while number <= size        ; display all entries
  3892.          PhoneRead number,name,password,link,log,phone,total,last
  3893.          print "BBS name:",name," phone:",phone," last on:",last
  3894.          number = number + 1      ; next entry
  3895.       endif
  3896.  
  3897.  
  3898.  PhoneSize
  3899.  ─────────────────────────────────────────────────────────────────────
  3900.  
  3901.  Function     Gets the number of entries in a phone directory.
  3902.  
  3903.  Syntax       PHONESIZE size
  3904.  
  3905.  Remark       PHONESIZE calculated the phone directory size by
  3906.                 <size> = <file size of .fon> / 131
  3907.               Each entries is 131 bytes.
  3908.  
  3909.  Return       <success> is FALSE if the phone directory cannot be
  3910.               open.
  3911.  
  3912.  See also     PhoneDirectory, PhoneFind, PhoneRead, PhoneWrite
  3913.  
  3914.  
  3915.  
  3916.  TELEMATE SCRIPT                              TOOLBOX PROCEDURES    70
  3917.  
  3918.  
  3919.  PhoneWrite
  3920.  ─────────────────────────────────────────────────────────────────────
  3921.  
  3922.  Function     Writes an entry
  3923.  
  3924.  Syntax       PHONEWRITE number,name,password,linkscript,logfile,
  3925.                          phone,total,last
  3926.  
  3927.  Remark       PHONEWRITE writes the entry # <number> from the
  3928.               variables.  <total> is an integer variable.  The others
  3929.               are string.
  3930.  
  3931.               <name> is the name field,
  3932.               <password> is the password field,
  3933.               <linkscript> is the script field,
  3934.               <logfile> is the log file field,
  3935.               <phone> is the phone number,
  3936.               <total> is the total number connected, an integer,
  3937.               <last> is the last logon date.
  3938.               Tailing spaces in each variables should have been
  3939.               discarded.
  3940.  
  3941.  Return       <success> is FALSE if the phone directory cannot be
  3942.               open.
  3943.  
  3944.  Caution      This procedure will close the formly opened file since
  3945.               the OPEN command is used.  You should close the file
  3946.               before issuing this procedure and reopen the file after
  3947.               this procedure.
  3948.  
  3949.  See also     PhoneDirectory, PhoneFind, PhoneRead, PhoneSize
  3950.  
  3951.  Example
  3952.  
  3953.       PhoneRead 10,name,password,link,log,phone,total,last
  3954.       total = total+1     ; total is an integer variable
  3955.       date last           ; get today's date
  3956.       PhoneWrite 10,name,password,link,log,phone,total,last
  3957.  
  3958.  
  3959.  TELEMATE SCRIPT                      APPENDIX A: ERROR MESSAGES    71
  3960.  
  3961.  
  3962.  APPENDIX A: ERROR MESSAGES
  3963.  
  3964.  Compiler Error Messages
  3965.  ─────────────────────────────────────────────────────────────────────
  3966.  
  3967.  "'CASE' expected"
  3968.  
  3969.  "Declaration error"
  3970.  
  3971.  A symbol is placed in wrong sequence  the declaration part.  You  may
  3972.  have forgotten the comma between two variables.
  3973.  
  3974.  "'ENDIF' expected"
  3975.  
  3976.  "'ENDPROC' expected"
  3977.  
  3978.  "'ENDSWITCH' expected"
  3979.  
  3980.  "'ENDWHILE' expected"
  3981.  
  3982.  "Identifier expected"
  3983.  
  3984.  An identifier was expected at this point.  You may be trying to use a
  3985.  reserved word as an variable.
  3986.  
  3987.  "Invalid expression"
  3988.  
  3989.  This symbol cannot participate in an  expression in the way it  does.
  3990.  You may have forgotten to write an operator between two operands.
  3991.  
  3992.  "Invalid option"
  3993.  
  3994.  You have  mistyped the  option  or forgotten  the comma  between  the
  3995.  option and the value.
  3996.  
  3997.  "Invalid parameter"
  3998.  
  3999.  Too many or too few parameter in calling a procedure.
  4000.  
  4001.  "Invalid sequence"
  4002.  
  4003.  The symbol cannot at a statement.
  4004.  
  4005.  "Invalid string operation"
  4006.  
  4007.  An arithmetic operator is  applied to string  expression.  To  concat
  4008.  two strings, use the 'ConCat' function.
  4009.  
  4010.  "Misplacing Exit statement"
  4011.  
  4012.  The EXIT can only be  placed in WHILE and  REPEAT loop. You may  have
  4013.  put it outside a loop.
  4014.  
  4015.  
  4016.  TELEMATE SCRIPT                      APPENDIX A: ERROR MESSAGES    72
  4017.  
  4018.  
  4019.  "New line expected"
  4020.  
  4021.  Every statement should be in a line.
  4022.  
  4023.  "Nested too deep"
  4024.  
  4025.  TMScript allows no more than 10 nested procedures.
  4026.  
  4027.  "Number out of range"
  4028.  
  4029.  Integer must within the range from -2147483648 to 2147483647.
  4030.  
  4031.  "Numeric expression expected"
  4032.  
  4033.  The preceding expression must be of integer type.
  4034.  
  4035.  "Program Incomplete - Unexpected end of file"
  4036.  
  4037.  Your source file ends due to  unbalanced begins and ends.  Check  the
  4038.  IF statement, SWITCH statement, WHILE loop, REPEAT loop and procedure
  4039.  definition.
  4040.  
  4041.  "Script file not found"
  4042.  
  4043.  The include script of the #include directive does not exist.  You may
  4044.  have forgotten the ".SCR" extension or not having the include  script
  4045.  in the current directory.
  4046.  
  4047.  "String expression expected"
  4048.  
  4049.  The preceding expression must be of string type.
  4050.  
  4051.  "String incomplete"
  4052.  
  4053.  You have most likely forgotten the ending quote in a string constant.
  4054.  
  4055.  "Syntax error"
  4056.  
  4057.  An illegal character  was found  in the source  file.   You may  have
  4058.  forgotten the quotes around a string constant.
  4059.  
  4060.  "Too many include scripts"
  4061.  
  4062.  TMScript allows no more than 10 nested include file.
  4063.  
  4064.  "Type mismatch"
  4065.  
  4066.  This is due to incompatible types of the variable and the  expression
  4067.  in an assignment statement  or incompatible types  of operands in  an
  4068.  expression.
  4069.  
  4070.  "'UNTIL' expected"
  4071.  
  4072.  
  4073.  TELEMATE SCRIPT                      APPENDIX A: ERROR MESSAGES    73
  4074.  
  4075.  
  4076.  "',' expected"
  4077.  
  4078.  "':' expected"
  4079.  
  4080.  "')' expected"
  4081.  
  4082.  "'=' expected"
  4083.  
  4084.  "'"' expected"
  4085.  
  4086.  
  4087.  Runtime Error Messages
  4088.  ─────────────────────────────────────────────────────────────────────
  4089.  
  4090.  "Division by zero"
  4091.  
  4092.  A number is divided by a expression of zero.
  4093.  
  4094.  "Invalid format in script file"
  4095.  
  4096.  Make sure  the .TMS  file is  a  compiled script  file.   You  should
  4097.  compile the script file using TMS.EXE.
  4098.  
  4099.  "Out of memory"
  4100.  
  4101.  This error  occurs  when TM.EXE  is  run  out of  memory  and  cannot
  4102.  allocate enough memory to the script file.
  4103.  
  4104.  "Stack overflow"
  4105.  
  4106.  This error is  reported on  entry to a  procedure when  there is  not
  4107.  enough stack space to allocate the procedure's local variables.
  4108.  
  4109.  
  4110.  TELEMATE SCRIPT                                           INDEX    74
  4111.  
  4112.      INDEX
  4113.  
  4114.  .SCR file, 1                       Connection, 44
  4115.  .TMS file, 1                       Console I/O, 20
  4116.                                     Control Code, 3
  4117.  A                                  Create, 22, 27
  4118.  
  4119.  AddLineFeed, 44                    D
  4120.  AddReturn, 44
  4121.  Alarm, 24                          Data Type, 3
  4122.  AlarmSound, 44                     Data, 44
  4123.  AlarmTime, 44                      Date, 4, 28
  4124.  ANSI Color Code, 57                Delay, 28
  4125.  Append, 22, 23                     Delete, 22, 28
  4126.  Arithmetic Operators, 8            DestBs, 44
  4127.  ASCII Code, 3                      Dial, 29
  4128.  Assignment, 10                     DialAttempt, 44
  4129.  At, 20, 24                         DialList, 44
  4130.  Atoi, 22, 24                       DialPause, 44
  4131.  AutoWrap, 44                       DialTime, 44
  4132.                                     DiffDate, 66
  4133.  B                                  DiffTime, 67
  4134.                                     Dos, 30
  4135.  Background Color Code, 57          Download, 40
  4136.  Baud, 44
  4137.  Bell, 44                           E
  4138.  Boolean, 4
  4139.  Boolean Operators, 8               Echo, 57
  4140.  Built In Procedures, 20, 23        EchoBkColor, 58
  4141.                                     EchoBlink, 59
  4142.  C                                  EchoBlock, 59
  4143.                                     EchoBox, 60
  4144.  Calling Procedure, 18              EchoClearScreen, 60
  4145.  Capture, 44                        EchoColor, 61
  4146.  Character, 3                       EchoGotoXY, 61
  4147.  CharPace, 44                       EchoHiLite, 61
  4148.  ChDir, 22, 25                      EchoNormal, 62
  4149.  Clear COM, 20, 25                  EchoReverse, 62
  4150.  Clear Key, 20, 25                  EchoInt, 57
  4151.  Clear Text, 20, 26                 EchoToLocal, 57
  4152.  Close, 22, 26                      EchoToRemote, 57
  4153.  Color Code, 56                     Else, 10
  4154.  Color Value, 56                    ElseIf, 11
  4155.  COM I/O, 20                        EndIf, 10
  4156.  ComInCount, 20, 26                 EndSwitch, 11
  4157.  ComOutCount, 20, 26                EndWhile, 11
  4158.  Comment, 10                        Error Messages, 73
  4159.  Comparison, 9                      Exit, 13
  4160.  Compiling Script, 1                ExitTelemate, 32
  4161.  Compiler Error Message, 71         Expand Blank Line, 45
  4162.  Concat, 22, 27                     Expression, 8
  4163.  ConfirmHangUp, 44                  Extend Pacing, 45
  4164.  CONNECTED, 5, 29
  4165.  
  4166.  
  4167.  TELEMATE SCRIPT                                           INDEX    75
  4168.  
  4169.  
  4170.  F                                  M
  4171.  
  4172.  FALSE, 4                           Music, 45
  4173.  File I/O, 22
  4174.  FileExist, 22, 31                  N
  4175.  FileSize, 22, 31
  4176.  Foregound Color Code, 56           Nested Procedures, 18
  4177.  FOUND, 6, 21, 50
  4178.                                     O
  4179.  G
  4180.                                     Open, 22, 37
  4181.  Get, 20, 31                        Otherwise, 11
  4182.  GetCh, 20, 32                      Outgoing, 45
  4183.  GetN, 63
  4184.  GuessFile, 45                      P
  4185.  GuessInitial, 45
  4186.                                     PaceChar, 45
  4187.  H                                  Parity, 45
  4188.                                     Parameter Passing, 18
  4189.  HangUp, 20, 32                     PhoneDirectory, 67
  4190.  Height, 7                          PhoneFind, 67
  4191.                                     PhoneRead, 68
  4192.  I                                  PhoneSize, 69
  4193.                                     PhoneWrite, 70
  4194.  If, 10                             Port, 45
  4195.  Image, 32                          Precedence, 6
  4196.  Incoming, 45                       Predefined Variables, 4
  4197.  Input, 20, 33                      Prefix, 28, 34
  4198.  InputCh, 20, 63                    Print, 16, 25, 33
  4199.  InputN, 63                         Printer, 28, 34
  4200.  Integer, 3                         Procedure Declaration, 15
  4201.  Isalpha, 64                        Procedure, 15
  4202.  Isalnum, 64                        Protocol, 40, 43
  4203.  Iscntl, 64                         Put, 21, 38
  4204.  Isdigit, 65
  4205.  Itoa, 22, 34                       R
  4206.  
  4207.  L                                  Read, 22, 39
  4208.                                     ReadCh, 22, 40
  4209.  Length, 22, 35                     ReadN, 44
  4210.  LinePace, 45                       Receive, 20, 40
  4211.  LoadFon, 35                        Relational Operators, 9
  4212.  LocalEcho, 45                      Repeat, 12
  4213.  Logging, 7, 35, 36                 Return, 18
  4214.  LogOff, 35                         RtsCts, 45
  4215.  LogOn, 36                          Running Script, 1
  4216.  LogPause, 36                       Runtime Error Messages, 73
  4217.  LogResume, 36
  4218.  
  4219.  
  4220.  TELEMATE SCRIPT                                           INDEX    76
  4221.  
  4222.  
  4223.  S                                  U
  4224.  
  4225.  Script, 42                         Until, 12
  4226.  Scope of Variables, 18             Upload, 43
  4227.  Seek, 22, 42                       Usage, 50
  4228.  Send, 20, 43                       UsageLog, 45
  4229.  Set, 44, 45                        Using TMS.EXE, 1
  4230.  Statement, 10
  4231.  Stop, 46                           V
  4232.  StrDel, 22, 46
  4233.  String, 3                          Variable Declaration, 5
  4234.  String Handling, 22
  4235.  StrIns, 22, 47                     W
  4236.  StripHighBit, 45
  4237.  StrPos, 22, 47                     Waitfor, 21, 50
  4238.  StrSet, 22, 48                     WaitUntil, 51
  4239.  SubStr, 22, 48                     When, 21, 52
  4240.  SUCCESS, 6                         WhenIdle, 21, 52
  4241.  Suffix, 45                         WhereX, 20, 53
  4242.  SwapToDisk, 45                     WhereY, 20, 54
  4243.  SwapToEMS, 45                      While, 10, 32
  4244.  Switch, 11                         Width, 7
  4245.                                     Write, 22, 54
  4246.  T
  4247.                                     X
  4248.  Tell, 22, 29
  4249.  Terminal, 45                       XonXoff, 45
  4250.  Time, 4, 49
  4251.  Toolbox Procedures, 56             Z
  4252.  Toolbox #1, 56
  4253.  Toolbox #2, 62                     zASCII, 45
  4254.  Toolbox #3, 66                     zAutoDownload, 45
  4255.  TRUE, 4                            zRecovery, 45
  4256.  
  4257.  
  4258.  
  4259.