CK9KER.BWR          "Beware File" for C-Kermit Version 5A        -*- text -*-

			      OS-9/68000 VERSION

Applies to 6.0.192
Last update: Wed Jul 03 19:48:00 1996

Author: Christian Hemsing, Germany.
        Ulrich Schlueter, Germany.

[Comments in brackets are by James Jones, USA; they reflect his opinions and
judgement and the (minimal, thanks to the fine work of Herren Hemsing and
Schlueter and all who have worked on C-Kermit for OS-9) changes made since
the 5A(188) version, and do not necessarily reflect the opinions of any
organization.]

  Copyright (C) 1985, 1996, Trustees of Columbia University in the City of New
  York.  Permission is granted to any individual or institution to use this
  software as long as it is not sold for profit.  This copyright notice must be
  retained.  This software may not be included in commercial products without
  written permission of Columbia University.

Report problems, suggestions, fixes, etc, to Frank da Cruz:

 Internet: fdc@watsun.cc.columbia.edu  (or)  fdc@columbia.edu
 BITNET/EARN: FDCCU@CUVMA

Columbia University Center for Computing Activities
612 West 115th Street, New York, NY  10025  USA

DOCUMENTATION

C-Kermit 5A is documented in the book "Using C-Kermit" by Frank da Cruz
and Christine M. Gianone, Digital Press, Burlington, MA, USA.  Digital
Press ISBN: 1-55558-108-0; Prentice-Hall ISBN: 0-13-037490-3.  Price: US
$36.95.  In USA, call DECdirect at 1-800-344-4825, refer to order number
EY-J896E-DP.  ["5A" reflects a prior numbering system for C-Kermit versions.
The file CKCKER.UPD documents changes made to C-Kermit since the publication
of the book "Using C-Kermit".]


KNOWN BUGS AND LIMITATIONS

[OS-9 C Kermit will require source changes to compile and run under OS-9000,
to move from OS-9 to OS-9000 system call interfaces and to recast the
assembly language code in ck9asm.a into a more portable form.]

[As I do not have ready access to the old 3.2 OS-9/68000 C compiler or to
gcc for OS-9/68000, I cannot guarantee that C Kermit will compile with those
compilers, though I have made minimal changes to the source, and have made
every effort to not break things for those attempting to compile with either
of those compilers.  The most likely difficulty will be managing the amount
of non-remote data.]

SET FILE DISPLAY FULLSCREEN only works for VT100 and compatible terminals,
emulators, and/or console drivers.  If it doesn't work for you, please use
one of the other FILE DISPLAY styles, such as CRT.

During text-mode file transfer, linefeed characters are converted to
carriage returns.

Unlike UNIX, OS-9/68000 has a built-in method to gain exclusive access to
devices, so no lock files are needed.  The user will be told if the device
is already in use.

1)  Setting the speed of the communications line:

    With OS-9 there are two different ways to set the line speed which
    need a little discussion.

    a) Assumption: you have a properly implemented driver for your teminal
       lines.  This means that with any SS_Open and SS_Opt call to the driver
       will check whether the speed has changed and will re-program the
       hardware accordingly.  In this case everything is fine and kermit will
       only have to do an _ss_opt call and the speed will be changed.  This is
       what tmode does.

    b) Assumption (more likely): your driver does not check the speed change.
       You could try to change the speed with the xmode command, close the
       path currently open on it and reopen it again (xmode only modifies the
       device descriptor in memory; NOT any currently existing path
       descriptors).  But this won't help you much if your line was iniz'ed
       before, because the driver's init routine will NOT be called again and
       since the poorly implemented driver does not check the speed with an
       SS_Open call the actual speed is not changed.  The only way is to have
       the device not iniz'ed.  But this again might cause some problems:
       again, a poorly implemented driver does not wait till output buffer
       (the drivers!, not to be mixed up with the buffer e.g. setbuf(), works
       on) is empty, before the termination routine runs.  So, when the device
       was not iniz'ed and therefore the termination routine is called
       everytime the last existing open path closes, characters might get lost
       (e.g. a list file.name >/t3 on a previously not iniz'ed device often
       will not show all characters on /t3 if the drivers termination routine
       does not wait).  The best solution is to deiniz the device till there
       are no interrupts running any more (with OS-9 V 2.3 and later use irqs)
       then use xmode and iniz the device again.

    How to find out: let kermit change the speed (using _ss_opt) and see
    wether the change worked.  Otherwise use the method mentioned above.  I
    included the xmode version in kermit (which only works on non-iniz'd
    line, but its use is strongly discouraged.  You can include the -dXMODE
    option in the makefile to have this method used by kermit.

    Another problem could arise on a system with an installed memory
    protection unit: if the device descriptor does not have public write
    access, xmode cannot change the device descriptor unless you are
    privileged.  In that case changing the speed with xmode from within kermit
    will not work.  The _ss_opt (tmode) method works also with an installed
    memory protection unit, because it acts only on the path descriptor (not
    on the device descriptor) which is owned by the current user.  The best
    solution is: already have or get or write a decent driver.

2)  Setting raw mode on line: Again a remark: If you change XON/XOFF to 0 with
    _ss_opt, the driver should wait until the output buffer is empty, because
    if there is pending output the driver might receive an XOFF which will
    result in an output halt.  Next time you change the mode with XON set to
    0, and the driver will never start output again, because there is no XON
    character anymore.  This might happen when you type the CONNECT command.
    In this case kermit says something like "Connection thru blabla" and then
    puts the terminal line in raw mode.  But your terminal might have sent an
    XOFF (and shortly later an XON again), but the XON might be lost.  The
    only way to circumvent this (unfortunately OS-9 currently offers no way to
    find out whether the driver's output buffer is empty; there are many
    situations when one would like to know that) is to wait.  If this happens
    to you, edit ck9con.c to wait after the message.

3)  Kermit now does an open with initial file size.  This avoids the
    frustration of attempting to receive a long file only to fail at
    the very end because of fragmentation or lack of disk space.

4)  You can make the module (and its data requirements) a lot smaller by
    adding certain compiler switches to the makefile like -dNODEBUG.
    For the possible switches, read the file ckccfg.doc.

5)  Sending a BREAK on a line is again a matter of the driver.  There is a
    setstat call SS_Break, but again many carelessly implemented driver do
    not support the call.  If there is no support, kermit will try to switch
    to a lower speed for the BREAK, but again this may not work (see above).
    Things would be much easier, if drivers were written more carefully.
    One known device driver takes 5 hours (!) to return from the send-BREAK
    code.

6)  [When compiled for the old 3.2 C compiler or with gcc, C-Kermit is now
    using its own rename function. Compiling with Ultra C will use the ANSI
    library rename() function.]  This enables moving files.  But you have to
    use another syntax: To rename a file "foo" in the directory "oofa" to
    "oofa/fooo" the OS-9 shell syntax is "rename oofa/foo fooo" - but the
    C-Kermit syntax is "rename oofa/foo oofa/fooo".

7)  There is now a version available with network support (Microware ISP
    1.3-1.4). This version needs the carefully implemented driver (aborting
    I/O on signals less than 32). When sending files to an OS-9 Kermit server
    with TCP/IP and large packets the transfer get's stuck because of a buggy
    telnetdc and pkdvr. You have at least to increase the buffer size of the
    pseudo ttys to 2048. This buffer size can be found in the pk device
    descriptor at offset 0x4A (buffer size = (*(char *)0x4A) + 1) * 128).

(End of CK9KER.BWR)
