.--------------------------------------------------------.
| ECU README - last revised Sat Sep 12 18:28:06 EDT 1992|
`--------------------------------------------------------'

This is ecu revision 3.20.  ECU is a asynchronous communications
program for these environments:

  SCO XENIX System V/286          ECU may be too large for '286
  SCO XENIX System V/386          ECU is stable on SCO XENIX/386
  SCO UNIX System V/386           ECU is very robust on SCO UNIX
  SCO ODT 1.x,2.0                 ODT is the same as UNIX for ECU

  ISC 386/ix 2.2 or later         Ports to these systems are
  ISC System V Release 4          not supported as regularly
  ESIX System V Release 4         and I cannot vouch for
  SunOS 4.1.[12]                  them at time of release 
                                  PLEASE GIVE ME FEEDBACK!

ECU (Extended Call Utility) is a research and engineering
communications program originally written for users of SCO UNIX
V.3.2/386 and XENIX V on 80286 and 80386 systems.  Support for
other systems has been added and further porting is possible with
"minor" effort to other systems based on or similar to UNIX
System V.

ECU provides the classic terminal communications facility of
passing keyboard data to a serial line and incoming data to the
computer video display.  In addition, a dialing directory, a
function key mapping feature, session logging, and other
basic features are available.  

ECU presents to the host a flexible "ANSI" terminal type,
accepting any valid video control sequences from MS-DOS or SCO
documentation as of late 1990.  It also fares well, though
imperfectly, with Sun and VT-100 in-band video control sequences.
Standards are great: everybody should have one, especially if
they call it "ANSI". For more information, refer to the manual
section titled "ANSI Filter."

Support for arbitrary video consoles is included.  I use ECU
(almost exclusively now) with an X11R4 xterm.  This release has
been tested extensively with xterms (particularly Metro Link
X11R5, SCO ODT 2.0 X11R4, SunOS 4.1 MIT standard distribution,
OpenWindows 2.0, and Roell's X386 1.1b).  Your terminal must be
fairly "smart", with insert/delete-line features,
erase-to-end-of-line, etc..  See "Supported Terminals" in the
manual.  Also check the note below named "KBDTEST3".

ECU supports numerous file transfer protocols: as of this
writing, XMODEM, XMODEM/CRC, XMODEM-1K, YMODEM/CRC Batch,
ZMODEM/CRC-16, ZMODEM/CRC-32, C-Kermit 5 and SEAlink are
supported.  For more information, refer to the manual sections
describing the individual interactive and procedure file transfer
commands.

A very flexible procedure (script) language is also incorporated
to automate many communications tasks.  In addition to augmenting
interactive tasks, by using shell scripts and ECU procedures, ECU
can perform batch-style communications sessions in an entirely
"unattended" fashion.

For applications too unwieldy for the procedure language,
"ecufriend" programs are supported.  Friends are spawned by ECU
having access to the shared memory segment containing an
ECU-managed "screen image" and other data and having use of the
attached communications line.

Gcc is supported for all programs in the release.  See the
configuration section and the note on gcc for important caveats.

Ports to ISC 2.2, ISC SVR4 and ESIX SVR4 and SunOS 4.1.1 are
fairly stable and useful, though not all features are working.
Also, the documentation suffers in covering these ports.

The doc subdirectory has all of the .txt files used to produce
ecu.man, the manual of sorts for the program.  A copy of it is
reluctantly included (net.bandwidth) for those who do not have
nroff.  I finally blew up my nroff with something related to
document length, so there are two documents, ecu.man and
proc.man.

*Please* take the time to read the (tedious) manuals and READMEs
even if you are a pre-3.20 user.  This will do me honor and
yourself justice because there are a lot of goodies in here,
many of which are not traditional features you'll be looking for.

--------------------------------------------------------------------

ACKNOWLEDGMENTS

MANY THANKS to those who helped me improve the program,
especially upaya!tbetz, ache@hq.demos.su, spel@hippo.ru.ac.za,
bel@trout.nosc.mil, dhmadsen@icaen.uiowa.edu, dug@kd4nc,
jts@ki4xo, jsm@n4vu, lamy@glsys.in-berlin.de, cma@tridom,
tabbs!aris, redi!donovan, neal@clkwrka, extel@quagga.ru.ac.za,
mjb@mjbtn, tmcsys.uucp!lothar, mju@mudos.ann-arbor.mi.us
elastic!fche, genrad!rob and spooley@compulink.co.uk.  There were
lots of others and I know I've forgotten someone who helped a
great deal; I apologize.

Very special thanks go to Dion L. Johnson at SCO for his untiring
and generous support.  Also, many kudos the guys at Metro Link for
their excellent X11R4/X11R5 package.  Yes, xecu has been born and is in
the works at last.  Right now, it is a telnet socket user only,
but serial I/O is on the way.  ECU may learn about telnet too.

Lothar Hirschbiegel <aega84!lh> did the ISC SVR4 port -- 
THANKS, Lothar!

Joseph H Buehler <jhpb@sarto.budd-lake.nj.us> extended the SVR4
port to ESIX -- THANKS, Joesph!

Robert Lewis <robertle@sco.com> and John Dashner <wa4cyb!jmd>
proofread the manual.  This is tedious work and special thanks
go to them.

The 3.20 alpha team of 

    Clayton Haapala       clayh@network.com            
    Cliff Yamamoto        cyamamot@kilroy.Jpl.Nasa.Gov 
    Jeff Liebermann       jeffl@comix.santa-cruz.ca.us 
    John Dashner          wa4cyb!jmd                   
    Joseph H Buehler      sarto!jhpb                   
    Lothar Hirschbiegel   aega84!lh                    
    MarK J. Bailey        root@mjbtn.jobsoft.com       
    Mark Ashton           n4hgf!ifsbd!cma              
    Robert Laughlin       bel@nosc.mil                 
    Robert Lewis          robertle@sco.com             
    Robert Lipe           robertl@arnet.com            
    Tim Sailer            tps@jptcs.com                

worked diligently daily over many weeks.  If there are fewer bugs
in this initial release than in previous releases, you have them
to thank.  It would have been many more months before 3.20 saw
the light of day (if ever) without their support.

--------------------------------------------------------------------

HOW NOT TO START DOWN THE WRONG PATH HERE

C Kermit 5 is a much, much better product than ECU.  It runs
in zillions of environments, is much more robust and has many
better features.  I wrote ECU when there was nothing like it
available.  Since then, C Kermit has grown sliding windows
and an excellent script language.  C Kermit won't do X/Y/ZMODEM
(although you can get there from here).  It doesn't have a gnarly
shared memory interface for "friend" programs (I do not know
of any one but me who has used it).  C-Kermit has
hundreds of implimenters/testers, thousands of users and two
most righteous Captains (Frank daCruz and Christine Gianone)
behind it.  ECU has less than 10 developers and about 15 users :-).

I will happily maintain and improve ECU for those who want it,
but if you are not a C hacker and unabashed techie (or even if you
*are*), C Kermit 5 is probably the asynchronous package for you!

--------------------------------------------------------------------

MAKING AND INSTALLING

1.   Unshar all of the shars

     I do not put anything in shell archives that is intentionally
     dangerous, but it is very, very unwise to unshar as root.
     Unpack shell archives as an unprivileged user.

     Make a directory and cd into it.  Use an unshar program
     to extract all of the forty-odd parts of ECU and the three
     or so parts of the manual.  If you do not have unshar, it
     may be quicker to find one than to extract ecu without it.
     However, if you must, edit each shar and remove all lines
     prior to #!/bin/sh and then feed each file to /bin/sh, like

        /bin/sh < part

2.   Type ./Configure

     This procedure builds Makefiles for ECU specific to your
     system.

     You must have your native compiler available for this.
     If it unavailable and you have gcc, you can TRY:
       gcc -fwritable-strings -fpcc-struct-return -o config config.c
       ./config
     If you are running *SCO UNIX*, add -DM_UNIX to the above gcc line.
     This alternate procedure is not guaranteed to work with future
     patchlevels and releases (There will always be a way to do it,
     but I very likely will be counting on SCO MSC M_... predefines more
     and more).

3.   Configure will compile and run config. 

     Answer the questions.  If you are using a supported system,
     answering the few simple questions is all that is necessary
     to produce a usable configuration.  (If you are trying to
     port it, make your best guess, hack the Makefiles and sources
     and send them to me with your patches.)

     You will be asked the system type.  Respond according to
     the following table:

        System                         |   Type
     ----------------------------------+------------
       SCO UNIX (any version)          |     s
       SCO ODT (any version)           |
       SCO XENIX (2.0.6 or later)      |
     ----------------------------------+------------
       ISC 386/ix (2.2 or later)       |     i
     ----------------------------------+------------
       SunOS (4.1.1 or later)          |     S
     ----------------------------------+------------
       ISC SVR4                        |     I
     ----------------------------------+------------
       ESIX SVR4                       |     E


     If you answer SCO, you are asked which variety: XENIX/286,
     XENIX/386 or UNIX/386 prior to 3.2v4, or UNIX/386 3.2v4.

     Provided you did not opt for XENIX/286, you will be asked if
     you want to use the native cc or gcc.

     If you ask for gcc, you'll be asked if you have gcc 1.40 or
     not.  An obscure minor bug in 1.39 was fixed in 1.40 and
     it amounts to little effect as of this writing.  Answering
     no is safe, but future patches make make better use of the
     configuration information.

     You will be asked for a default tty line, baud rate and parity.
     The default for the default tty is  system dependent.  The
     defaults for baud rate and parity is 9600 and none.  You may
     override these with your personal preferences.

     You will be asked for the directory to install ECU and friends.
     library.  The default is /usr/local/bin.  If the directory
     does not exist, the install procedure will attempt to make it.

     You will be asked for the directory to use for a private ecu
     library.  The default is /usr/local/lib/ecu.  If the directory
     does not exist, the install procedure will attempt to make it.

     The config program will thank you (;->) and then build Makefiles
     from the Make.src files in each appropriate subdirectory.

     If you are porting to a new system, you will want
     to examine and modify the Makefiles before proceeding.

5.   The configure script suggests you "make depend".  This is
     unnecessary if you are building ECU for the first time.  Also,
     most patches will require you to rerun Configure.  Each time you
     reconfigure the software, it is automatically completely remade
     when you next run make.  Only if you anticipate making changes to
     the software is "make depend" necessary to ensure the code is
     properly made.

6.   Type 'make'.  Wait and watch a while.  This is a good time to
     be reading over doc/ecu.man and various READMEs.
     There are a great number of new features.  There are
     few incompatibilities ("I hate 'em").  The file HISTORY
     has some note on every change made since 3.16.  Unfortunately,
     HISTORY also contains technical/historical information of no 
     interest.

7.   Su to root, if not already there, and type 'make install'.

8.   The default models/funckeymap is copied to the ECU library
     as part of installing the program.  You will probably need
     to study and modify this file if you plan to use a console
     (user tty) other than the native console of your system.

9.   You must, as root, chmod +rwx your uucp locks directory.  In
     addition, if you are on a machine which ecuungetty does not
     support, you must, as root, chmod +rw all tty lines used by ecu.
     As of this writing, SCO operating systems are the only platform
     which ecuungetty supports.  The 'make install' does not do the
     chmods, because *you* should make the informed choice to do it.

10.  The gendial subdirectory contains some rigorous, yet
     experimental, SCO dialer programs for use with ecu, cu and uucico.
     They are currently undocumented and "as-is."  I have used each
     of them successfully at one time or another, but some have been
     modified since they were last proven to work.

     I use the T2500, Microcom 9624 and USR 2400 entry all the time.

     Make sure you like the modem options before using one of these
     dialers.  In particular, I enable remote access to Telebits.

11.  Make neat removes many temporary files that tend
     to accumulate over time. No make targets are removed.
     Make clean runs make neat and also removes all .o files.
     Make clobber runs make clean and also removes executables.

--------------------------------------------------------------------
Notes:

1.  KERMIT:

C-Kermit 5 (as of version 5A(179)) directly supports ECU's needs.
C-Kermit 5 is in beta testing as of this writing and appears to
be in excellent shape.  You will need a ~/.kermrc to set up the
desired characteristics.  I use:

set block 3
set win 3
set send packet-l 2048
set receive packet-l 2048
set file name literal
set file type bin
show

2.  SELECT(S) and CFLAGS "WORKING_SELECT"

ECU uses select() where possible for two purposes:
1. wait on a tty (comm line) read with timeout -and-
2. timeout (nap replacement).

If you have a working select, use -DWORKING_SELECT.
The Configure procedure does the job for you for systems I know about.

SCO XENIX V/386 Release 2.3.1 (and evidently 2.3.2) have a
broken-dead, yet fixable, BSD-style select() feature.  Also,
select() is missing from libc.a.  While ecu does not *require*
select(S), it is much more efficient to use it.  The x386sel
subdirectory in this release has information (thanks to
csch@netcs, ivar@acc, and ag@elgar) on how to fix the kernel and
to add select() to libc.a.  You'll have to add WORKING_SELECT to
config.local if you do this.

Select(S) is fully functional in SCO UNIX 3.2.0.  I am unsure of ODT
1.0/UNIX 3.2.1.  It is broken in ODT 1.1/UNIX 3.2v2.  It does work
in 3.2v4/ODT 2.0.

I found it in /usr/lib/libinet.a on the ISC system I used to
compile for ISC.  It works fine there.  I automatically put
WORKING_SELECT into the Makefile.

It works fine on the Sun and SVR4, naturally.

3.  SCO MULTISCREEN BUG

There has been a bug in the multiscreen driver for some time
wherein a MEDIA COPY (screen dump) sequence ("ESC [ 2 i") leaves
the "ESC [ 2" part "active".  When a screen dump (Cursor 5)
command is given, I do the screen dump, then send a "l" to the
screen to work around the bug ("ESC 2 [ l" unlocks the keyboard,
essentially a no-op).  If and when it gets fixed, you'll see an
"l" show up on your screen after a screen dump sequence.  To fix
this, comment out the
#define MULTISCREEN_DUMP_BUG
at the top of ecuscrdump.c.

The bug remains in place for every SCO product from XENIX 2.0.6
through UNIX 3.2v4.  It is a minor nuisance and there are a great
many other things they have fixed/improved in these years that
were much more important.

Note that from multiscreens, screen dump produces a dump of the
actual screen contents, including ecu-generated output.  When
using a non-multiscreen terminal, screen dump dumps only the
shared memory virtual screen as received from the host.

If, at a multiscreen, you wish a screen dump free of ecu output
"pollution," use Shift-Tab (BkTab) to redraw the screen, then
perform the screen dump.  If you are not on a multiscreen, then the
screen dump comes from the (sometimes inexact) screen memory
representation and this step is not necessary.

4. GCC

In case you didn't know, GCC is a great C compiler.  It generates
excellent code and gives excellent diagnostics and warnings.
There are more options available than for a Coup de Ville, so you
have to be careful if you get too fancy.  I should know -- I
think I may have done it.  With Configure and config.c, I have
tried to choose the best option set for ECU and it's utilities.
If you want to play around, you can place GCC_EXTRA_CFLAGS
definitions in a config.local file and experiment away.

I tried -pedantic and -ansi under SCO, but there are just too many
complaints about the development system header files:

  1. #ident not allowed in ANSI C (boo hiss on ANSI <again>)
  2. unterminated character constant in curses.h (an apostrophe
     in a -comment- threw gcc for a loop)
  3. bit fields not unsigned in machdep.h
  4. blah etc. etc.

I VERY reluctantly hacked my development system's header files so
I could exploit the more critical error checking, but I do not
recommend you do it for purposes of making ECU.  Hopefully since
I have done it and fixed what gcc reported, you don't have to.

On the Sun, you cannot use -ansi because of the whole way ioctl
2nd parameter defines are built (I refuse to demand you run gcc's
fixincludes to use my software).  Compilation proceeds with no
error, but few if any of your ioctls will work.  Also, with
-pedantic, you get one hundred gazillion complaints about text
after #else and #endif.  I hacked my compiler to omit that one
pedantic complaint and made a test run with -ansi and -pedantic.
As of version 3.15, I get no other warnings outside of some
funkiness in va_args.  With that exercise complete, I bid -ansi
and -pedantic adieu for a while with a good feeling about the
future should the ANSI KGB actually seize real power in Cyberdom.

Gcc's idea of prototype validity is just too much for me.  With
MSC ANSI, prototype arguments are tested at *reference* time not
*definition* time.  Thus with MSC it is convenient to define a
file with all the prototypes in it and include it everywhere.  To
do that with gcc, you'd have to include *every* header file you
ever use just to make sure structs and types referred to are
defined.

Other than all this, the code fares pretty well with -ansi
-pedantic I guess I am just not prepared for all the various
flavors of "ANSI" yet ...  and they grow more numerous ...  and
the throathold tightens on venerable code.

With the warnings I have enabled, you may get warnings about
variables possibly clobbered by longjmp.  Worry not.  You may get
warnings about /* in comments, but they will be from system
header files, not my code :-).

I have used gcc 1.40, 2.1 and 2.2.2 to compile ecu on SunOS and
SCO UNIX. 

5.  XTERMS

If you are using an xterm to run ecu,

1. the maximum geometry is 80x43
2. 4014 emulation is untested
3. you should use the following resources:

XTerm*titeInhibit:     true # enable screen clear functions normally
XTerm*curses:          true # curses bug fix

If titeInhibit fails to work (some versions which use terminfo as
their basis do fail), then remove the ti and te entries from
/etc/termcap.

The file models/funckeymap has keyboard definitions for a number
of xterm implementations.  Use kbdtest3 to determine what key
sequences are generated by each function key.  If a key produces
no output or ambiguous output (Home and End both produce the same
sequence), use xev to determine the keysym associated with the
keys in question.  Use xmodmap to map the keys to unique
sequences.  For instance, on the SunOS MIT server, IPX key
presses of Home and End produce:

Home:
KeyPress event, serial 13, synthetic NO, window 0xd00001,
    root 0x8006d, subw 0x0, time 2225786294, (124,70), root:(385,331),
    state 0x0, keycode 75 (keysym 0xffd8, F27), same_screen YES,
                                          ^^^
                                           |
                                           `--- name to use with xmodmap
    XLookupString gives 0 characters:  ""

End:
KeyPress event, serial 15, synthetic NO, window 0xd00001,
    root 0x8006d, subw 0x0, time 2225787104, (124,70), root:(385,331),
    state 0x0, keycode 119 (keysym 0xffde, R13), same_screen YES,
                                           ^^^
                                            |
                                            `-- name to use with xmodmap
    XLookupString gives 0 characters:  ""

Then, choose unique strings to map the keys to.  I generally use
the SCO function key sequences (described in the very first entry
in the distribution model/funckeymap).  Construct XTerm translations
for the chosen sequences.  An example for Home (F27) and End (R13)
is shown below.

XTerm*VT100*Translations: #override\
     <Key>F27:        string(0x1b) string("[H") \n \
     <Key>R13:        string(0x1b) string("[F") \n \
     Shift<Key>Tab:   string(0x1b) string("[Z")

Included in the above is a mapping for "backwards Tab," Shift Tab.
Most servers map Shift Tab to generate the same as unshifted Tab
(or not mapped at all).

Run kbdtest3 and see if all keys now produce a unique sequence.
If not, repeat the above process until you have each key producing
a unique sequence.

Sometimes, you just won't be able to get a particular key to work.
For instance, one X server I used refused to generate an event for
Shift Keypad 5 (Shift<Key>KP_5).  In these cases, you will have to
choose another key, perhaps a higher numbered function key.  Likewise,
if you are using a keyboard unaffected by the True Blue Path,
you may not have a key marked "Home" or "End" (I pity you :-> heh):
choose a replacement you are unlikely to need otherwise.

6. SCO UNIX MEMMOVE() AND GCC

Use of memmove has been eliminated.  See memmove/README for some
history.

7. FAS/i

For the brave, an instrumented version of FAS 2.08 is included
with this release for those who need driver instrumentation at
the cost of performance and portability.  It is not supported (Do
Not Contact Uwe Doering).  I am not at all interested in starting
a new tty faction.  Uwe has done a brilliant job of striking a
balance between compatibility and performance.  I only name this
thing FAS/i to show the derivation from FAS while marking it as
different.

8. EXCEL LOGFILE INTERFACE

The excel logfile utility posted to comp.sources.misc for ECU 3.0
remains compatible with this release of ECU.

9. KBDTEST3

This program is included to help you inspect your keyboard for
making funckeymap entries or for preparing you to ask for help
from me in getting your keyboard functional.

  cc -o kbdtest3 kbdtest.c
  run it, following the instructions

Once you have installed a new funckeymap, the ECU interactive
command "kbdtest" may assist in verifying it works.

I would appreciate your mailing me the output file (kbdtest3.out)
from each keyboard you try out regardless of what you do otherwise
(if your keyboard is not a SCO multiscreen or ISC virtual console).
This will assist me in making funckeymap entries for futures
releases.

-------------------------------------------------------------------------
This program, it sources, objects and utilities are placed in the
public domain.

Warren H. Tucker     wht@n4hgf.Mt-Park.GA.US    {gatech,emory}!n4hgf!wht
TuckerWare           (404)587-5766
150 West Lake Drive
Roswell, GA 30075
