TITLE : sumsset, sumsprint, sumswrite, sumsfolder AUTHORS : Stefan Stuntz AUTHORS : Bernhard Moellemann AUTHORS : Matthias Scheler AUTHORS : Klaus Melchior AUTHORS : Oliver Oster COPYRIGHT : Public Domain REQUIREMENTS: Kickstart 2.x, UMS release V10 HISTORY: -------- V1.0 (23-Aug-92) - Initial release V1.1 (30-Aug-92) filters: - corrected AGE filter. sumsset: - modified screen output a little bit. sumsprint: - added "old" command line parameter. source: - included full SAS/C source code. No comments, quick hack :) V1.2 (01-Sep-92) sumsprint: - "Netmail" is used for instead of an empty string. V2.0 (01-Sep-93) - Adapted for UMS V10. - Complete rewrite of the filter. It supports full boolean argument parsing (with AND, OR and braces) now. Attention: You will have to rewrite your scripts! - Included pattern support. - Please reread the docs, especially the filter part! V2.1 (16-Sep-93) [Bernhard Möllemann] - Added UMS V10 fields Newsreader, Reply#? in sumsprint and sumswrite. - Added support for printing status as characters. - Fixed some minor bugs and enforcer hits. - Added possibility to use every user flag for setting and filtering. V2.2 (02-Nov-93) - Searching for MsgText was impossible. - All tools were eating 24 bytes of memory. - Fixed some filter parsing bugs. V2.3 (03-Nov-93) - 2.2 was crap, please use 2.3 instead :-) - Note: If you want to filter with the orphan bit, you have to enclose it in quotes: 1> sumsset sysop "" *"orphan*"=1 "" V2.4 (03-Dec-93) - Searching for Folder now possible [MS] - wrote new tool "sumsfolder" [MS] V2.5 (03-Jan-94) - all: Commandline is parsed with ReadArgs() [kmel] - all: Added possibility to specify server [kmel] - Added 'source/sumstl.rel' to generate release archive [kmel] - umsfilter.c: Corrected date comparision, now the filter works like you read, e.g.: "Date>=01-Jan-94", all messages are selected from the first of January upto now. [kmel] V2.6 (30-Jan-94) - filter.c: Corrected misfeature with filter token, "AND" and "OR" were also recognized in expressions, e.g.: "group=adsp.networking" failed at 'netw or king' [kmel] Restrictions: Quotation marks '"' are still not recognized in filter strings - date.c: Added new date formats "01.01.78", "1.1.78" [kmel] - sumsprint.c: bumped to version 2.6 [kmel] - sumsfolder.c: bumped to version 2.6 [kmel] - all: Compiled with SASC 6.51 instead of DICE, now they should not crash while using the filter expression 'group=""' [kmel] - sumstl.rel: Changed, archive now includes "sumstl.readme" [kmel] V2.6a (13-Feb-94) - all: Bug removed, array of cli arguments has to be cleared before it is used. [kmel] V2.7 (05-Jul-94) - umsfilter.c: fixed searching for constant expression on not indexed header fields [MS] - all: added support for LogicalToName, LogicalToAddr and RFCMsgNum [MS] - all: reworked source codes and SAS/C Makefile, now V11 proof "DMakefile" should be reworked, too. [MS] V2.7a (28-Jul-94) - sumsfolder.c: only messages with View-, Read- and WriteAccess are modified now [MS] V2.7b (04-Aug-94) - DMakefile sumstl.h filter.h: changed to add DICE compatibility. [olio] - sumsfolder.c: now returns WARN (5) if no msgs matched the filter. Compiled with DICE 3.0. [olio] V2.8 (01-Dec-94) - sumswrite.c, sumsprint.c: added support for RfcAttr, FtnAttr, ZerAttr and MausAttr [MS] - sumsfolder.c, sumsset.c: added "Q=Quiet/S" option to suppress output of the filter [MS] - sumsset.c: added "FU=ForUser/K" option which specifies the user whose flags are modified (user flags only of course) [MS] OVERVIEW: --------- 'sumstl' stands for "Stuntzi's UMS Tools" and is a collection of four useful tools for the UMS message base system: sumsprint - extract certain messages from message base to a file. sumswrite - create new messages. sumsset - set certain bits on certain messages. sumsfolder - set folder on certain messages. With the aid of these four tools, you can perform lots of actions, such as automatic message archiving, automatic generation of return receipts, automatic message forwarding, areafix support, user filter, etc. You could e.g. select all messages about "MUI", extract them from the message base with 'sumsprint' and forward them to a special MUI-Area with 'sumswrite'. Or you could select all messages from user "Martin Horneffer" and route them via 'sumsprint' to a printer. Thus, you will have all his mumbling on a sheet of paper and can easily create some nice paper planes. :-) If you are a node that offers some kind of areafix, 'sumsprint' could extract all messages to user "Areafix" for further parsing with an areafix tool. Do you need some kind of expire? Just select all messages in 'fidonet.Amiga.ger' that are older than 30 days and set the Expire-Bit with 'sumsset'. There are simply no limits! LOGGING ON: ----------- Since Stuntzi-Tools are mainly intended for automatic use within script files, they will only work from CLI. All tools need a user name and a password and have the ability to set the server name. FILTERING: ---------- Now it's getting interesting. Whenever a Stuntzi-Tool offers Filter as parameter, you must specify a filter-string which describes the messages that this Stuntzi-Tool shall work with. Filter-strings consist of a boolean expression, e.g. something like that: ((age>10 AND group=fidonet.#?) OR (age>20 AND group=uucp.#?)) OR age>30 This expression would select all fidonet messages older than 10 days, all uucp messages older than 20 days and all other messages older than 30 days. To be a bit more specific, a filter expression consists of one or more conditions, concatenated with "AND" or "OR" and grouped together with braces. A condition consists of a keyword, followed by some relation specifier, followed by some kind of data. = Keywords are always bound to specific message fields, to global or user flags or to message age or number. Not all relations are valid for all keywords, have a look at the following table: Keyword Relations Parameter Type Sample --------------- --------------- ------------------- ------------------ MsgText = != string or pattern MsgText=#?mui#? FromName = != string or pattern FromAddr = != string or pattern ToName = != string or pattern ToName="Hans Nase" ToAddr = != string or pattern MsgID = != string or pattern CreationDate = != string or pattern ReceiveDate = != string or pattern ReferID = != string or pattern Group = != string or pattern Subject = != string or pattern Attributes = != string or pattern Comments = != string or pattern Organization = != string or pattern Distribution = != string or pattern Folder = != string or pattern Archive = != 1 or 0 Archive=1 Junk = != 1 or 0 PostPoned = != 1 or 0 Selected = != 1 or 0 Old = != 1 or 0 Old=0 WriteAccess = != 1 or 0 ReadAccess = != 1 or 0 ViewAccess = != 1 or 0 Owner = != 1 or 0 UFlag0 = != 1 or 0 UFlag1 = != 1 or 0 ... .... UFlagF = != 1 or 0 Deleted = != 1 or 0 Expired = != 1 or 0 Exported = != 1 or 0 Orphan = != 1 or 0 Link = != 1 or 0 Hardlink = != 1 or 0 Age = != < > <= >= number of days Age>25 Date = != < > <= >= Amiga-DOS date Date<=31-Dec-92 MsgNum = != < > <= >= number of message MsgNum=75 Notes: - All parameter and keyword strings are case insensitive. - Spaces not within double quotes are ignored. - Using patterns will significantly slow down the filter operation. You should always have conditions containing patterns executed last to save time. If you e.g. would like to see all new mails about MUI, you should use Old=0 AND Subject=*MUI* instead of Subject=*MUI* AND Old=0 Thus, the filter will first throw away all old messages and search for MUI only in the remaining part. - If you want to have spaces in your parameter strings, you will have to include them into double quotes: FromName = "Stefan Stuntz". In a CLI command line, you need to prefix these double quotes with an asterisk '*' to prevent the command line parser from parsing them itself: sumsprint sysop "" "Group=uucp.#? AND FromName=*"Stefan Stuntz*"" prints all mails that Stefan Stuntz wrote in usenet. - Due to UMS bit handling, depth of braces is limited to maybe 5 or 6. Examples: Select all messages of group fidonet.amiga.ger: Group=fidonet.Amiga.GER Select new messages for Joe Fake: Old=0 AND ToName="Joe Fake" Select new netmails for Stefan Stuntz or S.Stunz or whatever: Old=0 AND Group=Netmail AND ToName="#?Stun#?z#?" Select messages older than one month in fidonet.UMS.GER: Group=fidonet.ums.ger AND Age>30 Select all messages received 1992: Date>=01-Jan-92 AND Date<=31-Dec-92 Select messages 13,42,101,102,103 and 104: MsgNum=13 OR MsgNum=32 OR (MsgNum>=101 AND MsgNum<=104) SUMSPRINT: ---------- 'sumsprint' must be called with the following syntax: sumsprint U=User/A,P=Password/A,FI=Filter/A,FO=Format,FILE=Formatfile/K, O=SetOldFlag/S,B=Backwards/S,S=Server/K User name, password and filter (as always) were explained earlier, no more word about them, as option the server name. Format or Formatfile control how the message(s) shall appear on the screen. You can either specify a format string directly in the command line or make 'sumsprint' load the format string from a file by using "FILE=filename" as command line argument. In either case, the format string may consist of any characters, including the following special sequences: \n creates a line feed \r creates a carriage return \f creates a form feed \r creates a tab \< creates a '<' sign \> creates a '>' sign \e creates an escape (ascii 27) \\ creates a backslash '\' ^x creates a control-x (x & ~64) (x from A to Z) Fields of the message can be included with a '<' char, followed by the name of the field, optionally followed by a comma and a printf-style formatting string for this field, followed by a '>' char (template: ). Valid keywords and their default formats are: Keyword Default Meaning Format MsgText %s Complete message text QuoteText >_ Quoted message text (format is quote string) FromName %s Name of author FromAddr %s Address of author ToName %s Name of receiver ToAddr %s Address of receiver Group %s Group this message belongs to Subject %s Subject field CreationDate %s Date of creation Attributes %s Attribute field Comments %s Comment field Organization %s Organization field Distribution %s Distribution field Newsreader %s Newsreader field ReplyName %s Name to reply to ReplyAddr %s Address to reply to ReplyGroup %s Group for followup MsgID %s Message-ID ReferID %s Reference-ID MsgNum %ld Number of this message ChainUp %ld Number of message higher in reply tree ChainDown %ld Number of message lower in reply tree ChainLeft %ld Number of a message on same reply level ChainRight %ld Number of a message on same reply level HardLink %ld Number of a hardlinked message SoftLink %ld Number of a softlinked message GlobalStatus %08lx Global status bits for this message UserStatus %08lx User status bits for this message LoginStatus %08lx Login status bits for this message CDate %d-%b-%y %X Parsed and localized creation date IDate %d-%b-%y %X Localized receive date The last two items need a bit more explanation. To use them, you will need locale.library >V38. The format string is no printf-style here but may contain some other special characters that are replaced with strings containing current date and time information. For detailed explanation about this special characters see "autodocs/locale.doc" or appendix A. is guaranteed to work, may fail because the creation date of a message can look very different from system to system. Appendix B holds information about the date formats that 'sumsprint' knows. If the format is unknown, will automatically be replaced with . All keywords are case insensitive. For example, the format string "From: To: Flags: $" could generate something like From: Stefan Stuntz To: Martin Horneffer Flags: $deadbeef as output. Please remember the various possibilities that printf-style formatting offers. For more examples, refer to the #?.mfm files coming with this archive. If you neither specify Format or File=Formatfile in your command line, a default format will be used. To read the Flags without having ums.h in another window, there is a second format: Each flag may be represented by a letter, indicating it is set, or a dash if it is cleared. This format is selected by the absence of the percent sign in the first letter of the format. For every flag bit you have to specify either the letter, which is printed when the flag is set, or a dash to suppress this flag. If the character is uppercase the absence of the flag is shown by a dash. A lowercase character requests to ignore a cleared bit completely. The most right character is associated with the last significant bit of the flag word. The format may contain less than 32 characters. In this case the unset flags are ignored. Behind the flag characters may be a printf-like format string appended. It is recognized by the leading percent character. Example: A message has the user status $0D40==Old,ReadAccess,ViewAccess,PostPoned and the global status $0006==Exported,Expired. With the format string "From: \n Status: user= global=\n" ^^^^^^^^^ ^^^^^^ ||||||||Archive |||||Deleted |||||||Junk ||||Expired ||||||PostPoned |||Exported |||||Selected ||Orphan ||||Old |Link |||WriteAccess HardLink ||ReadAccess |ViewAccess Owner (My message) the message shows up as From: Joe 'DAU' User Status: user=-O-P- global=EX If you specify SetOldFlag, sumsprint will mark every read message as old. Notes: - If you use "LANGUAGE: " as the first line of your format file, 'sumsprint' will use this language for and . - None of the UMS global, user or local status bits are affected. As long as you don't specify SetOldFlag, printed messages won't become old. - Messages without view or read access cannot be printed. For this reason, 'sumsprint' will always append "AND readaccess AND viewaccess" to your filter string. SUMSSET: -------- sumsset U=User/A,P=Password/A,FI=Filter/A,SB=SetBits/A,CB=ClrBits, S=Server/K,FU=ForUser/K,Q=Quiet/S After user name, password and filter (as always), as option the server name. 'sumsset' wants you to specify one or two bit spec strings. These strings determine, which bits to set and which bits to clear on the selected messages. A bit spec string may consist of one or more bit names seperated by comma, or just be empty. Valid bit names are Archive, Junk, PostPoned, Selected, Old, WriteAccess ReadAccess, ViewAccess, Owner, Deleted, Expired, Exported, Orphan, Link and HardLink. These flags are either global or user flags. Please refer to ums.doc for their specific meaning. SysOp's may also modify flags of other users via the "ForUser" option. Examples: Expire area fidonet.AMIGA.GER: sumsset SysOp ss "Group=fidonet.AMIGA.GER" EXPIRED CleanUMS Mark all message from "Roland Schwefel" as new: sumsset SysOp ss "FromName=*"Roland Schwefel*"" "" OLD Bad-User-Filter: sumsset SysOp ss "FromName=*"Otto Nervbert*"" "" OLD,EXPIRED Give user "Joe" access to one of your mails: sumsset SysOp ss "MsgNum=42" ReadAccess,ViewAccess FORUSER "Joe" Notes: - Be careful with this command. You can do some very bad things to your message base! - Setting the deleted-bit seems to have no effect. No idea what happens if you play around with other strange bits (e.g. Link). SUMSWRITE: ---------- sumswrite U=User/A,P=Password/A,S=Server/K 'sumswrite' only needs these two standard parameters, as option the server name. The message to write will be read from standard input. It must contain some field names followed by an optional "=", followed by the fields contents, then a line with one or more "-", then the message text. Valid field names are: Field Name Field Type Comments/Examples ToName string Stefan Stuntz ToAddr string 2:246/46.10@fidonet Group string Netmail Subject string MUI bug report Organization string Distribution string Comments string ReferID string Attributes string CreationDate string AutoBounce boolean message will be bounced if invalid NoUpdate boolean message will be new FromName string only valid for importer FromAddr string only valid for importer MsgID string normally created by MBP MsgDate date only used to restore backups MsgNum number only useful to create links ReceiveDate string normally created by MBP ChainUp number rarely used HardLink number rarely used SoftLink number rarely used HdrFill number rarely used TxtFill number rarely used A boolean field's parameter can be "true" or "false" or empty, which will force a this field to be true. A date field must contain a valid date specification. See appendix B for known date formats. Please refer to UMS documentation for detailed documentation about the meaning of these fields. Depending on your account status, you may or may not use some of them. 'sumswrite' will show you an error message if something fails. Of course, you needn't specify all these fields. A small message file could look like ToName Stefan Stuntz Subject Test -------------------- Hello Stefan! How are you? Bye. wich will create a locale private message to "Stefan Stuntz". SUMSFOLDER: ----------- sumsfolder U=User/A,P=Password/A,FI=Filter/A,FO=Folder/A,S=Server/K,Q=Quiet/S After user name, password and filter (as always), 'sumsfolder' wants you to specify a folder name. This name determine, in which folder the selected messages will be put. As option specify the server name. If no messages matched the filter sumsfolder returns WARN (5). Example: Put all mails from "Matthias Scheler" in folder "tron": sumsfolder SysOp ... "Group=*"*" AND FromName=*"Matthias Scheler*"" "tron" APPENDIX A - Date specifiers: ----------------------------- %a - abbreviated weekday name %A - weekday name %b - abbreviated month name %B - month name %c - same as "%a %b %d %H:%M:%S %Y" %C - same as "%a %b %e %T %Z %Y" %d - day number with leading 0s %D - same as "%m/%d/%y" %e - day number with leading spaces %h - abbreviated month name %H - hour using 24-hour style with leading 0s %I - hour using 12-hour style with leading 0s %j - julian date %m - month number with leading 0s %M - the number of minutes with leading 0s %n - insert a linefeed %p - AM or PM strings %q - hour using 24-hour style %Q - hour using 12-hour style %r - same as "%I:%M:%S %p" %R - same as "%H:%M" %S - number of seconds with leadings 0s %t - insert a tab character %T - same as "%H:%M:%S" %U - week number, taking Sunday as first day of week %w - weekday number %W - week number, taking Monday as first day of week %x - same as "%m/%d/%y" %X - same as "%H:%M:%S" %y - year using two digits with leading 0s %Y - year using four digits with leading 0s APPENDIX B - Known date formats: -------------------------------- "01 Jan 91 11:22:33" Fido "01 Jan 91 11:22" Fido without seconds "Wed 13 Jan 86 02:34" Fido SEAdog "JJMMTThhmm" Z-Netz "01-Jan-78 10:11:12" AmigaDOS "1.1.78 10:11:12" AmigaDOS, Style Guide German "01.01.78 10:11:12" AmigaDOS, Style Guide German, leading 0s When none of these formats matches, 'sumsprint' tries to parse the date with some more or less complex algorithms. This may or may not succeed. If you want to see another date format supported, just let me know. APPENDIX C - How to reach the author: ------------------------------------- Questions, comments, suggestions, bug reports, flames, gifts, etc. welcome. Send them to Stefan Stuntz Eduard-Spranger-Straße 7 80935 München Germany E-Mail: stuntz@informatik.tu-muenchen.de