@comment Tell Emacs to use -*-texinfo-*- mode
@comment $Id: modem.tex,v 2.5 91/09/02 01:37:50 adrian Exp $

@node Modem Stuff, Events, The Sysop Command Reference, Top
@chapter Modem Stuff
@cindex Modems

Modems are finicky beasts, and cajoling them into talking to your
Fnordadel properly can be a tricky piece of business.  This chapter, then,
deals with the various modem configuration options in Fnordadel, and
gives some tips on how to make a recalcitrant modem behave.

@node Basic Modem Requirements, Setting Up the Modem, Modem Stuff, Modem Stuff
@section Basic Modem Requirements

To run a Fnordadel, you must have a modem possessing a
modicum of basic features.  These are:

@itemize @bullet
@item
Must be able to auto-answer the phone.
@item
Must be able to respond to DTR (Data Terminal Ready)
line control by the computer.  DTR is supposed to be
pin 20 on the RS-232 connector.  Ideally, the modem
should be able to hang up the phone, disable auto
answer, and go to `command' mode when the computer flips
DTR off (and reverse the above when DTR goes high).
@item
Must have the CD (Carrier Detect) line tracking the
status of the carrier.  CD (or DCD) is supposed to be
pin 8 on the RS-232 connector.
@item
If you want to do any calling out (i.e., during networking
or whatever), the modem must be able to autodial the
phone using a command string.
@end itemize

Most modems are perfectly capable of all of the above.
If your modem is advertised as being ``Hayes-compatible'', then it
@emph{should} work fine.  The DTR and CD settings will likely have to
be adjusted, since most modems do not by default listen to DTR
and most leave the CD line high all the time.  These behaviours
can be changed either by using a DIP-switch or in the software;
it's almost always possible.

STadel 3.3b, from which Fnordadel is descended, was
advertised to work with the following list of modems, and there's
no reason to believe that we've introduced any incompatibilities:

@itemize @bullet
@item
Avatex 1200, 1200E, 1200HC, 2400HC	
@item
Everex 2400
@item
FastComm 19200
@item
Hayes 1200, 2400
@item
Incomm 2400
@item
MultiTech 1200, 2400
@item
Prometheus 2400B2
@item
Supra 2400
@item
Telebit Trailblazer 19,200
@item
USR Courier 2400, HST 9600
@end itemize

@noindent
The Fnordadel developers both use the Supra 2400; we've been
running 24 hours a day for a few years now and have had no problems
with the wee beasties.  Your mileage may vary, of course.

@node Setting Up the Modem
@section Setting Up the Modem
@cindex Modem setup
@cindex Setup, modem

If your modem meets the above criteria, then we're off.
(If it doesn't, then go buy a real modem---1200 and 2400 baud Hayes
compatible modems are dirt cheap these days.)  In this section we'll
describe some of the @file{ctdlcnfg.sys} options for the modem.

@node Baud rate, Initialisation, Setting Up the Modem, Setting Up the Modem
@subsection Baud rate
@cindex Baud rates supported

You must tell Fnordadel the highest baud rate
at which the modem will function; this is accomplished by
setting the variable
@vindex sysbaud
@code{#sysbaud} in @file{ctdlcnfg.sys}.
@vindex sysbaud
@code{#sysbaud}
can have any one of the following values:

@table @code
@item 0
300 bps only
@item 1
300 and 1200 bps
@item 2
300, 1200 and 2400 bps
@item 3
300, 1200, 2400 and 9600 bps
@item 4
300 up to 19200 bps
@end table

Note that 4800 bps is not supported.  The ST serial port
will do 4800, but we've never heard of a modem that will,
other than ones that will also go faster.  If for some
reason you find yourself in dire need of 4800, see @ref{Fnordadel Support}.

@node Initialisation, Baud-rate detection, Baud rate, Setting Up the Modem
@subsection Initialisation
@cindex Modem setup
@cindex Modem initialisation
@cindex Initialisation, modem

Hayes compatible modems, at least, understand
a set of commands to control their behaviour.  Fnordadel
requires that the modem be set up in a certain way; thus,
you must define a command string which will be sent to the
modem every time Fnordadel wants to reset the modem.
Simply put a line like the following:
@vindex modemsetup
@example
#modemsetup "AT &C1 &D2 V0 E0 M0 Q0 X4 S0=1\r%10"
@end example
@noindent
in your @file{ctdlcnfg.sys}.  The example above will work on many
Hayes-compatible modems.  The various parts mean:

@itemize @bullet
@item
The initial @samp{AT} tells the modem that a command
string is coming.
@item
@samp{&C1 &D2} sets up the required behaviour for the
CD and DTR lines (@pxref{Basic Modem Requirements}).  If your
modem controls CD and DTR with hardware switches,
it probably will not support these commands, so you may have to
remove them.
@item
@samp{V0 E0 M0 Q0} selects numeric result codes (@pxref{Result codes}),
turns off command echoing, turns
off the built-in speaker, and turns on result codes.
@item
@samp{X4} tells the modem to return the full range of
result codes (@pxref{Result codes}).
@item
@samp{S0=1} tells the modem to answer the phone on the
first ring.
@item
@samp{\r} represents a carriage return, which must be
there to terminate the command string.
@item
And finally, @samp{%10} is a special notation which
causes Fnordadel to pause for 10 tenths of a
second (i.e., one second).  This is necessary for
some modems, which take a comparatively long time
to process the command string.  (See the front of
@file{ctdlcnfg.doc} for more on the format of these sorts
of string variables.)
@end itemize

Please be warned that your modem may not recognise
some or all of the above codes; they may be different, or
absent, or whatever.  We've seen some pretty mental modem
behaviour, so be sure to read your modem manual.

A trick which has proved useful with many modems
is as follows:  If the modem allows you to save its
settings in non-volatile @sc{ram} (i.e., if the settings can be
preserved when the modem is powered off), then you can use
a terminal program of some kind to manually set up the
modem the way Fnordadel wants it, by sending your version
of the above command string to the modem.  Then use the command
to save settings (usually @samp{AT&W} or something).  At this
point you can simply use @samp{ATZ\r%10} as the
@vindex modemsetup
@code{#modemsetup}
string; @samp{ATZ} has the effect of resetting the modem to the
saved state.  The advantage of this is that the string is
shorter, so it can speed things up a bit, especially during
networking or auto-dialing when the modem is being reset
many times.

@node Baud-rate detection, Dialing out, Initialisation, Setting Up the Modem
@subsection Baud-rate detection
@cindex Baud-rate detection

Fnordadel must be able to detect the baud rate
of incoming calls, and it has a couple of ways to
accomplish this.  The first is by @code{searchbaud}, and the
second is using result codes.  Result codes are by far the
better method, and since most modems can support the
feature, we recommend it.

@node Searchbaud, Result codes, Baud-rate detection, Baud-rate detection
@subsubsection Searchbaud
@cindex Baud rate searching

If you define the @file{ctdlcnfg.sys} variable
@vindex searchbaud
@code{#searchbaud} to be @samp{1}, it will cause Fnordadel to
loop through the range of supported baud rates (as
defined by
@vindex sysbaud
@code{#sysbaud}; @pxref{Baud rate}), waiting
one-half second at each rate for a carriage return
(@samp{<CR>}) from the caller.  The upshot of this is that
callers must hit @samp{<CR>} once or twice when they
connect with the @sc{bbs}.

@vindex searchbaud
If @code{#searchbaud} is @samp{0}, then your @sc{bbs} will
work at @emph{only} the highest baud rate represented by
@vindex sysbaud
@code{#sysbaud}.  This is last-resort stuff, kids.  You
should normally run with
@vindex searchbaud
@code{#searchbaud} set to @samp{1}
unless your modem absolutely fails to properly
detect other speed connections.  (If your modem is this stupid, it might
be time to consider getting another one.)

The variable
@vindex connectprompt
@code{#connectprompt} modifies
the behaviour of
@vindex searchbaud
@code{#searchbaud} slightly; if defined to be @samp{1}, it
causes Fnordadel to loop through the baud rates,
spitting out a prompt which says ``Type return'' and
waiting for a @samp{<CR>} for a while; it does all this
until the user hits @samp{<CR>} at some baud rate, or
until it gives up.

Anyway, this is all pretty ugly, really;
a far better method is to use result codes.

@node Result codes, 2400-baud operation, Searchbaud, Baud-rate detection
@subsubsection Result codes
@cindex Modem result codes
@cindex Result codes, modem

Most modems, Hayes-compatible ones
included, will send a code to the computer when
they pick up a carrier; furthermore, they can
usually be configured to return a different code
depending on the speed of the connection.  We
utilise this to our advantage.

There is a @file{ctdlcnfg.sys} variable for each
baud rate that Fnordadel supports
@vindex reply300
(@code{#reply300}
through
@vindex reply19200
@code{#reply19200}) which you should set to
match the string that your modem returns when it
connects at that baud rate.  For example:
@vindex reply300
@vindex reply1200
@vindex reply2400
@example
#reply300 "1"
#reply1200 "5"
#reply2400 "10"
@end example
@noindent
are the usual settings for a Hayes-compatible
2400-baud modem.  (As always, your mileage may
vary.)

Please note that the defined reply strings
must be sent (by the modem) terminated with a
carriage return; however, don't put @samp{\r} in the
@code{#reply} strings.  (i.e., if the 300 baud reply sent from the modem is
@samp{1\r}, use
@vindex reply300
@samp{#reply300 "1"}.)

If you've got the @code{#reply} strings defined
in @file{ctdlcnfg.sys}, then Fnordadel will use the
result code method instead of the searchbaud
stuff.  You must have a @code{#reply} string for each
permissible baud rate (i.e., if you defined
@samp{sysbaud 1}, then you need a
@vindex reply300
@code{#reply300} and a
@vindex reply1200
@code{#reply1200} defined before Fnordadel will use
the result code method.)

Note also that you must have the modem
set up to return the codes properly.  @xref{Initialisation}.

@node 2400-baud operation, Connect delay, Result codes, Baud-rate detection
@subsubsection 2400-baud operation

Many 2400-baud modems have a slight quirk.
They will not connect with a 2400 baud caller
unless they have been initialised with the serial
port set at 2400 baud; they will, however, connect
with any lower baud rate no matter what speed
they're initialised at.  We don't know why this
is; but if your modem is like this, there's a
@file{ctdlcnfg.sys} parameter (well, two, actually) which
will help.

Simply define the variable
@vindex init-speed
@code{#init-speed} to
be the baud rate at which the modem should be
initialised; the permissible values are the same
as for
@vindex sysbaud
@code{#sysbaud} (@pxref{Baud rate}).  In the case
of the quirky 2400 baud modems, put @samp{init-speed 2}
and the problem will go away.

Another way of fixing it is to define
@vindex hs-bug
@code{#hs-bug} to be @samp{1}.  This causes Fnordadel to initialise
the modem at the highest supported baud rate,
which is specified by
@vindex sysbaud
@code{#sysbaud}.  Either method
works.

@node Connect delay,  , 2400-baud operation, Baud-rate detection
@subsubsection Connect delay

Some modems, we understand, will croak if
a character is sent to them too quickly after they
connect with an incoming caller.  This could
happen if you've got both @code{searchbaud} and
@code{connectprompt} set.  If it does happen, then
set @code{connectdelay} to be the number of seconds
to wait after carrier is first detected, before
sending anything.

@node Dialing out,  , Baud-rate detection, Setting Up the Modem
@subsection Dialing out
@cindex Dialing out
@cindex Modem setup, dialing out

If you want to do any networking, or if you just
want to use your Fnordadel as a terminal program, then
you have to tell it some stuff about how to make your
modem dial the phone.

@node The dialing commands, Long-distance dialing, Dialing out, Dialing out
@subsubsection The dialing commands
@cindex Modem dialing prefix
@cindex Modem dialing suffix

The relevant @file{ctdlcnfg.sys} variables are
@vindex calloutprefix
@code{#calloutprefix} and
@vindex calloutsuffix
@code{#calloutsuffix}.  As you'd
expect, they should be defined as the strings used
to start and end a dialing command.  The string
sent to the modem will consist of:
@example
<@var{calloutprefix}><@var{number}><@var{calloutsuffix}>
@end example
@noindent
For Hayes-compatible modems, the following
settings work:
@vindex calloutprefix
@vindex calloutsuffix
@example
#calloutprefix "ATD"
#calloutsuffix "\r"
@end example
An optional @samp{T} or @samp{P} may be put after @samp{ATD} to
specify Touch-Tone or Pulse (rotary) dialing.
If your modem is not standard Hayes, then look it
up in the manual.

@node Long-distance dialing, Timing, The dialing commands, Dialing out
@subsubsection Long-distance dialing
@cindex Dialing, long-distance
@cindex Modem setup, long-distance dialing

If the variable
@vindex usa
@code{#usa} is defined to be
@samp{1}, then Fnordadel assumes it is in North
America and will form the dial string for a
long-distance number as follows:
@example
<@code{calloutprefix}>1<@var{area code}><@var{number}><@code{calloutsuffix}>
@end example
@vindex usa
If @code{#usa} is @samp{0}, Fnordadel will simply
spit the number out as-is.

@node Timing, A speed-up, Long-distance dialing, Dialing out
@subsubsection Timing

Two more @file{ctdlcnfg.sys} variables are used
to tell Fnordadel how long to wait for a
connection when dialing out.  The two variables are
@vindex local-time
@code{#local-time} and
@vindex ld-time
@code{#ld-time}; they default to
25 seconds and 50 seconds respectively.  (The time
used for long-distance (``ld'') dialing is longer
because of delays in the phone system.)

@node A speed-up,  , Timing, Dialing out
@subsubsection A speed-up

If you define the variable
@vindex hayes
@code{#hayes} to be
@samp{1}, then Fnordadel will blithely assume that
the modem returns @samp{3} for @samp{NO CARRIER} and @samp{7} for
@samp{BUSY} when it's dialing out.  This is a useful
kludge to speed up dialing out; otherwise, you've
got to wait for the defined amount of time (@pxref{Timing})
to pass before Fnordadel will realise that the call is not going to be
successful.

Please note that defining
@vindex hayes
@code{#hayes} has no
other effect; it will not cause Fnordadel to
assume anything else about the nature of your
modem.

@node High-Speed Modems
@section High-Speed Modems
@cindex High-speed modems
@cindex Port locking

Getting high-speed modems (9600 bps and up) to work with your system
isn't quite as straight forward as with lower-speed units.  For one
thing, if you're using @sc{tos} 1.4 or higher, there is a glitch that
prevents hardware (@sc{rts}/@sc{cts}) flow control from working.  To fix
the problem, you need to install @code{tos14fx2.prg} in your AUTO folder.
@xref{Things to Make Fnordadel Work or Work Better}.

For another thing, high-speed modems are typically able to talk to your
Atari at a fixed speed (usually 19,200 bps), and handle the online user's
varying connect speed themselves.  To make this work properly, you don't
want your Fnordadel to try altering the serial port speed; instead, you
want it locked at a fixed setting.  This is done by setting
@vindex sysbaud
@code{#sysbaud} to the speed at which you wish the system locked,
@vindex searchbaud
@code{#searchbaud} to @samp{0}, and all the result code strings to the
null string, "".  @xref{Searchbaud}, and @ref{Result codes}.

Two side-effects of port locking are that file transfer time estimates will
be out of whack, and the @file{calllog.sys} file will show all users
connected at the locked speed.  These problems will be fixed some day.

@node Common Modem Problems
@section Common Modem Problems

@itemize @bullet
@item
@i{"The modem won't work properly at 2400 baud! Help!"}

@xref{2400-baud operation}.

@item
@i{"What happens if I turn the modem off while someone is online?"}

Nothing bad.  Because you've got the
@vindex modemsetup
@code{#modemsetup}
string defined (you @emph{have} got it defined, right?
If not, @pxref{Initialisation}), the @sc{bbs} will simply
detect the loss of carrier and immediately
reinitialise the modem properly for the next
caller, logging the previous caller off.

@item
@i{"My Blistering-Speed-of-Deth 153,600 baud modem won't work
right with Fnordadel!  Help!"}

Please send us two of the modems in question, and
we promise to have Fnordadel working flawlessly
with them right away!
@end itemize