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

[00.10] ****  EXIT

 Default key:   Alt+X
 Description:   Exit {COMMO}.

 General form:

      {EXIT number}

           number
                The return code to be passed to DOS.  It may be tested with the
                IF ERRORLEVEL batch command.  Range is 0 to 255.

 Switches:

      D1 or D
           Drop DTR and RTS.  Dropping DTR will cause the modem to disconnect
           if it has been properly initialized (see "Setting Up Your Modem").

      D0
           Do not drop DTR and RTS.

           If the switch is absent, the current setting of the toggle will be
           used.  The toggle can be set in the Setup File or by using the Alt+T
           key command.

 Examples:

      {exit}
           No arguments (return code = 0).

      {exit 3}
           With return code.

      {exit-D}
           Drop DTR and RTS.


[00.20] ****  FILE

 Default key:   none
 Description:   Find or display directory information.

 General form:

      {FILE path\filespec}

           path\filespec
                The path and filespec (file mask) to be used for finding or
                displaying directory entries (filenames and subdirectories).
                The filespec may contain wildcards.

 Switches:

      X1 or X
           Find next matching entry.

      X0
           Find first matching entry (default).

      S1 or S
           Display a listing of filenames and subdirectories.

 Examples:

      {file c:\upload\*.*}
           Find first filename or subdirectory in the directory "c:\upload."

      {file-x}
           Find next filename or subdirectory.

      {file-s c:\upload\*.zip}
           Display all subdirectories and .ZIP files in the directory
           "c:\upload".


[00.30] ***  Getting file information: FILE, FILE-X

 The FILE function will find directory information about the files and
 subdirectories specified in "filespec."  The data will be made available in
 the following built-in variables:

      _ffn
           Filename or subdirectory name.  Subdirectory names will be preceded
           with a "\".  The parent directory is "\..".

      _ffs
           File size in bytes.

      _ffd
           File date.  The format will be as specified in Setup File item
           "dat".

      _fft
           File time.  The format will be as specified in Setup File item
           "tim".

 The FILE function must be executed without the "X" switch (or with X0) to
 initialize the directory.  This will also make available the first filename or
 subdirectory.  Subsequent executions (with the "X" switch) will make
 subsequent names available.

 Use the IFCOndition function to determine if a filename was made available.
 The first label ("true") will be taken if a filename was found;  the second
 label ("false") will be taken if no additional filenames are available.

 TIPS on using FILE, FILE-X:

  >   IMPORTANT!  Do not use IFEXist until all files have been found (it uses
      the same DOS file finding functions).

  >   The built-in variables will always contain the data for the last filename
      found.  If no filename has ever been found, the contents are
      unpredictable.


[00.40] ***  Selecting files: FILE-S

 The "S" switch is used when you want {COMMO} to display the names of the files
 in the specified directory.  Files may then be selected (tagged) for uploading
 or other purposes.  Tagged pathnames are appended to the file {SEND}.LST in
 the {COMMO} home directory (except when Esc is pressed).  Facilities are also
 provided for navigating, changing the filespec and editing the {SEND}.LST
 file.

 The Exit Code is set according to the user's action (keys are shown in Online
 Help) and the built-in variable "_ffn" contains returned information (when
 applicable).  The Exit Code appears in the variable "_err" and may also be
 tested with the IFERrorlevel function.  Exit Codes are as follows:

      0    The "finish" key has been pressed.

      1    The Escape key has been pressed.

      2    The "edit" key has been pressed.

      3    A new drive has been chosen (drive letter is in "_ffn").

      4    A new directory has been chosen (subdirectory name is in "_ffn" and
           is preceded by a "\";  the parent directory is "\..").

      5    A new file specification has been entered (filespec is in "_ffn",
           e.g., *.zip).

 TIPS on using FILE-S:

  >   Use {wind-k} to get a smooth display between invocations of FILE-S.

  >   When a clean list is desired, {SEND}.LST should be deleted prior to the
      first use of FILE-S.


[00.50] ****  FONFile

 Default key:   none
 Description:   Load a new Dialing Directory file.

 Example:

      {fonf local.fon}
           The Dialing Directory is replaced with the file LOCAL.FON.

 The current Dialing Directory file will be saved to disk if there are any
 outstanding changes.  Dialing marks in the new file will be erased if
 {cdm=yes} in the Setup File.


[00.60] ****  GETString

 Default key:   none
 Description:   Input a string from the modem to a variable.

 General form:

      {GETString name,count,label}

           name
                The name of the variable to which the string will be assigned.

           count
                The maximum number of data characters allowed.  A carriage
                return will always terminate input.  May be 1 to 240.  Default
                is 240.

           label
                A macro to GOTO if a carriage return is received and no
                characters have been entered (the string will be assigned as
                null).  If this argument is omitted, control will pass to the
                next function.

 Switches:

      A1 or A
           "Append" mode.  Characters will be appended to the variable.  If the
           current length of the variable is greater than the count in the
           second argument, a count of 240 will be assumed.

      A0
           The variable will be replaced (default).

      H1 or H
           "Hotkey" mode.  When the maximum number of characters has been
           entered, control will pass to the next function.

      H0
           Ignore all input after the maximum has been entered, except
           backspace and carriage return (default).

      I1 or I
           "Input" mode.  In this mode, characters from the modem will be
           ignored during the GETString (they will be buffered) and characters
           typed locally will not be sent to the remote.  This is another way
           to get local input (see also INPUt and INFOrm).  Echo Status from
           SETGet is ignored.

      I0
           Normal mode (default).

      P1 or P
           "Password" mode.  Asterisks will be echoed to the remote and local
           terminals in place of the received characters (Echo Status will be
           honored, see SETGet).

      P0
           Characters are echoed as received (default).

      R1 or R
           "Raw" mode.  A single character will be received and converted to a
           decimal number string.  All 256 character values are allowed.

      R0
           Normal GETString rules apply (default).

 Examples:

      {setget 60,timeout,y,^m^j}
           Set GETString parameters.

      {gets fonum,12,badinput}
           Get input to "fonum."

      {gets-p pword,20}
           Get a password.

      {gets-r char}
           Get an ASCII character value (0-255).

 TIPS on using GETString:

  >   Use SETGet to set important parameters for GETString.

  >   A carriage return (ASCII 13) terminates input.  The backspace character
      (ASCII 8) is used for simple editing.  ASCII 0 and 10 are ignored.  All
      other characters will be accepted.  Note that tab (ASCII 9) can cause
      problems in host macros.  Use RTRAn to filter tabs if necessary.

  >   GETString supports "tandem" input.  Characters entered at either end will
      be input to the string (and displayed at both ends if echo is on; see
      SETGet).  Turn on Local Echo to see text locally that is sent to the
      remote with SEND, ASCIiup, etc.

  >   Use the "H" switch and a character count of 1 for "hotkeys."

  >   Turn off echo (see SETGet) while waiting for the modem to answer (in host
      mode).  Some modems react poorly to characters being echoed when they are
      generating a response (such as "RING").

  >   Incoming characters displayed during a GETString function are not seen by
      subsequent SSLOok/CALOok/GOLOok/LOOKfor functions.

 See also SETGet, INPUt, INFOrm.


[00.70] ****  GOLOok

 Default key:   none
 Description:   GOTO a label when a string appears.

 General form:

      {GOLOok label,target}

           label
                A label to GOTO when the target is received from the serial
                port.

           target
                The ASCII string to look for.  The string begins following the
                "," and is terminated by the "}".

 GOLOok is used in conjunction with the LOOKfor function.  It sets up an
 additional string to look for.  When the target string appears, control will
 pass to the label.

 See LOOKfor for details, examples and tips on using GOLOok.

 See also SSLOok, CALOok, SETLook.


[00.80] ****  GOTO

 Default key:   none
 Description:   Transfer control of macro execution.

 General form:

      {GOTO label,filename}

           label
                The label to which control will be transferred.

           filename
                The name of the Macro File where the label is to be found.
                This argument is OPTIONAL and is normally used only if the file
                is not already loaded.  Do NOT specify a path; the {COMMO} home
                directory will be used.

 Switches:

      F1 or F
           Force loading of the specified file (as the auxiliary file).  No
           filename comparison will be made.

      F0
           Compare filenames.  If the file is already loaded (resident or
           auxiliary), it will not be reloaded (default).

 Examples:

      {goto mail_run}
           Control transferred to label "mail_run".

      {goto mail_run,ginger.mac}
           Control transferred to label "mail_run" in the auxiliary Macro File
           "ginger.mac".

      {goto ,ginger.mac}
           The auxiliary Macro File "ginger.mac" is loaded; macro execution
           STOPs (no label given).

 If a filename is specified, {COMMO} will check to see if the file is already
 loaded (resident or auxiliary).  If not, the file will be loaded as the
 auxiliary (the current auxiliary will be saved to disk if there are any
 outstanding changes).

 TIPS on using GOTO:

  >   It isn't necessary to specify a filename if the target label is in the
      resident Macro File or in the current auxiliary file.

  >   A Macro Error will result if either the label or the file do not exist.

  >   If the label is not found in the auxiliary Macro File, {COMMO} will also
      search the resident Macro File.

 See also CALL, UNLOad, "{COMMO} Support Files."


[00.90] ****  HANGup

 Default key:   Alt+H
 Description:   Disconnect by dropping DTR.

 Examples:

      {hangup}
           Prompt user for disconnect.

      {hangup y}
           Disconnect without prompting.


[01.00] ****  HELP

 Default key:   F1
 Description:   Open Online Help window.

 Switches:

      C1 or C
           Load and display a Contents file.

      C0
           Load a Contents file (do not display).

 Examples:

      {help}
           Display the current Online Help topic.

      {help 10.20.30}
           Display topic "10.20.30".  {COMMO} will search for the topic code
           "[20.30]" in the file "DOC_10.HLP".

      {help 88}
           Load and display the Help file "DOC_88.HLP."  Do not search for a
           topic code.

      {help-c AA}
           Display Contents file DOC_AA.HLP.  This file will also be displayed
           when "C" is pressed in Online Help.

 NOTE: The Help codes in Contents files and the topic codes in Help files must
 be enclosed in square brackets.  If the left bracket is in column 1, {COMMO}
 will not display the code to the screen in Online Help.

 See also "F1  Online Help."


[01.10] ****  HOLD

 Default key:   none
 Description:   Hold until specified time of day (24 hour format).

 Examples:

      {hold 3:30}
           Hold until 3:30 am.

      {hold 16:10}
           Hold until 4:10 pm.

      {hold 0:00}
           Hold until midnight.

 NOTE: Incoming characters displayed during a HOLD function are not seen by
 subsequent SSLOok/CALOok/GOLOok/LOOKfor functions.


[01.20] ****  IFCArrier

 Default key:   none
 Description:   Test for presence of Carrier Detect signal.

 General form:

      {IFCArrier true,false}

           true
                A label to GOTO or CALL if carrier is detected.

           false
                A label to GOTO or CALL if carrier is not detected.

 NOTE: If a target label is omitted (null), control will pass to the next
 function.

 Switches:

      C1 or C
           A CALL is performed on the label.  When the CALLed routine RETUrns,
           execution will continue following the IFCArrier.

      C0
           A GOTO is performed (default).

 Examples:

      {ifcarrier c10,c20}
           Using GOTO.

      {ifcarrier-c c10,c20}
           Using CALL.

 TIP on using IFCArrier:

  >   When using a loop to wait for a change in Carrier Detect, you should
      include a short pause in the loop if you want characters to display.  The
      following sequence will display incoming characters while waiting for
      Carrier Detect to drop:

           ... {:cd1} {pause 1} {ifcarrier cd1} ...

 See also NOCArrier.


[01.30] ****  IFCOndition

 Default key:   none
 Description:   Test for conditions set by other functions.

 General form:

      {IFCOndition true,false}

           true
                A label to GOTO or CALL if the Condition Flag is true.

           false
                A label to GOTO or CALL if the Condition Flag is false.

 NOTE: If a target label is omitted (null), control will pass to the next
 function.

 Numeric switches:

      no switches present
           Test the current state of the Condition Flag.

      E1 or E
           Test for numeric equality.  A numeric string contains only the
           digits 0-9 and is in the range 0 to 65535.

      L1 or L
           Numeric test -- if first COMPare argument is less than the second.

      G1 or G
           Numeric test -- if first COMPare argument is greater than the
           second.

 Other switches:

      C1 or C
           A CALL is performed on the label.  When the CALLed routine RETUrns,
           execution will continue following the IFCOndition.

      C0
           A GOTO is performed (default).

 Examples:

      {compare var1,message}
      {ifcondit match,nomatch}
           Compare and set Condition Flag.  GOTO "match" if the variable "var1"
           is set to "message," to "nomatch" if it is not.

      {compare value,200}
      {ifcon-GEC toobig,aok}
           Compare and set conditions.  CALL "toobig" if "value" is greater
           than or equal to 200, else CALL "aok."

      {instring zipcode,90}
      {ifcon yes,no}
           Test if "zipcode" contains the digits "90".  If "true" GOTO "yes",
           if "false" GOTO "no".

 Switches may be used in any combination.  If any numeric switches are present,
 the Condition Flag is not tested.

 The difference between testing for string equality and numeric equality is
 shown in this example:

      The strings "05" and "5" are different text strings, but are numerically
      equal.


[01.40] ****  IFERrorlevel

 Default key:   none
 Description:   Test the Exit Code set by certain functions.

 General form:

      {IFERrorlevel number,true,false}

           number
                A number from 0 to 255.  It will be compared to the last Exit
                Code that was set.

           true
                A label to GOTO or CALL if the Exit Code is greater than or
                equal to "number."

           false
                A label to GOTO or CALL if the Exit Code is less than "number."

 NOTE: If a target label is omitted (null), control will pass to the next
 function.

 Switches:

      C1 or C
           A CALL is performed on the label.  When the CALLed routine RETUrns,
           execution will continue following the IFERrorlevel.

      C0
           A GOTO is performed (default).

 Examples:

      {iferror 1,abc,def}
           GOTO "abc" if Exit Code is greater than or equal to 1.  Else GOTO
           def.

      {ifer-c 2,gtr2}
           CALL "gtr2" if Exit Code is greater than or equal to 2  Else
           continue.

 TIPS on using IFERrorlevel:

  >   The Exit Code is set by certain functions (e.g., EXECute-D, SHELl,
      RXMOdem, SXMOdem) and should normally be tested immediately following
      execution of those functions.

  >   EXECute without the "D" switch or Shell to DOS will normally set the Exit
      Code to 0.

  >   Many programs return an Exit Code greater than 0 when the result is
      unsuccessful.  HS/Link, for example, will return an Exit Code of 1 or
      higher if the file transfer has failed.

  >   The value of the Exit Code is also stored in the string variable "_err"
      and may be tested with COMPare.


[01.50] ****  IFEXist

 Default key:   none
 Description:   Test for existence of a disk file or files.

 General form:

      {IFEXist path\filename,true,false}

           path\filename
                A DOS path\filename.  If the path is omitted, the current
                directory will be used.  If wildcards are used the "true"
                condition will hold if any files match the specification.

           true
                A label to GOTO or CALL if the file exists.

           false
                A label to GOTO or CALL if no files match.

 NOTE: If a target label is omitted (null), control will pass to the next
 function.

 Switches:

      C1 or C
           A CALL is performed on the label.  When the CALLed routine RETUrns,
           execution will continue following the IFEXist.

      C0
           A GOTO is performed (default).

 Examples:

      {ifex-c a:file.xyz,,m20}
           CALL "m20" if not found.

      {ifex c:\data\words.txt,345}
           GOTO "345" if found.

      {ifex c:\ul\*.rep,a01,a02}
           Using a wildcard.


[01.60] ****  INCRement

 Default key:   none
 Description:   Add a number to a numeric variable.

 Examples:

      {incr count}
           Add 1 to the variable "count".

      {incr oranges,1234}
           Add 1234 to "oranges".

 The default for the second argument is 1.

 If either argument or the result is out of range, then the variable will be
 set to the string "ERROR".

 If the variable is not numeric, the results will be unpredictable.

 See also DECRement.


[01.70] ****  INFOrm

 Default key:   none
 Description:   Display an advisory message.

 General form:

      {INFOrm string}

           string
                Message to be displayed.

 Switches:

      Q1 or Q
           Query the user for a "Yes/No" response.  "Yes" will be the default
           if Enter is pressed.

           The Condition Flag will be set to "true" if the response is "yes".
           It will be set to "false" if the response is "no".  Test with
           IFCOndition.

      Q0
           Query the user for a "Yes/No" response.  "No" will be the default if
           Enter is pressed.  The Condition Flag is set as above.

      Dn
           Display the message for "n" seconds, then continue.  "n" may range
           from 0 to 999.  This switch is ignored if the "Q" switch is present.

      S2
           Make the "fail" sound as the message is displayed.  The sound is
           controlled with the "ers" item in the Setup File.

      S1 or S
           Make a warning sound (default).

      S0
           No sound will be made.

 Examples:

      {inform Press a key to continue}
           Wait for Esc.

      {info-qs0 Overwrite the file?}
           Yes/No response, no error sound.

      {info-d3 Login now in progress}
           Display message for 3 seconds, then continue.

 INFOrm will display a string in a pop-up box over the Terminal Screen.

 TIPS on using INFOrm:

  >   The string length is limited by the width of the screen.

  >   When the "Q" switch is used, Esc and Ctrl+Break will be ignored.

  >   The "D0" switch can be used in conjunction with WIND-K to leave a message
      on the screen during macro execution.

 See also INPUt, GETString.


[01.80] ****  INITmodem

 Default key:   Alt+O
 Description:   Send Modem Initialization String.

 Example:

      {init}
           No arguments


[01.90] ****  INPUt

 Default key:   none
 Description:   Input a string from the keyboard.

 General form:

      {INPUt name,prompt}

           name
                The name of a string variable.  The current value of this
                variable will appear in the input line.

           prompt
                A prompt string that will appear in the input window border.

 Switches:

      E0
           If Esc is pressed, macro execution will be terminated unless a label
           has been defined with SETEsc (default).

      E1 or E
           If Esc is pressed, continue macro processing and set the Condition
           Flag to "true" (set it to "false" if Enter is pressed).  Test with
           IFCOndition.

      Ln
           Length of the input field, "n" may range from 1 to 120 (default is
           60).

 Example:

      {input upfile,Enter a filename:}
           Input a string to the variable "upfile."

 If 0 data characters are entered, the variable will be set to null.

 See also GETString, INFOrm.


[02.00] ****  INSTring

 Default key:   none
 Description:   Find a string within a string, return its position.

 General form:

      {INSTring name,string}

           name
                The name of a variable (string to search in).

           string
                The string to search for.

 Example:

      {inst line,abc}
           The variable "line" is searched for the string "abc".

 INSTring will set the following:

  >   The Condition Flag will be set to "true" if the string is found, to
      "false" if the string is not found.  Test with IFCOndition, no
      switches.

  >   The starting position of the string will be returned in the built-in
      variable "_pos" (first character is "1").  "_pos" will be set to
      zero if the string is not found.


[02.10] ****  KEYStuff

 Default key:   none
 Description:   Put key codes into the keyboard buffer.

 Examples:

      {keys 1c0d}
           Put a carriage return into the keyboard buffer.

      {keys 1e41,6c00}
           Put an "A" in the keyboard buffer followed by Alt+F5.

 This function is usually used prior to EXECuting programs, batch files or DOS
 commands that require keys to be pressed.  It allows complete automation
 without operator intervention.

 TIPS on using KEYStuff:

  >   The key codes are given in hexadecimal (scan code/character code as
      received from the BIOS).  Press Alt+K in the Internal Editor to view any
      key code.

  >   One or more codes may be listed.  Do not insert extra spaces.

  >   Usually, when specifying an ASCII character, only the character code need
      be listed.  Thus the second example above could be written:

           {keys 41,6c00}


[02.20] ****  LENGth

 Default key:   none
 Description:   Determine the length of a string.

 Examples:

      {leng %line}
           Find the length of the string in the variable "line".

      {leng %line1%%line2}
           Find the combined length of "line1" and "line2".

 The length will be returned in the built-in variable "_len".  If the string is
 null, the length will be set to zero.


[02.30] ****  LIGHts

 Default key:   none
 Description:   Set Signal Lights toggle.

 Examples:

      {lights}
           Toggle Signal Lights on/off.

      {lights y}
           Turn on Signal Lights.

      {lights n}
           Turn off Signal Lights.


[02.40] ****  LOCAlecho

 Default key:   none
 Description:   Set Local Echo toggle.

 Examples:

      {local}
           Toggle Local Echo on/off.

      {local y}
           Turn on Local Echo.

      {local n}
           Turn off Local Echo.


[02.50] ****  LOOKfor

 Default key:   none
 Description:   Look for strings in the modem input stream.

 LOOKfor is used in conjunction with SSLOok, CALOok and GOLOok to scan for as
 many as 16 strings at the same time.  When SSLOok, CALOok and GOLOok set up
 additional strings to look for, the actual "looking" does not take place until
 the LOOKfor executes.

 Parameters controlling LOOKfor are set with the SETLook function and may be
 changed at any time with another SETLook.  See the description of the SETLook
 function for details.

 Examples using LOOKfor only:

      {lookfor first name?}
           Look for the string "first name?"

      {look ^(COMMO^)}
           Look for the string "{COMMO}".

      When the string comes in, control will pass to the next function.

 Example construct using SSLOok/CALOok/GOLOok/LOOKfor:

                {setlook 60,hng,3,n|}
                {setv ss_r,|}
                  ...
      {:start}
                {golook label-a,target1}
                {calook start,label-b,target2}
                {sslook ss_r,target3}
                {golook ,target4}
                {lookfor target5} {send answer5}
                {goto label-c}

      {:label-a}     {hangup y} {goto cancel}
      {:label-b}     {send answer2} {call subr} {return}
      {:label-c}          ...

      In this example {COMMO} will look for five target strings.

      When a target specified in any of the CALOok, GOLOok or LOOKfor functions
      is received, the LOOKfor is cancelled.  It may be set up again by going
      to "start".

      When the target specified in the SSLOok is received, the string in the
      variable will be transmitted to the serial port.  The LOOKfor will
      continue to look for the same targets.

      The GOLOok function for target1 will GOTO "label-a" when the string comes
      in.  In the example control will pass to "cancel" (macro not shown).

      If target2 comes in, the CALOok function will set "start" as the return
      point and then CALL "label-b".  When this routine RETUrns, control
      returns to "start" and the five string LOOKfor will be set up again.

      If target3 is received, the string in the variable "ss_r" will be sent
      (in this case, a carriage return) and looking will continue.

      The GOLOok for target4 has a null label and control will pass to the
      function following the LOOKfor if that string comes in.  The "," must be
      present.

      If target5 comes in, control will pass to the function following the
      LOOKfor.

 TIPS on creating LOOKfor strings:

  >   There should be just one space following the LOOKfor function name.  Any
      spaces beyond this point are part of the string.  The string ends at the
      right curly brace.

  >   SSLOok/CALOok/GOLOok/Auto Receive strings begin immediately after the
      comma delimiter.  There should be no spaces unless they are part of the
      string.

  >   Strings may be up to 32 characters in length (control characters like
      "^M" count as one).  Upper/lower case is ignored.

  >   ANSI control sequences are filtered if ANSI or VT102 emulation is
      enabled.

  >   Short strings may not be unique enough, long strings may not match if
      there is line noise.

  >   Rules for representing special characters in
      SSLOok/CALOok/GOLOok/LOOKfor/Auto Receive strings are given in "ASCII
      Character Representation."

  >   SSLOok, CALOok and GOLOok functions should immediately precede a LOOKfor
      (no string compares actually occur until the LOOKfor executes).  Up to 15
      SSLOok/CALOok/GOLOok strings may be used in addition to the LOOKfor (up
      to 16 strings total).

  >   Use FILTER Capture Mode to determine the prompt to look for.

  >   If two or more strings cause a match at the same time, the LAST such
      string listed is the one acted upon (for example, if "abcdef" and "def"
      are listed and the string "abcdef" comes in).

  >   When an SSLOok causes a string to be sent, the LOOKfor timeout timer is
      restarted.

 See also SSLOok, CALOok, GOLOok, SETLook.


