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