@Comment(-*-SCRIBE-*-) @Comment(SCRIBE Text Formatter Input for the KERMIT User Manual) @Make @Comment(Use /draft:F on command line to produce .LPT file w/cc in column 1) @Style @Modify @Comment(Printing Device Dependencies) @Define @Case @Comment(Set desired spacing around various environments) @Modify @Modify @Modify @Modify @Modify @Modify @Modify @Comment(Set spacing and paging requirements for chapter & section headings) @Modify(Hdx,Above 2,Below 1,Need 8) @Modify(Hd0,Above 2,Below 1,Need 8) @Modify(Hd2,Above 2,Below 1,Need 8) @Modify(Hd3,Above 2,Below 1,Need 8) @Modify(Hd4,Above 2,Below 1,Need 8) @String(What="Manual") @Comment(Start the document off with a titlepage) @Begin(TitlePage,Initialize "@BlankSpace(2.5inches)",sink 0) @MajorHeading(KERMIT USERS GUIDE) @i Frank da Cruz, Daphne Tzoar, Bill Catchings@foot Columbia University Center for Computing Activities New York, New York 10027 @value Copyright (C) 1981,1982,1983 Trustees of Columbia University in the City of New York @i @end(titlepage) @case,immediate) @blankpage(1) @set(page=-2) @comment{end: us.lerner modification for duplexing}"> @pageheading
@PrefaceSection The Kermits are coming home to roost. Recipients of earlier Kermit distributions have sent back their own contributions. The 4th edition includes these, plus additional work done at Columbia (where no attribution is made below, the work was done at Columbia): @begin @index KERMIT-32 was written for the VAX-11 running VMS by Bob McQueen at Stevens Institute of Technology. KERMIT-32 can act as a server. @index KERMIT-65 was written for the Apple II 6502-based DOS system by Antonino Mione at Stevens Institute of Technology. KERMIT-10 now has CONNECT command, added by Vanya Cooper at Pima Community College in Tucson, Arizona. KERMIT-20 has various new SET options, load-@|dependent timeouts, improved support for local operation (comforting messages on the screen to show the file and packet traffic), expanded help and information facilities, and the ability to issue commands to a Kermit Server (KERMIT-20 could already act as a Kermit Server itself), expanded debugging options, etc. Kermit-86 can now issue commands to a server, and can do wildcard sends. Z100 support was added to Kermit-86 at Stevens Institute of Technology. @index@index An adaptation of Kermit-80 was done by DEC for the Rainbow-100. This is not the "real" Rainbow Kermit, but a stopgap. It will only work at speeds up to 1200 baud. A similar adaptation was done for the DECmate-II with CP/M. @index A "generic" version of Kermit-80 has been done, which should work on any CP/M-80 system that implements the CP/M IOBYTE. @index@index@index An implementation of Kermit-80 was done for the TRS-80 II under CP/M by Bruce Tanner at Cerritos College in Norwalk, California. Another for the Osborne 1 by Charles Bacon at the National Institutes of Health. And another for the Telcon Zorba by Nick Bush at Stevens. @index@index The SYMBOL cross assembler was "reTOPS10ized" at several sites, but it has been dropped from the KERMIT distribution altogether in favor of MAC80, an 8080-@|specific cross assembler that assembles KERMIT-80 much faster than SYMBOL could do, and produces a smaller hex file in the bargain. SYMBOL was written in SAIL, which is never quite the same on any two TOPS-10 or TOPS-20 systems; MAC80 is written in MACRO-10, and doesn't require any special runtime support, and runs with no problems under either TOPS-10 or TOPS-20. MAC80 was contributed by Bruce Tanner. The RT-11 OMSI Pascal implementation contributed earlier by Philip Murton of the University of Toronto was fixed up by Michael Weisberg of Mt.@ Sinai Hospital in NYC to be self contained and complete, and actually brought up on real RT-11 systems (the previously distributed version was incomplete). The Columbia CS Department UNIX Kermit was updated to distinguish between "image mode" file transfers (e.g. UNIX-@|to-@|UNIX), and ordinary transfers (in which newlines are mapped to CRLFs). @end @PrefaceSection For the 3rd edition, the Kermit manual has been reorganized to improve clarity and to prune away a lot of redundant material. The wording and examples have become less oriented to Columbia, and less towards programmers. Much new material has been added as a result of new implementations of Kermit done at Columbia and elsewhere, notably for TOPS-10, UNIX, and the IBM PC. Other additions describe techniques for bootstrapping Kermit onto new systems, complications arising from system bytesize mismatches, and a new simplified way of running Kermit. The section describing the Kermit protocol has been moved to a new document, the @ux. Some material has been removed that described how to use certain systems. Due to the proliferation of systems supporting KERMIT, it is no longer practical to describe how to use each system. It is now assumed that the reader knows how to log in and run programs on the systems involved, how to start a micro, insert a floppy disk, and so forth. @unnumbered The KERMIT software is free and available to all. Columbia University, however, is not set up to distribute free software on the scale required for KERMIT. Therefore, to defray our costs for media, printing, postage, labor, and computing resources, we must request a moderate donation from sites that request KERMIT directly from Columbia. The schedule is as follows: @begin @tabclear()@tabset(4.0inches) Complete KERMIT Distribution@\$100@t<.>00 @i<(Tape, Users Guide, and Protocol Manual)> @blankspace(0.5) Printed Documents@\$5@t<.>00 each @i<(Users Guide, Protocol Manual, or Any Source Listing)> @end Other sites are free to redistribute KERMIT on their 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 below so that we can maintain a definitive and comprehensive set of KERMIT implementations for further distribution. @begin @blankspace(1) To order KERMIT from Columbia University, send a letter requesting either: @begin (a)@\The manuals or source listings you desire (specify each one), @i (b)@\A 9-track magnetic tape in one of the following formats: @begin @tabclear()@tabset(1.75inches,5.0inches) @u @\@ux @\@u TOPS-10 @\BACKUP/Interchange, Unlabeled @\ 800, 1600 TOPS-20 @\DUMPER, Unlabeled @\ 800, 1600 IBM VM/CMS @\EBCDIC, CMS Format @\1600, 6250 @\ @i EBCDIC, OS Standard Label@\1600, 6250 @i @\ASCII, ANSI Label, Format ``D''@\ 800, 1600 @end (Specify system, format, and density.) One copy of each manual will be included with the tape. We will supply the tape, packaging, and postage. @end @end We can only make tapes in the formats listed above. @ux; bootstrapping procedures are provided to allow the microcomputer versions to be downloaded from the mainframe for which the tape is produced. The tape includes all source programs, documentation, and, when practical, binaries or hex. Send your letter to: @begin KERMIT Distribution Columbia University Center for Computing Activities 7th Floor, Watson Laboratory 612 West 115th Street New York, N.Y. 10025 @end Please list the machines and operating systems you expect to run KERMIT on, specify the tape format or the listings desired, and mention whether there are additional systems for which you require KERMIT or if you might be interested in attempting your own implementation. Make checks payable to @i. KERMIT is also available to users of the BITNET network via a server at host CUVMA. BITNET users may type ``SMSG RSCS MSG CUVMA KERMSRV HELP'' for further information. Additional network and user group distribution methods are under consideration. Suggestions would be welcome. @begin(i) 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. @end(i) @Chapter Everyone wants to get computers talking to one another. There are many ways to do this, and most of them are very expensive. But there is one way that is cheap and relatively easy: connect the two computers through their terminal (TTY) ports, tricking one computer (or both) into believing that the other is a terminal. This can be expected to work because the standard for connecting computers to terminals is almost universally followed, in both hardware (plug and signal: EIA RS-232) and software (character code: ASCII). Once two computers (@i) are connected in this way, cooperating programs can be run on each host to achieve the desired communication by means of a communication @I. Why is a protocol @Index necessary at all? Two major problems occur when you try to connect two computers via TTY line: @begin @u. @Index Data can become garbled in transmission because of electrical interference, cosmic rays, or rodents chewing on the wires. The longer a wire, the more noise you can expect. The noise corrupts the data, sometimes in subtle ways which you may not notice until it's too late. @u. @Index One computer may be faster, or have larger buffers, @Index than the other. If one computer can send data faster than the other can take it in, then some kind of @i@index(Flow Control) mechanism, either in the data stream (XON/XOFF) @Index or in parallel to the data (modem control signals), can be employed to prevent data overruns, but no two computers can be assumed to honor the same conventions for flow control, or indeed to do it at all. Even when flow control is being done, those signals are themselves are subject to noise corruption. @end To prevent corruption of data and to synchronize communication, cooperating computers can send control information to one another at the same time that they are transferring data. This intermingling of control information with data, and the resulting actions, constitute a "protocol". @Index[KERMIT Protocol] KERMIT is a simple example of such a protocol. It is specifically designed for transfer of files over ordinary serial communication lines. KERMIT is not necessarily better than many other terminal-@|oriented file transfer protocols but it is free, it is well documented, and it has been implemented compatibly on a variety of microcomputers and mainframes. KERMIT transfers data by encapsulating it in @index "packets" of control information. This information includes a synchronization marker, a packet number to allow detection of lost packets, a length indicator, and a @index"checksum" to allow verification of the data. Lost or corrupt packets are detected, and retransmission is requested. In addition, various special control packets allow cooperating KERMITs to connect and disconnect from each other and to exchange various kinds of information. Very few assumptions are made about the capabilities of either computer, so the KERMIT protocol can work between many different kinds of systems. It should be noted that the checksum technique used by Kermit is not foolproof. There are conditions under which bad data can still generate a valid checksum. In practice, however, the protocol is quite reliable. Acknowledgements to the Stanford DIALNET project (John McCarthy and Mark Crispin), Peter Hurley of DEC (the "Hurley Protocol" described in the only known issue of the @i), the Stanford University Medical Center MAINSAIL project (TTYFTP), the University of Utah CS Department SMALL-FTP developers, and to the authors of the File Transfer Protocol section of the ARPANET Protocols Handbook. The original design was done by Bill Catchings, Frank @w, and Vace Kundakci of the Columbia University Computer Center, in consultation with some potential users, notably Peter Brooks. Bill wrote the initial implementations: one for TOPS-20 and one for a Z80 CP/M system, which has subsequently been adapted for a number of other CP/M systems. Bill also wrote the C kernel, which has been used as the basis of other implementations, particularly the UNIX implementation of Bob Cattani and Chris Maio of our CS Department. Daphne Tzoar of Columbia wrote and documented the IBM VM/CMS and the IBM PC implementations. Other contributors are noted appropriately throughout this manual. @Chapter @label<-using> KERMIT is a protocol for reliable file transfer between computers over the ordinary serial telecommunication lines that are used to connect terminals to computers. The mechanics of using KERMIT to get a file transferred can be confusing until you get the hang of it. A little background material might make the process a bit easier to understand. KERMIT is probably the cheapest way to put two computers into communication. The required hardware is usually already available, the software is free, and all components run as ordinary user programs, with no system modifications. This is in sharp contrast to a communication network, where there are dedicated high-@|speed communications channels and drivers, expensive software, and so forth. The network provides more services than KERMIT, usually at higher speed, and with greater convenience, because the network is usually part of the system. When a network is not available, KERMIT can fill in. But since KERMIT is not integrated with any particular system, but rather grafted on top of many different systems, it requires some extra work from those who use it. @section KERMIT embodies a set of rules for transferring files reliably between computers. In general, one computer is a large system (a @i, for instance a timesharing system with many terminals), and the other is a personal computer (@i)@foot{Host-@|to-@|host and PC-@|to-@|PC connections are also possible.}. The host believes that the PC is an ordinary terminal. In order for the KERMIT protocol to occur, a KERMIT @i must be running on each end of the communication line -- one on the host, one on the PC. The two Kermit programs exchange messages in a special language all their own, the @i. The dialog runs something like, "Hi! I'm going to be sending files to you. When you send messages to me, please don't make them more than 80 characters long, and if you don't hear anything from me for 15 seconds, wake me up, OK?" @i<"OK."> "Now, here comes a file called @q(FOO.TXT), OK?" @i<"OK."> "Here's the first piece..." @i<"Got it."> "Good! Here's the second piece..." @i<"Oops, sorry, the second piece was inconsistent."> "Well, then here it is again..." Et cetera. You don't see any of this. It's all packed into a very concise code which the two Kermits can understand; they do all the worrying about transmission, error checking, character set translation, and so forth. Each message is called a @i@index, and each packet is in a special format that all Kermits can understand. @section Your task is just to get the two Kermits started. The confusion arises because you have to use a single keyboard and screen to talk to two different computers, two different programs. Let's talk about a common case: you are sitting at a personal computer (PC@foot{The terms PC, micro, microcomputer, and workstation will all be used loosely in this document to denote a single-@|user system.}), which has a serial communication port. The serial port is connected to a host computer using, say, a dialup modem@foot{The actual means of connection isn't important in this case -- it also could be a direct line to the host, some kind of switched line, etc.}. Normally, when you use your PC, you are "talking" directly to it; your commands are interpreted directly by the PC's operating system (CP/M, MS-DOS, UNIX, whatever), or by some program that runs on the PC (an editor, a text formatter, space invaders...). The version of Kermit on your PC is a program like any other, but it has a special ability to either interpret your commands directly, like other programs, or to pass everything you type through to the host. When you tell Kermit to @indexCONNECT, it sends every character you type out the serial port, and it will put every character that comes in the serial port onto the screen. This is called @index@i -- one computer acts "virtually" as though it were a terminal on another. You are now "talking" to the host, and the PC is ignoring you. Kermit, like most programs, has a @i@index. The prompt is a symbol it types on the left margin to indicate that it is ready for you to type a command. Kermit's prompt is normally "@q@i@q(>)". The @i identifies the implementation of Kermit; the Kermit that runs on the DEC-20 is called "Kermit-20" and its prompt is "@q(Kermit-20>)"; the Kermit that runs on Z80 and 8080-@|based microcomputers is called "Kermit-80" and its prompt is "@q(Kermit-80>)"; the Kermit on the IBM PC is "Kermit-86"@foot{Although the processor in the IBM PC is an 8088, it is programmed as though it were an 8086.}, and so forth. If you become confused about who you are talking to, the prompt should provide a clue. In addition, most Kermits print an informative message like @example<[Connecting to remote host, type CTRL-]C to return]> when you CONNECT, and type another message like @example<[Connection closed, back at PC]> when you return. Having "connected" to the host, there must be a way for you to get back to the PC. This is accomplished by an @i@index. As Kermit passes your characters through to the host, it checks each one to see if it's a special predefined @i. When the PC sees this character, it stops ignoring you -- you are once again "talking" to the PC, not the host. The escape character is normally chosen to be one that you will not need to type while talking to the host, and one that is hard to type by accident -- it's usually a @i@index, such as Control-@q<]>, which is accomplished by holding down the key marked CTRL or CONTROL and typing the indicated character (in this case, a right bracket "@q<]>"). The CTRL key works just like a SHIFT key. Control characters are written either as CTRL-A or @q<^A>, where A is the character to be typed while holding down CTRL. @section To transfer a file, you must first get the attention of the PC's operating system. This is normally done by starting the PC, possibly inserting your system floppy disk first. Once you're at command level on your PC, you run Kermit. Then you tell Kermit to CONNECT you to the host. Now you're talking to the host -- at this point you must log in, and then run Kermit on the host. Now you have a Kermit on each end of the wire. The next step is to tell @i Kermit what to do. Suppose you want to transfer a file from the host to the PC; you would first tell the host Kermit to SEND the file, then "escape" back to the PC Kermit and tell it to receive the file. The transfer begins -- all you have to do now is sit back and watch. The PC Kermit will continuously show packet and retry counts on your screen, and will notify you when the transfer is complete. The desired file is now on your PC's disk. The Kermit protocol has ensured that the file arrived correctly and completely. Now you must clean up after yourself: CONNECT back to the host, exit from Kermit on the host, log out from the host, "escape" back to PC Kermit and exit from it. Now you can do whatever you had planned for your file -- edit it, print it on your PC printer, etc. The KERMIT protocol, and most Kermit programs, allow you to send a file reliably from the host to the PC, from the PC to the host, from host to host, or PC to PC, usually without any special regard for the nature of the particular machines involved. Most implementations also allow files to be sent in groups, with a single command, such as "Send all my Fortran files!" The scenario for each of these is always the same as above -- only the details of how to establish the actual connection differ. KERMIT works best with "printable" files -- files composed only of letters, digits, punctuation marks, carriage returns, tabs, and so forth -- since these can be represented on almost any kind of computer. KERMIT is also able to transfer "binary" files -- files such as executable programs -- composed of arbitrary bit patterns, but binary files normally are meaningful only to the kind of computer on which they are generated. Nevertheless, KERMIT can usually move such files from system A to system B (where they are not much use) and back to system A in their original condition, although in some cases some special care must be taken to accomplish this. Now that we have a basic understanding of what KERMIT does and how it works, let's look at some more concrete examples. First you need to know what the basic Kermit commands are. @section @label<-commands> @Index[Kermit Commands] These are generic descriptions of the most basic Kermit commands. Detailed descriptions for specific implementations of Kermit will come later. An underscored command is standard and should be found (in some form) in any implementation of Kermit. In these descriptions, @i@index refers to the system that you are directly connected to, @i@index refers to the system to which you are CONNECTed via Kermit. Commands may take one or more operands on the same line, and are terminated by a carriage return. @begin @Index[SEND] @ux@\Send the file or file group specified by @i(filespec) from this Kermit to the other. The name of each file is passed to the other Kermit in a special control packet, so it can be stored there with the same name. A file group is usually specified by including "wildcard"@index characters like "@q<*>" in the file specification. Examples: @begin(Example) send foo.txt send *.for @end(Example) Some implementations of Kermit do not support transfer of file groups; these versions would require a separate SEND command for each file to be transferred. @Index[RECEIVE] @u@\Receive a file or file group from the other Kermit. If an incoming file name is not legal, then attempt to transform it to a similar legal name, e.g.@ by deleting illegal or excessive characters. The name thus formed cannot be guaranteed to be unique, in which case previously existing files could be overwritten. Some versions of Kermit attempt to prevent this by warning you of filename collisions and taking, or allowing for, evasive action. @Index[CONNECT]@Index[Virtual Terminal] CONNECT@\Make a "virtual terminal" connection to the remote system. On a PC or micro, this usually means to send all keyboard input out the serial port, and display all input from the serial port on the screen. Mainframe KERMITs that have this command behave similarly; they send the characters typed at the terminal to a specified TTY line and pass all input from that TTY line to the terminal. KERMIT connections are most commonly initiated from the the small computer. To "escape" from a virtual terminal connection, type Kermit's @Index[Escape Character] escape character (e.g.@ @q, control-@|rightbracket), followed by the letter "C" for "Close Connection". @Index[SET] SET@\Establish various parameters, such as communication line number, CONNECT escape character, etc. See the description of the appropriate version of KERMIT in Chapter @ref<-implementations>. SHOW@\@Index[SHOW]Display the values of SET options. @u@\Type a summary of KERMIT commands and what they do. @u@\Exit from KERMIT back to the host operating system. @q(?)@\Typed anywhere within a KERMIT command: List the commands, options, or operands that are possible at this point. This command may or may not require a carriage return, depending on the host operating system. @end @section Kermit is used most commonly in several ways: a user sitting at a PC (personal computer, microcomputer, workstation) which is connected to a larger host computer; a user logged in to a host computer which is connected to another host; two users, each sitting at a PC. @SubSection In this example, the user is sitting at an IBM Personal Computer (PC), which is connected through its serial port to a DECSYSTEM-20 host computer. The IBM PC is @i, the DEC-20 is @i. This example will also apply almost literally to any other microcomputer implementation of Kermit. You have started up your PC and have the Kermit program on your disk. Begin by running Kermit on the PC. Use Kermit's CONNECT command to connect to the DEC-20. The PC will now behave as a terminal to the DEC-20. In fact, the PC emulates the popular DEC VT52 terminal, so it is desirable to tell the DEC-20 that your terminal is a VT52. Login on the DEC-20 and run Kermit there. Here is an example of this procedure with commands you type underlined: @Begin @tabclear@tabDivide(3) A>@u[kermit]@\! Run Kermit on the PC.@foot{Everthing from a "@q" mark to the end of line is a comment, not system typeout or part of a command.} Kermit V1.2 Kermit-86>@\! This is the Kermit prompt for the PC. Kermit-86>@u[connect]@\! Connect to the DEC-20. [Connecting to host. Type CTRL-]C to return to PC.] @\! You are now connected to the DEC-20. CU20B@\! The system prints its herald. @@@ux[terminal vt52]@\! Set your terminal type (optional). @@@ux[login my-id password]@\! Login using normal login method. @i<(At this point, the DEC-20 prints various messages.)> @@@u[kermit]@\! Run Kermit on the DEC-20. Kermit-20>@\! This is Kermit-20's prompt. @End You are now ready to transfer files between the two machines. @Paragraph @label<-rec> The following example illustrates how to send files from the DEC-20 to the PC. Note the use of the "*" @i@index character to denote a @i. @Begin @tabclear@tabDivide(3) Kermit-20>@ux[send *.for]@\! Send all FORTRAN files. @ux<^]c>@\! Now return back to the PC by @\! typing the escape sequence, in this case @\! ^]C (Control-] followed by "C") [Back at PC.] Kermit-86>@u[receive]@\! Tell the PC files are coming. @End If you take more than about 5 seconds to get back to Kermit-86 and issue the @Index[RECEIVE] @c command, the first packets from Kermit-20 may arrive prematurely and appear as garbage on your screen, but no harm will be done because the packet will be retransmitted by the DEC-20 until the PC acknowledges it. Once the connection is established, the PC will show you what is happening -- it first clears the screen and waits for incoming packets; as packets arrive, the current file name and packet number will be continuously displayed on the screen. When the PC's @q("Kermit-86>") prompt returns to your screen, the transfer is done. When the transfer is complete, you must CONNECT back to the DEC-20 host, EXIT from Kermit there, logout from the DEC-20, and return to the PC as you did previously. @Begin @tabclear@tabDivide(3) Kermit-86>@ux[connect]@\! Get back to the DEC-20. [Connecting to host. Type CTRL-]C to return to PC.] Kermit-20>@\! Here we are. Kermit-20>@u[exit]@\! Get out of Kermit-20. @@@ux@\! Logout from the DEC-20. Logged out Job 55, User MY-ID, Account MY-ACCOUNT, TTY 146, at 24-Jan-83 15:18:56, Used 0:00:17 in 0:21:55 @ux<^]c>@\! Now "escape" back to the PC, [Back at PC.] Kermit-86>@ux@\! and exit from the PC's Kermit. @End The files you transferred should now be on your PC disk. @Paragraph To send files from the PC to the DEC-20, follow a similar procedure. First follow the instructions in the previous section to log in to the DEC-20 through the PC. Then in response to the host Kermit's "@q(Kermit-20>)" prompt you type @Index[RECEIVE] RECEIVE rather than SEND. Now escape back to the PC and use the @Index[SEND] SEND command to send the local PC files to DEC-20 host. The PC will show you the progress of the transmission on its screen. When the "@q(Kermit-86>)" prompt indicates that the transmission is complete you should follow the procedure shown above to logout from the DEC-20 host, except that you may first wish to confirm that the files have been stored correctly in your directory on the DEC-20. @SubSection This section describes use of Kermit between two hosts. A "host" is considered to be a large or multi-user system, whose distinguishing characteristic is that it has multiple terminals. Use of Kermit for host-@|to-@|host file transfers differs from the PC-@|to-@|host case in that the line your terminal is connected to is not the same as the line over which the data is being transferred, and that some special commands may have to be issued to allow one Kermit to conform to unusual requirements of the other host. In this example, you are already logged in to a DEC-20, and you use an @index@i to connect to an IBM 370-@|style system running VM/CMS@index through DEC-20 TTY port 12. The autodialer, in this example, is invoked from program called DIAL (idealized here, for simplification), to which you merely supply the phone number. @Begin @tabclear@tabDivide(3) @@@ux[dial 765-4321/baud:300] 765-4321, baud 300 [confirm] Dialing your number, please hold... Your party waiting is on TTY12: @@ @End Other methods exist for connecting two hosts with a serial line. Dedicated hookups can be made simply by running an EIA cable@index between TTY ports on the two systems.@foot{Such a connection, by the way, requires the receive and transmit leads be swapped in one of the RS-232 connectors; this is called a @index(Null Modem)"null modem" cable.} For connecting to remote systems when no autodialer is available, a manual @index dialup connection is also possible, but tricky.@foot{Here's one way: log in on port x on your system, and assign another port, y, to which you have physical access. Unplug the terminal from port y, and connect the terminal to a dialup modem. Dial up the remote computer and log in on it. Now, using a null modem cable, connect the modem directly to port y. Go back to your terminal on port x, run Kermit from it, and CONNECT to port y.} If you have a microcomputer that supports KERMIT, you may find it easier to first transfer from host A to the micro, then from the micro to host B. The following procedure would be the same in any case, once a connection is made. Note that Kermit-20 accomplishes remote terminal connection by running a program called TTLINK in an inferior fork. @Begin @tabclear@tabdivide(3) @@ @@@ux[kermit]@\! Run Kermit on the DEC-20. Kermit-20>@ux[set ibm-flag]@\! Turn on special handshaking, parity, local echo. Kermit-20>@ux[set line (to tty) 12] ! Indicate the line we'll use. Kermit-20>@ux[connect]@\! And connect to it. [TTLINK: Connecting to remote host over TTY12:, type C to return.] VM/370 ONLINE@\! The IBM system prints its herald. .@ux[login myuserid XXXXXX]@\! Login to the IBM system. LOGON AT 20:49:21 EST THURSDAY 01/20/83 CUVMB SP/CMS PUT 8210 01/19/83 . .@ux[kermit] KERMIT-CMS>.@ux[send profile exec] ! Send a file. @ux<^Yc>@\! TTLINK's escape sequence typed here. [TTLINK: Connection Closed. Back at DEC-20.] Kermit-20>@ux[receive]@\! Tell Kermit-20 to RECEIVE. @End The transfer takes place now; Kermit-20 will print the names of incoming files, followed by dots or percents to indicate the packet traffic (a dot for every 5 packets successfully transferred, a percent for every timeout or retransmission). It is complete when when you see "@q<[OK]>" and the Kermit-20 prompt next appears. At that point we connect back to the remote IBM system, exit from the remote Kermit and log out. @Begin @tabclear@tabDivide(3) . PROFILE.EXEC.1 ..%%.[OK] Kermit-20>@ux[connect]@\! Get back to IBM and clean up. [TTLINK: Connecting to remote host over TTY12:, type C to return.] KERMIT-CMS>. KERMIT-CMS>.@u[exit] R; . SP/CMS .logout CONNECT= 00:03:01 VIRTCPU= 000:00.12 TOTCPU= 000:00.60 LOGOFF AT 20:52:24 EST THURSDAY 01/20/83 @ux[^Yc]@\! Type Kermit-20's escape sequence [TTLINK: Connection Closed. Back at DEC-20.] Kermit-20>@u[exit]@\! All done with Kermit. @End That's the whole procedure. The file is in your DEC-20 directory, completely readable, as @q -- note that KERMIT-CMS translated from the IBM EBCDIC character encoding into standard ASCII, and converted the space between the file name and file type to a dot. To send a file from the local host to the remote host, we would merely have reversed the SEND and RECEIVE commands in the example above. @subsection Kermit also works between personal computers (microcomputers, workstations). The difference here is that commands are typed on @i keyboards, rather than a single one. This is because a personal computer normally only accepts commands from its own keyboard. If one PC Kermit CONNECTs to another, there will normally be no program on the other side to listen. Making the physical connection between two micros is tricky. If the two units are in close proximity@foot{Why would you want to run Kermit between two PCs that are next to each other? One good reason is that if they are different models, their floppy disks are probably incompatible.}, you can connect their serial ports with a null modem@index cable@index. However, different micros have different requirements -- some may want a male connector on their serial port, others a female; many require that certain of the RS-232 signals be held high or low by wiring certain of the pins in the connector together@foot{For instance, some micros want DTR (Data Terminal Ready, pin 20) to be held high, and this might be accomplished by connecting it to CTS (Clear To Send, pin 5). See EIA Standard RS-232-C, and the appropriate manuals for your micro.}. In any case, you must also make sure the port speeds are the same at both ends. Connections at longer distances can be made via dialup, providing the required modems are available (one side needs @indexautoanswer capability), or using any kind of dedicated or switched circuit that may be available -- PBX, port contention unit, anything you can plug an EIA connector into. In this example, a DEC VT180 "Robin" CP/M microcomputer is connected to an Intertec "SuperBrain" CP/M micro, using a female-@|to-@|male null modem cable. Establishing the physical connection is the hard part. The connection can be tested by running Kermit and issuing the CONNECT command on both ends: typein from each micro should appear on the screen of the other. Suppose you want to send a file @q from the Robin to the SuperBrain. Proceed as follows: @begin Run Kermit on the SuperBrain, and give the RECEIVE command: @example[A>@u(kermit) CUCCA SuperBrain Kermit-80 - V3.2 Kermit-80>@u ] Run Kermit on the Robin, and give the SEND command for @q. @example[A>@u(kermit) CUCCA/DEC VT18X Kermit-80 - V3.2 Kermit-80>@ux(send foo.hex) ] Watch the packets fly. When you get a @q(Kermit-80>) prompt, the transfer is done, and you can EXIT from both Kermits. @end The key point is to start the @i end first -- most microcomputer Kermits do not include a timeout facility, and if the receiver is not ready to receive when the sender first sends, there will be a protocol deadlock. @section So far, we have been describing Version 1 of the KERMIT protocol. This edition of the KERMIT manual now presents Version 2, which includes the concept of a @i@index@index. A KERMIT server is a Kermit program that does not interact directly with the user, but only with another Kermit. You do not type commands to a Kermit server, you merely start it at one end of the connection, and then type all further commands at the other end. Not all implementations of Kermit can be servers, and not all know how to talk to servers -- yet. The server is run on the remote computer, which would normally be a large host, such as the DEC-20. You must still connect to the DEC-20 to log in and start the server, but you no longer have to tell one side to SEND and the other to RECEIVE, nor must you connect back to the remote side to clean up when you're done. Using the server, you can do as many send and receive operations as you like without ever having to connect back to the remote host. A Kermit server is just a Kermit program running in a special mode. It acts exactly like ordinary Kermit does after you give it a RECEIVE command -- it waits for a message from the other Kermit, but in this case the message is a command telling whether to send or to receive, and if to send, which file(s) to send. After escaping back to the local system, you can give as many SEND and RECEIVE commands as you like, and when you're finished transferring files, you can give the @indexBYE command, which sends a message to the remote Kermit server to log itself out. You don't have to connect back to the remote host and clean up. However, if you @i to connect back to the host, you can use the FINISH@index command instead of BYE, to shut down the Kermit server on the remote host without logging it off, allowing you to CONNECT back to your job there. Here's an example of the use of a Kermit server. The user is sitting at a CP/M microcomputer and a DEC-20 is the remote host. @Begin @tabclear@tabDivide(3) A>@u[kermit]@\! Run Kermit on the micro. Kermit V3.2 Kermit-80>@\! This is the micro Kermit's prompt. Kermit-80>@u[connect]@\! Connect to the DEC-20. [Connecting to remote host. Type CTRL-]C to return to micro.] CU20E@\! The DEC-20 prints its herald. @@@ux[terminal vt52]@\! Set your terminal type (optional). @@@ux[login my-id password]@\! Log in normally. @end @i<(The DEC-20 prints various login messages here.)> @Begin @tabclear@tabDivide(3) @@@u[kermit]@\! Run Kermit-20 normally Kermit-20>@u[server]@\! Tell it to be a server. [Kermit Server running on DEC-20 host. Please type your escape sequence to return to your local machine. Shut down the server by typing the Kermit BYE command on your local machine.] @u<^]c>@\! Now escape back to the micro. [Connection closed, back at micro.] Kermit-80>@ux[receive *.pas]@\! Get all my DEC-20 Pascal programs. Kermit-80>@ux[send foo.*]@\! Send all the "foo" files from my micro. Kermit-80>@ux[exit]@\! Exit from Kermit back to CP/M. A> @end @i<(Here you can do some work on the micro, edit files, whatever you like.)> @Begin @tabclear@tabDivide(3) A>@u@\! Run Kermit-80 some more. Kermit-80>@ux[send file.pas]@\! Send another file. Kermit-80>@ux[bye]@\! That's all. Shut down the Kermit server. A>@\! Back at CP/M automatically. @End This is @i simpler. Note that once you've cranked up the Kermit Server on the remote end, you can run Kermit as often as you like on the micro without having to go back and forth any more; just make sure to shut the server down when you're done. Here are the commands available for talking to servers. The underlined ones are standard. @begin @Index[SEND] @ux@\Sends a file or file group from the local host to the remote host in the normal way. @Index[RECEIVE] @ux@\Ask the remote host to send a file or file group. Example: @example[receive *.c] This command is exactly equivalent to typing "@w[send *.c]" at the remote host followed by "receive" on the local host. Note that the local Kermit does not attempt parse the filespec. If the server cannot parse it, or cannot access the specified file(s), it will send back an appropriate error message. @index @u@\Shut down the remote server and exit from Kermit. This will cause the job at the remote end to log itself out. You need not connect back and clean up unless you get an error message in response to this command (for instance, if your logged-@|out disk quota is exceeded on the remote host). @index LOGOUT@\Shut down the server but don't exit from Kermit. @index FINISH@\Shut down the server without having it log itself out, and don't exit from Kermit. A subsequent CONNECT command will put you back at your job on the remote host, at system command level. @end If you want to run the server with non-default options selected (like IBM-FLAG, FILE-BYTE-SIZE, etc), then you can issue the appropriate SET options before giving the SERVER command. @Section @Index[Error Recovery] There are various ways in which Kermit can become stuck, but since many hosts are capable of generating timeout interrupts when some process doesn't complete quickly enough, they can usually resend or @Index[NAK] "NAK" (negatively acknowledge) lost packets. Nevertheless, if a transfer seems to be stuck, you can type RETURN on the keyboard of most micros to wake up Kermit and have it retransmit the last packet. An interesting exception is the IBM host (VM/CMS) Kermit -- it cannot time out its "virtual console" (i.e.@ the user's terminal), so when using Kermit from a micro to an IBM host, occasional manual wakeups may be necessary. Here are a few symptoms and what to do about them. @subsection The following sections discuss various reasons why a transfer in progress could become stuck. Before examining these, first make sure that you really have a Kermit on the other end of the line, and you have issued the appropriate command: SEND, RECEIVE, or SERVER. If the remote side is not a server, remember that you must connect back between each transfer and issue a new SEND or RECEIVE command. @subsection The micro itself sometimes becomes hung for reasons beyond Kermit's control, such as power fluctuations. If the micro's screen has not been updated for a long time, then the micro may be hung. Try these steps (in the following order): @begin Check the connection. Make sure no connectors have wiggled loose from their sockets. If you're using a modem, make sure you still have a carrier signal. Reestablish your connection if you have to. Press RETURN to wake the micro up. This should clear up any protocol @Index[Deadlock] deadlock. If the problem was not a deadlock, restart the micro and then restart Kermit, CONNECT back to the host, get back to your job or login again, and restart the transfer. You may have to stop and restart Kermit on the remote host. @end @subsection If your local system is working but the transfer is hung, maybe the remote host @Index[Crash] crashed. "Escape" back to local Kermit command level and issue the CONNECT command so that you can see what happened. If the remote system has crashed then you will have to wait for it to come back, and restart whatever file that was being transfered at the time. @subsection @Index[Diskette] If your floppy disk or directory fills up, the Kermit on the machine where this occurs will inform you and then terminate the transfer. You can continue the transfer by repeating the whole procedure either with a fresh floppy or after cleaning up your directory. If you were sending a file group from the DEC-20 you can continue the sequence where it left off by using the @Index[SEND] SEND command and including the name of the file that failed in the "(INITIAL)"@index field, for example @example[Kermit-20>@ux{send *.for} (initial) @ux{foo.for}] See the Kermit-20 command summary for further information about the initial filespec. @SubSection Various error conditions can occur on the remote host that could effect file transmission. Whenever any such error occurs, the remote Kermit normally attempts to send an informative error message to the local one, and then breaks transmission, putting you back at Kermit command level on the local system. @SubSection There are certain conditions under which Kermit can believe it transferred a file correctly when in fact, it did not. One way this can happen is if errors occured during transmission that did not effect the byte count or checksum. For instance, if in a single packet one character bit @i was received as a zero when it should have been a one, and in another character, bit @i became a one when it should have been a zero, then the checksum would be the same as if no error had occured. The only remedies here are to edit the file after it is sent to fix the bad characters, or send the file again. A more likely cause of garbage files has to do with the tricky business of the @i@index. Most computers store files as sequences of 8-bit bytes, but there are some exceptions, like the DEC-10 and DEC-20, which store files in various ways -- text (printable) files as 7-bit bytes, binary files in 36-bit @i. To complicate matters further, different systems handle telecommunication differently: most systems transmit ASCII (a 7-bit code) in 8-bit bytes, but some allow the application (user program) to use the 8th bit for data -- thus allowing the transmission of binary files in 8-bit bytes -- while others insist upon using the 8th bit as a @i@index@foot{The parity bit is set to one or zero based upon whether sum of the other 7 bits is odd or even. Parity can be EVEN, ODD, MARK (always one), SPACE (always zero), or NONE (don't alter the 8th bit).}. These complications only come into play when attempting to transfer @i files; when transferring ordinary text files, there's never a problem about byte sizes. The following descriptions of the particular Kermit implementations tell what mechanisms are available for dealing with bytes size problems. @Chapter @label<-implementations> Kermit has been written for a wide variety of systems, both mainframes and microcomputers. Kermit is not written in a portable language; rather, each implemenation is written in the language best suited for the particular machine. The specification, given in the @i(Kermit Protocol Manual), is quite general and allows implementation on almost any machine. Here's a brief table summarizing the known Kermits, listing some of the features in which they might differ: the host processor, implementation language, and so forth. Notation for Service and Capabilities is explained below. @begin Operating Source @u@ux@u< Service Capabilities> DECSYSTEM-20 TOPS-20 MACRO-20 Columbia R L U S T F I W D E DECsystem-10 TOPS-10 MACRO-10 Stevens R L T F D E IBM 370 series VM/CMS 370 ASM Columbia R F W E (various) UNIX C Columbia R L T W D VAX-11 VMS Bliss-32 Stevens R S T F W D E PDP-11 RT-11 OMSI Pascal Toronto/CU R L W D E @i<8086/8088 implementations:> IBM PC PC DOS 8086 ASM Columbia L U F I W D E Heath/Zenith 100 MS DOS 8086 ASM CU/Stevens L U F I W D E @i<8080/8085/Z80 implementations:> DEC VT180 Robin CP/M 8080 ASM CU/DEC L U F I W E DEC Rainbow 100 CP/M-86/80 8080 ASM CU/DEC L U F I W E DEC DECmate II CP/M 8080 ASM CU/DEC L U F I W E Heath/Zenith 89 CP/M 8080 ASM CU/DEC L U F I W E Heath/Zenith 100 CP/M-85 8080 ASM CU/Stevens L U F I W E Apple II/Z80 CP/M 8080 ASM CU/DEC L U F I W E TRS-80 II CP/M 8080 ASM CU/Cerritos L U F I W E Osborne 1 CP/M 8080 ASM CU/NIH L U F I W E Superbrain CP/M 8080 ASM Columbia L U F I W E Vector Graphics CP/M 8080 ASM Columbia L U F I W E Telcon Zorba CP/M 8080 ASM CU/Stevens L U F I W E Ohio Scientific CP/M 8080 ASM Columbia L U F I W E "Generic" CP/M 8080 ASM CU/DEC L U F I W E @i<6502 implementations:> Apple II Apple DOS CROSS Stevens L F E @end (CU means Columbia University; CU/DEC implementations are modifications to the basic CU 8080 implementations done by DEC personnel mostly on their own time; Stevens is the Stevens Institute of Technology in Hoboken NJ.) Under "Service", R means it can act as a Remote Kermit (the object of a connection), L means it can act as a Local Kermit (initiate a connection to a Remote Kermit via a CONNECT command); U means it can can be the User of a remote Kermit server; S means it can act as a Server. Under "Capabilities", "T" means it can time out, "F" means it can take some kind of evasive action to avoid Filename conflicts, "I" means it can communicate with an IBM mainframe (which requires special half duplex line handshaking, local echoing, and parity control), "W" means it can do "wildcard" sends, "D" means it has a Debug mode that can display the packet traffic on the screen, and "E" means it can exchange Error messages with another Kermit. @section @index Most implementations (the UNIX version is the major exception) attempt to imitate the command parsing style of the DEC-20, which is roughly as follows: In response to the "@q(Kermit-)@i@q(>)" prompt you may type a keyword, such as SEND, RECEIVE, or EXIT, possibly followed by additional keywords or operands, each of which is called a @i. You can abbreviate keywords to any length that makes them distinguishable from any other keyword valid for that field. You can terminate a field with ESC and receive a special short prompt, called a @i, in parentheses, telling you what the next field should be. You can type a question mark at any time to get information about what's expected or valid at that point. The ESC and "?" features work best on full duplex systems (all but the IBM mainframe, so far), where the program can "wake up" immediately and perform the required function. On half duplex or record-@|oriented systems, the ESC feature is not available, and the "?" requires a carriage return to follow. In this example, the user types "set" and then a question mark to find out what the SET options are. The user then continues the command at the point where the question mark was typed, adding a "d" and another question mark to see what set options start with "d". The user then adds a "u" to select "duplex" (the only SET option that starts with "du") followed by an ESC (shown here by a dollar sign) to complete the current field and issue the guide word "(to)" for the next one, then another question mark to see what the possibilities are, and so forth. The command is finally terminated by a carriage return. Before carriage return is typed, however, the command can be edited using RUBOUT or other command editing keys. Finally, the same command is entered again with a minimum of keystrokes, with each field abbreviated to its shortest unique length. In the example, the parts the user types are underlined; all the rest is system typeout: @begin Kermit-20>@ux one of the following: debugging delay duplex escape file-byte-size IBM-flag line parity receive send Kermit-20>set @u one of the following: debugging delay duplex Kermit-20>set d@uplex (to) @u one of the following: full half Kermit-20>set duplex (to) @ualf Kermit-20>@ux @end This style is fully realized in TOPS-10, TOPS-20, CP/M, Apple DOS, and PC/MS DOS implementations of Kermit, partially realized in the IBM VM/CMS and VAX/VMS versions, and not used at all in the UNIX and RT versions. @section In the command descriptions, the following notation is used: @begin @\A parameter - the symbol in angle brackets is replaced by an argument of the appropriate type (number, filename, etc). @q<[>anything@q<]>@\An optional field. If omitted, it defaults to an appropriate value. @\An octal number, i.e. a number in base 8 containing digits in the range 0-7. @\A decimal, base-10, number. @\A single printable character. @end Commands are shown in upper case, but can be entered in any combination of upper and lower case. In order to keep the size of this chapter managable, sometimes only the differences from the command summary given in Chapter @ref<-commands> are noted. Also some infrequently used commands are omitted; consult the help files on each version for a complete list of commands. @Section @label<-k20> @Index[TOPS-20] @Index[Kermit Commands] @Index[DECSYSTEM-20] Kermit is written for the DEC-20 in assembly language using the MACRO assembler. It takes advantage of DEC-20 command parser, software interrupt system, etc. In general, as much intelligence as possible was put into Kermit-20 to allow smooth communication with even the most minimal Kermit implementations. DEC-20 file specifications are of the form @example(DEVICE:NAME.TYPE.GEN;ATTRIBUTES) where the DIRECTORY, NAME, and TYPE may each be up to 39 characters in length, GEN is a generation (version number), and various attributes are possible (protection code, account, temporary, etc). Generation and attributes are normally omitted. Device and directory, when omitted, default to the user's own disk and directory. Thus @q is normally sufficient to specify a file, and only this information is provided by Kermit for outgoing files. @Index[Word Size]@Index[Byte Size] The DEC-20 has an unusual word size -- 36 bits -- and differs from most other systems by storing text in 7-bit, rather than 8-bit, bytes. The word size is not a multiple of the normal byte size. In fact, the DEC-20 has several ways of storing files, which Kermit-20 must allow for: @begin @index[File Format] Normal text files (such as program source) are stored as strings of 7-bit bytes, 5 per 36-bit word; the remaining bit (bit 35) of each word is 0. @tag<-textfile> @index[Line Sequence Numbers] Files produced by text editors like EDIT, SOS, or Otto may have "line sequence numbers". Such files are distinguished from ordinary text files by having each line start on a word boundary. The first word in a line is the character representation of the 5-character line number, with bit 35 set to 1. The first character in the second word is a tab. The final word in a line is padded with nulls if necessary. There are also special page marks. @tag<-lsafile> @index[Binary Files]@index[.REL Files]@index[.EXE Files] Sequential binary files consist of 36-bit words in which all bits are used. Common examples are @q<.EXE> (executable) and @q<.REL> (relocatable) files. @tag<-binfile> @index[Eight Bit Files]@index[8-bit] Eight bit files are strings of 8-bit bytes, four per 36-bit word (left justified in 32 bits). This type of file is used most often to store executable files from other machines such as @q<.COM> files@index[.COM Files] for CP/M micros. You must use the SET FILE-BYTE-SIZE EIGHT-BIT (or AUTO) command to send these files, and EIGHT-BIT (only, not AUTO) to receive them. @index[ISAM Files]@index[Holes in Files]@index[RMS Files] Other DEC-20 file organizations can not be fully supported by Kermit-20. These include directory files, files with holes (missing pages), ISAM files, and RMS files. These files require external information (kept in the DEC-20's file descriptor block and/or index table) in order to be reconstructed; when sending files, Kermit transmits only the file name and the contents of the file. External control information is beyond the scope of the KERMIT protocol. Although Kermit-20 might be able to send these files, it cannot completely reconstruct them upon receipt. @tag<-otherfiles> @end @index[Remote]@index[Local] Kermit-20 can be run in two modes, @i and @i. When remote, all file transfer is done over the job's controlling terminal line; what TOPS-20 thinks is your terminal is really another computer running its own copy of Kermit. When local, file transfer is done over an external, assigned TTY line, which is connected in some way (e.g.@ dialout mechanism) to another computer, again running its own copy of Kermit. A local Kermit is in control of the screen, a remote Kermit has no direct access to it. A local Kermit is one that has issued the SET LINE @i command, described below. Some commands make sense only for remote (or local) Kermits, others can be used with either. Kermit-20 will accept a single command on the Exec command line, or you can run it interactively. Here are the Kermit-20 commands; special remote or local commands are appropriately marked: @begin @Index[BYE]BYE@\@i -- Shut down and log out a remote Kermit server, and exit from the local KERMIT. This command has no effect without a prior SET LINE @i command. If the remote Kermit is not a server (but is in receive mode), you'll get a message back like "Illegal packet type". @Index[CONNECT]CONNECT @q<[>@q<]>@\@i -- Act as a terminal to the system connected to the other end of the line specified, or if no line was specified, to the one given in the most recent SET LINE command. Use full duplex echoing, no parity, and CTRL-Y as the escape character by default, or else whatever was specified by appropriate SET commands. Kermit accomplishes the connection by running the TTLINK@index program in a lower fork. If a line is specified, it becomes the default for file transfer and subsequent CONNECTs. The escape character accepts single character arguments, as follows: @begin C@\Close the Connection. S@\Show Status of Connection. P@\Push to a new Exec. @q@\Type a brief help message listing these options. @q<^Y>@\(or whatever the escape character is) -- Send the escape character itself to the remote host. @end TTLINK has additional options which you can select if you run it directly, including the ability to establish a log file to record your remote session, which can provide "unguarded" (no error checking or correction) capturing of files from remote systems that don't have KERMIT. @i -- The DEC-20 is intrinsically incapable of taking in large amounts of data on a serial port; if either the baud rate or the system load average is high, incoming characters can be lost during CONNECT. EXIT@\Exit from KERMIT-20. The program may be CONTINUEd. You may also stop KERMIT-20 in the midst of a transfer or during server operation by typing several CTRL-C's; the program traps them and puts your terminal back to normal before halting (continuation puts it back at "Kermit-20>" command level). @Index[FINISH] FINISH@\@i -- Shut down a remote Kermit server without logging it out, so that you can still CONNECT to the remote job. Leaves you at local "Kermit-20>" prompt level. Has no effect without a prior SET LINE @i command. If the remote Kermit is not a server (but is in receive mode), you'll get a message back like "Illegal packet type". @Index[GET] GET @\@i -- Ask a remote Kermit server to send the specified files. The filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. As files arrive, their names will be displayed on your screen, along with "@q<.>" and "@q<%>" characters to indicate the packet traffic. If the remote KERMIT is not capable of server functions, then you will probably get an error message back from it like "Illegal packet type". In this case, you must connect to the other Kermit, give a SEND command, escape back, and give a RECEIVE command. (Note that most other Kermits use the RECEIVE command for this; Kermit-20 already had a RECEIVE command that was used differently; see below.) HELP []@\Give help. There's a general help text, plus separate help texts for each KERMIT-20 command. @Index[PROMPT]PROMPT@\Issue a prompt, and go into interactive command mode. This is useful only on the Exec command line, when running a version of Kermit-20 whose default mode of operation is as a server; this causes it to start up with the "@q(Kermit-20>)" prompt, allowing you to issue interactive commands. QUIT@\A synonym for EXIT. @Index[RECEIVE]RECEIVE @q<[>@q<]>@\ @begin Receive a file or group of files from other Kermit. If a filespec is given, the first file received will be stored on the DEC-20 under that name; otherwise, the name is taken from the incoming file header packet. Even if the name provided by the other host is not a legal TOPS-20 file name, KERMIT-20 will store it under that name, in which case you can refer to it later only by quoting the illegal characters (spaces, lower case letters, control characters, etc) with @q<^V>. If a file with the same name already exists, KERMIT-20 just creates a new generation. If running as a local Kermit, the names of the incoming files will be displayed on your screen, along with "." and "%" characters to indicate the packet traffic. If running as a remote Kermit, you should escape back to your local Kermit and give the SEND command. This command cannot be used to request files from a remote Kermit server; for that use the GET command. @end @Index[Initial Filespec]@Index[SEND] SEND @q<[>(INITIAL) @q<]>@\ @begin Send file(s) specified by to the other Kermit. If contains wildcard characters (@q<"*"> or @q<"%">), all matching files will be sent in alphabetical order by name, and may be specified as the initial file in the group to send (this allows an interrupted wildcard transfer to be resumed where it left off). This command may be used to send files to any Kermit, server or not. If running as a local Kermit, the name of each file will be displayed on your screen as the transfer begins, a "." will be printed for every 5 data packets sucessfully sent, and a "%" for every retransmission or timeout that occurs. If you see many "%" characters, you are probably suffering from a noisy connection. If running as a remote Kermit, you should escape back to your local Kermit and give the RECEIVE command. If you don't do this fast enough, several "send-init" packets may arrive prematurely; don't worry, KERMIT-20 will keep sending them until it gets a response. @end @Index[SERVER]SERVER@\@i -- Act as a Kermit Server with default options, or with whatever options have been established by previous SET commands. Note that all options (such as FILE-BYTE-SIZE, see below) remain as long as the server is running -- there is no way to change them without shutting down the server and restarting with new options. The server may be shut down from the local Kermit using BYE or FINISH commands, or by connecting back to the DEC-20 and typing several CTRL-C's. A BYE command logs out the server's job from the DEC-20; a FINISH command halts the server without logging it out. @Index[Set]SET @\Set the specified parameter to the specified value. Possible settings: @begin @Index[Debugging]DEBUGGING @\@i -- During local operation, Kermit-20 will display the name of each file being sent or received, and an "@q<[OK]>" message as each file is closed successfully. In between, there are several display options: @begin OFF@\No debugging information will be displayed. Rather, filenames and blips are displayed, a "@q<.>" for every 5 packets successfully transfered, a "@q<%>" for every timeout or retransmission. STATES@\Shows the packet number and type or internal state, for each packet. The packet types and states are: @begin S@\Send Initiate R@\Receive Initiate F@\File Header D@\Data Z@\End of File B@\Break Transmission C@\Transfer Complete E@\Error A@\"Abort" Transmission T@\Timeout @end PACKETS@\Display the actual incoming and outgoing packets on the screen. For a description of the packet format, see the @i. @end Debugging is OFF by default. The default for this command, however, is STATES. @Index[Delay]DELAY @\@i -- Specify the delay, in seconds, before sending the first @q packet. This gives you time to "escape" back to your local Kermit and issue a RECEIVE command. Normal delay is 5 seconds. @Index[Duplex]DUPLEX FULL (or HALF)@\@i -- Specify echoing during CONNECT to a remote host: FULL means the remote host echoes, HALF means the local KERMIT will do the echoing. FULL by default. HALF generally required with IBM hosts. @Index[Escape]ESCAPE @\@i -- Specify the control character you must type back to the local KERMIT when CONNECTed to a remote system. 31 (CTRL-Y) by default. The number is the octal value of the ASCII control character, 1 (CTRL-A) to 37 (CTRL-Underscore). @Index[IBM-flag]IBM-FLAG ON (or OFF)@\@i -- Allow the transfer of files to and from an IBM host. This causes the DEC-20 to wait for the IBM turnaround character (XOFF, CTRL-Q) before sending any characters out on the line, to send the required parity, and to strip away parity on incoming characters. When CONNECTing to the IBM host, local (half duplex) echoing will be done. @Index[FILE-BYTE-SIZE]@index[Eight Bit Files]@index[8-bit] @Index[Byte Size]@index[Seven Bit Files]@index[7-bit]@index[AUTO Byte Size] FILE-BYTE-SIZE@\Arguments are EIGHT-BIT, SEVEN-BIT, or AUTO. Establishes the DEC-20 byte size for incoming or outgoing files. You can tell the bytesize of a DEC-20 file by doing a VDIR of that file, e.g. @begin @@vdir foo PS: FOO.COM.1;P770000 1 492(8) 27-Jan-83 MAC.1;P770000 1 152(7) 27-Jan-83 .REL.1;P770000 1 39(36) 27-Jan-83 .EXE.1;P770000 2 1024(36) 27-Jan-83 Total of 5 pages in 4 files @end The bytesize is shown in parentheses, and the number directly preceding the parens shows how many bytes of that size are in the file. The number preceding that shows how many 512-@|word @i@index are in the file (a page is the smallest unit of disk storage on the DEC-20). @begin EIGHT-BIT@\Always do 8-bit i/o to the DEC-20 file. Incoming files will be stored in your DEC-20 directory with a bytesize of 8, and outgoing files will be sent in 8-bit mode: four 8-bit bytes from each 36 bit word, with the trailing four bits ignored. You should use this for binary files that originate on a non-@|DEC-10 or -20 remote host, or 8-bit files that are built on the DEC-20 (or -10) using cross compilers or loaders for downloading to 8-bit-@|byte systems. SEVEN-BIT@\When sending, each 36-bit word from the DEC-20 file is divided up into five 7-bit bytes, starting from the "left" (bit 0). Transmission is done in 8-bit bytes; the first four bytes have the 8th bit (otherwise used for parity) set to 0. The fifth byte has bit 8 set to the value of bit 35 of the DEC-20's word. This allows file types @ref<-textfile>, @ref<-lsafile>, and @ref<-binfile> above to be sent to a foreign host and reconstructed correctly upon receipt. Naturally, binary files will have little meaning on the foreign host. When receiving, Kermit reads bytes from the communication line 5 at a time, ignoring the 8th bit on the first 4, and setting bit 35 of the current word on disk from the 8th bit of the 5th byte. 7-bit is the default mode for receiving. AUTO@\When sending, take note of the bytesize with which the file is stored in the DEC-20 directory. If the byte size is 8, then use 8-bit i/o. If it is anything else, use 7-bit i/o as described above. This lets mixed groups of files be sent correctly, provided they are stored correctly on the DEC-20. When receiving, AUTO mode is the same as SEVEN-BIT mode. AUTO is the default mode. @end @Index[Line]LINE []@\@i -- Use the specified TTY line for subsequent CONNECT or file transfer, rather than the controlling terminal. Only useful if you can assign another TTY line on the DEC-20, and if that line is connected (directly, via an autodialer, or some other way) to a TTY port on another computer. Use whatever parity, duplex, and escape character were specified in the most recent SET commands, NONE, HALF, and CTRL-Y by default, respectively. Note that you don't have to change your own terminal speed to match the other line's. SET LINE @i puts Kermit-20 in "local" mode. To get back to (the default) "remote" mode, simply type SET LINE. @Index[Parity]PARITY @\Allows you to adjust the parity on characters sent by KERMIT-20 to another system's requirements. The possibilities are NONE, EVEN, ODD, SPACE, or MARK. If NONE, then the 8th bit can be used for data when sending and receiving binary files. If other than NONE, the 8th bit on outgoing characters will be set to achieve the desired parity, and the 8th bit on incoming characters will be discarded. Normally NONE. Should only be set to one of the others if the remote host won't work without parity. The specified parity is used for both terminal connection and file transfer. @Index[RECEIVE] RECEIVE @\These commands allow you to specify to the other Kermit what the packets it sends should look like, or to inform this Kermit what to expect. @begin @Index[End-Of-Line (EOL)] END-OF-LINE @\The character the other Kermit should terminate its packets with, CR (ASCII 15) by default. KERMIT-20 does not require any special "line terminator" after a packet. PACKET-LENGTH @\ The longest packet the other Kermit may send. Legal values are 10 to 94; default is 80. @Index PADDING , PADCHAR @\Inter-@|packet padding. The DEC-20 does not need any padding. @Index QUOTE @\The character the other Kermit should use for quoting control characters, normally ASCII 43 ("@q<#>"). There should be no reason to change this. Permissible values are 41 ("@q") to 176 ("@q<~>"), i.e.@ the ASCII characters in the printable range. @Index@Index START-OF-PACKET @\The character the other Kermit will be using to start its packets. Normally ASCII 1 (SOH, CTRL-A). If the other Kermit is incapable of transmitting an ASCII 1, you may use this command to tell Kermit-20 what control character to expect. Permissible values are 1 (CTRL-A) to 37 (CTRL-Underscore). @Index[Timeout] TIMEOUT @\The minimum number of seconds after which the remote Kermit should time out when waiting for a packet. You may adjust this as necessary to accomodate various line speeds, or to compensate for slow systems. Legal values range from 1 to 94 seconds. @end @Index[SEND] SEND @\These commands allow you to specify how outgoing packets should look, in case the other Kermit has nonstandard requirements. @begin @Index[End-Of-Line (EOL)] END-OF-LINE @\ The octal value of the ASCII character to be used as a line terminator for outgoing packets, if one is required by the other system. Carriage return (15) by default. Some systems may prefer LF (linefeed, ASCII 12) or some other control character. PACKET-LENGTH @\ Maximum packet length to send, decimal number, between 10 and 94, 80 by default. PADDING , PADCHAR @\ How much padding to send before a packet, if the other side needs padding, and what character to use for padding. Defaults are no padding, and NUL (ASCII 0) for the padding character. No cases are presently known where this is necessary. QUOTE @\ The printable character to use for quoting of control characters. 43 ("@q<#>") by default. There should be no reason to change this. @Index[Start-Of-Packet] START-OF-PACKET number@\ The control character that marks the beginning of an outgoing packet. Normally SOH (Control-A, ASCII 1). Change this only if the other Kermit can't input a Control-A. The two Kermits @i agree about the start-of-packet character. @Index[Timeout] TIMEOUT @\ The minimum number seconds to wait for a packet before trying again. If receiving a file, this means sending a NAK for the expected packet. If sending a file, this means resending the same packet in hopes of getting the expected ACK. The number specified will be adjusted on a per-@|packet basis by Kermit-20 to compensate for the system load, up to the maximum value of 94 seconds. @end @end @Index{SHOW}SHOW@\Show the settings of parameters that can be affected by the SET command, plus the version number of KERMIT-20 and some other information. @Index[STATUS]STATUS@\Display statistics about the most recent transmission, including the effective baud rate (actual user data bits per nominal line speed). @end Work on Kermit-20 continues at Columbia. Planned future enhancements include: @begin Addition of new server functions: directory, type, delete, etc, plus user commands to invoke them. Host commands -- pass a command string to the TOPS-20 EXEC for execution. Terminal interrupts to stop or report status of a transfer in progress. Error correction technique options beyond current single-@|character checksum: 2-character checksum, 16-bit CRC, etc. 8th-bit quoting, to allow transfer of binary files with systems that can't use the parity bit for data. PUSH command for local operation. TAKE command. Initialization files. @end @Section @label<-k10> @Index[TOPS-10] @Index[Kermit Commands] @Index[DECsystem-10] The DECsystem-10 version of Kermit was adapted by Nick Bush, Bob McQueen, and Antonino Mione at the Stevens Institute of Technology in Hoboken NJ from an earlier DECSYSTEM-20 version. Local-@|mode operation (CONNECT) was added by Vanya Cooper, Pima Community College, Tucson, AZ. In general, the commands and other system dependencies for Kermit-10 are the same as Kermit-20. In particular, the TOPS-10 Galaxy facility (ORNMAC) for simulation of the TOPS-20-@|style command parser (COMND) was used to preserve the same style command interface. Major differences between the versions are that Kermit-10 does not allow wildcarding of the file specification in the SEND command, and there is not yet a TOPS-10 Kermit server, nor can KERMIT-10 issue the special server commands (BYE, FINISH, GET). TOPS-10 file specifications are of the form @example(DEV:NAME.TYP[P,PN]) where NAME is at most 6 characters long, TYP at most 3, and @q<[P,PN]> is a "project,@|programmer" number identifying the directory. DEV and PPN can be omitted when the file is in the user's own directory, and only @q is sent in the file header by KERMIT-10. KERMIT-10 commands are listed here. See the TOPS-20 section, above, for detailed descriptions: @begin CONNECT ( to line ) EXIT (to the monitor) HELP (with subject) QUIT (to the monitor) RECEIVE (file spec) [] SEND (file spec) SET @begin DEBUGGING ON (or OFF) DELAY ESCAPE-CHARACTER FILE-BYTE-SIZE EIGHT-BIT (or SEVEN-BIT) FILE-WARNING ON (or OFF) LINE RECEIVE @begin END-OF-LINE PACKET-LENGTH PAD-LENGTH PADDING-CHARACTER TIME-OUT @end SEND (same options as RECEIVE) @end SHOW (same options as SET, plus SHOW ALL) STATUS @end KERMIT-10 has self-contained code for the CONNECT command; there is no separate TTLINK program. @Section KERMIT-32 for DEC VAX-11 VMS systems was written in Bliss-32 at Stevens Institute of Technology by Bob McQueen. KERMIT-32 can be run from @q. It will prompt for input from @q. The commands and capabilities are approximately equivalent those of KERMIT-10. KERMIT-32 can operate as a remote server, but since the CONNECT command is not yet implemented, there are no local-@|mode options (BYE, SET IBM, etc). Here is a summary: @begin CONNECT@\(Not yet implemented) EXIT, QUIT RECEIVE [file-specification] SET parameter value @begin DEBUGGING ON or OFF@\Display packet traffic and other debugging information; only useful when transferring files over a separate line (see SET LINE). DELAY seconds ESCAPE character@\For CONNECT (not implemented) FILE@q<_>TYPE type @begin ASCII@\For text files BINARY@\For non-text files. Note that RMS-32 files are not transferred correctly because the attributes are lost. @end LINE device-specification@\The terminal line you are using, e.g. @q A separate terminal can be assigned, but as yet there is no CONNECT capability. RECEIVE parameter value@\ @begin PACKETLENGTH value@\Maximum length for incoming packets, 10-96. PADDING value@\Number of padding characters (normally not needed). PADCHAR value@\Character to use for padding if PADDING nonzero, an octal number 0 to 37 or 177. TIMEOUT value@\How many seconds to wait for an incoming message before trying again. ENDOFLINE value@\The character required to terminate incoming messages. Normally no need to change this. QUOTE@\Printable character to be used in incoming messages to quote control characters. @end SEND paramater value@\The parameters and values are the same as for SET RECEIVE. @end SEND file-specification@\Send the file or file group specified. The file specification may contain VMS wildcards. SERVER@\Act as a Kermit Server. Accept all further commands only from the other Kermit. These commands may be RECEIVE, SEND, FINISH, and BYE. SHOW parameter@\Show the value of a parameter that can be set by the SET command. Also, SHOW ALL to show all of them. @end @Section @Index[IBM]@Index[VM/CMS]@Index[Timeout] Written in IBM 370 assembly language to run under VM/CMS on IBM 370-@|series mainframes (System/370, 303x, 43xx, 308x, ...). These are half duplex systems; the communication line must "turn around" before any data can be sent to it. The fact that a packet has been received from the IBM system is no guarantee that it is ready for a reply. Thus any Kermit talking to this system must wait for the line turnaround character (XON) before transmitting the next character. IBM systems talk to their terminals through a communications front end (IBM 3705, 3725, COMTEN 3670, etc). These front ends generally insist on using the 8th bit of each character for parity. This means that binary files (files containing other than ordinary letters, digits, punctuation, carriage returns, tabs, and so forth) can @i be correctly sent or received by these systems with Kermit (protocol version 1). The IBM system under VM/CMS is unable to interrupt a read on its "console". This means that the IBM version of Kermit cannot timeout. The only way to "timeout" CMS Kermit is from the other side -- typing a carriage return to the micro's Kermit causing it to retransmit its last packet, or an automatic timeout as provided by Kermit-20. For this reason, CMS Kermit waits thirty seconds before sending its first packet when sending files from VM/CMS. This gives the user sufficient time to return to the local Kermit and issue the Receive command. Otherwise, a protocol deadlock would arise requiring manual intervention by the user. Also, VM/CMS stores files as records rather byte streams. VM/CMS Kermit has to worry about assembling incoming data packets into records and stripping CRLFs from incoming lines, and also appending CRLFs to -- and stripping trailing blanks from -- outgoing records. The VM/CMS file specification is in the form @example (abbreviated FN FT FM). FM is equivalent to a device specification on DEC or microcomputer systems (@w<@q[FN FT FM]> would translate to @q). FILENAME and FILEMODE are at most 8 characters in length, each, and FILEMODE at most 2. When FILEMODE is omitted from a filespec, the user's own disk is assumed. Kermit-CMS sends only FILEMODE and FILETYPE, and converts the intervening blank to a period for compatibility with most other operating systems. Kermit-CMS Commands: @begin @Index[SEND] SEND FN FT @q<[>FM@q<]>@\Send the specified file(s), using * or % as the wildcard characters (* will match any number of characters while % matches only one). Kermit-CMS assumes the file is located on the A disk, and sets the filemode to A1. If, however, the file is located on a different disk, the filemode must be cited. Also, note that if you use * for the filemode, Kermit-CMS will send only the first file that matches. Examples: @begin The command @q will send CEN SPSS A1. To send the same file located on your B disk, you must specify: @q. @q will send all fortran files on your A disk. @q will send all exec files with a four letter filename beginning with ABC. If you have the file PLOT SAS on your A disk and your B disk, @q will send PLOT SAS A1. @end @Index[RECEIVE] RECEIVE @q<[>FN FT @q<[>FM@q<]>@q<]>@\ Receive the file(s) sent from the other Kermit. If a file specification is not included, Kermit-CMS will use the name(s) provided by the other Kermit. Use the file specification to indicate a different filename or a disk other than the A disk (in this case, the file name and type must also be supplied or @w(@q<= = FM>) can be used.) Examples: @begin To receive files using the filename(s) sent by the micro, use: @q. To save a file under a different name, specify: @q. To save the file under the same name but on the B disk, specify: @q, or @q. @End @Index[SET] SET @\Set the parameter to the specified value. Legal Set commands are: @begin @index[RECFM] RECFM @\Denotes the record format to be used when creating the file. Only fixed and variable length records are allowed, where variable is the default. Indicate the desired record format by either an F or a V. @index[LRECL] LRECL @\Indicates the logical record length. The default is set to 80, and the maximum allowed is 256. @index[Quote] QUOTE @\The quote character you wish to use in place of the default (#). It must be a single, printable character from among the following: 33-62, 96, or 123-126 (decimal). @index[End-Of-Line (EOL)] END @\Indicates the end-of-line character you choose to send. The default is CR (ASCII 13 decimal), but can be set to any two digit number between 00 and 31 (decimal). @index[Packet-Length] PAC @\Allows the user to specify the packet size the micro should use when sending to Kermit-CMS. The range is 26-94 (decimal), where 94 is the default. @end @index[SHOW] SHOW @\Displays the current value of any variable that can be changed via the SET command. STATUS@\Returns the status of the previous execution of Kermit-CMS. Therefore, STATUS will either display the message "Kermit completed successfully", or the last error encountered prior to aborting. CMS@\Issues a CMS command from within Kermit-CMS. CP@\Issues a CP command from within Kermit-CMS. @q@\Lists all legal Kermit-CMS commands. @end This is a list of other salient facts about Kermit-CMS: @begin The commands are supplied with a help option, so a question mark can be typed to get the appropriate format or a list of options. The question mark, however, must be followed by a carriage return; Kermit-CMS will respond and display the prompt again. For instance, @q will list all valid options for the SET command. When receiving files, if the record format is fixed, any record longer than the logical record length will be truncated. If the record format is variable, the record length can be as high as 256. For sending files, the maximum record length is 256. Before connecting to the IBM mainframe from other systems (like the various microcomputer and PC Kermits, DEC-20 Kermit, etc), you should set the IBM flag ON so that echoing, parity, and handshaking can be done the way the IBM system likes. Note that "(" and ")" act as word separators on the input line. Therefore, if you try to set the quote character to "(*" or "*(", for example, only the first character will be used. Since some Kermits do not send an error packet when they "abort", Kermit-CMS does not always know the micro has stopped sending it information. Therefore, when you connect back to the IBM, Kermit-CMS may still be sending packets (they will appear on the screen). The user must hit a carriage return until Kermit-CMS has sent the maximum number of packets allowed and aborts. The error message, however, will not indicate that communication stopped because the micro aborted, but rather that no start of header character was found. The minimum send packet size Kermit-CMS will allow is 26. This is necessary to avoid an error while sending the filename or an error packet. If the micro tries to set the value to be less than 26, Kermit-CMS will immediately abort with an error of "Bad send-packet size." While the IBM's communication front end processor translates all incoming characters from ASCII terminals to EBCDIC, Kermit-CMS translates the data it reads back to ASCII (characters not representable in ASCII are replaced by a null). Not only is it easier to work with ASCII characters, but it makes things more consistent throughout the many versions of Kermit. When the packets are sent to the micro, Kermit-CMS converts all data back to EBCDIC. The ASCII to EBCDIC translation table can be found in the Appendix. If a transfer becomes stuck, you can CONNECT back to the CMS system and type a lot of carriage returns -- each one will cause KERMIT-CMS to retransmit the current packet, until the retransmission limit is reached, and you will be back at "KERMIT-CMS>" command level. Kermit-CMS supplies the micro and the user with numerous error messages. If the execution must be abnormally terminated, an error packet is sent to the micro before Kermit-CMS stops. The same message can be retrieved via the STATUS command when Kermit-CMS returns and displays the prompt. If Kermit-CMS aborted because the maximum amount of retries was exceeded (20 on initialization packets and 5 on others), the error message will display the most recent error (i.e.@ the last NAK Kermit-CMS encountered). If execution stops because the micro gave up, the error message will convey that to the user, but it is the micro's responsibility to pinpoint the error. The messages Kermit-CMS gives are as follows: @begin "Bad send-packet size"@\ Sent when the micro attempts to set its receive buffer size to a value that is less than 26 (the minimum that Kermit-CMS will accept) or larger than 94, the maximum. It will also occur if Kermit-CMS tries to send a packet that is larger than the maximum specified. "Bad message number"@\This and the following messages flag inconsistencies in a Kermit packet. "Illegal packet type" -- This can be caused by sending server commands. "Unrecognized State"@\ "No SOH encountered"@\ "Bad Checksum"@\ "Bad character count"@\ "Micro sent a NAK" "Lost a packet" "Micro aborted"@\The micro abnormally terminated the transfer. "Illegal file name"@\ When receiving the name of the file from the micro, Kermit-CMS expects it to be in the format 'filename.filetype'. If the filename, filetype, or dot is missing, Kermit-CMS will reject (NAK) the packet. Also, if either the filename or filetype exceeds eight characters, it will be truncated. "Invalid lrecl"@\ Kermit-CMS will abort on any file-system error it encounters when reading from the file it is to send. It can only send files with variable or fixed length record formats, therefore, Wylbur Edit or Packed format files will cause an error. "Permanent I/O error"@\ This signifies a permanent I/O error that occured when reading from an existing file. Execution is aborted immediately. "Disk is read-only"@\Attempt to write on a read-@|only disk. "Recfm conflict"@\ If a filename conflict arises, Kermit-CMS will append the received file to the existing one, provided the record formats of the two are the same. Otherwise, this error will cause a halt of the execution. "Disk is full"@\ Refers to any error regarding limitations on a user's storage space. Most likely, it signifies that the receiving disk is full, but the error can also mean that the maximum number of files allowed has been reached, or virtual storage capacity has been exceeded, and so on. "Err allocating space"@\ Kermit-CMS keeps a table of all files it has sent to the micro, allocating extra space if more than ten files are sent at one time. If there is an error obtaining more space, Kermit-CMS will abort with this error. @End @End Work on VM/CMS Kermit continues. Planned future enhancements include: @begin 8-bit quoting, to allow binary files to pass through communication front ends that insist on using the 8th bit for parity. Ability to act as a Kermit Server. Ability to SET LINE, so that Kermit-CMS can be used as a local Kermit, connecting to a remote host over another communication port. @end @Section @label<-kc> A sample, working implementation of the Kermit "kernel" was written in the C language, and widely distributed in the @i. This kernel was intended merely to illustrate the protocol, and did not include a "user interface", nor some of the fancy features like server support, 8-bit quoting, file warning, timeouts, etc. Several sites have added the necessary trappings to make this a production version of Kermit, usually under the UNIX operating system. The COMND style of user/program interaction favored by Kermit (program types prompt, user types command followed by operands, program types another prompt, etc) is contrary to the UNIX style, so UNIX implementations have a style more familiar to UNIX users. C versions of Kermit are running successfully on VAX and PDP-11 UNIX systems, and the SUN Microsystems MC68000-@|based workstation. UNIX filespecs are of the form @example where the tokens delimited by slashes form a @i, and by convention are each limited to 14 characters in length. The final token in a path is the actual file name. By convention, it is of the form @q, but there is nothing special about the dot separating name and type; to UNIX it's just another character, and there may be many dots in a filename. @subsection A version was done at Cornell by Dean Jagels and Alison Brown. It is the most ambitious Kermit implementation for UNIX. Several modifications were made to the protocol; in particular, the Cornell version allows for either a 2-character CRC or the single character checksum used by standard Kermit (the selection is made during the negotiation at initial connection). The programs were rewritten from the ground up, with various sections picked apart to form layers corresponding to the ISO network reference model, a "write-thru" state was added incorporating the CONNECT command into the protocol itself, and terminal interrupts were also added. Wildcard sends are expanded in the UNIX shell, which feeds the resulting filespecs one at a time to Kermit. @subsection The version in use at Columbia was adapted from the Kermit kernel by Chris Maio and Bob Cattani of the Columbia University Computer Science Department for the SUN and VAX under UNIX, and is described below by Chris Maio. It is a version 1 Kermit (no server functions). This version more or less conforms to the Unix command parsing conventions, and has the ability to time out. The new command syntax isn't as user friendly as the that of the other implementations, but it is closer to what most Unix users will expect. Roughly, this is how it works: You can only do one thing with any one invocation of Kermit; either connect, send, or receive. The format is basically like that of the "dump" or "tar" tape utilities, in that the first command line argument is a word made up of letters which specify the desired function and options. This "word" is then followed by the arguments for the options, in the order in which the options appear in the command "word," and then a list of files to be sent, if the send command is being invoked. The commands are: @begin @q@\connect @q@\send @q@\receive @end and the options are: @begin @q@\debug mode (no argument) @q@\image (8-bit) mode; no mapping from LF to CRLF, and all eight bits of each byte are sent or received. if this option is not specified, LF is mapped to CRLF, and only 7 bit bytes are sent or received. @q@\line (the next arg is a tty name, e.g. @q) @q@\baud rate (the next arg is a decimal number, e.g.@ 1200) @q@\escape char (next arg is a decimal number, interpreted as the ascii code for the desired escape character) @end The defaults are no debug mode, no external tty line (i.e. "host" mode -- remote -- operation), the system default baud rate, and @q<^D> as the escape character. For example, assume that a user on a micro running Unix wants to transfer files between her machine and a DEC-20 over a hardwire line, say, @q, at 4800 baud, using @q<^B> (ASCII code 2) as her escape character. Note that the order in which arguments are given must match the order in which corresponding letters appear in the first "word": @begin @tabclear()@tabdivide(2) % @ux Kermit: connected @@ @@; now we're on the -20 @@@u Kermit-20>@ux @hinge @\@i<(user types @q<^B> to get back to Unix)> Kermit: disconnected % % @ux@\@i<(no escape character needed here)> Receiving CONNECT.C Receiving MAIN.C Receiving RECEIVE.C Receiving SEND.C Receiving UTILS.C OK @hinge %@\@i<(now, let's send to the DEC-20)> % @ux Kermit: connected. @hinge @\@i<(now we're on the -20)> Kermit-20>@ux @u<^B>@\@i<(user types @q<^B> again to get back)> Kermit: disconnected. % % @ux Sending learn.pl Sending parse.pl OK % @end While the format shown above might seem verbose, it's easy to set up shell scripts or command macros so that, for a given tty line, all one need type is "connect", "send file1 file2 ..." or "receive." "Host" (remote) mode operation is much simpler. When running Kermit in host mode, nothing about the tty line need be specified, so the format reduces to @example<% kermit r> to receive files sent by the "remote" Kermit, and @example<% kermit s file1 file2 file3 ...> to send files back to your local system. Unfortunately, this command syntax doesn't allow you to own the tty line from the local machine to the "host" continuously, but this shouldn't be a problem for most users. The current version has been used to transfer files between VAXes running Berkeley 4.1bsd Unix, a Sun workstation running Unisoft Unix (basically Unix Version 7 with Berkeley extensions), and a DEC-20, over dialups at 1200 baud, the PACX@foot{The Gandalf PACX is used as a port contention unit at Columbia, supporting line speeds up to 4800 baud.} at 4800 baud, and hardwire lines at 9600 baud, all with no noticable problems. None of the special features of Berkeley Unix are used, so only minimal, straightforward changes should be necessary to get Kermit up and running on other flavors of Unix. Unix Kermit presently does not send or process error-@|message packets. @Section An implementation of Kermit was written in OMSI Pascal by Philip Murton at the University of Toronto for the RT-11 operating system, using the Software Tools techniques (Kernighan & Plauger, Addison-Wesley 1981), with UNIX-@|style commands. The version received at Columbia was incomplete and would not run. Michael Weisberg of the Columbia CS Department modified the Toronto version to run on his RT-11 system at Mt.@ Sinai Hospital. Here are his comments: This is NOT a portable version due to the limited I/O facilities of Pascal no such animal is currently possible. This version should work on all reasonably configured RT11 sytems and has been tested on several different processors. This version is largely based on the work of Philip Murton, University of Toronto Computing Services, Communications and Field Service. The main modifications are that the command structure have been modified to conform more closely to the Kermit standard although not exactly (they are documented by the HELP command) and the system has been made runnable as is under RT11 at the price of adding noportable I/O routines. Finally there is still alot of work that would be nice to do here especially improving the command parser and adding timeout capabilities (i.e. making this Kermit "smart") and adding the server capabilities. My encouragements to all! KERMIT-RT Commands: @begin(verbatim) C [h/f/d/v] Connect [Half/Full duplex, Debug/Verbose modes] (any combination of 3 switches possible.) S {,} Send file{s} R {} Recieve files P Print files recieved on local printer H Help on Commands E Exit Kermit Q Quit @end A file @q may be used change the defaults; here is a sample line which should be the first and only line of the file: @example{~( @@-#} This is just the raw data field from the Kermit SEND-INIT packet. The meaning of each character is as follows: @begin(example) @end(example) All characters are the CHAR function numeric equivalents except the quote char which is itself and the PAD char which is the CTL function equivalent. Hence the above line decodes to: @begin Receive size:@\94 Time out:@\8 seconds Number of PAD chars:@\ 0 PAD character:@\null EOL character:@\Carriage return QUOTE character:@\# @end See the GETPARAM procedure in the RT KERMIT program, or the @i, for further details. @Section<8080/Z80 CP/M KERMIT> @label<-k80> @Index[Kermit Commands] Implementations of Kermit-80 presently exist for the DEC VT180@ (Robin), the DEC Rainbow-100 and DECmate II, the Intertec Superbrain, the Heath/Zenith 89 and Z100, the @w with the Z80 SoftCard, the Osborne 1, the TRS-80 II with CP/M, the Telcon Zorba, and the Vector Graphics CP/M system. There is also a "generic" CP/M version that should run any any 8080-@|compatible CP/M system, but which may provide less performance. @i Since Kermit-80 runs on a standalone micro, it is always in control of the screen -- it is always @i@index. Thus, it always keeps the screen updated with the file name and the packet number, whether sending or receiving. Kermit-80 can't time out, so if the transmission gets stuck (and you can tell that this has happened if the screen fails to change for a while) you can type carriage return to have the micro do what it would have done on a @Index[Timeout] timeout, namely NAK@Index[NAK] the expected packet to cause to foreign host to send it again (or, if the micro is sending, to retransmit the last packet). If the foreign host is capable of timeouts (as the DEC-20 is) this action should not normally be necessary, but micro/@|micro or micro/@|IBM-@|mainframe transfers could require this kind of manual intervention. Most CP/M versions of Kermit only allow files to be received onto the default disk, the disk you are @i to. This means in order to receive files onto your B:@ disk you must give the CP/M command @q and see the @q(B>) prompt before running Kermit-80. CP/M file specifications are of the form @q(DEV:NAME.TYP). DEV is a device, such as disk @q or @q. NAME may be up to 8 characters in length, TYP up to 3. @q is sent in the Kermit file header packet. Kermit-80 Commands: @begin @Index[Virtual Terminal]@Index[Escape Character]@Index[Connect] CONNECT@\Establish a "virtual terminal" connection to any host that may be connected to the serial port, i.e.@ pass all typein to the serial port and display all input from the serial port on the screen. Also, emulate a DEC VT52 to allow cursor control, screen clearing, etc., if VT52-EMULATION is ON (see below), in which case you should also set your terminal type on the remote host to VT52. (Some versions emulate other terminals.) The escape character differs from micro to micro. Here is a list of the present versions and their default escape characters ("@q<^>" indicates that the following character is typed while holding down the CTRL key), and what terminals they emulate: @begin @tabclear@tabDivide(3) @Index[VT18X]@Index[Robin]VT180 (Robin)@\@q<^\> (CTRL-backslash) (VT100) @Index[DECmate II]@Index[DECmate-II]DECmate II@\@q<^\> (CTRL-backslash) (VT100) @Index[Rainbow-100]Rainbow-100@\@q<^\> (CTRL-backslash) (VT100, 1200b or below) @Index[Heath/Zenith H89]Heath/Zenith 89@\@q<^\> (CTRL-backslash) (VT52) @Index[Zenith Z100]Heath/Zenith Z100@\@q<^\> (CTRL-backslash) (VT52) @IndexApple II (with SoftCard)@\@q<^]> (CTRL-rightbracket) (VT52) @Index @IndexOsborne 1@\@q<^\> (CTRL-backslash) (ADM3A) @IndexTRS-80 II@\@q<^_> (CTRL-downarrow) (ADM3A) @Index[SuperBrain]SuperBrain@\@q<^]> (CTRL-rightbracket) (VT52) @Index[Vector Graphics]Vector Graphics@\@q< ~> (tilde) (VT52) @IndexOhio Scientific@\@q<^]> (CTRL-rightbracket) (dumb terminal) @IndexTelcon Zorba@\@q<^]> (CTRL-rightbracket) (VT52) @Index @i@\@q<^\> (CTRL-backslash) (dumb terminal) @End The available arguments to the escape character are: @begin B@\Send a BREAK signal. No Kermit-80 currently implements this function. C@\Close Connection, return to @q(Kermit-80>) command level. S@\Display Status of connection, but maintain remote connection. @q@\List available arguments. @q<^]>@\(or whatever - a second copy of the escape character) Send the escape character itself to the remote host. @end @Index[SEND]SEND @\Send file(s) specified by to the remote Kermit. The may contain CP/M wildcards. @Index[RECEIVE]@Index[File-Warning]RECEIVE@\Receive file(s) from the remote Kermit. Store them under the names provided in the file headers supplied by the remote host. If the names aren't legal, use as many legal characters from the name as possible (see the description of SET FILE-WARNING below). If there's a conflict, and FILE-WARNING is ON, warn the user and try to build a unique name for the file. When Kermit-80 is talking to a Kermit Server on the host, you may include a filespec in order to request the server to send files to you, for example: @q[@w] @Index[LOG]LOG @\ When CONNECTed to a foreign host as a terminal, log the terminal session to the specified diskette file. This functionality depends on the remote host's ability to do @Index[XON/XOFF]XON/XOFF flow control. @Index[BYE]BYE@\When talking to a remote Kermit Server, this command shuts down the server and logs it out, and also exits from Kermit-80 to CP/M command level. @Index[LOGOUT]LOGOUT@\Like BYE, but leaves you at Kermit-80 command level. @Index[FINISH]FINISH@\Like LOGOUT, but shuts down the remote server without logging it out. Leaves you at Kermit-80 command level; subsequent CONNECT commands will put you back at host system command level. @Index[SET]SET @q<[>@q<]>@\Set the specified parameter to the specified value. Possible settings: @begin @Index[File-Warning]FILE-WARNING ON (or OFF)@\Warn user of filename conflicts when receiving files from remote host. This is especially important when the remote host has less restrictive (e.g. longer) filenames than the local micro. ON by default. @Index[VT52]VT52-EMULATION ON (or OFF)@\When connected as a terminal to a foreign host, controls whether the micro emulates a VT52 or runs in "native mode". VT52 emulation is ON by default, except on micros that already have terminal functionality built in, such as the DEC VT180 and Rainbow, that act as @indexVT100-@|series terminals. The Osborne and TRS80 Kermits emulate the ADM3A. @Index[Local-Echo]LOCAL-ECHO ON (or OFF)@\When you CONNECT to a remote host, you must set LOCAL-@|ECHO ON if the host is half duplex, OFF if full duplex. OFF by default. @Index[Escape Character]ESCAPE@\Change the escape character for virtual terminal connections. Kermit-80 will prompt you for the new escape character, which you enter literally. @Index[Baud]BAUD@\@i. Display menu of available baud rates for serial port, allow user to select one of them. For other systems, you must set the port baud rate from CP/M or other setup mechanism before running Kermit-80. @Index[Parity]PARITY@\Sets parity for outgoing characters to one of the following: NONE, SPACE, MARK, EVEN, or ODD. On input, if parity is NONE, then the 8th bit is kept (as data), otherwise it is stripped and ignored. The parity setting applies to both terminal connection and file transfer. @Index[IBM-Flag]IBM ON (or OFF)@\Allow the transfer of files to and from the IBM VM/CMS@index system. This makes Kermit-80 wait for the IBM turnaround character (XON), ignore parity on input, send appropriate parity, and use local echoing during CONNECT. If you don't give this command, IBM mode is OFF. SET IBM, however, is equivalent to SET IBM ON. @Index[CPM-Created-File]CPM-CREATED-FILE ON (or OFF)@\Indicate to Kermit-80 that the file to be sent was created by CP/M (e.g. by ED) rather than transferred to the micro by Kermit from some other kind of system. If you do not set this flag when sending files created under CPM they may wind up with extraneous characters at the end (after a CTRL-Z) on the remote host. @end @end The various versions of KERMIT-80 should be available in the KERMIT area on your host computer for downloading, under names like @q, @q, etc. See the section on installing KERMIT for more information. Work will continue on KERMIT-80. Some areas that need improvement include: @begin A better logging function for capturing remote session transcripts, "unguarded" capturing of remote files. The current facility loses characters at high baud rates. Double buffering, with larger buffers, might do the trick. During terminal emulation, the ability to transmit a BREAK signal to the remote host. Very important for IBM mainframes. 8th-bit quoting for exchanging binary files with systems that can't control the parity bit. More commands for servers -- remote directory, type, delete, etc. Initialization files. Printer control. Isolation of system-dependent sections of code to allow new implementations to be added more easily, without even recompiling the system-@|independent part. @end @section @index@index<8080> "Generic Kermit-80" is a implementation of Kermit that should run on any 8080-@|compatible CP/M system no modification at all, or perhaps only a minor one. Unlike other Kermit-80 implementations, it contains no system-@|dependent manipulation of the serial port or keyboard. All I/O is done with standard CP/M BIOS@index calls, and I/O redirection is done using the CP/M IOBYTE function, which, according to the Digital Research @i, is an optional feature of any particular CP/M implementation. If your system does not provide the IOBYTE function, Generic Kermit-80 will not work; furthermore, not all systems that implement IOBYTE do so in the same way. The reason all Kermit-80 implementations aren't generic is that a good deal of speed is sacrificed by getting all services from the operating system. While a specific implementation of Kermit-80 may be able to operate at 4800, 9600, or even 19200 baud, Generic Kermit will fail to work on some systems at speeds in excess of 1200 baud. Generic Kermit also differs from other Kermit-80 implementations in that it does not do fancy screen control during file transfer; it simply types the file names, packet numbers, and messages in sequence across and down the screen. This works best if you can put your micro or terminal in "autowrap" mode; otherwise the packet numbers will pile up in the rightmost column; the filenames and messages will always appear on a new line, however. Note that VT180, DECmate-II, and Rainbow-100 Kermit are simply adaptations of Generic Kermit that do VT100 (ANSI) screen control during file transfer. To get Generic Kermit on to your system (if you can't get it on a floppy disk), use whatever procedure is available to you on your micro to download the file @q. The DDT program listed later will do the trick on most systems. DEC Rainbow users who also have access to a VT180 Robin can use the Robin's Kermit to get Generic Kermit-80 onto the Robin's floppy, which can then be read directly by the Rainbow. @section<8086/8088 KERMIT> @index<8086/8088>@index@index Kermit-86 is almost identical to Kermit-80 in functionality. If you are new to Kermit, you should go back and read the section on 8080/Z80 CP/M Kermit. This section will concentrate on the differences from the 8080 version. Kermit-86 was written initially to run on the IBM PC, and has also been adapted (by Nick Bush at Stevens Institute of Technology) to run on the Heath/Zenith Z100. The IBM PC version also works on PC-@|compatible systems, like the Compaq portable. When acting as a virtual terminal, Kermit-86 emulates the DEC VT52@foot(Hint: the Delete key is CTRL-Backarrow on the IBM PC.). The Kermit-86 command interpreter is modeled after the DEC-20's, allowing keyword abbreviation (and completion and guide words if you type ESC) and "@q" help at any point in the command. Unlike Kermit-80, Kermit-86 is interrupt driven; an interrupt is generated whenever data comes in to the serial port. Kermit stores the characters in a buffer and attends to them later - this way data is not normally lost if the host is too fast for the PC. @i{Kermit-86 runs on the IBM PC under PC DOS 1.1; it has not yet been thoroughly tested under PC DOS 2.0, nor has it been tested on the IBM XT, nor with any hard disk.} PC-DOS or MS-DOS file specifications are of the form @q(DEV:NAME.TYP). DEV is a device, such as disk @q or @q. NAME may be up to 8 characters in length, TYP up to 3. @q is sent in the Kermit file header packet. Kermit-86 Commands: @begin @Index[Bye]BYE@\When talking to a remote Kermit Server, this command shuts down the server and logs it out, and then exits from Kermit-86 to DOS. @Index[Connect]CONNECT@\Make a terminal connection to a remote system. Type an escape sequence to get back to the PC. The escape character is @q by default (you can SET it to be something else if you like, see below). Arguments to the escape character are: @begin @q< C>@\Close the connection. @q< S>@\Tell status of the connection. @q< ?>@\List these arguments. @q<^]>@\(or whatever the escape character is) -- send the escape character itself to the remote host. @end You can send a BREAK to the host by typing CTRL-BREAK. EXIT@\Exit from Kermit-86 back to PC DOS. @Index[Finish]FINISH@\When talking to a remote Kermit Server, this command shuts down the server but does not log out your job on the remote host. HELP@\Print a message similar to this list. @Index[Logout]LOGOUT@\When talking to a remote Kermit Server, this command shuts down the server and logs it out. This command is similar to BYE, but leaves you at the Kermit-86 command level. @Index[Receive]RECEIVE []@\Get a file or group of files from the other Kermit. Incoming file names that are illegal under DOS are transformed to legal names by deleting illegal or excessive characters, etc. When the remote Kermit is a server, you may include a filespec to request the server to send the file(s). If you include a filespec and the remote Kermit is not a server, you will probably get an error message about an illegal packet type. @Index[Send]SEND @\Send a file or group of files to the remote system. The filespec may contain the wildcard character "@q<*>" to match a whole field (filename or filetype) or the trailing characters of a field, For example, @q<*.FOR>, @q. Alternatively, the wildcard "@q<=>" matches one or zero characters. For example, @q will match the files @q and @q, but not @q. @Index[Set]SET@\Set the value of a parameter or flag. The SET options are as follows: @begin @indexBAUD @\Set terminal communications port speed to 300, 1200, 1800, 2400, 4800 (the default), or 9600 bits per second (baud). DEBUG@\Set debug mode ON or OFF (normally should be OFF). If ON, outgoing packets will also be displayed on your screen. @Index[End-Of-Line (EOL)]END-OF-LINE @\Change the character used at the end of outgoing packets to something other than the default of CR (13). It must be a number between 0 and 31 (decimal value of ASCII character). @Index[Escape]ESCAPE @\Change the escape character that gets Kermit-86's attention when CONNECTed to a remote host. The default is CTRL-@q<]>. @Index[File-Warning]FILE-WARNING@\ON/OFF, default is OFF. If ON, Kermit will warn you when an incoming file has the same name as an existing file, and rename the incoming file so as not to destroy an existing one. @Index[IBM-Flag]IBM@\Allow communication with an IBM VM/CMS system. Sets appropriate parity, local echo for CONNECT; activates half duplex line handshaking. @Index[Local-Echo]LOCAL-ECHO@\ON/OFF, default is OFF. This sets the duplex. It should be ON when CONNECTing to an IBM mainframe and OFF for CONNECTing to most other systems, including the DEC-10, DEC-20, UNIX, etc. @Index[Parity]PARITY@\EVEN, ODD, MARK, SPACE, or NONE. Select parity for outgoing characters, during both CONNECT and file transfer, to match the requirement of the remote host. NONE is the default. If other than NONE, the parity bit is stripped from incoming characters and ignored, and binary files cannot be transferred. VT52-EMULATION@\ON/OFF, default is ON. Sets the local terminal type when CONNECTing to a remote host. Should be ON unless the host supports the IBM PC as a terminal in "native mode". @end STATUS@\Display the values of parameters that can be modified via the SET command. @end Kermit-86 only receives files onto the default disk. Therefore, before running Kermit to get files from a remote host, you must "connect" to the disk you want to put the files on, using the "@q" or "@q" command. You can send files from any disk. Kermit-86 provides complete support for standard ASCII files but does not treat binary files in a general way. Some special cases of eight-bit and binary files are programmed. A special case exists for EasyWriter@index files. EasyWriter stores information in the beginning of the file which is non-standard ASCII. Therefore, to send an EasyWriter file to the DEC-20 or VM/CMS, first use the TRANSFER program provided on the EasyWriter diskette. (Use the mode to translate the file to ASCII). After you send the file to the DEC-20, run EZFIX on the -20. EZFIX prevents extra information used by EasyWriter from becoming incorporated into your text file. Optionally, EZFIX will change a bare linefeed to carriage return-line feed thus making the file a standard ASCII file and suitable for editing in EMACS. If, however, you add the carriage returns and send the file back to the PC, you will find that EasyWriter considers that each line has an end-of-paragraph marker. This cannot be avoided (see page E-7 of the EasyWriter manual). No changes need to made after running the TRANSFER program if sending to VM/CMS. Since the IBM PC has a pictorial representation for every character, a small circle is printed on the screen when the host sends a tab character. To get the tab translated to spaces, tell the DEC-20 "term no tabs." The IBM VM/CMS system does not replace the tab with spaces, and the user will see the circle. Work on Kermit-86 continues. Plans for future releases include: @begin General binary file support (8-bit quoting). Device specification for incoming files. Heath/Zenith-19 terminal emulation. This is a superset of VT52 that allows insert/delete character/line editing functions, which lets the PC take advantage of host video editors (like EMACS) that support these functions. @end Kermit-86 was written at Columbia by Daphne Tzoar, based on Bill Catchings's 8080 implementation. Acknowledgements to Bill Westfield at SRI International for help with the terminal emulation code, and to Dick Gillmann at USC-ISI for moderating the ARPAnet INFO-IBMPC mailing list, where we got a lot of valuable information. @section @index KERMIT-65 (so called because of the Apple @q<][> 6502 processor) was contributed by Antonino N.J.@ Mione of Stevens Institute of Technology in Hoboken, New Jersey. It is modeled after KERMIT-80, and has mostly the same commands and style. It is described here in terms of its differences from KERMIT-80: KERMIT-65 is currently missing some features which exist in KERMIT-80. There are also some restrictions which apply. The differences and restrictions are as follows: @begin Session logging is not included in KERMIT-65 at this time. KERMIT-65 does not have the commands that pass commands to a SERVER mode KERMIT (BYE, etc.). IBM-mode support has not been written. There is no wild-carding of filenames as in KERMIT-80. When transferring files, the file type must be made known to KERMIT-65 by setting the FILE-TYPE parameter to one of the following: @begin TEXT APPLESOFT INTEGER BINARY @end @end There is no timeout support in KERMIT-65 since the standard Apple configuration has no accessible clock. To time out KERMIT-65 and have it resend a packet, hit any printable character on the keyboard except a 'Q'. Typing a 'Q' during a transfer will quit the entire transfer. Seven-bit ASCII file transfer should only be attempted for text files, otherwise data integrity may be sacrificed. Using seven-@|bit transfer on both KERMITs will cause KERMIT-65 to strip off the high order bit when sending and turn on the high order bit when receiving. This will insure that the receiving system gets positive ASCII text as opposed to negative ASCII which is used on the Apple. KERMIT-65 will write negative ASCII characters to disk when receiving in seven-@|bit mode. If you wish to edit BASIC programs on the mainframe system, you should convert them to text files on the Apple before you send them since the BASIC interpreters store keywords as single character tokens. Documentation on how to convert BASIC programs to and from text files can be found in the DOS Manual for the Apple @q<][>. If the receiving system does not handle eight-@|bit ASCII or negative ASCII characters well, KERMIT-65 should have its FILE-@|BYTE-@|SIZE set to SEVEN-@|BIT. It will send positive seven-@|bit ASCII to the receiving KERMIT. When KERMIT-65 is receiving from such a system, this will pick up the seven-@|bit characters and write out negative ASCII on the disk file. @Chapter(Installing KERMIT) A paradox is involved in the installation of KERMIT on a system that never had it before: You need a mechanism to get the Kermit program on to your system, and KERMIT is that mechanism -- so it seems you can't get it unless you already have it. Kermit is normally distributed only to central sites on magnetic tape. These sites can simply read the Kermit programs and documents from the tape onto the system and run them directly. The following sections are aimed at those who want to customize and rebuild one of the Kermit programs, or who need to @Index[Bootstrap]"bootstrap" Kermit on to a microcomputer when no it's not available on any directly readable medium (like a floppy disk). Bootstrapping usually means writing a small program that does some part of what Kermit does, in order to get Kermit itself from a system that has it onto one that does not. The following sections give hints for several implementations. It is assumed that you have access to a system on which there resides a copy of the implementation of KERMIT that interests you. @section Normally, TOPS-20 systems get Kermit on magnetic tape, and store all the Kermit files in the directory @q(PS:). The source for Kermit-20 is the file @q<20KERMIT.MAC>; it depends only upon the standard DEC assembly language programming tools @q, @q, and @q. The latter may be missing from some systems, so it is also provided with the KERMIT distribution as @q<20CMD.MAC>. These tools should reside in @q, @q, or @q. The CONNECT capability of KERMIT-20 is provided by a separate program, TTLINK, which KERMIT-20 runs in a lower fork. The source for TTLINK is also provided. If you need to modify KERMIT-20, copy it to your directory as @q, use an editor to make the desired changes, compile, load, and save it: @begin @@@ux{copy 20kermit.mac (to) kermit.mac} @@@ux(load kermit.mac) MACRO: Kermit LINK: Loading @@@ux(save) KERMIT.EXE.1 Saved @@ @end TTLINK may be built similarly. When building KERMIT-20, you can elect whether it starts by default as a server@index or as an interactive program. In location DFSTRT, put the value SERVER for the former, PROMP for the latter. These values are simply symbolic starting addresses. This should be done with an editor, before assembling, but can also be done to @q with DDT. If KERMIT-20 is built as a server, the only way to run it as an interactive program is with a special command line argument, PROMPT: @begin(example) @@@ux Kermit-20> @end(example) The only site-@|dependent aspect of Kermit-20 is the "IBM-FLAG", used for connecting over an assigned TTY line to a remote IBM mainframe. Setting the IBM flag on selects half duplex terminal emulation, mark parity, and half duplex line handshaking, using CTRL-Q as the turnaround character. If you need to communicate to an IBM system that has different characteristics, you must modify the definitions in the @q source and reassemble it. Read this section further if you have Kermit-20 on line and want to "download" it to another DEC-20 that does not. A procedure is available for propogating Kermit from one DEC-20 to another. The two machines are connected via dialup or other means, and then a "baby Kermit", called PIGGY@index, is "downloaded"@index to the target machine using a program called KERBOO@index. The procedure is as follows: Log in on the target machine and do @example Then escape back to the local DEC-20, run KERBOO, and send @q. PIGGY is a bare bones version of @q, with no command parser and every comment and extraneous character stripped away; when run, PIGGY executes the Kermit RECEIVE command. KERBOO sends a character at a time, waits for it to echo, and then sends the next character, until done@foot{No error checking is done, although a fancier variation could compare the sent and echoed characters and when they don't agree, send a DELETE or BACKSPACE character and resend the original. This sounds simple, but complications arise.}. When KERBOO has finished sending PIGGY, connect back to the remote system, assemble PIGGY (if you get errors, then some characters may have been garbled in transmission -- fix them with an editor), and run it. Escape back to the local system, start the real KERMIT, and send @q. You now have a real KERMIT on both ends, and you can send whatever other files you may desire. By the way, you could use KERBOO in this way to download any text file to any full duplex system. @Section This is the first implementation of the Kermit protocol for the VAX/VMS system. Kermit-32 implements a subset of the functionality required for a full KERMIT. To install Kermit-32 on the VAX/VMS system, the following files should be available: @begin @q @q @q @end Use the @q file to install Kermit-32 on the system. There are two different versions of Kermit-32, a Bliss-32 version and a Macro-32 version generated from Bliss-32. If changes must be made to Kermit, it is preferable to make the changes to the Bliss-32 source file and rebuild the program from it. If you don't have a Bliss-32 compiler, it is possible to make changes to the Macro code and assemble it. If you received KERMIT-32 on a tape that was not written by a VAX, then you will only receive the Bliss and Macro source files, and you will have to either compile the Bliss or assemble the Macro. If you wish to build Kermit you can use the @q command procedure. The following files are required to rebuild Kermit-32; the names are shown as they would appear on the VAX. In the normal Kermit distribution, the "KER" prefix is replaced by "VMS". @begin @q (or @q) @q (or @q) @q (or @q) @q (or @q) @q @q (BLISS-32 version only) @q (BLISS-32 version only) @q @q @end To build Kermit-32 do the following: @example[ $ @@INSTALL Kermit-32 Installation procedure. ] @q<[Q 1]> The command procudure will then ask you if you wish to rebuild Kermit-32 from the source files. If you do answer YES to the question, else answer NO. The default is NO. If you answered NO or take the default the next question that will be asked will be Q3. @example @q<[Q 2]> You will now be asked if you wish to rebuild from the Macro-32 or the Bliss-32 version of Kermit. This question has no default. @example You will then be told that it may take a while to rebuild Kermit-32. @q<[Q 3]> The next question that will be asked is if you want to install Kermit-32 on the system, otherwise the command procedure will exit. @example You will now have on your area a @q and @q. @section Kermit distribution tapes written on the IBM VM/CMS system include the executable Kermit module. The Kermit distribution from both DEC and IBM systems includes the necessary source files for building KERMIT-CMS. These are @w(@q), @w(@q), and @w(@q). To build Kermit on the VM/CMS system, assemble each one, load them together, and then generate the Kermit module: @begin(example) .a kermit .a nextfst .a wild .load kermit nextfst wild .genmod kermit @end(example) You should now have an executable @w. @section<8080/Z80 CP/M> Kermit-80 was written originally for the @Index[Superbrain] Intertec SuperBrain -- painfully -- in lowest-@|common-@|denominator @Index[8080] 8080 code with the standard assembler, ASM (no macros, no advanced instructions), so that it can be assembled on any CP/M-80 system@foot{The 8080 assembler is distributed as a standard part of CP/M-80, whereas the fancier Z80@Index[Z80] assembler is normally a commercial product}. It has since been modified to run on many other systems as well. Kermit-80 should be able to run on any 8080-, 8085- or Z80-@|based microcomputer under @Index[CP/M] CP/M with only minor modifications (see below). Thanks to Bernie Eiben at DEC for the VT180, Rainbow, and Generic code, and for constant support, encouragement, and promulgation of KERMIT. Thanks also to Jim Grossen and John Bray of the University of Tennessee for several important bug fixes, and for adding XON/@|XOFF during CONNECT to allow logging to work to some degree; to Charles Bacon of NIH for the Osborne code, to Bruce Tanner of Cerritos college for the TRS-80 code, to Nick Bush at Stevens for Heath/@|Zenith 100 and Telcon code, to Scott Robinson at DEC for the Apple code, and to anonymous donors at DEC for the Heath 89 code and DECmate II code. All versions of Kermit-80 are assembled from the same source, with system dependencies taken care of by assembly-@|time conditionals. The most important system dependencies are terminal emulation (when CONNECTed to the remote host) and screen handling, which are dependent on the individual micro's escape codes (these features are table driven and easily modified for other CP/M systems), and the lowest level i/o routines for the serial communications port. The latter routines do not call on CP/M 2.x @Index[BIOS] Basic I/O System (BIOS) because: @begin The BIOS routines are slow. BIOS always sets the 8th bit to 0, preventing transfer of binary files. Using BIOS calls, there's no way to poll the serial port; you must hang until input appears. Kermit-80's routines are able to check the port status and go elsewhere if no input is available; this allows for virtual terminal connection, keyboard interruption of stuck transmissions, etc. @end Many CP/M micros don't have hardware clocks and the 8080 interrupt facility is so primitive and system dependent that Kermit-80 does not @Index[Timeout] time out nor are most implementations driven by data-@|available interrupts at the keyboard or serial port. The "ibm-flag" setting is site dependent. As shipped from Columbia, it turns on half duplex line handshaking, using CTRL-Q as the turnaround character, sets LOCAL-ECHO ON, and sets PARITY MARK. If you need to install Kermit on your micro, and you cannot borrow a Kermit floppy but you do have access to a mainframe computer with a copy of the Kermit-80 distribution, you should read this section. @subsection @Index[Bootstrap]@index There are several ways to get Kermit from a host system to your micro. The easiest is to "download" the precompiled "hex" file into your micro's memory and then save it on the disk. The following is a procedure which, though far from foolproof, should allow you to get a version of Kermit to your CP/M based micro. It depends upon the host prompt, or at least the first character of the host prompt, being some character that cannot appear in a hex file (the valid characters for hex files are the digits 0-9, the upper case letters A-F, the colon ``:'', carriage return, and line feed). As soon as any other character is encountered, the transfer will terminate. If your host does not issue a prompt that will accommodate this scheme, you can achieve the same effect by modifing the adding an atsign ``@@'' to the very end of the hex file before sending it from the host. The program below looks for an atsign (the normal DEC-20 prompt). DECSYSTEM-10 users would look for a dot, hex 2E. @Begin Look for the appropriate hex file in the host's KERMIT area. The name will be something like @q, @q, @q, etc. If you don't find it, but you do find a corresponding @q<.ASM> or @q<.M80> file, you'll either have to build a new hex file on the host using a cross assembler (see below for how to do this on a DEC-10 or DEC-20), or else bring the ASM source file to your micro and assemble it there. Connect to your host using a terminal or a terminal emulation facility. Ensure that your host does not have your terminal in "page mode". E.g. on the DEC-20, give the Exec command @q. Tell the host to display the hex file at your terminal. E.g. on the DEC-20, give the Exec command @q, @i<@u(without) a terminating carriage return>. Return to your micro. Connect to a floppy disk with plenty of free space. Make sure your IOBYTE is set so that @q and @q correspond to the I/O port that is connected to the DEC-20 (this would normally be the case unless you have done something special to change things). Run DDT and type in the following (the comments should not be typed in; they are there just to tell you what's happening): @Begin -ikermit.hex ;Setup FCB for file KERMIT.HEX. -a100 ;Begin assembling code at 100. 0100 lxi h,ffe ;Where to put HEX file. 0103 shld 300 ;Save the address. 0106 mvi e,d ;Get a CR. 0108 mvi c,4 ;Output function. 010A call 5 010D mvi c,3 ;Input function. 010F call 5 0112 ani 7f ;Turn off the parity. 0114 cpi 40 ;Our DEC-20 prompt atsign? 0116 jz 124 ;Yes, we have whole file. 0119 lhld 300 ;Get the pointer. 011C mov m,a ;Else, store the char. 011D inx h ;Increment the pointer. 011E shld 300 ;Save the pointer. 011F jmp 10d ;Go around again. 0124 mvi a,1a ;Get a control-Z. 0126 lhld 300 ;Get the pointer. 0129 mov m,a ;Store the char. 012A shld 300 ;Save the pointer. 012D lxi h,1000 ;Pointer to file. 0130 shld 310 ;Save the pointer. 0133 mvi c,16 ;Make file. 0135 lxi d,5c 0138 call 5 013B lhld 310 ;Get the file pointer. 013E xchg ;Put it in DE. 013F mvi c,1a ;Set DMA. 0141 call 5 0144 mvi c,15 ;Write DMA to file. 0146 lxi d,5c 0149 call 5 014C lhld 310 ;Get the file pointer. 014F lxi d,80 ;Get the DMA size. 0152 dad d ;Adjust file pointer. 0153 shld 310 ;Save it. 0156 lda 301 ;Get high order byte. 0159 cmp h ;Have we passed the end? 015A jm 170 ;Yes. 015D jz 163 ;Maybe. 0160 jmp 13b ;No. 0163 lda 300 ;Get low order byte. 0166 cmp l ;Passed the end? 0167 jm 170 ;Yes. 016A jz 170 ;Yes. 016D jmp 13b ;Not quite. 0170 mvi c,10 ;Close file. 0172 lxi d,5c 0175 call 5 0178 ret 0179 -g100,179 ;Execute the program. - ;Reboot @End Now there should be a file @q on your connected disk. Load this using the CP/M command LOAD to produce @q. This should be a runnable version of Kermit. Note that CP/M hex files have checksums on each line. If there were any transmission errors during the downloading process, the CP/M loader will notice a bad checksum and will report an error (something like "Illegal Format"). If you get any errors during loading, either fix the hex file locally with an editor, or repeat the previous step. @End You now should have a running version of Kermit-80. @subsection The source for Kermit-80 should be available on your host computer. It is written using 8080 assembler mnemonics, so it can be assembled on most 8080s and Z80s using the standard 8080 assembler provided with CP/M. If you have @q on your CP/M system, you can assemble it directly on the micro using ASM, setting the desired assembly switches as explained below. If you don't have it, you can attempt to download the source file from the host using the procedure outlined above. A cross assembler @index is provided that runs on the @index@index DEC-10 and DEC-20, called MAC80, contributed by Bruce Tanner at Cerritos College, that may be used for cross assembling KERMIT-80 as shown in this example (for TOPS-20): @begin Copy @q(PS:CPMKERMIT.ASM) (the 8080 assembler source file) to your directory, as @q (TOPS-10 filename rules must be followed). Edit @q to set the conditional assembly switch for your machine. These are right near the top of the file, after the edit history. The switch for your machine should be set to 1 and all the others to 0. The switches currently available are: @begin @Index[Superbrain] BRAIN@\Intertec SuperBrain. @Index[Heath/Zenith H89] HEATH@\Heath/Zenith H89 @Index[Zenith Z100] Z100@\Zenith Z100 running CP/M-85. @Index[Ohio Scientific] OSI@\Ohio Scientific @Index[Robin]@Index[VT18X]@Index[DEC VT18X] ROBIN@\DEC VT18X "Robin" @Index[DECmate-II]DMII@\DECmate II word processor with CP/M @Index[Vector Graphics] VECTOR@\Vector Graphics @Index RAINBO@\DEC Rainbow 100 @IndexGENER@\Any CP/M systems that implements IOBYTE. @Index[Apple II]APPLE@\Apple II, with Z80 SoftCard, D.C.@ Hayes Micromodem II. @indexTRS80@\TRS-80 II, running Lifeboat CP/M 2.25 or later. @indexOSBRN1@\Osborne 1. @indexTELCON@\Telcon Zorba. @end Look in the source file; there may be new ones since this manual was written. @begin @index@index Run MAC80: @begin @@@u *@ux *@ux<^Z> @end The result will be in your directory as @q. @end Use Kermit to transfer @q(KERMIT.HEX) to the micro, or download it using the DDT program shown above. On the micro, load the hex file: @example{A>@ux[load kermit]} @q(KERMIT.COM) will appear on the floppy. The new Kermit should be ready to run. @end @subsection @index@Index If your CP/M system implements i/o redirection via the (optional) IOBYTE mechanism, you can probably run Generic Kermit on it, either without modification, or by a very simple change to the program. The standard CP/M IOBYTE is set up as follows: @begin I/O Byte assignments (four 2-bit fields for 4 devices at location 3) : bits 6+7 LIST field 0 LIST is Teletype device (TTY:) 1 LIST is CRT device (CRT:) 2 LIST is Lineprinter (LPT:) 3 LIST is user defined (UL1:) bits 4+5 PUNCH field 0 PUNCH is Teletype device (TTY:) 1 PUNCH is high speed punch (PUN:) 2 PUNCH is user defined #1 (UP1:) 3 PUNCH is user defined #2 (UP2:) bits 2+3 READER field 0 READER is Teletype device (TTY:) 1 READER is high speed reader (RDR:) 2 READER is user defined #1 (UR1:) 3 READER is user defined #2 (UR2:) bits 0+1 CONSOLE field 0 CONSOLE is console printer (TTY:) 1 CONSOLE is CRT device (CRT:) 2 CONSOLE is in Batch-mode (BAT:); READER = Input, LIST = Output 3 CONSOLE is user defined (UC1:) @end (Here, bit zero is the least significant, "rightmost", bit). I/O redirection is accomplished by switching the IOBYTE between two values, "batch i/o" and "normal i/o". In normal i/o mode, the keyboard is defined to be the console. In batch i/o mode, the serial port is defined to be the console. This switching is necessary because the console is the only device that can be tested to see if input is available, but KERMIT must shuttle back and forth between the keyboard @i the serial port looking for input. Here are the batch and default i/o mode definitions used in "standard" Generic KERMIT-80: @begin batio EQU 056H ;I/O byte CON=BAT,LIST=CRT,READER=RDR defio EQU 095H ;I/O byte CON=CRT,LIST=LPT,READER=RDR @end Other systems may have other logical devices that point to the serial port, in which case you'll need to redefine these symbols to point to those devices and then reassemble the program (with assembly switch GENER set to TRUE, all others FALSE). @section<8086/8088> @index[IBM PC]@index[8086/8088] Kermit-86 is written in 8086 Macro Assembler (ASM86), and assembled locally on the micro. Versions for the IBM PC (PC DOS) and the Heath/Zenith Z100 (MS DOS) are prepared from common source using conditional assembly switches similar to those in KERMIT-80. The IBM flag has site-@|dependent meaning. As shipped from Columbia, it means local echo during CONNECT, mark parity, and half duplex line handshaking using CTRL-Q as the turnaround character. If you need to install Kermit on your PC, and you do not have a Kermit floppy but you do have access to a mainframe computer with a copy of the IBM PC Kermit distribution, you should read this section. Since the PC assembler is not provided with the minimum system, IBM PC users cannot be expected to have it. Assembler source plus the runnable version (@q<.EXE>) of Kermit are distributed@foot{The PC assembler's object (@q<.OBJ>) files are not printable, like CP/M hex files, so the Kermit-80 bootstrapping technique would not work here.}, along with some special "bootstrap" files, described below. @subsection The @q file is converted by an assembler program on the PC, KFIX@index, which makes all bytes in the file printable by breaking each one up into two 4-bit "nibbles" and adding a constant. The result is a printable file called @q. It is assumed that a copy of @q is available to you on a mainframe computer. To download@index the file to the PC, two cooperating programs are run: a Fortran program, KSEND@index, on the mainframe and a Basic program, KGET@index, on the PC. These programs are very short; they are shown in their entirety below. KSEND reads a line at a time from @q, types the line, and waits for a signal from KGET that it can send more data. KGET reads each line and converts the text back to the format of an executable (@q<.EXE>) file. Here's the procedure: @begin You should have a version of KGET on the PC and KSEND on the mainframe; if you don't have them, copy them (i.e.@ type them in, using an editor@foot{You'll also have to compile and load the KSEND program on the mainframe.}) from the listings below. Log in@tag<-logmain> on the mainframe. This could be tricky if you have no terminal emulation facility on the PC. If you have the IBM asynchronous communication package, you can do this at low speeds (baud rates). If your PC has no terminal emulation facility, you'll have to use a real terminal to log in, and then switch the cable to the PC. Compile @q on your mainframe, if it needs compiling. Define logical unit numbers 5 and 6 to be the controlling terminal, and logical unit number 7 to be @q. On the DEC-20, for example: @begin @@@ux @@@ux @@@ux @end On a @Index[DECsystem-10]DECsystem-10, do something like: @begin .@ux .@ux .@ux .@ux @end On an IBM system under VM/CMS, @begin .@ux .@ux .@ux @end Start KSEND on the mainframe. It will print a message, and then sit and wait for the PC to send back an OK; don't change any connectors until you see the message. Escape back to the PC, or connect the PC to the mainframe. The PC's communication port should be connected with a cable to the modem that's connected to the mainframe (dialup, dedicated, switched, whatever hookup you normally have available for logging in on the mainframe from a terminal). If you were using a different terminal to log in to the mainframe, make sure the PC's communication port is set at the same speed. Enter BASIC and run KGET on the PC. If KGET prints messages about i/o errors, run it again. If it still gets errors, reboot the PC and try again. Once KGET is running, the transmission will begin. KGET will print each 64-character line of nibbles as it arrives from the mainframe. Each line should be the same length -- if you see a ragged edge, you can assume there has been a transmission error, and you should start the process again. When transmission is complete, you'll see the BASIC "Ready" prompt again. Leave BASIC by typing SYSTEM. You should now have @q on your PC. Try to run it. If you see the "@q(Kermit-86>)" prompt, try to CONNECT to the host mainframe and transfer some files. If Kermit doesn't run correctly, there may have been transmission errors, in which case you should start the process again from step @ref<-logmain> above. @end @subsection This is the mainframe side, KSEND, in transportable Fortran (it should run on both DEC and IBM mainframes): @begin C KSEND -- Download a file over the terminal line. No special checking is done, C except to wait for response (any response at all) from other side. C C This Fortran program should be run on the mainframe in conjunction C with the KGET program on the IBM PC to transfer KERMIT.FIX to the PC. C C Daphne Tzoar, CUCCA, Jan 83 INTEGER A(64) WRITE(6,50) 50 FORMAT(' Ready to transfer data......') C - Get terminal handshake 100 READ (5,10,END=35)X 10 FORMAT(A1) C - Get line from file 35 READ (7,20,END=90)A 20 FORMAT(64A1) C - Write to tty WRITE (6,25)A 25 FORMAT(' ',64A1,';') GOTO 100 90 CONTINUE C - Send final handshake WRITE (6,30) 30 FORMAT(' ',65('@@')) STOP END @end The final @q<@@>'s tell KGET that the transmission is done. This works because the technique for forming @q ensures that the file will contain no @q<@@>'s. @subsection This is the PC side, KGET, in PC Basic. Note that the communication port is opened at 4800 baud (you could substitute any other speed). @begin 1 'KGET.BAS 5 'Run this program on the PC in conjunction with a Fortran program on the 6 'mainframe to get Kermit to the PC. Daphne Tzoar, CUCCA, Jan 83 10 OPEN "com1:4800,n,8,1" AS #1 ' Clear the port status. 20 CLOSE #1 30 OPEN "com1:4800,n,8,1,cs,ds,cd" AS #1 ' Open it for real. 40 OPEN "KERMIT.EXE" FOR OUTPUT AS #2 50 OK$ = "ok" 60 PRINT#1,OK$ ' Tell host we're ready for data 70 X$=INPUT$(65,#1) ' Data plus semi-colon 80 VALUE$ = LEFT$(X$,1) ' First char of input 90 VALUE = ASC(VALUE$) 100 IF VALUE = 64 OR VALUE = 192 GOTO 430 ' @@ means we're done 110 IF VALUE >= 160 AND VALUE <= 175 THEN GOTO 140 ' Kill all illegal chars 120 IF VALUE >= 32 AND VALUE <= 47 THEN GOTO 140 130 X$ = MID$(X$,2) : GOTO 80 140 IF VALUE <> 174 GOTO 210 ' Not a dot (for read) - don't worry 150 TWO$ = MID$(X$,2,1) ' Look at char after the dot. 160 TWO = ASC(TWO$) 170 IF TWO >= 160 AND TWO <= 175 THEN GOTO 210 ' It's ok. 180 IF TWO >= 32 AND TWO <= 47 THEN GOTO 210 190 X$ = MID$(X$,3) ' Kill the char 200 GOTO 80 210 SIZ = LEN(X$) ' How much input was actual data 220 READIN = 65 - SIZ 230 XTWO$=INPUT$(READIN,#1) ' Get rest of data 240 X$ = X$ + XTWO$ : X$ = LEFT$(X$,64) 250 PRINT X$ ' Optional - use this line to follow the transmission 260 GOSUB 290 270 PRINT#2,X$; ' Put data to the file. 280 GOTO 60 290 ' Get two chars, subtract space (20 hex) from each, and combine 300 ' to one digit. 310 FOR A = 1 TO 32 320 Y$ = MID$(X$,A,1) 330 Z$ = MID$(X$,A+1,1) 340 YNUM = ASC(Y$) : ZNUM = ASC(Z$) 350 IF YNUM > 127 THEN YNUM = YNUM - 128 ' Turn off hi bit if on 360 IF ZNUM > 127 THEN ZNUM = ZNUM - 128 370 YNUM = YNUM -32 : ZNUM = ZNUM -32 ' Subtract the space 380 XNUM = (16 * YNUM) +ZNUM 390 NEWCHR$ = CHR$(XNUM) 400 X$ = MID$(X$,1,A-1) + NEWCHR$ + MID$(X$,A+2) 410 NEXT A 420 RETURN 430 PRINT " [All done.]" 440 CLOSE #1,#2 ' Clean up. 450 END @end If you already have a working Kermit on your PC and you want to get a new one, you should use Kermit itself to transfer the @q file. Once you have the new @q on your PC disk: @begin Rename @q to something else, so you'll still have it in case something goes wrong. Modify KGET: @begin Remove lines 10 and 20. Change line 30 to @example<30 OPEN "KERMIT.FIX" FOR INPUT AS #1> Remove line 60, since we're not handshaking with a remote host any more. In line 70, change "65" to "64". Remove line 250, since there's no need to monitor a transmission line. Change line 280 from "@q" to "@q". @end Alternatively, you can use your old Kermit to bring KEXE.BAS from the mainframe. Save the modified KGET under a new name, say @q@index, and run it. It will end with some error like "Input past end in 70", which just means it came to the end of file (of course, you could avoid this error by trapping it, but no harm is done in any case). You should now have a new, working version of @q on your PC disk. @end @section @Index@index@index KERMIT-65 is written in a special language processed only by the cross assembler known as CROSS, which is found only on DECsystem-10 and DECSYSTEM-20 mainframes. HEX files for the more common configurations and modems are included in the distribution. The following sections describe how to download a hex file, and how to build a new version of KERMIT-65 from the CROSS source. @subsection The procedure to bootstrap an assembled KERMIT object file to the Apple is as follows: @begin On the Apple, type in the @q program, listed below. It is recommended that you save this program, as it may be needed to bootstrap newer versions of KERMIT or APPHXL in the future. You can leave out the REMarks when you type it in to speed things up. Call and login to the mainframe on which KERMIT-65 resides. Do the following (the part you type is underlined; control characters are denoted by a preceding "@q<^>", e.g. @q<^A> is Control-A): @begin @q{]@u} ! Where @i is between 1 and 7 For Communication card, do the following: @begin Dial number for computer system. Seat phone receiver in modem cradle. @q{]@ux<^A^F>} ! Full duplex, 300 baud @end For the D.C.@ Hayes Micromodem, do the following: @begin @q{]@ux<^A^F>} ! Full duplex, 300 baud @q{MICROMODEM II: BEGIN TER @ux<^A^Q>} @q{MICROMODEM II: DIALING: @i(nnn-nnnn)} ! @i(nnn-nnnn) is phone number of computer system. @end @end In your directory on the mainframe, the following files should be present: @begin @q - Sends the file @q to the micro, a line at a time. @q - A hex loader to be sent to the micro by @q. Once this program is resident on the micro, it will be used to load @q from the mainframe. @q - Make sure this is the correct copy for your micro. Normally, this would be a copy of either @q (for the Apple communications card in slot 2) or @q (for the D.C.@ Hayes Micromodem II in slot 2) from the KERMIT distribution area. @end If your communication card is not in slot 2, do the following: @begin Edit @q. Change the address which is assigned to the symbol SLOT to "$C@i00", where @i is the number (from 1 to 7) of the slot holding the communication interface. Reassemble with CROSS. @end Compile and execute @q. This will be used along with @q on the Apple to load the @q program. Once @q is executing on the mainframe, give control back to the Apple and then run @q on the Apple. For either the Communication Card or the D.C.@ Hayes Micromodem, the procedure is: @begin @q{@ux<^A^X>} ! Give control to Apple's Brain @q{]@ux} @q{]@ux} @q{]@ux} @end Relocate and save @q. Type the following: @begin @q<]@ux(CALL -151)> ! Enter Apple's system monitor @q{*@ux(9000<2000.21FFM)} ! Move APPHXL from $2000 to $9000 @q(*@u<^C>) ! Reenter Apple BASIC @q{]@ux} ! Save APPHXL to disk @end(enumerate) Now start executing APPHXL: @begin @q{]@ux} ! Enter monitor @q{*@ux<9000G>} ! Start APPHXL @q{ENTER FILENAME TO LOAD @ux} ! Tell APPHXL what to load. @end You could also supply any other filename, e.g.@ @q. The APPHXL program simply sends this name to the mainframe in a TYPE command, like "@q". As the mainframe "types" the file, APPHXL will print what it is receiving on the screen as well as loading it into memory. When APPHXL finishes, type the following to the Apple to save KERMIT on disk: @begin ]@ux @end You may set up a turn-key system by having the hello file on the disk load and run KERMIT. Otherwise, to load and run KERMIT, you must type: @begin @q{]@ux} ! Execute KERMIT-65 on the Apple The Apple will display the following: @begin STEVENS - APPLE ][ KERMIT-65 VER. 1.0 KERMIT-65> @end @end You are now ready to transfer files. @end @subsection KERMIT-65 is written in the CROSS language, for the CROSS assembler, which runs only on the DECsystem-10 and DECSYSTEM-20. This assembler is actually a version of MACY11, a cross assembler for the PDP-11, which has been modified to generate code for a variety of micros. The following files should be available: @begin @q@\Initial bootstrap program to load @q. @q@\Program on mainframe to talk to @q. @q@\Source of hex loader program that loads KERMIT-65. @q@\The KERMIT-65 source program. @q@\Assembled version of KERMIT-65 with the defaults: @begin Apple @q<][> computer D.C.@ Hayes Micro-modem Slot 2 as communication port @end @q@\Assembled version of KERMIT-65 with the defaults: @begin Apple @q<][> computer Apple communication card Slot 2 as communication port @end @q@\KERMIT-65 user and system instructions, source for the DEC RUNOFF or DSR text formatter. @q@\KERMIT-65 user and system instructions, suitable for reading or printing. @q@\CROSS Microprocessor Assembler (Source). @q@\CROSS Microprocessor Assembler (Object). @q@\The CROSS Manual. @q@\A brief description of CROSS. @end Two versions of KERMIT-65 are assembled for use. If the configuration of the machine is either of these, nothing need be done. Otherwise, the file @q must be altered and the KERMIT-65 program must be assembled. A listing of the parameter portion of @q for the D.C.@ Hayes Micromodem in slot number 2 may be found below. The feature test FTCOM must be set to the type of computer for which KERMIT-65 is being assembled. The only machine KERMIT-65 is available for currently is the Apple @q<][>. This parameter must be set to FTAPPL. The feature test FTCDEV represents the communication device being used. The currently defined and implemented devices are: @begin @q@\Apple communication card @q@\D.C.@ Hayes Micromodem II @end That parameter should be set to one of the above according to which device is being used. There is a definition for KERSLO which must be set according to the slot in which the board resides. This is the address of the I/O rom for the board and is in the format "@q<$C@i(n)00>" where @i'n' is the slot number. After setting any options neccessary in @q, do the following: @begin @q{.@ux} ! Run the CROSS Microprocessor Assembler @q{*@ux} ! Generate @q<.HEX> file @end This command will produce an ASCII HEX file which can be downline loaded onto the Apple using APPHXL. If a listing is desired, one can be produced by adding "@q<,KERMIT.LST>" after the "@q" in the command line to CROSS. @subsection @begin 10 REM - LOADER FOR HXLOAD 11 OAD = 0 100 N$ = "0123456789ABCDEF" 110 D$ = CHR$ (4) 130 PRINT D$;"IN#2" : REM CHANGE '2' TO SLOT OF COMM. CARD IF NECCESARY 135 PRINT CHR$ (1); CHR$ (6) 136 PRINT D$;"PR#2" : REM CHANGE '2' TO SLOT OF COMM. CARD IF NECCESARY 140 C3 = 0 150 HOME 199 REM - REQUEST NEXT LINE 200 REM - PUT A DOT ON THE SCREEN FOR EACH LINE RECEIVED 201 C3 = C3 + 1: POKE 1024 + C3, ASC (".") 202 L$ = "":Y2% = 1: PRINT 203 GET A$:L$ = L$ + A$:Y2% = Y2% + 1: IF Y2% < 81 THEN 203 205 C1 = 0:C2 = 0:I = 0 208 IF LEFT$ (L$,1) > = "0" AND LEFT$ (L$,1) < = "9" THEN 220 210 L$ = RIGHT$ (L$, LEN (L$) - 1): GOTO 208 220 LL = LEN (L$) 249 REM - FETCH THE DATA BYTE COUNT FOR THIS LINE 250 GOSUB 1000:C1 = C1 + B:CO = B 255 IF CO = 0 THEN 990 259 REM - CONSTRUCT THE LOAD ADDRESS FOR THIS LINE 260 GOSUB 1000:C1 = C1 + B:AD = B: GOSUB 1000:C1 = C1 + B:AD = AD * 256 + B 265 AD = AD - 28672 266 IF AD < OAD THEN 990 267 OAD = AD 270 FOR X = 0 TO CO - 1 275 REM - GO GET A BYTE AND PUT IT IN THE NEXT MEMORY LOCATION 280 GOSUB 1000:C1 = C1 + B 290 POKE AD + X,B 300 NEXT X 310 GOSUB 1000:C2 = B: GOSUB 1000:C2 = C2 * 256 + B 320 IF C1<>C2 THEN POKE 1024+C3,ASC("E") 330 GOTO 201 990 FOR X = 1 TO 1000: NEXT X 995 PRINT D$;"IN#0": PRINT D$;"PR#0": HOME : END 999 REM - GET BYTE 1000 GOSUB 1501:B = N1: GOSUB 1501:B = B * 16 + N1 1010 RETURN 1500 REM - GET NIBBLE 1501 IF LEN (L$) = 0 THEN N1 = 0: RETURN 1510 H$ = LEFT$ (L$,1) 1511 IF LEN (L$) = 1 THEN L$ = "": GOTO 1525 1515 L$ = RIGHT$ (L$, LEN (L$) - 1) 1520 REM - RETURN VALUE OF HEX NIBBLE 1525 FOR X1 = 1 TO 16 1530 IF H$ = MID$ (N$,X1,1) THEN 1610 1540 NEXT X1 1550 REM - DIGIT WAS NOT FOUND, RETURN ZERO 1560 N1 = 0: RETURN 1600 REM 1610 N1 = X1 - 1: RETURN @end @subsection Note, this uses Fortran-77 conventions in the OPEN, READ, and WRITE statement; these can be translated to the older notation easily on systems that do not have Fortran-77. @begin CHARACTER LINE*80,SENTNL*1 OPEN (UNIT=00,FILE='HXLOAD.HEX',MODE='ASCII') 10 READ (UNIT=05,FMT=20) SENTNL 20 FORMAT (A1) READ (UNIT=00,FMT=25,END=999) LINE 25 FORMAT(A80) WRITE (UNIT=05,FMT=30) LINE 30 FORMAT(A80) GO TO 10 999 STOP END @end @subsection @begin .SBTTL Feature test definitions ; Machines ftappl = $01 ; Apple (under DOS 3.3) ; Communication devices ftaser = $01 ; Apple serial communications board fthays = $02 ; D.C. Hayes modem .SBTTL Kermit feature test options ftcom = ftappl ; Assemble for Apple ][ under DOS 3.3 ftcdev = fthays ; Assemble for D.C. Hayes Micromodem .SBTTL Additional definitions kerslo = $c200 ; Slot rom address (default slot is 2) kercsr = kerslo^ ; High order byte address of comm card rom kercsi = *16-$0c00 ; Communication card slot index @end @Include(KER:ASCII.MSS) @case(device,x9700="@COMMENT @SendEnd(#Index `@begin@end') @COMMENT")