home *** CD-ROM | disk | FTP | other *** search
/ The Datafile PD-CD 3 / PDCD_3.iso / internet / mailbot / !MailBot / Docs / BotDocsT < prev    next >
Text File  |  1995-02-26  |  27KB  |  739 lines
  1.  
  2. MailBot Reference Manual - ASCII Version
  3. Freebieware © Tony Howat 1994, 1995
  4.  
  5. v1.20 (26th Feb 1995)
  6.  
  7. ---
  8.  
  9. Mailbot is © Tony Howat 1994, 95 and is freebieware - i.e. distribution is
  10. unlimited, but :
  11.  
  12.      No charge may be made for this software,
  13.      The software must be distributed as a complete package,
  14.      The software should not be modified and distributed,
  15.      Any handling fee charged by PD libraries must be nominal (<£1).
  16.  
  17. FreebieWare[tm] also requires any commercial organisation using this
  18. program to send the author a freebie. Anything from a biro to a company
  19. car. Not only will you satisfy the conditions of FreebieWare[tm] but you
  20. will also gain some shameless advertising in future releases of MailBot.
  21. The address to send any freebies to is :
  22.  
  23.      Tony Howat
  24.      12 Dover Road
  25.      Birkdale
  26.      Southport
  27.      Merseyside
  28.      PR8 4SY
  29.  
  30. Enquiries/suggestions/bug reports relating to MailBot should be e-mailed to
  31. thowat@xargle.demon.co.uk.
  32.  
  33. To find out about the latest release of MailBot e-mail a blank message to
  34. mbv@xargle.demon.co.uk. Any new releases are announced on comp.sys.acorn
  35. and demon.ip.support.archimedes. The latest official release of
  36. MailBot is always availiable by FTP from ftp.demon.co.uk in
  37. pub/archimedes/developers.
  38.  
  39. The Incredible Flying Frisbee Company is, of course, a fictional company;
  40. but you knew that, didn't you?
  41.  
  42. ---
  43.  
  44. CONTENTS
  45.  
  46. - Introduction
  47.  
  48. 1.0       What MailBot does
  49. 1.1       Features
  50. 1.2       Possible Applications of MailBot
  51.  
  52. - Configuration
  53.  
  54. 2.0       Command line parameters
  55. 2.1       How MailBot fits in with KA9Q & Debatchers
  56. 2.2       The Exclude file
  57.  
  58. - Writing MailBot Scripts
  59.  
  60. 3.0       Introduction to MailBot Scripts
  61. 3.1       Example MailBot script
  62. 3.2       Testing MailBot scripts
  63. 3.3       MailBot commands
  64.  
  65. - Error Messages
  66.  
  67. 4.0       General errors
  68. 4.1       Script Syntax errors
  69.  
  70. ---
  71.  
  72. 1.0 What MailBot does
  73. ~~~~~~~~~~~~~~~~~~~~~
  74.  
  75. The Incredible Flying Frisbee Company, being the trendy organisation that
  76. they are, have an Internet connection, so all their customers can e-mail
  77. orders and find out about new products.
  78.  
  79. T.I.F.F.C. use an Acorn machine running KA9Q to access their Demon account.
  80.  
  81. One of the services tiffc.demon.co.uk offers is an information system,
  82. where customers can mail info@tiffc.demon.co.uk and information concerning
  83. T.I.F.F.C. products will be returned to them. Up until now this was run by
  84. hand, every request had to be replied to manually.
  85.  
  86. Not any longer, for MailBot is here. 
  87.  
  88. Mailbot searches a mailbox, and sends a reply to every message in that
  89. mailbox containing a specified file. There are hundreds of possible uses
  90. for this simple function, and it acts as an invaluable replacement for
  91. finger on systems which are not on line 24hrs a day.
  92.  
  93. ---
  94.  
  95. 1.1 Features
  96. ~~~~~~~~~~~~
  97.  
  98. Features
  99.  
  100.  Versatile script language
  101.  Can send any number of messages in response to each request
  102.  Can trigger other programs
  103.  Can search any number of mailboxes
  104.  Optional logging of requests to a file
  105.  Mail loops prevented
  106.  Header and footer files
  107.  Exclusion facility for troublesome users
  108.  
  109. Suggestions for new facilities are welcomed by the author, see the front of
  110. this manual for contact addresses.
  111.  
  112. Details of the latest version of MailBot can be obtained by sending a
  113. message to mbv@xargle.demon.co.uk, and any new releases are announced on
  114. comp.sys.acorn.announce and demon.ip.support.archimedes.
  115.  
  116. ---
  117.  
  118. 1.3 Possible Applications of MailBot
  119. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  120.  
  121. • Making a document or program availiable on your system but keeping  
  122.   track of who has a copy.
  123. • Providing information on a company's products or services.
  124. • A fortune cooky server.
  125. • A substitute for finger for info on users (users of mailbot on a single
  126.   user system should create an "aboutme" mailbot).
  127.  
  128. ---
  129.  
  130. 2.0 Command Line Parameters
  131. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  132.  
  133. The actual MailBot application is run in the form :
  134.  
  135.      mailbot <scriptfile> [-q(uiet)]
  136.  
  137. Where <scriptfile> is the MailBot script to interpret. Appending "-q" to the
  138. mailbot command in the !Run file will suppress all non-essential messages.
  139.  
  140. If no parameters are supplied Mailbot refers to the system variables
  141. MailBot$ScriptFile and MailBot$Options. In normal use these are set in
  142. the !MBotUser.!Options file. So, for silent running you load
  143. !MBotUser.!Options into a text editor, and insert a Q inbetween the quotes
  144. of the line setting MailBot$Options.
  145.  
  146. ---
  147.  
  148. 2.1 How MailBot fits in with KA9Q and debatchers
  149. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  150.  
  151. MailBot reads its input from <Mail$Dir>.spool.mail.text. This means
  152. !MailBot should be run before any debatchers such as !NewsBase or ka9q->rucp
  153. in your dialler script, that is, unless you can modify your debatchers to
  154. take their mail feed from a different directory to prevent them from
  155. debatching mail for !MailBot. Newsbase users can be modified to do this
  156. by loading the file "!NewsBase.transports.ka9q.params" and editing the
  157. line reading "in <Mail$Dir>.spool.mail.text.*" to "in Bot:User.OtherMail.*". 
  158. Once this modification has been performed !NewsBase will not find any e-mail
  159. until after MailBot has been run, preventing any problems. The mail files
  160. are moved by a program called "MailCopy" in the !MBotUser directory, this
  161. is called by the Obey file "!Finished". You should edit "!Finished" and
  162. comment out the "<Obey$Dir>.MailCopy" line if you are not using NewsBase.
  163.  
  164. Mail is sent by inserting directly into the SMTP queue in <Mail$Dir>.spool.
  165. mqueue.work/text.
  166.  
  167. The relevant sections of my SlipDial script (based on Rob Orwin's) with the
  168. modifications for MailBot follow:
  169.  
  170.   #######################
  171.   # Dial Demon and Log on
  172.   :dodial
  173.   set diff 4
  174.   set tmstrt 0
  175.   set tmend 0
  176.   ## kill off newsbase so it won't debatch Mailbot's mail
  177.   task /kill=“Newsbase”
  178.   
  179.   [*** Rest of :dodial unmodified ***]
  180.   
  181.   ###############################################
  182.   # Call has been terminated, so release the port
  183.   :terminate
  184.   task /kill=“TCP/IP”
  185.   message /close
  186.   message “Call Terminated” /centre
  187.   release
  188.   
  189.   # now pause for 1 second to allow RISC OS to sort out the display.
  190.   pause 1
  191.   
  192.   # run MailBot *then* Newsbase.
  193.   task “<Internet$Dir>.!MailBot.!Run”
  194.   task “<Internet$Dir>.!Newsbase.!Run”
  195.   
  196.   #now trim DemHist File
  197.   call trimfile <NNTP$Dir>.DemHist
  198.   
  199.   return 1
  200.  
  201. The next, and most important stage of configuration is writing the script.
  202. The section three explains how to do this.
  203.  
  204. ---
  205.  
  206. 2.2 The Exclude File
  207. ~~~~~~~~~~~~~~~~~~~~
  208.  
  209. The Bot:User.Exclude file should usually be non existant. It lists any users
  210. or groups of users you wish to prevent from using your mailbots. If a user's
  211. address matches a line in the Exclude file no responses are forwarded,
  212. and a note is made in the Log.
  213.  
  214. Hopefully you won't have to resort to using the exclude file, but it would
  215. be extremely naive to suppose that everyone will be ultra considerate about
  216. your paying for their requests (assuming you're using a dial up connection
  217. and you're paying 8) ).
  218.  
  219. Examples:
  220.  
  221. "@vfuture.demon.co.uk"
  222.  -- would ignore requests from john@vfuture.demon.co.uk,
  223.     bob@vfuture.demon.co.uk, phantom@vfuture.demon.co.uk etc.
  224.  
  225. "phantom@vfuture.demon.co.uk"
  226.  -- would ignore requests from phantom@vfuture.demon.co.uk.
  227.  
  228. "aol.com"
  229.  -- would ignore all requests from America On Line subscribers.
  230.  
  231. "x"
  232.  -- would ignore all requests from addresses including the letter x.
  233.  
  234.  
  235. As you may have guessed if an address contains a string from the exclude
  236. list it is ignored. Both the Reply-to: and From: lines are checked.
  237.  
  238. The list is dynamically allocated so you can exclude as many addresses
  239. as your wimpslot will allow.
  240.  
  241. ---
  242.  
  243. 3.0 Writing Mailbot Scripts
  244. ~~~~~~~~~~~~~~~~~~~~~~~~~~~
  245.  
  246. MailBot's scripting language is extremely simple, there are no user
  247. variables, comparative instructions or string handling functions etc.
  248.  
  249. The MailBot Script Language centres around box..endbox structures.  Most
  250. instructions work differently depending on whether they are used outside or
  251. inside one of these structures. 
  252.  
  253. Commands which set a value -----------------------------------------------
  254.    The commands botbox, replyto, botnic, organisation, header, footer
  255. and title if used outside a box/endbox structure set