uupc establishes connections with other sites by use of what is known as 
a "chat script".  A script of this sort consists of a set of "expect" 
strings (what uupc expects to "hear") and a set of "send" strings (what 
uupc will send when it "hears" what it expects).  Chat scripts can have 
some small amount of "intelligence", in the sense that an "expect" string 
can specify some actions to be taken if the expected string is _not_ 
received within a reasonable amount of time.  It isn't possible to built 
any very sophisticated scripts within uupc, however... loops and 
branching within scripts is not possible.

uupc is most easily used with a Hayes-compatible modem.  With modems of 
this sort, you can use the built-in "HAYES" dialer to place calls to your 
neighbor sites.  The HAYES dialer is flexible enough to work with most 
modems which support extensions to the Hayes command set... you can 
include additional commands, options, and S-register settings in the chat 
script, and the HAYES dialer will add them to the commands it sends to 
the modem.

If you have a non-Hayes-compatible modem, you won't be 
able to autodial... instead, you'll have to write up a complete chat 
script to send dialing commands to the modem and handle the modem's 
responses.

-----

SETTING UP UUPC TO USE A STANDARD MODEM CABLE

By "standard modem cable", I mean a cable which wires the Mac's
"handshake output" pin to the modem's Data Terminal Ready (DTR)
input, and wires the "handshake input" pin to the modem's Carrier
Detect (CD) or Data Set Ready (DSR) pin.

You should set up the modem's DIP switches, S-registers, and/or other 
options or nonvolatile memory so that the modem will behave in the 
following fashion:

-  The modem should be configured to "watch DTR" or "honor DTR"... that 
is, it should pay attention to the Data Terminal Ready signal from the 
Macintosh.  uupc raises (asserts, turns on) DTR when it wishes to place a 
call or is willing to accept an incoming call.  uupc lowers (deasserts, 
turns off) DTR to signal that it has completed a call, and wishes the 
modem to "hang up the phone".

Many Hayes-compatible modems are delivered with a different default 
setup... "provide DTR" or "ignore DTR".  Modems which are set up in this 
fashion will not hang up the phone when DTR is deasserted;  this will 
cause uupc to become confused, or to fail to terminate calls reliably.

Some Hayes-compatible modems can be set up so that deasserting DTR not 
only hangs up the phone, but also resets the modem to its default 
condition.  If your modem supports this option, I recommend that you use 
it... either by storing this option in the modem's nonvolatile memory 
(best) or by including the command needed to activate this mode in the 
HAYES dialer specification.

-  The modem should be connected to the Macintosh with a standard 
"Macintosh to modem" peripheral cable.  You should NOT use a "hardware 
handshaking" cable, which connects the Mac's handshaking pins to the RTS 
and CTS lines on the modem... these cables do not allow uupc to control 
the DTR line, and the modem won't work properly (it either won't go 
off-hook and dial, or won't hang up when you expect it to).

-  The modem should be set up with the "auto-answer" feature disabled.  
This is usually done via a DIP switch, or by setting the S0 register to 
zero.  uupc will enable auto-answering when it's ready to accept an 
incoming call.

--------

SETTING UP UUPC TO USE A HARDWARE HANDSHAKING MODEM CABLE

By "hardware handshaking modem cable", I mean a cable which wires the 
Mac's "handshake output" pin to the modem's Request To Send (RTS)
input, and wires the "handshake input" pin to the modem's Clear
To Send (CTS) pin.  Some hardware-handshaking cables wire the Mac's
handshake output to BOTH the DTR and RTS pins.

You should set up the modem's DIP switches, S-registers, and/or other 
options or nonvolatile memory so that the modem will behave in the 
following fashion:

-  The modem should be configured to "ignore DTR" or "provide DTR"... that 
is, it should ignore the Data Terminal Ready signal from the 
Macintosh, since the cable may not be wiring anything to that pin, or
may be providing an inappropriate signal.

-  The modem should be set up with the "auto-answer" feature disabled.  
This is usually done via a DIP switch, or by setting the S0 register to 
zero.  uupc will enable auto-answering when it's ready to accept an 
incoming call.

-  You must use one of the following dialer types or connection tools
if you are using a hardware handshaking cable:

[1] Use a direct connection to your Mac's serial port (specify "a" or "b"
    for the port identifier), and specify "HAYES*" or "HAYES*options" as 
    the dialer.  The HAYES* dialer specification tells uupc to lock
    the serial port speed (the port will not attempt to switch speeds 
    based on the CONNECT message from the modem), tells uupc to use a "software" 
    disconnection command to hang up the modem, and enables hardware flow 
    control on the serial port.
    
[1] Use the Communications Toolbox, specify the Serial Tool in your CTB
    configuration, specify "DTR & CTS" handshaking in the Serial Tool 
    configuration dialog, and specify "HAYES*" or "HAYES*options" as 
    the dialer.
    
[2] Use the Communications Toolbox interface, specify the Apple Modem 
    Tool in your CTB configuration, specify "DTR & CTS" handshaking in
    the Apple Modem Tool configuration dialog, and specify the "DIR" 
    non-dialer in your Systems file.


FLOW CONTROL, COMPRESSION, AND PROTOCOLS

Many modern Hayes-compatible modems support one or more of the following:

-  Error control... MNP levels 3 or 4, or V.42.  When both modems in a 
conversation support a particular error-control protocol, and when the 
protocol is enabled, the modems will provide a nearly-error-free 
communication link even if the phone line is somewhat noisy... data is 
checked for correctness, and retransmitted one or more times if it's 
incorrect.

-  Compression... MNP level 5, or V.42bis.  Modems which support 
compression will "squeeze" data into a smaller form, using a 
sophisticated "lossless" compression algorithm such as Huffman or 
Lempel-Ziv coding.  Some data (ASCII text) can be compressed by as much 
as 4:1;  other data (.SIT files) cannot be compressed by any significant 
amount.

- Flow control. Error-controlling and data-compressing modems are usually
capable of accepting data from a computer (or a human) faster than it can
be sent over the phone line, and storing the data for transmission at the
earliest possible moment. Modems of this sort can usually signal the
computer that their storage capacity is running out, and that additional
data should not be sent until some of the older data has been successfully
transmitted. Two forms of flow control are commonly used: XON/XOFF or
"software" flow control, in which special ASCII characters are used to
indicate "stop sending" and "OK, go ahead", and RTS/CTS or "hardware" flow
control, in which electrical signals on the serial-port connector are used
to control data transmission).

In order for uupc to work properly, you _must_ configure your modem for 
the correct sort of error control, compression, and flow control.  The 
wrong settings can prevent uupc from working at all, or can greatly 
reduce the throughput of a uupc connection.

You may want to store these configuration settings in your modem's 
nonvolatile memory.  More commonly, you'll want to include the necessary 
commands in your chat script... append them to the HAYES dialer 
specification (e.g. "HAYES+commands" or "HAYES!commands" or 
"HAYES*commands").

RULES OF THUMB FOR THE 'g' PROTOCOL

For the normal 3-window 'g' protocol: turn all flow control OFF! This is
CRITICAL! The 'g' protocol is self-pacing, and does not require either
hardware or software flow control except under very unusual conditions.  

The 'g' protocol is COMPLETELY incompatible with XON/XOFF flow control!
The 'g' protocol insists on being able to send all 256 ASCII data codes,
without interpretation or interference by the modem. If XON/XOFF flow
control is in use at _any_ point in the communication path between uupc and
its peer, the protocol will eventually stall and will not recover. 

Hardware (RTS/CTS) flow control can be used with the 'g' protocol, but it is 
normally unnecessary.  You'll need to use a hardware handshaking cable, 
and one of the port/dialer combinations which supports hardware 
handshaking (see above).

For most 'g' protocol sessions, turn error control and data compression 
off.  Error control adds delay to most transmissions, and this will cause 
the 'g' protocol to run more slowly than otherwise possible.

  [Possible exception:  if your peer site supports a 'g' protocol window 
   of more than 3 packets, and if your files are long enough to require 
   more than a few seconds each to transmit, try turning error control and 
   data compression on, if your modems support them.  You may get better 
   throughput.  You'll have to increase the port speed... for example, if 
   you're placing a call at 2400 bits/second, use a speed setting of 4800 
   or 9600 in your chat script... and call the dialer "HAYES!" rather than
   "HAYES" so that it will lock the serial port at the higher speed.  Specify
   'g7' in the protocol field, to enable a larger window.]
   
RULES OF THUMB FOR THE 'f' PROTOCOL

The 'f' protocol is a very different beast.  It REQUIRES that the modems 
support error control and flow control... and it works very 
well indeed with modems which support data compression, and which are 
operating at a high serial-port speed.  I've used 'f' with both the
MNP 3/4 error control protocol (with its attendant MNP 5 data compression
capability) and the newer V.42 error control protocol (with V.42bis
compression).  If your modem supports either of these protocol suites, and
if the system you're calling has a compatible error-control modem and is
capable of using the 'f' protocol, you may want to give it a try.

The 'f' protocol implementation in uupc 3.0 is designed to work with the
same type of serial cable as the 'g' protocol uses... that is, the cable is
not required to support hardware flow-control handshaking.  When uupc starts
up an 'f' protocol session, it configures the Mac's serial ports for
XON/XOFF flow control, which works quite well with 'f' (although it's slow
death if you try to use it with 'g').  Naturally, this requires that the
modem be capable of supporting XON/XOFF flow control (almost all error-
controlled modems do) and that the modem be configured to actually use
XON/XOFF flow control.

The best way to set the modem configuration is to tell the HAYES dialer how
to do so.  This is done by invoking the dialer as "HAYES+options" or as
"HAYES!options", rather than simply as "HAYES".  The "options" would be the
necessary S-register settings, or other modem command codes needed to
turn on XON/XOFF flow control.  For example, on a U.S.Robotics Dual Standard
modem, an appropriate dialer specification would be

   barney Any a HAYES!&B1&M4&H2&I2 19200 5551212 f ogin: me word: again

This means

-  Use the Hayes-compatible-modem dialer;
-  Send commands to the modem port (a) at 19200 bits/second.
-  Do not change the Mac's serial port speed to match the CONNECT message (!);
-  The modem should not change its serial-port speed to match the speed of
   the actual connection, but should continue to operate at the speed at
   which the dialing command was sent (&B1);
-  The modem should insist upon an error-controlled session, and should
   disconnect if it cannot negotiate error control with its peer (&M4);
-  The modem should use XON/XOFF flow control when accepting data from
   the Mac (&H2) and when sending data to the Mac (&I2);
-  Use the 'f' protocol (f).

You can, if you wish, use the 'f' protocol with hardware flow control.  To 
do this, use a hardware handshaking cable, and use one of the port/dialer 
combinations noted earlier in this document.

If your modem supports data compression, you'll get the best throughput if
you use the highest serial-port speed that your modem supports (e.g. 19200
bits/second or faster for a V.32 modem), and instruct both the modem and
the Macintosh to lock their serial ports at the higher speed regardless of
the actual modulation speed of the session (e.g. 9600 bits/second for a
V.32 connection).

It's important to remember that the 'f' protocol requires flow control at
both ends of the connection.  You'll have to make sure that the system
you're calling, and the modem that it uses, are capable of supporting
flow control, and have been configured to do so.

If you're calling another Macintosh running uupc, flow control should be
specified in the dialer field for the INCOMING entry on the system which
is receiving the phone call (very much as was done above, in the entry for
"barney").

If you're calling a Unix system, you should ask the system administrator to
make certain that the port you're calling is configured for flow control.
Hardware flow control (RTS/CTS) is usually most appropriate for Unix
systems.  This usually requires that the modem be pre-programmed for this
form of flow control (the necessary options being placed in the modem's
nonvolatile memory), and that the Unix "login" or "getty" program
enable hardware flow control for the serial port (via options in the
/etc/ttytab or /etc/gettytab file, or equivalent).