HOST 3.2
Miniature BBS program

by
Bob Eyer
[73230,2620]

May 5, 1993

See SHARE.TXT for instructions on how to register, also how to
order a copy of HOSP.


FEATURES OF HOST
(see below about added features of HOSP)

- Can be run 'right out of the box' with no configuration at all
- Uses very little disk space, and generally uses less than 60K memory
- Two types of local Sysop logon
- ESC key abort to terminate online caller
- network support

- Internal menus replaceable by external file
- Chat
- Switched mail function with message search
- User-specifiable upload directory inaccessible to download
- Optional user-selectable prompt color control
- Option to activate downloading before bulletins and main menu
- Option to turn on caller access to user data
- Option to make uploads readonly
- Switched file transfer, typing files, support for wildcards
- Switched user-specifiable protocols with remark-out function
- Switched FMS operation (makes possible downloading from any
number of DOS directories via just one file description list)
- Switched title page
- Switched trailer page
- Switched bulletin system
- Sysop shell to DOS
- User-specifiable communications driver for all shell operations
- Global expert/novice toggle
- Global wipe/nowipe toggle
- Global logoff command
- Global quit command

- Ctrl-K/X (abort)
- Selectable timelimit for non-Sysop callers
- Variable prompt inactivity logoff
- Variable clumping factor for event logging
- Variable message size limit

- User specifiable rings to answer on
- Ringback option - user selectable wait time
- RTS/CTS hardware handshaking for maximum speed
- Automatic string pool error eject to DOS with error level 2
- Optional 7-bit filtering below 9600 baud




Syntax
------

HOST [port baud LOCAL DL USERS COLOR NOFILTER R] [>file | >prn]

Command-line options, where used at all, may be specified in any
order.

port The number of the communications port to be made active.
HOST is capable of identifying ports 1-4, without
supplementary specification of IRQ lines and addresses.

If not mentioned, HOST defaults to 1.

baud The baud rate at which to open the communications port.
If not mentioned, HOST defaults to 9600. Valid baud
rates are 300, 1200, 2400, 9600, and 19200.

If 19200 is selected, HOST will assume the modem is a
USRobotics Courier HST or Dual Standard, and will send
&B1 &N8 to the modem to fix the modem to the DTE (the
communications port), unless the user overrides by
specifying a new value of FIXED in the HOST.CFG file (see
below). In such case, remote must call at same speed.

LOCAL A commandline keyword which specifies that HOST is to be
run without communicating with the modem at all, for test
or illustration purposes.

The user may see how HOST works for the first time and
without a modem, just by entering the command

HOST LOCAL

At the YOUR NAME prompt, just enter the name in which you
wish to log on.

Where LOCAL is not specified, the user may logon simply
by hitting the Esc key. However, in this case, HOST's
code does activate communications functions (such as

raising and lowering DTR, etc).

USERS A commandline keyword which TURNS ON caller access to
the ther callers and ist users functions on the
Main menu. The purpose of this option is to accommodate
Sysops who may or may not want their callers looking at
the identity and/or behaviour of their other callers.
Prior to this release it was assumed that all sysops
would want to provide this option to callers; however,
the assumption is not correct: Most customers for this
kind of program tend to prefer denying that kind of
access to the ordinary caller. Accordingly, the default
is no access for ordinary callers.

This option has no impact on the operation of the
username/password system. This system is activated not
by the USERS option, but by running a check on the
existence of HOST.USR. See below about this file.

COLOR A commandline keyword which activates the
function on the Main menu. The default is therefore no
color for the ordinary caller. See below about the main
menu and color adjustment.

DL Command line keyword which puts every caller into the
download sequence as soon as he or she logs on, thus
short-circuiting bulletins and the main menu. (Exit from
the download area, however, still returns the user to the
Main menu).

NOFILTER A commandline keyword which turns off 7-bit filtering.
See remarks about Noise below near the end of this
documentation.

R A commandline keyword which causes HOST to set public
file uploads to readonly status.


>file | >prn
All of HOST's video is redirectable to a file or to your
printer.

This means that your printer can be used as a means of
recording caller sessions. When doing so, take care to
set your printer to its highest speed modes. Many
printers set to draft mode will be a pretty good match to
2400 baud video, and will perform more evenly at 1200
baud. Avoid redirecting 9600 baud calls to a printer.

Redirecting to a file has much less impact on a
communications session and can be used at high speeds.


Added Features of HOSP (HOST Plus)

- Switched external mail function
- Switched private file before prebulletin downloading
- Switched private download function
- Switched restricted user fcn with password logon and hide
as well as new-user handling capability (can handle as many
as 15,000 users, yet provide almost instantaneous identity
checks).
- Switched more extensive bulletin system
- Switched information services section
- Switched DOOR option
- Switched BEGIN and FINAL program access

- All this adds less than 6k to the size of the EXE file.

- Includes new version of a special STOP program which permits
optioned batch language programming for communications door
programs.

- Other added features (program under continual development).

- Free update privilege, if done by electronic transfer.

You pay only $25 US ($5 for HOSP and $20 registration fee). See
SHARE.TXT for ordering instructions.





IMPORTANT WARNINGS
==================

1. Fast host video
-------------------
Be careful what video drivers you use with this program.

Very many people today use in CONFIG.SYS some variant of NANSI.SYS
as a replacement for ANSI.SYS, to speed up video, supply extended
ANSI support, and to correct ANSI's difficulty in handling 43- and
50-line video modes. Normally, there is no problem about the use
of most alternatives to ANSI.SYS. However, in all video speedup
programs there is the risk that the speedup is purchased at the
price of removing or partially crippling DOS redirection,
especially to the communications port. For example, the FAST
option of NNANSI.SYS has this kind of crippling effect. If you
use such a driver, there is the risk that your callers will never
be able to connect with HOST, simply because HOST's echo function
is disabled or crippled by the external video driver.

Therefore, where possible, avoid the use of video drivers which
function in this manner. If you must use Tom Almy's NNANSI.SYS as
I do (I love it!!), take care to use NNANSI's SLOW option, when
you activate HOST. The SLOW option of NNANSI is still faster than
NANSI, but does not cripple communications port redirection.

2. Modem speed maxima
---------------------
HOST has no way of determining the maximum speed of your modem.

If you invoke HOST's default of 9600 baud on a modem whose maximum
is lower than 9600, the program will appear to function normally
until someone calls to make a connection - and then it will always
fail with the message on the local screen,

CONNECT FAILURE 0.

If your modem has a maximum speed lower than 9600, then you MUST
specify the desired speed at which to initialise that modem on the
HOST command line. And that speed must not be in excess of the
maximum rating of that modem.

Example: HOST

will open COM1 at 9600 baud, No parity, 8 bits, 1 stop bit, and
will function so as to enable callers to connect, PROVIDED the
modem supports 9600 baud, and PROVIDED the modem is connected to
COM1.

'HOST 2400' opens COM1 at 2400 baud.

'HOST 3 300' opens COM3 at 300 baud, if COM3 exists.

'HOST 1200 2' opens COM2 at 1200 baud, if COM2 exists.



General Discussion
------------------
The largest problem with most host programs in occasional use is
that they require the user to refresh his memory on how to
configure them. This is a normal hazard with any program, but it
becomes particularly acute in managing BBS programs. Even the
simplest of them previously required the Sysop to spend several
hours setting it up before it could be tested and used.

Another problem is disk space. Keeping a fully configured BBS
system on one's hard drive can mean wasting space of the order of
megabytes. This is inappropriate for software which is intended
to be used only once in a while.

RBBS, PCBoard, Wildcat, and most other programs have long been in
the "large host" category; and so they just don't fill this
particular need.

In contrast to these and many other smaller programs, HOST can be
run immediately by any owner of a low speed Hayes-compatible
modem, or a high speed USRobotics Courier HST or Dual Standard,
or equivalent.

By "immediately" is meant 'without preparing associated data or
configuration files'. HOST, unlike just about every other BBS
program, can be run directly from the DOS prompt, as though it
were merely a self-contained utility program. And it will thus
work at its simplest level.

HOST combines this default level of simplicity with powerful
options for easy expansion in operational sophistication. Create
a BUL file, and presto - you have a ulletin function on the
menu. Put at least one file in the file transfer directory and
presto - HOST puts the ownload and ype options on the Main
menu. Create FMS.DIR and LST.DIR files, and presto - HOST has FMS
operation with a separate iles section on the menu. HOST has a
fair number of such optional features, which you can add or
subtract simply by making the appropriate files available in the
local directory.

In general, HOST makes heavy use of file-switching techniques -
that is, it controls many of its optional modes of operation by
automatic file detection, rather than by specifying a control
parameter on the command line or in a configuration file. This is
what is meant by describing a function as being "switched".

Due to its superior internal organisation, HOST can behave like
large BBS programs and yet still retain the memory and speed
advantages of miniaturisation.

For now, there should be only two essential things to remember:

- You must know which port your modem is connected to, and its
maximum speed. If different from HOST's defaults, you must
specify on the command line the ones that apply. Do NOT enter a
baud rate on the command line which exceeds the maximum rating
of your installed modem. See Syntax and the note labelled
'IMPORTANT' above.

- If you don't specify your file transfer directory in HOST.CFG,
HOST will assume that it is the root directory of the current
drive. Files visible to the caller must be either reset,
archive or read-only attribute status.

Menus
-----
From this point on, the focus of discussion is on how to expand
functionality beyond the bare minimum immediate mode of
operation. For this purpose it is useful to present a picture of
menu options showing which ones are "switched" (More switched
options are available in HOSP).

Main Files

* ulletins elp
ist files <
hat ms/nofms
* ead messages
* srch string
nter message
+* ile list
+* ownload
+* <=> srch, wildcard (files)
+* ype file
+ pload
*
*** ther callers
**

ipe/nowipe
pert/novice
oodbye (logoff)
uit

There are two options not on this display: The iles option and
the hell option. The iles option automatically replaces the
five options marked + when FMS.DIR is detected by HOST,
transferring those options over to the Files area. The hell
option is not available to the general caller, but only to the
Sysop, and so there is little point listing it here.

Triple asterisks refer to options which require a command line
option to be specified, before the existence check is used by HOST
to decide whether they are available. In particular, the ther
callers option falls into this category, requiring the USERS
keyword to be on the commandline, for ordinary caller access.

The double-asterisked option - - requires a command line
parameter for ordinary caller access, but uses no file existence
check.

Except at the file and file-protocol prompts (which appear when
you select the D or U options), the last four options of the Main
menu are always available at any prompt, regardless whether they
are displayed. They are available even at page prompts. These
global options are

ipe/nowipe
pert/novice
oodbye (logoff)
uit

All prompts, in the meaning here, always begin with a number in
parenthesis referring to the number of minutes the caller has been
online. That is, where such a time-usage number is displayed, all
global options are available, even where not mentioned. Time
usage is preferred to the usual time-remaining statistic,
primarily because this type of program is most likely to be of
interest to Sysops who want to inform long-distance callers about
how much time they'll be charged for being online, rather than how
much more time they might use to fool around on the BBS.

Where HOST detects FMS.DIR, the Main menu automatically divides
into two menus--Main itself, and the Files menu. The options
which would normally have been grouped as file options on Main
then appear in Files.

The reason for this division is to provide further scope for
adding mail options, as well as additional files options. The
present version supports both message and file searches direct
from the Main menu, and without splitting the Files functions off
into a separate section, the default Main menu could overflow the
screen under FMS operation.



-------
Prompt color may be controlled by the user online, using the
option - which covers all usable ANSI foreground colors.
The Sysop who makes this option available, however, should use a
bulletin message to warn the caller not to use it unless his or
her machine is configured to interpret ANSI coding. Color is
achieved in this option by using ANSI codes to inform video at
both host and remote what colors to use. If an ANSI-compatible
video driver is not installed, or if the caller's communications
program is not set to interpret such codes, they will simply
appear as so much garbage on the screen.

The option enables the user to reach 8 background choices
and 16 foreground choices, simply by hitting ENTER until the
choice is reached. The user may hit ENTER any number of times;
the choice logic in this option is circular.

WARNING: Except for session recycling (which always resets the
screen to standard white on black), the default foreground color
is always the previous foreground color and the default background
color is always black. The reason for this is to make things a
little easier for people who accidentally get into the COLOR area
without having ANSI support. As a result, if the user previously
sets his or her foreground to black, a second use of the COLOR
option will produce black on black, which obviously cannot be
read. The user should be reminded of this possibility in a
bulletin, with the instruction simply to hit ENTER once again to
change the color, so the prompt can be read.

Color highlighting is HOST's default mode of operation only for
the Sysop. To make this option available to all callers, just
specify COLOR on the command line.

ms/nofms
-----------
HOST makes available two different ways of viewing and handling
available files for transfer purposes. The simple DOS directory
approach is based merely on presentation of sequential lists of
files, filesizes and dates of last modification. These lists are
automatically generated by HOST internally in memory, and do not
involve the preparation of external disk files by the Sysop.

The second approach is called "FMS" -- meaning 'file management
system' (a term coined by the RBBS community that popularised it).

In many BBS systems, the Sysop is required to prepare ASCII
directory files with descriptions of each file in the particular
directory to which the file corresponds. When the caller looks at
what is available, he or she is actually reading one of these
files (as opposed to reading the DOS directory itself). The
problem with this primitive approach to file management (still
used by PCBoard and certain other systems) is that it causes the
Sysop to spend enormous amounts of time making sure that his ASCII
directory lists accurately reflect the situation at DOS level
(every time he moves the DOS file to another directory, he has to
cut and paste the description line from the corresponding
directory file to another such file).

FMS reduces the maintenance problem created by this procedure, by
using just ONE directory list which covers all available DOS
directories. The way this is achieved is by telling the BBS what
the download path is. Each time the BBS is asked to send a file
in the common list, it uses information about the download path to
determine what path is appropriate to attach to the selected file,
much as DOS does when it searches through the DOS path to find the
executable file corresponding to a DOS command.

Similarly, when a caller uploads a file to an FMS system, he or
she adds the description material to the common list, and all the
Sysop has to do is move the underlying file from the upload
directory to whatever directory is appropriate, in the light of
preferred disk management priorities. The Sysop, however, does
NOT have to edit the file list (as would otherwise be necessary).

HOST activates FMS and an option for the user to toggle between
FMS and NOFMS on the file menu, on simple detection of the common
file list containing description material, called FMS.DIR. The
download path must be provided in LST.DIR.

See FMS section below about the technical specifications of
these two files.


Network operation
-----------------
HOST should be compatible with network operation. A new variable
CPATH has been provided to make it possible for any number of
nodes to share the same data files. There is one exception:
HOST.CFG (see below) cannot be treated as a shared data file,
since it is the very file which tells HOST where to find the files
it needs.

For the purpose of sharing files, HOST opens all data files (see
below about HOST control files) in shared mode. In addition, it
has error handlers which prevent node hangs on serious network
collisions. These handlers cause HOST, on detection of any error,
to attempt reopen of a given file once every second for a maximum
of 10 seconds. If an error is still detected on the 11th try,
HOST simply returns to the originating prompt (the user can then
try again later).


===================== HOST Control Files ========================
- More sophisticated modes of operation -

See sections below about the asterisked files.

* HOST.CFG Sets fine-tuning variables such as the SYSOP secret
name. This is the only control file which is not
affected by CPATH; and so, it must be in the local
directory.

* HOST.MSG Contains user-entered messages.
Automatically generated and updated by HOST in the
local directory, when the user confirms that he wishes
to save his message. Requires no formatting.

Message size is controlled by the CFG variable MSIZE.
See HOST.CFG below.

* HOST.LOG Records what each caller does while online.
Automatically generated by HOST in the local
directory.

* FMS.DIR Text file listing of available files for download.
Detection of the existence of this file causes HOST to
split the Files section off from the Main menu and
provide the ms/nofms toggle option in the new area.

See FMS Section below for details on the structure
of this file.

* LST.DIR Text file listing of all directories where the files
listed in FMS.DIR may be found.

See FMS Section below for details.

- HELP.DIR Text file read as help for callers in using file
commands when in FMS mode. Should be written by Sysop
in light of special difficulties which his clientele
may have with HOST FMS processing.

Existence of this file used as a switch to activate
the option on the Files menu when FMS is
available.

- NOTE.DIR Sysop-created note file to be read immediately prior
to a download or typing operation.

* HOST.XFR Protocol syntaxes replacing HOST's defaults.

- HOST.TIT Logon title page.
HOST skips the title page function if this file does
not exist in the local directory.

- HOST.M External Main menu.
HOST uses internal menu if this file does not exist.

- HOST.F External File menu.
HOST uses internal menu if this file does not exist.
(the internal menu assumes that the Sysop has informed
his callers that the W, X, and G options are
global--and so need not be explicitly listed on
submenus).

HOST provides a separate File section only where it
detects the existence of FMS.DIR.

- HOST.END Logoff trailer page.
HOST skips this function if this file is not found.

- HOST.BUL Logon bulletin.
HOST checks for the existence of this file and puts
the ulletins option on the menu if the check is
positive.

Each of these files is an ASCII text file, intelligible to any
text editor, and except for the LOG and MSG files, they must be
created by the Sysop end-user who wishes to implement the
functions which they activate.

All of these files except HOST.CFG can be put on a RAM disk for
speed and to minimise disk wear and tear, by the simple expedient
of specifying CPATH to be the ramdisk.

See sections below for more detailed descriptions on the files
asterisked above.


HOST.CFG
--------
This file has a very simple structure. It is based on the use of
16 keywords, each of which is optional: SYSOP, REDIR, DELAY,
LIMIT, RBACK, RINGS, TWARN, CLUMP, MSIZE, FPATH, UPATH, CPATH,
NRAM1, NRAM2, MINIT, and FIXED. The space character is used to
associate each keyword with its intended value. All values are
read as strings, so don't use quotes. The order in which these
variables are listed and defined in HOST.CFG is immaterial; HOST
will figure out which is which.

SYSOP - Your secret name, as the Sysop (no length limit).
The default is no Sysop name, and so no Sysop
privilege. If SYSOP is defined in HOST.CFG, then the
caller logging on with this name will have access to the
shell function. Further, this secret name is the only
logon string which HOST will accept as a single-part
string. Normal users are required by HOST to enter at
least two names each separated by a blank.

At logoff a Sysop caller will see a free memory report
before DTR is dropped; other callers only see trailer
page, if any.

REDIR - The name of the device used for redirecting data to the
communications port when the shell is in use. The
default is the port name (COM1 for port 1, COM2 for port
2, and so on).

The disadvantage of the default mode of redirection is
that the observer of the host screen cannot see what is
happening when the caller drops to DOS. A number of
alternate device drivers is available, each of which
redirects data to both the communications port and the
local (host) screen, such as IBMAUX and GATEWAY. To use
these drivers, they must be properly installed in the
CONFIG.SYS file at the host. In the former case, the
device names are AUX1 or AUX2, in the latter GATE1 or
GATE2. The device name is what corresponds to REDIR,
not the name of the file which puts the device driver
into RAM at boot time.

If you are using some other device driver for
communications redirection but don't know the device
name which it creates, you can use a program to list all
the active device names in your computer. For example,
Quarterdeck's MANIFEST will do this job; there are also
many Shareware programs which do it also, such as the
MAPMEM program of Kokkonen's TSRCOM package.

FPATH - The drive-directory where file transfer takes place.
If not mentioned, this variable defaults to '\' - that
is, the root directory of the current drive.

UPATH - The drive-directory where files go when a caller uses
the pload function. Where this path is different
from FPATH, callers will be denied download access to
uploaded files.

Such a feature can be used by the Sysop to review
uploads before moving them into the FPATH area for
download exposure.

CPATH - The drive-directory where all HOST's data files other
than HOST.CFG are to be kept. If this variable is not
mentioned, HOST assumes that these files will be in the
local directory.

HOST.CFG must be in the local directory, regardless what
value is assigned to this variable.

The main purpose here is to make possible network
operation for HOST. Each copy of HOST.CFG (one for each
node) should specify the same value for this parameter
(same drive and directory on the network server), so
that each node sees the files on that server.

DELAY - The delay time, in seconds, between modem commands.
In command mode (when no caller is online), instructions
sent to the modem are followed by responses from the
modem. If commands are sent too quickly, they won't be
received, since some of them may occur during the modem
reply. The default of HOST is 1 second, which should
generally be adequate to prevent this kind of effect on
USR Couriers. However, you may find it necessary to set
the DELAY at 2 or 3.

LIMIT - A non-Sysop caller's session time limit in minutes.
HOST prescribes no time limit for any person who logs on
with the Sysop's secret name (see above). All other
callers have a time limit assigned by LIMIT. HOST's
default is 20.

RBACK - The number of seconds the host should wait before re-
cycling to receive the caller's second ring sequence.
If this number is a positive integer, ringback mode is
automatically assumed by HOST.

HOST does not make any use of hardware modem ringback
technology, but instead controls ringback processing
entirely from within HOST. As a result, the user may
define any kind of ringback mode he wishes, with
ringback wait (the minimum interval between the caller's
first and second call) set anywhere between 10 and 32767
seconds. Usually, the appropriate setting should be at
least 10 seconds. The standard length of the telephone
ring cycle is about 6 seconds; and a few additional
seconds are necessary to distinguish a new ring cycle
from merely the next one in the same cycle.

Where RBACK is omitted or is non-positive, HOST
deactivates ring-back mode.

RINGS - The number of rings which must occur before HOST will
make connect with a caller. Again, HOST does not make
use of modem technology here but handles the ring
problem entirely at the software level.

Where RINGS is omitted or set to 0, HOST will attempt a
connect on detection of the leading edge of the first
ring (i.e. answer on "zero rings").

TWARN - The number of seconds to wait at an inactive prompt
before the system automatically flashes INACTIVITY
WARNING. If not given, HOST defaults this number to
60. As in previous versions, the warning is displayed
for a maximum of 60 seconds, after which the caller is
automatically logged off the system - unless he or she
makes keyboard input.

CLUMP - The number of online events required to cause HOST to
empty the log buffer into HOST.LOG. If not given, the
default is 10. Each time the buffer is emptied, HOST
reinitialises the logging system.

Every unit increase in this variable adds 80 bytes to
HOST's use of RAM. See below about LOG files.

MSIZE - The maximum size of a message in lines.
If this variable is left unassigned, HOST defaults its
value to 100.

NRAM1, NRAM2, MINIT, and FIXED are modem initialisation
variables. You may see illustrations of these strings simply by
running HOST. They are summarised below the initial help screen.
Caution: each initialisation string MUST begin with the Hayes "AT"
command.

All these initialisation strings have default values supplied by
HOST, as can be seen below HOST's help screen on invokation at the
DOS prompt. But each may be varied by the user as experiment
warrants, by supplying the relevant variable and associated value
in the HOST.CFG file.

FIXED is the only initialisation variable that behaves differently
from the other three: The purpose of FIXED is to override the
other settings when 19200 is used on the HOST commandline. The
purpose here is to set up a USR Courier HST or Dual Standard to
receive fixed baud calls at 19200, so as to achieve throughput of
14400 baud. The supplied defaults should do this; but, if fine
tuning is necessary, the default value of FIXED can be made
subject to the user's own override values.

At 9600 or below, HOST sends &B0, &M4, and &N0 to the modem, so
that it will follow the caller's connect rate, unless the user
overrides the NRAM settings in HOST.CFG.

To save a series of extended modem commands, simply add &W to the
end of the desired string.

However, HOST does not in its default configuration save commands
to the modem's NRAM, but resets modem settings to their previous
states on exit. Saving modem commands to NRAM is liable to be
counterproductive, since most people will be using their modems in
other non-HOST environments and will not want to be forced to
reconfigure the modem for those other environments every time a
HOST session ends.

There is no advantage in saving modem commands in HOST's case,
since HOST always does a complete temporary configuration on the
modem every time it is run. (Many communications programs do only
a partial configuration, which is why they rely on some original
complete configuration to supply the missing information from the
modem's nonvolatile memory.)

Sample HOST.CFG file:
--------------------

SYSOP DD334RTM_2
DELAY 2
LIMIT 30
REDIR GATE1

In this example, the Sysop's secret name for logon purposes is
DD334RTM_2, the modem command delay is set at 2 seconds, non-Sysop

callers will receive a maximum of 30 minutes online, and the Sysop
is using GATE1 as the communications driver when any function is
used which involves shelling to DOS (all external program options,
including DOOR and the Sysop's own hell option).


HOST.MSG
--------
Beginning with the current version, HOST provides support for
normal BBS message structure in contrast to the "note" structure
previously available. The difference permits the user to search
all messages for a given string by reading messages in blocks
rather than line-by-line. In HOST's structure the beginning of
a message block is defined by the appearance of the following
six characters at column 1 of any line:

*FROM:

The end of the block so identified is that character which
immediately precedes the next and subsequent occurrence of these
six characters at the column 1 position.

In the event that some messages contain more than the maximum (see
MSIZE in HOST.CFG above), HOST will generate the message

--> NEXT MESSAGE EXCEEDS xyz LINES

and return immediately to the Main prompt (xyz is the value of
MSIZE). Since HOST does not change the user's text format, it
counts blank lines as well as filled lines.

In addition, HOST runs a memory test on use of the read or search
functions, and will abort to Main menu with an appropriate message
if there isn't sufficient free memory. HOST currently requires at
least 60K free at runtime to accommodate itself and the mail
subsystem, assuming MSIZE is 100.

In practice, the user/Sysop need not worry about the line limit or
how to block HOST messages, since HOST takes all the required
steps itself when a caller uses the nter message function on
the Main menu. The Sysop need only be concerned about proper
message blocking, if he intends to start a HOST.MSG file from a
text editor, rather than by using HOST's own message entry
functions.

The best way to see how HOST's message functions work is to
actually try them out during a HOST LOCAL session.

However, three functions should be documented here--the search,
review and stop functions.

HOST's search commands ('/' for mail and '=' for files) are the
only commands which are always followed immediately by their
corresponding arguments. Thus, suppose your message base contains
a lot of philosophical debate material, and you wish to read only
those messages which contain some reference to Immanuel Kant.
Then, from the Main prompt, you would enter the following
command--

/Immanuel Kant

HOST's search is case-insensitive, so you need not worry about
capitalisation. But note carefully that the argument 'Immanuel
Kant' is entered WITH the search command. There is no separate
prompt for this argument.

The same principle applies to starting searches from a page or END
OF MSG (EOM) prompt within the message read function. The syntax
and effect will be exactly the same. HOST always starts every new
search from the top of HOST.MSG.

You will notice that message page and EOM prompts contain the
eview command. Simple entry of the R of this command will
cause HOST to start again from the top of HOST.MSG and repeat
whatever operation was previously in progress. If it was a simple
read process, a simple read from the top will be the result. If
it was a search, the same search will begin again.

The top function merely skips the remainder of a given message
down to the next EOM prompt. If you wish to exit the read
function entirely, just use the global uit or oodbye
commands.

Message entry requires little explanation. I should note,
however, that HOST does not open HOST.MSG until the caller is
finished with his message and proceeds confirm that he wishes to
save it.

HOST.LOG
--------
In some recent versions of HOST, caller operations were logged to
this file as soon as they were completed. This, however, tends to
cause excessive disk wear and tear. For this reason, normal
logging behaviour in the current version is saved to an array, and
that array does not update HOST.LOG until it is full, or until the
caller's session terminates.

The array HOST uses to update HOST.LOG has a capacity of 10 lines,
unless the Sysop alters the capacity by specifying a new value of
CLUMP (see HOST.CFG above). Each time this array is filled up,
HOST automatically spills it out to HOST.LOG and then
reinitialises it for collection of new event data. For this
reason, there is no limit to the number of logged session events.

The advantage of this procedure is that it drastically reduces the
total amount of mechanical activity occurring inside the disk
drive on which HOST is run. In network applications, it should
also reduce collision effects substantially by cutting the total
time required to update this file.

FILE TRANSFER
-------------
There are five file functions: ile list or ist files,
ownload, pload, ype file, and <=>string or wildcard
search. Searches are always assumed to be preparations for a
download operation when they are initiated at logon, from the Main
or from the Files menus. When initiated from file prompts, the
search assumes the same objective as the original command which
generated the prompt. For example, a search initiated from within
a ype command will result eventually in typing a file rather
than shelling out to download it.

Except for the listing and search functions, HOST begins by
displaying a file prompt in response to each of these commands.
Under FMS (see the FMS subsection below) the Novice prompt looks
like this--

[Filename, Search cmd (=string), ENTER]: _

If you enter a filename, HOST checks for its existence. If you
just press ENTER alone, HOST simply returns to the Main menu.
BUT, if you enter text which begins with "=", HOST searches the
file list for those lines which contain the string immediately
following the equals sign. If no string is specified after the
equals sign, HOST merely generates a complete file listing.
Otherwise, it only displays those lines in the list where matches
are found.

In FMS, HOST does not remove leading or trailing blanks from the
search string (such blanks count as part of the entered string).

The expert prompt under FMS simply reads--

File or search cmd: _

It is thus assumed that the "expert" user will be familiar with
how to enter a search command from the file prompt.

Where FMS is not active, the file prompt has the following two
forms--

Novice
[Filename, wildcard, ENTER]: _

Expert
File: _

A "wildcard" is simply any string which contains either a "*" or
a "?" character--or it may be a DOS abbreviation (i.e. '.' for
the current directory). And the response of HOST to a wildcard
proceeds along the same lines as indicated in the discussion
above, except that, where the caller wants to relist the entire
file listing, he or she must enter the universal wildcard *.* or
abbreviation thereof, and HOST can only list files located in
FPATH or UPATH (where identical to FPATH).

Downloading
-----------
In HOST, downloading is relatively simple: You select the file,
then the protocol and then hit your download routine from your
dialling program. If you want to see what's available, just use
your search command from the file prompt (see above syntax).

HOST does not yet support either batch downloads or command
stacking.


Uploading
---------
HOST's FMS uploading routine requires specification of the
description of the file which the caller is about to upload BEFORE
file transfer begins.

After entering the filename, HOST will prompt the caller for a
description, as follows--

Upload description (one line only):
<-------------------------------------------->
_


placing the cursor under the left bracket of the field indicated.

On return, HOST attends to several jobs before passing control to
a menu.

First, if the file upload is zero bytes in size, HOST deletes the
file and returns directly to the menu, without updating any log or
FMS file.

Secondly, if the file is not zero bytes but experienced a transfer
error or carrier loss (as detected by DSZ), the file is deleted
from DOS and the appropriate notation is made in HOST.LOG,
indicating the DSZ error code.

If no DSZ error is detected and the R keyword appears on HOST's
command line then HOST sets the file to read-only status.
Further, if the session is in FMS mode, then the previously
entered file description is added to FMS.DIR. If the transfer was
in error, the file description is ignored, and whatever is left of
the file is deleted.

These steps of course depend on the Sysop having correctly set
DSZ's DSZLOG variable in the local DOS environment. If that
setting is incorrect or unavailable, HOST has no means of
determining whether there was a file transfer error (HOST reads
that log to determine the returned error status).


ype files
------------
This function permits the user to do an ASCII download of a text
file in the file transfer directory; en passant, the file appears
on the screen as well. In this version, HOST accepts readonly
text files, as well as reset and archive status files.

A few words should be said about "ASCII text" files. An "ASCII
file" is a file whose lines always end with the carriage-return
linefeed sequence. Generally, ASCII files also end with an
end-of-file character immediately following the last
carriage-return linefeed sequence; and some authors of text
editors take the absence of an EOF in that position to be a
deviation from ASCII format. However, HOST is not that
restrictive.

The problem about typing files directly to the screen and
communications port is that the file typed may be a binary file.
Typing binary files produces video garbage, as you may find by
applying the DOS TYPE command to any of your executable files.

Therefore, a ype function should check the file before it
performs its job, so as to avoid this kind of problem.

When HOST is about to type a text file to the screen and the
communications port, it first tests the file, and if the file
fails the test, the message

{filename} not ASCII text, or improper format

appears.

The test consists of sampling the first 82 bytes of the file and
then checking that sample for the presence of carriage-return
linefeed sequences. If the sample contains no carriage-return
linefeed sequence, then the file fails the test.

This test is actually more permissive than the one which appears
in earlier versions of HOST, because there is no test for NULL
characters (some batch files contain null characters and would be
rejected in previous versions of HOST). Generally, however, the
test should be sufficiently effective.

The reason for the 82-byte limit on sample size is that HOST does
not support 132-column video displays, and 2 bytes extra are
required to accommodate the carriage return and linefeed
characters, if the first line in the file is a maximum 80
characters long. (This is the reason for the addition of the
phrase 'improper format'--that is, ASCII format is "improper"
for HOST where lines are longer than 80 characters.)

The same test is employed by HOST in reading all text files,
including its configuration files, menus, and any text data made
available in any of its sections--other than mail.

Networked file transfer
-----------------------
Since HOST permits the user to specify a value of FPATH in
HOST.CFG, it is possible to get all nodes of a network to see the
same list of files in that path.

In that case, files are shared by all nodes. In some types of
networks, such as IBM LAN, it may be necessary to set all such
files to read-only attribute status so as to prevent network
collision errors during file transfer (the purpose of HOST's R
commandline option); others, such as the Novell, may use a
different scheme for avoiding file transfer problems.

It is important to understand that this is a network or external
protocol (e.g. DSZ) problem, NOT a host code problem.

HOST does not itself open any user-selected file when it directs a
file transfer, and so cannot be the cause of a collision problem
in a network environment.


FMS
---
FMS operation is enabled by HOST when it detects the existence of
FMS.DIR. When such detection occurs, HOST splits off all the
files functions from Main into a Files section, adding an
ms/nofms toggle option. The caller can therefore switch back
and forth between regular DOS and FMS directory modes within a
Files section. The status is indicated by the presence or absence
of a lower-case "f" in the Files prompt.

The format of an FMS.DIR file is the same as an ordinary DOS DIR
listing, except that there is no time column, and a description
column 46 characters long begins two spaces after the date column,
followed by a mandatory period (".") character and a carriage
return linefeed sequence. Each line must therefore be 82 bytes
long. The last character visible when FMS.DIR is examined by a
text editor is the final period of each line, found at position 80
of the line; but, within HOST, that period is suppressed from
view. The purpose of the final period is to prevent text editors
from shortening the line on saving the file (many text editors
automatically strip trailing blanks from text lines before writing
them out to a file).

Reviewing standard DOS 5 directory format, the filename field
occupies the column range 1-12; the filesize field occupies
columns 13-22; and the date field occupies columns 23-31. In FMS,
the next two columns are left blank, and the description field
occupies columns 34-79.

The best way to see how this works is simply to select one of
your own directories (let's call it "SYS") and execute the
following command from DOS:

DIR SYS > FMS.DIR

Then bring up FMS.DIR with your text editor and remove all lines
which don't begin with a filename. Next, cut away the time column
and put in your descriptions, starting column 34 as indicated by
your editor's status line. DON'T FORGET TO PUT A PERIOD
PRECISELY AT COLUMN 80 OF EACH LINE.

Then save the result, transfer FMS.DIR to HOST's local directory,

and then run HOST LOCAL, get to Main menu, select iles and take
a look at your result by punching one of the file commands (D or
T). If the result is scrambled, you have one or more lines which
are not terminated properly with a period at column 80.

Once you have set up your FMS.DIR properly (adding in whatever
other files in other directories you want to describe and
display), the next step is to define LST.DIR.

LST.DIR tells FMS what paths to look at to check for the existence
of any file selected from FMS.DIR. It's a simple list of paths,
one on each line of the file. Thus, following the example above,
it might look like this --

c:\sys
d:\util\
e:\

When a caller selects a file from the list at the file prompt,
HOST reads LST.DIR and tries out each of these paths from top to
bottom, checking whether the selected file exists in one of them.
If the file is found, the appropriate path is attached to the
filename and a download or typing operation will then proceed (or
an upload operation will be aborted--HOST does not permit callers
to overwrite existing files).

It is not necessary to specify the value of FPATH in LST.DIR: HOST
automatically checks FPATH before it checks the other paths in
that file. HOST, however, does NOT check UPATH (where different
from FPATH), unless that path is specifically mentioned in
LST.DIR.

Thus, when FMS is enabled in HOST and where UPATH is different
from FPATH, the Sysop can either provide or deny download access
to the upload directory, simply by mentioning, or not mentioning,
the value of UPATH somewhere in LST.DIR.

If you have many directories intended for download access, it may
be important for you to remember the order in which HOST searches
LST.DIR: It searches from the top (line 1) of this file to the
bottom. This fact makes it desirable to list those directories
containing the most popular files, or those most likely to be
popular, in paths near the top of LST.DIR. If you don't know
which files are most likely to be popular, you may analyse
HOST.LOG to see which kinds of files are most often downloaded.


HOST.XFR
--------
If HOST.XFR exists in the local directory and is in the proper
format, HOST will use it to replace the default protocol list with
the user's list of protocols.

The format of this file is as follows, beginning at column 1 of
each line:

Menu option letter:Menu line:Download syntax:Upload syntax

Each line uses the colon (:) as a separator.

In the strings used for download and upload syntax, the
asterisk (*) is used to show where in the string HOST is expected
to inject the pathed filename of the file to be transferred.

For example, HOST's defaults for COM1 are as follows:

X: Xmodem Checksum :DSZ port 1 sx * :DSZ port 1 rx *
C: Xmodem CRC :DSZ port 1 sx * :DSZ port 1 rc *
Y: Ymodem (Xmodem-1k):DSZ port 1 sx -k *:DSZ port 1 rx -k *
Z: Zmodem :DSZ port 1 sz * :DSZ port 1 rz *

[Note: These DSZ commands include ' handshake on ' immediately
before the transfer command (sx, sz, rx, etc). If you feel some
other DSZ syntax would work better in your application then you
must use the HOST.XFR file and supply your desired syntax.]

You may also use protocols other than those provided by DSZ;
however, the only caveat here is that HOST will not be able to
pick up the error code (if a transfer error occurs) for logging
purposes.

Where HOST.XFR does NOT exist, HOST automatically selects the
right number to use for the port. Where HOST.XFR is specified and
the protocol syntax requires the use of port information on the
commandline, the user must supply that information explicitly.
The reason for this is that authors of file transfer protocols use
many different keywords and syntaxes for indicating port
information, thus making it impractical for HOST to anticipate
them.

Note carefully the use of ':' in these examples. A minimum of
four separable pieces of information are required to specify a
file transfer protocol in a BBS program: The command letter to use
when selecting the protocol, the text to appear in the menu for
that selection, the download protocol syntax, and the upload
protocol syntax. The colon character is used a separator for each
of these pieces of information.

Notice that, for a host installation, the download syntax is a
SENDING syntax, not a RECEIVING syntax.

Notice also the use of the * character in each protocol string.
For DSZ, the position of the filename is last on each commandline;
but other protocols may, or may not, use this convention. HOST
automatically looks for that asterisk and splits the commandline
in such a way as to inject the filename where the user requires,
reassembling the commandline in the appropriate manner.

File transfer is impossible unless the * character is put in the
proper place for EACH protocol string. HOST does not assume any
default position, unless HOST.XFR does NOT exist in the lcoal
directory.

The user may "remark out" a particular line in HOST.XFR, simply by
inserting an apostrophe (') at the extreme left of the line. HOST
will ignore such a line.

Finally, notice in the DSZ examples above that all parameters are
specified in LOWER CASE. Forsberg requires lower case usage, but
other protocol authors are likely to be indifferent to the
upper/lower case issue. HOST picks up this information and
preserves it intact.

HOST is currently configured to permit the user to identify a
maximum of 20 protocols. The only reason for this limit is to
allow callers to select a protocol from a list viewed as complete
in one screen of information, using 25-line video. If there
is demand for extending this limit, I will provide it; but I
really doubt anyone would want to use HOST to make available
large numbers of protocol choices.

Note:
HOST does not have any internal protocols for file transfer, but
takes for granted, where HOST.XFR does not exist, that the user
has a registered copy of Chuck Forsberg's DSZ.COM located
somewhere in the DOS path. The four default protocols which HOST
presents as choices all make use of Forsberg's module. HOST
shells out to DSZ and automatically sets up the DSZ commandline,
conformable to the user's selected option and DSZ's syntax. File
transfer does not involve setting up special batch files.

In the event DSZ.COM or DSZ.EXE is not found in the DOS path (or
in the local directory), HOST simply returns to the Main menu
without apparent effect to a caller.

To make HOST respond to other protocol programs, it is necessary
to create the HOST.XFR file containing the proper syntaxes for
each.


============== MISCELLANEOUS OPERATIONAL PROBLEMS ================

Use of the hell function
---------------------------
There are two main reasons why a person running a BBS should never
provide general caller access to DOS through a shell or exit
function. (1) Any caller could do great damage to the software on
his or her computer, and (2) callers who are not knowledgeable on
the use of shells in communications environments could easily hang
up the operation of the BBS by doing something that would prevent
them from exiting out of DOS level. A few notes should be made
about this second danger.

(a) Normally, when BBS operators arrange for the use of a DOS
shell, they do it by having the BBS program specify a batch
file to execute the functions intended, and this batch file
will call some kind of watchdog utility which causes the
host computer to reboot in the event of a prematurely
dropped carrier.

The main reason for the watchdog utility is that, if
carrier is lost, the caller will be denied any further
control over processing. If no program is resident, which
can automatically restore the BBS, it will simply hang, and
no other user will be able to log on, until the condition
of the computer is fixed by the Sysop.

An arbitrary shell function for Sysops does not provide any
such utility; so if you call your own host and drop to DOS,
you could make a simple mistake and cause your system to
hang - unless you MANUALLY call a watchdog utility as soon
as you are at DOS level. Watchdog utilities do not,
however, work equally well on all types of computers - so
the risk of hang when drop to DOS occurs is still quite
substantial even for the Sysop.

(b) Certain keys, such as the backspace key, and perhaps even
the cursor keys, may cause infinite loops to develop at DOS
level.

DON'T use any keys at DOS level, except the numbers and
letters of the alphabet, and the ENTER key. Any deviation
from this rule could cause your host computer to hang while
you are at DOS level within a shell.

If you must use DOS while online, use it through an
applications program whose video i/o is redirectable to a
communications port, and which itself has internal carrier
protection. (DON'T use programs which write direct to
video in a communications shell!)

Directory change at DOS level
-----------------------------
Although the Sysop may theoretically exit from DOS back to code
from anywhere at DOS level, this type of return behaviour should
be avoided when the code is a BBS program. The reason is that BBS
programs generally have files that are written to or read from in
their local directories, and will not function properly, if the
local directory was accidentally changed during an online
shell-to-DOS session.

This problem may be met by the Sysop by providing full drive and
path specifications for CPATH, FPATH, and UPATH in HOST.CFG.

Noise
-----
Generally, when run on error-correcting modems like the line of US
Robotics Couriers, noise is rarely a serious problem. The problem
arises when a BBS is run in non-error correcting environments.
HOST limits this problem by filtering all strings transmitted
through the echo function of prompts at speeds below 9600 baud,
unless the NOFILTER commandline option is selected.

In particular, the filter passes only those characters whose ASCII
value is less than 127 at speeds lower than 9600 baud. At 9600
baud or above, HOST assumes the modem is of the error-correcting
variety, and so does no filtering, even when NOFILTER is not
specified.

This filtering process applies to all echoing to remote at
opportunities for user input - for example, in chat, or in message
entry. It follows that, where filtering is active, HOST does not
permit remote upload of a graphics message to the Enter Note
function.

7-bit filtering never applies to file transfer.


Errors
------
HOST supports error detection, much of which is used for internal
reprocessing (such as error handling when the CTS line is
dropped), and is of no interest to the user. However, the
following errors have diagnostic importance:

- Modem not connected to port or modem turned off

This occurs when the modem status register has a value less than
16.

Please let me know if your modem is otherwise operational, but
you cannot get past this message. HOST will report to you the
MSR value on your screen at run time. I have tested HOST on a
number of different kinds of modems with successful results on
this error condition, but admit that I don't have exhaustive
information about all modems.

This error condition is an attempt to deal with a problem which
many communications programs simply ignore, with the result that
they simply hang the computer, if the modem is not connected or
is electrically turned off.

Well-designed programs, especially communications programs,
should provide some hardware diagnostics to help users who may
be having difficulty.

- Illegal baud rate

If you select a baud rate not supported by HOST, this message
will occur, returning you to DOS. HOST will inform you what
baud rates are legal.


- Wrong port, wrong baud, or hardware problem

This message occurs if HOST encounters any error while opening
the communications port. For example, if you select 2 on the
commandline for the port, and your machine only has a
communications card that supports COM1, this error will occur.
It may also occur if you have a hardware problem - for example,
if your communications card needs to be reseated on the
motherboard, or perhaps you should do a cold boot because of a
lost bit somewhere in RAM. Try rebooting if this message
occurs. If that doesn't work, open up your machine WITH POWER
OFF and try reseating your communications card. Of course, make
sure you're using the right port and baud on the commandline,
when the machine is afterwards TURNED ON and rebooted.

If all this fails to make HOST get past this message, you
probably have an electrically defective communications card.


- STRING SPACE CORRUPT; Please call back in about 20 seconds

This error may occur when HOST's string pool has become
corrupt. HOST automatically puts the phone line off-hook,
closes the communications port, and exits to DOS with DOS error
level 2, when this circumstance occurs. The appropriate action
is merely to start HOST again from DOS, and this can be arranged
automatically by making direct use of HOST's exit code.

Since HOST allocates far more string space (8K) than it uses
(1-3K), the user may never see this error occur. But, if HOST
is used as a 24-hour BBS, the activating batch file should take
it into account, in order to avoid losing the host on rare
occasions. For example, the following statements in the
activating batch file would do the trick:

:START
HOST
IF ERRORLEVEL 2 GOTO START

In this case, the absence of any parameters on the commandline
indicates that HOST will activate its defaults: port 1 and 9600
baud. It's up the user to choose the proper commandline
parameters appropriate for his or her particular implementation.


Logging off and recycling
-------------------------
HOST reports inter-session processing on the local screen, so you
can see where any documented error occurs.

One important problem that may develop, but for which HOST has no
error handler, occurs when a caller logs off but HOST does not
drop his carrier - thus forcing him to drop carrier at the other
end. This fault is due to the fact that the switches of the modem
which HOST is using are set to force the DTR line high at all
times.

HOST drops the caller's carrier by dropping the local DTR line; if
the host modem does not respond to this command, the remote caller
will still be online. The caller will see evidence of this
malfunction, by noting that his line was not dropped after he
logged off, and that he sees on his screen the message to put the
host line offhook (it won't really be offhook if the remote caller
sees that message). As a result, he'll have to drop his
own carrier manually.

Therefore, do NOT operate HOST on a modem configured to force DTR
high at all times. The 'force DTR high' switch should be turned
off.

In Closing
----------
Please feel free to offer any criticisms or suggestions you may
have; I can be reached at Compuserve [73230,2620].


- Regards, Bob

----------------------
End of documentation