ftp.wwiv.com/ftp.wwiv.com.zip/ftp.wwiv.com/pub/MISC/TGAUP200.ZIP/TGAVG.DOC

Text File | 1998-11-10 | 19KB | 414 lines

                       Telegard Average User Profiler v2.00
                               by Ken Reaverson
                                For TG 3.09+

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ Introduction ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

 Telegard Average User Profiler (hereafter referred to as TGAUP) is a third
 party utility which will read from a Telegard BBS's user file, average the
 statistics for users in three different category (Male,Female, Overall) and
 output that information in a user definable template.

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ License and Disclaimer ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

 The author of TGAUP is not responsible for any damaged, corrupted, lost,
 or otherwise harmful occurences that may occur from use (or inability
 thereof) of this program. It has been tested, and the author runs it on his
 own system. To the best of my knowledge, TGAUP has no bugs and will not
 destroy anything on your system. However, I guarentee nothing, except that
 this program will take up hard drive space.

 No Warranty is given, either expressed or implied, as to the functionality
 of this software program. By using this program, you are agreeing not to
 hold the author, Kenneth Reaverson, responsible for any damages (consequential
 or incidental) that arise from your ability to use or misuse this program,
 that you have read this entire document, and are familiar with its terms,
 and agree to exempt Kenneth Reaverson from any and all responsibilities in
 the event of any damages to your system which are caused either through
 direct or indirect use of this software.

 If it breaks, you own both halves.

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ Requirements ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

 TGAUP's requirements differ depending on which executable is being run:

   TGAUP/DOS:

     - MS-DOS (or compatible) 5.00 or higher
     - Telegard BBS v3.09.g1 or higher
     - An 80286 processor or better

   TGAUP/2:

     - OS/2 Warp 3 or higher
     - Telegard BBS v3.09.g1 or higher
     - An 80486 processor or better

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ Installation ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

 Installation of TGAUP is simple. First, decide which executable you're going
 to use (DOS or OS/2) and rename it either TGAVG.DOS or TGAVG.OS2 to
 TGAVG.EXE. Once this is done, decide where you want the executable (the
 author recommends the main Telegard directory). If the TELEGARD environmental
 variable is defined, TGAUP can be run from anywhere on the system. Otherwise
 it must be run from the main Telegard directory.

 The template file must be in the same directory as the executable. Either
 create your own, or use the default TGAVG.TPL included in the archive.

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ Usage ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

 TGAUP is best run as part of the logoff process, or as a nightly event.
 It's all up to the sysop. I personally run it after every caller logs off.
 TGAUP will detect and skip deleted user records that have yet to be packed
 out of the userfile.

 Since TGAUP does seperate averages for Males and Females, it is recommended
 that System.Config->Newuser->I. Gender be set to Yes in your Telegard
 configuration. Otherwise, TGAUP will see all users without a gender specified
 as Female. Yeah, I could program a way around that, but I don't want to. ;)

   TGAVG.EXE will accept the following on the commandline:

     First Parameter:

         Template - This is the user definable template that TGAUP will
                    read in and spit back out with the totals on it.

            /?    - A small help screen. If this parameter is defined, all
                    following parameters are ignored.

            /V    - A small screen of miscellanous information about the
                    program. If this parameter is defined, all following
                    parameters are ignored.


     Second Parameter:

           Output - This is the filename to give the bulletin that TGAUP
                    will create. TGAUP will automatically create this
                    file in your TEXT\ directory, as defined in CONFIG.TG


         Example: TGAVG.EXE TGAVG.TPL BULLET1.MSG

     Third Parameter (Optional):

                # - TGAUP outputs the average # of k downloaded/uploaded
                    in all three categories. In addition to the number,
                    a lowercase 'k' is added to the end, and is included
                    when the MCI translates. The default color assigned
                    to that 'k' is |07 (Light Grey). This parameter allows
                    the end user to change that default color. This should
                    be a two digit number, ranging from 01 to 15, and
                    the numbers correspond to the standard Forum Pipe
                    Codes (ie, |07 for Light Grey, |15 for White, |14
                    for Yellow, etc). Do *not* specify a | on the commandline,
                    it is assumed. Only the two digit number is needed.
                    If this parameter is defined, then it must be
                    the third on the commandline.

     Fourth Parameter (Optional):

               /S - This specifies whether or not the Sysop's statistics
                    will be included in the averaging. By default, TGAUP
                    will not include the sysop's numbers. It is the opinion
                    of the author that the Sysop is anything but an average
                    user, and the inclusion of his/her totals throws off
                    the real averages quite a bit. However, for those
                    who feel differently, simply specify this parameter,
                    and TGAUP will accomadate you. This can be either
                    the third or the fourth parameter on the commandline.
                    If it's the third, then nothing else may be defined
                    behind it. If you do define a fourth parameter with
                    /S as the third, then the /S will be ignored. If /S
                    is defined as the fourth, then it must be preceeded
                    by the K-Color parameter mentioned above.

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ MCI Codes & The Template ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

 TGAUP allows the user to define their own custom template. I recommend that
 the template be a standard ascii file using Telegard specific color codes
 as opposed to an ANSI file. An Ansi file may very well work with TGAUP, I
 don't know, I haven't tried it. ;)

 TGAUP reads the template line by line, looks for MCI codes, translates them,
 and then writes that line to the output file.

 MCI Codes come in two varieties: Format MCI Codes and Statistic MCI codes.

Statistical MCI Codes:

   Statistic MCI codes translate to the various statisical averages that TGAUP
   collects. Statistical MCI codes are 3 characters long. Staying with the
   Telegard standard for MCI codes, they begin with a ~.

   The next character determines which set of data a statistic will be pulled
   from:

     M - Male
     F - Female
     T - Overall

   The final character determines which statistic will be displayed:

     1 - Average # of Calls
     2 - Average # of Public Posts
     3 - Average # of Private Posts
     4 - Average # of Netmail Posts
     5 - Average # of Uploaded/K
     6 - Average # of Downloaded/K
     7 - Average # of Uploads
     8 - Average # of Downloads
     9 - Average Total Time Online
     A - Average # of Mins/Call
     B - Average User Age

   So therefore, if you wanted to display the average Male user age, the
   MCI Code would ~MB. If you wanted to display the Overall average # of
   Public Posts, the MCI code would be ~T3. If you wished to show the average
   # of kilobytes uploaded by female users, the MCI code would be ~F5.

   I know, this sounds confusing for the new guys. :) The easiest way to
   remember is this: An MCI code has three parts. The tilde(~), which tells
   TGAUP that the following two letters are an MCI code, and need to be
   translated. The second part determines the sex from which the statistic
   will be pulled (Male, Female, or All) and the final part determines which
   statistic is actually displayed.

   In addition to these 33 MCI codes, there are 3 more available:

     ~TM - Total # of Male Users
     ~TF - Total # of Female Users
     ~TU - Total # of Users

   These are statistical MCI codes, but since they don't follow the above
   convention, I chose to mention them seperately. Anywhere one of these
   MCI codes appears in the template, they will translate to their respective
   totals.

Format MCI Codes:
  Format MCI codes are just what they sound like: They format text. The valid
  MCI codes that TGAUP will recognize are as follows:

    ~EL - Left Justified
    ~ER - Right Justfied
    ~EC - Center

  The Format MCI codes affect the next statistical MCI code. Immedietly
  following a format code must be a number in the range of 1 to 40.
  This number specifies how many spaces to pad the MCI code out to before
  justification or centering.

  For example, to center the Average Age of all Users within 20 spaces,
  the MCI code would look like this:

  ~EC20~TB

  This would cause TGAUP to insert 20 spaces, beginning from where the first
  ~ appears, and the Average User Age would appear as the 10th and 11th
  characters (assuming a two digit average user age ;)).

  NOTE: When centering, if an item cannot be placed at the exact center
        of the string (same number of spaces on each side of the data),
        the extra space will be added after the translated code. All space
        you specify will be accounted for, and remainders get tacked on to
        the end.

  Say you wanted to left justify the Average Female Public Posts out to 9
  spaces. The MCI Code would be ~EL9~F2. If your total was, say 320, then
  320 would appear starting where the first ~ was, and 6 empty spaces would
  be added after it. Right justify works the same way, except that the
  empty spaces are added first.

  NOTE: Do *not* define a leading 0 if the number of spaces to pad is
        less than 10. ~EC5 is valid. ~EC05 is not.

  I've tried to keep this as near to Telegard as I possibly could, so if
  you've experience creating your own custom screens in TG, this should
  be old hat to you.

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ Notes ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

 This was probably the most valuable learning experience I've had to date.
 Adding the ability for custom templates to this program required me to
 figure out how to do what I wanted on my own.

 When creating your templates, keep in mind that MCI values are dynamic and
 tend to change often. This is important, as if you don't allocate enough
 space (or any) in your templates for growth, they'll start appearing
 out of whack. The easiest way to do this is to remove all extra spaces from
 your template and tell TGAUP to add them via one of the Formatting MCI
 codes when it translates and justifies the next Statistical MCI code.

 Take this for example:

 ┌─────────┐
 │   ~TU   │
 └─────────┘

 That's the MCI for total overall users. Let's just say, for the sake
 of arguement, you've got one user. What happens?

 It ends up looking like this:

 ┌─────────┐
 │    1  │
 └─────────┘

 As you can see, this is *not* the boxed effect you were going for.

 However, what happens if you tack those two missing spaces on in a
 justification code?

 ┌─────────┐
 │    ~EL3~TU   │
 └─────────┘

 That's what the MCI would look like (note, it's 3 spaces because you
 want to make up that extra two, plus the data is taking up one.

 The MCI here looks disjointed, but that's okay. Because when TGAUP goes
 to translate, the MCI code is deleted, and it looks something like this:

 ┌─────────┐
 │       │
 └─────────┘

 Since you've told it to display an MCI code out to three characters,
 justified left, the 1 appears where the first ~ was, and two empty
 spaces are tacked on, for the final appearance of this:

 ┌─────────┐
 │    1    │
 └─────────┘

 That's probably the effect you were going for. What happens if you
 have a sudden expansion of growth, and now have 357 users? Well, those
 two empty spaces it's tacking on will be filled with the other two numbers
 instead.

 Note that if you do not specify enough space for the code to display in
 it's entirety, it will act as though it hasn't been justified at all (ie,
 it will insert all necessary spaces and no extra).

 So if you specified ~EL3~TU, and you had 1500 users, 1500 would display
 beginning from the first ~.

 Templates are mostly a matter of trial and error. Remember to account
 for the space, and you should come out fine. If you absolutely, positively
 cannot get a template to display the way you want it, send me a copy of
 what you want the final output to look like, and I'll make it into a
 template myself. :)

 One more warning: When considering how many spaces to pad out for
 the various Uploaded/K & Downloaded/K MCI codes, add three. :) The reason
 for this is that there's a color code added in to that string, right before
 the 'k' is appended. That color code does count towards your overall space
 as far as TGAUP is concerned. Telegard translates the color code,
 effectively removing it from the string, and taking away three spaces that
 TGAUP thought it had covered when the template was made. :)

 TGAUP/DOS has been compiled with Borland Pascal v7.0.

 TGAUP/2 has been compiled with Virtual Pascal v1.10

 The source code to either version is not available to the public, and it
 is not for sale, so please don't ask. :)

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ Registration ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

 TGAUP is FreeWare. End of story. Live free or die, ladies and gentlemen. :)

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ Distribution ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

 TGAUP may be freely distributed in it's unmodified format. See PACKING.LST
 for a list of what should be included in the archive. The archive's original
 fornat is ZIP, and it has been stamped with my AV codes. If the archive
 you've received is not a ZIP, be wary. When unzipping this archive, at
 the very end, you should see the following:

 Authentic Files Verified!   # CIS105
 Blood Enterprises, Inc.

 If this message is not present, the archive may have been tampered with.

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ Copyrights ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

     Telegard Average User Profiler is Copyright Blood Enterprises, 1998.
                                    All Rights Reserved.

     Telegard is Copyright Tim Strike, 1994,1998. All Rights Reserved.

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ Special Thanks ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

 The following people deserve special thanks for their efforts, whether it
 be direct or indirect, for bringing this utility about:

      Tim Strike  - As always, and always. Keep up the good work, man. :)

     David Stumpf &
      Scott Adams - For some initial help in getting the concept of processing
                    a text file line by line. ;)

     Arthur Stark - For patiently enduring my bitching on IRC while trying
                    to figure this stuff out. ;)

    Black Sabbath &
        Biohazard - For providing such cool music to distract me when I
                    started to get frustrated. ;)

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ Future Plans ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

 Well, I plan to run for governor of Minnesota next term. If Jessie Ventura
 can win it, than I damned well better be able to. ;)

 All levity aside, the only thing planned for TGAUP are bugfixes should any
 pop up. Since I've rewritten and added a good portion of code, I'm betting
 that I screwed up somewhere. :) Hopefully someone will catch it and I'll
 fix it, but until that time, the TGAUP code gathers dust.

┌─────────────────────────────────────────────────────────────────────────────┐
│▒▒ Service & Support ▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒▒│
└─────────────────────────────────────────────────────────────────────────────┘

 Contact Information -

   Author: Ken Reaverson
    Email: [e-mail]
      WWW: http://www.darktech.org/shadowdale
  Netmail: 1:133/1004   - FidoNet
           111:4350/101 - Sysop's TechNet
 EchoMail: TG_SUPPORT (FidoNet)
           ADV_TG (AdventureNet)

 If you have a question or a problem with the software, by all means, get
 into contact with me via one of the above methods. I welcome comments and
 suggestions, and if you find a bug in the software, I'll do my damndest to
 fix it with all speed.