home *** CD-ROM | disk | FTP | other *** search
/ The CDPD Public Domain Collection for CDTV 4 / CDPD_IV.bin / networking / uucp / amigauucpsupport / trimspool / trimspool.doc next >
Text File  |  1994-06-29  |  19KB  |  566 lines
  1.  
  2.  
  3.  
  4.                                 "TrimSpool"
  5.                             User Documentation
  6.  
  7.                             ##################
  8.                             ##       ##     ##
  9.                             ####   ###   #####
  10.                             ####   ####   ####
  11.                             ####   #####   ###
  12.                             ####   ######   ##
  13.                             ####   ###     ###
  14.                             ##################
  15.  
  16.                                 Version 1.0
  17.              (The "Singing For Mothra / Monster Zero" Release)
  18.  
  19.                               by Gregg Giles
  20.                     Copyright © 1994 by Gregg M. Giles
  21.  
  22.  
  23.                                 06.04.1994
  24.  
  25.  
  26.   -----------------------------------------------------------------------
  27.   PUBLIC RELEASE VERSION - FREEWARE - SPREAD AT WILL - POPULATE THE EARTH
  28.   -----------------------------------------------------------------------
  29.  
  30.  
  31.  
  32.  
  33.  
  34.  
  35. ###########################################################################
  36. #
  37. # Purpose
  38. #
  39. ###########################################################################
  40.  
  41.    TrimSpool  is  designed  as an aid to those running a system receiving a
  42. UseNet feed. Simply, its purpose it to scan through the spool directory and
  43. delete any files equal to or over a certain age (in days) specified by you.
  44.  
  45.    If  you run AmigaUUCP 1.16 or earlier, you'll know that there is no easy
  46. way  to  have  any  bad  or unprocessed mail packets deleted for you - more
  47. often  than  not,  you  have to go through the spool directory manually and
  48. delete  old  mail packets. TrimSpool was written to keep you from having to
  49. do that.
  50.  
  51.    For  a  complete  list  of  improvements  since the last version of this
  52. program, see the section "Revisions & Planned Enhancements".
  53.  
  54.  
  55.  
  56.  
  57.  
  58. ###########################################################################
  59. #
  60. # Features
  61. #
  62. ###########################################################################
  63.  
  64. TrimSpool has the following features:
  65.  
  66. * Permits trimming files equal to or over a certain age (in days) specified
  67. * Permits you to specify the spool directory to process
  68. * Can be run from any script (ideal for use with BBS systems)
  69. * Quiet operation possible
  70. * Debugging features built-in for reporting problems to the author
  71.  
  72.  
  73.  
  74.  
  75.  
  76. ###########################################################################
  77. #
  78. # Requirements
  79. #
  80. ###########################################################################
  81.  
  82. In order to use TrimSpool, you must have the following:
  83.  
  84. *  An Amiga computer
  85.  
  86. *  An  active  UseNet  feed  with UUCP software installed and working. (The
  87.    "AmigaUUCP"  package  by  Matt  Dillon  will  permit you to connect your
  88.    system  to  another  UseNet system - see that package for details or ask
  89.    your local Internet guru for help.)
  90.  
  91. *  Workbench 2.0 or better
  92.  
  93. *  ARexx (must be installed - see your Amiga manual for details)
  94.  
  95. *  The "TrimSpool.rexx" ARexx script (supplied)
  96.  
  97.  
  98.  
  99. What you do NOT need to use TrimSpool:
  100.  
  101. *  TrimSpool  does NOT require any special BBS package. It can, however, be
  102.    used with ANY bulletin board system package with no problems. (TrimSpool
  103.    operates completely independently of both AmigaUUCP and any BBS software
  104.    which you may have in operation.)
  105.  
  106. *  TrimSpool does NOT require any special registration keys to work.
  107.  
  108.  
  109.  
  110.  
  111.  
  112. ###########################################################################
  113. #
  114. # Installation
  115. #
  116. ###########################################################################
  117.  
  118.    TrimSpool  can be run from anywhere. For best results, ensure that it is
  119. located in a directory within your machine's search path. An ideal location
  120. is in your C: directory.
  121.  
  122.    There are no other requirements for installation.
  123.  
  124.  
  125.  
  126.  
  127.  
  128. ###########################################################################
  129. #
  130. # Usage
  131. #
  132. ###########################################################################
  133.  
  134.    TrimSpool  is not currently executable from the Workbench, so it must be
  135. used from the Shell. The usage for this program is:
  136.  
  137.  
  138.    rx TrimSpool SOURCE <spool_dir> DAYS <days> [DEBUG=<level>] [QUIET]
  139.  
  140.  
  141.    For  further  details  on what each of these command line parameters do,
  142. see the section titled "Command Line Flags".
  143.  
  144.  
  145.  
  146.  
  147.  
  148. ###########################################################################
  149. #
  150. # Command Line Flags
  151. #
  152. ###########################################################################
  153.  
  154.    The  program  makes  use  of command line "flags", also known as command
  155. line  "arguments",  which  will  greatly  enhance the program's utility and
  156. power.   Flags  are not case sensitive, but must be spelled correctly to be
  157. understood by the program.
  158.  
  159.    The current flags available are:
  160.  
  161.  
  162.  
  163. ###########################################################################
  164. # DAYS
  165. ###########################################################################
  166.  
  167. Flag Name  : DAYS
  168. Template   : DAYS <days>
  169. Default    : n/a
  170.  
  171. Description: 
  172.  
  173. Specifies  the cut-off age in days which TrimSpool will use to delete files
  174. from  the spool directory. Any files which were received or created by your
  175. system and have an age (in days) equal to or older than this specified date
  176. will  be deleted. Caution: if you have any outbound mail which has not been
  177. processed, it will also be subject to deletion.
  178.  
  179. WARNING:  A  "DAYS"  value  of  1  will  delete  *all*  files in your spool
  180. directory!  Use  this  value with extreme caution, and *only* after you are
  181. positive  that  you  have properly delivered and processed all incoming and
  182. outgoing  mail,  and  that  you are aware that any log files stored in your
  183. spool directory will be deleted.
  184.  
  185. As  a  safety  precaution  (please read the section titled "Mail Processing
  186. While  Running  TrimSpool"), it is recommended that you set your DAYS value
  187. to no fewer than 3 days when running TrimSpool from a Cron. The recommended
  188. expirate  age  is 7 days. Only use a value below 3 if you are positive that
  189. your  incoming and outgoing UseNet mail is being properly processed by your
  190. system.
  191.  
  192. CAUTION:  If  you value any UUCP logfiles which are stored in spool, it's a
  193. good  idea  to  back  them  up  before  they fall victim to old age and are
  194. deleted  by TrimSpool (it's a good idea to back up your logfiles nightly if
  195. you want to keep them for future reference).
  196.  
  197.  
  198.  
  199. ###########################################################################
  200. # DEBUG
  201. ###########################################################################
  202.  
  203. Flag Name  : DEBUG
  204. Template   : DEBUG=<debugging_level>
  205. Default    : DEBUG=0
  206.  
  207. Description: 
  208.  
  209. When  supplied,  debugging information is displayed on the screen.  A value
  210. of 1-9 must be supplied; the higher the number, the more verbose the output
  211. will be.  The following values will yield the following results:
  212.  
  213. 0  No debugging output (default)
  214. 1  Display name of data files and source directorie
  215. 2  <not implemented>
  216. 3  <not implemented> 
  217. 4  <not  implemented> 
  218. 5  Show file information, keyword stubs, variable values
  219. 6  Show library and file openings and closings, display function calls,
  220.    important comments
  221. 7  <not implemented>
  222. 8  <not implemented>
  223. 9  <not implemented>
  224.  
  225. Note:  when  any debugging level greater than 0 is active, no files will be
  226. deleted,  even  if they are equal to or older than the specified expiration
  227. date  given  with  the  DAYS  parameter.  This  is  done so that a user may
  228. successfully  get  debugging  information  without  harming  the  files  in
  229. question.
  230.  
  231.  
  232. ###########################################################################
  233. # SOURCE
  234. ###########################################################################
  235.  
  236. Flag Name  : SOURCE
  237. Template   : SOURCE <spool_dir>
  238. Default    : n/a
  239.  
  240. Description: 
  241.  
  242. Specifies  the  source  directory  (your  system's  spool  directory) which
  243. TrimSpool will examine. This value may be either a complete drive/path name
  244. or  a logical assignment (ie: "sys:"). If you specify a directory, it isn't
  245. necessary  to  end it with a slash, since TrimSpool will check for this and
  246. add one if absent.
  247.  
  248.  
  249.  
  250. ###########################################################################
  251. # QUIET
  252. ###########################################################################
  253.  
  254. Flag Name  : QUIET
  255. Template   : QUIET
  256. Default    : n/a
  257.  
  258. Description: 
  259.  
  260. Suppresses  all  screen  output,  with  the  exception  of  error messages.
  261. Debugging information is not effected by the QUIET flag.
  262.  
  263.  
  264.  
  265.  
  266.  
  267. ###########################################################################
  268. #
  269. # Usage Examples
  270. #
  271. ###########################################################################
  272.  
  273.    The  following example will run TrimSpool as a background task, and will
  274. delete any files in the specified spool directory that are equal to or over
  275. 3 days old:
  276.  
  277.    run rx TrimSpool SOURCE <spool_dir> DAYS 3
  278.  
  279.  
  280.    The  following  example  will  display  no  output (except for any error
  281. messages) to the Shell; any files in your spool directory equal to or older
  282. than 3 days will be deleted:
  283.  
  284.    rx TrimSpool SOURCE <spool_dir> DAYS 3 QUIET
  285.  
  286.    The  following  example  will display debugging information which can be
  287. used  to  report  problems  to  the program author (note: when debugging is
  288. active,  the files in the spool directory will not be deleted, even if they
  289. are  equal  to  or older in age than the specified expiration date given by
  290. the DAYS parameter):
  291.  
  292.    rx TrimSpool SOURCE <spool_dir> DAYS 6 DEBUG=5
  293.  
  294.  
  295.  
  296.  
  297.  
  298. ###########################################################################
  299. #
  300. # Script File Usage
  301. #
  302. ###########################################################################
  303.  
  304.    TrimSpool  can  be  run from an AmigaDOS or ARexx script. In an AmigaDOS
  305. script, add the line:
  306.  
  307.    rx TrimSpool SOURCE <spool_dir> DAYS 5
  308.  
  309.    In an ARexx script, add the line:
  310.  
  311.    address command 'rx TrimSpool SOURCE <spool_dir> DAYS 5'
  312.  
  313.    ...  where  SOURCE is your spool directory. You will need to fill in the
  314. <spool_dir> value with the appropriate directory name or assignment.
  315.  
  316.  
  317.  
  318.  
  319.  
  320. ###########################################################################
  321. #
  322. # Running TrimSpool From A Cron
  323. #
  324. ###########################################################################
  325.  
  326.    TrimSpool can be run from a Cron just like any normal ARexx script. This
  327. can  be useful if you are running a system which receives a large amount of
  328. mail, and you need to ensure that you have as much storage free as possible
  329. (since  old  mail  in  the  spool directory can often accumulate). See your
  330. Cron's documentation for details.
  331.  
  332.    It  is recommended that you run TrimSpool at least once per week, if not
  333. more  frequently. The recommended minumum expiration age is 3 days (see the
  334. section titled "Mail Processing While Running TrimSpool" for details).
  335.  
  336.    The  following example is placed within the "EventList.TAB" file used by
  337. Matt  Dillon's  "CyberCron"  event  handler; it runs TrimSpool every Sunday
  338. (day 0) midnight, deleting all files equal to or over 7 days old:
  339.  
  340.    0 0 0 * * rx TrimSpool SOURCE <spool_dir> DAYS 7
  341.  
  342.    The next example also uses CyberCron, and runs TrimSpool at 18:00, every
  343. Tuesday  (day  3) and Saturday (day 6) evening, deleting all files equal to
  344. or over 3 days old:
  345.  
  346.    0 18 3,6 * * rx TrimSpool SOURCE <spool_dir> DAYS 3
  347.  
  348. Note that TrimSpool's processing time is completely dependent upon how many
  349. files must be processed as well as your system speed.
  350.  
  351.  
  352.  
  353.  
  354.  
  355. ###########################################################################
  356. #
  357. # Troubleshooting
  358. #
  359. ###########################################################################
  360.  
  361.    It  is possible that you will encounter an error in some form or another
  362. during  your  use  of  this  program.   All error messages generated by the
  363. program are listed and explained below.
  364.  
  365. Message    : "Error: cannot open rexxsupport.library" 
  366. Explanation: The ARexx library "rexxsupport.library" could not be opened.
  367. What to do : Ensure that the file "libs:rexxsupport.library" exists. If  it
  368.              does and you still experience this problem, panic. :)
  369.  
  370. Message    : "Error: couldn't get file information on <filename>"
  371. Explanation: The  file  being  examined  was  probably in use 
  372. What to do : Nothing. Odds are that the file which TrimSpool is  trying  to
  373.              get  information on is a temporary file being received by your
  374.              system. (Since it is a new file, there really is no problem to
  375.              worry about.)
  376.  
  377. Message    : "Error: invalid DAYS value supplied"
  378. Explanation: The command line argument "DAYS" was given a bad value.
  379. What to do : Use a value of 1 or greater (see section titled "Command  Line
  380.              Flags"  and "Mail Processing While Running TrimSpool" for more
  381.              details about the DAYS flag).
  382.  
  383. Message    : "Error: invalid DEBUG value - not displaying debug information"
  384. Explanation: The command line argument "DEBUG" was given a bad value.
  385. What to do : Use a debugging value of 1-9 (see section titled "Command Line
  386.              Flags" for more details about the DEBUG flag).
  387.  
  388. Message    : "Error: no source directory specified"
  389. Explanation: No source directory was given at all.
  390. What to do : Specify your source directory using the "SOURCE" flag. See the
  391.              section  titled "Command Line Flags" for details on how to use
  392.              this flag.
  393.  
  394. Message    : "Error: source directory doesn't exist (<directory name>)"
  395. Explanation: The specified source directory doesn't exist
  396. What to do : Check to make sure you gave the correct path and spelling  for
  397.              your  source  directory.  Next  make  sure  that the directory
  398.              actually exists.
  399.  
  400.  
  401.  
  402.  
  403.  
  404. ###########################################################################
  405. #
  406. # Mail Processing While Running TrimSpool
  407. #
  408. ###########################################################################
  409.  
  410.    If  you're  concerned about TrimSpool harming unprocessed mail, or about
  411. running  TrimSpool  while  your  system  is receiving mail, don't be. It is
  412. assumed  that  you  process your inbound mail on a regular basis, generally
  413. immediately  after  a  UUCP session has completed; if you do this, then you
  414. are  safe.  Since  TrimSpool  is usually told to work only on old files, it
  415. is  not  possible for it to harm new inbound or outbound mail. 
  416.  
  417.    If  you  would  like  to test TrimSpool without harming your spool files
  418. just  to  convince yourself it works, issue this command (where <spool_dir>
  419. is your spool directory, and you want to delete any files equal to or older
  420. than <x> days):
  421.  
  422.    rx TrimSpool SOURCE <spool_dir> DAYS <x> DEBUG=1
  423.  
  424.    The  above  command  will  process  all  files  in  your spool directory
  425. normally,  but  it  will not delete them. The age of each file is displayed
  426. during the directory processing, proving that it's doing what it's supposed
  427. to be.
  428.  
  429.    CAUTION:  TrimSpool  can  really  only  delete  unprocessed  incoming or
  430. outgoing  mail  if  something  prevents  your  mail from being processed or
  431. delivered  properly.  If your incoming or outgoing mail sits around in your
  432. spool for long enough for some reason, it is quite likely that it will fall
  433. victim to old age and be deleted by TrimSpool. Your unprocessed mail could
  434. fall victim to old age for one of these reasons:
  435.  
  436.    1) Your  inbound  mail  isn't  being processed properly by your  system,
  437.       builds up in your spool directory, and thereby ages itself.
  438.  
  439.    2) Your outbound mail isn't being delivered properly to your host system
  440.       due  to some technical problem (your feed goes down, your system goes
  441.       down,  problems  connecting  with  the  feed, etc.), collects in your
  442.       spool directory, and thereby ages itself.
  443.  
  444.    There  is  nothing  that  can be done about this except making sure that
  445. your  system  operates  properly and that all incoming and outgoing mail is
  446. processed  on time. As a safety, it is discouraged to use an expiration age
  447. of  one  day - three days is actually a recommended minimum, and seven days
  448. is  a  safe  setting to use (if your system is working correctly and hasn't
  449. been  able  to  process  a  mail  packet for seven days, chances are pretty
  450. darned good that the mail packet is bad).   :)
  451.  
  452.  
  453.  
  454.  
  455.  
  456. ###########################################################################
  457. #
  458. # Program Background
  459. #
  460. ###########################################################################
  461.  
  462.    I  got  sick of having to delete old, unprocessed (error) mail piling up
  463. in  my spool directory manually, I couldn't find a utility to do it for me,
  464. and I was bored, so I wrote this. :)
  465.  
  466.  
  467.  
  468.  
  469.  
  470. ###########################################################################
  471. #
  472. # Revisions & Planned Enhancements
  473. #
  474. ###########################################################################
  475.  
  476.    The  following changes have been made to this program since the previous
  477. version:
  478.  
  479. * No previous version.
  480.  
  481.  
  482.  
  483. Known bugs in this version:
  484.  
  485. * None.
  486.  
  487.  
  488.  
  489. Planned Enhancements:
  490.  
  491. * None planned, unless somebody wants them.
  492.  
  493.  
  494.  
  495.  
  496. ###########################################################################
  497. #
  498. # Legalese
  499. #
  500. ###########################################################################
  501.  
  502.    This  program  is  freeware  and  may  be  copied and distributed freely
  503. without  the  consent  of  the  author for non-commerical purposes where no
  504. charge is made for the copying or distribution of this program.
  505.  
  506.    Commerical  sale  or  use, duplication, distribution, or modification of
  507. this program is forbidden without the consent of the author.
  508.  
  509.   The  following  people  and  organizations  are  entitled to include this
  510. program  in  their  public domain collections as a thank-you for all of the
  511. work  they  have  done  to  promote the Amiga and provide scum like us with
  512. decent public domain software:
  513.  
  514.    * Fred Fish
  515.    * AmiNet (all sites)
  516.    * Walnut Creek CD-ROM [Restriction: I must receive one copy of any
  517.          CD-ROM on which this utility appears since it is copyright.]
  518.    * Amiga Atlanta, Inc.
  519.    * Eugene/Springfield Amiga Users' Group (ESAUG)
  520.    * All other Amiga users' groups
  521.  
  522.  
  523.  
  524.  
  525.  
  526. ###########################################################################
  527. #
  528. # Contacting The Author
  529. #
  530. ###########################################################################
  531.  
  532. To contact the author of this program, use any of the following addresses:
  533.  
  534. US Mail Address : Gregg Giles
  535.                   3330 Kinsrow 217
  536.                   Eugene, OR 97401-8824 USA
  537.  
  538. FidoNet NetMail : 1:152/18 as "Sysop" (Sensory Overload BBS)
  539.  
  540. Internet Mail   : ggiles@so.efn.org (your best best)
  541.                   ggiles@efn.org (forwarded)
  542.                   ggiles@cie-2.uoregon.edu (forwarded)
  543.  
  544.                   If those fail, try these last resort addresses...
  545.  
  546.                   ggiles@cie.uoregon.edu
  547.                   ggiles@greylady.uoregon.edu
  548.  
  549. Sensory Overload: 503-484-1281, 14.4 kbps as "Sysop"
  550.  
  551. Donations and contributions will be accepted, but are not demanded.
  552.  
  553.  
  554.  
  555.  
  556.  
  557. ###########################################################################
  558. #
  559. # Thanks For Inspiration/Entertainment
  560. #
  561. ###########################################################################
  562.  
  563.    LA Style, Wiz 'N' Liz, Red Dwarf, the fruit I'm eating at the moment and
  564. can't  remember  the  name  of, that stupid Godzilla movie with those goofy
  565. Japanese girls singing to Mothra, and Monster Zero.
  566.