Category : BBS Programs+Doors
Archive   : WAF165.ZIP
Filename : DOS.DOC

Waffle/DOS Reference Manual - Version 1.65
(C) Copyright 1992 Darkside International, All Rights Reserved.

C O N T E N T S

I Installing the DOS Version
II Setting up the Modem
III Troubleshooting Under DOS
IV The Scheduler
V Function Keys & Terminal
VI Support for FAX
V Multitasking and LAN's

I N S T A L L I N G T H E D O S V E R S I O N

It is stongly suggested you read or at least review this
entire document before proceeding (and its companion document,
MANUAL.DOC; information on some of the more obscure options
will be found there.

If you have the Unix version of Waffle, please see the
document UNIX.DOC, "INSTALLING THE UNIX VERSION".

1. System Requirements for the DOS version

o IBM XT or AT compatible computer with at
least 512K of RAM.

o Hard drive; the size depends on whether you are getting
any Usenet newsgroups, and how many groups.

o Hayes compatible modem; one that uses the AT
command set.

o MS DOS 3.3 or later. Versions of DOS from 3.0
to 3.2 can be used with minor changes to .BAT files.

2. Create Required Directories

Most people install Waffle in C:\WAFFLE, and this is
how the default version is distributed.

Following are the default locations for the directories;
you don't have to manually create this if you are unpacking
using the PKZIP -D option:

C:\WAFFLE C:\WAFFLE\INFO
C:\WAFFLE\ADMIN C:\WAFFLE\MENUS
C:\WAFFLE\BIN C:\WAFFLE\SYSTEM
C:\WAFFLE\DOCS C:\WAFFLE\TEXT
C:\WAFFLE\EXTERN C:\WAFFLE\UUCP
C:\WAFFLE\HELP C:\WAFFLE\WORDS

Some additional directories are also required. If you
run a small system, you might put them under C:\, otherwise
it may be a good idea to place them on another drive.

Create the following directories:

C:\TEMP A place to put temporary files
C:\FILES The FILES section goes beneath this
C:\USER User's individual files

If you are going to be using UUCP or Usenet under DOS,
create a spool directory to store files before they are sent
to other systems:

C:\SPOOL UUCP spool directory

3. Unpack Files in Their Respective Directories

Using PKUNZIP (Phil Katz's ZIP archive utility) or
compatible program, unzip the WAF165.ZIP file that was
included with the Waffle distribution. Use the -D
option (create directories) or equivalent.

PKUNZIP -D WAF165.ZIP

Note that the -D must be uppercase.

4. Configure Directories in Static File

Waffle's main configuration file is the "static file"
which can be found as C:\WAFFLE\SYSTEM\STATIC.

If you placed the directories anywhere other than
the default locations (such as setting the main Waffle
directory to D:\WAFFLE) you must change the
configurations in the static file:

files : C:\FILES
spool : C:\SPOOL
temporary : C:\TEMP
user : C:\USER
waffle : C:\WAFFLE

Waffle's configuration files are distributed in such
a way to make installation on drive C: easiest.

5. Tell DOS About WAFFLE

Place this line in your AUTOEXEC.BAT file. This points
to the startup file which you will configure. There must
be no spaces on either side of the = sign.

SET WAFFLE=C:\WAFFLE\SYSTEM\STATIC

Alter your PATH to include the C:\WAFFLE\BIN directory.
Most people already have a PATH set in their AUTOEXEC.BAT;
but in case you don't, here's an example:

PATH C:\DOS;C:\UTIL;C:\WAFFLE\BIN

While you're at it, lines similar to these should be
present in your CONFIG.SYS file:

BUFFERS = 48
FILES = 20
SHELL = \COMMAND.COM /E:1000 /P

6. Try logging in

Reboot DOS (to rest your PATH) and type LOGIN. Waffle should
display a banner message something to the effect of:

elf.santa-cruz.ca.us (elf)

Test UUCP & Mail site,
Elf Consulting, Santa Cruz CA.

Waffle version 1.65, out of the box.

Login or NEW:

At this point, Waffle is requesting a username and password.
The default "factory configuration" password is:

Login: system
Password: system

This is a "privileged" system account. Login with it.
A welcome message will be displayed, and you will find yourself
at the "main Waffle prompt".

Poke around for a while.

7. Get WAFFLE to Answer the Phone

This section is required only if you will have dialup
access to Waffle (either by UUCP sites or BBS users).

Edit the static file, C:\WAFFLE\SYSTEM\STATIC. Set
the "device" entry to your COM port (1 or 2), and the
"speed" entry to the highest baud rate your modem
supports (such as 2400):

device : 1
speed : 2400

From the DOS command prompt, type RUN. The top status bar
should appear, your modem should initialize and the following
messages should display:

Calls: 0

Awaiting Call..

If this does NOT happen, (for instance, if the first line
was printed but not the second), refer to the section
"SETTING UP THE MODEM" later in this document; this will
tell you how to change the "AT" string sent to initialize
the modem, and other important information.

Have someone call the modem number. You should see:

Calls: 0
Awaiting Call..Ring..

[connect 2400]

8. Choose a NODE name for your system

Choose a short name for your system. Valid characters
are "a" through "z" and "-" (dash). It should describe
your system in some manner, or it can be a silly name.

If you are not connecting to outside systems, it does
not matter what your node name is.

If you intend to connect to the UUCP network, you
must choose a nodename that hasn't been used. (Ask
someone on the network to check for you.)

Some examples of node names:

Elf Consulting elf.UUCP
The Muffler Palace muffler.UUCP

Edit your static file C:\WAFFLE\SYSTEM\STATIC and
set the "node", "alias", and "uucpname" parameters to
match your hostname.

The "alias" is any alternative name by which
your system might be known.

o Normal UUCP-only site:

node : elf.UUCP
alias : elf.UUCP
uucpname : elf

o Site *REGISTERED* within the .US domain:

node : elf.santa-cruz.ca.us
alias : elf.UUCP
uucpname : elf

o Site *REGISTERED* within a domain:

site : oval.white-house.gov
alias : oval.UUCP
uucpname : oval

If you are not in a registered domain, DO NOT USE anything
except a name ending with .UUCP as your NODE name. Mail
software WILL NOT DELIVER any mail to unregistered domains.

The .UUCP domain is an unofficial domain for UUCP sites,
and it is recognized by most hosts.

9. Define your ORGANIZATION

Edit the "organ" entry in the static file,
C:\WAFFLE\SYSTEM\STATIC.

Set it to the name of your company, school, BBS, or
whatever organization that operates the system. It
should not be a person, as it is used to display the
originating system for messages sent over a network.

Examples:

organ : The Dark Side +1 408 245 SPAM
organ : Central Intelligence Agency, Langley, VA
organ : Thespian Institute, Poughkeepsie NY

10. Define your SMARTHOST

If your system is connected to the UUCP network, it
should be possible to define a smarthost for which to
send mail that isn't addressed to your neighbors.

This smarthost can choose to send it to its smarthost,
etc. If you connect to only one host, you can probably
define it as your smarthost:

smarthost : ozone

Normally this will be a neighbor one hop away, and that
neighbor will either be a Unix site running pathalias,
or an Internet site. However, remotely connected sites
may define the SMARTHOST to be a "bang path" (a bang
is a ! sign) in which case addresses will be rewritten
to direct it towards the smarthost:

smarthost : ozone!jammin!rutgers

11. Configure the message base ("LOCAL" and "USENET") files

In the C:\WAFFLE\SYSTEM directory, two files may contain
message base information. These are "LOCAL", for local
boards, and "USENET", if you receive a Usenet newsfeed. The
structure of both these files are identical. See the
section in FORUM.DOC concerning Forum Configuration for
information on the more esoteric options.

You should try to modify what's currently in these files
rather than attempt to build your own.

12. Set Timezone

The time zone, also in the static file, consists of
three fields -- your timezone, the number of hours West
of Greenwich, and the daylight savings time zone, if
there is one. Set these according to your timezone:

timezone : PST 8 PDT (for US Pacific Time)
timezone : EST 5 EDT (for US Eastern Time)

If your area has no daylight savings, omit it:

timezone : GMT 0

13. Edit system's text messages and menus

You will want to customize the various text messages and
menus, especially if you run a BBS. Some files that you
should customize are..

In /waffle/text:

entry Banner printed before login
logout Displayed as user logs out (not provided)
newusers Message printed to new users once
welcome Welcome message, right after logging in

In /waffle/menus:

main Main menu for ? command

In /waffle/help/forums:

menu Forum Main menu
local Local message bases
usenet Usenet newsgroups

There are many others; the above just the most visible.


S E T T I N G U P T H E M O D E M

This section applies to the DOS release only, and only if you are
using Waffle to answer the phone. Under Unix, getty or an appropriate
replacement supplies these functions.


For the Hayes 2400 and compatibles:

initialize : AT H0 M0 S0=1 V1 E0 X4

Previous versions of Waffle required operation in E1 V0 mode, but this
is no longer the case. You may operate in any mode, and it does not
matter what the Ex Vx settings are - use whatever seems to work best,
or what you are used to.

Special characters that may appear in modem sequences:

| Send a carriage return, useful if you need to
send more than one init string. Use of this may or
may not confuse Waffle, depending on invokation.

^ Set DTR high, and wait 1/10th of a second.

v Bring DTR low, and wait 1/10th of a second.

~ Delay of one second. You may need to place this as
the first character of your init string, if your
modem has a tendency to be unready at startup.

` A short delay of 1/10th of a second.

If a FOSSIL driver is detected, it will be used. If you are using a
high speed modem - say the HST or a Telebit - you would be foolish not
to use a FOSSIL. We recommend the BNU driver which is available as a
"terminate and stay resident" program.

Modem speed may be locked at a specific rate by adding a line

locked : 19200

to the static file. Some FOSSIL drivers will allow you to lock the
modem speed as well; we suggest using both.

The most common rates to lock at are 19200 and 38400. Locking is
mandatory when using a compression technique such as MNP or V.42, and
a "Very Good Thing" when operating a high speed modem.

If you are having problems with the modem, try starting up using the
'debug: modem' option in your static file. This will give some extra
information regarding the modem and its working with Waffle.


T R O U B L E S H O O T I N G U N D E R D O S

o The program gets to "Calls: xxx" but not to
"Awaiting Call" during initialization sequences.

An incorrect AT string may be the problem. Check modem manual.
This may also be due to initialization at an incorrect modem
speed, or at a COM port that is not configured. In the static
file, you should generally set speed: to the highest rate your
modem is capable of.

o The modem won't hang up.

Your modem must disconnect the line when DTR is dropped. Some
modems require an &Dx or &Cx sequence; others will require
flipping a small DIP switch inside or at the back of the modem.
If neither of these is the case, throw your modem from a tall
building (we recommend the Oakland Hyatt Regency).

o Program starts up with endless "Login or NEW: : : : : : : "

Your modem is not sending the carrier detect signal as it should.
It *must* tell the computer the proper DCD (data carrier detect).
This may be an &Cx or &Dx sequence, or another DIP switch.

99% of modems support proper DCD in some configuration. Waffle
needs a proper DCD signal in order to answer the phone.

o Program behaves in a bizarre manner when I type keys.

You may have an incompatible TSR installed in your AUTOEXEC
file. Remove all TSR's and see if the problem remains. CED and
HISTORY are known to work correctly, so don't worry about them.

o Incoming UUCICO sessions (FOSSIL) have bogus baud rate.

Certain FOSSIL drivers do not keep the baud rate properly
between terminating Waffle and starting up UUCICO. You will
need to supply the -b parameter to UUCICO to pass the baud
rate instead. The best way to do this is to modify the "Shell"
account attribute with the "ADMIN S" command:

Shell: $uucico -r0 -b%b

The $ passes the command to DOS while exiting WAFFLE.EXE,
to keep the maximum amount of memory available.

Don't do this unless you really have to. If you are using the
native driver, there is no need. We have noticed that some but
not all FOSSIL drivers don't behave as expected.

o I am running DOS 3.2 (or worse) and RUN.BAT isn't cycling.

There are CALL statements in RUN.BAT. The CALL command will run
another batch file without terminating the current one. This
behavior can be approximated with DOS 3.2 by replacing

replacing :POLL (in RUN.BAT)
CALL POLL
GOTO TOP

with :POLL (in RUN.BAT)
POLL

and adding a "RUN" statement to the end of POLL.BAT. Additionally,
with CRON, batch files that you call should end in RUN as well.

o Will WAFFLE multitask under DOS?

It is sometimes possible to run multiple copies of Waffle under
a Multitasker such as DesqView or Windows. See the "MULTITASK"
parameter in the STATIC.DOC file.

Previous versions of Waffle made no attempt to multitask under DOS.
We have made 1.65 WAFFLE.EXE network and multitasker aware. However,
in this version there are things that you still should not do. For
instance, only one node should be running UUCICO or UUXQT at one time.

Also, if you are running on a single machine, a FOSSIL driver
is highly recommended (and sometimes required.) This is because two
individual partitions cannot share the same interrupt easily.

If you absolutely must use DOS for a multiple dialup BBS, we
recommend individual networked machines each running a copy of Waffle
rather than multitasking on a single machine.

o I get the message "[ Echo shouldn't be on - waaah! ]"

Your modem initialization string contains no E1 and yet
the modem is echoing back your AT sequence. This message should
never happen (and if it does, it isn't Waffle's fault.)
This is a rare error but it does occur.

You can put an E1 in your initialization string, or play
with E0/E1/V0/V1 settings. Waffle tries to accept anything
reasonable. Another thing to try is a leading ~ (tilde)
at the beginning of the string.

o I'm running Waffle as a door (yuck) and it drops carrier
when I type BYE. How can I avoid this?

Place in your static file the line

disable: BYE

Also, you can include any other synonyms for BYE that you
might use, such as LOGOUT or LOGOFF.

Then, define an alias for BYE in /waffle/extern/bye:

/exit=15 /logout=BYE

The "/logout=BYE" places the word BYE in the caller list, so
you might make it something like "/logout=RET" to indicate
that they returned to the calling program.

Your batch file must then process the exit code.

Actually, a better idea might be to define a RETURN command
that does the return, and have BYE continue to drop carrier.

o When returning from externals, the system isn't working.

Certain external programs mess with the UART settings and
then don't undo the damage when they exit. This is incorrect
behavior and is a serious bug in the external program.
Certain versions of DSZ are apparently subject to this problem.

If you're running a FOSSIL driver, some FOSSIL's will allow
you to reset the UART with a command; you can do this before
returning from a Waffle external (in a batch file.)

For instance, the BNU driver has a /i+ switch that may help.

o I am running 4DOS or Norton NDOS and addresses with %'s act funny.

The 4DOS shell is reading the text following %'s as DOS environment
variables, and substituting the translations. Thus x%y@z is being
read as x@z (since "y" is probably not a valid environment variable,
it's replaced by the null string.)

Solution is not to use 4DOS is you have lots of %'s in addresses,
or replace x%y@z with y!x@z, or use a full domain address.

o Get "can't set initial newsgroup" message, and Waffle exits.

Change or set the static file parameter "general:" to the name of
a newsgroup that your system carries.


T H E S C H E D U L E R

o Purpose of the scheduler

It is sometimes convenient to have Waffle execute certain DOS
commands at various times during the day, for such tasks as
polling neighboring hosts, optimizing the hard drive, or trimming
the log files. Any DOS command may be executed in this manner.

Upon startup, Waffle will read the schedule file, which is
normally C:\WAFFLE\SYSTEM\SCHEDULE, and check this to determine
if there are any pending commands. If any are found, they are
written to a file CRON.BAT and Waffle exits to execute them.

Hourly events are considered "too old" if the hour has past
and Waffle hasn't gotten a chance to execute the event. Daily
events do not expire until the following calendar day.

Waffle is not distributed with a SCHEDULE file installed; however
there is a sample present as C:\WAFFLE\SYSTEM\SCHEDULE.EX file.

o Format of the schedule file

The schedule file consists of five fields, followed by a DOS
command. All five fields are integers, and they correspond to:

#1 Minutes: a number 0 through 59, the
number of minutes past the hour.

#2 Hours: a number 0 through 23

#3 Day: a number 0 through 31, corresponding
to the calendar day of the month.

#4 Month: a number 1 through 12, matching
January to December. Not used much.

#5 Day of Week: a number 0 through 6,
corresponding to Sunday through Saturday.

Whenever a field is not used, a "*" should be left in its
place to signify that any time is ok (a "wildcard").

For example, to execute a command 10 minutes past every hour,
all fields are wildcarded except the "minutes" field.

10 * * * * uupoll

To execute a daily event, both the "minutes" and "hour"
field are set to the desired time:

29 17 * * * echo "the 5:29 pm alarm!"

o Esoterica

The syntax of this file is difficult.

Multiple entries in fields (ie "10,20 * * * * uupoll" are
not currently supported.

Users will NOT be kicked off to handle events; Waffle will
wait until they have logged out.

Events that are too "old" are not executed.

If you are running CRON to invoke multiple batch files scheduled
to run at the same time, you should prefix them with a CALL
statement, such as "10 * * * * call uupoll". This is because DOS
batch files chain instead of spawn (a poor Microsoft decision).


F U N C T I O N K E Y S & T E R M I N A L

Available in the DOS Version only, these local keys may be hit at almost
any time. Some keys cause windows to appear. To see this list, hit F1.

ALT-B Change modem speed F1 This menu
ALT-C Enter chat. ^D to exit F2 Local login
ALT-E Change FULL/HALF duplex F3 Remote user login
ALT-H Hang up phone F4 Next call
ALT-J Operating system SHELL F5 Give user the boot
ALT-P Change transfer protocol F6 Switch 8N1 7E1
ALT-Q Quit program F7
ALT-T Toggle SYSOP mode on/off F8 Control show on/off
ALT-U Online user profile editor F9 Backspace ^H/DEL
ALT-V Validate current user 10 Terminal mode

END Increase time allotment
UP Upload file (C) Copyright 1992 Darkside Int'l
DOWN Download file PO Box 4436 Mountain View CA 94040

When waiting for a phone call, that is, at the

Calls: 456
Awaiting Call..

prompt, these keys have special actions:

A - answer the phone (send Hayes AT A)
C - enter the CHROME news/mail reader
E - display last 20 events
F - "finger" a user
L - display last 20 callers
M - recent offsite mail sent or received
N - recent UUCP network connections
P - invoke outgoing UUCP poll
Q - exit to system
S - login locally (also F2 key)
T - last 20 file transfers
U - recent Usenet mail & news traffic

To signify you are willing to chat, turn the SCROLL LOCK key on;
otherwise it will display the /waffle/system/excuse file.

If you are running Waffle as a single-user UUCP station, it is
usually better to login using LOGIN.BAT rather than typing S here.


S U P P O R T F O R F A X

Some FAX boards may be supported. If your board returns the
string "FAX" as part of the connect string, such as CONNECT 9600/FAX,
then the /waffle/extern/_system file's "fax" entry is executed.

You can configure the FAX recognition string by setting "fax: xxx"
in the static file. By default, this is set to "FAX".

To use this feature, you must add a line similar to this to your
/waffle/extern/_system file:

fax /exit=220

Also, RUN.BAT needs to be modified to notice this errorlevel and
dispatch a batch file (say, INFAX.BAT) to pick up the connection.

Whether you can actually do this depends on the quality and capability
of your FAX software, so your results may vary.


M U L T I T A S K I N G A N D L A N S

Some notes and caveats if you are either running on a LAN, or
running multiple copies on one machine with a multitasker.

NOTE: This section of Waffle is 'new' and not officially supported
on all platforms. The only one we've extensively tested under
is Novell's 3.0 Netware. Additionally, we think this version of
Waffle is better at multitasking under DOS on a single machine
(we cringe at the very thought) than previous versions. Feel
free to experiment and please report back your results.

o Enable multitasking features

See the STATIC.DOC sections regarding the 'multitask:' parameter.
In particular, 'multitask: dos' turns on file locking, making it
possible to access the password file without fear of corruption.

Also, time slices may be relinquished if running the DesqView or
Windows 3.0 multitaskers (see STATIC.DOC).

Systems running on LAN's will generally want to enable sharing
if multiple users are to access the system at once.

o SCHEDULER issues

When running multiple copies with a multitasker and you
want to use the scheduler, each 'partition' must have a different
schedule file. The port number is added to the filename:

schedule.1 <- File for COM1 partition
schedule.2 <- File for COM2 partition

If you have a 'channel:' defined (recommended, see STATIC.DOC),
the channel is used as the extension.

In general you don't want the same events in both files.

One possible strategy is to have only one partition use the
scheduler, and the other for dialin (you would have a SCHEDULE.1
file but a blank SCHEDULE.2 file.) This is the safest.

Another strategy is to have uucico poll one set of hosts from
partition #1, and poll the other set from #2. If you do this, UUXQT
must be told to process ONLY jobs from the hosts it is accountable
for on that partition. To do otherwise invites disaster.

o Serial communications

It should be possible to run Waffle in two partitions on either
COM1/COM2 or COM3/COM4 using the Native driver. It's NOT possible to
run 4 partitions at once using the native driver.

To run more than 2 partitions, a FOSSIL is required. It should
probably be loaded as a device driver before the multitasker, so that
it will be available to all partitions. (There may be other ways.)
X00 should be able to do handle this.

o Novell networks

When running the scheduler on a Novell network, the workstation
time may be unsynchronized with the server time. Run the SYSTIME
program supplied by Novell as part of a nightly job (at minimum),
or you may want to run SYSTIME in the RUN.BAT file.

With the network software running (IPX plus NET3, or similar),
a full 640K of memory is highly recommended. It's possible to run
with less memory, but tweaking may be required.

Use CASTOFF ALL to prevent the Waffle systems from blocking
when recieving broadcast messages.

--
[email protected]
(C) Copyright 1992 Darkside Int'l