@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 @PageHeading
@Modify @Comment(Set desired spacing around various environments) @Modify @Modify @Modify @Modify @Modify @Modify @Comment(Printing Device Dependencies) @Define @Case @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) @Modify @Modify @Begin(TitlePage,Initialize "@BlankSpace(2.5inches)",sink 0) @MajorHeading(KERMIT USER GUIDE) @i Frank da Cruz, editor Columbia University Center for Computing Activities New York, New York 10027 @value Copyright (C) 1981,1982,1983,1984 Trustees of Columbia University in the City of New York @i @case[device, x9700 "@blankpage(1)"]@Comment{Duplex Kludge} @case[device, imprint10 "@blankpage(1)"]@Comment{Duplex Kludge} @end @set(page=1) @PageHeading(Even,Left="Page @ref(page)",Right="@b") @PageHeading(Odd,Left="@b<@Title[Chapter]>",Right="Page @ref(page)") @PrefaceSection Since the 4th Edition of the @i was produced in July 1983, the KERMITs have been flying thicker and faster than anyone could keep up with. Old versions have improved, and implementations for many new systems have appeared. It is no longer practical to even attempt to cover all the implementations in a single manual. Therefore, this manual will try to describe a sort of "ideal" KERMIT program, one which has most of the features specified in the @i. Most real KERMIT programs will fall short of this description in some ways. After the main, system-@|independent part of the manual there are sections for several particular KERMIT programs, emphasizing their differences from the ideal, @i. The system-@|dependent portions of this manual will rapidly become dated; current information about any particular KERMIT program can be found in the accompanying on-line help or documentation files, or built-in internal help text. @Heading The KERMIT file transfer protocol was designed at the Columbia University Center for Computing Activities (CUCCA) in 1981-82 mainly by Bill Catchings and Frank @w. Bill wrote the first two programs, one for the DECSYSTEM-20 and one for a CP/M-80 microcomputer. The initial objective was to allow users of our DEC-20 and IBM timesharing systems to archive their files on microcomputer floppy disks. The design owes much to the ANSI and ISO models, and ideas were borrowed from similar projects at Stanford University and the University of Utah. The protocol was designed to accommodate the "sensitive" communications front end of the full-@|duplex DEC-20 system as well as the peculiarities of half-@|duplex IBM mainframe communications. The protocol was soon implemented successfully on our IBM 4341 systems under VM/CMS by Daphne Tzoar of CUCCA. Meanwhile it was becoming apparent that KERMIT was useful for more than just file archiving; IBM PCs were beginning to appear in the offices and departments, and there arose a general need for file transfer among all our systems. Daphne soon had prepared an IBM PC implementation. After our initial success with KERMIT, we presented it at conferences of user groups like DECUS and SHARE, and we began to get requests for it from other sites. Since we had written down a description of the protocol, some sites wrote their own implementations for new computers, or adapted one of our implementations to run on additional systems, and sent back these new versions to us so that we could share them with others. In this way, KERMIT has grown to support about 50 different systems; it has been sent on magnetic tape from Columbia to hundreds of sites in dozens of countries, and has reached hundreds or thousands more through various user groups and networks. To date, contributions to the KERMIT effort have been made by individuals at the following institutions: Stevens Institute of Technology, Cornell University, Rutgers University, Cerritos College, the University of Toronto, the University of Tennessee at Knoxville, the University of California at Berkeley, the University of Toledo, the University of Texas at Austin, the University of Michigan, Oakland University, the University of Wisconsin, University College Dublin, the University of Washington, ABC-Klubben Stockholm, the Helsinki University of Technology, the US National Institutes of Health, Digital Equipment Corporation, The SOURCE Telecomputing, Hewlett-@|Packard Laboratories, Litton Data Systems, RCA Laboratories, Atari Computer, and others. The list grows constantly. @Heading Although this manual was produced at Columbia University, all attempts have been made to keep it free of site-@|specific information. However, due to the large number of KERMIT implementations, descriptions of each one would make the manual unnecessarily thick. Therefore, the manual is sent from Columbia with specific documentation about a selection of systems. Some of these descriptions may not be of interest at your site, while others that are may be lacking. Each site, upon receiving a KERMIT tape, may decide which versions of KERMIT are important to it, and include the appropriate documentation in this manual. This is most conveniently done if your site has the Scribe text formatting system (from UNILOGIC Ltd in Pittsburgh PA, USA), with which this manual was produced. Scribe runs on a wide variety of systems. There are also Scribe subsets, such as Perfect Writer and Final Word, that run on various microcomputers. The system-specific parts of the KERMIT User Guide are included with "@q<@@INCLUDE>" statements at the end of the Scribe source file for this manual, whose filename is @q. You may add or delete @q<@@INCLUDE> statements to suit your needs, and run the result through the text formatter to produce a customized manual. Not all system-specific documentation is provided in @q<.MSS> (Scribe input) format, since some KERMIT contributors do not have Scribe at their sites. In that case, you will either have to add Scribe formatting commands, or else enclose the whole subfile in @q<@@VERBATIM> brackets. If you do not have SCRIBE, you may still use an editor to delete or add sections to the finished documentation file, though the results will not be as satisfactory -- the table of contents, index, and page numbers will not be automatically adjusted. If you are running a version of KERMIT for which adequate documentation has not been provided (after all, this is a distributed, volunteer effort@q), please feel free to write some, preferably in Scribe input format, and send it back to Columbia so that others may benefit from it. Likewise if you produce a new implementation of KERMIT. @Unnumbered The KERMIT software is free and available to all. Columbia University, however, cannot afford to distribute free software on the scale required for KERMIT. Therefore, to defray our costs for media, printing, postage, materials, labor, and computing resources, we must request a moderate distribution fee 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. Unfortunately, our limited resources to not allow us to provide automatic updates to KERMIT recipients when new implementations, documentation, or bug fixes appear. 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 for a new system. Make checks payable to @i. KERMIT is 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. KERMIT is also available to users of ARPANET, via anonymous FTP from host COLUMBIA-20, in the area @q(PS:). And KERMIT is distributed regularly by various computer user groups such as DECUS and SHARE. Since new KERMIT programs are added -- and old ones improved -- so frequently, sites that use KERMIT heavily are encouraged to contact Columbia two or three times a year for news. @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 are connected in this way, cooperating programs can be run on each to achieve the desired communication by means of a communication @I. Why is a protocol @Index necessary at all? Three major problems occur when you try to connect two computers via TTY line: @begin @i -- @Index It is rarely safe to assume that there will be no electrical interference on a line; any long or switched data communication line will have occasional interference, or noise, which typically results in garbled or extra characters. Noise corrupts data, perhaps in subtle ways that might not be noticed until it's too late. @i -- Data must not come in faster than the receiving machine can handle it. Although line speeds at the two ends of the connection may match, the receiving machine might not be able to process a steady stream of input at that speed. Its central processor may be too slow or too heavily loaded, or its buffers too full or too small. The typical symptom of a synchronization problem is lost data; most operating systems will simply discard incoming data they are not prepared to receive. @i -- A line may stop working for short periods because of a faulty connector, loss of power, or similar reason. On dialup or switched connections, such intermittent failures will cause carrier to drop and the connection to be closed, but for any connection in which the carrier signal is not used, the symptom will be lost data. @End(Enumerate) 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 such a protocol. It is specifically designed for transfer of sequential files over ordinary serial telecommunication 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. Duplicated packets are discarded. 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. @Heading Section @ref<-using>, @i, tells all you need to know to transfer text files in most cases, and shows some specific examples. If you follow the examples in Section @ref<-using> but you can't make a terminal connection or you can't transfer files successfully, consult Section @ref<-wrong>, @i. If you expect to be a heavy user of KERMIT, you should read Section @ref<-commands>, @i, which describes all the features of KERMIT in detail. You may find that familiarity with the material in this section will help you get past difficulties that can crop up when you are making new kinds of connections or transferring unusual kinds of files. You will also find descriptions of some advanced file management features that have been omitted from the earlier sections. Section @ref<-implementations>, @i, briefly lists the systems for which KERMIT is available @i. The subsequent chapters describe selected particular implementations. You should read the appropriate section for each system with which you are using KERMIT; each section describes the file naming conventions and other system features that are important to KERMIT users, and lists the KERMIT commands for that system mainly in terms of their differences from the "ideal" KERMIT described in section @ref<-commands>. @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<"That second piece was junk."> "Well, then here it is again..." Et cetera. You don't see any of this. It's all packed into a 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 -- you can sit back and watch, or go make yourself a sandwich. 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 @Index[Kermit Commands] These are generic descriptions of the most basic Kermit commands. Detailed descriptions will come later. In these descriptions, @i@index refers to the system that you are using directly, @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] SEND @i(filespec)@\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 may not support transfer of file groups; these versions would require a separate SEND command for each file to be transferred. @Index[RECEIVE] RECEIVE@\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. To "escape" from a virtual terminal connection, type Kermit's @Index[Escape Character] @i (e.g.@ @q, control-@|rightbracket), followed by the letter "C" for "Close Connection". @Index[SET] SET@\Establish various nonstandard settings, such as CONNECT escape character, file characteristics, communication line number, parity, or flow control. SHOW@\@Index[SHOW]Display the values of SET options. HELP@\Type a summary of KERMIT commands and what they do. EXIT@\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 can be used in several ways: from a PC that is connected to a larger host computer; from a host computer which is connected to another host; from one PC to another. @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 become a terminal to the DEC-20. In fact, the PC emulates the popular Heath-19 (or VT52) terminal, so it is desirable to tell the DEC-20 that your terminal is one of these. 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 commentary, not system typeout or part of a command.} Kermit V1.20 Kermit-86>@\! This is the Kermit prompt for the PC. Kermit-86>@u[connect]@\! Connect to the DEC-20. [Connecting to host, type control-] to return to PC. Baud rate is 9600, connecting over COM1.] @\! You are now connected to the DEC-20. CU20B@\! The system prints its herald. @@@ux[terminal heath-19]@\! 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. 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 my 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 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. During file transfer, the microcomputer screen looks something like this: @begin IBM PC Kermit-86 V1.20 Number of Packets: 294 Receiving... Number of Retries: 2 File Name: FOO.TXT @end The packet and retry counts are continuously updated, and the word in the upper right tells the status of the transfer -- receiving, sending, complete, interrupted, or failed. When the transfer is complete (most versions of KERMIT sound a beep to wake you up), you must CONNECT back to the DEC-20 host, EXIT from Kermit there, logout, and "escape back" 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-84 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. 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-@|series 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 simplicity), to which you merely supply the phone number. @Begin @tabclear@tabDivide(3) @@@ux[dial 765-4321/baud:1200] 765-4321, baud 1200 [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, usually requires the receive and transmit leads (pins 2 and 3) 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]@\! 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 mypassword]@\! Login to the IBM system. LOGON AT 20:49:21 EST THURSDAY 01/20/84 CUVMB SP/CMS PUT 8210 01/19/84 . .@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]>", a beep is sounded, 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/84 @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@foot{By wiring certain of the pins in the connector together; 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, almost anything you can plug an EIA connector into. In this example, a DEC VT180 "Robin" CP/M microcomputer is connected to a Intertec "SuperBrain" CP/M micro, using a female-@|to-@|male null modem cable. Getting the cable right 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: @begin[example] A>@u(kermit) Intertec SuperBrain Kermit-80 - V3.7 Kermit-80>@u @end[example] Run Kermit on the Robin, and give the SEND command for @q. @begin[example] A>@u(kermit) DEC VT18X Kermit-80 - V3.7 Kermit-80>@ux(send foo.hex) @end[example] Watch the packets fly. When you get the next @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 the bare-@|bones version of the KERMIT protocol. An optional extension to the protocol 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 program. 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 remote host 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 and log out 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. Some servers also provide additional services, such as directory listings, file deletion, or disk usage inquiries. A Kermit server is just a Kermit program running in a special mode. It acts much 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 what to do, normally to send or to receive a file or group of files. After escaping back to the local system, you can give as many SEND and GET 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-80 microcomputer and a DEC-20 is the remote host. @Begin @tabclear@tabDivide(3) A>@u[kermit]@\! Run Kermit on the micro. Kermit V3.7 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[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[get *.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 started 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 by typing the BYE command. Here are basic the commands available for talking to servers. @begin @Index[SEND] SEND @i(filespec)@\Sends a file or file group from the local host to the remote host in the normal way. @Index[GET] GET @i(filespec)@\Ask the remote host to send a file or file group. Example: @example[get *.c] This command is exactly equivalent to typing "@w[send @q<*.c>]" at the remote host followed by "receive" on the local host. Note that the local Kermit does not attempt to validate the filespec. If the server cannot parse it, or cannot access the specified file(s), it will send back an appropriate error message. @index BYE@\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 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 @Chapter @label<-wrong> @Index[Error Recovery] Connecting two computers can be a tricky business, and many things can go wrong. Before you can transfer files at all, you must first establish terminal communication. But successful terminal connection does not necessarily mean that file transfer will also work. And even when file transfer seems to be working, things can happen to ruin it. @Section If you have a version of KERMIT on your microcomputer, but the CONNECT command doesn't seem to work at all, please: @begin Make sure all the required physical connections have been made and have not wiggled loose. If you are using a modem, make sure the carrier light is on. If you have more than one connector on your micro, make sure you are using the right one. Make sure that the port is set to the right communication speed, or @i. Some versions of KERMIT have a built-@| SET BAUD command, others require that you set the baud rate using a system command or setup mode before you start the KERMIT program. Use the SHOW command to find out what the current baud rate is. Make sure that the other communication line parameters, like parity, bits per character, handshake, and flow control are set correctly. @end You must consult the appropriate manuals for the systems and equipment in question. @index If all settings and connections appear to be correct, and communication still does not take place, the fault may be in your modem. Internal modems (i.e. those that plug in to a slot inside the microcomputer chassis) are @i recommended for use with KERMIT. Many microcomputer KERMIT programs are written to control the communication hardware explicitly; internal modems can interfere with that control. @index@index@index KERMIT normally expects to have full control of the communication port. However, it is sometimes the case that some communications equipment controls the line between the two computers on either end. Examples include modems (particularly "smart" modems), port contention or selection units, multiplexers, local networks, and wide-@|area networks. Such equipment can interfere with the KERMIT file transfer protocol in various ways: @Begin(Itemize) @index It can impose @i upon the communication line. This means that the 8th bit of each character is used by the equipment to check for correct transmission. Use of parity will: @Begin(Itemize) Cause packet checksums to appear incorrect to the receiver and foil any attempt at file transfer. In most cases, not even the first packet will get through. @Index Prevent the use of the 8th bit for binary file data. @End(Itemize) If terminal connection works but file transfer does not, parity is the most likely culprit. To overcome this impediment, you should find out what parity is being used, and inform the KERMITs on each side (using the SET PARITY command) so that they can: @Begin(Itemize) Compose and interpret the checksums correctly. Employ a special encoding to allow 8-bit data to pass through the 7-bit communication channel. @End(Itemize) Many packet-switched networks, such as GTE TELENET, require parity to be set.@foot @index Communications equipment can also interpret certain characters in the data stream as commands rather than passing them along to the other side. For instance, you might find your "smart" modem suddenly disconnecting you and placing a call to Tasmania. The only way to work around such problems is to put the device into "transparent" or "binary" mode. Most communication devices have a way to do this; consult the appropriate manual. In some cases, transparent mode will also cancel the parity processing and allow the use of the 8th bit for data. @End(Itemize) @Section There are various ways in which Kermit file transfers can become stuck, but since many hosts are capable of generating timeout interrupts when input doesn't appear 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 simulate a timeout. An interesting exception is the IBM mainframe (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. 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. @Section 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. Several RETURNs might be necessary. 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 @Section If your local system is working but the transfer is hung, maybe the remote host or the remote KERMIT program @Index[Crash] crashed. Get back to command level on the local KERMIT (on microcomputer implementations, you may be able to do this by typing about five RETURNs, or one or more Control-C's). 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 transferred at the time. @Section @Index[Diskette] If your local floppy disk or remote 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. Some KERMIT programs allow you to continue the sequence where it left off, for instance on the DEC-20 by using the @Index[SEND] SEND command and including the name of the file that failed in the "(INITIAL)"@index field: @example[Kermit-20>@ux{send *.for} (initial) @ux{foo.for}] See the Kermit-20 command summary for further information about the initial filespec. @Section You may find that file transfers fail occasionally and upredictably. One explanation could be that terminal messages are being mixed with your file packet data. These could include system broadcast messages (like "System is going down in 30 minutes"), messages from other users ("Hi Fred, what's that KERMIT program you're always running?"), notifications that you have requested ("It's 7:30, go home!" or "You have mail from..."). Most KERMIT programs attempt to disable intrusive messages automatically, but not all can be guaranteed to do so. It may be necessary for you to "turn off" such messages before starting KERMIT. @Section 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. @Section There are certain conditions under which Kermit can believe it transferred a file correctly when in fact, it did not. The most likely cause has to do with the tricky business of @i, such as text vs binary, 7-bit vs 8-bit, blocked vs stream, and so forth. Each system has its own peculiarities, and each KERMIT has special commands to allow you to specify how a file should be sent or stored. However, these difficulties usually crop up only when sending binary files. Textual files should normally present no problem between any two KERMIT programs. @Section When transferring a text file from a microcomputer to a mainframe, sometimes you will find extraneous characters at the end of the file after it arrives on the target system. This is because many microcomputers don't have a consistent way of indicating the end of a file. CP/M is a good example. The minimum unit of storage on a CP/M floppy is a "block" of 128 bytes. Binary files always consist of a whole number of blocks, but a text file can end anywhere within a block. Since CP/M does not record a file's byte count, it uses the convention of marking the end with an imbedded Control-Z character. If your microcomputer version of KERMIT is not looking for this character, it will send the entire last block, which may contain arbitrary junk after the "real" end of the file. To circumvent this problem, most microcomputer KERMITs have commands like SET FILE ASCII or SET FILE TEXT to instruct KERMIT to obey the CTRL-Z convention. Some microcomputer KERMITs operate in "text" mode by default, others in "binary" or "block" mode. @Chapter @label<-commands> An "ideal" KERMIT program will be described here, which has most of the features specified in the @i. No KERMIT program will have all these commands or support all these options. The exact form of some of the commands may differ from version to version. Some KERMIT programs may support system-@|dependent options not described here. The intention of this description is to provide a base from which specific KERMIT programs can be described in terms of their differences from the "ideal." @Section @index[Remote]@index[Local] Some KERMIT programs can be run in two ways, @i and @i. A remote Kermit is usually running on a mainframe, which you have CONNECTed to through a PC or other computer. When KERMIT runs remotely, all file transfer is done over the job's controlling terminal line -- the same line over which you logged in, and to which you would type interactive commands. What the system thinks is your terminal is really another computer, usually a microcomputer, running its own copy of Kermit. When KERMIT is in "local mode", file transfer is done over an external device, such as a microcomputer's serial communication port, or an assigned terminal line on a mainframe. The local Kermit is connected in some way (like a 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. Microcomputer KERMITs usually run in local "mode", whereas mainframe Kermits usually need to be given some special command to run in local mode. Some commands make sense only for remote Kermits, others only for local, still others can be used with either. Local and remote operation of KERMIT is shown schematically here: @Begin(Example,leftmargin +1,group) @i Communication Line (Packets) +-------------------/ /-----------------+ Other terminals | | | | | | | | | | PC | LOCAL Mainframe | | | | REMOTE +----------+----------+ +------------+--+--+--+--------+ | Serial Port | | | | | | | | | | | | | | | +---------------+ | | Your job's | | | Packets: 724 | | | terminal line | | | Retries: 7 | | | | | | File: FOO.BAR | | | | | +---------------+ | | | | Screen | | | | | | | +---------------+-----+ +------------------------------+ | | (Commands) | +------------+---------+ \ Keyboard \ +----------------------+ You @end The KERMIT program on the PC is a @i Kermit. It can control the screen, the keyboard, and the port separately, thus it can update the screen with status information, watch for interrupt signals from the keyboard, and transfer packets on the communications port, all at the same time. The KERMIT program running on the mainframe is a @i Kermit. The user logs in to the mainframe through a terminal port. The host computer cannot tell that the user is really coming in through a microcomputer. The keyboard, screen, and port functions are all combined in user's mainframe terminal line. Therefore a remote Kermit is cut off from your screen and keyboard during file transfer. A KERMIT server is always remote, and must get its commands from a local KERMIT. The following descriptions will indicate when a command must be remote or local. @section @index Most implementations (the UNIX version is the major exception) have an interactive keyword-@|style command interface, modeled after that of the DECSYSTEM-20, which is roughly as follows: In response to the "@q(Kermit-)@i@q(>)" @i 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 (but not file names) to any length that makes them distinguishable from any other keyword valid for that field. 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 handshake IBM 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 @section In the command descriptions, the following notation is used: @begin @i@\A parameter - the symbol in italics is replaced by an argument of the specified type (number, filename, etc). [@i]@\An optional field. If omitted, it defaults to an appropriate value. @i@\A whole number, entered in prevailing notation of the system. @i@\A single character, entered literally, or as a number (perhaps octal or hexadecimal) representing the ASCII value of the character. @i@\A "real" number, possibly containing a decimal point and a fractional part. @i@\A file specification, i.e. the name of a file, possibly including a search path, device or directory name, or other qualifying information, and possibly containing "wildcard" or pattern-@|matching characters to denote a group of files. @q<^X>@\A control character may be written using "uparrow" or "caret" notation, since many systems display control characters this way. Control characters are produced by holding down the key marked CTRL or Control and typing the appropriate character, e.g. X. @end Commands are shown in upper case, but can be entered in any combination of upper and lower case. @newpage() @Section Here is a brief list of KERMIT commands as they are to be found in most KERMIT programs. The following sections will describe these commands in detail. @begin @i@\ SEND, RECEIVE, GET @i@\ CONNECT, SET LINE, SET PARITY, SET DUPLEX, SET HANDSHAKE, SET ESCAPE, @w @i@\SERVER @i@\BYE, FINISH, GET, SEND, REMOTE @i@\ SET BLOCK-CHECK, SET DEBUG, SET DELAY, SET FILE, SET INCOMPLETE, SET PARITY, SET RETRY;@* SET SEND (or RECEIVE) END-OF-LINE, START-OF-PACKET, PACKET-LENGTH, PAUSE, TIMEOUT, PADDING @i@\ DEFINE @i@\ Control-X, Control-Z, Control-C @i@\ HELP, STATISTICS, SHOW @i@\ TAKE @i@\ LOG TRANSACTIONS @i@\ LOG SESSION, TRANSMIT @i@\ EXIT, QUIT @End(Description) If you have a file called @q in your default or home disk, KERMIT will execute an automatic TAKE command on it upon initial startup. @q may contain any KERMIT commands, for instance SET commands, or DEFINEs for SET macros to configure KERMIT to various systems or communications media. @newpage() @Section @Index[Initial Filespec]@Index[SEND] Syntax: Sending a single file: @display(@q) Sending multiple files: @display(@q) The SEND command causes a file or file group to be sent to the other system. There are two forms of the command, depending on whether @i{filespec1} contains "wildcard" characters. Use of wildcard characters is the most common method of indicating a group of files in a single file specification. For instance if @q is a single file, a FORTRAN program named FOO, then @q<*.FOR> might be a group of FORTRAN programs. @subheading<@ @ Sending a File Group> If @i{filespec1} contains wildcard characters then all matching files will be sent, in directory-@|listing order (according to the ASCII collating sequence) by name. If a file can't be opened for read access, it will be skipped. @IndexThe initial file in a wildcard group can be specified with the optional @i{filespec2}. This allows a previously interrupted wildcard transfer to continue from where it left off, or it can be used to skip some files that would be transmitted first. @subheading<@ @ Sending a Single File> If @i{filespec1} does not contain any wildcard characters, then the single file specified by @i{filespec1} will be sent. Optionally, @i{filespec2} may be used to specify the name under which the file will arrive at the target system; @i{filespec2} is not parsed or validated locally in any way. If @i{filespec2} is not specified, the file will be sent with its own name. @Subheading<@ @ SEND Command General Operation> Files will be sent with their filename and filetype (for instance @q, no device or directory field, no generation number or attributes). @Index@Index@Index If communication line parity is being used (see SET PARITY), the sending KERMIT will request that the other KERMIT accept a special kind of prefix notation for binary files. This is an advanced feature, and not all KERMITs have it; if the other KERMIT does not agree to use this feature, binary files cannot be sent correctly. @Index The sending KERMIT will also ask the other KERMIT whether it can handle a special prefix encoding for repeated characters. If it can, then files with long strings of repeated characters will be transmitted very efficiently. Columnar data, highly indented text, and binary files are the major beneficiaries of this technique. @Subheading<@ @ SEND Remote Operation> If you are running KERMIT remotely (for instance, from a microcomputer), you should "escape back" to your local Kermit within a reasonable amount of time and give the RECEIVE command. Don't take more than a minute or two to complete the switch, or KERMIT may "time out" and give up (in that case, you'll have to CONNECT back to the remote system and reissue the SEND command). @Subheading<@ @ SEND Local Operation> If you're running KERMIT locally, for instance on a microcomputer, you should have already run KERMIT on the remote system and issued either a RECEIVE or a SERVER command. Once you give KERMIT the SEND command, the name of each file will be printed on your screen as the transfer begins, and information will be displayed to indicate the packet traffic. When the specified operation is complete, the program will sound a beep, and the status of the operation will be indicated by a message like OK, Complete, Interrupted, or Failed. If you see many packet retry indications, you are probably suffering from a noisy connection. You may be able to cut down on the retransmissions by using SET SEND PACKET-LENGTH to decrease the packet length; this will reduce the probability that a given packet will be corrupted by noise, and reduce the time required to retransmit a corrupted packet. @index@index@Index If you notice a file being sent which you do not really want to send, you may cancel the operation immediately by typing either Control-X or Control-Z. If your are sending a file group, Control-X will cause the current file to be skipped, and KERMIT will go on to the next file, whereas Control-Z will cancel sending the entire group and return you to KERMIT-20 command level. @Section @Index[RECEIVE] Syntax: @q The RECEIVE command tells KERMIT to wait for the arrival a file or file group sent by a SEND command from the other system. If only one file is being received, you may include the optional @i{filespec} as the name to store the incoming file under; otherwise, the name is taken from the incoming file header. If the name in the header is not a legal file name on the local system, KERMIT will attempt to transform it to a legal name. If an incoming file has the same name as an existing file, KERMIT will either overwrite the old file or else try to create a new unique name, depending on the setting of FILE WARNING. @Index@Index@Index If you have SET PARITY, then 8th-bit prefixing will be requested. If the other side cannot do this, binary files cannot be transferred correctly. The sending KERMIT may also request that repeated characters be compressed. If an incoming file does not arrive in its entirety, KERMIT will normally discard it; it will not appear in your directory. You may change this behavior @Index by using the command SET INCOMPLETE KEEP, which will cause as much of the file as arrived to be saved in your directory. @subheading<@ @ RECEIVE Remote Operation> If your are running KERMIT remotely, you should escape back to your local Kermit and give the SEND command. You should do this within about two minutes, or KERMIT may time out and give up; if this happens, you can CONNECT back to the remote system and reissue the RECEIVE command. @subheading<@ @ RECEIVE Local Operation> If you are running KERMIT locally, you should already have issued a SEND command @foot(@i SERVER -- use the GET command to receive files from a KERMIT server.) to the remote KERMIT, and then escaped back to DEC-20 Kermit. As files arrive, their names will be shown on your screen, along with a continuous display the packet traffic. @Index@Index@Index If a file begins to arrives that you don't really want, you can attempt to cancel it by typing Control-X; this sends a cancellation request to the remote Kermit. If the remote Kermit understands this request (not all implementations of Kermit support this feature), it will comply; otherwise it will continue to send. If a file group is being sent, you can request the entire group be cancelled by typing Control-Z. @Section @i -- Syntax: @q The GET command requests a remote KERMIT server to send the file or file group specified by @i. Note the distinction between the RECEIVE and GET commands: RECEIVE puts KERMIT into a passive wait state, whereas GET actively sends a command to a server. The GET command can be used only when KERMIT is local, with a KERMIT server on the other end of the line. This means that you must have CONNECTed to the other system, logged in, run KERMIT there, issued the SERVER command, and escaped back to the local KERMIT. The remote 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 a continuous indication of the packet traffic. As in the RECEIVE command, you may type Control-X to request that the current incoming file be cancelled, Control-Z to request that the entire incoming batch be cancelled. 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. @Section @Index @i -- Syntax: @q The SERVER command instructs KERMIT to cease taking commands from the keyboard and to receive all further instructions in the form of KERMIT packets from another system. A KERMIT server must be remote; that is, you must be logged in to the system through another computer, such as a microcomputer. In addition, your local KERMIT should have commands for communicating with remote servers; these include GET, FINISH, and BYE. After issuing this command, escape back to your local system and issue SEND, GET, BYE, FINISH, or other server-@|oriented commands from there. If your local KERMIT does not have a BYE command, then it does not have the full ability to communicate with a KERMIT server and you should not put the remote KERMIT into SERVER mode. If your local KERMIT does have a BYE command, use it to shut down and log out the KERMIT server when you are done with it. Any nonstandard parameters should be selected with SET commands before putting KERMIT in server mode, in particular the block check type and special file modes. @Section @i -- Syntax: @q When running as a local Kermit talking to a KERMIT server, use the BYE command to shut down and log out the server. This will also close any debugging log files and exit from the local KERMIT. @Section @i -- Syntax: @q When running as a local Kermit talking to a remote KERMIT server use the FINISH command to shut down the server without logging out the remote job, so that you can CONNECT back to it. Also, close any local debugging log file. @Section @i -- Syntax: @q @i When running in local mode, talking to a remote KERMIT server send the specified command to the remote server. If the server does not understand the command (all of these commands are optional features of the KERMIT protocol), it will reply with a message like "Unknown KERMIT server command". If does understand, it will send the results back, and they will be displayed on the screen. The REMOTE commands are: @begin CWD [@i]@\Change Working Directory. If no directory name is provided, the server will change to the default directory. Otherwise, you will be prompted for a password, and the server will attempt to change to the specified directory. If access is not granted, the server will provide a message to that effect. DELETE @i@\Delete the specified file or files. The names of the files that are deleted will appear on your screen. DIRECTORY [@i]@\The names of the files that match the given file specification will be displayed on your screen. If no file specification is given, all files from the current directory will be listed. DISK [@i]@\Provide information about disk usage in the current directory, such as the quota, the current storage, the amount of remaining free space. HELP@\Provide a list of the functions that are available. HOST [@i]@\Pass the given command to the server's host command processor, and display the resulting output on your screen. KERMIT [@i]@\Pass the given command, which is expressed in the server KERMIT's own interactive-@|mode command syntax, to the server for execution. This is useful for changing settings, logging, and other functions. RUN @i [@i]@\ Have the remote KERMIT run the indicated program with the indicated command line; send the results back to your screen. PROGRAM [@i]@\Send the command to the program started by most recent REMOTE RUN program, and display the results on the screen. If no command is given, send newline character. TYPE @i@\Display the contents of the specified file on your screen. @end @Section Syntax: @q Execute the specified command on the local system -- on the system where KERMIT to which your are typing this command is running. These commands provide some local file management capability without having to leave the KERMIT program, which is particularly useful on microcomputers. @begin CWD [@i]@\"Change Working Directory" to the specified directory. DELETE @i@\Delete the specified file or files. DIRECTORY [@i] Provide a directory listing of the specified files. @end Some KERMIT programs may provide commands for these or other functions in the syntax of their own system, when this would cause no confusion. For instance, CP/M KERMIT may use ERA in place of LOCAL DELETE. @Section @i -- Syntax: @q Establish a terminal connection to the system at the other end of the communication line. On a microcomputer, this is normally the serial port. On a mainframe, you will have to specify a terminal line number or other identifier, either in the CONNECT command itself, or in a SET LINE command. Get back to the local KERMIT by typing the escape character followed by a single character "command". Several single-@|character commands are possible: @Begin(Description,leftmargin +6,indent -4, spread 0) @q@\Close the connection and return to the local KERMIT. @q@\Show status of the connection. @q@\Send a BREAK signal. @q<0>@\(zero) Send a NUL (0) character. @q

@\Push to the local system command processor without breaking the connection. @q@\Quit logging session transcript. @q@\Resume logging session transcript. @q@\List all the possible single-@|character arguments. @q<^]> (or whatever you have set the escape character to be)@\Typing the escape character twice sends one copy of it to the connected host. @End(Description) You can use the SET ESCAPE command to define a different escape character, and SET PARITY, SET DUPLEX, SET HANDSHAKE to establish or change those parameters. @Section Syntax: @q Typing HELP alone prints a brief summary of KERMIT and its commands, and possibly instructions for obtaining more detailed help on particular topics. Most KERMIT implementations also allow the use of "?" within a command to produce a short help message. @Section @q Execute KERMIT commands from the specified file. The file may contain contain any valid KERMIT commands, including other TAKE commands. @Section @Index@Index@Index @q Exit from KERMIT. @Index @q is a synonym for EXIT. @Section Syntax: @q Establish or modify various parameters for file transfer or terminal connection. When a file transfer operation begins, the two KERMITs automatically exchange special initialization messages, in which each program provides the other with certain information about itself. This information includes the maximum packet size it wants to receive, the timeout interval it wants the other KERMIT to use, the number and type of padding characters it needs, the end-@|of-@|line character it needs to terminate each packet (if any), the block check type, the desired prefixes for control characters, characters with the "high bit" set, and repeated characters. Each KERMIT program has its own preset "default" values for these parameters, and you normally need not concern yourself with them. You can examine their values with the SHOW command; the SET command is provided to allow you to change them in order to adapt to unusual conditions. The following parameters may be SET: @Begin(Description,spread 0.2) BAUD-RATE@\Set the speed of the current communications port BLOCK-CHECK@\Packet transmission error detection method DEBUGGING@\Mode or log file DELAY@\How long to wait before starting to send DUPLEX@\For terminal connection, full (remote echo) or half (local echo) ESCAPE@\Character for terminal connection FILE@\For setting file parameters like name conversion and byte size FLOW-CONTROL@\Selecting flow control method, like XON/XOFF HANDSHAKE@\For turning around half duplex communication line IBM@\Set things up for communicating with an IBM mainframe INCOMPLETE@\What to do with an incomplete file LINE@\Terminal line to use for terminal connection or file transfer PARITY@\Character parity to use PORT@\For switching communication ports RECEIVE@\Various parameters for receiving files RETRY@\How many times to retry a packet before giving up SEND@\Various parameters for sending files @End(Description) The DEFINE command may be used to compose "macros" by combining SET commands. The SET commands are now described in detail. @Subheading @Index Set or change the baud rate (approximate translation: transmission speed in bits per second) on the currently selected communications device. The way of specifying the baud rate varies from system to system; in most cases, the actual number (such as 1200 or 9600) is typed. Systems that do not provide this command generally expect that the speed of the line has already been set appropriately outside of KERMIT. @Subheading @Index KERMIT normally uses a 1-character block check, or "checksum", on each packet. The sender of the packet computes the block check based on the other characters in the packet, and the receiver recomputes it the same way. If these quantities agree, the packet is accepted and the transmission proceeds. If they disagree, the packet is rejected and transmitted again. However, the block check is not a foolproof method of error detection. The normal single-@|character KERMIT block check is only a 6-bit quantity (the low order 8 bits of the arithmetic sum folded upon itself). With only six bits of accuracy, the chances are one in 2@+<6> -- that is, 1/64 -- that an error can occur which will not be detected in the checksum, assuming that all errors are equally likely. You can decrease the probability that an error can slip through, at the expense of transmission efficiency, by using the SET BLOCK-CHECK command to select more rigorous block check methods. Note that all three methods will detect any single-@|bit error, or any error in an odd number of bits. The options are: @Begin(Description) 1-CHARACTER-CHECKSUM:@\The normal single-character 6-bit checksum. 2-CHARACTER-CHECKSUM:@\A 2-character, 12-bit checksum. Reduces the probability of an error going undetected to 1/4096, but adds an extra character to each packet. 3-CHARACTER-CRC:@\A 3-character, 16-bit Cyclic Redundancy Check, CCITT format. In addition to errors in any odd number of bits, this method detects double bit errors, all error bursts of length 16 or less, and more than 99.99% of all possible longer bursts. Adds two extra characters to each packet. @End(Description) The single character checksum has proven to be quite adequate in practice, much more effective than straightforward analysis would indicate, since all errors are @i equally likely, and a simple checksum is well suited to catching the kinds of errors that are typical of telecommunication lines. The other methods should be requested only when the connection is @i noisy. Note that the 2- and 3-character block checks are not available in all versions of KERMIT; if the other KERMIT is not capable of performing the higher-@|precision block checks, the transfer will automatically use the standard single-@|character method. @Subheading @Index Syntax: @q Record the packet traffic, either on your terminal or in a file. Options are: @Begin(Description) STATES@\Show Kermit state transitions and packet numbers (brief). PACKETS@\Display each incoming and outgoing packet (lengthy). LOG-FILE@\Log the selected information (STATES or PACKETS) to the specified file. If log file not specified, then use the terminal if local. OFF@\Don't display debugging information (this is the default). If debugging was in effect, turn it off and close any log file. @End(Description) @Subheading @Index Syntax: @q Specify how many seconds to wait before sending the first packet after a SEND command. Use when remote and SENDing files back to your local Kermit. This gives you time to "escape" back and issue a RECEIVE command. The normal delay is 5 seconds. In local mode or server mode, KERMIT does not delay before sending the first packet. @Subheading @Index@Index Syntax: @q For use when CONNECTed to a remote system. The keyword choices are FULL and HALF. FULL means the remote system echoes the characters you type, HALF means the local system echoes them. FULL is the default, and is used by most hosts. HALF is necessary when connecting to IBM mainframes. Half duplex is also called "local echo". @Subheading @Index Syntax: @q Specify or change the character you want to use to "escape" from remote connections back to KERMIT. This would normally be a character you don't expect to be using on the remote system, perhaps a control character like @q<^\>, @q<^]>, @q<^^>, or @q<^_>. Most versions of KERMIT use one of these by default. After you type the escape character, you must follow it by a single-character "argument", such as "C" for Close Connection. The arguments are listed above, under the description of the CONNECT command. @Subheading Syntax: @q Establish file-related parameters. Depending on the characteristics of the system, it may be necessary to tell KERMIT how to fetch an outbound file from the disk, or how to store an incoming file. The actual parameters you can specify in this command will vary from system to system, and you should consult the documentation for your particular version of KERMIT. Some examples would be byte size (PDP-10 architecture), record length or block size (record oriented systems), end-@|of-@|file detection method (on microcomputers). This can be a very important command if you intend to transfer binary files, but is normally unecessary for transmitting textual files. @Subheading @Index Syntax: @q For communicating with full duplex systems. System-@|level flow control is not necessary to the KERMIT protocol, but it can help to use it if the same method is available on both systems. The most common type of flow control on full duplex systems is XON/XOFF. @Subheading @Index Syntax: @q For communicating with half duplex systems. This lets you specify the line turnaround character sent by the half duplex host to indicate it has ended its transmission and is granting you permission to transmit. When a handshake is set, KERMIT will not send a packet until the half duplex host has sent the specified character (or a timeout has occurred). The options may include: @Begin(Description,leftmargin +12,indent -8,spread 0) NONE@\No handshake; undo the effect of any previous SET HANDSHAKE. XOFF@\Control-S. XON@\Control-Q. BELL@\Control-G. CR@\Carriage Return, Control-M. LF@\Linefeed, Control-J. ESC@\Escape, Control-[. @End(Description) @Subheading @Index Syntax: @q Specify what to do when a file transfer fails before it is completed. The options are DISCARD (the default) and KEEP. If you choose KEEP, then if a transfer fails to complete successfully, you will be able to keep the incomplete part that was received. @Subheading Syntax: @q Specify the terminal line to use for file transfer or CONNECT. This command is found on mainframe KERMITs, which normally run in "remote mode" using their own controlling terminal for file transfer. Specifying a separate line puts the program in "local mode." If no line is specified, revert to the job's controlling terminal, i.e. go back to "remote mode." @subheading Syntax: @q Specify the communications port for file transfer or CONNECT. This command is found on microcomputer KERMITs that run in "local" mode. SET PORT does not change the remote/@|local status but simply selects a different port for local operation. @Subheading @Index Syntax: @q Parity is a technique used by communications equipment for detecting errors on a per-@|character basis; the "8th bit" of each character acts as a check bit for the other seven bits. KERMIT uses block checks to detect errors on a per-@|packet basis, and it does not use character parity. However, some systems that KERMIT runs on, or equipment through which these systems communicate, may be using character parity. If KERMIT does not know about this, arriving data will have been modified and the block check will appear to be wrong, and packets will be rejected. @Index If parity is being used on the communication line, you must inform both KERMITs, so the desired parity can be added to outgoing characters, and stripped from incoming ones. SET PARITY should be used for communicating with hosts that require character parity (IBM mainframes are typical examples) or through devices or networks (like GTE TELENET) that add parity to characters that pass through them. Both KERMITs should be set to the same parity. The specified parity is used both for terminal connection (CONNECT) and file transfer (SEND, RECEIVE, GET). The choices for SET PARITY are: @begin NONE@\(the default) eight data bits and no parity bit. MARK@\seven data bits with the parity bit set to one. SPACE@\seven data bits with the parity bit set to zero. EVEN@\seven data bits with the parity bit set to make the overall parity even. ODD@\seven data bits with the parity bit set to make the overall parity odd. @end NONE means no parity processing is done, and the 8th bit of each character can be used for data when transmitting binary files. @Index@Index If you have set parity to ODD, EVEN, MARK, or SPACE, then advanced versions of KERMIT will request that binary files will be transferred using 8th-bit-prefixing. If the KERMIT on the other side knows how to do 8th-bit-prefixing (this is an optional feature of the KERMIT protocol, and not all implementations of KERMIT have it), then binary files can be transmitted successfully. If NONE is specified, 8th-bit-@|prefixing will not be requested. @Subheading @q> Parameters for outgoing packets, as follows: @Begin(Description,leftmargin +8,indent -8) @Index END-OF-LINE @i@\The ASCII character to be used as a line terminator for packets, if one is required by the other system, carriage return by default. You will only have to use this command for systems that require a line terminator other than carriage return. @Index PACKET-LENGTH @i{number}@\ Maximum packet length to send between 10 and 94 (decimal). Shortening the packets might allow more of them to get through through without error on noisy communication lines. Lengthening the packets increases the throughput on clean lines. @Index TIMEOUT @i@\ How many seconds to wait for a packet before trying again. @Index PAUSE @i@\ How many seconds to pause before sending each data packet. Setting this to a nonzero value may allow some slow systems enough time to consolidate itself packet before the next packet arrives. Normally, no per-packet pausing is done. @Index PADDING @i, PADCHAR @i@\ 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 (0) for the padding character. QUOTE @i@\ What printable character to use for quoting of control characters, "#" (43) by default. There should be no reason to change this. @Index START-OF-PACKET @i@\ The start-of-packet character is the only control character used "bare" by the KERMIT protocol. It is Control-A by default. If a bare Control-A causes problems for your communication hardware or software, you can use this command to select a different control character to mark the start of a packet. You must also issue the reciprocal command (SET RECEIVE START-OF-PACKET) to the KERMIT on the other system (providing it has such a command). @End(Description) @Subheading Syntax: @q> Parameters to request or expect for incoming packets, as follows: @Begin(Description,leftmargin +8,indent -8) @Index END-OF-LINE @i@\ Carriage return (15) by default. @Index PACKET-LENGTH @i@\ Maximum length packet for the other side to send, decimal number, between 10 and 94, decimal. @Index TIMEOUT @i@\How many seconds the other Kermit should wait for a packet before asking for retransmission. @Index PAUSE @i@\How many seconds to pause before acknowledging a packet. Setting this to a nonzero value will slow down the rate at which data packets arrive, which may be necessary for systems that have "sensitive" front ends and cannot accept input at a high rate. @Index PADDING @i, PADCHAR @i@\How many padding characters to request before each incoming packet, and what the padding character should be. No KERMITs are known to need padding, and if one did, it would request it without your having to tell it to do so. This command would only be necessary, therefore, under very unusual circumstances. QUOTE @i@\What printable character to use for quoting of control characters, "#" (43) by default. There should be no reason to change this. @Index START-OF-PACKET @i@\The control character to mark the beginning of incoming packets. Normally SOH (Control-A, ASCII 1) (see SET SEND START-OF-PACKET, above). @End(Description) @Index @Subheading @q> Set the maximum number of retries allowed for: @Begin(Description,leftmargin +8,indent -8) INITIAL-CONNECTION@\How many times to try connecting before giving up, normally something like 15. PACKETS@\How many times to try sending a particular packet before giving up, normally 5. If a line is very noisy, you might want to increase this number. @End(Description) @Section @Index @q @i [@i] Define a "SET macro" to allow convenient association of one or more SET parameters with a mnemonic keyword of your choice. The SET parameters are a list of one or more SET options, separated by commas. If you use KERMIT to communicate with several different kinds of systems, you may set up a macro for each, for instance: @Begin(Example,leftmargin +1) DEFINE IBM PARITY MARK, DUPLEX HALF, HANDSHAKE XON, SEND PACKET-LENGTH 80 DEFINE UNIX PARITY NONE, DUPLEX FULL, HANDSHAKE NONE @Index DEFINE TELENET PARITY MARK, RECEIVE TIMEOUT 20 @End(Example) You may then type SET IBM, SET UNIX, and so forth to set all the desired parameters with a single command. It is convenient to include these definitions in your @q file. Another other handy use for SET macros would be for rapid adaptation to different conditions of line noise: @Begin(Example,leftmargin +1) DEFINE CLEAN BLOCK-CHECK 1, SEND PACKET-LENGTH 94, RETRY PACKET 5 DEFINE NOISY BLOCK-CHECK 2, SEND PACKET-LENGTH 60, RETRY PACKET 10 DEFINE VERY-NOISY BLOCK 3, SEND PACKET 40, RETRY PACKET 20 @End(Example) You may redefine an existing macro in the same manner as you defined it. You can undefine an existing macro by typing an empty DEFINE command for it, for instance: @Begin(Example,leftmargin +1) DEFINE IBM @End(Example) You can list all your macros and their definitions with the SHOW MACROS command. @Section @Index Syntax: @q [@i