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.