home *** CD-ROM | disk | FTP | other *** search
/ Amiga Elysian Archive / AmigaElysianArchive.iso / comm / mstat14a.lha / M-Stat.doc < prev    next >
Text File  |  1993-08-23  |  8KB  |  214 lines
  1.                                  M - S t a t
  2.  
  3.                                     v1.4a
  4.  
  5.                     A statistics generator for DLG BB/OS
  6.  
  7.                     (c) Phillip Eastham August 1993
  8.  
  9. ------------------------------------------------------------------------------
  10.  
  11.  
  12. What is it?
  13. ~~~~~~~~~~~
  14.        M-Stat is a new statistics generating program.  M-Stat will generate
  15. several text files which show the users who is best at the different areas of
  16. the BBS.  Also listed is the percentage of the total each of the top users
  17. has attained.  The top users values are totalled and both a number and a
  18. percentage of the total is included.
  19.  
  20.  
  21. Why?
  22. ~~~~
  23.        I had been using DLGTopX for 12 months or so when I logged onto a
  24. local BBS and had a look at the statistics program he was running. I thought
  25. it was quite nifty so I set about writing something similar. M-Stat is the
  26. result.
  27.  
  28.  
  29. How do I use it?
  30. ~~~~~~~~~~~~~~~~
  31.        M-Stat requires a configuration file.  It also has a few command line
  32. switches available.
  33.  
  34.    Config file: The config file is a standard ASCII text file which contains
  35.                 the path and name of each of the statistic panels produced.
  36.                 No comments or blank lines are allowed. Only the path/name on
  37.                 each line is allowed! An example config is included. The
  38.                 config file should be placed in 'DLGConfig:Misc/M-Stat.cfg'.
  39.                 The order is:-
  40.  
  41.        *  Line 1:  Sysop name
  42.           Line 2:  Downloaded KBytes
  43.           Line 3:  Uploaded KBytes
  44.           Line 4:  Uploaded Files
  45.           Line 5:  Downloaded Files
  46.           Line 6:  Messages written
  47.           Line 7:  Messages read
  48.           Line 8:  Calls
  49.           Line 9:  On-line time
  50.           Line 10: Chatters
  51.           Line 11: User averages
  52.           Line 12: Usage graph
  53.           Line 13: Characters to use in the usage graph. (See below)
  54.  
  55.        * To cater for Co-Sysops, I now use an in string function. If the
  56. current users name is found in this string, it is assumed they are a
  57. Co-Sysop.
  58.  
  59.        NOTE: The config MUST have 13 lines. If the program returns an 'end of
  60. file' error, edit the file and make sure that each line is terminated with a
  61. LF.
  62.  
  63.    Switches: These are the switches available:-
  64.  
  65.        -B     Turn on the horizontal bar's for the usage graph.
  66.     +  -C     Turn on Chatters mode.
  67.        -E     Inform user they are on top via 'Event.log'
  68.        -Lxx   Use xx records instead of 10.
  69.        -N     Add 15 spaces to the end of user and log output when in verbose
  70.               mode. This is for people who login remotely.
  71.        -P     Do NOT produce stats panels. Use to just produce usage graph.
  72.        -R     Place a '%RETURN' at the end of each file.
  73.        -S     Include sysop in statistics. Name taken from config.
  74.        -Txx   Set number of lines to use for usage display.
  75.        -U     Generate Usage graph
  76.        -V     Be verbose. Completely silent otherwise unless a program error
  77.               occurs.
  78.        -?     A short help screen.
  79.  
  80.  
  81.        + The chat file will be produced regardless of this switch. This
  82. switch toggles event log reporting of top chatter and the chatter line in the
  83. user averages panel.
  84.  
  85.        Place the command in your midnight event script, or run it several
  86. times a day via TpTCron.
  87.  
  88.        You will then need to set up a menu item for each stats panel.  Use
  89. the DLG supplied 'DF' command to display the text file.  A menu entry would
  90. look like this:
  91.  
  92.    [ 1] Letter:                   D
  93.    [ 2] Executable: (path/name)   DLG:DF DLGConfig:Text/TopFDn.TXT
  94.    [ 4] Description:              Worst file downloaders
  95.    [ 5] Type:                     Executable
  96.    [ 6] Help File:                STATS/D
  97.    [ 7] Lower level:              1
  98.    [ 8] Upper level:              255
  99.    [ 9] Hidden:                   NO
  100.    [10] Load type:                OVERLAY
  101.    [11] Ask user if sure:         NO
  102.    [12] Pend messages:            YES
  103.    [13] Cli mode:                 NO
  104.    [14] Pause on completion       YES
  105.  
  106.        Or you can use the inclosed prepaired M-Stat.menun file. It will
  107. display all the panels and the usage graph generated by M-Stat's default
  108. config file. All you need to do is change the sysop name in the config.
  109.  
  110.  
  111. A note about the usage graph:
  112. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  113.        It is best to run the usage graph section of M-Stat just before
  114. midnight.  If you run it just after midnight, chances are the current day will
  115. be empty.
  116.  
  117.        The usage graph allows the sysop to select a 2 character wide
  118. representation for each of the 4 catagories. Either leave this blank or
  119. include 8 characters. If its left blank, a double ANSI solid block will be
  120. used. See the config for an example.
  121.  
  122.        When a value close to the minimum value is found, a half height ANSI
  123. block will be used instead of the defined sysop character.
  124.  
  125.  
  126. Other files accessed:
  127. ~~~~~~~~~~~~~~~~~~~~~
  128.        M-Stat requires several files in order to run. First is the file
  129. DLGConfig:Misc/Users.BBS. The program will exit if this file doesn't exist.
  130. M-Stat then reads in each users data file.
  131.  
  132.        The filenames stored in the config file are not checked for existance.
  133. Make sure the path you give exists!
  134.  
  135.        The 8 log files contained in DLGConfig:Text/ are also needed for usage
  136. graph production. If a file is not present, it will be skipped.
  137.  
  138.        DLG.Library V2.0 is now required for M-Stat to run.
  139.  
  140.  
  141. Program status:
  142. ~~~~~~~~~~~~~~~
  143.        M-Stat is freeware.  Use it as you please.  Any bug reports or
  144. suggestions for improvements can be sent to me via Fido or UUCP:
  145.  
  146.      FidoNET:  Phillip Eastham@3:622/406
  147.      InterNET: phillip_eastham@kumear.apana.org.au
  148.  
  149.  
  150. History:
  151. ~~~~~~~~
  152.       Version 1.0  - Initial release.
  153.  
  154.       Version 1.1  - Made byte values dynamic to each system. Will switch
  155.                      between Bytes, KBytes, and MBytes depending on how many
  156.                      bytes the top user has accumulated.
  157.                    - Adjusted output so the graph was a little wider.
  158.                    - Streamlined operations a little.
  159.  
  160.       Version 1.2  - Fixed a problem when there are no more users with
  161.                      non-zero values. Now the entire line is just left blank.
  162.                    - Streamlined operations a little more!
  163.                    - Changed several error-trapping routines.
  164.                    - Added error output to sysop's 'Event.log' file.
  165.  
  166.       Version 1.3  - Added usage graph generation.
  167.                    - Made number of records totally sysop settable.
  168.                    - Changed formatting a little.
  169.  
  170.       Version 1.3a - Fixed a problem with incorrect ANSI on usage graph when
  171.                      stats panels not generated.
  172.                    - Fixed a bug in detection of Sysop in stats generation.
  173.                    - Made total for top users in byte down/uploads conform to
  174.                      2 decimal places if there is room.
  175.                    - Added a bit more verbosity when turned on.
  176.  
  177.       Version 1.3b - Fixed a problem with the message bar of usage graph
  178.                      using the upload bar's characters for custom bar's.
  179.                    - Added the -B option to make the usage graph more
  180.                      customisable.
  181.  
  182.       Version 1.3c - Implemented some library calls.
  183.  
  184.       Version 1.3d - Fixed a problem with event.log recording.
  185.                    - Cleaned up some routines.
  186.                    - Fixed a problem that was causing a RAM leak.
  187.                    - Changed the usage graph just a little.
  188.  
  189.       Version 1.4  - Added top chatters with limited disabling.
  190.                    - Added Co-Sysop support.
  191.                    - Changed average values to Integers for those panels
  192.                      where you can't have fractions.
  193.                    - Removed error reporting to sysop's event.log because of
  194.                      the Co-Sysop support. Now appends error messages to a
  195.                      global error file called 'LOGS:M-Error.log'.
  196.  
  197.       Version 1.4a - Fixed a major problem with system crashes and freezes
  198.                      under OS3.1. Host machine was an A3000. Apparantly fixed
  199.                      in a test version sent to system.
  200.  
  201.  
  202. Thanks to:
  203. ~~~~~~~~~~
  204.        Thanks go to Mike West for testing the program on a sparsely populated
  205. BBS.
  206.  
  207.        Thanks to the Eric De Jong for the ARexx script from which the usage
  208. graph is taken.
  209.  
  210.        Thanks go to the OS3.1 owner who shall remain nameless (for obvious
  211. reasons!).
  212.  
  213.  
  214.