ProfitPress Mega CDROM2 …eeware (MSDOS)(1992)(Eng)/ProfitPress-MegaCDROM2.B6I/BBS/MISC/QCKTOP26.ZIP/QCKTOP40.DOC

Text File | 1991-04-16 | 43.6 KB | 1,164 lines

                       Top40 - version 2.6

    WILDCAT! BBS, QuickBBS, and PowrBBS Top 40 user utility

                         January 7, 1990

                     Revised April 16, 1991

    (C) Copyright 1990 Judson McCranie.  All rights reserved.

                       Judson S. McCranie
                       Mantissa Software
                       1505 E. Park, #G4
                       Valdosta, GA 31602
                       Ph: [phone]

NOTE: This documentation applies to three versions of Top40:
WCTop40 for Wildcat BBS, QckTop40 for QuickBBS, and PwrTop40 for
PowrBBS.  The actual program files are prefixed with "WC", "Qck",
or "Pwr" except for the output bulletin files.

The latest version of the program and support are available
through:

                       Bad Lands (QuickBBS)
                  300/1200/2400/9600 HST 8,N,1.
                        Sysop: Andy Smith
                         [phone]

This program is distributed on a "Shareware" (try-before-you-buy)
basis.  You are free to copy it and to distribute copies at cost.
You may not alter the program (or its documentation) or sell it
for profit.

You may try this program for a period of 30 days.  If you
continue to use this program after the 30 day period then you
must register it by sending your the name of your board, the
board's phone number, and your name & address along with the
program name and version number with a $20 registration and
license fee to me at the address above.  You will receive support
for the program, announcements of new versions of this program,
and information about several other programs.  Please send any
inquires, comments, or suggestions to me at the address above.


WHAT IS TOP40:

Top40 is a Sysop utility designed to create over a dozen
different top user bulletins.  It makes full use of the activity
log and creates a user data file which is updated with each use.
The WC version of the program is designed to work with WILDCAT
2.xx but may work with previous versions.  The Qck version is
designed to work with QuickBBS version 2.6x, but may work with
other versions.  The Pwr version of the program is designed to
work with PowrBBS version 1.30 but should work with other
versions.

You should find the following files in the archived file.

  xxxTop40.DOC  this documentation file
  Top40   .XM?  examples of bulletins
  xxTop40I.EXE  sysop installation program (PwrT40I.EXE for Pwr)
  xxxTop40.EXE  program to generate bulletins
  WCTop40C.EXE  converts files from 1.5x format to 2.0x (WC only)
  WCT40C23.EXE  converts files from 2.1x/2.2 to 2.3/2.4 (WC only)
  ORDERBLK.DOC  registration form
  OTHER   .DOC  other programs by this author

where xxx = "WC", "QCK", or "PWR" and xx = "WC", "QCK", or "PW".

The program will generate the following files in the current
directory:

  xxTop40.OPT  generated by the installation program
  xxTop40.DAT  generated by the main program
  xxTop40.SIZ  generated by then main or conversion program

where xx = "WC", "Qck", or "Pwr".

These files should be in the same directory as the Top40 EXE
files and that directory should be the current directory when
Top40 is run (i.e. - don't run Top40 with a path).  You can
specify a path to the activity log and user data files and a path
to which the bulletin files will be written.

This program is a utility to add top user lists to the WILDCAT
BBS, QuickBBS, or PowerBBS.  It can be run after each call or as
an event.  You can specify the number of users that will appear
on the list, or disable any report.  The program compiles reports
of the top users of each of following from the activity log:

     callers
     posters (messages)
     uploaders
     downloaders
     door openers
     carrier droppers (Use as a bulletin if D/Cs are really bad)
     security violators (recommended for yourself only)

Note: The program currently considers any termination of the call
other than a normal logoff a "carrier drop".  It could more
properly be called an abnormal termination or logoff.

It also will generate these compilation reports:

     newest users
     best users (based of total points > 0)
     BBS losers (based on total points < 1)
     All users  (based on total points)

     triple list - report of any three of the above categories

Three "triple lists" are available.

The most unique feature is the list of the top users, which is
based on a weighted point system.  For instance, you can assign 2
points for each call, 1 point for each message, 10 points for
each upload, -5 points for each download, -10 points for each
security violation, etc.  The user's total points is based on
this value calculated from his statistics.

    Item Used             Recommended Point Value

    Number of Calls                  1 to   2
    Number of Messages posted        2 to   4
    Number of Uploads               10 to  25
    Number of Downloads             -5 to -15
    Number of Door uses              1 to   3
    Number of Carrier drops         -1 to  -3
    Number of Security violations   -3 to  -5

Feel free to experiment with the point values until the resulting
scores suit you.  You should probably consider a balance between
the points for uploads and the points for downloads.  For
instance, if you expect a 5:1 upload:download ratio, the point
value for an upload should probably be 5 times as large (in
absolute value) as the value for a download (e.g. +20 for an
upload, -4 for a download).

The "newest users" is a list of the newest users.  The newest
user will be #1 on the list, etc.  This should be encouraging to
new users since they will get to see their names at the top of
the list the next time they call.  Otherwise, it would be quite a
while before they make any of the top user lists.


CHANGES IN VERSION 2.6:

Added support for QuickBBS.


CHANGES IN VERSION 2.5:

Fixed a bug in the Wildcat version installation program.

Added the option of entering the name of the user data file.


CHANGES IN VERSION 2.4:

Faster reading and writing of disk files.

Smaller EXE file.


CHANGES IN VERSION 2.3:

Add support for PowrBBS.

Add an extension option for ASCII files.

New options file format.


CHANGES IN VERSION 2.2:

The "Purge deleted users" choice in the installation program will
delete any users from the Top40 data file that have been deleted
from the Wildcat user data base.  The "Delete users" (which
deleted individual users) has been removed from the installation
program.  I no longer see a need for it, but if you think it
should stay in the program please let me know.

The background color problem in the ANSI screens has been fixed.
(Thanks to Bob Lias for informing me of the problem.)

You can now specify the path to the user data file (USERFILE.DAT
or USERS).


CHANGES IN VERSION 2.14:

There was a bug in versions 2.1 through 2.13 in the "newest user
list".  (Thanks to Cam DeBuck for pointing this out.)  See "How
bugs creep into programs" for more details.


CHANGES IN VERSION 2.1:

  Support for Wildcat version 2.15.

  Fix a bug when a user is deleted by WCRepair.

  Option of ANSI screens.

  Option of counting down to number 1 on the lists.


SUMMARY OF CONVERSION FOR USERS OF VERSIONS PRIOR TO 2.3:

The options data file (WCTop40.OPT) has been reorganized.  You
can't simply run the program with the old option file like you
could when going from version 2.0x to 2.1x or 2.2, or from 2.1x
to 2.2.

Here is my recommendation for users of previous versions who
which to upgrade to the current version while retaining their
data.  There are several things you could do to upgrade the data
files.  In all cases, I recommend making a backup copy of the
data files before doing the conversion.  More details follow, but
my recommendations are:

For users of 2.1x or 2.2, the easiest way to get to 2.4 (or 2.3x)
is to run WCT40C23 to convert the options file to the new format,
and then run the installation program and check all options.  In
particular, you need to check the ASCII file extension option if
you want something other than the default "ASC".  Alternatively,
you could delete the "WCTop40.OPT" file and reinstall the
parameters.

For users of version 2.0x the easiest thing to do is run the
program WCT40C23 and then run the installation program and check
the options.  In particular, you need to check the ASCII file
extension option if you want something other than the default
"ASC" and the options for the ANSI screens.  Alternatively,
delete the file WCTop40.OPT and reinstall the options.

For users of version 1.3x, 1.4x, and 1.5x, you need to run the
program WCTop40C.  This will bring the file WCTop40.DAT up to the
current standard and the option file (WCTop40.OPT) up to version
2.0 standard.  Then see the "For users of version 2.0x" above.
Alternatively, you could skip the upgrade programs, delete the
options file (WCTop40.OPT), reinstall the options, and then edit
the user database to check the include/exclude option on each
user.


USERS OF VERSION 2.1x OR 2.2:

You can use the program WCT40C23.EXE to convert the option file
to the new (version 2.3/2.4) format.  In version 2.3 and 2.4 the
extension for the ASCII files has been separated from the file
names.  The default is "ASC".  You can change this by running the
installation program after the conversion program.
Alternatively, you can delete the options file (WCTop40.OPT or
PwrTop40.OPT) and run the installation program again.


USERS OF ANY VERSION PRIOR TO 2.1:

I recommend deleting the file Top40.OPT and reinstalling the
parameters as being the easiest way to get up and running with
this version.  Users of 1.x see the following note.

Before version 2.1 there was a problem when you delete a user and
use WCRepair.  WCRepair changes user's record number (that
appears in ACTIVITY.LOG).  Versions before 2.1 used this record
number to match up records (as opposed to the names).  If you
were using Top40 then deleted a user, then ran Top40 again then
Top40's data file (Top40.DAT) will be corrupted - users will be
listed more than once with their old and new record numbers.
These seems to be no feasible way to correct the dat file since
the data for an old user that had a user's new record number will
be lost.  The best thing to do is to delete Top40.DAT and
Top40.SIZ and let Top40 rebuild the data file.

Versions of Top40 prior to 2.1 will not work correctly with
Wildcat! version 2.15 (or later versions).  The reason is that
the versions before 2.1 read the record number from the activity
log and used that to match records.  In Wildcat version 2.1, the
second line of the calling record had "Record number:", whereas
version 2.15 has "Record:".  Old versions of Top40 looked for the
former wording.  Version 2.1 of Top40 avoids the problem (and
other problems) by going by the user name only.


USERS OF VERSION 2.0x:

If you want to generate ANSI screens then you need to run the
installation program and set the colors and the extension of the
ANSI files.  There is also a new option of counting down to
number 1 on the lists.


USERS OF VERSION 1.3, 1.4x, OR 1.5x:

The format of the file Top40.OPT has been changed slightly to
accommodate new features.  You can either:

  1) Delete the file Top40.OPT and run the installation program
     to reinstall the options

  2) Edit the file Top40.OPT manually.

It is a good idea to make backup copies of Top40.DAT and
Top40.OPT before running the conversion program (Top40C).  All
Top40C does is set the include/exclude option on each user.  If
you don't use the conversion program you will need to use the
installation program to edit the user data and set everyone's
inclusion/exclusion option.

If you are converting from version 1.3, 1.4x, or 1.5x, the
options file should be converted either by hand or the conversion
program before the data file is converted.  The conversion
program expects the options file to be in 1.5 format.  That is,
if you convert the options file by hand to 1.5 format then you
should run the conversion program to convert the options file and
data file.  Do not convert the options file to 2.0 format by
hand, otherwise the "excluded user" information will be lost.

After converting to 2.0 format then you can run WCT40C23 to
convert to version 2.3/2.4 format.  (See "USERS OF VERSION 2.1x
OR 2.2".)

If this seems confusing, here is a recap:

Users of version 1.3 or 1.4x, do either:

  1) Convert the options file to 1.5 format by hand and
     then see option 1 below.

  2) Delete options file and reinstall - see option 2 below.

  3) Convert options to 2.0 format by hand - see option 3 below.
     Then convert to 2.4.


Users of version 1.5x, do either:

  1) Run the conversion and tell it to convert BOTH the options
     file AND the data file.

  2) Delete Top40.OPT and reinstall options, then run the
     conversion program and tell it NOT to convert the options
     file but DO tell it convert the data file.

  3) Convert the options file to 2.0 format by hand and then run
     the conversion program - telling it NOT to convert the
     options file but DO convert the data file.  Then use the
     installation program to exclude the users you want to
     exclude (if any).  Then run the conversion program WCT40C23
     to convert to version 2.3/2.4 format.


INSTALLATION:

The opening screen of the installation program (Top40I) gives you
the following options:

    General options (board name and file paths)
    Category options (calls, messages, etc)
    Point lists (lists based on weighted points)
    Triple lists (combination of any three lists)
    Add users
    Edit users
    Purge deleted users from file (replaces "Delete users")
    List users to printer
    Quit installation

in the form of a standard pick list.  You can use the cursor to
get down to the desired item and press <ENTER> or you can simply
press the first letter of the option.

To use, enter Top40I at the DOS prompt and answer the questions
you will be asked.  The edit screens use standard editing keys -
arrows, backspace, home, end, <ENTER>, etc.  When you have
finished with your entries to a given screen press <CTRL-ENTER>
to save the configuration.  Press <ESC> to exit from the screen
without saving changes.

Once you have the installation complete, you need only type in
Top40 and hit return to compile the data file, or you can wait
for it to be called the completion of the next call or event.

The program Top40I is the sysop's installation program where you
can set various options.  There are four option screens.

The first option screen allows you enter the name of the board
and enter paths for the activity log file and for the generated
reports.  There is not much error checking on the file names and
paths you enter, so be sure to enter valid paths and file names.
The program will append a "\" to the end of the path, if needed.
Otherwise, the full path must be specified.  It is not necessary
to put the drive code in the path if it is the same as the
current drive.

The second option screen is for entering options pertaining to
each of the categories.  For each category you can set the output
filename, whether or not to go down the columns (Y/N), the number
of columns to print (2 or 3), and the number of each you want
listed (a zero keeps the report from being generated).  For each
of the categories you can enter the number of points that item
should count for the user's total point standing.  A value of
zero points means that the item is not included in the total
point calculation.  Even if you do not select a report for an
individual category it still counts in the total user points.

The third option screen allows you enter options pertaining to
the compilation reports ("newest users", "best users", "BBS
losers", and "all users").  You can enter the number you want
printed (zero means no report will be generated), the file name
to which the report will be written, whether or not to go down
columns (Y/N), and the number of columns (2 or 3).  The all users
will list all users in order of total points, with an upper limit
of the number you specify.  To list all users, set this value to
a high number (default is 1500).

The fourth option screen allows you enter options pertaining to
the the triple lists.  You can enter the number you want printed
(zero means no report will be generated) and the file name to
which the report will be written.  This screen also sets you
select the three categories to be used in each of three triple
lists.  For each triple list you can select any three of the
categories listed above ("calls" through "security violators",
"newest users", "best users", and "BBS losers").  You can put the
three in any order.  The option screen will show a line with
three boxes with the name of one of the categories in each box
for each triple list.  With the cursor on a box, press the "+"
key or the "-" key to change the selection.

Note:  The program builds its data file from your current
activity log (see "EXECUTION" for more details).  It reads all of
the call records in activity log to initialize its data file.  If
you have old copies of your activity log still available, you can
include that information in the data file too by taking the
following steps:

  1) Make a copy of your current activity log.

  2) Make a copy of Top40.SIZ if it exists.

  3) Repeat for each old activity log you have:

      A. Delete Top40.SIZ if it exists.

      B. Copy your old activity log to "ACTIVITY.LOG" (in the
         proper directory).

      C. Run Top40.  (It will add the data in the log.)

  4) Restore your original activity log.

  5) Restore the original Top40.SIZ if it existed,
     otherwise delete Top40.SIZ.

This is an example of the file Top40.OPT that is generated by the
installation program and read by the programs.  This is the new
format for version 2.3.

2.3                          | Version number
Board Name                   | BBS name
\DATA\                       | Path to activity log
\WC\                         | Path to output files
\WC\                         | Path to BBS user data file
ASC                          | Extension for ASCII output files
SCR                          | Extension for ANSI output files
N                            | Count down to #1 (Y/N)
  1 11 12 15 10 14 13        | ANSI color codes
Top40CAL N 2   30      1     |{These lines are parameters for the
Top40MES N 2   30      3     |{single-item bulletins.  See the
Top40UPL N 2   30     20     |{description below for detailed
Top40DNL N 2   30     -5     |{information.
Top40DOR N 2   30      2     |
Top40DRP N 2   30     -2     |
Top40SEC N 2   30     -4     |
Top40NEW N 2   30      0     |
Top40TOP N 2   30      0     |
Top40BOT N 2   30      0     |
Top40ALL N 2 1000      0     |
Top40TR1 15  7  2  3         |{These lines are parameters for the
Top40TR2 15  1  4  8         |{triple lists.  See descriptions
Top40TR3 15  5  6  9         |{below for detailed information.
ACTLOG1                      | Name of PowrBBS activity log
USERINFO.DAT                 | Name of the user data file

The lines of the file are:

Version number of installation program

Board Name

Path for the activity log (if not in current directory)

Path for ASCII output (if not in current directory)

Path for user data file (if not in current directory)

A line giving the extension of the ASCII output screens.

A line giving the extension of the ANSI output screens, if they
are to be generated.  If this is blank the ANSI versions of the
bulletins will not be generated.  For PowrBBS this should be "C"
if ANSI bulletins are desired.  Also in PowrBBS, the extensions
are not appended.

A line giving "Y" or "N" - Y indicates count lists down to #1.

A line containing 7 numbers between 0 and 15 that give the
numbers of the colors of the background, frame, heading, integer,
legend, name, and value, respectively.  The color numbers are:

         #  Color          #  Color

         0  Black          8  Dark gray
         1  Blue           9  Light blue
         2  Green         10  Light green
         3  Cyan          11  Light cyan
         4  Red           12  Light red
         5  Magenta       13  Light magenta
         6  Brown         14  Yellow
         7  Light gray    15  White

Note that these colors are the standard DOS color numbers - NOT
the ANSI color codes.

Eleven lines of the form (one for each report)

"Filename  Down columns(Y/N)  Columns   Number   Points"

for calls, messages, uploads, downloads, doors, carrier drops,
security violations, newest users, best users, BBS losers, all
users.  (The value for "points" doesn't matter for newest, top,
bottom, and all users.)

Three lines of the form (one for each triple list)

"Filename    #   cat. 1, cat. 2, cat. 3;

where 0 = calls, 1 = messages, ..., 9 = worst users.

---- END OF OPTION FILE ----

The Down columns Y/N must be in column 10.  The numbers must be
delimited by at least one blank from anything else.

If the path names are blank the program looks for the activity
log (ACTIVITY.LOG for Wildcat, or the sysop supplied name for the
PowrBBS version) and user data file (USERFILE.DAT for Wildcat,
USERS for PowrBBS) in the current directory and writes the data
files to the directory specified in the output path.


EDITING USER DATA:

The installation program will also let you edit user data.
Standard editing keys work here.  You can use this to add user
data, change data, or print a list of users.

You can use the "Add users" to set up the database if you want
to.  Note that there is no error checking to make sure that the
record number or name is not the same as one already in the data
file. Recall that Top40 will automatically compile all data that
is in the activity log.

Note: the "Add users" option described above has been disabled
since it is not of much use.  The program automatically adds all
users it finds in the activity log.  Future versions will have
the option of reading the Wildcat user data file to include all
users - even if they aren't in the activity log.  Please let me
know if you need the manual "add users" option back.

You can use the "Edit user" function to change data on a user.
You can change any of his statistic fields.  For instance, you
may decide to not credit the user for one upload.  You also
specify whether or not this user is to be included in the output
lists.  If he is not included his statistics will still be
tabulated - they just are ignored on the lists.

The "Edit user" give you a pick list to choose the desired user.
Once a user has been selected in the "Edit user" function you can
use <PageUp> and <PageDown> to scroll through the user records.


PURGE DELETED USERS FROM THE TOP40 DATA FILE:

Top40 keeps its own data file (Top40.DAT).  If you delete users
from the Wildcat user data file they are not automatically
deleted from Top40's data file.  If you run WCRepair after
deleting users from the Wildcat user data file, you can then
update Top40's data file by running the "Purge deleted users"
option in the installation program (Top40I).


EXECUTION:

Once the program is installed, the BBS can either call the
program Top40 after the completion of each call or as an event.
If it is run as an event it must be run before any process that
deletes or purges the activity log.  Top40 reads the new call
records from the file activity log, updates its own data file
(Top40.DAT), and generates ASCII files with the top user lists.

If the file Top40.DAT does not exist (it shouldn't initially)
then Top40 will build it.  It will read the entire activity log
and create and build Top40.DAT, including all of the information
in the activity log.  If you ever want to zero out the statistics
simply delete the file Top40.DAT.

WILDCAT should call the program Top40 after each call or as an
event.  The data files it needs (other than the activity log and
the user data file) are expected to be in the current directory,
so it is best to make the directory with Top40 (and its data
files) the current directory before running it.  The program
requires 96K of available memory in order to work.  This program
reads the activity log and builds the files it needs.

Note that Top40 currently gets all of its information from the
activity log.  It initially builds its data file from the entire
log, thereafter it gets the new caller records from the activity
log and updates those user's records.  It is best to initialize
the data file with the most complete set of activity logs you can
get.  Your lists may not have many stats until you get enough
calls.  Also, an old user who is not in the activity log when the
data file is built will be considered a new user the next time he
calls.

One registered user uses Top40 to award a prize for the best user
each month, then start the statistics over at the beginning of
the next month.  This is easily accomplished by deleting the
following files at the end of the month: the activity log,
Top40.DAT, and Top40.SIZ.  This will cause Top40 to start the
data file over from scratch.  (It is important to purge Top40.SIZ
only if Top40 is run as an event instead of after each call.  See
"Purging the activity log and running Top40 as an event.)


LIMITATIONS, ETC:

The program is currently limited to 1500 active users.  Note that
the program will work with over 1500 users, but the statistics
will be compiled for only the first 1500 active users found in
the activity log.  Generally your oldest users are the most
faithful and have called the most number of times, so that limit
shouldn't be a major problem.  We are planning a future version
that will allow for as many users as the BBS allows.

Each user can have up to 65,535 instances of each of the
categories ("calls" through "security violations") recorded.  The
points calculated for a user can be from -2 billion to +2
billion, but if it exceeds 100 million or is less than -10
million then the bulletin will not print properly (number field
will overflow).  Therefore the weights should be reasonably small
numbers.  The sum of the positive weights should be less than
1,526 (99,999,999 / 65,535 = 1,525.9).  Similarly, the sum of the
negative weights should be greater than -153 (less than 153 in
absolute value.)

You can set a number up to 65,535 for the number of users to
appear on a given list.  If there are fewer users, only the
actual number of users will appear.  For instance, if you have
400 users, if you set the number of users to appear on a list at
1,000, for example, only 400 users will appear on the list - you
will not get 600 "zeros".  This is a way to list everyone's
standings.

If a caller never enters the correct password the call is *not*
counted (i.e. it doesn't count as a security violation or
abnormal disconnect).  The reason is that the caller was probably
not who he said he was.

For the three-column list format - the user's name will be
abbreviated by the program if it is too long.  It will be given
as a first initial and last name (not truncated) unless the last
name is extremely long.

Top40 takes on the order of 6 to 8 seconds to read, compile the
data, update the data file, and write all of the ASCII bulletins
on a 8 MHz AT with a 28ms hard disk, without disk caching
software (no ANSI bulletins).  About 3/4s of this time is
consumed by writing all of the ASCII file bulletins to disk, and
there isn't much we can do to speed that up.  So don't have it to
generate bulletins you aren't going to use if you want to save a
little time.  Incidentally, even though the program reads the
activity log - once the program has been installed and run once,
the running time of Top40 does *not* increase as the activity log
gets large.

Top40 currently limits the maximum number of "newest users"
listed to 40.

PwrTop40 currently works on node 1 only!  A multi-node version
will be forthcoming if there is demand for it.


USE OF WCTop40 WITH S-PRO!:

If you are running S-PRO! with the 'kill activity log' option on,
please note that Top40 will only list those calls it finds in the
actual activity log.  If you use Top40 you will find that only
those calls will be used and no previous history will be listed.
I am trying to get the information needed to allow Top40 to
initialize with S-PRO!'s .HST file.


PURGING THE ACTIVITY LOG AND RUNNING TOP40 AS AN EVENT:

There is one extra thing you (or a batch file) should do if you
run Top40 as an event.  Each time the activity log is purged you
should delete the file Top40.SIZ.

The reason for deleting Top40.SIZ when the activity log is purged
is as follows:  When the program Top40 runs it stores the current
size of the activity log in the file Top40.SIZ.  This tells the
program where to start reading in the activity log next time it
is run.  If the file Top40.SIZ is missing or the number in the
file is larger than the actual size of the activity log file the
program will read and compile all of the activity log.  Otherwise
it will start reading at that byte in the activity log.  Deleting
Top40.SIZ when the activity log is purged will eliminate what
would otherwise be an unlikely but potential problem if the
activity log was deleted and then build up to an even larger size
between two runs of Top40.

If you are using version 1.3, 1.4x, or 1.5x, then the conversion
program will generate the file Top40.SIZ based on the current
activity log when you convert the data file.


ERRORS:

If Top40 is unable to find the activity log or other needed file
then it will write an error message to the screen (with a beep)
and also write the error message to a file "Top40.ERR".


HOW BUGS CREEP INTO PROGRAMS:

This section is meant to be an apology of and an explanation of
how bugs creeped into this program, and a view of what goes on
behind the scenes.  Sometimes a program feature that used to work
doesn't work anymore.  This section gives a human view of the
program development and debugging process.

One such bug caused Top40 (versions before 2.1) to not work with
Wildcat version 2.15.  All of the record numbers were being
listed as zero.  We did not have Wildcat version 2.15 yet, and
registered user Don Bill sent me a sample of his activity log
under Wildcat 2.15 along with a listing of his users (from the
Top40 installation program).  (Thanks Don.)  The problem was that
versions of Wildcat prior to version 2.15 listed "Record number:"
as the second line of the calling record in the activity log.
Top40 scanned for those words and then read the next few
characters to get the record number.  Top40 was using the record
number to match up calling records with records in its database.
In Wildcat version 2.15 the wording was changed from "Record
number:" to simply "Record:" so Top40 couldn't find the phrase
for which it was searching.  A human can look at printouts of the
two types of activity logs for several minutes without noticing
the difference.  But a dumb computer program is different.

Another bug that several users encountered is that the Top40 data
base would be corrupted when Top40 was run after a user was
deleted, and WCRepair was run.  The problem is that WCRepair
removes deleted users from the list and moves up the other users
to fill the space - meaning that the user's record number
changes.  Top40 was assuming that the record number never
changed, so when it found that the record number and name found
in the activity log didn't match with the name of that record
number in its data base it believed that it was a new name.  This
meant that callers after WCRepair was run would be listed under
their old and new record numbers, and previous data associated
with the record number would be lost.

Version 2.1 was to correct this problem.  Several reasonable
approaches were considered.  One was to use the record number
read from the activity log as a starting place to look for the
name.  For instance, if record number 100 - John Doe was read in
from the activity log the program would first look in its
database to see if record number 100 was "John Doe".  If it was
then everything is OK.  Otherwise it would know that the record
numbers had been changed, so it would start looking at 101, then
102, etc for John Doe.  But this is a messy, unnecessarily
complicated process.  Sysop Soren Fried suggested using the name
only.  The record numbers really were used only to match up the
records, so they can be ignored.

So version 2.1 used the user names instead of record numbers.
(It still attempted to read the record number, however.)  This
version left the names already in the data file in the same
order, and it would add new users at the end.  This was working,
except for the fact that it was still reading and updating the
record numbers, and under Wildcat version 2.15 it couldn't find
the record numbers, so they all would get record number 0 (and be
listed as "invalid record number" on the screen when the program
runs).

One drawback, however, is that it takes a program much longer to
compare strings (such as names) than to compare numbers.  I
estimated that a board with 1000 users with 100 calls per day
running Top40 as a daily event on a 10 MHz XT would see roughly a
10 second increase in update time.  I thought that this might be
objectionable, so I considered faster methods.  One method is to
keep the records sorted alphabetically and using binary search on
the names, which will find any name very quickly.

Although the method given above is a very reasonable approach, I
decided on something different for this application.  I made a
study of users of our board, and I found that less than 6% of the
users accounted for more than 50% of the calls!  So I decided to
sort the users according to the number of calls, with the most
frequent caller first.  That way, most callers will be found in
the database very quickly.  This approach has a couple of other
advantages too.  When a new user calls he is simply added to the
end of the list.  If the records were sorted alphabetically by
name a new user would have to be inserted into the middle of the
list, which would require moving a lot of records to make room.
The records are easily maintained in order of the number of calls
by moving up a record if this call gives him more calls than the
one above him on the list.  The other advantage of this method is
that the program compiles the top user lists by reading though
the database inserting users if they should appear on the list.
The quicker it finds the top 40 (or whatever) the less shuffling
of users on the list there will be.  For instance, under this
method the top callers will be immediately found, since they are
all at the first of the list.  Since the most frequent callers
are likely to be ones with a large number of messages, uploads,
etc, these lists can be compiled quickly too.

I implemented this sorting method in version 2.11 - or so I
thought!  Unfortunately, for the sorting routine I simply copied
a sorting routine I already had into this program.  Like most
sorting routines, this one was written to sort in ascending
order, whereas I really wanted to sort in descending order of the
number of calls.  I failed to make this change in the routine,
and I didn't discover the error until after a couple of minor
releases.

This method of sorting user records in descending order of the
number of calls should work well for our application, but it
introduced another bug, which was discovered by sysop Cam DeBuck.
The list of "newest users" was not right.  The reason is that
older versions of Top40 found the newest users simply by looking
at the end of the database, since new users are given the highest
record number and added to the end of the list.  If the records
in the database are not sorted by record number then this won't
be true, and I failed to think of it.  (It is difficult to think
of all of the implications that such a change can cause in a
program.)  That means either going back to the old order of the
database, or getting the newest users by some other method.
Top40 now reads the Wildcat user data file to get the list of
"newest users".  This has the advantage of working even when
Top40's data file has been deleted.


REMEMBER:

If the file "Top40.DAT" is missing then the program will compile
all of the calls in the activity log otherwise it will add only
the new calls.  This is useful for setting up the program.

Top40 requires an intact activity log to create the full user's
history.  Otherwise the bulletins will only reflect what a user
has done since the earliest date in the activity log.

If you want to use this utility, then the author asked that you
register your copy.  The registration cost $20 and entitles you
to future upgrades and support through the following bulletin
board:

                      Bad Lands (QuickBBS)
                  300/1200/2400/9600 HST 8,N,1.
                        Sysop: Andy Smith
                         [phone]

The latest version of Top40 should always be available on this
board.

If you like this program you may like my other WILDCAT! BBS
utilities - WCFields and WC-B-Day:

WCFields checks user data fields for possible duplicate users.
It looks for duplicate phone numbers, duplicate birthdays, same
or *similar* passwords, and same or *similar* names.

WC-B-Day generates bulletins listing users with birthdays this
week or month.  This should be popular with the users.


TOP40 VERSIONS:

  Alpha- 1-5-90.  Alpha test version.


  Beta - 1-6-90.  Beta test on Land of Confusion BBS.


  1.0  - 1-7-90.  Test version.


  1.1  - 1-8-90.  Test version.


  1.2  - 1-9-90.  Test version.


  1.3  - 1-10-90.  Initial released version.


  1.4  - Added "newest users" list.

         Miscellaneous changes.

         Options file format change.


  1.5  - Added "all users" list.

         Miscellaneous changes.

         Options file format change.


  1.51 - Redefined "top users", misc. changes (unreleased).


  1.52 - Fixed a bug crediting new users with an extra call.

         Change report format to allow for > 999 users.


  1.53 - 1-20-90

         No longer writes disk files if no change (excluded user
         or login failure, etc).

         Make sure excluded users do not appear on lists.
         Previously if a user gathers statistics and then is
         excluded his old stats would continue to appear on
         lists.


  2.0  - 1-25-90 (limited release)

         Can run as an event or after each call.

         More efficient reading of the activity log.

         Full editing of user data.

         Ability to include or exclude each user.

         Option of two or three column format.

         Option of going down columns instead of across.

         Options file format change.

         Data file format change.
         (A reserved byte now used to indicate inclusion).


  2.01 - 1-27-90

         Checks to make sure printer is on before print list.

         New users default to "include" (caused blank lines).


  2.02 - 1-30-90

         Adding new users allows entry of the name and record #.


  2.03 - 1-31-90

         Make all four option screens accessible from the menu.


  2.04 - 2-2-90

         Raise limit from 1000 to 1500 active users.


  2.1  - 4-8-90 (limited release)

         Support for Wildcat 2.15.

         Added ANSI screen option.

         Added countdown to #1 option.

         Fixed the bug caused when WCRepair deletes a user.

         Options file format change.


  2.11 - 4-9-90 (limited release)

         Fixed bug where long path & file names are truncated.

         Ignore record numbers in activity log.

         Faster updating of Top40's data file.

         Faster compilation of information for lists.

         Faster writing of triple lists to disk.

         Pick users alphabetically.

         Eliminate "add users" in installation program.
         Is it needed?


  2.12 - 4-10-90 (limited release)

         Added error message file.


  2.13 - 4-10-90 (limited release)

         Fixed sorting error for faster updating of data.


  2.14 - 4-16-90

         Fixed bug in "newest user" list that was introduced in
         version 2.1.

         Fixed bug where 2-column across was listing downward.


  2.2 - 5-17-90

         Fixed bug with storing a changed background color in the
         ANSI screens.

         The "Delete users" function in the installation program
         was replaced by "Purge deleted users" which will delete
         all users that have been deleted from the Wildcat user
         database (after WCRepair has been run).

         Add path to USERFILE.DAT.


  2.3 ALPHA - 6-2-90

         Added extension option for ASCII files.

         Option file format change.

         WCT40C23 - conversion from version 2.1x & 2.2 to 2.3.

         Alpha release for testing on PowrBBS.


  2.3 BETA - 6-3-90

        Release of version 2.3 BETA.


  2.3 GAMMA - 6-4-90

        Changes for PowrBBS bulletin files:
          no extension
          append "C" for ANSI color screens


  2.3  - 6-5-90 (Limited release)

       Allow PowrBBS sysops to enter the activity log file name.


  2.31 - 6-12-90 (limited release)

       Fixed bug with activity path and file name.


  2.32 - 6-12-90 (limited release)

       Fixed bug with ANSI file names in PowrBBS version.

       More descriptive error message and file.


  2.33 - 6-12-90

       Fixed bug in PowrBBS version with renaming activity log.

  2.34 - date unknown

       Smaller EXE files.


  2.4 - 11-22-90

       Faster reading and writing of disk files.


  2.5 - 2-6-91

       Fixed bug in Wildcat installation program
       Added option of user data file name.


  2.6 alpha - 4-14-91

      Alpha test of QuickBBS version.


  2.6 - 4-16-91

      QuickBBS version released.


PLANNED ENHANCEMENTS IN FUTURE VERSIONS:

  Unlimited number of users.

  Faster updating of records.

  Pick users alphabetically by last name.

  More list categories:
    Most recent callers
    Total time connected
    Total kilobytes uploaded
    Total kilobytes downloaded


ACKNOWLEDGMENTS:

Thanks to the users who sent in suggestions and the users who
have registered the program.  In particular, thanks to Bob Lias,
Cam DeBuck, and Don (I forgot the last name).

Thanks to Guy Tyson for suggesting the program, being an alpha
and beta tester, for putting up with half a dozen different test
versions (often with file formats incompatible with previous
versions), for finding a few bugs, for publicizing the program,
and for letting the "Land of Confusion" be the home board for
Top40.  (JM)

Thanks to the Andy Smith, sysop of the Bad Lands BBS for being
the test board and home board for the PowrBBS and QuickBBS
versions of Top40, and the support board for the Wildcat version.

WILDCAT! BBS is by Mustang Software.

PowrBBS is by Russell Frey.

QuickBBS is by S. Gabrilowitz and R. Creighton.

This program was written in Turbo Pascal 5.5 from Borland
International.  The Turbo Professional 5.0 package by Turbo Power
software provided routines for screen editing in the setup
program, as well as a few other useful functions.  The EXE files
were compressed using PKLITE Professional from PK Software.


Program by: Jud McCranie

Documentation by: Jud McCranie and Guy Tyson