HOW TO USE KERMIT FOR TRANSFERRING FILES BETWEEN MICROCOMPUTERS Norman Weatherby, Ph.D. Center for Population and Family Health Columbia University July 24, 1984 KERMIT (like the frog, a registered trademark of Henson Associates, Inc., used by permission) is ideal for transferring ASCII and binary files between computers of all sizes. It is a protocol for transferring sequential files between computers of all sizes over ordinary asynchronous telecommunication lines using packets, checksums, and retransmission to promote data integrity. KERMIT is non-proprietary, thoroughly documented, well tested, and in wide use. The protocol and the original implementations were developed at Columbia University and have been shared with many other institutions, some of which have made significant contributions of their own. KERMIT programs have been written for a wide variety of microcomputers, minicomputers, and mainframes. Which ones? At the end of this document is an extensive listing that was downloaded (using KERMIT) from a DEC mainframe at Columbia University. In addition, you will find the address to write for futher documentation, and some information for those who would like to participate in the growth and acceptance of KERMIT as one of the major file-transfer protocols. I wrote this guide so that people who have very little computer experience could use KERMIT to transfer files between CP/M micros or between CP/M and IBM PC-type systems. It simply tells you how to work with KERMIT, without going into its features. This guide was submitted to the KERMIT distributors, and they like it, but they have NOT stamped their approval on it. It is not a substitute for the real documentation. And, as the real documentation states: No warranty of the software nor of the accuracy of the documentation surrounding it is expressed or implied, and neither the authors nor Columbia University acknowledge any liability resulting from program or documentation errors. KERMIT is copyrighted, and it is not "public domain". Simply, it is a free program that is not to be sold as a product. As the distributors state, you are free to redistribute KERMIT on your own terms, and are encouraged to do so, with the following stipulations: KERMIT should not be sold for profit; credit should be given where it is due; and new material should be sent back to Columbia University at the address given in the summary so that they can maintain a definitive and comprehensive set of KERMIT implementations for further distribution. Where do you get KERMIT? As stated below, Columbia University distributes versions of the program only on nine track magnetic tape. You can get the program from friends, bulletin board systems, and various areas on services such as CompuServe. Look around for the latest version for your micro, and be aware that the program is constantly improving. NOW, KERMIT Without going into the details of KERMIT, this guide shows you how to use the program to transfer files between micro- computers that have KERMIT. The sections include 1. Connecting the computers, either directly or through modems 2. Setting the baud rates 3. Loading KERMIT into memory 4. Setting KERMIT's options 5. Communicating between computers 6. Sending and receiving files 7. Checking what was sent 8. Figuring out why (If) KERMIT does not work 9. Summary CONNECTING THE COMPUTERS If you are going to transfer the file over the telephone system through modems, hook up a full duplex modem to each computer's serial communications port (com1: on IBM PC type machines, or on CP/M machines, rdr:/pun: or auxin:/auxout:). You may need to get a cable that switches pins 2 and 3 to a modem if the port is a printer port (lst: or printer). If you are working with acoustically coupled modems, set one modem to answer mode and the other modem to originate mode. If you do not have two modems, and the computers are in the same room, you can a. Directly connect the serial modem ports of the two machines. The cable that is needed is one in which pins 2 and 3 are switched when connecting two modem ports. OR b: Directly connect the serial modem port of one computer to the serial (not parallel) printer port of the other computer. This may cause a problem, since you have to make sure that KERMIT talks to the printer port of the other machine. However, it is the only way to get, for example, the Osborne Executive to KERMIT a file to an IBM PC-type machine. One benefit of using a direct connection between the computers is that you can use high baud rates, such as 4800 baud, to transfer the files. Since you are not using modems or telephones, ignore the parts of this guide that concern use of the modems and dialing of the telephone. SETTING THE BAUD RATE The baud rate controlls the speed of the file transfer. The baud rate can be set from within KERMIT some CP/M machines, such as the Osborne 1 and the Intertec Superbrain, and on MSDOS (PCDOS) computers. One really nice feature of KERMIT is that you do not have to cope with that poorly-documented mode command on the IBM PC-type micros. If you do not know whether KERMIT handles the baud rate, skip forward in these instructions and load KERMIT into memory. At the KERMIT prompt, give the command set baud where means to "hit" the return key. KERMIT will tell you if the baud rate setting command has not been implemented. If you cannot set the baud rate from within KERMIT, such as on H89 systems, then you can get back to your operating system by typing, at the prompt, exit Then use the computer's software to set its baud rate, usually to 300 or 1200 baud when modems are used. The baud rate of a CP/M machine is set through the SETUP or CONFIGUR utilities supplied with the system. LOADING KERMIT INTO MEMORY Loading KERMIT into the memory of an Apple II or Atari computer is more difficult than loading it into CP/M or MSDOS (PCDOS) systems. Thus, readers should refer to other documentation and help files for assistance with these systems. IF YOU HAVE A HARD DISK: Micros with hard disks, such as the IBM PC-XT, often refer to all or part of the hard disk as disk C . If you have a hard disk, copy your KERMIT program and associated utility, help, and documentation files from the KERMIT floppy to the hard disk (if someone else has not copied them over already). Then work off of the hard disk. That is, if you do not see the prompt for the hard disk on your screen, type the command c: Then, to load KERMIT into memory, type the name of your kermit program, which is usually KERMIT. For example, at your operating system's prompt, type kermit Then skip to the section below about setting KERMIT's options. IF YOU HAVE TWO FLOPPY DRIVES: Put the KERMIT diskette in drive A of each computer. Note that on a CP/M machine such as a Kaypro, H89, or Osborne 1, it is wise to have the operating system on the KERMIT disk (through the use of the SYSGEN utility) and to type the command cntl C (without a carriage return) where cntl is the control key and C can be upper or lower case, to make the computer realize that a new disk has been put in drive A. This "warm boot" command is not necessary on micros that use CP/M 3.0, MSDOS, or PCDOS operating systems. Put a formatted disk in drive B of the system which is to receive the file. On the sending system, put the disk with the file that you want to transfer in drive B. Go to drive B, and then get into KERMIT on each machine by typing a: and the name of the program, which is usually KERMIT. For example, type a:kermit Newer versions of KERMIT allow you to change the "logged disk drive," but it is wise to follow the above advice so that you are sure of the disk that you are sending from or receiving to. SETTING KERMIT'S OPTIONS To see the options that are available in your version of KERMIT, type at the prompt the command status Note that the toggle command set ibm , which can be set on or off , is NOT FOR IBM PC MICROS--it is a command for Columbia University's IBM mainframes. SETTING THE PARITY: A computer "byte" is composed of eight bits--where each bit is a zero or one. All (english) printable letters, numbers, punctuation marks, and spaces between words can be represented by seven of the eight bits. The eighth bit is reserved for checking to make sure that the other seven bits are correct. However, some microcomputer software packages (such as WordStar) use the eighth bit for special characters that allow features such as right justification. In any event, if both computers allow the following command, issue it to allow the transmission of all eight bits: set parity none SETTING THE FILE-MODE: Microcomputers store files in two ways: ASCII files--codes such as letters, numbers, punctuation marks, and spaces, or as binary files--codes that are recognizable to a computer but not to you, such as the way programs are stored. If you are transferring an ASCII file, issue the command set file ascii If your are transferring a binary file, use set file binary SETTING THE BAUD RATE: If you can set the baud rate from within KERMIT, make the baud rates of both computers equal by typing at the prompt the command set baud xxxx where xxxx is the baud rate you want. For example, you may type set baud 1200 If these commands do not work, try set baud ? and select the correct baud rate from a menu that is given on the screen. If you get messages that set baud command is not implemented, you will have to get out of KERMIT and set it from your operating system, as discussed above. COMMUNICATING BETWEEN COMPUTERS Then type at the prompt the command connect on each computer. This will put you into the connect mode, which allows one computer operator to send messages to the other operator through the modems or the direct connection. Note that KERMIT replies with an "escape" message that tells you how to get back to the command state of the program. WRITE DOWN THIS MESSAGE, AS YOU WILL NEED IT LATER. In fact, it is a good idea to test the command now. The way you get back to the KERMIT prompt varies by the type of system. In general, you will have to issue the command but add a C (upper or lower case) to it to get back. For example, on many CP/M machines that have the backslash character \ , the "escape" command is control \ , but you type ctrl\c (without typing a return) where ctrl is the control key. After some experimentation, you will see the KERMIT prompt, and then you can type the command connect again. For those who are using modems: From the originate modem, dial the answering modem. If you have an auto-dial modem, you can issue the dial command to it. For example, with a touch tone telephones and a Hayes SmartModem, the only command that is necessary is for the originate modem: ATDTxxxxxxx where xxxxxxx is the telephone number to dial. When the connection is made, each you each will be able to send and receive messages that serve to test the connection. If you want to see what you are typing, get back to the KERMIT prompt by typing the "escape" command that you wrote down and tested above. Then issue the command set loc on to have a local echo, but you must remember to set loc off before attempting to transfer a file. If the connection is not made, so that it is not possible to send AND receive messages, then you should check the baud rates of the computers, the modems, and the wiring to the modems, or the wiring between the directly-connected computers, and make sure that the computer is sending or receiving data to the correct port on the computer. It is also helpful, as a last resort, to check whether or not the telephone died because you forgot to pay the bill (don't laugh...it once happened to us!) SENDING AND RECEIVING FILES When each computer operator is satisfied that a connection has been made, then both operators return to the KERMIT prompt, as explained above. The operator that wants to receive a file types receive The file name will be sent from the other machine. The operator that wants to send a file types the command send [drive:]filename.ext For example, to send the file on disk B that is named myfile.txt , the operator would type send b:myfile.txt It is usually not necessary to type in the drive specification, since you should be using disk B as the "logged disk drive", but it is always safe to do so. If the receiving operator hits the return before the sending operator hits the return, it may be necessary for the receiving operator to hit another return before the file will be sent. KERMIT will wait for a few seconds, and then the operators will see on their screens that packets of information are being sent and received. KERMIT first sends the file name, and it is a good sign to the receiving operator when the file name appears on his or her screen. The number of packets will increment on both machines until the transfer is complete, and then each computer will return to the KERMIT prompt. At that time, the receiving operator can check the file or another file can be sent. CHECKING WHAT WAS SENT Once a connection has been established with KERMIT, it is not broken if one or both of the operators return to the operating system of their computers to check something such as the length or name of a file. Thus, when a transfer is complete, the receiving operator can get out of KERMIT by typing exit at the KERMIT prompt. The file that was received can be examined, usually by issuing the command type [drive:]filename.ext The file will scroll by on the screen, and you will see that it has been transferred without error! The receiving operator can then return to KERMIT by reloading KERMIT into memory. As stated above, go to your B disk and type A:KERMIT or whatever the file name of your program is. If you need to, reset the baud rate, and you will then be able to transfer another file or get into connect mode and send messages. FIGURING OUT WHY (IF) KERMIT DOES NOT WORK KERMIT has never, in my two years of experience with the program, made a mistake in sending and receiving files between CP/M computers or between CP/M computers and mainframes. It accurately transfers files even when the telephone line is unusable for voice transmissions because of static and noise. Operators do, however, tend to make mistakes. One such problem is impatience. Please let KERMIT wait for a few seconds before you touch a carriage return on the receiving computer to "make it work." If KERMIT seems to be dead after about thirty seconds of waiting, then something is wrong. If you were able to send messages back and forth in connect mode, or if KERMIT fails after the first four or five packets, then probably the problem is that one of the operators set the local echo switch on but forgot to set it off. It is also possible that the file that you wanted to send does not exist, because the sending operator missppelled its name in the send command. Occasionally, KERMIT will fail for reasons beyond its control. The transfer will fail if one of the computers involved goes down. For example, mainframe computers or their communi- cation ports often go down (that's why we are now using micros for most of our work, right?). A feature such as call waiting or intercom messages on a telephone line will stop the transmission if they happen during a transfer. I view these failures as advantages in that it shows that KERMIT is smart enough to quit when there is a major problem. We have also encountered a problem with the way BASICA and dBASE II on IBM PC-type computers mark the end of a file and save it. The solution is to load the file into a text editor or word processor and then resave it before sending it. For example, load a file into WordStar and then save it. An unreliable alternative is to copy the file using the /A parameter. The problem is not fully understood; it centers around the PCDOS and MSDOS software's use of buffered output when writing disk files. Apple II versions of KERMIT work well with DOS 3.3, but Apple IIs do not work so well. They are slow, there are differences between the II, the II+ and the IIe, and there is no standard way that people set up their Apple's for communications. If you plan to use Apple KERMIT, please check with other Apple KERMIT users before ordering your communications card and modem. Currently, the best cards may be the Apple Communications card, the Hayes Micromodem II, or the Super Serial Card. Actually, the best way may be to install a Z80 card in the Apple II and run the Apple CP/M version of KERMIT. SUMMARY KERMIT is a very powerful program, with extensive error checking, and thus it is ideal for transferring files between computers. The full documentation will show you many commands and options for the program. You may want to order the documentation, but the simple procedures in this guide may be adequate for your needs. Extensive documentation is available for this program from KERMIT Distribution Columbia University Center for Computing Activities 7th Floor, Watson Laboratory 612 West 115th Street New York, NY 10025 There are three publications: the User's Guide, the Protocol Manual, and the Source Listing for your system. Each costs $5.00, and you should make out your check to Columbia University Center for Computing Activities. Make sure and tell them what microcomputer and operating system you are using. Those who are interested in mainframe implementations (which currently cost $100 for the complete distribution) should write for ordering information. Note that the KERMIT distributors can provide the programs only on 9-track magnetic tape in a varity of formats. They do not provide the program on floppies. When necessary, there are specific help files that are distributed with KERMIT to help with its use. For example, there is a help file with the Kaypro II version because of the non- standard way a Kaypro handles tab stops on its screen. There are also articles and announcements about KERMIT. For example, see BUSS #88 and June-July, 1984 issues of BYTE. Please do not call the Kermit Distribution Center for assistance with KERMIT for your micro. After all, it is a free program, and national support, sales, service, debugging, revisions, everything else is being handled by only two or three part-time people. You can write, however, for the publications. Finally, KERMIT is changing and improving constantly -- versions are added for new systems, old versions are improved, and documentation is rewritten. You are encouraged to make your own contributions to "KERMIT culture" and to make them available not only to your friends, but also to send them back to Columbia at the address given above, on 9-track magnetic tape or IBM PC eight sector floppy disk. For example, we need KERMIT for TurboDos version 1.2, and we need to know how to implement the "break" key on many CP/M machines (like the H89) through software. The most current version of KERMIT for CP/M machines is 3.9a, which fixes a bug in version 3.9 that may garble the transmission of apmersands. A brand-new MSDOS version is soon to be released. Watch for new releases and updates. Meanwhile, below is a recent but even now out-of-date listing of available versions. CURRENT KERMIT VERSIONS as of 4:42pm Wednesday, 6 June 1984 Listed in reverse chronological order of installation at Columbia. "Code" is the prefix under which the files are stored in the KERMIT distribution area. CURRENT KERMIT VERSIONS as of 9:46pm Wednesday, 18 July 1984 Listed in reverse chronological order of installation at Columbia. "Code" is the prefix under which the files are stored in the KERMIT distribution area. New entries are added at the top. Code Machine/OS Language Ver # dd/mm/yy Author or Contact TSO IBM 370/MVS/TSO IBM Asm 1.0 18/07/84 SYSRONR@UCHIVM1.BITNET APP Apple II/DOS CROSS 2.1 18/07/84 G.BUSH@COLUMBIA-20 20 DEC-20/TOPS-20 MACRO-20 4.1(236) 18/07/84 CC.FDC@COLUMBIA-20 K11 PDP11/RSX11M,M+ MACRO-11 2.18 17/07/84 ATSBDN@UOFT01.BITNET K11 PDP11/RSTS MACRO-11 2.18 17/07/84 ATSBDN@UOFT01.BITNET K11 PDP11/RT-11 MACRO-11 2.18 17/07/84 ATSBDN@UOFT01.BITNET APO Apollo/Aegis FORTRAN 1.0 13/07/84 John Lee, RCA Labs HPM HP1000/RTE FORTRAN 1.0 13/07/84 John Lee, RCA Labs SIR Sirius-1 MASM 1.20 12/06/84 Barry Devlin, Dublin ST HP3000/SoftwareTools/Ratfor 1n 18/02/84 kpd%HP-LABS@CSNET-Relay ST Univac/SoftwareTools/Ratfor 1n 11/06/84 kpd%HP-LABS@CSNET-Relay CPM Apple II/CPM-80 ASM 3.9A 6/06/84 CC.FDC@COLUMBIA-20 CPM DECmate II/CPM80 ASM 3.9A 6/06/84 CC.FDC@COLUMBIA-20 CPM Generic CPM80 2.2 ASM 3.9A 6/06/84 CC.FDC@COLUMBIA-20 CPM Generic CPM80 3.0 ASM 3.9A 6/06/84 CERRITOS@USC-ECL CPM H/Z-19/CPM-80 ASM 3.9A 6/06/84 CC.FDC@COLUMBIA-20 CPM H/Z-100/CPM-80 ASM 3.9A 6/06/84 CC.FDC@COLUMBIA-20 CPM Kaypro II/CPM-80 ASM 3.9A 6/06/84 CC.FDC@COLUMBIA-20 CPM Osborne 1/CPM-80 ASM 3.9A 6/06/84 CC.FDC@COLUMBIA-20 CPM Superbrain/CPM80 ASM 3.9A 6/06/84 CC.FDC@COLUMBIA-20 CPM TRS80-II/CPM80 ASM 3.9A 6/06/84 CERRITOS@USC-ECL CPM Vector Graphx/CPM ASM 3.9A 6/06/84 CC.FDC@COLUMBIA-20 CPM VT180/CPM-80 ASM 3.9A 6/06/84 CC.FDC@COLUMBIA-20 CPM TelconZorba/CPM80 ASM 3.9A 6/06/84 G.BUSH@COLUMBIA-20 PRO DEC Pro-350 Bliss 1.0 1/06/84 G.BUSH@COLUMBIA-20 VMS VAX/VMS Bliss 3.0.051 1/06/84 G.BUSH@COLUMBIA-20 K10 DEC-10/TOPS-10 MACRO/Bliss 3(124) 1/06/84 G.BUSH@COLUMBIA-20 TRS TRS-80 I and III M80 3.5 30/05/84 stan@RICE 170 Cyber 170/NOS Fortran77,asm 2.0 25/05/84 knutson@UT-NGP UCI IBM PC/p-System UCSD Pascal 0.1 23/05/84 KMM@CORNELLA.BITNET RBLC Rainbow/MS-DOS CI/86 2.14 23/05/84 LCAMPBELL@DEC-MARLBORO 800 ABC-800/ABCDOS BASIC-II 2.2 8/05/84 Per_Lindberg_QZ@QZCOM 86/APC NEC APC/CPM-86 ASM86 2.7 7/05/84 CONTEXT@WASHINGTON 86/RB Rainbow/CPM-86 ASM86 2.7 4/05/84 CC.FDC@COLUMBIA-20 MAC80 8080 Cross Asmblr MACRO-10 10E(120) 30/04/84 CERRITOS@USC-ECL CPM Morrow Decision I ASM 3.9 26/04/84 CC.FDC@COLUMBIA-20 CPM Nokia MikroMikko ASM 3.9 26/04/84 CC.FDC@COLUMBIA-20 CPM Ohio Sci/CPM-80 ASM 3.9 26/04/84 CC.FDC@COLUMBIA-20 MP PDP-11/MUMPS-11 MUMPS(1982) 11/04/84 KMM@CORNELLA.BITNET UCT Terak/p-System UCSD Pascal 11/04/84 KMM@CORNELLA.BITNET KPROTO"KERMIT Protocol Manual" 5th Ed 2/04/84 CC.FDC@COLUMBIA-20 KUSER "KERMIT User Guide" English 5th Ed 5/03/84 CC.FDC@COLUMBIA-20 MU Honeywell/MULTICS PL/I 28/02/84 P.Amaranth, Oakland U TA2 Tandy 2000/MS DOS MASM 1.20 16/02/84 smp@UTEXAS-11 PRI Prime/PRIMOS PL/P 10/02/84 L.Spira, The SOURCE AOS Data General/AOS Ratfor 2/02/84 John Lee, G.E. HP1 HP-150/MS-DOS MASM 1.3 2/02/84 Frank Heartney, H-P CMS IBM 370/VM/CMS IBM Asm 1/02/84 CC.DAPHNE@COLUMBIA-20 MDS Intel DevSys/ISIS PL/M 27/01/84 Chris@COLUMBIA-20 RT PDP11/RT11 OMSI Pascal 24/01/84 Bruce Pinn, U Toronto HP9 HP-98xx/p-System HP Pascal 20/01/84 Gallaher@RUTGERS VF VAX/VMS Pascal/Fortran 18/01/84 Bruce Pinn, U Toronto ATA Atari/DOS Action! 9/01/84 G.TANG@SU-SCORE MTS IBM 370/MTS Asm, Pascal 6/01/84 "Gavin Eadie"b@UMich-MTS UN Univac 1100/Exec Exec Assembler 22/12/83 STEVENS@MACCWISC.MAILNET PC IBM PC etc/PC-DOS MASM 1.20 30/11/83 CC.Daphne@COLUMBIA-20 PC H/Z-100 MASM 1.20 30/11/83 CC.Daphne@COLUMBIA-20 VIC Victor 9000/CPM86 ASM86 1.1 25/11/83 Barry Devlin, Dublin SEE Seequa/MS DOS MASM 1.18 17/11/83 Glenn Everhart, RCA VIC Victor 9000/MSDOS MASM 1.18 10/11/83 Bryan Peterson, ORNL UX (various) Unix 17/10/83 CC.FDC@COLUMBIA-20 VIC Victor 9000/MSDOS MASM 1.1 3/06/83 Barry Devlin, Dublin VX VAX/VMS VAX-11 C 24/04/83 Todd Little, DEC