home *** CD-ROM | disk | FTP | other *** search
/ ftp.wwiv.com / ftp.wwiv.com.zip / ftp.wwiv.com / pub / BBS / SQFLO129.ZIP / SQFILTER.DOC < prev    next >
Text File  |  1995-06-04  |  17KB  |  399 lines
  1. SqFilter v1.29 - Message & file bases tools - (c) Raphaël Vanney, 06/95.
  2.  
  3.  
  4.       ┌─────────────────────────────────────────────────────────┐
  5.       │ This program comes with no kind of warranty whatsoever. │
  6.       │   I do _not_ garantee that it will not delete each and  │
  7.       │   every file on your hard disk (nor do I garantee that  │
  8.       │       it will do that : it's not its purpose :-))       │
  9.       └─────────────────────────────────────────────────────────┘
  10.  
  11.  
  12.                          I need your comments !
  13.  
  14.            You may reach me, for bug reports or enhancements
  15.          requests (or whatever, including congratulations :-)),
  16.                       at the following addresses :
  17.  
  18.                 FidoNet : 2:320/215.9
  19.                 e-mail  : rvanney@ibm.net
  20.                        or zlika@chaos2.frmug.fr.net
  21.  
  22.    Other good reasons to drop me a line if you use SqFilter include :
  23.     - it's always nice to know that people are using your products,
  24.     - you will be notified when a new version of SqFilter gets out.
  25.  
  26.  
  27.          If you send me a bug report, it helps if you include :
  28.     - the version of SqFilter you use (version number, DOS or OS/2),
  29.     - your configuration files (SqFilter.Cfg and include files),
  30.     - other configuration files where appropriate (Squish.Cfg,
  31.       FileArea.Ctl, Areas.BBS, SysFile.Dat),
  32.     - SqFilter's log file when run with the 'Debug' command-line
  33.       parameter,
  34.     - a description of what happens and how,
  35.     preferably zipped and UUEncoded. Hopefully, with all that
  36.     information, solving your problem will be a piece of cake.
  37.  
  38.                    ╔════════════════════════════════╗
  39.                    ║ Hey, folks, this is freeware ! ║
  40.                    ╚════════════════════════════════╝
  41.  
  42.           You are highly encouraged to distribute it widely !
  43.  
  44.                                Oh, yes :
  45.  
  46.     "This product uses the JAM(mbp) API -
  47.      Copyright 1993 Joaquim Homrighausen, Andrew Milner, Mats Birch,
  48.                     Mats Wallin. ALL RIGHTS RESERVED."
  49.  
  50. I- What is SqFilter
  51. ───────────────────
  52.  
  53. SqFilter was originally designed to help me not to miss messages that
  54. could be of interest to me among the flow that reaches my point system
  55. each day. It searches through designated message bases for strings and
  56. places the messages that correspond to the searching criterias in a
  57. destination message base.
  58. One of the first usages people may have for SqFilter is to search for
  59. messages addressed to them and put these messages in a particular
  60. message base.
  61. I recently added the statistics feature because I needed to check the
  62. ability of my Squish base object to write messages. Furthermore, it's
  63. not a big step when you scan a message base to gather statistics.
  64. Then came the Allfix request processor, which was added because I was
  65. not really happy with the AllFix program, and I thought this would be a
  66. good step towards the file anouncement utility, which was added a few
  67. days later.
  68.  
  69. To sum it up, SqFilter is :
  70.         . a message filter,
  71.         . an Allfix requests processor,
  72.         . a new files announcer,
  73.         . a files listing generator,
  74.         . a statistics gatherer.
  75.  
  76. II- How to use SqFilter
  77. ───────────────────────
  78.  
  79. SqFilter should be run periodically (for instance each time you toss new
  80. mail). When run, SqFilter will read its configuration file, then do its
  81. job as specified in the configuration file.
  82.  
  83. To run, SqFilter needs a file named SqFilter.Cfg in the directory where
  84. SqFilter.Exe resides. It will create a file named SqFilter.Log in the
  85. same directory, except if specifically asked otherwise using the LOG:
  86. command line parameter.
  87.  
  88. The following optional command-line parameters are available :
  89.  
  90.         Debug      : displays & log a bunch of information. Sets
  91.                      maximum log level.
  92.         ReScan     : discards last-read information ; completely rescan
  93.                      all messages bases.
  94.         Log1       : selects log level 1 (fine for normal use)
  95.         Log2       :    "     "    "   2
  96.         Log3       :    "     "    "   3
  97.         Log4       :    "     "    "   4 (heavy duty log file)
  98.         Log:<file> : use <file> as a log file
  99.         <filename> : uses <filename> as a configuration file
  100.  
  101. III- How to configure SqFilter
  102. ──────────────────────────────
  103.  
  104. See the file SqFilter.Cfg.
  105.  
  106. IV- Compatibility issues, limitations
  107. ─────────────────────────────────────
  108.  
  109. * SqFilter opens all message bases in shared mode, and locks them when
  110.   appropriate (well, except for *.MSG bases, that is). This should
  111.   garantee proper operation with other well-designed programs. Beware,
  112.   however, that not all maintenance utilities are well-designed.
  113.  
  114. * The DOS version may raise some problems due to memory limitations, or
  115.   number of opened files limitation. If memory problems appear, I may
  116.   release a DPMI version. Number of opened files problems are handled
  117.   through the FILES= command of the DOS CONFIG.SYS.
  118.  
  119. * There seems to be many, many ways to guess the origin address of a
  120.   message ; SqFilter uses two that seem quite standard : 1/ the address
  121.   specified in the message's header ; unfortunately, this sometimes is
  122.   not filled or, worse, contains wrong information. 2/ the address given
  123.   by the MSGID kludge line ; when present, this one should always be
  124.   correct.
  125.   If there is demand for this, I might try to fetch the one in the
  126.   origin line as well.
  127.  
  128. * SqFilter can't handle messages bigger than 64k.
  129.  
  130. V- About the internals of SqFilter
  131. ──────────────────────────────────
  132.  
  133. * SqFilter uses the Squish specification as defined in the Squish
  134.   Developpers Kit version 2.0. Among other things, this means that the
  135.   Squish areas where SqFilter writes messages need not be packed: the
  136.   number of messages, hence the size of the file, will stop growing when
  137.   a maximum defined in the configuration file has been reached. See the
  138.   'SquishMaxMsg' and 'To' keywords in SqFilter.Cfg for more information.
  139.  
  140. * The Hudson and JAM bases handling code is mostly not mine, though I
  141.   had to modify it to run under OS/2. This means that I may not be aware
  142.   of hidden bugs, nor am I really responsible for performance.
  143.  
  144. * I'm not aware of any official method to lock fido *.MSG bases, so I
  145.   don't perform any kind of locking on them.
  146.  
  147. * SqFilter supports the "AREA:" "kludge". If this "kludge" is also
  148.   supported by your mail reader, this will enable your reader to let you
  149.   respond to messages in the area where the message originally was (the
  150.   'N' key in GoldEd).
  151.  
  152. * SqFilter generates a "CHRS:" kludge in its messages.
  153.  
  154. * SqFilter uses the country information from your system.
  155.  
  156. * SqFilter needs a 286+ operated by DOS 3.3+ (DOS version) or any
  157.   version of OS/2.
  158.  
  159. VI- History
  160. ───────────
  161.  
  162.       If you are upgrading from a previous version, this is _the_
  163.           place where to look for new features and bug fixes.
  164.  
  165. 16/07/94 version 0.02ß
  166.     First public release.
  167.  
  168. 16/07/94 version 0.03ß
  169.         Now opens files in shared mode.
  170.     Handles the situation where a base is already opened in
  171.       exclusive mode by another process.
  172.     OS/2 executable version. File locking not thoroughly tested.
  173.           Does not fully support HPFS file names. I guess I'm gonna have
  174.           to wait for Borland to make an OS/2 version of BP for full
  175.           HPFS support.
  176.  
  177. 17/07/94 version 0.04ß
  178.         Now handles the 'AreaFile AreasBBS' configuration option.
  179.         Extended log options, user configurable.
  180.  
  181. 20/07/94 version 0.05ß
  182.         The base is now locked when scanned. This should not normally be
  183.       necessary, but it looks like some programs lock a greater part
  184.           of the file than they should.
  185.         Performance statistics in log file (LogLevel>=2).
  186.         Changed the mode used for file opens under OS/2.
  187.  
  188. 23/07/94 version 0.06ß
  189.         Reorganised message base objects so that adding new message
  190.           bases types will be kinda piece of cake.
  191.         Corrected something that looked like a hidden bug.
  192.         Added the 'UnScan' keyword in the configuration file.
  193.         Changed the processing method so that a message base is no
  194.           longer scanned twice if two message filters need it. Drawback
  195.           is I can't keep destination bases locked during the whole
  196.           process. Another drawback is that most certainly DOS users
  197.           will hit the maximum number of opened files limit. OTOH, this
  198.           garantees much greater consistancy in lastread pointers in
  199.           case of error, and much greater speed.
  200.  
  201. 24/07/94 version 0.07ß
  202.         Destination bases are now instanciated only once. This allows to
  203.           lock them, and presumably to enhance speed, specially if there
  204.           are a lot of write operations. DOS users are less likely to
  205.           encounter the max opened files limit, but still. As of today,
  206.           DOS users should not define more than three filters that write
  207.           to the same destination base _and_ scan at least one common
  208.           base.
  209.         Added the 'Stat' keyword (and functionality!)
  210.  
  211. 25/07/94 version 0.08ß
  212.         Taken care of the 'Too many open files' threat. It's now much,
  213.           much less likely to happen.
  214.         Added the 'StatMsgFrom', 'StatMsgTo', 'StatMsgSubject' keywords.
  215.         French configuration file.
  216.         Tried some optimization tricks that did not work. If I were to
  217.           believe Turbo-Profiler, I can't do anything to improve speed.
  218.  
  219. 31/07/94 version 0.09ß
  220.         Added the 'TrackKeyWord' undocumented keyword.
  221.         Done a little change that should improve speed on slower CPUs.
  222.         Done another change that improved performance by 30% (as measured
  223.           by the number of messages processed per second).
  224.         Fixed a bug when reducing the size of the log file (at best, blank
  225.           lines would appear in the log file).
  226.         Fixed a bad behaviour when trying to lock a file that's already
  227.           locked by another process.
  228.         Added command-line configuration file name.
  229.         Added date in stat messages body.
  230.  
  231. 03/08/94 version 0.10ß
  232.         A date was not filled in the message header.
  233.  
  234. 03/08/94 version 0.11ß
  235.         Added fido *.MSG message bases support. Look out for bugs !
  236.  
  237. 04/08/94 version 0.12ß
  238.         Added support for country information, plus French program
  239.           messages.
  240.         Added the 'français' keyword. This makes the program generate
  241.           French output. Automagic if your country code is 33.
  242.  
  243. 09/08/94 version 0.13ß
  244.         Added an Allfix requests processor.
  245.  
  246. 10/08/94 version 0.14ß
  247.         Fixed bug when no AfxReqArea was defined.
  248.         Various and numerous improvements to the Allfix processor.
  249.         Added Lora SYSFILE.DAT reading ability.
  250.         Fixed bug in origin network address when creating messages.
  251.  
  252. 11/08/94 version 0.15ß
  253.         Added 'Log:' command-line parameter.
  254.         Added processing of Allfix 'second requests' (requests directed
  255.           to 'SqFilter z:n/n.p' gets list of remaining files).
  256.         Added new files announcement feature.
  257.         Slightly changed file areas configuration.
  258.  
  259. 15/08/94 version 0.16ß
  260.         Fixed a huge bug in the OS/2 version.
  261.         Added support for Maximus' FILEAREA.CTL file.
  262.  
  263. 16/08/94 version 0.17ß
  264.         Cosmetic changes.
  265.  
  266. 03/09/94 version 1.00
  267.         Fixed a bug in the 'AreaFile' & 'Area' keywords, when the area
  268.           tag was not uppercased.
  269.         Added the 'LockMaxDelay' keyword.
  270.         Cosmetic changes.
  271.         Added the undocumented 'Rescan' configuration keyword.
  272.         Added the 'English' configuration keyword.
  273.         Added some trace in debug mode.
  274.         Got out of the beta status.
  275.  
  276. 04/09/94 version 1.01
  277.         Added the 'NFASubject' configuration keyword.
  278.         Sped-up the files scanning.
  279.  
  280. 08/09/94 version 1.02
  281.         Gone back to the previous files scanning method to fix a bug.
  282.  
  283.          version 1.03
  284.         Cosmetic change.
  285.         Added some error checking.
  286.         Corrected a bug with the date handling (should have affected a
  287.           field in Squish messages).
  288.  
  289. 12/09/94 version 1.10ß
  290.         Added the JAM bases support, thus the following keywords :
  291.           'JAMUserName', 'JAMUserCRC'. Available for beta-testing.
  292.  
  293. 13/09/94 version 1.11ß
  294.         Changed the way kludge lines are internally handled.
  295.         Fixed a bug with locking JAM bases.
  296.         Fixed several bugs in the JAM bases handling which were introduced
  297.           with the OS/2 version -and made JAM bases unuseable.
  298.         Added an all files listing generator, configured with the keywords
  299.           'AFLFileHdr', 'AFLFileFtr', 'AFLScan' and 'AllFilesListing'.
  300.  
  301. 13/09/94 version 1.12ß
  302.         Cosmetic changes in the 'all files' listing.
  303.  
  304. 19/09/94 version 1.20ß
  305.         Better JAM message flags support.
  306.         Added Hudson bases support ; huge kludge. New keywords :
  307.           'HudsonPath', 'HudsonUserNo'. Unlike JAM bases, Hudson bases
  308.           are also supported through the AREAS.BBS configuration file.
  309.         Removed a bug with kludge lines handling in reading Squish bases
  310.           when the kludges where misplaced.
  311.         Fixed a bug with JAM dates handling.
  312.         Added some information in the log file in case of 'too many open
  313.           files' error (DOS version).
  314.         The .NFA file name is now made after the config file name. This
  315.           enables you to announce new files from different file areas in
  316.           different message areas, by using different config files.
  317.         Added Squish.Cfg support in the 'AreaFile' keyword.
  318.         Fixed a bug where the Hudson bases where never closed.
  319.  
  320. 20/09/94 version 1.21ß
  321.         Added understanding of JAM areas defined in AREAS.BBS file.
  322.  
  323. 09/10/94 version 1.22ß
  324.         Fixed a bug in Hudson bases where messages longer than 16kb
  325.           would cause unpredictable behaviour.
  326.         Added the 'NFAUnScan' keyword.
  327.         Cosmetic changes.
  328.         (Temporarily ?) removed OS/2-specific popup error window.
  329.         Re-inserted the beta warning in the cfg file.
  330.  
  331. 04/12/94 version 1.23
  332.         Added 'TOPT' and 'FMPT' kludges handling.
  333.         Added the 'PopupOnError' keyword (OS/2 version only).
  334.  
  335.          version 1.24
  336.         Fixed a bug with OS/2's RTL (DOSFindFirst) which resulted in
  337.          lots of unfound files in file listings.
  338.         Added country code 2 (French-speaking Canada now has French
  339.          as a default language.)
  340.         Fixed a bug in the new files announcer where older files would
  341.          be announced again when the NFA file fills up.
  342.  
  343. 01/04/95 version 1.25
  344.         (note : this is not a joke)
  345.         Added handling of 'AND' and 'OR' operators in allfix requests.
  346.  
  347. 19/04/95 version 1.26
  348.         Squish.Cfg files now can really be used.
  349.         Filters TAB characters in configuration files ; TAB characters have
  350.          been known to cause nice problems...
  351.         Added the 'StatFtr' keyword.
  352.  
  353. 04/05/95 version 1.27
  354.         Added some log info in case of error.
  355.         Added the 'orgaddr' and 'destaddr' section keywords in filter
  356.          definitions (see the 'Include' keyword in SqFilter.Cfg for
  357.          details).
  358.         Corrected a bug with date calculations in April.
  359.         Added the files areas statistics feature ('FStArea', 'FStFtr',
  360.          'FStScan', 'FStUnScan', 'FStSubject' keywords).
  361.         Now uses the originate's MSGID kludge when answering a message.
  362.         Now handles *.MSG style bases in Squish.Cfg.
  363.         Worked around a bug that caused a failure when using a
  364.          FileArea.Ctl file.
  365.  
  366. 20/05/95 version 1.28
  367.         Now ignore passthru areas in Squish.Cfg.
  368.         Now adds a 'MSGID' kludge to the written messages.
  369.         Added the 'template' concept. Lots of new keywords.
  370.         Now processes allfix requests, new files announces and
  371.          statistics before filters ; this allows forwarding of such
  372.          messages by way of filters without re-running SqFilter.
  373.         Added the 'AreasWrittenTo' keyword (EchoToss.Log-like thing).
  374.         Added the 'Include' keyword.
  375.  
  376. 04/06/95 version 1.29
  377.         Added the 'Lora' option to the 'AreaFile' keyword.
  378.         Fixed a bug where SqFilter would add a '\' after the FILELIST
  379.          file name in Maximus FileArea.Ctl processing.
  380.         Fixed a problem with more-than-25-lines displays.
  381.  
  382. VII- Planned enhancements
  383. ─────────────────────────
  384. * Short term
  385.         I think SqFilter could be used to send messages to warn whoever
  386.           you want that something's wrong with the machine it runs on
  387.           (free disk space, size of a directory, whatever), and to
  388.           answer messages from a user to SqFilter regarding
  389.           configuration, directory tree, whatever... Ideas welcome.
  390.  
  391. * Long term (depends on demand)
  392.         Make use of other BBS's configuration files.
  393.         Logical operators within include/exclude specifiers.
  394.         Full HPFS support.
  395.         Handling of the CHRS/CHARSET kludges for string searches.
  396.  
  397. -----------------------------------------------------------------------------
  398.  
  399.