KERMIT USER GUIDE KERMIT USER GUIDE KERMIT USER GUIDE _____ _______ Fifth Edition Frank da Cruz, editor Columbia University Center for Computing Activities New York, New York 10027 2 March 1984 Copyright (C) 1981,1982,1983,1984 Trustees of Columbia University in the City of New York __________ __ _______ __ ___ __________ __ ___________ __ ____ __ Permission is granted to any individual or institution to copy or ___ ____ ________ ___ ___ ________ _________ __ __ ______ ___ use this document and the programs described in it, except for __________ __________ ________ explicitly commercial purposes. Preface to the 5th Edition Preface to the 5th Edition Preface to the 5th Edition Page 1 Preface to the 5th Edition Preface to the 5th Edition Preface to the 5th Edition ______ _____ _____ Since the 4th Edition of the KERMIT Users Guide 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 ap- peared. It is no longer practical to even attempt to cover all the implemen- tations 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 ______ ________ ______ KERMIT Protocol Manual. 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, at the time of this writing. The system-de- pendent 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. A LITTLE HISTORY A LITTLE HISTORY A LITTLE HISTORY The KERMIT file transfer protocol was designed at the Columbia University Cen- ter for Computing Activities (CUCCA) in 1981-82 mainly by Bill Catchings and Frank da Cruz. 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 sys- tems 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 com- munications. 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 depart- ments, 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 im- plementations 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 Univer- sity, Rutgers University, Cerritos College, the University of Toronto, the Preface to the 5th Edition Preface to the 5th Edition Preface to the 5th Edition Page 2 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 Equi- pment Corporation, The SOURCE Telecomputing, Hewlett-Packard Laboratories, Lit- ton Data Systems, RCA Laboratories, Atari Computer, and others. The list grows constantly. CUSTOMIZING THIS MANUAL CUSTOMIZING THIS MANUAL CUSTOMIZING THIS MANUAL 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 descrip- tions may not be of interest at your site, while others that are may be lack- ing. 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 sys- tem (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 microcom- puters. The system-specific parts of the KERMIT User Guide are included with "@INCLUDE" statements at the end of the Scribe source file for this manual, whose filename is USER.MSS. You may add or delete @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 .MSS (Scribe input) for- mat, 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 @VERBATIM brackets. If you do not have SCRIBE, you may still use an editor to delete or add sec- tions 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!), 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 im- plementation of KERMIT. Ordering Information Ordering Information Ordering Information Page 3 ORDERING INFORMATION ORDERING INFORMATION ORDERING INFORMATION 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 distribu- tion fee from sites that request KERMIT directly from Columbia. The schedule is as follows: Complete KERMIT Distribution $100.00 ____ _____ _____ ___ ________ ______ (Tape, Users Guide, and Protocol Manual) Printed Documents $5.00 each _____ _____ ________ ______ __ ___ ______ _______ (Users Guide, Protocol Manual, or Any Source Listing) Other sites are free to redistribute KERMIT on their own terms, and are en- couraged 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 dis- tribution. To order KERMIT from Columbia University, send a letter requesting either: __ (a) The manuals or source listings you desire (specify each one), or (b) A 9-track magnetic tape in one of the following formats: ______ ____ ______ _________ System Tape_Format Densities TOPS-10 BACKUP/Interchange, Unlabeled 800, 1600 TOPS-20 DUMPER, Unlabeled 800, 1600 IBM VM/CMS EBCDIC, CMS Format 1600, 6250 __ or EBCDIC, OS Standard Label 1600, 6250 _____ Other ASCII, ANSI Label, Format ``D'' 800, 1600 (Specify system, format, and density.) One copy of each manual will be included with the tape. We will supply the tape, packaging, and postage. __ ______ _______ ______ We can only make tapes in the formats listed above. We_cannot__produce__floppy _____ disks; bootstrapping procedures are provided to allow the microcomputer ver- sions 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: Ordering Information Ordering Information Ordering Information Page 4 KERMIT Distribution Columbia University Center for Computing Activities 7th Floor, Watson Laboratory 612 West 115th Street New York, N.Y. 10025 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 ________ __________ ______ ___ _________ __________ Columbia University Center for Computing Activities. 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 infor- mation. KERMIT is also available to users of ARPANET, via anonymous FTP from host COLUMBIA-20, in the area 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. __ ________ __ ___ ________ ___ __ ___ ________ __ ___ _____________ ________ No warranty of the software nor of the accuracy of the documentation surround- ___ __ __ _________ __ _______ ___ _______ ___ _______ ___ ________ __________ ing it is expressed or implied, and neither the authors nor Columbia University ___________ ___ _________ _________ ____ _______ __ _____________ ______ acknowledge any liability resulting from program or documentation errors. Introduction Introduction Introduction Page 5 CHAPTER 1 CHAPTER 1 CHAPTER 1 INTRODUCTION INTRODUCTION INTRODUCTION 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 com- puters are connected in this way, cooperating programs can be run on each to ________ achieve the desired communication by means of a communication protocol. Why is a protocol necessary at all? Three major problems occur when you try to connect two computers via TTY line: _____ 1. Noise -- It is rarely safe to assume that there will be no electri- cal 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, per- haps in subtle ways that might not be noticed until it's too late. _______________ 2. Synchronization -- 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 proces- sor 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. ____ _______ 3. Line Outages -- 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. 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". KERMIT is such a protocol. It is specifically designed for transfer of sequen- tial files over ordinary serial telecommunication lines. KERMIT is not neces- sarily 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 "packets" of control information. This information includes a synchronization marker, a packet number to allow detection of lost packets, a length indicator, and a "checksum" to allow verification of the data. Lost or corrupt packets are detected, and Introduction Introduction Introduction Page 6 retransmission is requested. Duplicated packets are discarded. In addition, various special control packets allow cooperating KERMITs to connect and dis- connect 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. ORGANIZATION OF THIS MANUAL ORGANIZATION OF THIS MANUAL ORGANIZATION OF THIS MANUAL ___ __ ___ ______ Section 2, How to Use KERMIT, 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 2 but you can't make a terminal connec- ____ ______ tion or you can't transfer files successfully, consult Section 3, When Things __ _____ Go Wrong. ______ If you expect to be a heavy user of KERMIT, you should read Section 4, KERMIT ________ Commands, 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 dif- ficulties 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 sec- tions. ______ _______________ Section 5, KERMIT Implementations, briefly lists the systems for which KERMIT __ __ ____ _______ is available as of this writing. 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 4. How to Use KERMIT How to Use KERMIT How to Use KERMIT Page 7 CHAPTER 2 CHAPTER 2 CHAPTER 2 HOW TO USE KERMIT HOW TO USE KERMIT HOW TO USE KERMIT KERMIT is a protocol for reliable file transfer between computers over the or- dinary serial telecommunication lines that are used to connect terminals to computers. The mechanics of using KERMIT to get a file transferred can be con- fusing 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. 2.1. The KERMIT Program 2.1. The KERMIT Program 2.1. The KERMIT Program KERMIT embodies a set of rules for transferring files reliably between com- ____ puters. In general, one computer is a large system (a host, for instance a s time1haring system with many terminals), and the other is a personal computer __ (PC) . The host believes that the PC is an ordinary terminal. In order for _______ the KERMIT protocol to occur, a KERMIT program 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 Kermit protocol. 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?" "OK." "Now, here comes a file called FOO.TXT, OK?" __ ___ __ "OK." "Here's the first piece..." "Got it." "Good, here's the second piece..." ____ ______ _____ ___ ____ "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 Ker- mits can understand; they do all the worrying about transmission, error check- ______ ing, character set translation, and so forth. Each message is called a packet, and each packet is in a special format that all Kermits can understand. _______________ 1 Host-to-host and PC-to-PC connections are also possible. How to Use KERMIT How to Use KERMIT How to Use KERMIT Page 8 2.2. Talking to Two Computers at Once 2.2. Talking to Two Computers at Once 2.2. Talking to Two Computers at Once 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 com- puters, two different programs. Let's talk about a common case: you are sit- 2 ting at a personal computer (PC ), which has a serial communication port. The 3 serial port is connected to a host computer using, say, a dialup modem . 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 CONNECT, 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 virtual terminal service -- 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 prompt. 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 "Kermit-xx>". The xx identifies the implementation of Kermit; the Kermit that runs on the DEC-20 is called "Kermit-20" and its prompt is "Kermit-20>"; the Kermit that runs on Z80 and 8080-based microcom- puters is called "Kermit-80" and its prompt is "Kermit-80>"; the Kermit on the 4 IBM PC is "Kermit-86" , 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 [Connecting to remote host, type CTRL-]C to return] when you CONNECT, and type another message like _______________ 2 The terms PC, micro, microcomputer, and workstation will all be used loosely in this document to denote a single-user system. 3 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. 4 Although the processor in the IBM PC is an 8088, it is programmed as though it were an 8086. How to Use KERMIT How to Use KERMIT How to Use KERMIT Page 9 [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 escape sequence. As Kermit passes your charac- ters through to the host, it checks each one to see if it's a special ______ _________ predefined escape character. When the PC sees this character, it stops ignor- ing 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 _______ _________ control character, such as Control-], which is accomplished by holding down the key marked CTRL or CONTROL and typing the indicated character (in this case, a right bracket "]"). The CTRL key works just like a SHIFT key. Control charac- ters are written either as CTRL-A or ^A, where A is the character to be typed while holding down CTRL. 2.3. Transferring a File 2.3. Transferring a File 2.3. Transferring a File To transfer a file, you must first get the attention of the PC's operating sys- tem. 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 each 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 reli- ably 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 estab- lish 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 ar- How to Use KERMIT How to Use KERMIT How to Use KERMIT Page 10 bitrary 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. 2.4. Basic KERMIT Commands 2.4. Basic KERMIT Commands 2.4. Basic KERMIT Commands These are generic descriptions of the most basic Kermit commands. Detailed _____ descriptions will come later. In these descriptions, local refers to the sys- ______ tem that you are using directly, remote 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. ________ ________ SEND filespec Send the file or file group specified by 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" characters like "*" in the file specifica- tion. Examples: send foo.txt send *.for 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. RECEIVE Receive a file or file group from the other Kermit. If an in- coming 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 over- written. Some versions of Kermit attempt to prevent this by warning you of filename collisions and taking, or allowing for, evasive action. 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 escape character (e.g. CTRL-], control- rightbracket), followed by the letter "C" for "Close Connection". SET Establish various nonstandard settings, such as CONNECT escape character, file characteristics, communication line number, How to Use KERMIT How to Use KERMIT How to Use KERMIT Page 11 parity, or flow control. 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. ? Typed anywhere within a KERMIT command: List the commands, op- tions, or operands that are possible at this point. This com- mand may or may not require a carriage return, depending on the host operating system. 2.5. Real Examples 2.5. Real Examples 2.5. Real Examples 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. 2.5.1. PC to Host 2.5.1. PC to Host 2.5.1. PC to Host 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 local, the DEC-20 is remote. 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: 5 ______ A>kermit ! Run Kermit on the PC. Kermit V1.20 Kermit-86> ! This is the Kermit prompt for the PC. _______ Kermit-86>connect ! Connect to the DEC-20. [Connecting to host, type control-] to return to PC. Baud rate is 9600, connecting over COM1.] _______________ 5 Everthing from a "!" mark to the end of line is commentary, not system typeout or part of a command. How to Use KERMIT How to Use KERMIT How to Use KERMIT Page 12 ! You are now connected to the DEC-20. CU20B ! The system prints its herald. ________ ________ @terminal_heath-19 ! Set your terminal type (optional). _____ _____ ________ @login_my-id_password ! Login using normal login method. __ ____ _____ ___ ___ __ ______ _______ ________ (At this point, the DEC-20 prints various messages.) ______ @kermit ! Run Kermit on the DEC-20. Kermit-20> ! This is Kermit-20's prompt. 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 "*" wildcard character to denote a file group. ____ _____ Kermit-20>send_*.for ! Send all my FORTRAN files. ___ ^]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>receive ! Tell the PC files are coming. If you take more than about 5 seconds to get back to Kermit-86 and issue the RECEIVE 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 ar- rive, the current file name and packet number will be continuously displayed on the screen. When the PC's "Kermit-86>" prompt returns to your screen, the transfer is done. During file transfer, the microcomputer screen looks some- thing like this: IBM PC Kermit-86 V1.20 Number of Packets: 294 Receiving... Number of Retries: 2 File Name: FOO.TXT The packet and retry counts are continuously updated, and the word in the upper right tells the status of the transfer -- receiving, sending, complete, inter- rupted, 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. How to Use KERMIT How to Use KERMIT How to Use KERMIT Page 13 _______ Kermit-86>connect ! Get back to the DEC-20. [Connecting to host. Type CTRL-]C to return to PC.] Kermit-20> ! Here we are. ____ Kermit-20>exit ! Get out of Kermit-20. ______ @logout ! 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 ___ ^]c ! Now "escape" back to the PC, [Back at PC.] ____ Kermit-86>exit ! and exit from the PC's Kermit. 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 "Kermit-20>" prompt you type RECEIVE rather than SEND. Now escape back to the PC and use the 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 "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. 2.5.2. Host to Host 2.5.2. Host to Host 2.5.2. Host to Host 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 dif- fers 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 __________ autodialer to connect to an IBM 370-series system running VM/CMS 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. ____ __________________ @dial_765-4321/baud:1200 765-4321, baud 1200 [confirm] Dialing your number, please hold... Your party waiting is on TTY12: @ Other methods exist for connecting two hosts with a serial line. Dedicated How to Use KERMIT How to Use KERMIT How to Use KERMIT Page 14 c hookups 6an be made simply by running an EIA cable between TTY ports on the two systems. For connecting to remote systems when no autodialer is available, a 7 manual dialup connection is also possible, but tricky. If you have a microcom- puter 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". @ ______ @kermit ! Run Kermit on the DEC-20. ___ ___ Kermit-20>set_ibm ! Turn on special handshaking, parity, local ec ___ ____ ___ ____ __ Kermit-20>set_line_(to_tty)_12 ! Indicate the line we'll use. _______ Kermit-20>connect ! And connect to it. [TTLINK: Connecting to remote host over TTY12:, type C to retur VM/370 ONLINE ! The IBM system prints its herald. _____ ________ __________ .login_myuserid_mypassword ! Login to the IBM syst LOGON AT 20:49:21 EST THURSDAY 01/20/84 CUVMB SP/CMS PUT 8210 01/19/84 . ______ .kermit ____ _______ ____ KERMIT-CMS>.send_profile_exec ! Send a file. ___ ^Yc ! TTLINK's escape sequence typed here. [TTLINK: Connection Closed. Back at DEC-20.] _______ Kermit-20>receive ! Tell Kermit-20 to RECEIVE. 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 "[OK]", a beep is sounded, and the Kermit-20 prompt next appears. At that point we connect back to the _______________ 6 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 "null modem" cable. 7 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. How to Use KERMIT How to Use KERMIT How to Use KERMIT Page 15 remote IBM system, exit from the remote Kermit and log out. . PROFILE.EXEC.1 ..%%.[OK] _______ Kermit-20>connect ! Get back to IBM and clean up. [TTLINK: Connecting to remote host over TTY12:, type C to retur KERMIT-CMS>. ____ KERMIT-CMS>.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 ___ ^Yc ! Type Kermit-20's escape sequence [TTLINK: Connection Closed. Back at DEC-20.] ____ Kermit-20>exit ! All done with Kermit. That's the whole procedure. The file is in your DEC-20 directory, completely readable, as PROFILE.EXEC -- 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. 2.5.3. Micro to Micro 2.5.3. Micro to Micro 2.5.3. Micro to Micro Kermit also works between personal computers (microcomputers, workstations). ___ The difference here is that commands are typed on two 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 nor- mally be no program on the other side to listen. Making the physical connection between two micros is tricky. If the two units 8 are in close proximity , you can connect their serial ports with a null modem cable. However, different micros have different requirements -- some may want a male connector on their serial port, others a female; many require that _______________ 8 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. How to Use KERMIT How to Use KERMIT How to Use KERMIT Page 16 9 certain of the RS-232 signals be held high or low . 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 autoanswer 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 In- tertec "SuperBrain" CP/M micro, using a female-to-male null modem cable. Get- ting 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 FOO.HEX from the Robin to the SuperBrain. Proceed as follows: 1. Run Kermit on the SuperBrain, and give the RECEIVE command: ______ A>kermit Intertec SuperBrain Kermit-80 - V3.7 _______ Kermit-80>receive 2. Run Kermit on the Robin, and give the SEND command for FOO.HEX. ______ A>kermit DEC VT18X Kermit-80 - V3.7 ____ _______ Kermit-80>send_foo.hex Watch the packets fly. When you get the next Kermit-80> prompt, the transfer is done, and you can EXIT from both Kermits. _________ The key point is to start the receiving 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. _______________ 9 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. How to Use KERMIT How to Use KERMIT How to Use KERMIT Page 17 2.6. Another Way -- The KERMIT Server 2.6. Another Way -- The KERMIT Server 2.6. Another Way -- The KERMIT Server 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 Kermit server. 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 Ker- mit 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 nor- mally 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 com- mands as you like, and when you're finished transferring files, you can give the BYE command, which sends a message to the remote Kermit server to log it- self out. You don't have to connect back to the remote host and clean up. ____ However, if you want to connect back to the host, you can use the FINISH 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. ______ A>kermit ! Run Kermit on the micro. Kermit V3.7 Kermit-80> ! This is the micro Kermit's prompt. _______ Kermit-80>connect ! Connect to the DEC-20. [Connecting to remote host. Type CTRL-]C to return to micro.] CU20E ! The DEC-20 prints its herald. _____ _____ ________ @login_my-id_password ! Log in normally. ___ ___ __ ______ _______ _____ ________ ____ (The DEC-20 prints various login messages here.) ______ @kermit ! Run Kermit-20 normally ______ Kermit-20>server ! Tell it to be a server. Kermit Server running on DEC-20 host. Please type your escape sequence return to your local machine. Shut down the server by typing the Kermi command on your local machine. How to Use KERMIT How to Use KERMIT How to Use KERMIT Page 18 ___ ^]c ! Now escape back to the micro. [Connection closed, back at micro.] ___ _____ Kermit-80>get_*.pas ! Get all my DEC-20 Pascal programs. ____ _____ Kermit-80>send_foo.* ! Send all the "foo" files from my micro. ____ Kermit-80>exit ! Exit from Kermit back to CP/M. A> ____ ___ ___ __ ____ ____ __ ___ _____ ____ _____ ________ ___ ____ (Here you can do some work on the micro, edit files, whatever you like.) ______ A>kermit ! Run Kermit-80 some more. ____ ________ Kermit-80>send_file.pas ! Send another file. ___ Kermit-80>bye ! That's all. Shut down the Kermit server. A> ! Back at CP/M automatically. ____ This is much 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. ________ SEND filespec Sends a file or file group from the local host to the remote host in the normal way. ________ GET filespec Ask the remote host to send a file or file group. Example: get *.c This command is exactly equivalent to typing "send *.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. 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). 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. When Things Go Wrong When Things Go Wrong When Things Go Wrong Page 19 CHAPTER 3 CHAPTER 3 CHAPTER 3 WHEN THINGS GO WRONG WHEN THINGS GO WRONG WHEN THINGS GO WRONG 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. 3.1. Communication Line Problems 3.1. Communication Line Problems 3.1. Communication Line Problems If you have a version of KERMIT on your microcomputer, but the CONNECT command doesn't seem to work at all, please: - Make sure all the required physical connections have been made and have not wiggled loose. If you are using a modem, make sure the car- rier 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 ____ ____ baud rate. 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. You must consult the appropriate manuals for the systems and equipment in ques- tion. 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 not recom- mended for use with KERMIT. Many microcomputer KERMIT programs are written to control the communication hardware explicitly; internal modems can interfere with that control. 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, mul- tiplexers, local networks, and wide-area networks. Such equipment can inter- fere with the KERMIT file transfer protocol in various ways: ______ - It can impose parity 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: When Things Go Wrong When Things Go Wrong When Things Go Wrong Page 20 * 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. * Prevent the use of the 8th bit for binary file data. 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: * Compose and interpret the checksums correctly. * Employ a special encoding to allow 8-bit data to pass through the 7-bit communication channel. Many packet-switched networks, such as GTE TELENET, require parity to 10 be set. - 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 dis- connecting 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. 3.2. The Transfer is Stuck 3.2. The Transfer is Stuck 3.2. The Transfer is Stuck 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 "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 com- _______________ 10 TELENET uses MARK parity. When Things Go Wrong When Things Go Wrong When Things Go Wrong Page 21 mand: 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. 3.3. The Micro is Hung 3.3. The Micro is Hung 3.3. The Micro is Hung 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): - 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 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. 3.4. The Remote Host Went Away 3.4. The Remote Host Went Away 3.4. The Remote Host Went Away If your local system is working but the transfer is hung, maybe the remote host or the remote KERMIT program 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. 3.5. The Disk is Full 3.5. The Disk is Full 3.5. The Disk is Full 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 SEND command and including the name of the file that failed in the "(INITIAL)" field: ____ _____ _______ Kermit-20>send_*.for (initial) foo.for See the Kermit-20 command summary for further information about the initial filespec. When Things Go Wrong When Things Go Wrong When Things Go Wrong Page 22 3.6. Message Interference 3.6. Message Interference 3.6. Message Interference You may find that file transfers fail occasionally and upredictably. One ex- planation 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. 3.7. Host Errors 3.7. Host Errors 3.7. Host Errors Various error conditions can occur on the remote host that could effect file transmission. Whenever any such error occurs, the remote Kermit normally at- tempts 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. 3.8. File is Garbage 3.8. File is Garbage 3.8. File is Garbage 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 file attributes, 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. 3.9. Junk after End of File 3.9. Junk after End of File 3.9. Junk after End of File 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. KERMIT Commands KERMIT Commands KERMIT Commands Page 23 CHAPTER 4 CHAPTER 4 CHAPTER 4 KERMIT COMMANDS KERMIT COMMANDS KERMIT COMMANDS An "ideal" KERMIT program will be described here, which has most of the fea- ______ ________ ______ tures specified in the KERMIT Protocol Manual. 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." 4.1. Remote and Local Operation 4.1. Remote and Local Operation 4.1. Remote and Local Operation ______ _____ Some KERMIT programs can be run in two ways, remote and local. 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 com- mands 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: __ __ _____ _________ __ ______ PC is Local, Mainframe is Remote: KERMIT Commands KERMIT Commands KERMIT Commands Page 24 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 _____ The KERMIT program on the PC is a local 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 pack- ets on the communications port, all at the same time. ______ The KERMIT program running on the mainframe is a remote 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 KER- MIT. The following descriptions will indicate when a command must be remote or local. KERMIT Commands KERMIT Commands KERMIT Commands Page 25 4.2. Command Interface 4.2. Command Interface 4.2. Command Interface Most implementations (the UNIX version is the major exception) have an inter- active keyword-style command interface, modeled after that of the DECSYSTEM-20, __ ______ which is roughly as follows: In response to the "Kermit-xx>" 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 field. 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 dol- lar 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 car- riage 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 min- imum 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: ___ _ Kermit-20>set_? one of the following: debugging delay duplex escape file handshake IBM line parity receive send __ Kermit-20>set d? one of the following: debugging delay duplex __ _ Kermit-20>set du$plex (to) ? one of the following: full half __ Kermit-20>set duplex (to) h$alf ___ __ _ Kermit-20>set_du_h 4.3. Notation 4.3. Notation 4.3. Notation In the command descriptions, the following notation is used: ________ anything A parameter - the symbol in italics is replaced by an argument of the specified type (number, filename, etc). ________ [anything] An optional field. If omitted, it defaults to an appropriate value. KERMIT Commands KERMIT Commands KERMIT Commands Page 26 ______ number A whole number, entered in prevailing notation of the system. _________ character A single character, entered literally, or as a number (perhaps oc- tal or hexadecimal) representing the ASCII value of the character. ________ _____ ______ floating-point-number A "real" number, possibly containing a decimal point and a frac- tional part. ________ filespec A file specification, i.e. the name of a file, possibly including a search path, device or directory name, or other qualifying infor- mation, and possibly containing "wildcard" or pattern-matching characters to denote a group of files. ^X A control character may be written using "uparrow" or "caret" nota- tion, since many systems display control characters this way. Con- trol characters are produced by holding down the key marked CTRL or Control and typing the appropriate character, e.g. X. Commands are shown in upper case, but can be entered in any combination of up- per and lower case. KERMIT Commands KERMIT Commands KERMIT Commands Page 27 4.4. Summary of KERMIT Commands 4.4. Summary of KERMIT Commands 4.4. Summary of KERMIT Commands 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. ___ __________ _____ For exchanging files: SEND, RECEIVE, GET ___ __________ __ _ ______ ____ For connecting to a remote host: CONNECT, SET LINE, SET PARITY, SET DUPLEX, SET HANDSHAKE, SET ESCAPE, SET FLOW-CONTROL ___ ______ __ _ ______ For acting as a server: SERVER ___ _______ __ _ ______ For talking to a server: BYE, FINISH, GET, SEND, REMOTE _______ ___________ ____________ ___ ____ __________ Setting nonstandard transmission and file parameters: 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 ___ ________ ______ __ ___ ________ For defining "macros" of SET commands: DEFINE ___ ____________ ____________ For interrupting transmission: Control-X, Control-Z, Control-C _______ ___________ Getting information: HELP, STATISTICS, SHOW _________ _______ _____ Executing command files: TAKE ___ _________ ___ _______ __ _ ____ ________ _________ For recording the history of a file transfer operation: LOG TRANSACTIONS ___ ___ ________ ____ _______ __ ____________ For non-protocol file capture or transmission: LOG SESSION, TRANSMIT _______ ___ _______ Leaving the program: EXIT, QUIT If you have a file called KERMIT.INI in your default or home disk, KERMIT will execute an automatic TAKE command on it upon initial startup. KERMIT.INI may contain any KERMIT commands, for instance SET commands, or DEFINEs for SET mac- ros to configure KERMIT to various systems or communications media. KERMIT Commands KERMIT Commands KERMIT Commands Page 28 4.5. The SEND Command 4.5. The SEND Command 4.5. The SEND Command Syntax: Sending a single file: _______ _________ _________ SEND nonwild-filespec1 [filespec2] Sending multiple files: ____ _________ _________ SEND wild-filespec1 [filespec2] 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 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 FOO.FOR is a single file, a FORTRAN program named FOO, then *.FOR might be a group of FORTRAN programs. _______ _ ____ _____ __Sending_a_File_Group _________ If 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. The initial _________ file in a wildcard group can be specified with the optional 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. _______ _ ______ ____ __Sending_a_Single_File _________ If filespec1 does not contain any wildcard characters, then the single file _________ _________ specified by filespec1 will be sent. Optionally, filespec2 may be used to specify the name under which the file will arrive at the target system; _________ _________ filespec2 is not parsed or validated locally in any way. If filespec2 is not specified, the file will be sent with its own name. ____ _______ _______ _________ __SEND_Command_General_Operation Files will be sent with their filename and filetype (for instance FOO.BAR, no device or directory field, no generation number or attributes). If communica- tion line parity is being used (see SET PARITY), the sending KERMIT will re- quest that the other KERMIT accept a special kind of prefix notation for binary KERMIT Commands KERMIT Commands KERMIT Commands Page 29 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 cor- rectly. The sending KERMIT will also ask the other KERMIT whether it can handle a spe- cial 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. ____ ______ _________ __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). ____ _____ _________ __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 in- dicate 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. 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. KERMIT Commands KERMIT Commands KERMIT Commands Page 30 4.6. The RECEIVE Command 4.6. The RECEIVE Command 4.6. The RECEIVE Command ________ Syntax: RECEIVE [filespec] 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 filespec as the name to store the incom- ing 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. 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 dis- card it; it will not appear in your directory. You may change this behavior by using the command SET INCOMPLETE KEEP, which will cause as much of the file as arrived to be saved in your directory. _______ ______ _________ __RECEIVE_Remote_Operation If your are running KERMIT remotely, you should escape back to your local Ker- mit 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. _______ _____ _________ __RECEIVE_Local_Operation If you are running KERMIT locally, you should already have issued a SEND com- 11 mand 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 con- tinuous display the packet traffic. If a file begins to arrives that you don't really want, you can attempt to can- cel it by typing Control-X; this sends a cancellation request to the remote _______________ 11 ___ not SERVER -- use the GET command to receive files from a KERMIT server. KERMIT Commands KERMIT Commands KERMIT Commands Page 31 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 can- celled by typing Control-Z. 4.7. GET 4.7. GET 4.7. GET _____ ____ ______ ________ LOCAL ONLY -- Syntax: GET remote-filespec The GET command requests a remote KERMIT server to send the file or file group ______ ________ specified by remote-filespec. 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 es- caped 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 indica- tion 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. 4.8. SERVER 4.8. SERVER 4.8. SERVER ______ ____ REMOTE ONLY -- Syntax: SERVER 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 Commands KERMIT Commands KERMIT Commands Page 32 KERMIT in server mode, in particular the block check type and special file modes. 4.9. BYE 4.9. BYE 4.9. BYE _____ ____ LOCAL ONLY -- Syntax: BYE 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. 4.10. FINISH 4.10. FINISH 4.10. FINISH _____ ____ LOCAL ONLY -- Syntax: FINISH 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. 4.11. REMOTE 4.11. REMOTE 4.11. REMOTE _____ ____ _______ LOCAL ONLY -- Syntax: REMOTE command 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 un- derstand, it will send the results back, and they will be displayed on the screen. The REMOTE commands are: _________ CWD [directory] 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 at- tempt to change to the specified directory. If access is not granted, the server will provide a message to that effect. ________ DELETE filespec Delete the specified file or files. The names of the files that are deleted will appear on your screen. ________ DIRECTORY [filespec] 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 [directory] Provide information about disk usage in the current directory, such as the quota, the current storage, the amount of remaining free space. KERMIT Commands KERMIT Commands KERMIT Commands Page 33 HELP Provide a list of the functions that are available. _______ HOST [command] Pass the given command to the server's host command processor, and display the resulting output on your screen. _______ KERMIT [command] 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 program-name [command-line-argument] Have the remote KERMIT run the indicated program with the in- dicated command line; send the results back to your screen. _______ PROGRAM [command] Send the command to the program started by most recent REMOTE RUN program, and display the results on the screen. If no com- mand is given, send newline character. ________ TYPE filespec Display the contents of the specified file on your screen. 4.12. LOCAL 4.12. LOCAL 4.12. LOCAL _______ Syntax: LOCAL command 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. _________ CWD [directory] "Change Working Directory" to the specified directory. ________ DELETE filespec Delete the specified file or files. ________ DIRECTORY [filespec] Provide a directory listing of the specified files. 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. 4.13. CONNECT 4.13. CONNECT 4.13. CONNECT _____ ____ ________ __________ LOCAL ONLY -- Syntax: CONNECT [terminal-designator] Establish a terminal connection to the system at the other end of the com- munication 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 KERMIT Commands KERMIT Commands KERMIT Commands Page 34 "command". Several single-character commands are possible: C Close the connection and return to the local KERMIT. S Show status of the connection. B Send a BREAK signal. 0 (zero) Send a NUL (0) character. P Push to the local system command processor without breaking the connec- tion. Q Quit logging session transcript. R Resume logging session transcript. ? List all the possible single-character arguments. ^] (or whatever you have set the escape character to be) Typing the escape character twice sends one copy of it to the connected host. 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. 4.14. HELP 4.14. HELP 4.14. HELP Syntax: HELP Typing HELP alone prints a brief summary of KERMIT and its commands, and pos- sibly 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. 4.15. TAKE 4.15. TAKE 4.15. TAKE ________ TAKE filespec Execute KERMIT commands from the specified file. The file may contain contain any valid KERMIT commands, including other TAKE commands. 4.16. EXIT, QUIT 4.16. EXIT, QUIT 4.16. EXIT, QUIT EXIT Exit from KERMIT. QUIT is a synonym for EXIT. KERMIT Commands KERMIT Commands KERMIT Commands Page 35 4.17. The SET Command 4.17. The SET Command 4.17. The SET Command _________ ______ _____ Syntax: SET parameter [option] [value] Establish or modify various parameters for file transfer or terminal connec- tion. 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: 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 The DEFINE command may be used to compose "macros" by combining SET commands. The SET commands are now described in detail. ___ _________ SET_BAUD-RATE 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 ac- tual 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 ap- KERMIT Commands KERMIT Commands KERMIT Commands Page 36 propriately outside of KERMIT. ___ ___________ SET_BLOCK-CHECK 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 quan- tities 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 6 accuracy, the chances are one in 2 -- 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: 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. The single character checksum has proven to be quite adequate in practice, much more effective than straightforward analysis would indicate, since all errors ___ are not 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 very 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-preci- sion block checks, the transfer will automatically use the standard single- character method. KERMIT Commands KERMIT Commands KERMIT Commands Page 37 ___ _____ SET_DEBUG _______ Syntax: SET DEBUG options Record the packet traffic, either on your terminal or in a file. Options are: 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 ter- minal 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. ___ _____ SET_DELAY ______ Syntax: SET DELAY number 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 send- ing the first packet. ___ ______ SET_DUPLEX _______ Syntax: SET DUPLEX keyword 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". ___ ______ SET_ESCAPE _________ Syntax: SET ESCAPE character Specify or change the character you want to use to "escape" from remote connec- tions 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 ^\, ^], ^^, or ^_. Most versions of KERMIT use one of these by default. After you type the KERMIT Commands KERMIT Commands KERMIT Commands Page 38 escape character, you must follow it by a single-character "argument", such as "C" for Close Connection. The arguments are listed above, under the descrip- tion of the CONNECT command. ___ ____ SET_FILE _________ _______ Syntax: SET FILE parameter keyword 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. ___ ____________ SET_FLOW-CONTROL ______ Syntax: SET FLOW-CONTROL option 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. ___ _________ SET_HANDSHAKE ______ Syntax: SET HANDSHAKE option 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: 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-[. KERMIT Commands KERMIT Commands KERMIT Commands Page 39 ___ __________ SET_INCOMPLETE ______ Syntax: SET INCOMPLETE option Specify what to do when a file transfer fails before it is completed. The op- tions are DISCARD (the default) and KEEP. If you choose KEEP, then if a trans- fer fails to complete successfully, you will be able to keep the incomplete part that was received. ___ ____ SET_LINE ________ __________ Syntax: SET LINE [terminal-designator] 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 con- trolling terminal, i.e. go back to "remote mode." ___ ____ SET_PORT ________ __________ Syntax: SET PORT terminal-designator 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. ___ ______ SET_PARITY _______ Syntax: SET PARITY keyword 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. If parity is being used on the communication line, you must inform both KER- MITs, 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 KERMIT Commands KERMIT Commands KERMIT Commands Page 40 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: 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. NONE means no parity processing is done, and the 8th bit of each character can be used for data when transmitting binary files. 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. ___ ____ SET_SEND _________ SET SEND parameter Parameters for outgoing packets, as follows: _________ END-OF-LINE character 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 ter- minator other than carriage return. ______ PACKET-LENGTH number Maximum packet length to send between 10 and 94 (decimal). Shortening the packets might allow more of them to get through through without er- ror on noisy communication lines. Lengthening the packets increases the throughput on clean lines. ______ TIMEOUT number How many seconds to wait for a packet before trying again. ________ _____ ______ PAUSE floating-point-number How many seconds to pause before sending each data packet. Setting this to a nonzero value may allow some slow systems enough time to con- solidate itself packet before the next packet arrives. Normally, no per-packet pausing is done. KERMIT Commands KERMIT Commands KERMIT Commands Page 41 ______ _________ PADDING number, PADCHAR character How much padding to send before a packet, if the other side needs pad- ding, and what character to use for padding. Defaults are no padding, and NUL (0) for the padding character. _________ QUOTE character What printable character to use for quoting of control characters, "#" (43) by default. There should be no reason to change this. _________ START-OF-PACKET character 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). ___ _______ SET_RECEIVE _________ Syntax: SET RECEIVE parameter Parameters to request or expect for incoming packets, as follows: _________ END-OF-LINE character Carriage return (15) by default. ______ PACKET-LENGTH number Maximum length packet for the other side to send, decimal number, be- tween 10 and 94, decimal. ______ TIMEOUT number How many seconds the other Kermit should wait for a packet before as- king for retransmission. ________ _____ ______ PAUSE floating-point-number How many seconds to pause before acknowledging a packet. Setting this to a nonzero value will slow down the rate at which data packets ar- rive, which may be necessary for systems that have "sensitive" front ends and cannot accept input at a high rate. ______ _________ PADDING number, PADCHAR character 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, un- der very unusual circumstances. _________ QUOTE character What printable character to use for quoting of control characters, "#" KERMIT Commands KERMIT Commands KERMIT Commands Page 42 (43) by default. There should be no reason to change this. _________ START-OF-PACKET character The control character to mark the beginning of incoming packets. Nor- mally SOH (Control-A, ASCII 1) (see SET SEND START-OF-PACKET, above). ___ _____ SET_RETRY ______ ______ SET RETRY option number Set the maximum number of retries allowed for: 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. 4.18. DEFINE 4.18. DEFINE 4.18. DEFINE _________ ___ __________ DEFINE macroname [set-parameters] 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: DEFINE IBM PARITY MARK, DUPLEX HALF, HANDSHAKE XON, SEND PACKET-LENGTH 80 DEFINE UNIX PARITY NONE, DUPLEX FULL, HANDSHAKE NONE DEFINE TELENET PARITY MARK, RECEIVE TIMEOUT 20 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 defini- tions in your KERMIT.INI file. Another other handy use for SET macros would be for rapid adaptation to dif- ferent conditions of line noise: 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 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: KERMIT Commands KERMIT Commands KERMIT Commands Page 43 DEFINE IBM You can list all your macros and their definitions with the SHOW MACROS com- mand. 4.19. SHOW 4.19. SHOW 4.19. SHOW ______ Syntax: SHOW [option] The SHOW command displays the values of the parameters settable by the SET com- mand. If a particular option is not requested, a complete display will be provided. 4.20. STATISTICS 4.20. STATISTICS 4.20. STATISTICS Give statistics about the most recent file transfer, such as the total number of characters transmitted, the effective baud rate, and so forth. 4.21. LOG 4.21. LOG 4.21. LOG ______ ________ Syntax: LOG [option] [filespec] Log the specified entity to the specified log file. TRANSACTIONS Direct KERMIT to log transactions, such as files successfully sent or received or files that could not be successfully sent or received. A transaction is useful recording the progress of a long, unattended multifile transfer. SESSION Create a transcript of a CONNECT session, when running a local KERMIT connected to a remote system, in the specified file. The log is closed when connection is closed. In some implemen- tations, logging can be "toggled" by typing the connect escape character followed by Q (Quit logging) or R (Resume logging) or similar single-character commands. Session-logging is useful for recording dialog with an interactive system, and for "capturing" from systems that don't have KERMIT. No guarantee can be made that the file will arrive correctly or completely, since no error checking takes place. 4.22. TRANSMIT 4.22. TRANSMIT 4.22. TRANSMIT ________ Syntax: TRANSMIT filespec Send the contents of the specified file to the other system "bare", without protocol, packets, error checking, or retransmission. This command is useful for sending standard logon or connection sequences, and for sending files to systems that don't have KERMIT. No guarantee can be made that the target sys- KERMIT Commands KERMIT Commands KERMIT Commands Page 44 tem will receive the file correctly and completely. When receiving a file, the target system would normally be running a text editor in text collection mode. KERMIT Implementations KERMIT Implementations KERMIT Implementations Page 45 CHAPTER 5 CHAPTER 5 CHAPTER 5 KERMIT IMPLEMENTATIONS KERMIT IMPLEMENTATIONS KERMIT 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 im- plemenation is written in the language best suited for the particular machine. ______ ________ ______ The specification, given in the Kermit Protocol Manual, is quite general and allows implementation on almost any machine. Here's a brief table summarizing the known Kermit implementations, as of this writing. This list is constantly growing, and may be far out of date by the time you read it. _______ _________ ______ ________ _______ _________ ______ ________ _______ _________ ______ ________ Machine Operating System Language Machine Operating System Language Machine Operati ng_S DECsystem-10 TOPS-10 MACRO-10 DECSYSTEM-20 TOPS-20 MACRO-20 IBM 370 Series VM/CMS, MTS IBM Assembler, Pascal CDC Cyber 170 NOS Fortran-77 Univac-1100 EXEC EXEC Assembler Honeywell MULTICS PL/I PRIME PRIMOS PL/I VAX-11 VMS Bliss-32, Macro-32 PDP-11 RT-11 OMSI Pascal PDP-11 RSX-11,RSTS/E MACRO-11 VAX,PDP-11,SUN,etc UNIX C Data General AOS Ratfor HP3000, Univac, ... Software Tools Ratfor Terak, HP-98xx UCSD p-System UCSD Pascal, Macro-11 8080, 8085, or Z80 CP/M-80 DR ASM 8086, 8088 PC DOS, MS DOS MS MASM-86 8086, 8088 CP/M-86 DR ASM86 Apple II 6502 Apple DOS DEC-10/20 CROSS Atari Home Computer DOS Action! Even this is a partial list; some major systems (like VAX/VMS), have multiple implementations; some minor ones have been omitted. 8080 version 8080 version The 8080 version runs on the DEC VT180, DECmate II (CP/M), Heath/Zenith-89 and 100, Intertec Superbrain, Apple II with Z80 Softcard, TRS-80 II (CP/M), Os- 8086 MS DOS 8086 MS DOS borne, Kaypro, Vector Graphics, Telcon Zorba, and others. The 8086 MS DOS version runs on the IBM PC and lookalikes (such as the Compaq portable), the Heath/Zenith-100, HP-150, the Tandy 2000, the Seequa Chameleon, and the Victor 8086 CP/M-86 version 8086 CP/M-86 version 9000. The 8086 CP/M-86 version runs on the DEC Rainbow-100 and the NEC APC. The remainder of the KERMIT User Guide is devoted to descriptions of selected KERMIT implementations. If a description of your version of KERMIT does not appear, look in the KERMIT area on your mainframe for an on-line documentation file. Even if your version is described below, the version of the manual you are reading may be out of date and the online information may be more current. DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 46 CHAPTER 6 CHAPTER 6 CHAPTER 6 DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT _______ Authors: Frank da Cruz, Bill Catchings, Columbia University _______ Version: 4(200) ____ Date: February 1984 KERMIT-20 is a program that implements the KERMIT file transfer protocol for the Digital Equipment Corporation DECSYSTEM-20 mainframe computer. It is writ- ten in MACRO-20 assembly language and should run on any DEC-20 system with ver- sion 4 of TOPS-20 or later. This section will describe the things you should know about the DEC-20 file system in order to make effective use of KERMIT, and then it will describe the special features of the KERMIT-20 program. 6.1. The DEC-20 File System 6.1. The DEC-20 File System 6.1. The DEC-20 File System The features of the DEC-20 file system of greatest interest to KERMIT users are the form of the file specifications, and the distinction between text and bi- nary files. ______ ____ ______________ DEC-20_File_Specifications DEC-20 file specifications are of the form 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 nor- mally omitted. Device and directory, when omitted, default to the user's own (or "connected") disk and directory. Thus NAME.TYPE is normally sufficient to specify a file, and only this information is sent along by KERMIT-20 with an outgoing file. The device, directory, name, and type fields may contain uppercase letters, digits, and the special characters "-" (dash), "_" (underscore), and "$" (dollar sign). There are no imbedded or trailing spaces. Other characters may be included by prefixing them (each) with a Control-V. The fields of the file specification are set off from one another by the punctuation indicated above. The device field specifies a physical or "logical" device upon which the file is resident. The directory field indicates the area on the device, for in- stance the area belonging to the owner of the file. KERMIT-20 does not trans- mit the device or directory fields to the target system, and does not attempt to honor device or directory fields that may appear in incoming file names. The name is the primary identifier for the file. The type, also called the DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 47 "extension", is an indicator which, by convention, tells what kind of file we have. For instance FOO.FOR is the source of a Fortran program named FOO; FOO.REL might be the relocatable object module produced by compiling FOO.FOR; FOO.EXE could an executable program produced by LOADing FOO.REL, and so forth. The DEC-20 allows a group of files to be specified in a single file specifica- tion by including the special "wildcard" characters, "*" and "%". A "*" matches any string of characters, including no characters at all; a "%" matches any single character. Here are some examples: *.FOR All files of type FOR (all Fortran source files) in the connected directory. FOO.* Files of all types with name FOO. F*.* All files whose names start with F. F*X*.* All files whose names start with F and contain at least one X. %.* All files whose names are exactly one character long. *.%%%* All files whose types are at least three characters long. Wildcard notation is used on many computer systems in similar ways, and it is the mechanism most commonly used to instruct KERMIT to send a group of files. ____ _____ ___ ______ _____ __Text_Files_and_Binary_Files The DEC-20, like most computers, has a file system with its own pecularities. ____ _____ Like many other systems, the DEC-20 makes a distinction between text files and ______ _____ binary files. Text files are generally those composed only of printing charac- ters (letters, digits, and punctuation) and "carriage control" characters (carriage return, line feed, form feed, tab). Text files are designed to be read by people. Binary files are designed to be read by a computer program, and may have any contents at all. If you use the DEC-20 TYPE command to dis- play a text file on your terminal, the result will be intelligible. If you type a binary file on your terminal, you will probably see only gibberish. You can not always tell a text file from a binary file by its name or directory in- formation, though in general files with types like .TXT, .DOC, .HLP are textual (as are "source files" for computer programs like text formatters and program- ming language compilers), and files with types like .EXE, .REL, .BIN are bi- nary. The DEC-20 has an unusual word size, 36 bits. It differs from most other sys- tems by storing text in 7-bit, rather than 8-bit, bytes. Since text is encoded in the 7-bit ASCII character set, this allows more efficient use of storage. However, the word size is not a multiple of the normal byte size. The DEC-20 therefore stores five 7-bit characters per word, with one bit left over. It is also possible to store files with other byte sizes. The common layouts DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 48 are: 7 Text Files: +------+------+------+------+------++ | | | | | || +------+------+------+------+------++ 0 7 14 21 28 35 Normally, bit 35 is unused and set to zero. However, in EDIT (or SOS, or OTTO) line-numbered files, bit 35 is set to 1 when the word contains a line number. 8 "Foreign" binary files: +-------+-------+-------+-------+---+ | | | | | | +-------+-------+-------+-------+---+ 0 8 16 24 32 35 Bits 32-35 are unused. 36 "Native" binary files: +-----------------------------------+ | | +-----------------------------------+ 0 35 All bits are used. ____ The minimum unit of disk allocation on the DEC-20 is a page, 512 36-bit words, or 2560 7-bit characters, or 2048 8-bit bytes. Any file that contains at least one bit of information occupies at least a full page on the disk. The direc- tory information for a file includes the number of pages occupied on the disk, the bytesize of the file, and the number of bytes of that size which are in the file. This information can be seen by using the DEC-20 VDIRECTORY command, for instance @vdir foo.* PS: Name Protection Pages Bytes(size) Creation FOO.COM.1;P774242 1 384(8) 27-Dec-83 MAC.1;P774242 1 152(7) 27-Dec-83 .REL.1;P774242 1 39(36) 27-Dec-83 .EXE.1;P774242 2 1024(36) 27-Dec-83 Total of 5 pages in 4 files In this example, FOO.MAC occupies 1 page, and is composed of 152 7-bit bytes. This file is textual (program source for the MACRO assembler), 152 characters DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 49 long. Programs which read text files (such as text editors, program compilers, the TYPE command, etc) determine the end of a file from the byte count specified in the directory. KERMIT-20 determines the end of file in the same way, so although FOO.MAC occupies an entire 2560-word page of storage, only the first 152 characters are transmitted. Binary files, such as FOO.EXE (an ex- ecutable DEC-20 program), tend to occupy full pages, and programs that use them (such as the RUN command) often ignore the byte count. Why do you need to know all this? In most cases, you don't. It depends on whether you are using the DEC-20 as your "home base". _____ _ _____________ __ _______ ______ _____ __Using_a_Microcomputer_to_Archive_DEC-20_Files Most computers (other than the DEC-10 and DEC-20) store characters in 8-bit bytes. Let's call any such system an 8-bit-byte system. This discussion ap- plies to all 8-bit-byte systems, including all popular microcomputers, minicom- puters like the DEC PDP-11 and VAX, and mainframes like the IBM 370. For simplicity, we'll focus on microcomputers. KERMIT can send any "native" DEC-20 sequential file, text or binary, to an 8-bit-byte system and bring it back to the DEC-20 restored to its original form. If you are using a microcomputer to archive your DEC-20 files, you need never concern yourself with details of byte size or file format. The same holds true between two DEC-20s, or a DEC-10 and a DEC-20. _____ ___ ______ __ _______ _____________ _____ __Using_the_DEC-20_to_Archive_Microcomputer_Files You can use KERMIT to send textual files from a microcomputer or any 8-bit sys- tem to the DEC-20 with no special provisions, since KERMIT-20 stores incoming characters in 7-bit bytes as text unless you explicity instruct it otherwise. But KERMIT-20 has no automatic way of distinguishing an incoming binary file 12 from an incoming text file. Binary files from 8-bit-byte systems generally contain significant data in the 8th bit, which would be lost if the incoming characters were stored in 7-bit bytes, rendering the file useless when sent back to the original system. Thus if you want to use KERMIT to store foreign 8-bit binary data on the DEC-20, you must tell it to store such files with a bytesize of 8 rather than 7. This can be the source of much confusion and in- convenience. In particular, you cannot use a "wildcard send" command to send a mixture of text and binary files from an 8-bit-byte system to the DEC-20; rather, you must send all text files with KERMIT-20's file bytesize set to 7, and all 8-bit binary files with the bytesize set to 8. _______________ 12 Unless the incoming file has an "ITS Binary Header"; see below. DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 50 Once you get the foreign binary file into the DEC-20, stored with the correct bytesize (as FOO.COM is stored in the example above), you need take no special measures to send it back to its system of origin. This is because KERMIT-20 honors the bytesize and byte count from the directory. For instance, if you told KERMIT-20 to SEND FOO.*, every file in the example above would be trans- mitted in the correct manner, automatically. _____ _________ ______ ______ __Files_KERMIT-20_Cannot_Handle __________ The KERMIT protocol can only accommodate transfer of sequential files, files which are a linear sequence of bytes (or words). Some files on the DEC-20 are not sequential, and cannot be successfully sent or received by KERMIT-20. These include directory files, files with holes (missing pages), ISAM files, and RMS files. These files require external in- formation (kept in the DEC-20's file descriptor block and/or index table) in order to be reconstructed; when sending files, KERMIT-20 presently transmits only the file name and the contents of the file. External control information (file attributes) are not transmitted. 6.2. Program Operation 6.2. Program Operation 6.2. Program Operation Kermit-20's prompt is "Kermit-20>". Kermit-20 will accept a single command on the Exec command line, like this: @ ______ ____ _______ @kermit_send_foo.bar ___ ____ __ ____ the file is sent @ or you can run the program interactively to issue several commands, like this: @ ______ @kermit TOPS-20 KERMIT version 4(200) ____ _____ Kermit-20>send_foo.* _____ ___ ____ files are sent __________ Kermit-20>statistics ___________ __________ ___ _______ performance statistics are printed _______ Kermit-20>receive DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 51 _____ ___ ________ files are received ____ Kermit-20>exit @ During interactive operation, you may use the TOPS-20 help ("?") and recognition (ESC) features freely while typing commands. A question mark typed at any point in a command displays the options available at that point; typing an ESC character causes the current keyword or filename to be completed (or default value to be supplied), and a "guide word" in parentheses to be typed, prompting you for the next field. If you have not typed sufficient characters to uniquely specify the keyword or filename (or if there is no default value) then a beep will be sounded and you may continue typing. Command keywords may be abbreviated to their shortest prefix that sets them apart from any other keyword valid in that field. If you have a file called KERMIT.INI in your login directory, KERMIT-20 will execute an automatic TAKE command on it upon initial startup. KERMIT.INI may contain any KERMIT-20 commands, for instance SET commands, or DEFINEs for SET macros to configure KERMIT-20 to various systems or communications media. KERMIT-20 provides most of the commands possible for an "ideal" KERMIT program, as described in the main part of the KERMIT User Guide. The following sections will concentrate on system-dependent aspects of KERMIT-20. 6.3. Remote and Local Operation 6.3. Remote and Local Operation 6.3. Remote and Local Operation KERMIT-20 normally runs in remote mode, with the user sitting at a PC. But KERMIT-20 can also run in local mode. Local operation of KERMIT-20 is useful if the DEC-20 has an autodialer, or a hardwired connection to another computer. When in local mode, file transfer takes place over an assigned TTY line, and KERMIT-20 is free to update your screen with status information, and to listen to your keyboard for interrupt characters. _____ _________ __ ______ __ Local Operation of KERMIT-20: DEC-20 (local) +-------------------------------+ +----------+ | | (remote) | Terminal |----/ /---+-Your job's TTY | +--------+ +----+-----+ | | | | | | TTY assigned by KERMIT-+---/ /---+ Host | You | | | | +-------------------------------+ +--------+ DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 52 6.4. KERMIT-20 Commands 6.4. KERMIT-20 Commands 6.4. KERMIT-20 Commands This section describes the KERMIT-20 commands, in detail where they differ from the "ideal" KERMIT, briefly where they coincide. THE SEND COMMAND THE SEND COMMAND THE SEND COMMAND Syntax: Sending a single file: _______ _________ _________ SEND nonwild-filespec1 (AS) [filespec2] Sending multiple files: ____ _________ _________ SEND wild-filespec1 (INITIAL) [filespec2] The SEND command causes a file or file group to be sent from the DEC-20 to the other system. There are two forms of the command, depending on whether _________ filespec1 contains wildcard characters ("*" or "%"). KERMIT-20 automatically recognizes the two cases and issues the appropriate guide word, (AS) or _________ (INITIAL), depending on the form of filespec1. _______ _ ____ _____ __Sending_a_File_Group _________ If filespec1 contains wildcard characters then all matching files will be sent, in alphabetical order (according to the ASCII collating sequence) by name. If a file can't be opened for read access, it will be skipped. The initial file _________ in a wildcard group can be specified with the optional filespec2. This allows a previously interrupted wildcard transfer from where it left off, or it can be used to skip some files that would be transmitted first. _______ _ ______ ____ __Sending_a_Single_File _________ If filespec1 does not contain any wildcard characters, then the single file _________ _________ specified by filespec1 will be sent. Optionally, filespec2 may be used to specify the name under which the file will arrive at the target system; _________ filespec2 is not parsed or validated in any way by KERMIT-20, but lower case letters are raised to upper case, and leading "whitespace" (blanks and tabs) _________ are discarded. If filespec2 is not specified, KERMIT-20 will send the file DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 53 13 with its own name. ____ _______ _______ _________ __SEND_Command_General_Operation Files will be sent with their DEC-20 filename and filetype (for instance FOO.BAR, no device or directory field, no generation number or attributes). If you expect to be sending files whose names contain characters that would be il- legal in filenames on the target system, and you know that KERMIT on the target system does not have the ability to convert incoming filenames, you can issue the SET FILE NAMING NORMAL-FORM command to have KERMIT-20 replace suspect characters by X's. Each file will be sent according to its bytesize and byte count from the direc- tory unless you specify otherwise using SET FILE BYTESIZE, or unless the file has an "ITS Binary" header. If the bytesize is 8, then four 8-bit bytes will be sent from each DEC-20 36-bit word, and the low order four bits will be skipped. If other than 8, then five 7-bit bytes will be sent from each word, with the 8th bit of the 5th character set to the value of the remaining bit 14 ("bit 35") from the word. If communication line parity is being used (see SET PARITY), KERMIT-20 will re- quest 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 cor- rectly. This includes executable programs (like DEC-20 .EXE files, CP/M .COM files), relocatable object modules (.REL files), as well as text files with line sequence numbers. KERMIT-20 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. If you're running KERMIT-20 locally, for instance dialing out from the DEC-20 _______________ 13 Control-V's, which are used to quote otherwise illegal characters in DEC-20 file specifications, are stripped. 14 This is the same method used by the DEC-20 to encode 36-bit data on "ANSI-ASCII" tapes. It allows not only DEC-20 binary files, but also the line- sequence-numbered files produced by EDIT, SOS, or OTTO, which use bit 35 to distinguish line numbers from text, to be sent and retrieved correctly. DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 54 to another system using an autodialer, you should have already run KERMIT on the remote system and issued either a RECEIVE or a SERVER command. Once you give KERMIT-20 the SEND command, the name of each file will be displayed on your screen as the transfer begins; a "." will be displayed for every 5 data packets sucessfully sent, and a "%" for every retransmission or timeout that occurs (you may also elect other typeout options with the SET DEBUG command). If the file is successfully transferred, you will see "[OK]", otherwise there will be an error message. When the specified operation is complete, the program will sound a beep. If you see many "%" characters, 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. During local operation, you can type Control-A at any point during the transfer to get a brief status report. You may also type Control-X or Control-Z to in- terrupt the current file or file group. THE RECEIVE COMMAND THE RECEIVE COMMAND THE RECEIVE COMMAND ________ Syntax: RECEIVE [filespec] The RECEIVE command tells KERMIT-20 to receive a file or file group from the other system. If only one file is being received, you may include the optional ________ filespec as the name to store the incoming file under; otherwise, the name is taken from the incoming file header. Even if the name in the header 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 each illegal character (spaces, lowercase letters, control characters, etc) with Control-V. You may also use SET FILE NAMING NORMAL-FORM to have KERMIT-20 choose more conventional names for incoming files. If an incoming file has the same name as an existing file, KERMIT-20 just creates a new generation of the same name and type, for instance FOO.BAR.3, FOO.BAR.4. The oldest generation will be automatically deleted, but you can still UNDELETE it. Incoming files will all be stored with the prevailing bytesize, 7 by default, which is appropriate for text files. If you are asking KERMIT-20 to receive binary files from a microcomputer or other 8-bit system, you must first type SET FILE BYTESIZE 8. Otherwise, the 8th bit of each byte will be lost and the file will be useless when sent back to the system of origin. 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. In all cases, KERMIT-20 will request the other KERMIT to compress repeated characters; if the other side can do this (not all KERMITs know how) there may be a sig- nificant improvement in transmission speed. If an incoming file does not arrive in its entirety, KERMIT-20 will normally DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 55 discard it; it will not appear in your directory. You may change this behavior by using the command SET INCOMPLETE KEEP, which will cause as much of the file as arrived to be saved in your directory. If you are running KERMIT-20 locally, you should already have issued a SEND 15 command to the remote KERMIT, and then escaped back to DEC-20 Kermit. As files arrive, their names will be displayed on your screen, along with "." and "%" characters to indicate the packet traffic; you can type Control-A during the transfer for a brief status report. If a file 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. THE GET COMMAND THE GET COMMAND THE GET COMMAND ______ ________ Syntax: GET remote-filespec The GET command requests a remote KERMIT server to send the file or file group ______ ________ specified by remote-filespec. This command can be used only when KERMIT-20 is local, with a KERMIT server on the other end of the line specified by SET 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 DEC-20. 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 "." and "%" characters to indicate the packet traffic. As in the RECEIVE command, you may type Control-A to get a brief status report, ^X to request that the current incoming file be cancelled, ^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. _______________ 15 ___ not SERVER -- use the GET command to receive files from a KERMIT server. DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 56 THE SERVER COMMAND THE SERVER COMMAND THE SERVER COMMAND The SERVER command puts a remote KERMIT-20 in "server mode", so that it receives all further commands in packets from the local KERMIT. The KERMIT-20 server is capable (as of this writing) of executing most remote server com- mands, including SEND, GET, FINISH, BYE, REMOTE DIRECTORY, REMOTE CWD, REMOTE DISK, REMOTE DELETE, REMOTE TYPE, REMOTE HELP. Any nonstandard parameters should be selected with SET commands before putting KERMIT-20 into server mode, in particular the file bytesize. The DEC-20 Kermit server can send most files in the correct manner automatically, by recognizing the DEC-20 file bytesize. However, if you need to ask the DEC-20 KERMIT server to receive binary files from an 8-bit-byte system (that is, from almost any system that's not a DEC-10 or DEC-20) you must issue the SET FILE BYTESIZE 8 command before putting it into server mode, and then you must only send 8-bit binary files. You cannot send a mixture of text files and 8-bit binary files to a KERMIT-20 server. COMMANDS FOR SERVERS COMMANDS FOR SERVERS COMMANDS FOR SERVERS When running in local mode, KERMIT-20 allows you to give the full range of com- mands to a remote KERMIT server, with no guarantee the that the remote server can process them, since they are all optional features of the protocol. Com- mands for servers include the standard SEND, GET, BYE, and FINISH commands, as well as the REMOTE command, which has various options. _______ Syntax: REMOTE command Send the specified command to the remote server. If the server does not under- stand 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: _________ CWD [directory] Change Working Directory. If no directory name is provided, the server will change to the default or home directory. Otherwise, you will be prompted for a password, and the server will attempt to change to the specified directory. The password is entered on a separate line, and does not echo as you type it. If access is not granted, the server will provide a message to that effect. ________ DELETE filespec Delete the specified file or files. The names of the files that are deleted will appear on your screen. ________ DIRECTORY [filespec] 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. DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 57 DISK 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 [command] Pass the given command to the server's host command processor, and display the resulting output on your screen. ________ TYPE filespec Display the contents of the specified file on your screen. THE LOCAL COMMAND THE LOCAL COMMAND THE LOCAL COMMAND _______ Syntax: LOCAL [command] Execute the specified command on the local system -- on the DEC-20 where KERMIT-20 is running. These commands provide some local file management capability without having to leave the KERMIT-20 program. _________ CWD [directory] Change working directory, or, in DEC-20 terminology, CONNECT to the specified directory. ________ DELETE filespec Delete the specified file or files, but do not expunge them. ________ DIRECTORY [filespec] Provide a directory listing of the specified files. THE CONNECT COMMAND THE CONNECT COMMAND THE CONNECT COMMAND ______ Syntax: CONNECT [number] Establish a terminal connection to the system connected to the octal TTY number specified here or in the most recent SET LINE command, using full duplex echo- ing and no parity unless otherwise specified in previous SET commands. Get back to KERMIT-20 by typing the escape character followed by the letter C. The escape character is Control-Y by default. When you type the escape character, several single-character commands are possible: C Close the connection and return to KERMIT-20. S Show status of the connection. P Push to a new Exec. POP from the Exec to get back to the connection. Q If a session log is active, temporarily Quit logging. R Resume logging to the session log. B Send a simulated BREAK signal. ? List all the possible single-character arguments. ^Y (or whatever you have set the escape character to be) Typing the escape character twice sends one copy of it to the connected host. DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 58 You can use the SET ESCAPE command to define a different escape character, and SET PARITY, SET DUPLEX, SET HANDSHAKE to change those parameters. KERMIT-20 accomplishes the connection by running the TTLINK program in a lower fork. If all you want to do connect to a remote host over a TTY line, without file transfer, you can run TTLINK itself. Note that the function for sending a simulated BREAK can be dangerous. See the description of the TTLINK program below. KERMIT-20 does not have any special autodialer interface. It assumes that the connection has already been made and the line assigned. THE HELP COMMAND THE HELP COMMAND THE HELP COMMAND _____ ________ Syntax: HELP [topic [subtopic]] Typing HELP alone prints a brief summary of KERMIT-20 and its commands. You can also type _______ HELP command for any Kermit-20 command, e.g. "help send" or "help set parity" to get more detailed information about a specific command. Type HELP ? to see a list of the available help commands. THE TAKE COMMAND THE TAKE COMMAND THE TAKE COMMAND ________ Syntax: TAKE filespec Execute KERMIT-20 commands from the specified file. The file may contain con- tain any valid KERMIT-20 commands, including other TAKE commands; command files may be nested up to a depth of 20. THE EXIT AND QUIT COMMANDS THE EXIT AND QUIT COMMANDS THE EXIT AND QUIT COMMANDS Syntax: EXIT Exit from KERMIT-20. You can CONTINUE the program from the TOPS-20 Exec, provided you haven't run another program on top of it. You can also exit from KERMIT-20 by typing one or more control-C's, even if it's in the middle of transferring a file. KERMIT-20 will always restore your terminal to its original condition, and you will be able to CONTINUE the program to get back to "KERMIT-20>" command level with current settings intact. DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 59 QUIT is a synonym for EXIT. THE SET COMMAND THE SET COMMAND THE SET COMMAND _________ ______ _____ Syntax: SET parameter [option [value]] Establish or modify various parameters for file transfer or terminal connec- tion. You can examine their values with the SHOW command. The following parameters may be SET: 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 HANDSHAKE For turning around half duplex communication line IBM For communicating with an IBM mainframe INCOMPLETE What to do with an incomplete file ITS-BINARY For recognizing a special 8-bit binary file format LINE TTY line to use for terminal connection or file transfer PARITY Character parity to use RECEIVE Various parameters for receiving files RETRY How many times to retry a packet before giving up SEND Various parameters for sending files TAC-BINARY For negotiating binary mode with ARPANET TAC The DEFINE command may be used to compose "macros" by combining SET commands. Those SET commands which differ from the "ideal" KERMIT are now described in detail. ___ _____ SET_DEBUG _______ Syntax: SET DEBUG options Record the packet traffic, either on your terminal or in a file. Some reasons for doing this would be to debug a version of KERMIT that you are working on, to record a transaction in which an error occurred for evidence when reporting bugs, or simply to vary the display you get when running KERMIT-20 in local mode. Options are: STATES Show Kermit state transitions and packet numbers (brief). PACKETS Display each incoming and outgoing packet (lengthy). ________ ________ LOG-FILE [filespec [bytesize]] Log STATES or PACKETS to the specified file. If log file not DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 60 specified, then use TTY if local, or KERMIT.LOG in the current directory if remote. If a log-file name was specified, then log STATES unless PACKETS was specified. Also allow specifica- tion of bytesize for log file, 7 (normal, default), or 8 (for debugging binary transfers), for instance SET DEBUG LOG FOO.LOG 8 OFF Don't display debugging information (this is the default). If debugging was in effect, turn it off and close any log file. A 7-bit log file can be typed, printed, or examined with a text editor or searching program. An 8-bit log file can only be examined with a system utility like FILDDT. ___ ______ SET_ESCAPE _____ ______ SET ESCAPE octal-number Specify the control character you want to use to "escape" from remote connec- tions back to KERMIT-20. The default is 31 (Control-Y). The number is the oc- tal value of the ASCII control character, 1 to 37, for instance 2 is Control-B. After you type the escape character, you must follow it by a one of the single- character "arguments" described under the CONNECT command, above. ___ ____ SET_FILE _________ _______ Syntax: SET FILE paramater keyword Establish file-related parameters: _______ __ ______ BYTESIZE keyword or number Byte size for DEC-20 file input/output. The choices are SEVEN (7), EIGHT (8), and AUTO. SEVEN (or 7) Always store or retrieve five 7-bit bytes per word. When sending a file, ignore the file bytesize and do 7-bit in- put from the file. There would be no reason to use this option except to explicitly force an 8-bit file to be treated as a 7-bit file. EIGHT (or 8) Always store or retrieve four 8-bit bytes per word. When sending a file, ignore the file bytesize and do 8-bit in- put from the file. This command is necessary when receiving binary files from 8-bit-byte systems, such as most microcom- puters. AUTO Equivalent to SEVEN for incoming files, and for outgoing files DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 61 means to use EIGHT if the DEC-20 file bytesize (as shown by the Exec VDIR command) is 8, otherwise use SEVEN. The default is AUTO. The DEC-20 can send any mixture of file types in the correct way ____ automatically, but you must set the file bytesize to 8 for any incoming 8-bit binary files, and to AUTO (i.e. 7) for any incoming text files or DEC-20 binary files. __ NAMING UNTRANSLATED or NORMAL-FORM If NORMAL-FORM the names of incoming or outgoing files will be con- verted to contain only uppercase letters, digits, and at most one period; any other characters will be translated to "X". If UNTRANS- LATED, filenames will be sent and used literally. UNTRANSLATED is the default. ___ ___ SET_IBM __ Syntax: SET IBM ON or OFF SET IBM is really a predefined SET macro rather than a "hardwired" SET command; it can be redefined or undefined (see DEFINE); as distributed from Columbia, KERMIT-10 defines IBM to be "parity mark, handshake XON, duplex half". SET IBM should be used when running KERMIT-20 in local mode, connected to an IBM or similar mainframe. If you have redefined the SET IBM macro, then your parameters will be used instead. ___ __________ SET_ITS-BINARY __ Syntax: SET ITS-BINARY ON or OFF Specify whether ITS-Binary file headers are to be recognized or ignored. By default, they are recognized. ITS binary format is a way (devised at MIT) of storing foreign 8-bit binary data on a 36-bit machine to allow automatic recog- nition of these files when sending them out again, so that you don't have to depend on the file byte size, or to issue explict SET FILE BYTESIZE commands to KERMIT. An ITS format binary file contains the sixbit characters "DSK8" left-adjusted in the first 36-bit word. If ITS-BINARY is ON, then KERMIT-20 will send any file starting with this "header word" using 8-bit input from the file even if the file bytesize is not 8, and will not send the header word itself. KERMIT-20 will also store any incoming file that begins with that header word using 8-bit bytesize, again discarding the header word itself. If ITS-BINARY is OFF, then the header word, if any, will be sent or kept, and i/o will be ac- cording to the setting of FILE BYTESIZE. DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 62 This facility is provided for compatibility with the file formats used on cer- tain public-access CP/M libraries. ___ ____ SET_LINE _____ ______ Syntax: SET LINE [octal-number] Specify the octal TTY number to use for file transfer or CONNECT. If you issue _______ this command, you will be running KERMIT-20 locally, and you must log in to the remote system and run Kermit on that side in order to transfer a file. If you ________ don't issue this command, KERMIT-20 assumes it is running remotely, and does file transfer over its job's controlling terminal line. You can also select the line directly in the CONNECT command. If you type SET LINE with no number argument, you will deassign any previous assigned line and revert to remote mode. ___ __________ SET_TAC-BINARY __ Syntax: SET TAC-BINARY ON or OFF Only for users running KERMIT-20 on an ARPANET DEC-20, signed on through an AR- PANET TAC. SET TAC ON causes KERMIT-20 to negotiate binary mode with the TAC during file transfer. This is equivalent to typing the "@ B I S" command to your TAC, except that when the file transfer is done, KERMIT turns binary mode off again, so that you can continue to use the TAC escape character. ARPANET TAC users must use one of these methods in order to transfer files successfully with KERMIT. OFF by default. If you normally use KERMIT-20 through a TAC, you can put the command SET TAC-BINARY ON into your KERMIT.INI file. _______ CAUTION: This facility requires that certain bugs in the Release 5 TOPS-20 AR- PANET monitor be fixed. THE DEFINE COMMAND THE DEFINE COMMAND THE DEFINE COMMAND _________ ___ ______ ___ ______ Syntax: DEFINE macroname [set-option [, set option [...]]] The DEFINE command is available in KERMIT-20 for building "macros" of SET com- mands. The macro name can be any keyword-style character string, and the set options are anything you would type after SET in a SET command; several set op- tions may be strung together, separated by commas. Example: define notimeout send timeout 0, receive timeout 0 DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 63 Macro definitions may not include macro names. You can list all your macros and their definitions with the SHOW MACROS command. You can list a particular _________ macro definition with HELP SET macroname. THE SHOW COMMAND THE SHOW COMMAND THE SHOW COMMAND ______ Syntax: SHOW [option] The SHOW command displays various information: DAYTIME Current date, time, phase of moon. DEBUGGING Debugging mode and log file in effect, if any. FILE-INFO Byte size for DEC-20 file i/o, incomplete file disposition. LINE TTY line, parity, duplex, handshake, escape character. Note that the DEC-20 does not keep a record of the baud rate of a TTY line. MACROS Definitions for SET macros. PACKET-INFO For incoming and outbound packets. Items under RECEIVE column show parameters for packets KERMIT-20 expects to receive, under SEND shows parameters for outgoing packets. TIMING-INFO Delays, retries, server NAK intervals. VERSION Program version of KERMIT-20. ALL (default) All of the above. THE STATISTICS COMMAND THE STATISTICS COMMAND THE STATISTICS COMMAND Give statistics about the most recent file transfer. For instance, here's what KERMIT-20 displayed after transmitting a short binary file, using repeated- character compression: Maximum number of characters in packet: 80 received; 80 sent Number of characters transmitted in 2 seconds Sent: 34 Overhead: 34 Received: 107 Overhead: -408 Total received: 141 Overhead: -374 Total characters transmitted per second: 70 Effective data rate: 2570 Baud Interpacket pause in effect: 0 sec DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 64 Timeouts: 0 NAKs: 0 Last JSYS error: Does not match switch or keyword Note that the data compression allowed the effective baud rate to exceed the actual speed of the communication line, which in this case happened to be 1200 baud. The "Last JSYS error" is a diagnostic message which is mainly useful for program debugging or problem reporting. THE LOG COMMAND THE LOG COMMAND THE LOG COMMAND ______ ________ Syntax: LOG [option [filespec]] Log the specified option to the specified file: SESSION During CONNECT, log all characters that appear on the screen to the specified file. The TTLINK process does the actual log- ging. The session log can be temporarily turned off during the remote session by typing the escape character followed by Q (for Quit logging), and turned on again by typing the escape character followed by R (for Resume logging). Default log is SESSION.LOG in the current directory. TRANSACTIONS During file transfer, log the progress of each file. The DEC-20 transaction log file looks like this: KERMIT-20 Transaction Log File, Monday, 27-February-198 18:40:13: Opened Log: PS:SAMPLE.LOG.1 18:40:31: -- Send Begins -- 8th bit prefixing: Off Block check type: 1 18:40:31: Opened File: PS:LOGIN.CMD.6 Sending As "LOGIN.CMD" Sent: 547 7-bit bytes 18:40:34: Closed PS:LOGIN.CMD.6 18:40:34: Send Complete 18:40:50: -- Receive Begins -- 8th bit prefixing: Off Block check type: 1 18:40:50: Opened: PS:AUTOEXEC.BAT.1 Written: 186 7-bit bytes 18:40:51: Closed: PS:AUTOEXEC.BAT.1 18:40:56: Closed Transaction Log Transaction logging is recommended for long or unattended file transfers, so that you don't have to watch the screen. The log DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 65 may be inspected after the transfer is complete to see what files were transferred and what errors may have occurred. Default log is TRANSACTION.LOG in the current directory. SESSION is the default option. Thus the command "LOG" alone will cause CONNECT sessions to be logged in SESSION.LOG in the current directory. 6.5. The TTLINK Program 6.5. The TTLINK Program 6.5. The TTLINK Program KERMIT-20 accomplishes the CONNECT command by running a separate program called TTLINK as an inferior process. KERMIT constructs a command line based upon the current settings for line number, parity, duplex, "IBM mode", session logging, and so forth, and "feeds" this line to TTLINK. Once started, the TTLINK process can be restarted repeatedly, remembering its previous settings. TTLINK has the following commands: _____ ____ ______ ________ ________ CONNECT (TO TTY) octal-line-number optional-switches STATUS Display current line number, duplex, log file, and escape character. HELP Print a help message. EXIT If you continue, previous defaults are preserved. Command line arguments are accepted. Escape character arguments are: _____ blank Nothing (null command) C Close Connection, "escape" back to DEC-20 S Show Status of Connection P PUSH to new Exec Q Quit logging R Resume logging B Send a BREAK signal ? Help ______ _________ ______ escape character itself Send the escape character itself. Initial defaults for CONNECT are FULL DUPLEX, escape character = CTRL-Y, and PARITY NONE. No initial default for line or logfile. Defaults for subsequent CONNECT commands become whatever was specified in the most recent CONNECT com- mand, so that you can escape back to the DEC-20 and reconnect easily. Type HELP CONNECT and HELP BREAK for further information. DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 66 THE TTLINK CONNECT COMMAND THE TTLINK CONNECT COMMAND THE TTLINK CONNECT COMMAND _____ ____ ______ ________ ________ CONNECT (TO TTY) octal-line-number optional-switches The CONNECT command connects you to the specified line, with the specified op- tions. The options are specified as switches, each preceded by a slash, and followed by a colon and an argument. The valid switches are: /DUPLEX: FULL or HALF. If FULL, remote host echoes; if HALF, local host. /PARITY: NONE, MARK, SPACE, EVEN, or ODD. /LOGFILE: Name of file for logging transcript of remote session. _ /ESCAPE:n Octal value of an ASCII control character to be used as the es- cape character during CONNECT. Examples: 1=CTRL-A, 34=CTRL-\. _ /SPEED:n See below. _ /BREAK-NULLS:n See below. Examples: _______ ____ ___ _ _____ ___ ________ connect 5 connect over TTY 5, using all defaults _______ ____ ___ __ ____ _____ ____ conn 17/duplex:half connect over TTY 17, with local echo _______ ____ ___ __ _______ ____ ______ c 33/parity:even connect over TTY 33, sending even parity _____ ___ ________ ___ __ ________ c 77/dup:h/par:mark/esc:37 shows how switches may be combined During CONNECT, all characters that you type will be transmitted to the remote system except for your escape character. If you type your escape character, TTLINK will wait for you to type another character, and that character will be interpreted as shown above. These characters may be either upper or lower case. If you type any character not on this list, TTLINK will beep at you. SENDING A BREAK SIGNAL SENDING A BREAK SIGNAL SENDING A BREAK SIGNAL Sending a BREAK signal to the remote host can be a tricky business, because the DEC-20 supplies no function to do this. Therefore, TTLINK simulates a BREAK by temporarily setting the speed of the line to 50 baud, sending several null (ASCII 0) characters, and then setting the speed back to what it was. But TTLINK has no way of knowing what the speed was unless you tell it, because TOPS-20 does not remember the speed of a remote line. Therefore, if you intend to send a BREAK signal to the remote host, you must use the following switch on the CONNECT command: _ /SPEED:n The argument is a decimal number which is the current speed of the line, such as 300 or 1200. DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 67 If you omit this switch, TTLINK will not try to send a BREAK. You may transmit a BREAK by typing the BREAK key on your terminal ONLY IF YOU ARE DIRECTLY CONNECTED TO THE SYSTEM WHICH IS RUNNING TTLINK (if your are con- nected through a network, the BREAK generated by your terminal will not get through to TTLINK). In any case, you can always tell TTLINK to send a BREAK by typing your escape character followed by the letter B. If you find that your BREAK signal is not recognized correctly on the remote system, you may have to adjust the number of NULL characters that are sent; the following CONNECT command switch allows you to do this. _ /BREAK-NULLS:n The default number of NULLs transmitted is 3. If that is not enough, the remote system may not react. If that number is too high, the remote system may sense two or more BREAKs. 6.6. Examples 6.6. Examples 6.6. Examples Here are a few examples of the use of KERMIT-20. Text entered by the user is underlined. ______ _________ Remote_Operation The following example shows use of KERMIT-20 as a server from an IBM PC. In this example, the user runs KERMIT on the PC, connects to the DEC-20, and starts KERMIT-20 in server mode. From that point on, the user need never con- nect to the DEC-20 again. In this example, the user gets a file from the DEC-20, works on it locally at the PC, and then sends the results back to the DEC-20. Note that the user can leave and restart KERMIT on the PC as often as desired. ______ A>kermit _______ Kermit-86>connect @ ______ @kermit TOPS-20 KERMIT version 4(200) ______ Kermit-20>server DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 68 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. ___ ^[C ___ _______ Kermit-86>get_foo.txt ___ ________ _____ _____ The transfer takes place. ____ Kermit-86>exit A> ____ _______ __ ________ A>edit_foo.txt ; (or whatever...) A> ______ A>kermit ____ _______ Kermit-86>send_foo.txt ___ ________ _____ _____ The transfer takes place. ___ Kermit-86>bye A> The next example shows the special procedure you would have to use in order to send a mixture of text and binary files from a PC (or an 8-bit-byte system) to the DEC-20. Note that in this case, it's more convenient to avoid server mode. _______ Kermit-86>connect @ ______ @kermit TOPS-20 KERMIT version 4(200) _______ Kermit-20>receive ___ ^]C ____ _____ Kermit-86>send_*.txt _______ _____ ___ ____ Textual files are sent. _______ Kermit-86>connect ___ ____ ________ _ Kermit-20>set_file_bytesize_8 _______ Kermit-20>receive ___ ^]C ____ _____ Kermit-86>send_*.exe ______ _____ ___ ____ Binary files are sent. DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 69 _______ Kermit-86>connect ____ Kermit-20>exit ______ @logout ___ ^]C ____ Kermit-86>exit A> _____ _________ Local_Operation In this example, a program DIAL is used to direct an autodialer to call another computer (a DEC-10 at Stevens Institute of Technology); once the connection is made, DIAL starts KERMIT with an implicit CONNECT command for the appropriate communication line. DIAL is not part of KERMIT; if your system has an autodialer, there will be some site-specific procedure for using it. ____ @dial ____ _______ Dial>dial_stevens STEVENS, 1-(201) 555-1234, baud:1200 [confirm] Dialing your number, please hold... Your party is waiting on TTY11:. @ ______ @kermit TOPS-20 KERMIT version 4(200) ___ ____ __ Kermit-20>set_line_11 _______ Kermit-20>connect [TTLINK: Connecting to remote host over TTY11:, type C to return] CONNECTING TO HOST SYSTEM. Stevens T/S 7.01A(10) 20:20:04 TTY41 system 1282 Connected to Node DN87S1(101) Line # 57 Please LOGIN or ATTACH ___ _____ .log_10,35 JOB 51 Stevens T/S 7.01A(10) TTY41 Password: 20:20 15-Dec-83 Thur _ __________ .r_new:kermit TOPS-10 KERMIT version 2(106) ______ Kermit-10>server DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT DECSYSTEM-20 KERMIT Page 70 [Kermit Server running on the DEC 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.] ___ ^YC [TTLINK: Connection Closed. Back at DEC-20.] ___ ____ ________ _ Kermit-20>set_file_bytesize_8 ___ __________ Kermit-20>get_setdtr.cmd ^A for status report, ^X to cancel file, ^Z to cancel batch. __ SETDTR.CMD.7 ^A Receiving SETDTR.CMD.7, file bytesize 8 (repeated character compression) At page 1 Files: 0, packets: 1, chars: 66 NAKs: 0, timeouts: 0 .[OK] Kermit-20>bye Job 51 User F DA CRUZ [10,35] Logged-off TTY41 at 20:22:58 on 15-Dec-83 Runtime: 0:00:01, KCS:33, Connect time: 0:02:39 Disk Reads:72, Writes:4, Blocks saved:160 .... _ Hangup? y Click. Call duration was 193 seconds to area 201. ____ Dial>exit 6.7. Installation 6.7. Installation 6.7. Installation KERMIT-20 is built from a single MACRO-20 source file, 20KERMIT.MAC. It re- quires the standard DEC-distributed tools MONSYM, MACSYM, and CMD; the follow- ing files should be in SYS: -- MONSYM.UNV, MACSYM.UNV, MACREL.REL, CMD.UNV, and CMD.REL. The program should work on all TOPS-20 systems as distributed, but many customizations are possible. The site manager may wish to change various default parameters on a site-wide basis; this may be done simply by changing the definitions of the desired symbols, under "subttl Definitions", and reas- sembling. The most notable site dependency is the definition of "SET IBM". As dis- tributed from Columbia, KERMIT-20 defines "SET IBM" in a built-in SET macro definition as "parity mark, duplex half, handshake xon". This definition may be found at MACTAB+1, near the end of the impure data section. It may be changed or deleted, and the program reassembled. Sites that do not have ARPANET may wish to delete the TAC-BINARY entries from SET command tables, SETABL and SETHLP. VAX/VMS KERMIT VAX/VMS KERMIT VAX/VMS KERMIT Page 71 CHAPTER 7 CHAPTER 7 CHAPTER 7 VAX/VMS KERMIT VAX/VMS KERMIT VAX/VMS KERMIT _______ Authors: Bob McQueen, Nick Bush, Stevens Institute of Technology ________ Language: Bliss-32, Common Bliss _______ Version: 2.0 ____ Date: November 1983 KERMIT for the Digital Equipment Corporation VAX/VMS system is called "KERMIT-32" since the VAX is DEC's 32-bit line of computers. KERMIT-32 can be run from SYS$SYSTEM:. It will prompt for input from SYS$COMMAND:. Kermit-32 can be run in either local or remote modes. In remote mode, trans- fers take place over the controlling terminal line. Ususally, Kermit-32 is used in remote mode as a "server", meaning that it will accept commands from the other Kermit. In local mode, Kermit-32 will perform transfers over a ter- minal line other than the controlling terminal. In local mode, Kermit-32 is capable of giving commands to a "server" Kermit. Note that in order to use Kermit-32 in local mode, the protection code for the terminal to be used must allow the user access. This is set by the system manager. Kermit-32 is put into local mode by using the SET LINE TTcnn: command. Currently, VMS Kermit does not allocate the terminal line you are using for CONNECT or transfers. Therefore, when going between CONNECT and SEND or RECEIVE, VMS hangs up the phone for you. This is easily solved by using the DCL ALLOCATE command to allocate the terminal line before entering Kermit. VMS KERMIT implements a large subset of "idea" KERMIT, for both remote and local operation. Here is a summary of the commands of KERMIT-32: ___ CONNECT [dev:] The CONNECT command will allow you to connect as a virtual terminal over the line that was specified by the SET LINE command, or to the terminal line specified in the command. The terminal line must be one which is accessible to the users process. This means that the ap- plicable protection code for the terminal must have been set to allow your process to access it (done by the system manager). The format of the CONNECT command is: Kermit-32>CONNECT or __ Kermit-32>CONNECT TTcn: __ where TTcn: is the terminal line name to be used. _______ _______ HELP [keyword [keyword...]] Give VMS-style help on KERMIT commands. VAX/VMS KERMIT VAX/VMS KERMIT VAX/VMS KERMIT Page 72 EXIT, QUIT Exit from Kermit-32. RECEIVE The RECEIVE command is used to put Kermit-32 into remote mode waiting for a single file transfer transaction, or to have a local Kermit-32 request a file from the remote Kermit. If no file specification is given, Kermit-32 will wait for a file transfer initialization sequence from the other Kermit. This is most useful if the other Kermit does not support local server commands. In order for a file specification to be given, Kermit-32 must be running as a local Kermit (i.e. a SET LINE command must have been done). Kermit-32 will then request the other Kermit (which must be running in server mode) to transfer the specified file (or set of files) to Kermit-32. The file specification must be in the format of the system on which the server Kermit is run- ning. The format of the command is: Kermit-32>RECEIVE or ____ _____________ Kermit-32>RECEIVE file-specification where "file-specification" is any valid file specification on the sys- tem on which the server Kermit is running. ________ GET filespec ________ This command is identical to the RECEIVE filespec command. It is now the preferred command to cause the other Kermit (when running in server mode) to transmit a file to Kermit-32. BYE This command will cause Kermit-32 (when in local mode) to tell the other Kermit (which should be in server mode) to exit from Kermit and, if applicable, terminate its job (or process, etc.). When Kermit-32 receives the acknowledgement that this is being done, it will exit to VMS. FINISH This command will cause Kermit-32 (when in local mode) to tell the other Kermit (which should be in server mode) to exit from Kermit. After receiving the acknowledgement that this is being done, Kermit-32 will prompt for another command. LOGOUT This command will cause Kermit-32 (when in local mode) to tell the other Kermit (which should be in server mode) to exit from Kermit and, if applicable, terminate its job (or process, etc.). When Kermit-32 receives the acknowledgement that this is being done, it will prompt for another command. SEND The SEND command will allow you to send a file(s) to the other Kermit. The SEND command will allow file wild card processing as is found in VMS. If Kermit-32 is running in remote mode, the file will be sent on the controlling terminal line after waiting the number of seconds specified by the SET DELAY command. This gives the user time to escape VAX/VMS KERMIT VAX/VMS KERMIT VAX/VMS KERMIT Page 73 back to the other Kermit and issue a receive command. If Kermit-32 is running in local mode, the file will be sent immediately on the ter- minal line specified by the SET LINE command. The command format is: ____ _____________ Kermit-32>SEND file-specification Where "file-specification" is any normal VAX/VMS file specification. SERVER This command will cause Kermit-32 to enter server mode. The other Ker- mit can then issue server commands to send and receive files without having to give SEND or RECEIVE commands to Kermit-32. Kermit-32 may be put into SERVER mode while running as either a remote Kermit (transmitting over the controlling terminal line), or as a local Kermit (transmitting over a terminal specified by a SET LINE command). Note that in order to correctly receive binary files while in SERVER mode, a SET FILETYPE BINARY must be done first. At this time there is no way for Kermit-32 to determine whether an incoming file is ASCII or binary. The format of the command is: Kermit-32>SERVER STATUS The current status of Kermit-32 will be displayed. This includes the number of characters that have been sent and received from the remote Kermit. Also included is an estimate of the effective baud rate of THE SET COMMAND THE SET COMMAND THE SET COMMAND The SET command is used to set various parameters in Kermit. _______ BLOCK_CHECK_TYPEkeyword where keyword is one of: __ 1_CHARACTER_CHECKSUM or ONE_CHARACTER_CHECKSUM __ 2_CHARACTER_CHECKSUM or TWO_CHARACTER_CHECKSUM __ 3_CHARACTER_CRC_CCITT or THREE_CHARACTER_CRC_CCITT DEBUGGING The SET DEBUGGING command is used to set the debug type out on the user's terminal. The command will accept either the keywords ON or OFF. Kermit-32 can only do debugging type out when running as a local Kermit (SET LINE command done). This is because the debugging type out would interfere with the file transfer if it were sent to the controlling terminal line in remote mode. _____ Kermit-32>SET DEBUGGING state Where state is either 'ON' or 'OFF'. DELAY The DELAY parameter is the number of seconds to wait before sending data after a SEND command is given. This is used when VAX/VMS KERMIT VAX/VMS KERMIT VAX/VMS KERMIT Page 74 Kermit-32 is running in remote mode to allow the user time to escape back to the other Kermit and give a RECEIVE command. ______ __ _______ Kermit-32>SET DELAY number-of-seconds Where number of seconds is the (decimal) number of seconds to wait before sending data. ESCAPE This command will set the escape character for the CONNECT processing. The command will take the octal value of the character to use as the escape character. This is the charac- ter which is used to "escape" back to Kermit-32 after using the CONNECT command. It defaults to CTRL-] (octal 35). It is usually a good idea to set this character to something which is not used (or at least not used very much) on the system being to which Kermit-32 is CONNECTing. _____ _________ _____ Kermit-32>SET ESCAPE octal-character-value _____ _________ _____ where octal-character-value is the ASCII value of the character to use as the escape character (in octal). FILE_TYPE This command will set the file type that Kermit is receiving. A file type of ASCII should be used to receive text files which are to be used as text files on the VMS system. The file type BINARY should be used for binary files, such as CP/M .COM files, which need to be kept in a format that allows the file to be returned without any changes. ____ Kermit-32>SET FILE_TYPE type ____ where type is one of: ASCII File type ASCII is for text files. BINARY File type BINARY is for non-text files. Note that binary files which are generated on a VMS system cannot be transferred to another VMS system without losing file attributes. This means that (for example), an .EXE file cannot be transmitted with Kermit-32. (This problem should be resolved in a future version of Kermit). IBM_MODE For communicating with IBM mainframes; sets parity MARK, hand- shake XON, and local echo during CONNECT. _______ Kermit-32>SET IBM_MODE keyword _______ where keyword is either ON or OFF. INCOMPLETE_FILE_DISPOSITION VAX/VMS KERMIT VAX/VMS KERMIT VAX/VMS KERMIT Page 75 The SET INCOMPLETE_FILE_DISPOSITION allows the user to deter- mine what is done with a file that is not completely received. _______ Kermit-32>SET INCOMPLETE_FILE_DISPOSITION keyword _______ where keyword is either DISCARD or KEEP. LINE This will set the terminal line that you are using. The ter- minal line must be one which is accessible to the user's process. This means that the applicable protection code for the terminal must have been set to allow your process to access it (done by the system manager). You should also ALLOCATE the line from DCL before giving this command. ______ Kermit-32>SET LINE device: The device must be a terminal line (e.g. TTA0:). LOCAL_ECHO The SET LOCAL_ECHO command specifies whether characters should be echoed locally when CONNECTing to another system. _______ Kermit-32>SET LOCAL_ECHO keyword where keyword is either ON (local echo) or OFF (full duplex, normal case). MESSAGE This command sets the type of typeout Kermit-32 will do during transfers in local mode. Kermit-32 can type out the file specification being transferred, the packet numbers being sent an received, both or neither. The default is to type file specifications but not packet numbers. ____ _______ Kermit-32>SET MESSAGE type keyword Where type is either FILE or PACKET, and keyword is either ON or OFF. PARITY This command determines the type of parity to use on the trans- mission line. Kermit-32 normally uses characters which consist of eight data bits with no parity bit. _______ Kermit-32>SET PARITY keyword where keyword is NONE (default), MARK, SPACE, EVEN, or ODD. If any parity other than NONE is specified, 8th-bit-prefixing will be requested for transmission of binary files. RETRY This command sets the maximum number of times Kermit-32 should try to send a specific packet. _______ ______ Kermit-32>SET RETRY keyword number VAX/VMS KERMIT VAX/VMS KERMIT VAX/VMS KERMIT Page 76 _______ where keyword is either INITIAL_CONNECTION (for initial connec- ______ tion packet) or PACKET (for all other packets), and number is the decimal number of retries to attempt. RECEIVE It is possible to set various parameters associated with the receiving of the data from the remote Kermit. SET RECEIVE will enable you to set the various receive parameters. PACKET_LENGTH This will set the receive packet length, be- tween 10 and 96. The default value is 80. Kermit-32>SET RECEIVE PACKET_LENGTH 60 PADDING This command will set the number of padding characters that will be sent to the other Ker- mit. The default value is 0. _ Kermit-32>SET RECEIVE PADDING n _ Where n is the decimal number of padding characters to use. PADCHAR This parameter is the padding character that is sent to the remote Kermit. The parameter must be an octal number in the range of 0 to 37 or 177. All other values are illegal. The default value is 0 (an ASCII NUL). ___ Kermit-32>SET RECEIVE PADCHAR nnn ___ where nnn is the ASCII value of the character to be used as a pad character (in octal). START_OF_PACKET This command will set the start of packet character for Kermit. The start of packet character must be in the range of 0 to 36 oc- tal. The default value is 1 (ASCII SOH, CTRL-A). This value should only be changed if absolutely necessary. It must be set the same in both Kermits. Kermit-32>SET RECEIVE START_OF_PACKET 3 TIMEOUT This will set the number of seconds before Kermit-32 will time out the attempt to receive a message. This time out is used to handle transmission errors which totally lose a mes- sage. The default value is 15 seconds. _ Kermit-32>SET RECEIVE TIMEOUT n _ where n is the number of seconds to wait for a VAX/VMS KERMIT VAX/VMS KERMIT VAX/VMS KERMIT Page 77 message (in decimal). END_OF_LINE This will set the end of line character the Kermit-32 expects to receive from the remote Kermit. This is the character which terminates a packet. The default value is 15 (ASCII CR, CTRL-M). ___ Kermit-32>SET RECEIVE END_OF_LINE nnn ___ where nnn is the ASCII value of the character to use for the end of line character (in octal). QUOTE This will set the quoting character that Kermit-32 will expect on incoming messages. This is the character used to quote control characters. The default value is 43 (ASCII "#"). ___ Kermit-32>SET RECEIVE QUOTE nnn ___ where nnn is the ASCII value of the quoting character (in octal). SEND It is possible to set various parameters associated with the receiving of the data from the remote Kermit. SET SEND will enable you to set the various SEND parameters. These parameters should not normally be set, since as part of the transfer initialization process the two Kermit's exchange their RECEIVE parameters. The capability of setting these parameters is provided so that the transfer initialization can be com- pleted even if the default parameters are not correct. PACKET_LENGTH This will set the SEND packet length. The value for this parameter must be between 10 and 96. Packet lengths outside of this range are illegal. The default value is 80. PADDING This command will set the number of padding characters that will be sent to the other Ker- mit. The default value is 0. PADCHAR This parameter is the padding character that is sent to the remote Kermit. The parameter must be an octal number in the range of 0 to 37 or 177. All other values are illegal. The default value is 0 (an ASCII NUL). START_OF_PACKET This command will set the start of packet character for Kermit. The start of packet character must be in the range of 0 to 36 oc- VAX/VMS KERMIT VAX/VMS KERMIT VAX/VMS KERMIT Page 78 tal. The default value is 1 (ASCII SOH, CTRL-A). This value should only be changed if absolutely necessary. It must be set the same in both Kermit's. TIMEOUT This will set the number of seconds before Kermit-32 will time out a message it has sent to the other Kermit. message. This time out is used to handle transmission errors which totally lose a message. The default value is 15 seconds. END_OF_LINE This will set the end of line character the Kermit-32 will send to the remote Kermit. This is the character which terminates a packet. The default value is 15 (ASCII CR, CTRL-M). QUOTE This will set the quoting character that Kermit-32 will expect on incoming messages. This is the character used to quote control characters. The default value is 43 (ASCII "#"). ___ ____ _______ The_SHOW_Command The SHOW command will allow you to show the various parameters that are set with the SET command. ALL The SHOW ALL command will cause all of the parameters to be listed. BLOCK_CHECK_TYPE This command will type out what type of block check is being requested. COMMUNICATIONS This command will type out the communcations line related parameters. This includes the terminal line being used, the parity type, etc. DEBUGGING The SHOW DEBUGGING command will print the state of the debug- ging flag. DELAY This will display the number of seconds delay that Kermit will use before attempting to send or receive a file. ESCAPE This will display the current escape character for the CONNECT processing. FILE_PARAMETERS This will display the parameters related to files being used. This includes the file type and the incomplete file disposi- VAX/VMS KERMIT VAX/VMS KERMIT VAX/VMS KERMIT Page 79 tion. FILE_TYPE This will display the current file type that is used in sending the file to or receiving the from the micro computer. INCOMPLETE_FILE_DISPOSITION This will display the disposition of incompletely received files. LOCAL_ECHO This will display the status of the local echo flag. PACKET This will display the current settings of the send and receive packet parameters. PARITY This will display the current parity setting. SEND All of the send parameters will be displayed on the user's ter- minal. RECEIVE The current values of the RECEIVE parameters will be displayed on the user's terminal. Only the parmeters that can be set will be displayed. RETRY This command will show the maximum retry attempts that Kermit will attempt to send a message the remote. IBM VM/CMS KERMIT IBM VM/CMS KERMIT IBM VM/CMS KERMIT Page 80 CHAPTER 8 CHAPTER 8 CHAPTER 8 IBM VM/CMS KERMIT IBM VM/CMS KERMIT IBM VM/CMS KERMIT ______ Author: Daphne Tzoar, Columbia University _______ __________ Version: ( unnumbered ) ____ Date: February 1983 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 con- taining other than ordinary letters, digits, punctuation, carriage returns, ___ tabs, and so forth) can not 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 FILENAME FILETYPE FILEMODE (abbreviated FN FT FM). FM is equivalent to a device specification on DEC or microcomputer systems (FN FT FM would translate to FM:FN.FT). 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: __ __ __ SEND fn ft [fm] 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 IBM VM/CMS KERMIT IBM VM/CMS KERMIT IBM VM/CMS KERMIT Page 81 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. Ex- amples: The command SEND CEN SPSS will send CEN SPSS A1. To send the same file located on your B disk, you must specify: SEND CEN SPSS B. SEND * FORTRAN will send all fortran files on your A disk. SEND ABC% EXEC will send all exec files with a four let- ter filename beginning with ABC. If you have the file PLOT SAS on your A disk and your B disk, SEND PLOT SAS * will send PLOT SAS A1. __ __ __ RECEIVE [fn ft [fm]] Receive the file(s) sent from the other Kermit. If a file specifica- tion 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 = = FM can be used.) Examples: To receive files using the filename(s) sent by the micro, use: RECEIVE. To save a file under a different name, specify: RECEIVE ABC FORTRAN. To save the file under the same name but on the B disk, specify: RECEIVE ABC FORTRAN B, or RECEIVE = = B. _________ _____ SET parameter value Set the parameter to the specified value. Legal Set commands are: ______ RECFM option Denotes the record format to be used when creating the file. Only fixed and variable length records are allowed, where vari- able is the default. Indicate the desired record format by ei- ther an F (fixed) or a V (variable). _______ ______ LRECL decimal-number Indicates the logical record length. The default is 80, and the maximum allowed is 256. _______ ______ QUOTE decimal-number The ASCII value of the control prefix 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). _______ ______ END decimal-number Indicates the ASCII value of 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). _______ ______ PAC decimal-number Allows the user to specify the packet size the micro should use IBM VM/CMS KERMIT IBM VM/CMS KERMIT IBM VM/CMS KERMIT Page 82 when sending to Kermit-CMS. The range is 26-94, where 94 is the default. _________ SHOW parameter 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. ? Lists all legal Kermit-CMS commands. This is a list of other salient facts about Kermit-CMS: 1. 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, SET ? will list all valid options for the SET command. 2. 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. 3. 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. 4. 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. 5. Since some Kermits do not send an error packet when they "abort", Kermit-CMS does not always know the micro has stopped sending it in- formation. 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 max- imum 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. 6. 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, IBM VM/CMS KERMIT IBM VM/CMS KERMIT IBM VM/CMS KERMIT Page 83 Kermit-CMS will immediately abort with an error of "Bad send-packet size." 7. While the IBM's communication front end processor translates all in- coming characters from ASCII terminals to EBCDIC, Kermit-CMS trans- lates 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 throu- ghout 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. 8. 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. 9. Kermit-CMS supplies the micro and the user with numerous error mes- sages. If the execution must be abnormally terminated, an error packet is sent to the micro before Kermit-CMS stops. The same mes- sage 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 be- cause 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: "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 max- imum 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 com- mands. "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 IBM VM/CMS KERMIT IBM VM/CMS KERMIT IBM VM/CMS KERMIT Page 84 (NAK) the packet. Also, if either the filename or filetype ex- ceeds 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. Work on VM/CMS Kermit continues. Planned future enhancements include: 1. 8-bit quoting, to allow binary files to pass through communication front ends that insist on using the 8th bit for parity. 2. Ability to act as a Kermit Server. 3. Ability to SET LINE, so that Kermit-CMS can be used as a local Ker- mit, connecting to a remote host over another communication port. UNIX KERMIT UNIX KERMIT UNIX KERMIT Page 85 CHAPTER 9 CHAPTER 9 CHAPTER 9 UNIX KERMIT UNIX KERMIT UNIX KERMIT _______ Authors: Bill Catchings, Bob Cattani, Chris Maio, Columbia University with fixes and contributions from many others. _____________ Documentation: Walter Underwood, Ford Aerospace (Palo Alto, CA) _______ Version: (unnumbered) ____ Date: October 1983 A sample, working implementation of the Kermit "kernel" was written in the C ______ ________ ______ language, and widely distributed in the Kermit Protocol Manual. 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 keyword 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, IBM 370-compatible mainframes under Amdahl UTS, and the SUN Microsystems MC68000-based and other workstations. UNIX filespecs are of the form dir1/dir2/dir3/ ... /filename ____ ____ where the tokens delimited by slashes form a path name, and by convention are each limited to 14 characters in length. The final token in a path is the ac- tual file name. By convention, it is of the form name.type, but there is noth- ing special about the dot separating name and type; to UNIX it's just another character, and there may be many dots in a filename. In the tradition of UNIX, here's the UNIX KERMIT "man page". NAME kermit - file transfer, virtual terminal over tty link SYNOPSIS kermit c[lbe] [line] [baud] [esc] kermit r[ddilb] [line] [baud] kermit s[ddilb] [line] [baud] file ... DESCRIPTION Kermit provides reliable file transfer and primitive virtual terminal communication between machines. It has been imple- mented on many different computers, including microprocessors (see below). The files transferred may be arbitrary ASCII data (7-bit characters) and may be of any length. The file transfer protocol uses small (96 character) checksummed packets, with ACK/NACK responses and timeouts. Kermit currently uses a five UNIX KERMIT UNIX KERMIT UNIX KERMIT Page 86 second timeout and ten retries. The arguments to kermit are a set of flags (no spaces between the flags), three optional args (which, if included, must be in the same order as the flags which indicate their presence), and, if this is a Send operation a list of one or more files. (It is similar in some way to the tar command structure). Kermit has three modes, Connect, Send, and Receive. The first is for a virtual terminal connection, the other two for file transfer. These modes are specified by the first flag, which should be c, s, or r, respectively. Exactly one mode must be specified. The d flag (debug) makes kermit a bit more verbose. The states kermit goes through are printed along with other traces of its operation. A second d flag will cause kermit to give an even more detailed trace. The i flag (image) allows slightly more efficient file transfer between Unix machines. Normally (on Kermits defined to run on Unix systems) newline is mapped to CRLF on output, CR's are discarded on input, and bytes are masked to 7 bits. If this is set, no mapping is done on newlines, and all eight bits of each byte are sent or received. This is the default for non-Unix kermits. The l flag (line) specifies the tty line that kermit should use to communicate with the other machine. This is specified as a regular filename, like "/dev/ttyh1". If no l option is specified, standard input is used and kermit assumes it is run- ning on the remote host (ie. NOT the machine to which your ter- minal is attached). The b flag (baud) sets the baud rate on the line specified by the l flag. No changes are made if the b flag is not used. Legal speeds are: 110, 150, 300, 1200, 2400, 4800, 9600. Note that this version of kermit supports this option on Unix sys- tems only. The e flag (escape) allows the user to set the first character of the two character escape sequence for Connect mode. When the escape character is typed, kermit will hold it and wait for the next character. If the next character is c or C, kermit will close the connection with the remote host. If the second character is the same as the escape character, the escape character itself is passed. Any character other than these two results in a bell being sent to the user's terminal and no characters passwd to the remote host. All other typed charac- ters are passed through unchanged. The default escape charac- ter is '^'. UNIX KERMIT UNIX KERMIT UNIX KERMIT Page 87 The file arguments are only meaningful to a Send kermit. The Receiving kermit will attempt to store the file with the same name that was used to send it. Unix kermits normally convert outgoing file names to uppercase and incoming ones to lower case (see the f flag). If a filename contains a slash (/) all outgoing kermits will strip off the leading part of the name through the last slash. EXAMPLE For this example we will assume two Unix machines. We are logged onto "unixa" (the local machine), and want to communi- cate with "unixb" (the remote machine). There is a modem on "/dev/tty03". We want to connect to "unixb", then transfer "file1" to that machine. We type: kermit clb /dev/tty03 1200 Kermit answers: Kermit: connected... Now we dial the remote machine and connect the modem. Anything typed on the terminal will be sent to the remote machine and any output from that machine will be displayed on our terminal. We hit RETURN, get a "login:" prompt and login. Now we need to start a kermit on the remote machine so that we can send the file over. First we start up the remote, (in this case receiving) kermit, then the local, (sending) one. Remem- ber that we are talking to unixb right now. We type: kermit r (there is now a Receive kermit on unixb) We type ^ (the escape character) and then the letter c to kill the local (Connecting) kermit: ^C Kermit answers: Kermit: disconnected. We type: kermit slb /dev/tty03 1200 file1 Kermit answers: UNIX KERMIT UNIX KERMIT UNIX KERMIT Page 88 Sending file1 as FILE1 When the transmission is finished, kermit will type either "Send complete", or "Send failed.", depending on the success of the transfer. If we now wanted to transfer a file from unixb (remote) to unixa (local), we would use these commands: kermit clb /dev/tty03 1200 _________ __ _____ (connected to unixb) kermit s file9 __ _____ _ ___ _______ _ ^c (up-arrow c not control-c) _______ __ _____ _____ (talking to unixa again) kermit rl /dev/tty03 1200 After all the transfers were done, we should connect again, log off of unixb, kill the Connect kermit and hang up the phone. FEATURES Kermit can interact strangely with the tty driver. In par- ticular, a tty with "hangup on last close" set (stty hup), will reset to 300 Baud between kermit commands. It will also hang up a modem at that time. It is better to run with "stty -hup", and use "stty 0" to explicitly hang up the modem. The KERMIT Protocol uses only printing ASCII characters, Ctrl-A, and CRLF. Ctrl-S/Ctrl-Q flow control can be used "underneath" the Kermit protocol (TANDEM line discipline on Berkeley Unix). Since BREAK is not an ASCII character, kermit cannot send a BREAK to the remote machine. On some systems, a BREAK will be read as a NUL. This kermit does have timeouts when run under Unix, so the protocol is stable when communicating with "dumb" kermits (that don't have timeouts). ______ ____ ______ DIAGNOSTICS cannot open device The file named in the line argument did not exist or had the wrong permissions. ___ ____ _____ bad line speed The baud argument was not a legal speed. _____ ___ ______ ____ Could not create file A Receive kermit could not create the file being sent to it. _______ __ _______ __ nothing to connect to A Connect kermit was started without a line argument. PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 89 CHAPTER 10 CHAPTER 10 CHAPTER 10 PC-DOS AND MS-DOS KERMIT-86 PC-DOS AND MS-DOS KERMIT-86 PC-DOS AND MS-DOS KERMIT-86 _______ Program: Daphne Tzoar, Columbia University, with contributions from Jeff Damens (Columbia), Dave King (CMU), Herm Fischer (Litton Data Systems), and others. _____________ Documentation: Frank da Cruz, Columbia University; Herm Fischer, Litton Data Sys- tems (Van Nuys CA) _______ Version: 2.25 ____ Date: February 1984 KERMIT-86 is a program that implements the KERMIT file transfer protocol for the IBM PC and several other machines using the same processor family (Intel 8088 or 8086) and operating system family under PC-DOS or MS-DOS (henceforth referred to collectively as MS-DOS), versions 1.1, 2.0, and 2.1. This section will describe the things you should know about the MS-DOS file system in order to make effective use of KERMIT, and then it will describe the KERMIT-86 program. MS-DOS KERMIT runs on a variety of systems, including the IBM PC and XT, the the Heath/Zenith 100, HP-150, the Seequa Chameleon, the Victor 9000, the Tandy 2000, the Compaq Portable, the Columbia MPC, and others. This document con- centrates on the IBM PC/XT implementation; the others will be (possibly complete) subsets of that (see Section 10.5 for details about support for other MS DOS systems). 10.1. The MS-DOS File System 10.1. The MS-DOS File System 10.1. The MS-DOS File System The features of the MS-DOS file system of greatest interest to KERMIT users are the form of the file specifications, and the distinction between pre-MS-DOS 2.0 file names and newer file names which allow directory paths. MS-DOS FILE SPECIFICATIONS MS-DOS FILE SPECIFICATIONS MS-DOS FILE SPECIFICATIONS MS-DOS file specifications are of the form DEVICE:\PATHNAME\NAME.TYPE where the DEVICE is a single character identifier (e.g., A for the first floppy disk, C for the first fixed disk, D for a RAM disk emulator), PATHNAME is up to 63 characters of identifier(s) (up to 8 characters each) surrounded by reverse slashes (or ".." for parent or "." for current directory), NAME is an iden- tifier of up to 8 characters, and TYPE is an identifier of up to 3 characters in length. Device and pathname may be omitted. Pathname is normally omitted, and cannot be specified for MS-DOS 1.x or with those commands which allow MS-DOS 1.x use (e.g. pathnames can only be accepted by commands which are specific to MS-DOS 2.x). Device and directory pathnames, when omitted, default to the user's current (or "defaulted") disk and directory path (path="."). PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 90 Thus NAME.TYPE is normally sufficient to specify a file, and only this infor- mation is sent along by KERMIT-86 with an outgoing file. The device, path, name, and type fields may contain uppercase letters, digits, and the special characters "-" (dash), "_" (underscore), and "$" (dollar sign). (For use only among MS-DOS processors, additional filename special characters allowed are "#&!%(){}'`". DOS 1.x allows others as well.). There are no im- bedded or trailing spaces. Other characters may be not be included within the MS-DOS environment (e.g. quoted characters are not permissible). The fields of the file specification are set off from one another by the punctuation in- dicated above. The device field specifies a physical or "logical" device upon which the file is resident. The directory pathname identifies an area on the device, for in- stance the area belonging to the logical ownership of the file. KERMIT-86 does not transmit the device or pathname directory fields to the target system, and does not attempt to honor device or directory fields that may appear in incom- ing file names. The name field is the primary identifier for the file. The type, also called the "extension", is an indicator which, by convention, tells what kind of file we have. For instance FOO.BAS is the source of a BASIC program named FOO; FOO.OBJ might be the relocatable object module produced by compiling FOO.BAS; FOO.EXE could an executable program produced by linking FOO.OBJ, and so forth. The MS-DOS allows a group of files to be specified in a single file specifica- tion by including the special "wildcard" characters, "*" and "?". A "*" matches any string of characters from the current position to the end of the field, including no characters at all; a "?" matches any single character. Here are some examples: *.BAS All files of type BAS (all BASIC source files) in the current direc- tory. FOO.* Files of all types with name FOO. F*.* All files whose names start with F. F?X*.* All files whose names start with F and contain X in the third position, followed by zero or more characters. ?.* All files whose names are exactly one character long. Wildcard notation is used on many computer systems in similar ways, and it is the mechanism most commonly used to instruct KERMIT to send a group of files. KERMIT-86 uses the ? character for help while commands are being typed, so the single-character wildcard in KERMIT commands is = rather than ?, for example Kermit-86>send =.* The KERMIT-86 user must bear in mind that other (non-MS-DOS) systems use dif- PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 91 ferent wildcard characters; for instance KERMIT-20 uses % instead of the ? as the single character wildcard. When using KERMIT-86 to request a wildcard file group from a KERMIT-20 server, the Kermit-86 "=" must be replaced by DEC-20 "%" characters. TEXT FILES AND BINARY FILES TEXT FILES AND BINARY FILES TEXT FILES AND BINARY FILES The MS-DOS systems store files as bulk collections of 8 bit bytes, with no peculiar differences between text, program code, and binary files. Since a non-MS-DOS receiving system might need to know file type distinctions, the user might need to use various SET functions on the remote system to inform it that the incoming file is of some particular (non-default) type. In transmitting files between KERMIT-86'es, regardless of file contents, the receiving MS-DOS system is equally capable of processing text, code, and data (and is, in fact, not knowledgable of the usage of the bytes in the file). ASCII files are presumed to have recognizable characteristics (carriage returns and linefeeds delimiting lines, form feeds delimiting pages, and control-Z's delimiting the end of file), though all internal bit codes are transmitted. Receiving non-MS-DOS systems may well get confused when presented with nonstan- dard ASCII files. Files produced by EASYWRITER or Word Star, for example, may need preprocessing prior to transmission by commonly available "exporter" programs, to convert them to conventional ASCII formats. Spreadsheet data files, and dBASE II files need special formatting to be meaningful to non- MS-DOS recipients (though they can be transmitted between MS-DOSes with KERMIT-86's). Furthermore, those word processors storing formatting data at the end of the file, after the control-Z and before physical end (such as BLUE or Easy Writer), will need to be told to strip the formatting data, lest they confuse non-MS-DOS recipients. 10.2. Program Operation 10.2. Program Operation 10.2. Program Operation KERMIT-86's prompt is "Kermit-86>". KERMIT-86 can run interactively to issue several commands, like this: A> ______ A>kermit MS DOS Kermit V2.25 ____ _____ Kermit-86>send_foo.* _____________ ________ _____ ___ _____ _____ ____ informational messages about the files being sent ______ Kermit-86>status _______ ______ _____________ ____ ___ _________ various status informational data are displayed _______ Kermit-86>receive PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 92 _____________ ________ _____ ___ _____ _____ ________ informational messages about the files being recieved ____ Kermit-86>exit A> During interactive operation, you may use the help ("?") and recognition (ESC) features freely while typing commands. Command keywords may be abbreviated to their shortest prefix that sets them apart from any other keyword valid in that field. 10.3. MS DOS KERMIT Commands 10.3. MS DOS KERMIT Commands 10.3. MS DOS KERMIT Commands MS DOS KERMIT implements a large subset of the local mode commands of "ideal" KERMIT. Not all of the following commands are available on all MS DOS systems, and some of the commands may work somewhat differently between DOS versions. THE SEND COMMAND THE SEND COMMAND THE SEND COMMAND ________ Syntax: SEND filespec The SEND command causes a file or file group to be sent from the MS-DOS to the other system. The filespec may contain a device designator, like A:, and the wildcard characters "*" and/or "=". The current release of Kermit-86 does not allow pathnames in this command. ________ If the filespec contains wildcard characters then all matching files will be sent, in directory search order (according to how your MS-DOS lists its direc- tory contents). If a file can't be opened for read access, standard MS-DOS recovery procedures will be available (these may necessitate restarting Kermit). ____ _______ _______ _________ SEND_Command_General_Operation Files will be sent with their MS-DOS filename and filetype (for instance FOO.TXT, no device or pathname). If you expect to be sending files whose names contain characters that would be illegal in filenames on the target system, and you know that Kermit on the target system does not have the ability to convert incoming filenames, you can copy and/or rename the file using MS-DOS commands prior to loading Kermit. Each file will be sent as a sequence of eight bit bytes. Once you give KERMIT-86 the SEND command, the name of each file will be dis- played on your screen as the transfer begins; a packet count and retry summary will be displayed, and informational messages displayed as appropriate. If the file is successfully transferred, you will see "COMPLETED", otherwise there PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 93 will be an error message. When the specified operation is done, the program will sound a beep. 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-86 will go on to the next file, whereas Control-Z will can- cel sending the entire group and return you to KERMIT-86 command level. A Control-C cancels sending immediately and returns you to the Kermit-86 prompt. THE RECEIVE COMMAND THE RECEIVE COMMAND THE RECEIVE COMMAND ________ Syntax: RECEIVE [filespec] The RECEIVE command tells KERMIT-86 to receive a file or file group from the other system. KERMIT simply waits for the file to arrive; this command is not to be used when talking to a KERMIT server (see GET). If the optional filespec is provided, store the incoming file under that name. The filespec may include a device designator, or may consist of only a device designator. The incoming file is stored on the default or specified device (current directory in DOS 2.0). If no name was specified, the name from the incoming file header packet is used; if that name is not a legal MS-DOS file name, KERMIT-86 will delete illegal or excessive characters from the name. If the optional filespec was provided, but more than one file arrives, the first file will be stored under the given filespec, and the remainder will be stored under their own names. If the incoming file name already exists, and FILE-WARNING is set, KERMIT-86 will change the incoming name (and inform you how it renamed it) so as not to obliterate the pre-existing file. If an incoming file does not arrive in its entirety, KERMIT-86 will normally discard it; it will not appear in your directory. You may change this behavior by using the command SET INCOMPLETE KEEP, which will cause as much of the file as arrived to be saved in your directory. If a file begins to arrive that you don't really want, you can attempt to can- cel it by typing Control-X; this sends a cancellation request to the remote Kermit. If the remote Kermit understands this request (this is an optional 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. If you type Control-C, you will be returned immediately to the Kermit-86> command level. PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 94 THE GET COMMAND THE GET COMMAND THE GET COMMAND ______ ________ Syntax: GET remote-filespec ______ ________ The GET remote-filespec command requests a remote KERMIT server to send the ______ ________ file or file group specified by remote-filespec. This command can be used only when KERMIT-86 is local, with a KERMIT server on the other end. This means that you must have CONNECTed to the other system, logged in, run KERMIT there, issued the SERVER command, and escaped back (e.g. ^]C) to the local KERMIT-86. The remote filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. (A remote PC server will accept device names, but not path names in the filespec.) As files ar- rive, their names will be displayed on your screen, along with packet traffic statistics and error messages. You may type ^X to request that the current in- coming file be cancelled, ^Z to request that the entire incoming batch be can- celled, and ^C to return immediately to the Kermit-86> prompt. 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. THE BYE COMMAND THE BYE COMMAND THE BYE COMMAND When running a local Kermit which is talking to a remote KERMIT server over a communications line, use the BYE command to shut down the server and log out its job, and exit from Kermit-86 to DOS. THE FINISH COMMAND THE FINISH COMMAND THE FINISH COMMAND Like BYE, FINISH shuts down the remote server. However, FINISH does not log out the server's job. You are left at Kermit-86 prompt level so that you can connect back to the job on the remote system. THE LOGOUT COMMAND THE LOGOUT COMMAND THE LOGOUT COMMAND The LOGOUT command is identical to the BYE command, except you will remain at Kermit-86 prompt level, rather than exit to DOS, so that you can establish another connection. PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 95 THE CONNECT COMMAND THE CONNECT COMMAND THE CONNECT COMMAND Syntax: CONNECT Establish an interactive terminal connection to the system connected to the currently selected communications port (COM1 or COM2) using full duplex echoing and no parity unless otherwise specified in previous SET commands. Get back to KERMIT-86 by typing the escape character followed by the letter C. The escape character is Control-] by default. When you type the escape character, several single-character commands are possible: ? Help - prints the commands allowed (as below). C Close the connection and return to KERMIT-86. S Status of the connection. B Break signal is sent to the port (on the PC/XT you may also type CTRL-BREAK to send a BREAK). ^] (or whatever you have set the escape character to be) Typing the escape character twice sends one copy of it to the connected host. You can use the SET ESCAPE command to define a different escape character, and on some systems (including the PC and XT) you can SET BAUD to change the baud rate, and SET PORT to switch between COM1 and COM2 In the connect mode, you can communicate with your autodialer, control the com- munications line, hang it up, and the like. (E.g., typing +++ to a Hayes-like modem will allow you to follow that by dialing or hang-up commands, when in the connection state). THE REMOTE COMMAND THE REMOTE COMMAND THE REMOTE COMMAND The REMOTE keyword is a prefix for a number of commands. It indicates that the command is to be performed by the remote Kermit, which must be running as a server. Note that not all Kermit servers are capable of executing all these commands. In case you send a command the server cannot execute, it will send back a message to the effect that the command is unknown to it. If the remote can execute the command, it will send the results to your screen. Here are the REMOTE commands which KERMIT-86 may issue: _________ CWD [directory] Change Working Directory on the remote host. Change the default source and destination area for file transfer. ________ DELETE filespec Delete the specified file or files on the remote host. In response, the remote host should display a list of the files that were or were not successfully deleted. ________ DIRECTORY [filespec] The remote host will provide a directory listing of the specified files. If no files are specified, then all files in PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 96 the default area will be listed. _________ DISK [directory] Provide a brief summary of disk usage in the specified area on the remote host. If none specified, the default or current area will be summarized. HELP The remote host tells what server functions it is capable of. _______ HOST [command] Send the command to the remote host's command processor for ex- ecution. ________ TYPE filespec Display the contents of the specified remote file or files on the screen. THE SET COMMAND THE SET COMMAND THE SET COMMAND _________ _____ Syntax: SET parameter [value] Establish or modify various parameters for file transfer or terminal connec- tion. You can examine their values with the STATUS command. The following parameters may be SET: BACKARROW Backarrow (backspace) key sends BACKSPACE or DELETE. BAUD Communications port line speed BELL The bell (beep) is normally sounded at the end of a trans- action. SET BELL OFF may be used to silence the bell. DEBUG Mode END-OF-LINE Character to replace CR at end of packets ESCAPE Character for Kermit-86 attention during terminal connection FILE-WARNING Warn if an incoming filename would conflict with an existing file name, and attempt to construct a new unique name for it. HEATH-19 Interpret Heath/Zenith-19 screen control codes. IBM Set up for communication with IBM mainframes: local echo (half duplex) during terminal emulation, line turnaround handshake during file transfer, and appropriate parity at all times. INCOMPLETE What to do with an incomplete file, KEEP or DISCARD. LOCAL-ECHO For terminal connection, OFF (remote echo, or full duplex) or ON (local echo, or half duplex) PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 97 PARITY Character parity to use, NONE (the default), ODD, EVEN, MARK, or SPACE PORT RS232 port to use for terminal connection or file transfer, COM1 (the default) or COM2 ___ _________ SET_BACKARROW _____ Syntax: SET BACKARROW state The IBM PC keyboard does not have a key marked DELETE (RUBOUT) or BACKSPACE. DELETE and BACKSPACE are two different ASCII characters (ASCII 127 and ASCI 8 respectively), and one or the other of these characters is normally used by host systems for deleting the characters just typed. Some systems use BACK- SPACE, some use DELETE. This command allows you to specify which character the backarrow key should transmit during terminal connection. BACKSPACE Backarrow (backspace) key transmits the backspace (BS) charac- ter, Control-H. CTRL-Backarrow sends DELETE. DELETE Backarrow (backspace) key transmits the delete (DEL, RUBOUT) character. CTRL-Backarrow sends BACKSPACE. In all cases, CTRL-H sends BACKSPACE. ___ ____ SET_BAUD ____ Syntax: SET BAUD rate Set terminal communications port speed to 300, 1200, 1800, 2400, 4800, 9600 or other common baud rates. The site default baud rate can be determined by the STATUS command immediately upon loading Kermit-86, and is displayed upon is- suing of the CONNECT command. ___ ____ SET_BELL _____ Syntax: SET BELL state ON Bell (beeper) sounds, at completion of transmissions and other times. OFF Bell (beeper) remains silent. PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 98 ___ _____ SET_DEBUG _____ Syntax: SET DEBUG state ON Record the packet traffic on your terminal. OFF Don't display debugging information (this is the default). If debugging was in effect, turn it off. ___ ___________ SET_END-OF-LINE _______ ______ _______ _ ___ __ Syntax: SET END-OF-LINE decimal number between 0 and 31 Change the character used at the end of outgoing packets to the character whose decimal ASCII value is given. The default is 13 (carriage return). ___ ______ SET_ESCAPE _________ Syntax: SET ESCAPE character Specify the control character you want to use to "escape" from remote connections back to KERMIT-86. The default is Control-]. ___ ____________ SET_FILE-WARNING ______ Syntax: SET FILE-WARNING option Specify what to do when an incoming file has the same name as an existing file in the default directory of the default device. If ON, Kermit will warn you when an incoming file has the same name as an existing file, and automatically rename the incoming file (as indicated in the warning) so as not to destroy (overwrite) the pre-existing one. If OFF, the incoming file replaces the pre-existing file. ___ ________ SET_HEATH-19 ______ Syntax: SET HEATH-19 option ON Specifies that, in the connect state, incoming characters are to be ex- amined for Heath/Zenith-19 terminal screen control commands (escape sequences), and if encountered, the commands are to be emulated on the PC screen. The Heath-19 codes are a superset of the popular DEC VT52 codes, so if your system does not support the Heath-19, you may tell your terminal type is VT52 (or one of the many VT52 compatibles). Heath-19 emulation is available on the IBM PC and XT. PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 99 OFF All incoming characters will be sent to the screen "bare", through DOS. If you have loaded a device driver into DOS for the CON: device, such as ANSI.SYS, then that driver will be able to interpret the codes it- self. Most non-IBM systems have their own screen control code inter- preter built into DOS or firmware. On the IBM systems, function keys and numeric keypad cursor control keys do not send characters when in the Heath-19 mode, unless the user has used a key redefinition package like ProKey. ___ ___ SET_IBM ______ Syntax: SET IBM option Specify setup for communication with an IBM mainframe. ON sets appropriate parity (per options used to assemble Kermit at your site, MARK as distributed), local echo for CONNECT, and half-duplex line handshaking (XON line turnaround). OFF reestablishes full duplex, nonparity operation. ___ __________ SET_LOCAL-ECHO ______ Syntax: SET LOCAL-ECHO option Specify mode for character echoing when in the CONNECT state. ON specifies that characters are to be echoed within Kermit (because neither the remote com- puter, nor the communications circuitry has been requested to echo). Generally IBM mainframes accessed directly (not via Telenet) will need this option (or the IBM option, q.v.) ON; generally most DEC sites and inter-PC communications will need it OFF. It is OFF by default, i.e. communication is assumed to be full duplex (remote echo). ___ ______ SET_PARITY _______ Syntax: SET PARITY keyword The choices for SET PARITY are NONE (the default), ODD, EVEN, MARK, and SPACE. NONE means no parity processing is done, and the 8th bit of each character can be used for data when transmitting binary files. You will need to SET PARITY to ODD, EVEN, MARK, or possibly SPACE when com- municating with a system, or over a network, that requires or imposes character parity on the communication line. For instance, GTE TELENET requires MARK parity. If you neglect to SET PARITY when the communications equipment re- quires it, the symptom may be that terminal emulation works partially, and file transfer does not work at all. PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 100 If you have set parity to ODD, EVEN, MARK, or SPACE, then KERMIT-86 will re- quest that binary files will be transferred using 8th-bit-prefixing. If 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 bi- nary files can be transmitted successfully. If NONE is specified, 8th-bit- prefixing will not be requested. ___ ____ SET_PORT ______ Syntax: SET PORT number Specify the port number to use for file transfer or CONNECT, COM1 or COM2. This command lets you use a different asynchronous adapter, or to switch be- tween two simultaneous remote sessions. THE STATUS COMMAND THE STATUS COMMAND THE STATUS COMMAND Report the status of parameters which can be modified by the SET commands. 10.4. Installation 10.4. Installation 10.4. Installation 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 16 (.EXE) of Kermit are distributed , along with some special "bootstrap" files, described below. The KERMIT.EXE file is converted by an assembler program on the PC, KFIX, 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 _______________ 16 The PC assembler's object (.OBJ) files are not printable, like CP/M hex files, so the Kermit-80 bootstrapping technique would not work here. PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 101 KERMIT.FIX. It is assumed that a copy of KERMIT.FIX is available to you on a mainframe computer. To download the file to the PC, two cooperating programs are run: a Fortran program, KSEND, on the mainframe and a Basic program, KGET, on the PC. These programs are very short; they are shown in their entirety below. KSEND reads a line at a time from KERMIT.FIX, 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 (.EXE) file. Here's the procedure: 1. 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, 17 using an editor ) from the listings below. 2. Log in on the mainframe. This could be tricky if you have no ter- minal 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. 3. Compile KSEND.FOR 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 KERMIT.FIX. On the DEC-20, for example: ______ __ ____ @define_5:_tty: ______ __ ____ @define_6:_tty: ______ __ __________ @define_7:_kermit.fix On a DECsystem-10, do something like: ______ ____ __ .assign_tty:_5: ______ ____ __ .assign_tty:_6: ______ ____ __ .assign_dsk:_7: ______ _____________________ .rename_for007.dat=kermit.fix On an IBM system under VM/CMS, _______ _ ____ _ _____ __ _____ _ .filedef_5_term_(_lrecl_64_recfm_f _______ _ ____ _ _____ __ _____ _ .filedef_6_term_(_lrecl_64_recfm_f _______ _ ____ ______ ___ _ _____ __ _____ _ ____ .filedef_7_disk_kermit_fix_(_lrecl_62_recfm_f_perm 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. _______________ 17 You'll also have to compile and load the KSEND program on the mainframe. PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 102 4. 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. 5. 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 62-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. 6. When transmission is complete, you'll see the BASIC "Ready" prompt again. Leave BASIC by typing SYSTEM. You should now have KERMIT.EXE on your PC. Try to run it. If you see the "Kermit-86>" prompt, try to CONNECT to the host mainframe and transfer some files. If Kermit doesn't run correctly, there may have been trans- mission errors, in which case you should start the process again from step 2 above. _________ _ _________ ____ __ _________ KSEND.FOR_-_Mainframe_Side_of_Bootstrap This is the mainframe side, KSEND, in transportable Fortran (it should run on both DEC and IBM mainframes): C This Fortran program should be run on the mainframe in conjunctio C with a Basic program on the IBM PC to transfer Kermit.Fix to the INTEGER A(62) 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(62A1) C Write to tty WRITE (6,25)A 25 FORMAT(' ',62A1,';') GOTO 100 90 CONTINUE PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 103 C Get final handshake WRITE (6,30) 30 FORMAT(' ',63('@')) STOP END The final @'s tell KGET that the transmission is done. This works because the technique for forming KERMIT.FIX ensures that the file will contain no @'s. ________ __ __ ____ __ _________ KGET.BAS_--_PC_Side_of_Bootstrap 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). 5 'Run this program on the PC in conjunction with a Fortran program on 6 ' mainframe to get Kermit to the PC 7 ' Daphne Tzoar , December 1983 8 ' Columbia University Center for Computing Activities 9 ' 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 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$(63,#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 >= 176 AND VALUE <= 191 THEN GOTO 140 ' Kill all illegal 120 IF VALUE >= 48 AND VALUE <= 63 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 >= 176 AND TWO <= 191 THEN GOTO 210 ' It's ok. 180 IF TWO >= 48 AND TWO <= 63 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 = 64 - SIZ 225 IF READIN = 0 GOTO 260 230 XTWO$=INPUT$(READIN,#1) ' Get rest of data 240 X$ = X$ + XTWO$ : X$ = LEFT$(X$,62) 250 PRINT X$ ' Optional - use this line to follow the transmiss 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 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 104 300 ' TO ONE DIGIT. 310 FOR A = 1 TO 31 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 -48 : ZNUM = ZNUM -48 ' 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 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 KERMIT.FIX file. Once you have the new KERMIT.FIX on your PC disk: 1. Rename KERMIT.EXE to something else, so you'll still have it in case something goes wrong. 2. Get or copy the program KEXE from the mainframe. Alternatively, you may modify KGET as follows: a. Remove lines 10 and 20. b. Change line 30 to 30 OPEN "KERMIT.FIX" FOR INPUT AS #1 c. Remove line 60, since we're not handshaking with a remote host any more. d. In line 70, change "63" to "62". e. Remove line 250, since there's no need to monitor a transmis- sion line. f. Change line 280 from "GOTO 60" to "GOTO 70". Save the modified KGET under a new name, say KEXE.BAS, 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). 3. You should now have a new, working version of KERMIT.EXE on your PC disk. PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 PC-DOS and MS-DOS KERMIT-86 Page 105 10.5. Adding Support for New Systems 10.5. Adding Support for New Systems 10.5. Adding Support for New Systems MS DOS Kermit supports many different systems. Like CP/M-80 KERMIT, this sup- port was added to the program piecemeal, at many sites, using conditional as- sembly. However, before allowing the program to grow into a complicated monolith like CP/M-80 KERMIT, we have broken the program up into separate modules, with system dependencies isolated into separate modules, consisting of compact collections of low-level primitives for console and port i/o. The last monolithic (single source file) release of MS DOS Kermit was 1.20. To this and earlier versions was added support for systems like the Seequa Chameleon, the HP-150, the Victor 9000, the Heath/Zenith 100, and others. As time permits, support for these systems will be integrated with the new modular version. Meanwhile, implementations based on these old versions will have at least the following incompatibilies from the version described here: ________ ________ - RECEIVE filespec is used instead of GET filespec. There is no GET command in older versions, and no way to specify a new name for an incoming file. - No REMOTE command. - No 8th-bit prefixing. To install support for a new system, you would copy the system-dependent modules for terminal emulation and port and console i/o, modify them to suit the requirements of your machine, and rebuild the program. In many cases, a "generic" MS DOS Kermit will run as-is on new systems. The generic version ac- complishes all its port and console i/o through DOS calls, and does no terminal emulation -- many systems do not need terminal emulation because they have ter- minal firmware built in. _______ __ __ ______ __ Details to be filled in... CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 106 CHAPTER 11 CHAPTER 11 CHAPTER 11 CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT _______ Program: Bill Catchings, Columbia University, with contributions from Bernie Eiben (DEC), Nick Bush (Stevens), John Bray (University of Tennessee), Bruce Tanner (Cerritos College), Greg Small (University of California at Berkeley), Kimmo Laaksonen (Helskini University of Technology), and many others. ________ Language: 8080 Assembler or MAC80 _______ Version: 3.8 ____ Date: February 1984 _____________ Documentation: Frank da Cruz, Columbia University SUMMARY OF CP/M SUMMARY OF CP/M SUMMARY OF CP/M CP/M-80 (version 2.2) has only five built-in commands, and they all deal with files; other functions are done by invoking programs. CP/M file specifications are of the form DEV:XXXXXXXX.YYY, where ______ ____ DEV: is a device name, normally the A: or B: floppy. If omitted, the device name defaults to your connected diskette. ________ XXXXXXXX is a filename of up to 8 characters. ____ ____ YYY is the file type, up to 3 characters. File names and file types may contain letters, digits, and some special charac- ters, including dash, dollar sign, and underscore, but no imbedded spaces. Up- per and lower case letters are equivalent. "Wildcard" file-group specifications are permitted in file names and file types (but not device names) within certain contexts; a "*" matches a whole field, a "?" matches a single character, including space. Examples: "*.F??" specifies _____ all files whose types start with F and are 1, 2, or 3 characters long; "F?.*" specifies all files whose names start with F and are no more than two charac- ters long (before the trailing spaces). The five CP/M commands are: ____ DIR file Lists the the names of the specified files. The default file specification is "*.*". Example: "DIR B:*.FOR". ____ ERA file Erases (deletes) the specified file(s); wildcards allowed. ___ ___ ___ ___ REN new old Changes the name of a file from old to new, e.g. "REN NEW.FOR=OLD.FOR". SAVE Saves the specified number of memory blocks into a file. CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 107 ____ TYPE file Types the specified file on the screen, e.g. "TYPE FOO.TXT". The most important programs are: STAT Gives statistics on disk usage. _ _ _ PIP Peripheral Interchange Program. Copies files. In response to the "*" prompt, give a command of the form disk:outfile=disk:infile Wildcards ("*" for a whole field or "?" for a letter) can be used. Examples: "A:=B:*.*" to copy a whole disk, "A:=B:*.FOR" to copy all the Fortran programs from disk B to disk A. If the disk specification is omitted, your "connected" disk is as- sumed. Command line arguments are also accepted, e.g. "PIP A:=B:*.*". For further information on CP/M, consult your microcomputer manual or a CP/M handbook. KERMIT-80 DESCRIPTION KERMIT-80 DESCRIPTION KERMIT-80 DESCRIPTION Implementations of Kermit-80 presently exist for the DEC VT180 (Robin), the DECmate II, the Intertec Superbrain, the Heath/Zenith 89 and Z100, the Apple II with the Z80 SoftCard, the Osborne, the TRS-80 II with CP/M, the Telcon Zorba, the Kaypro, the Vector Graphics CP/M system, and others. There is also a "generic" CP/M version that should run on most 8080-compatible CP/M systems, but which may provide less performance. Since Kermit-80 runs on a standalone micro, it is always in control of the _____ screen -- it is always local. Thus, it always keeps the screen updated with the file name and the packet number, whether sending or receiving. Kermit-80 is capable of an imprecise, or "fuzzy" timeout on an input request, and can break deadlocks automatically. In most cases, this is not important, because the KERMIT on the other side is most likely able to handle the timeouts. The timeouts done by Kermit-80 are fuzzy because they depend on the speed of the Z80 processor and other factors that can vary from system to system. If despite the timeout capability, the transmission appears to be 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 timeout, namely NAK the expected packet to cause to foreign host to send it again (or, if the micro is sending, to retransmit the last packet). Micro/ micro or micro/IBM-mainframe transfers could require this kind of manual inter- vention. File transfers may be interrupted in several ways. Control-C This will return you to Kermit-80 command level immediately, so CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 108 that you can connect back to the remote system, or take any other desired action. Control-X When sending a file, this will terminate the sending of the current file with a signal to the KERMIT on the other side to discard what it got so far. If there are more files to be sent, KERMIT-80 will go on to the next one. When receiving a file, KERMIT-80 will send a signal to the remote KERMIT to stop sending this file. If the remote KERMIT understands this sig- nal (not all implementations of KERMIT do), it will comply, otherwise the file will keep coming. In any case, the remote KERMIT will go on to the next file in the group, if any. Control-Z Like Control-X, except if a file group is being transmitted, this will stop the transmission of the entire group. If only a single file is being transmitted, it is exactly like Control-X. Carriage Returns If you type carriage return repeatedly Kermit-80 will retry the current packet up to its retry limit (something like 16 times) and then, if no valid response was received, return to Kermit-80 command level. KERMIT-80 COMMANDS KERMIT-80 COMMANDS KERMIT-80 COMMANDS KERMIT-80 uses the DECSYSTEM-20 keyword style command language. Each keyword may be abbreviated to its minumum unique length. "?" may be typed to request a menu of the available options for the current field at any point in a command. ESC may be typed at any point in a command to fill out the current keyword or filename; if sufficient characters have not been typed to identify the current field uniquely, KERMIT-80 will sound a beep and allow you to continue from that point. CONNECT Establish a "virtual terminal" connection to any host that may be con- nected 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; when you issue the CONNECT command, the micro will print a message telling you how to get back. The escape sequence is generally an uncommonly-used control character, like CTRL-backslash or CTRL-rightbracket, followed by a single letter "command". C Close Connection, return to Kermit-80> command level. S Display Status of connection, but maintain remote connection. ? List available single-character commands. 0 (zero) Send a null (0) character. B Send a BREAK signal. Only some systems provide this function. CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 109 ^] (or whatever - a second copy of the escape character) Send the es- cape character itself to the remote host. ________ SEND filespec ________ ________ Send file(s) specified by filespec to the remote Kermit. The filespec may contain CP/M wildcards. 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 con- flict, and FILE-WARNING is ON, warn the user and try to build a unique name for the file. ________ GET filespec When Kermit-80 is talking to a Kermit Server on the host, you may in- clude a filespec in order to request the server to send files to you, for example: get hlp:k*.hlp ________ LOG filespec When CONNECTed to a foreign host as a terminal, log the terminal ses- sion to the specified diskette file. This functionality depends to some extent on the remote host's ability to do XON/XOFF flow control, and does not guarantee a complete transcript (after all, that's what the KERMIT protocol is for). The log file is closed when the connec- tion is closed by typing the escape character followed by the single- character command "C". ________ TRANSMIT filespec Send the specified file to the system on the other end of the connec- tion as though it were being typed at the terminal, one line at a time. No KERMIT protocol is involved. You must manually confirm each line. This is useful for sending files to systems that don't have a KERMIT program. During transmission, you may type the escape character fol- lowed by one of these single-character commands: C Cease transmission R Re-transmit the previous line 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. LOGOUT Like BYE, but leaves you at Kermit-80 command level. 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. _________ _____ SET parameter [value] Set the specified parameter to the specified value. Possible settings: CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 110 WARNING ON (or OFF) Warn user of filename conflicts when receiving files from remote host, and attempt to generate a unique name by modifying the given one. ON by default. 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 DECmate (these act as VT100-series terminals). Some systems emulate other terminals, like the ADM3A. 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. ESCAPE Change the escape character for virtual terminal connections. Kermit-80 will prompt you for the new escape character, which you enter literally. BAUD Change the baud rate of the communications port. This command only works on some systems, and its actual operation can vary from system to system. Type SET BAUD followed by a question mark, and follow the directions. On systems that do not sup- port this command, you must set the port baud rate from CP/M or other setup mechanism outside of KERMIT-80. 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 con- nection and file transfer. IBM ON (or OFF) Allow the transfer of files to and from an IBM mainframe com- puter. This makes Kermit-80 wait for the IBM turnaround character (XON), ignore parity on input, add appropriate parity to output, and use local echoing during CONNECT. If you don't give this command, IBM mode is OFF. BLOCK-CHECK-TYPE The options are: 1-CHARACTER-CHECKSUM Normal, default, standard 6-bit checksum. 2-CHARACTER-CHECKSUM A 12-bit checksum encoded as two characters. 3-CHARACTER-CRC-CCITT A 16-bit CCITT-format Cyclic Redundancy Check, encoded as 3 characters. CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 111 The 2 and 3 character options should only be used under con- ditions of extreme line noise. Many implementations of KERMIT only support the single character checksum. FILE-MODE Tells KERMIT-80 what kind of file it is sending, so that KERMIT can correctly determine the end of the file. SET FILE BINARY means to send the entire last block; SET FILE ASCII is used for text files, and transmission stops when the first Control-Z is encountered anywhere in the file. If binary transmission is used on a text file, some extraneous characters (up to 127 of them) may appear at the end of the file on the target system. If ASCII transmission is used on a binary file, the entire file will not be sent if there happen to be any bytes that cor- respond to Control-Z. DEFAULT-DISK This allows you to set the default disk as source and destina- tion of file transfers. In addition, issuing this command causes you to switch to the specified disk and log it in, write-enabled. The selected disk appears in your KERMIT-80 prompt, for instance Kermit-80 A:> PORT Allows you to switch between different communication ports. This command is not available on all systems. PRINTER ON or OFF. Turns copying of CONNECT session to printer on and off. No attempt is made to do buffering or flow control; it is assumed printer can keep up. DIR This provides a directory listing of the specified files. If no files are specified, all files on the default disk are listed. File sizes, in K, are included. You may interrupt the listing at any time by typing any character. The listing (even if interrupted) concludes with a display of the amount of free storage left on the disk. ERA This executes the CP/M ERA command on the specified file(s). The names of the files being erased are not displayed. 11.1. Generic KERMIT-80 11.1. Generic KERMIT-80 11.1. Generic KERMIT-80 "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 screen. All I/O is done with standard CP/M BIOS calls, and I/O redirection is done using the CP/M IOBYTE function, which, __ _ _________ ______ ______ according to the Digital Research CP/M Operating System Manual, 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 sys- CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 112 tems 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. Neither does generic Kermit-80 do termimal emulation; thus a generic Kermit-80 acts either as a "dumb terminal" (sometimes called a "glass TTY"), or else its own built in terminal firmware provides cursor control functions independent of the Kermit program. Note that VT180 and DECmate-II Kermit are simply adaptations of Generic Kermit that do VT100 (ANSI) screen control during file transfer. 11.2. Installation 11.2. Installation 11.2. Installation Kermit-80 was written originally for the Intertec SuperBrain in lowest-common- denominator 8080 code with the standard assembler, ASM (no macros, no advanced 18 instructions), so that it can be assembled on any CP/M-80 system . 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 CP/M with only minor modifications (see below). 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 port routines are best done only with BDOS calls, but some systems do not allow this, primarily because the BDOS routines strip the parity bit during port i/o, and the parity bit is used for data when transmitting binary files. Also, using BDOS calls, there's no way to poll the serial port; you must hang until input appears. _______________ 18 The 8080 assembler is distributed as a standard part of CP/M-80, whereas the fancier Z80 or macro assemblers are normally a commercial product CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 113 Kermit-80's i/o routines must check the port status and go elsewhere if no in- put is available; this allows for virtual terminal connection, keyboard inter- ruption of stuck transmissions, etc. On systems that fully implement i/o redirection via the optional CP/M IOBYTE facility, this may be done by switch- ing the IOBYTE definition. On others, however, IN/OUT instructions explicitly referencing the port device registers must be used. CP/M-80 KERMIT version 3.8 and above includes a "fuzzy timer" that allows a timeout to occur after an interval ranging from 5 to 20 seconds (depending upon the speed of the processor and the operating system routines) during which ex- pected input does not appear at the port. In this case, retransmission occurs automatically. In any case, you may type a carriage return during transmission to simulate a timeout when the transfer appears to be stuck. 11.2.1. Downloading Kermit-80 11.2.1. Downloading Kermit-80 11.2.1. Downloading Kermit-80 If you already have a version of Kermit on your micro and you want to install a new version, simply use your present version to get the new one. If it's stored in the form of a .COM file, you can run it directly. If it's stored as a .HEX file, you must first LOAD it on your micro to produce a .COM file. If you do not have a copy of KERMIT on your micro, and you cannot borrow a Ker- mit floppy but you do have access to a mainframe computer with a copy of the Kermit-80 distribution, you should read this section. 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, hex 40). DECSYSTEM-10 users would look for a dot, hex 2E. 1. Look for the appropriate hex file in the host's KERMIT area. The name will be something like CPMROBIN.HEX, CPMHEATH.HEX, CPMOSBORN.HEX, etc. If you don't find it, but you do find a cor- responding .ASM or .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 M80 source file to your micro and assemble it there. 2. 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 TERMINAL NO PAUSE END-OF-PAGE. CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 114 3. Tell the host to display the hex file at your terminal. E.g. on the _______ _ ___________ DEC-20, give the Exec command TYPE KERMIT.HEX, without a terminating ________ ______ carriage return. 4. Return to your micro. Connect to a floppy disk with plenty of free space. Make sure your IOBYTE is set so that RDR: and PUN: cor- respond 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): -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. CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 115 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 Now there should be a file KERMIT.HEX on your connected disk. 5. Load this using the CP/M command LOAD to produce KERMIT.COM. 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. You now should have a running version of Kermit-80. 11.2.2. Building KERMIT.HEX 11.2.2. Building KERMIT.HEX 11.2.2. Building KERMIT.HEX 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 KERMIT.ASM 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 is provided that runs on the DEC-10 and DEC-20, called MAC80, contributed by Bruce Tanner at Cerritos College, that may be used for cross as- sembling KERMIT-80 as shown in this example (for TOPS-20): __ 1. Copy PS:CPMKxx.M80 to your directory, as KERMIT.M80. TOPS-10 filename rules must be followed. This is the 8080 assembler __ source file; xx is the current version number; for instance version 3.8 would be stored as CPMK38.M80. 2. Edit KERMIT.M80 to set the conditional assembly switch for your machine. These are right near the top of the file. The switch for your machine should be set to TRUE and all the others to FALSE. The switches currently available are: CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 116 BRAIN Intertec SuperBrain. HEATH Heath/Zenith H89 Z100 Zenith Z100 running CP/M-85. OSI Ohio Scientific ROBIN DEC VT18X "Robin" DMII DECmate II word processor with CP/M VECTOR Vector Graphics GENER Any CP/M systems that implements IOBYTE. APPLE Apple II, with Z80 SoftCard, D.C. Hayes Micromodem II. TRS80 TRS-80 II, running Lifeboat CP/M 2.25 or later. OSBRN1 Osborne 1. TELCON Telcon Zorba. KPII Kaypro-II CPM3 CP/M Plus (3.0) Look in the source file; there may be new ones since this manual was written. 3. The "ibm-flag" setting is site dependent. As shipped from Columbia, it turns on half duplex line handshaking, using CTRL-Q as the tur- naround character, sets LOCAL-ECHO ON, and sets PARITY MARK. Make any changes required for your site. 4. The default FILE-MODE is ASCII as shipped from Columbia. This means that when text files are sent from the CP/M system, no extraneous characters will be sent after the end, but that outgoing binary files may be truncated erroneously if the user forgets to SET FILE BINARY. You can change the default to BINARY, so that no data is ever lost from any file, but text files will usually have extraneous junk at the end. 5. Run MAC80: _____ @mac80 ______________ *kermit,=kermit __ *^Z The result will be in your directory as KERMIT.HEX. 6. Use Kermit to transfer KERMIT.HEX to the micro, or download it using the DDT program shown above. 7. On the micro, load the hex file: ____ ______ A>load_kermit KERMIT.COM will appear on the floppy. 8. The new Kermit should be ready to run. CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 117 11.2.3. Generic Kermit-80 11.2.3. Generic Kermit-80 11.2.3. Generic Kermit-80 If your CP/M system implements i/o redirection via the (optional) IOBYTE mechanism, you can probably run Generic Kermit on it, either without modifica- tion, or by a very simple change to the program. The standard CP/M IOBYTE is set up as follows: 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:) (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 con- sole. 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 and the serial port looking for input. Here are the batch and default i/o mode definitions used in "standard" Generic KERMIT-80: batio EQU 056H ;I/O byte CON=BAT,LIST=CRT,READER=RDR defio EQU 095H ;I/O byte CON=CRT,LIST=LPT,READER=RDR Other systems may have other logical devices that point to the serial port, in CP/M-80 KERMIT CP/M-80 KERMIT CP/M-80 KERMIT Page 118 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). CP/M-86 KERMIT CP/M-86 KERMIT CP/M-86 KERMIT Page 119 CHAPTER 12 CHAPTER 12 CHAPTER 12 CP/M-86 KERMIT CP/M-86 KERMIT CP/M-86 KERMIT _______ Authors: Bill Catchings, Columbia University; Ron Blanford, University of Washington; Richard Garland, Columbia University. _______ Version: 2.4 ____ Date: February 1984 This version of KERMIT is written in Digital Research CP/M-86 assembler, ASM86. It is designed to support any CP/M-86 system. So far it supports the DEC Rainbow-100 and the NEC Advanced Personal Computer (APC). It is very similar to CP/M-80 and MS DOS KERMIT. ________ ___ _____________ FEATURES_AND_RESTRICTIONS: - Performs all standard KERMIT functions. - Has commands to talk to KERMIT servers. - Runs up to 9600 baud on all systems tested. - Can use XON/XOFF during terminal connection or file transfer. - Can time out. - Can send BREAK (Rainbow only). - Can exchange files with IBM host. - No local CP/M functions (ERA, DIR, SET DEFAULT disk). - No REMOTE command. - No 8th-bit prefixing. - No repeat-count prefixing. - No 2- or 3-character block checks. - Protocol to interrupt a transfer (^X/^Z). - ^C during file transfer gets back to Kermit-86 command level im- mediately. _____________ INSTALLATION: CP/M-86 KERMIT is broken up into several source modules: 86KERCMD.A86 Command parser 86KERFIL.A86 File handler 86KERIO.A86 System Dependent I/O 86KERMIT.A86 Main Program 86KERPRO.A86 Protocol Module 86KERSYS.A86 System Dependent Commands and Modifications 86KERUTL.A86 Utilities The main program module, 86KERMIT.A86, contains INCLUDE directives for the other files. The program may be built on the CP/M-86 system by obtaining all the source files listed above, storing them on the current disk with the names indicated, setting the appropriate conditional assembly parameters (RAINBO or NECAPC) in 86KERMIT.A86 to TRUE or FALSE, and doing: CP/M-86 KERMIT CP/M-86 KERMIT CP/M-86 KERMIT Page 120 ASM86 86KERMIT $PZ (this takes about 6 minutes on the Rainbow) GENCMD 86KERMIT (takes less than a minute) and, if desired, REN KERMIT.CMD=86KERMIT.CMD DEC Rainbow users who have access to a DEC VT180 can use VT180 (Robin) Kermit to bootstrap CP/M-86 Kermit, since the Rainbow can read a VT180 disk. Use VT180 Kermit to download RBKERMIT.CMD or RBKERMIT.H86, take the disk to your Rainbow, and copy the file onto a Rainbow disk (if you took the .H86 file, you will have to load it first with GENCMD). VT180 Kermit can run on the Rainbow under CP/M-86/80 version 1 (not 2 or above) at speeds of 1800 baud or below. If you don't have a VT180, you can bootstrap the RBKERMIT.H86 file onto your system using the DDT program that is used for bootstrapping KERMIT-80 onto a CP/M-80 system. This works because the Rainbow includes a CP/M-80 system. KERMIT User Guide KERMIT User Guide KERMIT User Guide Page 121 I. THE ASCII CHARACTER SET I. THE ASCII CHARACTER SET I. THE ASCII CHARACTER SET _____ ____ _____ __________ ASCII_Code_(ANSI_X3.4-1968) There are 128 characters in the ASCII (American national Standard Code for In- formation Interchange) "alphabet". The characters are listed in order of ASCII value; the columns are labeled as follows: Bit Even parity bit for ASCII character. ASCII Dec Decimal (base 10) representation. ASCII Oct Octal (base 8) representation. ASCII Hex Hexadecimal (base 16) representation. EBCDIC Hex EBCDIC hexadecimal equivalent for Kermit translate tables. Char Name or graphical representation of character. Remark Description of character. The first group consists of nonprintable 'control' characters: KERMIT User Guide KERMIT User Guide KERMIT User Guide Page 122 .....ASCII.... EBCDIC ___ ___ ___ ___ ___ ____ _______ Bit Dec Oct Hex Hex Char Remarks 0 000 000 00 00 NUL ^@, Null, Idle 1 001 001 01 01 SOH ^A, Start of heading 1 002 002 02 02 STX ^B, Start of text 0 003 003 03 03 ETX ^C, End of text 1 004 004 04 37 EOT ^D, End of transmission 0 005 005 05 2D ENQ ^E, Enquiry 0 006 006 06 2E ACK ^F, Acknowledge 1 007 007 07 2F BEL ^G, Bell, beep, or fleep 1 008 010 08 16 BS ^H, Backspace 0 009 011 09 05 HT ^I, Horizontal tab 0 010 012 0A 25 LF ^J, Line feed 1 011 013 0B 0B VT ^K, Vertical tab 0 012 014 0C 0C FF ^L, Form feed (top of page) 1 013 015 0D 0D CR ^M, Carriage return 1 014 016 0E 0E SO ^N, Shift out 0 015 017 0F 0F SI ^O, Shift in 1 016 020 10 10 DLE ^P, Data link escape 0 017 021 11 11 DC1 ^Q, Device control 1, XON 0 018 022 12 12 DC2 ^R, Device control 2 1 019 023 13 13 DC3 ^S, Device control 3, XOFF 0 020 024 14 3C DC4 ^T, Device control 4 1 021 025 15 3D NAK ^U, Negative acknowledge 1 022 026 16 32 SYN ^V, Synchronous idle 0 023 027 17 26 ETB ^W, End of transmission block 0 024 030 18 18 CAN ^X, Cancel 1 025 031 19 19 EM ^Y, End of medium 1 026 032 1A 3F SUB ^Z, Substitute 0 027 033 1B 27 ESC ^[, Escape, prefix, altmode 1 028 034 1C 1C FS ^\, File separator 0 029 035 1D 1D GS ^], Group separator 0 030 036 1E 1E RS ^^, Record separator 1 031 037 1F 1F US ^_, Unit separator The last four are usually associated with the control version of backslash, right square bracket, uparrow (or circumflex), and underscore, respectively, but some terminals do not transmit these control characters. The following characters are printable: KERMIT User Guide KERMIT User Guide KERMIT User Guide Page 123 First, some punctuation characters. .....ASCII.... EBCDIC ___ ___ ___ ___ ___ ____ _______ Bit Dec Oct Hex Hex Char Remarks 1 032 040 20 40 SP Space, blank 0 033 041 21 5A ! Exclamation mark 0 034 042 22 7F " Doublequote 1 035 043 23 7B # Number sign, pound sign 0 036 044 24 5B $ Dollar sign 1 037 045 25 6C % Percent sign 1 038 046 26 50 & Ampersand 0 039 047 27 7D ' Apostrophe, accent acute 0 040 050 28 4D ( Left parenthesis 1 041 051 29 5D ) Right parenthesis 1 042 052 2A 5C * Asterisk, star 0 043 053 2B 4E + Plus sign 1 044 054 2C 6B , Comma 0 045 055 2D 60 - Dash, hyphen, minus sign 0 046 056 2E 4B . Period, dot 1 047 057 2F 61 / Slash Numeric characters: .....ASCII.... EBCDIC ___ ___ ___ ___ ___ ____ _______ Bit Dec Oct Hex Hex Char Remarks 0 048 060 30 F0 0 Zero 1 049 061 31 F1 1 One 1 050 062 32 F2 2 Two 0 051 063 33 F3 3 Three 1 052 064 34 F4 4 Four 0 053 065 35 F5 5 Five 0 054 066 36 F6 6 Six 1 055 067 37 F7 7 Seven 1 056 070 38 F8 8 Eight 0 057 071 39 F9 9 Nine More punctuation characters: .....ASCII.... EBCDIC ___ ___ ___ ___ ___ ____ _______ Bit Dec Oct Hex Hex Char Remarks 0 058 072 3A 7A : Colon 1 059 073 3B 5E ; Semicolon 0 060 074 3C 4C < Left angle bracket 1 061 075 3D 7E = Equal sign 1 062 076 3E 6E > Right angle bracket 0 063 077 3F 6F ? Question mark 1 064 100 40 7C @ "At" sign KERMIT User Guide KERMIT User Guide KERMIT User Guide Page 124 Upper-case alphabetic characters (letters): .....ASCII.... EBCDIC ___ ___ ___ ___ ___ ____ _______ Bit Dec Oct Hex Hex Char Remarks 0 065 101 41 C1 A 0 066 102 42 C2 B 1 067 103 43 C3 C 0 068 104 44 C4 D 1 069 105 45 C5 E 1 070 106 46 C6 F 0 071 107 47 C7 G 0 072 110 48 C8 H 1 073 111 49 C9 I 1 074 112 4A D1 J 0 075 113 4B D2 K 1 076 114 4C D3 L 0 077 115 4D D4 M 0 078 116 4E D5 N 1 079 117 4F D6 O 0 080 120 50 D7 P 1 081 121 51 D8 Q 1 082 122 52 D9 R 0 083 123 53 E2 S 1 084 124 54 E3 T 0 085 125 55 E4 U 0 086 126 56 E5 V 1 087 127 57 E6 W 1 088 130 58 E7 X 0 089 131 59 E8 Y 0 090 132 5A E9 Z More punctuation characters: .....ASCII.... EBCDIC ___ ___ ___ ___ ___ ____ _______ Bit Dec Oct Hex Hex Char Remarks 1 091 133 5B AD [ Left square bracket 0 092 134 5C E0 \ Backslash 1 093 135 5D BD ] Right square bracket 1 094 136 5E 5F ^ Circumflex, up arrow 0 095 137 5F 6D _ Underscore, left arrow 0 096 140 60 79 ` Accent grave KERMIT User Guide KERMIT User Guide KERMIT User Guide Page 125 Lower-case alphabetic characters (letters): .....ASCII.... EBCDIC ___ ___ ___ ___ ___ ____ _______ Bit Dec Oct Hex Hex Char Remarks 1 097 141 61 81 a 1 098 142 62 82 b 0 099 143 63 83 c 1 100 144 64 84 d 0 101 145 65 85 e 0 102 146 66 86 f 1 103 147 67 87 g 1 104 150 68 88 h 0 105 151 69 89 i 0 106 152 6A 91 j 1 107 153 6B 92 k 0 108 154 6C 93 l 1 109 155 6D 94 m 1 110 156 6E 95 n 0 111 157 6F 96 o 1 112 160 70 97 p 0 113 161 71 98 q 0 114 162 72 99 r 1 115 163 73 A2 s 0 116 164 74 A3 t 1 117 165 75 A4 u 1 118 166 76 A5 v 0 119 167 77 A6 w 0 120 170 78 A7 x 1 121 171 79 A8 y 1 122 172 7A A9 z More punctuation characters: .....ASCII.... EBCDIC ___ ___ ___ ___ ___ ____ _______ Bit Dec Oct Hex Hex Char Remarks 0 123 173 7B C0 { Left brace (curly bracket) 1 124 174 7C 4F | Vertical bar 0 125 175 7D D0 } Right brace (curly bracket) 0 126 176 7E 7E ~ Tilde Finally, one more nonprintable character: 0 127 177 7F 07 DEL Delete, rubout KERMIT User Guide KERMIT User Guide KERMIT User Guide Page 126 INDEX INDEX INDEX Delay 37 8080 111, 112 DELETE 54 8086/8088 100 Dialup 14 Diskette 21 Apple II 116 Downloading 101, 113 ARPANET 62 Duplex 37 ASCII 121 Autoanswer 16 EBCDIC 121 Autodialer 13 Eighth-Bit Prefix 30, 40, 54, 99 Eighth-Bit-Prefix 28, 53 Backarrow 97 End Of Line 40, 41 Baud 110 End of line character 98 Baud Rate 35, 97 End-Of-Line (EOL) 81 Beeper 97 Error Recovery 19 Bell 97 Escape Character 10, 108, 110 Binary Files 20, 28, 40, 53, 54, 99 Escape Character for CONNECT 37, 60, BIOS 111 98 Block Check 36, 110 Escape Sequence 9 Bootstrap 113 EXIT 34, 58 BREAK 66 BYE 17, 18, 109 File Renaming 98 Byte Size 48, 56, 60 File Warning 98 File-Warning 109 Cables 14, 15 FINISH 17, 18, 109 Cancelling a File Transfer 29, 30, Flow Control 38 54, 55, 93 Function Keys 99 Capturing Files 43 Checksum 5 Generic Kermit-80 111, 116, 117 Command Parsing 25 GET 18, 109 CONNECT 8, 10, 108 CONTINUE 34, 58 Handshake 38 Control Characters 9, 122 Heath-19 Terminal Emulation 98 Control-A 54 Heath/Zenith H89 116 Control-C 34, 58, 93 Help 51, 92 Control-V 54 Hex File 116 Control-X 29, 30, 54, 55, 93 Control-Z 29, 30, 54, 55, 93 IBM 61, 80, 110 CP/M 112 IBM Compatibility 99 CP/M-Plus 116 IBM PC 89, 100 Crash 21 Incomplete File Disposition 30, 55, Cross Assembler 115 93 Incomplete File Transfer 39 Deadlock 21 Initial Filespec 21, 28, 52, 92 Debugging 37, 59, 98 Internal Modem 19 DEC VT18X 116 IOBYTE 117 DECmate-II 116 ITS-Binary Format 61 DECsystem-10 101, 115 DECSYSTEM-20 46, 115 Kaypro 116 DEFINE 62 Kermit Commands 10 Define SET Macros 42 KERMIT Protocol 5 KERMIT User Guide KERMIT User Guide KERMIT User Guide Page 127 Kermit server 17 KEXE 104 SEND 10, 13, 18, 21, 28, 52, 80, 92, KFIX 100 109 KGET 101 Server 17, 31, 56 KSEND 101 SET 10, 81, 109 SHOW 11, 43, 63, 82 Line Sequence Numbers 53 Smart Modem 19, 20 Local 10, 23, 107 Start Of Packet 41, 42 Local Echo 37 Superbrain 112, 115 Local Echoing 99 Local-Echo 110 TAC Binary Mode 62 LOG 43, 109 Telcon Zorba 116 LOGOUT 109 TELENET 39, 42 LRECL 81 Timeout 40, 41, 80, 107, 113 TOPS-20 46 MAC80 116 TRANSMIT 109 Modem 19 TRS-80 II 116 MS-DOS 89 UNDELETE 54 NAK 20, 107 Network 19 Vector Graphics 116 Noise 5 Virtual Terminal 8, 10, 108 Normal Form for File Names 53, 61, VM/CMS 13, 80 92 VT100 110 Null Modem 14, 15 VT18X 116 VT52 110 Ohio Scientific 116 Osborne 1 116 Warning 109 Wildcard 10, 12, 47, 90 Packet 5, 7 Word Size 48 Packet Length 40, 41 Packet-Length 81 XON/XOFF 109, 122 Padding 40, 41 Parity 19, 28, 30, 39, 53, 54, 99, Z80 112 110, 122 Zenith Z100 116 Pause Between Packets 40, 41 PC-DOS 89 Prompt 8 Protocol 5 QUIT 34, 58 Quote 81 RECEIVE 10, 12, 13, 30, 54, 81, 93, 109 RECFM 81 Recognition 51, 92 Remote 10, 23 Repeated Character Compression 29, 30, 53, 54 Retry Limit 42 Robin 116 KERMIT User Guide KERMIT User Guide KERMIT User Guide Page i Table of Contents Table of Contents Table of Contents Ordering Information Ordering Information Ordering Information 3 1. Introduction 1. Introduction 1. Introduction 5 2. How to Use KERMIT 2. How to Use KERMIT 2. How to Use KERMIT 7 2.1. The KERMIT Program 7 2.2. Talking to Two Computers at Once 8 2.3. Transferring a File 9 2.4. Basic KERMIT Commands 10 2.5. Real Examples 11 2.5.1. PC to Host 11 2.5.2. Host to Host 13 2.5.3. Micro to Micro 15 2.6. Another Way -- The KERMIT Server 17 3. When Things Go Wrong 3. When Things Go Wrong 3. When Things Go Wrong 19 3.1. Communication Line Problems 19 3.2. The Transfer is Stuck 20 3.3. The Micro is Hung 21 3.4. The Remote Host Went Away 21 3.5. The Disk is Full 21 3.6. Message Interference 22 3.7. Host Errors 22 3.8. File is Garbage 22 3.9. Junk after End of File 22 4. KERMIT Commands 4. KERMIT Commands 4. KERMIT Commands 23 4.1. Remote and Local Operation 23 4.2. Command Interface 25 4.3. Notation 25 4.4. Summary of KERMIT Commands 27 4.5. The SEND Command 28 4.6. The RECEIVE Command 30 4.7. GET 31 4.8. SERVER 31 4.9. BYE 32 4.10. FINISH 32 4.11. REMOTE 32 4.12. LOCAL 33 4.13. CONNECT 33 4.14. HELP 34 4.15. TAKE 34 4.16. EXIT, QUIT 34 4.17. The SET Command 35 4.18. DEFINE 42 4.19. SHOW 43 4.20. STATISTICS 43 KERMIT User Guide KERMIT User Guide KERMIT User Guide Page ii 4.21. LOG 43 4.22. TRANSMIT 43 5. KERMIT Implementations 5. KERMIT Implementations 5. KERMIT Implementations 45 6. DECSYSTEM-20 KERMIT 6. DECSYSTEM-20 KERMIT 6. DECSYSTEM-20 KERMIT 46 6.1. The DEC-20 File System 46 6.2. Program Operation 50 6.3. Remote and Local Operation 51 6.4. KERMIT-20 Commands 52 6.5. The TTLINK Program 65 6.6. Examples 67 6.7. Installation 70 7. VAX/VMS KERMIT 7. VAX/VMS KERMIT 7. VAX/VMS KERMIT 71 8. IBM VM/CMS KERMIT 8. IBM VM/CMS KERMIT 8. IBM VM/CMS KERMIT 80 9. UNIX KERMIT 9. UNIX KERMIT 9. UNIX KERMIT 85 10. PC-DOS and MS-DOS KERMIT-86 10. PC-DOS and MS-DOS KERMIT-86 10. PC-DOS and MS-DOS KERMIT-86 89 10.1. The MS-DOS File System 89 10.2. Program Operation 91 10.3. MS DOS KERMIT Commands 92 10.4. Installation 100 10.5. Adding Support for New Systems 105 11. CP/M-80 KERMIT 11. CP/M-80 KERMIT 11. CP/M-80 KERMIT 106 11.1. Generic KERMIT-80 111 11.2. Installation 112 11.2.1. Downloading Kermit-80 113 11.2.2. Building KERMIT.HEX 115 11.2.3. Generic Kermit-80 117 12. CP/M-86 KERMIT 12. CP/M-86 KERMIT 12. CP/M-86 KERMIT 119 I. The ASCII Character Set I. The ASCII Character Set I. The ASCII Character Set 121 Index Index Index 126