Black Box 4

home *** CD-ROM | disk | FTP | other *** search

/ Black Box 4 / BlackBox.cdr / bbs_opus / uds200.arj / UDS200.DOC < prev next >

Wrap

Text File | 1991-04-26 | 23.0 KB | 492 lines

UDS: The User Description System Version 2.00f for Fido* Copyright (c) 1991 by Lester B. Kooyman (1:204/501.0) for Caffeine-Free Software (Portions copyright by Allan P. Hurst) Documentation by PC Bear Documentation (c) 1991 Caffeine-Free Software (*Fido, FidoNet, and the dog-with-diskette are trademarks of Tom Jennings and Fido Software, without whom none of this would be possible. Thanks, TJ! I would also like to thank Bob Hartman and Vince Perriello for writing BinkleyTerm and making it available. Tip o' the hat also to Ray Gwinn for his excellent X00 FOSSIL driver. Also thanks to Wynn Wagner III, who originated Opus, and set the groundwork upon which BinkleyTerm and other programs have been built. Without the work of these fine people [and others I have inadvertently forgotten to mention], the FidoNet software environment would not be what it is today - a sophisticated and cheap BBS and email standard for the world. Also many thanks to Yoshi for writing LHARC!) (Intel is probably still claiming trademark on the names of their CPU processor family. At this writing, the name "386" has been held in a court of law to not be a trademark. Personally, I recommend purchasing processors from any vendor *other than Intel* and thus helping to break the monopolistic stranglehold Intel has on the PC industry. AMD makes excellent processors, for example. Harris and others manufacture versions of the 286, and AMD has just introduced versions of the 386. Even an IBM version of an Intel processor will help to break the monopoly, but probably doesn't send the message that purchasing an AMD product does. Vote with your dollars! Down with monopolies! Up with competition! This has been a paid political announcement.) =============================================================================== 0. Packing List --------------- The archive UDS200.LZH should contain the following files: READ.ME (a very small plea) UDS.286 UDS.EXE UDSMAINT.286 UDSMAINT.EXE UDSUPDT.286 UDSUPDT.EXE UDS200.DOC (this file) The versions of the programs ending in ".EXE" are generic and should run on all 8088, 8086, 80186, 80286, 80386 or 80486 systems. It should run on the 80786 when Intel gets there. This assumes Intel continues to maintain object-code compatibility in the 80X86 processor family, a safe bet. The versions of the programs ending in ".286" have been compiled with an option to optimize for the 80286 and higher processors. Machine instructions specific to the 286 have been used. These versions of the programs will *not* run on the 8088, 8086 or 80186 processors, but should provide somewhat better performance on 80286 and higher processors (this includes the 386). Users of 286, 386, or 486 CPUs should erase the versions ending in ".EXE" and rename the versions ending in ".286" to replace them. Keep your original archive for backup! =============================================================================== 1. What it is, etc., other introductory drivel. ----------------------------------------------- The User Description System (hereafter referred to as "UDS" or "the UDS" but never as "Mr. UDS to you") is designed to add a user description database to the Fido BBS system. The UDS runs as an outside program from Fido. To run the UDS, you should be running the FOSSIL version of Fido. Although the UDS has only been tested with Ray Gwinn's fine X00 software, it uses general FOSSIL calls and should work with other FOSSIL drivers such as BNU and OPUSCOMM. While I cannot promise I will be able to respond to support queries with drivers other than X00, if you netmail me the FOSSIL you are using (along with its documentation) and a description of problems you are experiencing, I will investigate to the limits of my time and ability. Transcriptions of error messages or screen prints would be very helpful, along with a description of your hardware and software environment. Priority will be given to problems reported by those who have read and responded to the small plea in READ.ME. The UDS consists of three programs: UDS.EXE, UDSUPDT.EXE, and UDSMAINT.EXE. Their functions are as follows - UDS.EXE: The User Description System itself. Allows users to search and display descriptions of other users as well as create, delete, and modify their own descriptions. UDSUPDT.EXE: A program to update the dates that users last called the BBS, as held in their user description file entries. Should be run no less often than daily. UDSMAINT.EXE: A program to provide two less-frequently-needed functions; to remove duplicate descriptions for users who somehow end up with more than one (this is unlikely at this "advanced" stage of development of the UDS), and to delete the descriptions of users who no longer appear in your CALLER.SYS file. In other words, if you run UDSMAINT after stamping and purging the records of users who have not called your BBS in some time, you will effectively delete them from the UDS as well. =============================================================================== 2. How to run the programs -------------------------- a.) UDS.EXE ----------- This program creates and maintains a file named USERDESC.DAT. The first time a description is entered by a user, UDS will create USERDESC.DAT if it does not exist. The command line to run the UDS is: UDS /# [/REBOOT|/END] {/SHARE /UDSPATH=path /CALLERPATH=path /FIDOPATH=path} where: /# is a FOSSIL port number in the range of 0-7 /REBOOT indicates to terminate with reboot upon carrier loss (controlled by the FOSSIL) /END indicates to simply end the program upon carrier loss, setting the DOS errorlevel prior to exit /SHARE indicates DOS file sharing/record locking support is active and should be used. /UDSPATH=path is the path to be used to open USERDESC.DAT /CALLERPATH=path is the path to be used to open CALLER.SYS /FIDOPATH=path is the path to be used to open FIDO.SYS Parameters between "{" and "}" are optional Parameters between "[" and "]" are mandatory, one and only one must be chosen from the selections separated by "|" The parameters are case-insensitive. "/REBOOT" is the same to the program as "/reboot". /#: -- Note that the FOSSIL port number argument is positional and mandatory (it must be the first argument specified on the command line). The UDS uses the same port numbering scheme as X00. That is, port 0 is the first FOSSIL port, and port 7 is the highest port. Whatever number is used will be passed on to the FOSSIL directly. Fido numbers ports in a slightly different fashion, i.e., from 1 to 8 rather than 0 to 7. For this reason you should use the general rule of thumb that the port specified to the UDS should be one less than the number you specify to Fido. Therefore, in the most common configuration, with Fido using com1, you would specify the port to the UDS as 0. [/REBOOT|/END]: -------------- You must choose one or the other of these parameters. If you choose /reboot, during program initialization the UDS will tell the FOSSIL to reboot your computer if carrier drops. This is mostly for single-line Fido installations. It would not be a good idea when running under DESQview or another multitasker! It also may not function on certain 386 systems with certain BIOSes (it does not work on my new 386). In that case, you should use the /end parameter. When the UDS exits normally back to the batch file that invoked it, the FOSSIL will be told to no longer reboot if carrier drops. The /end parameter tells the UDS to use its own routines to monitor the loss of carrier on the line. In most cases this will be much faster than the /reboot option. The reason it will be faster is that my tests have shown that the UDS's internal carrier-loss-detect routines react nearly as quickly as X00's, and you do not need to wait for your system to reboot. This option is recommended, even for single-line systems. When the UDS exits due to carrier loss, it will set the DOS ERRORLEVEL to 2. If it exits for any other reason, the DOS ERRORLEVEL will be set to 1. The following batch file is an example of this. Note that this batch file may not look exactly like yours, since it is used with my system, where I run BinkleyTerm and Fido. @Echo Off :START D: Cd \FIDO goto loop :RELOGIN relogin :LOOP E:FIDO %1/O /1 1/I if errorlevel 6 goto esp if errorlevel 5 goto exit :ESP uds /0 /end /share /udspath=d:\fido /callerpath=d:\fido /fidopath=d:\fido if errorlevel 2 goto exit goto relogin :EXIT modemoff /0 cd \mail Binkley If carrier drops while the caller is in the UDS, the program will exit with an errorlevel of 2. This batch file will trap that, and branch to the label :EXIT. At that label I run a quick utility to take the modem off-hook, and then return to the main batch file which runs BinkleyTerm, which I call BINKLEY.BAT. Fido had been exited to in the first place with Binkley's BBSBATCH option. If the program exits normally, the DOS ERRORLEVEL will be set to 1, and the batch file branches to label :RELOGIN, where the caller is relogged onto Fido. I downloaded the relogin program from TJ's bbs, but you can find this program on lots of systems. While the /end option senses carrier loss very quickly in my experience, there is at least one case I have noticed where it may take a few seconds to notice that carrier has dropped. I have discovered that with high speed modems (in my case a V32/V42bis 9600bps Practical Peripherals modem) it can take a few extra seconds. /SHARE: ------- This parameter is optional. It is intended for multiline installations. I am running under DESQview, but this should also work if a LAN is in use. If you specify /share, you *must* load the DOS program SHARE.EXE during your system's initialization (probably in your AUTOEXEC.BAT file). Some versions of DOS have sharing support built in. If your version of DOS includes SHARE.EXE on its distribution disks, then you should use it (if you are running a multiline Fido installation). As far as I know, this means that you should use SHARE.EXE with all versions of Microsoft's and IBM's DOS from 3.1 through and including 3.3. This parameter actually causes the UDS to do more than open the USERDESC.DAT file with sharing. When /share is specified, the UDS will do two things: - Lock the USERDESC.DAT file during changes. This includes description additions, changes and deletions by users while online. - Close and reopen USERDESC.DAT whenever a user executes either a search or a list of users' descriptions. There are a couple of consequences of the above. First, no attempt is made in the program to be graceful if SHARE.EXE (or sharing support) has not been loaded. If you start the program with /share, and have not loaded SHARE.EXE, the program will either lock up your computer or exit with an unexpected error level that will probably cause your system to do unexpected things. The other consequence is more pleasant. If two users are online in the UDS, and the caller on line 1 updates his or her description, the user online on line 2 will see the new or changed description the next time he or she executes a search or a list. This makes the UDS database "almost realtime". For those interested in such details, the UDS locks the USERDESC.DAT file on a record basis rather than locking the entire file. In addition, the record that is locked is always the first record in the file. This lock is held only as long as is physically necessary. In other words, all the preparation for writing or deleting the record is done before the lock is obtained, then the file activity takes place, and the record is immediately unlocked. In this way, record 1 of the file serves as a resource serialization semaphore. It is a way of signalling that the file is locked for update in a logical rather than a physical fashion. For this reason, other programs will not necessarily know that the file is logically locked unless they understand this convention. If you write additional programs to manipulate the USERDESC.DAT file, you should be aware of this. /UDSPATH=path: ------------- This is the path where the USERDESC.DAT file lives. It should be specified without a trailing backslash, like so: /udspath=d:\fido It does not need to be the path where Fido is installed. This is an optional parameter. If it is not specified, the UDS will look for the file USERDESC.DAT in the directory which is current when the program UDS.EXE is invoked. Please see the section "a note about path options and multiline" which follows later. /CALLERPATH=path: ---------------- This is the path where CALLER.SYS is located. Like /udspath, it should be specified without a trailing backslash (putting the trailing backslash on any of these path options will cause the program to malfunction). Again, this does not need to be the path where Fido is installed. The default, as in the /udspath option, is to look in the directory which is current when the program UDS.EXE is invoked, if this optional paramter is not specified on the command line. Please see the section "a note about path options and multiline" which follows later. /FIDOPATH=path: -------------- Again, an optional parameter, with the same default logic if not specified. This is the path where FIDO.SYS is located. It does not need to be the same path as /callerpath or /udspath, and will probably not be in multiline installations. Please see the section "a note about path options and multiline" which follows later. A note about path options and Multiline operation: ------------------------------------------------- Although Fido's author has replied that multiline Fido installations may share FIDO.SYS, the UDS has not been tested in such an environment and will probably not work if Fido is configured that way. The only way that the UDS has been tested to work in a multiline Fido configuration is in a configuration like the following: - One copy of USERDESC.DAT, located where you want it. - One copy of CALLER.SYS, located most likely in the directory where your "main" or first copy of Fido is located. - One copy of FIDO.SYS *for each line of Fido you are running* located in the directories dedicated to each Fido line. In other words, if you are running three lines of Fido, you would have: - One copy of USERDESC.DAT, shared by all lines. - One copy of CALLER.SYS, shared by all lines. - Three copies of FIDO.SYS, in three different subdirectories, one for each of the three lines of Fido you are running. In this case, while setting up Fido, you would have run "SET-FIDO" three times, once in each of the subdirectories dedicated to the three individual Fido lines you are running. You would have pointed the second and third copies of Fido to the copy of CALLER.SYS they all share, with the options in FIDO.INI that are meant for this purpose. The reason that this is necessary is that the UDS reads the FIDO.SYS file for its line (as specified in the command-line parameter /fidopath) in order to find the record number of the caller online. The UDS then gets the caller's record from CALLER.SYS. The path in /callerpath is used to find the CALLER.SYS file. Theoretically, you could have a separate copy of CALLER.SYS for each line, as long as you tell Fido (in FIDO.INI for that line) and the UDS (with the /callerpath parameter) about it. In fact, I have run with this type of configuration on my own system for a short time. You might wish to do this, for example, if you provide one free or otherwise unrestricted telephone line to your system, and other lines that have access requirements (such as requiring a caller to be a contributor or member of a club or other organization). =============================================================================== b.) UDSUPDT.EXE --------------- This program updates the "this user last called on" information in the file USERDESC.DAT. It should be run at least once a day so that this information is current. Multiline installations should beware of running this program while multiple lines are active. I run it during my daily maintenance event, when all lines other than my main mailer line are executing wait events. See the READ.ME file included in the UDS200.LZH distribution archive for information on OFFHOOK.LZH, another fine product of Caffeine-Free Software, which helps Fido lines to go offhook during these times while one line executes maintenance-type events. This also means your callers reach a busy signal rather than a ring-no-answer. If you run UDSUPDT.EXE without any command-line parameters, it will display the following: UDSupdt 2.00f (29Mar91)/(c)1991 Lester B. Kooyman for Caffeine-Free Software (Not Coffee-Protected!) Syntax: udsupdt /udspath=xxx /fidopath=yyy OR: udsupdt /current Where: xxx is the path where USERDESC.DAT is found and: yyy is the path where CALLER.SYS is found. Or: /current means use the current subdirectory for both files. The /udspath and /fidopath parameters are specified under the same rules as described for UDS.EXE. Don't include a trailing backslash! If you have USERDESC. DAT and FIDO.SYS installed in the directory which is current when you run UDSUPDT, you can use the shorter argument /current. One of these approaches must be used. =============================================================================== c.) UDSMAINT.EXE ---------------- This program takes no command-line arguments and is unforgiving. It has no error recovery, so be good to it! Its purpose is twofold: one to remove multiple descriptions if a user has more than one (should not occur, happened to me before I got the multiline logic correct), and two to delete description entries for users who are not found in CALLER.SYS or who have descriptions which are blank. CALLER.SYS and USERDESC.DAT must be in the same subdirectory, and this directory must be the current one when the program is invoked. It does not touch your original input file, so it is safe to run. The output is in a file called NEWUDS.DAT. This allows you to have second thoughts. You need to erase (or archive and save) the original USERDESC.DAT and then rename NEWUDS.DAT to USERDESC.DAT for the actions taken by this program to have effect in your UDS installation. =============================================================================== Various things to be aware of. ------------------------------ The program assumes two things to work properly: one, that the caller is calling at 8N1, and two, that the caller is either using VT100 or ANSI-BBS terminal emulation. The only use of ANSI/VT100 control sequences is to clear the screen. Both of these requirements are stated on the opening screen that the caller sees when he or she first enters the UDS. If this proves to be an inconvenient set of assumptions, I may be able to do something about it. I've planned for a while to allow the UDS to pick up the user's terminal type from Fido's CALLER.SYS record, but at this time there are no terminal types defined in the version of Fido that I am running (and that the UDS has been tested with), which is 12r. Another thing to be aware of is that the user description itself is one long string and is written to the caller's terminal that way. If the caller's terminal program does not wrap lines longer than 80 characters on his or her screen, the caller will see the first 79 characters of the description followed by whatever is the last character of the description in column 80, as the characters above 80 will overwrite the last portion of the line. Some terminal programs may give other, less desireable results. You may want to tell your callers to turn on line wrapping in the help file you create for the UDS. If some nice sysop out there will netmail his or her help file to me, I will include it in a future release of the UDS. The UDS attempts to handle the time the caller is online in the UDS correctly. There is at least one known exception, described below. When the caller first enters the UDS, the program checks the maximum times you have defined in FIDO.SYS for callers to be online. This includes both the time allowable per call and total per day. As the user remains in the UDS and time elapses, time is checked on a regular basis (and in more than one location in the code). The caller's time online so far today (as held in FIDO.SYS) is constantly updated, so that the caller can't "beat the system" by dropping carrier and calling back in to the BBS. At the conclusion of the user's online session, the time remaining on this call is given to Fido. This is done only upon successful completion since it doesn't matter under other circumstances. The UDS gives callers time based on their privilege level. Since Fido doesn't store the time per day for each user, it's necessary to get the time per day and multiply it correctly for each user privilege level. The case that UDS doesn't handle correctly is Sysop access. Sysops will have their time set to the maximum user level time rather than unlimited time when they return to the BBS from the UDS. Under most circumstances this will not be a great inconvenience. While the UDS does not test for or handle DESQview in any special way, it does do well-behaved video I/O and should be compatible with all known multitaskers. There are no direct video writes. I hope you and your callers enjoy the UDS as much as I enjoyed writing it. Oh, there is no documentation on the operation of the UDS itself, since it is *supposed* to be self-explanatory. If this is not true, complain and I'll see what I can do about it. Better yet, include a help file or other documentation with your message, and if I use your version I'll be sure to give you credit for writing it (if you don't want to remain anonymous, that is.) =============================================================================== "Caffeine-Free Software: Not Coffee-protected!" ===============================================================================