 {COMMO} (tm) Help  (C)Copyright 1989-1997 Fred P. Brucker  All Rights Reserved

[00.10] *****  Programming {COMMO} Macros (tutorial)

 IMPORTANT!  Please read this tutorial before you attempt to write any macros!
 The rules for writing {COMMO} macros are few in number, but must be followed
 carefully.

 Examples of more complex macro programming are given in the sample Macro File
 COMMO.MAC, in the supplied file SAMPLES.MAC and in the Host Mode macro.  A
 macro from SAMPLES.MAC is discussed in detail at the end of this section.

 The following pages assume familiarity with {COMMO}'s key commands and with
 other features of the program.  Since many macro functions have corresponding
 key commands, duplicate explanations will not be given here.  Refer to the
 description of the key command.


[00.20] ****  Overview

 {COMMO}'s Macro Files may contain any number of macros and are limited in size
 to 64k bytes each (total of 128k if auxiliary Macro File is used).

 Macros are "interpreted," which implies the following:

  >   Macros are not processed in any way until execution begins.  Rules for
      starting macros are listed under "Executing Macros" later in this
      section.

  >   Only macros within the currently loaded Macro File(s) are available for
      immediate use.

  >   Macros added or modified with the Internal Editor are ready for execution
      without additional processing.

 COMMO.MAC is the resident Macro File.  An auxiliary Macro File may be loaded
 (or replaced) at any time using the CALL and GOTO functions (or manually
 within the Macro File window).  See the individual descriptions of the CALL,
 GOTO and RETUrn functions for details.  See also "{COMMO} Support Files" for
 more information on Macro Files.

 Macro Files may be compiled to increase speed, to reduce size and to improve
 security of source code.  See "Alt+M  Macro File" for details.


[00.30] ****  Macro Structure

 Macros consist of a series of items enclosed in curly braces.  Multiple items
 may be placed on the same line, but a single item may not be split between
 lines.  Lines may be up to 255 characters in length and all text outside the
 curly braces is commentary and is ignored when macros are executing.

 There are two types of items: "functions" and "labels."

      Functions are action items.  Some are equivalent to {COMMO} key commands,
      such as DIAL, while others are unique to the macro language, such as
      SETVariable.

      Labels are macro entry points and may be placed anywhere within the Macro
      File.


[00.40] ****  Macro Functions

 Each macro function is described in detail later in this document.  See also
 "Macro Functions Listed by Class."

 The general form of any macro function is:

      {name-switches arg1,arg2,...,argn}

           name
                The function name describes the action to be performed and
                consists of four or more characters. Only the first four are
                significant and case is ignored.

           switches
                These are used to alter the operation of a function.  Each
                switch is a single letter and may be followed by a numeric
                value, usually "1" or "0" to indicate "yes" or "no"
                respectively.

                Switches have default interpretations when the numeric value is
                omitted, or when the switch is not present.

                Switches must be separated from the name with a hyphen (no
                intervening spaces).  They may be upper or lower case.

                See individual function descriptions for details (note that
                only certain functions have switches).

           args
                A SINGLE SPACE separates the arguments from the function name
                and switches.

                Individual arguments are separated with commas and may contain
                no extraneous spaces (all spaces are significant).

 NOTE: Curly braces may be represented within macro functions by using ^( for {
 and ^) for }.

 Examples:

      {send Hi, how are you?}

           This function sends the string "Hi, how are you?" to the modem.
           SEND has only one argument -- the string to send out.  Since the
           string is the last argument, it may contain commas and spaces.
           Quotes are not used to define strings.

      {ifcon-LE label1,label2}

           The IFCOndition function tests for conditions set by other
           functions, such as COMPare.  Here two switches are present, telling
           {COMMO} to test for less than or equal:

                L    Test for "less than."
                E    Test for "equal."

           The two arguments are labels to GOTO depending on the conditions.

           Notice that "name-switches" may be written in a number of different
           ways:

                ifco-LE  ifcondition-EL  ifcond-LE

      {asci-S0E1 path\filename}

           The ASCII Upload function will send the file indicated by
           "path\filename."  The switches override current settings and tell
           {COMMO}:

                S0   Do NOT strip linefeeds.
                E1   DO expand blank lines (may also be written "E").

      {sound}   {sound yes}

           The first function will TOGGLE Master Sound ON/OFF (since there is
           no argument).  The second will turn the sound ON.


 One very important function is the STOP function.  It is used to terminate
 macro execution and may appear in either its long form or short form:

      ... {stop}     long form
      ... {}         short form

 Macro execution continues until a STOP function is executed.  Be sure to use
 one or execution will continue into the next macro in the Macro File!


[00.50] ****  Macro Labels

 Labels are identifiers consisting of one or more characters.  When a label is
 defined, it must be preceded by a colon.  References to labels, such as {goto
 label}, do not require the colon.

 IMPORTANT!  {COMMO} always searches for labels from the beginning of the
 auxiliary Macro File (if one is loaded), then from the beginning of the
 resident Macro File.  This means that if a label is duplicated within the
 files, the first occurrence will be used.

 Only the first eight characters in a label are significant.  Case is ignored.
 All characters above ASCII 27 are allowed in labels except the following:

      colon           ":"
      space           " "
      comma           ","
      slash           "/"
      curly braces    "{" or "}"

 Examples:

      {:mailrun} {call login} ...

      {:start-here} {:another.entry} {send Begin now!} ...


 A number of three character labels are reserved and are called "key-labels."
 When the corresponding key is pressed from the Terminal Screen, {COMMO} will
 look for the key-label in the current Macro File(s).  If the key-label is
 found, macro execution will begin at that location.

 Any default key assignment may be overridden using a key-label.  For example,
 pressing Alt+D normally enters the Dialing Directory.  But suppose this line
 is in the Macro File:

      {:ald} {clear} {}

 Now pressing Alt+D will clear the screen.

 There are predefined key-labels and user-defined key-labels.  See "{COMMO}
 Macro Key-labels" for complete details.


[00.60] ****  Macro Variables

 {COMMO} maintains a String Variable Space in which variables appear in the
 form:

      name,string

           name
                An identifier consisting of one or more characters of which
                only the first eight are significant.  Case is ignored.  The
                following are the ONLY valid characters that may be used in a
                variable name:

                     "A" through "Z" (uppercase or lowercase)
                     "0" through "9"
                     "_" underscore

                All other characters will terminate the name.

           string
                A text string.  The string must not contain ASCII 0, 10 or 13
                (null/cr/lf).  If a string is set to null (0 characters), it is
                deleted from variable space.  Note the difference between the
                null character (ASCII 0) and a null string (0 characters).

                NOTE: Any variable not defined is considered to be null.

                Strings consisting of only the digits 0-9 and representing a
                decimal number from 0 to 4,294,967,295 (2^32-1) are also
                numeric variables.  There is no other difference between string
                and numeric variables.

                The maximum length of strings is 240 characters.

 The String Variable Space may be viewed from within the Macro File window.
 The amount of unused string space will also be shown.

 Once a variable is defined, it remains in String Variable Space until it is
 redefined or deleted (set to null).  Therefore variables should be deleted or
 re-used to prevent String Variable Space from becoming full.

 The default size of String Variable Space is 3072 bytes, but it may be
 adjusted with the "vsp" item in the Setup File or with the "/v" command line
 switch at program startup.  The valid range is from 1 to 64 kilobytes.  See
 also "Command Line Options."


[00.70] ***  How to Use Variables

 {COMMO} variables may be set (or "defined") in numerous ways:

  >   With the SET item in the Setup File.
  >   By various macro functions (e.g., SETVariable).
  >   By variable strings at the end of a Dialing Directory entry.
  >   During execution of certain program operations.

 Variables are used (or "referenced") in macro function arguments and in the
 telephone number field of the Dialing Directory.  See also "Alt+D  Dialing
 Directory."

 When a variable name appears, the string assigned to the name is substituted
 for the name.  If the variable is null, then the name is replaced with 0
 characters.  {COMMO} will expand the variables in a macro function before
 executing it.

 In order to distinguish variable names from other parts of function arguments,
 they must be preceded with a percent sign "%" (use two consecutive percent
 signs if a percent sign is needed in the data).

 The end of the variable name is indicated by another "%" or by the first
 character that is not allowed in a name (see list of characters above).


 A variable definition example:

      {setvar animal,Elephant} or {setvar %animal,Elephant}

           Notice that the "%" is not required (but is permitted) when the
           variable name is the first argument of a function that defines,
           modifies or tests the value of a variable.  Other such functions
           include INPUt, GETString, INCRement, DECRement, COMPare, SUBString,
           INSTring, READ.

           If the variable name itself needs to be a variable, then use two
           percent signs:

                {setv %%animal,Elephant}


 Variable usage example 1:

      {setvar animal,Elephant}
      {send %animal}
           Sends "Elephant" to the modem.
      {send animal}
           Sends "animal".
      {send %animal%s are large animals}
           Sends "Elephants are large animals".  Note that the trailing "%" is
           required here.

 Variable usage example 2:

      {setvar animal,Elephant}
      {setv creature,animal}
      {send creature}
           Sends "creature".
      {send %creature}
           Sends "animal".
      {setv %%creature,Giraffe}
      {send %animal}
           Sends "Giraffe".


 IMPORTANT!  Variables may NOT be substituted within the function name or
 switches.  They may be substituted anywhere else, even for the commas
 separating arguments.

 See "SETVariable" for additional examples and more ways to set
 variables.


[00.80] ***  Reserved Variables

 Certain variables have fixed names so that {COMMO} can find them whenever they
 are needed.  The names of these variables begin with an underscore character
 "_".  There are two types of reserved variables: "user-defined" and "built-in"
 (see "List of Reserved Variables").

 USER-DEFINED reserved variables are defined in the same way that you define
 ordinary variables -- in the Setup File using SET, or in a macro using
 functions such as SETVariable, INPUt, etc.  These variables define strings
 used by certain program features.  For example, the path\filename of the Usage
 Log is defined in the Setup File as follows:

      {set _uselog,c:\commo\commo.log}

 BUILT-IN variables are defined by {COMMO} based on current system
 parameters.  Examples are:

      _cap
           Current Capture File path\filename

      _tim
           Current time of day

 Any variable that starts with the same four characters as a built-in variable
 ("_" plus the next three) will be considered the same variable.  For example
 "_pas" may be written "_password" and "_yea" may be written "_year".

 {COMMO} will always search String Variable Space first when looking up the
 value of any variable.  This allows built-in variables to be overridden, but
 only when using their four character minimum names.  For example, to override
 the serial port number, you must use "_por", not "_port".


[00.90] ****  Executing Macros

 Macro execution may be started in any of the following ways:

  >   Open the Macro File window by pressing Alt+M.  Position the Selector Bar
      at the desired starting point and press Enter.  The macro will begin
      executing at the first macro label or function on the line.

      NOTE: Macros started with the Selector Bar do not need macro labels and
      may be started at any point within the macro.

  >   If a macro label is also a key-label, then you may press that key from
      the Terminal Screen.  Note that if the same key-label appears more than
      once, the first occurrence will be used.

  >   A macro may be linked to a Dialing Directory entry (Linked Macro).  In
      this case {COMMO} will GOTO the macro when a connection is established
      with that system (or optionally CALL it, see the DIAL function).

  >   A startup macro may be specified in the Setup File using the "mac" item.

  >   A startup macro may be specified on the command line with the switch
      "/:label".  This will override the Setup File macro.

  >   A macro may be an argument of another function such as CALL, GOTO, DIAL
      or SETLook.

 Some macro functions show their current action on the Status Line.  In
 addition, a "face" character near the middle of the Status Line indicates that
 a macro is executing.


[01.00] ****  Additional Macro Execution Rules

 Characters may be typed to the serial port during functions that wait
 (LOOKfor, GETString, PAUSe, HOLD, etc.).  Command keys (e.g., Alt+D) will be
 ignored during macro execution (except in Doorway Mode).

 Functions will execute IN SEQUENCE until one of the following conditions
 occurs:

  >   A CALL, GOTO, RETURn, STOP, EXIT, etc. is encountered.

  >   Control is transferred to an alternate macro from certain functions when
      a special condition occurs.  An example of this is the SETLook function.
      The alternate will execute when a subsequent LOOKfor times out.

  >   A Macro Error occurs (and SETR has not been executed).  This will bring
      up the Macro File window with the Selector Bar on the problem line.  The
      macro will be terminated.

  >   The end of a Macro File is reached.


[01.10] ****  Cancelling a Macro

 The Esc key is used to terminate macro execution.  To type an <esc> code
 (ASCII 27) to the remote during macro execution (without terminating the
 macro), press Ctrl+[ (Ctrl + left bracket).

 Current function execution may be terminated by pressing Ctrl+Break.  For
 example, this can be used to terminate a LOOKfor, PAUSe or HOLD prematurely.
 Macro execution will advance to the next function.

 If a macro contains a function that brings up a {COMMO} window (Dialing
 Directory, Capture File Options, etc.), then Esc will exit the window and
 execution continues with the next function.  To terminate macro execution from
 a window, press Ctrl+Break.

 NOTE: The SETEsc function may be used to help prevent accidental termination
 of macros.


[01.20] ****  A Macro Example in Detail

 The following macro example from SAMPLES.MAC can be used to log in to many
 types of Bulletin Board Systems.  This is a Linked Macro, so the label "login"
 would appear in the Dialing Directory macro field for each system that uses
 it.  When you dial and connect to one of the systems, {COMMO} will
 automatically GOTO the macro.

 The subroutine "gls" (generic login subroutine) can also be called from macros
 that perform mailruns and other BBS operations.

 Note that labels and functions may be placed side by side on the same line (up
 to 255 characters).  For purposes of this example each item is placed on its
 own line.

 The main routine at "login" performs some initial functions and then calls the
 subroutine at "gls".  The subroutine looks for various prompts, responds to
 them and returns after responding to the "password" prompt.


 {:login}
      The entry point.  All labels begin with a ":".

 {capture y,c:\commo\commo.cap}
      "y" means open the Capture File.  The path\filename of the file is
      specified here, otherwise the current Capture File (if one is defined)
      would be opened.

 {asci ,}
      Set ASCII Upload to "no pacing."

 {call gls}

      CALL the macro at "gls".  When the subroutine executes a RETUrn, control
      will come back here.

 {}
      STOP and resume manual operation in the Terminal Screen.  Without this
      STOP execution would continue into subsequent macros.  Remember that
      labels are "passed over" during sequential macro execution.

 {:gls}
      The entry point of the "gls" subroutine.

 {setlook 60,hng,10,|}
      This function specifies parameters that go into effect whenever a LOOKfor
      executes.  It tells {COMMO} to wait up to 60 seconds for the string (or
      strings) and to GOTO the label "hng" if none of the strings appear within
      that time.  The timer is restarted each time a LOOKfor begins to execute.

      This SETLook also specifies that a "|" (carriage return) should be sent
      to the modem whenever 10 seconds have elapsed and no characters are
      received.  This is used to respond to prompts that are not explicitly
      specified in SSLOoks/CALOoks/GOLOoks/LOOKfors (e.g., "Press any key to
      continue").

      Use this latter facility with care since a BBS may spend time processing
      and not actually be expecting input from the caller.  The carriage
      returns sent will accumulate and be used to satisfy later prompts,
      causing things to get out of "sync."  Adjust the 10 second timeout as
      needed.

 {setv ss_r,~|}
 {setv ss_yr,~y|}
      Variables are set for some common responses.  They will be used later by
      SSLOok functions.  For convenience, these variables may be defined in the
      Setup File (using the "set" keyword).

      SSLOoks, CALOoks and GOLOoks store strings to look for, but do not wait
      for the strings (only a LOOKfor can do the actual waiting).

 {:li1}
 {sslo ss_r,(enter)}
 {sslo ss_yr,graphics (enter)}
 {sslo ss_yr,is this correct}
      The SSLOoks will send the strings in the variables when the respective
      targets are received.  The looking for all of the stored strings then
      resumes.

 {calo li1,li2,first name}
 {calo li1,li3,last name}
      CALOoks will CALL the second label if the target string appears (the
      LOOKfor is terminated).  When the macro executes a RETUrn, control goes
      to the first label where all of the strings can be set up again.  Note
      that CALOoks are used here for demonstration.  SSLOoks could be used as
      well (and probably should be).

 {golo li1,;passwor}
      A GOLOok will set up a string and GOTO the label if the string appears
      (only one label is used).  In this example the specified string is to be
      ignored.  This was needed for a BBS that used the string
      "first;last;password" prior to the actual password prompt.

 {lookfor password}
      This is where the actual "looking" takes place.  Remember that SSLOoks,
      CALOoks and GOLOoks only cause strings to be stored but do not actually
      wait for the strings.

      The LOOKfor will wait for the string specified and also any other stored
      strings (up to 16 total).  If the string in the LOOKfor appears, control
      passes to the next macro function.

      "password" is assumed to be the last prompt in the login sequence.

 {send ~%_pas|}
      Control then passes here and the string is sent to the modem.  The tilde
      (~) causes a half-second delay before sending the password.  The password
      in the Dialing Directory entry was stored into the built-in variable
      "_pas" when dialing began.

      Finally, a carriage return (|) is sent.

 {return}
      This will RETUrn to the "login" macro.

 {:li2}
 {send ~Firstname|}
      Response to "first name".

 {return}

 {:li3}
 {send ~Lastname|}
      Response to "last name".

 {return}


