home *** CD-ROM | disk | FTP | other *** search
/ Club Amiga de Montreal - CAM / CAM_CD_1.iso / files / 157.lha / Access_v1.4 / Script.doc < prev    next >
Encoding:
Text File  |  1988-04-28  |  9.6 KB  |  263 lines
  1. ------------------------------------------------------------------------------
  2. Script.doc         -- Access! (C) 1987/88 By Keith Young --
  3.  
  4. Other text files in this archive:
  5.     Access!me        The origional 'doc' file describing most of Access!'s
  6.                     features.
  7.  
  8.     Future.txt        This author's ramblings about what the future may hold
  9.                     for Access! (please read)
  10.  
  11.     Update.doc        Documentation describing additions/changes to the current
  12.                     release of Access! (please read)
  13.  
  14. ------------------------------------------------------------------------------
  15.    Time: -23:-
  16.    Date: 8/14/88
  17. Subject: Script Commands and Formats
  18.  
  19.  
  20.         Scripts -- I am in the process of adding 'real' scripts (as opposed
  21.     to the 'psuedo scripts' that _were_ available through the macro keys).
  22.     This release has a limited (first) verson of the new scripting language
  23.     and it will be expaned in future releases. Below are listed the various
  24.     commands (and format for each command) that are currently implemented.
  25.     There should also be an example script in the arc.
  26.     ( anything within the [] is optional, but may effect the way the command
  27.     works ). 
  28.  
  29. ----------------------------------------------------------------------------
  30. ASEND
  31.  
  32.     Format:    ASEND [drive:dir/filename]
  33.  
  34.     Discusion:    This will start an ASCII text send of the filename given.
  35.                 Or if there is an ASCII send in progress, it will abort
  36.                 the send. This command just 'starts' (or stops) the send 
  37.                 in motion then continues with the script.
  38.         
  39. ----------------------------------------------------------------------------
  40. BEEP
  41.  
  42.     Format:    BEEP
  43.  
  44.     Discusion:    Causes an audible 'beep' of the terminal.
  45.                 This can be used to signal certain events such as the
  46.                 script finishing, a certain string being recieved, etc.
  47.  
  48. ----------------------------------------------------------------------------
  49. BYE
  50.  
  51.     Format:    BYE
  52.  
  53.     Discusion:    This will cause the the terminal to hangup the modem.
  54.  
  55. ----------------------------------------------------------------------------
  56. CAPTURE
  57.  
  58.     Format:    CAPTURE [drive:dir/filename]
  59.  
  60.     Discusion:    Opens an ASCII capture file with the specified name.
  61.                 Or if there is an ASCII capture already in progress,
  62.                 it will close the capture file. This command just
  63.                 'starts' (or stops) the capture then continues with
  64.                 the next script command.
  65.  
  66.     See Also:    TOGLCAP, ASEND
  67.  
  68. ----------------------------------------------------------------------------
  69. DELAY
  70.  
  71.     Format:    DELAY x
  72.  
  73.     Discusion:    Causes a delay of 'x' seconds. eg. DELAY 10 will delay
  74.                 the execution of the script for 10 seconds (there is 
  75.                 a minimum of 1 second).
  76.  
  77. ----------------------------------------------------------------------------
  78. DISPLAY
  79.  
  80.     Format: DISPLAY "Strings with spaces in them must have quotes |"
  81.  
  82.     Discusion:    This command is used for displaying messages to the local
  83.                 screen (not sent to the modem). This can be used to help
  84.                 you debug your scripts, using several of these in various
  85.                 parts of your script will let you know where you currently
  86.                 are within the script (this is my 'printf()' 8)
  87.  
  88.     See Also:    DISPEN, BEEP, ON, WAIT, SEND
  89.  
  90. ----------------------------------------------------------------------------
  91. DISPEN
  92.  
  93.     Format:    DISPEN x
  94.  
  95.     Discusion:    Sets the 'pen color' for DISPLAYed messages. Where 'x' is
  96.                 a number from 0-15 for one of the 16 colors of the terminal.
  97.  
  98.     See Also:    DISPLAY
  99.  
  100. ----------------------------------------------------------------------------
  101. EXIT
  102.  
  103.     Format:    EXIT
  104.  
  105.     Discusion:    Exit the current script. (need I say more? 8)
  106.  
  107. ----------------------------------------------------------------------------
  108. GOTO
  109.  
  110.     Format:    GOTO Label
  111.  
  112.     Discusion:    The normal execution of a script is from top to bottom. 
  113.                 You can use GOTO to jump to a specified    position ( a label)
  114.                 in the script (can be either a forwards or backwards jump).
  115.                 See then 'General' section below for the format of a label.
  116.                 ( I know... a GOSUB would be nice... I'll look into it 8)
  117.  
  118.     See Also:    ON, WAIT, General (below)
  119.  
  120. ----------------------------------------------------------------------------
  121. SEND
  122.  
  123.     Format:    SEND "Send this out to the modem, plus a return char-> | "
  124.  
  125.     Discusion:    Sends a string to the modem. Strings with spaces in them
  126.                 must have quotes. A '|' char is interpreted as a CR.
  127.  
  128.     See Also:    DISPLAY, ASEND
  129.  
  130. ----------------------------------------------------------------------------
  131. TOGLCAP
  132.  
  133.     Format:    TOGLCAP
  134.  
  135.     Discusion:    The first time this cammand is used, it will open an ASCII
  136.                 capture file with the name specified in the DEFINE window
  137.                 of Access! as the "Def.Capture:". Subsiquent (sp) calls will
  138.                 toggle the capturing on/off without closing the file. It
  139.                 'suspends' and 'unsuspends' the capturing, this works
  140.                 _exactly_ the same as hitting <L-Amiga> <c> from within the
  141.                 program and can be used along with the keyboard command.
  142.                 To close a capture file after it's been started using this
  143.                 command, use the CAPTURE command with no filename. (this
  144.                 file will also be closed when you quit the program but not
  145.                 automatically when the script finishes).
  146.  
  147.     See Also:    CAPTURE, ASEND
  148.  
  149. ----------------------------------------------------------------------------
  150. ON
  151.  
  152.     Format:    ON "Password:" SEND "MyPassword|"
  153.             ON "?a?sword?" SEND "MyPassword|"
  154.             ON "NO CARRIER" GOTO Exit
  155.             ON "Hey Fred" BEEP
  156.             ON "dir" ASEND dh0:Acc!BBS/filelist     (hint, for the future 8)
  157.  
  158.     Discusion:    Even though only one 'on string' is allowed at a time
  159.                 (currently), this is a powerful command. It tells the
  160.                 terminal to store the 'string' in memory and if/when the
  161.                 term recieves it (no matter where else it may be in the
  162.                 script at the time) to stop what it's doing and perform 
  163.                 the specified command. As mentioned above, currently only
  164.                 _one_ ON string is stored in memory at a time... each 
  165.                 call to ON will replace it with the new string to look for.
  166.                 This command along with WAIT (below) and GOTO make a powerful
  167.                 team if used wisely. (hopefully, future versions will allow
  168.                 multiple ON strings for matching... this (and a few other
  169.                 'parsing' and conditional-type commands) would make a simple
  170.                 automated BBS a trivial thing to do... all with just a script
  171.                 .... I like it <grin> )
  172.  
  173.     See Also:    WAIT (in particular), and every other command <grin>
  174.  
  175. ----------------------------------------------------------------------------
  176. PRINT
  177.  
  178.     Format:    PRINT
  179.  
  180.     Discusion:    Toggles the printer on/off.
  181.  
  182. ----------------------------------------------------------------------------
  183. WAIT
  184.  
  185.     Format:    WAIT "Password:"
  186.             WAIT "?as?word?"
  187.  
  188.     Discusion:    Causes the execution of the script to _stop_ until the
  189.                 specified string is recieved. When/if the string is
  190.                 received, the script continues at the next instruction.
  191.                 If the string is never recieved, the script never continues,
  192.                 and must be manually aborted. You might want to setup an
  193.                 ON string (see above) before using WAIT for a way to bail
  194.                 out in case the string you are WAITing for doesn't arrive.
  195.  
  196.     See Also:    ON, GOTO, General (below)
  197.  
  198. ----------------------------------------------------------------------------
  199. General
  200.  
  201.     I'd like to make a few comments that apply to the scripts in general... 
  202.  
  203. o    The commands ON and WAIT have a 'string' as thier argument. This string
  204.     is 1) case sensitive 2) must be 20 chars. or less 3) you may use a '?'
  205.     char. as a wild-card to match any single char. (this is useful if you
  206.     are not sure of the 'case' of a particular char. in a string you will
  207.     be waiting on, or if you are like me and just plain don't know how
  208.     to spell it 8).
  209.  
  210. o    You may use 'white space' to whatever degree suits your taste of 
  211.     formatting.    ( TABs SPaces and (I think) LFeeds )
  212.  
  213. o    A '|' char. is interpreted by the script parser as a <return> char.
  214.  
  215. o    A ';' charactor is used to specify a comment line, anything after the ';'
  216.     charactor is ignored by the script parser. Currently, comments must be 
  217.     on a line by themselves and may _not_ be on the same line as a command.
  218.  
  219. o    A label is specified by a ':' char following a case sensitive string.
  220.     Generally, a descriptive word with the first letter in Upper-case should
  221.     be used, although this is not required. Here is a short example of how
  222.     the GOTO command and labels might be used (see the supplied example script
  223.     file for further examples)...
  224.  
  225. Top:
  226. ;---------------------------------------------------------------------
  227. ; First set up an ON string in case something goes wrong... note that
  228. ; you can use all the 'white space' you want between the command
  229. ; and it's argument and at the beggining of the line
  230. ;---------------------------------------------------------------------
  231.     ON "NO CARRIER" GOTO Exit
  232.     WAIT "Name:"
  233.     SEND            "Roger Rabbit|"
  234.     WAIT "Password:"
  235.     SEND            "IDunWorkForNo'Toons|"
  236.     WAIT "Command:"
  237. ;---------------------------------------------------------------------
  238. ; Ok, we're logged on to this 'made up' BBS, so lets open up a capture 
  239. ; file and read new messages
  240. ;---------------------------------------------------------------------
  241.     CAPTURE dh0:msgs/filename
  242.     SEND "rtn|"
  243. ;---------------------------------------------------------------------
  244. ; Now we'll reset the ON string to set up a little loop to send a 
  245. ; return char each time we get a 'Read Action:' prompt... until we
  246. ; get back to the main 'Command:' prompt that we are WAITing for
  247. ;---------------------------------------------------------------------
  248.     ON "Read Action:" GOTO Again
  249. Again:
  250.     SEND    "|"
  251.     WAIT "Command:"
  252. ;---------------------------------------------------------------------
  253. ; We're through reading new messages, so close the capture, send the
  254. ; logoff string to the BBS, hang up the modem, then Beep to signal
  255. ; that the script is done and finally Exit
  256. ;---------------------------------------------------------------------
  257.     CAPTURE
  258.     SEND    "Goodbye|"
  259. Exit:
  260.     BYE
  261.     BEEP
  262.     EXIT
  263.