"What IS all this stuff?"

Well, this is a MEX overlay for the SB180 using the XECOM 12xx MOSART.

Plus a few other odds and ends...

1. First and foremost, this is what the name says it is--an overlay for MEX
that supports the XECOM 12xx MOSART as used on the SB180 COMM180 modem co-
processor board.  It implements all the necessary functions to allow MEX to
oparate on this hardware.  It supports dialing, data input and output, and
hardware disconnect (the MOSART does not have an equivalent of the
Smartmodem 'software' disconnect).  It includes a SET command that allows
changing the baud rate, number of data bits, parity, audio output on/off,
and dialing mode.  Install it into MEX, and MEX will work exactly like it
does on any other machine, and exactly as described in the MEX manual.

BUT, if you want to use a little more of the capability of the MOSART, read
on... 

2. Extended Phone Number Prefix Processing - The Need

MEX allows you to specify up to two additional digit strings as part of your
phone number library.  These two strings are assigned the special
identifiers '>' and '<'.  To add these to another number, simply prefix the
number with the desired character, and the numbers that go with that prefix
identifier will be dialed before the remainder of the number.

Up to a point.

The problem is that MEX allows a maximum of 27 digits to be specified by any
dialing command, including one that uses the prefix identifiers.  For many
people, this is no problem, since their prefix string (typically used to
dial into an Alternate Long Distance Service (ALDS), such as Sprint or MCI)
is relatively short--usually no more than 15 characters.  Plus, these
services can be counted on to (usually) respond within a relatively short
period, which can be programmed into the number with delay characters (if
the modem supports delays).  The MEX manual has a good discussion of how to
use the prefix identifiers for this purpose.

Unfortunately, that does not work for the ALDS I use.  The characteristics
of my system are as follows:

   a) The system is accessed by dialing a toll-free inward WATS (800) number.
      That is 11 digits right there.

   b) After the 800 number is dialed, one of three things may happen:

      1) A busy signal may be presented, indicating that the system is unable
         to accept more calls at the time.

      2) A second dial tone may be presented.  However, the delay time before
         this dial tone starts may be anywhere from a couple of seconds if the
         system is relatively free up to as long as 50 (!) seconds.

      3) If the system is extremely busy (or they are having problems), no
         signal at all is presented--no busy signal, no dial tone, no reorder
         signal, no anything.

   c) If the second dial tone is presented, the password string is dialed,
      (another 8 digits) and, after a very short delay, the third dial tone
      is presented.

   d) The desired number is dialed into this dial tone (including the area
      code--10 more digits).

And then, of course, all the usual things may happen--busy, no ring, ring
but no answer, answer with a modem answer tone, answer with (heaven forbid!)
a voice, answer with nothing, reorder, off-hook, etc., etc.

So, to be able to properly handle all possible cases, the program needs to
be able to:

   a) Insert pauses of an unspecified duration into the dialing sequence,
      until the next dial tone is presented.

   b) If no dial tone if forthcoming, recognize this fact after some amount
      of time and either abort the dialing sequence or start over.

   c) Recognize any of several possible signals (or lack of signal) after the
      desired number is reached.

As far as I know, none of the "Smart" modems comes anywhere close to these
capabilities.  These modems are 'smart' in the sense that they can be told
what to do and how to operate by the software, but they have no ability to
analyze what is happening on the line and report the same back to the
calling program.

3. One Solution

Enter the MOSART.  The MOSART, rather than having a specified set of pre-
programmed command strings with fixed responses, has a very large number of
'functions', each of which does one specific task and returns some type of
result.  The functions associated with dialing are completely separate from
the functions that try to establish modem communications, which are in turn
unrelated to the functions that monitor the status of the phone line.  By
combining these functions, an extremely versatile interface can be
constructed that modifies its operation depending on what happened on the
line during the execution of the process.

Enough of the soapbox.  This is what this overlay can do:

   a) As discussed above, act exactly like the 'Smartmodem'-type dialing
      interfaces available for that type of modem (exception: if you want a
      fixed delay, use a 'P' instead of a ',' in the number.  Also, since
      MEX translates the string to upper case, the delay will be five
      seconds rather than two).

   b) Insert 'wait-for-dial-tone' pauses anywhere in a digit string.  The
      character to indicate where the dial tone wait is to happen is a 'W',
      upper or lower case.  When this character is recognized, the dialer
      will go into a loop, checking the line for a dial tone before dialing
      any more of the number.  Multiple 'W's may be inserted in a string.
      Typing a Control-C will, as usual, abort the dialing process, even
      during a dial tone wait.  Also, if the wait for the dial tone exceeds
      a preset time (set to about 55 seconds in the distribution version),
      the dialer will time out, hang up, and try again.  It will continue
      trying until it is successful or you use the Control-C keyboard abort.

   c) If you always use the same ALDS or prefix string, you can code it into
      the overlay directly.  The string to be dialed is at the label PRENUM:
      near the end of the code.  This string may be up to 39 characters
      long, and it MUST be terminated with a null (binary 0). The way this
      string is used is to place a 'Q' (again, upper or lower case) as the
      FIRST character in the number to be dialed.  This is used as a prefix,
      so it MUST be the first character.  I have defined the '>' MEX prefix
      identifier in my phone library as 'Q' (by typing 'PHONE >=Q' from the
      MEX command line), so I use my ALDS just like the MEX manual talks
      about, i.e., to dial the number 123-456-7890 with the ALDS prefix, I
      just use the MEX command 'DIAL >123-456-7890'. The repeat specifier
      works as advertised, but the repeat count applies to the dialing of
      the actual number; the overlay will handle trying the ALDS line as
      many times as it takes to get through.

   d) If you have TWO ALDS prefixes you like to use, you can put the second
      one in at the label ALTPRE:.  It is used exactly the same way as the
      first one, with the trigger character being 'Y' instead of 'Q'.  So,
      you can define '<' as 'Y', and...

Note that if the total length of (your ALDS access number + password string
+ any 'W's you need for delays + the number you are dialing) is not over 27
characters, you can do the same thing by defining the '>' and '<'
identifiers to be the appropriate strings, just like the MEX manual shows,
with the addition of the 'W's for the delays.  If the total length is 28
characters or longer, you MUST install the ALDS strings into the overlay and
use the 'Q' and 'Y' prefix characters to access them.  It would be nice if
MEX allowed 35 or 40 character phone numbers, but the current limit is 27.

This system should work for all the standard ALDS systems around (IF they
return a dial tone; if not, use fixed delays and hope for the best), as well
as those that the normal fixed-delay sequences can not handle properly.

4. Other stuff.

The other thing that I have added to the overlay is the 'Boot Fail' option
of the SET command.  This provides a (VERY) limited conditional execution
capability for MEX.  One of the major advantages of MEX is that its READ
files allow the process of dialing up, logging onto, and interacting with a
remote system to be automated.  This allows you to set your system up to
wait until 3:17 a.m., when NOBODY in their right mind is on the phone, and
then call up your favorite BBS, log in, get your mail, get a directory of
the upload area, save all of the above to a file, then log off and hang up
the phone.  But what if the phone is busy?  Or the SYSOP forgot to plug the
computer back in after he finished installing his new modem board, and his
wife wakes up and answers the phone instead?  She may be cute, but can she
produce a quality 2225 Hz tone?  A conventional MEX READ script will abort
when the DIAL command returns a failure status.  So far, so good. But what
about the other 3 BBSs you were doing the same thing with, using a multiple
command line, or ZEX, or SUPERSUB?  With the READ script aborted, you will
come in the next morning and find yourself looking at the MEX command prompt
of the failed run, with the rest of the batch patiently waiting for the
current process to quit hogging the phone--literally, since the READ script
never got to the DSC command to hang up the phone.  No wonder your parents
couldn't reach you from Australia to invite you over, all expenses paid, and
had to wake up your sister-in-law instead.  But that's okay, I'm sure she'll
send lots of pictures.

The 'Boot Fail' option allows you to avoid this problem.  When SET ON, this
flag will cause any dialing failure to do a warm boot, rather than returning
to MEX.  This way, the next job on the batch list will gain control, and the
entire job stream will run to completion, with only the failed job affected.
You could even use conditional execution in your job stream (such as the IF
EX test of ZCPR3 to see if the log file the job was supposed to build had
been successfully created) to rerun the failed job again.  This is NOT
conditional execution of items within a READ script, but it DOES provides the
capability to get out of a failed script and get on with whatever else needs
to be done.

5. Some notes on the structure of the overlay.

As you can see, this overlay is in the older 'MXO-' format of the combined
hardware and modem overlays rather than the newer 'MXH-' and 'MXM-' separate
versions.  There are two reasons I wrote the overlay this way:

   a) Time and convenience.  Having the modem overlay separate from the
      hardware overlay would require a bunch of mode setting calls from the
      modem section to the low-level I/O routines in the hardware section
      every time a command needed to be executed or the status of a command
      needed to be checked.  This would increase the size of the modem
      section a little.  This is a relatively minor consideration.

   b) A more serious problem is that the MEX overlay format does not provide
      ANY way to OUTPUT something to the modem's control port.  The hardware
      section does this as part of initialization, but that is no problem,
      since it is purely internal to the hardware section.  However, the
      modem section MUST be able to output control words to the MOSART to
      tell it to change modes back and forth between data and command.  I
      have added such a routine to the hardware section, but, since there is
      no guarantee that future versions of MEX will maintain the same vector
      of subroutines, I have not used this routine.  Thus, the modem section
      has a lot of hardware-specific code in it also.

For these two reasons, the practicality, plus the feasibility, of making
completely independent hardware and modem overlays is doubtful. Rather than
spend a lot of time separating them, using techniques that are not
guaranteed to be portable to future versions of MEX, I have tried to make
the overlays as easy to customize for a particular installation a possible.
As indicated in the overlay itself, all you need to do to adapt the overlay
for a different MOSART installation is to change the definition of the DATA
port address to match your hardware and reassemble the overlay.

This overlay is written in Z80 mnemonics, mostly because I much prefer them
to the 8080 version.  However, some Z80-specific instructions are used,
mostly relative-jump types.  I have included macros to convert these to the
equivalent 8080-compatible expansion.  If you are using a MOSART in an 8080
or 8085 system (or maybe a V20 system?), change the definition of the
'I8080' equate to TRUE and reassemble the overlay.  Of course, you must have
an assembler that accepts Z80 mnemonics and macros.

6. Known bugs/anomalies.

Yes, it pains me to admit it, but the system occasionally does strange things:

   a) Dial mode switching.  I have not been able to get the MOSART to
      reliably switch back and forth between tone and pulse dial modes.
      Specifically, the SET DIAL PULSE command WILL switch the MOSART to
      pulse dialing, but a subsequent SET DIAL TONE will not always make it
      go back to tone dialing.  This may simply be a problem with my system.
      However, it is not really that much of a problem, because you aren't
      going to need to switch dial modes while you are connected (at least
      not very often).  By using the SET DIAL TONE command and then using
      the SET BPS command (which can ONLY be used when there is not an
      active connection), the MOSART will be reset to its default tone-dial
      mode.  You don't have to use a different BPS rate; just use the SET
      BPS command to set the BPS rate to what you are already using, and the
      MOSART will go back to tone dial.

   b) Depending on the characteristics of your switching network, the two
      second pause after the MOSART returns a 'V' status, indicating a
      voice, may not be long enough.  The MOSART is very sensitive to
      transients on the line when using the 'M' line-monitor command, and
      will return a 'V' status when it hears the switching transients as the
      connection completes.  The pause is designed to allow the line to
      settle down before checking again, and then verifying that the noise
      was really a voice.  If you start getting 'VOICE!!' aborts when you
      KNOW that no such voice answered, try increasing the delay value by
      changing the lower-case 'p', which gives a two second pause, to an
      upper-case 'P', for a five second wait.  If the problem persists, you
      may have to code the VOICE: routine with a loop that checks the status
      more than twice, with appropriate delays, before returning the abort
      status code.

7. Notes to modifiers.

If you modify the dialing routines, be very careful to keep track of the
stack!  The 'BOOTFAIL' kluge sets up the abort by pushing a zero word onto
the stack as the pseudo return address.  A successful connection returns to
MEX via the ONLINE routine, which pops this extra word off the stack.  All
the various failure modes return directly, so they will end up being sent to
the warm boot vector if BOOTFAIL is ON.  When modifying this routine, make
sure your routines end up at the same place on the stack, or you may find it
impossible to dial without warm booting the machine.  Similarly, be careful
to preserve the value in A at the end of the different dial failure
routines.  The value in A tells MEX what the problem was, so the appropriate
error message can be printed.

8. Soapbox. Part 2.

Note that the word 'baud' does not appear anywhere in the overlay.  In fact,
the line above is the only place you will find that word anywhere in this
package.  The term does not apply to current modem communication protocols,
and I have used the more correct term BPS (bits per second) in all
discussions of the data transfer rate.  Purely a personal preference, but
eventually the 'BPS' term will probably be the only one used, since it more
properly relates to what is really happening on the line.

I will be glad to help anyone who wants assistance in modifying the overlay
to work with other systems, or wants to add to or change the command
structure or operation of the overlay.  Please feel free to contact me at
the BBS numbers below, or by voice.

Steve Dirickson                                            26 Feb 1987
ZNode #12: 206-325-1325
ZNode Central: 415-489-9005
Voice: 206-697-1270