home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / ibm370 / ik0con.txt < prev    next >
Text File  |  2020-01-01  |  7KB  |  129 lines
  1. Notes on implementing terminal controller types in portable IBM/370
  2. Kermit.     -- Revised 1992 January 23
  3.  
  4. Can support, in fact, be added?  It all hinges on whether the controller
  5. has some kind of "transparent" communication mode which can
  6.  
  7. a) transmit at least one control character (preferably SOH) and all
  8.    95 printable ASCII characters to the terminal,
  9. b) receive at least one control character and all 95 printable ASCII
  10.    characters (or enable an application program to decode all 96 from
  11.    what it *does* receive),
  12. c) refrain from inserting extra characters into packets whether sent or
  13.    received,
  14. d) allow packets at least 25 bytes long in both directions, and
  15. e) refrain from echoing control characters it receives from the terminal
  16.    (and preferably not echo anything).
  17.  
  18. The implementation should be easy if and only if the controller can do
  19. all those things on command from Kermit.  It may still be possible to
  20. satisfy condition (b) with only a "semitransparent" mode where only the
  21. 95 printable ASCII characters can be received (possibly even translated
  22. into EBCDIC), provided that packet synchronization is available by
  23. taking each packet to start at a fixed offset into the input I/O buffer
  24. (the packet character can then be "decoded" into the right position
  25. artificially by the handler).  If you determine conclusively that any
  26. particular device can *not* support Kermit transfers, please relay that
  27. information (with details) to JCHBN@CUVMB.CC.COLUMBIA.EDU.  If you find
  28. that the device *can* support transfers, then the following notes should
  29. assist you in adding the proper code to Kermit-370.
  30.  
  31. 1) Many Kermit subroutines, particularly the system-specific ones, are
  32.    called with a command code in register 0 or 1.  The code selects
  33.    which of several possible operations the routine is to perform.
  34.    Routines that require other arguments besides the command code, i.e.,
  35.    FSPEC, DISKIO, TERMIO, and SCRNIO, find the command code in R0, but
  36.    routines SUPFNC and SETMSG find it in R1.  See the comments at the
  37.    beginning of each routine for a description of the parameters and
  38.    the meanings of the command codes.  Any new terminal I/O handlers
  39.    will be expected to have the same calling sequences as TERMIO and
  40.    SCRNIO.
  41.  
  42. 2) The controller names are generic, i.e., common to all operating
  43.    systems, but the corresponding handlers are system-specific.  Thus,
  44.    it may require some coordination among the various versions of
  45.    Kermit-370 to get a new controller type properly implemented.  If,
  46.    for example, a new handler demanded a change in the shared calling
  47.    sequence, all handlers in all versions would probably need to be
  48.    modified accordingly.
  49.  
  50. 3) A new controller name can be implemented by simply adding it to the
  51.    list of names at SETTRKW.  Handling the new controller type requires
  52.    a bit more work.
  53.  
  54. 4) The currently selected controller name is saved internally by Kermit
  55.    as a one-character code (in TRMTP).  Hence, things are much simpler
  56.    if the names have unique first letters.
  57.  
  58. 5) If there exists a means of detecting a particular type of controller
  59.    from within Kermit-370, the test should be made in routine SETMSG
  60.    (called with code 5) or, if possible, in the generic routine SETCON
  61.    in order to initialize TRMTP properly.  At present, the tests can
  62.    distinguish TTY from SERIES1 (by checking if the terminal has full-
  63.    screen capability), SERIES1 from GRAPHICS or AEA (by issuing a Yale
  64.    ASCII status request and assuming that only SERIES1-type controllers
  65.    will respond), and AEA from GRAPHICS (by issuing a Read Partition
  66.    Query).  In addition, under TSO, Kermit can detect whether a line-
  67.    mode terminal is connected via VTAM and thereby distinguish between
  68.    TTY and VTAMTTY.
  69.  
  70. 6) Routines RIO, SIO, INTINI, and RPAR (all generic) have logic based on
  71.    TRMTP for deciding which system-dependent handler to call at various
  72.    points and for inserting the proper transparent-mode commands, if
  73.    any, into the packet buffer.  The handlers have a shared calling
  74.    sequence.  If a new controller type is similar enough to existing
  75.    ones, it may be able to share an existing handler.  Otherwise, a new
  76.    handler modelled along the lines of TERMIO and SCRNIO should be
  77.    added.
  78.  
  79. 7) Uses of TRMTP:
  80.    a) selecting I/O handlers in SIO, RIO, INTINI, RPAR
  81.    b) controlling system-specific setup in SETMSG
  82.    c) limiting packet size for TTY terminals
  83.    d) controlling generic I/O operations as needed
  84.    e) initialized in SETMSG/SETCON, if possible
  85.  
  86. 8) Support for a new controller type must cover all the usual require-
  87.    ments for the Kermit protocol:  there must be some sequence of
  88.    commands to place the controller in transparent mode, such that
  89.    inbound characters are not echoed and are presented to Kermit-370 "as
  90.    is" (or at worst converted to EBCDIC), and outbound characters are
  91.    similarly presented to the terminal.  Such a command sequence might
  92.    be "once-only", but is more likely required for each outbound packet.
  93.    Routine INTINI, for example, sets up a transparency introducer, which
  94.    may be either invariant (as for GRAPHICS) or context-dependent (as
  95.    for AEA).  Code re-entrancy demands that the latter kind be kept in
  96.    the variable STORAG area.  Any system dependence of the introducer
  97.    (presumably limited to the command codes at the very beginning)
  98.    should be arranged through variable symbols (like &S1CMD) to be
  99.    defined in the system-dependent macro SSYMS.  Things become awkward
  100.    if the length of the introducer (instead of just the content) is
  101.    context-dependent.  The same is true of the length of the non-data
  102.    portion of each in-bound packet, although the Kermit protocol is
  103.    pretty resistant to problems induced by garbage characters prepended
  104.    to packets.
  105.  
  106. 9) Once a transfer is started, the succession of calls to the device
  107.    handlers is entirely regimented.  In the absence of I/O errors, the
  108.    transfer consists entirely of pairs of calls to the appropriate
  109.    handler, first with code 4 (write) and then code 5 (read).  Errors
  110.    can interrupt the sequence with other calls as needed for recovery.
  111.    During a transfer, the flag WRRD has the value 5, indicating that
  112.    every Write operation is followed immediately by a Read.  However,
  113.    depending on the type of transfer, the last packet may be either
  114.    inbound or outbound.  In the latter case, WRRD is set to 0 for the
  115.    last 4/5 pair of calls, indicating that the Read call need not return
  116.    any data.
  117.  
  118. 10) If a new I/O handler must be added, it should be equipped with a
  119.     facility for logging the details of the I/O, as in routine SCRNIO.
  120.     This will prove especially useful in the development stage.  The
  121.     code at label SCRLOG in any current variant of Kermit-370 can serve
  122.     as a pattern.
  123.  
  124. ------------------------------------------------------------------------
  125. With a few exceptions, CONTROLLER will be set automatically when Kermit
  126. is invoked.  See file IK0AAA.HLP for a list of controllers (front end
  127. processors) that allow Kermit file transfers.
  128.  
  129.