The Astrodome Bulletin Board Software Version 1.10 Copyright 1988 by Thomas Boutell Please distribute this package as widely as possible. Do NOT separate or break up the files making up the package when distributing it; distribute either the original archive or duplicates of the original distribution disks. This package is NOT free software; if the program meets your needs, you are asked to pay a registration fee of $75. This registration fee entitles you to two direct updates by mail without charge and direct support from the author. It also entitles you to profit from the registration of additional operators. If you are a registered user, and another individual registers the package mentioning that you gave it to them, $25 of their registration fee will be sent to you as a finder's fee. You must have registered your own copy to receive a finder's fee. Please send all inquiries and registration payments to: Thomas Boutell Tuttle Rd., Box 284 Durham, CT 06422 United States of America Compuserve PIN 75006,1072 When registering, PLEASE give your name, your address, and the current version number of your system. Also state the media you require; 720k 3.5" and 360k 5.25" MSDOS floppies are available. 1 Table of Contents Subject Page Shareware Terms.............................. 1 Table of Contents............................ 2 Basic Setup.................................. 3 Initializing the System...................... 4 Local Options for the Operator............... 6 Using the Supplied BBS....................... 7 The Operators' Menu.......................... 9 Message Areas................................ 10 File Areas................................... 12 The Menuscript Language...................... 14 Scripts...................................... 14 Databases.................................... 14 Menus........................................ 15 Sigops....................................... 16 General Access Levels........................ 16 Creating Databases........................... 17 Description Files............................ 19 Enlarging Databases.......................... 19 Dictionary of Menuscript Commands............ 20 File Transfers............................... 28 Multilingual Operation....................... 29 Personal Extensions.......................... 31 Exiting to External Programs................. 31 ANSI Graphics................................ 33 Multitasking................................. 34 DOS Problems................................. 34 Other Fossil Drivers......................... 34 File Structures.............................. 35 Revision History............................. 36 2 Basic Setup It is important to realize that the Astrodome BBS Software package need not be set up as a traditional BBS, or even a recognizable one. This software is suited to any host application, from simple electronic mail to advanced custom applications. However, since a typical public- access BBS configuration is provided, it is very easy to get the system up and running initially. There is one item you will definitely need in order to take advantage of the software, and that is a good text editor. If you have Wordstar, the non- document mode will do fine. In general, any word processor in non- document "ASCII text" mode will do an acceptable job. A text editor is needed to edit the title screens, menus and initialization file of your system. The internal editor can be used for these jobs, but a solid full- screen editor is of course preferable. A second type of editor you may wish to use is an ANSI editor. This is an optional item, but the system does support the use of full- color text in title screens, and will display it only to callers who have selected the option. All ANSI editors should work well with this version of the Astrodome, including those supporting animation. There is one file you will need to edit before testing out your system. This file is called MODINIT.DAT, and contains the initial setup for your modem, the highest baud rate it can support, and other information used by the BBS. In using this manual, I recommend you begin by reading the "initialization" section and then proceed to try out your system by typing ADOME and firing it up; read the following section about your local escape- key options to learn how to log on locally and also upgrade your access once you're on. If all goes well, and you can receive outside calls, go on from there and begin reading the bulk of the manual, which deals with customizing your system, adding areas, adding external programs, and completely redesigning it. First of all, though, follow the instructions in READ.ME in order to get the software in place on your drive, if you haven't already! Good luck. Thomas Boutell 3 Initializing the System In order to set up the system, you must create a file named MODINIT.DAT. One is provided, but you will almost certainly have to revise it to meet your own requirements. This file is a text file containing the following: Modem Initialization String Maximum Baud Rate Terminal Batch File Initial Access Level User Status Filename Caller Log Size Database Default Path Menu Default Path New User Time Limit Communications Port (1 or 2) System Password (optional) Data bits (optional) Default language (optional) The first initializes your modem appropriately for use with the system. This package takes a true Hayes- compatible modem as an absolute requirement. You must set the system for "terse" numeric result codes, to automatically answer, and not to "echo" information sent to it by the system. This works out to the following initialization string: AT V0 S0=1 E0 In addition, a 1200- baud Hayes compatible will require that X1 be present on the line to access 1200 baud properly. AT V0 S0=1 E0 X1 If you have another configuration, or higher baud rate, please check your documentation, particularly as to the X parameter, which must be set higher for a baud rate of 2400 in order to make "result code 10" (2400 baud) available. If you operate above 2400 baud, I regret that I do not have support for this at this time. This is purely due to the fact that I have no test site for such operations and if you wish to become one you are enthusiastically welcome to do so; contact me and give me the appropriate result codes for each baud rate, and I'll do my worst to get you up and running at whatever spectacular baud rate you require. The "maximum baud rate" should be 300, 1200 or 2400 at this time. The modem must be initialized at its highest speed or it will not answer at that speed. 4 "Terminal batch file" is the name of a batch file that will take the system to your favorite terminal software. It's recommended that you create such a file. Here's an example, for a sysop with Procomm: The "terminal batch file" line would contain PROCOMM.BAT. PROCOMM.BAT would contain the following: CD \PROCOMM PROCOMM CD \BBS EXIT This assumes, of course, that the subdirectories for Procomm and the board are Procomm and BBS, respectively. A variation on this should suit your purposes readily, however. Just make sure the file RETURNS TO YOUR BBS DIRECTORY and then exits. The initial access level is the degree of general access given to new users and can range from 0 to 9999, but most frequently it is quite a low number. For a private system, set it to zero, and give all options on your main menu except "goodbye" a minimum access level above zero. My own public system starts new users off at level 35, which gives full general access but plenty of basement room to drop miscreants into later on. The "user status file" contains information the board must store while SHELLing out to another program. I suggest you name it EXTERNAL.DAT and leave it at that; my own external programs use this filename. "Caller log size" is the number of calls that will be recorded in a self- maintaining log of activities. I suggest a size of 200. "Database default path" is the subdirectory where the message, file, mail, security, news and feedback areas are kept. This is usually a subdirectory named DATABASE off of the main BBS subdirectory; typically, \BBS\DATABASE\ . "Menu default path" is the same as above, except that it is the home of all .MNU and .SCR menu and script files. "New User Time Limit" is the number of minutes per day available to brand new users. The "communications port" option can be set to either 1 or 2 and specifies the COM serial port to be used. If you require a different port, see the documentation included for the fossil driver; it is capable of fooling the system into using any port you may have. 5 The next option, "System Password," is left blank in the supplied file. If you choose to use one, all users will be required to enter this password before they can even begin to log onto the board. It is meant only for strictly private systems. If you don't wish to create a closed system, leave this line blank. The next- to- last option, "Data bits," is necessary only if you are interested in allowing users to enter ascii codes greater than 127. The cause for this lies in using the system in a foreign language; Norwegian, for instance, requires these codes to be available. Left blank, this option will set itself to 7. If can be set to either 7 or 8; 8 activates the higher ascii codes. The final option, "default language," specifies what language you wish the BBS to communicate with the caller in when it first starts up; this language should be that preferred by the system operator himself or herself. If this option is left blank, it is assumed to be ENGLISH. Further details on setting up foreign- language and multilingual systems are given later in the manual. These are all the initialization options. Fortunately only a few will probably have to be changed for your installation, and most of those only once. In general, if you don't now understand what the option is talking about, it's already been dealt with by the sample system included. But the modem initialization string must be properly set, and executing the "exit to terminal" option will leave you sitting at a DOS prompt until you configure it. 6 Local Options for the Operator The operator- meaning, presumably, you- has access to a number of special options. While the system is running, you can call these up by pressing the ESCape key. This will display a menu containing the following options: 1. Log on Locally. This should not be used while a user is on the line, of course. This key allows the sysop to log on directly as a user. 2. Enter chat mode. This option allows you to converse with an external caller. To exit chat mode, press ESCape again. 3. Exit to terminal. This option, when configured through MODINIT.DAT, allows the sysop to exit to a preferred terminal package, presumably to make a call, and then return to the point of departure. It requires, of course, that there be enough RAM free for both the BBS package and the terminal to be in memory at the same time. If there is not, you may implement a similar option using by using the ! operator and the SHELL command in a "terminal" option of your "sysop" menu; see the section on menus and the entry for SHELL in the Menuscript dictionary. 4. Exit to DOS. This option simply clears the system out of memory entirely. If there is a user online, the system prompts for confirmation, because exiting to DOS with a user on line will cause the system to "forget" that particular call, including time used. 5. Hang up. This option simply disconnects the current user immediately. 6. Change access level and time. This option allows you to change the access level of the current user "on the fly." Remember to change it back if you don't want the change to be permanent. You'll find that after a change you must step off a menu and then back onto it for the change to be visible there. This command is also used to grant a user more time on the system, or less. 7. Exit to DOS but remain resident. This option exits to the operating system but does not remove the BBS from memory; in order to return to the system, COME BACK TO YOUR MAIN BBS DIRECTORY (critical!), then type EXIT. Remember to do this; I have occasionally "stacked" two or three copies of the board in memory at once by repeatedly exiting and just typing ADOME! 8. Continue. This option just decides not to decide and picks up where you had interrupted with the ESCape key. In addition, when a user has requested they be able to chat with you, the screen colors are reversed to alert you of this. They are also asked why they wish to chat. If you want to find out, press your TAB key; the system will display the user's reason for chatting. You can then make a decision whether or not to answer 7 the request without having to break in. Using the Supplied BBS Although the Astrodome BBS Software is meant to be highly customized by the individual sysop, a typical public- access BBS configuration is included. In order to learn the ropes of the package, please log on locally by setting up the system, pressing ESCape, and then pressing the "1" key. Enter your name when asked. If you have not logged on to the system before, you will be prompted for various bits of personal information. Since the system is your own, of course, you can enter whatever you wish. Your screen width should be 80; your screen height should be 24. When you are asked if you can display ANSI graphics, go ahead and say yes. An important aside here: I am assuming that you will generally be logging on to the system from the local keyboard. If you will more frequently be calling from another location to maintain the system, the screen width and height of that system may differ, and if it is not IBM- compatible you probably shouldn't select ANSI graphics. If text like "[0m;1m;" appears on your screen, you don't have ANSI support and should shut it off by using the (S)etup option on the main menu. Along with requesting your personal information, the system will display first a general help file, titled HELP.REA, which should describe in a general fashion how to navigate the BBS. You must create this file yourself, since your BBS will not necessarily resemble other systems running the software. The system will also display a file titled NEWUSER.REA, which should contain the rules by which users must abide on your system. This is typically where users are reminded of the importance of uploading files and posting messages, and of any restrictions on the access of new users, or those not paying a subscription fee if you charge one. Of course, if you are running a private system, this file can be quite brief since only users given the access password can log on at all, and presumably you have already told them the rules. Now, once you have entered your personal information, the system will look for general news you haven't seen. Since posting such news is your job, naturally there won't be any yet. As a first- time caller, though, you'll be told how the news system works. This descriptive file is stored in the file NEWS.DES in the DATABASE subdirectory of the system, and you can alter it freely. Next, the system will check for private mail. The same thing applies; since no one has logged on there won't be any, but the system will let you know the rules private mail works under. Again, you can alter this description by editing the file MAILPER.DES in the DATABASE subdirectory. 8 At this point the main menu should appear. Congratulations; your system is up and running. It's a good idea to upgrade your access to sysop level now in order to see all the options on the menu; to do this, press escape and then "6", for "Access." At the "(T)ime or (A)ccess? " prompt, press A and hit the RETURN key. When prompted for the access level, enter 9999, giving yourself the maximum level of access to the system. In order to see the new options this opens up on the menu, you must step off it to another menu and then return. Press the "M" key; pressing the RETURN key is not necessary. A menu of message areas will appear, although in your brand- new system there is just one "general" discussion area. Then press "Q" to leave this menu and return to the main menu. You should now be able to see the (O)perator's Menu option, which is the key to controlling the system. The Operators' Menu Press O to enter the Operators' Menu. From here you can control most aspects of your BBS. (R)ead Feedback allows you to read messages left to yourself and any other operators; users are asked if they wish to enter feedback when they log off. If you try out this option, a descriptive file will be displayed, just on the first time you use it; this file is called FEEDBACK.DES and is located in the DATABASE subdirectory of your BBS, where you are free to edit it. (S)end News allows you to make public announcements, which are displayed when users first log on. Most likely you'll wish to leave a news message announcing the creation of the system. (R)emove user allows you to remove users from the system, freeing their space to be used by another caller. (F)ile editing permits you to edit any text file, and also to specifically edit various menus of the BBS; you'll need to do this to add message and file areas, and eventually to customize your system. Doing this is described in the "Menuscript Language" section that makes up the bulk of the manual. (E)dit User allows you to change most aspects of a user's profile on the system, including their name, their password, their "real name" assuming you allow any difference between this and the name other users can see, their phone number, their level of access to the system, and various personal options they may not have learned how to select by themselves. At this point, log off the system by pressing Q to quit the operator's menu, then G for Goodbye, and pressing RETURN twice, which will answer the "send feedback?" and "do you really want to log off?" questions. Logging off the system permanently records you as a user. Once you have done so, log back on by pressing "ESCape" and then "1". Type your name and password, and soon you will be back to the main menu. Select the operator's menu again, and choose E for Edit User. Type in your own name, and your profile should appear. At this point, press "D" for "Daily Time Limit", and type 1440 to give yourself a daily time limit of twenty- four hours. Needless to say you will never use that up! 9 Two other options on the operator's menu refer to "databases." You will use these options to create new message and file areas, a task that is explained early in the section entitled "The Menuscript Language." Message Areas Now go ahead and leave the operator's menu, selecting (M)essage Forums from the main menu. A menu of message areas will be shown; only one has been pre- created. Go ahead and select the (G)eneral area. You will now find yourself faced with a menu offering (R)ead Messages, (P)ost Messages, (S)earch Messages, and (A)rea Change, among other options. The first just lets you read any messages that have been entered; there are none yet as you are the first user to log on. The second lets you enter a message; go ahead and pick this now. You will be asked for a message title; enter anything you wish, probably something like "Welcome to the BBS." Type "ALL" when asked who the message is to, and when you are asked if you want to use a text file on disk, just press RETURN. If you do say yes to this question, you are asked for a filename, and the system will read in the message from any text file you wish. This option is available only from the local keyboard; however, if you call from another system, you will find you have the option of "uploading" the message, that is, sending it by Xmodem or Xmodem-1k protocol instead of typing it in by hand. This gives both the sysop and the system's users the ability to write messages while not connected to the system and quickly upload them when they call. You can even read from disk or upload messages created with Wordstar (TM) without any conversion. Now, since you are not reading a file from disk, you will find yourself in the message editor. This is essentially a small word processor. Since most users cannot send cursor control information over the modem, it is not a full screen editor, but it is still very capable. Enter your message by just typing freely; words will automatically wrap at the ends of lines, just as with any word processor. If you find you have made a mistake in the message, enter /H and take a look at the various editing options available. This same editor is used to edit the system news, to send private mail, and to create descriptions for message areas. It can also be used to edit menus with the (F)ile Editing option of the operator's menu. Of course, you can use another text editor if you wish for such work, but the ability is there to let you completely edit your system when calling from elsewhere. When you have completed your message, enter /S, and it will be saved. Message saves are very quick, but the system displays its progress as it goes along; a "." appears for each line saved, a ">" for every 128 bytes actually stored to disk, and a "C" each time an old message is deleted to make room. Of course, no "C"s 10 should appear when saving this first message. Now go back and select the (R)ead Messages option. At the prompt (N)ew, (P)revious, or (S)pecific, you are being asked whether you want to see messages you have not previously read, look back a particular number of messages, or read from a specific date and time forward. Choose (N)ew, and when you are asked if you want to read (P)rompted or (N)on- Stop, press P for Prompted in order to be able to reply to messages if you wish. If you choose (N)on- Stop, you have the option of capturing the messages you read to disk instead of reading them now. If you choose (N)on- stop together with (S)pecific, you are asked exactly how many messages you want to see, since you would otherwise have to read all the way up to the present. For now, go with Prompted; you should be told that "the remaining messages are your own." This is because you entered the only message on the system yourself. Say yes to reading it anyway, and it will be displayed. After the message is displayed, you are asked if you wish to reply; if you said yes, you would be in the message editor again. The system keeps track of the message each reply replies to, so that users can read that message in order to make sense of the reply. Later on, when there are more messages on the system, you will frequently see the message, "This message is a reply. Read the original (y/N)? " which gives you the chance to look back at the message being replied to in order to understand the whole conversation. If that original message is a reply to yet another, you can step farther back, until you reach the message that started the whole "thread" or the oldest one still stored in the message database. You may note that having to answer several questions after each message is displayed is time- consuming. This is true, and there are several ways to solve that problem. First, whenever you see a prompt such as "(y/N)? ", the capitalized letter- in this case, N for no- is the "default" option, and pressing RETURN will select it. Most of the time the default matches what you wish to do. Second, instead of answering up to three questions after each message, you can go back to the main menu and select (S)etup. When you do, you will find yourself given the chance to change most aspects of your profile; you can turn off the single- key menu commands, for instance, if you frequently call from elsewhere and have problems with line noise. And you can also select the "Quick Message Menu," which displays a single prompt after each message instead of a series of questions. That prompt offers several options incorporating the three questions as well as new possibilities, and you will probably want to switch to it very early on. Now, returning to the general message area if you have left it, select the (M)anagement option. You will now see a menu offering complete control of access to the general message area. The "Individual's Access" option will allow you to select whether any 11 individual can enter the area, and if they can, whether they have "sigop" access to it. Sigops can access the (M)anagement menu, and can also kill messages; they are quite common, for instance, on systems with message areas for various computer systems, where the sysop doesn't know the topic well and decides to delegate authority. The "user's status" option will let you know what item a particular user has most recently seen in that message area, if they have accessed it at all, and how much access they have to it. The "Private Area" option will make the message area private; don't do this in your general area, of course, unless you have something unusual in mind, because new users won't be able to enter it; in a private area, users must be individually granted access to enter. In an "open area," new users can come in, but you can deny access to any particular individual if you wish. From the management menu, you can also create a new description file for users to see the first time the enter the area. This is the place to set down the rules of the area in! If they are placed in the first message, they will eventually be deleted. File Areas Now step over to the main menu again and choose the (F)ile Areas. You will be presented with a menu similar to that for the message areas, offering just "general files" at the moment. You can create more; see the section of the manual entitled "The Menuscript Language." Enter the General Files area. Again, the menu will be somewhat similar to that for a message area; but in place of reading and posting messages, there are options to upload, download and list files. (U)ploading a file is sending it from another system TO the bulletin board. If you choose (U)pload while logged on right here at the local keyboard, though, the system knows you can't be transferring a file from another computer, so it expects the file to already be in the subdirectory set aside for general files. So, if you have files you want to make available to users, copy them to the GFILES subdirectory; you may wish to do this now by pressing ESCape, then 7 for "DOS." When you have the files in place, make sure you have returned to the main BBS subdirectory, not GFILES; then type EXIT, and you will be back where you left off. When you (U)pload a file, you are asked for the file name; type it in, then enter a brief description of the file when asked for it. When a user uploads, of course, they are given a menu of different protocols by which they can transfer the file. These are (X)modem, (1)k Xmodem, (Y)modem, and (T)ext. The first three can be used to transfer programs as well as text files; the last is for text only, and not nearly as reliable. (Y)modem, unlike the others, can be used to transfer several files at one time. There is additional detail about file transfers later in the manual in the section entitled "File Transfers." 12 The (D)ownload option normally means transferring a file from the bulletin board TO a remote caller. If you use it locally, the system assumes the file is a text file, and will display it on your screen. If the file is a program file, it will display meaningless characters, so be sure the file you are displaying locally is indeed a text file. The (L)ist Files option will display a list of all the files available on the system; if you select a (D)etailed list, the name of the person who uploaded the file is given, along with the full description, filename and length. If you choose a (S)hort list, just an abbreviated description, filename and length are displayed. The (N)ew Files option serves the same purpose, but lists only files that you haven't previously listed; this is the way to look at brand- new uploads. The rest of the options in a file transfer area are essentially identical to those in a message area; the Management menu works just as it does in a message area. That's a basic guided tour of the standard Astrodome BBS system you have been provided with. Remember, it's just the barest starting point compared to what you can create yourself with the Menuscript language- the details of which follow. 13 The Menuscript Language "Menuscript" is the name I have given to the collection of commands and structures this package provides for constructing your system. I have titled it Menuscript because there are two basic types of files used: Menus and scripts. Scripts Scripts are sequences of actions much like the batch files of MS- DOS. All scripts end with the extension .SCR and are found in the MENU subdirectory of your BBS directory. One such script is executed when a user first connects with the system, or you log on locally. It is titled LOGON.SCR, and takes care of all the activities the sysop desires to take place before the user sees his first menu. Here's a sample LOGON.SCR script: SHOW WELCOME NEW NEWS READ NEW CLOSE NEW MAILPER READ NEW CLOSE GO MAIN * What's going on here? The first command, SHOW WELCOME, displays a title screen to the caller. This screen is displayed differently depending on the user's screen width; since WELCOME is given no extension, the program adds .32, .80 or .ANS, for 32- column screens (and up), 80 column screens, and screens with ANSI VT-100 graphics. In this way the user receives the most dramatic greeting his computer can display. Databases The next command, NEW NEWS, opens up the news database. "OH NO! DATABASES! This isn't Dbase II, for crying out loud!" Don't worry, I use the term database to refer to any news, personal mail, operator feedback, message, security, or file area on the system. Since it's not convenient to list all six types constantly, I decided on "Database" as a reasonable interchangeable term. Once the news database has been opened, the system is prepared to display messages within it, and so the next command, READ NEW, displays any messages the user hasn't yet seen in that database- and as a result, the caller gets a look at any announcements the sysop has made since the caller last visited. The next command, CLOSE, lets the system know that we're done working with the NEWS database. Afterward the same process- NEW 14 and READ NEW- is repeated for the "personal mail" database, which I've named MAILPER in this example. Finally, the script jumps to the main menu by executing the command GO MAIN. This causes the system to load the file MAIN.MNU and present the user with a set of options. Every script must end with an * on a line by itself to make sure the system doesn't run past the end of the file. Menus Since menus require that the user make a decision among many options, they are somewhat different from scripts. All menus are found in the MENU subdirectory of your BBS directory and have the extension .MNU. They contain the same commands, but they also contain a great deal of information controlling how options are presented, and who they are presented to. For instance, here's a sample main menu: Main Menu ECHO Welcome to the Hippimatic BBS! * (M)essage Areas M 20 GO MAREAS * (F)ile Areas F 25 GO FAREAS * (N)ews N NEW NEWS READ CLOSE * (H)elp H HELP * (S)et your Options S SETUP * (G)oodbye G BYE * * The first line of any menu is always a title. It may be left blank, but there does have to be a first line before any commands are executed. Following this are any commands you wish to execute when a menu is first loaded. In this case I've inserted a single ECHO command, which displays the message "Welcome to the Hippimatic BBS!" conceivably several more ECHO commands might follow. An * 15 always ends any series of commands. Now the actual menu options begin. Each menu option looks like this: What the User Sees Key to be pressed access level/ other requirements Commands to be executed * For instance, in the first case, the user sees: (M)essage Areas The user must press: M And the minimum access level is: 20 The command executed is GO MAREAS, which jumps to the message- areas menu; and the * ends the series of commands. Now, there are several more options that could have appeared after that "M". The first is requiring "sigop" access. Sigops What's a sigop? A sigop is a person assigned to be in charge of a particular database. This is common in message areas, where many operators of public systems choose to delegate such responsibilities. To require sigop access for an option, follow it with an "*" instead of an access level number. A database must be open for this option to be of any use, of course; it wouldn't make any sense on the main menu. It is most frequently put after an option such as (K)ill Message in a message forum menu. All users with an access level above 9000 automatically have sigop access to all databases. Otherwise, it can be granted by the ACCESS verb in individual databases. General Access Levels "General" access levels are the numbers you see following many options. These can be set anywhere between zero and 9999 for any particular user, and you can also set the access level of new users to anything you want. (Creating a private system is a simple matter of setting the new- user access level to zero, and making no options other than "Goodbye" available at that access level.) The advantage of general access levels is that, unlike private forums, they are not visible except to those with sufficient access. They suffice very well for most security tasks; if you need, however, to finely control the access of individuals to a particular area, that is when the PUBLIC, PRIVATE and ACCESS commands become useful. They are available in the sample menu system provided and fully documented in the "Menuscript Dictionary" portion of this manual. 16 A third way of controlling access to an option is the @ character. When this is placed after an option, it is available only to you, or another person logged in at the local keyboard. First of all, this is a simple way to mark of a sysop's area if you have no external assistants, don't call from outside and don't wish to deal with access levels at all. More commonly, though, it is used to link in a convenient gateway to a favorite word processor; it will only be available when you are using the system personally from home, so you can enclose a SHELL to any program you wish. Each menu must end with an additional "*". This means that, since the string of commands following the last option also ends in a "*" character, every menu ought to end with two asterisks in succession. Take a good look at the provided set of .MNU menu files, and the LOGON.SCR script file. Also, read through the "dictionary of Menuscript commands," which will explain all the commands available. Through these commands you may tie your system together in any way you wish and create a thoroughly unique system, and one more appropriate to your needs than a "standard" BBS package. Creating Databases Before you can add an additional message base or file area, create a new news area for some purpose other than general news, or create a security area to limit access to a particular portion of the system, you'll need to create a database. This can be done by using the "create a database" option on the operator's menu, in the set of menus provided with the BBS. This option makes use of the CREATE command of the menu language. CREATE will give you a choice of six types of databases. They are described below: Message Forums: Intended for open communications between users, these are standard "message bases" in the usual BBS sense. Private Mail: These databases perform much like message forums, but users only see mail addressed specifically to them. (The sysop can personally override this; see READ OTHER in the dictionary section.) File: Not a message base at all; this is a file- transfer area. File databases store the names, lengths, dates, and uploaders of files for transfer between yourself and users. The files themselves are stored in separate subdirectories. News: News databases are much like regular message forums but "ordinary" users are not usually permitted to post messages in them. Their most frequent use is as a general announcement 17 system; see the description of LOGON.SCR in the section titled "The Menuscript Language." Feedback: Intended for users to be able to send messages, but not normally read them; the usual use is as a place for users to comment to the operator. The BYE command directly posts messages in the "FEEDBACK" database, which must exist as this type. Security: Not a message system OR a file system; just the security "head" of a database without the message and file "body." These are handy for simply controlling access to a region of the board, say a game, on an individual basis rather than by general access levels. For ideas on their use see the dictionary entries for the PUBLIC, PRIVATE and ACCESS commands. Once you have selected a type, if you're creating a security databse, you're finished. If you're creating any other type, you'll be prompted for the number of records. In a file database, this should be the number of files you expect to see in that area, maximum, plus a goodly margin! If "extra" files are uploaded beyond the size you prepared room for, the listings of the oldest files will be deleted, although the physical files will still be on disk. In a database containing messages of one sort or another, each record represents 128 bytes of text. 128 bytes are always used for the header of a message; after that, it all depends on the length of a message. However, a reasonable rule of thumb is to expect about three records to a message most of the time; so if you want approximately 100 messages, use 300 records. My objective here was to let the sysop fix how much space would be used, and not have to deal with fluctuations due to the length of messages. Next it is necessary to give the name of the database. This should be an eight- letter filename (NO EXTENSION) and something you can easily remember. Now, if you're creating a message database, you're done with this stage of the job. If you're creating a file database, you must enter the pathname. This is the full subdirectory name where the system can expect to find, and place, files in this database. It is strongly recommended you create a SEPARATE subdirectory of your BBS directory for each file database. A user can download any file in the correct directory if he or she knows the filename, so make sure you use separate subdirectories! The subdirectory name must end with a \, and it is recommended that you give the full pathname from the root directory on down, like this: \BBS\IBM\ For an IBM file transfer area, for instance. 18 Make sure you actually create the subdirectory with a MKDIR command from the operating system! If it's not there the system will fail when it attempts to access it. Having created the database, you can now "hook it in" by adding it into the menus. This is not difficult to do; just look at the examples contained in MAREA.MNU and FAREA.MNU, and add it on identically. You now have a new message or file area. You will want to create a description file for it, however. Description Files Description files appear whenever a database is first opened by a particular user for the first time, and later, whenever requested by an ABOUT command. They are text files beginning with the database filename and ending in .DES. They can be created by the use of the DESCRIBE command, which is demonstrated in the sample menu set (go ahead and do this), or with your text editor. Descriptions are needed for all databases, including security. If no description is entered by the operator, the file will be created but left blank. In general descriptions provide an excellent way to let a user know what the rules are in a particular area and what the area is for. Enlarging Databases If you find it necessary later to enlarge a database, make use of the "enlarge database" option on the provided menus. This option uses the "ENLARGE" command of the menu language. Give it the filename and follow the directions to enlarge the area. This will bring your database up to size without destroying data. That's it for databases and the menu system. Go ahead and see what you can do with this section and the dictionary of commands provided. Creating a system that does exactly what you wish it to will take work, but much less than writing it from scratch. If you wish, just expand on the framework provided- if you feel the need, throw it out and just remember that LOGON.SCR must be the first script and MAIN.MNU ought to exist. Beyond that, it's all up to you. Removing Databases In order to remove a database, you must do three things. First, remove it from the menu or script that accessed it, so no user can stumble onto it after its deletion. Second, remove it from the text file BASES.DAT, which is a list of all databases on your system and is in the main BBS directory. Make sure you don't inadvertently delete other areas in the process. Finally, enter the DATABASE subdirectory and delete all the files belonging to that database- for instance, if you were to remove the general database, DEL GENERAL.*. 19 Dictionary of Menuscript Commands ABOUT The ABOUT verb displays a descriptive file that accompanies the currently open database. These descriptive files begin with the eight- letter filename of the database and have an extension of .DES. They can be edited with any text editor, or by the DESCRIBE command (see below). ACCESS The ACCESS verb controls access to a particular database. This is NOT for controlling the general access level of a user; this command is used to set (1) whether the user can enter a particular area, and (2), if so, whether they may do so with "sigop" access. AMNESTY The AMNESTY verb can be used whenever you decide to wipe the slate clean and upgrade everyone to a given level of access and daily access time. You may need to do this, also, if you were not previously using time limits at all, in which case you'll need to use the AMNESTY command to bring everyone up to a minimal level. Similarly, if you previously had the access levels of all commands left at zero and then decided to restrict new user access or just give yourself some breathing room to reduce access of troublemakers below normal, the AMNESTY command should be available on your sysop menu in order to set the bulk of users up to one level. Note that AMNESTY does NOT reduce access levels and time limits that are greater than the levels you request. BYE The BYE verb allows the user to log off properly. You may make it available on any menu or place it in a script. When BYE is executed, the user is asked if he or she wishes to make a comment to the sysop; if so, the program directly executes a NEW FEEDBACK command and a POST command in order to leave a message to the operators. However, the previously open database will be reopened if the user chooses not to log off. (Note that this verb is not always final since the user may say no, having said "goodbye" by accident!) CALL The CALL verb resembles GO in that it transfers control to another menu; however, it places the name of the current menu on a "stack." This allows the RETURN verb to jump back to the CALLing menu. CALL and RETURN allow one menu to be accessed by more than one route gracefully. They are analogous to BASIC's GOSUB and RETURN. Note that CALL should not be executed from a script, only a menu. CALLERS The CALLERS verb allows a search of the user log, in which any part of a name may be typed in and a search for that name will ensue. The system will display only user name, most recent call and first call, so this 20 command is appropriate for use by all users. CALLS The CALLS verb lets a user access the rotating log of calls. This log is maintained in LOG.DAT, and a parameter in MODINIT.DAT controls how many numbers are maintained within it. The user has the option of listing all calls since his or her last visit, or typing in the number of calls to be displayed. CHAT The CHAT verb simply reverses the screen video in order to catch the operator's attention without annoying him or her with a bell accidentally left available at three in the morning. The user is told to go on using the board in the meantime; the sysop may, as always, initiate chat whenever desired, and this command is just intended to let the sysop know a user wants to talk. CLOSE The CLOSE verb closes the currently open database. While CLOSE is automatically executed under a variety of circumstances it is recommended that your menus CLOSE a database when done with it. CREATE The CREATE verb will create a new database. This command must be used to create a new message, file, mail, news, security, or feedback area. After using the CREATE verb, of course, the database must actually be made available by inserting it into a menu. DESCRIBE The DESCRIBE verb allows the user to write a new .DES file for the current database. This is the file that appears when that database is accessed for the first time by a particular user, or when requested through the ABOUT command. This command is best made available only to operators and "sigops," individuals given responsibility for particular message and file areas. (You might also wish to create a "game- op" of a security database controlling access to an online game, for instance.) DOWNLOAD (FILE) The DOWNLOAD verb allows the user to download a file from your system to theirs. This can be done by any of three protocols at present: XMODEM, "XMODEM-1K," and Text. Text transfer simply displays the file and is intended for use only with text files containing information meant for the human eye. NOTE: If you "download" from the local keyboard the system will automatically assume a text transfer and display the file. XMODEM is an error- correcting protocol. It is featured by the vast majority of all terminal software on virtually all computers. Its purpose is to transfer files, usually programs meant for a computer's eye, without the occasional errors and uncertainties that creep into a text transfer. XMODEM-1K is a variant of 21 XMODEM that uses larger blocks. Some programs erroneously call this "YMODEM," and call true YMODEM, which I will add soon, "YMODEM-Batch." You may wish to advise users of this. Further information on XMODEM transfers and file transfer in general appears later in this manual. DOWNLOAD FILENAME- that is, the download command followed by an explicit filename in the menu or script file- forces a particular filename to be downloaded instead of prompting the user for a filename. ECHO (text) The ECHO command displays a line of text to the user. This command is useful in all sorts of situations to explain to a user that there will be a delay when loading a program, to announce the name of an area's sigop, to display a brief title screen for a message forum, or any other task that calls for text output. ECHO without an argument just displays a blank line. EDIT The EDIT verb permits the user to edit the account of any user, setting any and all parameters, including their access level, password, real name, telephone number, system name, time online, and so on. This verb SHOULD NOT BE AVAILABLE TO ANYONE EXCEPT YOURSELF AND THOSE YOU HAVE COMPLETE TRUST IN! Therefore it should be set an access level of 9999, and no one should have that access level except yourself and assistants, normally called "co- sysops." EDIT FILE (filename) The EDIT FILE verb permits the use of the system's simple text editor to edit any file. EDIT FILE without a filename is an EXTREMELY potent command and should not be available, again, to anyone other than yourself and your assistants. Be careful when typing in filenames for EDIT FILE as, although a nonexistent file can be handled gracefully, a nonexistent directory is not. If the file being edited does not exist, it will be created. If it DOES exist, the file is loaded into memory and addition to the file begins after the last line. Note that there is a 200- line limit on the built- in editor. EDIT FILE with an explicit filename simply loads a particular file and permits it to be edited. This command might be useful given to a "columnist" who periodically writes a file for the system. You also might wish to put it into your sysop menu in a form like this: EDIT FILE MODINIT.DAT, since this is a frequently edited file. The purpose of EDIT FILE is basically to allow external assistants to control all aspects of the system. ENLARGE The ENLARGE command is used to increase the size of an existing database. You may use this to make provision 22 for more files in a file area or messages in a message area. It's also recommended that you use this command if users complain of not receiving private mail, as this may mean the area is too small to suppor the number of messages being entered in it daily, if messages "roll over" too fast. The ENLARGE command should be restricted strictly to yourself and trusted assistants. FINDNEW The FINDNEW command displays the number of messages or files in a database, and the number which are new. Do not use this command in a private mail database as it will include all messages in its count, not just those for a particular user. FINDNEW is frequently executed when a message menu first loads, like READSEND.MNU in the sample set. GO (menu filename) The GO verb jumps to a different menu and begins interpreting it. Naturally it must be the last verb in a series, as those after it will never be executed. No extension should be given as .MNU is assumed. HELP The HELP command displays the file HELP.REA to the user. It is equivalent to SHOW HELP.REA. KILL (filename) The KILL verb permits messages or files to be deleted from the system. Messages can be located by the time they were entered, or through a search. Files are located by filename. Messages, once deleted, are entirely gone; in the case of files, whether or not to actually delete the file from disk is optional. Otherwise the system simply "forgets" the file, but it is still on disk and the sysop can UPLOAD it again. KILL with an explicit filename just deletes a particular file; if it does not exist, the command is just ignored. This should only be used in a file database. LANGUAGE [translation file] The LANGUAGE command will load a new language file from disk. From then on, all system prompts and messages not stored in menus will be drawn from those in this file. This command can be used to implement a multilingual BBS. It can also be used, more modestly, to support several sets of prompts; in a public- access BBS run partly for entertainment, it can be amusing to have a separate set of "humorous" or "lecherous" prompts to complement the regular set. Language files have the extension .TRA and are created by starting with the file ENGLISH.TRA and changing the text there. NOT ALL items in ENGLISH.TRA can be changed. The file COMMENTS.TRA is an additional copy of ENGLISH.TRA which explains which can be altered and which cannot. Language files should reside in the main BBS directory. LIST (NEW) The LIST verb displays a list of all messages or files in a database. This can be in either a "detailed" or "brief" format; the user selects which. LIST NEW 23 displays only those messages a user has not read, or files a user has not previously listed. LIST is most frequently used in file databases and should not be used in a private mail database. LOGON The LOGON verb is necessary only in a multilingual system. When a user logs on, the system determines whether the system is multilingual- that is, whether it supports several human languages or variations on a single language- by attempting to load a LANGUAGE.MNU file. If the system cannot find this file, it will automatically log the user on, as previous versions of this package did. If it can find the file, it will load it. This menu is responsible for allowing the user to choose an appropriate language; see the LANGUAGE verb and the section of the manual devoted to multilingual operation for details of this. After selecting a language, the LOGON verb should be executed, and MUST be executed before allowing the user beyond this point, as the user is only a "guest" until the LOGON verb is executed. When the user has finished logging on, if the system is multilingual, the file [language].SCR will be loaded, in order to provide a separate menu system for each language. If the system is NOT multilingual, LOGON.SCR will be looked for, as in previous versions. NEW [database] The NEW verb loads a new database to be accessed by the user. Databases are of the following types: Message, mail, file, news, feedback, and security. Full details about databases appear elsewhere in this manual. The database filename is required and cannot be entered by the user. POST The POST verb allows the user to enter a message. Do NOT make this command available in a file area! The results are unpredictable and wholly undesirable. Also, do not make it available in a news database to all users unless you wish all users to be able to make general announcements. PRIVATE The PRIVATE verb will take a database private. This means two things: (1) all current users, except those with sigop access or those with general access of 9000 or above, are immediately denied access. (2) new users entering the database will be denied access. After executing this verb, access must be granted to users on an individual basis. It is most useful for creating a private forum on an otherwise public system, or creating a restricted file area. When possible, use general access levels to restrict areas, as users will then not even see them as options on a menu. But when you need fine control on an individual basis of who can go where, the PRIVATE verb, combined with the ACCESS verb, fits the bill. PUBLIC The PUBLIC verb is the reverse of PRIVATE, and will make 24 a database public again. This means that (1) all users are immediately granted access, and (2) new users entering the database for the first time will be granted access. READ (NEW) (OTHER) The READ verb allows messages to be read. It should not be used under any circumstances in a file database. In a feedback database, it should be available only to yourself and your personal henchmen, assuming the feedback is intended for you. (It's also conceivable to use a FEEDBACK database to let someone else, for instance, receive feedback about a software package they provide support for on your system.) READ NEW will display only new messages. Normally the user is prompted as to whether he or she desires new messages, "specific" messages tracked down by the date and time they were posted, or "previous" messages, which is to say a given number counting back from the newest. READ NEW forces the first choice. READ OTHER is strictly for use in a private mail database. Normally, any user of any degree of access only sees private mail intended for them. READ OTHER, however, permits ALL mail messages to be read. It should only be available to yourself and your assistants as its use amounts to direct eavesdropping on private correspondence. The SEARCH verb is usually a better idea as it can be used to check up on a particular problem user and not ruin the privacy of all. RECOGNIZE (filename) The RECOGNIZE verb is equivalent to an upload at the local keyboard, in that it merely recognizes a file already existing in the current file database's directory. With an explicit filename, it forces an extension just as UPLOAD FILENAME does. This command should be used to make available a file created by a SHELLed program. REMOVE The REMOVE verb allows a user to be deleted entirely from the system. This is another command that is best made available strictly to yourself and your assistants! RESIDENT The RESIDENT verb is equivalent to the SHELL verb described below in all ways but one: The RESIDENT verb does not remove the BBS from memory. This means that, after the SHELLed batch file has run whatever programs you wish and returned to the main BBS directory, it must execute an EXIT command, rather than an ADOME command, in order to return to the board; be sure to make this change if you use RESIDENT. RESIDENT allows a much faster return to the system, but also requires more memory. In general, if you are not multitasking, RESIDENT is ideal. If you are multitasking and have less than 400k in the BBS' partition, SHELL is preferable. RETURN The RETURN verb returns to the menu which most recently 25 CALLed. If all CALLs have already been RETURNed, the program will display an error message and jump to MAIN.MNU. SCRIPT (script filename) The SCRIPT verb will execute a script file of commands; it is the complement of the GO verb, which executes a menu. SCRIPT files always have an extension of .SCR, so an extension should not be given. SEARCH The SEARCH verb allows a file or message to be tracked down by a search for a given string in the title, "From:" and "To:" fields. SETUP The SETUP verb permits the user to select various preferences- screen width, screen height, password, the use of single- key menu commands, the use of the "quick menu" when reading messages, and the use of ANSI VT100 color text. Changing names is a function reserved for operators and the EDIT command, in order to help you keep track of who is who. SHELL FILENAME (*B *T *N *W *P *F) The SHELL command executes an operating system batch file and returns to the system. This command is exceedingly powerful and constitutes the ability to exit completely from the program. The system does not remain memory- resident; it creates a file storing its current status and exits to the operating system, where a batch file created by the SHELL command takes over. A new variation on this command, the RESIDENT verb, will keep the BBS resident in memory for speed. A program executed by SHELL, normally a batch file, can do anything it desires. The only requirement is that it MUST eventually execute the batch file "ADOME," in order to return to the system by reexecuting BBS.EXE. This should be done even if the connection is broken! Naturally, it is usually necessary to pass some information about the user to the program being executed. The * parameters allow for this. *B substitutes the baud rate, as a decimal; it reports a baud rate of 0 for a local logon. *T substitutes the number of minutes remaining on line before the user's time limit expires. *N substitutes the user's name, which is always 32 characters long and padded with spaces on the right. *W substitutes the user's screen width in columns; *P substitutes the user's screen height in text lines. *F substitutes the most recently accessed filename; this could be used to permit your own software to process a file that has just been uploaded. An IMPORTANT NOTE: In a menu, the SHELL command must be the last verb in a sequence. when the program returns from the batch file the menu will be redisplayed. However, in a *script* file, the script can pick right up where it left off, even after a SHELL command. If you are performing complex processing on a file, then displaying the file, and so on, use a .SCR file instead 26 of a .MNU file, and just execute the script file from your menus with the SCRIPT command, then return to the menu with the GO command at the end of the script. Further details on executing other programs follow later in the manual. SHOW FILENAME The SHOW command displays a file to the user. If an extension is given, the file is assumed to be a text file. (The extension can be a solitary . if you wish.) This means it will be word- wrapped, and page breaks will be displayed. If no extension is given, the file is considered to be a "picture" file, such as a welcoming screen for the system. In this case, the system will substitute one of the following extensions: .32, .80, and .ANS. The .32 file is displayed to users with a screen width below 80 (widths range down to 32 columns). .80 is displayed to non- VT100- compatible users with 80- column screens. .ANS is shown to those with VT100/ ANSI color and cursor positioning capability. If you do not wish to separately support these, use duplicates and just create one file, copied to the other two extensions. It is recommended that .80 and .32 be supported, however, unless you have no users under 80 columns whatsoever. 80- column screens look miserable to 40- column callers. STATUS The STATUS verb prompts for a user's name; when this is given, it reveals (1) whether the user has ever accessed the current database, (2) their degree of access (none, normal or sigop), and (3) the most recent item listed, read or downloaded by that user. This command is useful for sigops trying to determine who uses their forum or file area regularly. TIME The TIME verb displays the daily time limit, time used so far and time remaining for the current user. UPLOAD (filename) The UPLOAD verb allows a user to transfer a file to your computer. As with the DOWNLOAD verb, XMODEM, XMODEM- 1K, and text transfers are available; see the DOWNLOAD verb for details, as well as the separate section on file transfers. UPLOAD with an explicit filename forces the uploading of a particular file, and forces the title the user would normally enter to "automatic upload." This is generally for use in applications where a file is being uploaded, then processed by an external program with SHELL, then displayed, and so on. UPLOAD, when used by the sysop at the local keyboard, simply recognizes an existing file in the subdirectory ssigned to a file database. It is, in this case, equivalent to RECOGNIZE. 27 File Transfers File transfers are the transfer of programs, data files, documentation, pictures, and so on from an external user to your system. They are done in file databases, which work much like message areas except that they are intended for the transfer of files instead of messages. When a user sends a file to your system, this is known as an upload. When a user receives a file from your system, this is known as a download. If you are running a public- access system, maintaining a steady flow of uploads is probably one of your goals, and the best way to do this is by giving credit to users who upload files. The program allows for this by providing a "time ratio;" when you use this option, you can give back any number of minutes for each minute spent uploading. If you wish to set this up, see the section on initialization. The general nature of databases, and the rules of uploading and downloading, are described elsewhere (see the dictionary entries for the UPLOAD and DOWNLOAD verbs). However, some information on what you will see when a transfer takes place is in order. During a text download, you will see the file just as the user does, since the user is simply "reading" the file. During a text upload, you see nothing; but the system is alert and will give up on the attempt if the user stops sending for too long. During an XMODEM or XMODEM-1k transfer, you'll see a constant record of the transfer in progress. Here is an example of a typical XMODEM transfer of a short file, if a user is downloading: N......C....C..........C.......Transfer complete. XMODEM moves information in 128- byte blocks. Eight blocks represent 1k of the file. The system displays a "." for each block that is successfully received, and coincidentally a full line of dots across your screen is exactly 10k, a handy yardstick to figure out how far along the transfer has gone. If an "N" appears, this means a "NAK"- a character meaning "negative acknowledge-" has been received. This means noise crept into the transfer, and a block had to be resent. It does NOT mean the file is damaged; the point of XMODEM is to correct such errors by resending the blocks. Ten consecutive errors, however, will abort the transfer, on the assumption that the connection is just plain awful and transfer is not practical. However, you may see the letter "C" instead. This also means a bad block has been received, but the other system is using a better error checking system known as CRC. (Most XMODEM systems now do this.) 28 You will normally see one N or C at the beginning of every transfer; this is normal and just part of the stabilization that begins the transfer. XMODEM-1k is not much different. Under XMODEM-1k, blocks are 1024 bytes- 1k- in size, instead of 128 bytes. These larger blocks take more time to transfer, but because the system is not frequently waiting for acknowledgements between blocks the transfer is somewhat faster and more efficient. At the end of the transfer, a few 128- byte blocks will be sent to "finish up." Uploads are similar, except that you will not see an initial "N," and there will be occasional "?" characters when a meaningless character is received from the far end. In general, XMODEM and XMODEM-1k transfers are very robust at this time. A few Apple users have complained of difficulties; these users were using an older version of a commercial package called ProTerm, and evidently the problem lay there and has since been repaired. Other than this there have been no recent problems with the "XMODEM engine." Again, XMODEM-1k is often erroneously called YMODEM, and you may wish to inform users of this so they will be aware that they have XMODEM-1k support under the wrong name. YMODEM, sometimes known as "Ymodem- Batch," is essentially a version of XMODEM-1k with the power to transmit more than one file at once. When a YMODEM transfer is in progress, you will see separate transfers for each file displayed, and in an upload the filename and length of each incoming file will be displayed. Sometimes the length will not be available or will appear ridiculous if the program uploading to the system does not support Ymodem well, but the filename will always be available, and the system does not "trust" the file length sent, so this is harmless. Multilingual Operation The Astrodome BBS Software now supports multilingual operation. It is possible, by translating the supplied ENGLISH.TRA file, to run the system in an alternative language, or to offer several languages on- line. If you wish to run a single language other than English, you must do the following: 1. Print out the file COMMENTS.TRA supplied with the system. This file contains an edition of ENGLISH.TRA that contains numerous comments explaining which of the prompts stored in ENGLISH.TRA can be changed, and which are internal information used by the program itself. Following these instructions, translate all texts in ENGLISH.TRA into the language of your choice. Call this new 29 translation file by an appropriate name- SPANISH.TRA, for instance. Work from a backup, of course. You may eventually want to run the system multilingually. 2. Edit your MODINIT.DAT file; see the earlier section of the manual concerning this. The last three lines of the file contain the system password, which can be blank, the number of data bits, and the default language, which is the language used in a single- language system. If the language you are working in requires the higher ascii codes, try 8 for the number of data bits; otherwise, this line should contain 7. The last line should now contain the name of your new language file instead of ENGLISH; if your translation file is SPANISH.TRA, this line should contain SPANISH as the new default language. 3. Translate your .MNU, .SCR and .DES files found in the database directory. The actual menuscript commands contained in your .MNU and .SCR files can be changed, but only if you have been careful to translate them all at every occurence in the .TRA file. You may wish to leave these commands in English as they are never seen by callers. If you wish to operate a multilingual system, the process is similar to that above. However, you must create a separate .TRA file for each language you wish to support, and your default language, set as above, should be your own preferred tongue, as this is the one that the system's title screen will be displayed in. In order to make your system multilingual, you will need to create a LANGUAGE menu, LANGUAGE.MNU. This menu must permit each user to select a language through the LANGUAGE verb, described in the Menuscript dictionary; it should then execute the LOGON verb, as the user is not asked for his or her name and password until the language has been set. When the LOGON verb has finished logging the user is in, it will jump to an appropriate .SCR file for the language the user has chosen- SPANISH.SCR if the language is SPANISH, ENGLISH.SCR if ENGLISH, and so on. These files can be simple copies of LOGON.SCR, but they should of course be translated into the correct tongue. However, ideally each should jump to a separate set of menus at the end- a main menu for each language, with submenus of its own. This allows the sysop to create a completely multilingual system, and offer separate message areas for separate languages, or clearly identify which areas are shared in common. In addition, multilingual systems must have the following files for each language: Single- Language Name Multilingual Name HELP.REA [language].HLP EDITOR.REA [language].EDI NEWUSER.REA [language].NEW 30 Personal Extensions Personal extensions are a feature of the program provided in order to ensure that users can upload files with unique filenames- if your system is receiving forms from them, processing them, returning results and storing those results for later perusal, for instance. They work as follows: Whenever an upload or download is attempted, if an extension of # is given, the system will replace the # with a three- letter code based on the user's internal account number. This code will always be unique to the user unless that user is deleted, in which case the sysop should make certain all that user's files are deleted as well. Basically, the way to use them is like this: Let's say you want to receive a standardized form from a caller, by way of a file upload. Then the following would work: UPLOAD FORM.# SHELL PROCESS *F RECOGNIZE RESULT.# DOWNLOAD RESULT.# First, UPLOAD FORM.# would delete any previous FORM file belonging to that particular user; then it would allow a file transfer of the form. Second, the PROCESS batch file would be executed by the SHELL command, allowing an external program to process the file. The *F option attaches the filename to the command line, so the external program knows what file to expect. Finally, after returning from the PROCESS.BAT file, the RECOGNIZE command makes the system aware of the RESULT file created by the external program, and DOWNLOAD RESULT.# permits the user to download the report of the PROCESS program. Exiting to External Programs Exits to external programs are a primary feature of the Astrodome BBS Software; your system can run another program without any memory overhead whatsoever, then return to the BBS. An external program has access to all information about the current user, and can even change that information if necessary. All of this is accomplished through the SHELL verb, which is described in the dictionary of commands. A new command, RESIDENT, performs as SHELL does but keeps the BBS in memory for speed. You may use either depending on your memory resources. However, beyond the parameters of the SHELL verb, there is another way of transferring information to an external program if you must have access to EVERYTHING; and that is the "user status file," the name of which is usually EXTERNAL.DAT, although you can set it in MODINIT.DAT. This file contains a complete image of the user's account containing everything except access information about databases other than the one currently open. If you need only pass information to your program and aren't planning to tamper with the user's account, just go ahead and use 31 the parameters offered by the SHELL verb; they are more than adequate. If you need more, however, here is the structure of EXTERNAL.DAT, generated by both SHELL and RESIDENT: EXTERNAL.DAT is a sequential text file. Each line is delimited by a carriage return and line lengths are not fixed. It is very convenient to read with a compiled BASIC language, and reasonably convenient with other languages. It contains the following: User's Name Password Phone Number Real Name The above are all individual lines of text. The following parameters follow on the next line, separated by commas and represented by decimal numbers: Last Call Date/Time, Screen Width, Flags*, First Call Date/Time, Access Level, Unused Argument, ANSI (2- on, 0 or 1- off), Record Number in User Log, Local/ External flag (1- local, 2- external), Baud Rate, Lines on Screen, Current Line in Current Script, Callers as of Last Visit, Time Limit in Minutes, Time Used in Minutes as of start of call, Seconds Used in this Call, Time Warnings Received, Date of last Time Check, Seconds Available this Call, current option in currently open menu, number of command presently being executed in that menu. *: The flags are individual bits in this number. The "ones place" is expert mode, on or off; "twos" are single- key input, on or off; "fours" are right justification, on or off; and "eights" are quick message menu, on or off. (Additional text lines following:) Name of Current Menu Chat Request Status (1=on) Database Open? (Contains "Open" if so) Current Database Most Recenly Entered Filename CALL/RETURN Stack (names of menus, most recent first) Current Language NOTE: If there is no user online, the user status file simply contains the one line "Not External." This cannot be mistaken for a name because it contains lowercase; names are all- uppercase. Working with the user status file is a messy and potentially unpleasant job, particularly if you must write it back out afterward if you're making changes. But it does give you complete access to the entire user account. It's unlikely will need this degree of access, fortunately, but it's there if you need it. It is possible to determine the path of the current file 32 database, if one is open, by reading the name of the currently open database, then opening the file basename.PTH, where "basename" is the currently open database. This file will be a one- line text file containing the full path and is found in the DATABASE subdirectory. A further note on shelling: One thing your DOS manual may lead you to attempt is the use of the CTTY command to redirect I/O to the modem and therefore give an external user control of a program not written to drive the modem. DON'T. I can't stress this strongly enough. CTTY gives the external user complete control- including the ability to press CONTROL-C while the batch file is running and run amok in the operating system! It also denies the sysop any means of viewing what is going on. There are other programs available that redirect I/O without blinding the operator and without giving the external user absolute power. The only time you may wish to use CTTY is in providing YOURSELF or a VERY trusted assistant with an exit to the operating system. If you want to give an external sysop, or yourself when calling from elsewhere, an exit to the operating system, do it like this: SHELL CTTY COM1: (Note: COM1: Should be changed to the particular COM port you are using, of course.) This will grant the user access to DOS and allow him or her to operate the system completely- while in DOS. Do NOT try running programs that use anything other than totally plain- vanilla teletype input and output while using CTTY; they will run to the screen, and since you're not at hand the system will be stuck. Remember, if you create such an exit, you must reexecute ADOME.BAT in order to get back to the board- type ADOME, in other words, and move to your BBS subdirectory first unless you've set up a PATH to ADOME.BAT and added a line to it to return to your BBS directory, which is recommended. Ansi Graphics The latest version of the Astrodome BBS Software can now display virtually any ANSI graphic file. This is now true because all screen I/O is being sent through DOS. This is slightly slower but it ensures that you will be able to display any ANSI information you like. ANSI graphics are a standard permitting full- color text to be displayed, and the cursor moved freely. Surprisingly good results can be had when designing title screens with ANSI. Despite the name, "ANSI graphics" have nothing to do with actual graphics; the standard concerns itself strictly with text. However, the upper half of the ASCII set, those codes from 128-255, include many useful graphics blocks. Most sysops of public systems assume that those who have ANSI support also have IBM compatibles, and can display these graphics. This is frequently true, but not 33 universally so. The choice, of course, of whether to use them is yours. ANSI editors are widely available on many public- access bulletin boards. You will first want to create WELCOME.ANS and GOODBYE.ANS, the ANSI welcome and goodbye screens specified by the supplied BBS menus. Those running commercial terminal software are often those who can't display ANSI, surprisingly enough. The most common IBM terminal package among users of public- access bulletin board systems seems to be ProComm Plus, from Datastorm Technologies, which is a commercial package with its roots in the BBS shareware community. This package will perform well with ANSI as well as other features of the BBS and is recommended. The system does not permit users who upload messages to incorporate ANSI graphics in them. This is because ANSI graphics in the message base would prevent users without ANSI from reading the messages properly. Worse, it is possible to create a "trojan horse" message with ANSI by including codes that redefine the keyboard to type destructive DOS commands. Multitasking In general, this package is very cooperative with multitasking. It will behave well in a partition of DoubleDOS and is very comfortable in a small section of RAM; presently the requirement is approximately 240k of memory. This remains true despite the SHELL function because the system exits from memory entirely while a SHELL is running. Only the "exit to terminal" option requires more memory, because the BBS remains resident. The previous caveats have been removed. The system should now be able to cooperate with another program written under Microsoft's Quickbasic (tm), and will no longer "bleed" its video display into another task's screen, as all video display is now being sent through DOS "politely." DOS Problems So far there has been only one: A beta site running the program under DOS 3.3 ran into repeated "Stack Overflow" errors. If this happens to you, incorporate the following line in your CONFIG.SYS file: SHELL=COMMAND.COM /P /E:1024 Fossil Drivers This package previously relied on a fossil driver, which is a small resident program that takes care of all actual communications through the modem. I have eliminated the use of such a driver in this version. If, however, you have non- standard MSDOS hardware and are interested in being able to run the package, contact me concerning a fossil- driven version if 34 you can find or create an appropriate fossil driver for your system. File Structures (For those who MUST know) For those who absolutely must know, here is the structure of the USERLOG.DAT file located in the main BBS directory, by popular request. (This file contains the status of each user and is used as a pointer to additional information. Those not interested in writing programs that directly "play games" with the user log can skip this. If you really need to read it, you know who you are!) Each user's record consists of 128 bytes laid out as follows: 32 Bytes: User Name (uppercase ascii) 16 Bytes: User Password (uppercase ascii) 8 Bytes: Date/ Time of Most Recent Call (note 1) 2 Bytes: Screen width (two- byte integer) 2 Bytes: Personal Setup Flags (note 2) 32 Bytes: Real name (uppercase ascii) 4 Bytes: Date/ Time of First Call (note 3) 2 Bytes: Minutes per day (two- byte integer) 2 Bytes: Access Level (two- byte integer) 16 Bytes: Phone Number (ascii) 4 Bytes: Callers as of last call (four- byte integer) 2 Bytes: ANSI flag (note 4) 2 Bytes: Lines per screen page (2- byte integer) Note 1: Date/ time values are stored as four- byte long integers, keeping time down to the one- second level. Theoretically they represent seconds since January 1st, 1986, but assume 32,140,800 seconds per year, whether it is a leap year or not; a few "padding days" are added, and months are assumed to be 2,678,400 seconds long. This means that there are "times" that will never be recorded, but it's easier to keep track of and accomplishes the simple objective of storing any possible date in a four- byte integer. In this case eight bytes are reserved; the extra four are free space for future use as I previously used double- precision floating point variables for the same purpose. Note 2: The flags are individual bits in this number. The "ones place" is expert mode, on or off; "twos" are single- key input, on or off; "fours" are right justification, on or off; and "eights" are quick message menu, on or off. Note 3: A date/ time value stored just as in note 1. Note 4: This integer contains a "1" if ANSI is NOT supported, a "2" if the user does have ANSI, and a "0" if the state of ANSI support is not known. "0" should no longer appear. Additional flags will eventually appear here for other terminal emulations. 35 Revision History Version 1.0 was the first general release; at this point I had just added support for Ymodem multiple- file transfers. Version 1.01 corrected a bug in the database- adding code of BBS.EXE. Version 1.02 added nonstop message reading, a name- check in private mail areas, the CALL/RETURN commands and various minor revisions and corrections. 1.02 also added extensive revisions to this manual. Version 1.03 added uploading and downloading of messages, the ability to send private letters to multiple users without using any additional space, and the "Using the Supplied System" tutorial section of this manual. In addition, the CALL command can now be used in the midst of a string of commands in a menu. It also corrected bugs in the upgrading of a user's time on line and added the "file structures" section of the manual for true masochists- that is, programmers. Version 1.04, not released to the public, eliminated the use of the fossil driver. Version 1.10 added multilingual operation, the LANGUAGE, LOGON and RESIDENT verbs, a great number of minor improvements and fixes, and additional material in this manual. 36