Delrina FreeComm 1.0
                           Scripting Manual
                                       
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                   
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
                                     
     
     
            
Delrina FreeComm 1.0
     
  1995, Delrina (Delaware) Corporation. All rights reserved.
  The use and copying of this product is subject to a license agreement. 
  Any other use is prohibited. No part of this publication may be reproduced, 
  transmitted, transcribed, stored in a retrieval system or translated into
  any language in any form by any means without the prior written consent of 
  Delrina (Canada) Corporation.
  Information in this manual is subject to change without notice and does not 
  represent a commitment on the part of the vendor.
     
  Federal copyright law permits you to make a backup of this software for 
  archival purposes only. Any other duplication of this software, including 
  copies offered through sale, loan, rental or gift is a violation of law, 
  and subject to both criminal and civil penalties. Delrina (Canada) 
  Corporation, as a member of the Software Publishers Association (SPA), 
  supports the industry's effort to fight the illegal copying of personal 
  computer software. Report copyright violations to: Software Publishers 
  Association, 1101 Connecticut Avenue, NW, Suite 901, Washington, DC, 
  U.S.A. 20036.
     
  Trademarks
     
  FreeComm is a trademark of Delrina (Wyoming) Limited Liability Company.
  WinComm PRO is a trademark of Delrina (Delaware) Corporation.
  FormFlow, PerForm, WinFax, DosFax, Delrina Fax and Delrina are trademarks 
  of Delrina (Canada) Corporation.
  WinComm is a trademark of Delrina (Delaware) Corporation.
     
  Adobe and PostScript are registered trademarks of Adobe Systems, Inc.
  AT&T is a registered trademark of American Telephone and Telegraph Company
  Compaq is a registered trademark of Compaq Computer Corporation
  CompuServe is a registered trademark of CompuServe, Inc.
  dBASE and Paradox are trademarks of Borland International.
  DEC and VT, registered trademarks of Digital Equipment Corporation
  DESQView, registered trademark of Quarterdeck Office Systems
  Hayes, Smartmodem, and ESP, registered trademarks of Hayes Microcomputer 
  Products, Inc.
  Hewlett-Packard, HP and LaserJet are registered trademarks, and Deskscan II 
  is a copyright, of Hewlett-Packard Company.
  HyperPilot, HyperProtocol, HyperTerminal and HyperGuard are registered 
  trademarks of Hilgraeve Inc.
  IBM, OS/2, PC AT and PC XT are registered trademarks, and DB2 is a 
  trademark, of International Business Machines, Inc.
  Intel and SatisFAXtion are trademarks of Intel Corporation.
  Kermit, developed by Columbia University, is included at no additional 
  charge.
  Microsoft, MS and MS-DOS are registered trademarks, and Windows is a 
  trademark of Microsoft Corporation.
  Oracle and SQL*NET are registered trademarks, and Oracle Server and SQLPLUS 
  are trademarks of Oracle Corp.
  Procomm and Procomm Plus are registered trademarks of Datastorm 
  Technologies, Inc.
  TrueType is a registered trademark of Apple Computer, Inc.
  Type Director and Intellifont are registered trademarks of Agfa Corporation.
  All other product names are copyright, trademarks or tradenames of their 
  respective owners.
      
  
  
  
                                        Delrina (Canada) Corporation 
                            
                                        

                              Contents    
                                   



                                    Chapter 1
                                   ===========

      Editing or Writing Scripts
      
       1.1  Introduction . . . . . . . . . . . . . . . .4
       1.2  An overview of scripts . . . . . . . . . . .4
       1.3  How to develop scripts in general. . . . . .5
       1.4  How to examine, edit, or write a script. . .5
       1.5  What to do when a script keeps stopping. . .6
       1.6  Having a script type for you . . . . . . . .6
       1.7  Keeping in step with a remote system . . . .7
       1.8  Having scripts make decisions. . . . . . . .9
       1.9  Taking alternate courses of action . . . . 10
       1.10 Capturing text and printing with scripts . 10
       1.11 Splicing two learned scripts together. . . 12
       1.12 Transferring files with scripts  . . . . . 13
       1.13 Displaying local prompts or messages . . . 13
       1.14 Prompting for keyboard input . . . . . . . 14
       1.15 String, integer, and flag variables. . . . 15
       1.16 Waiting for less predictable messages. . . 16
       1.17 Comparing and dissecting strings . . . . . 17
       1.18 Building strings . . . . . . . . . . . . . 18
       1.19 Reading text from external files . . . . . 19
       1.20 Writing text into external files . . . . . 20
       1.21 Storing strings in the list. . . . . . . . 21
       1.22 Passing inputs to scripts. . . . . . . . . 21
       1.23 Using an escape key. . . . . . . . . . . . 22
       1.24 Substituting your own error routine. . . . 22
       
  Chapter 2                                          
         HyperPilot Functions. . . . . . . . . . . . . 23
       
                           
                           
                           
                           1.1 Introduction
                          ==================

  In the Delrina FreeComm User's Guide you learn how to create commands and 
  scripts that handle routine, repetitive tasks that arise in communications. 
  In this manual, you learn how to write scripts or edit learned ones, in 
  order to automate many other aspects of communications. Here are some 
  possible applications:
  
  þ    Enhance learned scripts so that they vary their actions depending on 
       events that occur during use
  þ    Make scripts that can execute reliably even when you're not present, 
       such as at night when phone rates are low
  þ    Perform complex, custom functions beyond those provided by the 
       FreeComm menus themselves
  þ    Design your own custom menus to supplement the regular menus, or to 
       eliminate the need to use regular menus
       
  Each script is a separate file that describes a process for Delrina 
  FreeComm(tm) to perform. Scripts consist of word-like functions from 
  the HyperPilot language, so they are relatively easy to read and understand.

  HyperPilot is the ideal tool for automating communications: Its functions 
  can operate FreeComm, type characters to remote systems, wait for remote 
  systems to respond, display prompts you've created, accept keyboard input, 
  send files, receive files, manipulate files on your disks, and much more.
       
  An assortment of scripts is supplied with FreeComm; for a description of 
  them, read the file SCRIPTS.DOC. You can use these scripts as is, edit them 
  to suit your needs, or use them for reference when writing new scripts.
       
  Some of the FreeComm features use scripts. For example, the Call menu runs 
  the CALL script when you place calls, and the Answer menu runs the ANSWER 
  script. 
       
  This manual explains the basic procedures for writing and editing scripts, 
  and tells how to write routines to handle some of the more common needs and 
  gives reference information on the HyperPilot language. This manual in 
  conjunction with the Delrina FreeComm User's Guide will help you maximize 
  the capabilities of FreeComm(tm).
            
                     
                     1.2  An overview of scripts
                    =============================

  To help you decide how HyperPilot can best be applied to your needs, here 
  is a quick overview of how scripts are run, how they are created, and the 
  types of files involved.
       
  You can run scripts in these ways:
  þ    The instant you connect with a system, the logon script you have listed 
       for that system runs.
  þ    You can run a script from anywhere in FreeComm by pressing the key to 
       which it is assigned.
  þ    You can run a script by pressing ALT-R and entering its name, and you 
       can pass inputs to it as well.
  þ    To run a script as you start FreeComm, enter DFC, a space, and the 
       script name. As you do this, you can also pass inputs to the script.
       
  You can create scripts in these ways:
  þ    Learn scripts while logging on to systems.
  þ    Learn scripts by pressing ALT-L and performing the steps you want the 
       script to learn. 
  þ    Write scripts using the Editor.
  þ    Learn scripts and edit them, for increased power and versatility.
       
  
  
  About different kinds of script files:
  þ    Each script is a file whose filename consists of its sequence name, 
       plus an extension showing which type of script file it is.
  þ    Scripts whose filenames have the HP extension (short for HyperPilot) 
       are text files. When you write or edit scripts, this is the kind of 
       script file you work with.
  þ    Scripts whose filenames have the RDY extension (short for ReaDY) are 
       encrypted binary files.
       When you run a script, it is the RDY file which is executed, not the 
       HP file.
  þ    After you learn, write, or edit a script, the resulting HP file is 
       automatically compiled to create a RDY file with the same name, but 
       with the RDY extension.
  þ    After you finish developing a script and FreeComm has created the 
       RDY file, you may remove the HP file to a backup disk; only the RDY 
       file need be present to run the script.
       
                  
                  1.3  How to develop scripts in general
                 ========================================                    

  Here is the general procedure for developing scripts:
  1.   Plan out what the script will do. (It's best to start with less 
       ambitious applications.)
  2.   Familiarize yourself with the task the script will do. You need a 
       clear grasp of each step the task involves, so practice doing manually 
       any parts of the task that can be done by hand.
  3.   Write the script (or learn and edit it).
  4.   Let FreeComm compile the script.
  5.   Fix errors that display when compiling, and compile again.
  6.   Run the script. Check to see that it runs to completion and that it 
       does what you intended.
  7.   Correct errors, compile, and run the script again.
       
  When automating a complex task, it is best to divide it into smaller tasks 
  and write one part at a time. This section gives basic methods you are 
  likely to need and the next gives important reference information. 
       
       
                 1.4  How to examine, edit, or write a script
                ==============================================                           

  To examine, edit, or write a script, load the script into the Editor 
  (or use an external editor). To do this, select "Edit a macro", "command" 
  or "script" from the Keys menu and enter the script name without the 
  extension. If you are creating a new script, you can enter a new name of up 
  to 8 letters. You may find it convenient to copy functions from the list 
  and paste them into your script. 
  
  Note: Don't forget to substitute real arguments.
       
  Follow these guidelines for script construction (syntax):
  þ    Each function is one or two words followed by parentheses.
  þ    After each function are two, one, or no arguments in parentheses. 
       When you use two arguments, separate them with a comma. Even when you 
       use no arguments, include the parentheses.
  þ    Substitute real arguments for the argument descriptions. Descriptions 
       in quotes must be replaced with real arguments in quotes. Arguments 
       in braces ({ and }) are optional and may be omitted. Arguments in 
       uppercase are not to be replaced.
  þ    For easier reading, indent all lines except those containing label 
       names. Scripts are easier to understand if you include blank lines 
       between groups of related lines.
  þ    For clarity and reference, include plenty of comments (text to the 
       right of a semicolon). Comments can be on the same line with functions 
       (they must come after the functions) or on lines by themselves.
  þ    Normally a script ends with the "end()" on a line by itself.
  
  When you exit the Editor after creating or changing a script, you are asked 
  if you want the script compiled. It is generally best to answer "Yes". If 
  you answer "No", the script compiles later, the first time you run it; 
  compiling at run-time causes a delay which may make scripts that perform 
  time-sensitive operations fail the first time you run them.
       
  Note: If "insufficient memory" displays during compiling, you can still 
  compile from outside FreeComm. to do this, Quit FreeComm and at the DOS 
  prompt enter DFCMP <script name>.
       
                   
                   1.5  What to do when a script keeps stopping
                  ==============================================                   
                  
  If a learned (or written) script stops prematurely, this indicates that 
  one of its lines was unable to complete its task. (When this happens, 
  press ENTER and resume manual control; if you haven't pressed ENTER after
  60 seconds, the Comm screen "Hang-up" option is selected automatically to 
  prevent your PC from remaining on-line indefinitely.) A script may stop 
  occasionally if line noise obscures essential prompts, but if it stops
  consistently at the same point, you need to correct that line or lines 
  before it.
       
  To examine the line, load the HP file into the Editor, press ALT-O, select 
  "Jump" and "Line-number", and then enter the line number. You may be able 
  to tell what's wrong at a glance. If it's not obvious, reading more of this
  chapter should give you additional insight.
       
  When learned scripts stop, the problem may stem from the fact that learning 
  assumes that tasks are repetitive that the system prompts are the same 
  every time. If an expected prompt never occurs in a subsequent call, the
  script stops at the line which waits for that prompt. By editing the script, 
  you can make it cope with prompts that vary, or make it take alternate 
  steps in response to varying prompts. See the end of Section 1.7 for some
  possible solutions.
       
       
                      1.6   Having a script type for you
                     ====================================                
                     
  One of the most common needs is to have scripts "type" things for you such 
  as passwords, user IDs or remote system commands. Though you may never have 
  thought of this as a two step process, it truly is. The first step (which 
  is instinctive in manual communications) is to wait for an indication that 
  you should begin typing an indication such as a prompt from the remote 
  system. In a script you must include a function that waits for such
  an indication before executing a function which types. Here's a script 
  excerpt which demonstrates this:
  
         wait prompt("Enter your password:")
         type("hedgehog<ENTER>")
       
  The first line waits for "Enter your password:" and the second types 
  "hedgehog" and ENTER.
       
  If the prompt has arrived *before* the script starts, it's fine for a 
  script to begin with "type", but any subsequent line that uses "type" to 
  send responses to the remote system must generally be preceded by "wait 
  prompt" (or by other functions that begin with "wait").
       
  This excerpt also demonstrates that optional arguments can be omitted: While 
  the general form of "wait prompt" is "wait prompt("string"{,timeout})", 
  no "timeout" was included here. When you omit an optional argument, a 
  generally applicable default value is assumed. For details on specific 
  functions and their arguments, see the next chapter.
       
  
  Using wait prompt
  ~~~~~~~~~~~~~~~~~     
  For "wait prompt" to succeed, its "string" argument must precisely match 
  what you're receiving. This requires care on your part. For example, 
  waiting for "Enter password:" will not do, when what you really receive is
  "Enter your password:". If the system sends a prompt which ends with a 
  space, you must wait for the space as well. Since long strings stand a 
  greater chance of being corrupted by line noise, it's best to wait only 
  for the last several characters of any prompt. For example, waiting for 
  "word:" proves more reliable than waiting for "Enter your password:".
       
  When a prompt contains an unpredictable character, you can include ? as a 
  wildcard. For example, to wait for a prompt containing the current date in 
  the format MM-DD-YY, you could use ??-??-??. (To wait literally for ?, 
  you must first use "setting("wildcard")" to define a different character 
  as the wildcard character.)
       
  You can also wait for control characters. For example, to wait for a > 
  prompt which appears at the beginning of a line, it is best to wait for 
  /x0D/x0A>. The /x indicates that the following number is the hex value of 
  an ASCII character. Thus, /x0D/x0A> represents a carriage return and line 
  feed followed by >. Waiting for this sequence permits your script to 
  distinguish the > prompt from a > which occurs within received text.
       

  Using type
  ~~~~~~~~~~     
  The excerpt above also shows that "type" can be used to send characters 
  (hedgehog) or keys (<ENTER>). To send keys, you must enclose the key name 
  within < and >. (To send the characters < and >, use /> and /<.)
       
  The full form of the function is "type("keys"{,delay})", where the second 
  argument is optional. When you leave out the second argument, a default 
  value of 50 milliseconds is used, to simulate manual typing speed. To make
  your scripts faster, you can try using progressively smaller arguments. 
  When the remote system begins to lose characters, you've gone too far.
       
  You can issue keys that operate FreeComm menus as well. For example, 
  "type("<ALT-M>DM<ENTER>R1200<ENTER><ALT-C>")" displays the Main menu, 
  selects "Define system settings" and "Modify", accepts the proposed system, 
  selects "Rate", sets the baud rate to 1200, and returns to the Comm screen. 
  (Equivalent functions sometimes exist; for example, "setting("BAUD",1200)" 
  has the same effect.)
       
  Whenever you use type to issue keys that bring up a FreeComm menu, be sure 
  to end with <ALT-C>, to return to the Comm screen so the script can execute 
  subsequent lines. If type appears in one or more successive lines, only the 
  last need end with <ALT-C>. When you want a script to end on a menu, omit 
  <ALT-C> and include end() on the next line after the type function.
       
       
                      1.7  Keeping in step with a remote system
                     ===========================================           
                          
  Scripts are most often used to interact with remote systems, and to do this, 
  scripts must coordinate their actions with the remote system. Section 1.6 
  introduced the most common technique: Wait for a prompt with "wait prompt" 
  and send a response using "type". But there are times when a script may 
  need to wait for other kinds of events. Here are the functions you can use 
  for this:
  
  wait prompt("string"{,timeout})
  
  This waits for a specific string of displayed text and/or undisplayed 
  characters followed by a pause, as described in Section 1.6.
  
  
  wait text("string"{,timeout})
  
  This waits for a specific string of displayed text only, disregarding any 
  undisplayed screen control codes, escape sequences or character attributes 
  that may be intermingled with the text. This tends to be easier to use 
  than "wait prompt", which requires that you include every received 
  character, even those you cannot see.
  
  
  wait characters("string"{,timeout})
  
  This waits for a specific string of displayed and/or undisplayed characters, 
  but unlike "wait prompt", does not require that the string be followed by a 
  pause. This is used to wait for characters which may be followed immediately 
  by other characters.
  
  
  wait lines(lines{,timeout})
  
  Use this to wait for the screen to scroll (or for the cursor to move down or 
  up) the number of lines you specify.
  
  
  wait activity({timeout})
  
  Use this to wait for activity on your connection, that is, to wait for the 
  end of a period during which the remote system sends nothing to you.
  
  
  wait lull({timeout})
  
  Use this to wait for a lull on your connection, that is, to wait for the end 
  of a period during which the remote system sends text to you continuously. 
  For example, when a remote system is sending information to you, you might 
  use "wait lull" to wait for it to finish. (If the information ends with 
  known characters, it would be better to wait for those characters using 
  "wait prompt instead)".
  
  
  wait seconds(seconds)
  
  This merely waits a specific length of time. It should be used only when no 
  other functions in this section apply; using time alone as a means of 
  keeping in step with a remote system is inefficient at best. Response times 
  of remote systems vary and to be sure your script doesn't get ahead of the 
  remote system, you must wait at least as long as the longest delay the 
  remote system may exhibit.
  
  
  wait tenths(tenths)
  
  This the same as "wait seconds" except that it waits tenths of seconds. Use 
  it where waiting for more than one second seems excessive.
       
  Information received while a script is running is put in a buffer prior to 
  being displayed on the Comm screen. Each time a function whose name begins 
  with "wait" is executed, information is allowed to flow from the buffer
  onto your screen until that "wait" function detects the occurrence it was 
  waiting for. If you want to let the entire contents of the buffer flow onto 
  your screen without checking it for any specific occurrence, use "wait 
  seconds."
       
  The optional "timeout" argument in the above functions specifies how long 
  each function waits for the occurrence it is intended to detect. The default 
  value is 30 seconds. In Section 1.8, you'll learn what happens when a 
  function "times out."
       
  
  Substituting functions into learned scripts
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~     
  Since learning cannot possibly tell non-recurring system prompts from 
  recurring ones, a learned script may occasionally contain a "wait prompt" 
  for a string which doesn't occur in subsequent calls. Each time that "wait
  prompt" is encountered, the script stops. To solve this, try to identify 
  some event or some facet of remote system behavior that does occur at that 
  point in every call, and substitute a function that waits for it. For
  example, if the system sends text which varies but that always contains the 
  same number of lines, you could substitute "wait lines". If the remote 
  system sends an amount of text which varies and then pauses, you could use
  "wait lull". If all else fails, try "wait seconds". If it is necessary to 
  type different characters from one call to the next, however, you must use 
  techniques from the following sections.
       
       
                   1.8  Having scripts make decisions
                  ====================================                   
                  
  To have a script make decisions, you use functions that produce a TRUE or 
  FALSE in conditional statements, which cause the script to take alternate 
  courses of action. This chapter discusses only simple, single-line 
  statements; see the descriptions of "if" and "ifnot" in Chapter 2 for more 
  complex, powerful block statements. Single-line conditional statements have 
  the following general forms:
       
       if function1 then function2 else function3
       ifnot function1 then function2 else function3
       
  Function1 must be a function with a TRUE/FALSE result. The meaning of this 
  result depends on the function. For example, "wait prompt" gives a TRUE or 
  FALSE to indicate whether a prompt arrives within a given time, while 
  "equal" gives a TRUE only if two numbers are equal.
       
  Conditional statements work just the way they read. In the if statement, 
  if function1 is true function2 executes; if function1 is false function3 
  executes. In the ifnot statement, if function1 is false function2 executes; 
  if function1 is true function3 executes.
       
  Certain parts of the statements are optional. If you like, you can omit 
  else function3, or omit the word "then". Omitting both reduces conditional 
  statements to their simplest form "if" function1 function2 and "ifnot" 
  function1 function2 the form used most often in examples throughout this 
  chapter. The following examples use the "wait prompt" function to 
  illustrate how conditional statements of this type work.
       
        if wait prompt("word:",10) type("turnip<ENTER>")
       
  If "wait prompt" receives "word:" (the end of the prompt "Enter your 
  password:)" within 10 seconds, "type" executes, sending "turnip". If the 
  "word:" failed to arrive in time, "type" would not be executed. Here's a 
  more useful example:
       
         ifnot wait prompt("word:",10) end()
         type("turnip<ENTER>")
       
  If "word:" were not received within 10 seconds, "end()" would execute, 
  terminating the script. If "word:" does arrive in time, the next line would 
  send "turnip", and the script would continue.
       
  Functions that produce TRUE/FALSE results do so even when not preceded by 
  "if" or "ifnot". When you use such functions on a line by themselves (or as 
  function2 or function3 in single-line "if-then-else" statements), the 
  TRUE/FALSE result provides a simple form of error detection. If it is TRUE, 
  the script continues unaffected. If it is FALSE (indicating that the 
  function was unable to perform its operation), the script stops and 
  displays the line number. You can have scripts trap such errors and 
  continue running by including an error routine as described in Section 1.24.
       
        
                1.9  Taking alternate courses of action
               =========================================                      
               
  The previous section showed how to construct conditional statements that 
  either execute or skip executing a given function. By extending this 
  technique, you can make a script execute or not execute a series of lines. 
  The simplest way to do this is to use "goto" labelname as the second 
  function in a conditional statement.
       
  When "goto" executes, it makes a script jump (or branch) to a script line 
  that contains a specific labelname. For example, executing "goto apple" 
  jumps to a script line that contains "apple:". To illustrate this, here's a 
  script that takes an alternate course when there is mail to be captured, but 
  that simply hangs up when there's no mail:
       
         
       if wait characters("You have mail") goto Mail
         wait prompt("and: ")        ;waits for the "Command: " prompt
         type("quit<ENTER>")         ;sends the system's logoff command
         hangup()                    ;makes your modem disconnect
         end()
       
       Mail:
         wait prompt("and: ")        ;waits for the "Command: " prompt
         capture begin("MAIL.TXT")   ;makes your PC capture mail
         type("send mail<ENTER>")    ;this makes the system send mail
         wait characters("mail")     ;waits for "No more mail"
         capture end()               ;stops capturing mail
         wait prompt("and: ")        ;waits for the "Command: " prompt
         type("quit<ENTER>")         ;sends the system's logoff command
         hangup()                    ;makes your modem disconnect
         end()
       
  There are many ways to use branching. For example, by re-arranging the above 
  script, the same task can be accomplished with fewer lines:
       
         ifnot wait characters("You have mail") goto NoMail
         wait prompt("and: ")        ;waits for the "Command: " prompt 
         capture begin("MAIL.TXT")   ;makes your PC capture mail
         type("send mail<ENTER>")    ;this makes the system send mail
         wait characters("mail       ;waits for "No more mail"
         capture end()               ;stops capturing mail
       
       NoMail:
         wait prompt("and: ")        ;waits for the "Command: " prompt 
         type("quit<ENTER>")         ;sends the system's logoff command
         hangup()                    ;makes your modem disconnect
         end()
       
  Experienced programmers often prefer using "gosub", or block structures 
  (if-then-else or while) rather than goto statements. For descriptions of 
  these functions, see Chapter 2.
       
            
            1.10      Capturing text and printing with scripts
           ====================================================                          
           
  If you routinely capture and/or print text from a system, you could save 
  time by having a script do it instead. The previous section showed how to 
  use :capture begin", "type", "wait characters", and "capture end" to 
  accomplish this. However, that approach has an unintended side-effect: It 
  also captures the command you use to tell the remote system to display the 
  text, and the message that the remote system sends to let you know the text 
  has ended. This approach captures only the desired text:
       
         ifnot wait characters("You have mail") goto Done
         wait prompt("and: ")          ;waits for the "Command: " prompt
         type("send mail<ENTER>")      ;this makes the system send mail
         wait echo("send mail")        ;waits for "send mail" to echo
         capture begin("MAIL.TXT")     ;makes your PC capture mail
         wait capture("No more mail")  ;see explanation below
       
       Done:
         wait prompt("and: ")          ;waits for "Command: "
         type("quit<ENTER>")           ;sends the system's logoff command
         hangup()                      ;makes your modem disconnect
         end()
       
  To avoid capturing the system command "send mail", this uses "wait echo" to 
  let the command display, prior to executing "capture begin". Then wait 
  capture waits for the message "No more mail;" this function stops capturing 
  when the message arrives, without putting the message into the capture file. 
  The end result: The capture file contains only mail, free from extraneous 
  commands or messages.
       
  To begin printing, use "print begin" and to stop, use "print end". (Before 
  running a script that prints, be sure your printer is on.) The following 
  example prints mail in addition to capturing it:
       
         ifnot wait character("You have mail") goto Done
         wait prompt("and: ")          ;waits for "Command: "
         type("send mail<ENTER>")      ;this makes the system send mail
         wait echo("send mail")        ;waits for "send mail" to echo
         print begin()                 ;prints subsequently received text
         capture begin("MAIL.TXT")     ;captures subsequent text
         wait capture("No more mail")  ;stops capturing
         print end()                   ;stops printing after No more mail
       
       Done:
         wait prompt("and: ")        ;waits for "Command: "
         type("quit<ENTER>")         ;sends the system's logoff command
         hangup()                    ;makes your modem disconnect
         end()
       
  To print strings, use print("string"{,add line feed?}). For example, you 
  can use this to time- and date-stamp a printout or to insert comments into 
  printouts, as follows:
  
         ifnot wait characters("You have mail") goto NoMail
         print("Arrived //TIME, //DATE")  ;prints time and date
         wait prompt("and: ")             ;waits for "Command: "
         type("send mail<ENTER>")         ;this makes the system send mail
         wait echo("send mail")           ;lets echo of "send mail" appear
         print begin()                    ;prints subsequently received text
         capture begin("MAIL.TXT")        ;prepares your PC to capture mail
         wait capture("No more mail")     ;stops capturing
         print end()                      ;this stops printing
         goto Done
       
  
       NoMail:
         print("No mail, //TIME, //DATE") ;records there was no mail
       Done:
         wait prompt("and: ")             ;waits for "Command: "
         type("quit<ENTER>")              ;sends the system's logoff command
         hangup()                         ;makes your modem disconnect
         end()
       
  You can also use print for debugging purposes: By sprinkling print 
  statements throughout a script, you can have it print status messages to 
  help you track down programming errors.
       
       
              1.11  Splicing two learned scripts together
             =============================================                        
             
  One way to create a script which takes either of two courses of action is 
  to learn two separate scripts and "splice" them together. The following 
  example shows this in connection with an electronic mail service:
       
  Prior to splicing the scripts together, you need to learn them. To learn 
  the first one, you connect with the service and after it displays a message 
  that there is no mail, you start learning and perform the steps necessary 
  to disconnect from the system. You name the script NOMAIL. It looks like 
  this:
  
         type("quit<ENTER>")
         wait prompt("in/x0D/x0A")
         type("<ALT-O>h")
         end()
  
  (The first line enters "quit" to log off the system; the second line waits 
  for "Please call again", and the third selects the Comm screen option 
  Hang-up.)
       
  In a later call, when the system displays a message that there is mail, you 
  start learning and perform the steps necessary to capture the mail. You name 
  this script MAIL. It looks like this:
  
         type("<ALT-OcbMAIL.TXT<ENTER>asend mail<ENTER>")
         wait prompt("and: ")
         type("<ALT-O>cequit<ENTER>")
         wait prompt("in/x0D/x0A")
         type("<ALT-O>h")
         end()
  
  (The first line selects "Capture" and "Begin", enters a filename, selects 
  "Append", and enters "send mail" to make the remote system begin sending 
  mail; the second waits for "Command: " to display (which indicates that the
  mail has ended); the third selects "Capture", "End", and enters "quit".)
       
  There are several ways to splice scripts together. One is to combine them 
  into a single file and add a conditional statement that determines which of 
  the two series of lines will be executed. Another is to create a third 
  script containing a couple of conditional statements that decide which of 
  the other scripts should be run:
  
        if screen match("no mail") then run("NOMAIL") else run("MAIL")
        end()
       
  You could run this script each time you call, by starting it after the 
  message "You have no mail" either does or does not display. ("screen" match 
  scans the screen and produces a TRUE only if the message is present.) It
  would be more convenient, however, to add the above lines to your logon 
  script, so the entire call would be automated. The final result might look 
  like this:
  
        wait prompt("rd: ")          ;waits for "Enter your password:"
        type("banana<ENTER>")        ;sends your password
        wait prompt("and: ")         ;waits for "Command: " prompt
        if screen match("no mail") then run("NOMAIL") else run("MAIL")
        end()
       
                 1.12 Transferring files with scripts
                ======================================                     
                
  If you often transfer files with a system, perhaps you could save time by 
  having a script do it for you. The functions used to accomplish this in a 
  script largely parallel the steps you perform when manually transferring
  files.
       
  Here is an excerpt from a script that receives a file; the remote system is 
  a PC which has FreeComm and is in Answer mode:
  
         wait prompt("C:\DFC>")              ;waits for that PC's > prompt
         type("HSEND STOCK.QTS<ENTER>")      ;makes that PC send a file
         wait characters("send")             ;waits for "Ready to send"
         transfer receive("QUOTE.STK","H")   ;makes your PC receive
         type("done<ENTER>")                 ;sends the logoff command
         end()
       
  Here is another script excerpt that sends a file to a PC which has FreeComm 
  and is in Answer mode:
  
         wait prompt("C:\DFC>")            ;waits for that PC's > prompt
         type("HREC DATABASE.FIL<ENTER>")  ;makes that PC receive
         wait characters("eive")           ;waits for "Ready to receive"
         transfer send("YEAREND.INV","H")  ;makes your PC send
         type("done<ENTER>")               ;sends the logoff command
         end()
       
  To transfer files with a remote computer that is not running FreeComm, 
  naturally your script must type commands other than HSEND and HREC, and 
  must wait for prompts other than "Ready to send" or "Ready to receive".
       
  Both "transfer send" and "transfer receive" give a TRUE result if the 
  transfer succeeds and a FALSE if it fails (say, due to loss of connection 
  or excessive line noise). By including "transfer send" and "transfer 
  receive" in conditional statements, you can sense when this occurs and take 
  an alternate course of action.
       
       
                 1.13  Displaying local prompts or messages
                ============================================                     
                
  It is often convenient to have a script display prompts or messages on the 
  screen which are not sent to the remote system. You can use such messages 
  to provide information or instructions to the person running the script. 
  Here's a simple example:
       
         prompt("/nStand by while this script picks up your mail./n")
       
  This moves the cursor to a new line (/n), displays the string, then moves 
  the cursor to the line below. The following lines display the same prompt 
  in reverse video, to set it apart from other text which displays on the
  Comm screen:
       
         option("RVIDEO",yes)   ;turns on reverse video
         prompt("/nStand by while this script picks up your mail./n")
         option("RVIDEO",no)    ;turns off reverse video
       
  The lines below display the same prompt for 5 seconds, then restore any 
  text which the prompt might have overwritten:
       
         save screen(1,80) ;saves text from line where cursor is
         option("RVIDEO",yes)   ;turns on reverse video
         prompt("Stand by while this script picks up your mail./x0D")
         option("RVIDEO",no)    ;turns off reverse video
         pause(5)               ;pauses 5 seconds
         restore screen()       ;re-displays text saved above
       
  This stores an area of text 1 row high by 80 columns wide, extending to the 
  right of the cursor, changes to reverse video, displays the prompt, turns 
  off reverse video, and re-displays the stored text. (The /x0D at the end of 
  the prompt is a carriage return, which moves the cursor back to the 
  beginning of the line.)
       
  These lines display the message in a box for 5 seconds, then redisplay the 
  text that was overwritten by the box. 
       
         cursor save()          ;saves current cursor position
         position(12,11)        ;puts cursor at row 12, column 11
         save screen(3,55) ;saves 3 lines x 55 columns of text
         draw box(3,55)         ;displays an empty box
         position(13,12)        ;positions the cursor inside the box
         prompt("Stand by while this script picks up your mail.")
         pause(5)               ;pauses 5 seconds
         restore screen()       ;re-displays text saved above
         cursor restore()       ;restores cursor to original location
       
  This puts the cursor at row 12, column 11, saves text from a 3-line by 
  55-column area to the lower right of the cursor, draws a box using line 
  graphics characters, puts the cursor in its upper left-hand corner, displays 
  the prompt for 5 seconds, re-displays the saved text, and puts the cursor 
  back where it was.
       
       
                   1.14  Prompting for keyboard input
                  ====================================                   

  You can have a script ask the person who is running it to enter information, 
  selections, or other input for subsequent use by the script. Here's an 
  example of how a script can accept and use a yes or no response:
       
         key flag(F(1),"/nWant to remain connected? (Enter Y or N): ")
         if flag(F(1)) goto StayOn   ;branches to StayOn if Yes
         hangup()                    ;disconnects from remote system
         end()
       
  StayOn:
  
  This displays "Want to remain connected? (Enter Y or N):" and waits for the 
  user to enter Y, y, YES, Yes or yes (which sets F(1) to TRUE) or N, n, NO, 
  No or no (which sets F(1) to FALSE). (F(1) is a flag variable which can 
  have a TRUE or FALSE value; variables are discussed in Section 1.15.) The 
  conditional statement above hangs up only if F(1) is FALSE.
       
  Here's how you might prompt the operator to enter an integer value:
       
         key integer(I(3),"How many pieces of mail are to be sent: ")
         if greater(I(3),0) goto SendMail  ;if there's mail, go send it
         hangup()                          ;disconnects from system
         end()
       
  SendMail:
       
  The integer that the user enters in response to this prompt is stored in 
  the integer variable I(3). In the subsequent conditional statement, if I(3) 
  is greater than 0, the script branches to SendMail (which might be followed 
  by lines that send mail, making further use of the value in I(3)). If I(3) 
  is 0, the script merely disconnects from the system and ends.
       
  
  To allow the user to enter a string, you can use this approach:
       
         key string(S(8),"/nEnter the DOS command to execute: ")
         memory execute("/S(8)")     ;executes the DOS command
         end()
       
  This displays "Enter the DOS command to execute:", stores the string the 
  user enters in string variable S(8), then executes the string at the DOS 
  command prompt, leaving FreeComm in memory. (The significance of /S(8) is 
  covered in following sections.) FreeComm resumes running when the DOS 
  command completes.
       
  To display a string and permit the user to edit it, you use this procedure:
       
         set string(S(5),"Ted Waldecker")  ;defines string variable
         prompt("/nEdit addressee's name or press ENTER to accept: ")
         key edit(S(5),20)                 ;allows user to edit or accept name
       
  This example first sets string variable S(5) to Ted Waldecker (a person to 
  whom the user often sends mail). Next, it displays "Edit addressee's name 
  or press ENTER to accept:". Then "key edit" displays the string stored in 
  S(5) and places the cursor at its beginning; the user can accept the 
  current string by pressing ENTER, edit it using DEL, BACKSPACE, INS, Left 
  Arrow or Right Arrow, or replace it by typing up to 20 new characters. The 
  final string is stored back into S(5). For more information on these and 
  other "key functions" (for accepting other kinds of keyboard input), see 
  Chapter 2.
       
                
                1.15  String, integer, and flag variables
               ===========================================                      
               
  The previous section showed techniques for accepting information from a 
  user during execution of a script information which for obvious reasons 
  could not be pre-programmed into a script. Information that can't be
  pre-programmed but that may be essential to a script can be gleaned from 
  other sources as well from disk directories, ASCII files or the Comm screen 
  itself. To store and use variable information such as this, you use string, 
  integer, and flag variables.
       
  
  String variables
  ~~~~~~~~~~~~~~~~     
  
  For storing text, ASCII characters or non-ASCII characters, you can always 
  use string variables S(0) through S(9), or variable names as described 
  below.
       
  
  Integer variables
  ~~~~~~~~~~~~~~~~~     
  
  For storing integer variables having values from -2,147,483,648 to 
  +2,147,483,648, use integer variables I(0) through I(9), or variable names 
  as described below.
       
  
  Flag variables
  ~~~~~~~~~~~~~~     
  
  For storing flags which can have a TRUE or FALSE value use flag variables 
  F(0) through F(9), or variable names as described below.
       
  
  Using descriptive variable names instead of S(N), I(N), and F(N)
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~     
  
  Scripts are easier to understand if instead of S(N), I(N), and F(N) you use 
  descriptive variable names, which can be any string of alphanumeric 
  characters without spaces or punctuation. It is best to begin names with 
  capital letters, to distinguish them from functions; when variable names 
  contain more than one word, capitalize the first letter of each, and use 
  no spaces between.
       
  Prior to the point where a variable name is first used in a script, you 
  must include a "declare" statement which sets whether it is a string, 
  integer, or flag, and establishes its name so the compiler can catch 
  misspellings or other errors. (S(0)-S(9), I(0)-I(9), and F(0)-F(9) require 
  no "declare" statements.) The following statements might be used to declare 
  certain variable names:
       
         declare string SystemName, ModemType, Directory
         declare integer NumberOfCalls, FileCount
         declare flag MadeConnection, LostConnection, SentFiles
       
       
               1.16  Waiting for less predictable messages
              =============================================                       
              
  Earlier sections described how to wait for specific prompts or messages. 
  But when you need to wait for *any of several messages*, or for messages 
  that vary so much that "wait prompt" or "wait characters" cannot be used, 
  try these approaches:
  
  þ    Allow the message to display on the Comm screen, then scan back over 
       the Comm screen to examine the message.
  þ    Trap the message into a string variable as the message arrives, and 
       then examine the contents of the string variable.
       
  In either case, since you cannot wait for the message of interest directly, 
  you must wait for some predictable occurrence just before or after the 
  message. The following examples help clarify this.
       
  Suppose a system displays a message from which your script must determine 
  how many pieces of mail to pick up, such as "You have no pieces of mail" or 
  "You have 2 pieces of mail". You can trap this message by using "wait 
  text("mail")"; a singular feature of "wait text" is that, when it receives 
  text for which it is waiting, it puts it and any text that precedes it on 
  that line, into string variable S(9). After that, you can examine the 
  contents of S(9) using methods described in Section 1.17.
       
  With a service that might display either Number of messages for you = 0 or 
  Number of messages for you = 3, you could use wait text("you = ?"). The 
  question mark acts as a wildcard for any character that may display. As in 
  the previous paragraph, this puts the string which contains this pattern 
  into string variable S(9), so it can be examined as described in Section 
  1.17.
       
  Letting messages display and then scanning back over them with "screen 
  match("pattern"{,number of lines})" is a more versatile approach. Beginning 
  where the cursor is, "screen match" scans up the screen for the first line 
  containing the specified string. If it finds such a line, it puts that 
  entire line into string variable S(9). This can be applied in several ways. 
  For example, with a system that may display...
  
       
       Welcome to XYZ Electronic Mail Service
       There is no mail for you
       Enter command:
       
  or may display
       
       Welcome to XYZ Electronic Mail Service
       Number of messages for you = 2
       Enter command:
       
  ...you could use the following script lines to determine whether there is 
  mail and how much mail exists:
       
         wait prompt("and: ")  ;waits for the prompt "Command: "
         screen match("you")   ;puts the line containing "you" in S(9)
       
  Here, "wait prompt" allows all three lines from the remote system to 
  display, and "screen match" scans back over the lines, putting the one that 
  contains "you" into string variable S(9). Methods from Section 1.17 could
  then be used to evaluate contents of S(9).
       

  Waiting for any of several events
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~     
  
  When you need to wait simultaneously for any of several possible events--say, 
  for certain prompts, a number of lines, or a lull in received data--try the 
  "watch" function, described in Chapter 2. Also see "while", which together 
  with "watch" can be used to wait repeatedly for certain recurring events.
       
           
               1.17  Comparing and dissecting strings
              ========================================                       
              
  Scripts whose actions hinge on information (numbers, words, or phrases) 
  collected during use, often must glean this information from strings which 
  contain unimportant information as well. Once the strings are stored in 
  string variables (as discussed in previous sections) you easily can extract 
  the desired information with these techniques:
       
  
  Getting an integer from a string variable
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~     
  
  To extract a number from a string, you use the function "get integer(integer 
  variable,"string")". Suppose, for example, there's a string in S(9) from 
  which you need to extract a number, and you want to store that number in the 
  integer variable in I(4); for this, you would use "get integer(I(4),"/S(9)")". 
  If S(9) happens to contain "You have 6 pieces of mail", this would put 6 
  into I(4). If S(9) were to contain "You have no pieces of mail", then
  "get integer" would give a FALSE result, so you may want to put "get 
  integer" into a conditional statement such as "if get integer(I(4),"/S(9)") 
  goto Mail. The next chapter gives more information on "get integer".
       
  
  Checking a string for a pattern of characters
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  To determine if a string contains a certain pattern of characters, use 
  "string match(string variable,"pattern")". For example, these lines ask a 
  user which operation he wants to perform:
       
         declare string UserKeys
       SendOrReceive:
         key string(UserKeys,"/nEnter SEND or REC: ")
         if string match(UserKeys,"SEND") goto Send   ;jump to send
         if string match(UserKeys,"REC") goto Receive ;jump to receive
         prompt("/nYou must enter SEND or REC. Please try again.")
         goto SendOrReceive
       
  
  
  The "string match" function produces a true if the specified pattern exists 
  *anywhere* in the string variable "UserKeys". For example, the above routine 
  would branch to the "Receive" label even if the user were to enter RECEIVE 
  (instead of entering just REC, as he was told to do).
       
  
  Eliminating case-sensitivity
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~     
  
  Case sensitivity:in scripts;String matching functions normally are case-
  sensitive. For example, if "string match" were used to check for the pattern 
  REC in a string variable which contains receive, it would not find a match.
  The following lines show how to use "option("IGNORE CASE",yes)" to make 
  string matching functions disregard case:
         
         declare string UserKeys
       SendOrReceive:
         key string(UserKeys,"/nEnter SEND or REC: ")
         option("IGNORE CASE",yes)                    ;begin ignoring case
         if string match(UserKeys,"SEND") goto Send   ;jump to send
         if string match(UserKeys,"REC") goto Receive ;jump to receive
         prompt("/nYou must enter SEND or REC. Please try again.")
         goto SendOrReceive
       
  The routine above would accept user entries send, Send, SEND, rec, Rec, or 
  REC.
       
  
  Keeping only the right-hand portion of a string
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

  To retain only the right-hand portion of a string, use "cut" or "right". 
  For example, if S(6) contains a filename from which you need to remove the 
  path, you could use this routine:
       
       CutFirstCharacter:
         if cut(DataFile,"\") goto CutFirstCharacter
       
  If the string variable DataFile holds C:\DATABASE\JUNE.DAT, cut would remove 
  C:\, give a TRUE result, and branch back. When cut executes next, it would 
  remove DATABASE\, and branch again. When cut executes again, it would find 
  no \ (since DataFile now contains only JUNE.DAT) and give a FALSE, which
  would cause execution to continue on the next line.
       
  The right function is used less often. It retains a fixed number of 
  characters from the right-hand end of a string and discards the rest.
       
  Keeping only the left-hand portion of a string
  ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~     
  To retain only the left-hand portion of a string, use truncate or left. For 
  example, if the string variable DataFile contains a complete filename from 
  which you need only the drive letter, you could use truncate(DataFile,":") 
  to discard the colon and everything to its right. This would leave only the 
  drive letter in DataFile. Or your could use left(DataFile,1) to keep the 
  left-most character and discard the rest.
       
       
                       1.18  Building strings
                      ========================               
                      
  Sometimes you may need to build strings by combining characters, string 
  variables and/or integer variables. Many functions include arguments 
  enclosed by quotes (referred to as literal strings or just strings) and it 
  is within such arguments that you can combine strings and variables.
       
  To insert the contents of any variable named S(N), I(N), or F(N), simply 
  precede the name with a slash (say, /S(N), /I(N), or /F(N)), as illustrated 
  in this section.
       
  To insert contents of any variable having a descriptive name, you must 
  enclose the name in parentheses and precede it with a slash, as in 
  "/(descriptive name)".
       
  Suppose you have an integer variable I(7), which contains a file's size in 
  kilobytes, and a string variable S(4), which contains the file's name, and 
  you wish to display this information. To do this, you could use "prompt
  ("/S(4) is /I(7)K")". If S(4) contains LOTUS.WK1 and I(7) contains 127, 
  then this would display LOTUS.WK1 is 127K.
       
  Suppose you need to delete a file whose drive letter, directory and filename 
  are stored in separate string variables S(1), S(2) and S(3). You might 
  simultaneously combine these variables with : and \ and erase the file using 
  erase("/S(1):\/S(2)\/S(3)"). Alternatively, you could combine the variables 
  into a new string variable S(4), then use the new variable in the erase 
  function:
  
         set string(S(4),"/S(1):\/S(2)\/S(3)") ;builds a filename
         erase("/S(4)")                        ;erases the file
       
  When you combine string variables, keep in mind that if the total, expanded 
  length of a string exceeds 128 characters, characters at the right-hand end 
  will be lost. To avoid losing characters, you can use the declare function 
  to specify in advance that the string variable's length may range up to 256 
  characters.
       
  Here are some other items that you can insert by using a /:
       
  /x00 through /xFF
       A slash followed by x and a hexadecimal value inserts a byte having 
       that value, such as control characters (hex values from 00 to 1F), 
       alphanumeric characters (20 to 7F), or extended ASCII characters 
       (80 to FF). See Appendix E for a table of hex values.
  /n
       This moves the cursor to the beginning of the line below its present 
       line. When used in prompts that your script displays locally (only on 
       your screen), this has the same effect as a line feed and carriage
       return. /n is seldom included in strings sent to remote systems; when 
       used this way, it sends only a line feed.
  /r
       This inserts a carriage return. (In the type function, this can be 
       used interchangeably with <ENTER>.) Including this in strings sent to 
       remote systems generally results in the cursor moving to the beginning
       of the next line below its present location. But when used in a prompt 
       that displays locally, it merely moves the cursor to the beginning of 
       the present line.

  /L(0) through /L(9)
       Use these as described in Section 1.21.

  To include / itself in a string, use // instead. To include " within a 
  string, use /". To have type send < or >, use /< or />.
       
       
                   1.19  Reading text from external files
                  ========================================                     
                
  It is possible for scripts to read text from external ASCII files such as 
  those created with a text editor. This can be a handy way to load operating 
  parameters, lists, or other data used within the script. Reading such data 
  from external files eliminates the need to "hard code" the data into your 
  script, and stores the data in a form accessible to other scripts and 
  programs.
       
  Before you can read text from a file, you must open it using read "from
  ("filename")". After that, you can read from the file using "read(string 
  variable,"pattern")".
       
  Access to files is sequential. In effect, opening the file with "read from" 
  opens a window through which "read" may examine the file a window which 
  initially contains the first line in the file. When read executes, it
  advances the window a line at a time until it finds the line it is seeking. 
  It copies that line and leaves the window positioned on the next line. 
  Executing "read" again, moves the window forward from that point. Once the 
  window reaches the end of the file, it remains there. To reposition the 
  window at the beginning of the file, you must re-open the file using "read 
  from".
       
  The function "read(string variable,"pattern")" seeks the next line that 
  contains the pattern and copies that line into the string variable. If you 
  specify no "pattern" (by including ""), this simply copies whichever line is 
  next. When read succeeds in copying a line, it gives a TRUE, but if it 
  cannot copy a line (because the window has already reached the file's end 
  or because it cannot find the "pattern"), it produces a FALSE.
       
  For example, suppose you use the Editor to create an ASCII file named 
  OFFICES.LST. You type into the file a list of branch offices, along with 
  the files that should be sent to each:
       
       Chicago, \GRAPHICS\CAD\*.PIC
       Dallas, \ACCTS\INVENTORY\*.*
       Denver, \DOCUMENTS\*.DOC
       Los Angeles, \ACCTS\INVENTORY\*.NEW
       New York, \STOCKS\*.BUY
       
  To have a script read OFFICES.LST to determine which files to send to each 
  office, you use the following script lines.
  
         declare string FileLine
         read from("OFFICES.LST")              ;opens file OFFICES.LST
         read string(FileLine,"Los Angeles")   ;seeks Los Angeles line 
         cut(FileLine,", ")                    ;removes city, comma and space
  
  This copies the line "Los Angeles, \ACCTS\INVENTORY\*.NEW" into "FileLine" 
  and removes "Los Angeles", from it. The script might then go on to send the 
  files \ACCTS\INVENTORY\*.NEW. To retrieve another line from OFFICES.LST 
  (one which may occur before or after the Los Angeles line), you would use 
  "read from("OFFICES.LST")" again, so that OFFICES.LST would be searched 
  from its beginning.
       
  Files from which you read typically should contain only ASCII data, not 
  binary or word processor formatting codes. Only one file can be open for 
  reading at a time; if you execute "read from" to open another, the first 
  file is closed for you. While you can close a file by executing "read 
  from("")", it's unnecessary to do so; files are closed for you when the 
  script ends.
       
                  
                  1.20  Writing text into external files
                 ========================================                    
                 
  Scripts can write text into external ASCII files as well. This can be 
  useful for logging activities, adding notes to captured text, or storing 
  important numbers, words or phrases gathered by the script.
       
  You can also make scripts that adapt to the user: The first time a script 
  runs, have it let the user enter preferences, then store them in a file; in 
  subsequent runs, read the file and act accordingly.
       
  Before a script can write to a file, it must open it using "write to
  ("filename")"; if the file doesn't exist, this will create it. Then write 
  to the file using "write("string"{,add line feed?})". This appends the 
  string to any existing file contents.
       
  For example, prior to capturing mail into a file, you might want to execute 
  the following lines, to insert the time and date into the file:
  
         write to("EMAIL.NEW")               ;opens the file EMAIL.NEW
         write("Received //DATE at //TIME")  ;puts time & date in file
       
  The optional "{,add line feed?}" argument in the "write" function 
  establishes whether a line feed and carriage return are added to the end of 
  the string as it is written to the file. If you simply leave out this 
  argument (as was done above), a line feed and carriage return are added.
       
  Files into which you write should typically contain only ASCII data, not 
  binary or word processor formatting codes. Only one file can be open for 
  writing at a time; if you execute "write" to open another, the first file 
  is closed for you. While you can close a file by executing "write to("")", 
  it's unnecessary to do so; files are closed for you when the script ends.
       
       
                   1.21  Storing strings in the list
                  ===================================                      
               
  For temporary storage of often-used strings, the list can be faster and 
  more convenient than external files. Each script can store a list of up to 
  128 strings in memory for fast access; it is cleared from memory when the 
  script ends. (This list should not be confused with the System List, which 
  is unrelated.)
       
  Each string stored in the list is referred to as an item. The first string 
  you store becomes the top of the list and is assigned item number 0. The 
  next string stored goes beneath it and is assigned item number 1. In other 
  words, each additional string that you store is added to the end of the 
  list and is assigned the next available item number. You can remove a string 
  or strings only from the list's end, not from its middle or beginning.
       
  There are several ways to store strings into the list. You can store one 
  string at a time into the list using "set list". You can accept a string 
  entered by the user and store it using "key list". To read strings from an 
  external file and store them into the list, first use "read from" to open 
  the file, then use "read list". To check the current size of the, list, use 
  "list size". To display an item or items, use show. To remove one or more 
  items, use "clear".
       
  To insert a list item into a string, you use a two-step process: First, you 
  store the desired item number in an integer variable (such as I(4)); Second, 
  you include /L(N) in the string, where N must be the same number as is used 
  in the parentheses of the integer variable. That is, if the desired item 
  number is stored in I(4), you would need to use /L(4); the 4 in /L(4) 
  essentially indicates that integer variable I(4) contains the desired item 
  number.
       
  For example, to insert item number 45 into a string, you might use "set 
  integer" to store 45 in counter I(8), then include /L(8) in a string. If 
  item number 45 were "The quick brown fox", then prompt("/L(8) jumped over 
  the lazy dog") would display "The quick brown fox jumped over the lazy dog".

       
                       1.22  Passing inputs to scripts
                      =================================                    
                      
  Passing inputs to scripts is useful under two circumstances: 1) when you 
  start a script manually; 2) when you have your script start another script 
  (or command).
       
  When you manually start a script by pressing ALT-R and entering its name 
  followed by inputs, each function it executes whose name begins with "key" 
  uses one of the inputs, rather than waiting for a response from the 
  keyboard. The inputs can be anything that would be acceptable to each 
  particular "key" function. If the script starts another script or command, 
  the inputs are available to it as well.
       
  When you have a script start another script (or command) by using "run
  ("sequence name")", you can pass additional inputs to it by replacing 
  "sequence name" with a script or command name followed by inputs. You can
  use literal characters as inputs, or use string or integer variables 
  preceded by /. If any inputs included in the run function remain unused 
  when that script or command finishes, they are discarded.
       
  When one script runs another, it is in some ways similar to using a 
  subroutine, except that the first script's variables and list are not 
  available to the second. (Each script has its own variables and list; when 
  the first script resumes, its variables and list are intact.)
       
  Passing inputs allows you to move data from the first script to the second, 
  but not back. A more versatile way to share data among scripts is to use 
  "put environment" and "get environment".
       
                       
                       1.23  Using an escape key
                      ===========================               
                      
  While any script can be aborted by pressing ALT-A, those containing escape 
  routines can also be interrupted with an escape key. To add an escape 
  routine, use "escape key("key name")" to define the escape key, and add an 
  escape routine that begins with the "_Escape:" label. (Pressing the escape 
  key jumps to this label.) The routine can include lines that display 
  messages, log information, hang up, or do whatever you like.
       
  Often an escape routine is used not to end a script, but to make it take an 
  alternate course of action. For example, in a script that automatically 
  picks up electronic mail and hangs up, you might define an escape key and 
  put statements after _Escape: which instead leave you connected and let you 
  take manual control of the call.
       
  If you define an escape key without including "_Escape:", pressing the 
  escape key will merely end the script and disconnect your call.
       
       
                   1.24 Substituting your own error routine
                  ==========================================                   
                  
  When a TRUE/FALSE function not preceded by "if" or "ifnot" gives a FALSE 
  (which typically indicates it could not perform its task), the script stops, 
  displays the function's line number, then hangs up unless you resume control 
  within 60 seconds. But you can have it execute an error routine of your own 
  instead. To do this, begin the error routine with the "_Error:" label. This 
  label has special significance: if an error occurs in a script where this 
  label exists, execution jumps to this label automatically.
       
  You may want to have your error routine take remedial steps, or simply 
  display or log the error. (To obtain the line number of the error, use 
  "report("ERROR LINE",integer variable)".)
       
  If you plan to have the script run while you're away, you may want to 
  include "hangup()" in your error routine, so your PC will not remain 
  on-line.
       
  When including an error routine in logon scripts for systems that you may 
  call using the multiple call feature, also include "put environment 
  ("HA_CALL_STATUS","FAILED")". This statement notifies the batch call 
  facility if the script fails, so that the call can be tried again.
       
  When including an error routine in logon scripts for systems that you may 
  call using the multiple call feature described in Section 4.3, also include 
  put environment("HA_CALL_STATUS","FAILED"). This statement notifies the 
  batch call facility if the script fails, so that the call can be tried 
  again.
                
                
                
                
                
       
                           Chapter 2
                          ===========

                      HyperPilot Functions
            

       HyperPilot Function Definitions    
       ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
       
       add(integer variable, integer)
       
       Purpose: To add two integers.
       Action: Adds the contents of the integer variable to the specified 
       integer and stores the result back into the integer variable.
       Example: add(I(4),61)
       
       
       alert("prompt"{, timeout})    T/F
       
       Purpose: To get the attention of the user.
       Action: Displays the prompt and beeps every 3 seconds.
       T/F result: FALSE only if the user fails to respond by pressing any 
       key within the timeout period.
       Example: alert("Press any key to go on",10)
       Remarks: When the second argument is omitted, "alert" waits up to 30 
       seconds (or a time previously defined using "change timeout").
       
       
       and (flag variable, flag variable) T/F
       
       Purpose: To AND the states of two flags (using boolean logic).
       Action: Produces a TRUE or FALSE result; does not change either flag 
       variable. 
       T/F result: TRUE if both flags are TRUE; FALSE if either or 
       both flags are FALSE.
       Example: and(F(3),F(7))
       
       
       ascii("string", integer variable)  T/F
       
       Purpose: To obtain the ASCII value of a character.
       Action: Finds the decimal ASCII value of the first character in the 
       string and stores that value in the integer variable. 
       T/F result: FALSE only if the string contains no characters.
       Example: ascii("/S(3)",I(4))
       
       
       ask("prompt")  T/F
       
       Purpose: To get a yes or no answer from the user.
       Action: Displays the prompt and waits the user to type Y or N and 
       press ENTER. 
       T/F result: TRUE if the user answers yes; FALSE if he answers no.
       Example: if ask("/nWant to hang up? Enter Y or N: ") hangup()
       Remarks: This serves much the same purpose as "key flag", except that 
       "ask" merely produces a TRUE or FALSE, while "key flag" stores the 
       user's response as a flag variable for subsequent use in the script.
       
       
       bottom line(column,"string")
       
       Purpose: To display prompts in the bottom line of the Comm screen.
       Action: Displays the string beginning at the specified column; the 
       string remains in the bottom line even as text on the Comm screen 
       scrolls.
       Example: bottom line(1,"Script written by B. Jones")
       Remarks: Before you use "bottom line" to display your own bottom line, 
       use "option("BOTTOM LINE",no)" to turn off the normal bottom line. 
       Then, if you merely wish to clear the bottom line, use "bottom 
       line(0,"")". Later, to remove your bottom line and restore the normal 
       one, use "option("BOTTOM LINE",yes)".
       

       box characters("characters")
       
       Purpose: To set alternate characters used for drawing boxes.
       Action: Establishes which characters are used by subsequent "draw box" 
       functions.
       Example: box characters("ÉÍ» º º Èͼ")
       Remarks: Within quotes, list one of each character used to draw the 
       box, going clockwise starting with the box's upper left corner. (The 
       example lists É Í » º º È Í ¼, but without spaces.) To type such 
       characters, hold ALT down and type keypad numbers (see Appendix E for 
       numbers). Using draw box without first using box characters to define 
       characters draws a single-line box.
       
       
       break()
       
       Purpose: To send a break signal out the communications port.
       Action: Sends a break signal of 1.5 seconds duration.
       
       
       call connected("system name")
       
       Purpose: To update information used for sorting the System List.
       Action: Informs FreeComm that the system has been called; FreeComm 
       uses this information to sort systems in the System List according 
       to how recently or frequently they are called.
       Example: call connected("MCI Mail")
       
       
       capture begin("filename"{,append?})     T/F
       
       Purpose: To start capturing text that arrives on the Comm screen.
       Action: Text that arrives on the Comm screen subsequent to "capture 
       begin" is saved into the specified file. If the second argument is no, 
       the new text overwrites existing file contents; if it is yes or 
       omitted, new text appends to existing text. If the specified file does 
       not exist, it is created.
       T/F result: FALSE only if the file cannot be opened.
       Example: capture begin("CAPTURED.TXT",no)
       Remarks: When you are ready to stop saving, use "capture end". Once 
       you've begun capturing to a given file, you can suspend and resume 
       capturing by using capture suspend and capture resume.
         (For pointers on capturing text, see Section 1.10.)
       
       
       capture end()  T/F
       
       Purpose: To stop capturing text.
       Action: Executing capture end() prevents information that arrives on 
       the Comm screen subsequently from being stored into the capture file, 
       and closes the capture file.
       T/F result: FALSE only if capturing is not begun beforehand.
       Example: capture end()
       Remarks: Begin capturing by using "capture begin". Once you have begun 
       capturing to a given file, you can suspend and resume capturing by 
       using "capture suspend" and "capture resume". 
         (For pointers on capturing text, see Section 1.10.)
       
       
       capture resume()    T/F
       
       Purpose: To resume capturing text to a file, after you have suspended 
       capturing.
       Action: After you have executed "capture suspend", executing "capture 
       resume" causes information that arrives on the Comm screen to resume 
       flowing into the capture file.
       T/F result: FALSE only if capturing was not suspended beforehand.
       Example: capture resume()
       
       
       capture suspend()   T/F
       
       Purpose: To suspend capturing text to a file without closing the file.
       Action: After you have executed "capture begin", executing "capture s
       uspend" stops information which arrives on the Comm screen from 
       flowing into the capture file.
       T/F result: FALSE only if capturing is not begun beforehand.
       Example: capture suspend()
       
       
       change timeout(seconds)
       
       Purpose: To set the timeout used by other functions.
       Action: Defines the timeout period that functions use when you omit 
       optional "timeout arguments".
       Example: change timeout(60)
       Remarks: The timeout period is 30 seconds unless you use "change 
       timeout" to define a different period.
       
       
       character(string variable, ascii number)     T/F
       
       Purpose: To obtain the character corresponding to an ASCII value.
       Action: Adds to the end of the string variable the character whose 
       decimal ASCII value is specified.
       T/F result: FALSE only if the number is outside the possible range 
       (0 to 255) or if the string variable reaches the maximum length.
       Example: character("S(7)",102)
       
       
       character delay(milliseconds)
       
       Purpose: To slow the rate at which characters are sent.
       Action: Inserts a delay of up to 255 milliseconds after sending each 
       character.
       Example: character delay(50)
       Remarks: Until you execute this function, the "character delay" remains 
       as set on the Receiving menu(see Section 10.3). To avoid losing 
       characters, you may need to use character delay prior to sending with 
       Text protocol to systems or modems which cannot handle data at full 
       speed. ("character delay" does not affect the "type" function, whose 
       speed is independently set by its second argument.)
       
       
       clear list(beginning item number)
       
       Purpose: To remove items from the list.
       Action: Deletes from the list the item number specified here and all 
       items below it.
       Example: clear list(12)
       Remarks: For information regarding use of the list, refer to Section 
       1.21. 
       
       
       connected(string variable, integer variable)
       
       Purpose: To find how long a call has been connected.
       Action: Copies the current connect clock reading from the lower right 
       corner of the screen into the string variable and puts its value in 
       seconds into the integer variable.
       Example: connected(S(6),I(3))
       
       
       cursor restore()
       
       Purpose: To return the cursor to a previously stored location.
       Action: Moves the cursor back to the same screen position it had when 
       "cursor save" was last executed, and restores former character 
       attributes (display color, reverse video, etc.).
       Example: cursor restore()
       Remarks: "cursor restore" has no effect unless "cursor save" has been 
       executed previously.
       
       
       cursor save()
       
       Purpose: To save the cursor location so you can restore it to this 
       location later.
       Action: Saves the screen location and character attributes (display 
       color, reverse video, etc.).
       Example: cursor save()
       Remarks: To restore the cursor, use "cursor restore". 
       
       
       cut(string variable,"pattern")T/F
       
       Purpose: To extract a desired piece of text from a string.
       Action: Discards from the string variable, the pattern and all 
       characters to the left of the pattern.
       T/F result: FALSE only if the string variable lacks the pattern.
       Example: If FileMsg contains "The filename is TEST.TXT", then 
       "cut(FileMsg,"is ")" would discard all but TEST.TXT.
       Remarks: If the pattern is absent, the string variable remains intact. 
       If the pattern appears more than once, the left-most occurrence is cut. 
       The pattern can include ? as a wildcard. The truncate function works 
       the same, but discards text from the right-hand end. To retain only a
       specific number of characters from the right- or left-hand end of a 
       string, use right or left instead.
       
       
       date(string variable)
       
       Purpose: To obtain the date from the operating system.
       Action: Stores into the string variable the date in the format MM-DD-YY.
       Example: date(S(8))
       
       
       declare variabletype variablename(s)
       
       Purpose: To designate user-defined names as variables.
       Action: Instructs the compiler to accept the name or names specified as 
       variable(s) of the type specified.
       Example: See Section 1.15 for examples and explanation.
       Remarks: Where a string normally has a maximum length of 128 characters, 
       you can set a length up to 256 characters by using the form "declare 
       string variablename(length)".
       
       
       decrement(integer variable)T/F
       
       Purpose: To count down or to control looping operations.
       Action: Subtracts one from the integer variable.
       T/F result: FALSE only when the integer variable reaches zero.
       Example:    declare integer Counter
                   set integer(Counter,10)
                 DisplayNext:
                   prompt("/Counter ")
                   if decrement(Counter) goto DisplayNext
                   prompt("done")
       This routine sets integer variable Counter to 10, displays it, 
       decreases it by 1, loops back, displays it again, etc. When the value 
       stored in Counter reaches zero, the screen would display: 
       10 9 8 7 6 5 4 3 2 1 done.
       Remarks: The "decrement" function can be used together with "while" 
       or "if-then-else" to construct loops for performing operations 
       similar to Basic language DO or FOR NEXT loops.
       
       
       delay(hours,minutes)T/F                           
       
       Purpose: To delay a prescribed length of time before executing 
       subsequent lines (typically lines intended to perform unattended 
       operations).
       Action: Makes the script halt until the specified number of hours and 
       minutes have passed; "delay" also displays the amount of time remaining.
       T/F result: FALSE if the user presses ENTER during the delay; TRUE 
       after the specified time has passed.
       Example: ifnot delay(3,45) end()
       Remarks: To make a script begin a process after a prescribed length of 
       time, put "delay" ahead of the lines that perform the process, then 
       start the script as you leave your PC. When "delay" times out, 
       subsequent lines will execute. By including delay in a suitably 
       constructed conditional statement, you can make the script either
       continue or end, by pressing ENTER. (The example above would end the 
       script if ENTER were pressed.)
       
       
       delay until("HH:MM"{,show time?})  T/F
       
       Purpose: To delay until a specified time before executing subsequent 
       lines (typically lines intended to perform unattended operations).
       Action: Makes the script pause until the specified time. If the second 
       argument is yes or is omitted, a message stating the awaited time is 
       displayed; the second argument is no, no message displays.
       T/F result: FALSE if time is specified using an invalid format or if 
       the user presses ENTER during the delay; TRUE after the specified time 
       arrives.
       Example: ifnot delay until("23:30") goto ActNow
       Remarks: To make a script begin a process at a specified time, put 
       "delay until" ahead of the lines that perform the process, then start 
       the script as you leave your PC. When your PC's internal clock reaches
       the prescribed time, subsequent lines will execute. By including delay 
       until in a suitably constructed conditional statement, you can make 
       the script either continue or end, by pressing ENTER. (If ENTER were 
       pressed in the above example, this would make the script continue at 
       the label ActNow.)
       

       divide(integer variable,integer)
       
       Purpose: To divide one integer by another.
       Action: Divides the contents of the integer variable by the specified 
       integer and stores the answer in the integer variable.
       Example: divide(SizeOfFile,1024)
       Remarks: Any remainder is truncated. Division by zero gives zero.
       
       
       draw box(rows,columns)
       
       Purpose: To draw a box on the local screen in which a message can then 
       be displayed.
       Action: From the current cursor position, draws a box (using characters 
       defined in "box characters") extending down and to the right the 
       specified number of rows and columns.
       Example: draw box(8,50)
       Remarks: Before you draw a box, you may want to save the current 
       screen and find the cursor location (with "get position"), so you can 
       later restore the screen and reposition the cursor (with "position"); 
       see Section 1.13 for examples. Because not all terminal emulators use 
       the same characters for line graphics, you may need to select 
       different characters with box characters prior to using "draw box". 
       (If you're emulating a terminal that supports cursor-positioning and 
       line graphics, another way to draw boxes or other screen displays is
       to issue suitable cursor-positioning and character codes to the 
       terminal emulator with "prompt"; to find if your terminal type 
       supports cursor-positioning and line graphics, and to find out which 
       codes to issue, refer to documentation from the manufacturer of that 
       type of terminal.) 
       
       
       emulate("terminal") T/F
       
       Purpose: To change which terminal is being emulated.
       Action: Switches from the current terminal to the specified terminal.
       T/F result: FALSE only if the specified terminal does not exist or is 
       misspelled. (See Appendix F for a list of terminals.)
       Example: emulate("VT100")
       
       
       end()
       
       Purpose: To end a script.
       Action: Ends the script, leaving the Comm screen displayed.
       Example: end()
       Remarks: If you want to end the script and leave FreeComm, use "quit", 
       instead. To end a script and remain on a screen or menu other than 
       the Comm screen, use "type" to issue keys that go from that Comm screen 
       to the desired location, followed by <ALT-L>SS (which stops learning 
       and stays on the menu where learning stops.)
       
       
       equal(integer variable,integer)    T/F
       
       Purpose: To see if an integer variable equals an integer.
       Action: None except to produce a TRUE or FALSE result; the integer 
       variable remains intact.
       T/F result: TRUE only if the integer variable equals the integer.
       Example: ifnot equal(Events,12) goto TryAgain
       
       erase("filename")
       Purpose: To delete a file from the PC's disk.
       Action: Deletes the file.
       Example: erase("JUNKFILE.TXT")
       Remarks: This function does not accept wildcards (* or ?). Attempting 
       to erase a nonexistent file does not cause a problem.
       
       
       escape key("key name")   T/F
       
       Purpose: To define a key used to interrupt execution of a script.
       Action: Once an escape key is defined with this function, pressing 
       that key causes execution to jump to the label "_Escape". See Section 
       1.23 for more information.
       T/F result: FALSE only if the specified key is not a valid choice.
       Example: escape key("<ESC>")
       Remarks: The most common choice for an escape key is ESC.
       
      
      execute("program name"{,allow remote use?})T/F
      
     Purpose: To execute DOS or programs and commands.
     Action: Executes the program or command. Under DOS, this command first 
     stores FreeComm to disk to free up memory, then restores it to memory 
     after executing the command. Including yes as the second argument allows 
     a caller who is connected with your PC to run the specified program 
     remotely. (The caller must have FreeComm and be using the HYPERTRM 
     emulator.) T/F result: FALSE only if there is insufficient memory to run 
     the program. With DOS, FALSE may also occur if there is insufficient disk 
     space for FreeComm to be stored to disk, or if COMMAND.COM cannot be found.
     Example: execute("COPY *.* B:")
     Remarks: Use "memory execute" instead for faster execution of programs 
     which do not require large amounts of memory.
     
  
     fetch character(string variable,"prompt") T/F
        
        
     Purpose: To prompt a remote user for input and accept his response.
     Action: Sends the prompt, then stores in the string variable the next 
     character received from the remote user.
     T/F result: FALSE if the remote user fails to type any character within 
     30 seconds (or a time previously defined using "change timeout").
     Example: To accept single-key selection from a remote user, you could 
     use "fetch character(UserResponse,"Enter Y or N: ")" followed by 
     functions that examine "UserResponse" to determine whether it is Y or N.

     
     fetch string(string variable,"prompt")    T/F
        
        
     Purpose: To prompt a remote user for input and accept his response.
     Action: Sends the prompt, then stores into the string variable the 
     response entered by the remote user.
     T/F result: FALSE if the remote user fails to enter a response within 30 
     seconds (or a time previously defined using "change timeout").
     Example: To accept a password from a remote user prior to allowing him 
     to access your computer, you could use "fetch string(Password,"Enter 
     password: ")" followed by functions that examine "Password" to verify 
     that the password is correct.
     Remarks: The remote user must end his response by pressing ENTER on his 
     computer.
     
     
     filesize("filename",integer variable)     T/F
     
     Purpose: To check size (or existence) of a file or files on the PC's 
     disks.
     Action: Puts the size of the file or files in kilobytes into the integer 
     variable.
     T/F result: FALSE only if the file cannot be found.
     Example:    declare integer Amount
                 filesize("B:ARTICLE.TXT",Amount)
     Remarks: To find the total size of a file group, include * or ? in the 
     filename.  You can also use "filesize" to check for existence of a file 
     by including this function in a conditional statement.
     
     
     flag(flag variable)   T/F
     
     Purpose: To check the state of a flag.
     Action: None except to produce a TRUE or FALSE result; the state of the 
     flag is not affected.
     T/F result: TRUE if the flag has a TRUE state; FALSE if it has a FALSE 
     state.
     Example: if flag(NoErrors) goto KeepGoing
      
      
     
     full filename(string variable,"filename")
     
     Purpose: Expands a filename to include a full path.
     Action: Adds the current default drive and directory to the specified 
     filename and puts the result in the string variable.
     Example:    declare string LocalFile
                 full filename(LocalFile,"FUTURES.WK1")
     
     
     get environment(string variable,"name") T/F
        
     Purpose: To facilitate sharing of information among scripts and programs, 
     this allows strings to be retrieved from your operating system's 
     environment.
     Action: Checks the environment for a string having the specified name, 
     then copies that string into the string variable.
     T/F result: FALSE only if the environment contains no string having the 
     specified name.
     Example:    declare string System
                 get environment(System,"SYSTEM_NAME").
     Remarks: The environment is an area of memory containing strings which 
     DOS makes available to all programs; it is explained in your operating 
     system manual. Strings can be stored in the environment using" put 
     environment". The environment is an excellent way to pass strings among 
     scripts.
     
     
     get integer(integer variable,"string")    T/F
        
     Purpose: To extract a integer value from a string.
     Action: Searches left to right through the string and puts the first 
     integer found into the integer variable.
     T/F result: FALSE only if no integer is found.
     Example: If the string variable "FileMsg" contains "File size = 24K", 
     then "get integer(FileSize,"/FileMsg")" would put 24 into the integer 
     variable FileSize.
     Remarks: If a string contains two integers separated by a character such 
     as the period in a floating point number, only the integer left of the 
     character is reported. (To get the next integer, use "cut" to discard the 
     left-hand portion of the string.) If no integer exists, the integer 
     variable's value remains unchanged. The maximum integer that can be 
     reported is 2,147,483,648 (231).
     

     get key(string variable)   T/F
        
     Purpose: To retrieve a key which the user has pressed earlier.
     Action: From among keys pressed by the user but not yet retrieved by the 
     script, this retrieves the earliest-pressed key and stores its string 
     representation in the string variable. 
     T/F result: FALSE only if there are no keys to be retrieved.
     Example: if get key(KeyName) goto EvaluateKey
     Remarks: The string representation of alphanumeric keys is the 
     alphanumeric character itself. Non-alphanumeric keys or key combinations 
     are represented by key names in angle brackets. The "get key" function 
     retrieves keys the user has already pressed, in contrast to functions 
     whose names begin with the word "key", which wait for keys to be pressed.

     
     get position(int. variable, int. variable)
        
     Purpose: To determine the present location of the cursor.
     Action: Puts the column number of the cursor's position in the first 
     integer variable and the row number in the second integer variable.
     Example:    declare integer CursorColumn, CursorRow
                 get position(CursorColumn,CursorRow)
     Remarks: You may want to "use get" position to find where the cursor is 
     before you display a prompt, so that when you clear the prompt from the 
     screen you can use "position" to restore the cursor to that location.
     
     
     goto labelname
        
     Purpose: To control the order in which lines are executed.
     Action: Makes execution jump unconditionally to the line containing the 
     specified "labelname", followed by a colon.
     Example: This example reads and displays lines from a file, one at a 
     time, until it reaches the end of the file:
              declare string FileLine
              read from("EXAMPLE.FIL")
            ReadLine:
              read string(FileLine,"")
              prompt("/FileLine/n")
              goto ReadLine
     Remarks: Note that the line to which a "goto" statement branches must 
     contain only a label name followed by a colon (you may include a 
     semicolon and comment to its right). Label names can be any string of 
     alphanumeric characters without spaces or punctuation. It is customary 
     to begin label names with a capital letter, to help distinguish them 
     from functions. To make label names with more than one word, begin each 
     with a capital and use no spaces between (or separate words with an 
     underscore). 
     
     
     gosub labelname...return
        
     Purpose: To allow use of subroutines.
     Action: Makes execution jump to the line containing the specified 
     "labelname". When "return" is encountered at the end of the subroutine, 
     execution resumes with the line following gosub.
     Example: gosub CheckStatus
     Remarks: When a certain routine appears repeatedly in a script, you may 
     be able to compact the script by using a subroutine. To do this, replace 
     each occurrence of that routine with gosub labelname and put the routine 
     in a subroutine at the end of your script. Begin the subroutine with 
     that labelname, and end it with return.
     You can include as many subroutines as you want. Subroutines can contain 
     gosub to branch to other subroutines. (This is called nesting; subroutines 
     can be nested 16 deep.) If you put a subroutine at the wrong location and 
     execution strays into it when "no gosub" has been executed, the message 
     "Error in script--"return()" executed while not in subroutine" displays.
     Either precede the subroutine with a "goto" or "end" statement, or move 
     the subroutine to the end of the script.
     
     greater(integer variable, integer)   T/F
        
     Purpose: To see if the integer variable is greater than a given integer.
     Action: None except to produce a TRUE or FALSE result; the integer 
     variable remains intact.
     T/F result: FALSE only if the integer variable is less than or equal to 
     the integer.
     Example: ifnot greater(Total,276) goto AddMore
     
     
     hangup()
        
     Purpose: To make the modem hang up.
     Action: Sends a signal to the modem telling it to disconnect from the 
     remote system.
     Example: hangup()
     Remarks: This has the same effect as pressing ALT-O and selecting 
     "Hangup" on the Comm screen. For this to make the modem disconnect, the 
     modem's switches must set so that the modem responds to the DTR signal.
     
     
     if...then...else
        
     Purpose: To construct conditional statements which affect the order of 
     execution of a script.
     Action: Executes a function which produces a TRUE/FALSE result; if the 
     result is TRUE, the function listed after then executes; if the result 
     is FALSE, the function listed after else is executed.
     Example: If filesize is TRUE (meaning INVOICE.DAT exists), these 
     statements send the file. If it is FALSE, a comment indicating that the 
     file does not exist is sent instead:
        
            if filesize("INVOICE.DAT",I(0)) then
              type("HREC<ENTER>")
              wait lull(2)
              transfer send ("INVOICE.DAT",HyperProtocol)
            else
          type(";Sorry, no invoice data to send today.<ENTER>")
            endif
     Remarks: "if-then-else" can be used in single-line statements as 
     described in Section 1.8 or in block structures, as described here. 
     "if-then-else" block structures offer these advantages:
        þ   More structure and flexibility by allowing conditional
            branches across several lines
        þ   Make it possible to test more complex conditions
        þ   Let you use longer statements and structures within "then-
            else" portions of statements
        þ   Program structure can be guided by logic rather than by
            how many statements fit on a line
        
        The general form of "if-then-else" block structures is:
        
                 if function1 {then}
                    statementblock1
                 {elseif function2 {then}
                    statementblock2}
                 {elseif function3 {then}
                    statementblock3}
                 {else
                    statementblockN}
                 endif
        
        Function1 must be a TRUE/FALSE function. If function1 is TRUE, lines 
        comprising statementblock1 execute. If function1 is FALSE, each 
        "elseif" (or "elseifnot") condition is evaluated in turn. If an 
        elseif condition is TRUE (or an elseifnot condition is FALSE), lines 
        in its statementblock execute. If none of the "elseif" or "elseifnot" 
        conditions is satisfied, lines in the statementblock following "else" 
        are executed, and the script continues with the lines following 
        "endif." Including "else", "elseif", and "elseifnot" blocks is 
        optional. You may include as many "elseif" and "elseifnot" blocks as 
        you like, but only one "else" block. Any statementblock can contain 
        nested "if-then-else" block structures.
        Including any function to the right of then causes that line to be 
        treated as a single-line "if-then-else" statement, rather than the 
        beginning of a block structure. "if", "elseif", "elseifnot", "else", 
        and "endif" can appear only at the beginnings of lines (except in the 
        single-line form of "if-then-else", where "else" is within the line). 
        Block "if-then-else" structures must end with "endif".
        
        
     ifnot...then...else
        
     Purpose: To construct conditional statements which affect the order of 
     execution of a script.
     Action: Executes a function which produces a TRUE/FALSE result; if the 
     result is FALSE the function listed after then is executed; if the 
     result is TRUE the function listed after else is executed.
     Example: IFNOT DECREMENT(I(0)) GOTO KEEPGOING ELSE GOTO STOP
     Remarks: "ifnot-then-else" can be used in single-line statements (see 
     Section 1.8), or in block structures (see "if-then-else"). 
     Block "ifnot-then-else" structures end with "endif".
     
     
     inclusive or(flag variable, flag variable)     T/F
        
     Purpose: To OR the states of two flags (using Boolean logic).
     Action: None except to produce a TRUE or FALSE result; the states of the 
     flags remains intact.
     T/F result: TRUE if the state of either flag is TRUE and FALSE if neither 
     has a TRUE state.
     Example: inclusive or(F(1),F(9))
     
     
     invert(flag variable)
        
     Purpose: To switch the state of a flag.
     Action: Changes the state of the flag from its current value (TRUE or 
     FALSE) to the opposite value.
     Example: invert(F(9))
     
     
     key edit(string variable, maximum length)
        
     Purpose: To allow the user to edit a string, type a new string, or accept 
     the string as is.
     Action: Displays the string and lets the user edit it using Right Arrow, 
     Left Arrow, INS, DEL, or BACKSPACE, type a new string, or accept it as is 
     by pressing ENTER. If more than the maximum length (specified as a number 
     of characters) is typed, the PC beeps to notify the user of his error. 
     When the user presses ENTER, the final string ¯s put in the string 
     variable.
     Example: If string variable "Addressee" contains the string "Bob Jones", 
     the line "key edit(Addressee,20)" would display "Bob Jones" and position 
     the cursor under the first character.
     
     
     key flag(flag variable,"prompt")
        
     Purpose: To get a yes or no answer from the user.
     Action: Displays the prompt and waits for the user to enter Y for Yes or 
     N for No. A Yes entry sets the flag variable to TRUE and a No sets it to 
     FALSE.
     Example: key flag(ReadyStatus,"/nReady to send? (Y or N):")
     Remarks: This serves much the same purpose as "ask", except that" ask" 
     produces a TRUE or FALSE and is generally used in conditional statements, 
     where "key flag" stores the user's response as a flag variable, for 
     subsequent use in the script.
     
     
     key function(integer variable,"prompt")
        
     Purpose: To let users make selections or control a script by pressing 
     special keys.
     Action: Displays the prompt and waits for the user to press one of the 
     keys shown below. A number corresponding to that key is put into the 
     integer variable. If any other keys are pressed, the PC beeps to notify 
     the user of his error.
     Example: key function(I(0),"/nPress F1 to begin.")
     Remarks: Pressing these keys puts the following numbers into the integer 
     variable:
      
  
                F1 - F10                       1 - 10
                SHIFT-F1 - SHIFT-F10           100 - 110
                UP ARROW                       50
                DOWN ARROW                     51
                RIGHT ARROW                    52
                LEFT ARROW                     53
                HOME                           54
                PGUP                           55
                PGDN                           56
                END                            57
      
      
      key integer(integer variable,"prompt")
      
      Purpose: To allow the user to enter an integer.
      Action: Displays the prompt and waits for the user to enter an integer, 
      which is then put into the integer variable.
      Example:   declare integer UserEntry
            key integer(UserEntry,"/nEnter a number: ")
      
      
      key list("prompt")
      
      Purpose: To accept and store in the list, a string entered by the user.
      Action: Displays the prompt and waits for the user to enter a string, 
      which is then added to the end of the list.
      T/F result: FALSE only if the list is full (contains 128 lines).
      Example: key list("/nPlease enter a filename: ")
      Remarks: (For information regarding use of the list, refer to Section 
      1.21.) The length of the entry is limited to the space to the right of 
      the prompt; to allow entries up to 80 characters, use "key list
      ("/nEnter data in the line below:/n")".
      
      
      key string(string variable,"prompt")
      
      Purpose: To allow the user to enter a string.
      Action: Displays the prompt and waits for the user to enter a string, 
      which is then put into the string variable.
      Example:   declare string UserName
            key string(UserName,"Enter your name: ")
      
      
      left(string variable, number)
      
      Purpose: To extract desired text from a string.
      Action: Discards all of the string variable except the leftmost 
      specified number of characters. If the string variable contains fewer 
      than the specified number of characters, its contents remain intact.
      Example: left(S(8),8)
      
      
      length("string",integer variable)   T/F
      
      Purpose: To count the characters in a string.
      Action: Puts the length of the string into the integer variable.
      T/F result: FALSE only if the length is zero.
      Example: length("/S(3)",I(5))
      
      less(integer variable, integer)     T/F
      
      
      Purpose: To determine whether an integer variable is smaller than an 
      integer.
      Action: None except to produce a TRUE or FALSE; the integer variable 
      remains intact.
      T/F result: FALSE only if the integer variable is greater than or equal 
      to the integer.
      Example: if less(Total,269) goto Disconnect
      
      list size(integer variable)
      
      
      Purpose: To determine the number of items in the list.
      Action: Counts the number of items in the list and puts the number into 
      the integer variable.
      Example:   declare integer TotalSize
            list size(TotalSize)
      Remarks: For information regarding use of the list, refer to Section 
      1.21.
      
      
      
      load directory("vilename",integer variable)   T/F
      
      Purpose: To allow the PC's disk directories to be read by a script.
      Action: Stores into the list the names of files matching the filename 
      (which can include ? and *) and puts the total number of files into the 
      integer variable.
      T/F result: FALSE only if no files are found. If there are more 
      filenames than the list can hold, it loads as many as possible  (128 is 
      the maximum) and still gives a TRUE.
      Example:   declare integer FileCount
            load directory("*.EXE",FileCount)
      Remarks: For information regarding use of the list, refer to Section 
      1.21.
      
      
      load system("system name"{,keep port?})  T/F
      
      Purpose: To load settings for a particular system.
      Action: Loads settings for a system which appears in the System List on 
      the Main menu. If the second argument is yes, it keeps using the same 
      port as the previously loaded system; omitting this argument or using 
      no invokes the new system's port setting. (Loading a system does not 
      dial the system.)
      T/F result: FALSE only if the system is not in the System List.
      Example: load system("Easylink")
      Remarks: Prior to using load system, you may sometimes want to save 
      your current settings temporarily, so the script can reload them later. 
      To do this, precede "load system" with "store system("/SAVE")". Later, 
      to reload the saved settings, use "load system("/SAVE")".
      
      
      log duration(string variable,"filename")
      
      Purpose: To log the duration and other details about a call.
      Action: Tells FreeComm to wait for the ongoing call to end, then write 
      the string variable to a file.
      Example: set string(S(2),"/S(1) on //DATE //TIME //DURATION")
          log duration(S(2),"PHONE.LOG")
      The first line above sets S(2) equal to the combination of a system's 
      name (/S(1)), the date (//DATE), the time (//TIME), and the call's 
      length (//DURATION). "log duration" then passes the string in S(2) to
      FreeComm to complete. When the call ends even if the script is no 
      longer running FreeComm inserts the time, date, and duration, and writes 
      the string into the PHONE.LOG file. (To determine when a call ends, 
      FreeComm watches for the carrier detect (CD) signal to change state; 
      thus, the modem's CD output must accurately reflect whether a connection 
      exists.)
      
      
      lowercase(string variable,"string")
      
      Purpose: To convert a string to all lowercase letters.
      Action: Changes any uppercase letters in the string to lowercase, and 
      puts the resulting string into the string variable.
      Example: lowercase(UserName,"/UserName")
      Remarks: The example above would change the contents of a string 
      variable UserName to lowercase and put the resulting string back into 
      the same string variable.
      
      
      memory execute("program name") T/F
      
      Purpose: To execute DOS programs and commands while FreeComm remains in 
      memory.
      Action: Executes the program or command.
      T/F result: FALSE only if there is insufficient memory to run the 
      program (with DOS 2.XX, also
        FALSE if COMMAND.COM cannot be found).
      Example: memory execute("COPY *.* B:")
      
      
      multiply(integer variable,integer)
      
      Purpose: To multiply an integer variable by an integer.
      Action: Multiplies the integer variable by the specified integer and 
      puts the answer into the integer variable.
      Example: multiply(SizeOfFile,1024)
      Remarks: When the product of two numbers is outside the acceptable 
      range (-2,147,483,648 to +2,147,483,648), an invalid answer will result.

      
      open port("port name")
      
      Purpose: To choose which port on the PC is used.
      Action: Selects the port used for subsequent communications.
      T/F result: FALSE only if the specified port does not exist.
      Example: open port("COM2")
      Remarks: An argument of COM1 or COM2 is most common, but other port 
      names may be used under some circumstances. See Appendix A for a 
      discussion of other possible choices.
      
      
      option("7-BIT ASCII",yes/no)
      
      Purpose: To let you force incoming text to 7-bit ASCII.
      Action: Executing this with yes changes 8-bit characters, which might 
      otherwise appear as graphics characters, into normal 7-bit characters. 
      Executing it with no allows characters to appear as they are.
      Example: option("7-BIT ASCII",yes)
      Remarks: This is equivalent to Receiving text menu option "Force 
      incoming data to 7-bit ASCII".
      
      
      option("BLANK",yes/no)
      
      Purpose: To blank (prevent display of) subsequently received text, such 
      as passwords or other information you want to suppress.
      Action: Executing this with yes prevents subsequently received or typed 
      characters from displaying. Executing it with no ceases to blank 
      characters.
      Example: These lines would temporarily blank the display to allow a 
      local user to enter a password, which is then stored in a string 
      variable named Password:
      Remarks: There is no menu option equivalent to this. Option functions 
      can have lasting effects. Ending a script after using option("BLANK",
      yes) leaves blanking on. The same is true with every option function 
      that has no equivalent menu setting. Furthermore, option functions that 
      do have equivalent menu settings, will leave those settings permanently 
      changed, unless you first use option("TEMPORARY SETTINGS",yes).
      
      
      option("BLINK",yes/no)
      
      Purpose: To display prompts that blink.
      Action: Prompts displayed after executing this function with yes will 
      blink; prompts displayed after executing this with no do not blink.
      Example: option("BLINK",no)
      Remarks: There is no menu option equivalent to this.
      
      
      option("BOLD",yes/no)
      
      Purpose: To display prompts using bold characters.
      Action: Prompts displayed after executing this function with yes will 
      appear as bold characters; prompts displayed after executing this with 
      no are not bold.
      Example: option("BOLD",yes)
      Remarks: There is no menu option equivalent to this. On color monitors, 
      bold characters display in highlight color.
      
      
      option("BOTTOM LINE",yes/no)
      
      Purpose: To turn off the bottom line that normally displays on the Comm 
      screen.
      Action: Executing this with no stops the normal bottom line from 
      displaying on the Comm screen. Executing it with yes resumes display of 
      the normal bottom line.
      Example: option("BOTTOM LINE",no)
      Remarks: Execute this with no, prior to using "bottom line" to display 
      your own line. When the script ends, the bottom line returns to its 
      normal status (as set with the Comm screen "Display" and "Bottom-line" 
      options).
      
      
      option("DISPLAY ASCII",yes/no)
      
      Purpose: To display visible representations of screen control codes and 
      other characters which do not normally display.
      Action: Executing this with yes makes characters that don't normally 
      display appear as hex values in square brackets. Executing this with no 
      treats the characters normally.
      Example: option("DISPLAY ASCII",yes)
      Remarks: This is equivalent to Receiving menu option "Show hex values 
      of non-displaying characters".
      
      
      option("ECHO",yes/no)
      
      Purpose: To echo received characters back to the sender.
      Action: Executing this with "yes" causes subsequently received characters 
      to be echoed back to the remote system. Executing it with "no" ceases 
      to echo characters.
      Example: option("ECHO",yes)
      Remarks: This is equivalent to the Receiving menu option Echo "received 
      characters to sender".
      
      
      option("FDUPLEX",yes/no)
      
      Purpose: To switch from full duplex to half and vice versa.
      Action: Executing this with "yes" selects full duplex. Executing it with 
      "no" selects half duplex.
      Example: option("FDUPLEX",yes)
      Remarks: This is equivalent to the Sending text menu option "Duplex".
      
      
      option("IGNORE CASE",yes/no)
      
      Purpose: To set whether string matching and string manipulation functions 
      consider uppercase and lowercase letters to be different.
      Action: Executing this with "yes" makes subsequent string operations 
      disregard the case of letters. Executing it with "no" causes 
      differentiation of uppercase and lowercase letters.
      Example: option("IGNORE CASE",yes)
      Remarks: There is no menu option equivalent to this.
      
      
      option("LOCAL",yes/no)
      
      Purpose: To set whether the terminal emulator merely keeps and displays 
      keys that the user types (local mode), or sends them to the remote 
      system.
      Action: Toggles terminal emulator into and out of local mode.
      Example: option("LOCAL",yes)
      Remarks: There is no menu option equivalent to this.
      
      
      option("PRINT",yes/no)
      
      Purpose: To set whether text arriving on the Comm screen is also 
      directed to the printer.
      Action: Toggles printing on and off.
      Example: option("PRINT",yes)
      Remarks: This command has the same effect as "print begin" and "print 
      end".
      
      
      option("RECIEVE LINE FEEDS",yes/no)
      
      Purpose: To set whether your PC adds a line feed after each carriage 
      return in received text.
      Action: Executing this with "yes" adds line feeds to subsequently received 
      line ends. Executing it with "no" does not add line feeds.
      Example: option("RECEIVE LINE FEEDS",yes)
      Remarks: This is equivalent to the Receiving menu option "Append line 
      feeds to incoming line ends".
      
      
      option("RVIDEO",yes/no)
      
      Purpose: To display prompts in reverse video.
      Action: Executing this with "yes" causes prompts subsequently to appear 
      in reverse video. Executing it with "no" stops reverse video display.
      Example: option("RVIDEO",no)
      Remarks: There is no menu option equivalent to this.
      
      
      option("SEND LINE FEEDS",yes/no)
      
      Purpose: To set whether your PC when sending files with Text protocol 
      also sends the line feeds that occur in files.
      Action: Executing this with "yes" sends line feeds. Executing it with 
      "no" does not send line feeds.
      Example: option("SEND LINE FEEDS",yes)
      Remarks: This is equivalent to the Sending text menu option "Send lines 
      with line feeds".
      
      
      option("TEMPORARY SETTINGS",yes/no)
      
      Purpose: To cause menu setting changes made with "option" and "setting" 
      functions to be temporary.
      Action: Executing this with "yes" makes changes to menu settings last 
      only until another group of system settings is loaded, or until the 
      present group is reloaded. Executing this with "no" (or never executing 
      it at all), causes setting changes made with "option" and "setting" 
      functions to be stored permanently with the currently loaded system 
      settings.
      Example: option("TEMPORARY SETTINGS",yes)
      Remarks: There is no menu option equivalent to this. Because its 
      effects do not carry over from one script to the next, you must include 
      this in every script that makes settings which you want to be only 
      temporary.
      
      
      option("TENTHS",yes/no)
      
      Purpose: To set whether time values are tenths of seconds or seconds.
      Action: Executing this with "yes" causes time values expressed in 
      subsequent functions to be considered tenths of seconds. Executing it 
      with "no" treats them as seconds.
      Example: option("TENTHS",no)
      Remarks: There is no menu option equivalent to this.
      
      
      option("USE LINE WAIT",yes/no)
      
      Purpose: To set whether your PC, when sending files with Text protocol, 
      waits for each line to echo before sending the next.
      Action: Executing this with "yes" waits for each carriage return to be 
      echoed. Executing it with "no" does not wait.
      Example: option("USE LINE WAIT",yes)
      Remarks: This is equivalent to setting the Sending text menu option 
      "Wait for this character after sending each line" to "0Dh".
      
  
      option("USE MENU COLORS",yes/no)
      
      Purpose: To set whether characters displayed on the Comm screen will 
      use the same color scheme as the menus.
      Action: Executing this with yes causes subsequently displayed characters 
      to use the same foreground, background and highlight colors as the FreeComm 
      menus. Executing it with no causes subsequently displayed characters to 
      use the Comm screen colors.
      Example: option("USE MENU COLORS",yes)
      Remarks: This function (together with "draw box") lets you display 
      messages or prompts in boxes resembling the one that displays when you 
      press ALT-O on the Comm screen.
      
      
      option("WRAP LINES",yes/no)
      
      Purpose: To set whether lines received on the Comm screen that are wider 
      than the width of the screen are wrapped automatically.
      Action: Toggles line wrap on and off.
      Example: option("WRAP LINES",yes)
      Remarks: This is equivalent to the Receiving text menu option "Wrap lines 
      that exceed width of screen".
      
      
      option("XPROTOCOL",yes/no)
      
      Purpose: To set whether your PC uses XOFF/XON to control the flow of text 
      that is sent and received.
      Action: Executing this with "yes" uses XOFF/XON protocol. Executing it with 
      "no' does not use XOFF/XON.
      Example: option("XPROTOCOL",no)
      Remarks: This is equivalent to both the Sending text menu option 
      XOFF/XON to control sending and the Receiving text menu option 
      "XOFF/XON to control remote system".
      
      
      passord("password",detail number)                  T/F
      
     Purpose: To exchange data with the FreeComm program relating to Answer mode 
     callers and caller privileges.
     Action: When this function is executed (typically with a password 
     entered by someone who has just connected with Answer mode), data 
     relating to a caller is either extracted from the Password List, or 
     passed to Answer mode. Data from the Password List is placed in S(9). 
     The data exchanged and TRUE/FALSE result depend on the detail number.
     T/F result: See Remarks.
     Example: password("abracadabra",1)
     Remarks: Example gives a TRUE or FALSE which indicates whether the 
     password is valid, and puts the listed caller name into S(9). Here are 
     the effects of each detail number:
        
        Detail # T/F implies  S(9) contains
            0    no T/F result  no string (see below)
            1    password valid?     caller name
            2    password valid?     Yes/No for read privilege
            3    password valid?     Yes/No for write
            4    password valid?     Yes/No for overwrite
            5    password valid?     Yes/No for file management
            6    password valid?     Yes/No for printer access
            7    password valid?     Yes/No for DOS use
            10   password valid?     directory name
            11   callback access?    phone number
            12   logon scr/prg? scr/prg name
            13   next logon scr/prg? scr/prg name
            16   logoff scr/prg?     scr/prg name
            17   next logoff scr/pgm?     scr/prg name
            40   no T/F result  no string (see below)
            50   no T/F result  no string (see below)    
  
     This function is seldom used by scripts other than the ANSWER script, 
     which uses detail 1 to confirm passwords entered by callers. This lets 
     FreeComm determine for itself which privileges to grant callers, without
     ANSWER using details 2-7. If detail 1 returns no caller name, ANSWER 
     asks the caller his name, and uses "password("<caller name>",40)" to 
     pass it to FreeComm. When you press ESC to admit callers without passwords, 
     ANSWER uses password("",50) to make FreeComm grant full privileges. ANSWER 
     uses details 11-17 to determine callback, logon, and logoff procedures. 
     After the call, it uses password("",0) to reset for subsequent calls.
     
     
     pause(seconds)
     
     Purpose: To pause a number of seconds.
     Action: Pauses the specified number of seconds.
     Example: pause(15)
     Remarks: Often this is used after displaying a prompt and before clearing 
     it, so that the prompt stays on the screen for a set length of time. 
     When you need to pause to let a remote system complete an operation, 
     consider using wait seconds instead.
     
     
     position(row,column)
     
     Purpose: To position the cursor anywhere on your PC's screen except the 
     bottom line. (This is usually done to position a prompt which the script 
     will display subsequently.)
     Action: Moves the cursor to the specified location.
     Example: position(3,16)
     Remarks: The top row is considered row 1 and the leftmost column is 
     column 1. To put the cursor in the bottom line, use bottom line.
     
     
     print("string"{,add line end?})
     
     Purpose: To print strings or to insert notations into printouts.
     Action: Sends the string to your PC's printer. If the second argument is 
     yes or is omitted, a line feed and carriage return are sent to the 
     printer after each string; using no adds none.
     Example: print("Call received at /S(9)")
     Remarks: This can be used to print hard copy records of events, or to 
     insert notations or form feeds into text being received and printed. 
     (Also see "print begin".) You can also use "print" as a script debugging 
     tool:
       Include "print" statements at several points in the script to print 
       messages or contents of variables, then examine the printout after 
       each run, to locate problems.
     
     
     print begin()    T/F
     
     Purpose: To direct Comm screen text to your PC's printer.
     Action: Executing this causes text that arrives subsequently on the Comm 
     screen to be printed.
     T/F result: FALSE only if the print device cannot be opened.
     Example: print begin()
     Remarks: Be sure your printer is turned on before you use this. This uses 
     the printer configuration details defined on the Printer menu, which you 
     can reach from the System setting menu by selecting "Hardware" and then 
     "Printer".   
     
     
     print end() T/F
     
     Purpose: To stop printing text from the Comm screen and/or cause the 
     printer to eject a page.
     Action: Stops the flow of text from the Comm screen to the printer and 
     sends a form feed to the printer.
     T/F result: FALSE only if printing was not on in the first place.
     Example: print end()
     Remarks: If you want to stop printing without causing a page to eject, 
     use "print suspend" instead.
     
     
     print resume()   T/F
     
     Purpose: To resume passing text from the Comm screen to your PC's printer.
     Action: Executing this causes Comm screen text to resume printing.
     T/F result: FALSE only if printing was not suspended beforehand.
     Example: print resume()
     
     
     print suspend()  T/F
     
     Purpose: To stop Comm screen text from flowing to your PC's printer.
     Action: Executing this suspends the flow of text from the Comm screen to 
     your PC's printer.
     T/F result: FALSE only if printing was not on in the first place.
     Example: print suspend()
     Remarks: Use this instead of print end when you want to stop printing 
     without having your printer eject a page.
     
     
     prompt("string")
     
     Purpose: To display messages on your PC (without sending them).
     Action: Displays the string.
     Example: prompt("/nThis is displayed by a script.")
     
     
     put environment("name","string")     T/F
     
     Purpose: To facilitate sharing of information among scripts and programs, 
     this allows strings to be written to your operating system's environment.
     Action: Writes the name and the string into the environment. The name and 
     string together can total up to 127 characters.
     T/F result: FALSE only if there is insufficient space remaining in the 
     environment.
     Example: put environment("SYSTEM_NAME","/S(4)")
     Remarks: The environment is excellent for exchanging strings among 
     scripts. It is an area of memory containing strings which DOS makes 
     available to all programs; it is explained in your operating system 
     manual. To retrieve strings from the environment, use "get environment". 
     Strings put in the environment by scripts are automatically removed from 
     the environment when you quit FreeComm.
     
     
     quit({integer})
     
     Purpose: To stop running a script and quit FreeComm.
     Action: Ends the script and leaves FreeComm. If the optional integer 
     argument is included, FreeComm will pass its contents as a return code 
     (or error code) to the program or batch file from which FreeComm was 
     started.
     Example: quit()
     
     
     read from("filename"{,search path?}) T/F
     
     Purpose: To open a file from which the script can read strings.
     Action: Opens a file from which subsequent functions can read.
     T/F result: FALSE only if the file cannot be found.
     Example: read from("CALLER.LOG")
     Remarks: This allows files of text or text-like data to be opened for use 
     by a script. Only one file can be open for reading at a time; it is closed 
     automatically when you open another file or end the script. (Be sure to 
     close the file before writing to it with functions such as "write to"; to 
     close the file without opening another, use "read from("")". Include 
     "yes" as the second argument only if you want "read from" to search for 
     the file in locations defined with the operating system PATH command.
     
     
     read list(number of lines,"pattern")    T/F
     
     Purpose: To read data from a file into the list.
     Action: Copies lines from a file (previously opened using "read from") 
     into the list.
     T/F result: FALSE only if the pattern is not found or if no file is open 
     for reading. (It does not produce FALSE if fewer than the specified 
     number of lines exist.)
     Example: read list(3,"")
     Remarks: (For information regarding use of the list, refer to Section 
     1.21.) "read list" copies lines sequentially, starting at the beginning 
     of the file or at the point where a previous function left off. (To read
     lines prior to where the previous function left off, use "read from" to 
     re-open the file). read list can be used in these ways:
  
        1. Specify no pattern and a number greater than zero (see example 
           above) to copy that number of lines, beginning with the next line 
           in the file.
        
        2. Specify a pattern and a number greater than zero to copy that 
           number of lines, beginning with the line after the one which 
           contains the pattern.
        
        3. Specify a pattern and zero, to begin copying with the line after 
           the one which contains the pattern, and continue copying until the 
           next blank line or the end of the file.
        
        4. Specify no pattern and zero, to begin copying with the next line 
           and continue copying until a blank line or the end of the file.
  
         
       read prompt(number of lines,"pattern")  T/F
           
        Purpose: To read data from a file and display it directly on the PC's 
        screen.
        Action: Copies lines from a file (previously opened using "read from") 
        onto the PC's screen. (The lines are not sent.)
        T/F result: FALSE only if the pattern is not found or if no file has 
        been opened from which to read data. (It does not produce FALSE if 
        fewer than the specified number of lines exist.)
        Example: read prompt(24,"")
        Remarks: Use and operation of "read prompt" is identical to that of 
        read list, except that read prompt copies lines to the screen, not 
        the list. Refer to Remarks on "read list".
        
        
       read string(string variable,"pattern")  T/F
           
        Purpose: To read a line from a file for subsequent use in a script.
        Action: Copies a line from a file (previously opened using "read from") 
        into the string variable.
        T/F result: FALSE if the pattern is not found, if no file is open for 
        reading, or if the end of the file has been reached.
        Example: declare string Addressee
                 read string(Addressee,"John Doe")
        Remarks: "read string" copies lines sequentially, starting at the 
        beginning of the file or at the point where a previous function left 
        off. (To read lines prior to where the previous function left off, 
        re-open the file using "read from".) "read string" can be used in 
        these ways:
        
        1. Specify no pattern (use "") in order to copy the next line from 
           the file into the string variable.
        
        2. Do specify a pattern in order to copy the next line which contains 
           the pattern into the string variable.
        
  
       report("BAUD",integer variable)
           
       Purpose: To determine the current baud rate setting.
       Action: Puts the baud rate into the integer variable.
       Example: declare integer BaudRate report("BAUD",BaudRate)
        

       report("BOTTOM LINE",integer variable)  T/F
           
        Purpose: To find the current setting for the Comm screen bottom line 
        (accessed by pressing ALT-O and selecting Display, Bottom_line on the 
        Comm screen).
        Action: Places the value 1 in the integer variable if the current 
        setting is Yes, or 0 if it is No.
        T/F result: FALSE if the setting is No.
        
        report("DISK SPACE",integer variable)  T/F
           
           
        Purpose: To determine the amount of free disk space on a drive.
        Action: The drive whose number is specified in the integer variable 
        is checked and the number of kilobytes of disk space is then put back 
        into the integer variable.
        T/F result: FALSE if disk space is zero.
        Remarks: Use this table to determine which numbers to use:
  
                    Current drive              0
                    A:                         1
                    B:                         2
                    C:                         3
                    D:                         4
                    etc.                     etc.
      
      report("DISPLAY ASCII",integer variable) T/F
      
      
      Purpose: To find the setting for the Receiving text menu item "Show hex 
      values of non-displaying characters".
      Action: Places the value 1 in the integer variable if the setting is Yes, 
      or 0 if it is No.
      T/F result: FALSE if the setting is No.
      

      report("ERROR LINE",integer variable)
      
      Purpose: To find the line number of a script line which fails _ a line 
      which contains a T/F command that gives a False result, though the line 
      is not constructed as a conditional statement.
      Action: Places the line number in the integer variable.
      Remarks: This function may be used as described in section 1.24.
      
      
      report("FDUPLEX",integer variable)  T/F
      
      Purpose: To find whether the current setting is half or full duplex.
      Action: Places the value 1 in the integer variable if the setting is 
      currently full duplex, or 0 if it is half duplex.
      T/F result: FALSE if the setting is half duplex.
      
      
      report("FREE MEMORY",integer variable)
      
      Purpose: To find how much memory remains with FreeComm loaded.
      Action: Puts the number of kilobytes of memory remaining into the 
      integer variable.
      Example:   declare integer FreeRam
            report("FREE MEMORY",FreeRam)
      
      
      report("INGOING HHS",integer variable)   T/F
      
      Purpose: To determine the setting for the Standard comm port menu item 
      "Incoming hardware handshaking".
      Action: Puts one of the following numbers into the integer: 5 for CTS, 
      6 for DSR, 8 for CD, or 0 for none.
      T/F result: FALSE if "Incoming hardware handshaking" is set to nothing.
      
      
      report("INTERRUPT",integer variable)
      
      Purpose: To determine the comm port interrupt level currently selected.
      Action: Puts the comm port interrupt level into the integer variable.
      Example:   declare integer IntLevel
            report("INTERRUPT",IntLevel)
      
      
      report("MENU BACKGROUND COLOR",integer variable)
      
      Purpose: To determine menu color settings.
      Action: Copies the "Background color" setting from the Menu display 
      menu into the integer variable.
      Remarks: For color numbers, see "setting("BACKGROUND",number)".
      

      report("MENU FIRST LETTER COLOR",integer variable)
      
      Purpose: To determine menu color settings.
      Action: Copies the "First letter color" setting from the Menu display 
      menu into the integer variable.
      Remarks: For color numbers, see "setting("FOREGROUND",number)".
      
      
      report("MENU OUTLINE COLOR",integer variable)
      
      Purpose: To determine menu color settings.
      Action: Copies the "Outline color" setting from the Menu display menu 
      into the integer variable.
      Remarks: For color numbers, see "setting("FOREGROUND",number)".
      
      
      report("Menu Prompt Box Background Color",integer variable)
      
      Purpose: To determine menu color settings.
      Action: Copies the "Prompt box background color" setting from the Menu 
      display menu into the integer variable.
      Remarks: For color numbers, see "setting("BACKGROUND",number)".
      
      
      report("MENU TITLE COLOR",integer variable)
      
      Purpose: To determine menu color settings.
      Action: Copies the "Menu title color" setting from the Menu display 
      menu into the integer variable.
      Remarks: For color numbers, see "setting("FOREGROUND",number)".
      
      
      report("MICROCHANNEL",integer variable)  T/F
      
      Purpose: To determine if the PC is a PS/2 (or has a MicroChannel buss).
      Action: Puts a 1 in the integer variable if the PC has a Microchannel 
      buss, and a 0 if it does not.
      T/F result: FALSE only if the PC does not have MicroChannel buss.
      Example: if report("MICROCHANNEL") goto ConfigurePort
      Remarks: In scripts that display a range of possible ports and prompt 
      the user for a selection, you first want to check for  MicroChannel 
      architecture, and display the broader range it supports (up to COM8).
      

      report("OPERATING SYSTEM",integer variable)
      
      Purpose: To find which operating system the PC is using.
      Action: Places a number corresponding to the operating system in the 
      integer variable; the number is 1 for DOS and 2 for OS/2.
      
      
      report ("OPERATING SYSTEM VERSION",integer variable)
      
      Purpose: To find which version of the operating system the PC is using.
      Action: Places a number corresponding to the operating system version 
      times 100 in the integer variable.  For example, version 1.31 of OS/2 
      would return a value of 131.
      
      
      report("OUTGOING HHS",integer variable)  T/F
      
      Purpose: To determine the setting of the Standard comm port menu item 
      "Outgoing hardware handshaking".
      Action: Puts one of the following numbers into the integer: 4 for RTS, 
      20 for DTR, or 0 for none.
      T/F result: FALSE if "Outgoing hardware handshaking" is set to nothing.
      
      
      report("PORT",integer variable)
      
      Purpose: To determine the current port selection.
      Action: Puts the number of the comm port into the integer variable.
      Example:   declare integer CommPort
            report("PORT",CommPort)
      

      report("RECEIVE LINE FEEDS",integer variable) T/F
      
      Purpose: To find the setting for the Receiving text menu item "Append 
      line feeds to incoming line ends".
      Action: Places the value 1 in the integer variable if the setting is 
      Yes, or 0 if it is No.
      T/F result: FALSE if the setting is No.
      

      report("SEND LINE FEEDS",integer variable)    T/F
      
      Purpose: To find the setting for the Sending text menu item "Send lines 
      with line feeds".
      Action: Places the value 1 in the integer variable if the setting is Yes, 
      or 0 if it is No.
      T/F result: FALSE if the setting is No.
      
      
      report("TRANSFER TIME",integer variable)
      
      Purpose: To determine the length of time a transfer took.
      Action: Puts the elapsed time in seconds into the integer variable.
      Example:   declare integer XferTime
            report("TRANSFER TIME",XferTime)
      

      restore secreen()    T/F
      
      Purpose: To allow text which has been saved from the screen (and 
      possibly overwritten subsequently by prompts or messages) to be 
      re-displayed.
      Action: Re-displays text which was last saved using "save screen"; 
      the current location of the cursor establishes where the upper-left 
      corner of the saved text will display.
      T/F result: FALSE only if no text was previously saved.
      Example: restore screen()
      

      right(string variable,number)
      
      Purpose: To extract desired text from a string.
      Action: Discards all of the string variable except the rightmost 
      specified number of characters. If the string variable contains fewer 
      than the specified number of characters, its contents remain intact.
      Example: right(FileName,3)
      
      
      run("sequence name") T/F
      
      Purpose: To run a macro, command or script from within a script.
      Action: Stores all variables and the list of the present script and 
      runs the macro, command or script. (The sequence name should not include 
      a filename extension.) When that macro, command or script completes, 
      execution of this script resumes with all variables and the list intact.
      T/F result: FALSE only if the sequence does not exist.
      Example: run("SENDMAIL /Input")
      Remarks: The Example runs a script (or command) and passes to it the 
      contents of a string variable named Input; see Section 1.22 for more 
      information.
      
      
      save screen(rows,columns) T/F
      
      Purpose: To save text (which may subsequently be overwritten by prompts 
      or messages) so it can be re-displayed later.
      Action: Saves the specified number of rows and columns of text extending 
      down and to the right from the cursor position.
      T/F result: FALSE only if there is insufficient memory for storage of 
      the text.
      Example: save screen(12,80)
      
      
      screen match("pattern",{number of lines})     T/F
      
      Purpose: To search text on the Comm screen for a particular pattern of 
      characters.
      Action: Searches the specified number of lines on the Comm screen for 
      the pattern, beginning with the line the cursor is on (which counts as 
      the first line) and progressing up the screen. Every line is searched, 
      not just those from the remote system. When the pattern is found, the 
      line containing it is copied into S(9), and the search ends. If you 
      leave out the second argument, the search extends to the top of the 
      screen.
      T/F result: FALSE only if the pattern is not found. If you specify that 
      it search beyond the physical limits of the screen, it does not give a 
      FALSE, it merely searches the lines that are visible.
      Example: screen match("CONNECT",24)
      Remarks: Since this literally searches the screen image, the pattern 
      cannot contain non-displaying characters, such as line feeds or carriage 
      returns. It can include ? as a wildcard. See Section 1.11 and 1.16 for 
      additional information.
      
      
      send characters("string")
      
      Purpose: To send characters or text to the remote system.
      Action: Sends the ASCII characters which comprise the string.
      Example: send characters("Press <ENTER> when done")
      Remarks: This function differs from the "type" function in that it sends 
      characters literally, without interpreting them as key names.  Hence, 
      in the example above, <ENTER> would be sent as < E N T E R >; if the 
      type function were used, the ENTER key's output would have been sent 
      instead.
      
      
      set flag(flag variable,true/false)
      
      Purpose: To set a flag "true" or "false".
      Action: Sets the flag to the specified state.
      Example: set flag(F(5),true)
      
      
      set integer(integer variable,integer)
      
      Purpose: To put an integer into a integer variable.
      Action: Puts the specified integer into the integer variable.
      Example:   declare integer FileCount
            set integer(FileCount,24)
      Remarks: This can be used to set one integer variable equal to another 
      integer variable. For example, "set integer(I(4),I(5))" sets I(4) equal 
      to I(5).
      
  
      set list("string")
      
      Purpose: To store strings into the list.
      Action: Puts the string into the list just below any other items already 
      in the list.
      T/F result: FALSE only if the list is full (128 items).
      Example: set list("Delrina/n")
      Remarks: For information regarding use of the list, refer to Section 1.21.
      
      
      set string(string variable,"string")
      
      Purpose: To store a string in a string variable.
      Action: Puts the string into the specified string variable.
      Example:   declare string Address
            set string(Address,"Monroe, MI 48161/n")
      Remarks: See Section 1.18 for additional information.
      
      
      set porttype("porttype")  T/F
      
      Purpose: To define the communications port type.
      Action: Same effect as selecting Communications port and selecting a port 
      type on the System settings menu.
      T/F result: FALSE only if the port type listed is invalid.
      Example:  set porttype("Shared OS/2 comm port")
      Remarks: The port type which you use in this function must exactly match 
      one of the port types which the System settings menu lists when you 
      select Communications port. After selecting a port type, you will need 
      to open the port using "open port".
      
      
      setting("BACKGROUND",NUMBER)   T/F
      
      Purpose: To set colors of the Comm screen.
      Action: Changes the background color to the number specified.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("BACKGROUND",0)
      Remarks: Equivalent to the Comm screen display menu setting "Background 
      color". You can use these color numbers:
  
                  Black                             0
                  Blue                              1
                  Green                             2
                  Cyan                              3
                  Red                               4
                  Magenta                           5
                  Brown                             6
                  White                             7
      
      
      
      setting functions will have lasting effects.
      Unless you first use option("TEMPORARY SETTINGS",yes), every setting 
      function you use will make a permanent change to the currently loaded 
      system settings.
      
      
      setting("BAUD",baud rate  T/F
      
      Purpose: To set the baud rate.
      Action: Changes the baud rate to the specified number.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("BAUD",1200)
      Remarks: Equivalent to "Rate" on the System settings menu.
      
      
      setting("DCD PIN",pin number)  T/F
      
      Purpose: To define which pin is monitored for the modem's DCD (or CD) 
      signal.
      Action: Causes FreeComm to monitor the pin whose number is specified.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("DCD PIN",8)
      Remarks: Equivalent to Port menu setting "Connect signal (CD) on pin". 
      The possible settings are 5, 6, and 8.
      

      setting("BOTTOM LINE BACKGROUND COLOR",number)     T/F
      
      Purpose: To set the colors of the bottom line.
      Action: Changes the color of the bottom line's background.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("BOTTOM LINE BACKGROUND COLOR",7)
      Remarks: Equivalent to the Bottom line display menu setting "Background 
      color". For color numbers, see "setting("BACKGROUND",number)".
      
      
      setting("BOTTOM LINE HIGHTLIGHT COLOR",number)     T/F
      
      Purpose: To set the colors of the bottom line.
      Action: Changes the color of highlighted characters.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("BOTTOM LINE HIGHLIGHT COLOR",14)
      Remarks: Equivalent to the Bottom line display menu setting "Highlighted 
      text color". For color numbers, see "setting("FOREGROUND",number)".
      
      
      setting("BOTTOM LINE NORMAL COLOR",number)    T/F
      
      Purpose: To set the colors of the bottom line.
      Action: Changes the color of normal foreground characters.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("BOTTOM LINE NORMAL COLOR",11)
      Remarks: Equivalent to the Bottom line display menu setting "Normal 
      text color". For color numbers, see "setting("FOREGROUND",number)".
      
      
      setting ("DATA BITS",number of bits)     T/F
      
      Purpose: To set the number of data bits comprising each ASCII character.
      Action: Sets data bits to 8, 7, 6, or 5.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("DATA BITS",7)
      Remarks: Equivalent to "Bits per character" on the System settings menu.
      
      
      setting("FOREGROUND",number)   T/F
      
      Purpose: To set the colors of the Comm screen.
      Action: Changes the foreground color to the number specified.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("FOREGROUND",11)
      Remarks: Equivalent to the Comm screen display menu setting "Normal 
      text color". Use these color numbers:
       
       black      0                                 
                  blue                              1
                  green                             2
                  cyan                              3
                  red                               4
                  magenta                           5
                  brown                             6
                  white                             7
                  gray                              8
                  bright blue                       9
                  bright green                      10
                  bright cyan                       11
                  bright red                        12
                  bright magenta                    13
                  bright brown                      14
                  bright white                      15
      

      setting("HANGUP PIN", pin number)   T/F
      
      Purpose: To define the pin used to make the modem hang up.
      Action: The output on the specified pin is toggled momentarily each 
      time hangup is used to make the modem disconnect.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("HANGUP PIN",20)
      Remarks: Equivalent to Port menu setting "Hangup signal is output on 
      pin(s)". The possible settings are 4 and 20.
      
      
      setting("HIGHLIGHT",color number)   T/F
      
      Purpose: To set the colors of the Comm screen.
      Action: Changes the highlight color to the number specified.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("HIGHLIGHT",14)
      Remarks: Equivalent to the Comm screen display menu setting "Highlight 
      text color". Use color numbers given in Remarks on 
      "setting("FOREGROUND")".
      
      
      setting("INCOMING HHS",pin number)  T/F
      
      Purpose: To define pins used for hardware handshaking.
      Action: The input on this pin is automatically monitored to determine when 
      your modem or the remote system wants your PC to stop sending.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("INCOMING HHS",5)
      Remarks: Use this only with modems or devices that support hardware 
      handshaking (most do not). This is equivalent to Port menu setting 
      "Incoming hardware handshaking" on pin(s). Possible arguments are 5 for 
      CTS, 6 for DSR, 8 for CD, or 0 for none.
      
      
      setting("INTERRUPT",interrupt number)    T/F
      
      Purpose: To define which port interrupt level is used.
      Action: Selects the interrupt level, which may be a number from 2 to 5 
      (corresponding to IRQ2 through IRQ5).
      T/F result: FALSE only if the second argument is an invalid setting.
      Example:   setting("PORT",3E8h)
            setting("INTERRUPT",4)
      Remarks: When using COM1 or COM2, it is unnecessary to define an 
      interrupt level using this function. See "Comm port selection" in 
      Appendix A for more information.
      
  
      setting("MENU BACKGROUND COLOR",number)  T/F
      
      Purpose: To set the colors of the menus.
      Action: Changes the color of the menus' background.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("MENU BACKGROUND COLOR",0)
      Remarks: Equivalent to the Menu display setting "Background color". For 
      color numbers, see "SETTING("BACKGROUND",NUMBER)".
      
      
      setting("MENU FIRST LETTER COLOR",number)     T/F
      
      Purpose: To set the colors of the menus.
      Action: Changes the color of the first letter of each option on the 
      menus.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("MENU FIRST LETTER COLOR",14)
      Remarks: Equivalent to the Menu display setting "First letter color". 
      For color numbers, see "setting("FOREGROUND",number)".
      
      
      setting("MENU OUTLINE COLOR",number)     T/F
      
      Purpose: To set the colors of the menus.
      Action: Changes the color of the outline encircling the menus.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("MENU OUTLINE COLOR",15)
      Remarks: Equivalent to the Menu display setting "Outline color". For 
      color numbers, see "setting("FOREGROUND",number)".
  
      
      setting("Menu Prompt Box Background Colot),number) T/F
      
      Purpose: To set the colors of the menus.
      Action: Changes the background color used in the menus' prompt box.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("MENU PROMPT BOX BACKGROUND COLOR",5)
      Remarks: Equivalent to the Menu display setting "Prompt box background 
      color". For color numbers, see "setting("BACKGROUND",number)".
  
      
      setting("MENU TITLE COLOR",number)  T/F
      
      Purpose: To set the colors of the menus.
      Action: Changes the color of the titles of the menus.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("MENU TITLE COLOR",11)
      Remarks: Equivalent to the Menu display setting "Menu title color". For 
      color numbers, see "setting("FOREGROUND",number)".
      
      
      setting("OUTGOING HHS",pin number)  T/F
      
      Purpose: To define pins used for hardware handshaking.
      Action: The output on the pin specified here is automatically toggled 
      when necessary, to stop your modem or the remote system from sending 
      data to your PC.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("OUTGOING HHS",4)
      Remarks: Use this only with modems or devices that support hardware 
      handshaking (most do not). This is equivalent to Port menu setting 
      "Outgoing hardware handshaking on pin(s)". Possible arguments are 4 for 
      RTS, 20 for DTR, or 0 for none.
      
      
      setting("PORT",port number)    T/F
      
      Purpose: To define which port is used for communications.
      Action: Selects the port name, which may be a number from 1 to 8 
      (corresponding to COM1 through COM8, or the hex address of the port 
      followed by h.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("PORT",2)
      Remarks: When selecting a comm port other than COM1 or COM2 on 
      non-Microchannel computers, you must also use the "setting("INTERRUPT")" 
      to select the desired interrupt.  See "Comm port selection" in Appendix 
      A for more information.
      
      
      setting("READY PIN",pin number)     T/F
      
      Purpose: To define the pin the PC uses to indicate to the modem that 
      the PC is ready.
      Action: The output on the pin specified here is held on continuously 
      (except for a moment each time hangup executes).
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("READY PIN",20)
      Remarks: Equivalent to Port menu setting "Hangup signal is output on 
      pin(s)". Possible arguments are 4 and 20.
      
      
      setting("STOP BITS",number of bits)      T/F
      
      Purpose: To set the number of stop bits accompanying each ASCII 
      character.
      Action: Sets stop bits to 1 or 2.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("STOP BITS",1)
      Remarks: Equivalent to "Stop bits" on the System settings menu.
      
      
      setting("STOP BITS",number of bits) T/F
      
      Purpose: To set the number of stop bits accompanying each 
      ASCII character.
      Action: Sets stop bits to 1 or 2.
      T/F result: FALSE only if the second argument is an invalid setting.
      Example: setting("STOP BITS",1)
      Remarks: Equivalent to "Stop bits" on the System settings menu.
      
      
      setting("WILDCARD",ascii number)    T/F  T/F
      
      Purpose: To change the wildcard character used to represent unknown or 
      unspecified characters in strings.
      Action: Sets the wildcard character to the character whose ASCII 
      decimal value is specified.
      Example: setting("WILDCARD",126)
      Remarks: The wildcard is ? (ASCII decimal value 63) unless you use this 
      function to define a new character. The example above defines ~ as the 
      wildcard character. See Appendix E for values of other characters.
      
      
      show(first item number,number of items)
      
      Purpose: To display items from the list.
      Action: Displays the specified number of items from the list on the PC's 
      screen, beginning with the specified item. Each line in the display 
      consists of a item's number, a colon, and then the item.
      Example: show(29,10)
      Remarks: (For information regarding use of the list, refer to Section 
      1.21.) The first item in the list is numbered 0 and the last is 127. 
      If the list contains fewer items than are specified in the second 
      argument, no error results and only those items that exist are displayed.

      
      slave(idle period)
      
      Purpose: To allow the local computer to act as a slave under the control 
      of the remote user.
      Action: Makes your PC respond to commands typed on the keyboard of a 
      remote computer. (See Appendix H for a list of commands.) Execution 
      continues with the next script line when the remote user enters QUIT, 
      types nothing for the number of minutes specified, or hangs up.
      Example: slave(10)
      Remarks: Your modem switches must be set as in Appendix A so that the 
      modem's CD (carrier detect) signal accurately reflects whether the 
      modem is connected with a remote modem.
      
      
      store system("system name")    T/F
      
      Purpose: To store the current settings.
      Action: Stores the current settings and options in the System List 
      under the specified system name. If there is already a system by that 
      name, its settings are overwritten.
      T/F result: FALSE only if the System List is full (2,000 systems).
      Example: store system("Brad's BBS")
      Remarks: To save current settings temporarily so the script can reload 
      them later, use "store system("/SAVE")". To reload them, use "load 
      system("/SAVE")".
      
      
      string match(string variable,"pattern")  T/F
      
      Purpose: To determine whether a certain pattern is present in a string 
      variable.
      Action: None except to produce a TRUE or FALSE result; the string 
      variable remains intact.
      T/F result: TRUE only if the pattern exists in the string variable.
      Example: string match(FileName,".OBJ")
      
      
      subtract(integer variable,integer)
      
      Purpose: To subtract one number from another.
      Action: Subtracts the integer from the integer variable and puts the 
      answer back into the integer variable.
      Example: subtract(I(0),6)
      
      
      synchronize(integer variable,timeout)    T/F
      
      Purpose: To adapt your PC's baud rate to that of a caller.
      Action: Determines the caller's baud rate, switches to it, and puts the 
      baud rate into the integer variable. (The caller may need to press ENTER 
      about once per second to aid synchronization process.)
      T/F result: TRUE when the baud rate is determined. FALSE if it cannot be 
      determined within the "timeout" (or, if "timeout" is omitted, within 30 
      seconds or the period defined with "change timeout").
      Example:   declare integer BaudRate
            if synchronize(BaudRate,60) goto SetBaudRate
      Remarks: synchronize can adapt to 300, 1200, 2400, 4800, 9600 or 19200 
      bps.
      
      
      time(string variable,integer variable)
      
      Purpose: To obtain the time of day from DOS.
      Action: Stores the time as an integer in the integer variable and as a 
      string in the string variable.
      Example:   DECLARE STRING TIMEDISPLAY
            DECLARE INTEGER TIMECOUNT
            TIME(TIMEDISPLAY,TIMECOUNT)
      Remarks: The integer stored in the integer variable is the number of 
      minutes since midnight. The string stored in the string variable has 
      the format HH:MM:SS.
      
      
      transter receive("filename","protocol")  T/F
      
      Purpose: To receive files from a remote system.
      Action: Receives a file (or files) using the specified protocol.
      T/F result: FALSE only if the transfer cannot complete, due to line 
      noise, loss of connection, insufficient disk space, etc.
      Example: transfer receive("//O C:\DFC","Xmodem")
      Remarks: (Before a script executes transfer receive, it must type 
      commands to the remote system to make it send files; see Section 1.12.) 
      The first argument specifies where the receive file(s) is stored and 
      can be a filename, drive, directory or "", which receives to current 
      working directory (see Section 3.3 for details). The second argument 
      specifies the protocol used and can be HyperProtocol, Zmodem, Ymodem, 
      G Ymodem, Kermit, Xmodem, 1K Xmodem or Compuserve B (see Appendix G for 
      details).
      Received files are automatically renamed if their names conflict with 
      existing files. If you want to have the incoming files overwrite 
      existing files, include //O with the filename, as shown in the example
      above. (See Section 3.6 for additional slash options.) When including 
      slash options in string arguments,
        you must use a double-slash, as explained at the end of Section 1.18.
      
      
      transfer send("filename","protocol) T/F
      
      Purpose: To send files to a remote system.
      Action: Sends a file (or files) using the specified protocol.
      T/F result: FALSE if the specified file cannot be found, or if the 
      transfer cannot complete, due to line noise, loss of connection, 
      insufficient disk space, etc.
      Example: transfer send("GRAPHICS.IMG","Ymodem")
      Remarks: (Before a script executes "transfer send", it must type 
      commands to the remote system to make it receive files; see Section 
      1.12.) The second argument specifies the protocol used and can be
      HyperProtocol, Zmodem, Ymodem, G Ymodem, Kermit, Xmodem, 1K Xmodem, 
      Compuserve B or Text.
      The first argument specifies which files are sent and can be any 
      filename, with or without wildcards and directory names (see Section 
      3.3 for details). You may also use the name of a file batch preceded by 
      //B, to send a pre-selected group of files. (See information in Section 
      3.5 and 3.6 regarding this and other slash options.) When including 
      slash options in string arguments, you must use a double-slash, as 
      explained at the end of Section 1.18.
      
      
      truncate(string variable,"pattern") T/F
      
      Purpose: To extract desired text from a string.
      Action: Discards from the string variable, the pattern and characters 
      to the right of the pattern.
      T/F result: FALSE only if the string variable doesn't contain the 
      pattern.
      Example: If the filename SAMPLE.EXT were stored in the string variable 
      "Name", you could use "truncate(Name,".EXT")" to strip the extension 
      from the file name, leaving only SAMPLE in "Name".
      Remarks: If the pattern is not found, the contents of the string 
      variable remain intact. If the pattern appears more than once, only the 
      leftmost occurrence is discarded. You can include ? as a wildcard in 
      the pattern. The "cut" function works exactly the same, except that it 
      discards text from the left-hand end of a string. To retain only a 
      specific number of characters from the right- or left-hand end of a 
      string, use "right" or "left" instead.
      
      
      type("keys"{,delay})
      
      Purpose: To type keys or characters to the remote system.
      Action: Sends the keys and characters just as though you typed them. 
      Omit the second argument for a delay between characters of 50 
      milliseconds, or include a different number of milliseconds.
      Example: type("send mail")
      Remarks: See Section 1.6 for instructions and examples.
      
      
      unique filename(string variable,"filename")
      
      Purpose: To create a new filename based on an old one.
      Action: Derives a unique filename from the specified filename and puts 
      it into the string variable.
      T/F result: FALSE only if the first argument contains unrecognized key 
      names enclosed by < and >.
      Example:   declare string NewFile
            unique filename(NewFile,"RCVMAIL.TXT")
      Remarks: Each execution of the above example would produce unique 
      filenames RCVMAIL0.TXT, RCVMAIL1.TXT, and so on, up to RCVMA999.TXT.
      
  
      uppercase(string variable,"string")
      
      Purpose: To convert a string to all uppercase letters.
      Action: Changes any lowercase letters in the string to uppercase, and 
      puts the resulting string into the string variable.
      Example: uppercase(S(0),"filename: /S(1)")
      Remarks: The example above would change "filename" and the contents of 
      string variable S(1) to uppercase and place the resulting string in 
      string variable S(0).
      

      wait activity({timeout})  T/F
      
      Purpose: To wait for characters to start arriving.
      Action: Waits for characters to begin arriving at the serial port.
      T/F result: FALSE only if no characters arrive in time.
      Remarks: After you've commanded a remote system to perform an operation 
      that generates no screen display for some time, you might want to use 
      this to wait for the first characters to arrive. After wait activity, 
      you normally use other wait commands to examine the text you're 
      receiving.
      
      Omitting timeout ...
      arguments from wait functions makes them wait up to 30 seconds (or the 
      length of time defined earlier using change timeout). To have wait 
      functions wait longer or shorter times, include the number of seconds.
      

      wait capture("pattern"{,timeout})   T/F
      
      Purpose: To stop capturing received text.
      Action: Waits for the pattern and stops capturing when it arrives; the 
      pattern and text after it are not put into the capture file.
      Example: wait capture("END OF MAIL")
      T/F result: FALSE only if the pattern is not received in time or if no 
      "capture begin" precedes wait capture.
      Remarks: (See Section 1.10 for examples.) When capturing large bodies 
      of text, be sure to use a timeout argument large enough for all the 
      text to have arrived.
      
      
      wait carrier(seconds{,timeout})     T/F
      
      Purpose: To detect when a call is connected.
      Action: Waits for the modem's carrier signal (CD or Carrier Detect) to 
      remain on for the specified number of seconds.
      T/F result: TRUE if the carrier signal either stays on for the specified 
      number of seconds, or comes on within the timeout period and stays on 
      for the specified number of seconds.
      Example: The following script lines could be used to await calls:
            WaitForCalls:
              ifnot wait carrier(2,30) goto WaitForCalls
      If the carrier doesn't go on and stay on within 30 seconds (indicating 
      that a call has connected), this branches back to "WaitForCalls" and w
      aits once more; subsequent lines execute only after a call connects.
      Remarks: For "wait carrier" to work, your modem switches must be set as 
      described in Appendix A for the modem to generate the carrier detect 
      (DCD) signal. Usually, a first argument of 1 to 3 is used. To wait for 
      calls indefinitely, use a huge second argument (the maximum is 
      2,147,483,648 seconds, about 68 years!), or put this function in a loop 
      so it executes repeatedly until a call arrives (see Example). During a 
      call, you can also use "wait carrier" periodically to confirm that the 
      connection still exists. In this case, use 0 for both arguments; wait 
      carrier produces an immediate TRUE or FALSE result, indicating whether 
      the carrier is still there.
      
      You can also use "wait carrier" to wait for the modem to disconnect 
      after you use "hangup()". For example, "wait carrier(5,1)" gives FALSE 
      the instant a modem disconnects, and gives TRUE only if it fails to 
      disconnect after 5 seconds.

      
      wait characters("characters"{timeout})   T/F
      
      Purpose: To wait for a series of characters (whether displayable or not) 
      which may be followed immediately by other characters.
      Action: Waits for the specified series of characters.
      T/F result: FALSE only if the characters are not received in time.
      Example: wait characters("/x1B[J")
      Remarks: This example waits for a VT100 screen control code (ESC[J, 
      which clears the screen). Don't use "wait" characters when other 
      functions are better suited: "wait text" is better when waiting for 
      strictly displayable characters, and "wait prompt" is better when 
      waiting for displayable or non-displayable characters followed by a 
      pause.
      
      
      wait echo("echoed text"{,timeout})  T/F
      
      Purpose: To wait for the echo of characters you have sent.
      Action: Waits for the specified series of displayable characters.
      T/F result: FALSE only if the characters are not received in time.
      Example: wait echo("send mail")
      Remarks: In full duplex communications, you can use this to accept the 
      echo of remote system commands you have sent with "type". The argument 
      "echoed text" should consist only of text that is echoed onto your 
      screen, not non-displayable characters such as /r, /n or codes 
      beginning with /x.
      
      
      wait key(string variable{,timeout}) T/F
      
      Purpose: To detect when a key is pressed at the local keyboard.
      Action: Waits for the user to press a key and puts that name of that 
      key into the string variable. Any text that arrives during this time is 
      allowed to flow directly onto the Comm screen.
      T/F result: FALSE only if no key is pressed within the timeout period.
      Example:   DECLARE STRING KEYNAME
            IF WAIT KEY(KEYNAME,1) GOTO EVALUATEKEY
      Remarks: If a non-alphanumeric key or key combination is pressed, the 
      string variable will contain its name within < and >.
      
      
      wait lines(number of lines{,timeout})    T/F
      
      Purpose: To wait for the cursor to move a number of lines.
      Action: Waits for the screen to scroll (or for the cursor to move down 
      or up) the specified number of lines.
      T/F result: FALSE if the cursor does not move the specified number of 
      lines in time.
      Example: if wait lines(3,15) goto SearchScreen
      Remarks: When you cannot wait for certain text with "wait prompt", 
      "wait characters" or "wait text" because the text ends with no 
      predictable pattern, perhaps you can wait for it with wait lines. 
      After wait lines, you may want to use screen match to examine the lines 
      that have displayed.
      
      
      wait lull(seconds{,timeout})   T/F
      
      Purpose: To wait for a lull in received text.
      Action: Waits for a lull of specified length, during which no characters 
      are received.
      T/F result: FALSE only if the lull does not occur in time.
      Remarks: This is generally used to wait for a large body of received 
      text to finish displaying. If the text ends with a predictable pattern 
      of characters, it is better to use "wait prompt", "wait characters", or 
      "wait text".
      
      
      wait nocarrier(seconds{,timeout})                  T/F
      
     Purpose: To detect when no call is connected.
     Action: Waits for the modem's carrier signal (CD or Carrier Detect) to 
     remain absent for the specified number of seconds.
     T/F result: TRUE if the carrier signal is absent for the specified 
     number of seconds within the timeout period.
     Example: The following routine uses this function to sense when toggling 
     DTR with hangup fails to disconnect, and resorts instead to issuing 
     software commands to the modem:
            hangup()
            if wait nocarrier(1,3) then
              end()
            else
              type("+++",100)
                             wait text("OK")
              type("ATH<ENTER>")
              end()
            endif
     Remarks: To have "wait nocarrier" produce an immediate TRUE or FALSE 
     which indicates whether carrier is absent at this instant, use arguments 
     of (0,0). To check for presence of carrier, use "wait carrier" instead.
     
     
     wait prompt("promptP{,timeout}) T/F
        
     Purpose: To wait for a prompt from the remote system.
     Action: Waits for a series of non-displayable or displayable characters 
     followed by a pause of at least 3 tenths of second.
     T/F result: FALSE only if the prompt is not received in time.
     Example: wait prompt("/x0D/x0A-> ")
     Remarks: This example waits for a carriage return and line feed followed 
     by ->. It can be used to wait for any pattern of characters, including 
     undisplayed control characters and screen control codes. You can use ? 
     in the argument as a wildcard. While "wait prompt" is the most frequently 
     used of the wait functions, it is better to use "wait characters" for 
     characters not followed by a pause, or wait text to wait for only 
     displayed characters.
     
     Don't use "wait prompt" to wait for text that is not followed immediately 
     by a pause. When you do use wait prompt, be sure you include the very 
     last characters that arrive prior to the pause, even if they are 
     non-displaying characters such as a carriage return and line feed (that 
     is, /x0D/x0A).
     
     
     wait seconds(seconds)
     
     Purpose: To wait a number of seconds (typically, so that a remote system 
     can display information on your screen).
     Action: Waits a number of seconds, during which any received information 
     is allowed to flow directly onto the PC's screen.
     Example: wait seconds(15)
     Remarks: Use this (or "wait tenths")if no other "wait" function applies. 
     Time is a poor way to keep in step with a remote system, because you must 
     wait longer than the longest delay the remote system may exhibit. If 
     conditions change or the system turns out to be slower than you 
     anticipated, your script will barge ahead even though the remote system 
     is not ready.
     

     wait tenths(tenths)
     
     Purpose: To wait a number of tenths of seconds (typically, so that a 
     remote system can display information on your screen).
     Action: Waits a number of tenths of seconds, during which any received 
     information is allowed to flow onto the PC's screen.
     Example: wait tenths(7)
     Remarks: See Remarks on "wait seconds".
     

     wait text("text"{,timeout})     T/F
        
     Purpose: To wait for a series of displayable characters to arrive.
     Action: Waits for the specified series of displayable characters. When 
     they arrive, those characters and any text to their left is put into 
     string variable S(9).
     T/F result: FALSE only if the text is not received in time.
     Example: wait text("A:",360)
     Remarks: The "text" argument should consist only of characters that 
     display on your screen, not non-displayable characters such as /r, /n or 
     codes beginning with /x. It can include ? as a wildcard. This allows only 
     information up to and including the specified text to display. 
     Information received after it (including the end of the line containing 
     the pattern itself) remains in a buffer until additional "wait" functions 
     let it display.
     
     
     watch({timout}) ... endwatch
     
     Purpose: To watch for any of several real-time events to occur.
     Action: Watches for events listed between "watch" and "endwatch". When an 
     event occurs, the function(s) associated with that event are executed, 
     and execution then resumes with statements after "endwatch". Execution 
     also resumes after "endwatch" when the timeout period elapses without 
     any of the events occurring.
     Example: This routine checks the electronic mail service discussed in 
     Section 1.10 for mail, and takes the appropriate steps:
              watch(10)
                event text("You have mail") then
                  wait prompt("Command: ")
                  type("send mail<ENTER>")
                  wait echo("send mail")
                          capture begin("MAIL.TXT")
                  wait capture("No more mail")
                event text("You have no mail")
                event nocarrier(2) then goto Disconnect
              endwatch
              wait prompt("Command: ")
              type("quit<ENTER>")
            Disconnect:
              hangup()
              end()
       Remarks: The general form of "watch" is:
                 watch({timeout})
                    event1 {then} {function1}
                      {statementblock1}
                    event2 {then} {function2}
                      {statementblock2}
                    eventN {then} {functionN}
                      {statementblockN}
                 endwatch
        You may list as many events as you like, using the single-line or 
        block form. In the single-line form, the event has one function to 
        its right. In the block form, the event has no functions to its right 
        but is followed by one or more statements. The word "then" is optional 
        in either form. In place of event1, event2, etc., use the following 
        special-purpose functions:
            event activity("timeout")
            event capture("pattern")
            event carrier(seconds)
            event characters("characters")
            event echo("echoed text")
            event key(string variable)
            event lines(number of lines)
            event lull(seconds)
            event nocarrier(seconds)
            event prompt("prompt")
            event text("text")
            event timeout()     
        For information on all but "event timeout", see the matching "wait" 
        function. (For example, for "event prompt" see "wait prompt".) Each 
        function checks for the same condition as the "wait" function, but 
        where the wait function works independently with its own timeout, 
        "event" functions work together within the timeout of the "watch" 
        function. If several events are simultaneously satisfied, only the 
        event listed first is detected. To detect when no event has been 
        satisfied, include "event timeout"; functions associated with it 
        execute only when watch times out. For an infinite timeout, use a 
        timeout value of 0. If there is a "watch" with no "endwatch", or 
        "endwatch" with no "watch", the compiler displays WATCH without 
        ENDWATCH, or ENDWATCH without WATCH. Avoid branching into a 
        "watch-endwatch" structure without executing the "watch" statement, 
        as this may cause run-time errors that are difficult to track down.
        Note that watch ends as soon as any one watched-for event occurs and 
        functions associated with that event execute. To watch for the events 
        repeatedly, you need to enclose watch within a while loop (as shown 
        in the example for the "while-endwhile" function, below).
        
        
        while ... endwhile
        
        Purpose: To execute a series of statements, as long as a given 
        condition is TRUE.
        Action: Executes the TRUE/FALSE function to the right of "while". If 
        that function is TRUE, any intervening statements are executed until 
        "endwhile" is encountered, which loops back and executes the function 
        to the right of while once more. If it is still TRUE, the process 
        repeats. If it is FALSE, execution resumes with statements following 
        "endwhile".
        Example: The following script demonstrates use of watch within a 
        while loop. For use with a host that displays text one page after 
        another, this routine types ENTER for each page, until the host runs
        out of text and displays a Command: prompt.
            while wait carrier(0,0)
              watch (300)
                event prompt("ENTER for more...") type("<ENTER>")
                event prompt("Command: ") goto EnterCommands
              endwatch
            endwhile
        Remarks: The general form of a while loop is:
                 while function1
                    statementblock
                 endwhile
        Any TRUE/FALSE function can be used as function1. If you use a "wait" 
        function, bear in mind that it executes again each time the loop 
        repeats, and execution pauses in the wait function each time for the 
        awaited event to occur again. (wait carrier in the example above is 
        an exception; when you use (0,0) arguments, it gives an immediate 
        TRUE or FALSE which tells whether you are still connected.)
        The statementblock can consist of as many lines as you like, and may 
        include other while loops. Each endwhile matches the most recent 
        while. If there is a while with no endwhile, or a endwhile with no 
        while, the compiler will display WHILE without ENDWHILE, or ENDWHILE 
        without WHILE. Avoid branching into the body of a while loop without 
        executing the while statement, as this may cause run-time errors that 
        are difficult to track down.
        
        
        wipe screens({rows}{,columns})
        
        Purpose: To clear the screen of the local computer.
        Action: Clears an area of the screen which extends to the right and 
        down from the cursor the specified number of columns and rows, and 
        leaves the cursor in the upper left corner of the area. If you omit 
        the arguments, the entire screen is cleared (except for the bottom 
        line).
        Example: wipe screen()
        Remarks: Prior to clearing the screen, you may want to use save 
        screen to save the current screen, so that you can redisplay it later 
        with restore screen.
        
        
        write("string"{,add line end?})   T/F
        
        Purpose: To append a string of text to a file.
        Action: Adds the string to the end of a file previously opened using 
        "write to".
        T/F result: FALSE only if no disk space remains or if no file is open 
        for writing.
        Example: write("J. Public called on 7-18-89")
        Remarks: You can use this to store information such as the duration 
        of calls, names of callers, or phone numbers. You can also use it to 
        insert information into a file that is currently open for saving. You 
        can use "write" as a script debugging tool as well: Include write 
        statements at several points in the script to write messages or 
        contents of variables, then examine the file after each run, to 
        locate problems. Omitting the second argument or using "yes" adds a 
        line feed and carriage return after writing each string; using "no" 
        adds none.
        
        
        write to("filename"{,search path?})    T/F
        
        Purpose: To open a file into which a script can write strings.
        Action: Opens a file into which subsequent functions can write 
        characters, words, phrases or other strings.
        T/F result: FALSE only if the file cannot be opened.
        Example: write to("CALL.LOG")
        Remarks: Include "yes" as the second argument only if you want "write 
        to" to search for the file in locations defined with the operating 
        system PATH command. If the file doesn't exist, it is created in the 
        default directory. Only one file can be open for writing at a time; 
        it is closed automatically when you open another file or end the 
        script.  write to can simultaneously have the same file open as 
        capture begin; this makes it possible to write strings into captured 
        text. (However, you must be sure to close the file before reading 
        from it with functions such as read from; to close the file without 
        opening another, use write to("").)