home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / pofamuup.zip / POFAMU.INF (.txt) < prev    next >
OS/2 Help File  |  2000-06-08  |  16KB  |  373 lines
  1.  
  2. ΓòÉΓòÉΓòÉ 1. PMMAIL Offline Folder Archive and Maintenance Utility ΓòÉΓòÉΓòÉ
  3.  
  4. This program is for the 'offline' maintenance of PMMAIL folders, meaning that 
  5. PMMAIL should not be running when it is invoked. It is designed for 
  6. user-programmers; i.e., not for the GUI-bred. The program is directed almost 
  7. entirely from a control file. 
  8.  
  9. The program allows the user to specify selection criteria for mail messages 
  10. using the fields maintained by PMMAIL in its index files. These criteria are 
  11. assigned Reserved Names by POFAMU such as From_name, From_addr and are used to 
  12. form boolean expressions.  These expressions are assigned user identifiers 
  13. called Spec-names. These Spec-names are used to assign specified actions to 
  14. selected groups of messages. 
  15.  
  16. Support has been added to attempt to accomodate users of PMMail version 1.53 
  17. which has an ACCT.CFG file rather ACCT.INI. 
  18.  
  19.  What I would recommend is running this utility at some fixed interval (weekly 
  20. or so), rather than waiting until you are overrun with mail. I run it 3 times a 
  21. week (probably more than necessary) as part of a CRON arrangement. 
  22.  
  23.  
  24. ΓòÉΓòÉΓòÉ 2. Installation ΓòÉΓòÉΓòÉ
  25.  
  26. This isn't a GUI program, so I haven't considered building a desktop object for 
  27. it, as part of installation.  Just copy POFAMU.EXE to any directory in your 
  28. PATH statement.  You might want to copy a program template to the desktop and 
  29. build an object that references your 'daily' control file in the Parameters 
  30. field. Also copy CWIND.EXE to a directory in your PATH.  This program sends a 
  31. polite WM_CLOSE to one or more windows in the Window List. 
  32.  
  33. Using any ASCII text editor, edit your control file and place it in the working 
  34. directory referenced by the new program object. 
  35.  
  36. You might want to add the invocation to your 'chron' or 'alarm clock' program 
  37. if you are running round the clock. As of Rel. 1.12, cwind.exe will be supplied 
  38. to allow the user to close PMMail from a script. In your script, invoke it with 
  39. 'cwind PMMail'.  This isn't the best implementation for this and better 
  40. 'closers' may be found on Hobbes and LEO. There are also programs to open WPS 
  41. objects which may be used to restart PMMail after running maintenance. 
  42.  
  43. You may also indicate a REXX script to be used via the PMMAIL Settings notebook 
  44. item and have the script execute in 'Force' mode on exit from PMMAIL. This does 
  45. not give you the opportunity to preview the results as does CheckOut, but it is 
  46. automated.  See 'Mode' below. 
  47.  
  48. POFAMU does not normally re-index your PMMAIL folders. It relies on the user 
  49. having kept his PMMAIL folders in order via the 're-index' menu function. 
  50. Before first use of POFAMU, it's advisable to re-index your folders. See the 
  51. indexing feature below. 
  52.  
  53.  INFO-ZIP and UNZIP are required for operation of the Archive function. The ZIP 
  54. switches -m -j -@ are used. 
  55.  
  56.  
  57. ΓòÉΓòÉΓòÉ 3. Indexing, Threading, and Duplicate Control ΓòÉΓòÉΓòÉ
  58.  
  59. Beginning with version 1.13 POFAMU will provide a means to Re-Index your PMMail 
  60. folders, as well as thread a folder and check for duplicate messages. For any 
  61. of these features, the message indexing feature will be enabled. 'MessageIndex 
  62. = yes' builds a hash table for all the 'Message-ID' header strings in every 
  63. message, in every Folder. This table is used to directly determine whether 
  64. duplicate messages exist in the folder tree.  This is the Duplicate Control 
  65. feature.  When message indexing is enabled, large amounts of virtual storage, 
  66. cpu cycles, and disk accesses may occur. 
  67.  
  68. Since all the headers of specified folders are being processed, it is possible 
  69. to re-index a folder at the same time.  This has no direct relationship to 
  70. Duplicate Control, but takes advantage of the same code path, and so requires 
  71. 'MessageIndex'. 'MessageIndex = yes' will automatically be set when either 
  72. 'ReIndex = x' or 'ThreadSubj = x' is specified. 
  73.  
  74. 'ReIndex' should NOT be used with Release 2.x versions of PMMAIL and above. It 
  75. will not add the analyze or add the correct MIME-type fields to the FOLDER.BAG 
  76. file.  Sorry. 
  77.  
  78. Folders may be threaded according to the relationship between 'Message-ID' and 
  79. 'In-Reply-To' headers.  Not all listservers/mailers co-operate well in 
  80. providing an 'In-Reply-To' header for the purposes of threading. Immediately 
  81. after the 'Folder' statement, code the statement 'ThreadSubj'.  Threading 
  82. implies re-indexing of that folder, with the subject line being modified to 
  83. begin with a sort string indicating in which thread group(s) this message 
  84. belongs. ThreadSubj will support the arguments 'UnRead', 'Read', 'Sent', and 
  85. 'Replied' to indicate the state to which all the message files will be set in 
  86. the FOLDER.BAG (index) file. 
  87.  
  88.  
  89. ΓòÉΓòÉΓòÉ 4. Control File ΓòÉΓòÉΓòÉ
  90.  
  91. Using the configuration and rules information in the control file specified in 
  92. the invocation argument, manipulate the PMMail folders therein described. 
  93.  
  94. The character set for non-quoted text in the control file is restricted to: 
  95.  
  96.      0123456789:<=>ABCDEFGHIJKLMNOPQRSTUVWXYZ\^_!abcdefghijklmnopqrstuvwxyz{|} 
  97.  
  98.  
  99. ΓòÉΓòÉΓòÉ 4.1. Keywords ΓòÉΓòÉΓòÉ
  100.  
  101. Control file statements have the form of keyword = value, one per line. The 
  102. operands of these statements are case insensitive, treated as upper-case, when 
  103. not within a quoted string. 
  104.  
  105. Order IS important, since the Base entry is required prior to any Account or 
  106. Folder statements. Whitespace is the only delimiter for tokens within these 
  107. statements.  Tabs and blanks constitute (normal) whitespace. 
  108.  
  109. Only interlinear (# in 1st char) comments are allowed. 
  110.  
  111. Possible statement keywords: 
  112.  
  113.   Mode 
  114.             CheckOut, Run, or Force, defaults to CheckOut.  CheckOut allows the 
  115.            user to test his/her control file prior to use. 
  116.  
  117.   Logmode 
  118.             Audit or Silent or Warn or Debug - how verbose the output, defaults 
  119.            to 'Audit'. 
  120.  
  121.   Base 
  122.            like e:\southsde\pmmail  - your root PMMail directory; This is a 
  123.            required parameter.  The directory where pmmail.exe is stored. 
  124.  
  125.   MessageIndex 
  126.             Required for Re-Indexing or Threading folders.  Also required for 
  127.            Duplicate Control. Any operand is considered 'yes'. 
  128.  
  129.   specname 
  130.            boolex << relop '{' boolex >  relop boolex '}' > specnames 
  131.  
  132.   Account 
  133.            "Internal Account-Name". Begin processing the specified account. 
  134.            PMMAIL has a habit of corrupting the account name by shifting a 
  135.            control character into the the first character position of the name. 
  136.            If you receive an "Invalid Account" error, view ACCT.INI with a 
  137.            binary editor and check out the characters beginning x'80' offset 
  138.            from the string 'DACCTNAME'.  Include this character within the 
  139.            quoted string for account-name. 
  140.  
  141.            All following specifications until the next Account keyword will 
  142.            apply to this account. 
  143.  
  144.   Folder 
  145.            "Internal Folder-Name" Nested folders are designated via multiple 
  146.            strings; i.e. "Friends" "Joe".  Take care to insure that all target 
  147.            folder specifications have a token denoting account ('=' if current 
  148.            account) and the complete, perhaps nested, specification of the 
  149.            folder. All statements following this one apply to this folder.  The 
  150.            first such statement may be 'ThreadSubj' or 'ReIndex' as special 
  151.            cases. These statements will all be of the form: 'action' = 
  152.            specification-name-list including 
  153.  
  154.   ReIndex or ThreadSubj 
  155.             which describe actions to be taken at the folder level. 
  156.  Both ReIndex and ThreadSubj take a 'state' type as an optional argument. 
  157.  These may be 'UnRead', 'Read', 'Sent', or 'Replied', and apply to all messages 
  158.  in the indexed folder. The 'Sent Mail' and 'Trash' folders do not participate 
  159.  in the indexing process. 
  160.  
  161.  
  162. ΓòÉΓòÉΓòÉ 4.2. Selection Criteria ΓòÉΓòÉΓòÉ
  163.  
  164. The boolean expressions used by POFAMU are of the form: 
  165.  
  166. Reserved Word Operator Constant 
  167.  
  168. The Reserved words are: 
  169.  
  170.  Subject 
  171.            The subject line as stored in the FOLDER.BAG file. If the specified 
  172.            constant string is a case-insensitive substring of this Subject line 
  173.            than it is considered equal ('='). 
  174.  
  175.  From_name 
  176.            The name (if any) in the From: line of the header. If the specified 
  177.            constant string is a case-insensitive substring of this From_name, 
  178.            than it is considered equal ('='). 
  179.  
  180.  From_addr 
  181.            The email address (if any) in the From: line of the header. If the 
  182.            specified constant string is a case-insensitive substring of this 
  183.            From_addr, than it is considered equal ('='). 
  184.  
  185.  To_addr 
  186.            The email address (if any) in the To: line of the header. If the 
  187.            specified constant string is a case-insensitive substring of this 
  188.            To_addr, than it is considered equal ('='). 
  189.  
  190.  To_name 
  191.            The email address (if any) in the To: line of the header. If the 
  192.            specified constant string is a case-insensitive substring of this 
  193.            To_name, than it is considered equal ('='). 
  194.  
  195.  Status 
  196.            The constants for comparison must be Read, Unread, Replied, or Sent. 
  197.            This is the current FOLDER.BAG state of the message. 
  198.  
  199.  Size 
  200.            The constants for size comparison must be numbers of bytes, without 
  201.            a 'k' or 'm' suffix. 
  202.  
  203.  Age 
  204.            This value means the age in hours of the message.  The difference 
  205.            between the current date/time and date/time stored in FOLDER.BAG. 
  206.            The suffix 'd' or 'h' is mandatory. 
  207.  
  208.  
  209. ΓòÉΓòÉΓòÉ 4.3. Action Statements ΓòÉΓòÉΓòÉ
  210.  
  211.  Actions are of the form: 
  212.  
  213. action-name = specname <..specname> <Account-specifier> 
  214.  
  215. The built-in actions are Move, Delete, Archive, and Copy. 
  216.  
  217.  A message file is the subject of an action statement once and only once during 
  218. a given run of POFAMU.  That is, once a message has been selected for a move, 
  219. delete, or archive; it will participate in only that action for the run of the 
  220. program.  This is to avoid some troublesome 'double-jeopardy' scenarios. 
  221.  
  222.   Archive = specname <..specname> 
  223.                          Messages meeting the criteria of any of the 
  224.                          specification names are ZIP-moved into the file 
  225.                          POFAMU.ZIP in the affected folder directory. The 
  226.                          message file is deleted. A file POFAMU.BAG within the 
  227.                          POFAMU.ZIP file is in standard PMMAIL index format. 
  228.  
  229.   Delete = specname <..specname> 
  230.                          Messages meeting the criteria of ANY of the 
  231.                          specification names in the list 
  232.  
  233.   Move = specname account-name 
  234.                          Messages meeting the criteria of the single 
  235.                          specification are moved to the specified account and 
  236.                          folder.  If account-name is given as '=', then the 
  237.                          current account is assumed. 
  238.  
  239.   Migrate = target-path SIZE | AGE zipsize in k | zip age in days 
  240.                          Effective at the folder level, prior to processing the 
  241.                          first message eligible for archiving into the 
  242.                          folder-local POFAMU.ZIP.  The current POFAMU.ZIP is 
  243.                          inspected for conforming size in k (1024 byte) 
  244.                          segments, or POFAMU.ZIP file age in days. If the 
  245.                          criterion is met, the POFAMU.ZIP will be copied to the 
  246.                          target path and assigned a name matching the name in 
  247.                          the target path with the '||' characters replaced with 
  248.                          alphanumerics not currently in use in the target 
  249.                          directory. A value of 0 for AGE or SIZE will force 
  250.                          migration of the last-written POFAMU.ZIP file. Enclose 
  251.                          the target-path in quotes. See below for an example of 
  252.                          a Migrate statement. 
  253.  
  254.   Copy = specname account-name 
  255.                          Copy is not implemented currently. 
  256.  
  257.  It is highly recommended that you test any new or modified control files with 
  258.  Mode = CheckOut before using Mode = Run. If fact, you might want to leave the 
  259.  Mode command out of your control file altogether.  When you truly want to 
  260.  commit the changes, use Run as the second command line argument. 
  261.  
  262.  
  263. ΓòÉΓòÉΓòÉ 4.4. Syntax ΓòÉΓòÉΓòÉ
  264.  
  265.   account-name ::: PMMail internal account name | '=' (for current account) 
  266.  
  267.   folder-name ::: PMMail internal folder name 
  268.  
  269.   time_val ::: number || tqal 
  270.  
  271.   tqal ::: 'd' or 'h'  days or hours 
  272.  
  273.   boolex :::  key_id operator comparator 
  274.  
  275.   operator ::: '=' or '>' or '<' or '<>' 
  276.  
  277.   comparator ::: "string" or number 
  278.  
  279.   relop ::: 'AND' or 'OR' 
  280.  
  281.   key_id ::: Age or From_addr or From_name or Status or Size or To_addr or 
  282.  To_name or Subject 
  283.  
  284.   'OR' logic has not yet been tested.  So don't expect it to work. 
  285.  
  286.   ( For Status, the 'number' may be 'Unread', 'Read', 'Replied' , 'Sent', 
  287.  or 0, 1, 2, or 3 ) 
  288.  
  289.  
  290. ΓòÉΓòÉΓòÉ 5. Command Line ΓòÉΓòÉΓòÉ
  291.  
  292.  Invoke the program like so: 
  293.  
  294.   pofamu  control-file-path  <runmode> 
  295.  
  296.  Control-file-path is mandatory.  Runmode is optional and overrides the value 
  297. in the control file. 
  298.  
  299.  
  300. ΓòÉΓòÉΓòÉ 6. Sample Control File ΓòÉΓòÉΓòÉ
  301.  
  302. # initial test configuration file
  303. #
  304. # Base directory for PMMAIL folders
  305. # must specify where to start looking
  306.   Base = e:\uupc\southsde\pmmail
  307. # Execute mode
  308.   Mode = CheckOut
  309. # Message (listing) mode
  310.   logmode = audit
  311.  
  312. # Here are the selection criteria
  313.   Bobs_3day =  { From_name = "Bob Rocky" }  AND { Age > 3d }
  314.   Hale_3day =  { From_name = "Haley Landers" } AND { Age > 3d }
  315.   Golden_3day  = { From_name = "Dave Goldenbugle" } AND { Age > 3d }
  316.   Rick_3day   =  { From_name = "Rick G. Shepherd" } AND { Age > 3d }
  317.   Paul_3day =  { From_name = "Paul Brash" } AND { Age > 3d }
  318.   THE_author = { From_name = "Mark Hessling" }
  319.   Humor =  From_name = "west@ib"
  320.   Weekold =  Age > 7d
  321.   TwoWeekOld = Age > 14d
  322.   MonthOld = Age > 30d
  323.  
  324.  
  325. # We have two accounts that are actively in use
  326.   Account = "Dave's Mail"
  327.  
  328.     Folder = "Trash"
  329.       Move =   Bobs_3day =  "Friends"  "Bob"
  330.       Move =   Paul_3day =  "Friends"  "Bash"
  331.       Move =   Hale_3day =  "Friends"  "Hale"
  332.       Move =   Golden_3day =  "Friends"  "Goldenbugle"
  333.       Move =   Rick_3day =  "Friends"  "Rick"
  334.       Move =   THE_author =  "Programming"  "Hessling"
  335.       Move =   Humor = "Humor"
  336.       Delete = TwoWeekOld
  337.  
  338.     Folder = "Sent Mail"
  339.       Delete = MonthOld
  340.  
  341.     Folder = "Programming" "MVS-OE"
  342.       Migrate = "f:\mailarc\mvsoe||.zip" SIZE 200
  343.       Archive = Weekold
  344.  
  345.   Account = "Trish's Mail"
  346.  
  347.     Folder = "Trash"
  348.     Delete = TwoWeekOld
  349.  
  350.  
  351. ΓòÉΓòÉΓòÉ 7. Problem Diagnosis ΓòÉΓòÉΓòÉ
  352.  
  353. Beginning with version 1.9, if an exception occurs during operation, POFAMU 
  354. will output a short message and produce a file M2DUMP.nnn in your SPOOL 
  355. directory. If the reason for the exception isn't apparent, zip this file and 
  356. PMMAIL/Attach it to a message sent to the author. 
  357.  
  358. A common problem is not specifying a folder target with a complete path, i.e., 
  359. not providing a account-name (perhaps '=') or not specifying the complete path 
  360. of nested folders to the target folder. 
  361.  
  362.  
  363. ΓòÉΓòÉΓòÉ 8. Author ΓòÉΓòÉΓòÉ
  364.  
  365. This code is the work of : 
  366.  
  367.  
  368.     Dave Serls
  369.  
  370.     Internet: dave@dashs.denver.co.us
  371.  
  372. Thanks to Irv Thomae for assistance in enabling support for PMMail version 1.53 
  373. accounts.