home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / BBS / BBS2DRAG.ZIP / ROBOC430.ZIP / SCRIPT.DOC < prev    next >
Text File  |  1995-02-10  |  70KB  |  1,960 lines
  1.  
  2.  
  3.         ┬─┬─────┐
  4.         │ │     │
  5.         │ ├───┬─┘ ┌┬──┐ ┬┬─┐  ┌┬──┐ ┌┬──┐ ┌┬──┐ ┌┬─┬─┐ ┌┬─┬─┐ (tm)
  6.         │ │   │   ││  │ │├─┴┐ ││  │ ││    ││  │ ││ │ │ ││ │ │
  7.         ┴─┴   ┴── └┴──┘ ┴┴──┘ └┴──┘ └┴──┘ └┴──┘ ┴┴ ┴ ┴ ┴┴ ┴ ┴
  8.                                                    ┬  ┌┐ ┌──┬┐
  9.         The ultimate tool for unattended           └──┤│   ─┼┤
  10.         BBS communications.                           └┘o└──┴┘
  11.  
  12.  
  13.                       ┌────────────────────────────┐
  14.                       │  Script Language Reference │
  15.                       └────────────────────────────┘
  16.  
  17.  
  18.  
  19.  
  20.                   (c) Copyright 1995, Parsons Consulting
  21.  
  22.  
  23.  
  24.  
  25.  
  26.           Table of Contents
  27.  
  28.  
  29.           ROBOCOMM 4.3 SCRIPT PROCESSING ...............................  1
  30.           INTRODUCTION .................................................  1
  31.           SCRIPT COMMENTS ..............................................  1
  32.           DOCUMENTATION SYNTAX .........................................  1
  33.           LABELS .......................................................  2
  34.           MACROS .......................................................  2
  35.           USER-DEFINED MACROS ..........................................  3
  36.           PARAMETERS ...................................................  3b
  37.           SCRIPT COMMANDS ..............................................  4
  38.           CAPTURE "<cFile>" [OVERWRITE | APPEND] .......................  4
  39.           CD "<cDirectory>" ............................................  5
  40.           CLEAR [WATCHES] ..............................................  5
  41.           CLOSE ........................................................  5
  42.           COPY "<cSource>" [TO "<cTarget>"] ............................  6
  43.           DEBUG ON|OFF .................................................  6
  44.           DELAY <nSeconds> .............................................  6
  45.           DISABLE <nWatch> .............................................  7
  46.           DOWNLOAD ["<cFileSpec>"] [USING "<cProtocol>"] ...............  7
  47.           ENABLE <nWatch> ..............................................  8
  48.           ERASE "<cFile>" ..............................................  9
  49.           EXIT <nReturnVal> ............................................  9
  50.           GOSUB <label> ................................................  9
  51.           GOTO <label> ................................................  10
  52.           HANGUP ......................................................  10
  53.           IF [NOT] <condition> ["<argument>"] <command> ...............  11
  54.           EMPTY .......................................................  11
  55.           EXIST .......................................................  11
  56.           DAY .........................................................  11
  57.           DIR .........................................................  11
  58.           CONNECTED ...................................................  12
  59.           ERRORLEVEL ..................................................  12
  60.           IMPORT ["A"|"D"] "<cFile>" [EXISTONLY] ......................  12
  61.           JOIN "<cConference>" ........................................  13
  62.           MD "<cDirectory>" ...........................................  13
  63.           MESSAGE "<cString>" .........................................  13
  64.           NOTES "<cFile>" .............................................  14
  65.           PARAMETER [nNumber] "<cPrompt>" .............................  14
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.  
  75.  
  76.  
  77.  
  78.  
  79.  
  80.  
  81.  
  82.  
  83.  
  84.  
  85.                                         - i -
  86.  
  87.  
  88.  
  89.  
  90.  
  91.           Table of Contents
  92.  
  93.  
  94.           PASSWORD "<cPassword>" ......................................  14
  95.           RD "<cDirectory>" ...........................................  14
  96.           RENAME "<cfile>" [TO] "<cNewName>" ..........................  15
  97.           RENUMBER "<cFile>" [<nCount>] ...............................  15
  98.           RETURN ......................................................  15
  99.           RUN "<cDosCommand>" [KEYBOARD "<cKeyString>"] ...............  16
  100.           SEND "<cString>" ............................................  20
  101.           SOUND <nFrequency> <nDuration> ..............................  21
  102.           STATISTICS "<cFile>" ........................................  22
  103.           TERMINAL ....................................................  22
  104.           TERSE ON|OFF ................................................  22
  105.           TIMEOUT <nSeconds> ..........................................  22
  106.           TITLE "<cString>" ...........................................  22
  107.           UPLOAD "<cFileSpec>" [USING "<cProtocol>"] ..................  23
  108.           VENUE <cVenueCode> ..........................................  23
  109.           WAITFOR "<cString>" [FAILURE <command>] .....................  24
  110.           WAITUNTIL ["<cTime>"] ["<cDate>"] ...........................  25
  111.           WHEN "<cString>" <command> ..................................  25
  112.  
  113.  
  114.  
  115.  
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.  
  141.  
  142.  
  143.  
  144.  
  145.                                        - ii -
  146.  
  147.  
  148.  
  149.  
  150.  
  151.  
  152.            I. Robocomm 4.3 Script Processing
  153.  
  154.                * INTRODUCTION
  155.  
  156.                  Robocomm's script processing system is a high level
  157.                  interpreted language designed to extend the automation
  158.                  capabilities of the software in instances where the
  159.                  pre-defined "Agenda Items" do not perform the service
  160.                  required.
  161.  
  162.                  If you have done any programming at all on the PC, even at
  163.                  the batch file level, then Robocomm's script language
  164.                  should be fairly intuitive and straight-forward.  The
  165.                  script commands are processed sequentially with the
  166.                  ability to jump to "labels" like DOS batch files using
  167.                  GOTO and GOSUB statements like BASIC programs.
  168.  
  169.                  Perhaps the most significant capability of the script
  170.                  language is its ability to prompt the user for an
  171.                  unlimited number of parameters from the agenda
  172.                  creation/editing screen.  This allows for a great deal of
  173.                  flexibility in the creation of "generic" scripts that will
  174.                  work on a wide variety of systems.  At the time the
  175.                  "Execute Script" agenda item is created, the script itself
  176.                  asks the user to supply any needed information that is
  177.                  specific to the script run, such as a door number or a
  178.                  file name.
  179.  
  180.                  In addition, all of the prompt definitions and other
  181.                  BBS-Specific information for each BBS can be accessed from
  182.                  within the script, allowing the script author to limit the
  183.                  amount of "hard coded" search text within the script.
  184.  
  185.                  What all of this means is that it is now possible for
  186.                  people to create their own generic "agenda items" with
  187.                  Robocomm's script language.  These scripts can then be
  188.                  distributed and run without modification by other Robocomm
  189.                  users!
  190.  
  191.  
  192.                * SCRIPT COMMENTS
  193.  
  194.                  You may place non-executable descriptive text anywhere you
  195.                  like within a script file, as long as it is on a line by
  196.                  itself and is preceded by a semicolon.
  197.  
  198.  
  199.                * DOCUMENTATION SYNTAX
  200.  
  201.  
  202.  
  203.  
  204.           _________________________________________________________________
  205.           Robocomm 4.3 - Script Language Reference                 Page: 1
  206.  
  207.  
  208.  
  209.  
  210.  
  211.  
  212.  
  213.  
  214.                  As you read through this documentation, places where a
  215.                  command argument is to be entered by the script author are
  216.                  indicated between angle brackets <like this>.  Text
  217.                  between angle brackets and also surrounded by quotation
  218.                  marks indicates that the script author is to input a word
  219.                  surrounded by quotation marks:
  220.  
  221.                  "<cFile>"  --> "robocomm.cap"
  222.  
  223.                  Reserved Words (or COMMANDS) appear in all UPPER CASE.
  224.                  Optional command arguments are surrounded by square
  225.                  brackets [LIKE THIS].  When a choice between one or more
  226.                  command arguments is required, all available options will
  227.                  be listed, separated by the pipe symbol.  Thus, an
  228.                  optional command argument with three choices will look
  229.                  like this:
  230.  
  231.                  [ SEVERAL | OPTIONAL | COMMANDS ]
  232.  
  233.  
  234.                * LABELS
  235.  
  236.                  Labels in Robocomm scripts are created by starting a line
  237.                  with a colon character.  Many script commands allow
  238.                  command control to quickly jump forward or backward within
  239.                  a script file be referencing a label name.  Labels must be
  240.                  on a line all by themselves.  Robocomm will use all text
  241.                  contained between the colon character and the first space
  242.                  or end of line as the label name.  The following are all
  243.                  examples of valid label lines:
  244.  
  245.                  :ERROR (something must have gone wrong)
  246.                  :start
  247.                  :This-Is-An-Example-Of-A-Very-Long-Label-Indeed!
  248.  
  249.  
  250.                * MACROS
  251.  
  252.                  Most commands ask for text to be supplied as an argument.
  253.                  Whenever that text is contained within quotes, several
  254.                  "macros" can be used with specific meanings.  All Robocomm
  255.                  script macros are indicated by surrounding text by percent
  256.                  signs.  At script run-time, these macros will be replaced
  257.                  with the appropriate text before being used by the
  258.                  specified script command.
  259.  
  260.  
  261.  
  262.  
  263.  
  264.           _________________________________________________________________
  265.           Robocomm 4.3 - Script Language Reference                 Page: 2
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.                  1. %ID% - Translated to the BBS ID of the currently
  274.                     connected BBS.
  275.  
  276.                  2. %QWKDIR% - Translated to the configured download
  277.                     directory for mail packets.
  278.  
  279.                  3. %REPDIR% - Translated to the configured directory for
  280.                     outgoing replies.
  281.  
  282.                  4. %DLDIR% - Translated to the configured file download
  283.                     directory.
  284.  
  285.                  5. %ULDIR% - Translated to the configured file upload
  286.                     directory.
  287.  
  288.                  6. %DOW% - Translated to three characters indicating the
  289.                     current day of the week:  MON,TUE,WED,THU,FRI,SAT,SUN
  290.  
  291.                  7. %DOM% - Translated to two numeric characters indicating
  292.                     the current day of the month.  Range 01-31.
  293.  
  294.                  8. %MONTH% - Translated to three characters indicating the
  295.                     current month:
  296.                     JAN,FEB,MAR,APR,MAY,JUN,JUL,AUG,SEP,OCT,NOV,DEC
  297.  
  298.                  9. %NMONTH% Translated to two numeric characters
  299.                     indicating the month of the year.
  300.  
  301.                 10. %YEAR% - Translated to 4 numeric characters indicating
  302.                     the current year, e.g. 1991
  303.  
  304.                 11. %BBS##% - Translated to field number ## from the
  305.                     Directory-BBS record for the currently connected BBS.
  306.                     See Appendix "A" for a complete list of the BBS##
  307.                     macros.
  308.  
  309.                     a) ## is the field from BBS40.DBF to return.
  310.  
  311.                 12. %P##% - Translated to the text parameter number ##,
  312.                     which was entered by the user when he/she created the
  313.                     currently running "execute script" agenda item.
  314.  
  315.                 13. %WC#% - Translated to Wildcat Command number #.
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.           _________________________________________________________________
  325.           Robocomm 4.3 - Script Language Reference                 Page: 3
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.                * USER DEFINED MACROS
  334.  
  335.                  You can also create your own user-defined script macros
  336.                  and store them in the Notes for the BBS system.
  337.                  (Select the Notes menu item from the Directory-BBS
  338.                  entry for a system to see/edit the notes).  To do this,
  339.                  simply add lines to the system's notes using the
  340.                  following form:
  341.  
  342.                      <MACRO>=<value>
  343.  
  344.                  These type of macros can be very useful for creating
  345.                  "generic" login scripts for PCB and Wildcat systems.
  346.                  For and example of this, see the TELNET.RS example
  347.                  script  supplied with Robocomm. This script can be used
  348.                  to connect to any BBS reachable via the Internet by
  349.                  loggining into an internet provider's shell account
  350.                  (Netcom, in this example) and executing TELNET to
  351.                  access the BBS.  The TELNET.RS script makes use of
  352.                  three user defined macros: LOGIN, PASSWORD and
  353.                  IPADDRESS.  Once you have specified the script as the
  354.                  login script on Robocomm's Directory-BBS screen, go to
  355.                  the notes and edit them to contain the macro names and
  356.                  values.  For example, you might include lines such as:
  357.  
  358.                      LOGIN=jsmith
  359.                      PASSWORD=g7y-fft
  360.                      IPADDRESS=199.67.41.2
  361.  
  362.                  Once the notes have been saved, whenever Robocomm is
  363.                  running any script on the BBS, and it encounters the
  364.                  %IPADDRESS%, %LOGIN% or %PASSWORD% user macros, it will
  365.                  look up the appropriate value in the BBS's notes and
  366.                  make the substitution accordingly.
  367.  
  368.  
  369.                * PARAMETERS
  370.  
  371.                  With Robocomm, you can set up scripts which prompt the
  372.                  user for input when an "Execute Script" agenda item is
  373.  
  374.  
  375.  
  376.  
  377.  
  378.  
  379.  
  380.  
  381.  
  382.  
  383.  
  384.           _________________________________________________________________
  385.           Robocomm 4.3 - Script Language Reference                 Page: 3b
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.                  being created.  To do this, simply embed a statement
  394.                  similar to the following in your script file:
  395.  
  396.                  PARAMETER "Enter your mother's maiden name:"
  397.  
  398.                  When the user is creating the agenda, Robocomm will pause
  399.                  and ask the question specified between the quotes on the
  400.                  parameter line.  The user will be allowed to enter up to
  401.                  128 characters of any type in response to the question.
  402.  
  403.                  To access the text input by the user, the script author
  404.                  embeds %P##% into his/her script file at any location
  405.                  where double quotes are to surround text. In the text
  406.                  above, ## represents the parameter number you wish to
  407.                  access.
  408.  
  409.                   Continuing our example, to send the user's mother maiden
  410.                  name to the BBS you would use the following script
  411.                  command:
  412.  
  413.                  SEND "%P1%
  414.  
  415.                  In the example above the number "1" is specified to access
  416.                  the parameter text input in response to the first
  417.                  PARAMETER statement which is contained in the file.  It is
  418.                  important to understand that Robocomm numbers the
  419.                  parameters so that they correspond to the same order as
  420.                  the PARAMETER statements within the text file.  For a
  421.                  working example of PARAMETERs, examine the file
  422.                  SET_PCB.RS.
  423.  
  424.  
  425.           II. Script Commands
  426.  
  427.                * CAPTURE "<cFile>" [OVERWRITE | APPEND]
  428.  
  429.                  Opens capture file <cFile> and closes any capture file
  430.                  previously opened.
  431.  
  432.                  Options:  If OVERWRITE is specified, then the contents of
  433.                  any existing <cFile> will be replaced with the captured
  434.                  data.  If APPEND is specified
  435.  
  436.                  Defaults:  <cFile> defaults to the current BBS ID with a
  437.                  CAP extension.  The file creation mode defaults to APPEND.
  438.  
  439.                  Example:
  440.  
  441.  
  442.  
  443.  
  444.           _________________________________________________________________
  445.           Robocomm 4.3 - Script Language Reference                 Page: 4
  446.  
  447.  
  448.  
  449.  
  450.  
  451.  
  452.  
  453.                     CAPTURE "\ROBOCOMM\LOGS\CHESSGAM.CAP" OVERWRITE
  454.  
  455.                  See Also:
  456.                     CLOSE
  457.  
  458.  
  459.                * CD "<cDirectory>"
  460.  
  461.                  Changes the current DOS drive and/or directory to
  462.                  <cDirectory>.
  463.  
  464.                  Note: The Robocomm home drive and directory is always
  465.                  restored upon termination of script processing.
  466.  
  467.                  Note: If the specified directory does not exist, Robocomm
  468.                  will make a log notation and abort the script processing.
  469.  
  470.                  Example:
  471.  
  472.                     CD "F:\TEMP\LISTS"
  473.  
  474.                  See Also:
  475.                     MD
  476.                     RD
  477.  
  478.  
  479.                * CLEAR [WATCHES]
  480.  
  481.                  Clears all text watches installed via the WHEN command.
  482.  
  483.                  Robocomm adds another watch item each time you issue the
  484.                  WHEN command from within a script.  Deactivating a watch
  485.                  with the DISABLE command does not actually remove it from
  486.                  the list of text items which are compared to all incoming
  487.                  text.  The CLEAR command should be used when you wish to
  488.                  discard the entire "watch list."  The next WHEN command
  489.                  issued after a CLEAR will install watch #1.
  490.  
  491.                  See Also:
  492.                     WHEN
  493.                     WAITFOR
  494.                     DISABLE
  495.                     ENABLE
  496.  
  497.  
  498.                * CLOSE
  499.  
  500.  
  501.  
  502.  
  503.  
  504.           _________________________________________________________________
  505.           Robocomm 4.3 - Script Language Reference                 Page: 5
  506.  
  507.  
  508.  
  509.  
  510.  
  511.  
  512.  
  513.                  Closes any open capture file started via the CAPTURE
  514.                  command.  If no capture file is currently active, the
  515.                  command is ignored.
  516.  
  517.                  See Also:
  518.                     CAPTURE
  519.  
  520.  
  521.                * COPY "<cSource>" [TO "<cTarget>"]
  522.  
  523.                  Copies the file <cSource> to <cTarget>.  If <cSource>
  524.                  cannot be opened or <cTarget> cannot be created a notation
  525.                  will be made in ROBOCOMM.LOG and script processing will be
  526.                  terminated.  If <cTarget> already exists when the copy
  527.                  begins, it will be replaced with the contents of
  528.                  <cSource>.  <cTarget> is optional, and if not specified,
  529.                  Robocomm will attempt to create a file with the same name
  530.                  as <cSource> in the current directory.
  531.  
  532.                  Note:  Attempting to COPY a currently open log or capture
  533.                  file is not possible and will result in the termination of
  534.                  script processing.
  535.  
  536.                  Examples:
  537.  
  538.                     COPY "C:\ROBOCOMM\GROUPONE.CAP"
  539.                  "C:\OLDCAPS\GROUPONE.CAP"
  540.                     COPY "%QWKDIR%%ID%.PTR"
  541.  
  542.                  See Also:
  543.                     ERASE
  544.                     RENAME
  545.  
  546.  
  547.                * DELAY <nSeconds>
  548.  
  549.                  Pauses all script processing for <nSeconds>.  No
  550.                  characters are read from the active communications port.
  551.                  Absolutely nothing happens, other than a not-so-dramatic
  552.                  pause.  Keep in mind that the BBS may still be sending
  553.                  characters to Robocomm.  If so, they will be stored in
  554.                  Robocomm's internal communications buffer until the end of
  555.                  the delay period.
  556.  
  557.                  Note: If you set a long delay period, keep in mind that
  558.                  Robocomm may appear to be "frozen" to some users because
  559.                  the timeout counter in the upper corner of the screen will
  560.                  not update.  If you are worried that some user may
  561.  
  562.  
  563.  
  564.           _________________________________________________________________
  565.           Robocomm 4.3 - Script Language Reference                 Page: 6
  566.  
  567.  
  568.                  over-react to this condition, consider placing a MESSAGE
  569.                  command to place a notation in the lower log window before
  570.                  the call to DELAY.
  571.  
  572.                  Example:
  573.  
  574.                     DELAY 10
  575.  
  576.                * DEBUG ON | OFF
  577.  
  578.                  Writes all lines of the executing script to the ROBOCOMM
  579.                  log file as it is executed.
  580.  
  581.  
  582.                * DISABLE <nWatch>
  583.  
  584.                  Temporarily disable a watch installed via the WHEN
  585.                  command.  The contents of watch number <nWatch> will not
  586.                  be compared against incoming text during subsequent
  587.                  WAITFOR processing.  The watch may be reactivated later
  588.                  with the ENABLE command.
  589.  
  590.                  Example:
  591.  
  592.                     DISABLE 5
  593.  
  594.                  See Also:
  595.                     WHEN
  596.                     WAITFOR
  597.                     ENABLE
  598.                     CLEAR WATCHES
  599.  
  600.  
  601.                * DOWNLOAD ["<cFileSpec>"] [USING "<cProtocol>"] [RESUMEOK |
  602.                  OVERWRITE]
  603.  
  604.                  Downloads a file to <cFileSpec> using <cProtocol>.
  605.  
  606.                  <cFileSpec> may be a complete filename or a download path.
  607.                  If the protocol you select is a batch protocol and the BBS
  608.                  sends a file of a different name than that specified in
  609.                  <cFileSpec>, Robocomm will attempt to rename the file to
  610.                  the specified name after the download is complete.
  611.                  <cFileSpec> defaults to the currently defined file
  612.                  download directory.
  613.  
  614.                  USING "<cProtocol>" is an optional parameter which
  615.                  specifies the protocol or batch file to use for the
  616.                  transfer.  All of Robocomm's internal protocols, "ZMODEM",
  617.                  "YMODEM","YMODEM-G", "ASCII" are valid values for
  618.                  <cProtocol>, as is the name any batch file which uses
  619.                  Robocomm's standard method for communicating with batch
  620.                  files.
  621.  
  622.  
  623.  
  624.           _________________________________________________________________
  625.           Robocomm 4.3 - Script Language Reference                 Page: 7
  626.  
  627.  
  628.  
  629.  
  630.  
  631.  
  632.  
  633.                  <cProtocol> defaults to the currently defined file
  634.                  download protocol.
  635.  
  636.                  If you are using Robocomm's internal ZMODEM protocol, you
  637.                  may inform the protocol that it is OK to attempt to resume
  638.                  an aborted transfer by adding the RESUMEOK directive to
  639.                  the DOWNLOAD command line.  The existing portion of the
  640.                  file will be verified with the sending file and a resume
  641.                  will be attempted if possible.
  642.  
  643.                  If you anticipate that the DOWNLOAD command will be
  644.                  receiving a file which already exists, then you may
  645.                  specify the OVERWRITE directive to replace the existing
  646.                  file with the file being downloaded.
  647.  
  648.                  Examples:
  649.  
  650.                     DOWNLOAD
  651.  
  652.                  This command will use the currently defined file download
  653.                  path and protocol to receive a file.
  654.  
  655.                     DOWNLOAD "%ULDIR%" USING "YMODEM-G"
  656.  
  657.                  Downloads files to your configured file upload directory
  658.                  using Robocomm's internal Ymodem-G.
  659.  
  660.                     DOWNLOAD USING "ROBORH"
  661.  
  662.                  Downloads files to the default file download directory
  663.                  using the HS/Link external batch protocol.
  664.  
  665.  
  666.  
  667.  
  668.                * ENABLE <nWatch>
  669.  
  670.                  Resume processing of a watch previously suspended with the
  671.                  DISABLE command.  If text read from the communications
  672.                  port during a WAITFOR matches the contents of watch number
  673.                  <nWatch> the previously indicated action will be executed.
  674.  
  675.                  Example:
  676.  
  677.                     ENABLE 3
  678.  
  679.                  See Also:
  680.                     WAITFOR
  681.  
  682.  
  683.  
  684.           _________________________________________________________________
  685.           Robocomm 4.3 - Script Language Reference                 Page: 8
  686.  
  687.  
  688.  
  689.  
  690.  
  691.  
  692.  
  693.                     WHEN
  694.                     DISABLE
  695.  
  696.  
  697.                * ERASE "<cFile>"
  698.  
  699.                  Erases <cFile> from disk.  No error is returned and script
  700.                  processing will continue normally if <cFile> does not
  701.                  exist.  If <cFile> does exist, it will be deleted.
  702.  
  703.  
  704.                * EXIT <nReturnVal>
  705.  
  706.                  Quits script processing and returns to the agenda control
  707.                  level.  If <nReturnVal> is greater than zero, a notation
  708.                  will be made in the log and the "Execute Script" agenda
  709.                  item will be marked with an exclamation mark.  The
  710.                  exclamation mark implies an error, and will prevent the
  711.                  agenda item from being deleted if it has "temporary"
  712.                  status.
  713.  
  714.                  <nReturnVal> defaults to zero.  If the script returns zero
  715.                  to the agenda processing module, the task will be marked
  716.                  as completed.  This means that if the "Execute Script"
  717.                  agenda item was temporary it will be removed from the
  718.                  agenda on its next "re-set" operation.
  719.  
  720.  
  721.                * GOSUB <label>
  722.  
  723.                  Branches control flow to the line following the specified
  724.                  <label>.  Control will remain at the specified level until
  725.                  a RETURN statement is encountered, at which time agenda
  726.                  processing will resume with the first valid command line
  727.                  immediately following the GOSUB statement.  GOSUBs may be
  728.                  nested 4096 levels deep.
  729.  
  730.                  Example:
  731.  
  732.                  The following script lines, would send "Robocomm 4.3" to
  733.                  the BBS:
  734.  
  735.                     GOSUB firstpart
  736.                        SEND "4.3"
  737.  
  738.                     :FIRSTPART
  739.                        SEND "Robocomm "
  740.                     RETURN
  741.  
  742.  
  743.  
  744.           _________________________________________________________________
  745.           Robocomm 4.3 - Script Language Reference                 Page: 9
  746.  
  747.  
  748.  
  749.  
  750.  
  751.  
  752.  
  753.  
  754.                  See Also:
  755.                     GOTO
  756.                     RETURN
  757.  
  758.  
  759.                * GOTO <label>
  760.  
  761.                  Pass the sauce.  Spaghetti code lives!  The ubiquitous
  762.                  GOTO command will branch script control to the line
  763.                  following the specified <label> and never  look back.
  764.                  It's up to you to keep track of where the program's going
  765.                  when you use GOTOs.
  766.  
  767.                  Example:  The following code produces an infinite loop,
  768.                  from which Robocomm will never recover without a loving
  769.                  keystroke from you.
  770.  
  771.                     :Label1
  772.                        Send "Even robots can get "
  773.                        GOTO Label3
  774.  
  775.                     :Label2
  776.                        Send "Dizzy!!! |"
  777.                        GOTO Label1
  778.  
  779.                     :Label3
  780.                        Send "a little bit "
  781.                        GOTO "Label2
  782.  
  783.                  NOTE: Pressing the F3 "Abort Agenda" or "F1" jump to
  784.                  terminal keys during a runaway script are your escape
  785.                  hatches in instances like these.
  786.  
  787.                  See Also:
  788.                     GOSUB
  789.                     Two Guys From Italy.
  790.  
  791.  
  792.                * HANGUP
  793.  
  794.                  Terminates the current connection by hanging up the modem.
  795.                  Script processing continues after the disconnection with
  796.                  the line following the hangup command.  If a WAITFOR
  797.                  command is issued subsequent to a disconnection, Robocomm
  798.                  will assume that you did not intend to drop carrier and
  799.                  will abort the current script.
  800.  
  801.  
  802.  
  803.  
  804.           _________________________________________________________________
  805.           Robocomm 4.3 - Script Language Reference                 Page: 10
  806.  
  807.  
  808.  
  809.  
  810.  
  811.  
  812.  
  813.                * IF [NOT] <condition> ["<argument>"] <command>
  814.  
  815.                  Evaluates <condition> and executes the script command
  816.                  <command> if it is true.  The optional NOT parameter may
  817.                  be added immediately following the keyword IF when you
  818.                  want to execute <command> only when <condition> is not
  819.                  true.
  820.  
  821.  
  822.                  1. EMPTY
  823.  
  824.                     Use this command to test the existence of a parameter.
  825.                     If a parameter is not passed (i.e. left blank on the
  826.                     agenda editing screen), then EMPTY will be true.
  827.  
  828.                     Examples:
  829.  
  830.                     IF EMPTY "%P1%" GOTO ERROR
  831.                     IF NOT EMPTY "%P2%" SEND "%P2%|"
  832.  
  833.  
  834.                  2. EXIST
  835.  
  836.                     Use this test for the existence of a file.
  837.  
  838.                     Examples:
  839.  
  840.                     IF EXIST "C:\QWKS\GROUPONE.KEY" GOTO SENDKEY
  841.                     IF NOT EXIST "%ID%.RLY" GOSUB GETMSGS
  842.                     IF EXIST "ALLFILES.ZIP" RENAME "ALLFILES.ZIP" TO
  843.                     "ALLFILES.OLD"
  844.  
  845.  
  846.                  3. DAY
  847.  
  848.                     Robocomm can test today's day of week with the use of
  849.                     any of these keywords.
  850.  
  851.                     Examples:
  852.  
  853.                     IF NOT DAY "SUN" GOTO WORK
  854.                     IF DAY "SUN" GOTO CHURCH
  855.                     IF DAY "MON" RENAME "BULL_1.CAP" TO "BULL_1.MON"
  856.  
  857.  
  858.                  4. DIR
  859.  
  860.  
  861.  
  862.  
  863.  
  864.           _________________________________________________________________
  865.           Robocomm 4.3 - Script Language Reference                 Page: 11
  866.  
  867.  
  868.  
  869.  
  870.                     Use this option test for the existence of a
  871.                     subdirectory on a disk.
  872.  
  873.                     Examples:
  874.  
  875.                     IF DIR C:\SCRIPTDIR\TEMP\ GOTO KILLDIR
  876.  
  877.                     IF NOT DIR \TEMP MD \TEMP
  878.  
  879.                  5. CONNECTED
  880.  
  881.                     Tests if the modem is currently connected with a BBS
  882.                     system.
  883.  
  884.                     Examples:
  885.  
  886.                     IF CONNECTED SEND "BYE|"
  887.                     IF NOT CONNECTED GOSUB CLEANUP
  888.  
  889.                  6. ERRORLEVEL
  890.  
  891.                     Tests to see is the last command executed with the RUN
  892.                     command set an errorlevel greater than zero.
  893.  
  894.                     IF ERRORLEVEL GOTO TRYAGAIN
  895.                     IF NOT ERRORLEVEL GOTO SUCCESS
  896.  
  897.                  7. YES
  898.  
  899.                     Checks to see if a parameter is equal to Y,y,YES,
  900.                     Yes or yes.
  901.  
  902.                     IF YES "%P3%" GOTO SENDREP
  903.  
  904.                * IMPORT ["A"|"D"] "<cFile>" [EXISTONLY]
  905.  
  906.                  This command allows you to import the <cFile> file listing
  907.                  into Robocomm's "Available Files" or "Downloaded Files"
  908.                  directory.  The optional letter "A" or "D" tells Robocomm
  909.                  which file directory to send the file names to.  By
  910.                  default Robocomm sends file listings to the "Available
  911.                  Files" directory.  The optional EXISTONLY clause tells
  912.                  Robocomm to only import those files that can be located in
  913.                  your configured download, upload or search directories.
  914.  
  915.                  Example:   IMPORT "D" "VAMPIRE.CAP" EXISTONLY
  916.  
  917.                  This command tells Robocomm to import VAMPIRE.CAP into the
  918.                  "D"ownloaded files directory, adding only those files to
  919.                  the directory that can be found in any of Robocomm's
  920.                  configured search directories.  NOTE: If you are
  921.                  creating a file list in a script, you can use the
  922.                  CONFSTAMP "<text>" script command to write the current
  923.                  conference marker to the capture file.
  924.           _________________________________________________________________
  925.           Robocomm 4.3 - Script Language Reference                 Page: 12
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.  
  933.  
  934.                     IMPORT "GIFS.CAP"
  935.  
  936.                  This command tells Robocomm to import the file GIFS.CAP
  937.                  into the available files directory.
  938.  
  939.  
  940.                * JOIN "<cConference>"
  941.  
  942.                  Attempts to join the conference specified, using the
  943.                  prompts defined on the Directory-BBS-Prompts screen for
  944.                  the currently connected BBS.  Script processing is aborted
  945.                  if the Join attempt is unsuccessful or cannot be verified.
  946.  
  947.                  Examples:
  948.  
  949.                     JOIN "0"
  950.  
  951.                  Attempts to navigate to the "Main Board" prompt.
  952.  
  953.                     JOIN "Robocomm"
  954.  
  955.                  Attempts to navigate to the "Robocomm Conference Command"
  956.                  prompt.
  957.  
  958.  
  959.                * MD "<cDirectory>"
  960.  
  961.                  Attempts to create a subdirectory named <cDirectory>.
  962.  
  963.                  Note: If the specified directory cannot be created,
  964.                  Robocomm will make a log notation and abort the script
  965.                  processing.
  966.  
  967.                  Example:
  968.  
  969.                     MD "C:\TEMPDOWN"
  970.  
  971.                  See Also:
  972.                     CD
  973.                     RD
  974.  
  975.  
  976.                * MESSAGE "<cString>"
  977.  
  978.                  Posts <cString> as a message in ROBOCOMM.LOG.
  979.  
  980.  
  981.  
  982.  
  983.  
  984.           _________________________________________________________________
  985.           Robocomm 4.3 - Script Language Reference                 Page: 13
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.                * NOTES "<cFile>"
  994.  
  995.                  This command places the contents of <cFile> into
  996.                  Robocomm's internal data structures so that the data can
  997.                  be viewed later via Robocomm's "Notes" command on the
  998.                  Directory-BBS screen.
  999.  
  1000.                  NOTE: Robocomm will not import a file longer than 10,240
  1001.                  characters.  Attempts to do so will be ignored.
  1002.  
  1003.                  Example:
  1004.  
  1005.                     NOTES "%ID%.NOT"
  1006.  
  1007.  
  1008.                * PARAMETER [nNumber] "<cPrompt>"
  1009.  
  1010.                  Defines a parameter question that will be used to prompt
  1011.                  the user for input at agenda creation time.  <cPrompt> may
  1012.                  be up to 40 characters in length.  The user will be
  1013.                  allowed to input up to 128 characters.
  1014.  
  1015.                  NOTE: The optional nNumber argument is really only for
  1016.                  readability purposes and is not examined by Robocomm at
  1017.                  all.  Robocomm numbers parameters sequentially, in the
  1018.                  order they are encountered within  the script file.
  1019.  
  1020.                  Example:
  1021.  
  1022.                  PARAMETER "Heard any good jokes lately?"
  1023.  
  1024.  
  1025.                * PASSWORD "<cPassword>"
  1026.  
  1027.                  Updates the password in the Directory-BBS record for the
  1028.                  current BBS with <cPassword>.
  1029.  
  1030.                  Example:
  1031.  
  1032.                     PASSWORD "NewPass"
  1033.  
  1034.  
  1035.                * RD "<cDirectory>"
  1036.  
  1037.                  Attempts to remove subdirectory <cDirectory>.  The
  1038.                  specified directory must be completely empty, with no
  1039.                  hidden files or subdirectories.
  1040.  
  1041.  
  1042.  
  1043.  
  1044.           _________________________________________________________________
  1045.           Robocomm 4.3 - Script Language Reference                 Page: 14
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.                  Note: If the specified directory cannot be removed,
  1054.                  Robocomm will make a log notation and abort the script
  1055.                  processing.
  1056.  
  1057.                  Example:
  1058.  
  1059.                     RD "C:\GONNER"
  1060.  
  1061.                  See Also:
  1062.                     CD
  1063.                     MD
  1064.  
  1065.  
  1066.                * RENAME "<cfile>" [TO] "<cNewName>"
  1067.  
  1068.                  Attempts to rename <cFile> to <cNewName>.  Just as with
  1069.                  DOS, this command will fail if a file names <cNewName>
  1070.                  already exists.  The TO clause is optional, and functions
  1071.                  only to enhance readability.
  1072.  
  1073.  
  1074.                * RENUMBER "<cFile>" [<nCount>]
  1075.  
  1076.                  Uses Robocomm's internal renumbering scheme to maintain a
  1077.                  <nCount>   archived versions of <cFile>.  <nCount>
  1078.                  defaults to 1 if not specified.
  1079.  
  1080.                  Example:
  1081.  
  1082.                  RENUMBER "VAMPIRE.CAP" 5
  1083.  
  1084.  
  1085.                * RETURN
  1086.  
  1087.                  Causes script process control to return to the first valid
  1088.                  command line immediately following the most recent GOSUB
  1089.                  command.
  1090.  
  1091.                  Example:
  1092.  
  1093.                     IF SUN GOSUB GETFILES
  1094.                     SEND "BYE|"
  1095.                     EXIT 0
  1096.  
  1097.                     :GETFILES
  1098.                        MESSAGE "It's Sunday.  Downloading and processing
  1099.                  Allfiles"
  1100.                        RENUMBER "%DLDIR%ALLFILES.ZIP" 2
  1101.  
  1102.  
  1103.  
  1104.           _________________________________________________________________
  1105.           Robocomm 4.3 - Script Language Reference                 Page: 15
  1106.  
  1107.  
  1108.  
  1109.  
  1110.  
  1111.  
  1112.  
  1113.                        SEND "D;ALLFILES.ZIP|"
  1114.                        DOWNLOAD
  1115.                     RETURN
  1116.  
  1117.  
  1118.  
  1119.                * RUN "<cDosCommand>" [KEYBOARD "<cKeyString>"]
  1120.  
  1121.                  Shells to DOS and runs the command <cDosCommand>.  If you
  1122.                  need to test the result of the called process, the
  1123.                  ERRORLEVEL set by the called program is retained by
  1124.                  Robocomm to be queried with the IF ERRORLEVEL script
  1125.                  command.
  1126.  
  1127.                  Note: Robocomm's current drive and directory is always
  1128.                  restored automatically after the called process returns
  1129.                  control.
  1130.  
  1131.                  Examples:
  1132.  
  1133.                     RUN "Rexclude c:\download"
  1134.  
  1135.                  CAUTION:  If you do not plan on exploring the KEYBOARD
  1136.                  clause, detailed below, be sure not to call any process
  1137.                  from within Robocomm that will require a keypress.  If you
  1138.                  do this and aren't around to manually press the required
  1139.                  key, Robocomm will be unable to recover and all processing
  1140.                  will halt until you show up to rectify the situation.
  1141.  
  1142.                  Using the KEYBOARD clause:
  1143.  
  1144.                  In cases where you really want to run an external program
  1145.                  that requires keystrokes, the optional KEYBOARD command
  1146.                  can help.  This command stuffs the keyboard by temporarily
  1147.                  taking over BIOS interrupt 16h.  Thus, you can automate
  1148.                  all or part of the program that you call with Robocomm's
  1149.                  RUN command.
  1150.  
  1151.                  This capability was inspired by a memory resident program
  1152.                  called Key-Fake by Charles Petzold and copyrighted by
  1153.                  Ziff-Davis Publishing Company.  Mr. Petzold did an
  1154.                  excellent job and Robocomm imitates, with a few
  1155.                  enhancements, Mr. Petzold's method of defining the keys to
  1156.                  stuff the keyboard.  The KEYBOARD command function works
  1157.                  with almost any programs you might want to call, except
  1158.                  for those rare  programs that directly take over the
  1159.                  keyboard.
  1160.  
  1161.  
  1162.  
  1163.  
  1164.           _________________________________________________________________
  1165.           Robocomm 4.3 - Script Language Reference                 Page: 16
  1166.  
  1167.  
  1168.  
  1169.  
  1170.  
  1171.  
  1172.  
  1173.                  The KEYBOARD <cKeyString> is a character string parameter.
  1174.                  This character string can contain:
  1175.  
  1176.                     1) embedded character strings.
  1177.                     2) named keys within curly brackets.
  1178.                     3) the number 0 by itself.
  1179.                     4) the number 1 by itself.
  1180.  
  1181.  
  1182.                  1) Embedded character strings:
  1183.  
  1184.                  Characters within inner quotes (either single or double
  1185.                  quotes) are normal ASCII characters. KEYBOARD
  1186.                  "'EXIT'"would stuff the keyboard with the four keys 'E',
  1187.                  'X', 'I', and 'T'.
  1188.  
  1189.                  Normally, these characters are limited to those
  1190.                  alphabetical, numeric, and symbol characters that can be
  1191.                  typed at the keyboard.  Keys such as <F1> and <Insert>
  1192.                  cannot be specified this way.  You can specify other non-
  1193.                  keyboard characters such as graphics characters which are
  1194.                  not normally available from the keyboard.
  1195.  
  1196.                  If non- keyboard characters are specified, KEYBOARD will
  1197.                  attempt to pass them to the called program, but some
  1198.                  programs may not be able to accept them.  Please note that
  1199.                  the character string passed to KEYBOARD begins and ends
  1200.                  with double quotes ("), and that the inner string begins
  1201.                  and ends with single quotes (').
  1202.  
  1203.  
  1204.                  2) Named keys within curly braces:
  1205.  
  1206.                  In order to specify keys such as <F1>, <Insert>, and
  1207.                  <Ctrl-A>, you must specify them within curly braces.
  1208.                  KEYBOARD can handle every possible key combination that
  1209.                  converts to a keycode.  Some keys such as the
  1210.                  <PrintScreen> and <NumLock> have no keycode value and
  1211.                  cannot be stuffed with KEYBOARD.
  1212.  
  1213.                  When specifying the keys, case is not important.  You may
  1214.                  use uppercase, lowercase, or mixed case.  The keys are
  1215.                  specified with the form {[<switch>-]keyname} where keyname
  1216.                  is the name of the key optionally preceded by one of the
  1217.                  switch keys: <Shift>, <Ctrl>, <Alt>.  Only one switch key
  1218.                  can be specified because they are mutually exclusive.
  1219.                  When more than one switch key is pressed at a time, the
  1220.  
  1221.  
  1222.  
  1223.  
  1224.           _________________________________________________________________
  1225.           Robocomm 4.3 - Script Language Reference                 Page: 17
  1226.  
  1227.  
  1228.  
  1229.  
  1230.  
  1231.  
  1232.  
  1233.                  <Ctrl> key overrides the <Shift> key and the <Alt> key
  1234.                  overrides the <Ctrl> key.
  1235.  
  1236.                  The following keys are valid:
  1237.  
  1238.                     {F1}..{F12}
  1239.                     {Shift-F1}..{Shift-F12}
  1240.                     {Ctrl-F1}..{Ctrl-F12}
  1241.                     {Alt-F1}..{Alt-F12}
  1242.  
  1243.                  Note that F11 and F12 are only available on enhanced
  1244.                  keyboards and may not be accepted by a program running on
  1245.                  a computer with a standard keyboard.
  1246.  
  1247.                     {Ctrl-A}..{Ctrl-Z}
  1248.                     {Alt-A}..{Alt-Z}
  1249.                     {Ctrl-0}..{Ctrl-9}
  1250.                     {Alt-0}..{Alt-9}
  1251.  
  1252.                  These keys correspond to the keys on both the numeric
  1253.                  keypad and the QWERTY keyboard when a standard keyboard is
  1254.                  in use.  An enhanced keyboard can differentiate between
  1255.                  the numeric keypad and the QWERTY keyboard if the software
  1256.                  enables it to do so.  If the software you're using
  1257.                  requires that the numbers come from the numeric keypad,
  1258.                  use the # symbol explained below.
  1259.  
  1260.                  {<Symbol>}
  1261.                  {Ctrl-<Symbol>}
  1262.                  {Alt-<Symbol>}
  1263.                  where <Symbol> is anyone of the 30+ symbols available on
  1264.                  the keyboard such as !@#$%&*~_-+={}[]|\:;"'<>,.?.
  1265.  
  1266.                  {Enter}, {Esc}, {Tab}, {Bksp}, {Space}
  1267.                  {Ctrl-Enter}..{Ctrl-Space}
  1268.                  {Alt-Enter}..{Alt-Space}
  1269.  
  1270.                  {Home}, {End}, {PgUp}, {PgDn}, {Left}, {Right}, {Up},
  1271.                  {Down}, {Ins}, {Del}
  1272.                  {Ctrl-Home}..{Ctrl-Del}
  1273.                  {Alt-Home}..{Alt-Del}
  1274.                  These keys are all found on the numeric keypad.
  1275.  
  1276.                  {*Home}, {*End}, {*PgUp}, {*PgDn}, {*Left}, {*Right},
  1277.                  {*Up}, {*Down}, {*Ins}, {*Del}
  1278.                  {Ctrl-*Home}..{Ctrl-*Del}
  1279.                  {Alt-*Home}..{Alt-*Del}
  1280.  
  1281.  
  1282.  
  1283.  
  1284.           _________________________________________________________________
  1285.           Robocomm 4.3 - Script Language Reference                 Page: 18
  1286.  
  1287.  
  1288.  
  1289.  
  1290.  
  1291.  
  1292.  
  1293.                  where the * symbol stands for the extra cursor control pad
  1294.                  available on enhanced keyboards.  These keys can only be
  1295.                  specified when an enhanced keyboard is in use; these keys
  1296.                  are not available on a standard keyboard.  Use these keys
  1297.                  when the software requires that the keypress be from the
  1298.                  extra cursor control pad.
  1299.  
  1300.                  {#0}..{#9}, {#.}, {#}, {#*}, {#-}, {#+}, {#Enter}
  1301.                  {Ctrl-#0}..{Ctrl-#9}, {Ctrl-#.}..{Ctrl-#Enter}
  1302.                  {Alt-#0}..{Alt-#9}, {Alt-#.}..{Alt-#Enter}
  1303.                  where the # symbol stands for the numeric keypad.  These
  1304.                  keys can only be specified when an enhanced keyboard is in
  1305.                  use; a standard keyboard does not differentiate the
  1306.                  numeric keypad keys from their QWERTY keyboard
  1307.                  counterparts.  Use these keys when the software requires
  1308.                  that the keypress be from the numeric keypad only.
  1309.  
  1310.                  {SysReq}
  1311.                  notice that the {SysReq} key is specified without the
  1312.                  {Ctrl-} prefix.
  1313.  
  1314.  
  1315.                  3) The number 0 by itself:
  1316.  
  1317.                  The number 0 by itself is a special symbol to KEYBOARD; it
  1318.                  tells the function to report back to the called program,
  1319.                  at that point, that the keyboard buffer is empty.  This
  1320.                  should be unnecessary for most programs, but if you find
  1321.                  that at some point the called program seems to clear the
  1322.                  keyboard buffer or lose keystrokes, you may need to use a
  1323.                  0 to fool the program into thinking the keyboard buffer is
  1324.                  empty.  By default, KEYBOARD stuffs a 0 key after each
  1325.                  keystroke.  This makes the external program think that the
  1326.                  keyboard buffer is empty after each keystroke.  This is
  1327.                  necessary because some programs clear the keyboard buffer
  1328.                  after each keystroke.
  1329.  
  1330.                  4) The number 1 by itself:
  1331.  
  1332.                  The number 1 by itself is also a special symbol to
  1333.                  KEYBOARD.  It tells the function to wait for the user to
  1334.                  hit a key before continuing; the keystroke is then passed
  1335.                  directly to the external program.  Obviously, this
  1336.                  capability has limited usefulness in an unattended
  1337.                  environment, but is useful when the user must make a
  1338.                  choice or enter a secret code before KEYBOARD can continue
  1339.                  stuffing more keys.
  1340.  
  1341.  
  1342.  
  1343.  
  1344.           _________________________________________________________________
  1345.           Robocomm 4.3 - Script Language Reference                 Page: 19
  1346.  
  1347.  
  1348.  
  1349.  
  1350.  
  1351.  
  1352.  
  1353.                  Summary:
  1354.  
  1355.                  All of these key definitions can be put in the same
  1356.                  character string.  You are currently limited to stuffing
  1357.                  250 keystrokes into the keyboard.  Some programs take over
  1358.                  the keyboard directly, which keeps Robocomm from stuffing
  1359.                  the keyboard.  There is nothing that can be done about
  1360.                  these programs, but they are definitely in the minority.
  1361.  
  1362.                  Example:
  1363.  
  1364.                  Import Robocomm's TRANSFER.LOG into a dBASE database using
  1365.                  FoxPro:
  1366.  
  1367.                  RUN "foxproln" KEYBOARD "`USE TRANSFER.DBF` {ENTER} `APPE
  1368.                  FROM TRANSFER.LOG` {ENTER} `QUIT` {ENTER}"
  1369.  
  1370.                  In our doc file, that line wrapped to a second line, but
  1371.                  in your script file, it should be all on one line.
  1372.  
  1373.  
  1374.  
  1375.                * SEND "<cString>"
  1376.  
  1377.                  This command sends one or more characters to the BBS.
  1378.                  Before sending the text, Robocomm will look for the
  1379.                  existence of two special characters; the pipe "|", the
  1380.                  carat "^" and the tilde "~".  Use the pipe character
  1381.                  whenever you would like Robocomm to send a carriage
  1382.                  return.  Use the carat to signify that the next character
  1383.                  is a "control character."   Use the tilde whenever you
  1384.                  would like Robocomm to pause for on half second before
  1385.                  sending the next character.
  1386.  
  1387.                  Examples:
  1388.  
  1389.                  SEND "^X^X~~~~^X^X"
  1390.  
  1391.                  This example sends two "Control-X" characters, pauses for
  1392.                  2 seconds, and then sends another paid of Control-X
  1393.                  characters.  This is the key sequence that is commonly
  1394.                  used to abort a file transfer.
  1395.  
  1396.                  SEND "B|1|"
  1397.  
  1398.                  This example sends the letter "B" followed by a carriage
  1399.                  return (ASCII code 13), followed again by the number 1 and
  1400.                  another carriage return.
  1401.  
  1402.  
  1403.  
  1404.           _________________________________________________________________
  1405.           Robocomm 4.3 - Script Language Reference                 Page: 20
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.                  NOTE:  Robocomm does not automatically append a carriage
  1415.                  return to the text you specify between quotes.  If a
  1416.                  carriage return is required, you must supply it by ending
  1417.                  the string with the | or ^M characters.
  1418.  
  1419.                  SENDING RESERVED CHARACTERS: To send a tilde, carat or
  1420.                  pipe character to the BBS as part of your send string,
  1421.                  simply place a carat before the character.
  1422.  
  1423.                     ^^    sends    ^
  1424.                     ^~    sends    ~
  1425.                     ^|    sends    |
  1426.  
  1427.  
  1428.  
  1429.                * SOUND <nFrequency> <nDuration>
  1430.  
  1431.                  Creates a sound on the PC's speaker.
  1432.  
  1433.                  <nFrequency> is a numeric value indicating the desired
  1434.                  frequency, in the range of 37 to 32767.  If not specified,
  1435.                  <nFrequency> defaults to 500.
  1436.  
  1437.                  <nDuration> is the amount of time to continue the sound,
  1438.                  in 100ths of a second.
  1439.  
  1440.                  NOTE: If the user has the speaker style option on
  1441.                  Robocomm's General Configuration screen set to SILENT no
  1442.                  sound will be produced.
  1443.  
  1444.                  For the musical purists in the group, the following is a
  1445.                  table of values to produce standard musical pitches:
  1446.  
  1447.                  Pitch           Frequency         Pitch          Frequency
  1448.                  ----------------------------------------------------------
  1449.                  C               130.80            mid C          261.70
  1450.                  C#              138.60            C#             277.20
  1451.                  D               146.80            D              293.70
  1452.                  D#              155.60            D#             311.10
  1453.                  E               164.80            E              329.60
  1454.                  F               174.60            F              349.20
  1455.                  F#              185.00            F#             370.00
  1456.                  G               196.00            G              392.00
  1457.                  G#              207.70            G#             415.30
  1458.                  A               220.00            A              440.00
  1459.                  A#              233.10            A#             466.20
  1460.                  B               246.90            B              493.90
  1461.  
  1462.  
  1463.  
  1464.           _________________________________________________________________
  1465.           Robocomm 4.3 - Script Language Reference                 Page: 21
  1466.  
  1467.  
  1468.                * STATISTICS "<cFile>"
  1469.  
  1470.                  This command places the contents of <cFile> into
  1471.                  Robocomm's internal data structures so that the data can
  1472.                  be viewed later via Robocomm's "Statistics" command on the
  1473.                  Directory-BBS screen.
  1474.  
  1475.                  NOTE: Robocomm will not import a file longer than 10,240
  1476.                  characters.  Attempts to do so will be ignored.
  1477.  
  1478.                  Example:
  1479.  
  1480.                     STATISTICS "%ID%.STS"
  1481.  
  1482.  
  1483.                * TERMINAL [NOKEY] [EXITON "<text>"] [DOORWAY]
  1484.  
  1485.                All parameters are optional.  Their purposes are:
  1486.  
  1487.                NOKEY -     Bypasses the alarm and the necessity to press
  1488.                            a key after jumping to terminal.
  1489.  
  1490.                            NOTE: The terminal mode "alarm" is actually a
  1491.                            60 second timer that will enable Robocomm to
  1492.                            recover if no one is around to interact with
  1493.                            the terminal. Using the NOKEY clauses
  1494.                            disables this alarm, so Robocomm will jump to
  1495.                            terminal mode and will not go back to
  1496.                            automated processing until the user presses
  1497.                            Alt-X or when the EXITON text is seen. (See
  1498.                            below)
  1499.  
  1500.                EXITON -    This command allows you to specify a text
  1501.                            string that Robocomm will watch for whenever
  1502.                            it is in terminal mode.  If Robocomm
  1503.                            encounters the specified text it will
  1504.                            immediately exit the terminal mode and resume
  1505.                            script processing.
  1506.  
  1507.                DOORWAY -   This command causes the terminal to start
  1508.                            with "Doorway" mode turned on.
  1509.  
  1510.                            NOTE: You will need to Press [Alt =] to turn
  1511.                            doorway mode off before you can exit with
  1512.                            Alt-X.
  1513.  
  1514.                    Examples:
  1515.  
  1516.                        TERMINAL
  1517.                         Goes into standard terminal mode, sounds alarm.
  1518.                        TERMINAL NOKEY
  1519.                         Goes into standard terminal with no alarm or keypress.
  1520.                        TERMINAL DOORWAY
  1521.                         Goes into Doorway mode terminal, sounds alarm.
  1522.  
  1523.  
  1524.           _________________________________________________________________
  1525.           Robocomm 4.3 - Script Language Reference                 Page: 22
  1526.  
  1527.  
  1528.  
  1529.                        TERMINAL EXITON "<EXIT>"
  1530.                         Goes into terminal.  Automatically exits on <EXIT>.
  1531.                        TERMINAL NOKEY DOORWAY EXITON "<EXIT>"
  1532.                         You get the idea...
  1533.  
  1534.                * TERSE ON|OFF
  1535.  
  1536.                  Sends the codes necessary to shift PCBoard systems in and
  1537.                  of "Terse" mode.  Please note that Robocomm must be waiting
  1538.                  at a non-PPE created prompt for this command to execute
  1539.                  properly.
  1540.  
  1541.                * TIMEOUT <nSeconds>
  1542.  
  1543.                  Sets the number of seconds that all subsequent WAITFOR
  1544.                  commands will allow to pass while they watch for their
  1545.                  intended string.  If <nSeconds> elapses before the match
  1546.                  is found, control will pass to the defined WAITFOR FAILURE
  1547.                  clause, or, if none is defined, to the next executable
  1548.                  statement in the script.
  1549.  
  1550.                  Example:
  1551.  
  1552.                  TIMEOUT 30
  1553.  
  1554.                  See Also:
  1555.                     WAITFOR
  1556.  
  1557.  
  1558.                * TITLE "<cString>"
  1559.  
  1560.                  Sets the script title that will appear in the Script
  1561.                  Selection window on the agenda modification screen.
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.           _________________________________________________________________
  1585.           Robocomm 4.3 - Script Language Reference                Page: 22a
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.                  Although this statement can appear anywhere within the
  1594.                  script file, you should place it as the first line in the
  1595.                  script, to make the Script Selection window pop-up as
  1596.                  rapidly as possible.  It's also a good idea to indicate
  1597.                  the type of BBS system the script is designed to handle in
  1598.                  the title.
  1599.  
  1600.                  Example:
  1601.  
  1602.                     TITLE "(PCBoard)  This is a script title example!"
  1603.  
  1604.  
  1605.                * UPLOAD "<cFileSpec>" [USING "<cProtocol>"]
  1606.  
  1607.                  Sends <cFileSpec> to the BBS using <cProtocol>.
  1608.  
  1609.                  <cFileSpec> may be any valid path and/or filename,
  1610.                  including wildcard characters.  If the optional USING
  1611.                  <cProtocol> clause is specified, then Robocomm will use
  1612.                  the protocol specified.  By default Robocomm will attempt
  1613.                  to use configured file upload protocol.  ASCII is a
  1614.                  valid upload protocol type.
  1615.  
  1616.                  Examples:
  1617.                     UPLOAD "c:\qwks\%ID%.KEY" USING "YMODEM-G"
  1618.                     UPLOAD "C:\OUTGOING\*.ZIP"
  1619.                     UPLOAD "message.txt" USING "ASCII"
  1620.  
  1621.                * VENUE <cVenueCode>
  1622.  
  1623.                  Attempts to move to the area of the BBS system specified
  1624.                  by cVenueCode.  Valid codes are:
  1625.  
  1626.                  Code        Description                         Systems
  1627.                  --------    ---------------------------------   -------
  1628.                  MSGS        Go to the message sub-menu          Wildcat
  1629.                  FILE        Go to the file sub-menu             Wildcat
  1630.                  MAIN        Go to the Main Menu                 PCB/WC
  1631.                  MAIL        Go to the defined QWK door          PCB/WC
  1632.  
  1633.                  Examples:
  1634.  
  1635.                     VENUE MAIL
  1636.                     VENUE MSGS
  1637.  
  1638.                  See also:
  1639.  
  1640.                     JOIN
  1641.  
  1642.  
  1643.  
  1644.           _________________________________________________________________
  1645.           Robocomm 4.3 - Script Language Reference                 Page: 23
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.                * WAITFOR "<cString>" [FAILURE <command>]
  1654.  
  1655.                  Watches for incoming text matching <cString> while
  1656.                  simultaneously watching for any "watches" defined with the
  1657.                  WHEN command.  The amount of time that Robocomm watches
  1658.                  for text is defined separately with the TIMEOUT command.
  1659.  
  1660.                  If <cString> is recognized within the allotted time,
  1661.                  Robocomm simply proceeds on to the next executable line in
  1662.                  the script.  If, however, <cString> is not recognized,
  1663.                  Robocomm's subsequent behavior depends upon whether the
  1664.                  optional FAILURE clause has been specified.  If a FAILURE
  1665.                  <command> has been specified, Robocomm will immediately
  1666.                  process <command>.  If no FAILURE command is specified,
  1667.                  then an error message is inserted in the log and script
  1668.                  processing is terminated.
  1669.  
  1670.                  NOTE: Aside from the file transfer commands.  WAITFOR is
  1671.                  the only script command which actually retrieves incoming
  1672.                  text from the comm port receive buffers.  For this reason,
  1673.                  you will see text scrolling in the online window only
  1674.                  while a WAITFOR is being evaluated.
  1675.  
  1676.                  NOTE: To copy a list of the currently active watches to
  1677.                  the VERBOSE mode log in Robocomm, simply press [Alt-S]
  1678.                  while Robocomm is watching for text.  This feature will
  1679.                  aid you greatly in debugging your scripts.
  1680.  
  1681.                  Examples:
  1682.  
  1683.                  The following script fragment sets up a number of watches
  1684.                  via the WHEN command and demonstrates the use of the
  1685.                  WAITFOR command in conjunction with them.
  1686.  
  1687.                     ; A sample script to download ProDoor ZIPMail packets.
  1688.                     ;
  1689.                     ; FOR DEMONSTRATION PURPOSES ONLY -- NOT TESTED
  1690.                     ;
  1691.                     TIMEOUT 10
  1692.                     WHEN "MORE?" SEND "N|"
  1693.                     WHEN "[ENTER] TO CONTINUE" SEND "|"
  1694.                     WHEN "SCAN MESSAGES" SEND "N|"
  1695.                     WAITFOR "COMMAND?" FAILURE GOTO ERROR
  1696.  
  1697.                     TIMEOUT 600
  1698.                     SEND "ZIPM|"
  1699.                     WHEN "NO MESSAGES" GOTO NOMAIL
  1700.                     WHEN "NOT ENOUGH TIME" GOTO ERROR
  1701.                     WHEN "PROTOCOL" SEND "Z|"
  1702.                     WAITFOR "CTRL-X ABORTS" FAILURE GOTO ERROR
  1703.  
  1704.           _________________________________________________________________
  1705.           Robocomm 4.3 - Script Language Reference                 Page: 24
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.                     RENUMBER "%QWKDIR%%ID%.ZPM" 5
  1714.                     DOWNLOAD "%QWKDIR%%ID%.ZPM"
  1715.                     EXIT 0
  1716.  
  1717.                     :ERROR
  1718.                        HANGUP
  1719.                        EXIT 1
  1720.  
  1721.                     ; End of script.
  1722.  
  1723.                  See Also:
  1724.                     WHEN
  1725.                     TIMEOUT
  1726.  
  1727.  
  1728.                * WAITUNTIL ["<cTime>"] ["<cDate>"]
  1729.  
  1730.                  Pauses script execution until a specified date and/or
  1731.                  time.
  1732.  
  1733.                  <cTime> is the time of day to start, in 24 hour format
  1734.                  HH:MM
  1735.  
  1736.                  <cDay> is the date to start in MM/DD/YY or MM-DD-YY
  1737.                  format.
  1738.  
  1739.                  Both parameters are optional, but at least one must be
  1740.                  specified.  If <cDate> is not specified, it defaults to
  1741.                  the current date.  If <cTime> is not specified, it
  1742.                  defaults to "00:00" (Midnight).
  1743.  
  1744.                  Examples:
  1745.  
  1746.                     WAITUNTIL "06:00"
  1747.                     WAITUNTIL "12:00" "12/13/91"
  1748.                     WAITUNTIL "12/01/91"
  1749.  
  1750.  
  1751.                * WHEN "<cString>" <command>
  1752.  
  1753.                  Creates an incoming text watch for <cString> and executes
  1754.                  <command> whenever it is seen.  WHEN commands are valuable
  1755.                  when prompts from the BBS may come in random order or when
  1756.                  a standardized response to a prompt should be sent
  1757.                  whenever a certain prompt is received from the BBS.  It is
  1758.                  important to understand that the WHEN command merely posts
  1759.                  <cString> and <command> for evaluation by the WAITFOR
  1760.  
  1761.  
  1762.  
  1763.  
  1764.           _________________________________________________________________
  1765.           Robocomm 4.3 - Script Language Reference                 Page: 25
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.                  command.  Thus, WHENs are only valid while a WAITFOR is
  1774.                  currently being evaluated.
  1775.  
  1776.                  Example:
  1777.                     See example under the WAITFOR command.
  1778.  
  1779.                  See Also:
  1780.                     WAITFOR
  1781.                     DISABLE
  1782.                     ENABLE
  1783.                     CLEAR
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.  
  1793.  
  1794.  
  1795.  
  1796.  
  1797.  
  1798.  
  1799.  
  1800.  
  1801.  
  1802.  
  1803.  
  1804.  
  1805.  
  1806.  
  1807.  
  1808.  
  1809.  
  1810.  
  1811.  
  1812.  
  1813.  
  1814.  
  1815.  
  1816.  
  1817.  
  1818.  
  1819.  
  1820.  
  1821.  
  1822.  
  1823.  
  1824.           _________________________________________________________________
  1825.           Robocomm 4.3 - Script Language Reference                 Page: 26
  1826.  
  1827.  
  1828.                                    APPENDIX A
  1829.  
  1830.     Directory-BBS Field Macros
  1831.     --------------------------
  1832.  
  1833.     The following %BBS??% macros are all to non-prompt related items:
  1834.  
  1835.     Macro # Description
  1836.     ------- ----------------------------------------------------
  1837.     1       The BBS Robocomm/Mail ID.  (duplicated by %ID%)
  1838.     2       The BBS Name
  1839.     3       Phone Number #1  \
  1840.     4       Phone Number #2   |-- Dialing macros A-J NOT expanded.
  1841.     5       Phone Number #3  /
  1842.     7       Login Password
  1843.     13      Login Name
  1844.     17      Qmail Door Conference
  1845.     19      File Upload Protocol
  1846.     20      File Download Protocol
  1847.     21      Mail Door Upload Protocol
  1848.     22      Mail Door Download Protocol
  1849.     60      PC-Pursuit outdial city
  1850.     63      Command to Open Mail Door (Wildcat!) or  Door Number/Name (PCBoard)
  1851.     66      Upload area               (Wildcat! only)
  1852.  
  1853.     
  1854.     The Following BBS?? Macros are the defined prompt definitions for
  1855.     PCBoard Systems:
  1856.  
  1857.     29      Language to use
  1858.     30      Help prompt
  1859.     31      Do you want graphics
  1860.     32      More?
  1861.     33      Scan Messages
  1862.     34      Pause - "Enter to Continue"
  1863.     35      Main Board Prompt
  1864.     36      Confernce ID string (# translated to conference number)
  1865.     37      Upload file description
  1866.     38      No Protocol Defined
  1867.     39      Start Transfer
  1868.     40      Mail Door Main Command
  1869.     41      Start Mail Download
  1870.     42      Start Mail Upload
  1871.     43      Packet Transfer Confirmation.
  1872.     44      No Mail to Download
  1873.     45      Enter First Name
  1874.     46      Enter Password (logon)
  1875.     47      Message Menu Prompt
  1876.     48      Download File Not Found
  1877.     49      Generic Command (usually "Command")
  1878.     50      Duplicate Upload
  1879.     51      Insufficient security to download (restricted access)
  1880.     52      Not enough time/bytes to download.
  1881.     53      Upload file not accepted
  1882.     54      ProDoor: Enter Upload Description
  1883.     55      <not in use>
  1884.     56      ProDoor: Main Board Command
  1885.     57      <not in use>
  1886.     58      ProDoor: Start Transfer
  1887.     59      Front End Prompt (Usually "DOOR #")
  1888.     70      Front End Mail Program (Robo sends 2 ESC characters)
  1889.     71      Not enough time to download mail
  1890.  
  1891.  
  1892.  
  1893.     The Following BBS?? Macros are the defined prompt definitions for
  1894.     Wildcat! Systems:
  1895.  
  1896.     29      Read Bulletins?
  1897.     30      View Mail?
  1898.     31      Location Confirmation (are you xxxx from xxxx?)
  1899.     32      Press Enter to Continue
  1900.     33      Enter Birthday
  1901.     34      Pause
  1902.     35      Main Menu
  1903.     36      Confernce ID string (# translated to conference number)
  1904.     37      Upload file description
  1905.     38      Bulletin Menu
  1906.     39      Start File Download
  1907.     40      Mail Door (TomCat) Command Prompt
  1908.     41      Start Mail Download
  1909.     42      Start Mail Upload
  1910.     43      Packet Transfer Confirmation.
  1911.     44      No Mail to Download
  1912.     45      Enter First Name
  1913.     46      Enter Password (logon)
  1914.     47      Message Menu Prompt
  1915.     48      File Name to Download
  1916.     49      Read Newsletter?
  1917.     50      Duplicate Upload
  1918.     51      Upload file not a duplicate
  1919.     52      Logon name failure
  1920.     53      Start file upload
  1921.     54      File Menu
  1922.     55      Enter Last Name
  1923.     56      Phone number confirmation
  1924.     57      <not in use>
  1925.     58      D/L File Found
  1926.     59      Front End Prompt (Usually "DOOR #")
  1927.     70      File Upload Rename
  1928.     71      Extended Descriptions
  1929.     72      File Keywords
  1930.     73      Not Enough Time to Download Mail
  1931.     74      Choose Upload Area
  1932.     75      Not Enough Time to Download
  1933.     76      Not Enough Bytes to Download
  1934.     77      Not Enough Credit to Download
  1935.     78      Password protect upload question
  1936.  
  1937.  
  1938.     The following %WC?% macros are the defined commands for the currently
  1939.     connected Wildcat BBS system:
  1940.  
  1941.  
  1942.     Number  Command                                       Default
  1943.     ------  --------------------------------------------  -------
  1944.     1     Quit from FILE or MESSAGE menu to MAIN menu.     Q
  1945.     2     Go to the MESSAGE menu from the MAIN menu.       M
  1946.     3     Go to the FILE menu from the MAIN menu.          F
  1947.     4     Start file download sequence                     D
  1948.     5     Start file upload sequence                       U
  1949.     6     "Info Scan" a downloadable file                  I
  1950.     7     Start the new file scan sequence                 N
  1951.     8     Log off from FILE, MESSAGE or MAIN menus.        G
  1952.     9     Start conference join sequence                   J
  1953.  
  1954.     Example:
  1955.  
  1956.     ; Go to the file menu
  1957.     SEND "%WC3%|"
  1958.  
  1959.  
  1960.