Falcon CBCS Top Users V2.0b ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ (c) David Dustin 10 August, 1992 Preface ~~~~~~~ The programs and files in this distribution are freely distributable, but are also Copyright (c) David Dustin. They may be freely distributed as long as no more than a minimum fee is charged to cover time and copying costs. It may not altered or in anyway backward engineered. Permission is given for this distribution archive to be placed into Public-Domain collections such as the Amiga Library run by Fred Fish. If you do decide to make use of Top Users, you are suggested to send any form of donation or gift as payment. This will get you the latest version of Top Users, and also any other programs I have released. Written in 100% pure assembly using Devpac 3.02. The source code, and whatever information I have found out about the Falcon User.BBS datafile is available from me if you decide to register Top Users. If you do have any suggestions, bug notes or ideas about this program, or if you would like to donate something, please let me know. Write to me at the following address: David Dustin 30 Richmond Ave Palmerston North NEW ZEALAND Or I can be contacted via: INFA 3:771/425 Contents ~~~~~~~~ 1. An introduction 2. Usage 3. History 4. Credits / Copyrights 1. An Introduction ~~~~~~~~~~~~~~~~~~ This program was written because there was no easy way for me to get information about who had made the most use of my BBS, without having to write everything down on paper from within Falcon. Top Users was also my first major play with making use of the functions of ReqTools by Nico François. The only trouble is that I got a bit carried away, and now EVERYTHING in Top Users now makes use of ReqTools requestors (from file selection, through to displaying the data) I know that Top Users is a bit of a silly name, but I was hard pressed to think of anything else that fitted, while still describing what it does. Top Users works on both Kickstart/Workbench 1.3 and 2.x, and can be used from the CLI/Shell or via Workbench, but REQUIRES the ReqTools.library by Nico François. As of version 1.01, Top Users now requires ReqTools 2.0+ (V38), and will NOT work with earlier versions of this library (sorry). 2. Usage ~~~~~~~~~ Top Users can be either used from the CLI, or from Workbench. - First of all via the CLI: Usage of this program is as follows: TopUsers The arguments are optional and are designed so that you can modifiy settings and operation of Top Users as you want. A full description of all of the settings available is listed later in this document. - Via the Workbench Top Users can be used from Workbench by making use of ToolTypes in it's Icon. The available ToolTypes are the same as the settings used from the CLI and also from the config file. These are explained further down this document. Once you have started the program, and unless you have already selected the option that you want via the command line (explained later), you will be prompted to choose which set of information you would like. The six options are: Callers - Top callers to the BBS since it's Birthday Messages - Users that have posted messages to the system (EMail and Public) Downloaded - The users that have downloaded the most KiloBytes from your system. Useful for knowing if users are just using your system as a source of new programs. Uploaded - Those lovely people that out of the kindness of their hearts have decided that you were missing some files from yours system, and spent their time sending them to you. About - Simply gives you some information about me and where to send your registration fee for the program :-) Quit - Quits out of the program without asking "Are you Sure??" All of the options that appear from now on, are changeable via Command Line, ToolTypes or by using the config file. For ease, I will explain each function as if you had not modified it via one of the aforementioned methods. I will explain how to change these options later on. After you have chosen the information that you want to see, a file requestor to select the data file to scan for the data from. Just goto the directory contining the datafile, and select the file to view. Be warned that I do NO checking to see if the file is a correct UserBase file (there are no Identifying marks in the file), also if you do not select as file (by hitting Cancel, or having no filename when exiting), then Top Users will just quit out cleanly. Now you get to choose how many entries you want in the list. You can have between 2 and 10 users listed. 10 is the defualt, but 5 seems to be the most popular size. Next comes the choice of where you want to output the Top Users list to. You have three choices and one option to cancel. Printer - This will copy the data to your printer via the PRT: device for most compatibility. File - You will be presented with a file requestor asking where you want the data to be saved out to. The data will be saved as a pure ASCII text file. If there is an error in trying to open the save file, or if you cancel or do not provide a valid name, then the information will be output to the screen (nothing will be saved). Screen - This will open out a big requestor with the data in it. when you have had enough of looking at the results, then just hit the Continue gadget. If you select the Output to File option, and you select a file that already exists, you will be asked what you want to do about it. You can: OverWrite - This will erase the file and write the information in it's place. There is NO way of recovering a file that has been overwritten. Join - This will add the new information onto the end of the file that is already there. Choose Again- This will take you back to the file requestor to select a new filename. Cancel - This aborts the output to file, and will just display the information out to the screen. An option that was suggested to me was the to hide a user if you don't want them listed. The most common use for this would be to hide the SysOp from the list, as logicaly they should have done more on the system than most other users. You will be presented with a string requestor asking for the name to hide (must be spelt correctly, but is Case-INsensitive). If you don't enter anything, or hit the cancel option, then ALL users will be included into the sort. The name entered here is buffered, so that if you use Top Users more than once in one sitting, then it will already be in the requestor, so can be selected by simply hitting Return. Once you have finished looking at the data, or once it is finished saving/printing, you will be presented with a requestor asking if you want to use Top Users again. Defualt is No, but if you do decide to run Top Users again, the first requestor (the one to select the data to view), will be brought back up. Because you would logically want to use the same User.BBS database file, I have buffered the data file so that it will not need to be loaded again. If you want to use a different User.BBS file, you will need to re-load Top Users again. As of version 2.0, all of the options above can now be pre-set so as to reduce the time needed when making use of Top Users. The options are listed here, and a description follows each on what the different settings are. Don't forget to include the = signs between the option, and it's settings, and make sure that you spell things correctly when typing. USERBASE= Here is where you can provide name full path and name of the Userbase file to load and use. If you provide a filename which doesn't exist, you will be warned, and you will have to re-run Top Users with a different setting ENTRIES= The number 'x' is the number of entries that you want displayed. If you do not have anything here, or you use a number greater than 10, or less than 2, then the defualt of 10 will be used. ENTRIESREQUEST=/ This option toggles whether the above requestor (number of entries) is displayed. The defualt is yes. If you do hide the requestor, but do not provide it with an amount as above, then the defualt of 10 will be used. OUTPUT=// Selecting one of these options chooses where the data obtained is output to. If you use Printer, make sure that you have paper in printer, and that it is online. If you choose File, then you might be asked to select a filename unless you have taken care of that here as well. If this option is not or incorrectly used, then you will be asked when you actually run Top Users. SAVENAME= If you put a name and path of a file here, and if you select output to file (either from these settings or from withen the program), then this is where/what your data file will be saved as. If an incorrect path or a file which cannot be generated is selected, then you will be presented with an error message, but the data will still be output to the screen. SAVEREQUEST=/ If you have this option set to No, then you will not be faced with the Save requestor. You can only hide the requestor if you have already provided a Savename. The defualt is Yes (bring up requestor). SAVEOPTS=/ You have two options here. You can either Join the current data onto the selected file, or you can overwrite the file with the new data. If the file selected does not exist, then these options will be ignored until you try to modify a file that does exist. HIDEUSER= If you provide a username here, then this name will be exluded from the list of users when the TopUsers data is calculated. Be sure to spell the name correctly. HIDEREQUEST=/ This option allows you to hide the requestor asking about the name of the user you want hidden. If you select this option, but do not have a name already entered to be hidden, then all users will be included into the calculations. Defualt is Yes. AGAIN=/ This is the final option that you can select. This option allows you to choose whether Top Users will loop and let you have a go a generating more information. The defualt is No. If you leave this option out of your configuration/commandline/tooltypes, then a requestor will be brought up when you reach the correct point. If you do select the Yes option, then the only way to quit out is to choose the quit option from the main selection requestor. There is one last option, and this is designed to allow you to make use of Top Users from within a script or the like. It can ONLY be used from Command line, and allows you to select what data that you want to be output. The purpose of this is so that you should set up all of the various settings into a configuration file, then simply call Top Users with the approprate option, and everything will be done very quickly, and silently (unless you have an option set to bring up a requestor). The setting is: SELECT=/// The four options relate to the equivlent gadgets in the main screen. Because it would be quite easy to put Top Users into an infinate loop by selecting this option, and having Again set to Yes, thus causing the program to loop back onto itself, the Again option is disabled if you use the SELECT option. To use these options via the CLI, you would simply enter each option that you want, one after the other with a space in between each entry. Don't forget that if an entry needs a space in it, then you must enclose the option withen quotes (don't forget to put the closing quote after the data) TopUsers USERBASE=BBS:User.bbs ENTRIES=5 HIDEUSER="Joe Bloggs" To enter the options using the tooltypes in the icon, simply enter each option on it's own line using your normal method of changing an icons tooltypes. If an option requires a space in it's data, the quotes are NOT needed (in fact, if you include them, then things probably won't work correctly :-) Thus, the ToolTypes that you would enter in the icon to achieve the same result as above, would be: USERBASE=BBS:User.bbs ENTRIES=5 HIDEUSER=Joe Bloggs The most popular option is to make use of a configuration file. This allows you to have TopUsers set to your favourite settings, and then just change the details as necessary. The file is called: TopUsers.Cfg and should be placed in your S: directory. Nowhere else is supported. This file is a standard AscII text file, with each option on it's own line, terminated by a single return. As with the ToolTypes, no Quotes are needed for options needing a space. 3. History ~~~~~~~~~~~ V1.0 27 July 1992 * First release. V1.01 28 July 1992 * Added "Use Again" option, with buffering of User.BBS datafile * Added check to see if output file exists, and if it does, offers several options * Included option to hide a specific user from TopUsers sorting * Tidied up code, and fixed a few small errors V1.02 31 July 1992 * Fixed a serious bug with the path names. If you tried to use a sub- directory, then the name of the directroy would be added to the filename instead of putting it into the directory * Added "Variable Entries" option, to allow you to choose how many entries to have in the TopUser lists * Added support for UnderScored gadgets. Just press the letter that is underlined to activate the gadget V1.02b 31 July 1992 (when I woke up again) * Fixed a bug with the output options. If you outputted to File or printer, then used again and tried to output to screen, nothing would appear (sometimes it would crash) * Improved Save routine, so it remembers the name of the file that you last saved the data as (also reduced memory needed for a save) * Corrected several bugs with the ErrorChecking (mainly file handling) * Removed several routines that were not being called but were present V1.02c 2 August 1992 * There was an error if no path name was supplied, then the file would not be saved correctly * Because of a typo, the join function did not work unless the file to be joined to had been created in the current usage of Top Users * Fixed a potentialy fatal error if used in low memory situations V2.0 9 August 1992 * Major update & Bug fix * Configuation file support added * All options are now controlable via ToolType/CommandLine * Made it possible to use Top Users from withen a script * All options speed up and cleaned up * Internal changes make Top Users more stable and compatible with different machines/configurations V2.0b 10 August 1992 * Corrected error with filesave/printout when used more than once * Added date/time of data creation to file/print outputs * Replaced several redundent routines * Improved data managment * Fixed several errors created with the inclusion of the config file - Wouldn't accept the settings if you tried to change something already set in the config file - Option strings weren't being copied correctly from Icon ToolTypes - I had a spelling mistake in one of the settings keywords :-( - Was calling wrong routine when checking settings on some settings 28-Jan-1996 Released into the public domain by the author Dave Dustin 4. Credits / Copyrights ~~~~~~~~~~~~~~~~~~~~~~~~ Main code - David Dustin Icon - Karl Mottram Ideas/Bug testing - Renze de Ruiter Paul Dunlop Karl Mottram Top Users - (c) 1992 David Dustin Falcon CBCS - (c) 1988-91 Brian Fehdrau Devpac 3.02 - (c) 1991 HiSoft Kickstart/Workbench - (c) 1985-91 Commodore-Amiga, Inc. ReqTools - (c) 1991-92 Nico François