UUPC and the Communications Toolbox
-----------------------------------

Starting with version 3.1b6, uupc supports the Macintosh Communications
Toolbox.  That is to say, uupc can use the Connection Manager, and any
available connection tool, in place of the Serial Driver (the Serial Driver
interface still works, naturally!).

Support in 3.1b9 handles both inbound and outbound calls. Performance
should be comparable to the Serial Driver implementation. There are
probably still bugs which may cause irregular behavior or crashes.

Basic philosophy
----------------

When you use the Serial Drivers, you can use either of two methods to cause
your modem to place a phone call to your neighbor site.  These methods are
selected via options in the site's line in your Systems file.

* You can specify one of uupc's built-in dialers (either HAYES or VADIC),
specify the baud rate and phone number, and let the uupc dialer talk to
the modem, autobaud it, dial, and interpret the CONNECT or BUSY messages.

* You can specify the DIR (direct-connection) "dialer", which simply
opens the serial port connection;  your chat script (the expect/send
strings) must send commands to the modem and wait for the modem's responses.

When you use the Communications Toolbox, you have both of these options,
and even more.  You can use the dialing or call-connection facilities
in a CTB connection tool;  you can use a CTB tool to give you access to a
modem or serial port on your Mac, and use uupc's HAYES dialer to place the
call;  or, you can use a CTB tool to access a serial port, and drive the
modem yourself via a chat script.

Setting up a Communications Toolbox configuration
-------------------------------------------------

Access to the Communications Toolbox takes place through connection
records, which you must configure using menus and dialogs.

To create a new connection record, select "New..." from the "CTB" menu.
A dialog box will pop up, selecting a default connection tool (usually
the Apple Serial Tool).  Choose the tool that you really wish to use...
e.g. the Apple Modem Tool, Apple ADSP Tool, or some other tool... and
configure it with whatever information, options, phone numbers, network
addresses, etc. are relevant.  Click the OK button.  You'll be asked to
enter the name under which this configuration should be stored... do so
(names which do not contain blanks are preferred).

To alter an existing configuration, choose its name from the CTB menu,
edit the configuration, and click OK.  The configuration will be updated
and stored.

To duplicate an existing configuration, hold down the shift key and
select its name from the CTB menu.  The configuration will be "cloned" and then its
dialog box will appear.  Make any changes you want (which will apply to the
new version, not the original!) and click OK.  You'll be prompted for
the name under which the new configuration should be stored.

To delete an existing configuration, hold down the option key and select
its name from the CTB menu.  A confirmation dialog box will appear;
click Delete or Cancel as appropriate.

Using Communications Toolbox configurations
-------------------------------------------

In order to use a connection tool to place a call to one of your uucp
neighbors, you must modify the neighbor's line in your Systems file. In the
field which normally specifies a serial-port name (usually "a" or "b),
place a string of the form "CTB/configurationname". The "configurationname"
should be the name of a CTB configuration that you have created and saved.
When you place a call using the information in this line in the Systems
file, uupc will bypass the Serial Driver, load the CTB configuration you
specified, and use it to initiate a connection

Accessing auxiliary serial ports
--------------------------------

The simplest way to use a CTB tool is to use it to give you access to 
a serial port on your Mac.  This is usually done with the Apple Serial
Tool.  Using this tool, you may specify the modem port, printer port, or
any auxiliary port which has been registered with the Connection Manager.

For a connection of this sort, you will usually specify the HAYES dialer,
and allow uupc to dial the call for you.  You may, if you wish, specify
the DIR non-dialer, and place the call "manually" using the chat
script.

Using a Modem Tool (Apple's or otherwise)
-----------------------------------------

You may wish to use the Apple Modem Tool to establish a connection with one
or more of your neighbors. The Apple Modem Tool supports a number of
popular modem types, and supplies certain features that uupc's built-in
HAYES dialer does not (automatic redial, RTS/CTS flow control, "soft"
hangup using the Hayes +++ escape sequence, etc.). To do this, you must
create a CTB configuration which selects the Apple Modem Tool, and
specifies whatever options you feel are appropriate.

When you use a Modem Tool to place a call, you will NOT be using the
HAYES dialer which is built into uupc.  For this reason, you MUST specify
the "DIR" (direct connection) non-dialer whenever you use a Modem Tool to
place a call.  Otherwise, massive confusion will result!

You may, if you wish, store the phone number in the CTB configuration, and
omit the phone number from the line in your Systems file (simply put a
hyphen in the phone number field).  You'll probably want to use this
approach if you have only a single uucp neighbor, or if you decide that
you'd rather have one CTB configuration per neighbor.

Or, you may leave the phone number out of the CTB configuration, and
specify it in the Systems file (just as you normally do when using the
built-in Hayes dialer). If the phone number is present in the Systems file,
it will override the number stored in the CTB configuration record. This
allows you to use one CTB configuration to place calls to two or more
neighbors.

Similarly, you may specify the baud rate in either of two places - in the
CTB configuration record, or in the Systems file.  If a baud rate is
present in the Systems file, it will override the baud rate in the
configuration record;  if the baud-rate field in the Systems file simply
contains a hyphen, it is ignored, and the baud-rate field in the
configuration record is used.

Using other connection tools
----------------------------

You can use other sorts of connection tools... for example, the Apple
ADSP Tool... in much the same way as you would use a Modem Tool.
Fill out the connection information completely, store it, name it in the
CTB/port field in the Systems file entry, and use the DIR direct-connection
non-dialer.

You may pass options to a connection tool, by placing them in either the
baud-rate or phone-number fields in the Systems file.  Options are specified
as a single string of the form:

	'name value name value'

where the names and values of the options are defined by whatever Connection
Tool is being invoked.  uupc simply passes these options through to the
tool, and passes back any error information it receives in return.  It
does not attempt to interpret these options itself.  Don't put more than
127 characters (excluding quotes but including quoted spaces) in either of
these fields, or Bad Things will happen.

Background, foreground, and synchronous operation
-------------------------------------------------

uupc can perform I/O to the Communications Toolbox in any of three modes.
These three modes differ in performance and compatibility.  In theory, 
the highest-performance mode should always work... and I've made it the 
default for that reason - but I've encountered a number of CTB Connection 
Tools which do not appear to implement all of the connection services 
properly, and may require one of the lower-performance modes to operate 
correctly.

In order to configure your connection to use one of these modes, place 
one of the following keywords in the baud-rate field in the line in your 
Systems file:

-  "-background".  The -background keyword specifies the highest- 
   performance mode of operation.  It allows uupc to use asynchronous I/O 
   calls, and allows additional data to be written from within an I/O 
   notification subroutine.  This mode works fine with the Apple Modem 
   Tool and the Serial Tool.

-  "-async".  -async allows uupc to use asynchronous I/O calls, but 
   forbids uupc from attempting to write additional data to a connection 
   from within an I/O notification routine.  This mode is required with 
   some versions of the Hayes Modem Tool.
   
-  "-sync". -sync completely disables all asynchronous CTB operations.  
   It hurts performance and makes uupc much less friendly in a 
   MultiFinder or System 7 environment - other tasks get almost no CPU 
   time at all while uupc has a connection open.  The -sync operation is 
   required with some versions of the TGE TCP Tool (but not with more 
   recent ones).

Listening for inbound calls
---------------------------

To receive incoming calls using a CTB tool, set up the configuration in
the usual way.  In the Systems file line for the INCOMING pseudo-neighbor,
specify "CTB/configurationname" in the device field, either "DIR" or "HAYES"
in the dialer field, and specify "@" in the phone-number field.  You should,
as always, specify the "HAYES" dialer only if you're using the Serial Tool...
for other tools, specify "DIR", and let the tool itself listen for the
inbound call.

Tool-supplied progress windows
------------------------------

Some connection tools, such as the Apple Modem Tool, will put up a non-modal
dialog box when opening or closing a connection.  uupc 3.1 suppresses the
appearance of these dialog boxes when it's run in the normal (no-debugging)
mode.  The dialog boxes are enabled when debugging is turned on (level
1 or above).

Examples of use
---------------

In these examples, please assume that the following CTB configurations have
been created and stored:

	modem - Serial Tool, accesses the modem port
	work  - Apple Modem Tool, set up to dial my Sun at work

#
# Call my system at work, using the Serial Driver and the HAYES dialer
#
ntg Any a HAYES+&B1&M0 9600 5551212 g7 ID? GHOTI ogin: IAM word: TRUSTME
#
# Call my system at work, using the Comm Toolbox to gain access to the
# modem port, and use the built-in dialer
#
ntg Any CTB/modem HAYES+&B1&M0 9600 5551212 g7 ID? GHOTI ogin: IAM word: TRUSTME
#
# Call my system at work, using the Apple Modem Tool.  The phone number
# and baud rate are already in the CTB configuration, and are not
# respecified here.
#
ntg Any CTB/work DIR - - g7 ID? GHOTI ogin: IAM word: TRUSTME
#
# Call my system at work, using the Apple Modem Tool.  Override the phone
# number in the CTB configuration.
#
ntg Any CTB/work DIR - 5551313 g7 ID? GHOTI ogin: IAM word: TRUSTME
#
# Call my system at work, using the Apple Modem Tool.  Override both the baud
# rate and the phone number
#
ntg Any CTB/work DIR 2400 5551414 g7 ID? GHOTI ogin: IAM word: TRUSTME
#
# Listen for incoming calls using the Apple Modem Tool.  It doesn't matter
# if there's a phone number in the configuration, as specifying "@" here
# will cause it to be ignored, and an inbound-call listening operation to
# take place.  If the caller requests the 'g' protocol, start negotiation
# with a larger packet-size and window than is the default (this won't
# affect the 'f' protocol if that's what the caller requests).
#
INCOMING Any CTB/work DIR - @ g7/128

Caveats
-------

I've tested the incoming-call listener with the AppleTalk ADSP tool, over
a Rube Goldberg sort of AppleTalk connection which involved a dialup
Async AppleTalk connection, UDP, EtherTalk, a FastPath box, and LocalTalk
to another Mac.  It actually worked, much to my amazement.  g3/64 sessions
worked, with throughput limited to about 200 bytes/second over a V.32 link
(too much latency).  g7/128 didn't work, apparently due to timing and
error-recovery problems in the protocol that I haven't chased down yet.
The 'f' protocol worked like a charm with excellent throughput - not
surprising, as it's intended to work over long-distance networks.

I haven't yet run real-world tests on the incoming-call listener using
the Apple Modem Tool - it should work, but I can't guarantee that it will.

I've had rather poor luck trying to use the Apple Modem Tool (version 1.1)
with high-speed, speed-buffered modems (those in which the serial port
speed is locked at a higher rate than the modem-to-modem modulation).
The Apple Modem Tool has an annoying habit of "blasting" Hayes-style
commands at the modem at full speed.  This seems to cause the command-
autobauding logic in some modems to fail... not only does the modem fail
to recognize the command, but it also goes into some severely confused
state and won't recognize commands at _any_ speed until its power is turned
off and then on again.  I deliberately introduced delays into the uupc
HAYES dialer to keep this from happening;  there doesn't seem to be any
way to persuade the Apple Modem Tool to insert similar delays.

So - use the Apple Modem Tool at your own risk of frustration.  At high
line speeds, I find uupc's HAYES dialer to be more reliable.

The code has not yet been extensively beaten upon.  It may hang, crash,
or defoliate your houseplants.  No guarantees.