Notes on implementing terminal controller types in portable IBM/370
Kermit.     -- Revised 1992 January 23
 
Can support, in fact, be added?  It all hinges on whether the controller
has some kind of "transparent" communication mode which can
 
a) transmit at least one control character (preferably SOH) and all
   95 printable ASCII characters to the terminal,
b) receive at least one control character and all 95 printable ASCII
   characters (or enable an application program to decode all 96 from
   what it *does* receive),
c) refrain from inserting extra characters into packets whether sent or
   received,
d) allow packets at least 25 bytes long in both directions, and
e) refrain from echoing control characters it receives from the terminal
   (and preferably not echo anything).
 
The implementation should be easy if and only if the controller can do
all those things on command from Kermit.  It may still be possible to
satisfy condition (b) with only a "semitransparent" mode where only the
95 printable ASCII characters can be received (possibly even translated
into EBCDIC), provided that packet synchronization is available by
taking each packet to start at a fixed offset into the input I/O buffer
(the packet character can then be "decoded" into the right position
artificially by the handler).  If you determine conclusively that any
particular device can *not* support Kermit transfers, please relay that
information (with details) to JCHBN@CUVMB.CC.COLUMBIA.EDU.  If you find
that the device *can* support transfers, then the following notes should
assist you in adding the proper code to Kermit-370.
 
1) Many Kermit subroutines, particularly the system-specific ones, are
   called with a command code in register 0 or 1.  The code selects
   which of several possible operations the routine is to perform.
   Routines that require other arguments besides the command code, i.e.,
   FSPEC, DISKIO, TERMIO, and SCRNIO, find the command code in R0, but
   routines SUPFNC and SETMSG find it in R1.  See the comments at the
   beginning of each routine for a description of the parameters and
   the meanings of the command codes.  Any new terminal I/O handlers
   will be expected to have the same calling sequences as TERMIO and
   SCRNIO.
 
2) The controller names are generic, i.e., common to all operating
   systems, but the corresponding handlers are system-specific.  Thus,
   it may require some coordination among the various versions of
   Kermit-370 to get a new controller type properly implemented.  If,
   for example, a new handler demanded a change in the shared calling
   sequence, all handlers in all versions would probably need to be
   modified accordingly.
 
3) A new controller name can be implemented by simply adding it to the
   list of names at SETTRKW.  Handling the new controller type requires
   a bit more work.
 
4) The currently selected controller name is saved internally by Kermit
   as a one-character code (in TRMTP).  Hence, things are much simpler
   if the names have unique first letters.
 
5) If there exists a means of detecting a particular type of controller
   from within Kermit-370, the test should be made in routine SETMSG
   (called with code 5) or, if possible, in the generic routine SETCON
   in order to initialize TRMTP properly.  At present, the tests can
   distinguish TTY from SERIES1 (by checking if the terminal has full-
   screen capability), SERIES1 from GRAPHICS or AEA (by issuing a Yale
   ASCII status request and assuming that only SERIES1-type controllers
   will respond), and AEA from GRAPHICS (by issuing a Read Partition
   Query).  In addition, under TSO, Kermit can detect whether a line-
   mode terminal is connected via VTAM and thereby distinguish between
   TTY and VTAMTTY.
 
6) Routines RIO, SIO, INTINI, and RPAR (all generic) have logic based on
   TRMTP for deciding which system-dependent handler to call at various
   points and for inserting the proper transparent-mode commands, if
   any, into the packet buffer.  The handlers have a shared calling
   sequence.  If a new controller type is similar enough to existing
   ones, it may be able to share an existing handler.  Otherwise, a new
   handler modelled along the lines of TERMIO and SCRNIO should be
   added.
 
7) Uses of TRMTP:
   a) selecting I/O handlers in SIO, RIO, INTINI, RPAR
   b) controlling system-specific setup in SETMSG
   c) limiting packet size for TTY terminals
   d) controlling generic I/O operations as needed
   e) initialized in SETMSG/SETCON, if possible
 
8) Support for a new controller type must cover all the usual require-
   ments for the Kermit protocol:  there must be some sequence of
   commands to place the controller in transparent mode, such that
   inbound characters are not echoed and are presented to Kermit-370 "as
   is" (or at worst converted to EBCDIC), and outbound characters are
   similarly presented to the terminal.  Such a command sequence might
   be "once-only", but is more likely required for each outbound packet.
   Routine INTINI, for example, sets up a transparency introducer, which
   may be either invariant (as for GRAPHICS) or context-dependent (as
   for AEA).  Code re-entrancy demands that the latter kind be kept in
   the variable STORAG area.  Any system dependence of the introducer
   (presumably limited to the command codes at the very beginning)
   should be arranged through variable symbols (like &S1CMD) to be
   defined in the system-dependent macro SSYMS.  Things become awkward
   if the length of the introducer (instead of just the content) is
   context-dependent.  The same is true of the length of the non-data
   portion of each in-bound packet, although the Kermit protocol is
   pretty resistant to problems induced by garbage characters prepended
   to packets.
 
9) Once a transfer is started, the succession of calls to the device
   handlers is entirely regimented.  In the absence of I/O errors, the
   transfer consists entirely of pairs of calls to the appropriate
   handler, first with code 4 (write) and then code 5 (read).  Errors
   can interrupt the sequence with other calls as needed for recovery.
   During a transfer, the flag WRRD has the value 5, indicating that
   every Write operation is followed immediately by a Read.  However,
   depending on the type of transfer, the last packet may be either
   inbound or outbound.  In the latter case, WRRD is set to 0 for the
   last 4/5 pair of calls, indicating that the Read call need not return
   any data.
 
10) If a new I/O handler must be added, it should be equipped with a
    facility for logging the details of the I/O, as in routine SCRNIO.
    This will prove especially useful in the development stage.  The
    code at label SCRLOG in any current variant of Kermit-370 can serve
    as a pattern.
 
------------------------------------------------------------------------
With a few exceptions, CONTROLLER will be set automatically when Kermit
is invoked.  See file IK0AAA.HLP for a list of controllers (front end
processors) that allow Kermit file transfers.
 
