BBC KERMIT USER GUIDE ===================== This guide describes how to use the implementation of KERMIT for the BBC Computer produced by the Computing Department's Communications Group at Lancaster University. BBC KERMIT may be used on BBC models B, B+ and B+128; and also on the Master 128. It operates with the Acorn DFS, 1770 DFS, ADFS, Econet, and any other Acorn-compatible filing system. The information in this edition applies to version 1.42 EDITION 4.1 July 1986 Alan Phillips BBC KERMIT User Guide CONTENTS 1. INTRODUCTION 1.1 BBC KERMIT capabilities at a glance 2. AN OVERVIEW OF KERMIT 3. CONTROLLING BBC KERMIT 3.1 Entering BBC KERMIT 3.1.1 The RAM version 3.1.2 The sideways ROM version 3.2 Leaving BBC KERMIT 3.3 BBC KERMIT command language 3.3.1 Command format 3.3.2 Abbreviating commands and parameters 3.3.3 Numeric parameters 3.3.4 Obtaining help 3.4 Reading commands from a file 3.5 Storing parameter settings 3.6 Setting the command screen width 3.7 Function and cursor keys 3.8 Using an auto-boot file 4. USING BBC KERMIT AS A TERMINAL EMULATOR 4.1 Running a terminal session 4.1.1 Choosing the terminal emulation required 4.1.2 Setting the line speed 4.1.3 Setting parity 4.1.4 Selecting the flow control method 4.1.5 Specifying an "ignore" character 4.1.6 Starting terminal emulation 4.1.7 Sending a break signal 4.1.8 Using the function keys 4.1.9 Using the cursor keys 4.1.10 Pausing screen output 4.1.11 Returning to command mode 4.2 Logging output to a disc file 4.3 Logging output to a printer 4.4 Sending files to a host without KERMIT 4.5 VT52 keypad emulation 5. TRANSFERRING FILES WITH KERMIT 5.1 Principles 5.2 File type 5.2.1 Binary files 5.2.2 Printable text (ASCII) files 5.2.3 How to decide on the file type to use 5.3 Sending eight bit data 5.4 Starting up the mainframe KERMIT 5.5 Using BBC KERMIT with a remote server 5.5.1 Sending files to a server 5.5.2 Fetching files from a server 5.5.3 Controlling a remote server 5.5.4 Closing down the server 5.6 Using BBC KERMIT with a remote non-server 5.6.1 Sending files to a non-server 5.6.2 Receiving files from a non-server 5.7 Transferring data to and from memory 5.8 Transferring data to a parallel printer 5.9 Handling problems 5.10 Advanced facilities 5.10.1 Interrupting transfers 5.10.2 Using timeouts 5.10.3 File name translation 5.10.4 Detailed protocol control Appendices A1. BBC KERMIT COMMANDS A1.1 Commands for general control of BBC KERMIT A1.2 Commands for transferring data A1.3 Commands for terminal emulation A1.4 Commands for control of remote servers A1.5 Commands for detailed protocol control A2. OBTAINING, BUILDING AND MODIFYING BBC KERMIT A2.1 Obtaining BBC KERMIT A2.1.1 The source files A2.2 Building BBC KERMIT from a hex file A2.3 Building BBC KERMIT from source A2.3.1 Source file layout A2.3.2 The assembly process A2.4 Changing KERMIT defaults A2.4.1 Changing the source A2.4.2 Patching the object code A2.4.3 Format of the defaults block A2.5 The hex to binary converter program A2.6 Contact addresses A3. USING THE EDT EDITOR ON VAX/VMS A3.1 Setting up the terminal details A3.2 Edit keypad keys A3.2.1 Models B, B+ and B+128 A3.2.2 The Master 128 1: INTRODUCTION This user guide describes the KERMIT implementation on the BBC Micro produced by the Communications Group of the Computing Department at Lancaster University. It is intended to provide enough information for a novice KERMIT user to be able to transfer data to and from his BBC micro to another KERMIT system. Other KERMIT systems are desribed only in passing: thus you will almost certainly need to consult the equivalent user guide for the KERMIT system on the other machine. The guide is divided into several chapters. The next chapter is a general overview of KERMIT as a whole, and explains its advantages as a file transfer system over "dumb capture" programs. The succeeding chapter describes the command language that BBC KERMIT uses. Following that are chapters that describe how to use BBC KERMIT as a terminal, and how to use it to transfer data. The appendices comprise the "reference section". They describe in full detail the commands available in BBC KERMIT, grouping them by functionality (i.e. "Commands for file transfer", "Commands for terminal emulation", etc). They also describe how to obtain BBC KERMIT, and, having obtained it, how to build it from the assembly language sources or modify the compiled binary version. BBC KERMIT is, of course, freely available to anyone who wants it. It can be obtained from the KERMIT tapes distributed by Columbia University; alternatively, it can be picked up from Lancaster University's KERMIT distribution service. This latter option enables it to be acquired either over file transfer from the Lancaster University VAX 11/780 system, or on Acorn format discs, or (in small numbers) as programmed EPROMs. The Lancaster KERMIT distribution service also maintains on-line bulletin files giving details of new releases of BBC KERMIT and of reported bugs: these can be consulted in a public-access username. Lancaster University intend to continue development of the BBC KERMIT system. We welcome any comments or suggestions that you may wish to pass on, as well as reports of bugs, problems and deficiencies in the program or the documentation. The addresses are given in Appendix 2. 1.1 BBC KERMIT CAPABILITIES AT A GLANCE Local operation Yes Remote operation No Transfer text files Yes Transfer 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 No Terminal emulation Yes Communications settings Yes Transmit BREAK Yes IBM mainframe communication Yes Transaction logging No Session logging (raw download) Yes Raw transmit Yes Act as server No Talk to server Yes Advanced server functions No Advanced commands for servers Yes Local file management Yes Handle file attributes No Command files Yes Command macros No 2: AN OVERVIEW OF KERMIT KERMIT is a system, devised at the Center for Computing Activities at the University of Columbia in New York (CUCCA), to permit the simple and flexible transfer of data from a microcomputer to a mainframe or another microcomputer. CUCCA retain the copyright on KERMIT (the programs are not "public domain"), but have published full information on it and permit anyone to implement it on their own machines, provided this is not done for commercial purposes and that copies are sent to them for distribution. The result is that KERMIT is now available on a very wide range of machines indeed: very few micros and mainframes do not have a KERMIT of some sort suitable for them, and the programs can be easily acquired from the Lancaster University KERMIT distribution service. The primary design aim of KERMIT is to permit the reliable transfer of any data whatsoever between systems, and to make the data usable on the system that receives it if this is possible. To illustrate why this is important, and not possible with simple systems, we can consider an ordinary terminal emulation system that allows data to be captured into files or sent from them. Simple terminal emulator systems, such as those commercially available for the BBC micro, do permit you to transfer files from a mainframe in a rudimentary way. You would tell the emulator to copy any characters that appear on the screen into a file, then ask the mainframe to display the file. The reverse process would let you input data into a mainframe file from your BBC discs. The problems arise in the nature of the communications system that connect the micro to the mainframe, and how the mainframe itself uses this system. A character of data in a file occupies one byte, which consists of 8 binary digits or "bits". If you regard the pattern of bits representing a character as a number, this allows numbers ranging from 0 to 255 to be used. However, many communications systems will allow only 7 of the eight bits to be transmitted along them. The most significant bit, termed the "parity bit", is used by the communications system as an error-checking device. Thus, even though you send a byte of 8 bits to the mainframe, it may receive only 7 of them. This immediately restricts the range of characters that can be sent to those whose codes are in the range 0 to 127. A further restriction may be imposed if the communications system uses some of those characters for its own control purposes: thus systems often will use the characters whose codes are 17 and 19 to prevent overloads occurring. In such systems, you cannot transmit these characters at all. To make matters even worse, some machines will (apparently arbitrarily) decide that you could not possibly want to send some characters, so, if you do send them, it will change them into something else entirely. As far as the BBC micro is concerned, you could just about live with such problems. The character range 0 to 127 covers all the printable characters, so that transferring text files should just about be possible. Of course, if the communications line you are using is unreliable or noisy (a dial up connection over telephone lines, for instance, can be expected to garble a significant number of characters) there is nothing to prevent data being corrupted in transmission, so that you will never be sure that the data that arrives is the data that you sent. But although text files are about manageable, those including teletext control codes or word processor control codes are highly unlikely to be, since such codes are likely to lie in the range 128 to 255; and tokenised BASIC programs produced by SAVE haven't a hope of being transferred in any useful way at all. KERMIT overcomes all these difficulties by encoding the data it sends according to a standard set of rules or "protocol". The rules recognise that many characters cannot be transmitted down a communications line, so if those characters occur, they will be translated into something that can be transmitted. The receiving end, of course, will translate them back again to what they were. This technique enables you to send any data at all, even SAVEd BASIC files or machine code programs. It further guarantees that the data you send is the data that arrives, since KERMIT uses special methods for detecting garbling and will repeat any transmissions that did not get through correctly. KERMIT's encoding and checking techniques are more efficient than some other systems that offer this facility, since only bytes that need encoding actually are encoded, thus keeping the volume of data sent to the minimum possible. Besides the problems of actually transferring data corectly, there is the problem of making it usable on the other end of the transmission link. If you are sending, say, a SAVEd BASIC program to a VAX, this isn't a problem, since the VAX can't understand BBC BASIC anyway. Nor does it matter if you use the VAX system only as an archive: it's irrelevant how the data is held on the VAX, as long as when it is brought back to the BBC side it looks the same as when it was sent. The usability problem does appear, though, if you want to move a file from a BBC to a VAX and then actually use it on the VAX. You might, for instance, word process a file on a BBC, then send it to a VAX to be printed. In this case, you do not want to transfer the data byte-for-byte, since the way the BBC and the VAX denote things like the end of each line of text will almost certainly be different. What you require is that the file of printable lines on the BBC, which you can process on that machine, becomes a file of printable records on the VAX, that can be processed there. Using a dumb terminal emulator system would probably let you send the data, but it would appear byte-for-byte as it was on the BBC. And probably you would get a file on the VAX with extra line-feeds and carriage-returns that would need laborious editing before you could use the file sensibly. With KERMIT the problem can easily be circumvented. The KERMIT protocols define a standard way of indicating the end of a printable line. When you send a file from the BBC, BBC KERMIT will translate whatever ends the lines of text in your file into this standard form before sending the data. The receiving end, seeing this standard end-of-line indicator, will translate it into however it indicates end-of-line. You thus end up with a usable file of lines, with no extra characters anywhere. The requirements you must meet before using KERMIT are simple. You will need a BBC KERMIT in your BBC micro; a KERMIT program in whatever mainframe or micro you wish to transfer data to; and a way of linking the machines, be it a network, an ordinary cable, or a piece of wet string. For a micro to micro transfer KERMIT is extremely simple to use. You would, for example, tell one machine that it is going to receive a file, tell the other to send it, and sit back and let them get on with it. Micro to mainframe transfers involve an extra step, which is also simple. BBC KERMIT includes its own terminal emulator program: you initially use this to log in to the mainframe as though the BBC micro were an ordinary terminal. Once logged in, you start the KERMIT program on the mainframe, and can then flip from giving commands to this mainframe KERMIT, to giving commands to BBC KERMIT. As before, once you have told each side to transfer a file, you just sit back and relax while it happens. And KERMIT provides one further facility to help you spend your time doing more useful things. As well as sending one file at a time from one machine to the other, you can send them in groups: thus, you could say "send all the files on my disc to the VAX" in one command. The KERMIT programs will send the files one by one until all are gone, quite automatically.