home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / usagep24.lzh / USAGE.DOC < prev    next >
Text File  |  1993-02-04  |  11KB  |  211 lines
  1.  
  2. USAGE -- Reads one or more Maximus or Binkley logs and generates a usage graph
  3.  
  4. Version 2.4  (02/04/93)
  5.  
  6. Written by Bob Quinlan of Austin, Texas, USA
  7. Sysop of Red October at 512-834-2593 (1:382/111)
  8. Special thanks to Steve Antonoff for suggestions and code.
  9.  
  10. Copyright 1993 by Bob Quinlan
  11.  
  12. Compatible with Maximus 2.00 and 2.01 and BinkleyTerm 2.55 and 2.56
  13.  
  14.  
  15. This program reads one or more Maximus or Binkley type logs and
  16. generates a BBS-format usage graph based on the data.  By default it
  17. will read MAX.LOG in the current directory and write USAGE.BBS.  The
  18. following switches allow you to configure it for your system and
  19. preferences:
  20.  
  21.     /Cx=y       Set color number 'x' to Avatar color 'y'.  'x' values
  22.                 mean the following:
  23.                     0 = default color
  24.                     1 = title
  25.                     2 = frame
  26.                     3 = reference text (%)
  27.                     4 = reference lines (%)
  28.                     5 = hour text
  29.                     6 = hour dots (odd hour values)
  30.                     7 = hour lines
  31.                     8 = data bars
  32.                     9 = enter prompt
  33.                 Avatar color codes are given in two-digit hexadecimal.
  34.                 The first digit sets the background color (0-7 only) and
  35.                 the second digit sets the foreground color (0-F).  Each
  36.                 digit corresponds to the following colors:
  37.                     0 = black
  38.                     1 = blue
  39.                     2 = green
  40.                     3 = cyan
  41.                     4 = red
  42.                     5 = magenta
  43.                     6 = brown
  44.                     7 = white
  45.                     8 = grey
  46.                     9 = bright blue
  47.                     A = bright green
  48.                     B = bright cyan
  49.                     C = bright red
  50.                     D = bright magenta
  51.                     E = yellow
  52.                     F = bright white
  53.                 Example: To set the data bars to yellow on blue you
  54.                 would use the switch /C8=1E.
  55.  
  56.     /Ddays      Days of history to use.  Any log events or history file
  57.                 entries older than this many days will be ignored.
  58.  
  59.     /Hfile      History file to process.  This eliminates the need to
  60.                 rescan old log data.  Every time USAGE runs a new record
  61.                 is added to the history file for future reference.
  62.                 Records older than the /D parameter specifies will be
  63.                 removed from the history file automatically.
  64.  
  65.                 This information is stored in USAGE.HST by default.  You
  66.                 can specify another name using the /H parameter.  Using
  67.                 /H by itself will prevent history file processing.
  68.  
  69.     /Ifile      Incremental file to process.  This file keeps track of
  70.                 where and in what state the previous log ended.  If the
  71.                 file has been restarted since the last run that will be
  72.                 detected and the location pointer reset to the beginning
  73.                 of the new file.
  74.  
  75.                 Incremental processing means that your maintenance times
  76.                 will be included in the graph as "in use" periods.
  77.                 Without this feature they would never register because
  78.                 the processing would also end with an unresolved active
  79.                 event.
  80.  
  81.                 This information is stored in USAGE.INC by default.  You
  82.                 can specify another name using the /I parameter.  Using
  83.                 /I by itself will prevent incremental file processing.
  84.  
  85.     /Lfile      Log file to process.  Note that the /L parameter can be
  86.                 used more than once to specify several logs.  This
  87.                 feature is particularly useful if you have multiple
  88.                 lines with separate logs.
  89.  
  90.     /M          Military time.  Display the hours as 0-23.
  91.  
  92.     /Sfile      Search file to process.  You can override the default
  93.                 search strings that are used to recognize system
  94.                 activity in the log by specifying a search file.
  95.  
  96.                 A search file is just a text file containing one string
  97.                 per line.  Search strings must begin with the log field
  98.                 immediately following the date.  Add a + as the first
  99.                 character of each line that indicates an activity is
  100.                 starting.  Add a - as the first character of each line
  101.                 that indicates an activity is ending.
  102.  
  103.                 By default USAGE uses a set of search strings that
  104.                 should work with both BinkleyTerm and Maximus.  BINK.S
  105.                 and MAX.S are included both as samples to help you
  106.                 construct your own search files.  Other .S files may
  107.                 also be included.
  108.  
  109.     /Ttitle     Title for graph.  You may want to supply multiple word
  110.                 values for title.  You can separate the words by spaces
  111.                 or by underscores (which will be replaced by spaces).
  112.                 For example, both of these lines would produce the same
  113.                 results:
  114.                     usage /lmax.log /tRed October Usage
  115.                     usage /lmax.log /tRed_October_Usage
  116.  
  117.     /Ufile      The file to which the usage graph will be written.  The
  118.                 .BBS extension is not automatically added.
  119.  
  120.     /V          Verbose diagnostic mode.  Prints out each log entry that
  121.                 triggers a starting or ending time.  Prints the elapsed
  122.                 time between each start/end pair.  Not recommended for
  123.                 normal use.
  124.  
  125.     /Vcount     Volume.  If verbose mode is not turned on a dot is
  126.                 printed every time a new usage entry is found.  Setting
  127.                 'count' to zero turns off the dots.  Setting 'count' to
  128.                 any other number divides down the number of dots by a
  129.                 factor of 'count'.  (For example: /V3 produces one dot
  130.                 for every three usage entries.)
  131.  
  132. If you use WFC within Maximus pass USAGE the Maximus log.  If you use
  133. Binkley to answer the phone pass it the Binkley log.  You can mix log
  134. types if you have lines with different configurations.
  135.  
  136. As an example, lets say a system has two lines.  One runs Binkley and
  137. the runs Maximus with WFC.  A new log is started every month.  Here is
  138. how to generate an overall usage graph:
  139.  
  140. usage /lbink01.log /lmax02.log /tOverall Usage
  141.  
  142. I also want to generate usage graphs for each line separately.  I want to
  143. reprocess the same logs for this purpose and I want to keep the history
  144. data separate, so I specify different history and incremental files for
  145. each:
  146.  
  147. usage /husage01.hst /iusage01.inc /lbink01.log /uusage01.bbs /tLine One
  148. usage /husage02.hst /iusage02.inc /lmax02.log /uusage02.bbs /tLine Two
  149.  
  150.  
  151. USAGE returns ERRORLEVEL 0 after a successful run.  ERRORLEVEL 1 is
  152. returned to indicate an error.
  153.  
  154. NOTICE:  You may use, copy, and distribute this program freely as long
  155. as you insure that both the executable and the documentation (.DOC)
  156. files are included in the distribution package.  The source code does
  157. not need to be included.  You may modify this program and document, so
  158. long as reasonable credit is given to the original author if a
  159. substantial portion of the original remains intact.  The author is not
  160. responsible for any losses which may occur either directly or indirectly
  161. as a result of using this program.
  162.  
  163. HISTORY:
  164. Version 2.4  (02/04/93) -- Added three new default Binkley search
  165.                            strings thanks to Walter Anderson.
  166. Version 2.3  (11/10/92) -- Modified the /I file format (again!) so that
  167.                            file contents are checked against stored
  168.                            positions.  This eliminates the need to worry
  169.                            about new files being shorter than old ones.
  170.                            The default is now /IUSAGE.INC.  /I with no
  171.                            parameter will turn off this feature.  /H now
  172.                            defaults to /HUSAGE.HST.  /H with no
  173.                            parameter will turn history off.
  174. Version 2.2  (11/07/92) -- Modified /I file format so that active usage
  175.                            can be tracked across log boundaries.  This
  176.                            should keep your maintenance period from
  177.                            showing up as a blank spot on the graph.  A
  178.                            CVTINC utility is included to convert 2.1
  179.                            format incremental files to the 2.2 format.
  180. Version 2.1  (11/04/92) -- Added the /I parameter to allow incremental
  181.                            processing of log files.  Added a new /V
  182.                            switch option (volume) to limit screen
  183.                            output.
  184. Version 2.0  (11/03/92) -- Added the /H parameter to specify a
  185.                            self-maintaining history file.  Added the /S
  186.                            parameter to specify a file of user-defined
  187.                            search strings.  Added the /D parameter to
  188.                            specify how many days to include in the
  189.                            graph.  Improved the speed of elapsed time
  190.                            calculations.  Track event times in seconds
  191.                            instead of minutes.  Track total time by
  192.                            seconds intsead of days.  Cleaned up a lot of
  193.                            messy code.  Many of the improvements were
  194.                            suggested and originally coded by Steve
  195.                            Antonoff.
  196. Verison 1.9  (10/28/92) -- Skipped.
  197. Version 1.8   (8/28/92) -- Added the /M switch for military time.
  198. Version 1.7   (8/25/92) -- Added the ability to pass multiple-word
  199.                            parameters using spaces.
  200. Version 1.6   (6/03/92) -- Adjusted graph to start at midnight.
  201. Version 1.5   (5/29/92) -- Improved Binkley support.  Added verbose
  202.                            diagnostic mode.
  203. Version 1.4   (5/27/92) -- Allow custom color selections.
  204. Version 1.3   (5/26/92) -- Removed event and keyboard switches.
  205.                            Added support for Binkley logs.
  206.                            Added log file sharing (again).
  207. Version 1.2   (5/14/92) -- Removed log file sharing due to compiler bug.
  208. Version 1.1   (5/13/92) -- Added log file sharing.
  209. Version 1.0   (4/22/92) -- Original release.  Written in Borland C.
  210.  
  211.