The CIA World Factbook 1992

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

/ The CIA World Factbook 1992 / k3bimage.iso / sel / 02 / 0029 / gtrunpcb.doc < prev next >

Wrap

Text File | 1991-12-02 | 34.3 KB | 633 lines

GTRUNPCB A PCBoard Door Interface For GT Power BBSes These programs, both in executable and source code form, as well as all associated documentation are Copr. 1988 by Scott Swaine DISCLAIMER: ---------- I make no warranties, either expressed or implied, as to the usefulness of this product under any application. I will not be held liable for any damages, either incidental or consequential, that may arise from the use or misuse of this product. DISTRIBUTION: ------------ Redistribution of this software is subject to the following: o It may NOT be modified in any way. o It may not be sold or otherwise distributed for profit save for the following exceptions: - Users groups and Public Domain software houses that distribute software for a nominal handling/media fee not to exceed five (5) dollars (US). - Online services that charge a fee for general access to the system. o No fee may be charged for it's use in any situation. o All associated files comprising this package must be included in the same archive-type file. The source code is not being released for distribution. CREDITS: ------- First off, let me give credit where credit is due. I wish to thank the people who helped contribute to this program by providing me with the information I needed on the file formats for these PCBoard files. I especially want to say thanks to Carl Evans, Sysop of Vervan's War Board, 714-989-7596. Without his help, much of the information needed to make the PCBOARD.DAT file editor would have been much harder to come by. I'm thankful for his patience, too! For all the persistent nagging I put him through, asking questions of one kind or another, I'm STILL a member of his very fine BBS! I also want to thank Harwood Software Associates for providing their fast and easy-to-use screen writing routines in HSA_TEXT which I'm using in MAKE_DAT. This saved me a lot of extra work in the screen display routines. OVERVIEW: -------- One of the best things about BBSes nowadays are the 'doors'. Doors are programs, like games and utilities, that are not usually a part of the BBS software itself. There are many different kinds of programs that can be used in a door. Many of these are 'dedicated' door programs. This means that they were always intended to be run in a door and therefore have built-in support for using the comm port, monitoring the carrier, etc. Since these kinds of programs usually need some info from the BBS in order for them to know whether the user is 'local' (at the console) or 'remote' (calling in from somewhere else), what comm port is being used at this time, who the user is, how much time is left and various other pieces of info that tell it what was going on inside the BBS, the door program is usually designed to be specific to a particular kind of BBS software. While this makes it very easy to set it up for use with THAT software, it makes it nearly impossible to use it with a different BBS software package. Thus arises the need for conversion programs to make the info that the one BBS provides for it's door facility available for the other BBS's doors. In this package, otherwise known as an 'archive', should be several files. The following is a list: GTRUNPCB.DOC - The thing you're gawking at now! MAKE_DAT.EXE - The utility to create the file PCBOARD.DAT. MAKE_SYS.EXE - The utility to create the file PCBOARD.SYS. PCBDATRF.ARC - A reference guide to the PCBOARD.DAT file formats. README.* - An addendum to the docs with last minute info. If the ARC you received does NOT have all of the above files in it, a complete copy can be downloaded from my BBS (see the info at the end of this documentation). MAKE_SYS and MAKE_DAT are both equipped to handle the file formats used by PCBoard version 12.1 and 14.0. MAKE_SYS creates the file PCBOARD.SYS, which is required by all PCBoard door programs. It provides the information on the current user that the door needs to function properly. You will need to run MAKE_SYS just prior to running the PCBoard door program. MAKE_DAT is needed only for those doors that insist on using some of the information that is stored in a file called PCBOARD.DAT. The PCBOARD.DAT file contains various configuration information for a PCBoard BBS. This information consists of file names, path names, user access privileges, etc. The usual stuff one would need to have defined to operate a BBS. This program should be run only once to set up the PCBOARD.DAT file the first time, then can be put away (unless you need to edit the file later). The PCBOARD.DAT file does not change from one door execution to another. However, you MAY need two copies of the file, one for doors using the version 12.1 format and one for doors using the version 14.0 format. USING MAKE_SYS: -------------- Program features: This program is a lot more flexible than any others like it that I've seen. While they just barely cover some of the basics, I go into the internals of the PCBOARD.SYS file. Not only do I set the proper values according to what the BBS uses, I also allow for command line switches to set options that door programs might use. MAKE_SYS doesn't require a lot in order for it to work. In fact, it doesn't really require ANYTHING to use it for normal purposes. To use it, simply call it by name. You don't have to be in the GT directory for it to find the GTUSER.BBS file. It looks in the environment to find the GTPATH variable and then looks in the directory that it points to. Then, it reads the GTUSER.BBS file, parses it into it's constituent data fields, converts them into the PCBoard equivalent, adds in any command line parameter switch settings, and then writes it out as a PCBOARD.SYS file in the current directory. MAKE_SYS uses default values for everything in the PCBOARD.SYS file, including the version of the format for the file. But the option to control certain key areas has been built in. The PCBOARD.SYS file has a multitude of data fields in it which contain various kinds of information from the BBS for doors to use at their discretion. Many of these have no GT equivalent, so I made up some reasonable values for them. There are also a bunch of 'flag' values which can each turn on or off a particular option. These can be controlled by using a set of command line switches. In the following paragraphs I will attempt to explain what each of these switches does and what the default value is. Command Line Switches: All switches must start with either a slash ('/') or a hyphen ('-'), followed by a letter defining the type of switch and then a colon (':'). There are two kinds of switches in use here. One kind takes a 'Y' or 'N' value to turn 'on' or 'off' an option, respectively and the other takes a numeric value. However, there is one command line option that is NOT a switch. This one is simply a question mark ('?') and it tells MAKE_SYS to list the help screen. This option must be the only thing on the command line. Anything after it will be ignored and anything before it will cause a error. To use it, simply enter: MAKE_SYS ? Each switch must be separated by a space on the command line in order for the program to recognize it as a separate switch. The order in which they appear is not significant, nor is the case (upper or lower) of the letter in the switch. Here is a list of the available switches: Switch Value(s) Description /A: Y or N Caller Alarm. Some doors will beep or otherwise make some kind of noise to let you know a caller has entered it. If this option is turned off, you won't hear the beep. The default for this is to turn it off (I don't want my computer beeping at me all the time). /B: Y or N Sysop Page Bell. In most dedicated door program, the Sysop can enter 'chat' mode with the user. But some doors can also 'page' the Sysop in much the same way as they can in the main board. This switch controls whether they can or not. The default is 'not'. /C: number Comm Port Select. In version 14.0, but not version 12.1, you can put the comm port number in the PCBOARD.SYS file. Valid values are 0, 1 & 2. If a 0 is used, 'local' mode is forced. See the section below on 'local' operation. The default comm port is COM1. /D: Y or N Display Active. Normally, the console display is active while the user is in a door. This is so the Sysop can see who is doing what on the system. But if the Sysop should want to disable the display, a value of 'N' would do it. /G: Y or N ANSI Graphics Override. GT provides doors with the current status of the ANSI mode. This had been a problem at one time with some conversion programs that did not properly set this switch. The default is to use the setting in the BBS. This switch is only for those special occasions where an override is needed. /P: Y or N Printer Logging. This switch turns on or off the printer logging feature of the doors that log caller activities on a printer. I'm not sure how many people have a printer hooked up to their BBS computer, but I'm not one of them. So the default for this is NOT to use a printer (it's just a waste of paper, anyway). /T: number Time Allowance Override. GT doesn't provide doors with an accurate time value of how long the caller has on the system, but MAKE_SYS can figure it out from the info it DOES provide. However, if you want a user to have a certain 'fixed' amount of time in a door, specify that amount, in minutes, on this switch. The number must be between 1 and 1440 minutes. This will override the default of using the amount left on the board. /V: number PCBoard Version. Even though version 14.0 of PCBoard has yet to be officially released (as of this writing), most PCBoard doors out right now are made for use under PCBoard version 12.1. Therefore, the default is to make a ver. 12.1 compatible format of PCBOARD.SYS. If you wish to run a version 14.0 compatible door, specify a '14' as the value for this switch. You may also specify a '12' if you wish for informational purposes. The result will be the same as if you did not use it at all. When specifying a command line switch that takes a Y/N value, you need only specify the first letter to define the value. In other words, you could use 'YES' or 'NO' if you wanted, but MAKE_SYS only looks at the first letter of the value to identify it. So, I could specify a switch with something like 'You_betcha!' and it would interpret it as a 'Y' only. For these types of switches, simply specifying the switch itself, without any Y/N value, will assume a 'Y' value. On the switches that require a numeric value, it must be a positive integer. If the first character is not a number, an error is returned. Numbers after a decimal point are ignored. Time Calculations: The GTUSER.BBS file provides minimal information on the amount of time left on the board. It provides the amount of time left till the end of the current call and the amount of time left till the next scheduled event. It also provides the time (in HH:MM format) that the file was written. Since none of these time values are current as of the moment the BBS exits to the door, it is up to the door program to figure out from this information (and also the current DOS time) what amount of time the user actually has left on the board. It is a good idea to do this calculation anyway, even if a future version of GT rewrites the GTUSER.BBS file before running the door or includes more information in it on the time left on the board. This way, you will KNOW you are getting an accurate time calculation. MAKE_SYS has the ability to figure out how much time the user has left by using a combination of things. It takes the time entry from GTUSER.BBS, which was the 'current' time when the file was written, and calculates from the DOS time how much time has elapsed since then. Once I get the elapsed time, I get the total time allowed for that call, be it the regular 'total' time or the 'event' time (as specified in GTUSER.BBS). If the event time comes before the total time, I use it instead, and it takes off 5 minutes from that time for GT's 'pre-event wait', since it's not included in the value from the file. It then finds out how much time is remaining by subtracting the elapsed time from the total allowed time. When calculating the time left on the board, I also take off 2 minutes from the 'allowed' time. This will insure the user does not come back from the door only to be rudely kicked off because the time ran out on the board. Local Operation: In GT Power ver. 14 and up, the baud rate parameter in the GTUSER.BBS file will read 'LOCAL' if the Sysop has logged in locally at the console. GT Power ver. 13 did NOT do this. So, if the Sysop wanted to use a door in 'local' mode, the GTUSER.BBS file would have to be edited to show 'LOCAL' in place of the baud rate for the conversion program to work properly and set 'local' mode (assuming the door program didn't have a special switch to use local mode). MAKE_SYS can work around this problem by using the '/C:' (Comm Port Select) switch. If a comm port of '0' is specified, a 'local' mode is forced regardless of the status of the baud rate parameter in GTUSER.BBS. This way, the Sysop of a GT 13.00 BBS can log on locally by forcing the 'local' condition. GT 14.xx Sysops don't really need this feature since the 'LOCAL' parameter would already be specified in GTUSER.BBS. Fixed DTE: The PCBOARD.SYS for version 14.0 of PCBoard has a field for specifying a 'fixed' DTE (computer-to-modem speed). MAKE_SYS has no way of knowing what the fixed DTE is that GT in using, if any. So this baud rate is set to the same as in GTUSER.BBS (supposedly the computer-to-modem speed) or to 2400 baud if in 'local' mode (why not?). PCBoard-Specific Data: There is a lot of different kinds of data stuffed into this little 128-byte file. Much of it is specific to PCBoard operations. These data fields contain such stuff as user record number, download limits, conference areas visited, node chat status, etc. These have no direct GT counterparts, so I put in the appropriate data to make it workable in a situation where this data might come under real use by some doors. ProDoor is an example. It uses several areas of information in this and other files to do it's job. I'm not guaranteeing that ProDoor will work using MAKE_SYS as part of it's door setup batch routine, but it's at least a step closer. There is one field, however, that PCBOARD.SYS uses which is not supported with the equivalent information from GT. This is the password field. First of all, I don't know the format of the GTMAIL.CTL file where GT stores it's user records. But that's beside the point. I'm using a 'fake' password in this field. I don't want to jeopardize anyone's security by fetching their real password from their user record in GT, so I'm using the word 'PASSWORD' in this field. I doubt many door programs will use this field much, anyway. But just in case you start experiencing problems with a door not allowing you in because of a bad password, you'll need to edit the data files of that door to fix things. Undocumented Features: I'm including this section because of a couple features that probably should be described but, for all intents and purposes, should be considered 'undocumented'. These are 'extra' command line parameters that are supported solely for the use of future programs I may make as an interface to certain doors that use several other PCBoard files. An example of this kind of door is ProDoor. As such, these extra parameters have no use for the casual user in general. There are two command line parameters that are recognized by MAKE_SYS which would normally be passed to it by the future interface programs using it. If they are used at all, they must appear in a very specific order. The first parameter is specified by the '@' character and is immediately followed by a number (no spaces). It MUST be the first option after the program name. It specifies the user number for the current user as it is registered in PCBoard's user database. This value must be a positive integer (greater than 0). The other parameter is for use only in the version 14 format PCBOARD.SYS file (it is ignored in the version 12 file). It is specified by the '#' character and is also immediately followed by a number. This parameter MUST be the second one on the command line and MUST follow the '@' parameter described above (ie. you can't use this one if you're not using the other one). This one specifies a fixed DTE baud rate in case you are using a USR, Hayes or similar modem that supports a fixed computer-to-modem baud rate. Valid baud rate values on this option are 9600 and 19200. Those are the most often used and the only ones I support here. As I said before, IF these options are used at all by the user, they must be used in this order. If these extra options are not the first and second parameters, respectively, on the command line, they will cause an error. All other parameters (the normal ones specified with the '/' and/or '-') are to follow these. They may be in any order in relation to each other. Exit Return Codes: When exiting, MAKE_SYS sets a return code according to the results of the operation. This result code can then be tested by DOS in the batch file with the ERRORLEVEL statement. There are 3 possible codes in all. If all is well and the PCBOARD.SYS file was created properly, it returns a code of '0'. If there was an error in the command line somewhere, like a bad command switch or value, it returns a result code of '1'. The final result code is for a file- related error. The reasons for this could be if the GTUSER.BBS could not be read, the GTPATH environment variable was missing or if the PCBOARD.SYS file could not be written properly. The result code in this case is '2'. These result codes may not be of much use to the casual user, but may be used by any future programs I make to interface with these programs. USING MAKE_DAT: -------------- I know of only one other GT to PCBoard conversion program that creates the PCBOARD.DAT file. And even at that, it's far from being complete or even the least bit useful to a door that needs to get some information from it. MAKE_DAT will allow you to create and edit a complete file for those door programs that need to use it. I searched far and wide and went through great pains to get information on the data formats for this file, so I hope somebody appreciates it. Since this file only needs to be made once, you can put MAKE_DAT away someplace until you need it again for editing the file. Also, it would be best to put the PCBOARD.DAT file in a place common to where you normally put these files for your PCBoard doors to use. This program provides an easy-to-use interface for users while editing the data fields of the PCBOARD.DAT file. In fact, because of the ease of use and power, I wouldn't be surprised if some PCBoard Sysops used it as a 'quick fix' utility for reconfiguring the file. For a reference to the data fields in this file, see the included files PCBDAT.REF & PCBDAT.OTL, both of which are contained in the file PCBDATRF.ARC along with some documentation in PCBDATRF.DOC. They describe the data formats of both the version 12.1 and 14.0 files. The file PCBDAT.REF is a plain ASCII 'block save' file generated from the file PCBDAT.OTL. The file PCBDAT.OTL is the original work file I was using when putting things together. It's a SideKick Plus outline file. You will need SideKick Plus or some kind of conversion program to use it. Running The Program: When you first start up the program, you may include the pathname of where the PCBOARD.DAT file is to be on the command line. If the file exists in that directory, you will be asked to use the existing information in it, overwrite it with a new file or to abort the program without doing anything. If you choose to use the existing data, it will automatically determine what format file it is, load it in and then go to edit it. If you should want to overwrite the file, it continues as if you were creating a brand new file by asking which version format it should be in. This is a multiple choice field (see below), so you use the cursor left and right to select the version number you want and then press F10 to 'accept' this choice. After selecting the version, you can start editing it. If you decide to abort at this point, just press ESC. When starting a new file, the data fields are all set up with default values. Once you get into the editing mode, a notice showing which version of file you are editing is displayed in the upper left of the 'work screen' area. Moving Through The Fields: To move from one field to another, you would use the up and down cursor keys and the tab keys. The up arrow moves you to the next higher field above the current one. In the case where there are multiple columns of fields, it will move to the first column of the bottom line of the columns (unless you move to a previous page which will put you on the last column). With this in mind, you can probably assume the down arrow moves down through the fields. It moves to the first column of the top line in multi-column areas. To move across through multiple columns of fields, you use the tab key. It will move forward through the columns, wrapping at the last column to the first one of the next line. It also can move down to the following field below the current one in single-column screens. If you want to back up to the previous field in a row, use the shift- tab key (referred to here as a 'backtab'). The backtab performs the opposite function of the tab. With it, you can move backwards through the columns, wrapping from the first column to the last one on the previous line. You may also move upward through the screen 'page' of single-column fields. You will notice that I refer to the screens as 'pages' of fields. This is how they are structured. You may move 'off' the bottom of one page to the top of the next page or 'off' the top of a page to the bottom of the previous one. The page number is displayed in the upper right corner of the 'work screen' area. The last page will wrap around to the first page as will the first page wrap to the last. This structure is similar to a circle where you can keep going 'round and 'round to find the things you want. You may move through the pages by using PgUp to go backwards through the pages (page 2 to page 1, etc.) and PgDn to go forward (page 1 to page 2, etc.). This will place the cursor at the top of the page (first field) for you to go from there. This makes for an easy trip to the field you want to edit, if you know what page it's on. Editing The Fields: The PCBOARD.DAT file is a very complex data file with a LOT of information stored in it. But I was able to break it down and create three different types of fields, two of which are quite similar (I derived the function for handling one from the other). These field types are multiple choice, toggle and text entry. The multiple choice fields offer you a selection of choices. You use the left and right arrow keys to move the selection cursor between them. Once the cursor is on the choice you want, you may go on to the next field and edit it. The toggle fields work in exactly the same way as the multiple choice fields. You use the left and right arrow keys to move between two possible choices, 'on' and 'off'. These kinds of fields control a true/false or on/off type of option with usually enables and disables certain functions in the PCBoard BBS. The text entry field is a bit more complex. In these fields, you might have a couple of different kinds of data that may be edited. This may be standard alphanumeric text (like filenames, pathnames, prompt lines, etc.), numeric entries or time entries (in HH:MM format). The filenames and pathnames, text that normally should be upper case, are forced as such. In other words, you can't type a lower case letter in a filename. But in the prompt lines and Sysop name field, you may use upper and lower case letters as well as any other kinds of characters. I don't do any checking on the validity of the filenames and pathnames. That's up to you and what ever program needs this information. Numeric entries only allow numbers to be entered, as do the time entries. When editing a text entry field, you have the use of certain cursor keys and other keys to help move around the field and edit the data. To move through the data in the field, you may use the left and right cursor keys. Left moves you one space to the left, until you hit the left side of the field. Right moves you one space to the right until you reach the limit on that end, which may be the space right after the end of the current text or the rightmost location of the field (whichever come first). The HOME key moves you to the beginning of the field and the END key moves you to the end of the text. If you should reach the rightmost location of the field, the cursor will appear to go off the end and disappear. This is because it is out of the range of the field and you can't go any further. I've seen some routines where it reaches the end of the field and stops, then if you go to backspace, you take the character under the cursor with you to the left. If you wanted to delete that character, you have to go another step to do it. Not here. If you go to the end of the data field, you can still use backspace to delete that last character. The backspace key deletes the character on the left of the cursor, moving all data after it one space to the left. The DEL key deletes the character under the cursor and moves text on the right to fill in. Normally, when you first go into a text entry field, you go in using 'overwrite' mode, ie. text you type is written over the existing data. If you hit the INSERT key, you may toggle 'insert' mode on and off. With it on, text you type is inserted at the current cursor location pushing the data after it to the right. A status indicator on the bottom line of the screen will show a low intensity 'Ins' when insert mode is off and a highlighted one when on. The above functions work in both the regular alphanumeric entries and numeric entries (where the text must be all numbers). But a slightly different setup is used when editing a time entry. To save on some code so I didn't have to move characters all over the place, I disabled the backspace, DEL and INSERT keys for the time entries. In these, you simply type the numbers and use the left/right cursor keys to move through it. The cursor will automatically jump over the colon in the middle of the time field. Once you have finished typing in the data (if any), you may move on to the next field. Clicks And Buzzes: One little thing I included to help let you know what's going on is a beeper. It 'clicks' whenever you move from one field to another and 'buzzes' when you encounter an error. The errors may be something like trying to move beyond the left or right boundaries of a field, trying to type more text than a field can hold, typing an illegal character for an entry, or entering a number for a numeric entry that is out of the range for that entry. This last one happens after you try exiting from the field to let you know it won't accept it as-is. Exiting And Saving: Now what kind of program would this be if you couldn't exit from it or save the data? If, for some reason, you decide NOT to keep the changes to the data you're currently editing, you may hit ESC to abort the program. If you want to exit and save the data, hit the F10 key. Pretty simple, eh? SHAREWARE: --------- I am releasing these programs to the public as Shareware. If you should find them useful and continue using them past a trial period of two weeks, a contribution of five (5) dollars (US) is requested. Please send a check or money order to: Scott Swaine c/o Console Command Headquarters 160-D N. Fairview Ave. Suite 223 Goleta, CA 93117 These programs are full working versions so there is no 'Registered Copy' to buy. But I hope you see fit to send in your contribution anyway. Supporting this software will encourage me to bring out new and better programs in the future. When sending in your contribution, please include a short note on where you found this program so I can get some idea of the extent of the distribution of this software. CONCLUSION: ---------- These programs are probably all you'll need to set up and run most PCBoard doors successfully on a GT Power BBS. I went to great lengths to make sure that these programs reproduced the exact data required by those doors. I hope they serve you well. If you should ever find a problem in the operation of these programs, let me know so I can fix it. I try very hard to make programs that are bug-free, but even *I* can miss something (although it doesn't happen very often, heh heh). Bug reports, questions, comments, etc. can be directed to me via the information below. Enjoy! Scott Swaine, Sysop Console Command Headquarters (805) 968-5094, 24 hours/day 300/1200/2400/9600 baud, 8-N-1 GT Network net/node 054/000 CompuServe ID: 72057,1542