Relay-Version: version B 2.10 5/3/83; site utzoo.UUCP Path: utzoo!mnetor!uunet!seismo!rutgers!ames!ucbcad!ucbvax!STONY-BROOK.SCRC.SYMBOLICS.COM!jrd From: jrd@STONY-BROOK.SCRC.SYMBOLICS.COM (John R. Dunning) Newsgroups: comp.sys.atari.8bit Subject: Kermit-65 Posting. Part 2 of 4. Message-ID: <870806103831.3.JRD@GRACKLE.SCRC.Symbolics.COM> Date: Thu, 6-Aug-87 10:38:00 EDT Article-I.D.: GRACKLE.870806103831.3.JRD Posted: Thu Aug 6 10:38:00 1987 Date-Received: Sat, 8-Aug-87 10:49:36 EDT Sender: daemon@ucbvax.BERKELEY.EDU Distribution: world Organization: The ARPA Internet Lines: 839 Here's the DOC file... ---------------------------------------------------------------- Kermit-65 Manual and bug list Page 1 Kermit-65 for Atari 800s By John Dunning. Bug reports to me (JRD@Symbolics.COM) via Arpanet, or (617) 577-7569 (office). If anyone really wants my home number, ask. Kermit-65 is a port of the kermit-65 available for Commodore frobs. It runs on 48K Atari 800 family machines. Current version (first release) is 3.1. Capabilities: File transfer, text and binary: Without going into excruciating detail here, Kermit-65 is a fairly complete implementation of a user side, using the KERMIT protocol. It's been tested against Kermit-11 under RSX, and C-Kermit under VMS and Un*x, and seems to work fine. For a description of what the KERMIT file protocol is all about, and something about how the it works, see the 'Kermit protocol' section at the end of this do- cument. Terminal emulation: Glass tty, Vt52, or Vt100. Supports 3 flavors of screen configuration; Atari standard screen, 80-column pannable (40-column visible) like VTERM, and 80-column graphics, like V10SQR. Terminal emulation modes may be used in any combination with screen configurations, though some combinations won't work real well; for instance trying to do full-screen Vt100-style ed- itting when using the Atari screen is a good way to lose. Local file management: Kermit-65 includes Directory, Erase, and Rename commands, allowing the user to do most kinds of maintainance operations without leav- ing the program. It also allows you set set the default drive to any value 1 thru 8, so you're not stuck using a single drive for everything. Typing at Kermit-65: The command processor accepts command lines, consisting of a key- word, optionally some more keywords, and optional values. Things in command lines are delimited by spaces, and terminated by . At any time, you may type '?' to get a list of valid completions for the word you're typing. You need not type keywords completely; however much uniquely identifies the word you want is enough. At any time, will attempt to complete what you've Kermit-65 Manual and bug list Page 2 typed so far. Note that if you've typed a word, but haven't hit a or yet, so that the cursor's at the end of the word, '?' will tell you that there's only the one possibility. Hit a space, then '?', for a list of possibilities for the next word. Some commands are 'defaults' in the sense that if you type some- thing non-unique, and hit escape, and one of the possibilities is a 'default', it will win over the other possibilities. One exam- ple of this is 'Send'. Example: The following illustrates a typical interaction between you, the user, and Kermit-65. The stuff that Kermit types (prompts, echos of partial commands, and help) is on the left, stuff typed by the user is in the middle, and commentary is on the right. Kermit types: You type: Comments: "Kermit-65>" Kermit prompts. "s?" User starts typing a command starting with "s", then hits "?" for help. "Keyword, one of the following: Kermit prints possible set show for "s"... send Kermit-65>s" and reprompts, with the partial command. "et?" User finishes the "set" command, and asks for help again. "Keyword, one of the following: Kermit prints the (one) set possible completion. Kermit-65>set" " ?" User hits a space, then asks for help again. "Keyword, one of the following:" Kermit prints possible (various subcommands of 'set' here) completions for words that can follow "set" Kermit-65 Manual and bug list Page 3 Kermit-65 commands: Bye Tells the kermit on the other side to log out. Finish Tells the kermit on the other side to exit server mode, but stay logged in. Connect Puts Kermit-65 in terminal mode, using whatever param- eters are currently set for Terminal and Screen confi- guration. See 'Set Terminal' and 'Set screen' for more details. Quit Exit from Kermit-65 back to Atari DOS. Exit Same as Quit. Get Ask the kermit on the other side to send the named file, using whatever file and protocol parameters are currently in effect. See 'Set' for more details. Note that may be wildcarded; assuming the serving kermit allows that. In that case the serving kermit may send several files; Kermit-65 will try to receive all of them. Send Send the named file to the kermit on the other side. Receive Attempt to receive into the named file. Assumes the other kermit is already trying to send it. If no file name is given, Kermit-65 will attempt to get the name from the file-header information coming from the other side. This is the command to use after telling the other kermit "Send ". Kermit-65 Manual and bug list Page 4 Set Baud (50..9600) Sets baud rate on the comm port to the supplied value. Parity Even, Odd, Mark, Space, None Sets specified parity for the comm port. See the Atari 850 man for more details on the behaviour of the various parity options. Word-size Seven, Eight Set frame size used for comm port. The default is eight-bit. The preferred value for this depends on what the parameters of the serial line are set to on the other side. In my experience, older systems will tend to use seven-bit configurations, more modern ones will tend to use eight-bits. If you're not sure, it usually works to use eight-bit. Default-disk <1..8> Sets the default disk for all file operations. Legal values are 1 to 8, inclusive. Rs232-registers <16-bit hex number> Directly sets the values used in the XIO 38 and XIO 36 calls when setting up the comm port. This allows set- tings to be used that aren't covered by the supplied keywords in Baud, Parity, and Word-size. Debugging Off, Terse, Verbose Turns on/off various debug msgs strewn around in the code. Eight-bit-quoting On, Off Turns on/off eight-bit mode in the kermit protocol. The default is off. This may be an artifact, as bi- nary transfers seem to work fine with it turned off. Perhaps this is part of the protocol that isn't usu- ally implemented? Kermit-65 Manual and bug list Page 5 File-byte-size Seven, Eight Determines whether data to/from file is masked. (currently ignored) File-warning On, Off When this mode is on, Kermit-65 will refuse to overwrite files when receiving. When it attempts to receive a file that's already present, it will alter the filename of the incoming file so as not to overwrite the old version. The algorithm for altering the filename is to replace the extension field of the name with a 2 digit hex number, and retry. If the file still exists, the number is incremented. This repeats until a free name is found, or the extension reaches "FF", at which time the receive is aborted. (I think it's never possible to get that far anyway, as you can't put 256 files on one of these disks) File-type Atascii This is a standard atari text file, and is the default mode. End of line is signalled by the ATEOL character ($9B). When sending, other ATASCII characters are translated to their ASCII equivalents, ie ATTAB ($7F) -> Tab ($09), ATRUB ($7E) -> Rubout ($7F). The file header info generated indicates that a text file is being sent. Receiving one does the opposite transfor- mation. Ascii Files are sent/received as ordinary ascii-text. Line terminators are assumed to be CR ($0D) followed by LF ($0A), and are handled in the usual kermit fashion. No translation of data happens. This mode isn't the right thing for regular old text files, but is useful for sending around files that are output in plain as- cii from various utilities. For example, I have a word processor program which produces formatted output files in ascii, intended to be dumped directly to a printer. This mode gets them over to my pdp-11's print spooler. Binary Data is sent in kermit binary form, no line termina- tors etc. Kermit-65 Manual and bug list Page 6 Script Speedscript file. This allegedly translates Speedscript files to ascii as they are transmitted/re- ceived. It hasn't been tested, nor can I think of any way to do so, unless someone has an implementation of Speedscript for Ataris. Anyone got any info about that? Flow-control On, Off Turns ^S^Q flow control on/off for the incoming line. See 'Com port handling', below, for more details. Ibm-mode On, Off Turns on/off 'IBM mode'. This is apparently a stan- dard thing in kermit implementations, made necessary by the wierditudes designed into the blue equipment. This code has been left as is, so it's got some chance of working, but has not been tested. Local-echo On, Off Controls echo mode in terminal emulator. Default is off. Send End-of-line, Padding, Timeout, Pad-char, Quote-char, Eight-bit-quote, Packet-length Sets one of the listed parameters for the transmitting side of the kermit protocol. All input values are in hex. This command is primarily used when talking to a kermit that can't or won't use the standard set of protocol characters for beginning-of-frame, end-of-frame, etc. As such, it's not generally use- ful, at least I've never seen a kermit that required it. There are things that might come in handy, though. For instance, if you've got an exceptionally dirty phone connection, you might want to set the frame size down from the default of 94. ($5E), you'd say "Set Send Frame-size 30". (That's 48 decimal). Receive All parameters settable same as 'Send' Kermit-65 Manual and bug list Page 7 Screen-driver Atari The standard 24x40 Atari screen driver. This mode does its output to the internal E: device. This isn't very useful for complicated things, but is sup- plied in case kermit's running someplace where there's not enough memory to do anything better. (Besides, I had to have all the code for it lying aound for other reasons, so why not?) 40-column A 24x80 screen, using the character CTIA mode. Since that mode only allows 40 visible columns, the screen is pannable left to right, allowing any 40-column chunk to be displayed. The terminal code will attempt to keep the cursor visible by panning around while output is happening. You can also pan manually using the Start and Select keys. In this mode, reverse- vi- deo output works, but none of the other highlighting types. 80-column A 24x80 screen, using the hi-res (320 bits/raster) graphics CTIA mode. In this mode, both reverse video and underlining are supported. This is the default setting for screen mode. Terminal-emulation Vt100, Vt52, None Sets the terminal emulation mode to the specified va- lue. The default is Vt100. Show any of the same keywords as 'Set', or 'All' Display the value(s) of the specified thing(s). 'All' displays the values of everything in sight. Status Dump various goodies about the last (accumulated?) file transfer; characters in, out, naks, timeouts etc. Directory [] Display a directory list from the default drive. is optional, if omitted, it defaults to "*.*". Kermit-65 Manual and bug list Page 8 Rename Does a rename operation on files on the default drive. Either filespec may be wildcarded, in which case the rename operation happens according to the rules described in the ATARI OS FMS documentation. Erase Erases files on the default drive. Filespec may be wild- carded, in which case the erase operation happens according to the rules described in the ATARI OS FMS documentation. Save Dump Kermit-65 parameters such as screen settings, send/re- ceive parameters, etc to an init file "KERMIT.INI" on the de- fault disk. Restore Read parameters from "KERMIT.INI" back into the running Kermit-65. Help Gives a summary of the above command list. Other interesting things about terminal modes: Depending on what terminal you're using, there are several things which may be of interest. In 40 or 80 column modes, there's a status line under the 24 data lines. It displays what special keys are active, and the status of the comm port. In 40 column mode, Start pans the screen right, and Select pans left. In both 40 and 80 col modes, Option is used to get the kermit's attention. In Atari mode, c-Y is used instead. Once you have kermit's attention, it wants a character; one of: C Break the connection B Send a break (busted) S Display status Function keys: Kermit-65 can generate function key sequences ala VT100. The cur- rent function key bindings are as follows: (c-sh- means control-shift...) c-sh-0..c-sh-9 keypad 0 thru 9 c-sh-. keypad dot c-sh-backspace keypad minus c-sh-, keypad comma c-sh-return Enter Kermit-65 Manual and bug list Page 9 c-sh-q..c-sh-r PF1..PF4 c-sh-- Up arrow c-sh-= Down arrow c-sh-< Left arrow c-sh-> Right arrow Other key bindings for things not on the Atari keyboard: sh-< { (left brace) sh-> { (right brace) sh-backspace ~ (tilde) c-sh-backspace, or c-7 ` (backquote) These key bindings aren't quite what I had in mind, but the OS rom won't let me get at all the control-shift keypresses, so they'll have to do for now. I encourage any feedback about how these feel. I've been using them for a while now, and they don't seem as bad as I expected. In particular, they work passably well when using EDT (I'm typing this document with it), which I think is an indication that they're useable, as it's a real keypad hog. Com port handling: In it's current configuration, Kermit-65 expects to talk thru an Atari 850. In principal, that ought not to be a restriction, but I (JRD) only have an 850 to test with, and don't know what re- quirements there are for other devices. I've tried to be scrupu- lous about sticking to the documented interfaces to things, however, so I'd expect any driver that adheres to the spec to work. The port's opened and closed a lot; you'll hear it, as I've left the 'noisy bus' option turned on. It uses page 6 ($600) as an IO buffer. Since that's only 256 bytes, there's the possibility of overruns at high baud rates. When flow-control's on, Kermit will attempt to shut off the other side when it sees more than 50 bytes pending; it will turn it back on when there's less than 10. Other ramblings: Version 3.1 loads at $2D20, and uses up thru about $B000. That means it'll only run on 48K machines. It appears to run fine on XL and XE equipment, but most of my testing has been on an 800, so there may be some problems. BTW, that load address was chosen be- cause the latest version of DOS XL for Indus GT's uses up thru $2D14 when it's configured for two drives, and the 850 driver is loaded. Older versions of DOS XL take up less memory, as does DOS. I don't know what the requirements are for things like Kermit-65 Manual and bug list Page 10 Spartados. If anyone comes up with a conflict, let me know, and I'll assemble you a version that's org'ed somewhere else. On XLs and XEs, kermit-65 will require that the machine be booted with BASIC disabled, as it's not yet bright enough to detect that that's where it is and map out the cart. (if anyone knows how to do that, and feels like saving me some work...) Kermit-65 is available in 'bare' form, or with an autoloader for the 850 driver prepended to it. The bare version requires that you load whatever rs232 driver you're going to use first, then run kermit. The au- toloader equipped version does that for you. Kermit-65 Manual and bug list Page 11 Bugs and misfeatures: There's no way to set the comm port to other than R1:. Does any- one care? The help processor doesn't deal properly with upper-case, and thinks there are no completions. Vt100 mode is missing still missing insert/delete character. Blinking fields, bright fields, double-high, double-wide, and 132-col mode are not supported. (Reverse vid and underline are) There's currently no way to set the screen colors. It's possible to confuse yourself by hitting c-1 in terminal mode, as my screen drivers ignore it, but Atari's doesn't. You're fine until you break the connection, then everything appears to wedge up. Flow control for the incoming side of the connection isn't imple- mented. This can cause problems when trying to send at high baud rates to a host that's got a stupid serial driver, or a small ty- peahead buffer. The part of the command parser that deals with pathnames is com- pletely bankrupt (that's what I get for using old code), and doesn't work properly unless it's told that a null pathname is le- gal. The result of all this is that when entering pathnames and asking for help before entering any data, it will tell you "input file spec or confirm with ". Pay no attention to the man be- hind the curtain; you really do have to put a pathname in there for anything to happen. Kermit-65 Manual and bug list Page 12 Bugs fixed for v 3.1 Save and Restore now actually do something, instead of being ef- fectively no-ops. Rename and Erase commands are now implemented. This means that virtually all file operations one cares about (while up/download- ing) can be done without leaving Kermit. File-warning mode has been fixed so that it really does something useful, instead of just bitching about the file conflict. The pathname parsing substrate has been installed, so that de- faulting and merging can be done in a reasonable fashion, instead of by ad hoc kludgery. The screen hacking code has been cleaned up a good bit, so as not to be continually clearing the screen when doing transfers. Logging code has been added to tell the user what files are being sent and received. Status and help commands in terminal mode are now working. The directory command now takes an optional filespec parameter. Kermit-65 Manual and bug list Page 13 The Kermit Protocol The following a brief description of the Kermit file protocol, ex- cerpted from one of the many documents kicking around. If you al- ready know what it is, or don't care, skip this section. The Kermit protocol allows many (if not most) types of computer systems to effect, at minimum, error free file transfer with other systems and microcomputers over asynchronous lines. Introduction With the widespread use of personal computers the need for file exchange between systems has become of foremost concern among users and managers alike. There are many commercial products available which meet this need, some of which may offer more ad- vanced functions such as transparent record oriented file access. Networks that do this, such as DECnet, can be expensive, and if your computer or microcomputer is not on the network your needs won't be met. Transfer of files with removable disks can work, but generally only when the computers are of the same type, it's not very useful when the systems are removed in location. Rarely will a larger mini or supermini be able to read a microcomputer's disk. A more realistic approach, from both cost and convenience, is to find a way to use ordinary telecommunications and/or in-house PBX systems to connect computers and microcomputers together. If a local connection using a PBX or front end switch is not available, there is always dialup access with standard 103/212 modems. Data can be transferred with very simple methods, such as TYPING a file on one system and capturing it on the other system, but this gives no protection from noise and overrun of data. It is not very user friendly either. What is really needed is a protocol to accom- plish file transfer reliably and efficiently. The first obvious use of any program or protocol designed to ac- complish file transfer is to be able to provide the ability to support file uploads and downloads from minis and superminis such as the VAX and PDP-11 to remote personal computers, such as the Atari 800. It should also be widely available for many different micros and mainframes. File transfer from micro to micro, as well as from a larger central host, should be possible. The command interface should be easy to learn, and require no intervention from a central site operator or other user. The many implementa- tions of Kermit follow these lines, and all versions allow some form of transfer in either direction. More advanced versions, Kermit-65 Manual and bug list Page 14 such as those found on the PDP-11, DEC10/20 and VAX, offer what is known as server operation, which allow the remote (connected) Ker- mit system to completely control the file exchanges from their system. Since as of this writing (October 9, 1985) there are available over 160 versions of Kermit available for numerous mi- cro, mini and mainframe configurations, Kermit addresses this need quite well. While the primary use of Kermit will likely be to support file transfer from microcomputer to mini/supermini and mainframe con- nections, there are many uses for Kermit for connections from mini to mini and so on. The Kermit protocol The Kermit protocol is designed to operate over normal asynchro- nous terminal lines. All data and commands are transferred with a packet oriented protocol, basically consisting of a start of packet character (normally SOH), followed by length, control, data and checksum fields. Communication is half duplex, in that for every packet sent, the sender must wait for either an acknowledge- ment packet (ACK) or a negative acknowledgement packet (NAK). Transmission is in ascii, with no requirements for the transmis- sion of eight bit characters or control characters other than control-A for marking the start of a packet. All 'control' char- acters imbedded in the data are prefixed to convert them to print- able characters, the same applying to eight bit characters if required by the characteristics of the line. Since there are many different implementations of Kermit, the protocol provides a me- chanism by which the capabilities of two connected Kermits can be negotiated to allow for differences in the level of protocol sup- port. Examples of protocol features that not all Kermits under- stand include data compression and transfer of file attributes. The packet format is +------+-----+-----+------+---------------+-------+ | MARK | LEN | SEQ | TYPE | DATA... | CHECK | +------+-----+-----+------+---------------+-------+ where all fields consist of ASCII characters, and the char func- tion converts a number in the range 0-94 (10) to a printable ASCII character by adding 32 (10). The MARK, LEN, SEQ and TYPE fields are one byte, the DATA field is variable in size, and the CHECK field is one to three bytes in size. The MARK (normally control A) signifies the start of a packet. The length field tells how long the rest of the packet is. The SEQ field is used to insure synchronization used to detect lost or Kermit-65 Manual and bug list Page 15 duplicate packets. The SEQ number wraps around every 64 packets due to the need to encode it as a printable ascii character in the range 32 (10) to 126 (10). The TYPE field specifies whether the packet is a DATA or CONTROL packet. The DATA section is used for the actual transfer of data or informative messages from a Kermit server, this field can be up to 90 characters in length. Any character whose low seven bits fall in the range of 0 to 37 (8), ie, char and 177 (8) is less than 40 (8), will have the value 100 (8) exclusive or'ed (xor'ed) with itself and be prefixed by a shift character, '#'. Other shift characters may be use for eight bit characters if the line characteristics require such. Data compression may also occur in the data field, this is done with yet another shift code and byte count sequence. The CHECK field is a checksum, either a one character, two character or three character CRC check; the sender computes it and the receiver must compute it and compare. A checksum mismatch will result in the receiver sending a NAK packet (negative acknowledgment) which di- rects the sender to resend the NAK'ed packet. The packet may be following by a terminator (likely an ascii 13). This terminator is NOT part of the protocol and is sent only to tell the receiver that a 'line' is present. Not all Kermit implementations require this; all Kermits will discard data outside of a packet in any event. Error detection and recovery is by checksum, as noted, and by packet read timeouts. If the packet should be corrupted the checksum will be incorrect, the receiver will NAK the packet. If an expected packet never arrives within the timeout period, or if the received packet is not the expected one (as determined by the SEQ field) the packet will also be NAK'ed. There are limits as to how many times an expected packet will be NAK'ed without aborting the current operation. Packet types D Data Y Acknowledgement (ACK), test may be in DATA field N Negative Acknowledgement (NAK) S Send initiate (Send-Init) R Receive Initiate B Break (EOT, end of transmission) F File name header Z End of file (EOF, end of current file) E Error packet, text may be present in DATA field G Generic SERVER command. The first character in the data field will be a command to a server, arguments may follow that character. I Login, user and password follow in data field C CWD, change working or default directory. Kermit-65 Manual and bug list Page 16 L Bye, Logout server F Finish, Exit server, but do not log out E Erase, delete files on server system D Directory query U Disk space usage query T Type a file onto local kermit R Rename file(s) on server system K Copy file(s) on server system W Who's logged in, as in sho sys, sy/s, dev tt M Send a terminal message to a user H Help, the server responds with commands it can do Q Server status query P Program, run a program J Journal V Variable, alter a Kermit setting C Execute host command. The host command follows in the data field. Note that some of the generic server commands, as well as the C packet, may not be feasible for a given environment. For in- stance, the REMOTE LOGIN command, which sends the generic I com- mand to the server, can only be done under systems that allow you to dial up and start a Kermit without logging in; the generic U command (disk space) is meaningless under some systems (like RSX) unless one wants the free space on the entire volume. No Kermit server will abort on receiving a packet it can't execute, it will simply send an error packet with an informative message saying it can't process the requested function. An example of a Kermit-65 kermit telling a PRO Kermit-11 server to expect a file follows. The Kermit-65 command was "Send foo.txt" (0)Atari sends: * S~# @-#Y( (0)Pro sends: 0 Y~* @-#Y1~* ~T (1)Atari sends: *!FFOO.TXTE (1)Pro sends: #!Y? (2)Atari sends: S"DThis is a test file#M#J containing two lines.#M#JU (2)Pro sends: #"Y@ (3)Atari sends: ##ZB (3)Pro sends: ##YA (4)Atari sends: #$B+ (4)Pro sends: #$YB In packet zero, the Kermits exchanged information regarding their capabilities. The Atari sent an 'S' packet with the data for its Kermit-65 Manual and bug list Page 17 maximum packet length, default time out, number of pad characters to follow a packet (none, hence the space), use a null for pad- ding, end of line terminator (a CR + 32), the prefix character for control characters, and a 'YES' to say the it can prefix eight bit characters with the default. It doesn't send any of the extension fields, like indicators for multi-byte CRCs, file header info etc. In packet 1, the Atari sends the filename the Pro should use for the file it creates. The Pro then sends the acknowledgement. In packet three, the Atari sends the first (and only for this file) packet of data. Note that the sequence #M#J is a carriage re- turn/line feed sequence with 100 (8) xored into each character. The '#' character informs the other Kermit that it must xor the next character with 100 (8). In packet three the Atari sends an EOF packet, the Pro acks it. In packet four, the Atari sends a break packet which tell the Pro that no more files (of a possibly wildcard group) are coming and the Pro Kermit acks the break packet. The Pro kermit then enters the server idle state. More specific information regarding Kermit packets and state transi- tions can be found in the references listed at the end of the article. Future directions With the advent of packet switched networks and satellite communi- cations the Kermit protocol will likely be extended to increase efficiency over such links. The main problem is the half duplex nature of Kermit, the packet acknowledgements can take up to sev- eral seconds in transit thus drastically reducing the throughput. There are several possibilities under discussion and a standard should be appearing shortly. Summary With the knowledge that there are Kermit implementations for most personal computers in use it becomes apparent that the Kermit standard is well worth looking in to. (End of protocol description) For more documentation on what Kermit protocol is all about, see the extensive doc available from the Kermit folks at CU20B.ARPA. Kermit-65 Manual and bug list Page 18 References: Kermit: A File-transfer Protocol for Universities Frank da Cruz and Bill Catchings BYTE Magazine, June/July 1984 The Kermit Protocol Manual, version 5 Frank da Cruz April 1984 Columbia University Center for Computing Activities Information on obtaining Kermit: KERMIT Distribution Columbia University Center for Computing Activities 7th Floor, Watson Laboratory 612 West 115th Street New York, N.Y. 10025