The Astrodome Bulletin Board Software

Version 1.10

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.

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

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

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.

"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.

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.

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

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.

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!

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

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

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."

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.

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

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 *

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.

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

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.

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.*.

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

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

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

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

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

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

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

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.

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.)

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

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

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

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

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

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

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.

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.