KERMIT USER GUIDE Sixth Edition, Revision 2 Frank da Cruz, editor Columbia University Center for Computing Activities New York, New York 10027 May 26, 1986 Copyright (C) 1981,1986 Trustees of Columbia University in the City of New York Permission is granted to any individual or institution to use, copy, or redistribute this document so long as it is not sold for profit, and provided this copyright notice is retained. Kermit User Guide Page i Table of Contents How To Get Kermit 4 Organization of This Manual 5 1. Introduction 6 1.1. Why Kermit? 6 1.2. How Kermit Works 7 2. How to Use Kermit 9 2.1. Transferring a File 10 2.2. Basic Kermit Commands 10 2.3. Real Examples 11 2.3.1. PC to Host 12 2.3.2. Host to Host 13 2.3.3. Micro to Micro 15 2.4. Another Way -- The Kermit Server 16 3. When Things Go Wrong 19 3.1. Basic Connection Problems 19 3.2. Terminal Connection Works But The Transfer Won't Start 19 3.3. Special Characters 21 3.4. 3270 Protocol Emulators 21 3.5. The Transfer Starts But Then Gets Stuck 21 3.5.1. The Micro is Hung 22 3.5.2. The Connection is Broken 22 3.5.3. The Disk is Full 22 3.5.4. Message Interference 23 3.5.5. Transmission Delays 23 3.5.6. Noise Corruption 23 3.5.7. Host Errors 23 3.6. File is Garbage 23 3.7. Junk after End of File 24 4. Kermit Commands 25 4.1. Remote and Local Operation 25 4.2. The Command Dialog 25 4.3. Notation 27 4.4. Summary of Kermit Commands 28 4.5. The SEND Command 29 4.6. The RECEIVE Command 30 4.7. GET 31 4.8. SERVER 32 4.9. BYE 32 4.10. FINISH 32 4.11. REMOTE 32 Kermit User Guide Page ii 4.12. LOCAL 33 4.13. CONNECT 34 4.14. HELP 35 4.15. TAKE 35 4.16. EXIT, QUIT 35 4.17. The SET Command 35 4.18. DEFINE 42 4.19. SHOW 43 4.20. STATISTICS 43 4.21. LOG 43 4.22. TRANSMIT 44 4.23. INPUT 44 4.24. OUTPUT 44 4.25. PAUSE 44 4.26. SCRIPT 44 5. Kermit Implementations 45 6. DECSYSTEM-20 KERMIT 46 6.1. The DEC-20 File System 46 6.2. Program Operation 51 6.3. Remote and Local Operation 52 6.4. Conditioning Your Job for Kermit 52 6.5. Kermit-20 Commands 53 6.5.1. Commands for File Transfer 54 6.5.2. Server Operation 58 6.5.3. Commands for Local File Management 59 6.5.4. The CONNECT Command 60 6.5.5. The SET, SHOW, and DEFINE Commands 61 6.5.6. Program Management Commands 67 6.6. Login Scripts: The INPUT, OUTPUT, CLEAR, and PAUSE Commands 69 6.7. Raw Download and Upload 76 6.8. Kermit-20 Examples 79 6.9. Installation of Kermit-20 81 7. VAX/VMS KERMIT 83 7.1. The VAX/VMS File System 84 7.2. Program Operation 87 7.3. Conditioning Your Job for Kermit 88 7.4. Kermit-32 Commands 89 7.4.1. Commands for File Transfer 89 7.4.2. Server Operation 92 7.4.3. Commands for Local File Management 94 7.4.4. The CONNECT Command 95 7.4.5. The SET and SHOW Commands 96 7.4.6. Program Management Commands 100 7.5. Raw Download 101 7.6. Installation of Kermit-32 102 Kermit User Guide Page iii 8. IBM VM/CMS KERMIT 106 8.1. The VM/CMS File System 107 8.1.1. File Specifications 107 8.1.2. File Formats 108 8.2. Program Operation 108 8.3. Kermit-CMS Commands 110 8.4. Before Connecting to the Mainframe 115 8.5. How to build an executable version of Kermit-CMS 116 8.6. What's New 116 8.7. What's Missing 117 9. UNIX KERMIT 118 9.1. The Unix File System 119 9.2. File Transfer 119 9.3. Command Line Operation 120 9.4. Interactive Operation 126 9.5. UUCP Lock Files 144 9.6. C-Kermit under Berkeley or System III/V Unix: 145 9.7. C-Kermit on the DEC Pro-3xx with Pro/Venix Version 1 145 9.8. C-Kermit under VAX/VMS 146 9.9. C-Kermit on the Macintosh 146 9.10. C-Kermit Restrictions and Known Bugs 146 9.11. How to Build C-Kermit for a Unix System 148 9.12. Adapting C-Kermit to Other Systems 148 10. MACINTOSH KERMIT 153 10.1. The Macintosh File System 154 10.2. File Transfer 154 10.3. Remote Commands 155 10.4. Settings 156 10.5. Terminal Emulation 156 10.6. Installation 158 10.7. CKMKEY - Macintosh Kermit's Keyboard Configurator 158 10.7.1. What is CKMKEY? 158 10.7.2. Modifier vs Normal Keys 159 10.7.3. Key Maps 159 10.7.4. What's in CKMKEY's Keymaps 160 10.7.5. Menus 160 10.7.6. MENU: Set 160 10.7.6.1. DIALOG: Set Modifer Keys 160 10.7.6.2. DIALOG: Set Function Definitions 163 10.7.6.3. DIALOG: Set Keys 163 10.7.7. MENU: File 164 10.7.8. CKMKEY Known Limitations, Restrictions, Bugs 164 10.7.9. Unlocking CAPS LOCK 164 11. MS-DOS KERMIT 167 Kermit User Guide Page iv 11.1. The MS-DOS File System 168 11.1.1. File Specifications 168 11.1.2. File Formats 170 11.2. Program Invocation 170 11.3. Kermit-MS Commands 174 11.3.1. Commands for Terminal Connection 175 11.3.2. Commands for File Transfer 175 11.3.3. Commands for Controlling Remote Kermit Servers 178 11.3.4. Commands for File Management 179 11.3.5. The SERVER Command 182 11.3.6. The SET Command 183 11.3.7. The SHOW Command 194 11.3.8. Command Macros 194 11.4. Terminal Emulation 195 11.5. Installation of Kermit-MS 199 11.5.1. Try Again To Find A Kermit Disk 200 11.5.2. Bootstrapping From the Communication Line 200 11.6. Compatibility with Older Versions of MS-DOS Kermit 205 11.7. What's Missing 205 11.8. Program Organization 206 11.9. Running Kermit on New Systems 207 11.10. IBM-PC MS Kermit Terminal Emulator Summary 208 11.10.1. Keyboard Layout and Characters Sent 208 11.10.2. Responses To Characters Received By the Terminal Emulator 210 11.10.3. DEC VT102 functions while in VT52 mode 212 11.10.4. Heath-19 functions while in non-ANSI mode 213 12. CP/M-80 KERMIT 215 12.1. Summary of CP/M 215 12.2. Kermit-80 Description 216 12.3. Kermit-80 Flavors 221 12.3.1. Generic Kermit-80 221 12.3.2. CP/M 3 Kermit 222 12.3.3. System-Specific Versions 222 12.4. Installation of Kermit-80 223 12.4.1. Organization of Kermit-80 224 12.4.2. Downloading Kermit-80 225 12.4.3. Assembling Kermit-80 from the sources 230 12.5. Adding Support For A New System 233 12.6. Notes on New Features in Kermit-80 Version 4 234 12.7. Future Work 235 13. CP/M-86 KERMIT 236 13.1. Kermit-86 Commands 237 13.2. Installation: 241 13.3. DEC Rainbow 100 Support 241 13.4. NEC Advanced Personal Computer Support 242 14. APPLE-DOS KERMIT 244 Kermit User Guide Page v 14.1. The DOS 3.3 File System 244 14.2. Program Operation 246 14.3. Remote and Local Operation 248 14.4. KERMIT-65 Commands 248 14.5. Customizing, Building, and Installing KERMIT-65 255 I. The ASCII Character Set 262 Index i Kermit User Guide Page vi List of Figures Figure 1-1: A Kermit Packet 7 Figure 1-2: Kermit File Transfer 8 Figure 4-1: Local and Remote Kermits 26 Figure 6-1: DECSYSTEM-20 Word/Byte Organization 49 Figure 6-2: DEC-20 Kermit Local Operation 53 Figure 10-1: Macintosh Kermit Modifier Key Dialog 162 Kermit User Guide Page vii List of Tables Table 11-1: Kermit-MS Screen Scroll Keys 197 Table 11-2: Kermit-MS Terminal Emulation Options 199 Table 12-1: Kermit-80 SET PORT Options 222 Table 12-2: Systems supported by Kermit-80 225 Table 12-3: Terminals known to Kermit-80 233 Preface to the 6th Edition, March 1985 Page 1 Preface to the 6th Edition, March 1985 Kermit is the name of a protocol for transferring files from one computer to another over ordinary asynchronous terminal connections. Kermit programs have been written for many different computers, and in general any two computers that have Kermit programs can exchange sequential files correctly and com- pletely. This manual describes use and installation of Kermit programs. A companion volume, the Kermit Protocol Manual, attempts to specify the protocol sufficiently to allow new Kermit programs to be written. This manual describes an "ideal" Kermit program, one which has most of the fea- tures specified in the Kermit Protocol Manual, and then describes several real Kermit programs in detail. Most real Kermit programs fall short of the ideal in some ways; a few may surpass it. The system-dependent portions of this manual may be 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 distributed with the Kermit programs. Since the publication of the Fifth Edition of the Kermit User Guide in July 1984, there have been new releases of most of the Kermit implementations described in this manual. The Sixth Edition includes new chapters for all these implementations. In addition, some material has been added to the front sections to describe some new facilities like login scripts, and to reflect new experiences as Kermit spreads to increasingly diverse environments. Revision 1 of the Sixth Edition (June 1985) includes a new chapter for Macin- tosh Kermit, and replacement chapters for several other Kermits, including VAX/VMS, VM/CMS, UNIX, and MS-DOS. Revision 2 of the Sixth Edition (May 1986) includes new chapters for MS-DOS Kermit 2.29, VAX/VMS Kermit 3.2, and Macintosh Kermit 0.8(34), and an improved bootstrapping procedure for CP/M-80 Kermit. HISTORY AND ACKNOWLEDGEMENTS 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 Preface to the 6th Edition, March 1985 Page 2 groups like DECUS and SHARE, and began to get requests for it from other sites. Since we had written down a description of the protocol, some sites wrote their own implementations for new computers, or adapted one of our implementations to run on additional systems, and sent back these new versions to us so that we could share them with others. In this way, Kermit has grown to support more than 100 different systems; it has been sent on magnetic tape from Columbia to thousands of sites in dozens of countries, and has reached hundreds or thousands more through various user groups and networks. Thanks to the hundreds of individuals and institutions who have contributed to the Kermit storehouse over the years. The Kermit protocol was named after Kermit the Frog, star of the television series THE MUPPET SHOW; the name Kermit is used by permission of Henson As- sociates, Inc., New York. FURTHER READING - A two-part article describing the Kermit protocol appeared in the June and July 1984 issues of BYTE Magazine: "Kermit, A File Transfer Protocol For Universities", by Frank da Cruz and Bill Catchings. The title (chosen by the BYTE editors to fit the theme of the June issue) is a bit misleading, because there's nothing about Kermit that's par- ticular to universities. - The book "Kermit, A File Transfer Protocol," by Frank da Cruz, Digi- tal Press, Bedford MA (1986), ISBN 0-932376-88-6, DEC order number EY-6705E-DP, describes Kermit in detail, from the points of view of the user, of computer professionals who have to install Kermit programs or support their use, and of programmers who wish to write new Kermit implementations, and also contains tutorials on data com- munications, file organization, plus a detailed troubleshooting guide, bootstrapping hints, and many illustrations and tables. DISCLAIMER Neither Columbia University, nor the editor, nor the authors of the individual chapters, nor any individual or institution contributing Kermit programs or documentation to the Columbia University Kermit Distribution, acknowledge any liability for any claims arising from use or misuse of Kermit programs or for inaccuracies in the documentation or bugs in the programs. Kermit programs are produced on a voluntary basis and contributed freely for public use in the hope that they will be useful, but without any kind of warranty or guarantee, or any commitment to address or fix problems. In practice, Kermit programs and documentation are contributed in good faith, and will be supported on a best- effort basis, time and other commitments permitting. Preface to the 6th Edition, March 1985 Page 3 CUSTOMIZING THIS MANUAL Although the Kermit User Guide was produced at Columbia University, all at- tempts have been made to keep it free of site-specific information. However, due to the large number of Kermit implementations, descriptions of each one would make the manual unnecessarily thick. Therefore, the manual is sent from Columbia with specific documentation about a selection of systems. Some of these descriptions may not be of interest at your site, while others that are may be lacking. Each site, upon receiving a Kermit tape, may decide which versions of Kermit are important to it, and include the appropriate documentation in this manual. This is most conveniently done if your site has the Scribe text formatting 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 KUSER.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. If you do this, you should include an indication on the title page that the manual has been customized for your site. 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 @BEGIN(VERBATIM)...@END(VERBATIM) brackets (and replace all atsigns (@) in the text with double atsigns (@@)). 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. If you don't know Scribe, you can use one of the ex- isting chapters as a model. How To Get Kermit Page 4 How To Get Kermit Kermit is available to users of the BITNET network via a Kermit file server at host CUVMA. BITNET users may type ``SMSG RSCS MSG CUVMA KERMSRV HELP'' for further information. Kermit is also available to users of the Internet via anonymous FTP from host CU20B, in the area KER:, and to users of UNIX(tm) sys- tems via UUCP from host "okstate" at the Oklahoma State University Computer Science department. And Kermit is distributed regularly by various computer user groups such as DECUS and SHARE. (This information in the paragraph is current as June 1985, but is subject to change.) 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. 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. Please note that although Kermit is free, it is not in the public domain. The Kermit manuals, and most Kermit programs, bear copyright notices. This copyright notice is to protect Columbia University and the various contributors from having their work usurped by others and sold as a product. This is not to say that the Kermit file transfer protocol can never be included as a feature of a commercial product; the conditions under which this may be done are spelled out in a flyer POLICY ON COMMERCIAL USE AND DISTRIBUTION OF KERMIT. To inquire about obtaining the Kermit distribution, write to: Kermit Distribution Columbia University Center for Computing Activities 612 West 115th Street New York, N.Y. 10025 Since new Kermit programs are added -- and old ones improved -- so frequently, sites that use Kermit heavily are encouraged to contact Columbia for updates two or three times a year for news. -- PLEASE USE KERMIT ONLY FOR PEACEFUL AND HUMANE PURPOSES -- Organization of This Manual Page 5 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. Introduction Page 6 1. Introduction There is an ever-increasing need to move information from one computer to another. Information can be exchanged using magnetic media -- tapes or disks -- or over networks. Networks are expensive, and when your computer is not connected to one (or to the right one), you must find other means to transfer information. In the early days of computing, magnetic media formats were rela- tively standardized, but with the arrival of microcomputers things have changed: most microcomputer users have no access to tapes, and disk formats are incompatible between most microcomputer makes and models. Even when disk for- mats agree, the disk must be physically moved from one system to the other in order for information to be exchanged -- the effort and delay can be sig- nificant if the systems are widely separated. The telecommunication line provides an alternative to networks and magnetic media. Asynchronous telecommunication is the method used by most terminals to connect to most computers. When dedicated "hardwired" connections, such as those found between a timesharing computer and its local terminals, are not available, computer users can create their own connections with a telephone and a modem. Most computers come equipped with asynchronous telecommunications interfaces, or "serial ports", which allow them to act as, or communicate with, terminals. The question is how to use the serial port to exchange data. Fortunately, the standards for connecting terminals to computers are almost universally fol- lowed: connector configuration (DB-25 or DB-9), transmission signals (EIA RS-232), a commonly accepted set of transmission speeds (baud rates), and a convention for encoding characters in storage and during transmission (ASCII). These standards provide the physical medium and the data format, but they do not specify a process for exchanging data. 1.1. Why Kermit? When data is transmitted from one computer to another; the receiving computer has to be instructed to take in the data and put it somewhere, and it also needs a way of ensuring that the data has been received correctly and com- pletely in spite of several factors that will tend to interfere with this process: 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. Timing -- Data must not come in faster than the receiving machine can handle it. Although line speeds at the two ends of the connec- tion must match before communication can take place, the receiving machine might not be able to process a steady stream of input at that speed. Its central processor may be too slow or too heavily loaded, or its buffers too full or too small. The typical symptom of a timing 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 Introduction Page 7 a faulty connector, loss of power, or similar reason. On dialup or switched connections, such intermittent failures may 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 special messages to one another along with the data. Inter- mingling of control information with data together requires a set of rules for distinguishing messages from data, and specifying what the messages are and the actions associated with each message. Such a set of rules is called a protocol. Kermit is a file transfer protocol. It is specifically designed for transfer of sequential files over ordinary serial telecommunication lines. Kermit is not necessarily better than other terminal-oriented file transfer protocols but it is free, it is well documented, and it has been implemented compatibly on a wide variety of microcomputers and mainframes. 1.2. How Kermit Works Kermit transfers data by encapsulating it in packets of control information. This information includes a synchronization marker, a packet sequence number to allow detection of lost packets, a length indicator, and a "block check" to al- low verification of the data, as shown in Figure 1-1. +------+------+------+------+--------- - - - -+-------+ | MARK | LEN | SEQ | TYPE | DATA | CHECK | +------+------+------+------+--------- - - - -+-------+ Figure 1-1: A Kermit Packet The MARK (usually an ASCII Control-A character) appears at the beginning of the packet. The next character is a length field (LEN), specifying how long the rest of the packet is. The sequence number (SEQ) is used to detect lost or duplicated packets; retransmission is requested for lost packets and duplicate packets are discarded. The TYPE field specifies whether the packet contains data or control information. The CHECK field contains a quantity obtained by combining all the other characters in the packet together in one of several ways; the sender computes this value and sends it. The packet receiver also computes the value and checks it against the value sent; if they agree, the packet is accepted; if they disagree, then the packet has been corrupted and retransmission is requested. The DATA field contains up to 90 characters of data. All fields except the mark are encoded as printable ASCII characters, to prevent host or network interference. Figure 1-2 shows how a typical file transfer proceeds. Figure 1-2 does not show how Kermit recovers from errors. Very briefly, here's how it works: - If a packet is corrupted in transit by noise or loss of characters, the block check will be wrong. A file receiver will NAK ("negatively acknowledge") a corrupted packet, which causes the sender to retransmit the same packet. A file sender only receives ACKs and NAKs from the receiver; a corrupted ACK or NAK from the receiver is treated exactly the same as a NAK. - If the file sender does not receive an ACK within the prescribed Introduction Page 8 Sender Receiver Send-Init -------------> Sender and Receiver exchange greetings <-------------------- ACK File-Header -----------> Sender sends first file name to Receiver <-------------------- ACK Receiver acknowledges File-Data -------------> Sender sends first file data packet <-------------------- ACK File-Data -------------> Sender sends second file data packet <-------------------- ACK File-Data --xx~~~p'''--> Third data packet is corrupted by noise <-------------------- NAK and Receiver negatively acknowledges it File-Data -------------> Sender retransmits third packet <-------------------- ACK File-Data packets are sent and acknowledged until the whole file is sent End-Of-File -----------> Sender indicates first file is complete <-------------------- ACK File-Header -----------> Name second of file <-------------------- ACK File-Data -------------> First data packet for second file <-------------------- ACK File-Data packets are sent and ack'd until the whole file is sent End-Of-File -----------> Sender indicates second file is complete <-------------------- ACK End-Of-Transaction ----> Sender indicates no more files to come <------------------- ACK Figure 1-2: Kermit File Transfer timeout interval, it retransmits the same packet. If the file receiver does not receive an expected packet within the timeout in- terval, it sends a NAK for the expected packet. Several encoding, compression, and block check options are provided. Very few assumptions are made about the capabilities of either computer, so the Kermit protocol can work between many different kinds of systems. The protocol is described in detail in the Kermit Protocol Manual, and in the BYTE Magazine ar- ticle on Kermit, published in the June and July 1984 issues. How to Use Kermit Page 9 2. How to Use Kermit Kermit embodies a set of rules for transferring files reliably between two com- puters. In general, one computer is a large system (a host, for instance a timesharing 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. Your task is just to get the two Kermits started. You have to use a single keyboard and screen to talk to two different computers, two different programs. Let's talk about a common case: you are sitting at a personal computer (PC), which has a serial communication port. The 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 other, remote computer. When you tell Kermit to CONNECT, it sends every character you type out the serial port, and it puts 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 remote computer, and the PC is "vitually" ignoring you. Kermit, like most interactive programs, has a prompt. The prompt is a string of characters 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 iden- tifies 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 microcomputers is called "Kermit-80" and its prompt is "Kermit-80>"; the Kermit that runs under CP/M-86 is "Kermit-86, and so forth. If you become confused about which Kermit 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 [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 characters 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 entered 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 How to Use Kermit Page 10 while holding down CTRL. 2.1. Transferring a File From system command level on your PC, first run the Kermit program. Then tell Kermit to CONNECT you to the host. Now you're talking to the remote 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 produce a running display on your screen as the transfer proceeds, and will notify you when it 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. Transferring a file in the other direction works the same way, but with the SEND and RECEIVE commands exchanged. 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 *.*" The scenario for each of these is the same as above -- only the details of how to establish the actual connection differ. Kermit works best with "printable" files -- files composed only of letters, digits, punctuation marks, carriage returns, tabs, and so forth -- since these can be represented on almost any kind of computer. Kermit is also able to transfer "binary" files -- files such as executable programs -- composed of ar- 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 most cases special measures must be taken to accomplish this. Let's look at some more concrete examples. First you need to know what the basic Kermit commands are. 2.2. 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 How to Use Kermit Page 11 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 specification. 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 incoming file name is not legal, then attempt to transform it to a similar legal name. Options are be provided for handling filename collisions. CONNECT Make a "virtual terminal" connection to the remote system. 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, speed, parity, or flow control. All of these are explained later. 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 almost anywhere within a Kermit command: List the commands, options, or operands that are possible at this point. This command may or may not require a carriage return, depending on the host operating system. 2.3. 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. How to Use Kermit Page 12 2.3.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; the material lined up on the right is com- mentary, not system typeout or part of a command: A>Kermit Run Kermit on the PC. Kermit-MS V2.27 Kermit-MS> This is the Kermit prompt for the PC. Kermit-MS>connect Connect to the DEC-20. [Connecting to host, type Control-] to return to PC] 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. (Various greeting or notice messages are displayed.) @Kermit Run Kermit on the DEC-20. TOPS-20 Kermit version 4.2(251) 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-MS>receive Tell the PC that files are coming. If you take more than about 5 seconds to get back to Kermit-MS 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 arrive, the current file name and packet number will be continuously displayed on the screen. When the PC's "Kermit-MS>" prompt returns to your screen (with an ac- companying beep to catch your attention) the transfer is done. Notice the How to Use Kermit Page 13 screen display; the status should be indicated as "complete". If not, an error has occurred and an appropriate message should be displayed to tell you why. After you're finished transferring files, you must CONNECT back to the DEC-20 host, EXIT from Kermit there, logout, and "escape back" to the PC as you did previously: Kermit-MS>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-Oct-84 15:18:56, Used 0:00:17 in 0:21:55 ^]c Now "escape" back to the PC, [Back at PC.] Kermit-MS>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-MS>" 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.3.2. Host to Host This section describes use of Kermit between two host computers. A "host" is considered to be a large or multi-user system, whose distinguishing charac- teristic is that it has multiple terminals. Use of Kermit for host-to-host file transfers differs from the PC-to-host case in that the line your terminal is connected to is not the same as the line over which the data is being trans- ferred, and that some special SET 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 Dialing your number, please hold... Your party waiting is on TTY12: @ How to Use Kermit Page 14 Other methods exist for connecting two hosts with a serial line. Dedicated hookups can be made simply by running an EIA cable between TTY ports on the two 1 systems. For connecting to remote systems when no autodialer is available, a 2 manual dialup connection is also possible, but tricky. If you have a microcomputer that supports Kermit, you may find it easier to first transfer from host A to the micro, then from the micro to host B. The following procedure would be the same in any case, once a connection is made. @ @Kermit Run Kermit on the DEC-20. Kermit-20>set ibm Turn on handshaking, parity, local echo. Kermit-20>set line (to tty) 12 ! Indicate the line we'll use. Kermit-20>connect And connect to it. [Kermit-20: Connecting over TTY12:, type C to return.] VM/370 ONLINE The IBM system prints its herald. .login myuserid mypassword Login to IBM system. 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. ^\c Kermit-20's escape sequence typed here. [Kermit-20: 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 remote IBM system, exit from the remote Kermit and log out. . PROFILE.EXEC.1 ..%%.[OK] _______________ 1 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. Such cables may also require certain other modem signals such as DTR held high. 2 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 Page 15 Kermit-20>connect Get back to IBM and clean up. [Kermit-20: Connecting over TTY12:, type C to return.] 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 ^\c Type Kermit-20's escape sequence [Kermit-20: 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.3.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 3 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 cer- 4 tain 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. _______________ 3 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. 4 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 Page 16 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 - V4.05 Kermit-80>receive 2. Run Kermit on the Robin, and give the SEND command for FOO.HEX. A>Kermit DEC VT18X Kermit-80 - V4.05 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 -- some 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. 2.4. 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 -- but most of the major ones can and do. The server is run on the remote computer, which would normally be a large host, such as the DEC-20. You must still connect to the remote host to log in and start the server, but you no longer have to tell one side to SEND and the other to RECEIVE, nor must you connect back to the remote side to clean up and log out when you're done. Using the server, you can do as many send and receive operations as you like without ever having to connect back to the remote host. Some servers also provide additional services, such as directory listings, file deletion, or disk usage inquiries. A Kermit server is just a Kermit program running in a special say. It acts much like ordinary Kermit does after you give it a RECEIVE command -- it waits How to Use Kermit Page 17 for a message from the other Kermit, but in this case the message is a command saying 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 com- mand 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-80 V4.05 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 to return to your local machine. Shut down the server by typing the Kermit BYE command on your local machine. ^]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 the basic 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. How to Use Kermit Page 18 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. REMOTE command [argument] Ask the server to perform the specified command, and send the results to your screen. Not all servers are capable of per- forming REMOTE commands; those that can most commonly provide REMOTE DIRECTORY, REMOTE DELETE, REMOTE SPACE, and similar file management services. 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. Server operation is not limited to mainframes. Some PC Kermit implementations can also act as servers, notably MS-DOS and Unix. For instance, an IBM PC at the office with an autoanswer modem can be left in server mode at the end of the day, and then dialed up from home in the evening for file transfer. When Things Go Wrong Page 19 3. 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. Basic Connection 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-in SET BAUD or SET SPEED command, others require that you set the baud rate using a sys- tem command or setup mode before you start the Kermit program. Some versions of Kermit have SHOW or STATUS commands that will tell you 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 may have to consult the appropriate manuals for the systems and equipment in question. 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 unless they totally mimic the asynchronous serial port hardware they purport to replace. Many microcomputer Kermit programs are written to control the communication hardware explicitly; internal modems can interfere with that control. Even external modems can cause trouble -- the "smarter" they are, the more potential danger of disagreement between the modem and the microcomputer about settings of baud rate, character framing, echo, and so forth. Make sure your modem is set up correctly. 3.2. Terminal Connection Works But The Transfer Won't Start Once you've made a terminal connection to the remote system, you will generally also be able to transfer files. But not always. If Kermit's terminal emula- tion seems to work correctly, but a file transfer will not start at all, then something in the communication path is probably interfering with the packet data. When Things Go Wrong Page 20 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. In addition to modems, ex- amples include port contention or selection units, multiplexers, local net- works, and wide-area networks. Such equipment can interfere with the Kermit file transfer protocol in various ways: PARITY: A device 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: - 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 be set. ECHOING: Some communication processors, typically front ends, echo their input. When this happens, every Kermit packet that is sent to it will bounce right back, causing no end of confusion. Some Kermit programs have been designed to ignore echoed packets, but most have not. If you encounter this problem, there are several possible solutions: - Disable the front end echoing by typing some special command, if such a command is provided by the system. - Some front ends respond to certain escape or control sequences as commands to turn off echoing, either from that point onward, or else on a per-line basis. In this case, the appropriate control sequence can be inserted between packets by Kermit programs in- structed to do so, for instance using the SET PAD command. - If the echoing cannot be disabled, then the two Kermit programs should be instructed to use differing packet start markers, using the SET START-OF-PACKET command -- for instance, one Kermit uses Control-A as usual, and the other uses Control-B. This can only be done if both Kermits have this SET command. When Things Go Wrong Page 21 3.3. Special Characters There is one problem that can prevent a file transfer from starting at all, or may crop up after the file transfer is underway. For instance, during a file transfer operation you might find your smart modem suddenly hanging up your current connection and placing a call to Tasmania. Or you might find that packets containing a certain character like "@" cannot be transmitted success- fully. This is the problem of "special characters". Some device in the communication path -- a front end, a port switcher, a multiplexer, a "smart" modem -- inter- prets certain characters in the data stream as commands rather than as data to be passed them along to the other side. Usually such equipment interferes only with the transmission of ASCII control characters; so long as Control-A and Carriage Return -- Kermit's normal packet start and end delimiters -- are not molested, then Kermit can operate. However, equipment may exist which swallows even printable characters. Since Kermit assumes that ALL printable ASCII characters (ASCII 40 through 176, octal) can be transmitted without inter- ference or modification, such equipment will prevent Kermit file transfer un- less its printable-character-swallowing features can be disabled. 3.4. 3270 Protocol Emulators Connections to IBM mainframes through 3270 protocol emulation hardware or software cannot be used for file transfer with Kermit or any similar program. Kermit requires an asynchronous stream ASCII telecommunications environment. 3270-style terminals operate in a block-mode bisynchronous EBCDIC environment. Protocol converters change the EBCDIC screen data blocks into streams of ASCII characters with imbedded terminal control sequences. Packetized file transfer is impossible under these circumstances because the data is modified and the packet block check invalidated. The only exception to this rule occurs on IBM mainframes with protocol emulators that can be put into transparent mode by a command from the host, and whose Kermit programs have been coded explicitly to do this. For instance, as of this writing there are IBM mainframe Kermit programs that allow file trans- fer through the Series/1 or 7171 front ends. 3.5. The Transfer Starts But Then Gets Stuck Once a Kermit file transfer has begun, there are certain conditions under which it can become stuck. Since many hosts are capable of generating timeout inter- rupts when input doesn't appear within a reasonable interval, they can resend unacknowledged packets or request that missing packets be retransmitted. But since not all Kermit programs are capable of timing out, a means for manual in- tervention is provided in the local Kermit -- you can type a carriage return on the keyboard of most micros to wake up and continue the transfer. 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- 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. When Things Go Wrong Page 22 3.5.1. 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): - 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 Kermit, CONNECT back to the host, get back to your job or login again, and restart the trans- fer. You may have to stop and restart Kermit on the remote host. 3.5.2. The Connection is Broken 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. If upon reconnection you get no response, 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.3. 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. Some Kermits also have a feature that allows you to keep incom- pletely received files; this would allow you go back to the sending system, ex- tract the unsent portion of the file, and send it, and then append the two received portions together using an editor or other system utility. Kermit does not provide the ability to switch disks during a file transfer. When Things Go Wrong Page 23 3.5.4. 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.5.5. Transmission Delays Packet transmission can be delayed by various agents: congested timesharing systems or networks, earth satellites, etc. When transmission delay exceeds the per-packet timeout interval for a significant length of time, the transfer could fail. Most Kermit programs provide commands that allow you to adjust the timeout interval or the packet transmission retry threshhold in order to accom- modate to severe transmission delays. 3.5.6. Noise Corruption If your connection is extremely noisy, packets will become corrupted -- and re- quire retransmission -- more often. The probability that successive retransmissions will fail because of corruption rises with the noise level un- til it exceeds the retry threshhold, at which point the file transfer fails. There are several recourses. First, try to establish a new connection. If that is impractical, then use SET commands (when available) to reduce the packet length and increase the retry threshhold. Shorter packets reduce the probability that a particular packet will be corrupted and the retransmission overhead when corruption does occur, but they also increase the overall protocol overhead. In a noisy environment, you should also request a higher level of error checking. 3.5.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.6. 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. When Things Go Wrong Page 24 3.7. 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. To complicate matters, certain software on other microcomputer systems, such as MS-DOS, follows the CP/M end-of-file convention. Under MS-DOS, certain editors and other programs use Control-Z for end-of-file, and other programs do not. MS-DOS Kermit provides a SET command to choose the desired format. Kermit Commands Page 25 4. 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 In any connection between two Kermit programs, one Kermit is remote and the other is local. The 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 com- mands. 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 are run in local mode unless instructed otherwise; mainframe Kermits run remotely unless some special command places them in local mode. Some commands make sense only for remote Kermits, others only for local, still others can be used with either. Local and remote operation of Kermit is shown schematically here: The Kermit program on the PC is a local Kermit. It can control the screen, the keyboard, and the port separately, thus it can up- date the screen with status information, watch for interrupt signals from the keyboard, and transfer packets on the communications port, all at the same time. The Kermit program running on the mainframe is a 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. 4.2. The Command Dialog Most Kermit programs communicate with you through interactive keyword-style command dialog. The program issues a prompt, indicating that it is waiting for you to type a command. The prompt is usually of the form Kermit-xx> where xx indicates the version of Kermit -- Kermit-MS> for MS-DOS Kermit, Kermit-86> for CP/M-86 Kermit, etc. In response to the program's prompt you may type a keyword, such as SEND, Kermit Commands Page 26 PC is Local, Mainframe is Remote: 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 Figure 4-1: Local and Remote Kermits 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 "?" re- quires 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, then another question mark to see what the possibilities are for the next field, and so forth. The command is finally terminated by a carriage return. Before carriage return is typed, however, the command can be edited or erased using RUBOUT or other command editing keys. Finally, the same command is entered again with a minimum of keystrokes, with each field abbreviated to its shortest unique length. In the example, the parts the user types are underlined; all the rest is system typeout: Kermit-20>set ? one of the following: debugging delay duplex escape Kermit Commands Page 27 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 In the command descriptions, the following notation is used: italics A parameter - the symbol in italics is replaced by an argument of the specified type (number, filename, etc). [anything] A field enclosed in square brackets is optional. If omitted, the field defaults to an appropriate value. You don't type the brack- ets. {x,y,z} A list of alternatives is enclosed in curly braces; you type one of the alternatives. 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 Page 28 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, SET SPEED (or BAUD) 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 commands: DEFINE For interrupting transmission: Control-X, Control-Z, Control-C, Control-E 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, INPUT, OUTPUT, PAUSE, CLEAR, SCRIPT For closing log files: CLOSE 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 macros to configure Kermit to various systems or communications media. Note: Your particular implementation of Kermit may use a different name for this file. Kermit Commands Page 29 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. Some Kermit programs allow the initial file in a wildcard group to 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 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. Kermit Commands Page 30 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. 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 Kermit Commands Page 31 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 the protocol 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- mand to the remote Kermit, and then escaped back to DEC-20 Kermit (you can not issue a RECEIVE command to a Kermit server, you must use the GET command for that). 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 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 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 instructs the program to wait passively, whereas GET actively sends a request 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. Optional Syntax: If you are requesting a single file, you may type the GET com- mand without a filespec. In that case, Kermit programs that implement the op- tional GET syntax will prompt you for the remote filespec on the subsequent line, and the name to store it under when it arrives on the line after that: Kermit-MS>get Kermit Commands Page 32 Remote Source File: aux.txt Local Destination File: auxfile.txt 4.8. SERVER 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. The other Kermit must have commands for communicating with remote servers; these include GET, SEND, FINISH, and BYE. After issuing this command, return to the "client" system and issue SEND, GET, BYE, FINISH, or other server-directed commands from there. If your local Ker- mit does not have a BYE command, then it does not have the full ability to com- municate with a Kermit server and you should not put the remote Kermit into SERVER mode. If your local Kermit does have a BYE command, use it to shut down and log out the Kermit server when you are done with it. Any nonstandard parameters should be selected with SET commands before putting Kermit in server mode. 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 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 LOCAL ONLY -- Syntax: REMOTE command When running as a local Kermit talking to a remote Kermit server, use the REMOTE command to request special functions of the remote server. If the serv- er does not understand the command or offer the requested service (all of these commands and services 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: REMOTE CWD [directory] Change Working Directory. If no directory name is provided, the server Kermit Commands Page 33 will change to the default directory. Otherwise, you will be prompted for a password, and the server will attempt to change to the specified direc- tory. If access is not granted, the server will provide a message to that effect. REMOTE DELETE filespec Delete the specified file or files. The names of the files that are deleted should be displayed on your screen. REMOTE DIRECTORY [filespec] The names of the files that match the given file specification will be dis- played on your screen, possibly along with additional information about file sizes and dates. If no file specification is given, all files from the current directory will be listed. REMOTE SPACE [directory] Information about disk usage in the current remote directory -- quota, cur- rent storage, or amount of remaining free space -- is displayed on your screen. REMOTE HELP A list of available server functions is displayed. REMOTE HOST [command] The given command is passed to the server's host command processor, and the resulting output is displayed on your screen. REMOTE KERMIT [command] The given command, which is expressed in the server Kermit's own interactive-mode command syntax, is passed to the server for execution. This is useful for changing settings, logging, and other functions. REMOTE RUN program-name [command-line-argument] The remote Kermit is asked to run the indicated program with the indicated command line; the program's terminal output is sent back to your screen. REMOTE PROGRAM [command] The command is sent to the program started by most recent REMOTE RUN program, and the program's response is displayed on the screen. If no com- mand is given, a newline character is sent. REMOTE TYPE filespec The contents of the specified file is displayed on your screen. 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. The LOCAL prefix for these commands can be omitted. CWD [directory] Kermit Commands Page 34 "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. SPACE Display local disk usage and/or free space. RUN filespec [operands] Run the indicated program with the supplied command-line operands. PUSH Invoke the local system command interpreter in such a way that it can return (or "pop" or "exit") back to Kermit. 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 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 "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. D Drop the line, hangup the modem. 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 FLOW-CONTROL, SET HANDSHAKE to establish or change those parameters. Kermit Commands Page 35 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 Syntax: 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 Exit from Kermit. QUIT is a synonym for EXIT. 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 Kermit Commands Page 36 MODEM Modem type or characteristics PARITY Character parity to use PORT For switching communication ports PROMPT For changing the program's command prompt RECEIVE Various parameters for receiving files RETRY How many times to retry a packet before giving up SEND Various parameters for sending files TIMER Enable/disable timeouts 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. Ten bits per second is equivalent to one character per second; 300 baud = 30 cps. The way of specifying the baud rate varies from system to system; in most cases, the actual number (such as 1200 or 9600) is typed. Systems that do not provide this command generally expect that the speed of the line has already been set appropriately outside of Kermit. Common values are 300, 1200, 2400, 4800, 9600. SET BLOCK-CHECK {1, 2, 3} 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 transmission proceeds. If they dis- agree, the packet is rejected and retransmission is requsted. 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, Kermit Commands Page 37 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 and/or when sending binary files. 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. SET DEBUG {ON, OFF} Syntax: SET DEBUG options Record debugging information, either on your terminal or in a file. Options are: ON Turn on debugging. OFF Don't display debugging information (this is the default). If debugging was in effect, turn it off and close any log file. Some Kermit programs may control debugging by use of the LOG DEBUG command. 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 {FULL, HALF} 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". Kermit Commands Page 38 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 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 value 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 file type (text or binary), byte size (PDP-10 architecture), record length or block size (record oriented systems), end-of-file detection method (on microcomputers), file naming conversion option. 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 {XON/XOFF,NONE} 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. When a system's input buffer comes close to being full, it will send an XOFF character (Control-S) to request the other system to stop sending. When it has emptied sufficient characters from its input buffer, it signals the other system to resume sending by transmitting an XON character (Control-Q). This process operates in both directions simultaneously. The op- tions for the Kermit SET FLOW command are usually restricted to XON/XOFF and NONE, which is used to disable this feature. 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: Kermit Commands Page 39 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-[. Some Kermit programs may require the option to be specified by typing the character literally or entering its numeric ASCII value. If you use this com- mand to enable handshaking, you should also SET FLOW OFF. SET INCOMPLETE Syntax: SET INCOMPLETE {KEEP, DISCARD} 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 {EVEN, ODD, MARK, SPACE, NONE} 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. Kermit Commands Page 40 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 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 PROMPT Syntax: SET PROMPT string This allows you to change the program's prompt. This is particularly useful if you are using Kermit to transfer files between two systems of the same kind, in which case you can change the prompts of the Kermit programs involved to in- clude appropriate distinguishing information. SET SEND SET SEND parameter value Parameters for outgoing packets, as follows: END-OF-LINE character The ASCII character to be used as a line terminator for outbound pack- ets, if one is required by the other system, carriage return by default. You will only have to use this command for systems that re- quire a line terminator 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. Kermit Commands Page 41 TIMEOUT number How many seconds to wait for a packet before trying again. A value of zero means don't time out -- wait forever. PAUSE floating-point-number How many seconds to pause before sending each data packet. Setting this to a nonzero value may allow a slow system enough time to con- solidate itself before the next packet arrives. Normally, no per-packet pausing is done. 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. This command is also handy for inserting special characters that may be required by communications equipment. 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 value 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 Kermit Commands Page 42 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, "#" (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 establishing the initial protocol connection be- fore 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 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 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 Kermit Commands Page 43 instance: DEFINE IBM You can list all your macros and their definitions with the SHOW MACROS com- mand. Some Kermit programs allow macro definitions to include any Kermit com- mand, not just SET commands. 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 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 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. DEBUGGING Record debugging information in the specified file. There may be several options to select the desired information -- entire packets, state transitions, internal program trace, etc -- available via the SET DEBUGGING command. PACKETS Record packets, and all communication line traffice during file transfer, in the specified file. Kermit Commands Page 44 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- 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. 4.23. INPUT Syntax: INPUT [interval] [string] Input characters from the remote system for the specified interval, looking for the specified string. Terminate when the string is found or when the interval has expired, whichever comes first. Useful for synchronizing with remote sys- tem prompts. 4.24. OUTPUT Syntax: OUTPUT [string] Send the specified string to the remote system. Useful in conjunction with the INPUT command to form "login scripts". 4.25. PAUSE Syntax: PAUSE [interval] Pause for the specified interval. Useful in login scripts. 4.26. SCRIPT Syntax: SCRIPT [string] The string is a "login script" in some system- or implementation-dependent for- mat, such as the UNIX(tm) UUCP "expect-send" format. Kermit Implementations Page 45 5. 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- plementation is written in a language 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. Versions for "Portable Operating Systems": OS; Language (Machines) CP/M-80; ASM (Kaypro, H/Z-89, H/Z-100, Osborne, DEC VT180, many others) CP/M-86; ASM86 (DEC Rainbow, NEC APC, others) MS-DOS; MASM (IBM PC,XT,AT, DEC Rainbow, HP-150, NEC APC, others...) MUMPS (PDP-11) Software Tools; Ratfor (HP3000, Sperry-Univac 1100) UCSD p-System; Pascal (IBM PC, Terak, HP98x6, Pascal Microengine) UNIX v7,4.xBSD,Sys III/V,Venix,Xenix,PC/IX; C (VAX, PDP-11, SUN, many more) Host Versions: Machine (OS; Language) Burroughs B6800 (Algol) Cray-1, Cray-XMP (CTSS; Fortran-77) CDC Cyber 170 (NOS, NOS/BE; Fortran-77) Data General Nova (RDOS; Fortran-5) Data General Eclipse (AOS; Fortran-5), MV Series (AOS/VS; Pascal) DEC PDP-11 (RT11, RSX11M(+), RSTS, P/OS, TSX+; Macro-11) DEC VAX-11 (VMS; Bliss-32 or Macro-32 or Pascal/Fortran) DECsystem-10 (TOPS-10; Bliss-36, Macro-10), DECSYSTEM-20 (TOPS-20; Macro-20) Harris 800 (VOS; Pascal) Honeywell (MULTICS; PL/I), DPS-6,8 (GCOS; C) Hewlett-Packard 1000 (RTE-6/VM; Fortran), HP3000 (MPE; SPL or Ratfor) IBM 370 Series (VM/CMS, MVS/TSO, MVS/GUTS, MUSIC, MTS; Assembler) Perkin Elmer 3200 Series (OS/32; Fortran) PRIME (PRIMOS; PL/P) Tandem (Nonstop; TAL) Sperry/Univac-1100 (EXEC; Assembler or Ratfor or Pascal) PC Versions: Machine (OS; Language) Alpha Micro 68000 (Assembler) Apollo (Aegis; Fortran or Pascal) Apple II 6502 (Apple DOS; DEC-10/20 CROSS or Apple Assembler) Apple Macintosh (SUMACC C) Atari (DOS; Action!) Commodore 64 (DEC-10/20 CROSS or FORTH) DEC Pro-300 Series (P/OS; Bliss-16 or Macro-11), (Pro/RT; Macro), (Venix; C) Intel Development System (ISIS; PL/M) Perq (Pascal) TRS80 I, III, Model 4 (TRSDOS; ASM) TRS-80 Color Computer (Radio Shack DOS) 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 Page 46 6. DECSYSTEM-20 KERMIT Authors: Frank da Cruz, Bill Catchings, Columbia University Language: MACRO-20 Version: 4.2(257) Date: May 1985 Kermit-20 Capabilities At a Glance: Local operation: Yes Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Y interruption: Yes Filename collision avoidance: Yes Timeouts: Yes 8th-bit prefixing: Yes Repeat character compression: Yes Alternate block check types: Yes Communication settings: Yes Transmit BREAK: Yes IBM mainframe communication: Yes Transaction logging: Yes Session logging: Yes Debug logging: Yes Raw transmit: Yes Login scripts: Yes Act as server: Yes Talk to server: Yes Advanced commands for servers: Yes Local file management: Yes Command/init files: Yes Handle file attributes: No 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. The Kermit-20 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 The features of the DEC-20 file system of greatest interest to Kermit users are the form of the file specifications, and the distinctions between text and bi- nary files. DECSYSTEM-20 KERMIT Page 47 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; for instance, it will not create new directories. The name 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.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 and SAVing 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. DECSYSTEM-20 KERMIT Page 48 TEXT FILES AND BINARY FILES The DEC-20, like most computers, has a file system with its own peculiarities. 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 mainly gibberish. You can not always tell a text file from a binary file by its name or directory information, though in general files with types like .TXT, .DOC, .HLP are tex- tual (as are "source files" for computer programs like text formatters and pro- gramming language compilers), and files with types like .EXE, .REL, .BIN are binary. 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 of bytes within a word are shown in Figure 6-1. 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 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-byte 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. In this case too, Kermit-20 uses the byte count to determine the end of file. Why do you need to know all this? In most cases, you don't. It depends on DECSYSTEM-20 KERMIT Page 49 ------------------------------------------------------------------------------- 7: Text Files: Five 7-bit bytes per word. +------+------+------+------+------++ | | | | | || +------+------+------+------+------++ 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: Four 8-bit bytes per word. +-------+-------+-------+-------+---+ | | | | | | +-------+-------+-------+-------+---+ 0 8 16 24 32 35 Bits 32-35 are unused. 36: "Native" binary files: One 36-bit byte per word. +-----------------------------------+ | | +-----------------------------------+ 0 35 All bits are used. Figure 6-1: DECSYSTEM-20 Word/Byte Organization ------------------------------------------------------------------------------- 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. Microcomputers that run CP/M or MS-DOS or PC-DOS, and any computers than run Unix, store these 8-bit bytes in a linear sequence. Certain other 8-bit-byte systems (PDP-11 or VAX systems with FILES-11, IBM mainframes) have more complex file formats. This discussion applies to all linear 8-bit-byte systems, including most popular 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 DECSYSTEM-20 KERMIT Page 50 holds true between two DEC-20s, or a DEC-10 and a DEC-20. There is, however, one special complication of which you should be aware. Cer- tain microcomputer operating systems, notably CP/M, do not have an entirely satisfactory way of indicating the end of file. The file length is recorded in blocks rather than bytes. For text files, the end of file is marked within a block by inserting a Control-Z after the last data character. Binary files, however, might easily contain Control-Z characters as data. Therefore, in or- der not to lose data, these systems must transmit binary files in complete blocks. If the binary file is of foreign origin (for instance, from a DEC-20), and it did not happen to fill up the last block when it was transferred to the micro, then when that file is sent back to the system of origin in "binary mode," junk will appear at the end (if it is sent back in "text mode," it could be truncated at the first data byte that happened to correspond to Control-Z). For DEC-20 programs in .EXE format, this generally has no effect on the run- nability or behavior of the program. But for other binary files, particularly internal format numerical data or relocatable program object (.REL) files, the junk could have bad effects. For instance, extraneous data at the end of a .REL file will generally cause LINK to fail to load the file. Most microcomputer Kermit programs have commands to control end-of-file detec- tion -- commands like SET FILE TEXT, SET FILE BINARY, SET EOF CTRLZ. 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 explicitly instruct it otherwise. But Kermit-20 has no automatic way of distinguishing an incoming binary file 5 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. 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. The previous discussion assumes you want to store text files in usable form on the DEC-20. However, if you are using the DEC-20 purely as a repository for _______________ 5 Unless the incoming file has an "ITS Binary Header"; see below. DECSYSTEM-20 KERMIT Page 51 your microcomputer files, and you have no desire to display or share the con- tents of those files on the DEC-20, you can SET FILE BYTESIZE 8 for all incom- ing files, both text and binary. When the files are sent back to a microcom- puter, they will be stored correctly. 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 and file attributes are not transmitted. 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.2(257) Kermit-20>send foo.* files are sent Kermit-20>statistics performance statistics are printed Kermit-20>receive 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 DECSYSTEM-20 KERMIT Page 52 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 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. Kermit-20 enters local mode when you issue a SET LINE n command, where n is the octal TTY number of any line other than your own controlling terminal. 6.4. Conditioning Your Job for Kermit Kermit-20 does as much as it can to condition your line for file transfer. It saves all your terminal and link settings, and restores them after use. However, there are some sources of interference over which Kermit-20 can have no control. In particular, messages issued by superior or parellel forks could become mingled with Kermit packets and slow things down or stop them entirely. For this reason, before using Kermit-20 for any extended period, you should: - Type the Exec commands SET NO MAIL-WATCH and SET NO ALERTS - Make sure you don't have any print or batch jobs pending that were submitted with the /NOTIFY option. - Make sure you don't have any superior or parallel forks that have en- abled terminal interrupts on Control-A; these could prevent Kermit packets (which start with Control-A) from getting through. After running Kermit, you can restore your mail-watch and alerts by hand. Al- ternatively, you could have an Exec command file for invoking Kermit like this: set no alerts set no mail-watch DECSYSTEM-20 KERMIT Page 53 ------------------------------------------------------------------------------- Local Operation of Kermit-20: DECSYSTEM-20 +---------------------------------------+ | | | +--------------------+ | | | Your Job | | | | | | | | +------------+ | <--Commands | Your Job's | | | Kermit-20 +---+--------------+----------------- (-: You | | | | | Display---> | Controlling TTY | | | | | | | | | | | | | | | | | <--Packets | Kermit's | | | +---+--------------+-----------------> Remote | | +------------+ | Packets--> | Assigned TTY System | | | | | +--------------------+ | | | +---------------------------------------+ Figure 6-2: DEC-20 Kermit Local Operation ------------------------------------------------------------------------------- kermit set mail-watch set alert 1:00PM Go to lunch set alert 6:00PM Go to dinner set alert 11:30PM Go to sleep 6.5. Kermit-20 Commands This section describes the Kermit-20 commands -- in detail where they differ from the "ideal" Kermit, briefly where they coincide. Kermit-20 has the fol- lowing commands: BYE to remote server. CLEAR a stuck connection CLOSE log file and stop logging remote session. CONNECT as terminal to remote system. CWD change local working directory. DEFINE macros of Kermit-20 commands. DELETE local files. DIRECTORY listing of local files. ECHO a line of text. EXIT from Kermit-20. FINISH Shut down remote server. GET remote files from server. HELP about Kermit-20. INPUT characters from communication line. DECSYSTEM-20 KERMIT Page 54 LOCAL prefix for local file management commands. LOG remote terminal session. OUTPUT characters to communication line. PAUSE between commands. PUSH to TOPS-20 command level. QUIT from Kermit-20 RECEIVE files from remote Kermit. REMOTE prefix for remote file management commands. RUN a DEC-20 program. SEND files to remote Kermit. SERVER mode of remote operation. SET various parameters. SHOW various parameters. SPACE inquiry. STATISTICS about most recent file transfer. TAKE commands from a file. TRANSMIT a file "raw". TYPE a local file. 6.5.1. Commands for File Transfer Kermit-20 provides the standard SEND, RECEIVE, and GET commands for transfer- ring files using the Kermit protocol. 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. DECSYSTEM-20 KERMIT Page 55 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 6 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 the 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 7 ("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. _______________ 6 Control-V's, which are used to quote otherwise illegal characters in DEC-20 file specifications, are stripped. 7 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 Page 56 If you're running Kermit-20 locally, for instance dialing out from the DEC-20 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 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, con- trol characters, etc) with Control-V. If for some reason an incoming filename simply cannot be converted to legal form, the file will be saved as -UNTRANSLATABLE-FILENAME-.KERMIT (new generation). You may also use SET FILE NAMING NORMAL-FORM to have Kermit-20 choose more conventional names for incom- ing 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 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 DECSYSTEM-20 KERMIT Page 57 as arrived to be saved in your directory. If you are running Kermit-20 locally, you should already have issued a SEND 8 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 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. If you need to in- clude otherwise illegal characters such as "!" or ";" (the normal command com- ment delimeters), "?" (the command help character), "@" (the indirect command file indicator), or certain control characters, then you should precede each such character by a Control-V. Kermit-20 will discard these Control-V quoting prefixes before sending the file specification to the remote host. If you want to store the incoming file name with a different name than the remote host sends it with, just type GET alone on a line; Kermit-20 will prompt you separately for the source (remote) and destination (local) file specifica- tion. If more than one file arrives, only the first one will be stored under the name given; the rest will be stored under the names they are sent with. Example: Kermit-20>get Remote Source File: profile exec a1 Local Destination File: profile.exec 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. _______________ 8 not SERVER -- use the GET command to receive files from a Kermit server. DECSYSTEM-20 KERMIT Page 58 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 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 Efficiency: 214.1667 per cent Interpacket pause in effect: 0 sec Timeouts: 0 NAKs: 0 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 efficiency is displayed only if the actual baud rate is known. 6.5.2. Server Operation 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 the following remote server commands: SEND, GET, FINISH, BYE, REMOTE DIRECTORY, REMOTE CWD, REMOTE SPACE, 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. DECSYSTEM-20 KERMIT Page 59 COMMANDS FOR SERVERS When running in local mode, Kermit-20 allows you to give a wide 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. 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, perhaps along with size and date information for each file. If no file specification is given, all files from the current directory will be listed. HELP Provide a list of the functions that are available from the server. HOST [command] Pass the given command to the server's host command processor, and display the resulting output on your screen. SPACE Provide information about disk usage in the current directory, such as the quota, the current storage, the amount of remaining free space. TYPE filespec Display the contents of the specified file on your screen. 6.5.3. Commands for Local File Management 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. DECSYSTEM-20 KERMIT Page 60 DELETE filespec Delete the specified file or files, but do not expunge them (unless you have SET EXPUNGE ON). DIRECTORY [filespec] Provide a directory listing of the specified files. RUN [filespec] Attempts to run the specified file, which must be in ".EXE" format (.EXE is the default filetype), in an inferior fork. Control returns to Kermit-20 when the program terminates. Once you have used this command, you can restart the same program by issuing a RUN command with no arguments. If you RUN SYSTEM:EXEC, then you will be able to issue TOPS-20 commands without leaving Kermit; you can get back to Kermit from the EXEC by typing the EXEC POP command. SPACE Show how much space is used and remaining in the current direc- tory. TYPE Display the contents of the specified file or files at your terminal. This works like the DEC-20 TYPE command, except that if a file has a bytesize of 8, Kermit-20 will do 8-bit input from it rather than 7-bit. Also, the DEC-20 Control-O command discards output only from the file currently being displayed; if multiple files are being typed, then output will resume with the next file. The LOCAL commands may also be used without the "LOCAL" prefix. 6.5.4. 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-Backslash (^\) by default. When you type the es- cape character, several single-character commands are possible: C Close the connection and return to Kermit-20. S Show status of the connection; equivalent to SHOW LINE. 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. ^\ (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, SET FLOW, and SET SPEED to change those communication-line-oriented parameters. In order for the simulated BREAK sig- nal to work, TOPS-20 must know the speed of the terminal. If it does not, you may use the SET SPEED command. Type the SHOW LINE command for information DECSYSTEM-20 KERMIT Page 61 about your current communication settings. Kermit-20 does not have any special autodialer interface. It assumes that the connection has already been made and the line assigned. 6.5.5. The SET, SHOW, and DEFINE Commands SET is used for establishing or changing parameters, DEFINE lets you group several SET commands together into a single "macro" command, and SHOW lets you examine current settings or macro definitions. 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: BREAK Adjust the BREAK simulation parameter BLOCK-CHECK Packet transmission error detection method DEBUGGING Record or display state transitions or packets DELAY How long to wait before starting to send DUPLEX For terminal connection, FULL or HALF ESCAPE Character for terminal connection FILE For setting file parameters like byte size FLOW-CONTROL For enabling or disabling XON/XOFF flow control HANDSHAKE For turning around half duplex communication line IBM For communicating with an IBM mainframe INCOMPLETE What to do with an incomplete file INPUT For specifying behavior of the INPUT command ITS-BINARY For recognizing a special 8-bit binary file format LINE TTY line to use for file transfer or CONNECT PARITY Character parity to use PROMPT Change the program's command prompt RECEIVE Various parameters for receiving files RETRY How many times to retry a packet before giving up SEND Various parameters for sending files SPEED Baud rate of communication line TVT-BINARY For negotiating binary mode on ARPANET 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 BREAK Syntax: SET BREAK n Specify the number of nulls to be sent at 50 baud to simu- late a BREAK signal when connected to a remote host via SET LINE and CONNECT. DECSYSTEM-20 KERMIT Page 62 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). OFF Don't display or record debugging information (this is the nor- mal mode). If debugging was in effect, turn it off and close any log file. The debugging information is recorded in the file specified by the most recent LOG DEBUGGING command, DEBUGGING.LOG by default. 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 34 (Control-\). The number is the oc- tal value of the ASCII control character, 1 to 37 (or 177), 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 EXPUNGE SET EXPUNGE ON or OFF Tell whether you want a DELETE command (either the LOCAL DELETE command or a REMOTE DELETE command sent to a Kermit-20 server) to expunge files as it deletes them. On the DEC-20, a deleted file continues to take up space, and may be "undeleted" at a later time in the same session. To expunge a deleted file means to remove it completely and irrevocably, freeing its space for fur- ther use. EXPUNGE is OFF by default; deleted files are not automatically ex- punged. SET EXPUNGE applies only to files that are deleted explicitly by Kermit-20, and not to files that are implicitly deleted when new generations of existing files are created. SET FILE Syntax: SET FILE parameter keyword Establish file-related parameters: BYTESIZE keyword or number Byte size for DEC-20 file input/output. The choices are SEVEN (7), DECSYSTEM-20 KERMIT Page 63 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 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-20 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 explicit SET FILE BYTESIZE commands to Kermit. DECSYSTEM-20 KERMIT Page 64 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. This facility is provided for compatibility with the file formats used on cer- tain public-access CP/M libraries. SET INPUT Syntax: SET INPUT parameter value The INPUT command is used in TAKE command files or DEC-20 Batch control files as part of the login script facility, which is explained in greater detail later. SET INPUT controls the behavior of the INPUT command. The parameters are as follows: SET INPUT DEFAULT-TIMEOUT n n is the number of seconds for an INPUT command to time out after not receiving the requested input, when no interval is explicitly given in the INPUT command. For instance, if the default timeout interval is 10 seconds, then the command INPUT login: will look for the "login:" prompt for 10 seconds. The default may be overriden by including an explicit interval in the INPUT command: INPUT 15 login: The default timeout interval is 5 seconds. SET INPUT TIMEOUT-ACTION PROCEED or QUIT If the INPUT command comes from a Kermit-20 command file (see TAKE command) or a TOPS-20 Batch control file, then use this command to specify whether processing of the command file should proceed or quit after a timeout occurs. For TAKE files, the current command file is terminated and control returns to the invoking level (Kermit-20 prompt level, or a superior TAKE file). The default action is PROCEED. SET INPUT CASE IGNORE or OBSERVE Specify whether alphabetic case should be ignored ("a" matches "A") or observed ("a" does not match "A") when scanning the input for the specified search string. By default, aphabetic case is ignored. SET INPUT commands are "global"; the settings are not "pushed" and "popped" when entering or leaving TAKE command files. DECSYSTEM-20 KERMIT Page 65 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; the command CONNECT 12 is equivalent to SET LINE 12 CONNECT If you type SET LINE with no number argument, you will deassign any previous assigned line and revert to remote mode. The SHOW LINE command will display the currently selected communication line and its charactistics, including parity, duplex, handshake, flow control, the speed if known, whether carrier is present (if it is a modem-controlled line), and whether Kermit-20 is in local or remote mode. SET RECEIVE In addition to the full complement of SET RECEIVE commands described in the main part of the Kermit User Guide, you may also SET RECEIVE SERVER-TIMEOUT to a value between 0 and 94. This specifies the number of seconds between timeouts during server command wait, 0 specifies that no timeouts should occur during server command wait. When a Kermit server times out, it sends a NAK packet. Some systems cannot clear piled-up NAKs from their input buffers; if you're using such a system to communicate with a Kermit-20 server, and you ex- pect to be leaving the server idle for long periods of time, you should use this command to turn off server command-wait timeouts. SET SPEED Syntax: SET SPEED n Set the baud rate of the currently selected communication to n, the decimal baud rate, for instance 300, 1200, 4800. When operating in local mode, it may be necessary to issue this command in order to enable BREAK simulation. SET TVT-BINARY Syntax: SET TVT-BINARY ON or OFF Only for users running Kermit-20 on an ARPANET DEC-20, signed on to an ARPANET virtual terminal (TVT) from another host or through an ARPANET TAC. SET TVT ON causes Kermit-20 to negotiate binary mode (8-bit) communication with the AR- DECSYSTEM-20 KERMIT Page 66 PANET during file transfer. Without this command, file transfer through a TVT would not work in most cases. TVT-BINARY is OFF by default. If you normally use Kermit-20 through the AR- PAnet, you can put the command SET TVT-BINARY ON into your KERMIT.INI file. CAUTION: This facility requires certain features in the Release 5 TOPS-20 AR- PANET monitor, which may not be present in releases distributed by DEC. See the Kermit-20 source code for details. 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, receive server 0 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 Syntax: SHOW [option] The SHOW command displays various information: DAYTIME Current date, time, phase of moon. DEBUGGING Debugging mode in effect, if any. FILE-INFO Byte size for DEC-20 file i/o, incomplete file disposition. INPUT INPUT command parameters. LINE TTY line, parity, duplex, flow control, handshake, escape character, speed (if known), and session loggin information. Note that before release 6.0 of TOPS-20, the DEC-20 does not keep a record of the actual baud rate of a modem-controlled or "remote" 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. This is also displayed when DECSYSTEM-20 KERMIT Page 67 Kermit-20 is initially started. ALL (default) All of the above. 6.5.6. Program Management Commands 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. Default file type for the command file is .CMD. THE ECHO COMMAND Syntax: ECHO line of text The line of text is echoed at the terminal. This is useful when issued from within TAKE command files, to report progress or issue instructions. 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 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. QUIT is a synonym for EXIT. DECSYSTEM-20 KERMIT Page 68 THE LOG COMMAND Syntax: LOG [option [filespec]] Log the specified option to the specified file: SESSION During CONNECT or execution of a login script, log all charac- ters that appear on the screen to the specified file. During CONNECT, 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-Feb-1984 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 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. DEBUGGING Log STATES or PACKETS, as specified in the most recent SET DEBUGGING command, to the specified file. If log file not specified, then use TTY if local, or DEBUGGING.LOG in the cur- rent directory if remote. If no SET DEBUGGING command was previously issued, log STATES to the specified file. Also al- low specification of bytesize for the log file, 7 (normal, default), or 8 (for debugging binary transfers when the parity bit is being used for data), for instance LOG DEBUGGING BINARY.LOG 8 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 ex- amined with a system utility like FILDDT. When logging pack- DECSYSTEM-20 KERMIT Page 69 ets, each packet is preceded by a timestamp, the current timeout interval (preceded by a slash), and "R:" or "S:" to in- dicate data being received and sent, respectively. Packet for- mat is described in the Kermit Protocol Manual. SESSION is the default option. Thus the command "LOG" alone will cause CONNECT sessions to be logged in SESSION.LOG in the current directory. Any log files are closed when you EXIT or QUIT from Kermit, and are reactivated if you CON- TINUE the program. You may explicitly close a log file and terminate logging with the CLOSE command. THE CLOSE COMMAND Syntax: CLOSE option Close the specified log file, SESSION, TRANSACTION, or DEBUGGING, and terminate logging to that file. 6.6. Login Scripts: The INPUT, OUTPUT, CLEAR, and PAUSE Commands When running Kermit-20 in local mode, connecting from the DEC-20 to another system via an external TTY line (for instance, through an autodialer), you may use the Kermit-20 INPUT, OUTPUT, CLEAR, and PAUSE commands to carry on a dialog with the remote system. When combined into a "script" in a Kermit-20 TAKE com- mand file, or included in a Batch control file, these commands provide the ability to initially connect and log in to a remote system, and to set it up for file transfer. While you may do this yourself manually using the CONNECT command, the login script facility allows this often tedious task to be automated, and more important, allows it to take place unattended -- perhaps late at night when the phone rates are low and the system is faster. During script execution, session logging may be used to record the dialog. THE CLEAR COMMAND Syntax: CLEAR Clear the input and output buffers of the currently selected line, and attempt to clear any XOFF deadlock. THE PAUSE COMMAND Syntax: PAUSE [interval] Pause the specified number of seconds before executing the next command. The default interval is one second. DECSYSTEM-20 KERMIT Page 70 THE INPUT COMMAND Syntax: INPUT [interval] [string] On the currently selected communication line, look for the given string for the specified interval of time, which is specified in seconds. If no interval is specified, then wait for the default interval, which may be specified by SET INPUT DEFAULT-TIMEOUT, and is normally 5 seconds. Specifying an interval of 0 (or less) means no timeout -- wait forever for the specified string. An INPUT command can by interrupted by typing one or more Control-C's, which will return you to Kermit-20> prompt level. Characters coming in from the line will be scanned for the search string, and when a match is found, the command will terminate successfully; if the string is not found within the given interval, the command will terminate unsuccess- fully. While the INPUT command is active, all incoming characters will appear on your screen. The search string may contain any printable characters. Control or other spe- cial characters that you could not normally type as part of a command may be included by preceding their octal ASCII values with a backslash, for instance foo\15 is "foo" followed by a carriage return (ASCII 15, octal). A backslash alone will be taken as is, unless it is followed by an octal digit (0-7); if you want to actually specify a backslash in this context, double the backslash (\\5 will be taken as \5). While scanning, alphabetic case is ignored ("a" = "A") unless you have SET IN- PUT CASE OBSERVE. If no search string is given, then the INPUT command will simply display all incoming characters on your screen until it times out or is interrupted. If the INPUT command finds the specified string within the alloted amount of time, it terminates immediately, without an error message, and the next command will be executed. If the INPUT command fails to find the requested string, it will "fail"; failure is only significant if the command was issued from a TAKE command file or a Batch control file, and INPUT TIMEOUT-ACTION is SET to QUIT. When a timeout occurs under these conditions, the command file is immediately terminated and control is returned to the invoking level, either Kermit-20> prompt level or a superior command file, and an error message is issued at the terminal which begins with a "?", which signals the Batch controller to detect an error. If INPUT TIMEOUT-ACTION is SET to PROCEED, then the next command (if any) will be executed from the current command file, and any timeout error mes- sages will be issued starting with a "%", which does not signal an error to Batch. In addition to otherwise untypable control characters (like Control-C), certain printable characters in the search string may need to be "quoted" using the backslash mechanism: @ (ASCII 100) If it is the first character in the string, atsign tells TOPS-20 that the following characters will be the name of an indirect command file, for instance input 10 @foo.txt tells Kermit to spend 10 seconds scanning the communication DECSYSTEM-20 KERMIT Page 71 line input for the string which is contained in the file FOO.TXT. If you need to specify a string that starts with "@", use \100 instead. ? (ASCII 77) A question mark tells TOPS-20 to provide a brief help message about this part of the command; use \77 instead. ! (ASCII 41) If it is the first character in the string, an exclamation point will cause TOPS-20 to ignore the rest of the string, i.e. treat it as a comment, use \41. ; (ASCII 73) Same as exclamation mark, use \73. ( (ASCII 50) In first position, TOPS-20 will think this marks the beginning of a "guide word"; use \50. - (ASCII 55) In final position, a dash tells TOPS-20 that the command line is to be continued, concatenated with the following line. Use \55 instead of a final dash. For instance, to specify the string "More?--", use "More\77-\55". THE OUTPUT COMMAND Syntax: OUTPUT string The given string is sent out the currently selected communication line. The string is in the same form as the INPUT string; control or special characters may be included by prefacing their octal ASCII value with a backslash. Note that any terminating carriage return must be included explicitly as \15. The string will also be echoed at your terminal. HOW TO USE LOGIN SCRIPTS Login scripts are useful on DEC-20's that have autodialers or TTY ports hardwired or otherwise connected to terminal ports on other systems. Scripts can be used to automate the task of connecting and logging in. For instance, suppose your DEC-20 is connected to a VAX Unix system through a hardwired line on TTY port 13. To send a file to the VAX, you must connect to the VAX through the port, log in, run Unix Kermit, escape back to the DEC-20, and issue the ap- propriate file transfer commands, then connect back to the VAX and logout. This may all be automated by means of the following "script" stored in a DEC-20 file invoked by the Kermit-20 TAKE command: set line 13 output \15 input login: out myuserid\15 in 10 Password: out mypassword\15 in 20 % out kermit -r\15 send foo.bar out \4 input DECSYSTEM-20 KERMIT Page 72 The first line points Kermit-20 at the communication line. The next line sends a carriage return, which makes Unix issue a "login:" prompt; the following IN- PUT command waits for this prompt to appear. When it does, Kermit-20 outputs "myuserid" followed by a carriage return. Unix then prompts for a password; after the prompt appears, Kermit-20 supplies the password. Then, Kermit-20 waits up to 20 seconds for the Unix shell's "%" prompt; this allows time for various system messages to be displayed. When the shell prompt appears, Kermit-20 sends the command "kermit -r", which tells Unix Kermit to receive a file; then a SEND command is given to Kermit-20. After the file is success- fully transferred, Kermit-20 sends a logout command (Control-D, "\4") to Unix. The final INPUT command causes Kermit-20 to display any typeout (in this case the Unix system's logout message) that occurs up to the default timeout inter- val. The INPUT command is very important, because it ensures synchronization. One might expect to be able to simply send all the characters out the communication line at once, and let the remote host's typeahead and buffering facilities take care of the synchronization. In rare or simple cases, this might work, but it assumes that (a) the remote host allows typeahead, (b) the remote host's typeahead buffers are big enough to accommate all the characters, and (c) that the remote host never clears pending typeahead. These conditions rarely hold. For instance, Unix clears its input buffer after issuing the "Password:" prompt; any typeahead will be lost. Interactive users as well as login script facilities must wait for the prompt before entering the password. This is the function of the INPUT command. On half duplex systems, this function is criti- cal -- these systems cannot accept any input in advance of a prompt; there is no typeahead. Note, by the way, that it is not a good idea to store passwords in plain text in a file. The facilities of the TOPS-20 command parser make this unnecessary, so long as you are sitting at your terminal. Suppose the above login script is stored in the file UNIX.CMD. If you change the line out mypassword\15 to out @tty: you may enter the password from your terminal as follows: login: myuserid Password: mypassword\15^Z That is, you type the password, a backslash-encoded carriage return, and then Control-Z. This may be done even when executing commands from a TAKE file; after the ^Z, control returns to the TAKE file. In the OUTPUT command, "@TTY: designates TTY: (your job's controlling terminal) to be an indirect command file; the ^Z is the "end of file" for a terminal. This same technique could have been used in the first script example to allow you to supply from the ter- minal the name of the file to be sent. It might be a good idea to for you to include an ECHO command in your script file to remind you to do this, for in- stance: input password: echo ^GType your password, followed by "\15" and then a CTRL-Z DECSYSTEM-20 KERMIT Page 73 output @tty: The ^G is a Control-G, which should get your attention by sounding a beep at your terminal. One might expect to be able to use the same indirect file mechanism with the OUTPUT command to provide a crude "raw upload" facility, as in output @foo.bar to send the contents of the file FOO.BAR to the remote system, with no synchronization or error checking. Unfortunately, there are two problems with this approach: first, TOPS-20 converts all carriage return / linefeeds in an indirect command file to spaces, and second, only very short files may be treated this way, because they must fit within TOPS-20's command "atom" buffer. The Kermit-20 TRANSMIT command provides a synchronized raw uploading of files. The Kermit script facility is not a programming language; there is no con- ditional execution of commands, no branching, no labels. Nevertheless, the SET INPUT command provides a degree of control. If the Unix system were down in the sample script above, Kermit-20 would still proceed merrily through the en- tire script, sending its output into the void and waiting the entire timeout interval on each INPUT command, then attempting to send a file to a Kermit that wasn't there. It could take several minutes of timing out to terminate the script. This could be avoided by including the command SET INPUT TIMEOUT-ACTION QUIT at the top of the script. When the "login:" prompt failed to appear within the timeout interval, the rest of the script would be cancelled. Kermit-20's nested command file capability combined with input timeout action selection can be used to provide a kind of "if-then-else" feature. Suppose you want to log in automatically to a system which sometimes asks you a question immediately after you log in. You don't want to always include the answer (say, "no") because if you type the string "no" at normal system command level, it performs some undesirable function. You can handle the situation by writing a script that invokes another script. In this example, the system's prompt is "%" and the question's prompt ends in "?". set input def quit output \15 input login: out myuserid\15 in 10 password: echo Type your password now^G out @tty: take question in % out who\15 Here, after logging in successfully, the Kermit command file QUESTION.CMD is invoked from within this fragment of the UNIX.CMD file; QUESTION.CMD looks like this: input \77 DECSYSTEM-20 KERMIT Page 74 output no\15 If the question mark appears, Kermit-20 will answer no. If not, a timeout will occur, and the current command file will be terminated without outputting the "no", returning control to the command file that invoked it. The Kermit script facility allows complicated tasks to be performed routinely, since any Kermit commands can be included in a command file. For instance, at Columbia all systems are reached through a port contention unit, which prompts you for a system and then connects you to it. That system may itself be another "front end" which prompts you for yet another system. Each of these systems may have different characteristics as to duplex, parity, and so forth: set parity none set duplex full set flow none input => pause output cuvm\15 input valid-sw-chars are A B pause output B\15 set duplex half set parity mark set handshake xon output \15 input .\21 output login myuserid\15 input .\21 echo ^G Type your password, \15, ^Z output @tty: In this fragment, we talk full duplex no parity to the port switcher, select the "cuvm" front end, then select the "b" system, then switch to mark parity, half duplex, XON handshaking, for system B. Then we log in to the half duplex B system, which always issues a prompt of "." followed by an XON (^Q, ASCII 21 octal) when it is ready for input. Note the judicious use of the PAUSE com- mand, to give these often slow switching devices enough time to prepare them- selves for input; the fact that they have issued a prompt is not necessarily enough. The script facility allows Kermit-20 to operate under TOPS-20 Batch. This is desirable for performing routine file transfer late at night, when systems are not as busy and phone rates are lower. Without scripts, there is no good way to log in to the remote system without encountering the typeahead problems men- tioned above. Login scripts provide the necessary synchronization. Suppose a Columbia University professor is collaborating on a research project with a colleague at the University of Saskatchewan, and there is no network link be- tween the two machines, which are both DEC-20's. The researcher in Saskatoon has left new data in the directory called . The cost-conscious Colum- bia professor leaves the following batch job to be executed after 3:00 A.M. (by using the DEC-20 SUBMIT/AFTER command), and then goes home. @dial saskatchewan * *Kermit DECSYSTEM-20 KERMIT Page 75 *set input take-action quit ! Look for an atsign prompt *input \100 ! Log in *output login myuserid mypassword\15 ! Wait for atsign prompt *in \100 ! Start up a Kermit server *out Kermit server\15 ! Let it print its startup message *set input take-action proceed *input 10 *pause ! Get the files from the remote server *get *.* ! Shut down and log out the remote server *bye ! Done with Kermit *exit ! Let's see what new files we have. @vdirectory *.*.0, @since today @ @ The next day, the batch log file can be examined to determine the progress of the batch job. If any errors occurred (the phone number could not be dialed, an INPUT command timed out), the error messages will cause the batch job to terminate. It is also possible to construct the batch control file to resubmit itself to run, say, an hour later if it fails. In the example above, the "\100" specifies an atsign (@), which is the DEC-20's prompt. It can't be written as an atsign in the INPUT command, however, be- cause in that context it would denote an indirect command file; this is where the backslash mechanism can come in handy. The "dial" command invokes a program that looks up its "argument" (Saskatchewan in this case) in a phone list, dials the corresponding number on an autodial modem, and then invokes Kermit-20 in a lower fork with the correct line number already set. INPUT and OUTPUT commands are then used to log in and start up a Kermit server on the remote end and then normal Kermit commands (GET, BYE) are used to get the desired files and disconnect. Dialing programs are highly site-dependent, and therefore cannot be made part of Kermit-20. However, a DEC-20 that has a dialout modem connected to one of its ports can be controlled directly by Kermit-20, if the user can assign the port. Suppose, for example, such a modem is connected to TTY6:, and accepts commands of the form +++Dnnnnnnn, where the +++ is a special sequence of characters to get the modem's attention, and which must be preceeded and fol- lowed by at least a full second of "silence", and D is a command to the modem to dial the following number (which ends with a carriage return). If the num- ber is dialed successfully and is answered by a carrier signal, then the modem replies "-X" (in upper case) and makes the connection, otherwise it replies "-x" (lower case). The following script could be used with such a modem: set input take quit set input case observe DECSYSTEM-20 KERMIT Page 76 set line 6 pause 1 output +++ pause 1 output D5551212\15 input 30 -X set input case ignore output \15 Here, SET commands are used to achieve the desired effects -- if the number can't be dialed, or a confirmation is not returned, execution of the script will stop. PAUSE commands delimit the "+++" by the required amount of silence. 6.7. Raw Download and Upload "Raw Download" is the term commonly used to describe the capture of a remote file on the local system, without any kind of error detection or correction. This allows you to obtain files from remote systems that do not have Kermit, but with the risk of loss or corruption of data. Kermit-20 provides raw downloading via the LOG SESSION command during CONNECT to a remote system. The session log is described above. To use session log- ging to capture a file: 1. Run Kermit on the DEC-20. 2. SET LINE to the TTY number through which you will be connected to the remote system. 3. Perform any required SET commands to condition Kermit for communica- tion with the remote system. You may need SET PARITY, SET DUPLEX, SET FLOW, SET HANDSHAKE, etc., depending on the characteristics of the remote system and the communication medium. 4. CONNECT to the remote system and log in. 5. Condition your job on the remote system not to pause at the end of a screenful of text, and give whatever commands may be necessary to achieve a "clean" terminal listing -- for instance, disable messages from the system or other users. 6. Type the appropriate command to have the desired file displayed at the terminal, but do not type the terminating carriage return. On most systems, the command would be "type", on Unix it's "cat". 7. Escape back to Kermit to the DEC-20 and give the LOG SESSION com- mand. 8. CONNECT back to the remote system and type a carriage return. The file will be displayed on your screen and recorded in the session log file. 9. Escape back to Kermit on the DEC-20 and give the CLOSE SESSION com- mand. DECSYSTEM-20 KERMIT Page 77 The file will be in SESSION.LOG in your connected directory, unless you gave another name for it in your LOG SESSION command. You will probably find that some editing necessary to remove extraneous prompts, messages, padding charac- ters, or terminal escape sequences, or to fill in lost or garbled characters. Here's an example showing how to capture a file foo.bar from a remote Unix sys- tem: @kermit Kermit-20>set line 23 Kermit-20>connect [KERMIT-20: Connecting to remote host over TTY23:, type C to return.] 4.2 BSD UNIX login: myuserid Password: mypassword % cat foo.bar^\C [KERMIT-20: Connection Closed] Kermit-20>log session foo.bar Kermit-20>connect [KERMIT-20: Connecting to remote host over TTY23:, type C to return.] [KERMIT-20: Logging to File FOO.BAR.1] (Type carriage return now.) This is the file foo.bar. It has three lines. This is the last line. % ^\ [KERMIT-20: Closing Log File FOO.BAR.1> [KERMIT-20: Connection Closed] Kermit-20>close session Note that in this case, the Unix "% " prompt at the end of the text will have to be edited out. RAW UPLOAD "Raw Upload" means sending a file from the local system to a remote one, again without error detection or correction. This allows you to send files from the DEC-20 to remote systems that don't have Kermit. Kermit-20 provides the TRANS- MIT command for this purpose. Syntax: TRANSMIT filespec [prompt] For use in local mode only. Sends the specified text file a line at a time, "raw" (as is, without using Kermit protocol), to the remote system, waiting for the specified prompt for each line. Only a single file may be sent with the TRANSMIT command; wildcards are not allowed in the filespec. The file should be a text file, not a binary file. Since protocol is not being used, no as- surance can be given that the file will arrive at the destination correctly or completely. The prompt is any string, for instance the prompt of a line editor in text in- sertion mode. The prompt string may include special characters by preceding their octal ASCII values with a backslash, e.g. \12 for linefeed, \21 for XON DECSYSTEM-20 KERMIT Page 78 (^Q). The syntax of the prompt string is explained in greater detail above, with the INPUT command. If a prompt string is supplied, alphabetic case will be ignored in searching for it unless you SET INPUT CASE OBSERVE. If a prompt string is not supplied, then linefeed will be used by default, unless you have performed a SET HAND- SHAKE command, in which case the current handshake character will be used. If you really want to send the entire file without waiting for any prompts, specify a prompt of "\0" (ASCII zero, null) (this is not advised). The file will be sent using the current settings for duplex, parity, and flow control. There are no timeouts on input, as there are with the INPUT command. The TRANSMIT command waits forever for the prompt to appear. However, if you observe that the transfer is stuck, there are three things you can do: - Type a Carriage Return to transmit the next line. - Type a Control-P to retransmit the line that was just transmitted. - Type two Control-C's to cancel the TRANSMIT command and get back to Kermit-20> command level. TRANSMIT should be used as follows: CONNECT to the remote system, login, and start up some kind of process on the remote system to store input from the ter- minal into a file. On a DEC-20 (that doesn't have Kermit), you could do copy tty: foo.bar or you could start a line editor like EDIT or OTTO and put it into text inser- tion mode. On a Unix system, you could cat /dev/tty > foo.bar or you could run "ed" and give it the "a" command. The Kermit-20 TRANSMIT command will send the first line of the file im- mediately. Then it will wait for a "prompt" from the remote system before sending the next line. When performing a copy operation from the terminal to a file, the "prompt" will probably be a linefeed, "\12" which is the default prompt -- most full duplex systems expect you to type a line of text terminated by a carriage return; they echo the characters you type and then output a linefeed. Half duplex systems, on the other hand, use some kind of line tur- naround handshake character, like XON (Control-Q), to let you know when they are ready for the next line of input. Line editors like EDIT and OTTO prompt you with a line number followed by a tab; in that case your prompt character would be "\11" (be careful -- if the remote DEC-20 doesn't think your terminal has hardware tabs, it will simulate them by outputting spaces). In any case, to assure synchronization, it is your responsibility to set up the target sys- tem to accept line-at-a-time textual input and to determine what the system's prompt will be when it is ready for the next line. Each line is sent with a terminating carriage return; linefeeds are not sent, since these are supplied by the receiving system if it needs them. The TRANS- MIT command continues to send all the lines of the file in this manner until it reaches the end, or until you interrupt the operation by typing Control-C's. DECSYSTEM-20 KERMIT Page 79 If you cannot make the TRANSMIT command work automatically, for instance be- cause the remote system's prompt changes for each line, you may TRANSMIT manually by specifying a prompt string that will not appear, and then typing a carriage return at your keyboard for each line you want to send. If the TRANSMIT command completes successfully (you'll get a message to the ef- fect that the transmission is complete), then you must connect back to the remote system and type whatever command it needs in orderto save and/or close the file there. 6.8. Kermit-20 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-MS>connect @ @Kermit TOPS-20 Kermit version 4.2(257) Kermit-20>server Kermit Server running on DEC-20 host. Please type your escape sequence to return to your local machine. Shut down the server by typing the Kermit BYE command on your local machine. ^[C Kermit-MS>get foo.txt The transfer takes place. Kermit-MS>exit A> A>edit foo.txt ; (or whatever...) A> A>Kermit Kermit-MS>send foo.txt The transfer takes place. Kermit-MS>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. DECSYSTEM-20 KERMIT Page 80 Kermit-MS>connect @ @Kermit TOPS-20 Kermit version 4.2(257) Kermit-20>receive ^]C Kermit-MS>send *.txt Textual files are sent. Kermit-MS>connect Kermit-20>set file bytesize 8 Kermit-20>receive ^]C Kermit-MS>send *.exe Binary files are sent. Kermit-MS>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 DECsystem-10); 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.2(257) Kermit-20>connect 11 [Kermit-20: Connecting 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 DECSYSTEM-20 KERMIT Page 81 .r new:Kermit TOPS-10 Kermit version 2(106) Kermit-10>server [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 [Kermit-20: 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 Note the use of Control-A to get a status report during the transfer. 6.9. Installation of Kermit-20 Kermit-20 is built from a single MACRO-20 source file, K20MIT.MAC. It requires the standard DEC-distributed tools MONSYM, MACSYM, and CMD; the following files should be in SYS: -- MONSYM.UNV, MACSYM.UNV, MACREL.REL, CMD.UNV, and CMD.REL. The CMD package is also included with the Kermit distribution as K20CMD.*, in case you can't find it on your system. The program should work on all TOPS-20 systems as distributed, but many cus- tomizations 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 reassem- bling. 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. DECSYSTEM-20 KERMIT Page 82 Sites that do not have ARPANET may wish to delete the TVT-BINARY entries from SET command tables, SETABL and SETHLP. VAX/VMS KERMIT Page 83 7. VAX/VMS KERMIT Authors: Robert C. McQueen, Nick Bush, Stevens Institute of Technology Language: BLISS-32 Version: 3.2 Date: May 6, 1986 VAX/VMS Kermit-32 Capabilities At a Glance: Local operation: Yes Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Y interruption: Yes Filename collision avoidance: Yes Timeouts: Yes 8th-bit prefixing: Yes Repeat character compression: Yes Alternate block check types: Yes Communication settings: Yes Transmit BREAK: No IBM mainframe communication: Yes Transaction logging: Yes Session logging: Yes Debug logging: Yes Raw transmit: No Login scripts: No Act as server: Yes Talk to server: Yes Advanced commands for servers: Yes Local file management: Yes Command/init files: Yes Attribute packets: No Kermit-32 is a program that implements the Kermit file transfer protocol for the Digital Equipment Corporation VAX series computers under the VAX/VMS operating system. It is written in BLISS-32 and MACRO-32, with sources for all BLISS modules also available as MACRO-32 sources. Kermit-32 should run on any VAX/VMS system from version 3 on (Version 3.1 of Kermit-32 corrected some problems that appeared in earlier versions when run under VMS version 4). The first section of this chapter will describe the things you need to know about the VAX/VMS file system and how Kermit-32 uses it. The second section describes the special features of Kermit-32. The final section contains infor- mation of interest to those who need to install Kermit-32 on a system. VAX/VMS KERMIT Page 84 7.1. The VAX/VMS File System The two main items of interest of the VAX/VMS file system (for the Kermit user) are the format of file specifications and the types of files and file data. VAX/VMS File Specifications VAX/VMS file specifications are of the form NODE::DEVICE:[DIRECTORY]NAME.TYPE;VERSION Under version 3.x of VMS, NAME may be up to 9 characters, TYPE may be up to 3 characters and each item in DIRECTORY may be up to 9 character long. Only al- phanumeric characters may be used in DIRECTORY, NAME and TYPE. VERSION is a decimal number indicating the version of the file (generation). DEVICE may be either a physical or logical device name. If it is a logical name, it may be up to 63 characters long and may contain alphanumeric characters plus dollar signs and underscores. NODE may be either a logical name which translates to a DECnet node name or a physical DECnet node name. In either case, access infor- mation can be included (see the DECnet-VMS User's guide for more information). The node name is not normally present, since most files are accessed on the same node where the user's job is running. The version number is not normally given (in fact, should not normally be given). When device and/or directory are not supplied, they default to the user's current default device and direc- tory. Therefore, NAME.TYPE is normally all that is needed to specify a file on the user's default device and directory. This is also all the Kermit-32 will normally send as the name of a file being transferred. The node field specifies the name (and access information) for the DECnet node where the file is located. Kermit-32 does not transmit the node field to the target system, but will attempt to honor a node field in an incoming file name. 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-32 does not nor- mally transmit the device or directory fields to the target system, but will attempt to honor device or directory fields that may appear in incoming file names. It will not create new directories, however, so any directory must al- ready exist. The name 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.FOR is the source of a Fortran program named FOO; FOO.OBJ might be the relocatable object module produced by compiling FOO.FOR; FOO.EXE could an executable program produced by LINKing FOO.REL, and so forth. VAX/VMS allows a group of files to be specified in a single file specification 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 default direc- tory. FOO.* Files of all types with name FOO. VAX/VMS KERMIT Page 85 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 two 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 file system used by VAX/VMS provides for a large number of attributes to be associated with each file. These attributes provide some indication of whether the file is a text file, or is some other type of non-text data. The two major attributes that affect Pro/Kermit are the record type and record attribute. The record type describes how logical records are stored in the file. Records may be of some fixed length (specified by another attribute), or variable length (specified within each record), or stream (implying no real record divisions). The record attributes describe how the breaks between records are to be treated. For example, a record attribute of implied carriage return means that any program reading the file with intentions of printing it out should add a carriage return/line feed sequence between each record. Other at- tributes include FORTRAN carriage control and print file format. The "standard" method of storing text in a file under VAX/VMS is to store one line of text per record (variable length records), with a carriage return/line feed sequence implied by the end of the record (implied carriage return). This is the method Kermit-32 uses to store files it receives when using FILE TYPE TEXT. Note that there are other formats which are used to store text under VAX/VMS, however, the one used be Kermit-32 is the only one which is handled correctly by all known utility programs under VAX/VMS. Also, most programs which work with text files (the editor EDT, for example) place some limit on the length of the lines which can be handled. Typically this is 255. Kermit-32 can write files with up to 4095 characters on a line, which means a text file from another system may be transferred and stored correctly by Kermit-32, but may still be unusable by certain VAX/VMS programs. There is no standard format for storing binary files. Basically, any record format with no record attributes are used for binary files. Since programs which work with binary files under VAX/VMS expect to see some particular for- mat, more infomation is needed for transfer of binary files than for transfer of text files. The current version of Kermit-32 is not capable of transferring all types of binary files which were created on a VAX/VMS system to another system and retrieving them intact, nor is it capable of transferring all of types binary files created on a VAX/VMS system to another VAX/VMS, P/OS, or RSX-11M/M+ system intact. However, certain formats of binary files can be transferred, and binary files from some other systems may be transferred to a VAX and recovered intact. Binary files which are created on a VAX (or other Files-11 systems) with fixed 512 byte records (a fairly common format) can be transferred using Kermit-32. The only required action is to set the file type to "fixed" in the receiving Kermit-32. VAX/VMS KERMIT Page 86 Using two programs supplied with Kermit-32, it is possible to transfer almost any type of sequential file between VAXen, or between a VAX and a P/OS or RSX-11M/M+ system. These two programs (VMSHEX and VMSDEH) will convert the bi- nary files to text (using a variation on Intel hex format). The resulting text file can be transferred like any other, and finally "dehexified" reproducing the original file, with the major attributes intact. Unfortunately, the text files tend to be about twice the size of the original binary files, so the transfers take a bit longer than regular text files. On the plus side, the text versions of the files can be transferred to any system with a Kermit and still retrieved intact. They can also be transferred over 7-bit data paths without any problems. The bootstrap procedure (described below), makes use of hexified versions of the binary file which makes up Kermit-32. USING THE VAX TO ARCHIVE MICROCOMPUTER FILES You can use Kermit to send textual files from a microcomputer or any 8-bit sys- tem to a VAX/VMS system with no special provisions, since Kermit-32 stores in- coming files as text files (variable length records with implied carriage returns) unless it is explicitly told otherwise. But Kermit-32 has no automatic way of distinguishing an incoming binary file from an incoming text file. It turns out that because of the method used by Kermit-32 for storing text files, a binary file can be stored like a text file so long as it does not contain a string of more than 4095 characters between carriage return, line feed sequences, and ends with a carriage return line feed. Since most binary files do not have these characteristics, you must inform Kermit-32 that a file it is about to receive is to be stored as a binary file. This is done using the SET FILE TYPE BINARY command. This instructs Kermit-32 to store the data it receives in the file without checking for carriage return, line feed se- quences. The file it creates will be variable record length, with no record attributes. Each record will contain 510 bytes of data, except the last, which will contain whatever amount is left before the end of the file. This allows Kermit-32 to correctly return exactly the data it was sent when the file is returned to the original system. Note that because of the need to use a different file type for binary files, it is not possible to use a "wildcard send" command to send a mixture of text and binary files to a VAX system unless the text files are not intended for use on the VAX; rather, you must send all text files with Kermit-32's file type set to text, and all binary files with the file type set to binary. Once you get the foreign file into the VAX system, stored with the correct file type, you need take no special measures to send it back to its system of origin. This is because Kermit-32 honors the record type and attributes of the file as it is stored on the VAX. In fact, SET FILE TYPE BINARY or TEXT only affects how Kermit-32 receives files - it does not affect how Kermit-32 trans- mits files. VAX/VMS KERMIT Page 87 FILES KERMIT-32 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 a VAX/VMS system are not sequential, and cannot be successfully sent or received by Kermit-32. These are mainly indexed data files, but can also include other files which require more than just the data in the file to be completely reconstructed. External control information and file attributes are not transmitted. 7.2. Program Operation Kermit-32's prompt is normally "Kermit-32>". If a foriegn command is defined to run Kermit-32 (eg. KERMIT := $KERMIT), Kermit-32 will accept a single com- mand on the command line, like this: $ $ Kermit send foo.bar the file is sent $ $ MCR Kermit send foo.bar the file is sent $ You can run the program interactively to issue several commands, like this: $ $ Run SYS$SYSTEM:Kermit VMS Kermit-32 version 3.2 Default terminal for transfers is: _TTA1: Kermit-32>send foo.* files are sent Kermit-32>statistics performance statistics are printed Kermit-32>receive files are received Kermit-32>exit $ Command keywords may be abbreviated to their shortest prefix that sets them apart from any other keyword valid in that field. Kermit-32 provides most of the commands possible for an "ideal" Kermit program, VAX/VMS KERMIT Page 88 as described in the main part of the Kermit User Guide. The following sections will concentrate on system-dependent aspects of Kermit-32. 7.3. Conditioning Your Job for Kermit Kermit-32 does as much as it can to condition your line for file transfer. It saves all your terminal settings, and restores them after use. However, there are some sources of interference over which Kermit-32 has no control. In par- ticular, messages issued by other processes in your job could become mingled with Kermit packets and slow things down or stop them entirely. This is a fairly rare occurance and can be easily avoided by not running any other process which wishes to perform I/O to your terminal while you are running Kermit-32. Normally, when Kermit-32 is run, it assumes you wish to use it in remote mode and perform file transfers over the terminal line which controls your job. This can be overridden, however, by defining a logical name which equates to some other terminal line in the system. The default terminal line to be used for file transfers is determined by the first of the following logical names which translates to a terminal line which is available for use by your process: KER$COMM, SYS$INPUT, SYS$OUTPUT, and SYS$COMMAND. If none of these logical names translate to an available terminal line, there is no default terminal line and a SET LINE command must be used before any transfer command is per- formed. Note that this is the typical case in a batch job. Kermit-32 will also default the type of parity to be used on the communication line to that which is set on its default terminal line when it is started. This means that if all communication at a site is normally done using even parity (for example), Kermit-32 will also use even parity. There are two things to keep in mind when using Kermit-32 in local mode (where the file transfers are done over a different terminal line from where commands are typed): - Under VAX/VMS, every terminal line has an owner UIC and protection code associated with it. This UIC and protection is used to deter- mine who can allocate (and therefore use) the terminal line when they are not logged in on that line. Therefore, in order for Kermit-32 to be able to perform file transfers over a terminal line other than the one on which you are logged in, the field of the protection code for the terminal which applies to your job (based on your UIC and the owner UIC of the terminal) must allow your job access to the ter- minal. You may need to request your system manager to change the protection for a terminal line to allow you to use it with Kermit-32 in local mode. - Terminal lines which have been declared as modem control lines will have the phone "hung up" whenever the terminal line becomes free (deallocated). This means that if you do not use the DCL ALLOCATE command to allocate the terminal line to your job before entering Kermit-32, exiting Kermit-32 will cause the terminal line to "hang up" the modem. If you do wish to get to DCL after having used Kermit-32 to connect a modem control line which you do not have al- located, you can use the PUSH command to spawn a subprocess running DCL. VAX/VMS KERMIT Page 89 7.4. Kermit-32 Commands This section describes the Kermit-32 commands -- in detail where they differ from the "ideal" Kermit, briefly where they coincide. Kermit-32 has the fol- lowing commands: @ synonym for "take". BYE to remote server. CONNECT as terminal to remote system. EXIT from Kermit-32. FINISH Shut down remote server. GET remote files from server. HELP with Kermit-32. LOCAL prefix for local file management commands. LOG remote terminal session. LOGOUT remote server. PUSH to DCL command level. QUIT from Kermit-32. RECEIVE files from remote Kermit. REMOTE prefix for remote file management commands. SEND files to remote Kermit. SERVER mode of remote operation. SET various parameters. SHOW various parameters. STATISTICS about most recent file transfer. TAKE Kermit-32 commands from a file. 7.4.1. Commands for File Transfer Kermit-32 provides the standard SEND, RECEIVE, and GET commands for transfer- ring files using the Kermit protocol. THE SEND COMMAND Syntax: Sending a file or files: SEND filespec The SEND command causes a file or file group to be sent from the VAX to the other system. If filespec contains wildcard characters then all matching files will be sent, in alphabetical order (according to the ASCII collating sequence) by name. If filespec does not contain any wildcard characters, then the single file specified by filespec will be sent. SEND Command General Operation: Files will be sent with at least their VAX/VMS file name and type (for instance FOO.BAR). If a SET FILE NAMING FULL command has been given, Kermit-32 will also send the device name, directory name and version number (for instance USER$DISK:[JOE]FOO.BAR;25). If a SET FILE NAMING UNTRANSLATED command has been given, Kermit-32 will send the file name, type and version number (for instance VAX/VMS KERMIT Page 90 FOO.BAR;25). If a SET FILE NAMING NORMAL_FORM command has been given (this is the initial default), Kermit-32 will only send the file name and type. Each file will be sent according to the record type and attributes recorded in its file descriptor. Kermit-32 attempts to translate all formats of text file (including those with FORTRAN or print carriage control) to a format usuable on any system. Note that there is no need to set the FILE TYPE parameter for sending files, since Kermit-32 always uses the information from the file descriptor to determine how to send the file. If communication line parity is being used (see SET PARITY), Kermit-32 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 .EXE files, CP/M .COM files), relocatable object modules (.OBJ files), as well as any text file containing characters with the eighth bit on. Kermit-32 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-32 locally, for instance dialing out from a VAX 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-32 the SEND command, the name of each file will be displayed on your screen as the transfer begins. If the file is successfully transferred, you will see "[OK]", otherwise there will be an error message. 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 Syntax: RECEIVE [filespec] The RECEIVE command tells Kermit-32 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. If the name in the header is not a legal VAX/VMS file name, Kermit-32 will normally replace the illegal characters with "X" (see SET FILE NAMING NORMAL_FORM). If an incoming file has the same name as an existing file, Kermit-32 just creates a new version of the same name and type, for instance FOO.BAR;3, FOO.BAR;4. Incoming files will all be stored with the prevailing file type, ASCII by default, which is appropriate for text files. If you are asking Kermit-32 to receive binary files from a microcomputer or other 8-bit system, you must first type SET FILE TYPE BINARY. Otherwise, an error may occur when receiving the file, or a carriage return, line feed will be added to the end of the file and VAX/VMS KERMIT Page 91 the file will be useless when sent back to the system of origin. If parity is being used on the communications line, then 8th-bit prefixing will be requested. If the other side cannot do this, binary files cannot be trans- ferred correctly. If an incoming file does not arrive in its entirety, Kermit-32 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 you are running Kermit-32 locally, you should already have issued a SEND 9 command to the remote Kermit, and then escaped back to Kermit-32. As files arrive, their names will be displayed on your screen. 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 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-32 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 VAX. The remote filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. Any leading spaces before the remote filespec are stripped, and lower case characters are raised to upper case. As files arrive, their names will be displayed on your screen. As in the RECEIVE command, you may type Control-A to get a brief status report, ^X to re- quest that the current incoming file be cancelled, ^Z to request that the en- tire 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. _______________ 9 not SERVER -- use the GET command to receive files from a Kermit server. VAX/VMS KERMIT Page 92 THE STATISTICS COMMAND Give statistics about the most recent file transfer. THE TAKE COMMAND Syntax: TAKE filespec The TAKE command tells Kermit-32 to execute commands from the specified file. You may also use the VMS notation "@" to specify a command file. 7.4.2. Server Operation THE SERVER COMMAND The SERVER command puts a remote Kermit-32 in "server mode", so that it receives all further commands in packets from the local Kermit. The Kermit-32 server is capable (as of this writing) of executing the following remote server commands: SEND, GET, FINISH, BYE, REMOTE DIRECTORY, REMOTE CWD, REMOTE SPACE, REMOTE DELETE, REMOTE TYPE, REMOTE HELP, REMOTE COPY, REMOTE RENAME, REMOTE SEND_MESSAGE, REMOTE WHO, and REMOTE HOST. Any nonstandard parameters should be selected with SET commands before putting Kermit-32 into server mode, in particular the file type. The Kermit-32 server can send all files in the correct manner automatically. However, if you need to ask Kermit-32 to receive binary files you must issue the SET FILE TYPE BI- NARY command before putting it into server mode, and then you must only send binary files. You cannot send a mixture of text files and 8-bit binary files to a Kermit-32 server unless the files are not for use on the VAX. COMMANDS FOR SERVERS When running in local mode, Kermit-32 allows you to give a wide 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, LOGOUT and FINISH com- mands, as well as the REMOTE command. 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: COPY filespec Copy file. The server is asked to make a copy of the specified file. Kermit-32 will prompt for the new file name on a separate line. Both filespecs must be in the correct format for the remote system. Kermit-32 does not parse or validate the file specifications. Any leading spaces will be stripped and lower case characters converted to upper case. Note that VAX/VMS KERMIT Page 93 this command simply provides for copying a file within the server's system - it does not cause a file to be transferred. 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. Note that while not all server Ker- mits require (or accept) a password to change the working directory, Kermit-32 will always ask for one when a directory name is provided. 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, perhaps along with size and date information for each file. If no file specification is given, all files from the current directory will be listed. DISK_USAGE [directory] Display information about disk usage in the given directory (or by the given user). If no directory is provided, disk usage information is provided for the current working directory (or user). This is the same as the REMOTE SPACE command. EXIT Requests the server to leave Kermit, allowing the terminal to be used for normal commands. FINISH Requests the server to return to the Kermit prompt, allowing statistics to be obtained about the transfers. HELP [topic] Provide information about the given topic. If no topic is given, provide a list of the functions that are available from the server. Some servers may ignore the topic and always dis- play the same information. HOST [command] Pass the given command to the server's host command processor, and display the resulting output on your screen. LOGIN user-id Supply information to the server Kermit to indicate what user-id, account and password are to be used. The server Ker- mit may use this to validate the user's access to the system as well as for billing purposes. It may also use this information to provide the user with access to files on its system. LOGOUT Request the server to exit Kermit and logout its job (or process). This command is identical to the LOGOUT command. RENAME filespec Change the name on the specified file (or files). Kermit-32 will prompt for the new file specification on the next line. Both file specifications must be valid for the server's system. VAX/VMS KERMIT Page 94 SEND_MESSAGE destination-address Request the server to send a single line message to the specified destination address (which might be a user-id, ter- minal designator, or some other item, depending upon the server Kermit). Kermit-32 will prompt for the single line message on the next line. SPACE [directory] Display information about disk usage in the given directory (or by the given user). If no directory is provided, disk usage information is provided for the current working directory (or user). This is the same as the REMOTE DISK_USAGE command. STATUS Display information about the status of the server. TYPE filespec Display the contents of the specified file on your screen. WHO [user-id] Display information about the given user. If no user-id is given, display information about the currently active users. Kermit-32 will prompt for options for selecting what infor- mation to display and/or formatting parameters. The format of both the user-id and the options are dependent upon the server Kermit. 7.4.3. Commands for Local File Management Syntax: LOCAL [command] Execute the specified command on the local system -- on the VAX/VMS system where Kermit-32 is running. These commands provide some local file management capability without having to leave the Kermit-32 program. These commands are very similar to the REMOTE commands in function and syntax. They are all ex- ecuted locally, and are available when Kermit-32 is either local or remote. The arguments to these commands are the same as the arguments expected from the user Kermit when Kermit-32 is processing a command in server mode. COPY filespec Make a copy of the given file (or files). Kermit-32 will prompt for the new file specification. The command is actually performed by using the DCL COPY command (COPY/LOG old-file new-file), and any options which are valid on the DCL COPY com- mand may be included. CWD [directory] Change working directory, or, in VAX/VMS terminology, change the default device/directory. This command takes the same ar- guments as the DCL SET DEFAULT command (i.e., a device and directory, only a directory, or only a device). If no argument is given, the default device and directory are reset to that in effect when Kermit-32 was run. The new default device and directory will be typed out. DELETE filespec Delete the specified file or files. This command is performed by using the DCL DELETE command (DELETE/LOG filespec). There- fore, any options which are valid on the DCL DELETE command may be included. VAX/VMS KERMIT Page 95 DIRECTORY [filespec] Provide a directory listing of the specified files. This com- mand is performed by using the DCL DIRECTORY command (DIRECTORY filespec), so any options valid for the DCL DIRECTORY command may be included. DISK_USAGE [uic] Display disk usage information for the given UIC. If no UIC is given, display disk usage information for the process UIC. This command is performed by using the DCL SHOW QUOTA command (SHOW QUOTA or SHOW QUOTA/USER=uic). HELP Display the help message describing the server commands which are available. HOST DCL command Perform the given DCL command. The command should not perform any action which will require more input. Any output resulting from the command will be typed on the terminal. RENAME filespec Change the name of the specified file. Kermit-32 will prompt for the new name on the next line. This command is performed by using the DCL RENAME command (RENAME/LOG old-file new-file), so any options which are valid on the DCL RENAME command may be included. SEND_MESSAGE terminal-name Send a single line message to the given terminal. Kermit-32 will prompt for the message on the next line. Since this com- mand is performed using the DCL REPLY command REPLY/TERMINAL=terminal-name "message" OPER priveleges are needed to perform it. TYPE filespec Display the contents of the specified file or files at your terminal. Each file will be preceded by its name in angle brackets. 7.4.4. The CONNECT Command Syntax: CONNECT [terminal-name] Establish a terminal connection to the system connected to the terminal line 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-32 by typing the escape character followed by the letter C. The escape character is Control-Close-Square-Bracket (^]) by default. When you type the escape character, several single-character commands are possible: C Close the connection and return to Kermit-32. Q If a session log is active, temporarily Quit logging. R Resume logging to the session log. S Show status of the connection. 0 Send a null character. VAX/VMS KERMIT Page 96 ? 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, and SET LOCAL_ECHO to change those communication-line-oriented parameters. Type the SHOW LINE command for information about your current com- munication settings. Kermit-32 does not have any special autodialer interface. It assumes that the connection has already been made and the line assigned. 7.4.5. The SET and SHOW Commands 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 Record or display state transitions or packets DELAY How long to wait before starting to send ESCAPE Character for terminal connection FILE For setting file parameters like file type HANDSHAKE For establishing half duplex line turnaround handshake IBM_MODE For communicating with an IBM mainframe INCOMPLETE_FILE What to do with an incomplete file LINE Terminal line to use for file transfer or CONNECT LOCAL_ECHO For terminal connection, ON or OFF MESSAGE The type of typeout to be done during transfers PARITY Character parity to use PROMPT Change the program's command prompt RECEIVE Various parameters for receiving files REPEAT_QUOTE Character to use for repeat compression RETRY How many times to retry a packet before giving up SEND Various parameters for sending files Those SET commands which differ from the "ideal" Kermit are now described in detail. SET DEBUGGING Syntax: SET DEBUGGING 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-32 in local mode. Options are: VAX/VMS KERMIT Page 97 ON Display each incoming and outgoing packet (lengthy). OFF Don't display or record debugging information (this is the nor- mal mode). If debugging was in effect, turn it off. The debugging information is recorded in the file specified by the most recent LOG DEBUGGING command. SET ESCAPE SET ESCAPE octal-number Specify the control character you want to use to "escape" from remote connec- tions back to Kermit-32. The default is 35 (Control-]). The number is the oc- tal value of the ASCII control character, 1 to 37 (or 177), 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 parameter keyword Establish file-related parameters: TYPE keyword Type of file for VAX/VMS file output. The choices are ASCII, BINARY, or FIXED. ASCII Store the file as a standard VAX/VMS text file. Any file received is stored as variable length records with carriage return, line feed sequences implied between records. This is the format preferred by most utility programs under VAX/VMS. An error will occur if any line is more than 4096 characters long. Note that lines are only terminated by carriage return, line feed sequences. A carriage return that is not followed by a line feed or a line feed that is not preceded by a carriage return is not considered the end of a line, and is included within the body of a record. BINARY Store the file as a binary file. Any file received is stored as variable length records with no record attributes. Kermit-32 actually will write 510 bytes in each record except the last. This makes each record take up one disk block (510 data bytes plus two bytes of record length). The last record is written containing only as much data is left to the end of the file. Any file which is just a stream of bytes can be stored as a BINARY file, and recovered intact later. This is the preferred file type for use in archiving files. FIXED Store the file as a fixed length binary fle. Any file received is stored as fixed length 512 byte records with no record at- tributes. This is the format used for binary files such as VAX/VMS "EXE" files and RSX-11M/M+ "TSK" files. Since even the last record of the file is written with 512 bytes (even if it VAX/VMS KERMIT Page 98 is not filled), this format does not necessarily maintain the correct length of a file. It should normally only be used for files which are coming from a VAX/VMS system which are cur- rently stored in fixed 512 byte records. NAMING keyword Determine the form of names to be sent with outgoing files and deter- mine the translation performed on incoming file names. The choices are FULL, NORMAL_FORM and UNTRANSLATED. FULL Kermit-32 will send full file names (including device, direc- tory, file name, file type and version number). When receiving a file, Kermit-32 will perform no translation of the file name (which must therefore be a legal VAX/VMS file specification). NORMAL_FORM Kermit-32 will send only the file name and file type. When receiving a file, Kermit-32 will convert the file specification received to contain only uppercase letters, digits, and at most one period. Any other characters will be translated to "X". There will be at most 9 characters before the period (if any), and at most 3 characters afterwards. This forces the file name to be a valid VAX/VMS file specification. Note that standard VAX/VMS file names and types are already normal form, and therefore do not need translation. This is the default. UNTRANSLATED Kermit-32 will send only the file name and file type. When receiving a file, Kermit-32 will not perform any conversions on the file specification, which therefore must be a legal VAX/VMS file specification. SET HANDSHAKE Syntax: SET HANDSHAKE o Sets the half duplex line turnaround handshake character to the ASCII character whose octal value is o. Normally required for communication with half duplex systems like IBM mainframes. SET IBM_MODE Syntax: SET IBM_MODE ON or OFF When IBM_MODE is set to ON, Kermit-32 will override the parity and local echo settings and use odd parity, local echo on, and also enable a handshake charac- ter of XON (control-Q, ASCII 021 octal). This feature allows Kermit-32 to talk with certain systems (notably some IBM mainframes), which require waiting for a XON before sending data. The various features selected by this command can be overriden subsequently by SET PARITY, SET LOCAL_ECHO, and SET HANDSHAKE commands. VAX/VMS KERMIT Page 99 SET LINE Syntax: SET LINE [terminal-name] Specify the terminal name to use for file transfer or CONNECT; the terminal-name can be up to 16 characters long. If you issue this command using other than your job's controlling terminal, you will be running Kermit-32 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-32 deter- mines whether it is to run locally or remotely based on the default terminal line found when Kermit-32 is started. Kermit-32 uses a list of logical names to determine which terminal should be the default terminal line. The first of these names which translates to a terminal which is available (i.e., not al- located by some other process) is used. The logical names Kermit-32 tries are KER$COMM, SYS$INPUT, SYS$$OUTPUT, and SYS$COMMAND. If none of these translate to an available terminal, Kermit-32 is running detached, and a terminal must be specified by the SET LINE command before any actions can be performed. If a terminal is found, Kermit-32 is running locally if this is a terminal other than the one controlling the job (i.e., different from SYS$COMMAND), otherwise Kermit-32 is running remotely. You can also select the line directly in the CONNECT command; the command CONNECT TTA0 is equivalent to SET LINE TTA0 CONNECT If you type SET LINE with no argument, you will deassign any previous assigned line and revert to remote mode. SET SERVER_TIMOUT Syntax: SET SERVER_TIMEOUT number This specifies the number of seconds between timeouts during server command wait, 0 specifies that no timeouts should occur during server command wait. When a Kermit server times out, it sends a NAK packet. Some systems cannot clear piled-up NAKs from their input buffers; if you're using such a system to communicate with a Kermit-32 server, and you expect to be leaving the server idle for long periods of time, you should use this command to turn off server command-wait timeouts. THE SHOW COMMAND Syntax: SHOW [option] The SHOW command displays various information: ALL All parameters. BLOCK_CHECK_TYPE The block check type being requested. VAX/VMS KERMIT Page 100 COMMUNICATIONS Parameters affecting the terminal line being used for com- munication. DEBUGGING Debugging mode in effect, if any. DELAY The number of seconds Kermit-32 will delay before starting a SEND or RECEIVE command when in remote mode. ESCAPE The current escape character for the CONNECT processing. FILE_PARAMETERS File type, file naming, and incomplete file disposition. INCOMPLETE_FILE_DISPOSITION The action to take when a transfer is aborted. LINE Terminal line in use. LOCAL_ECHO Whether characters should be echoed locally when CONNECTed. PACKET For incoming and outbound packets. PARITY The parity type in use. RECEIVE For inbound packets. RETRY The number of retries to be done on bad packets. SEND For outbound packets. 7.4.6. Program Management Commands 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. THE EXIT AND QUIT COMMANDS Syntax: EXIT Exit from Kermit-32. You can also exit from the Kermit-32 when it is waiting for a command by typing a control-Z. When Kermit-32 is running remotely, two control-Y's will abort the transfer, bringing Kermit-32 back to command mode. The two control-Y's must be typed together, as if a timeout occurs between them the first is ignored. When Kermit-32 is running locally, two control-Y's will stop Kermit-32 and return you to DCL. You will be able to CONTINUE if you do VAX/VMS KERMIT Page 101 not perform any command which runs a program. However, after continuing, control-A, control-X and control-Z will no longer be accepted as commands. QUIT is a synonym for EXIT. 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. During CONNECT, 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 Re- sume logging). TRANSACTIONS During file transfer, log the progress of each file. Trans- action logging is recommended for long or unattended file transfers, so that you don't have to watch the screen. The log may be inspected after the transfer is complete to see what files were transferred and what errors may have occurred. DEBUGGING Log debugging info to the specified file. If no SET DEBUGGING command was previously issued, the file will be opened and no information written. If DEBUGGING is turned on (either via the SET DEBUGGING command or by typed control-D during a local transfer), the packet debugging information will be written to the file. Packet format is described in the Kermit Protocol Manual. Any log files are closed when you EXIT or QUIT from Kermit. You may explicitly close a log file and terminate logging by using the LOG command without a file specification. 7.5. Raw Download "Raw Download" is the term commonly used to describe the capture of a remote file on the local system, without any kind of error detection or correction. This allows you to obtain files from remote systems that do not have Kermit, but with the risk of loss or corruption of data. Kermit-32 provides raw downloading via the LOG SESSION command during CONNECT to a remote system. The session log is described above. To use session log- ging to capture a file: 1. Run Kermit on the VAX/VMS system. 2. SET LINE to the terminal line through which you will be connected to the remote system. 3. Perform any required SET commands to condition Kermit for communica- tion with the remote system. VAX/VMS KERMIT Page 102 4. CONNECT to the remote system and log in. 5. Condition your job on the remote system not to pause at the end of a screenful of text, and give whatever commands may be necessary to achieve a "clean" terminal listing -- for instance, disable messages from the system or other users. 6. Type the appropriate command to have the desired file displayed at the terminal, but do not type the terminating carriage return. On most systems, the command would be "type", on Unix it's "cat". 7. Escape back to Kermit-32 and give the LOG SESSION command with the file specification where you wish to store the data. 8. CONNECT back to the remote system and type a carriage return. The file will be displayed on your screen and recorded in the session log file. 9. Escape back to Kermit-32 and give the LOG SESSION command without a file specification. The file you specified will contain everything that was typed on your screen. You will probably find that some editing necessary to remove extraneous prompts, messages, padding characters, or terminal escape sequences, or to fill in lost or garbled characters. 7.6. Installation of Kermit-32 Kermit-32 may be installed either by rebuilding the entire program from the sources, or by making use of the distributed copy of the program. When being built from sources, it may be built using either a BLISS-32 compiler or just the MACRO-32 assembler. FILES Kermit-32 is built from a number of BLISS-32 sources and one MACRO-32 source. In order to make it possible for sites without BLISS-32 to build, MACRO-32 sources generated by BLISS-32 are also included for all of the BLISS modules. In the normal distribution of Kermit-32, all of the files start with the prefix "VMS". This will need to be changed to "KER" in order to build the program properly. The following files are distributed as part of Kermit-32: VMSTT.BLI Common BLISS source for the terminal text output support. VMSGLB.BLI Common BLISS source for the global storage for VMSMSG.BLI. VMSMSG.BLI Common BLISS source for the protocol handling module. VMSCOM.REQ Common BLISS require file which defines various common parameters. This is required by VMSMSG.BLI. This file must be renamed to KERCOM.REQ. VMSMIT.BLI BLISS-32 source for the command parser, and some basic support routines. VAX/VMS KERMIT Page 103 VMSFIL.BLI BLISS-32 source for the file I/O. VMSTRM.BLI BLISS-32 source for the terminal processing. This handles the driving of the terminal line for the transfers and the connect command processing. VMSSYS.BLI System interface routines for the Kermit generic command processing. VMSGEN.MAR Macro-32 source file that contains the REMOTE command text that is given to VMS. Sites desiring to change what DCL commands are used to process the various generic server commands can make those changes in this source. This also contains the text of the help message returned in response to the server generic help command. VMSERR.MSG MESSAGE source for error messages used by VAX/VMS Kermit. VMSERR.REQ BLISS-32 require file which defines the error codes. This is REQUIREd by the BLISS-32 sources. VMSMIT.RNH RUNOFF source for the help files for VAX/VMS Kermit. When this is run through RUNOFF with /VARIANT=SYSTEM, it produces a .HLP (VMSSYS.HLP) file suitable for inserting into the system help library (SYS$HELP:HELPLIB.HLB) to provide a KERMIT topic for the system HELP command. When run through RUNOFF without the /VARIANT=SYSTEM, it produces a .HLP file (VMSUSR.HLP) to be stored on SYS$HELP: for use by the Kermit HELP command. VMSSYS.HLP RUNOFF output file for system wide Kermit HELP. VMSUSR.HLP RUNOFF output file for Kermit's HELP command. VMSINS.COM Command file to build and install VAX/VMS Kermit. VMSMIT.EXE The executable (binary) file of VAX/VMS Kermit. Note that this is only included when it is possible. This may be either a copy of the .EXE file which was transferred to a TOPS-10 or TOPS-20 system using Kermit with Kermit-10 (or -20) using FILE BYTE-SIZE 8-BIT, or a direct copy of the .EXE file (if the file is either on a native VAX/VMS tape or is residing on a VAX/VMS system). VMSMIT.HEX A hexifed version of .EXE file for VMS Kermit. This file can be dehexified using the supplied program. In the hexified form, the file should be transferrable over any medium which handles normal text. This is the most reliable copy of the ex- ecutable version of VMS Kermit. VMSHEX.MAR Source for the hexification program. This is the program which was used to produce VMSMIT.HEX. It can also be used to produce hexified version of any (or at least almost any) Files-11 file. The dehexification program should then be able to reproduce a copy of the original file with the file parameters correctly set. Note that the format used for the hexified files is basi- cally Intel hex format. There are some additional records used VAX/VMS KERMIT Page 104 to store the record format, etc. Also, the file name as typed to the prompt from VMSHEX is stored in the hexified version of the file for use by the dehexification program. By doing this, it is possible to store more than one binary file with a single hexified file. VMSDEH.MAR Source for the dehexification program. VMSV3.MEM Documentation on the changes between versions 2.0 and 3.0 of Kermit-32, and additional installation information. As distributed, Kermit-32 should work on any VAX/VMS system (version 3.0 and later). Customization is possible with or without a BLISS-32 compiler. Default parameter values may be changed by changing the appropriate LITERALs in the BLISS-32 source for VMSMSG, or the actual values which are stored in the routine MSG_INIT in the MACRO-32 source for VMSMSG. Sites can also easily change the commands which are used for processing the generic server functions (REMOTE commands when running as a server). The text which makes up these commands is in the file VMSGEN.MAR, along with the text of the REMOTE HELP message. This allows a site to make use of local programs for performing some of the commands (perhaps using FINGER to perform the WHO com- mand, etc.). BUILDING KERMIT-32 FROM SOURCES A command file is included which will build Kermit-32 from either the BLISS-32 or MACRO-32 sources and optionally install Kermit-32 on the system. This file (VMSINS.COM) has not been extensively tested, however it should work on most systems. It is also a good example of what needs to be done to compile each file and load the entire program. It also contains the commands necessary to install a version of Kermit-32 on the system once the .EXE and .HLP files are generated. USING KERMIT-32 TO INSTALL A NEW VERSION OF ITSELF If you already have a version of Kermit-32 running on a VAX/VMS system, you can use it to transfer a new version of itself from another system. If you have no need to build Kermit-32 from sources (because you have no local modifications), you can just transfer the new VMSMIT.EXE (or VMSMIT.HEX), and the new help file VMSMIT.RNH. If you have access to a system which has a copy of VMSMIT.EXE, you can transfer it simply by setting the FILE TYPE to FIXED on the receiving Kermit. Make sure that the sending Kermit is willing to send the file as a binary file. If the sending Kermit is another copy of Kermit-32, you don't need to do anything. If the sending Kermit is Kermit-10 or Kermit-20, make sure the file will be sent as an eight-bit binary file by using SET FILE BYTE-SIZE EIGHT. If some other Kermit is sending the file, make sure to give it whatever command is necessary to ensure that it sends eight-bit binary data from the file. Also, if the originating system is not a VAX/VMS, TOPS-10 or TOPS-20 system, make sure that the file was stored on that system correctly to start out with. Normally, the file VMSMIT.EXE will only be available from a VAX/VMS, TOPS-10 or TOPS-20 sys- tem. VAX/VMS KERMIT Page 105 If you only have access to a copy of VMSMIT.HEX, you will need to transfer that file (as a normal ASCII text file). You will also need a copy of VMSDEH.MAR. After you have obtained both files, you can produce a copy of the .EXE file as follows. First compile VMSDEH by using the command MACRO VMSDEH. Then load it by LINK VMSDEH. Now run VMSDEH and when it asks for a file name, type VMSMIT.HEX. The program will run for a short time and produce the .EXE file. The system wide and user help files are produced from VMSMIT.RNH by RUNOFF. To produce the user help file (the one used by Kermit-32's HELP command), type: $ RUNOFF VMSMIT.RNH/OUTPUT=KERUSR.HLP $ LIBARARY/CREATE/HELP SYS$HELP:KERMIT.HLB KERUSR.HLP To produce the system wide help file and install it in the system help library type: $ RUNOFF VMSMIT.RNH/OUTPUT=KERSYS.HLP/VARIANT=SYSTEM $ LIBRARY/REPLACE/HELP SYS$HELP:HELPLIB.HLB KERSYS.HLP This allows the DCL HELP command to provide information on Kermit-32. IBM VM/CMS KERMIT Page 106 8. IBM VM/CMS KERMIT Program: Daphne Tzoar, Columbia University; contributions from Bob Shields (U. of Maryland), Victor Lee (Queens U.), Gary Bjerke (U. of Texas at Austin), Greg Small (UC Berkeley) Language: CMS Assembler Documentation: Daphne Tzoar, Columbia University Version: 2.01 Date: May 1985 CMS Kermit Capabilities At A Glance: Local operation: No Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes (fixed format) Wildcard send: Yes ^X/^Y interruption: Yes Filename collision avoidance: Yes Can time out: No 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Terminal emulation: No Communication settings: No Transmit BREAK: No Transaction logging: Yes Session logging: No Raw transmit: No Act as server: Yes Talk to server: No Advanced server functions: No Advanced commands for servers: No Local file management: Yes Handle Attribute Packets: No Command/init files: Yes Command macros: No Kermit-CMS is a program that implements the KERMIT file transfer protocol for IBM 370-series mainframes (System/370, 303x, 43xx, 308x, etc.) under the VM/CMS operating system. It is written in IBM 370 assembly language. This program runs only over ASCII (asynchronous) lines attached to a 3705-style front end or a Series/1 running the Yale ASCII Terminal Communication System. The program should also work on the IBM 7171 ASCII Device Control Unit and the 4994, al- though this has not been verified as of this writing. For more details on this, see the section SET SERIES1. These systems have several peculiarities that users should be aware of. 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 trans- mitting the next character. It is up to the user to tell the other Kermit that it is talking to an IBM mainframe. IBM VM/CMS KERMIT Page 107 Also, a program running under VM/CMS is unable to interrupt a read on its "console". This means that the CMS version of Kermit cannot timeout. The only way to "timeout" CMS Kermit is from the other side: typing a carriage return to the local Kermit causing it to retransmit its last packet, or an automatic timeout as provided by most other Kermits. 8.1. The VM/CMS File System The features of the CMS file system of greatest interest to Kermit users are the format of file specifications and the concept of records. 8.1.1. File Specifications The VM/CMS file specification is in the form FILENAME FILETYPE FILEMODE (often abbreviated FN FT FM). FILENAME and FILETYPE are at most 8 characters in length each. The name field is the primary identifier for the file. The type is an indicator which, by convention, tells what kind of file we have. For instance TEST FORTRAN is the source of a FORTRAN program named TEST. MODULE is the normal suffix for executable programs. Although some operating systems consider the FILETYPE optional, VM/CMS requires a valid type. There- fore, Kermit-CMS supplies a default type of "X" if one is not provided by the remote system. The FILEMODE, which consists of a letter and a number, is similar to a device specification on microcomputer systems: FN FT FM would translate to FM:FN.FT in CP/M or MS-DOS. If FILEMODE is omitted from a file specification when sending, a FM of "*" is used. In this case, the users disks are scanned according to the search order and the first occurrence of the file is the one that is sent. If FILEMODE is omitted from a file spec when receiving, a default of "A1" is used. To provide compatibility with most other operating systems, Kermit-CMS sends only the FILENAME and FILETYPE. It also converts the intervening blank to a period. The FN and FT may contain, in any order, uppercase letters, digits, and the special characters "$" (dollar sign), "#" (pound sign), "@" (at sign), "+" (plus), "-" (dash), ":" (colon), and "_" (underscore). Other characters may be not be included. If an invalid character is found in the FN or FT field, it is replaced by the letter "X". VM/CMS allows a group of files to be specified in a single file specification by including the special "wildcard" characters, "*" and "%". A "*" matches any string of characters from the current position to the end of the field, includ- ing no characters at all; a "%" matches any single character. Here are some examples: * COBOL A All files of type COBOL (all COBOL source files) on the A disk. F* * All files whose names start with F. IBM VM/CMS KERMIT Page 108 % * B All files on the B disk whose FN is exactly one character long. 8.1.2. File Formats Several differences exist between VM/CMS files and those of most other operat- ing systems. One distinction is that CMS encodes its data using the EBCDIC character set. The operating system, VM, translates all incoming characters from ASCII to EBCDIC. Kermit-CMS then translates the data it reads back to AS- CII (characters not representable in ASCII are replaced by a null). This is done in order to correctly calculate the checksum, the method used to guarantee error-free transfer. When Kermit-CMS sends packets, it converts all data back to EBCDIC. Note that the translate tables used by Kermit must correspond to the ones used by the system (VM). The ASCII to EBCDIC translations can be found in the Appendix. Another difference is that VM/CMS stores files as records rather than byte streams. VM/CMS Kermit has to worry about assembling incoming data packets into records and appending carriage return-linefeed to outgoing records. 8.2. Program Operation Kermit-CMS can be invoked at the command line or from an exec. Commands con- sist of one or more fields, separated by spaces. Each field must be eight characters or less. Fields longer than the maximum length are truncated. Upon initial startup, the program looks for two special initialization files, SYSTEM KERMINI and (USERID) KERMINI (that is, the userid of the person running CMS-Kermit.) These files can be placed on any disk. The purpose of these files is to allow Kermit to be customized for a particular system and for a user's specific settings without changing the source code. The file SYSTEM KERMINI should be placed on a publicly accessible disk by a systems programmer. The file would contain commands that all users would need to issue in order for Kermit to run on the system, such as commands to modify the ASCII-to-EBCDIC and EBCDIC-to-ASCII tables used by Kermit-CMS. The file (USERID) KERMINI would contain commands that the user generally issues every time Kermit is run. Kermit-CMS executes any commands found in these files as though they were typed at the terminal. Here is a sample init file: * Asterisk in column one is a comment. set debug on set warning on set block 3 Three CP SET parameters MSG, IMSG and WNG are always set OFF during the actual file transfer (and restored afterwards) to prevent CP from interrupting any I/O in progress. IBM VM/CMS KERMIT Page 109 Interactive Operation: To run Kermit-CMS interactively, invoke the program from CMS by typing "KERMIT". When you see the command's prompt, KERMIT-CMS>. you may type Kermit commands repeatedly until you are ready to exit the program, for example: .KERMIT Kermit CMS Version 2.01 Enter ? for a list of valid commands KERMIT-CMS>.send foo * Files with fn FOO are sent KERMIT-CMS>.receive test spss File is received and called TEST SPSS A1 KERMIT-CMS>.exit During interactive mode, you may use the help ("?") feature while typing Kermit-CMS commands. A question mark typed at almost any point in a command, followed by a carriage return, produces a brief description of what is expected or possible at that point. Command Line Invocation: Kermit-CMS may also be invoked with command line arguments from CMS. For in- stance: .KERMIT send test fortran or .KERMIT set debug on # set file binary # server Kermit will exit and return to CMS after completing the specified command or commands. Note that several commands may be given on the command line as long as they are separated by the linend character, which is pound sign in this case. The command line may contain up to 130 characters. Exec Operation: Like other CMS programs, Kermit-CMS may be invoked from a CMS EXEC. Kermit will not run under CMSBATCH or disconnected since the user does not actually have a console. Commands can be passed using TAKE files and/or command line arguments. For example, to start up Kermit-CMS and have it act as a server, include the line: IBM VM/CMS KERMIT Page 110 KERMIT server To pass more than one command, they must be stacked in the order in which they are to be executed. To start up a Kermit-CMS server with a three character CRC, include: &STACK set block 3 &STACK server KERMIT Prompts and messages will still be displayed on the screen. 8.3. Kermit-CMS Commands Here's a brief summary of CMS Kermit commands: CMS executes a CMS command. CP executes a CP command. EXIT from Kermit-CMS. HELP about Kermit-CMS. QUIT from Kermit-CMS RECEIVE files from other Kermit. SEND files to other Kermit. SERVER mode of remote operation. SET various parameters. SHOW various parameters. STATUS inquiry. TAKE commands from file. TDUMP dumps the contents of a particular table. The remainder of this section concentrates on the commands that have special form or meaning for CMS Kermit. THE SEND COMMAND Syntax: SEND filespec The SEND command causes a file or file group to be sent from the CMS system to the Kermit on the remote system. filespec takes the form: filename filetype [filemode] filespec may contain the wildcard characters "*" or "%". If filespec contains wildcard characters then all matching files will be sent. If, however, a file exists by the same name on more than one disk, only the first one CMS Kermit encounters, according to the disk search order, is sent. Although the file transfer cannot be cancelled from the CMS side, Kermit-CMS is capable of responding to "cancel file" or "cancel batch" signals from the local Kermit; these are typically entered by typing Control-X and Control-Z respec- tively. IBM VM/CMS KERMIT Page 111 THE RECEIVE COMMAND Syntax: RECEIVE [filespec] The RECEIVE command tells Kermit-CMS to receive a file or file group from the other system. You should then issue a SEND command to the remote Kermit. The format of the filespec is: filename filetype [filemode] If the optional filespec is not included, Kermit-CMS will use the name(s) provided by the other Kermit. If that name is not a legal CMS file name, Kermit-CMS will delete excessive characters from it, and will change illegal characters to the letter X. Use the file specification to indicate that the incoming file should be stored under a different name. The filespec may include a filemode to designate the destination disk. If none is provided, the file will be saved with fm A1. If you want to use the same name but a different filemode, specify = = FM. Wildcards may not be used in any field. If the optional filespec is 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 on the A disk. If, however, = = FM is used, all files will be placed onto the specified disk. When receiving files, if the record format is fixed, any record longer than the logical record length will be split up to as many records as necessary. If the record format is variable, the record length can be as high as 64K. For send- ing files, the maximum record length is 64K. See the SET LRECL and SET RECFM commands. If an error occurs during the file transfer, as much of the file as was received is saved on disk. If the sending of a file is cancelled by the user of the remote system, Kermit-CMS will discard whatever had arrived. If the incoming file has the same name as a file that already exists, and WARN- ING is OFF, the original file will be overwritten. If WARNING is set ON, Kermit-CMS will change the incoming name so as not to obliterate the pre-exist- ing file. It attempts to rename the file by replacing the first character with a dollar sign ($). If a file by that name exists, it also replaces the second character with a dollar sign. It continues in this manner for all characters of the filename and filetype. If the file cannot be renamed, the transfer fails. THE TAKE COMMAND Syntax: TAKE filespec Execute Kermit commands from the specified file, where filespec has the format fn ft [fm]. The command file may include TAKE commands. IBM VM/CMS KERMIT Page 112 THE SERVER COMMAND Kermit-CMS is capable of acting as a server. The user connects to the CMS sys- tem once to set various options and to start the server. From then on, he need not connect to the CMS system again. The current version of Kermit-CMS can send files (the user on the other end types the GET command, using either a space or a period as the delimiter between filename, filetype, and filemode), receive files (the user types SEND), and terminate by either returning to CMS (user types FINISH) or logging the user out (user types BYE). To put Kermit-CMS into server mode, first issue any desired SET commands to select various options and then type the SERVER command. Kermit-CMS will await all further instructions from the user Kermit on the other end of the connec- tion. For example: KERMIT-CMS>.set warning on KERMIT-CMS>.set debug on KERMIT-CMS>.set block 3 KERMIT-CMS>.server THE SET COMMAND Syntax: SET parameter [value] Establish or modify various parameters for file transfer. You can examine their values with the SHOW command. The following SET commands are available in Kermit-CMS: ATOE Modify ASCII-to-EBCDIC table used by Kermit-CMS BLOCK Level of error checking for file transfer DEBUG Log packets sent and received during file transfer END-OF-LINE Packet terminator ETOA Modify EBCDIC-to-ASCII table used by Kermit-CMS FILE Type of incoming or outgoing file LRECL Logical Record length for incoming file PACKET-SIZE Maximum receive packet size QUOTE Use to quote outgoing control characters RECFM Record format for incoming files SERIES1 Indicate if coming in via a Series/1 WARNING Specify how to handle filename collisions SET ATOE Syntax: SET ATOE num1 num2 This command allows you to modify the ASCII-to-EBCDIC translate table used by Kermit-CMS to conform to your system. Specify the offset of the ASCII value within the table and the new value for that location. Both num1 and num2 should be between 0 and 255 (decimal). Note that the table is twice as long as necessary because the translate instruction expects a table that contains 256 characters. IBM VM/CMS KERMIT Page 113 SET BLOCK SYNTAX: SET BLOCK number Determine the type of block check used during file transfer. Valid options for number are: 1 (for a one character checksum), 2 (for a two character checksum) and 3 (for a three character CRC). SET DEBUG Syntax: SET DEBUG ON or OFF ON Keep a journal of all packets sent and received in the file KER LOG A1. If the file already exists, it is overwritten. OFF Stop logging the packets. SET END-OF-LINE Syntax: SET END-OF-LINE number If the remote system needs packets to be terminated by anything other than car- riage return, specify the decimal value of the desired ASCII character. number must be between 0 and 31 (decimal). SET ETOA Syntax: SET ETOA num1 num2 This command allows you to modify the EBCDIC-to-ASCII translate table used by Kermit-CMS to conform to your system. Specify the offset of the EBCDIC value within the table and the new ASCII value for that location. Both num1 and num2 should be between 0 and 255 (decimal). SET FILE Syntax: SET FILE BINARY or TEXT BINARY Tells CMS Kermit to treat each character as a string of bits and not to perform translation on the data. Also, no carriage-return is added to the end of outgoing records. Incoming bytes are added to the end of the current record which is written out when the specified LRECL is reached. TEXT Tells CMS Kermit that the file is plain text. ASCII-to-EBCDIC and EBCDIC-to-ASCII translation is performed on the data. Carriage return-linefeed are appended to outgoing records and are used to deter- mine the end of incoming records. IBM VM/CMS KERMIT Page 114 SET LRECL Syntax: SET LRECL number Set the logical record length for incoming files to a number from 1 to 65536 (64K). This variable is used only for fixed format files. The default is 80. SET PACKET-SIZE Syntax: SET PACKET-SIZE number Use the specified number as the maximum length for incoming packets. The valid range is 26-94, where 94 is the default. SET QUOTE Syntax: SET QUOTE char Use the indicated printable character for prefixing (quoting) control charac- ters and other prefix characters. The only reason to change this would be for sending a very long file that contains very many "#" characters (the normal control prefix) as data. It must be a single character in the range: 33-62, 96, or 123-126 (decimal). SET RECFM Syntax: SET RECFM option Set the record format to use for incoming files. Valid options are "F" for fixed format or "V" for variable format. The default is variable. SET SERIES1 Syntax: SET SERIES1 ON or OFF Kermit-CMS automatically determines whether you are connected via a Series/1 emulation controller or a TTY line. This command is provided though so you can override Kermit-CMS. When you SET SERIES1 ON, Kermit disables the 3270 protocol conversion function by putting the Series/1 into "transparent mode"; this allows Kermit packets to pass through the Series/1 intact. SET WARNING Syntax: SET WARNING ON or OFF ON If an incoming file has the same name as an existing file on the specified disk, Kermit will attempt to rename the incoming file so as not to destroy (overwrite) the pre-existing one. OFF Upon a filename collision, the existing file will be replaced by the incoming file. IBM VM/CMS KERMIT Page 115 THE SHOW COMMAND Syntax: SHOW option Use to display the values of all parameters that can be changed with the SET command, except for ATOE and ETOA (see the TDUMP command). option can be a particular parameter or the keyword "ALL". THE STATUS COMMAND Syntax: STATUS Returns the status of the previous command. The response will either display the message "Kermit completed successfully", or the last error encountered. THE TDUMP COMMAND Syntax: TDUMP table-name Display the contents of table-name since it can be modified using the SET com- mand. The ATOE and ETOA tables can presently be 'dumped'. CP AND CMS COMMANDS Syntax: CP text of command CMS text of command Although Kermit-CMS does not provide explicit commands for managing local files or interacting with the operating system, it is possible to do so. You can is- sue any CP or CMS command, though each word will be truncated to eight charac- ters. You can list, type, rename or delete files, send messages and so on. At this time, though, you cannot run another program from Kermit-CMS. 8.4. Before Connecting to the Mainframe When connecting to the CMS system as a TTY device ("line at a time" mode) several flags must first be set on the micro version of Kermit. You should set the LOCAL-ECHO flag to ON (this is used to indicate half-duplex). This is the norm but not true in every case; if each character appears twice, set the LOCAL-ECHO flag OFF. HANDSHAKE should be set to XON and FLOW-CONTROL should be set to NONE. The parity should be set according to the system's specifica- tions. On some micro versions of Kermit, all of the above is done in one step using the DO IBM macro (or SET IBM ON). Set the baud rate to correspond to the line speed. When connecting to the CMS system through the Series/1 terminal emulation con- troller ("full-screen" mode), certain flags must be set on the micro version of Kermit. You should set the LOCAL-ECHO flag to OFF (this is used to indicate full-duplex). HANDSHAKE should be set to OFF and FLOW-CONTROL should be set to XON/XOFF. For most systems, the PARITY should be set to EVEN. Set the baud rate to correspond to the line speed. Immediately after issuing a SEND, RECEIVE or SERVER command to Kermit-CMS, the screen will be cleared. This is IBM VM/CMS KERMIT Page 116 to make sure the terminal is not stuck in a MORE or HOLDING state before pack- ets are sent via the full-screen I/O operation. After the file transfer is complete, and you re-connect to Kermit-CMS, you should enter the Series/1 "Master Reset" sequence (probably "CTRL-G") so that the screen is refreshed. 8.5. How to build an executable version of Kermit-CMS Kermit-CMS is composed of three assembly language source files that are as- sembled separately and then linked together. They are: KERMIT, NEXTFST, and WILD. To create a runnable version: 1. GLOBAL the necessary MACLIBs. For SP, the MACLIBs used are DMSSP, CMSLIB and TSOMAC. 2. Make sure the source files are named as listed above and are saved on disk in fixed format with a logical record length of 80. 3. Assemble the three source files. 4. Load the files into memory via: LOAD KERMIT 5. Create a runnable version called KERMIT MODULE via: GENMOD KERMIT 6. If your site's ASCII/EBCDIC translation table does not conform to the one listed in the appendix (which in turn conforms to the one given in the IBM System/370 Reference Summary), then enter the ap- propriate SET ATOE/ETOA commands in the SYSTEM KERMINI file. Note that if the ASCII/EBCDIC translation is not invertible, Kermit will not and cannot work. To run CMS Kermit, simply type "KERMIT" to the CMS system prompt. 8.6. What's New Below is a list of the more important additions in Version 2.01 of CMS Kermit: 1. Add prefixing of the "8th bit". This allows CMS Kermit to send or receive fixed format binary data, such as microcomputer binary files. 2. The maximum record length allowed has been increased to 64K for both incoming and outgoing files. 3. Repeat count prefixing has been added to speed up transmission. In addition, Kermit-CMS now packs as much data as possible into an out- going packet rather than one packet per record (it makes a big difference). 4. Support for two character checksum and three character CRC. 5. If filetype is not supplied by the remote Kermit, use a default of "X" rather than failing. Also allow the option to rename an incom- ing file upon filename collision. IBM VM/CMS KERMIT Page 117 6. Add debugging mode to log packets and to acknowledge the attention if the user types a BREAK. Add a SHOW ALL command. 7. Allow input to command parser from command line. Multiple commands should be separated by the linend character. After execution of these commands, Kermit returns control to CMS. 8. Add support for Series/1 front end. 9. Add server support. 10. Upon startup, read commands from two init files: SYSTEM KERMINI and (USERID) KERMINI (that is the userid of the person running Kermit). Lines with an asterisk as the first character are comments. Add the TAKE command. The LRECL for these files must be 130 or less. 11. Implement skip file or file group when sending or receiving (in this case, discard incoming file). 12. Allow system manager to change ASCII/EBCDIC translation tables to conform to the various specifications of different systems. Also, bypass user translate tables when sending and receiving data. 8.7. What's Missing Work on Kermit-CMS will continue. Features that need to be improved or added include: - Allow timeouts so CMS Kermit does not wait forever if a packet does not arrive in a timely fashion. - Allow any binary file to be sent and received properly, not only fixed format binary files. - Better keyword parsing, which is rather crude at this time. - Support of the more advanced server functions. - Addition of a RUN command. - 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 Page 118 9. UNIX KERMIT Program: Frank da Cruz, Bill Catchings, Jeff Damens, Columbia University; Herm Fischer, Encino CA; contributions by many others. Language: C Documentation: Frank da Cruz, Herm Fischer Version: 4C(057) Date: July 26, 1985 C-Kermit is a completely new implementation of Kermit, written modularly and transportably in C. The protocol state transition table is written in wart, a (non-proprietary) lex-like preprocessor for C. System-dependent primitive func- tions are isolated into separately compiled modules so that the program should be easily portable among Unix systems and also to non-Unix systems that have C compilers. This document applies to Unix implementations of C-Kermit, and in most ways also to the VMS implementation. Unix Kermit Capabilities At A Glance: Local operation: Yes Remote operation: Yes Login scripts: Yes Transfer text files: Yes Transfer binary files: Yes Wildcard send: Yes File transfer interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Terminal emulation: Yes Communication settings: Yes Transmit BREAK: Yes Support for dialout modems: Yes IBM mainframe communication: Yes Transaction logging: Yes Session logging: Yes Debug logging: Yes Packet logging: Yes Act as server: Yes Talk to server: Yes Advanced server functions: Yes Local file management: Yes Command/Init files: Yes UUCP and multiuser line locking: Yes File attributes packets: No Command macros: No Raw file transmit: No C-Kermit provides traditional Unix command line operation as well as inter- active command prompting and execution. The command line options provide ac- cess to a minimal subset of C-Kermit's capabilities; the interactive command set is far richer. UNIX KERMIT Page 119 On systems with dialout modems, C-Kermit can use its command file and login script facilities to replicate the file transfer functionality of UUCP among heterogeneous operating systems, including the use of scheduled (e.g. late night) unattended operation. 9.1. The Unix File System Consult your Unix manual for details about the file system under your version of Unix. For the purposes of Kermit, several things are worth briefly noting. Unix files generally have lowercase names, possibly containing one or more dots or other special characters. Unix directories are tree-structured. Directory levels are separated by slash ("/") characters. For example, /usr/foo/bar denotes the file bar in the directory /usr/foo. Wildcard or "meta" characters allow groups of files to be specified. "*" matches any string; "?" matches any single character. When C-Kermit is invoked with file arguments specified on the Unix command line, the Unix shell (Bourne Shell, C-Shell, etc) expands the meta characters itself, and in this case a wider variety is available. For example, kermit -s ~/ck[uvm]*.{upd,bwr}] is expanded by the Berkeley C-Shell into a list of all the files in the user's home directory (~/) that start with the characters "ck", followed by a single character "u", "v", or "m", followed by zero or more characters, followed by a dot, followed by one of the strings "upd" or "bwr". Internally, the C-Kermit program itself expands only the "*" and "?" meta characters. Unix files are linear streams of 8-bit bytes. Text files consist of 7-bit AS- CII characters, with the high-order bit off (0), and lines separated by the Unix newline character, which is linefeed (LF, ASCII 10). This distinguishes Unix text files from those on most other ASCII systems, in which lines are separated by a carriage-return linefeed sequence (CRLF, ASCII 13 followed by ASCII 10). Binary files are likely to contain data in the high bits of the file bytes, and have no particular line or record structure. When transferring files, C-Kermit will convert between upper and lower case filenames and between LF and CRLF line terminators automatically, unless told to do otherwise. When binary files must be transferred, the program must be instructed not to perform LF/CRLF conversion (-i on the command line or "set file type binary" interactively; see below). 9.2. File Transfer If C-Kermit is in local mode, the screen (stdout) is continously updated to show the progress of the file transer. A dot is printed for every four data packets, other packets are shown by type: I Exchange Parameter Information R Receive Initiate S Send Initiate UNIX KERMIT Page 120 F File Header G Generic Server Command C Remote Host Command N Negative Acknowledgement (NAK) E Fatal Error T Indicates a timeout occurred Q Indicates a damaged, undesired, or illegal packet was received % Indicates a packet was retransmitted You may type certain "interrupt" commands during file transfer: Control-F: Interrupt the current File, and go on to the next (if any). Control-B: Interrupt the entire Batch of files, terminate the transaction. Control-R: Resend the current packet Control-A: Display a status report for the current transaction. These interrupt characters differ from the ones used in other Kermit implemen- tations to avoid conflict with commonly used Unix shell interrupt characters. With Version 7, System III, and System V implementations of Unix, interrupt commands must be preceeded by the 'connect' escape character (e.g. normally-\). CAUTION: If Control-F or Control-B is used to cancel an incoming file, and a file of the same name previously existed, and the "file warning" feature is not enabled, then the previous copy of the file will dis- appear. EMERGENCY EXIT: When running Unix Kermit in remote mode, if you have started a protocol operation (sending or receiving a file, server command wait, etc), you will not be able to regain control of the terminal until the protocol operation has run its course (completed or timed out). In particular, you cannot stop the protocol by typing the normal Unix interrupt characters, since the terminal has been put in "raw mode". If you need to regain control quickly -- for in- stance, because the protocol is stuck -- you can type the following sequence of four characters directly to the Unix Kermit program ("connect" first if necessary): Control-A Control-C Control-C Carriage-Return This will cause the program to exit and restore the terminal to normal. 9.3. Command Line Operation The C-Kermit command line syntax has been changed from that of earlier releases of Unix Kermit to conform to the Proposed Syntax Standards for Unix System Com- mands put forth by Kathy Hemenway and Helene Armitage of AT&T Bell Laboratories in Unix/World, Vol.1, No.3, 1984. The rules that apply are: - Command names must be between 2 and 9 characters ("kermit" is 6). - Command names must include lower case letters and digits only. - An option name is a single character. - Options are delimited by '-'. - Options with no arguments may be grouped (bundled) behind one delimiter. - Option-arguments cannot be optional. - Arguments immediately follow options, separated by whitespace. UNIX KERMIT Page 121 - The order of options does not matter. - '-' preceded and followed by whitespace means standard input. A group of bundled options may end with an option that has an argument. The following notation is used in command descriptions: fn A Unix file specification, possibly containing the "wildcard" charac- ters `*' or `?' (`*' matches all character strings, `?' matches any single character). fn1 A Unix file specification which may not contain `*' or `?'. rfn A remote file specification in the remote system's own syntax, which may denote a single file or a group of files. rfn1 A remote file specification which should denote only a single file. n A decimal number between 0 and 94. c A decimal number between 0 and 127 representing the value of an ASCII character. cc A decimal number between 0 and 31, or else exactly 127, representing the value of an ASCII control character. [ ] Any field in square braces is optional. {x,y,z} Alternatives are listed in curly braces. C-Kermit command line options may specify either actions or settings. If C-Kermit is invoked with a command line that specifies no actions, then it will issue a prompt and begin interactive dialog. Action options specify either protocol transactions or terminal connection. -s fn Send the specified file or files. If fn contains wildcard (meta) characters, the Unix shell expands it into a list. If fn is '-' then kermit sends from standard input, which must come from a file: kermit -s - < foo.bar or a parallel process: ls -l | kermit -s - You cannot use this mechanism to send terminal typein. If you want to send a file whose name is "-" you can precede it with a path name, as in kermit -s ./- -r Receive a file or files. Wait passively for files to arrive. -k Receive (passively) a file or files, sending them to standard output. This option can be used in several ways: UNIX KERMIT Page 122 kermit -k Displays the incoming files on your screen; to be used only in "local mode" (see below). kermit -k > fn1 Sends the incoming file or files to the named file, fn1. If more than one file arrives, all are concatenated together into the single file fn1. kermit -k | command Pipes the incoming data (single or multiple files) to the indicated command, as in kermit -k | sort > sorted.stuff -a fn1 If you have specified a file transfer option, you may specify an alter- nate name for a single file with the -a option. For example, kermit -s foo -a bar sends the file foo telling the receiver that its name is bar. If more than one file arrives or is sent, only the first file is affected by the -a option: kermit -ra baz stores the first incoming file under the name baz. -x Begin server operation. May be used in either local or remote mode. Before proceeding, a few words about remote and local operation are necessary. C-Kermit is "local" if it is running on PC or workstation that you are using directly, or if it is running on a multiuser system and transferring files over an external communication line -- not your job's controlling terminal or con- sole. C-Kermit is remote if it is running on a multiuser system and transfer- ring files over its own controlling terminal's communication line, connected to your PC or workstation. If you are running C-Kermit on a PC, it is in local mode by default, with the "back port" designated for file transfer and terminal connection. If you are running C-Kermit on a multiuser (timesharing) system, it is in remote mode un- less you explicitly point it at an external line for file transfer or terminal connection. The following command sets C-Kermit's "mode": -l dev Line -- Specify a terminal line to use for file transfer and terminal connection, as in kermit -l /dev/ttyi5 When an external line is being used, you might also need some additional op- tions for successful communication with the remote system: -b n Baud -- Specify the baud rate for the line given in the -l option, as in kermit -l /dev/ttyi5 -b 9600 UNIX KERMIT Page 123 This option should always be included with the -l option, since the speed of an external line is not necessarily what you expect. -p x Parity -- e,o,m,s,n (even, odd, mark, space, or none). If parity is other than none, then the 8th-bit prefixing mechanism will be used for transferring 8-bit binary data, provided the opposite Kermit agrees. The default parity is none. -t Specifies half duplex, line turnaround with XON as the handshake character. The following commands may be used only with a C-Kermit which is local -- ei- ther by default or else because the -l option has been specified. -g rfn Actively request a remote server to send the named file or files; rfn is a file specification in the remote host's own syntax. If fn happens to contain any special shell characters, like '*', these must be quoted, as in kermit -g x\*.\? -f Send a 'finish' command to a remote server. -c Establish a terminal connection over the specified or default com- munication line, before any protocol transaction takes place. Get back to the local system by typing the escape character (normally Control-Backslash) followed by the letter 'c'. -n Like -c, but after a protocol transaction takes place; -c and -n may both be used in the same command. The use of -n and -c is illustrated below. On a timesharing system, the -l and -b options will also have to be included with the -r, -k, or -s options if the other Kermit is on a remote system. Several other command-line options are provided: -i Specifies that files should be sent or received exactly "as is" with no conversions. This option is necessary for transmitting binary files. It may also be used to slightly boost efficiency in Unix-to-Unix trans- fers of text files by eliminating CRLF/newline conversion. -w Write-Protect -- Avoid filename collisions for incoming files. -q Quiet -- Suppress screen update during file transfer, for instance to allow a file transfer to proceed in the background. -d Debug -- Record debugging information in the file debug.log in the cur- rent directory. Use this option if you believe the program is mis- behaving, and show the resulting log to your local kermit maintainer. -h Help -- Display a brief synopsis of the command line options. The command line may contain no more than one protocol action option. Files are sent with their own names, except that lowercase letters are raised UNIX KERMIT Page 124 to upper, pathnames are stripped off, certain special characters like (`~') and (`#') are changed to `X', and if the file name begins with a period, an `X' is inserted before it. Incoming files are stored under their own names except that uppercase letters are lowered, and, if -w was specified, a "generation number" is appended to the name if it has the same name as an existing file which would otherwise be overwritten. If the -a option is included, then the same rules apply to its argument. The file transfer display shows any trans- formations performed upon filenames. During transmission, files are encoded as follows: - Control characters are converted to prefixed printables. - Sequences of repeated characters are collapsed via repeat counts, if the other Kermit is also capable of repeated-character compression. - If parity is being used on the communication line, data characters with the 8th (parity) bit on are specially prefixed, provided the other Kermit is capable of 8th-bit prefixing; if not, 8-bit binary files cannot be successfully transferred. - Conversion is done between Unix newlines and carriage-return-linefeed sequences unless the -i option was specified. Command Line Examples: kermit -l /dev/ttyi5 -b 1200 -cn -r This command connects you to the system on the other end of ttyi5 at 1200 baud, where you presumably log in and run Kermit with a 'send' command. After you escape back, C-Kermit waits for a file (or files) to arrive. When the file transfer is completed, you are again connected to the remote system so that you can logout. kermit -l /dev/ttyi4 -b 1800 -cntp m -r -a foo This command is like the preceding one, except the remote system in this case uses half duplex communication with mark parity. The first file that arrives is stored under the name foo. kermit -l /dev/ttyi6 -b 9600 -c | tek This example uses Kermit to connect your terminal to the system at the other end of ttyi6. The C-Kermit terminal connection does not provide any particular terminal emulation, so C-Kermit's standard i/o is piped through a (hypothetical) program called tek, which performs (say) Tektronix emulation. kermit -l /dev/ttyi6 -b 9600 -nf This command would be used to shut down a remote server and then connect to the remote system, in order to log out or to make further use of it. The -n option UNIX KERMIT Page 125 is invoked after -f (-c would have been invoked before). kermit -l /dev/ttyi6 -b 9600 -qg foo.\* & This command causes C-Kermit to be invoked in the background, getting a group of files from a remote server (note the quoting of the `*' character). No dis- play occurs on the screen, and the keyboard is not sampled for interruption commands. This allows other work to be done while file transfers proceed in the background. kermit -l /dev/ttyi6 -b 9600 -g foo.\* > foo.log < /dev/null & This command is like the previous one, except the file transfer display has been redirected to the file foo.log. Standard input is also redirected, to prevent C-Kermit from sampling it for interruption commands. kermit -iwx This command starts up C-Kermit as a server. Files are transmitted with no newline/carriage-return-linefeed conversion; the -i option is necessary for bi- nary file transfer and useful for Unix-to-Unix transfers. Incoming files that have the same names as existing files are given new, unique names. kermit -l /dev/ttyi6 -b 9600 This command sets the communication line and speed. Since no action is specified, C-Kermit issues a prompt and enters an interactive dialog with you. Any settings given on the command line remain in force during the dialog, un- less explicitly changed. kermit This command starts up Kermit interactively with all default settings. The next example shows how Unix Kermit might be used to send an entire direc- tory tree from one Unix system to another, using the tar program as Kermit's standard input and output. On the orginating system, in this case the remote, type (for instance): tar cf - /usr/fdc | kermit -is - This causes tar to send the directory /usr/fdc (and all its files and all its subdirectories and all their files...) to standard output instead of to a tape; kermit receives this as standard input and sends it as a binary file. On the receiving system, in this case the local one, type (for instance): kermit -il /dev/ttyi5 -b 9600 -k | tar xf - Kermit receives the tar archive, and sends it via standard output to its own UNIX KERMIT Page 126 copy of tar, which extracts from it a replica of the original directory tree. A final example shows how a Unix compression utility might be used to speed up Kermit file transfers: compress file | kermit -is - (sender) kermit -ik | uncompress (receiver) Exit Status Codes: Unix Kermit returns an exit status of zero, except when a fatal error is en- countered, where the exit status is set to one. With background operation (e.g., `&' at end of invoking command line) driven by scripted interactive com- mands (redirected standard input and/or take files), any failed interactive command (such as failed dial or script attempt) causes the fatal error exit. 9.4. Interactive Operation C-Kermit's interactive command prompt is "C-Kermit>". In response to this prompt, you may type any valid command. C-Kermit executes the command and then prompts you for another command. The process continues until you instruct the program to terminate. Commands begin with a keyword, normally an English verb, such as "send". You may omit trailing characters from any keyword, so long as you specify suf- ficient characters to distinguish it from any other keyword valid in that field. Certain commonly-used keywords (such as "send", "receive", "connect") have special non-unique abbreviations ("s" for "send", "r" for "receive", "c" for "connect"). Certain characters have special functions during typein of interactive com- mands: ? Question mark, typed at any point in a command, will produce a message explaining what is possible or expected at that point. Depending on the context, the message may be a brief phrase, a menu of keywords, or a list of files. ESC (The Escape or Altmode key) -- Request completion of the current keyword or filename, or insertion of a default value. The result will be a beep if the requested operation fails. DEL (The Delete or Rubout key) -- Delete the previous character from the command. You may also use BS (Backspace, Control-H) for this function. ^W (Control-W) -- Erase the rightmost word from the command line. ^U (Control-U) -- Erase the entire command. ^R (Control-R) -- Redisplay the current command. SP (Space) -- Delimits fields (keywords, filenames, numbers) within a com- mand. HT (Horizontal Tab) may also be used for this purpose. UNIX KERMIT Page 127 CR (Carriage Return) -- Enters the command for execution. LF (Linefeed) or FF (formfeed) may also be used for this purpose. \ (Backslash) -- Enter any of the above characters into the command, literally. To enter a backslash, type two backslashes in a row (\\). A backslash at the end of a command line causes the next line to be treated as a continuation line; this is useful for readability in com- mand files, especially in the 'script' command. You may type the editing characters (DEL, ^W, etc) repeatedly, to delete all the way back to the prompt. No action will be performed until the command is entered by typing carriage return, linefeed, or formfeed. If you make any mis- takes, you will receive an informative error message and a new prompt -- make liberal use of `?' and ESC to feel your way through the commands. One impor- tant command is "help" -- you should use it the first time you run C-Kermit. A command line beginning with a percent sign "%" is ignored. Such lines may be used to include illustrative commentary in Kermit command dialogs. Interactive C-Kermit accepts commands from files as well as from the keyboard. When you enter interactive dialog, C-Kermit looks for the file .kermrc in your home or current directory (first it looks in the home directory, then in the current one) and executes any commands it finds there. These commands must be in interactive format, not Unix command-line format. A "take" command is also provided for use at any time during an interactive session. Command files may be nested to any reasonable depth. Here is a brief list of C-Kermit interactive commands: ! Execute a Unix shell command, or start a shell. bye Terminate and log out a remote Kermit server. close Close a log file. connect Establish a terminal connection to a remote system. cwd Change Working Directory. dial Dial a telephone number. directory Display a directory listing. echo Display arguments literally. exit Exit from the program, closing any open files. finish Instruct a remote Kermit server to exit, but not log out. get Get files from a remote Kermit server. help Display a help message for a given command. log Open a log file -- debugging, packet, session, transaction. quit Same as 'exit'. receive Passively wait for files to arrive. remote Issue file management commands to a remote Kermit server. script Execute a login script with a remote system. send Send files. server Begin server operation. set Set various parameters. show Display values of 'set' parameters. space Display current disk space usage. statistics Display statistics about most recent transaction. take Execute commands from a file. The 'set' parameters are: UNIX KERMIT Page 128 block-check Level of packet error detection. delay How long to wait before sending first packet. duplex Specify which side echoes during 'connect'. escape-character Prefix for "escape commands" during 'connect'. file Set various file parameters. flow-control Communication line full-duplex flow control. handshake Communication line half-duplex turnaround character. incomplete Disposition for incompletely received files. line Communication line device name. modem-dialer Type of modem-dialer on communication line. parity Communication line character parity. prompt The C-Kermit program's interactive command prompt. receive Parameters for inbound packets. send Parameters for outbound packets. speed Communication line speed. The 'remote' commands are: cwd Change remote working directory. delete Delete remote files. directory Display a listing of remote file names. help Request help from a remote server. host Issue a command to the remote host in its own command language space Display current disk space usage on remote system. type Display a remote file on your screen. who Display who's logged in, or get information about a user. Most of these commands are described adequately in the Kermit User Guide. Spe- cial aspects of certain Unix Kermit commands are described below. THE 'SEND' COMMAND Syntax: send fn - or - send fn1 rfn1 Send the file or files denoted by fn to the other Kermit, which should be run- ning as a server, or which should be given the 'receive' command. Each file is sent under its own name (as described above, or as specified by the 'set file names' command). If the second form of the 'send' command is used, i.e. with fn1 denoting a single Unix file, rfn1 may be specified as a name to send it un- der. The 'send' command may be abbreviated to 's', even though 's' is not a unique abbreviation for a top-level C-Kermit command. The wildcard (meta) characters `*' and `?' are accepted in fn. If `?' is to be included, it must be prefixed by `\' to override its normal function of provid- ing help. `*' matches any string, `?' matches any single character. Other notations for file groups, like `[a-z]og', are not available in interactive commands (though of course they are available on the command line). When fn contains `*' or `?' characters, there is a limit to the number of files that can be matched, which varies from system to system. If you get the message "Too many files match" then you'll have to make a more judicious selection. If fn was of the form usr/longname/anotherlongname/* then C-Kermit's string space will fill up rapidly -- try doing a cwd (see UNIX KERMIT Page 129 below) to the path in question and reissuing the command. Note -- C-Kermit sends only from the current or specified directory. It does not traverse directory trees. If the source directory contains subdirectories, they will be skipped. Conversely, C-Kermit does not create directories when receiving files. If you have a need to do this, you can pipe tar through C-Kermit, as shown in the example on page 125, or under System III/V Unix you can use cpio. Another Note -- C-Kermit does not skip over "invisible" files that match the file specification; Unix systems usually treat files whose names start with a dot (like .login, .cshrc, and .kermrc) as invisible. Similarly for "temporary" files whose names start with "#". THE 'RECEIVE' COMMAND Syntax: receive - or - receive fn1 Passively wait for files to arrive from the other Kermit, which must be given the 'send' command -- the 'receive' command does not work in conjunction with a server (use 'get' for that). If fn1 is specified, store the first incoming file under that name. The 'receive' command may be abbreviated to 'r'. THE 'GET' COMMAND: Syntax: get rfn or: get rfn fn1 Request a remote Kermit server to send the named file or files. Since a remote file specification (or list) might contain spaces, which normally delimit fields of a C-Kermit command, an alternate form of the command is provided to allow the inbound file to be given a new name: type 'get' alone on a line, and you will be prompted separately for the remote and local file specifications, for example C-Kermit>get Remote file specification: profile exec Local name to store it under: profile.exec As with 'receive', if more than one file arrives as a result of the 'get' com- mand, only the first will be stored under the alternate name given by fn1; the remaining files will be stored under their own names if possible. If a `?' is to be included in the remote file specification, you must prefix it with `\' to suppress its normal function of providing help. If you have started a multiline 'get' command, you may escape from its lower- level prompts by typing a carriage return in response to the prompt, e.g. C-Kermit>get Remote file specification: foo Local name to store it under: (Type a carriage return here) UNIX KERMIT Page 130 (cancelled) C-Kermit> THE 'SERVER' COMMAND: The 'server' command places C-Kermit in "server mode" on the currently selected communication line. All further commands must arrive as valid Kermit packets from the Kermit on the other end of the line. The Unix Kermit server can respond to the following commands: Command Server Response get Sends files send Receives files bye Attempts to log itself out finish Exits to level from which it was invoked remote directory Sends directory lising remote delete Removes files remote cwd Changes working directory remote type Sends files to your screen remote space Reports about its disk usage remote who Shows who's logged in remote host Executes a Unix shell command remote help Lists these capabilities Note that the Unix Kermit server cannot always respond to a BYE command. It will attempt to do so using "kill()", but this will not work on all systems or under all conditions. If the Kermit server is directed at an external line (i.e. it is in "local mode") then the console may be used for other work if you have 'set file dis- play off'; normally the program expects the console to be used to observe file transfers and enter status queries or interruption commands. The way to get C-Kermit into background operation from interactive command level varies from system to system (e.g. on Berkeley Unix you would halt the program with ^Z and then use the C-Shell 'bg' command to continue it in the background). The more common method is to invoke the program with the desired command line arguments, including "-q", and with a terminating "&". When the Unix Kermit server is given a 'remote host' command, it executes it using the shell invoked upon login, e.g. the Bourne shell or the Berkeley C-Shell. THE 'REMOTE', 'BYE', AND 'FINISH' COMMANDS: C-Kermit may itself request services from a remote Kermit server. In addition to 'send' and 'get', the following commands may also be sent from C-Kermit to a Kermit server: remote cwd [directory] If the optional remote directory specification is included, you will be prompted on a separate line for a password, which will not echo as you type it. remote delete rfn delete remote file or files. UNIX KERMIT Page 131 remote directory [rfn] directory listing of remote files. remote host command command in remote host's own command language. remote space disk usage report from remote host. remote type [rfn] display remote file or files on the screen. remote who [user] display information about who's logged in. remote help display remote server's capabilities. bye and finish: When connected to a remote Kermit server, these commands cause the remote server to terminate; 'finish' returns it to Kermit or system command level (depending on the implementation or how the program was invoked); 'bye' also requests it to log itself out. THE 'LOG' AND 'CLOSE' COMMANDS: Syntax: log {debugging, packets, session, transactions} [ fn1 ] C-Kermit's progress may be logged in various ways. The 'log' command opens a log, the 'close' command closes it. In addition, all open logs are closed by the 'exit' and 'quit' commands. A name may be specified for a log file; if the name is omitted, the file is created with a default name as shown below. log debugging This produces a voluminous log of the internal workings of C-Kermit, of use to Kermit developers or maintainers in tracking down suspected bugs in the C-Kermit program. Use of this feature dramatically slows down the Kermit protocol. Default name: debug.log. log packets This produces a record of all the packets that go in and out of the com- munication port. This log is of use to Kermit maintainers who are tracking down protocol problems in either C-Kermit or any Kermit that C-Kermit is connected to. Default name: packet.log. log session This log will contain a copy of everything you see on your screen during the 'connect' command, except for local messages or interaction with local escape commands. Default name: session.log. log transactions The transaction log is a record of all the files that were sent or received while transaction logging was in effect. It includes time stamps and statistics, filename transformations, and records of any errors that may have occurred. The transaction log allows you to have long unattended file transfer sessions without fear of missing some vital screen message. Default name: transact.log. The 'close' command explicitly closes a log, e.g. 'close debug'. Note: Debug and Transaction logs are a compile-time option; C-Kermit may be compiled without these logs, in which case it will run faster, it will take up less space on the disk, and the commands relating to them will not be present. UNIX KERMIT Page 132 LOCAL FILE MANAGEMENT COMMANDS: Unix Kermit allows some degree of local file management from interactive com- mand level: directory [fn] Displays a listing of the names, modes, sizes, and dates of files matching fn (which defaults to `*'). Equivalent to `ls -l'. cwd [directory-name] Changes Kermit's working directory to the one given, or to the default directory if the directory name is omitted. This command affects only the Kermit process and any processes it may subsequently create. space Display information about disk space and/or quota in the current directory and device. ! [command] The command is executed by the Unix shell. If no command is specified, then an interactive shell is started; exiting from the shell, e.g. by typing Control-D, will return you to C-Kermit command level. C-Kermit at- tempts to use your preferred, customary shell. Use the `!' command to provide file management or other functions not explicitly provided by C-Kermit commands. The `!' command has certain peculiarities: - At least one space must separate the '!' from the shell command. - A 'cd' command executed in this manner will have no effect -- use the C-Kermit 'cwd' command instead. THE 'SET' AND 'SHOW' COMMANDS: Since Kermit is designed to allow diverse systems to communicate, it is often necessary to issue special instructions to allow the program to adapt to peculiarities of the another system or the communication path. These instruc- tions are accomplished by the 'set' command. The 'show' command may be used to display current settings. Here is a brief synopsis of settings available in the current release of C-Kermit: block-check {1, 2, 3} Determines the level of per-packet error detection. "1" is a single- character 6-bit checksum, folded to include the values of all bits from each character. "2" is a 2-character, 12-bit checksum. "3" is a 3-character, 16-bit cyclic redundancy check (CRC). The higher the block check, the better the error detection and correction and the higher the resulting overhead. Type 1 is most commonly used; it is supported by all Kermit implementations, and it has proven adequate in most circumstances. Types 2 or 3 would be used to advantage when transferring 8-bit binary files over noisy lines. delay n How many seconds to wait before sending the first packet after a 'send' command. Used in remote mode to give you time to escape back to your local Kermit and issue a 'receive' command. Normally 5 seconds. UNIX KERMIT Page 133 duplex {full, half} For use during 'connect'. Specifies which side is doing the echoing; 'full' means the other side, 'half' means C-Kermit must echo typein itself. escape-character cc For use during 'connect' to get C-Kermit's attention. The escape character acts as a prefix to an 'escape command', for instance to close the connec- tion and return to C-Kermit or Unix command level. The normal escape character is Control-Backslash (28). The escape character is also used in System III/V implementations to prefix interrupt commands during file transfers. file {display, names, type, warning} Establish various file-related parameters: display {on, off} Normally 'on'; when in local mode, display progress of file transfers on the screen (stdout), and listen to the keyboard (stdin) for inter- ruptions. If off (-q on command line) none of this is done, and the file transfer may proceed in the background oblivious to any other work concurrently done at the console terminal. names {converted, literal} Normally converted, which mean that outbound filenames have path specifications stripped, lowercase letters raised to upper, tildes and extra periods changed to X's, and an X inserted in front of any name that starts with period. Incoming files have uppercase letters lowered. Literal means that none of these conversions are done; there- fore, any directory path appearing in a received file specification must exist and be write-accessible. When literal naming is being used, the sender should not use path names in the file specification unless the same path exists on the target system and is writable. type {binary, text} Normally text, which means that conversion is done between Unix newline characters and the carriage-return/linefeed sequences required by the canonical Kermit file transmission format, and in common use on non- Unix systems. Binary means to transmit file contents without conver- sion. Binary (`-i' in command line notation) is necessary for binary files, and desirable in all Unix-to-Unix transactions to cut down on overhead. warning {on, off} Normally off, which means that incoming files will silently overwrite existing files of the same name. When on (`-w' on command line) Kermit will check if an arriving file would overwrite an existing file; if so, it will construct a new name for the arriving file, of the form foo~n, where foo is the name they share and n is a "generation number"; if foo exists, then the new file will be called foo~1. If foo and foo~1 ex- ist, the new file will be foo~2, and so on. If the new name would be longer than the maximum length for a filename, then characters would be deleted from the end first, for instance, thelongestname on a system with a limit of 14 characters would become thelongestn~1. CAUTION: If Control-F or Control-B is used to cancel an incom- ing file, and a file of the same name previously existed, and UNIX KERMIT Page 134 the "file warning" feature is not enabled, then the previous copy of the file will disappear. flow-control {none, xon/xoff} Normally xon/xoff for full duplex flow control. Should be set to 'none' if the other system cannot do xon/xoff flow control, or if you have issued a 'set handshake' command. If set to xon/xoff, then handshake should be set to none. This setting applies during both terminal connection and file transfer. incomplete {discard, keep} Disposition for incompletely received files. If an incoming file is inter- rupted or an error occurs during transfer, the part that was received so far is normally discarded. If you "set incomplete keep" then such file fragments will be kept. handshake {xon, xoff, cr, lf, bell, esc, none} Normally none. Otherwise, half-duplex communication line turnaround hand- shaking is done, which means Unix Kermit will not reply to a packet until it has received the indicated handshake character or has timed out waiting for it; the handshake setting applies only during file transfer. If you set handshake to other than none, then flow should be set to none. line [device-name] The device name for the communication line to be used for file transfer and terminal connection, e.g. /dev/ttyi3. If you specify a device name, Kermit will be in local mode, and you should remember to issue any other necessary 'set' commands, such as 'set speed'. If you omit the device name, Kermit will revert to its default mode of operation. If you specify /dev/tty, Kermit will enter remote mode (useful when logged in through the "back port" of a system normally used as a local-mode workstation). When Unix Kermit enters local mode, it attempts to synchronize with other programs (like uucp) that use external communication lines so as to prevent two programs using the same line at once; before attempting to lock the specified line, it will close and unlock any external line that was previously in use. The method used for locking is the "uucp lock file", explained in more detail later. modem-dialer {direct, hayes, racalvadic, ventel, ...} The type of modem dialer on the communication line. "Direct" indicates ei- ther there is no dialout modem, or that if the line requires carrier detec- tion to open, then 'set line' will hang waiting for an incoming call. "Hayes", "Ventel", and the others indicate that 'set line' (or the -l argument) will prepare for a subsequent 'dial' command for the given dialer. Support for new dialers is added from time to time, so type 'set modem ?' for a list of those supported in your copy of Kermit. See the description of the 'dial' command parity {even, odd, mark, space, none} Specify character parity for use in packets and terminal connection, nor- mally none. If other than none, C-Kermit will seek to use the 8th-bit prefixing mechanism for transferring 8-bit binary data, which can be used successfully only if the other Kermit agrees; if not, 8-bit binary data cannot be successfully transferred. prompt [string] UNIX KERMIT Page 135 The given string will be substituted for "C-Kermit>" as this program's prompt. If the string is omitted, the prompt will revert to "C-Kermit>". If the string is enclosed in doublequotes, the quotes will be stripped and any leading and trailing blanks will be retained. send parameter Establish parameters to use when sending packets. These will be in effect only for the initial packet sent, since the other Kermit may override these parameters during the protocol parameter exchange (unless noted below). end-of-packet cc Specifies the control character needed by the other Kermit to recognize the end of a packet. C-Kermit sends this character at the end of each packet. Normally 13 (carriage return), which most Kermit implemen- tations require. Other Kermits require no terminator at all, still others may require a different terminator, like linefeed (10). packet-length n Specify the maximum packet length to send. Normally 90. Shorter packet lengths can be useful on noisy lines, or with systems or front ends or networks that have small buffers. The shorter the packet, the higher the overhead, but the lower the chance of a packet being cor- rupted by noise, and the less time to retransmit corrupted packets. This command overrides the value requested by the other Kermit during protocol initiation. pad-character cc Designate a character to send before each packet. Normally, none is sent. Outbound padding is sometimes necessary for communicating with slow half duplex systems that provide no other means of line turnaround control. It can also be used to send special characters to communica- tions equipment that needs to be put in "transparent" or "no echo" mode, when this can be accomplished in by feeding it a certain control character. padding n How many pad characters to send, normally 0. start-of-packet cc The normal Kermit packet prefix is Control-A (1); this command changes the prefix C-Kermit puts on outbound packets. The only reasons this should ever be changed would be: Some piece of equipment somewhere be- tween the two Kermit programs will not pass through a Control-A; or, some piece of of equipment similarly placed is echoing its input. In the latter case, the recipient of such an echo can change the packet prefix for outbound packets to be different from that of arriving pack- ets, so that the echoed packets will be ignored. The opposite Kermit must also be told to change the prefix for its inbound packets. timeout n Specifies the number of seconds you want the other Kermit to wait for a packet before timing it out and requesting retransmission. receive parameter Establish parameters to request the other Kermit to use when sending pack- ets. UNIX KERMIT Page 136 end-of-packet cc Requests the other Kermit to terminate its packets with the specified character. packet-length n Specify the maximum packet length to that you want the other Kermit to send. Normally 90. pad-character cc C-Kermit normally does not need to have incoming packets preceded with pad characters. This command allows C-Kermit to request the other Ker- mit to use cc as a pad character. Default cc is NUL, ASCII 0. padding n How many pad characters to ask for, normally 0. start-of-packet cc Change the prefix C-Kermit looks for on inbound packets to correspond with what the other Kermit is sending. timeout n Normally, each Kermit partner sets its packet timeout interval based on what the opposite Kermit requests. This command allows you to override the normal procedure and specify a timeout interval for Unix Kermit to use when waiting for packets from the other Kermit. If you specify 0, then no timeouts will occur, and Unix Kermit will wait forever for ex- pected packets to arrive. speed {0, 110, 150, 300, 600, 1200, 1800, 2400, 4800, 9600} The baud rate for the external communication line. This command cannot be used to change the speed of your own console terminal. Many Unix systems are set up in such a way that you must give this command after a 'set line' command before you can use the line. 'set baud' is a synomym for 'set speed'. THE 'SHOW' COMMAND: Syntax: show {parameters, versions} The "show" command with the default argument of "parameters" displays the values of all the 'set' parameters described above. If you type "show versions", then C-Kermit will display the version numbers and dates of all its internal modules. You should use the "show versions" command to ascertain the vintage of your Kermit program before reporting problems to Kermit maintainers. THE 'STATISTICS' COMMAND: The statistics command displays information about the most recent Kermit protocol transaction, including file and communication line i/o, timing and ef- ficiency, as well as what encoding options were in effect (such as 8th-bit prefixing, repeat-count compression). UNIX KERMIT Page 137 THE 'TAKE' AND 'ECHO' COMMANDS: Syntax: take fn1 echo [text to be echoed] The 'take' command instructs C-Kermit to execute commands from the named file. The file may contain any interactive C-Kermit commands, including 'take'; com- mand files may be nested to any reasonable depth. The 'echo' command may be used within command files to issue greetings, announce progress, ring the ter- minal bell, etc. The 'echo' command should not be confused with the Unix 'echo' command, which can be used to show how meta characters would be expanded. The Kermit echo command simply displays its text argument (almost) literally at the terminal; the argument may contain octal escapes of the form "\ooo", where o is an octal digit (0-7), and there may be 1, 2, or 3 such digits, whose value specify an ASCII character, such as "\007" (or "\07" or just "\7") for beep, "\012" for newline, etc. Of course, each backslash must be must be entered twice in order for it to be passed along to the echo command by the Kermit command parser. Take-command files are in exactly the same syntax as interactive commands. Note that this implies that if you want to include special characters like question mark or backslash that you would have to quote with backslash when typing interactive commands, you must quote these characters the same way in command files. Long lines may be continued by ending them with a single back- slash. Command files may be used in lieu of command macros, which have not been imple- mented in this version of C-Kermit. For instance, if you commonly connect to a system called 'B' that is connected to ttyh7 at 4800 baud, you could create a file called b containing the commands % C-Kermit command file to connect to System B thru /dev/ttyh7 set line /dev/ttyh7 set speed 4800 % Beep and give message echo \\007Connecting to System B... connect and then simply type 'take b' (or 't b' since no other commands begin with the letter 't') whenever you wish to connect to system B. Note the comment lines and the beep inserted into the 'echo' command. For connecting to IBM mainframes, a number of 'set' commands are required; these, too, are conveniently collected into a 'take' file like this one: % Sample C-Kermit command file to set up current line % for IBM mainframe communication % set parity mark set handshake xon set flow-control none set duplex half Note that no single command is available to wipe out all of these settings and return C-Kermit to its default startup state; to do that, you can either res- UNIX KERMIT Page 138 tart the program, or else make a command file that executes the necessary 'set' commands: % Sample C-Kermit command file to restore normal settings % set parity none set handshake none set flow-control xon/xoff set duplex full An implicit 'take' command is executed upon your .kermrc file upon C-Kermit's initial entry into interactive dialog. The .kermrc file should contain 'set' or other commands you want to be in effect at all times. For instance, you might want override the default action when incoming files have the same names as existing files -- in that case, put the command set file warning on in your .kermrc file. On some non-Unix systems that run C-Kermit, this file might have a different name, such as kermit.ini. NOTE: The initialization file is currently not processed if Kermit is invoked with an action command from the command line. The same effect can be achieved, however, by defining an alias or shell procedure that starts up Kermit with the desired command line options. Commands executed from take files are not echoed at the terminal. If you want to see the commands as well as their output, you could feed the command file to C-Kermit via redirected stdin, as in 'kermit < cmdfile' Errors encountered during execution of take files (such as failure to complete dial or script operations) cause termination of the current take file, popping to the level that invoked it (take file, interactive level, or the shell). When kermit is executed in the background, errors during execution of a take file are fatal. THE 'CONNECT' COMMAND: The connect command links your terminal to another computer as if it were a lo- cal terminal to that computer, through the device specified in the most recent 'set line' command, or through the default device if your system is a PC or workstation. All characters you type at your keyboard are sent out the com- munication line, all characters arriving at the communication port are dis- played on your screen. Current settings of speed, parity, duplex, and flow- control are honored. If you have issued a 'log session' command, everything you see on your screen will also be recorded to your session log. This provides a way to "capture" files from systems that don't have Kermit programs available. To get back to your own system, you must type the escape character, which is Control-Backslash (^\) unless you have changed it with the 'set escape' com- mand, followed by a single-character command, such as 'c' for "close connection". Single-character commands include: UNIX KERMIT Page 139 c Close the connection b Send a BREAK signal 0 (zero) send a null s Give a status report about the connection h Hangup the phone ^\ Send Control-Backslash itself (whatever you have defined the escape character to be, typed twice in a row sends one copy of it). Uppercase and control equivalents for these letters are also accepted. A space typed after the escape character is ignored. Any other character will produce a beep. The connect command simply displays incoming characters on the screen. It is assumed any screen control sequences sent by the host will be handled by the firmware in your terminal or PC. If terminal emulation is desired, then the connect command can invoked from the Unix command line (-c or -n), piped through a terminal emulation filter, e.g. kermit -l /dev/acu -b 1200 -c | tek 'c' is an acceptable non-unique abbreviation for 'connect'. THE 'DIAL' COMMAND: Syntax: dial telephone-number-string This command controls dialout modems; you should have already issued a "set line" and "set speed" command to identify the terminal device, and a "set modem" command to identify the type of modem to be used for dialing. In the "dial" command, you supply the phone number and the Kermit program feeds it to the modem in the appropriate format and then interprets dialer return codes and modem signals to inform you whether the call was completed. The telephone- number-string may contain imbedded modem-dialer commands, such as comma for Hayes pause, or `&' for Ventel dialtone wait and `%' for Ventel pause (consult your modem manual for details). At the time of this writing, support is included for the following modems: - Cermetek Info-Mate 212A - DEC DF03-AC - DEC DF100 Series - DEC DF200 Series - General DataComm 212A/ED - Hayes Smartmodem 1200 and compatibles - Penril - Racal Vadic - US Robotics 212A - Ventel Support for new modems is added to the program from time to time; you can check the current list by typing "set modem ?". The device used for dialing out is the one selected in the most recent "set line" command (or on a workstation, the default line if no "set line" command was given). The "dial" command calls locks the path (see the section on line UNIX KERMIT Page 140 locking below) and establishes a call on an exclusive basis. If it is desired to dial a call and then return to the shell (such as to do kermit activities depending on standard in/out redirection), it is necessary to place the dialed call under one device name (say, "/dev/cua0") and then escape to the shell within Kermit on a linked device which is separate from the dialed line (say, "/dev/cul0"). This is the same technique used by uucp (to allow locks to be placed separately for dialing and conversing). Because modem dialers have strict requirements to override the carrier-detect signal most Unix implementations expect, the sequence for dialing is more rigid than most other C-Kermit procedures. Example one: kermit -l /dev/cul0 -b 1200 C-Kermit>set modem-dialer hayes hint: abbreviate set m h C-Kermit>dial 9,5551212 Connected! C-Kermit>connect hint: abbreviate c logon, request remote server, etc. C-Kermit> ... C-Kermit>quit hint: abbreviate q this disconnects modem, and unlocks line. Example two: kermit C-Kermit>set modem-dialer ventel C-Kermit>set line /dev/cul0 C-Kermit>dial 9&5551212% Connected! C-Kermit> ... Example three: kermit C-Kermit>take my-dial-procedure Connected! file my-dial-procedure: set modem hayes set line /dev/tty99 dial 5551212 connect For Hayes dialers, two important switch settings are #1 and #6. #1 should be up so that the DTR is only asserted when the line is 'open'. #6 should be up so carrier-detect functions properly. Switches #2 (English versus digit result codes) and #4 (Hayes echoes modem commands) may be in either position. For any dialers in general, this Kermit program requires that the modem provide the "carrier detect" signal when a call is in progress, and remove that signal when the call completes or the line drops. If a switch setting is available to force carrier detect, it should not be in that setting. Secondly, this Kermit program requires that the modem track the computer's "data terminal ready" sig- UNIX KERMIT Page 141 nal (DTR). If a switch setting is available to simulate DTR asserted within the modem, then it should not be in that setting. Otherwise the modem will be unable to hang up at the end of a call or when interrupts are received by Ker- mit. If you want to interrupt a dial command in progress (for instance, because you just realize that you gave it the wrong number), type a Control-C to get back to command level. THE 'SCRIPT' COMMAND: Syntax: script expect send [expect send] . . . "expect" has the syntax: expect[-send-expect[-send-expect[...]]] This command facilitates logging into a remote system and/or invoking programs or other facilities after login on a remote system. This login script facility operates in a manner similar to that commonly used by the Unix uucp System's "L.sys" file entries. A login script is a sequence of the form: expect send [expect send] . . . where expect is a prompt or message to be issued by the remote site, and send is the string (names, numbers, etc) to return. The send may also be the keyword EOT, to send Control-D, or BREAK, to send a break signal. Letters in send may be prefixed by `~' to send special characters. These are: ~b backspace ~s space ~q `?'(trapped by Kermit's command interpreter) ~n linefeed ~r carriage return ~t tab ~' single quote ~~ tilde ~" double quote ~x XON (Control-Q) ~c don't append a carriage return ~o[o[o]] an octal character ~d delay approx 1/3 second during send ~w[d[d]] wait specified interval during expect, then time out As with some uucp systems, sent strings are followed by ~r unless they have a ~c. Only the last 7 characters in each expect are matched. A null expect, e.g. ~0 or two adjacent dashes, causes a short delay before proceeding to the next send sequence. A null expect always succeeds. As with uucp, if the expect string does not arrive, the script attempt fails. If you expect that a sequence might not arrive, as with uucp, conditional se- quences may be expressed in the form: UNIX KERMIT Page 142 -send-expect[-send-expect[...]] where dashed sequences are followed as long as previous expects fail. Timeouts for expects can be specified using ~w; ~w with no arguments waits 15 seconds. Expect/send transactions can be easily be debugged by logging transactions. This records all exchanges, both expected and actual. Note that `\' characters in login scripts, as in any other C-Kermit interactive commands, must be doubled up. A line may be ended with a single `\' for con- tinuation. Example one: Using a modem, dial a UNIX host site. Expect "login" (...gin), and if it doesn't come, simply send a null string with a ~r. (Some Unixes require either an EOT or a BREAK instead of the null sequence, depending on the particular site's "logger" program.) After providing user id and password, respond "x" to a question-mark prompt, expect the Bourne shell "$" prompt (and send return if it doesn't arrive). Then cd to directory kermit, and run the program called "wermit", entering the interactive connect state after wermit is loaded. set modem-dialer ventel set line /dev/tty77 set baud 1200 dial 9&5551212 script gin:--gin:--gin: smith ssword: mysecret ~q x $--$ \ cd~skermit $ wermit connect Example two: Using a modem, dial the Telenet network. This network expects three returns with slight delays between them. These are sent following null expects. The single return is here sent as a null string, with a return appended by default. Four returns are sent to be safe before looking for the prompt. Then the Telenet id and password are entered. Then telenet is instructed to connect to a host site (c 12345). The host has a data switch, and to "which system" it responds "myhost". This is followed by a TOPS-20 logon, and a request to load Kermit, set even parity, and enter the server mode. Files are then exchanged. The commands are in a take file; note the continuation of the 'script' command onto several lines using the `\' terminator. set modem-dialer hayes set line /dev/cul0 set baud 1200 dial 9,5551212 set parity even script ~0 ~0 ~0 ~0 ~0 ~0 ~0 ~0 @--@--@ id~saa001122 = 002211 @ \ c~s12345 ystem-c~s12345-ystem myhost @ joe~ssecret @ kermit \ > set~sparity~seven > server send some.stuff get some.otherstuff bye quit UNIX KERMIT Page 143 Since these commands may be executed totally in the background, they can also be scheduled. A typical shell script, which might be scheduled by cron, would be as follows (csh used for this example): # #keep trying to dial and log onto remote host and exchange files #wait 10 minutes before retrying if dial or script fail. # cd someplace while ( 1 ) kermit < /tonight.cmd >> nightly.log & if ( ! $status ) break sleep 600 end File tonight.cmd might have two takes in it, for example, one to take a file with the set modem, set line, set baud, dial, and script, and a second take of a file with send/get commands for the remote server. The last lines of tonight.cmd should be a bye and a quit. THE 'HELP' COMMAND: Syntax: help or: help keyword or: help {set, remote} keyword Brief help messages or menus are always available at interactive command level by typing a question mark at any point. A slightly more verbose form of help is available through the 'help' command. The 'help' command with no arguments prints a brief summary of how to enter commands and how to get further help. 'help' may be followed by one of the top-level C-Kermit command keywords, such as 'send', to request information about a command. Commands such as 'set' and 'remote' have a further level of help. Thus you may type 'help', 'help set', or 'help set parity'; each will provide a successively more detailed level of help. THE 'EXIT' AND 'QUIT' COMMANDS: These two commands are identical. Both of them do the following: - Attempt to insure that the terminal is returned to normal. - Relinquish access to any communication line assigned via 'set line'. - Relinquish any uucp and multiuser locks on the communications line. - Hang up the modem, if the communications line supports data terminal ready. - Close any open log files. After exit from C-Kermit, your default directory will be the same as when you started the program. The 'exit' command is issued implicitly whenever C-Kermit halts normally, e.g. after a command line invocation, or after certain kinds of interruptions. UNIX KERMIT Page 144 9.5. UUCP Lock Files Unix has no standard way of obtaining exclusive access to an external com- munication line. When you issue the 'set line' command to Unix Kermit, Unix would normally grant you access to the line even if some other process is making use of it. The method adopted by most Unix systems to handle this situation is the "UUCP lock file". UUCP, the Unix-to-Unix Copy program, creates a file in its directory (usually /usr/spool/uucp, on some systems /etc/locks) with a name like LCK..name, where name is the device name, for in- stance tty07. Unix Kermit uses UUCP lock files in order to avoid conflicts with UUCP, tip, or other programs that follow this convention. Whenever you attempt to access an external line using the 'set line' command or `-l' on the command line, Kermit looks in the UUCP directory for a lock file corresponding to that device. For instance, if you 'set line /dev/ttyi6' then Kermit looks for the file /usr/spool/uucp/LCK..ttyi6 If it finds this file, it gives you an error message and a directory listing of the file so that you can see who is using it, e.g. -r--r--r-- 1 fdc 4 May 7 13:02 /usr/spool/uucp/LCK..ttyi6 In this case, you would look up user fdc to find out how soon the line will be- come free. This convention requires that the uucp directory be publicly readable and writable. If it is not, the program will issue an appropriate warning message, but will allow you to proceed at your own risk (and the risk of anyone else who might also be using the same line). If no lock file is found, Unix Kermit will attempt create one, thus preventing anyone who subsequently tries to run Kermit, UUCP, tip, or similar programs on the same line from gaining access until you release the line. If Kermit could not create the lock file (for instance because the uucp directory is write- protected), then you will receive a warning message but will be allowed to proceed at your -- and everyone else's -- risk. When Kermit terminates nor- mally, your lock file is removed. Even when the lock directory is writable and readable, the locking mechanism depends upon all users using the same name for the same device. If a device has more than one path associated with it, then a lock can be circumvented by using an alias. When a lock-creating program abruptly terminates, e.g. because it crashes or is killed via shell command, the lock file remains in the uucp directory, spuriously indicating that the line is in use. If the lock file is owned by yourself, you may remove it. Otherwise, you'll have to get the owner or the system manager to remove it, or else wait for a system task to do so; uucp sup- ports a function (uuclean) which removes these files after a predetermined age -- uucp sites tend to run this function periodically via crontab. Locking is not needed, or used, if communications occur over the user's login terminal line (normally /dev/tty). UNIX KERMIT Page 145 It may be seen that line locking is fraught with peril. It is included in Unix Kermit only because other Unix communication programs rely on it. While it is naturally desirable to assure exclusive access to a line, it is also un- desirable to refuse access to a vacant line only because of a spurious lock file, or because the uucp directory is not appropriately protected. 9.6. C-Kermit under Berkeley or System III/V Unix: C-Kermit may be interrupted at command level or during file transfer by typing Control-C. The program will perform its normal exit function, restoring the terminal and releasing any lock. If a protocol transaction was in progress, an error packet will be sent to the opposite Kermit so that it can terminate cleanly. C-Kermit may be invoked in the background ("&" on shell commmand line). If a background process is "killed", the user will have to manually remove any lock file and may need to restore the modem. This is because the kill signal (kill(x,9)) cannot be trapped by Kermit. During execution of a system command ('directory', 'cwd', or `!'), C-Kermit can often be returned to command level by typing a single Control-C. (With System III/V, the usual interrupt function (often the DEL key) is replaced by Control-C.) Under Berkeley Unix only: C-Kermit may also be interrupted by ^Z to put the process in the background. In this case the terminal is not restored. You will have to type Control-J followed by "reset" followed by another Control-J to get your terminal back to normal. Control-C, Control-Z, and Control-\ lose their normal functions during terminal connection and also during file transfer when the controlling tty line is being used for packet i/o. If you are running C-Kermit in "quiet mode" in the foreground, then interrupt- ing the program with a console interrupt like Control-C will not restore the terminal to normal conversational operation. This is because the system call to enable console interrupt traps will cause the program to block if it's run- ning in the background, and the primary reason for quiet mode is to allow the program to run in the background without blocking, so that you can do other work in the foreground. If C-Kermit is run in the background ("&" on shell commmand line), then the in- terrupt signal (Control-C) (and System III/V quit signal) are ignored. This prevents an interrupt signal intended for a foreground job (say a compilation) from being trapped by a background Kermit session. 9.7. C-Kermit on the DEC Pro-3xx with Pro/Venix Version 1 The DEC Professional 300 series are PDP-11/23 based personal computers. Venix Version 1 is a Unix v7 derivative. It should not be confused with Venix Ver- sion 2, which is based on ATT System V; these comments apply to Venix Version 1 only. C-Kermit runs in local mode on the Pro-3xx when invoked from the con- sole; the default device is /dev/com1.dout. When connected to a remote system (using C-Kermit's 'connect' command), Pro/Venix itself (not Kermit) provides UNIX KERMIT Page 146 VT52 terminal emulation. Terminal operation at high speeds (like 9600 baud) requires xon/xoff flow control, which unfortunately interferes with applica- tions such as the EMACS that use Control-Q and Control-S as commands. When logging in to a Pro-3xx (or any workstation) through the "back port", it may be necessary to give the command "set line /dev/tty" in order to get C-Kermit to function correctly in remote mode (on a system in which it normally expects to be operating in local mode). 9.8. C-Kermit under VAX/VMS Version 4C of C-Kermit can be built using VAX-11 C to run under VMS. Most of the descriptions in this manual hold true, but it should be noted that as of this writing the VMS support is not thoroughly tested, and no explicit support exists for the various types of VMS files and their attributes. The C-Kermit init file for VMS is called KERMIT.INI. 9.9. C-Kermit on the Macintosh The "protocol kernel" of C-Kermit is also used by Columbia's Macintosh Kermit. The user and system interface is entirely different, and is covered in a separate document. 9.10. C-Kermit Restrictions and Known Bugs 1. Editing characters: The program's interactive command interrupt, delete, and kill characters are Control-C, Delete (or Backspace), and Control-U, respectively. There is currently no way to change them to suit your taste or match those used by your shell, in case those are different. 2. High baud rates: There's no way to specify baud rates higher than 9600 baud. Most Unix systems don't supply symbols for them (unless you use EXTA, EXTB), and even when they do, the program has no way of knowing whether a specific port's serial i/o controller supports those rates. 3. Modem controls: If a connection is made over a communication line (rather than on the controlling terminal line), and that line has modem controls, (e.g. data terminal ready and carrier detection implementation), returning to the shell level will disconnect the conversation. In that case, one should use interactive mode com- mands, and avoid use of piped shell-level operation (also see 'set modem-dialer' and 'dial' commands.) 4. Login Scripts: The present login scripts implementation follows the Unix conventions of uucp's "L.sys" file, rather than the normal Ker- mit "INPUT/OUTPUT" style, so there's no way to arbitrarily mingle script output with Kermit commands (e.g. changing parity or duplex in the middle of a script). 5. Dial-out vs dial-in communications lines: C-Kermit requires a UNIX KERMIT Page 147 dial-out or dedicated line for the "set line" or "-l" options. Most systems have some lines dedicated to dial-in, which they enable "loggers" on, and some lines available for dial-out. Where a line must be shared between dial-in and dial-out, several options are available (though they are, strictly speaking, outside the pervue of C-Kermit). A simple shell program can be used to change directionality of the line if your Unix has the enable(8) and disable(8) commands. In that case, the shell program could "grep" a "who" to see if anybody is logged onto the desired line; if not, it could "disable" the line. The shell program will need to be set-uID'ed to root. The shell program can be called from kermit prior to a dial command, e.g., "! mydisable.shellprog". Prior to the final "quit" from C-Kermit, another shell program could be executed to "enable" the line again. This program also needs to be set-uID'ed to root. If your Unix lacks the enable(8) and disable(8) commands, another common technique works if your system supports the /etc/ttys file. A shell program could call up an awk program to find the line in the file and set the enable byte to 0 (to directly disable the line). Likewise, it can be reenabled by a counterpart at the end. It may be necessary to pause for 60 seconds after modifying that file be- fore the logger sees it and actually disables the line. 6. Using C-Kermit on Local Area Networks: C-Kermit can successfully operate at speeds up to 9600 baud over LANs, provided the network buffers are big enough to accommodate Kermit packets (which are al- most always less than 100 characters long). When computers are connected to LAN's through asynchronous terminal interfaces, then the connection should be configured to do XON/XOFF flow control between the network interface and the computer, rather than passing these signals through transparently. This can help prevent Kermit from overrunning the LAN's buffers if they are small (or if the LAN is congested), and will can also prevent the LAN from overrunning a slow Kermit's buffers. If the network hardware cannot accept 100 characters at a time, and flow control cannot be done between the network and the computer, then Kermit's "set send/receive packet-length" command can be used to shorten the packets. 7. Resetting terminal after abnormal termination or kill: When C-Kermit terminates abnormally (say, for example, by a kill command issued by the operator) the user may need to reset the terminal state. If commands do not seem to be accepted at the shell prompt, try Control-J "stty sane" Control-J (use "reset" on Berkeley Unix). That should take the terminal out of "raw mode" if it was stuck there. 8. Remote host commands may time-out on lengthy activity: Using "remote host" to instruct the C-Kermit server to invoke Unix func- tions (like "make") that might take a long time to produce output can cause timeout conditions. UNIX KERMIT Page 148 9. XOFF deadlocks: When connecting back to C-Kermit after a trans- action, or after finishing the server, it may be necessary to type a Control-Q to clear up an XOFF deadlock. There's not much the program can do about this... 10. PC/IX Login Scripts -- Unfound Bug: Though login scripts appear to work properly on most processors, in the case of the PC/XT with PC/IX, it appears that longer scripts need to be broken up into shorter scripts (invoked sequentially from the take file). This is because the portion of the script handler which checks if an opera- tion timed out seems to leave the processor in a strange state (i.e. hung). 9.11. How to Build C-Kermit for a Unix System The C-Kermit files, as distributed from Columbia, all begin with the prefix "ck". You should make a directory for these files and then cd to it. A makefile is provided to build C-Kermit for various Unix systems (there are separate makefiles for VMS and the Macintosh). As distributed, the makefile has the name "ckuker.mak". You should rename it to "makefile" and then type "make xxx", where xxx is the symbol for your system, for instance "make bsd" to make C-Kermit for 4.x BSD Unix. The result will be a program called "wermit". You should test this to make sure it works; if it does, then you can rename it to "kermit" and install it for general use. See the makefile for a list of the systems supported and the corresponding "make" arguments. 9.12. Adapting C-Kermit to Other Systems C-Kermit is designed for portability. The level of portability is indicated in parentheses after the module name: "C" means any system that has a C compiler that conforms to the description in "The C Programming Language" by Kernighan & Ritchie (Prentice-Hall, 1978). "Cf" is like "C", but also requires "standard" features like printf and fprintf, argument passing via argv/argc, and so on, as described in Kernighan & Ritchie. "Unix" means the module should be useful un- der any Unix implementation; it requires features such as fork() and pipes. Anything else means that the module is particular to the indicated system. C-Kermit file names are of the form: ck. where the part before the dot is no more than 6 characters long, the part after the dot no more than 3 characters long, and: is the file type: c: C language source h: Header file for C language source w: Wart preprocessor source, converted by Wart (or Lex) to a C program nr: Nroff/Troff text formatter source mss: Scribe text formatter source doc: Documentation hlp: Help text bld: Instructions for building the program bwr: A "beware" file - list of known bugs UNIX KERMIT Page 149 upd: Program update log mak: Makefile is a single character to tell what system the file applies to: a: Descriptive material, documentation c: All systems with C compilers d: MS-DOS m: Macintosh u: Unix v: VAX/VMS w: Wart is mnemonic (up to 3 characters) for what's in the file: aaa: A "read-me" file, like this one cmd: Command parsing con: Connect command deb: Debug/Transaction Log formats, Typedefs dia: Modem/Dialer control fio: System-depdendent File I/O fns: Protocol support functions fn2: More protocol support functions ker: General C-Kermit definitions, information, documentation mai: Main program pro: Protocol scr: Script command tio: System-dependent terminal i/o & control and interrupt handing usr: User interface us2: More user interface us3: Still more user interface Examples: ckufio.c File i/o for Unix ckmtio.c Terminal i/o for Macintosh ckuker.mss Scribe source for for Kermit User Guide chapter ckuker.nr Nroff source file for Unix C-Kermit man page The following material discusses each of the C-Kermit modules briefly. ckcmai.c, ckcker.h, ckcdeb.h (Cf): This is the main program. It contains declarations for global variables and a small amount of code to initialize some variables and invoke the com- mand parser. In its distributed form, it assumes that command line ar- guments are passed to it via argc and argv. Since this portion of code is only several lines long, it should be easy to replace for systems that have different styles of user interaction. The header files define symbols and macros used by the various modules of C-Kermit. ckcdeb.h is the only header file that is included by all the C-Kermit modules, so it contains not only the debug format definitions, but also any compiler-dependent typedefs. ckwart.c (Cf), ckcpro.w (C): The ckcpro module embodies the Kermit protocol state table and the code to accomplish state switching. It is written in "wart", a language which may UNIX KERMIT Page 150 be regarded as a subset of the Unix "lex" lexical analyzer generator. Wart implements enough of lex to allow the ckprot module to function. Lex it- self was not used because it is proprietary. The protocol module ckcpro.w is read by wart, and a system-independent C program is produced. The syn- tax of a Wart program is illustrated by ckcpro.w, and is described in ckwart.doc. ckcfns.c (C): The module contains all the Kermit protocol support functions -- packet formation, encoding, decoding, block check calculation, filename and data conversion, protocol parameter negotiation, and high-level interaction with the communication line and file system. To accommodate small systems, this module has been split into two -- ckcfns.c and ckcfn2.c. ckutio.c: This module contains the system-dependent primitives for communication line i/o, timers, and interrupts for the various versions of Unix. Certain im- portant variables are defined in this module, which determine whether C-Kermit is by default remote or local, what the default communication device is, and so forth. The tio module maintains its own private database of file descriptors and modes for the console terminal and the file trans- fer communication line so that other modules (like ckcfns or the terminal connect module) need not be concerned with them. The variations among Unix implementations with respect to terminal control and timers are accom- modated via conditional compilation. ckufio.c: This module contains system-dependent primitives for file i/o, wildcard (meta character) expansion, file existence and access checking, and system command execution for the various versions of Unix. It maintains an inter- nal database of i/o "channels" (file pointers in this case) for the files C-Kermit cares about -- the input file (the file which is being sent), the output file (the file being received), the various logs, the screen, and so forth. This module varies little among Unix implementations except for the wildcard expansion code; the directory structure of 4.2bsd Unix is dif- ferent from that of other Unix systems. Again, variation among Unix sys- tems is selected using conditional compilation. ckuusr.h, ckuusr.c, ckuus2.c, ckuus3.c (Unix): This is the "user interface" for C-Kermit. It includes the command parser, the screen output functions, and console input functions. The command par- ser comes in two pieces -- the traditional Unix command line decoder (which is quite small and compact), and the interactive keyword parser (which is rather large). This module is fully replacable; its interface to the other modules is very simple, and is explained at the beginning of the source file. The ckuusr module also includes code to execute any commands directly which don't require the Kermit protocol -- local file management, etc. The module is rated "Unix" because it makes occasional use of the system() function. Note that while ckuusr is logically one module, it has been split up into three C source files, plus a header file for the symbols they share in com- mon. This is to accommodate small systems that cannot handle big modules. ckuusr.c has the command line and top-level interactive command parser; ckuus2.c has the help command and strings; ckuus3 has the set and remote commands along with the logging, screen, and "interrupt" functions. UNIX KERMIT Page 151 ckucmd.c, ckucmd.h (Cf): This is an interactive command parsing package developed for C-Kermit. It is written portably enough to be usable on any system that has a C compiler that supports functions like printf. The file name parsing functions depend upon primitives defined in the fio module; if these primitives can- not be supplied for a certain system, then the filename parsing functions can be deleted, and the package will still be useful for parsing keywords, numbers, arbitrary text strings, and so forth. The style of interaction is the same as that found on the DECSYSTEM-20. ckucon.c (Unix): This is the connect module. As supplied, it should operate in any Unix en- vironment, or any C-based environment that provides the fork() function. The module requires access to global variables that specify line speed, parity, duplex, flow control, etc, and invokes functions from the tio module to accomplish the desired settings and input/output, and functions from the fio module to perform session logging. No terminal emulation is performed, but since standard i/o is used for the console, this may be piped through a terminal emulation filter. The ckucon function may be en- tirely replaced, so long as the global settings are honored by its replace- ment. PC implementations of C-Kermit may require the ck?con module to do screen control, escape sequence interpretation, etc, and may also wish to write special code to get the best possible performance. ckudia.c (Unix): This is the dialer module. As supplied, it handles Hayes, Ventel, Penril, Racal-Vadic, and several other modems. ckuscr.c (Unix): This is the login script module. As supplied, it handles uucp-style scripts. Moving C-Kermit to a new system entails: 1. Creating a new ck?tio module in C, assembler, or whatever language is most appropriate for system programming on the new system. If the system is Unix-like, then support may be added within the ckutio.c module itself using conditional compilation. 2. Creating a new ck?fio module, as above. 3. If the system is not Unix-like, then a new ckuusr module may be re- quired, as well as a different invocation of it from ckcmai. 4. If the distributed connect module doesn't work or performs poorly, then it may be replaced. For instance, interrupt-driven i/o may be required, especially if the system doesn't have forks. Those who favor a different style of user/program interaction from that provided in ckuusr.c may replace the entire module, for instance with one that provides a mouse/window/icon environment, a menu/function-key environment, etc. A few guidelines should be followed to maintain portability: - Keep variable and function names to 6 characters or less. Don't use identifiers that are distinguished from one another only by al- UNIX KERMIT Page 152 phabetic case. - Keep modules small. For instance, on a PDP-11 it is necessary to keep the code segment of each module below 8K in order to allow the segment mapping to occur which is necessary to run programs larger than 64K on a non-I-and-D-space machine. - Keep strings short; many compilers have restrictive maximum lengths; 128 is the smallest maximum string constant length we've encountered so far. - Keep (f,s)printf formats short. If these exceed some compiler de- pendent maximum (say, 128) memory will be overwritten and the program will probably core dump. - Do not introduce system dependencies into ckcpro.w or ckcfn*.c. - If a variable is a character, declare as CHAR, not int, to prevent the various sign extension and byte swapping foulups that occur when characters are placed in integer variables. - Remember that different systems may use different length words for different things. Don't assume an integer can be used as a pointer, etc. - Don't declare static functions; these can wreak havoc with systems that do segment mapping. - In conditional compilations expressions, use #ifdef and #ifndef and not #if, which is not supported by some compilers. Also, don't use any operators in these expressions; many compilers will fail to un- derstand expressions like #ifdef FOO | BAR. - Don't define multiline macros. In general, remember that this program will have to be compilable by old com- pilers and runnable on small systems. MACINTOSH KERMIT Page 153 10. MACINTOSH KERMIT Program: Bill Catchings, Bill Schilit, Frank da Cruz (Columbia University), Davide Cervone, University of Rochester Language: C (SUMACC) Documentation: Frank da Cruz, Bill Schilit Version: 0.8(34) Date: March, 1986 Macintosh Kermit, or "MacKermit", is an implemtation of the Kermit file trans- fer protocol for the Apple Macintosh (and Macintosh-XL) computer, developed at Columbia University, based on C-Kermit (which also forms the nucleus of Unix Kermit). MacKermit Capabilities At A Glance: Local operation: Yes Remote operation: Yes (server mode only) Login scripts: No Transfer text files: Yes Transfer binary files: Yes Wildcard send: No File transfer interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Terminal emulation: Yes (VT100,VT102) Communication settings: Yes Transmit BREAK: Yes Support for dialout modems: No IBM mainframe communication: Yes Transaction logging: No Session logging: No Debug logging: No Packet logging: No Act as server: Yes Talk to server: Yes Advanced server functions: No Local file management: Yes Command/Init files: Yes File attributes packets: No Command macros: No Raw file transmit: No The main differences between MacKermit and other Kermit programs are: - In MacKermit you are always connected via a terminal emulator (VT102). - MacKermit commands are issued by means of pull-down menus that over- lay your terminal session. MACINTOSH KERMIT Page 154 The major menus are File, Settings, Remote, and Transfer. The File menu in- vokes Kermit's file transfer functions, allows settings to be saved and res- tored, and like most Macintosh applications, includes a "quit" selection for leaving the program. The Settings menu provides dialog boxes for file, communications, and protocol settings. The Remote menu has the commands that can be sent to Kermit servers, as well as an option to turn Macintosh Kermit itself into a server. The Transfer menu gives you a standard Macintosh file box, allowing you to transfer directly to the selected application. 10.1. The Macintosh File System The Macintosh file system consists of one or more disks, each disk containing files. All files on a disk must have a unique name. Files may be collected together into "folders", but folders are not analogous to directories on other file systems, and no two folders on the same disk may contain files of the same name. Macintosh file names may contain practically any printable characters, including space and punctuation -- but colon (":") should be avoided because it is used in device names. 10.2. File Transfer Glossary: - Mode - Text or Binary. Binary means the data is sent or stored with- out modification. Text means that every carriage return character (CR) in a Macintosh file is translated to a carriage-return-linefeed (CRLF) sequence when sending, and every CRLF in an incoming file is turned into a CR when stored on the Mac disk. A text file is produced when you save a file from MacWrite using the "text only" op- tion; text files are not associated with any particular Macintosh ap- plication and can be sent in a useful fashion to other kinds of com- puters. - Fork - Data or Resource. Macintosh files may have two "forks". The data fork contains data for an application; the resource fork con- tains icons, strings, dialog boxes, and so forth. For instance, a MacWrite document contains text and formatting information in the data fork, and fonts in the resource fork. For applications, the ex- ecutable code is stored in the resource fork. Macintosh Kermit supports the standard Kermit commands for transferring files -- Send, Receive, and Get. Invocation of any of these commands produces a MacKermit file dialog box in which you specify the file name, the mode, and the fork. Defaults are determined from the selected file or taken from the current file settings, described below. When you select the Send command, you get a MacKermit file open box, which in- cludes the standard Macintosh dialog items -- a file list, Disk and Eject but- tons, etc. You can only send one file at a time, by clicking on its name in the file list. Clicking the Disk button will switch the file list to another physical disk. If desired, you can type an alternate name to send the file un- der. When you select a file, MacKermit examines its type; if the type is APPL, MACINTOSH KERMIT Page 155 then MacKermit expects to send the resource fork in binary mode, otherwise the data fork in text mode. The Mode and Fork radio buttons will display these choices; you may change them before clicking the Send button. You can receive or get multiple files, providing the opposite Kermit is capable of sending multiple files in a single transaction (most are). As files arrive, they will be decoded according to the current mode (text or binary), and stored in the default fork (data or resource) under either the name they arrive with (overwriting existing files of the same names) or under new unique names (when name conflicts occur), according to the current default for name collisions. You may also elect to perform an "attended" receive, in which you have an op- portunity to override all file defaults on a per-file basis. But this option must be used with caution -- if you take too long (more than about a minute) to execute an incoming file's dialog box, the opposite Kermit could time out and terminate the transaction. The folder for new files is the same as the location of the settings file, or if no settings file was used then the new files appear on the desktop. If you are transferring a lot of files and want to keep them together, create a folder, drag the settings file into it, and double click on the settings file; all created files will appear in that folder. File transfers can be cancelled by clicking on the Cancel File or Cancel Group buttons. These will always work when sending. When receiving, they will work if the opposite Kermit honors this (optional) feature of the protocol. In any case, an "emergency exit" from any protocol operation can be taken at any time by typing "Command-." -- that is, hold down the Command (Fan, Cloverleaf) key and type period. 10.3. Remote Commands The Remote menu allows you to send commands to a Kermit server. The response from these commands (if any) is displayed in a special pop-up window. Responses to multiple Remote commands are separated by a dashed line. The response window can be scrolled, sized, and positioned, and can be hidden by clicking the menu item "Hide Response" or the window's go-away box; all text remains intact and will be appended to the next time you do a Remote command; it can also be brought to the foreground by clicking the Show Response menu item. Note that typein to the terminal emulator will not take effect when the response window -- or any other window -- is up front. If the response window gets too full (i.e. fills up the free memory available to the MacKermit application), the program will probably bomb. If the remote Kermit server is in binary mode, its responses to Remote commands may look strange. For instance, a Unix Kermit server in binary mode will send lines of text separated by only linefeeds, rather than CRLFs. A Remote command can be cancelled by taking the Emergency Exit (Command-.). MACINTOSH KERMIT Page 156 10.4. Settings You can change File, Communications, and Protocol settings by using the Set- tings pull-down menu. You can save and restore these settings by invoking the appropriate selection in the File menu. If the bundle bit has been correctly set on your version of MacKermit you can double-click on the resulting document to start MacKermit with those settings. The File settings establish the defaults for file transfer: - Mode: text or binary. Used for received files only. When sending, MacKermit tries to figure out an appropriate mode for the file being sent (but then lets you override it the Send File dialog). - Fork: which fork -- data or resource -- to send, or to store an in- coming file into. - Naming: Whether incoming files should supersede existing files of the same name, or a new unique name should be assigned to them. If the latter, the new name is formed by adding a dot and a number to the end. For instance, if a file called FOO exists and a file called FOO arrives, MacKermit will store the arriving file as FOO.1; if FOO.1 exists, then FOO.2, etc. - Attended versus Unattended operation for incoming files. The Communications settings allow you to set the baud rate (anywhere between 300 baud and 57.6K baud), parity (odd, even, mark, space, or none), and duplex (full - remote echo, half - local echo). The Protocol settings allow you to set packet parameters for both incoming and outbound packets. These include the block check type (1 or 2 character check- sum, 3-character 16-bit CRC-CCITT), line turnaround handshake character (for file transfer with half duplex systems), packet start and end characters, pad- ding, packet length, timeout interval, and so forth (Refer to Kermit User Guide). Characters are specified by entering their ASCII value in decimal, e.g. 1 for Control-A, 13 for Control-M (Carriage Return), etc. 10.5. Terminal Emulation MacKermit provides a subset of the features of the DEC VT102 terminal; the VT102 is a VT100 with line and character insert/delete functions added. The functions provided are sufficient to allow MacKermit to act as a terminal for EMACS as it exists on the DEC-20, VAX (CCA EMACS on VMS or UNIX), and for most host-resident display-oriented applications that expect to do cursor position- ing and editing on the VT100 screen. MacKermit does not currently support the following VT100/102 functions: - double height or double width lines - smooth scrolling - 132 columns - Interpretation of multiple parameters in a single escape sequence - etc (this is not an exhaustive list) MACINTOSH KERMIT Page 157 The keyboard is set up by default as follows: The COMMAND (Fan, Cloverleaf) key is used as the Control key. The CAPS LOCK key forces all alphabetic characters to upper case, and causes keys on the numeric keypad to send VT100 keypad es- cape sequences. The OPTION key is "Control-Meta" (explained below). The ter- minal emulator sends ESC (escape) when the "`" key is pressed unshifted. The character "`" can be sent by typing Control (Command) and the same key. The Backspace key sends a Delete (Rubout) and Control-Backspace sends a Backspace. The main keypad Enter key sends a "short" (250ms) BREAK signal. The Mac+ does not have a main keypad Enter key, so the BREAK function must be reassigned to another key. Use CKMKEY (see below) to do this. The short break is F126 (function number 126) and long break is F127. MacKermit (V0.8 and later) comes with a separate key configuration program, CKMKEY, which lets you change the behavior of the keys, define function keys, and so forth. CKMKEY is described in detail below. MacKermit (V0.8(43A) and later) includes a mouse-controlled cursor postioning feature for use during terminal emulation. When the mouse button is pressed while the Option and Command keys are held down, the program acts as if you typed the keypad arrow keys to move the terminal cursor to where the mouse cur- sor is. You must have already defined the keypad arrow keys to send the ap- propriate character sequences for your host application. The Catch-22 here is that if you don't have a keypad, there's no way for you to define the keypad keys using MacKermit's keyboard configurator. In that case, you can use the VT100 startup file provided with MacKermit, which assigns the normal VT100 ar- row key sequences to the keypad arrow keys, and therefore also to the mouse-cursor feature. MacKermit honors your parity communications setting by using built-in functions of the Mac's serial i/o chip. Unfortunately, the chip has an unpleasant quirk -- arriving characters that do not have the specified parity are discarded rather than passed to the requesting application. Thus, if you are connected as a terminal using MacKermit to a device that requires, say, odd parity on characters sent to it, but does not put odd parity on characters it sends to you, then many incoming characters will not appear on your screen. To allow useful coexistence of desk accessories and Kermit, the terminal emula- tion may be dragged using the drag bar. A desk accessory that overlays the Kermit window can be clicked upon to move it behind the Kermit window, and then the Kermit window can be dragged to reveal the hidden desk accessory so that it can be restored to the foreground. The same thing can be done with Kermit's own remote response window. Note that Kermit's terminal emulation window does not accept input when any other window is in the foreground. The following features are missing from the MacKermit terminal emulator, and may be added in subsequent releases: - capturing text from the screen (e.g. cutting to clipboard, saving off top) - screen rollback, sizing - modem or dialer control - login scripts - transmission of raw text to host (e.g. pasting to screen) - printer support MacKermit does not use XON/XOFF flow control during terminal emulation or file MACINTOSH KERMIT Page 158 transfer. The terminal emulator can normally keep up at 9600 baud, but after several continuous scrolling screens at this speed, some characters may be lost. In the present version, when running at high baud rates keep your ter- minal in page mode, or use "more", or view text with a non-scrolling screen editor. Also, don't drag the terminal emulation window while characters are arriving; if you do, the characters will be lost and the display will become confused. 10.6. Installation MacKermit is distributed in source form for building on Unix (or VMS/Eunice) systems that have the Stanford SUMACC Macintosh cross-development tools, in .HQX "binhex" form, and sometimes also as a binary resource file. Those who want to work from the source are referred to the file CKMKER.BLD for instruc- tions. If you have the binary resource file available (its name will be CKMKER.RSRC, ckmker.rsrc, CKMKER.RSR, ckmker.rsr, or some variation on these, depending on what system it's stored on and how it got there), AND if you have "MacPut" on your system and MacTerminal on your Mac, AND if you have an 8-bit-wide (no parity) data path between your Mac and your system, use MacPut to download the binary resource file to MacTerminal's XMODEM option on your Mac. After doing this you must use SetFile on the Mac to set the author to KERM, the type to APPL, and turn on the bundle bit. For CKMKEY, the author should be KERK. If you have an earlier release of Columbia MacKermit, you may use Kermit in place of MacTerminal and MacPut. If you don't have the binary resource file available, you can download the CKMKER.HQX file in the same manner, then run "binhex" (version 4) on it. 10.7. CKMKEY - Macintosh Kermit's Keyboard Configurator This describes CKMKEY V0.8(0), May 1985. The version number of CKMKEY indicates compatability with the like version of CKMKER -- Macintosh Kermit, referred to simply as "Kermit" from now on. Edit numbers (within parentheses) may differ. If Kermit is used with a settings file containing a key configuration produced by an incompatible version of CKMKEY, then that configuration will be ignored. 10.7.1. What is CKMKEY? CKMKEY is a keyboard configurator program for use with Macintosh Kermit (versions 0.8 and greater). CKMKEY allows: - Redefinitions of keys - Definitions of multicharacter function keys - Selection of long and short BREAK keys CKMKEY is a separate program from Kermit. It may be thought of as an editor MACINTOSH KERMIT Page 159 for Kermit's terminal emulator key definition resource, which is kept in a Ker- mit settings file. Before you can use CKMKEY, you must already have used Ker- mit to create a settings file to operate on. The reason CKMKEY is separate from Kermit is that there is not enough room in the memory of a 128K Macintosh to hold a program that can do both. CKMKEY dis- plays and changes key settings, Kermit uses them. Once you have started Kermit with a given set of key definitions, there is no way to examine or change them. Some familiarity with the ASCII alphabet is assumed in the following discus- sion. 10.7.2. Modifier vs Normal Keys The Macintosh keyboard is composed of normal keys and modifier keys. Modifier keys are SHIFT, CAPS LOCK, OPTION, and COMMAND (also known as APPLE, CLOVER, or FAN). Only one normal key can be selected at a time, but one or more modifier keys can be depressed along with it. 10.7.3. Key Maps When a key on the keyboard or numeric keypad is depressed the result is a scan code -- a number between 0 and 127 (see Inside Mac Event Manager for details if you're interested). A table indexed by scan code resulting in the character to be displayed or transmitted will be referred to as a "keymap" or "key mapping." On the standard Mac many keymaps exist -- the modifier keys (such as SHIFT) specify which keymap is selected. For example, when no modifer keys are depressed the keymap contains the lowercase alphabet, numbers and some punctua- tion. The keymap in use when the SHIFT modifer is depressed contains the capi- tal letters and special characters. All in all it is possible to select 16 different keymaps by depressing from zero to four modifier keys. Normally however, 6 or so distinct keymaps will suffice. CKMKEY allows you to redefine 6 keymaps: shifted and unshifted combinations of keymaps named "normal", "capslock", and "control". These keymaps are predefined with the expected values -- the control map is preloaded with con- trol codes, the capslock preloaded with the unmodifed keymap but with all let- ters uppercase. In this document modifier keys are written in capital letters and key map names are written in lowercase. SHIFT, CAPS LOCK, COMMAND, and OPTION are modifier keys, "normal" "capslock" and "control" are key maps internal to CKMKER. Since one of the major functions of CKMKEY is to change maps invoked by modifier keys, it is important to keep this distinction in mind. MACINTOSH KERMIT Page 160 10.7.4. What's in CKMKEY's Keymaps A keymap is a list of 128 numbers. Which keymap is selected depends upon which modifier keys are depressed, and the entry within the key map is determined by the scan code. A keymap entry is an 8-bit quantity: if the high order bit is 0, then the entry is the 7-bit ASCII character to be transmitted through the serial port; if the high bit is 1, then the remaining 7 bits are an index into the function-key table. Notice that only single 7-bit values can be directly translated through the CKMKEY keymap. If you want a single key to transmit multiple characters, then you can designate that key to be a "function key", and the key map will contain an indirect reference to the function-key table. If you want a key to transmit an 8-bit value, assign the "meta" operation to one of the modifier keys and use the meta key together with the desired key (see below). Functions are numbered 0-127 with the highest few being reserved for special use. Currently functions 126 and 127 send a short 250 millisecond BREAK signal and a long 3.5 second BREAK respectively. In the future more special functions may be allocated so (since it is arbitrary anyway) please use low numbered functions when defining your own. 10.7.5. Menus CKMKEY has two menus, File and Set. First you must use the File menu to select and open a Macintosh Kermit settings file, which in turn has been created using the Kermit Save Settings option from its own File menu. Then use the Set menu to establish or alter key definitions, then use the File menu again to save the settings file back for Kermit. A variety of Kermit settings files can be kept, each with its own collection of settings and key definitions; Kermit can be started with the desired settings by double clicking on one of these settings files from the Macintosh desktop. Menus consist of options. If an option is followed by an ellipsis (three dots...) then clicking it will produce a dialog box of some kind; otherwise, clicking it causes the indicated action to be performed immediately. If an op- tion is dimmed then it is not available for some reason -- for instance, you can't set any keys until you open a settings file. 10.7.6. MENU: Set The Set menu includes dialogs for setting keys, defining functions, and reas- signing modifier keys. 10.7.6.1. DIALOG: Set Modifer Keys Background: Skip ahead to the next section if you already know about things like SHIFT, CAPS LOCK, CONTROL, and META. On a typewriter the only modifier key is SHIFT. Typing a character with no modifier key depressed selects a lowercase letter or the character printed on MACINTOSH KERMIT Page 161 the lower face of the keytop (say, the digit "4"). Typing a character with SHIFT depressed selects an uppercase letter or the character printed on the up- per face of the keytop (say, a dollar sign). Some keyboards also have a SHIFT LOCK key, which stays down once pressed and pops up the next time it's pressed; its operation is equivalent to holding down SHIFT. And some keyboards have a CAPS lock key which operates like SHIFT LOCK, but only upon letters. Computer terminals also have a modifier key called CONTROL (or CTRL). Its function is a little less obvious: it is intended to produce one of the 33 characters in the "control range" of the ASCII alphabet. Control characters are not graphic -- they are intended for use as format effectors (like carriage return, formfeed, tab, backspace), for transmission control, or for device con- trol. The remaining 95 characters -- letters, digits, and punctuation -- are the graphic characters. When a character is typed with the CONTROL modifier pressed, its "control equivalent" is transmitted. By convention, the control equivalent of A is Control-A, B is Control-B, etc, and there are also seven special control characters generally associated with punctuation characters or special keys. For the "alphabetic" control characters Control-A through Control-Z, SHIFT or CAPS LOCK modifiers are ignored; for the others, operation varies from terminal to terminal. The SHIFT and CONTROL modifiers allow all 128 ASCII characters to be sent from a normal typewriter-like keyboard that has about 50 keys. However, certain host-resident computer applications -- notably the full screen text editor EMACS and its descendents -- can be used to greater advantage with a 256 character alphabet (EMACS responds to single-character commands, and the more characters a terminal can send, the more commands are directly available). For this purpose, some terminals also provide a META modifier key. This key simply causes the high-order ("8th") bit of the selected ASCII value to be set to 1 upon transmission. META characters can only be transmitted when the communica- tion path allows all 8 bits to pass transparently; when this is not possible, software like EMACS allows a sequence of two 7-bit ASCII characters to represent a single meta character. The advantage of having a real META modifier key is that it can be held down while the actual key is struck repeatedly or even autorepeats, whereas a use of a "meta prefix" requires much more typing. To illustrate, suppose META-F is the command to go forward one word. If you want to execute this operation repeatedly, just hold down META and F and let it autorepeat. If you don't have a META key, then you have to use a "meta prefix" character (usually escape), and to enter META-F repeatedly in this case, you'd have to type FFF...etc. Macintosh Kermit Modifier Keys: You can define the modifier key to keymap correspondence in CKMKEY by selecting the "Modifer Keys..." menu item under SET, or by double clicking on a modifier key while in the SET KEYS dialog. The SET MODIFIERS dialog lets you define what map OPTION, CAPS LOCK and COMMAND refer to. Notice that SHIFT is missing -- SHIFT always references the shifted equivalents to the normal, control and caps lock maps. The dialog is layed out in columns with the three modifier keys as column head- ings and the three map names below. Also under each column is a "pseudo" key map for "meta." Meta is not a map, but an operation: it augments the value being transmitted MACINTOSH KERMIT Page 162 after it has been read from its map. Meta can either be set to send a prefix string before the character or to turn the high order (8th) bit on in the transmitted character. The default prefix for meta is set to be 033 (escape). If a meta modifier key is depressed and the key results in a function reference then no modification occurs; functions are not "metized". However, functions can be defined to include 8-bit values. Notice that meta can be set in conjunction with a key map. Since meta is an operation as described above there is no ambiguity. Consider for example set- ting OPTION to reference the "control" map and selecting "meta" for this modifier key as well. The result is a control-meta key. CAUTION: If you have used Kermit's communications settings menu to select any parity other than "none", then any high order bits that may be set by CKMKER's key mapping will be superseded when Kermit applies the selected parity to outbound characters. The SET MODIFIER KEYS dialog also lets you select your meta preferences: whether you want to use the 8th bit toggled on, or a prefix string. The prefix string is entered in the same manner as a function definition (backslash fol- lowed by 3 octal digits for non-printable characters, see below). Note that it is possible to cause ambiguities when selecting and using modifier keys. For example say you set OPTION to refer to the control map, and you set CAPS LOCK to refer to the caps map; at this point if you hold both OPTION and CAPS LOCK down it is unclear which map you want your character to come from. To try to prevent this type of ambiguity the SET KEY dialog will beep when you are holding down or mousing an ambigous set of modifier keys. The Kermit code itself references maps in this precendence: if a control map modifier is depressed then use control map, else if a capslock modifier is depressed use capslock, otherwise use the normal map. A sample modifier key configuration is shown in Figure 10-1. ------------------------------------------------------------------------- OPTION COMMAND CAPS LOCK o Normal * Normal o Normal * Control o Control * Control o Caps o Caps o Caps [X] Meta [X] Meta [ ] Meta Figure 10-1: Macintosh Kermit Modifier Key Dialog ------------------------------------------------------------------------- Here the CAPS LOCK key is used to reference "control", the COMMAND key to do the "meta" operation, and OPTION is "control-meta". Holding down COMMAND and CAPS LOCK together will also result in control-meta. MACINTOSH KERMIT Page 163 10.7.6.2. DIALOG: Set Function Definitions Background: Skip to next section if you know what function keys are. Many popular terminals have "function keys" in addition to the alpabetic, numeric, punctuation, and modifier keys described above. Function keys are usually labeled F0, F1, F2, ..., or PF1, PF2, ... On some terminals, like the DEC VT100, the function keys send predefined sequences of characters -- for in- stance PF1 sends three characters: ESCAPE (ASCII 033), followed by "O", and "P". On others, the function keys may have arbitrary strings assigned to them. For instance, if you find yourself typing "Aaaarrrgggghhh!!! Sigh..." a lot, you can assign this string to function key F1, and then pressing the F1 key will cause this entire character string to be transmitted. Macintosh Kermit Function Keys: The Macintosh has no physical function keys -- no keys are marked F0, F1, F2, etc. However, any key (modified by any combination of modifier keys) may be designated as a "soft" function key. Selecting "Function Definitions..." from the SET menu brings you to the SET FUNCTIONS dialog (it would be nice if you could double click on a function key in the SET KEYS dialog but that is not yet available). Use SET FUNCTIONS to declare a function definition string. Scroll through the function definition list and select a function to define, preferably starting with F0, though this is not required (high numbered functions are reserved for special uses). Type in the function definition; non printable characters must be entered with a backslash ("\") followed by exactly (yes exactly) three octal characters representing the ASCII value, for instance "\015" for carriage return. A backslash itself is entered as "\134". The function definition has to fit in the box. Having defined a function, you must use SET KEYS to actually associate it with a key. Note that it is possible to associate a function with more than one key. 10.7.6.3. DIALOG: Set Keys Selecting the "Keys..." menu item under SET initiates the SET KEYS dialog for redefining individual keys. SET KEYS displays a picture of the keyboard. You can either hold down the modifier and key you wish to define or click on the displayed picture with the mouse (double clicking on one of the modifier keys brings up the SET MODIFIER KEYS dialog). Once a key is selected, it and any modifiers are highlighted, the name of the key and its value are displayed in the lower portion of the dialog. You may enter the new value in the little box by selecting the box with the mouse and then typing a DECIMAL (yes decimal) number from 0 to 127. Then you should click on either SET KEY or else SET FUNCTION KEY. Clicking on SET KEY means that the key should transmit the ASCII character corresponding to the given value (subject to modification by the meta key); clicking SET FUNC- TION KEY means the number you entered in the box is a function number and that MACINTOSH KERMIT Page 164 the key should transmit the character string associated with that function. SET KEYS does not display a picture of the numeric keypad, but may be used with the keypad anyway -- just select the desired key by pressing it and then define it as above. 10.7.7. MENU: File The File menu must be used to Open a Kermit settings file before CKMKEY will allow you do perform any other operations. You may also Quit from CKMKEY through the File menu, and you can save your work. The Save option allows you to save the settings file back under its own name, replacing the previous copy. If you need to make copies of settings files, you can use Kermit itself to save them under different names, or else you can use the Finder. There is also a Decompile option, that is of use only to programmers working on Macintosh Kermit -- it decompiles the key definition resource into a form that can be included in a C program. 10.7.8. CKMKEY Known Limitations, Restrictions, Bugs - There is no picture of the numeric keypad in Set Keys. - In Set Keys, when you strike a key on the numeric keypad, its name is not displayed. You can still make assignments to the key. - There is no way to define a key from the numeric keypad unless you actually have a numeric keypad. - You can't save from CKMKEY under a different name. Use the Finder or Kermit to do that. - You must use decimal numbers in the SET KEY dialog, and backslash followed by 3 octal digits in function definitions, which can be con- fusing. - You may have problems on a 128K mac if you define many long func- tions. - CKMKEY doesn't deal with write protected diskettes very well. 10.7.9. Unlocking CAPS LOCK (Adapted from directions posted by David Chase on INFO-MAC@SUMEX-AIM, Friday 14 December 1984. Follow these instructions at your own risk. Not the authors, nor David Chase, nor Columbia University, nor Rice University provide any warranty, nor acknowledge any liability or respon- sibility for damage, injury, inconvenience, or loss of Apple or other service warranty sufferred as a result of the publication of these directions.) A major impediment to using the Macintosh as a terminal is that the CAPS LOCK key is where you would normally expect to find the CONTROL key. A key redefinition package, such as CKMKEY, can assign the CONTROL function to the MACINTOSH KERMIT Page 165 COMMAND or OPTION keys but these keys are not easy to reach. CONTROL can also be assigned to the CAPS LOCK key using software, but the CAPS LOCK key includes a mechanical locking device. The following directions tell how to remove the locking device so that the CAPS LOCK key will go up and down like the other keys. PROCEED AT YOUR OWN RISK. Tools you'll need: - Phillips screwdriver for screws on bottom of the keyboard. - Solder sucker/wick. - Soldering iron. - Small prying tools (jewelers screwdrivers, small knife blade, etc). - Tweezers/small needlenose pliers. - Some paper clips or straight pins. Now follow these steps: 1. Remove the five screws. The keyboard should fall into three pieces. 2. GENTLY pry off the Caps Lock keycap. This takes a little patience. 3. Remove the restoring spring so it doesn't get in the way. 4. Locate the two connections to the Caps Lock key on the back of the PC board, and remove all solder from them using wick or sucker. Be careful not to overheat the solder pads, since they can be damaged (come loose from the PC board). 5. Pry back the plastic locking clips holding the key in, and remove it. (All the keys are clipped into a metal frame. Removing the metal frame is not possible, since all the keys are soldered to the PC board, and clipped to the frame. The clips are located "north" and "south" of the key, where the number row is "north" and the space bar "south".) There are four clips holding the bottom of the key on; pry these back, and, WHILE HOLDING THE KEY BOTTOM UP, remove the bottom of the key. You may have to use some makeshift tools, like a couple of unbent paper clips, to hold the four clips open. 6. Two pieces should be ready to fall out; a small piece of PC-board-like material (about 7/16 by 3/32 inch, with two notches on one edge and a tiny hole in the center), and a tiny piece of wire (a small, beefy staple with short legs). Let them fall out. (It may help to toggle the key). These two pieces are the locking device, they should be removed and left out of the reassembly. 7. Replace the restoring spring, snap the key back into place, resolder the two leads, screw the keyboard back together, and replace the key cap. You may wish to experiment with the spring to reduce the key's springiness (this can be done with the keyboard assembled, though removing the cap is more difficult). For those who want to map the CAPS LOCK key to CTRL, but don't want to alter the keyboard as described in the manual, but still want to inhibit the locking function, the following suggestion is offered: Pry off the key using a small screwdriver. There is a spring whose end goes MACINTOSH KERMIT Page 166 through the plastic support. Stick a very small wad of paper or soft putty be- tween the tip and the bottom of the keyboard. This will prevent the key from depressing all the way and locking, but still allow contact of the key. Even- tually, the paper will work loose and you will need to find it and repeat the procedure. MS-DOS KERMIT Page 167 11. MS-DOS KERMIT Program: Daphne Tzoar and Jeff Damens (Columbia University), Joe R. Doupnik (Utah State University), James Harvey (Indiana/Purdue University), contributions by many others. Language: Microsoft Macro Assembler (MASM) Documentation: Frank da Cruz and Christine Gianone (Columbia University) Version: 2.29 Date: May 26, 1986 Kermit-MS Capabilities At A Glance: Local operation: Yes Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Y interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Terminal emulation: Yes Communication settings: Yes Transmit BREAK: Yes IBM mainframe communication: Yes Transaction logging: No Session logging: Yes Raw transmit: No Act as server: Yes Talk to server: Yes Advanced server functions: Yes Advanced commands for servers: Yes Local file management: Yes Command/init files: Yes Command macros: Yes Attribute packets: No Extended-length packets: No Sliding windows: No Kermit-MS is a program that implements the Kermit file transfer protocol for the IBM PC family, IBM compatibles, and several other machines using the Intel 8086 processor series (8088, 80286, etc) and operating system family (PC-DOS or MS-DOS, henceforth referred to collectively as MS-DOS or simply DOS). Kermit-MS version 2.29 runs in as little as 60K of memory (about 55K contiguous), but will occupy up to 100K, if it can be found, for extra screen rollback memory. It will also try to leave 24 Kbytes free for a second copy of COMMAND.COM which is needed for the SPACE command and others. Versions not using screen rollback memory will not require the additional space. On the IBM PC, Kermit-MS 2.29 performs almost complete emulation of the DEC VT-102 terminal at speeds up to 19,200 baud (lacking only smooth scrolling, 132 MS-DOS KERMIT Page 168 column mode, and ANSI printer control). Much of the speed is accomplished via direct writes to screen memory, but this is done in a "TopView" aware manner to allow successful operation in windowing environments like TopView, MS-Windows, and DesqView. Speed is also due to direct access of the serial port UART (8250) chip, with buffered, interrupt-driven receipt of characters and select- able XON/XOFF flow control. Full-speed 9600 baud operation is possible on 4.77Mhz systems without flow control, but flow control is required on these systems for 19,200 baud or higher rates. As of version 2.28, MS-DOS Kermit requires version 2.0 or later of DOS. Older versions of IBM PC Kermit are no longer distributed, but if you have version 2.27 or earlier, it can run under version 1.0 or 1.1 of PC-DOS. Kermit-MS 2.29 runs on a wide variety of MS-DOS systems, including the entire IBM PC family (the PC, XT, AT, PCjr, Portable PC, PC Convertible) and com- patibles (Compaq, Z150, etc), the DEC Rainbow, NEC APC, Sanyo MBC, Victor 9000, HP-110, HP-150, HP Portable Plus, and many others. This document 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-MS program itself. In system-specific areas like terminal emulation, most discussion focuses on the IBM PC version. It is assumed you are already familiar with the general ideas of Kermit file transfer. If you are not, con- sult the Kermit User Guide, or Kermit, A File Transfer Protocol, by Frank da Cruz, Digital Press (1986). 11.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 formats of the files themselves. 11.1.1. File Specifications MS-DOS file specifications (in version 2.0 or later of DOS) are of the form DEVICE:\PATHNAME\NAME.TYPE where the DEVICE is a single character identifier (for instance, 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) sur- rounded by reverse slashes, NAME is an identifier of up to 8 characters, and TYPE is an identifier of up to 3 characters in length. Device and pathname may be omitted. The first backslash in the pathname may be omitted if the specified path is relative to the current directory. In the path field, "." means the current directory, ".." means the parent directory. Some DOS im- plementations (like Wang) may use slash "/" rather than backslash as a direc- tory separator. Pathname is normally omitted, but can be specified in all Kermit-MS commands (as of version 2.29). Device and directory pathnames, when omitted, default to either the user's current disk and directory, or to the current directory search path as specified in the DOS PATH environment variable, depending on the context in which the file name appears. MS-DOS KERMIT Page 169 When this document says that a file is searched for "in the current path," it means that the PATH is searched first, and if the file is not found, then Kermit-MS looks on the current disk and directory. If the PATH environment variable is empty, Kermit looks only at the current disk and directory. NAME.TYPE is normally sufficient to specify a file, and only this information is sent along by Kermit-MS 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). When you type lowercase letters in filenames, they are converted automatically to uppercase. There are no imbedded or trailing spaces. Other characters may not be included; there is no mechanism for "quoting" otherwise illegal charac- ters in filenames. The fields of the file specification are set off from one another by the punctuation indicated above. The name field is the primary identifier for the file. The type, also called the extension or suffix, 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 be an executable program produced by loading FOO.OBJ, and so forth. .EXE and .COM are the normal suffixes for executable programs. 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 posi- tion, followed by zero or more characters. *.? All files whose types 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. Users of Kermit-MS should bear in mind that other (non-MS-DOS) systems may use different wildcard characters. For instance the DEC-20 uses "%" instead of "?" as the single character wildcard; when using Kermit-MS to request a wildcard file group from a Kermit-20 server, the DOS "?" must be replaced by the DEC-20 "%". MS-DOS KERMIT Page 170 11.1.2. File Formats MS-DOS systems store files as bulk collections of 8-bit bytes, with no par- ticular differences between text, program code, and binary files. ASCII text files consist of lines separated by carriage-return-linefeed sequences (CRLFs), which conforms exactly to the way Kermit represents text files during transmis- sion. Since a non-MS-DOS receiving system might need to make distinctions as to file type, you may need to use various SET functions on the remote system to inform it that the incoming file is of some particular (non-default) type, such as binary. In transmitting files between Kermit-MS programs, regardless of file contents, the receiving MS-DOS system is equally capable of processing text, code, and data, and in fact requires no knowledge of how the bytes in the file are to be used. Unlike most other Kermit programs, MS-DOS Kermit does not require a command like SET FILE TYPE BINARY to switch from text to binary file transfer. MS-DOS (unlike CP/M) is capable of pinpointing the end of file with precision by keeping a byte count in the directory, so one would expect no particular confusion in this regard. However, certain MS-DOS programs continue to use the CP/M convention of terminating a text file with a Control-Z character, and won't operate correctly unless this terminating byte is present. Therefore, you should be aware of a special SET EOF option for both incoming and outbound files, described later. Non-MS-DOS systems may well be confused by nonstandard ASCII files from Kermit-MS: - Files containing any of the 8-bit "extended ASCII" characters will probably need conversion (or translation) to 7-bit ASCII. - Files produced by word processing programs like Easywriter or Word Star may may contain special binary formatting codes, and could need conversion to conventional 7-bit ASCII format prior to transmission, using commonly available "exporter" programs. - Files created by word processors that store formatting data at the end of the file, after the Control-Z and before physical end, may re- quire special processing via SET EOF to strip the formatting data, lest they confuse non-MS-DOS recipients. - Spreadsheet or database files usually need special formatting to be meaningful to non-MS-DOS recipients (though they can be transmitted between MS-DOS systems with Kermit-MS). 11.2. Program Invocation Kermit-MS can be run interactively, from a batch file, or as an "external" DOS command. Commands consist of one or more fields, separated by "whitespace" -- one or more spaces or tabs. Upon initial startup, the program executes any commands found in the file MSKERMIT.INI in the current path. This initialization file may contain command macro definitions, communications settings for one or more ports, or any other Kermit-MS commands. Here is a sample MSKERMIT.INI file: MS-DOS KERMIT Page 171 comment -- MSKERMIT.INI, MS-DOS Kermit initialization file comment -- Don't overwrite my files! set warning on comment -- Define macros for the systems I use... define unix set local-echo off, set flow xon, set timer off def ibm set par odd, set loc on, set hands xon, set flo off, set tim on def modem set port 2, set baud 1200 comment -- Define a macro for quickly adapting to noisy connections... def noisy set block-check 3, set send packet-length 40, set retry 20 comment -- I always start out by connecting to my UNIX system... set port 1 set baud 4800 do unix connect Interactive Operation: To run Kermit-MS interactively, invoke the program from DOS command level by typing its name. When you see the command's prompt, Kermit-MS> you may type Kermit commands repeatedly until you are ready to exit the program, for example: A> A>kermit IBM PC Kermit-MS V2.29 Type ? for help Kermit-MS>send foo.* The files are sent. Kermit-MS>get bar.* The requested files are received. Kermit-MS>exit A> During interactive operation, you may edit the command you're currently typing using BACKSPACE to erase the character most recently typed, Ctrl-W to delete the most recent field, or Ctrl-U to delete the entire command. The editing characters may be used in any combination until the command is finally entered by typing RETURN (Carriage Return, Enter) or Ctrl-L. While typing commands, you may the help ("?") and keyword completion (ESC) features freely while typing Kermit-MS commands. A question mark typed at al- most any point in a command produces a brief description of what is expected or MS-DOS KERMIT Page 172 possible at that point (for this reason, Kermit-MS uses "#" for the single- character match wildcard in the first position of the local filenames and "?" thereafter, and ?-help is not available from within a filename). ESC typed at any point, except in a local filename, will cause the current field to be filled out if what you have typed so far is sufficient to identify it, and will leave you in position to type the next field (or to type a "?" to find out what the next field is); otherwise, the program will beep at you and wait for you to type further characters. Some Kermit-MS commands, like GET, SHOW KEY, SET KEY, may prompt for additional information on subsequent lines. If you have reached one of these prompts and then wish to cancel the command, you may type Control-C. Summary of Kermit-MS Command Editing Characters: SPACE Separates fields within the command. TAB Same as Space, and echoes as Space. You may also use Ctrl-I for Tab. BACKSPACE Deletes the character most recently typed. May be typed repeatedly to delete all the way back to the prompt. You may also use DELETE, RUBOUT, Ctrl-H, or equivalent keys. Ctrl-W Deletes the most recent "word", or field, on the command line. May be typed repeatedly. Ctrl-U Deletes the entire command line, back to the prompt. Ctrl-C Cancels the current command and returns to the "Kermit-MS>" prompt. ESC If enough characters have been supplied in the current keyword to identify it uniquely, supply the remainder of the field, and posi- tion to the next field of the command. Otherwise, sound a beep. ESC does not provide filename completion in version 2.29. ? Displays a brief message describing what may be typed in the cur- rent command field. Also, wildcard character for matching any single character in all but the first position of a filename. # Wildcard character for matching single characters in filenames. Equivalent to MS-DOS "?", but used in the first position of a filename only, so that "?" may be used to get help at the beginning of a filename field. RETURN Enters the command. On most keyboards, you may also use ENTER or Ctrl-M. Ctrl-L Clears the screen and enters the command. Liberal use of "?" allows you to feel your way through the commands and their fields. This feature is sometimes called "menu on demand" -- unlike systems that force you to negotiate menus at every turn, menu-on-demand provides help only when it is needed. MS-DOS KERMIT Page 173 Command Line Invocation: Kermit-MS may also be invoked with command line arguments from DOS command level, for instance: A>kermit send foo.bar or A>kermit set port 1, set baud 9600, connect In this case, help and completion are not available (because the program that provides them won't start running until after you type the entire command line), and Kermit-MS will exit back to DOS after completing the specified com- mand or commands. Therefore, when invoked with command line arguments, Kermit-MS will behave as if it were an external DOS command, like MODE. Note that several commands may be given on the command line, separated by commas. Batch Operation: Like other MS-DOS programs, Kermit-MS may be operated under batch with command line arguments. If you invoke it without command line arguments, it will run interactively, reading commands from the keyboard and not the batch file. When it exits, batch processing will continue to the end of the batch file. Remote Operation: The MS-DOS CTTY command allows an MS-DOS system to be used from a terminal con- nected to its communication port. Such sessions must be conducted with great care, since many programs assume that they are running on the real console, and explicitly reference screen memory or keyboard scan codes. Kermit can be used in this manner too, but before you give it any file transfer commands, you must inform it that it is running in "remote mode" rather than its normal "local mode." Use the SET REMOTE ON command for this purpose, to prevent the file transfer display from being sent out the port. MS-DOS KERMIT Page 174 11.3. Kermit-MS Commands MS-DOS Kermit implements a large subset of the commands of "ideal" Kermit. Here's a brief summary: BYE to remote server. CLEAR key redefinitions. CLOSE log file and stop logging remote session. COMMENT a command file. CONNECT as terminal to remote system. CWD change local working directory. DEFINE macros of Kermit-MS commands. DELETE local files. DIRECTORY listing of local files. DO a macro expansion. EXIT from Kermit-MS. FINISH Shut down remote server. GET remote files from server. HANGUP the phone. HELP about Kermit-MS. LOCAL prefix for local file management commands. LOG remote terminal session. LOGOUT remote server. PUSH to MS-DOS command level. QUIT from Kermit-MS RECEIVE files from remote Kermit. REMOTE prefix for remote file management commands. RUN an MS-DOS program. SEND files to remote Kermit. SERVER mode of remote operation. SET various parameters. SHOW various parameters. SPACE inquiry (about disk space). STATUS inquiry (about settings). TAKE commands from file. TYPE display a local file. VERSION display Kermit-MS program version number. The remainder of this section concentrates on the commands that have special form or meaning for MS-DOS Kermit. Not all of the following commands are necessarily available on all MS-DOS systems, and some of the commands may work somewhat differently between DOS versions. The notation used is as follows: Optional fields are in [square brackets], lists of alternatives are in {curly braces}. Parameters, such as numbers or filenames, are shown in italics (providing the printer is capable of printing italics), and in dialog examples user typein is underlined (on printers that can show it) to distinguish it from computer typeout. MS-DOS KERMIT Page 175 11.3.1. Commands for Terminal Connection The CONNECT command connects your PC as a terminal to the remote system, so that you can start up Kermit there. The CONNECT Command The CONNECT command establishes an interactive terminal connection to the sys- tem connected to the currently selected communications port (e.g. COM1 or COM2) using full duplex (remote) echoing and no parity unless otherwise specified in previous SET commands. You can type the escape character followed by the let- ter C to get back to Kermit-MS. On most MS-DOS systems the escape character is Ctrl-] by default. You can use the SET ESCAPE command to define a different escape character, and on most systems you can SET BAUD (or SPEED) to change the baud rate, and SET PORT to switch between ports. Read about the SET COMMAND in section 11.3.6 for more information on these and other settings. Terminal emulation is described in greater detail in section 11.4 below. The HANGUP Command HANGUP command attempts to lower the modem signals DTR and RTS. It may be used to hang up the phone when dialed up through a modem, or to get the attention of port contention units or terminal concentrators that operate in this manner. 11.3.2. Commands for File Transfer The file transfer commands are SEND, GET, and RECEIVE. The SEND Command Syntax: SEND filespec1 [filespec2] The SEND command causes a file or file group to be sent from the local MS-DOS system to the Kermit on the remote system. The remote Kermit may be running in either server or interactive mode; in the latter case, you should already have given it a RECEIVE command and escaped back to your PC. filespec1 may contain the wildcard characters "*" to match zero or more charac- ters within a field, and/or "#" (first position) or "?" (elsewhere) to match any single character. If filespec1 contains wildcard characters then all matching files will be sent, in the same order that MS-DOS would show them in a directory listing. If filespec1 specifies a single file, you may direct Kermit-MS to send that file with a different name, given in filespec2. For in- stance, in the command Kermit-MS>send foo.bar framus.widget filespec2 begins with the first nonblank character after filespec1 and ends with the carriage return; thus it may contain blanks or other unusual charac- MS-DOS KERMIT Page 176 ters that may be appropriate on the target machine. The alphabetic case of text in filespec2 is preserved in transmission. If the SEND command is specified by itself on the command line, then you will be prompted separately for the name of the file to send, and the name to send it under: Kermit-MS>send Local Source File: c:\chris\xcom1.txt Remote Destination File: com1.txt If a file can't be opened for read access, standard MS-DOS recovery procedures will take place. For example: Not ready error reading drive A Abort, Retry, Ignore? If you select "Abort," you will be returned to DOS. Files will be sent with their MS-DOS filename and filetype (for instance FOO.TXT, no device or pathname). If there is no filetype, then only the name will be sent, without the terminating dot. Each file is sent as is, with no conversions done on the data, except for possibly adding or deleting a ter- minating Control-Z character (see the SET EOF command). Once you give Kermit-MS the SEND command, the name of each file will be dis- played on your screen as the transfer begins. Packet, retry, and other counts will be displayed along with informational messages during the transfer. If the file is successfully transferred, you will see "Complete", otherwise there will be an error message. When the specified operation is done, the program will sound a beep. Several single-character commands may be given while a file transfer is in progress: ^X (Control-X) Stop sending the current file and go on to the next one, if any. ^Z Stop sending this file, and don't send any further files. ^C Return to Kermit-MS command level immediately without sending any kind of notification to the remote system. ^E Like ^C, but send an Error packet to the remote Kermit in an attempt to bring it back to server or interactive command level. CR Simulate a timeout: resend the current packet, or NAK the expected one. Control-X, Control-Z, and Control-E send the proper protocol messages to the remote Kermit to bring it gracefully to the desired state. Control-C leaves the remote Kermit in whatever state it happens to be in, possibly retransmit- ting its last packet over and over, up to its retry limit. You should only have to use Control-C in dire emergencies (the remote Kermit is stuck, the remote system crashed, etc), or at those times when you realize that you have given a file transfer command to Kermit-MS without first having told the remote Kermit about it. MS-DOS KERMIT Page 177 The RECEIVE Command Syntax: RECEIVE [filespec] The RECEIVE command tells Kermit-MS to receive a file or file group from the other system. Kermit-MS passively waits for the file to arrive; this command is not to be used when talking to a Kermit server (use GET for that). You should already have issued a SEND command to the remote Kermit and escaped back to Kermit-MS before issuing the RECEIVE command. If the optional filespec is provided, the first incoming file will be stored under that name. The filespec may include any combination of the following fields: Device designator Store the file on the designated device. If no device designator is given, store it on the current default device. Directory path Store the file in the designated directory. If no path given, store the file in the current directory. File name Store the file under the name given. If no name is given, store it under the name it was sent under, converted, if necessary, to suit DOS conven- tions, and modified, if desired, to avoid overwriting any file of the same name in the same directory. 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, but on the specified device and directory. If an incoming file does not arrive in its entirety, Kermit-MS will normally discard it and it will not appear in your directory. You may change this be- havior by using the command SET INCOMPLETE KEEP, which will cause as much of the file as arrived to be saved on the disk. The same single-character commands are available as during SEND: ^X Request that the remote Kermit stop sending the current file, and proceed to the next one immediately. Since this is an optional feature of the Kermit protocol, the remote Kermit might not honor the request. ^Z Request that the remote Kermit terminate the entire transfer; this is also an optional feature that may or may not be supported by the remote Kermit. ^C, ^E, and CR operate in the same way as they do during SEND. In this case, ^E should always do what ^Z is supposed to do. If the incoming file has the same name as a file that already exists, and WARN- ING is set ON, Kermit-MS will change the incoming name (and inform you how it renamed it) so as not to obliterate the pre-existing file. If WARNING is OFF, the original file will be overwritten; if you type ^X or ^Z to interrupt the transfer, you'll either get a partial new file, or else both the old and the new file of that name will be lost, depending on SET INCOMPLETE. In any case, MS-DOS KERMIT Page 178 when WARNING is off, files with the same name as incoming files will not sur- vive. Caution: If an incoming file's name (the part before the dot) corresponds to an MS-DOS device name, such as NUL, COM1, CON, AUX, or PRN, output will go to that device, rather than to a file with that name. This is a feature of MS-DOS. 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-MS has a Kermit server active on the other end of the connection. 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-MS. If the remote Kermit does not have a SERVER command, then you should use SEND and RECEIVE as described above. You may use the GET command in a special way to specify a different name for storing the incoming file. Just type GET alone on a line, and you will be prompted separately for the remote filespec and the local filespec: Kermit-MS>get Remote Source File: com1 txt Local Destination File: a:xcom1.txt The local file name may contain a device field, and/or a directory specifica- tion. If more than one file arrives, only the first will be renamed. Device and directory specifications in the local destination file name work the same way as in the RECEIVE command. The remote filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. It can contain whatever wildcard or file-group notation is valid on the remote system. As files arrive, their names will be displayed on your screen, along with packet traffic statistics and status messages. You may type ^X to request that the current incoming file be cancelled, ^Z to request that the entire incoming batch be cancelled, and ^C or ^E to return immediately to the Kermit-MS> prompt, exactly as described for the RECEIVE command. 11.3.3. Commands for Controlling Remote Kermit Servers The BYE, FINISH, and LOGOUT commands allow you to shut down a remote Kermit server: BYE When communicating with a remote Kermit server, use the BYE command to shut down the server, log out its job, and exit locally from Kermit-MS to DOS. FINISH Like BYE, FINISH shuts down the remote server. However, FINISH does not log out the server's job. You are left at Kermit-MS prompt level so that you can connect back to the job on the remote system. MS-DOS KERMIT Page 179 LOGOUT The LOGOUT command is identical to the BYE command, except you will remain at Kermit-MS prompt level, rather than exit to DOS, so that you can establish or use another connection. Other functions may be also requested of a server, described under the REMOTE command, immediately below. 11.3.4. Commands for File Management Kermit-MS provides commands or managing both local and remote files. The REMOTE Commands 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, and some Kermit servers may be able to perform functions for which Kermit-MS does not yet have the corresponding commands. In case you send a command the server cannot execute, it will send back a message stating that the command is unknown to it. If the remote server can execute the command, it will send the results to your screen (or whatever device you have specified in your most recent SET DESTINATION command). Here are the REMOTE commands that Kermit-MS may issue: REMOTE CWD [directory] Ask the server to Change your Working Directory on the remote host, that is, the default source and destination area for file transfer and management. You will be prompted for a password, which will not echo as you type it. If you do not supply a password (i.e. you type only a carriage return), the server will attempt to access the specified directory without a password. If you do not supply a directory name, your default or login directory on the remote system will be assumed and you will not be prompted for a password. REMOTE DELETE filespec Ask the server to delete the specified file or files on the remote sys- tem. In response, the server may display a list of the files that were or were not successfully deleted. REMOTE DIRECTORY [filespec] Ask the server to display a directory listing of the specified files. If no files are specified, then the list should include all files in the the current working directory. REMOTE HELP Ask the server to list the services it provides. REMOTE HOST [command] Ask the server to send the command to the remote system's command processor for execution. KERMIT command Send the command to the remote Kermit for interpretation as a Kermit MS-DOS KERMIT Page 180 command itself, in the remote Kermit server's own command syntax. Most Kermit servers, including Kermit-MS, do not yet recognize such com- mands. REMOTE SPACE [directory] Ask the server to provide a brief summary of disk usage in the specified area on the remote host or, if none specified, the default or current area. REMOTE TYPE filespec Ask the server to display the contents of the specified remote file or files on your screen. The LOCAL Command The LOCAL keyword is a prefix for a number of commands. It indicates that the specified command is to be executed on the local MS-DOS system. The LOCAL prefix may be omitted. All file specifications may include device and/or directory fields. The local commands are: CWD path Changes the current working directory to the given path. All references to local file names without explicit paths will refer to that path. DELETE filespec Deletes the specified file or files. As in DOS, the names of the deleted files are not listed, only the message "file(s) deleted" or "file(s) not found", and if you give the command "delete *.*", Kermit-MS will prompt "Are you sure?", like DOS. DIRECTORY [filespec] Lists the names, sizes, and creation dates of files that match the given file specification. If no filespec is given, the command is equivalent to DIR *.*. SPACE Performs the MS-DOS CHKDSK function by running the CHKDSK program from the current path. RUN command Passes the command line to COMMAND.COM for execution. Thus, any legal DOS operation is permitted: running a program (with command line ar- guments or i/o redirection), executing a DOS command, or executing a batch file. COMMAND.COM should be in the current path. Kermit is suspended while the command is executed and automatically resumes af- terward. Yes, one may nest RUN KERMIT several times if memory is available; but that just wastes memory. If the command is a DOS com- mand (like DIR or REN) it will be executed directly by COMMAND.COM. Otherwise, the specified file will be executed, which must be in .EXE or .COM format, or a .BAT file containing DOS commands, from the specified path or according to the value of the PATH variable if no path was included in the filespec. Example: Kermit-MS>run more < foo.txt MS-DOS KERMIT Page 181 TYPE filespec Displays the specified local file on the screen. Automatic pause is not available at the end of a page (but see above example for how to accomplish this). On most systems, Ctrl-S can be used to stop scroll- ing and Ctrl-Q to continue scrolling. PUSH Invokes an MS-DOS command processor "under" Kermit-MS, either COMMAND.COM or whatever shell you have specified with COMSPEC (or SHELL, depending on the system) in your CONFIG.SYS file. You can return to Kermit-MS by typing the MS-DOS EXIT command, and you will find Kermit-MS as you left it, with all settings intact. The same function is accomplished by the CONNECT escape-level command P. The local RUN command has various uses, one of which is to supplement the fea- tures of Kermit-MS. A common complaint about Kermit-MS, for instance, is that it lacks login scripts, autodialer control, and phone directories. While wait- ing for these features to appear in a generally useful form in some future release, you might be able to provide the specific functions you need by writ- ing a program in any compiled language (assembler, Pascal, C, etc) and then in- voking from within Kermit-MS using the RUN command. For instance, if you have a Hayes-like modem, you could write a short program to operate the dialer with AT commands, accepting the phone number to dial on the command line. If this program were called DIAL, then you could "run dial 7654321" from within Kermit. The TAKE Command Syntax: TAKE filespec The TAKE command instructs Kermit-MS to execute commands from the specified file, which may include an explicit path; if no path is specified, the value of the PATH variable is used; if PATH has no value, then the current disk and directory are searched. The command file may include any valid Kermit-MS com- mands, including TAKE, but it cannot include characters to be sent to a remote host during terminal emulation (i.e. after a CONNECT command). Commands within TAKE files, unlike interactive commands, may include trailing comments, preceded by semicolons: set port 2 ; Select the modem port set speed 1200 ; Set the baud rate for the modem Warning: since TAKE file processing discards all characters from a line begin- ning with the first semicolon, it is not possible to include semicolons in remote filespecs within TAKE files, e.g. get dska:foo.bar;6 Commands from the TAKE file will normally not be displayed on your screen. If you want to see them as they are executing, you can SET TAKE-ECHO ON. MS-DOS KERMIT Page 182 The LOG and CLOSE Commands Syntax: LOG filespec CLOSE Specifies that your terminal session during CONNECT will be recorded in the specified file; the filespec may include a device specification and/or direc- tory path. The LOG command allows you to "capture" files from a remote system that doesn't have Kermit, as well as to record remote command typescripts. The log is closed when you EXIT from Kermit-MS or when you issue an explicit CLOSE command. During terminal emulation, the LOG command records all the characters that ar- rive from the remote host in the specified file, including escape sequences. If you have SET LOCAL-ECHO ON, it will also record the characters you type. And if you have also SET DEBUG ON, then during file transfer it will also record the packets in the log. You may LOG PRN to cause the logging information to be printed directly on your printer. Note that any escape sequences that are sent to the screen are also sent to the printer. If you want to record information without imbedded escape sequences, use the screen dump feature, invoked by the CONNECT escape-level command F, which is described in more detail in the terminal emulation section. 11.3.5. The SERVER Command Kermit-MS is capable of acting as a full-fledged Kermit server, providing file transfer and management for users coming in through one of the communication ports. To put Kermit-MS into server mode, first issue any desired SET commands to select and configure the desired port, and then type the SERVER command. Kermit-MS will await all further instructions from the user Kermit on the other end of the connection, which may be hardwired or connected through an autoanswer modem. For example: Kermit-MS>set port 1 Kermit-MS>set baud 1200 Kermit-MS>set timer on Kermit-MS>set warning on Kermit-MS>server Kermit 2.29 server mode supports the following requests: SEND REMOTE DELETE REMOTE CWD GET REMOTE DIRECTORY REMOTE HOST FINISH REMOTE SPACE BYE REMOTE TYPE The REMOTE HELP command is not implemented. Remote CWD can be used to change both directories and devices. CAUTION: The method used for most of the REMOTE commands is to invoke a task with the user's command line, redirect standard output to a tem- MS-DOS KERMIT Page 183 porary file, $KERMIT$.TMP, send that file back to the remote end, and then delete the file. Sufficient space must be available to store this file. To service DOS commands or user tasks the boot drive must hold a copy of COMMAND.COM. PATH will not be searched (this can be dis- asterous on a floppy disk based system). FURTHER CAUTION: Any of these DOS tasks or programs may encounter an error, and in that case, DOS will generally put the familiar "Abort, Retry, Ignore?" message on the screen, and will wait for an answer from the keyboard. This will hang the server until a human comes to the keyboard and gives a response. The same thing will happen when any program is invoked that interacts with the real console. For instance, REMOTE SPACE works by running CHKDSK; if CHKDSK finds something wrong with the disk while tallying up the space, it will ask (at the console) if you want to it to be fixed. This, too, will hang the server. MORAL: The MS-DOS Kermit server should probably not be used for REMOTE commands unless someone is around to take care of it when it gets stuck. 11.3.6. The SET Command Syntax: SET parameter value or: SET parameter parameter value The SET command establishes or modifies various parameters for file transfer or terminal connection. You can examine their values with the STATUS and SHOW commands. The following SET commands are available in Kermit-MS: BAUD Communications port line speed (synonym for SPEED) BELL Whether to beep at the end of a transaction BLOCK-CHECK-TYPE Level of error checking for file transfer DEBUG Display packet contents during file transfer DEFAULT-DISK Default disk drive for file i/o DESTINATION Default destination device for incoming files DISPLAY For selecting the type of file transfer display DUMP Screen dump file (or device) name END-OF-LINE Packet termination character EOF Method for determining or marking end of file ESCAPE Escape character for CONNECT FLOW-CONTROL Enable or disable XON/XOFF HANDSHAKE Half-duplex line turnaround option INCOMPLETE What to do with an incompletely received file KEY Specify key redefinitions, or "keystroke macros" LOCAL-ECHO Specify which computer does the echoing during CONNECT MODE-LINE Whether to display a mode line during terminal emulation PARITY Character parity to use PORT Select a communications port PROMPT Change the "Kermit-MS>" prompt to something else RECEIVE Request remote Kermit to use specified parameters REMOTE For running Kermit-MS interactively from back port RETRY Packet retransmission threshold SEND Use the specified parameters during file transfer SPEED Communications port line speed (synonym for BAUD) MS-DOS KERMIT Page 184 TAKE-ECHO Control echoing of commands from TAKE files TERMINAL Emulation and parameters TIMER Enable/disable timeouts during file transfer WARNING Specify how to handle filename collisions The SET commands are now described in greater detail. SET BAUD Syntax: SET BAUD rate Set the speed of the currently selected terminal communications port (COM1 by default) to 300, 1200, 1800, 2400, 4800, 9600, 19200, or other common baud rate. Some implementations do not support this command. In any case, Kermit-MS leaves the current communication port settings alone unless you issue explicit SET commands to change them. SET SPEED is an acceptable synomym for SET BAUD. Note that on certain systems, when you first run Kermit after power- ing the system up, you may get a message "Unrecognized baud rate". This means that Kermit tried to read the baud rate from the port and none was set. Simply use SET BAUD (if available) or the DOS MODE command to set the desired baud rate. SET BELL Syntax: SET BELL {ON, OFF} Specifies whether the bell (beeper) should sound upon completion of a file transfer operation. Normally ON. SET BLOCK-CHECK Syntax: SET BLOCK-CHECK {1, 2, 3} Selects the error detection method: a 1-character checksum (the normal case), a 2-character checksum, or a 3-character 16-bit cyclic redundancy check (CRC). If the other Kermit program is not capable of type 2 or 3 checking methods, automatic fallback to type 1 will occur. SET DEBUG Syntax: SET DEBUG {ON, OFF} When debugging is ON, Kermit will display packet traffic on your screen during file transfer. If the debugger is loaded, control will be transferred to it when Ctrl-C is typed. During terminal emulation (on the IBM PC only), control characters are displayed in uparrow notation. If logging is being done, file transfer packets are included in the log. When OFF (this is the default), debugging information is not displayed, and packets are not logged. MS-DOS KERMIT Page 185 SET DEFAULT-DISK Syntax: SET DEFAULT-DISK x: Specify the default disk drive to use for file transfer, directory listings, and so forth. Equivalent to typing the DOS command for changing disks (A:, B:, etc). Affects Kermit and all inferior processes, but when you exit from Ker- mit, you will still have the same default disk as when you entered. SET DESTINATION Syntax: SET DESTINATION device Specify the device for incoming files during file transfer: DISK, PRINTER, or SCREEN. SET DESTINATION PRINTER will cause incoming files to be spooled directly to the printer; SCREEN will send output normally destined for the disk to the screen. The normal destination is DISK. SET DESTINATION affects only files transferred with SEND, GET, or RECEIVE; it cannot be used to reroute the output from REMOTE server commands. SET DISPLAY Syntax: SET DISPLAY {QUIET, REGULAR, SERIAL} During file transfer, MS-DOS Kermit's regular display is a formatted screen whose fields randomly updated with file names, packet numbers, error counts, percent done, error messages, and so forth: File name: FOO KBytes transferred: 7 Sending: In progress Percent done: 52% Number of packets: 74 Number of retries: 2 Last error: None Last warning: None The items in the right-hand column are updated more or less at random. If you wish to run Kermit-MS interactively through the back port, for instance after the operator has done CTTY COM1, you must give the command SET REMOTE ON (which, currently at least, is equivalent to SET DISPLAY QUIET); this sup- presses the file transfer display screen, so that the display won't interfere with the file transfer itself. You can also use this command to suppress the display in local mode, in case you are using a system that allows you to do other work while file transfer proceeds in the background. If you have your PC connected to a speaking device (a common practice for visually impaired people), or you are logging the display screen to a printer (using DOS ^P or kermit > prn), the random nature of the regular display will make the results of little use. SET DISPLAY SERIAL is provided for this pur- pose; it causes the program to report progress "serially" on the screen. In serial mode, error messages are preceeded with the word "Error" and repeat mes- sages with the word "Retry". Packets are numbered as dots with every tenth be- MS-DOS KERMIT Page 186 ing a plus sign. The packet display is automatically broken across lines at every 70th packet. The serial display makes much more sense when spoken than does the regular display. The serial display does not show the percent and kilobytes transferred. It is the default display style for generic MS-DOS Kermit; REGULAR is the default for all others. SET DUMP Syntax: SET DUMP path On those systems that support this feature, change the file or device name of the screen dump file. The normal file name is KERMIT.SCN. See the section on terminal emulation for details about screen dumps. END-OF-LINE Syntax: SET END-OF-LINE number If the remote system needs packets to be terminated by anything other than car- riage return, specify the decimal value of the desired ASCII character. SET EOF Syntax: SET EOF {CTRL-Z, NOCTRL-Z} Controls how the end of file is handled. CTRL-Z specifies a Control-Z charac- ter should be appended to the end of an incoming file, unless it already ends with a Control-Z. Certain MS-DOS text editors and other applications require files to be in this format. For outbound files, treat the first Control-Z as the end of the local file, and do not send it or any subsequent characters. NOCTRL-Z is the default; incoming files are stored, and MS-DOS files are sent, exactly as is, in their entirety. SET ESCAPE Syntax: SET ESCAPE character Specify the control character you want to use to "escape" from remote connec- tions back to Kermit-MS. The default is normally ^] (Control-Rightbracket). The character is entered literally, and should normally be chosen from the AS- CII control range. It is not possible to use non-ASCII characters (e.g. func- tion keys) for this purpose. SET FLOW-CONTROL Syntax: SET FLOW-CONTROL {XON/XOFF, NONE} Specify the full duplex flow control to be done on the currently selected port. The options are XON/XOFF and NONE. The specified type of flow control will be MS-DOS KERMIT Page 187 done during both terminal emulation and file transfer. By default, XON/XOFF flow control is selected. XON/XOFF should not be used on half-duplex (local echo) connections. If XON/XOFF is used, HANDSHAKE should be set to NONE. SET HANDSHAKE Syntax: SET HANDSHAKE {CODE number, BELL, CR, LF, NONE, XOFF, XON} Specify any half-duplex line turnaround handshake character for the currently selected port. The CODE number form allows any ASCII character to be specified by its decimal ASCII code. The specified handshaking is done during file transfer only. Handshake is NONE by default; if set to other than NONE, then FLOW-CONTROL should be set to NONE. SET INCOMPLETE Syntax: SET INCOMPLETE {DISCARD, KEEP} Specifies what to do with files that arrive incompletely: discard them or keep them. They are normally discarded. SET KEY Syntax: SET KEY key-specifier Specifies that when the designated key is struck during terminal emulation, the associated character string is sent. The key-specifier is one of the keywords F1, F2, ..., or else SCAN followed by a scan code. Systems that have a BACK- SPACE key also include BACKSPACE as a keyword. If SCAN is used, it is followed by a decimal number to indicate the scan code of the key, which you would ascertain from your system reference manual, or else by using the Kermit-MS SHOW KEY command. SET KEY prompts you on a new line for the definition string. Certain characters, like ESC and CR, may not be entered literally into the string, but can be included by inserting escape codes of the form \ooo, a backslash followed by a 2- or 3-digit octal number corresponding to the ASCII value of the desired character. If some other key redefinition package, like ProKey, has been loaded, then its redefinitions will take precedence over Kermit's. The SET KEY command is illustrated in the terminal emulation section below. Note that key redefinitions occur only during terminal emulation, and not at Kermit-MS command level, or outside of Kermit. SET LOCAL-ECHO Syntax: SET LOCAL-ECHO {ON, OFF} Specify how characters are echoed during terminal emulation on the currently selected port. ON specifies that characters are to be echoed by Kermit-MS (because neither the remote computer nor the communications circuitry has been requested to echo), and is appropriate for half-duplex connections. LOCAL-ECHO MS-DOS KERMIT Page 188 is OFF by default, for full-duplex, remote echo operation. When using Kermit to connect two PCs "back to back," use local echo so that when you CONNECT to the other PC to send messages to its operator, you can see what you are typing. Depending on the system, you may have to type a carriage return and a linefeed at the end of each line in order to make the display look right. SET MODE-LINE Syntax: SET MODE-LINE {ON, OFF} On systems, like the IBM PC family, which are capable of displaying a status, or "mode" line on the 25th line during terminal connection, disable or enable this function. Has no effect on systems that do not display a mode line during connect. When the mode line is enabled, it may be turned on and off using the CONNECT escape-level command M. Refer to the terminal emulation section, 11.4, for further details. SET PARITY Syntax: SET PARITY {EVEN, ODD, MARK, SPACE, NONE} Specify the character parity to be used on the currently selected port. NONE means no parity processing is done, and the 8th bit of each character can be used for data when transmitting binary files. This is the normal case. You will need to SET PARITY to ODD, EVEN, MARK, or possibly SPACE when com- municating with a system, or over a network, or through modems, concentrators, multiplexers, or front ends that require or impose character parity on the com- munication line. For instance, GTE Telenet normally uses MARK parity. If you neglect to SET PARITY when the communications equipment requires it, the symptom may be that terminal emulation works (well or maybe only partially), but file transfer does not work at all. If you have set parity to ODD, EVEN, MARK, or SPACE, then Kermit-MS will re- quest that binary files will be transferred using 8th-bit-prefixing. If the other Kermit 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. Note that there is no advantage to using parity; it reduces Kermit's file transfer efficientcy without providing any ad- ditional error detection. The SET PARITY command is provided only to allow Kermit to adapt to conditions where parity is required, or 8-bit transmission is otherwise thwarted. SET PORT Syntax: SET PORT {number, COM1, COM2} On machines with more than one communications port, select the port to use for file transfer and CONNECT. This command lets you use a different asynchronous adapter, or switch between two or more simultaneous remote sessions. Sub- MS-DOS KERMIT Page 189 sequent SET BAUD, PARITY, HANDSHAKE, FLOW, and LOCAL-ECHO commands will apply to this port only. SET PORT 1 selects COM1, SET PORT 2 selects COM2. All ver- sions default to port 1, except for the IBM PCjr, which uses port 2 by default (since Kermit does not know how to control its port 1, an internal modem). In "generic" MS-DOS Kermit, the following alternate forms allow you to experi- ment with device names or numbers until you find the communication port: SET PORT {DEVICE, FILE-HANDLE} Just type a carriage return after either of these commands, and you will be prompted for a device name or a numeric port-handle. Keep trying till you find one that works. SET PROMPT Syntax: SET PROMPT string This command allows you to change the MS-DOS Kermit program's prompt. SET RECEIVE Syntax: SET RECEIVE parameter value At the beginning of a protocol operation, request the remote Kermit to use the given value specified parameter, or inform Kermit-MS that the remote Kermit will be using it. PACKET-LENGTH number Ask the remote Kermit to use the specified maximum length for packets that it sends to Kermit-MS. The normal (and maximum) length is 94. Use this command to shorten packets if the communication line is noisy; this will decrease the probability that a particular packet will be corrupted, and will reduce the retransmission overhead when corruption occurs, but it will increase the protocol overhead. PADCHAR number Ask the remote Kermit to use the given control character (expressed as a decimal number 0-31, or 127) for interpacket padding. Kermit-MS should never require any padding. PADDING number Ask the remote Kermit to insert the given number of padding characters before each packet it sends. This should never be necessary. START-OF-PACKET number If the remote Kermit will be marking the beginning of packets with a control character other than Control-A, use this command to tell Kermit-MS about it (the number should be the decimal ASCII value of a control character). This will be necessary only if the hosts or com- munication equipment involved cannot pass a Control-A through as data, or if some piece of communication equipment is echoing packets back at you. MS-DOS KERMIT Page 190 TIMEOUT number Ask the remote Kermit to time out after the given number of seconds if a packet expected from Kermit-MS has not arrived. Use this command to change the normal timeout interval. SET REMOTE Syntax: SET REMOTE {ON, OFF} SET REMOTE ON removes the file transfer display (as if you had given the com- mand SET DISPLAY QUIET). It should be used when you are running Kermit-MS in remote mode (i.e. when coming in from another PC through the Kermit-MS's "back port", to which the console has been reassigned using the DOS CTTY command). It is necessary to issue this command because (a) Kermit-MS has no way of know- ing that its console has been redirected, and (b) when the console is the same as the port, the file transfer display will interfere with the file transfer itself. SET REMOTE OFF returns the file transfer display to its preferred style (REGULAR or SERIAL). SET RETRY Syntax: SET RETRY number Sets the number of times a packet is retransmitted before the protocol gives up. The number of retries can be between 1 and 63, and is 5 by default. This is an especially useful parameter when the communications line is noisy or the remote host is very busy. SET SEND Syntax: SET SEND parameter value PACKET-LENGTH number Use the specified maximum length for outbound packets. Normally, Kermit-MS uses whatever length the other Kermit requests. PADCHAR number Use the specified control character for interpacket padding. Some hosts may require some padding characters (normally NUL or DEL) before a packet, and certain front ends or other communication equipment may need certain control characters to put them in the right modes. PADDING number How many copies of the pad character to send before each packet, nor- mally zero. PAUSE number How many milliseconds to pause between sending the next packet, 0-127, normally zero. This helps half-duplex systems prepare for reception of our packet. Padding characters are sent only after the time limit ex- pires. QUOTE number MS-DOS KERMIT Page 191 Use the indicated printable character for prefixing (quoting) control characters and other prefix characters. The only reason to change this would be for sending a very long file that contains very many "#" characters (the normal control prefix) as data. START-OF-PACKET number Mark the beginning of outbound packets with some control character other than Control-A. This will be necessary if the remote host or the communication channel involved cannot accept a Control-A as data, or if it echoes back your packets. The remote host must have been given the corresponding SET RECEIVE START-OF-PACKET command. TIMEOUT number Change Kermit-MS's normal timeout interval; this command is effective only if TIMER is set to be ON; it is normally OFF so that the remote Kermit can control timeouts. When the timer is ON, the default timeout interval is 13 seconds. SET SPEED Syntax: SET SPEED rate Same as SET BAUD, q.v. SET TAKE-ECHO Syntax: SET TAKE-ECHO {ON, OFF} Specifies whether screen display should occur during implicit or explicit TAKE operations on MSKERMIT.INI or other Kermit-MS command files, and during evalua- tion of macro definitions. Handy for finding errors. SET TERMINAL Syntax: SET TERMINAL parameter [value] This command controls most aspects of terminal emulation. Most of the parameters are only settable (or meaningful) on the IBM PC family and com- patibles. (Programmers who are proficient on other MS-DOS systems are invited to fill in these functions for those systems and send the results back to Columbia.) The first group of parameters tells which kind of terminal to emulate. When Kermit-MS uses its built-in software for emulation, incoming characters are ex- amined for screen control commands (escape sequences) specific to that ter- minal, and if encountered, the commands are executed on the PC screen. NONE Act as a dumb terminal. All incoming characters will be sent to the screen "bare", as-is, 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 itself. Many non-IBM systems have their own screen control code interpreter built into DOS or firmware, or available as a loadable device driver. MS-DOS KERMIT Page 192 VT52 The DEC VT-52 terminal. HEATH The Heath/Zenith-19 terminal (H19), which supports all the VT52 com- mands, plus line and character insert/delete editing functions, and a 25th line. VT102 The DEC VT102 (ANSI) terminal, which is the same as a VT100 but also supports line/character insert/delete editing functions. TEKTRONIX A Tektronix 4010 graphics terminal. Only available on TI and Victor PCs. The specific escape sequences supported by Kermit for each of these terminal types are listed in section 11.10. The remaining SET TERMINAL commands specify setup options for the selected ter- minal: CHARACTER-SET {UK, US} UK displays # as a pound sterling sign, US displays # as #. COLOR number [, number [, number]] Several numbers, applied in left to right sequence, separated by com- mas or spaces: 0 Reset the colors to normal intensity white characters on a black background and use the "no-snow" mode on the IBM Color Graphics Adapter (CGA). 1 High intensity foreground 10 Request fast screen updating for use on the IBM EGA or PGA, and some non-IBM CGAs. 3x Foreground color 4x Background color where x is a single digit from 0 to 7, which is the sum of the desired colors: 1 Red 2 Green 4 Blue Example: 0, 1, 34, 40 on an IBM CGA would produce blue characters on black field with no snow. The snow removal business has to do with whether the program should synchronize with vertical retrace when up- dating screen memory. This is necessary with certain color adaptors (like the CGA) and unnecessary for others (like the EGA). CURSOR-STYLE {BLOCK, UNDERLINE} Sets the cursor rendition to your preference. Note that on some early IBM PCs and compatibles, the cursor may not be restored correctly after escape back from CONNECT because of a bug in the early IBM BIOS. KEYCLICK {ON, OFF} Turns electronic keyclick ON or OFF. If your keyboard has a mechani- cal clicker (as IBM boards do), you may not notice the effect of this MS-DOS KERMIT Page 193 command. MARGIN-BELL {ON, OFF} Controls whether the bell should be sounded when the cursor passes column 72 near the right screen margin. NEWLINE-MODE {ON, OFF} ON sends a carriage-return-linefeed combination (CRLF) when you type carriage return (CR) during terminal emulation; OFF (default) just sends a CR when you type CR. SCREEN-BACKROUND {NORMAL, REVERSE} NORMAL means dark background, light characters. REVERSE means light background, dark characters. TAB {AT n, CLEAR AT n, CLEAR ALL} Sets tab stops or clears one or all tab stops. n is the numeric posi- tion of the tab to be set or cleared. By default, tabs are every 8 spaces, at positions 9, 17, 25, etc. Only meaningful when emulating a terminal that has settable tabs (the VT52 doesn't). More than one tabstop may be specified by separating column numbers with commas, spaces, or tabs. WRAP {ON, OFF} ON automatically breaks screen lines (by inserting a CRLF) when they reach the the right margin; OFF disables wrapping -- if a line is too long, the excess characters go off the screen. SET TIMER Syntax: SET TIMER {ON, OFF} This command enables or disables the timer that is used during file transfer to break deadlocks that occur when expected packets do not arrive. By default, the timer is ON. SET WARNING Syntax: SET WARNING {ON, OFF} 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 message) so as not to destroy (overwrite) any existing one. If OFF, the pre-existing file is destroyed, even if the incoming file does not arrive completely. WARNING is OFF by default. The new name is formed by adding numbers to the part of the name before the dot. For instance, ABC.TXT becomes ABC00001.TXT, then ABC00002.TXT, etc. MS-DOS KERMIT Page 194 11.3.7. The SHOW Command Syntax: SHOW option Most parameters that may be altered with SET commands are displayed by the STATUS command. The SHOW command is used for displaying macro definitions and key redefinitions. The SHOW MACROS command displays the definitions of all currently defined mac- ros, as well as the amount of space left for new macro definitions. The SHOW KEY command allows you to determine the scan code produced by pressing a given key, so that you can construct a SET KEY SCAN command to redefine the key. If the key already has a redefinition in effect, that too will be dis- played. This can be done either interactively or in a macro command. Refer to the terminal emulation section for examples. The SHOW KEY command only works on certain systems. 11.3.8. Command Macros Kermit-MS provides a facility for combining commands into "macros." Command macro definitions may be included in your MSKERMIT.INI file, TAKEn explicitly from a specified file, or typed interactively. Macros are invoked with the DO command. The DEFINE Command Syntax: DEFINE macro-name [command [, command [, ...]]] Kermit-MS command macros are constructed with the DEFINE command. Any Kermit-MS commands may be included. Example: define telenet set parity mark, set baud 1200, connect A macro can be undefined by typing an empty DEFINE command for it, like define telenet A macro definition may be no longer than 128 characters. Longer definitions can be accomplished by "chaining." Example: define setup set port 1, set speed 19200, set parity even, do setup2 define setup2 set port 2, set speed 1200, set parity none, do setup3 define setup3 set warning on, set incomplete keep, connect The SHOW MACROS command displays the value of all currently defined macros, and tells how much space is left for further definitions. MS-DOS KERMIT Page 195 The DO Command A Kermit-MS command macro is invoked using the DO command. For instance, Kermit-MS comes with a predefined macro to allow convenient setup for IBM mainframe line-mode communications; to invoke it, you would type do ibm The IBM macro is defined as "set timer on, set local-echo on, set parity mark, handshake xon, set flow none". You can use the DEFINE command to redefine this macro or remove the definition altogether. There is no automatic way to undo the effect of a macro. If you need to ac- complish this effect, you should define another macro for that purpose. For instance, to undo the effect of "do ibm" so that you could connect to, say, a VAX, you could: define vax set par no, set hand no, set flo x, set tim off, set loc off Then you can "do ibm" whenever you want to use the IBM system, and "do vax" whenever you want to use the VAX. If you wish to view the macro expansion whenever you issue a DO command, you can SET TAKE-ECHO ON. 11.4. Terminal Emulation When you issue the CONNECT command, your PC acts as a terminal connected to a remote computer through the currently selected port. The characters you type are sent out the port, and characters that arrive at the port are displayed on your screen, or interpreted according to whatever type of terminal is being emulated. If you have not previously issued a SET PORT command, COM1 is used except on systems (like the IBM PCjr) where some other port is the default. If you have SET LOCAL-ECHO ON for the selected port, then Kermit-MS will display characters on the screen as you type them, otherwise it will rely on the remote system to echo them. XON/XOFF flow control will be done unless you have SET FLOW-CONTROL OFF. If you have SET PARITY to anything other than NONE, Kermit-MS will add the appropriate parity to each outbound character. While CONNECTed, you can also communicate directly with an autodialer or "smart modem" to control the communications line, hang it up, and the like, for instance, by typing AT com- mands to a Hayes-like modem. When you CONNECT, the program attempts to raise the DTR and RTS RS-232 signals, and it takes no specific action to lower them unless you explicitly issue the HANGUP command. The IBM PC version of Kermit-MS emulates the DEC VT102 terminal by default, and may also be instructed to emulate the DEC VT52, the Heath/Zenith-19, or no ter- minal at all, via the SET TERMINAL command. Emulation of each of these ter- minals is nearly complete. VT102 emulation lacks only smooth scroll, 132 column mode, and ANSI printer control. Double-height, double-width characters are supported, but simulated using ordinary characters. On color monitors, the foreground and background colors may be set using SET TERMINAL COLOR, and MS-DOS KERMIT Page 196 inverse/normal video display may also be selected, along with many other ter- minal parameters. A complete list of the commands, default key configurations, and escape sequences accepted by the IBM PC Kermit terminal emulator is given in section 11.10. The Escape Character The escape character is used to regain the attention of Kermit-MS during CON- NECT, i.e. terminal emulation. When you type the escape character, Kermit-MS waits for you to follow it with a single character command. For instance, the single character command "?" produces a list of available single character com- mands. This command is executed immediately; it may not be edited, and the program does not wait for a carriage return to confirm it. Here are the CON- NECT escape-level commands available in Kermit-MS: ? Help -- prints the available single-character commands. 0 (the digit zero) Transmit a NUL (ASCII 0). B Transmit a BREAK signal. C Close the connection and return to Kermit-MS prompt level. F File the current screen in the screen dump file. M Toggle the mode line, i.e. turn it off if it is on & vice versa. P Push to DOS; get back to CONNECT by typing EXIT. Q Temporarily quit logging the remote session. R Resume logging the remote session. S Show the status of the connection. ^] (or whatever you have set the escape character to be) Typing the escape character twice sends one copy of it to the connected host. Typing any other character (except the space bar, which is the "null command") after the escape character will cause Kermit-MS to beep, but will do no harm. The escape character can be changed to something other than Control- Rightbracket by using the SET ESCAPE command. The Mode Line When you first issue the CONNECT command, a message (on some systems, an in- verse video "mode line") will display the most important facts about the con- nection you've just established, so that you can quickly diagnose any problems. Here's what the IBM PC mode line looks like: +--------------------------------------------------------------------------+ | Esc-chr:^] help:^]? port:1 speed:9600 parity:odd echo:rem VT102 .... PRN | +--------------------------------------------------------------------------+ This shows that the escape character is Ctrl-Rightbracket, that you would type Ctrl-rightbracket followed by question mark (^]?) to get help during CONNECT, that you are connected on port 1 at 9600 baud with odd parity and remote echo, and that a VT102 terminal is being emulated. The four dots represent the VT102s LEDs (they turn into the digits 1,2,3,4 when "lit") and PRN will show up if the printer is activated (e.g. by Ctrl-PrintScreen). The mode line occupies the 25th line of those systems that have such a thing, and is not affected by scrolling. When emulating a VT102 or Heath-19, Kermit MS-DOS KERMIT Page 197 will allow the host to address the 25th line directly using cursor positioning commands. If this happens, Kermit will remove its mode line and relinquish control of the 25th line to the host (as if you had typed SET MODE OFF). When no terminal is being emulated, the 25th line (if any) is available for scroll- ing. If the mode line is disabled by an application or by the command SET MODE OFF then the only way to revive Kermit's mode line display is to give the com- mand SET MODE ON. Screen Scroll On certain systems, Kermit-MS provides several pages of screen memory, which may be scrolled up and down using keys as shown in Table 11-1. ------------------------------------------------------------------------------- System Screen Down Line Down Screen Up Line Up IBM PC PgUp Ctrl-PgUp PgDn Ctrl-PgDn Rainbow PrevScreen Ctrl-PrevScreen NextScreen Ctrl-NextScreen HP-150 Prev Shift-UpArrow Next Shift-DownArrow NEC APC Uparrow Ctrl-UpArrow DownArrow Ctrl-DownArrow Table 11-1: Kermit-MS Screen Scroll Keys ------------------------------------------------------------------------------- There is no way to assign these functions to other keys. The IBM PC also allows use of the Home key to get to the top of its display memory and End key to get to the bottom, and the keypad plus (+) key to toggle the mode line on and off. The Rainbow uses Shift-Next-Screen to get to the bottom of its display memory, but provides no key for moving directly to the top. Screen Dump The screen dump feature writes the contents of the screen to a file (KERMIT.SCN unless another file was selected by the SET DUMP command) when the CONNECT escape-level command F is typed. The screen dump file is appended to on each successive screen dump, with each screen separated by a formfeed (Ctrl-L). This feature may be used in conjunction with screen rollback -- a handy way to recapture screenfuls of laboriously typed-in text after a remote host has crashed without saving your work. A screen dump differs from a session log in two ways. First, each desired screen must be manually filed, and second, the screen dump file has been stripped of any escape sequences, whereas the session log records them. MS-DOS KERMIT Page 198 Printer Control During terminal emulation, a locally attached printer may be controlled in the normal manner, on most systems. Pushing the "Print Screen" key (shifted on some systems) will cause the current contents of the screen to be printed or spooled; holding down CTRL while depressing Print Screen will start or stop the spooling of incoming characters to the printer. On the IBM PC, the mode line will show PRN when the printer is activated in this manner. ^P or ^N are sent to the host during terminal emulation, and do not toggle printing, as they do when you're talking directly to DOS. CTRL-Print-Screen can be simulated with the Kermit-MS LOG PRN and CLOSE com- mands. Key Redefinitions Key redefinitions are useful for defining "keystroke macros" of login se- quences, frequently issued commands, and so forth, and for setting up the ter- minal for use with host resident software designed to work with terminals that send predefined sequences from their function keys. For instance, here's a key redefinition file for arranging the DEC Rainbow keyboard into the normal ASCII keyboard layout: ; Make shift-comma send a left angle bracket set key scan 556 < ; Shift-period sends a right angle bracket set key scan 558 > ; Accent grave is where ESC is supposed to be set key scan 96 \33 ; Put accent grave on the ESC function key set key f11 ` Since SET KEY is a two-line command, a special trick is necessary in order to include it in a single-line macro definition: just use a comma where you would have typed carriage return after the first line, for instance: define bar set key scan 261, foo The CLEAR command may be used to eliminate all key redefinitions. The SET KEY facility may be used provide the PC with a "meta" key for use with editors like EMACS or TVEDIT that can use "meta characters" as commands. A meta key is a shift key whose effect is to turn on the 8th (parity) bit of the character. For instance, on the IBM PC the scan codes produced by holding down ALT together with other keys can be determined using SHOW KEY, and then 8-bit ASCII equivalents with the 8th bit turned on can be defined using SET KEY; if the scan code produced by typing ALT-a, i.e. the letter "a" (ASCII 141, octal) with the ALT key held down, is 2078 (decimal), you would set the META equivalent to 141+200=341 (octal), or "\341" in octal SET KEY notation: Kermit-MS>sho key Press a key: ALT-a MS-DOS KERMIT Page 199 Scan Code: 2078 Definition: Kermit-MS>set key scan 2078 Definition String: \341 Whenever you type ALT-a with this definition in effect, Kermit-MS will transmit octal 341, rather than 141. Summary of Kermit-MS Terminal Emulation Features Table 11-2 shows the terminal emulation options for the systems presently sup- ported by Kermit-MS. ------------------------------------------------------------------------------- System EscChar Cabilities Terminal Service ACT Apricot ^] K ??? DEC Rainbow ^] R P K D VT102 firmware DECmate/DOS ^] ??? Generic DOS ^] Depends on system Grid Compass ^] ??? HP-110 ^] Dumb terminal HP-150 ^] R HP-2623 firmware IBM PC,XT,AT ^] R M P K D H19,VT52,VT102 emulation Intel 300 ^] ??? NEC APC ^] R P K VT100, ADM3A firmware Olivetti M24 ^] R M P K D VT100 emulation Sanyo MBC550 ^] ??? Wang PC ^A Wang firmware TI Pro ^] M P K VT100/Tektronix Victor 9000 Alt-] VT100 and/or Tek4010 Zenith Z100 ^] Heath-19 emulation R=Rollback, M=Modeline, P=Printer control, K=Key redefinition, D=screen Dump Table 11-2: Kermit-MS Terminal Emulation Options ------------------------------------------------------------------------------- 11.5. Installation of Kermit-MS If you already have Kermit on your PC, you can use it to obtain new versions of Kermit-MS when they appear on the central system at your site. If you do not have Kermit or any other reliable file capture facility on your PC, and there is no one from whom you can borrow a floppy disk to copy Kermit, then you should read the following instructions for initially "bootstrapping" Kermit-MS from a mainframe where it is stored onto your microcomputer. There are at least three methods of initially getting Kermit-MS onto your PC: 1. Try again to find a copy on diskette. MS-DOS KERMIT Page 200 2. Use another file capture facility to get it. 3. Type in and run a bootstrapping program. 11.5.1. Try Again To Find A Kermit Disk Before explaining how to bootstrap Kermit onto your PC, a disclaimer must be made. Although a fair amount of thought and time has gone into these procedures, they are far from error free. If they were foolproof, there would be no need for a protocol such as Kermit. There are many places where things can go wrong, from something as simple as a typing mistake to something as un- avoidable and probably inevitable as a communications line failure. By far the easiest and best way to install Kermit is from a floppy disk. Before you em- bark on any of the following procedures it is a good idea to check once again for a diskette to copy, even it it contains an old version of Kermit. The time you spend searching is likely to be far less frustrating than the time you spend trying to bootstrap Kermit by the methods described below. 11.5.2. Bootstrapping From the Communication Line If you can't find a diskette with Kermit on it, there are two other methods available for bootstrapping MS-DOS Kermit onto your PC. The first method is to use a file capture method or other file transfer protocol to transfer the file to your PC. Some systems come supplied with facilities like this, and various public domain or commercial packages are available. The second method requires you to type in your own downloading program. In either case, you must transmit the file from the system where it resides over a communication line and into your PC. The "BOO" encoding (developed for MS-DOS Kermit, but usable on any system for any kind of sequential binary file) packs 3 .EXE file bytes into 4 printable characters in the MSVxxx.BOO file, and also compresses adjacent zero bytes (of which there may be many). The .BOO file contains only printable ASCII characters, to ensure that downloading can take place regardless of parity or other peculariaries of the communication channel. Use An Existing File Capture Facility In the rest of this discussion of bootstrapping, the host-resident boot .BOO file will be referred to as MSKERMIT.BOO. In fact, the actual name will depend on which MS-DOS system you are using -- MSVIBM.BOO for the IBM PC or XT, MSVRB1.BOO for the Rainbow-100, etc. Use your file capture facility, whatever it may be, to get the file MSKERMIT.BOO onto your PC's disk, but first make sure you have enough room for it. Once the file is on your disk, you must run the BASIC program MSBPCT.BAS to decode the file back into KERMIT.EXE. This program can be downloaded by the same method you used with MSKERMIT.BOO. The program looks on your current disk and directory for the file MSKERMIT.BOO and outputs KERMIT.EXE to the same place. KERMIT.EXE is about 57K bytes, so make sure there is space for it on your disk or else you will have to start the program over. Since the program will take about twenty minutes to completely translate the file you will want to avoid running it more than once. MS-DOS KERMIT Page 201 There is a more complicated variation on this technique, but it will save you some time. Download the files MSBPCT.BAS and MSBPCT.BOO. The latter is a com- piled C program that does the same thing that the BASIC program does, but much faster. Use the BASIC program to "un-BOO" the C program into MSBPCT.EXE and then use the latter to decode the Kermit BOO file. Type In Your Own Bootstrap If you can't find some method for downloading the .BOO file and the BASIC program, the second way of bootstrapping Kermit is to use the programs MSBPCB.BAS and MSBOOT.FOR to download the BOO file from your host and translate it directly, "on the fly." You run the program MSBOOT.FOR on your host and then run the program MSBPCB.BAS in BASIC on your PC. The FORTRAN program sends the BOO to the BASIC program, which decodes it and stores it in executable form on your current directory as KERMIT.EXE. A very rudimentary form of error checking is done to allow obviously corrupted records to be retransmitted. Follow this procedure: 1. First, you must establish a connection from your PC to the host sys- tem. A high speed connection is preferable; a "clean" line is preferable to a noisy one. In fact, a clean line is essential for this procedure. You must be able to log in to the host system over this connection. If your PC already has a terminal emulation facility, use that. If not, you might need to put your PC next to a real terminal and use that for logging in, then switch the connector to the PC at the critical moment. If you are using a terminal, make sure the terminal and PC have their communication ports set to the same speed. Refer to the OPEN COM command in the Microsoft BASIC manual. 2. Ensure that the files MSBOOT.FOR and MSKERMIT.BOO are present on the host system. MSBOOT.FOR is listed below, in case you need to type it in. 3. Get back to your PC and type in MSPCBOOT.BAS on your PC; a listing appears below. There is no need to type in the comments (anything following an apostrophe); they are only there to clarify what the program is doing. Check very carefully for errors. You should check line 70 in the program to see that it reflects the way your system is actually set up. If necessary, substitute the correct baud rate for the supplied rate of 9600, and if you are not using COM1: make that change as well. If you are downloading from an IBM or other half-duplex mainframe, leave line 1000 as it is; otherwise, replace it by a RETURN statement. If you type it in directly to BASIC make sure you save the program before you run it, so you won't have to type it in again in case of error. 4. Get back to your host system and compile MSBOOT.FOR, if it needs compiling. Define logical unit numbers 5 and 6 to be the controll- ing terminal, and logical unit 7 to be the file MSKERMIT.BOO. On VAX/VMS systems, for example, use these commands: $assign sys$input for005 $assign sys$output for006 $assign mskermit.boo for007 MS-DOS KERMIT Page 202 On a DECSYSTEM-20, do: @define 5: tty: @define 6: tty: @define 7: mskermit.boo On an IBM system under VM/CMS, do this: .filedef 5 term ( lrecl 80 recfm v .filedef 6 term ( lrecl 80 recfm v .filedef 7 disk mskermit boo ( lrecl 77 recfm f perm 5. Set your host system up for downloading: - Ensure that your terminal does not automatically pause at the end of a screenful of output. For instance, on a DEC-20 you would issue the command "terminal no pause end-of-page". - Do whatever you can to disable messages from appearing at your terminal while these programs are running. This would include messages from other users, mail notification, alarms or alerts, system messages, and so forth. Such messages will interfere with the procedure, and probably render the result useless. - You should put your host terminal in "local echo" or "half duplex" mode, if possible. 6. Start the MSBOOT program on your host system. 7. Get back to the PC. If you have been using a terminal, switch the connector to the PC. 8. Now run the BASIC program, MSBPCB.BAS. This procedure will take at least twenty minutes and possibly longer depending on line speed. Watch your modem and/or disk lights for reassurance that something is happening. By using one of these installation methods, you should now have a working ver- sion of Kermit. If you experience any problems or quirky behavior with the program, you may need to repeat the procedure. Once you have Kermit-MS on your disk, you should make the disk available to other users for copying, so that they can be spared the tedium and frustration of this bootstrap procedure. Here is a listing of MSBPCT.BAS. The "outdented" PRINT statements with line numbers ending in 5 may be included if you want incoming records to be dis- played on the screen. You don't need to include the comments. 1 'Use this BASIC program on the PC if you have the printable file 2 'MSKERMIT.BOO already on the PC to convert it to an executable 3 'file. This program takes about 30 minutes to run on a PC with 4 'floppy disks. 5 ' Bill Catchings, June 1984 6 ' Columbia University Center for Computing Activities MS-DOS KERMIT Page 203 10 t$ = time$ ' Save the time. 20 defint a-z ' Integer to gain some speed. 30 n$ = chr$(0) 40 z = asc("0") 50 t = asc("~")-z 60 def fnuchr%(a$)=asc(a$)-z 70 open "MSKERMIT.BOO" for input as #1 100 input#1,f$ ' Is this the right file? 110 if len(f$) > 20 then goto 900 120 open f$ for output as #2 130 print "Outputting to "+f$ 200 if eof(1) then goto 800 ' Exit nicely on end of file. 210 input#1,x$ ' Get a line. 220 y$ = "" ' Clear the output buffer. 230 goto 400 300 print#2,y$; ' Print output buffer to file. 310 goto 200 ' Get another line. 400 if len(x$) < 2 goto 300 ' Is the input buffer empty? 410 a = fnuchr%(x$) 420 if a = t then goto 700 ' Null repeat character? 430 if len(x$) < 3 goto 300 ' Is the input buffer empty? 440 q$=mid$(x$,2,3) ' Get the quadruplet to decode. 450 x$=mid$(x$,5) 460 b = fnuchr%(q$) 470 q$ = mid$(q$,2) 480 c = fnuchr%(q$) 490 q$ = mid$(q$,2) 500 d = fnuchr%(q$) 600 y$ = y$ + chr$(((a * 4) + (b \ 16)) and 255) ' Decode the quad. 610 y$ = y$ + chr$(((b * 16) + (c \ 4)) and 255) 620 y$ = y$ + chr$(((c * 64) + d) and 255) 630 goto 400 ' Get another quad. 700 x$ = mid$(x$,2) ' Expand the nulls. 710 r = fnuchr%(x$) ' Get the number of nulls. 715 print " Null: ",r 720 x$ = mid$(x$,2) 730 for i=1 to r ' Loop, adding nulls to string. 740 y$ = y$ + n$ 750 next 760 print#2,y$; ' Output the nulls to the file. 770 y$ = "" ' Clear the output buffer. 780 goto 400 800 print "Processing complete, elapsed time: "+t$+" to "+time$ 810 print "Output in "+f$ 820 close #1,#2 830 goto 9999 900 print "?The version of the MSKERMIT.BOO file is incorrect" 910 goto 820 MS-DOS KERMIT Page 204 9999 end Here is a listing of MSBOOT.FOR, in case you can't find it on your host system: C This Fortran program should be run on the mainframe in conjunction C with a Basic program (MSBPCB.BAS) on the PC to transfer C MSKERMIT.BOO to the PC and translate it into KERMIT.EXE. This C program uses a very rudimentary technique to try to insure that C the characters it sends arrive correctly. It just sends a count C of the number of characters sent after each line. In this way any C errors of character loss or insertion will be caught. If a C character is just corrupted it will not be caught. Hopefully if C this happens it will be in a non-critical part of the KERMIT.EXE C file. The reason a simple checksum was not used was so that this C program could run on machines using either EBCDIC or ASCII C characters. This program should take about thirty minutes to run. C C This program assumes that 5 and 6 are directed to the terminal and C 7 is directed to the file MSKERMIT.BOO. C C Bill Catchings, Columbia University Center for Computing Activities C June 1984 (Revised September 1984) C INTEGER LINE(77), ACK(4), CHECK, OK, SPACE, COMMA WRITE(6,100) 100 FORMAT(' Ready to transfer data, now run MSPCBOOT.BAS on the PC.') C Get characters for constants (character constants are rough in C some FORTRANs). READ (5,200) OK, SPACE, COMMA, ACK 200 FORMAT(4A1) GO TO 20 C Get terminal handshake. 10 READ (5,200)ACK C Did the other side like it? (Did they send OK?) IF (ACK(1) .NE. OK) GO TO 50 C Yes, get new line from file. 20 READ (7,300,END=99)LINE 300 FORMAT(77A1) C Count the characters as some rudimentary check for noise. I = 1 30 IF (LINE(I) .EQ. SPACE) GO TO 40 I = I + 1 GO TO 30 C Put in a comma followed by the count. 40 LINE(I) = COMMA C Write to TTY. 50 WRITE (6,400)LINE,I-1 MS-DOS KERMIT Page 205 400 FORMAT(' ',77A1,I2) GOTO 10 C Send good-bye message. 99 WRITE (6,500) 500 FORMAT(' ',10('&'),',10') STOP END 11.6. Compatibility with Older Versions of MS-DOS Kermit 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 Tandy 2000, and others. Eventually, support for these systems may be integrated with the current 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 LOCAL or REMOTE commands. - No 8th-bit prefixing, repeat counts, CRCs or 2-character checksums. - No TAKE or initialization files. - No command macros or command line arguments. - No terminal session logging. and others, depending on the specific version. Incompatibilities between 2.28 and 2.29 include: - The SET HEATH command has been replaced with SET TERMINAL HEATH - The SET AUTOWRAP command has been replaced with SET TERMINAL WRAP - Filename completion no longer works (a consequnce of adding support for fully qualified DOS 2.0 pathnames). 11.7. What's Missing Kermit-MS has plenty of room for improvement. Features that need to be im- proved or added include: - A built-in facility for sending files "raw" to the remote system, obeying current settings for parity, flow control, handshake, and so forth. - Specification of character sequences having special meaning to com- munications "black boxes" which use ASCII characters for control pur- poses. Byte stuffing or character doubling may be required. - TRANSMIT command for raw file upload, obeying communication settings - Login scripts, integrated with Kermit commands & settings - DIAL command, telephone directory, support for various modems - Long packets, sliding windows, attribute packets MS-DOS KERMIT Page 206 - Tektronix or other graphics terminal emulation (except in TI Pro & Victor) - ANSI printer control added to VT102 emulator - Redefinable keys at Kermit-MS> prompt level - Control over display of 8-bit characters during CONNECT - Pause at end of screen during local TYPE - A simple way to make Alt = Meta, without many many SET KEY commands - Piped operation a la UNIX (e.g. "compress foo.bar | kermit send") - Transaction file logging. - A way to accept default values for omitted trailing fields in com- mands. - A better built-in help facility. 11.8. Program Organization Kermit-MS version 2 is composed of separate assembler source files, assembled separately, and linked together. The modules are: System/Device Independent: MSSKER.ASM Main program MSSSEN.ASM File sender MSSRCV.ASM File receiver MSSSER.ASM Server operation MSSFIL.ASM File i/o MSSCMD.ASM Command parser MSSTER.ASM CONNECT command MSSCOM.ASM Communications port buffering & flow control MSSSET.ASM SET, SHOW, and STATUS commands MSSFIN.ASM Dummy module to find the end of the data segment; must be linked LAST. MSSDEF.H Data structure definitions and equates System/Device Dependent: MSXxxx.ASM System-dependent code for system xxx MSYxxx.ASM Terminal emulation for system xxx MSZxxx.ASM More terminal emulation for system xxx The xxx is replaced by a 3-letter code for the particular system, e.g. IBM for the IBM PC family, RB1 for the Rainbow-100, etc. The modular organization allows easier modification of the program, quicker transfer of modified portions from system-to-system. The modules are designed to be well-defined and self-contained, such that they can be easily replaced. For instance, someone who prefers windows and mice to typing commands should be able replace the command parsing module without having to worry about the ef- fect on the other modules. To assemble any of the Kermit modules, file MSSDEF.H must be on the default disk. All the Kermit implementations require the modules MSSCMD, MSSCOM, MSSFIL, MSSKER, MSSRCV, MSSSEN, MSSSER, MSSSET, MSSTER, MSSFIN. MSSFIN must be linked last. MS-DOS KERMIT Page 207 Each particular implementation requires at least an MSXxxx module, and, if it is doing terminal emulation in software, also an MSYxxx and possible also an MSZxxx module. See the batch or make files from the source distribution for details of exactly which modules are required for a particular implementation. Once all the required object modules exist, they may be linked together to produce a Kermit program. For example, on the Rainbow: A>link Microsoft Object Linker V2.00 (C) Copyright 1982 by Microsoft Inc. Object Modules [.OBJ]: mssker msxrb1 msscom mssset msssen + mssrcv mssser mssfil msster msscmd mssfin Run File [MSSKER.EXE]: kermit List File [NUL.MAP]: A> 11.9. Running Kermit on New Systems You can bring Kermit-MS to systems that are not explicitly supported in one of two ways -- attempt to run the "generic" MS-DOS Kermit on it, or add explicit code to support your system. To get started with Kermit on a new system, try running "generic" MS-DOS Ker- mit; in many cases, it will run as is. The generic version accomplishes all its port and console i/o through DOS calls, and during terminal connection does not attempt to emulate any particular kind of terminal. In some cases, the generic version may still require some fiddling to run on a new system; for in- stance, different systems refer to their communication ports in different ways -- COM1, J1, AUX, etc. The SET PORT command allows you to specify the port using any of these device names, or using DOS file handles -- keep trying until you find the one that works. Generic MS-DOS Kermit will probably run no faster than 1200 baud, and it only works with DOS 2.0 or later. If you want to write code to explicitly support a new system, first call or write Kermit Distribution at Columbia to make sure no one else is already doing the same work. If you're the first, then begin by reading the file MSXAAA.DOC, provided with the MS-DOS Kermit sources in the Kermit distribution, which is a guide to the system dependent modules of Kermit-MS. Then create new a new MSXxxx.ASM module, and, if your version is also doing terminal emulation in software, also an MSY and possibly an MSZ module. MS-DOS KERMIT Page 208 11.10. IBM-PC MS Kermit Terminal Emulator Summary By Joe Doupnik, Utah State University This section summarizes the IBM PC Kermit-MS keyboard and screen operation during emulation of H19, VT52, and VT102 terminals. Note that spaces shown be- tween characters of escape sequences are there for ease of reading; the actual sequences contain no spaces. 11.10.1. Keyboard Layout and Characters Sent Here is how the keypad functions are assigned to the IBM keyboard function keys: --------------------------------------------------------------------------- Heath-19 and VT52 Keypads VT102 keypad IBM Keys IBM keys +------+------+-------+----------+ +------+------+------+------+ | Blue | Red | Grey | up arrow | | PF1 | PF2 | PF3 | PF4 | | F1 | F2 | F3 | up arrow | | F1 | F2 | F3 | F4 | +------+------+-------+----------+ +------+------+------+------+ | 7 | 8 | 9 |down arrow| | 7 | 8 | 9 | - | | F5 | F6 | F7 |down arrow| | F5 | F6 | F7 | F8 | +------+------+-------+----------+ +------+------+------+------+ | 4 | 5 | 6 | rgt arrow| | 4 | 5 | 6 | , | | F9 | F10 | SF1 | rgt arrow| | F9 | F10 | SF1 | SF2 | +------+------+-------+----------+ +------+------+------+------+ | 1 | 2 | 3 |left arrow| | 1 | 2 | 3 | E | | SF3 | SF4 | SF5 |left arrow| | SF3 | SF4 | SF5 | n S| +------+------+-------+----------+ +------+------+------+ t F| | 0------0 | . | Enter | | 0------0 | . | e 6| | SF7 | SF8 | SF6 | | SF7 | SF8 | r | +-------------+-------+----------+ +-------------+------+------+ SF1 means push Shift and F1 keys simultaneously --------------------------------------------------------------------------- Cursor Keys H-19 & VT52 VT102 VT52/H19 key IBM key All Modes Numeric Application up arrow up arrow ESC A ESC [ A ESC O A down arrow down arrow ESC B ESC [ B ESC O B right arrow right arrow ESC C ESC [ C ESC O C left arrow left arrow ESC D ESC [ D ESC O D MS-DOS KERMIT Page 209 Auxillary Keypad Heath-19 & VT52 VT102 VT52/H19 key IBM key Numeric Applic. Numeric Applic. PF1/HF7/Blue F1 ESC P ESC P ESC O P ESC O P PF2/HF8/Red F2 ESC Q ESC Q ESC O Q ESC O Q PF3/HF9/Grey F3 ESC R ESC R ESC O R ESC O R PF4/HF1 F4 ESC S ESC S ESC O S ESC O S 0 SF7 ESC ? p ESC O p 1 SF3 ESC ? q ESC O q 2 SF4 ESC ? r ESC O r 3 SF5 ESC ? s ESC O s 4 F9 ESC ? t ESC O t 5 F10 ESC ? u ESC O u 6 SF1 ESC ? v ESC O v 7 F5 ESC ? w ESC O w 8 F6 ESC ? x ESC O x 9 F7 ESC ? y ESC O y - (minus) F8 ESC ? m ESC O m , (comma) SF2 ESC ? l ESC O l (ell) . (period) SF8 ESC ? n ESC O n Enter SF6 ESC ? M ESC O M (SFn means hold down Shift key while pressing Function key n.) Other IBM keys operational in Connect mode: Del (White key) Send ASCII Del code (rubout). Backspace Send ASCII Del code (rubout). Shift BackSpace Send ASCII BS code (backspace). Keypad (Grey)+ Toggle mode line on/off (only if Mode Line is enabled). Alt - Toggle among Heath-19, VT52, and VT100 emulation. Alt = Clear screen and reset terminal emulator to starting (setup) state. Home Roll screen up (text down) to beginning of storage. End Roll screen down (text up) to end of storage. PgUp Roll screen up (back, earlier) one screen full. PgDn Roll screen down (forward, later) one screen full. Ctrl-PgUp Roll screen up one line. Ctrl-PdDn Roll screen down one line. Control PrtSc Toggle on/off copying of received text to printer, "PRN" shows on far right of mode line when activated. Control-End Dump image of screen to a disk file or device. Default filename is KERMIT.SCN in the current directory. Use command SET DUMP to change the filename. Screen images are appended to the file, separated by formfeeds. Shift-PrtSc Standard Print-screen, dump screen image to printer. "Alt -" means hold down Alt and type minus. This switches among the various kinds of emulation, but does not change most operating parameters of the MS-DOS KERMIT Page 210 emulator. CONNECT Escape Commands Type Kermit escape character (normally "^]"), then one of the keys below: ? display this short list. 0 send a null character. B send a BREAK signal. C close connect session & return to Kermit prompt. F dump screen to filespec, default is Kermit.scn. M toggle mode line on/off. P push to DOS. Q quit (suspend) logging. R resume logging. S show status. Kermit escape character itself: send it to the host. 11.10.2. Responses To Characters Received By the Terminal Emulator Unknown escape sequences of the form "ESC char" are absorbed by the emulator without further effect. DEC VT102 functions while in ANSI (VT102) mode, unsupported features marked by asterisk (*): Escape Seq Mnemonic Description of Action ESC D IND Index, moves cursor down one line, can scroll ESC E NEL Move cursor to start of line below, can scroll ESC H HTS Set one horizontal tab at current position ESC M RI Reverse Index, cursor up one line, can scroll ESC Z DECID Indentify terminal (response is ESC [ ? 6 c) ESC c RIS Reset terminal to initial state ESC = DECKPAM Enter keypad application mode ESC > DECKNPNM Enter keypad numeric mode ESC 7 DECSC Save cursor position and attributes ESC 8 DECRC Restore cursor from previously saved position ESC # 3 DECDHL Double height and width line, top half ESC # 4 DECDHL Double height and width line, bottom half ESC # 5 DECSWL Single height and width line ESC # 6 DECDWL Double width single height line ESC # 8 DECALN Screen alignment diagnostic - not supported ESC [ Pn A CUU Cursor up Pn lines, does not scroll ESC [ Pn B CUD Cursor down Pn lines, does not scroll ESC [ Pn C CUF Cursor forward, stays on same line ESC [ Pn D CUB Cursor backward, stays on same line ESC [ Pn; Pn H CUP Set cursor to row, column (same as HVP) ESC [ Ps J ED Erase in display: 0 = cursor to end of screen, inclusive 1 = start of screen to cursor, inclusive 2 = entire screen, reset lines to single width, cursor does not move. ESC [ Ps K EL Erase in line: MS-DOS KERMIT Page 211 0 = cursor to end of line, inclusive 1 = start of line to cursor, inclusive 2 = entire line ESC [ Pn L (VT102) Insert Pn lines preceding current line. ESC [ Pn M (VT102) Delete Pn lines from current downward, incl. ESC [ Pn P (VT102) Delete Pn chars from cursor to left, incl. ESC [ Pn; Pn R CPR Cursor report (row, column), sent by terminal Example: home position yields ESC [ 1; 1 R ESC [ Pn c DA Device attributes (reports ESC [ ? 6 c) ESC [ Pn; Pn f HVP Set cursor to row, column (same as CUP) ESC [ Ps g TBC Tabs clear, 0 = at this position, 3 = all ESC [ 20 h LNM Set newline mode (lf = cr/lf) ESC [ 20 l LNM Reset newline mode (lf = lf) ESC [ ? Ps;...;Ps h SM Set mode, see table below ESC [ ? Ps;...;Ps l RM Reset mode, see table below Ps mnemonic mode set reset 0 error (ignored) 1 DECCKM cursor keys application cursor/numeric 2 DECANM ANSI/VT52 ANSI/VT102 VT52 3 DECCOLM Columns *132 col 80 col 4 DECSCLM *Scrolling smooth jump 4 (VT102) Insert/Replace insert replace 5 DECSCNM Screen reverse video normal 6 DECOM Origin relative absolute 7 DECAWM Autowrap on off 8 DECARM *Autorepeat on off 9 DECINLM *Interlace on off 18 (VT102) *Printer termination character 19 (VT102) *Printer extent ESC [ Pn i (VT102) *Printer controls ESC [ ? Pn i (VT102) *Printer controls ESC [ Ps;...;Ps m SGR Select graphic rendition 0 = all attributes off (#'s 1, 4, 5, 7) 1 = bold, intensify foreground 4 = underscore (reverse video on IBM CGA) 5 = blink 7 = reverse video non-DEC extensions: 30-37 = foreground color = 30 + colors 40-47 = background color = 40 + colors colors: 1 = red, 2 = green, 4 = blue ESC [ Ps n DSR Device Status Report. Response from VT100: 0 = ready, 3=malfunction. Command to VT100: 5 = report status with DSR, 6 = report cursor position using CPR sequence. ESC [ Ps;...;Ps q DECLL Load LEDs, Ps=0 means clear LED#1-4 Ps = 1,2,3,4 sets LED # 1,2,3,4 ESC [ Pn; Pn r DECSTBM Set top and bottom scrolling margins ESC [ sol x DECREQTPARM Request terminal parameters, see table below ESC [ sol; par; nbits; xspeed; rspeed; clkmul; flags x DECREPTPARM Reports terminal parameters *sol = 0 request; term can send unsolicited reports - not supported sol = 1, request; term reports only on request sol = 2, this is a report (DECREPTPARM) MS-DOS KERMIT Page 212 sol = 3, terminal reporting only on request par = 1 none, 2 space, 3 mark, 4 odd, 5 even nbits = 1 (8 bits/char), 2 (7 bits/char) xspeed,rspeed = transmit & receive speed index 0,8,16,24,32,40,48,56,64,72,80,88,96,104,112,120 correspond to speeds of 50,75,110,134.5,150,200,300,600,1200,1800,2000,2400,3600,4800,9600,19200 baud clkmul = 1 (clock rate multiplier is 16) flags = 0-15 (Setup Block #5), always 0 here ESC [ 2; Ps y DECST *Confidence tests - not supported SCS Select character sets. ESC ( A SCS G0 points to UK symbols ESC ) A SCS G1 points to UK symbols ESC ( B SCS G0 points to ASCII symbols ESC ) B SCS G1 points to ASCII symbols ESC ( 0 SCS G0 points to special (line drawing) graphics ESC ) 0 SCS G1 points to special (line drawing) graphics ESC ( 1 SCS *G0 points to alt char ROM - not supported ESC ) 1 SCS *G1 points to alt char ROM - not supported ESC ( 2 SCS *G0 points to alt graphics ROM - not supported ESC ) 2 SCS *G1 points to alt grpahics ROM - not supported ^G BELL Sound VT102 style beep ^H BS Backspace, move cursor left one character ^I HT Horizontal tab, move cursor to next tabstop ^J LF Linefeed, move cursor down one line ^L FF Formfeed, treated as a line feed ^M CR Carriage return, move cursor to col 1 ^N SO Invoke usage of G1 character set ^O SI Invoke usage of G0 character set Other extensions: ESC [ ? 6 h ESC [ 25; Pc f VT52/VT100 move cursor to 25th line. ESC [ ? 6 h ESC [ 25; Pc H VT52/VT100 move cursor to 25th line. (These will disable Kermit's own status line.) ESC * char VT200 series graphics command, ignored. 11.10.3. DEC VT102 functions while in VT52 mode Escape seq Description of action ESC A Cursor up ESC B Cursor down ESC C Cursor right ESC D Cursor left ESC F Enter graphics mode ESC G Exit graphics mode ESC H Cursor home ESC I Reverse line feed ESC J Erase to end of screen ESC K Erase to end of line ESC Y row column Direct cursor address, offset from space ESC Z Identify (response is ESC / Z) ESC = Enter alternate keypad mode ESC > Exit alternate keypad mode ESC < Enter ANSI mode (changes to VT102) MS-DOS KERMIT Page 213 11.10.4. Heath-19 functions while in non-ANSI mode Escape seq Mnemonic Description of action ESC A HCUU Cursor Up ESC B HCUD Cursor Down ESC C HCUF Cursor Forward, can jump to next line ESC D HCUB Cursor Backward, can jump to previous line ESC E HCD Clear display ESC F HEGM Enter Graphics mode ESC G HXGM Exit Graphic mode ESC H HCUH Cursor Home ESC I HRI Reverse Index ESC J HEOP Erase to end of page ESC K HEOL Erase to end of line ESC L HIL Insert line ESC M HDL Delete line ESC N HDCH Delete character ESC O HERM Exit Insert Char mode ESC Y row col HDCA Direct cursor addressing, offset from space ESC Z HID Identify (responds ESC / K which is a VT52) ESC b HBD Erase Beginning of display ESC j HSCP Save cursor position ESC k HRCP Set cursor to saved position ESC l HEL Erase entire line ESC n HCPR Cursor Position Report request ESC o HEBL Erase beginning of line ESC p HERV Enter Reverse Video mode ESC q HXRV Exit Reverse Video mode ESC r Bn HMBR *Modify baud rate - not supported ESC t HEKS *Enter Keypad shifted mode, not supported ESC u HXKS *Exit Keypad shifted mode, not supported ESC v HEWA Wrap around at end of line ESC w HXWA Discard at end of line ESC x Ps HSM Set Mode. See table below ESC y Ps HRM Reset Mode. See table below Ps Mnemonic Mode Set Reset 1 HSM/HRM 25th line enabled disabled 2 *keyclick off on 3 *holdscreen enabled disabled 4 cursor type block underl. 5 *cursor on/off on off 6 *keypad shifted shifted unshiftd 7 alt app keypad enabled disabled 8 *linefeed CR=CRLF just CR 9 newline mode enabled disabled ESC z HRAM Reset to power-up configuration ESC = HAKM Enter Alternate Keypad mode ESC > HXAM Exit Alternate Keypad mode ESC < HEAM Enter ANSI mode (ESC [ stuff) ESC @ HEIM Enter Insert Char mode ESC [ HEHS *Enter Hold Screen mode, not supported ESC \ HXHS *Exit Hold Screen mode, not supported ESC { and } HEK, HDK *Keyboard enable/disable, not supported ESC ] HX25 *Transmit 25th line, not supported MS-DOS KERMIT Page 214 ESC # HXMP *Transmit page, not supported Heath-19 functions while in ANSI mode Escape Seq Mnenonic Description of Action ESC [ s PSCP Save cursor position & attributes ESC [ u PRCP Restore cursor position & attributes ESC [ z PRAM Reset to power-up configuration ESC [ 2 J ED Erase entire screen but do not move cursor; regular Heath-19 moves cursor to Home. ESC [ ? 2 h PEHM Revert to normal Heath-19 non-ANSI mode ESC [ > Ps h SM Same as ESC x Ps ESC [ > Ps l RM Same as ESC y Ps Plus most of the ANSI escape sequences listed for the VT102. CP/M-80 KERMIT Page 215 12. CP/M-80 KERMIT Program: Bill Catchings, Columbia University, with contributions from Charles Carvalho (ACC), 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: 4.05 Date: February 1985 Documentation: Charles Carvalho, ACC; Frank da Cruz, Columbia KERMIT-80 Capabilities At A Glance: Local operation: Yes Remote operation: No Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Z interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: No Alternate block checks: Yes Terminal emulation: Yes, VT52 and others Communication settings: Yes; duplex, parity Transmit BREAK: Yes; some versions IBM communication: Yes Transaction logging: No Session logging (raw download): Yes Raw upload: Yes Act as server: No Talk to server: Yes; SEND, GET, FIN, BYE Advanced commands for servers: No Local file management: Yes; DIR, ERA, SET DEFAULT disk Handle file attributes: No Command/init files: No Printer control: Yes, limited 12.1. 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. CP/M-80 KERMIT Page 216 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. 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; sets and displays IOBYTE. 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. 12.2. Kermit-80 Description 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 processor and other factors that can vary from system to system. CP/M-80 KERMIT Page 217 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 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 works exactly like Control-X. Carriage Return If you type a carriage return Kermit-80 will resend the current packet. You may do this repeatedly, up to the packet retry limit (somewhere between 5 and 16 times) for a particular packet. 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". CP/M-80 KERMIT Page 218 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. ^] (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 by adding "&" characters to the name. GET filespec When Kermit-80 is talking to a Kermit Server on the host, you should use the GET command to request the server to send files to you, for ex- ample: get hlp:k*.hlp Limitation: If you request an alternate block check type using the SET BLOCK command, the GET command will not communicate it to the remote server. If you want to have type 2 or 3 block checks done when getting files from the server, you have to issue the appropriate SET BLOCK com- mand to the remote KERMIT before putting it in server mode. 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. CP/M-80 KERMIT Page 219 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. VERSION Show the name, edit number, and edit date of several of the modules that make up Kermit-80. SET parameter [value] Set the specified parameter to the specified value. Possible settings: WARNING ON (or OFF) Warn user of filename conflicts when receiving files from remote host, and attempt to generate a unique name by adding "&" characters to the given name. 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; see table 12-3. 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-RATE Change the baud rate of the communications port. This command only works on some systems. value is the numeric baud rate (300, 9600, etc.) desired. Type SET BAUD followed by a ques- tion mark for a list of supported baud rates. On systems that do not support 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. If you set parity to anything other than none, KERMIT-80 will attempt to use "8th bit prefixing" to transfer binary files. If the other KERMIT is also capable of 8th bit prefixing, then binary files can be transferred suc- cessfully; if not, the 8th bit of each data byte will be lost (you will see a warning on your screen if this happens). TIMER ON (or OFF) Enable or disable the "fuzzy timer". The timer is off by default, because in the normal case KERMIT-80 is communicating CP/M-80 KERMIT Page 220 with a mainframe KERMIT that has its own timer. Mainframe KER- MIT timers tend to be more precise or adaptable to changing conditions. You should SET TIMER ON if you are communicating with a KERMIT that does not have a timer. You should SET TIMER OFF if you are communicating over a network with long delays. 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. As dis- tributed, KERMIT-80 uses MARK parity for IBM communication. If you don't give this command, IBM mode is OFF. Since IBM VM/CMS KERMIT does not have timeout capability, SET IBM ON also turns on the "fuzzy timer" automatically. 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. 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 all the 128-byte blocks of the file, including the last block in its entirety; SET FILE ASCII is used for text files, and transmission stops when the first Control-Z is en- countered anywhere in the file (this is the CP/M convention for marking the end of a text file). SET FILE DEFAULT tells Kermit to attempt to determine the file type by examining the file be- ing transmitted. If a Control-Z appears before the last block of the file, it is assumed to be BINARY; if, when the first Control-Z is encountered, the remainder of the file contains only control-Z's, it is assumed to be a text file. Unfor- tunately, not all programs fill the remainder of the last record of a text file with Control-Z's, so this algorithm is not always successful. 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 it happens to contain any data bytes that correspond 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 CP/M-80 KERMIT Page 221 causes you to switch to the specified disk and log it in, write-enabled. The colon must be included in the disk name (A:). 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. Type SET PORT ? for a list of valid options for your system. PRINTER ON or OFF. Turns copying of CONNECT session to printer on and off. No attempt is made to do buffering or flow control; Ker- mit assumes the printer can keep up. DEBUG ON or OFF. Enables/disables displaying of packets on the screen during file transfer. DIRECTORY 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. ERASE This executes the CP/M ERA command on the specified file(s). The names of the files being erased are not displayed. 12.3. Kermit-80 Flavors Many of the systems supported use an external terminal, rather than a built-in console. Kermit may be further customized for these systems by defining (at assembly time) the terminal type to be used. If the terminal type is unknown or does not match any of the existing terminal options, the generic "CRT" op- tion may be selected. In this case, Kermit cannot do fancy screen control during file transfer; it simply types the file names, packet numbers, and mes- sages 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. If no specific terminal has been selected, Kermit can- not do VT52 emulation; it can act as a "dumb terminal" (sometimes called a "glass TTY"), or else its own built in terminal firmware provides cursor con- trol functions independent of the Kermit program. 12.3.1. Generic Kermit-80 "Generic Kermit-80" is an implementation of Kermit that should run on any 8080- compatible CP/M 2.2 system with 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. All I/O is done with standard CP/M BIOS calls, and I/O redirection is done using the CP/M IOBYTE function, which, ac- cording 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 Page 222 tems that implement IOBYTE do so in the same way. The SET PORT command may be used to select the devices to be used for input and output. Table 12-1 lists the options to the SET PORT command and their effects. ------------------------------------------------------------------------- SET PORT xxx input from output to CRT CRT: CRT: PTR PTR: PTP: TTY TTY: TTY: UC1 UC1: UC1: UR1 UR1: UP1: UR2 UR2: UP2: Table 12-1: Kermit-80 SET PORT Options ------------------------------------------------------------------------- The default is SET PORT PTR. In all cases, the console (CON:) and list (LST:) devices used are those selected when Kermit is started. 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. In addition, many features of Kermit require more specific knowledge of the hardware involved -- Generic Kermit cannot send a BREAK signal, or change the baud rate. 12.3.2. CP/M 3 Kermit CP/M 3 Kermit should run on most CP/M 3 (CP/M-Plus) systems. It uses the auxilliary port (AUX:) to communicate to the remote Kermit. The SET BAUD and SET PORT commands are not supported; nor can a BREAK be sent. Like Generic Kermit, a terminal may be selected at assembly time. 12.3.3. System-Specific Versions There are also many versions of Kermit-80 tailored to specific systems. Most of these operate uniformly, but some of them take advantage (or suffer limitations) of the specific system. Here are some of the special features for particular systems: Apple II -- two variations: APMMDM: Apple with Z80 Softcard and Micromodem II in slot 2 Dialout capability provided in connect command; user is prompted for phone number if car- rier is not present. During connect mode, ^]D drops carrier. BYE com- mand also causes carrier to be dropped. AP6551: Apple with Z80 Softcard, and one of several 6551-based communication cards; the slot number is a compile-time parameter (default is slot 2). CP/M-80 KERMIT Page 223 SET BAUD-RATE supported; speeds are 110-19200 baud. BigBoard II: Uses serial port A. To use port B, change mnport, mnprts, and baudrt and reassemble. Can generate BREAK. SET BAUD-RATE supported; speeds are 300-38400 baud. Digicomp Delphi 100: SET BAUD-RATE supported; speeds are 50-19200 baud. CPT-85xx word processors: Can generate BREAK. SET BAUD-RATE supported; speeds are 50-9600 baud. DEC DECmate II word processor (with Z80 card): Can generate BREAK. DEC VT180 (Robin): Three output ports, referred to as COMMUNICATIONS, GENERAL, and PRINTER. Can generate BREAK. Intertec SuperBrain: SET BAUD-RATE supported; speeds are 50-19200 baud. Kaypro: Should work on most Kaypro models, as well as some related systems (Ferguson BigBoard I, Xerox 820). For the newer Kaypros with multiple ports, Kermit uses the one labeled "serial data"; it cannot use the serial printer or internal modem ports (but it should be possible to modify the values for mnport, mnprts, and baudrt to do this). Can generate BREAK. SET BAUD-RATE supported; speeds are 50-19200 baud. Morrow Decision I: Uses the Multi-I/O board. Port 1 is the console, port 3 is the communica- tions line. SET BAUD-RATE supported; speeds are 75-56000 baud. Nokia MicroMikko: Will not echo control-O (which locks keyboard). SET BAUD-RATE supported; speeds are 75-9600 baud. Ohio Scientific: Doesn't have screen control. Osborne 1:Uses serial line, not internal modem. Left-arrow key generates ("delete" or "rubout" character) during connect mode. SET BAUD-RATE sup- ported; speeds are 300 and 1200 baud. TRS-80: Two versions, one for Lifeboat CP/M, one for Pickles & Trout CP/M. 12.4. Installation of Kermit-80 Kermit-80 was written originally for the Intertec SuperBrain in lowest-common- denominator 8080 code with the standard assembler, ASM (single source module, no macros, no advanced instructions), so that it could be assembled on any CP/M-80 system (the 8080 assembler is distributed as a standard part of CP/M-80, whereas the fancier Z80 or macro assemblers are normally commercial products). It has since been modified to run on many other systems as well. CP/M-80 KERMIT Page 224 Kermit-80 should be able to run on any 8080-, 8085- or Z80-based microcomputer under CP/M with appropriate minor changes to reflect the port i/o and screen control for the system (see below). The proliferation of new systems supported by Kermit-80 made the program grow so large and complicated that it had to be broken up into system-independent and system-dependent modules, as of version 4 (this was done by Charles Car- valho of ACC). Each module is composed of multiple files. This has reduced the time and disk space necessary for assembly; Kermit-80 may once again be as- sembled on a CP/M system with roughly 150Kbytes of space. The majority of the code does not need to be reassembled to support a new system. Unfortunately, it can no longer be assembled with ASM, since ASM does not support multiple in- put files. To allow it to be assembled on any CP/M system, the public-domain assembler LASM is included in the distribution kit; Kermit-80 may also be as- sembled with Microsoft's M80 (not supplied), or cross-assembled on a DEC-10 or DEC-20 with MAC80 (also supplied in the distribution kit). In theory, any 8080 assembler supporting the INCLUDE directive ought to work, as well. All versions of Kermit-80 are assembled from the same set of sources, with sys- tem dependencies taken care of by assembly-time conditionals within the system- dependent module (eventually, the system-dependent module will itself be broken up into multiple files, one for each system). The most important system depen- dencies 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. 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 versions 3.8 and later include 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. 12.4.1. Organization of Kermit-80 Kermit-80 consists of two modules, each of which is generated from multiple source files. The first module contains the system-independent code; the second module is configured for a particular system and merged with the system- independent module to produce a customized Kermit-80. The distribution kit contains: - the system-independent module, CP4KER.HEX; - the system-dependent modules, CP4*.HEX (see table 12-2); CP/M-80 KERMIT Page 225 - the source files, CP4*.ASM, - the DEC-10/DEC-20 cross-assembler and linker, MAC80.* and LINK80.*, - the public-domain CP/M assembler, LASM.*, - the public-domain CP/M load/patch utility, MLOAD.* ------------------------------------------------------------------------------- Symbol Filename System AP6551 CP4APL Apple II, Z80 Softcard, 6551 ACIA in serial interface APMMDM CP4APM Apple II, Z80 Softcard, Micromodem II in slot 2 BBII CP4BB2 BigBoard II (terminal required) BRAIN CP4BRN Intertec SuperBrain. CPM3 CP4CP3 "generic": CP/M 3.0 (CP/M Plus) systems (terminal req'd) DELPHI CP4DEL Digicomp Delphi 100 (terminal required) DMII CP4DM2 DECmate II with CP/M option GENER CP4GEN "Generic": CPM 2.2 systems with IOBYTE (terminal req'd) HEATH CP4H89 Heath/Zenith H89. KPII CP4KPR Kaypro-II (and 4; probably supports all Kaypro systems) MDI CP4MDI Morrow Decision I (terminal required) MIKKO CP4MIK MikroMikko MMDI CP4UDI Morrow Micro Decision I (terminal required) OSBRN1 CP4OSB Osborne 1 OSI CP4OSI Ohio Scientific ROBIN CP4ROB DEC VT180 TELCON CP4TEL TELCON Zorba portable TRS80LB CP4TLB TRS-80 model II with Lifeboat 2.25C CP/M Display TRS80PT CP4TPT TRS-80 model II with Pickles + Trout CP/M Display VECTOR CP4VEC Vector Graphics. Z100 CP4Z00 Z-100 under CP/M-85 "symbol" is the symbol used to select the target system, in CP4TYP.ASM; "filename" is the name under which the module is supplied in the distribution. Table 12-2: Systems supported by Kermit-80 ------------------------------------------------------------------------------- 12.4.2. Downloading Kermit-80 You'll need either a pre-configured .COM file or the system-independent module, CP4KER, in binary (.COM) or hex (.HEX) format and the system-dependent overlay for your system (from table 12-2). If your system is not listed in the table, get the generic CP/M 2.2 Kermit or the generic CP/M 3 Kermit. 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 files. Transfer the files to your system and skip ahead to "merging the modules". 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 necessary "hex" files into your micro's memory and then save it on the disk. If you have a terminal emulator program on your CP/M-80 KERMIT Page 226 micro which can save a copy of the session to disk, connect to your host, and type the necessary files. Exit from the emulator, saving the session log, and edit the session log to extract the hex files. Skip ahead to "merging the files". 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 charac- ter 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 the prompt 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 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. Begin by typing in the following assembly language program, FETCH.ASM. This program provides unguarded text capture into memory. It begins by transmitting a carriage return to the host, then stores every character received in memory, until it receives an "@" character, at which point it stores the captured data on disk. The biggest file it can capture is about 40K. The program assumes RDR/PUNCH are aimed at the communication port and set at the appropriate baud rate, and there's sufficient free space on the disk. On most micros, FETCH cannot work successfully at baud rates above 1200. Note that this program only works for files that do not contain the "end" character. Since hex files do not contain atsign, period, dollar sign, per- cent, or other common prompt characters, this program should work for hex files on almost any system, but not for arbitrary text files. When entering the program, you don't have to type the comments. ;Originally by Bill Catchings, Columbia University ;Fixed and translated to assembler, 22-May-86, Bernie Eiben, DEC ; ORG 100H ;let's start at a standard address MEMADR equ 300H ;Where we start storing bytes MEMOFF equ 2H ;Linked to MEMADR [offset in 2 sector pai MEMST equ MEMADR-2 ;We 'swallow' first two bytes BYTPTR equ 200H ;Here we keep the pointer BYTHI equ BYTPTR+1 ;High order byte BYTLOW equ BYTPTR ;Low order byte DMAPTR equ BYTPTR+2 ;Sector pointer to write SECLEN equ 80H ;128 bytes are a 'sector' SEVBIT equ 7FH ;parity mask MONE equ 0FFFFH ;Minus one in 16 bits BDOS equ 5H ;System call Punch equ 4H ;Send to Punch {to Host} Reader equ 3H ;Read from Reader {from Host} Screen equ 2H ;Write to screen CLSFIL equ 10H ;Close file WRTSEC equ 15H ;Write a sector MAKFIL equ 16H ;Write NEW file SETDMA equ 1AH ;Set DMA address CP/M-80 KERMIT Page 227 FCB1 equ 5CH ;File Control Block 1 CR equ 0DH ;ASCII Carriage Return CTRLZ equ 1AH ;ASCII Control-Z ;Note--The following may need to be changed when downloading from other ;systems, e.g. to '.' for TOPS-10, '$' for VAX/VMS, etc. Alternatively, ;the hex file itself can have an '@' added to it, after its last line. ENDSIG equ 40H ;DEC-20 prompt '@' ;Here's the program: start: lxi h,MEMST ;Where to store in memory shld BYTPTR ;keep address there mvi e,CR ;oct 15 is CR mvi c,PUNCH ;Output to PUNCH {send to HOST} call BDOS gbyte: mvi c,READER ;Input from RDR {read from HOST} call BDOS ani 7FH ;mask to 7-bit {strip parity} push psw ;save a and flags mov e,a ;char to e for echo-call mvi c,SCREEN ;Output to screen call BDOS pop psw ;restore a and flags cpi ENDSIG ;End signal (system's prompt)? jz donfil ;Yes, we have whole file in memory call stuff ;No, store byte jmp gbyte ;go back for next byte donfil: mvi a,CTRLZ ;Control-Z is EOF call stuff ;Store Control-Z lxi h,MEMADR ;Pointer to file in memory shld DMAPTR ;Save here for DMA pointer ;a long divide by 256 follows lda BYTHI ;get HI byte sta BYTLOW ;store as low byte xra a ;zero a sta BYTHI ;wipe old HI byte mvi c,MAKFIL ;MAKE new FILE lxi d,FCB1 call BDOS again: call nsect ;write 128 bytes call nsect ;and another 128 bytes lxi h,MONE ;stick a -1 xchg ;into DE lhld BYTPTR ;get modified pointer (per 256 bytes) dad d ;decrement shld BYTPTR ;and store back mvi a,MEMOFF ; getting cmp l ; done ? jz done ;Yes, we hit it on the nail jmp again ;Not quite CP/M-80 KERMIT Page 228 nsect: lhld DMAPTR ;Get the file-pointer xchg ;move into DE mvi c,SETDMA ;Set DMA call BDOS mvi c,WRTSEC ;Write sector to file lxi d,FCB1 call BDOS lhld DMAPTR ;Get the file-pointer lxi d,SECLEN ;128 bytes got moved dad d ;add them to adjust pointer shld DMAPTR ;and save again ret ;and return stuff: lhld BYTPTR ;Get the pointer mov m,a ;store the character inx h ;Increment the pointer shld BYTPTR ;and save again ret ;and return done: mvi c,CLSFIL ;Close file lxi d,FCB1 call BDOS jmp 0 ;Do warm-reboot to always come back END START After saving FETCH.ASM on the disk, assemble it using ASM or LASM, and then load it using LOAD or MLOAD: ASM FETCH LOAD FETCH or LASM FETCH MLOAD FETCH Now follow these steps: 1. On your micro, connect to a floppy disk with plenty of free space. 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. Give any commands necessary to disable system messages, line wrap, and so forth, to prevent corruption of the hex file. 3. Tell the host to display the first hex file (the system-independent module) at your terminal. On most systems, the command would be "TYPE CP4KER.HEX", but typed without a terminating carriage return. 4. Return to your micro. Make sure your IOBYTE is set so that RDR: and PUN: correspond to the I/O port that is connected to the host (this would normally be the case unless you have done something special to change things). CP/M-80 KERMIT Page 229 5. Run the FETCH program to get the system-independent hex file: FETCH CP4KER.HEX The FETCH program will display the file on your screen as it is be- ing captured. If there is any obvious corruption, you will probably notice it. When the display stops, there should be a file CP4KER.HEX on your disk. 6. Return to the host, and tell it to display the second hex file (the system-dependent module for your configuration). Again, do not type the terminating carraige return. For example, to get the Kaypro-II hex file, "type cp4kpr.hex". 7. Return to your micro, and run the capture program again: FETCH CP4KPR.HEX Now there should be a file CP4KPR.HEX on your connected disk. Merging the files: 1. For purposes of illustration, we will assume the system-dependent overlay is called "cp4kpr.hex". The two hex files may be combined with MLOAD or DDT. If you already have a running Kermit, you can transfer MLOAD.HEX to your system and create MLOAD.COM by running LOAD. If you're bootstrapping Kermit, you could transfer MLOAD.HEX to your system the same way you got the other two .HEX files, but it's probably simpler to use DDT to get Kermit running, and get MLOAD later if you need it. 2. Using MLOAD, the two pieces may be easily merged: A>mload kermit40=cp4ker,cp4kpr [some messages about program size, etc.] A> 3. If you don't have MLOAD running, it's a bit more complex: A>ddt cp4ker.hex NEXT PC 3500 0100 -icp4kpr.hex -r NEXT PC xxxx 0000 -^C A>save dd kermit40.com The page count ("dd") used in the SAVE command is calculated from the last address ("xxxx") given by DDT in response to the R command: drop the last two digits and add 1 if they were not zero, then con- vert from hexadecimal (base 16) to decimal (base 10): 384F becomes 39 hex, which is 57 decimal (3 times 16 plus 9) -- but 3700 becomes 37 hex, or 55 decimal (consult an introductory computing book if you don't understand number base conversion). CP/M-80 KERMIT Page 230 4. Note that CP/M hex files have checksums on each line. If there were any transmission errors during the downloading process, LOAD or MLOAD will notice a bad checksum and will report an error (something like "Illegal Format"). If you get any errors during loading, ei- ther fix the hex file locally with an editor, or repeat the trans- fer. You now should have a running version of Kermit-80, called KERMIT40.COM. Test your new Kermit by running it. If it gives you a prompt, it might be OK. (don't delete your old one yet...). Instead of a prompt, you could get one of two messages indicating that the configuration information is invalid: ?Kermit has not been configured for a target system or ?Consistency check on configuration failed Of course, neither of these messages should appear if you're building Kermit from the distribution kit. The first message indicates that the overlay was not found where the system-independent module expected to find it, probably be- cause the overlay address is incorrect; the second indicates that the version of CP4LNK used in the system-dependent module is incompatible with the system- independent module. Once you are satisfied that KERMIT40 works correctly, you should rename your old KERMIT.COM to something else, like OKERMIT.COM, and rename KERMIT40.COM to KERMIT.COM. 12.4.3. Assembling Kermit-80 from the sources Kermit-80 is built in two pieces from the following 12 files: The system-independent files: CP4KER.ASM header file CP4DEF.ASM definitions for both KERMIT and KERSYS CP4MIT.ASM initialization, main loop, miscellaneous commands (BYE, EXIT, LOG, SET, SHOW, STATUS, and VERSION) CP4PKT.ASM the KERMIT protocol handler (SEND, RECEIVE, LOGOUT, and FINISH commands) CP4TT.ASM the transparent commands (TRANSMIT, CONNECT) CP4CPM.ASM CP/M commands (DIR, ERA) CP4WLD.ASM the wildcard handler CP4CMD.ASM the command parser CP4UTL.ASM utility routines and data CP4LNK.ASM linkage area description The system-dependent files: CP4TYP.ASM system selection CP4SYS.ASM system-specific code The system-independent module contains all of the system-independent files ex- cept for CP4LNK.ASM, which is assembled into the system-dependent module to provide the structures needed to connect the two modules. As distributed, the CP/M-80 KERMIT Page 231 system-independent module is named CP4KER.HEX. If you have a copy of CP4KER.HEX, you do not need to reassemble the system-independent module to con- figure Kermit for your system. The system-dependent module consists of CP4TYP.ASM, CP4DEF.ASM, CP4LNK.ASM, and CP4SYS.ASM. One copy of the system-dependent module is supplied already as- sembled for each supported system; the filename may be obtained from table 12-2. After assembling the two pieces separately, they are combined with DDT or MLOAD into a system-specific Kermit. If you want to rebuild the system-independent module, the only change you may need to make is to select the assembler to be used, in CP4KER.ASM. Define one of MAC80, M80, or LASM to TRUE to select it as the assembler; the others should be defined FALSE. Assuming you have the Microsoft Macro Assembler package (M80/L80), you'll need to do the following: A>m80 cp4ker=cp4ker.asm A>l80 /p:100,cp4ker,cp4ker/n/e This will produce CP4KER.COM. If you are using LASM instead, do this: A>lasm cp4ker LASM will generate CP4KER.HEX and CP4KER.PRN. LASM allows options to be specified in the same way as the standard assembler, ASM, so the command A>lasm cp4ker.abz will read the source files from drive A, send the .HEX file to drive B, and suppress the listing file. If you have access to a TOPS-10 or TOPS-20 system, you can cross-assemble Ker- mit there with MAC80, producing CP4KER.HEX: .run mac80 *=cp4ker.asm If you want to generate a system-dependent overlay for a particular system, or want to change the terminal supported, you'll need to check three areas in CP4TYP.ASM: First, the overlay start ADDRESS. The symbol "ovladr" is EQUated to the ad- dress of "LNKFLG" in the system-independent module, as the starting address of the overlay (3400H for version 4.05). You'll need to know this value if you're building the overlay with M80/L80. You won't normally need to change this value. Second, the assembler being used. Again, define one of MAC80, M80, and LASM to be TRUE to select it, and define the others to be FALSE. The two modules (system-independent and system-dependent) do not need to be built with the same CP/M-80 KERMIT Page 232 assembler. Third, the system configuration. Locate your system in table 12-2, then define the appropriate symbol TRUE, and the rest FALSE. If the system comes with a builtin console terminal, define all the terminal switches FALSE. If the sys- tem uses an external terminal as the console, locate the terminal in table 12-3 and define the appropriate symbol TRUE, and the remainder FALSE. If the ter- minal is not listed in table 12-3, use the CRT switch; in this case, VT52 emulation is not supported. In addition, there are a few general and system-specific symbols which may be altered to fit your system: APSLOT For Apple with 6551 ACIA, defines the slot number of the serial card CPUSPD Processor speed in units of 100KHz (currently used only for bbII and kpII for timing loops) TAC For users connecting through ARPAnet TACs: set to TRUE if you wish the default TACTRAP status to be ON. (This may be overrid- den with the SET TACTRAP command). If you're not connecting through a TAC, set tac to FALSE and ignore tacval. TACVAL For ARPANET TAC users: defines the default TAC intercept character (may be overridden with the SET TACTRAP command) If you are just assembling an existing configuration, you'll need to edit CP4TYP.ASM only. If you are adding support for a new system, you should not modify CP4DEF.ASM or CP4LNK.ASM; if you do, you'll have to change the system- independent module also. Eventually, CP4SYS.ASM will be split into separate files, each of which will generate one or more related systems. When this hap- pens, you'll want to pick the one closest to your system to use as a starting point. After editing CP4TYP.ASM as necessary, assemble and link the overlay as fol- lows: - With M80 (where "xxxx" is the hex value of ovladr from CP4LNK.ASM): A>m80 cp4typ=cp4typ.asm A>l80 /p:xxxx,cp4typ,cp4typ/n/x/e - With LASM: A>lasm cp4typ - With MAC80 on TOPS-10: .run mac80 *=cp4typ.asm - With MAC80 on TOPS-20: @run mac80 *=cp4typ.asm CP/M-80 KERMIT Page 233 The overlay (cp4typ.hex) may then be merged with the system-independent module as described above (creating a runnable Kermit from the distribution kit). If you have a TOPS-10 or TOPS-20 system and already have a running Kermit-80 v3.9 or later, you can merge the two .HEX files into a .COM file with LINK80, and transfer the new .COM file to your micro with Kermit: - Tops-10: .copy kernew.hex=cp4ker.hex,cp4typ.hex .link80 kernew - Tops-20: @append cp4ker.hex,cp4typ.hex (to) kernew.hex @link80 kernew producing KERNEW.COM. If LINK80 says "?Data overlaid", you have an old version of LINK80, and will have to transfer the .HEX files to the micro and merge them there. ------------------------------------------------------------------------------- Symbol Terminal description crt Basic CRT, no cursor positioning adm3a ADM3A Display or lookalike smrtvd Netronics Smartvid-80 tvi925 TVI925, Freedom 100 vt52 VT52 or VT52 emulator such as Heath H19, H29, etc. vt100 VT100 or emulator (most ANSI terminals should work) Table 12-3: Terminals known to Kermit-80 ------------------------------------------------------------------------------- 12.5. Adding Support For A New System Kermit-80 is built from a common set of source files; the system-dependent module makes heavy use of conditional assembly (this complication will be removed in future releases). The system dependencies arise from attempts to answer some questions: 1. What kind of terminal is to be supported? For many micros, the console is an integral part of the system, but others can use an external terminal. In either case, the commands to manipulate the screen (position the curser, erase the screen, etc) must be defined. 2. How is the serial line accessed? For systems supporting the IOBYTE function, this is straightforward; the symbol "IOBYT" is defined TRUE. If the serial line is accessed with IN and OUT instructions, it may be possible to use the simple CP/M-80 KERMIT Page 234 I/O routines provided. In this case, the symbol "INOUT" is defined TRUE, the MNPORT and MNPRTS are defined to be the data and control addresses, respectively, and bit masks for testing for "input data available" and "output buffer empty" must be defined. If the inter- face is strange, leave IOBYT and INOUT set to FALSE, and provide the I/O routines. 3. What initialization is necessary? You may wish to set the baud rate or configure the serial line at startup. Examples for a number of devices are present. 4. What special features are to be supported? You may want to provide the capability to select one of several serial lines with the SET PORT command, or to change the speed of the serial line with the SET BAUD-RATE command. To do this, you'll need to build a command table, using the systems already supported as examples. The ability to send a BREAK signal is desirable. Again, examples for several different interfaces (ACIA, SIO, etc) are present. 12.6. Notes on New Features in Kermit-80 Version 4 Debugging aids: SET DEBUG ON will add two fields to the SEND/RECEIVE display, labelled "Spack" and "Rpack". These display the last packet sent and received. Of course, this slows down the transfer, especially if the console is an exter- nal terminal. SET DEBUG OFF removes these fields. The VERSION command dis- plays the name, edit number, and edit date of several of the modules that make up Kermit. TAC support: ARPAnet TACs (and many other communication devices such as ter- minal concentrators, modems, port contention units, network PADs, etc) use a printing character (normally "@") as an intercept character, to allow commands to be issued to the TAC. In order to send this character to the host, it must be typed twice. The command "SET TAC CHARACTER" to Kermit enables the TACtrap and asks the user to specify the TAC intercept character. This character will be automatically doubled when it appears in Kermit protocol messages (sent by the SEND or RECEIVE commands) or when it appears in a file being sent with the TRANSMIT command. It is not automatically doubled when typed by the user in CONNECT mode. "SET TAC ON" enables the TACtrap but does not change the TAC in- tercept character, which is initially "@". "SET TAC OFF" disables the TACtrap. (These comments apply equally to any communication device that uses a printable attention character which it will pass through if doubled.) File buffering: Previous versions of Kermit-80 buffered only one sector (128 bytes) at a time during file transfer operations. This version buffers 16Kbytes at a time, reducing the number of times the floppy drive must be spun up and down, and increasing the effective throughput of the link. If the disk transfer rate is too slow, however, the remote Kermit may time out and retransmit packets. This will show up on the screen in the "Retries:" field; if this occurs after disk activity, you may want to increase the timeout value on the remote Kermit, or reassemble Kermit with a smaller value for MAXSEC (in CP4SYS.ASM). This buffer is also used by the TRANSMIT command; the log file enabled by the LOG command is still written a sector at a time. CP/M-80 KERMIT Page 235 12.7. Future Work Work that needs to be done in future releases includes: - Merge in support for additional CP/M-80 systems, particularly those for which support was recently added to the monolithic v3.x source. - Break up CP4SYS into discrete source files, one for each system. These source files should serve as simple models for adding support for new systems to Kermit-80 -- only the very basic screen defini- tions, flags, i/o primitives, initializations, and so forth should appear in each system-dependent file. Even better would be to struc- ture CP/M-80 Kermit like MODEM, so that Kermit can use the MODEM overlays, which support many more systems, terminals, and modems than does Kermit. - Make the file-stepping mechanism faster (buffer the FCB's in chunks th of 16 or 32 or 64). Currently, to access the n file in a directory requires n(n+1)/2 lookups... - Addition of missing features -- compression of repeated characters during packet transmission, transmission of file attributes (particularly size, so that "percent done" can be displayed for both incoming and outbound files), advanced commands for servers (REMOTE DIRECTORY, etc), command macros and initialization files, login scripts, remote operation and server mode, etc etc. CP/M-86 KERMIT Page 236 13. CP/M-86 KERMIT Authors: Bill Catchings, Columbia University; Ron Blanford, University of Washington; Richard Garland, Columbia University. Language: Digital Research ASM86 Version: 2.9 Date: December 1984 Documentation: Frank da Cruz, Columbia This version of KERMIT 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. CP/M-86 KERMIT-86 Capabilities At A Glance: Local operation: Yes Remote operation: No Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Y interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: No Alternate block checks: No Terminal emulation: Yes, uses PC firmware (VT100) Communication settings: Yes; duplex, parity Transmit BREAK: Yes IBM communication: Yes Transaction logging: No Session logging (raw download): Yes Raw upload: No Act as server: No Talk to server: Yes; SEND, GET, FIN, BYE Advanced commands for servers: No Local file management: Yes Handle file attributes: No Command/init files: Yes Printer control: No CP/M-86 KERMIT DESCRIPTION Since Kermit-86 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-86 is capable of timing out an input request, and can thus break deadlocks automatically. In most cases, however, this is not desirable because the KER- MIT on the other side is most likely better able to handle the timeouts; there- fore, Kermit-86's timer is normally not used. 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 long CP/M-86 KERMIT Page 237 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 intervention. File transfers may be interrupted in several ways. Control-C This will return you to Kermit-86 command level immediately, so 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-86 will go on to the next one. When receiving a file, KERMIT-86 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 either 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 works exactly like Control-X. Carriage Returns If you type carriage return repeatedly Kermit-86 will retry the current packet up to its retry limit (somewhere between 5 and 16 times) and then, if no valid response was received, return to Kermit-86 command level. When KERMIT-86 is started, it looks for the file KERMIT.INI. If found, it ex- ecutes KERMIT-86 commands from it before prompting you for commands. The KERMIT-86 prompt looks like this: Kermit-86 B3> in which "B" is your current default disk and "3" is the current default user number. 13.1. Kermit-86 Commands KERMIT-86 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-86 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, using the CP/M-86 KERMIT Page 238 system's own built-in support for ANSI (VT100-like) screen control. When you issue the CONNECT command, the PC will print a message telling you how to get back by typing an an escape sequence, an uncommonly-used control character, normally CTRL-backslash, followed by a single letter "command". C Close Connection, return to Kermit-86> command level. ? List available single-character commands. B Send a BREAK signal. Q Quit logging the remote session. R Resume logging the remote session. L Toggle logging. ^\ (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, using the prevailing file mode (ASCII or BINARY; see SET). The filespec may con- tain 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 by adding "&" characters to the name. You may also provide an optional file name in the RECEIVE command; if you do, the incoming file will be stored under the name you specify. If more than one file arrives, only the first will be stored under the given name, unless you included wildcard characters in the RECEIVE filespec; in that case, the filespec will be used as a mask for incoming filenames. For instance, you told the remote Kermit to send *.ASM, you could tell KERMIT-86 to "receive *.A86", thereby changing the filetype of all the incoming files. GET filespec When Kermit-86 is talking to a Kermit Server on the host, you should use the GET command to request the server to send files to you, for ex- ample: get hlp:k*.hlp BYE When talking to a remote Kermit Server, this command shuts down the server and logs it out, and also exits from Kermit-86 to CP/M command level. LOGOUT Like BYE, but leaves you at Kermit-86 command level. FINISH Like LOGOUT, but shuts down the remote server without logging it out. Leaves you at Kermit-86 command level; a subsequent CONNECT command should put you back at host system command level. EXIT Exit from KERMIT-86 back to CP/M. QUIT Synonym for EXIT. SET parameter [value] Set the specified parameter to the specified value. Possible settings: CP/M-86 KERMIT Page 239 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-86. DEBUG ON or OFF. If ON, displays incoming and outbound packets during file transfer. OFF by default. DEFAULT-DISK disk/user Specify default disk and user number for subsequent file recep- tion and transmission. The specification following the command must be in one of the following forms: d: = go to drive d (A through P) without changing user u: = go to user u (0 through 15) without changing drive du: = go to drive d and user u : = go to the defaults when Kermit was loaded Whenever a drive is specified, even if it is the same as the current default drive, the drive is logged in so that disks can be swapped without exiting Kermit to type control-C. Kermit restores the original drive and user upon termination. ESCAPE Change the escape character for virtual terminal connections. Select a character in the control range that you will not be likely to need at the remote host; type the new character literally. Certain characters, like Control-X, cannot be specified. FILE-TYPE Tells KERMIT-86 what kind of file it is sending, so that KERMIT can correctly determine the end of the file. SET FILE BINARY means to send all the 128-byte blocks of the file, including the last block in its entirety; SET FILE ASCII is used for text files, and transmission stops when the first Control-Z is en- countered anywhere in the file (this is the CP/M convention for marking the end of a text 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 it happens to contain any data bytes that correspond to Control-Z. ASCII is the default. FLOW-CONTROL Select the desired type of flow control to be used on the com- munication line. The choices are NONE and XON/XOFF. XON/XOFF is the default. If the remote system is not full duplex or cannot do XON/XOFF, you should use NONE. IBM ON (or OFF) Allow the transfer of files to and from an IBM mainframe com- puter. This makes Kermit-86 wait for the IBM turnaround character (XON), ignore parity on input, add appropriate parity to output, and use local echoing during CONNECT. As dis- CP/M-86 KERMIT Page 240 tributed, KERMIT-86 uses MARK parity for IBM communication. If you don't give this command, IBM mode is OFF. Since IBM VM/CMS KERMIT does not have timeout capability, SET IBM ON also turns on the timeout facility automatically, as if you had typed "SET TIMER ON". 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. LOG Specify a log file on the current CP/M disk into which to record incoming characters during CONNECT. If the remote host can do XON/XOFF, then the log file will normally capture every character shown on the screen. When connected to the remote system, several single-character arguments to the connect es- cape character can be used to control logging -- Q (quit), R (resume), L (toggle). If you use R or L during connect without having previously specified a log file name, then KERMIT.LOG is used. An open log is closed when you escape back to the PC. 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. If you set parity to anything other than NONE, Kermit-86 will attempt to use "8th bit prefixing" to transfer binary files. If the other KERMIT is also capable of 8th bit prefixing, then binary files can be transferred suc- cessfully; if not, the 8th bit of each data byte will be lost (you will see a warning on your screen if this happens). PORT Allows you to switch between different communication ports on the PC. This command is not available on all systems. TIMER ON (or OFF) Enable or disable the timeout facility. The timer is off by default, because in the normal case KERMIT-86 is communicating with a mainframe KERMIT that has its own timer. Mainframe KER- MIT timers tend to be more precise or adaptable to changing conditions. You should SET TIMER ON if you are communicating with another KERMIT that does not have a timer. You should SET TIMER OFF if you are communicating over a network with long delays. WARNING ON (or OFF) Warn user of filename conflicts when receiving files from remote host, and attempt to generate a unique name by adding "&" characters to the given name. OFF by default. SHOW Show the current settings of the SET parameters. TAKE Take KERMIT-86 commands from the specified file. The file should not contain any TAKE commands; nested command files do not work. LOCAL This is a prefix for local file management commands, to distinguish CP/M-86 KERMIT Page 241 them from remote file management commands (which aren't implemented yet). The LOCAL prefix is optional; if left off, the commands will be performed locally. SPACE Show how much space is used and remaining on the cur- rent disk. DIRECTORY Provide a directory listing for the current disk, show- ing the name and size of each file. A filespec may be given to select only a certain file or wildcard file group. DELETE Delete the specified files from the current disk. TYPE A wildcard filespec is accepted and files displayed al- phabetically. The display is paged in Unix fashion with "--more--" displayed on the last line. Typein op- tions at that point can be obtained by hitting a '?'. 13.2. Installation: CP/M-86 KERMIT is broken up into several source modules: C86CMD.A86 Command parser C86FIL.A86 File handler C86Xxx.A86 System Dependent I/O C86KER.A86 Main Program C86PRO.A86 Protocol Module C86TRM.A86 Terminal Emulation C86UTL.A86 Utilities The main program module, C86KER.A86, contains INCLUDE directives for the other files. The C86Xxx module is stored with "xx" replaced by codes denoting the machine for which the program is being built -- RB for Rainbow, AP for NEC APC, etc. 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 in- dicated, renaming the appropriate C86Xxx.A86 file to be C86XXX.A86, and then doing: ASM86 C86KER $PZ (takes about 6 minutes on the Rainbow) GENCMD C86KER (takes less than a minute) and, if desired, REN KERMIT.CMD=C86KER.CMD 13.3. DEC Rainbow 100 Support Kermit-86 runs on the DEC Rainbow 100 or 100+ under CP/M-86/80, version 1 or 2, on the 8088 side. It uses the built-in firmware to emulate a VT102 ANSI ter- minal during CONNECT, and runs well at speeds up to 9600 baud. You should be able to download the program using the old KERMIT on the Z80 side (Rainbow Kermit, VT180 Kermit, or generic CP/M-80 Kermit will do the job, but CP/M-86 KERMIT Page 242 only under DEC CP/M-86/80 version 1.0), or an earlier version of Kermit-86. If you don't have an earlier version of KERMIT, then follow the directions for installing KERMIT-80 (yes, KERMIT-80) in the KERMIT-80 section of the Kermit User Guide, but send the Kermit-86 hex file instead. This works because the Rainbow can run CP/M-80 programs like DDT. Another way to get Kermit onto your Rainbow for the first time would be from a DEC VT-180 diskette. A VT-180 can use its own Kermit to load Rainbow Kermit onto its disk, which can then be read directly by a Rainbow. Also, note that VT-180 Kermit-80 can actually run on the Rainbow on the Z80 side under DEC CP/M-86/80 version 1 (but not version 2 or higher), at speeds of 1800 baud or lower. 13.4. NEC Advanced Personal Computer Support (Contributed by Ron Blanford, University of Washington) Currently only the standard serial port is supported, and not the H14 auxiliary port. The SET PORT command is not implemented. While in Kermit's terminal emulation mode, local commands are initiated by a two-character sequence consisting of the "escape character" followed by one other character identifying the command. (Make the second character a '?' to see a list of the valid commands.) As distributed, the standard Kermit-86 uses the control-backslash character as the escape character in terminal mode. The trouble is that the CP/M-86 BIOS in the APC ignores a keyboard entry of Control-\ (i.e. holding down the CTRL key while striking the '\' key), making it difficult (impossible) to use this method to get out of terminal mode. One solution is to perform a "SET ESCAPE ^" command before entering terminal mode to change the escape character to a caret (or any other character the APC keyboard will generate). This command could be placed in your KERMIT.INI file for automatic execution every time Kermit is started. The simpler solution is to realize that the character code for a Control-\ is a hexadecimal 1C, and that this is the code generated by the INS key on the numeric keypad. Once you can remember that every reference to Control-\ should be interpreted as a reference to the INS key, this is actually easier to use than the two-key Control-\ sequence. In the standard CP/M-86 BIOS, the unshifted DEL key generates a Control-X character (hexadecimal 18). This is the CP/M command to erase the current in- put line, and is very useful for local processing. Most mainframes do not use the Control-X character at all, so it becomes much less useful during terminal emulation. The DEL character (hexadecimal 7F), on the other hand, is often used by mainframes and can only be generated on the APC by holding down the SHIFT key while striking the DEL key (this capability is not mentioned anywhere in the documentation). Because the Control-X character is so seldom used while the DEL character is commonly used, the initialization procedure in Kermit-86 modifies the CP/M-86 BIOS so that the DEL key generates the DEL character whether shifted or not. Control-X can still be generated if necessary by holding down the CTRL key while striking the 'X' key. The CP/M-86 BIOS is returned to its original state CP/M-86 KERMIT Page 243 when Kermit terminates. The APC uses escape sequences which have been standardized by the American Na- tional Standards Institute (ANSI) to control cursor movement, screen erasing, and character attribute manipulation. Perhaps the best-known other terminal which follows ANSI guidelines is the DEC VT100. The APC only recognizes a few of the more important ANSI commands, and not the complete set which the VT100 supports. The ANSI/VT100 features that the NEC APC supports are: - direct cursor addressing (by row and column) - relative cursor addressing (up, down, left, right) - line erasing (cursor to end, beginning to cursor, entire line) - screen erasing (cursor to end, beginning to cursor, entire screen) - character attributes (underline, reverse video, blink, but not bold) In addition, the first four grey function keys (unshifted) generate the escape sequences associated with PF1 through PF4 on the VT100 keyboard. The arrow keys and numeric keypad DO NOT generate the corresponding VT100 sequences. These functions are enough to support simple command line editing on most sys- tems, and allow mailers or paged file display programs to clear the screen be- fore each display. Underlining and reverse video are also useful in some ap- plications. This is not enough to support the more sophisticated screen con- trol required by screen editors such as EMACS or KED. In addition, due to a bug in the implementation of the CP/M-86 BIOS, the sequence ordinarily used to home the cursor (esc [ H) does not work correctly; a patch for CP/M to correct this problem is distributed with APC Kermit-86. APPLE-DOS KERMIT Page 244 14. APPLE-DOS KERMIT Authors: Antonino N. J. Mione, Stevens Institute of Technology\* Peter Trei, Columbia University Documentation: Antonino N.J. Mione, Stevens Institute of Technology Peter Trei, Columbia University Version: 2.1(45) Date: July 1984 Kermit-65 Capabilities At A Glance: Local operation: Yes Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes Wildcard send: No ^X/^Y interruption: No Filename collision avoidance: Yes Can time out: No 8th-bit prefixing: Yes Repeat count prefixing: No Alternate block checks: No Terminal emulation: Yes (VT52) Communication settings: Yes; local echo, parity Transmit BREAK: Yes IBM communication: Yes Transaction logging: No Session logging (raw download): No Raw upload: No Act as server: No Talk to server: Yes Advanced commands for servers: No Local file management: No Handle file attributes: No Command/init files: No Printer control: No KERMIT-65 is a program that implements the KERMIT file transfer protocol for the Apple ][ micro computer system. It is written in 6502 assembly language and should run on any Apple ][ or Apple ][ Plus system running DOS 3.3. This sec- tion will describe the things you should know about the DOS 3.3 file system in order to make effective use of KERMIT, and then it will describe the special features of the KERMIT-65 program. 14.1. The DOS 3.3 File System Items of importance which will be discussed in this section include Filenames and File Characteristics. APPLE-DOS KERMIT Page 245 Apple DOS Filenames Filenames under Apple DOS may contain almost any ASCII character (including space). It is not recommended that special characters, (i.e. control characters or spaces) be used in a filename to be transferred by Kermit-65 since they may cause problems when parsing the filename. Filenames may be up to 40 characters in length. No wildcarding of any kind can be done in KERMIT-65. Apple DOS File Characteristics All files in Apple DOS have a file type associated with them which is contained in the directory entry for the file but is not part of the filename itself. There are four types of files in DOS 3.3. They are: - APPLESOFT BASIC - INTEGER BASIC - BINARY - TEXT All file types have their data stored in eight-bit bytes although not all of them need the eighth bit. The two file types containing basic programs required the eighth bit due to the nature of the data being stored. BINARY files are images of memory copied into a file. Often, these are machine code programs. These files require all eight bits. TEXT files normally contain only printable or carriage control characters. They are stored in the form of seven-bit ASCII characters but the eighth bit should always be set since Apples manipulate all text internally as 'NEGATIVE ASCII'. When transmitting text files, the byte size should be set to seven-bit. When transmitting anything else, the user must insure that both Kermits are handling eight bit data so that no information is lost. If an eight-bit data path is not available (i.e. the remote Kermit needs to do parity checking with the eigth bit), then eight-bit quoting should be used. Of course, BINARY files as well as Apple BASIC files will not have much meaning on a different system. If the user desires to edit a BASIC file on a mainframe, for instance, he must convert it to a TEXT file before sending it over. After receiving the file back on the Apple, the user may convert it back to BASIC once again. The reason BASIC files would be meaningless to a different machine is that the Apple stores BASIC keywords as single character tokens to save space and processing time. To con- vert a BASIC program to and from a TEXT file, consult the Apple DOS 3.3 Manual. File information can be obtained by issuing the CATALOG command. For example: ]CATALOG DISK VOLUME 010 *A 002 HELLO B 078 KERMIT A 002 READER APPLE-DOS KERMIT Page 246 T 005 TESTFILE ] When KERMIT-65 is receiving a file, the file it creates on diskette will be of the type indicated by the FILE-TYPE parameter. The file will always be left in an unlocked state after it is closed by KERMIT-65. When sending a file, KERMIT-65 will use the FILE-TYPE parameter to determine how to detect an End-of-file condition. Thus, it is important to have this set properly in all cases. Recommendations for archiving files When using a large system for archiving purposes, there is no reason to convert Apple Basic programs into text files before sending them since there is no need to edit them on the mainframe. The FILE-TYPE parameter must always be set correctly when sending and receiving files. Also, when sending files which require eight-bit FILE-BYTE-SIZEs, this parameter must also be set properly since KERMIT-65 does not change it automatically based on FILE-TYPE. The procedure for archiving TEXT files is: - Run Kermit on remote system - SET FILE-BYTE-SIZE SEVEN-BIT ! On KERMIT-65 - SET FILE-TYPE-MODE TEXT ! On KERMIT-65 - Send files The procedure for archiving APPLESOFT, INTEGER, and BINARY files is: - Run Kermit on remote system - Set File-byte-size to Eight-bit ! On Remote Kermit - SET FILE-BYTE-SIZE EIGHT-BIT ! On KERMIT-65 - SET FILE-TYPE-MODE APPLESOFT ! (or INTEGER, or BINARY) On KERMIT-65 - Send files 14.2. Program Operation APPLE-DOS KERMIT Page 247 HARDWARE CONSIDERATIONS Prior to using KERMIT-65 for transferring files, the modem interface must be set to handle data in a certain manner. Firstly, the data format should be 8 data bits and 1 stop bit. Secondly, the card should be set to no parity. The baud rate (if adjustable) must be set to whatever rate the modem can handle. For the Apple Com card and the D.C. Hayes Micromodem, these parameters are set correctly by default, so very little has to be done. For the Apple Super Serial Card, however, these have to be set before using KERMIT-65. In all cases, use the same procedure to connect to the mainframe host as is indicated in the sec- tion below on Installing KERMIT. Some mainframes cannot handle data in the format of 8 data bits and 1 stop bit because they may need parity checking (i.e. most IBM machines). In this case, 7 data bits and 1 stop bit plus some parity setting (other than none) will usually work. When talking with such mainframes, binary and basic files on the Apple cannot be transferred unless Eighth-bit-quoting is used. CONVERSING WITH KERMIT-65 KERMIT-65's prompt is "KERMIT-65>". To run KERMIT-65 and issue commands to it, type the following: ]BRUN KERMIT STEVENS/CU - APPLE ][ KERMIT-65 - VER 2.1 Kermit-65>SEND TESTFILE file is sent Kermit-65>STATUS performance statistics are printed Kermit-65>Other commands . . . Kermit-65>EXIT ] KERMIT-65 uses a TOPS-20 style command parser. During interactive operation, you may use the ?-prompting help feature ("?") and recognition (ESC) features 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 to be completed (or default value to be supplied). 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. Keywords may be abbreviated to any prefix that is unique. APPLE-DOS KERMIT Page 248 There are several different Apple ]['s which can run KERMIT-65. Kermit will have no problems running on an Apple ][ or Apple ][+ system. It will run on the Apple //e as well, however, the 80-column board cannot be used at this time. Of the different communication devices available for the Apple ][, three are supported: - Apple Com Card - D.C. Hayes Micromodem - Apple Super Serial Card It is possible that other cards may have operational characteristics very similar or identical to one of the devices above. If this is the case, it may work using one of the currently available device drivers. The user may want to try each of the above options to see if any of them work. KERMIT-65 must be told which device is being used so that it may run with the correct device driver. It also must be told in which slot the card resides. This may be done with the 'SET' command (documented below). 14.3. Remote and Local Operation KERMIT-65 is normally run in local mode. It may be run as a remote Kermit as well although there is no advantage to doing things that way. KERMIT-65 sup- ports User-mode commands for talking to a Server. It does not currently support server mode. 14.4. KERMIT-65 Commands THE SEND COMMAND Syntax: SEND filespec The SEND command causes a file to be sent from the Apple to the remote system. The Filespec is the name of the file on the Apple diskette to be sent. The par- ser will not accept control characters and certain special characters in a filename (i.e. a comma), so the user may have to rename the file before it is sent. The user may also have problems in filename compatibility with remote Kermits. If the remote Kermit does not have the facilities to beat the filename into a format that its system likes, the user may have to rename the file be- fore sending it. The default disk drive used for file transfers is the drive used to boot the system or the last drive accessed with a DOS command. This can be changed with the 'SET DEFAULT-DISK' command (explained below). Either the slot or the drive or both may be altered. As a file is being sent, the screen displays either 'SENDING PACKET...' or 'WAITING PACKET...' followed by the absolute packet number since start of transmission. If a packet must be transmitted several times and it reaches the maximum retry count, the transfer will fail and the 'KERMIT-65>' prompt will return. If the remote Kermit sends an error packet, the text of the packet will be displayed on the screen and the prompt will return. APPLE-DOS KERMIT Page 249 Currently, a packet can be retransmitted manually by typing anything on the keyboard. If a 'Q' is typed, the entire transmission will be aborted. THE RECEIVE COMMAND Syntax: RECEIVE [filespec] The RECEIVE command tells KERMIT-65 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. If the name in the header is not a legal filename in DOS 3.3, KERMIT-65 will attempt to change it into something legal. There are very few things that are illegal in DOS 3.3. If FILE-WARNING is on and an incoming file has a name identical to a file already existing on the diskette, KERMIT-65 will issue a warning to the user and attempt to modify the filename to make it unique. GET 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 with a KERMIT server on the other end. The remote filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. 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 CONNECT COMMAND Syntax: CONNECT Establish a terminal connection to the remote system. Get back to KERMIT-65 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: B Send a BREAK Signal. C Close the connection and return to KERMIT-65. S Show status of the connection. 0 Send a null. Connect-escape Send the Connect-escape character itself. ? List all the possible single-character arguments. You can use the SET ESCAPE command to define a different escape character. When 'CONNECTED', KERMIT-65 will be passing characters entered on the keyboard APPLE-DOS KERMIT Page 250 to the remote system, and passing characters from the remote system to the Ap- ple screen. If VT52-EMULATION is turned on, Kermit will trap escape codes and simulate the appropriate functions of a VT52 terminal. On an Apple ][+ with an incomplete keyboard, special characters can be obtained by prefixing regular characters with a right-arrow. Also, Uppercase is shown in inverse and lowercase characters are displayed as normal uppercase characters. Here are the rules for using the special 2/2+ input, to get all printable ASCII characters, and how they appear on the screen: Special meanings are applied in various contexts to certain characters. The left and right arrow keys do special things, and sometimes the escape key does as well. For letters, the keyboard is always in either default UPPERCASE mode or default lowercase mode. When in UPPERCASE, all letters typed are sent out as upper- case. In lowercase, all letters are sent as lowercase. To reverse the case for the next character only, hit the right-arrow ("prefix") key. To switch the default case, hit the prefix-key twice in a row. For funny characters, the prefix key is also used to get the unusual punctua- tion characters which are not on the Apple keyboard. Here they are: (To represent the prefix character I am using the letter p). To get Type Appearence Left Square Bracket p( [ Right Square Bracket p) ] Left Curly Bracket p< { Right Curly Bracket p> } Underline p- _ Backslash p/ \ Tilde (wiggle) p^ ~ Vertical Line p. | The left-arrow key sends a rubout. With left-arrow and right arrow doing special things, its a little hard to enter their characters (^H and ^U respectivly). There is therefore an escape from prefix mode sequence. If you type prefix-ESC, the next character is sent without any interpretation. Currently, it is impossible to turn this special input and display on and off, so its a bit of a pain if you are on a Apple 2e. THE HELP COMMAND Syntax: HELP Typing HELP alone prints a brief summary of the KERMIT-65 commands. APPLE-DOS KERMIT Page 251 THE EXIT AND QUIT COMMANDS Syntax: EXIT Exit from KERMIT-65. You can restart the program, provided you haven't run anything else, by typing 'CALL 2049'. Syntax: QUIT This is merely a synonym for EXIT. 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: DEBUGGING TERSE or VERBOSE packet information. DEFAULT-DISK Which Diskette drive is used for file transfer? DEVICE-DRIVER Which communication device is being used? EIGHT-BIT-QUOTING Should eight-bit-quoting be used? ESCAPE Character for terminal connection. FILE-BYTE-SIZE SEVEN or EIGHT significant bits in a byte. FILE-TYPE Of Apple DOS file being sent/received. FILE-WARNING Warn users if incoming file exists? IBM For communicating with an IBM mainframe KEYBOARD ][+ or //e keyboard. LOCAL-ECHO Full or half duplex switch. PARITY Character parity to use RECEIVE Various parameters for receiving files SEND Various parameters for sending files SLOT Which slot # is communication device in? VT52-EMULATION Should Kermit emulate a VT52 when connected? APPLE-DOS KERMIT Page 252 SET DEBUGGING Syntax: SET DEBUGGING options Record the packet traffic on your terminal. Options are: TERSE Show packet info only (brief). VERBOSE Display packet field descriptions with packet info (lengthy). OFF Don't display debugging information (this is the default). SET DEFAULT-DISK Syntax: SET DEFAULT-DISK parameter value This command will tell KERMIT-65 which disk drive should be used for file transfers. The two parameters which may be set separately are SLOT and DRIVE. The value for SLOT ranges from 1 to 7. The value for DRIVE is either 1 or 2. SET DEVICE-DRIVER Syntax: SET DEVICE-DRIVER parameter keyword This command will tell KERMIT-65 what type of communication device is being used. Currently, three different cards are supported, however, other unsup- ported cards may work similar enough to one of the three available that it may be possible to use them. KERMIT-65 must also be told where the card is in the machine (see the SET SLOT command). The options for this set command are: APPLE-COM-CARD The old Apple communication card (300 baud). DC-HAYES The D.C. Hayes Micromodem II (300 baud). SUPER-SERIAL-CARD The Apple Super Serial Card (300-19.2k baud). SET ESCAPE Syntax: SET ESCAPE hexidecimal-number Specify the control character you want to use to "escape" from remote connec- tions back to KERMIT-65. The default is 0 (Control-@). The number is the hex value of the ASCII control character, 1 to 37, for instance 2 is Control-B. SET FILE-BYTE-SIZE Syntax: SET FILE-BYTE-SIZE parameter Byte size for Apple DOS file I/O. The choices are SEVEN-BIT or EIGHT-BIT. SEVEN-BIT APPLE-DOS KERMIT Page 253 When sending a file, shut the H.O. bit. When receiving, turn the H.O. bit on. This is done since text files are the only files which should be sent as SEVEN-BIT files and text files only make sense to the Apple if they are encoded in 'negative ascii' values. EIGHT-BIT Always send and receive the bytes intact. All 8 bits are significant. SET FILE-TYPE Syntax: SET FILE-TYPE parameter keyword This will inform KERMIT-65 what type of DOS file is being sent or received. It is important that this is set correctly since KERMIT-65 must create a file of the appropriate type when receiving (and it has no way of knowing what kind of file it is). When KERMIT-65 is sending, it must also know the type of file since that tells it how to detect the actual end-of-file. The options for this parameter are APPLESOFT, INTEGER, TEXT and BINARY. APPLESOFT The file being sent/received is an Applesoft Basic program. INTEGER The file being sent/received is an Integer Basic program. TEXT The file being sent/received is an ASCII Text file. BINARY The file being sent/received is a Binary image. SET FILE-WARNING Syntax: SET FILE-WARNING ON or OFF This tells KERMIT-65 whether to warn the user about incoming filenames con- flicting with existing files or not. SET IBM Syntax: SET IBM ON or OFF SET IBM actually sets a number of parameters. When setting it on, the command also turns on LOCAL-ECHO (half-duplex) and sets PARITY to MARK. When setting IBM OFF, LOCAL-ECHO will revert back to OFF and PARITY will be set to NONE. It should be used when doing file transfers with an IBM or similar mainframe. SET KEYBOARD Syntax: SET KEYBOARD 2P or 2E SET KEYBOARD tells KERMIT-65 if the user has a full keyboard (2E) or not (2P). If the user is on an Apple ][+, this should be set to 2P (which is the default). When set to that, certain character translations are available by using the right-arrow key as a prefix character. APPLE-DOS KERMIT Page 254 SET SLOT Syntax: SET SLOT parameter This option tells KERMIT-65 in which slot the communication device is located. The range for the parameter is 1-7. THE SHOW COMMAND Syntax: SHOW [option] The SHOW command displays various information: ALL All parameter settings (this is quite long). DEBUGGING Debugging mode. DEFAULT-DISK Which Diskette drive is used for file transfer? DEVICE-DRIVER Which communication device is being used? EIGHT-BIT-QUOTING Should eight-bit-quoting be used? ESCAPE Character for terminal connection. FILE-BYTE-SIZE SEVEN or EIGHT significant bits in a byte. FILE-TYPE Of Apple DOS file being sent/received. FILE-WARNING Warn users if incoming file exists? IBM For communicating with an IBM mainframe KEYBOARD ][+ or //e keyboard. LOCAL-ECHO Full or half duplex switch. PARITY Character parity to use RECEIVE Various parameters for receiving files SEND Various parameters for sending files SLOT Which slot # is communication device in? VT52-EMULATION Should Kermit emulate a VT52 when connected? The above options are analogous to the equivalent SET commands. APPLE-DOS KERMIT Page 255 THE STATUS COMMAND Give statistics about the most recent file transfer. This includes information such as number of characters sent/received, number of data characters sent/received, and last error encountered. 14.5. Customizing, Building, and Installing KERMIT-65 STANDARD INSTALLATION The Procedure The procedure to bootstrap an assembled KERMIT object file to the Apple is as follows: 1. On the Apple, Type in the APPLBT.BAS program supplied (See below). It is recommended that the user save this program as it may be needed to bootstrap newer versions of KERMIT or APPHXL in the fu- ture. Also, type the APPLESOFT program in with none of the REMs. It will execute quicker and take up less room. 2. Call and login to the mainframe on which the KERMIT-65 object file resides. Do the following: - ]IN#n ! Where n is between 1 and 7 - For Communication card, do the following: * Dial number for computer system. * Seat phone receiver in modem cradle. * ] !Full duplex, 300 baud - For the D.C. Hayes Micromodem, do the following: * ] ! Full duplex, 300 baud * MICROMODEM II: BEGIN TERM * MICROMODEM II: DIALING: nnn-nnnn ! nnn-nnnn is number of computer system - For the Apple Super Serial Card, do the following: * ] * APPLE SSC:0D ! 8 data bits, 1 stop bit * ] * APPLE SSC:0P ! Force no parity APPLE-DOS KERMIT Page 256 * ] * APPLE SSC:nB ! n = 6 for 300 baud, n = 8 for 1200 baud * Dial number for computer system. * Seat phone receiver in modem cradle. * ] * APPLE SSC:T ! Terminal mode, now talking to remote host 3. In your directory on the mainframe, the following files should be present: - APPLBT.FOR - APPHXL.HEX - APPLEK.HEX Compile and execute APPLBT.FOR. This will be used along with APPLBT.BAS on the Apple to load the APPHXL program. Once APPLBT is executing on the mainframe, give control back to the Apple and then run APPLBT.BAS on the Apple. For either the Communication Card or the D.C. Hayes Micromodem, the procedure is: - ! Give control to Apple's Brain - ]LOAD APPLBT.BAS - ]LOMEM:9500 - ]RUN 4. Relocate and save APPHXL. Type the following: - ]CALL -151 ! Enter Apple's system monitor - *9000<2000.2280M ! Move APPHXL from $2000 to $9000 - * ! Reenter APPLESOFT - ]BSAVE APPHXL,A$9000,L$280 ! Save APPHXL to disk 5. Now simply start executing APPHXL. - ]CALL -151 ! Enter monitor - *9000G ! Start APPHXL - SLOT FOR MODEM CARD? (1 TO 7 )n ! 'n' is slot # of card (no ) - ENTER FILENAME TO LOAD APPLEK.HEX ! Tell APPHXL what to load APPLE-DOS KERMIT Page 257 APPHXL will print the byte count and load address for each line it is receiving as it loads it into memory. At the end of each line, it will print '[OK]' if the line was received properly or '[CHECKSUM ERROR]' if there was a problem with it. 6. When APPHXL finishes type the following to the Apple: ]BSAVE KERMIT,A$801,L$4E00 ! Save KERMIT to disk 7. The user may set up a turn-key system by having the hello file on the disk load and run KERMIT. The user may also run KERMIT-65, change the defaults which are supplied in the program such as SLOT and DEVICE-DRIVER, and then resave KERMIT-65. The next time it is run, the user will not have to set these values again. If the user does not set up a turn-key system, he must start KERMIT-65 by typing: ]BRUN KERMIT ! Execute KERMIT-65 on the Apple The Apple will display the following: STEVENS/CU - APPLE ][ KERMIT-65 VER. 2.1 KERMIT-65> The user is now ready to transfer files. NOTE: For those users with the Apple Super Serial Card, the intercept character should be shut off by typing Z to the card before Kermit is run. The reason for this is that Kermit uses as a Start-of-Header character and this character may never reach the program if the card is taking it to be a command. APPLBT.BAS - The APPLESOFT Bootstrap program 10 REM - LOADER FOR HXLOAD 11 OAD = 0 100 N$ = "0123456789ABCDEF" 110 D$ = CHR$ (4) 130 PRINT D$;"IN#2" : REM CHANGE '2' TO SLOT OF COMM. CARD IF NECESSARY 135 PRINT CHR$ (1); CHR$ (6) 136 PRINT D$;"PR#2" : REM CHANGE '2' TO SLOT OF COMM. CARD IF NECESSARY 137 PR#2 : REM THIS LINE SHOULD BE HERE ONLY FOR THE APPLE COMM. CARD 140 C3 = 0 150 HOME 199 REM - REQUEST NEXT LINE 200 REM - PUT A DOT ON THE SCREEN FOR EACH LINE RECEIVED 201 C3 = C3 + 1: POKE 1024 + C3, ASC (".") 202 L$ = "":Y2% = 1: PRINT 203 GET A$:L$ = L$ + A$:Y2% = Y2% + 1: IF Y2% < 81 THEN 203 205 C1 = 0:C2 = 0:I = 0 208 IF LEFT$ (L$,1) > = "0" AND LEFT$ (L$,1) < = "9" THEN 220 210 L$ = RIGHT$ (L$, LEN (L$) - 1): GOTO 208 220 LL = LEN (L$) 249 REM - FETCH THE DATA BYTE COUNT FOR THIS LINE 250 GOSUB 1000:C1 = C1 + B:CO = B APPLE-DOS KERMIT Page 258 255 IF CO = 0 THEN 990 259 REM - CONSTRUCT THE LOAD ADDRESS FOR THIS LINE 260 GOSUB 1000:C1 = C1 + B:AD = B: GOSUB 1000:C1 = C1 + B :AD = AD * 256 + B 265 REM - IF THE LATEST VERSION OF CROSS IS USED, THIS SHOULD NOT BE NEEDED : REM AD = AD - 28672 266 IF AD < OAD THEN 990 267 OAD = AD 270 FOR X = 0 TO CO - 1 275 REM - GO GET A BYTE AND PUT IT IN THE NEXT MEMORY LOCATION 280 GOSUB 1000:C1 = C1 + B 290 POKE AD + X,B 300 NEXT X 310 GOSUB 1000:C2 = B: GOSUB 1000:C2 = C2 * 256 + B 320 IF C1<>C2 THEN POKE 1024+C3,ASC("E") 330 GOTO 201 990 FOR X = 1 TO 1000: NEXT X 995 PRINT D$;"IN#0": PRINT D$;"PR#0": HOME : END 999 REM - GET BYTE 1000 GOSUB 1501:B = N1: GOSUB 1501:B = B * 16 + N1 1010 RETURN 1500 REM - GET NIBBLE 1501 IF LEN (L$) = 0 THEN N1 = 0: RETURN 1510 H$ = LEFT$ (L$,1) 1511 IF LEN (L$) = 1 THEN L$ = "": GOTO 1525 1515 L$ = RIGHT$ (L$, LEN (L$) - 1) 1520 REM - RETURN VALUE OF HEX NIBBLE 1525 FOR X1 = 1 TO 16 1530 IF H$ = MID$ (N$,X1,1) THEN 1610 1540 NEXT X1 1550 REM - DIGIT WAS NOT FOUND, RETURN ZERO 1560 N1 = 0: RETURN 1600 REM 1610 N1 = X1 - 1: RETURN APPLBT.FOR - The Mainframe Bootstrap program CHARACTER LINE*80,SENTNL*1 OPEN (UNIT=00,FILE='APPHXL.HEX',MODE='ASCII') 10 READ (UNIT=05,FMT=20) SENTNL 20 FORMAT (A1) READ (UNIT=00,FMT=25,END=999) LINE 25 FORMAT(A80) WRITE (UNIT=05,FMT=30) LINE 30 FORMAT(A80) GO TO 10 999 READ (UNIT=05,FMT=20) SENTNL STOP END APPLE-DOS KERMIT Page 259 ALTERNATIVE INSTALLATION PROCEDURES HEXloading from Diskette Once the user has a working version of KERMIT-65 on his system, he can use this to load the .HEX files of future versions of KERMIT. There is another hexload program available called APPDXL. This program will load a hex file from an Ap- ple diskette into memory. To use this procedure, do the following: 1. Start executing APPHXL. - ]BLOAD APPHXL ! Get APPHXL into memory - ]CALL -151 ! Enter monitor - *9000G ! Start APPHXL - SLOT FOR MODEM CARD? (1 TO 7 )n ! 'n' is slot # of card (no ) - ENTER FILENAME TO LOAD APPDXL.HEX ! Tell APPHXL what to load APPHXL will print what it is receiving on the screen as well as loading it into memory. 2. Relocate and save APPDXL. Type the following: - ]CALL -151 ! Enter Apple's system monitor - *9000<2000.2500M ! Move APPDXL from $2000 to $9000 - * ! Reenter APPLESOFT - ]BSAVE APPDXL,A$9000,L$500 ! Save APPDXL to disk 3. Use Kermit-65 to transfer the new version of itself over. Make the Apple file a Text file. WARNING: This file will take LOTS of space (about 180 sectors) so make sure the disk is reasonably empty. The transfer takes a LONG time also, so please be patient. 4. Start executing APPDXL. - ]BRUN APPDXL ! Start APPDXL - ENTER FILENAME TO LOAD APPLEK.HEX ! Tell APPDXL what to load 5. When APPDXL finishes type the following to the Apple: ]BSAVE KERMIT,A$801,L$4E00 ! Save KERMIT to disk The new version of Kermit is now on disk. APPLE-DOS KERMIT Page 260 Using KERMIT-65 to transfer APPLEK.BIN There is yet another way to Bootstrap a new version of KERMIT onto an Apple. If the user has an older version of KERMIT-65 and has access to a machine with a valid copy of APPLEK.BIN, they can simply transfer APPLEK.BIN using their ver- sion of KERMIT. Be sure to set the File-byte-size to Eight-bit, and the File-type-mode to Binary before transfering the file since this is the actual object code. No special loading or conversion is needed. The file will be placed on the disk and ready to run. FILES SUPPLIED FOR KERMIT-65 The following files should be supplied on the distribution tape: - APPLBT.BAS - Initial bootstrap program to load APPHXL - APPLBT.FOR - Program on mainframe to talk to APPLBT.BAS - APPHXL.M65 - Source of program to load KERMIT-65 - APPHXL.HEX - Assembled version of Hex load program - APPDXL.M65 - Source of program to load KERMIT-65 from Apple diskette - APPDXL.HEX - Assembled version of Disk Hex load program - APPLEK.M65 - Source for the KERMIT-65 program - APPLEK.HEX - Assembled version of KERMIT-65 - APPLEK.BIN - Assembled version of KERMIT-65 (Eight-bit Binary object code) - CROSS.MAC - CROSS Microprocessor Assembler (Source) - CROSS.EXE - CROSS Microprocessor Assembler (Object) CUSTOMIZING AND BUILDING KERMIT-65 The source code to KERMIT-65 is in 6502 Assembler. It has been formatted for CROSS which is a micro-Cross Assembler program which runs on DECsystem-10s and DECSYSTEM-20s. Customizations would be made the easiest if CROSS were avail- able. KERMIT-65 currently supports the following communications devices: - FTASER - The Apple Communication card - FTHAYS - The D.C. Hayes Micromodem. - FTSSC - The Apple Super Serial Card All device drivers are included in the assembled version and may be used by is- suing a 'SET DEVICE-DRIVER' command to Kermit. If any of the device drivers are APPLE-DOS KERMIT Page 261 not needed, it(they) may be excluded by setting the appropriate feature test to zero in the Feature test section of the source code. Excluding one or more device drivers can reduce the size of the object code greatly. DO NOT disable all device drivers since KERMIT-65 will then have no way of talking over the communication device. The feature test FTCOM must be set to the type of computer for which KERMIT-65 is being assembled. The only machine KERMIT-65 is available for currently is the Apple ][. This parameter must be set to FTAPPL. After setting any options necessary in APPLEK.M65, rename it to KERMIT.M65, and do the following: - .R CROSS ! Run CROSS Microprocessor Assembler - *KERMIT.HEX/PTP:KIM=KERMIT.M65/M65 ! Generate .HEX file This command will produce an ASCII HEX file which can be downline loaded onto the Apple using APPHXL. If a listing is desired, one can be produced by adding ",KERMIT.LST" after the "/PTP:KIM" in the command line to CROSS. Kermit User Guide Page 262 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: .....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. Kermit User Guide Page 263 The following characters are printable: 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 Page 264 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 Page 265 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 A1 ~ Tilde Finally, one more nonprintable character: 0 127 177 7F 07 DEL Delete, rubout ,Kermit User Guide Page cclxvi Index 1 3270 Protocol Emulation 2Completion 171, 173 CONNECT 9, 11, 175, 195, 8080 221, 223 217, 237, 249 CONTINUE 35, 67, 100 ?-prompting 247 Control Characters 9, 262 Control-A 56, 90 ANSI.SYS 191 Control-C 35, 67, 100 APC 242 Control-V 56 Apple ][ 244 Control-X 30, 31, 56, 57, APPLESOFT 253 90, 91, 176, 177 ARPANET 65, 234 Control-Z 30, 31, 56, 57, ASCII 262 90, 91, 176, 177 ASCII-to-EBCDIC 112 CP/M 50, 224 Attention Character 234 Crash 22 Autoanswer 16 CRC 184 Autodialer 13, 75, 195 Deadlock 22 Batch 64 Debugging 37, 62, 96, 113, Batch Operation of Kermit-CMS 184, 239, 252 109 DEC Rainbow 241 -MS Batch Operation of KermitDECSYSTEM-20 46 173 DEFAULT-DISK 252 Baud 219, 238 DEFINE 66, 194 Baud Rate 36, 184 Define SET Macros 42 Beeper 184 Delay 37 Bell 184 DELETE 56, 90 BINARY 253 DEVICE-DRIVER 252 55, Binary Files 20, 29, 40, Dialout 75 56, 90, 188 Dialout Modems 139 Binhex 158 Dialup 14 BIOS 221 Diskette 22 84, Block Check 36, 113, 1Display, File Transfer 185 220 DO Command 195 Bootstrap 225 DOS 3.3 244 mit Bootstrapping MS-DOS KerDownloading 225 200 Duplex 37 BREAK Simulation 61, 65 BYE 17, 18, 218, 238 EBCDIC 262 Byte Size 48, 58, 62, 252EBCDIC-to-ASCII 113 Echo 20, 67 C-Kermit 118 Eighth-Bit Prefix 29, 30, Cables 14, 15 40, 55, 56, 90, 91, Cancelling a File Transfer 188, 219, 240 90, 30, 31, 56, 57, EMACS 198 91, 110, 176, 177 Emergency Exit 120 Capturing Files 43 End Of File 50, 170, 186 Checksum 184 End Of Line 40, 41 CKMKER 153 EOF 186 CKMKEY 158 Error Recovery 19 CLEAR 69 Escape Character 11, 217, CLOSE Command 182 219, 237, 239 Command Files 191 Escape Character for CONNECT Command Macro 194 38, 62, 97, 186, 252 Command Parsing 25 Escape Sequence 9 Kermit User Guide Page ii EXIT 35, 67, 100, 251 Local Echoing 187 2 Expunging Deleted Files 6Local-Echo 219, 240 LOG 43, 218, 240 File Renaming 114, 193 LOG Command 182 File Type 97 Login Scripts 69 3 File Warning 114, 120, 19LOGOUT 218, 238 FILE-BYTE-SIZE 252 FILE-TYPE 253 Macintosh Kermit 153 3 File-Warning 218, 238, 25Macro 194 Filespec 248 Message Interference 52, 88 FINISH 17, 18, 219, 238 META Key 161, 198 Flow Control 38, 186, 239Mode Line 188, 196 Modem 195 Generation 56 Modems 139 Generic Kermit-80 221 MS-DOS 167 Generic MS-DOS Kermit 189, 207 NAK 217, 237 GET 17, 218, 238, 249 NEC Advanced Personal Computer 242 Handicapped 185 Noise 6 Handshake 38, 78, 98, 187Normal Form for File Names Hayes Modem 140 55, 63, 89, 98 ion Heath/Zenith-19 EmulatNull Modem 14, 15 208 Help 51, 171, 247, 250 OUTPUT 69 20, IBM 63, 98, 106, 137, 2Packet 7 239, 253 Packet Length 40, 41 IBM PC 167 Padding 41 ion Incomplete File DispositParity 29, 30, 39, 55, 56, 30, 56, 91, 111, 177, 90, 91, 188, 219, 240, 187 262 39 Incomplete File Transfer Password 72 Indirect Command File 72 Passwords 72 54, Initial Filespec 22, 29, PAUSE 69 89 Pause Between Packets 41 INPUT 64, 66, 69, 70, 72 PC-DOS 167 mit Installation of MS-DOS KerPCjr 195 199 Printer 182, 185, 198 INTEGER 253 Prompt 9, 40 Intercept Character 234 Interference 52, 88 QUIT 35, 67, 101, 251 Internal Modem 19 ITS-Binary Format 63 Rainbow 100 241 Raw Download 76, 101 Kermit Commands 10 Raw Upload 73, 77 Kermit Protocol 7 RECEIVE 11, 12, 13, 30, 56, Kermit server 16 90, 111, 177, 218, Key Redefinition 187 238, 249 Key Redefinitions 198 Recognition 51, 247 KEYBOARD 253 Remote 10, 18, 25 Repeated Character Compression Line Sequence Numbers 55 29, 30, 55, 56, 90 Linefeed 78 Retry Limit 42 Local 10, 25, 216, 236 Rollback 197 Local Echo 37 Kermit User Guide Page iii Screen Dump 186, 197 Word Size 48 Screen Scroll 197 54, SEND 10, 13, 17, 22, 29, XON/XOFF 38, 218, 262 89, 175, 218, 238, 248 Series/1 114 Z80 223 Server 16, 18, 32, 58, 92 Server, MS-DOS 182 SET 11, 219, 238 SET INPUT 64, 73 SET TERMINAL 191 Setfile 158 SHOW 11, 43, 66, 99, 240, 254 SLOT 254 Smart Modem 195 Speaking Device 185 Speed 65, 66 Start Of Packet 41, 42 TAC 234 TAC Binary Mode 65 TAKE 64, 240 TELENET 39, 42, 142, 188 Terminal 191 TERSE 252 TEXT 253 Timeout 40, 41, 70, 193, 216, 217, 224, 236, 237 TIMER 219, 240 TOPS-20 46 TopView 167 TRANSMIT 73, 77, 218 TVT-Binary 65 Typeahead 72 UNDELETE 56, 90 Unix Kermit 118 Upload 73 VAX/VMS 83 VERBOSE 252 Version 90, 219 Virtual Terminal 9, 11, 217, 237 VM/CMS 13, 106 VT-102 Emulation 167 VT100 219 VT102 Emulation 192, 208 VT52 219 VT52 Emulation 208 Warning 114, 120, 193, 219, 240 Wildcard 11, 12, 47, 84, 107, 169, 172