Beijing Paradise BBS Backup

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

/ Beijing Paradise BBS Backup / PARADISE.ISO / software / BBSDOORW / 2AMDOOR.ZIP / 2AMDOOR.DOC next >

Wrap

Text File | 1989-05-28 | 32.2 KB | 828 lines

2AMDOOR A fast door interface utility for 2AM-BBS Copyright (c) 1989, Dave Maynard Files included in 2AMDOOR.ZIP 2AMDOOR.EXE 2AMDOOR.DOC README.DOC ORDER.DOC RELEASE.DOC 2 Contents 1. INTRODUCTION TO 2AM-BBS JUMP DOORS A. What is a jumpdoor . . . . . . . . . . . . . . . . . 3 B. How to install jumpdoors . . . . . . . . . . . . . . 4 C. Information passed to a jumpdoor by 2AM-BBS. . . . . 5 D. Other Door systems . . . . . . . . . . . . . . . . . 6 2. 2AMDOOR INSTALLATION A. Single port BBS. . . . . . . . . . . . . . . . . . . 7 B. Multi-port BBS . . . . . . . . . . . . . . . . . . . 8 3. 2AMDOOR OPERATION - PRODUCE OUTPUT FILES A. RBBS . . . . . . . . . . . . . . . . . . . . . . . . 11 B. WILDCAT. . . . . . . . . . . . . . . . . . . . . . . 11 C. PCBOARD. . . . . . . . . . . . . . . . . . . . . . . 11 4. 2AMDOOR OPTIONS - HANDLES AND LOG FILES A. Allow use of handles in jumpdoors. . . . . . . . . . 12 B. Maintain a 2AMDOOR log file. . . . . . . . . . . . . 12 5. TROUBLE YOU CAN GET INTO . . . . . . . . . . . . . . . . 13 A. With error messages . . . . . . . . . . . . . . . . 13 B. Without error messages . . . . . . . . . . . . . . . 13 6. EXAMPLES A. Czar wars . . . . . . . . . . . . . . . . . . . . . 15 B. Casino . . . . . . . . . . . . . . . . . . . . . . . 15 C. Bad example! . . . . . . . . . . . . . . . . . . . . 16 7. REGISTRATION AND BACKGROUND A. Technical Support & Registration . . . . . . . . . . 17 B. References . . . . . . . . . . . . . . . . . . . . . 17 3 1A. WHAT IS A JUMPDOOR? A jumpdoor is a program that may be run 'outside' of 2AM-BBS. Normally a door program was written to be an on-line game that the users of your BBS can play, however there are many door programs that are not games, but are user - accessible utilities. A program to view the contents of compressed format files, is an example of this type of door. The quantity and variety of door programs written to be on-line games is tremendous. In short, a jumpdoor program becomes an extension of your BBS, and adds capabilities to it! The only real constraints placed on a jumpdoor program is that they fit in memory, and can communicate with the modem. 2AM-BBS has all of the capabilities needed to run as many doors as you want. Each of the doors can also be assigned 'security' levels, so that if you wish, only selected users can utilize the doors. Basically, the way that 2AM-BBS interfaces to door programs is identical to most BBS systems. Here are the steps: TABLE I - STEPS OF RUNNING A JUMPDOOR ______________________________________________________________________ 1. A user with access to the door selection choices a jumpdoor selection. 2. Control of the BBS is passed to a SysOp configured file that contains the jumpdoor menu, as well as instructions for the BBS to complete when a door is selected. (PASSAGES.DAT) 3. Upon completion of the door selection, 2AM-BBS creates a file with information related to the user 'going through the door'. (JUMPER.DAT) This file contains information like the users name, time remaining on the board, if the user has graphics capability, etc. 4. The SysOp configured file (PASSAGES.DAT) normally will invoke a batch file that will: a) Turn on a carrier detection program (for protection) b) Convert the 2AM-BBS JUMPER.DAT file into a format compatible with the door program. c) Move to the directory where the door program is located. d) Start up the door program. e) Upon termination of the door program, de-activate the carrier detection program. 5. Control will be automatically be returned to 2AM-BBS at the completion of the above steps (the batch file invoked by PASSAGES.DAT) ______________________________________________________________________ 4 It is important to note that during the time that the jumpdoor program has control of the machine that attention must be paid to the 'protection' you have provided. When the door program is running, all of the 'bullet-proof' software of 2AM-BBS is not being run, and it is up to you to insure that a user cannot get himself into trouble by using the doors. 1B. HOW TO INSTALL JUMPDOORS Jumpdoors are easy to install, and not always easy to get running. There is complete information on how to install a jumpdoor in the 2AM-BBS system in the SysOps Manual, pages 11-1 to 11-3 READ IT!. Basically, it's a good idea to keep each of the door programs, and its support files in a separate directory than any of the 2AM-BBS required directories. I prefer to have all of my door directories as sub-directories of BBS\JUMP. For example the game Phantasia is located in C:\BBS\JUMP\PHANT. There is no real need for this structure, but it sure helps to keep things straight on the board. So, lets say that you are going to install Phantasia as a jumpdoor on your BBS. First make the C:\BBS\JUMP\PHANT directory, then un-compress the files into that directory. THEN READ ALL OF THE DOOR'S DOCUMENTATION! Each door author does things differently, and what worked before to get a door going may not work this time! Some doors have a separate utility program that must be run first. Quite often, these utility programs will create the data files needed by the door program, and perhaps set up your customized game. Be sure to run the configuration program first, if the door you are installing has one. (Phantasia has a program called SETUP.EXE) Most jumpdoor programs can be run in a local mode. Its a good idea to do this, and get used to the game. You don't have to be an expert on the game, but your users will expect you to know something about it, and you will also need to know if its working correctly. This is also a good way to find out if you have all of the jumpdoor's support files, if the setup you may have done is correct, and what type of maintenance will be expected of you during the course of the game. Now that you are sure that the door program is installed on your PC correctly, it's time to tell 2AM-BBS where the program is, and what to do when a user selects it. All that 2AM-BBS knows about a door program is contained in the file called PASSAGES.DAT located in the \BBS\JUMP directory. This file is not needed for your BBS to run, so you may not even the file on the disk. If not, it can be created with any ASCII text editor as shown in the 2AM-BBS SysOps manual. 5 There is not too much information that the PASSAGES.DAT file contains about the door programs. You must decide upon a privilege level for use in the door (normally a privilege level of 1 is available to all users). Normally, I do not allow all users to access a new door, but reserve it for trusted users that have agreed to assist in a little door checkout (and leave E-Mail about the results if I'm not around!). Most door programs will not have the LOCAL command turned on. Since most doors programs are for remote users, the LOCAL command should be a 0. The third piece of information in PASSAGES.DAT is a DOS command or file name to execute, when the door is selected (as in step 4 above). Almost always this is the name of a batch file. For Phantasia, I use a batch file called PHANT.BAT. PAY ATTENTION TO THE DISCUSSION ABOUT THE " /C" AND THE "%" IDENTIFIERS IN THE SYSOPS MANUAL PARAGRAPH 11.1.1! This can be easily ignored, and when ignored, almost nothing will work the way you think it should! If you are running a 2 port BBS, be sure you include the PORTNUM variable at the end of the PASSAGES.DAT command line. You will need this PORTNUM value in the batch file you are going to run! Also, don't get too carried away with the comment line(s) after the jumpdoor entry. You can only have two, and ALL of the comment line is included in the JUMP.LOG file created by 2AM-BBS, sometimes causing a real strange looking validator log file. Finally, there is a bug in version 3.0 that occurs when you have more than 8 doors included in the PASSAGES.DAT file. The selection menu displayed when the user does a "S" (show) command, gets shifted to the left a couple of places. It doesn't cause any harm, just looks funny (sorry Neil!). 1C. INFORMATION PASSED TO A JUMPDOOR BY 2AM-BBS 2AM-BBS produces a file called JUMPER.DAT (or JUMPER2.DAT for a multi-node system) when a jumpdoor is activated. This file provides user information to the door program in order for it to run. In version 3.0 of 2AM-BBS, there are 17 lines of information about the user created. This information includes things like the baud rate, users handle, if the user has graphics, where the user is calling from, etc. 6 1D. OTHER DOOR SYSTEMS This is where the program 2AMDOOR.EXE comes into play. Since 2AM-BBS is a relatively new type of board, the vast majority of existing door programs are built to interface with other types of BBS's. I wrote 2AMDOOR to serve as an interface between 2AM-BBS and WILDCAT, RBBS, or PCBOARD. The three types of interface files produced allow any 2AM-BBS to run a huge selection of door software. Not all of the information passed along by the JUMPER.DAT file is what is required by one of the other types, and also, some additional information is required by the other types. Where possible, I have calculated the correct information and put it into the 'target' file. Each different type of BBS creates a file that is a different structure from the other, it is also named differently. The following table shows the correct output file names for each type of door currently supported by 2AMDOOR: TABLE II - PROPER OUTPUT FILE NAMES FOR EACH BOARD TYPE ______________________________________________________________________ DOOR WANTS TO READ TYPE: A FILE NAMED: -------------------------------------- WILDCAT ............. CALLINFO.BBS PCBOARD ............. PCBOARD.SYS RBBS ............. DORINFOX.DEF (X stands for the port number: 1, or 2) ______________________________________________________________________ It's important to know the above relationship, since 2AMDOOR will not automatically produce the correct file name for you. It will create a file named anything you want! Some door programs expect to see more than the basic user information file. 2AMDOOR will NOT create these for you. This is a list of what a door program MAY expect to see for each type. The door program also may NOT expect to see them. Normally if the door expects to see one or more of the following files, the documentation will tell you. If the documentation doesn't tell you, sometimes you will get an error message from the door program telling you that it expected something. Other times, it just won't work, and you can only guess why. I have about 3 of these that I'm still playing around with. 7 2. 2AMDOOR INSTALLATION Installation of the 2AMDOOR program is extremely easy! You just need the 2AMDOOR.EXE file in your \BBS\JUMP directory. Actually, it could be just about anywhere, since full path names are supported by 2AMDOOR. Just make sure that wherever you locate the program, that the proper path names are passed to it for locating the input file (JUMPER.DAT) and the output files (one of the three mentioned above). If you elect the LOG option, 2AMDOOR will create a file called DOORLOG.TXT in the same directory that its located in. (more on the options latter on). 2A. SINGLE PORT OPERATION In a single port operation, there is no need to specify that the parameter PORTNUM be passed from the PASSAGES.DAT file (see the 2AM sysops manual section 11). Also, since there is only one possible port that originated the call, you do not need to include a decision in your batch files based upon the PORTNUM value. The following is a good example of a batch file used to create a WILDCAT door for the Phantasia game: TABLE III - SAMPLE SINGLE PORT BATCH FILE ______________________________________________________________________ echo off cls cd\bbs\jump echo SINGLE PORT IN USE echo > com1 echo Starting the jump now! > com1 echo > com1 echo Using 2AMDOOR to convert to WILDCAT format > com1 2amdoor wildcat jumper.dat d:\bbs\jump\phant\callinfo.bbs h l cd\bbs\jump\phant echo > com1 echo Copying the data files to Ram Disk for speed > com1 copy *. e:\phant COPY BULLETIN.TXT COM1: echo > com1 echo Starting up the game > com1 phant 1 WILDCAT rem Copying the datafiles back to the hard disk copy e:\phant\*. d:\bbs\jump\phant ______________________________________________________________________ 8 What appear to be pretty dumb commands "ECHO > COM1" really have a <ALT-255> character just in front of the ">" symbol. This gives the effect of double spacing the text lines to the user on the other end of the comm port. 2B. MULTI PORT BBS The basics of a batch file for a multi port system is basically the same as above except there has to be a way to distinguish between port one and port two. 2AM-BBS takes care of this for you by allowing the use of the variable PORTNUM to be passed to a batch file as a command line parameter. Based upon the value of PORTNUM, your batch file can do the right things to the right port, as well as tell 2AMDOOR which JUMPER.DAT file to use (JUMPER.DAT or JUMPER2.DAT) 9 TABLE IV - SAMPLE MULTI PORT BATCH FILE (NEVER BEEN RUN!) ______________________________________________________________________ echo off cls cd\bbs\jump IF %1 == 1, GOTO PORT1 IF %1 == 2, GOTO PORT2 GOTO END :PORT1 echo PORT ONE ACTIVE echo > com1 echo Starting the jump now! > com1 echo Using 2AMDOOR to convert to WILDCAT format > com1 2amdoor wildcat jumper.dat d:\bbs\jump\phant\callinfo.bbs h l cd\bbs\jump\phant echo > com1 echo Copying the data files to Ram Disk for speed > com1 copy *. e:\phant COPY BULLETIN.TXT COM1: echo > com1 echo Starting up the game > com1 phant 1 WILDCAT rem Copying the datafiles back to the hard disk copy e:\phant\*. d:\bbs\jump\phant GOTO END :PORT2 echo PORT TWO ACTIVE echo > com2 echo Starting the jump now! > com2 echo Using 2AMDOOR to convert to WILDCAT format > com2 2amdoor wildcat jumper2.dat d:\bbs\jump\phant\callinfo.bbs h l cd\bbs\jump\phant echo > com2 echo Copying the data files to Ram Disk for speed > com2 copy *. e:\phant COPY BULLETIN.TXT COM1: echo > com2 echo Starting up the game > com2 phant 1 WILDCAT rem Copying the datafiles back to the hard disk copy e:\phant\*. d:\bbs\jump\phant GOTO END :END ______________________________________________________________________ 10 This is only an example of multi port operation. I don't run multi port, but have experimented around a little running mine that way, and I think this is a pretty close approximation as to what it should be. If someone develops a good example of a multi port batch using 2AMDOOR, please send along a copy! You even could attempt to use the first parameter (%1) in the JUMPER.DAT portion of the command line, that way you could support any port number that came along. Actually, there is a problem with this particular method of running Phantasia. The batch file should check the current status of the RAM disk files before allowing another user to copy old ones in. Also, my machine doesn't have enough memory (only 640k) to allow two copies of Phantasia, so I guess I'll never have to figure that one out. The point that I really am trying to make in all of this is that 2AMDOOR will support as many ports as you want to. Notice in the above multi port example, that JUMPER2.DAT was passed to 2AMDOOR, not JUMPER.DAT. 2AMDOOR really doesn't care what the input file name is, it will try to open it and read it, no matter what or where it is. 11 3. 2AMDOOR OPERATION - PRODUCE OUTPUT FILES The product of 2AMDOOR is an output file. Right now (release 1.0) it can support three output file structures, RBBS, WILDCAT, and PCBOARD. The object of these output files is of course to satisfy the door program's requirements. For example, if you have a door that want to be run on a WILDCAT BBS, then you must tell 2AMDOOR to produce a WILDCAT format output file (WITH THE CORRECT FILE NAME!). Unlike several other door converters, wherever I could use 'live' data (from the JUMPER.DAT file) I did. Often, this meant a small amount of decision making in the converter software, since different door files have different information in them. 3A. RBBS You must tell 2AMDOOR what format output file you want it to produce. In this particular case, you must put RBBS (not case sensitive) as the first parameter following the program name. This is simply a message to 2AMDOOR, and there should be no path name associated with RBBS. If you enter a name that 2AMDOOR does not support, you will be told on the screen, as the program starts. The second parameter must be the full path and file name for the JUMPER.DAT file you are using. If 2AMDOOR cannot find it, you will get an error message on the screen. Make sure that the output file name you specify is proper for RBBS (DORINFOX.DAT). If you enter this name wrong, 2AMDOOR will produce the wrong file. It will simply produce whatever you tell it to call the file. 3B. WILDCAT By now, your getting the idea of how 2AMDOOR works. You must specify WILDCAT as the first command line parameter, the full path and file name for the JUMPER.DAT file you want used, and the correct path and file name for the output file (CALLINFO.BBS). 3C. PCBOARD This one is just a little different. For reasons of clarity, you must use PCB14 as the first parameter, NOT PCBOARD. This is because 2AMDOOR produces a PCBOARD version 14 file. 2AMDOOR will just not know what you are talking about if you use PCBOARD as the BBS type. Remember to call your output file PCBOARD.SYS! 12 4. 2AMDOOR OPTIONS - HANDLES AND LOG FILES Not done yet! There are a couple of options that you can select on the 2AMDOOR command line. One is if you wish to allow user handles to be passed to the door program instead of the full user's name. The other option tells 2AMDOOR to create and maintain a log of its use. 4A. Allow use of handles in jumpdoors By use of the H parameter (not case sensitive) as either of the last two command line parameters, 2AMDOOR will put the users handle in the output file, instead of the user's full name as entered in the 2AM-BBS new user application. For example: 2AMDOOR PCB14 JUMPER.DAT C:\BBS\JUMP\PCBOARD.SYS H Will tell 2AMDOOR to pass the users handle to the file PCBOARD.SYS. I normally use this H parameter, since a lot of users on my board prefer their handle vs. their name. Also, If I saw ALFRED HITCHCOCK (real name) instead of PIGBAG (handle) I wouldn't know who it was. 4B. Maintain a 2AMDOOR log file Using the L command line parameter tells 2AMDOOR to create and maintain a log file. The log file is amended each time that the L parameter is 'on' and 2AMDOOR is started. If you include the L parameter in some batch files and not in others, then you will not have a complete log of 2AMDOOR's usage. If you are curious about a single door's usage, you can use the L parameter for only that door, and examine the log to see how (and who) is using the door. The log file is called DOORLOG.TXT and is located in the same directory as the 2AMDOOR.EXE file. Here is an example of a log entry: DEREK WAHILA ... AKA ... DEREK > On Sat May 27 21:12:15 1989 > While connected at: 1200 Baud on COMM1 > Used 2AMDOOR to create a PCB14 file Each time the log is written to, 2AMDOOR includes the users real name as shown in the user's application, and the user's handle (after the AKA.. Also Known As), the date/time of the passage, baud rate, comm port, and the type of file produced. If you have an active board, this file can get pretty large, so you may want to delete it from time to time (via the scheduler?) 13 5. TROUBLE YOU CAN GET INTO There are several ways that you can get into 'trouble' running a door, or using 2AMDOOR. There are two types in my mind, those with error messages, and those without. 5A. WITH ERROR MESSAGES There are several sources of error messages. The first one is 2AM-BBS itself. If you mess something up in the PASSAGES.DAT file, 2AM-BBS will note it in one of the system log files. Normally, when I get this type of error, it's easily found by looking at the PASSAGES.DAT file. (beware of an extra blank line before the EOF). Make sure you check the system logs if something is going wrong, since you will not get an indication of what the trouble is from 2AM-BBS any other way. You can also get error messages from 2AMDOOR. There is a message that indicates you asked for a door conversion that doesn't exist. Like telling it to produce a PCBOARD file instead of a PCB14 file for instance. There is also an error message for each of the three files that 2AMDOOR opens and uses. The program will tell you which one it's having trouble with, just write it down, as it goes by. Finally, the door program itself may give you error messages. The better doors will have a list of these errors in the documentation, and a hint as to what the trouble is. Remember, some of the door programs require that the modem CD (carrier detect) be active, so if you are trying to debug the thing locally, and all looks good, it could be you need a trusty user to call and try it. 5B. WITHOUT ERROR MESSAGES The worst of all, the door doesn't work, and there is no indication of what is wrong. Well, it can still be narrowed down! First of all, its hard to mess up something in 2AM-BBS and not get an entry in one of the logs. So, put that consideration last on the list. Most likely its the way in which the door program is installed. RE-read the documentation for the door, some documents are tricky to understand. Look at the directory that the door is in, if there are a couple of .EXE or.COM files, do a little experimentation with them. One may be a setup program! Many door programs have their own configuration files that need to be edited for your configuration, so if you see something with a .DAT or .TXT extension, try looking at them with an editor. If the door program works in local mode, that doesn't mean it will work over the comm port! If the door program supports several different types of interfaces, try them by instructing 2AMDOOR (and the door program) to produce a different file. Make sure that 2AMDOOR is not giving you an error message when it starts up. Errors associated with files will cause a beep, errors that you make will not beep, but will be shown on the screen when the program starts up. 14 The door may sense that no-one is on the modem, so have a REALLY good friend call, and wander away from his PC, while you pretend you are the user, and try different things. (remember alt-J). Also, you can stay in chat mode, and start the batch file up also. If you think that there are error messages (or may be) shown on the screen, but they go by too fast to read, remember that you can log the screen to a disk file in 2AM-BBS, and then look at it latter. Finally, just give up and go on to another door. There's a million of 'em. 15 6. EXAMPLES Here are example batch files for some of the most favorite jumpdoors on my board: 6A. Czar wars Czar wars is one of the most favorite, and oldest BBS doors. Its a great space-trading adventure game and can support a HUGE and complicated universe. For more information on CZARWARS see the references section at the end of this document. echo off cls cd\bbs\jump echo > com1 echo Starting the jump now! > com1 echo > com1 echo Using 2AMDOOR to convert to PCBOARD format > com1 2amdoor pcb14 jumper.dat c:\czar\pcboard.sys l h cd\bbs\czar ECHO > com1 echo > Starting up the game... czar_pgm /pcb14 6B. CASINO Casino is a gambling game door, that has amazingly good graphics support. It's not restricted to graphics players however. For more information on CASINO see the references section at the end of this document. ECHO OFF cls cd\bbs\jump echo > com1 echo Starting the jump now! > com1 echo > com1 echo Using 2AMDOOR to convert to a wildcat format > com1 2AMDOOR PCB14 JUMPER.DAT \BBS\JUMP\casino\CALLINFO.BBS H L cd \bbs\jump\casino casino 1 \BBS\JUMP\CASINO WILDCAT 16 6C. Bad example! Suppose the following for CZARWARS: echo off cls cd\bbs\jump echo > com1 echo Starting the jump now! > com1 echo > com1 echo Using 2AMDOOR to convert to PCBOARD format > com1 2amdoor RBBS jumper.dat c:\czar\pcboard.sys l h cd\bbs\czar ECHO > com1 echo > Starting up the game... czar_pgm /pcb14 It won't work! 2AMDOOR was told to produce a output file in the RBBS format, and call it pcboard.sys. IT WILL!. Be careful of this. By about this time you may be wondering why I left it that way. Why not create a default output file name dependant upon the type of interface being produced? I wanted to maintain the multi port capability, and this way, you can call the output DORINFO1.DAT or DORINFO2.DAT or whatever. Besides, once you get the batch file working, there is no reason to mess with it! 17 7A. REGISTRATION & TECHNICAL SUPPORT This is a SHAREWARE program intended to be used by SysOps of 2AM-BBS. It's not intended to be FREE! If you have tried the program, and are using it on your board to run doors, then you should BUY the program from me for $15.00. I intend to continue to support this product by adding more door interfaces to it like GAP, WWIV, QBBS, and perhaps MONITOR. When you register your copy with me, I'll record your name and address and will send you the next higher release as soon as its completed. Also, by registering you can ask me all the questions you want about how to make a door work on your 2AM system. I run about 10 at any one time, deleting the not-so-favorite ones, and adding new ones all the time, so I have a lot of practice in this sort of thing. Just call my board and post a message in the 2AM discussion area. CONNECT! BBS @ (607)-724-7170, 24hrs, 2400/1200/300, 100 Megs As a registered user, you can also download any of the door programs that I have managed to get working, and its associated batch file as well! 7B. REFERENCES 1) 2AM-BBS (c) copyright 1986 - 1989 is a product of 2AM ASSOCIATES. It is supported via The DREW University Underground BBS at any of the following numbers: (201)-377-8245, (201)-377-8193 (201)-377-7861 (201)-377-6810, (201)-377-4538 2) Phantasia, a role playing game, by Edward Estes (AT&T Teletype Corporation) and Modified by Chris Robertson 1985 is distributed free of charge on MYCROFT BBS! at: (408)-927-0105 3) CZARWARS, a space trading game, (Copyright 1987-1989) by Ray Yeargin is distributed via Shareware and is available for evaluation on THE HOME OF CZARWARS BBS at: (904)-878-7704 4) CASINO a gambling game is written by Michael W. Bayley (SysOp of MYCROFT BBS!) and is distributed free of charge. 5) A lot of 'pointing to the right document' help was provided by Scott Swain SysOp of CONSOLE COMMAND BBS at: (805)-968-5901, (805)-968-9411, (805)-968-0307 6) Many thanks to the patient users of CONNECT! for helping me out with the debug of the doors and my program. 7) Special thanks to THIN ICE for all the debug time!