MailWatch version 2.4 USER'S MANUAL by Jon Glazer {glazer@ohstpy.mps.ohio-state.edu} Copyright (c) 1992,1993 Introduction: MailWatch is an email management program designed to give comprehensive reports about your email system and perform some management functions to help reduce the amount of space it utilizes. MailWatch has the ability to actually re-send unread mail to an alternative address to ensure that old mail does not continually build up on your system. MailWatch is designed to work with Pegasus Mail by David Harris and Charon by Brad Clements. Both of these are readily available off of most network sourced BBS systems and Compuserve. Future versions of MailWatch will also support MHS and possibly other email packages. This document will assume that the reader has a good understanding of Pegasus Mail and Charon and at least some rudimentary knowledge of basic Novell functions. History: .92b Final release of test version. 2.0 First release of rewritten shareware version. 2.1 Major bug fix release - Fixed numerous bugs regarding forwarding mail. - Fixed directory search algorythm to eliminate Novell errors. - Added support for return-to-sender and corrected forwarding algorythm to work as-stated (see RetunAdd). - Modified initial search to read from bindary rather than SYS:MAIL. Names are now read directly, converted to their HEX IDs then used to search for mail. Formerly, all directories under SYS:MAIL were searched, valid or not. - Added "Z" report for primitive dump of user preference settings. - Corrected a variety of errors regarding incorrect mail counts and inaccurate reports. - Added a total at the bottom of each numeric column. - Added banner info for email in MAILQUEUE when sending mail via Charon (real important huh?). 2.2 - Added DEBUG option in [SYSTEM] area of MWATCH.INI - Added MAILQUEUE option in [SYSTEM] area of MWATCH.INI - Added additional error checking on for output files. - Added support for group scanning in NAME variable. - Corrected my mailing address on the coverpage of this manual. - DEFAULT profile specified in [SYSTEM] is now correctly checked for. - Intelligent error messages added for profile names (given or missing) - GLOBAL and SYSTEM profile names are now known as reserved and cannot be specified. - Added Using Mailwatch section in this manual. 2.3 - Corrected mail scan for moved mailboxes. - Beautified registration screen. - Added additional profile error checking w/ messages. - Added multi-level DEBUG mode. - Corrected possible cause of "Error 105". - Added profile variable types to documentation. 2.4 - Corrected yet another bug dealing with name resolution. - Fixed additional Charron support - Added parameter override support for command line (see Using Mailwatch) - Clarified more clearly in documentation what the term PROFILE means. Installation: Place the MailWatch distribution files (*.EXE and *.INI at least) in any directory in your path. It might be convenient to place the in the same directory as PMAIL. MWATCH.INI contains many user-settable variables that will define how MailWatch performs its various tasks. MailWatch cannot operate properly without finding MWATCH.INI in the path or current directory. The user who runs MailWatch should have full access to the mail root directory. This is necessary to be able to accurately scan all of the mail subdirectories and delete/forward mail as needed. Using MailWatch Running MailWatch from the command line is very simple. The syntax is: MWATCH2 profilename [param1 param2 param3...] Profilename is the name of a valid profile you set up in MWATCH.INI with all the settings you plan to use. If you do not specify a profile name then MailWatch will use the name found in the [system] section of MWATCH.INI under Default=. If this is also missing than MailWatch will return an error. Please note that you may not use the names GLOBAL or SYSTEM in this manner. These are reserved names that MailWatch uses for system variables. See the section entitled MWATCH.INI for more information. Param1..n are overriding parameters for MailWatch to use instead of those found in MWATCH.INI. The order of preference here is. - use command line parameter (if found). - use parameter in specified profile (if found). - use parameter in [global] profile (if found). - report error if none of above find parameter and it is required. Parameters specified on the command line MUST BE IN THE SAME SYNTAX FOUND IN MWATCH.INI. That is, it uses the form KEYNAME=VALUE. For example, to specify the scanning of only those names beginning with "tom", you might run MWATCH2 AGED NAME=TOM* The profile name must be parameter #1 in this case. All other parameters are assumed to be variable definitions. No spaces are allowed in this type of declaration. Entering something like MWATCH2 AGED NAME = TOM* would tell MailWatch to use the parameters found in MWATCH.INI because spaces were found on either side of the equal sign. MWATCH2 NAME=TOM* would not work either since, in this case, MailWatch would try to use the information found in the profile [name=tom*] which probably does not exist in MWATCH.INI. *Note* Moved mailboxes may result in inaccurate counts. If a user moves his/her mailbox to a non-local drive (a drive letter less than "F"), the folders cannot be accessed and will not be processed. A indication of "N/A" in any of the folder related columns will signify this. MWATCH.INI MWATCH.INI conforms to the standard section/keyword/value format that is found in many other applications such as Windows. The .INI format is exceedingly easy to understand and manipulate and should make the more advance MailWatch features more easily understandable. MWATCH.INI is simply a text file that contains variables that the user defines to tell MailWatch how to run. The file can be edited by any text editor or word processor that can create standard DOS text files (those you can TYPE without seeing garbage). The file is segmented into sections known as PROFILES. Each section (or profile) is denoted by a single line that contains the name of the profile. The name is enclosed in brackets and all variable definitions between this name and the next (or the end of the file) pertain the this profile. For example: [section 1] a=1 b=2 c=3 [section 2] d=4 e=5 f=6 In this example, two profiles are defined "section 1" and "section 2". They are indicated by the enclosing brackets. The variables "a", "b", and "c" are defined for profile "section 1", and "d", "e", and "f" are for "section 2". Variables can be defined in defined in both profiles in any order desired. Only the profile referenced is actually looked at. Variables beginning with a ";" are assumed to be comments, therefore using ";a=1" in [section 1] above, will NOT set variable "a" to the value "1". MailWatch only cares about three different profiles found in MWATCH.INI. The [system] profile, [global] profile, and the profile name specified on the command line (perhaps [aged]). The rest of the file is essentially ignored. [system] Variables under this section define various system settings needed to tell MailWatch about your particular network and email system. MailDir= (S) This variable defines the root mail directory of the email system. For most Novell networks running Pegasus Mail this is SYS:MAIL, however the volume name "SYS" may change depending upon your installation. If this variable is not defined, SYS:MAIL is assumed. LogFile= (S) Enter the name of the log file you wish to use to maintain a log of the activities MailWatch performs. If you do not define a log file name, no log will be kept. LogSize= (I) Log files can build in size forever until your disk is full unless you periodically delete them or set a limit. LogSize defines the maximum number of bytes the log file can get before logging is suspended. By default, a size of 1024000 (1 meg) is assumed. Default= (S) You can define a default profile to use if you do not specify one on the command line by entering a valid profile name in this variable. Debug= (I) Three debugging levels are available to help resolve and report problems with MailWatch. Debug level zero turns off debugging. Level one shows minimal activity. Level two displays all procedures utilized durring process. Use DEBUG=0,1, or 2. MailQueue= (S) Enter the name of the Charon mail quue you setup when installing Charon and Pegasus Mail. If not specified then this name is MAILQUEUE. Registration= (S) MailWatch is not a free utility. By registering the product (paying for it) you will receive a passcode that will enable the restricted features of MailWatch. Enter the passcode here to tell MailWatch that it is now registered. See the section entitled REGISTRATION for more information. [global] Sections other than [system] define parameters to use when running MailWatch. MailWatch will search MWATCH.INI for each variable, first in the given profile section then, if not found, it will look in the [global] section for these variables before using defaults or erroring. The following variables are valid profile settings that may or may not be appropriate for the [global] section. This is where some logic in the design of MWATCH.INI will be needed. In the following list, expected variable types are displayed as either (S), (I) or (B). (S)= Any set of characters or numerals or symbols. (I)= Any set of numerals representing an integer value. (B)= Any boolean value. The following sets are equivelant (yes/no), (true,false), (on/off), (y/n), (t/f). NewMail= (S) New, unread mail, is stored in separate files in a user's mail directory with the extension .CNM (or at least it is for Pegasus Mail delivered by Charon or Pegasus). This variable allows you to define what extension to scan for new mail. Usually this would simply be *.CNM (and, in fact, is the default) but it is provided here in case you find some other use for MailWatch I cannot conceive of (or perhaps some other email package can use this utility?). Age= (I) MailWatch performs functions and reports on aged mail. This is mail that is older than a defined number of days (usually unread mail). Enter a number here that defines what is to be considered aged mail. There is usually no reason to place this in the [global] section, nor is there a default value. Age must be specified explicitly for MailWatch to function. Name= (S) You may have MailWatch perform functions on the entire mail system, or you can have it work on only selected users. Enter the name of the user you wish to scan in this variable. You may use wildcards if you wish to scan groups of names (such as all users with "J" as a first letter Name=J*). You can scan a valid Novell group name by preceding the name with a "#". For example, NAME=#ACCOUNTING would only scan members of the accounting group. If you wish to scan members of groups beggining with "ACC" then use NAME=#ACC*. ReturnAdd= (S) Aged mail can be forwarded to another user or to the same user on another host or return the message to the sender.. Reasons for doing this are: 1) if a user has old, unread mail, send the mail to the email administrator to sort out why the mail has not been read (notify the user). 2) if the user usually works from a Unix host (or some other foreign host) send the mail there. The user may not have enabled AutoForward. The mail will be rather old when he/she receives it and hopefully he/she will correct the entry in AutoForward to avoid this problem in the future. To have the mail sent to a different user, enter the full address of the user to send old mail to. If you wish to simply have the mail sent to the same user on another host, enter the mail path w/o the username and the addressee will be added by MailWatch. Ex.. ReturnAdd=@novell.com will send aged mail to the {addressee}@novell.com. If no value is given for ReturnAdd then the aged mail will be returned to sender with the appropriate message in the subject. OutputName= (S) When generating reports, MailWatch can send the report to a file. Enter the name of the file you wish to use for your report output. No default is provided. LineDraw= (B) Reports can be generated using either the PC linedraw characters or dashes and plusses. Some printers cannot print the linedraw characters. The default is no. PageLength= (I) Enter the length of a single page of output for reports. By default this is 60 lines. DeleteAged= (B) When aged mail is encountered, should it be deleted after processing (i.e., after the report is generated or after it is forwarded). If mail is forwarded and not deleted, then the next time MailWatch is run a duplicate mail message will be forwarded until the mail is deleted. ForwardAged= (B) Should aged, unread mail be forwarded to ReturnAdd? AgedGroup= (S) MailWatch has the ability to maintain a Novell group of users who have unread, aged mail. By placing usernames in this group, you can give notice to these users that their mail is being ignored and that it may eventually be deleted. This can be easily done in the login script (see Novell documentation). By running consecutive scans, you can provide different messages to users such as "You have mail older than 10 days waiting". "You have mail older than 20 days waiting", "Your unread mail is being deleted" etc.... Provide AgedGroup with the name of the group to maintain the names in. This group should already be created. Each time MailWatch is run, it is cleared of names and updated with only those that have been processed. ExcludeGroup= (S) You can provide a list of users to exclude from MailWatch processing by giving the name of an existing Novell group here. Users found in that group will be ignored by MailWatch. Quiet= (I) This tells MailWatch how much status to display when executing. A quiet level of 0 will display everything (not quiet). This can result in a rather messy display but it does allow for redirection of output in the event you wish to have information generated by reports piped into another application. Quiet level 1 (sort of quiet) will generate a series of colored dots that show status. The various colors signify different activities and are only provided to make the display interesting. Quiet level 2 (tight lipped) does not display anything at all unless an error is encountered. RepOrder= (S) This is a rather complex variable. Basically it provides MailWatch with the information you wish to see on a report. Reports are usually made of columns of information. Some of the information may not be wanted or may need to be in a particular order. Each column of information has an associated letter. Enter in RepOrder the column order you wish to see in the reports. This is simply a set of letters that turn on report columns and tell MailWatch to print them in a particular order. See the REPORTS section for more information. [Other Profiles] Additional should be defined with the above variable to describe various MailWatch functions. Examples might be sections to simply delete old mail, forward and delete old mail, generate specific reports, or any combination of these. You would run MailWatch with the name of the profile on the command line to have it use those values when running. If you do not provide a profile name, the one found in Default= in the [system] section will be used , if available. Reports: MailWatch has a rather sophisticated reporting system. It provides information as desired and limits its processing to only those areas required to acquire this information. In this way, MailWatch processing times may vary depending upon the type and quantity of information requested. Each report is made up of columns of information. Each column item has a corresponding column letter assigned to it. When generating reports, the columns are displayed in the order provided in the RepOrder variable. If a column is excluded from this variable, it will not be displayed at all. The following is a description of each of the available reporting columns you may include in RepOrder. General Pmail Unread MHS Folder A Userid C Total G Unread K MHS O Folder Email Total Total Total B User D Total H Unread L MHS Size P Folder Name Aged Size Size E Total I Unread M MHS Aged Q Folder Size Aged Deleted F Total J Unread N MHS R Folder ASize ASize Asize Mail S Folder Aged T *Folder Name * Requires special consideration (See below). The General columns are general information pertaining to the email user. Items under Pmail depict information regarding specific elements of Pegasus Mail mail. Totals in this category total both read and unread mail. The Unread category also deals with Pegasus Mail information. These are statistics about unread mail found. MHS statistics are not yet available but will be active using these settings eventually. Folder statistics can be taken if you wish to get that level of information. If you specify that the folder name is to be displayed (not usually useful) than another type of report will be generated giving sub totals for the folder information. This can become rather cluttered and is only offered as a service for debugging. ASize information depicts aged, unread mail sizes. Example If RepOrder=ABCGOE then the report would be UserId, UserName, TotalEmail, UnreadTotal, FolderTotal, TotalSize in that order. An additional report code of "Z" will dump user settings for Pegasus Mail. This should probably be used alone in it's own profile, otherwise a rather cluttered, and unreadable report will be generated. Example RepOrder=Z Disclaimer: This product is distributed "as-is". Loss or corruption of data or damage to equipment due directly or indirectly to the use of this product is not the responsibility of the author who cannot be made liable. Use this product at your own risk. Credits: Pegasus Mail is copyright by David Harris. Charon is copyright by Brad Clements. Novell is a trademark of Novell Inc. Windows is a trademark of Microsoft Inc. Registration: MailWatch is not free. It has been developed after a considerable amount of effort and is distributed in the shareware fashion. If you decide that MailWatch is useful for you, please send $39/ server to: Jon Glazer 2097 Brittany Road Columbus, Oh 43229. Questions and comments can be sent to glazer@ohstpy.mps.ohio- state.edu. You will receive a passcode that will enable any MailWatch protected features. This code will be good for any maintenance releases of MailWatch in the future. A maintenance release is a version whose minor number changes (i.e. 2.01, 2.02, 2.10 etc..). Please complete and send the following form: Please send me the MailWatch passcode via: [ ] U.S. Mail address ________________________________________ ________________________________________ ________________________________________ ________________________________________ [ ] Internet (email) , my address is: _______________________________________________ [ ] Compuserve (email), my id is: _______________________________________________