Q 1 S Kermit Abstract This document describes the Kermit file transfer protocol as implemented at ICCC. Frank da Cruz and Bill Catchings wrote in Byte in June 1984: `A communication protocol is a set of rules for handling packets of information; Kermit is not written in any particular language as it is not a portable program but a portable protocol.' Bulletin: NOS Kermit Authors: Allison Ballard Paul Jarvis October 1986 Q 1 LIST OF CONTENTS Section Page 1. Introduction 1 1.1 Notation used 1 2. Quick guide to using Kermit 2 3. File types on the Cyber mainframe 3 3.1 Structured files 4 3.2 File formats supported by Kermit 4 4. Understanding Kermit 5 4.1 Server mode 6 4.2 Local and remote 6 4.3 Error handling 6 5. Running Kermit on the Cyber mainframes 6 5.1 Explanation of Set command parameters 7 6. Extensions to the Kermit command 8 7. Glossary 8 Appendix 1 - Running Kermit on an IBM PC/AT 9 Appendix 2 - Running Kermit on Zenith Z148s 10 Appendix 3 - Running Kermit on a BBC micro 11 Q 1 1 NOS Kermit 1. Introduction Imperial College is typical of many institutions which have a large time-sharing computer and a number of smaller systems within departments. Thus, the need arises to transfer files between the central computer and the departmental systems. There is also a requirement to transfer files between different microcomputers that are available throughout the college. Kermit was developed at the Columbia University Centre of Computing Activities (CUCCA) in 1981-82, largely by Bill Catchings and Frank da Cruz. It now runs on almost all the popular personal computers and a wide range of mainframe computers. This document assumes that you are familiar with the Cyber mainframes. If not you should refer to EXPLAIN, the on-line help facility, to find out how to manipulate files on the Cybers and how to ensure that files are saved. (See ICCC Bulletin number 2.4/6, available from the Documentation Office.) You will find information on how to run Kermit on different micros in the appendices at the end of this document. 1.1 Notation used Any character or sequence of characters enclosed in angle brackets, < > , means press the key so marked. E.g. < return > means press the key labelled return. To indicate when you press two keys together the following notation is used: < ctrl + Y > This means press the 'control' key and while you hold the key down type the Y key. Then release the control key. Do not type the angle bracket keys on the keyboard. If you need to press two keys together followed by a third by itself, the following notation is used: < ctrl + P > A This means press the key labelled control and while you hold this down type the P key. Release both keys and then type the A key. Do not type the angle brackets on the keyboard. Items enclosed in square brackets, [] including any punctuation, are optional. 2. Quick guide to using Kermit to transfer files For a successful Kermit transfer two copies of Kermit are required, one on the local system and one on the remote system with which you wish to transfer files. The following shows you how to transfer files between a Cyber mainframe and a BBC micro. a. Start Kermit on the BBC by typing: *KERMIT b. In response to the Kermit prompt type: Q 1 2 NOS Kermit CONNECT c. Run Kermit on the Cyber by typing: KERMIT d. Type in the micro Kermit's escape sequence < ctrl + f0 > to return to the micro. e. Type in required Kermit commands, for example: SEND filename to send a file to the mainframe GET filename to retrieve a file from the mainframe. When you transfer a file, in either direction, you must ensure that the correct file format is used. Failure to observe this rule will result in the transferred file being unusable. For further information see section 3. f. There are three commands you can use to exit from Kermit when you have finished transferring files. If you enter: BYE the Cyber Kermit finishes and you log off. However, the micro is still running Kermit. If you enter FINISH The Cyber Kermit terminates; however, you are still logged in to the mainframe and can now enter NOS commands. The micro is still running Kermit. If you enter EXIT The micro version of Kermit is terminated, however, the mainframe state is left unchanged. I.e. If you enter 'finish' followed by 'exit' then the mainframe will be waiting for a NOS command and the micro will also be waiting for a command. 3. File types on the Cyber mainframe For those who are not used to the Cyber mainframe the following section describes some of the file types that are available. A description of Indirect access and Direct access files is given since some large files may need to be stored as Direct access files. a) Indirect access files ( IAF ) Q 1 3 NOS Kermit These are by far the most common type of file on the system, about 99% of files are IAFs. They are typically only a few sectors long and can contain all types of information, e.g. source programs, data, text. When you work on an IAF you are in fact using a local copy of the permanent file. If you change or create the local version of a file you have to make it permanent if you want to keep it. You can have a number of versions of the same file, providing you give each version a different name and you have enough disk space allocation. IAFs are created by SAVE and REPLACE commands and retrieved by GET and OLD commands. Because the local copy of the file is temporary in nature, if you log off or your batch job finishes the file is destroyed. If you want to keep the local copy you can either use the REPLACE command, in which case the old permanent file is overwritten, or you can use the SAVE command and make a copy of the file into a new IAF with a new name. Obviously, as a copy is involved each time the file is accessed the system can take a long time retrieving large files. For this reason a limit of 256 sectors is placed on IAFs. Above this size you must use a Direct access file. b) Direct access files ( DAF ) These are mainly used for files greater than 256 sectors in length and for files transferred between computers with the File Transfer Protocol (FTP). DAFs are created and accessed with the DEFINE and ATTACH commands. You act directly on a DAF, thus, if you modify the contents your changes take place immediately. Because DAFs are not accessed via a local copy they do have speed advantages, but they cost more. This is a consequence of the way they are stored on disk. On our present hardware system, disk space is assigned to DAFs in complete tracks, each of 640 sectors. If a DAF fills one track, another is assigned, so space is lost to the system in multiples of tracks regardless of the actual size of your DAF. Hence, a DAF which is not a multiple of 640 sectors in length has some wasted space associated with it. In contrast, an IAF only occupies the space it needs. Therefore, DAFs are not an efficient or cost effective way of storing small files, since they are charged to your allocation according to the number of tracks you use (i.e. in multiples of 640 sectors). Obviously, to keep a DAF you need an allocation in excess of 512 sectors. 3.1 Structured files Certain files on the Cybers are structured that is, they may contain pointers, within the file in order to ascertain where data is located, or they may contain delimiters which are not recognised by Kermit. These files cannot be transferred using Kermit. N.B. most text files are not structured. 3.2 File formats supported by Kermit Kermit only supports some of the many file formats that are available on the Cyber mainframes. Even with the reduced set available, there are still a number of pitfalls to avoid. A summary of the supported file formats follows. Further information can be found in the CDC manuals, available for short term loan or reference from the Documentation Office. Q 1 4 NOS Kermit DIS64. This file format stores each received character as a six-bit quantity and, hence, there are only 64 allowed characters. This is the default file format on the Cyber machines although Kermit defaults to ASCII. DIS64 is used by the FORTRAN compilers and so you should transfer any such source files using this file format. There is one major flaw with this format and that is the representation of the 'end of line', which is '0000'. As a colon (':') is stored as '00' two or more consecutive colons could produce an 'end of line'. Although this may seem an unlikely occurrence, it can still cause obscure errors. ASCII Kermit uses this file format by default. The full 128 character ASCII standard is supported so that any text file from a micro can be stored with all characters remaining intact. Note that the Cyber character size is six bits so, in order to obtain the full 128 ASCII character set, a convention is used where by some ASCII characters are saved as two Cyber mainframe characters. For example, the character 'A' is stored as '01' and the character 'a' is stored as '7601'. The Cyber mainframe file therefore contains either six or twelve bits per ASCII character and, hence, this file format is often referred to as '6/12' format. When an ASCII character is stored as a twelve bit value, the first six bits are either '74' or '76' which correspond to the Cyber mainframe characters '@' and ^ (which have an alternative twelve-bit representation). If an operation is done on a file and any resulting output has a liberal quantity of '@' or ^ characters then it is reasonable to assume that the file is in ASCII format. However there is no absolute method of determining the file format. ASCII8 This file format supports the full ASCII character set and each character is saved as its eight bit value. As the Cyber machines use a 60 bit word length, where eight bit values cannot be packed exactly, each eight bit ASCII character is saved within twelve bits. This means that five ASCII characters can be stored per machine word. This file format is often referred to as '8 in 12': eight data bits are saved in each 12 bits of the computer word. This file format is probably the least popular of those supported by Kermit. HEX This is not a Cyber mainframe file format but one invented specifically for Kermit. If a file is transferred into a Cyber mainframe, using one of the above file formats, one or more blanks may be added at the end of the file to ensure that the file contains a complete number of computer (60 bit) words. If this file is subsequently transmitted back to the source micro these blanks will be sent so that the received file is not identical to the one sent. To overcome this problem you can use HEX mode. This stores each received ASCII character as two hexadecimal digits and will only transmit similarly coded files. Thus, the file returning to the original micro will be identical, although not particularly useful on the Cyber. 4. Understanding Kermit The previous sections describe how to use Kermit for transferring files between a micro and the Cyber mainframes and file types available. This section introduces you to some of the concepts and tools that Kermit uses in order to achieve a successful transfer between a number of different types of micro and the Cyber mainframes. Kermit transfers data in the form of packets. A packet contains Q 1 5 NOS Kermit information, in the form of characters, to enable Kermit to exchange both commands and data. Generally, when one packet is transmitted no further transmission occurs until the receiving Kermit has acknowledged that the packet has been successfully transferred. Each packet contains a sequence number and length. The sequence number ensures that no packet is lost and the packet length enables the end of the packet to be located. The end of the packet contains a check character, as defined by the contents of the packet, to enable error checking. Kermit is very easy to use, but some people may find it difficult to understand that Kermit involves running two programs at the same time on two computers from the same terminal, and that one computer will sometimes pass on your commands to the other. To clarify this, let us first describe the different states or conditions each computer can enter. Your micro can be in one of four states or conditions: 1 Not running Kermit 2 Running Kermit and expecting a command from you. This is called Kermit command mode. 3 Running Kermit and pretending to be a normal terminal. In this state it passes almost everything typed to the Cyber. There is a special 'escape character(s)' which restores the micro back to Kermit command mode. 4 Running Kermit, but not acting as a terminal nor expecting a command. In this state Kermit is exchanging information with the Cyber in the form of specially encoded packets. At the same time the Cyber may also be in one of four states: 1 Not connected to your micro, i.e. not logged in. 2 Connected to the micro but not running Kermit. In this state the Cyber expects a normal NOS command. 3 Running Kermit and waiting for a Cyber Kermit command. The Cyber is in Kermit command mode. 4 Running Kermit but not expecting a Cyber Kermit command. In this state the Cyber is expecting to exchange code information with the micro. 4.1 Server mode When using Kermit on the Cybers the default is to put Kermit in server mode. Server mode enables you to enter commands to the Kermit running on the micro which will then instruct the Cyber mainframe accordingly. If you do not use Server mode you must enter commands to both the Kermit on the micro and the Cybers. You can, if you wish, use the Cyber mainframe in non-Server mode. This is used if your micro has an implementation of Kermit that cannot talk to Servers. If you find that you cannot use the GET command on your micro Kermit, you will not be able to use Server mode to transfer files. 4.2 Local and remote In a lot of Kermit documentation, you will see references to a local Kermit and a remote Kermit. The local Kermit is the version of Kermit available on the machine that you are using to input commands, i.e. if you are using a micro in the Microlab, the local Kermit is the version available on that micro. The remote Kermit is the version of Kermit on the machine that does not receive direct input from you, i.e. if you are using a micro in the Microlab to transfer files to and from the Cyber mainframes, the remote Kermit is the Kermit on the Cyber. You have to go through the local Kermit Q 1 6 NOS Kermit in order to issue commands to the remote Kermit. 4.3 Error handling If an error occurs during transfer then Kermit attempts to recover by resending the corrupt or missing data. Many implementations of Kermit will display a re-try count which indicates the number of recovery attempts. Similarly, if transfer appears to stop then the sending Kermit will be asked to re-transmit its last packet. This will also be counted as a re-try. If this re-try count exceeds its limit then the transfer will be aborted. This limit may be 'set' for the micro Kermit, see relevant documentation for the Set command. 5. Running Kermit on the Cyber mainframes You start the Kermit program that resides on the system by entering the command: KERMIT. This command will start Kermit running in Server mode, using the default parameters, as indicated below. Should you need to change any of the parameters from their default values then use the alternative form: KERMIT,I. This will initialize an interactive dialogue. After the prompt: NOS KERMIT > you can specify any of the following: Command Parameters Default ------- ---------------------------------------------- ------- SET CODE DIS64 (set 6 bit display code) ASCII (set 6/12 display code) * ASCII8 (set 8 in 12 ascii) HEX (set hex pair code) DEBUG OFF (deselect debug logging) * ON (select debug logging) DELAY n (set delay time to n seconds) 0 MODE LOCAL (leave files local) SAVE (save files, do not replace) * REPLACE (replace files) WINDOW OFF (deselect windowing option) ON (select default window size of 8) * SIZE m (set window size to m where 0 you should set your default disk drive to drive B, the drive containing your data disk, not the system disk. To do this enter: SET DEFA B: 3. Now connect to the Cyber by typing: C < return > 4. Log in to the Cyber as usual; when the Cyber asks for your terminal type you should enter VDU. The system prompt, /, will now appear on your screen. 5. To run Kermit on the Cyber you enter: KERMIT. 6. Now escape back to the Zenith by typing: < ctrl + ] > C This will return you to the Micro Kermit prompt. 7. To transfer a file from the Cyber to the Zenith enter: GET filename 8. When you have finished using Kermit you should finish the session as described in section 2. Transferring a file to the Cybers 1. Follow steps 1-6 above. 2. To send a file to the Cyber enter: SEND filename 3. Finish the session as described in section 2. Q 1 11 NOS Kermit Appendix 3 - Using Kermit on a BBC Micro Transferring a file from the BBC to the Cyber 1. Start running Kermit on your micro by typing: *KERMIT 2. In response to the Kermit prompt type: CONNECT 3. Run Kermit on the Cyber by typing: KERMIT. 4. Type in the micro Kermit's escape sequence < ctrl + f0 > to return to the micro. 5. To send a file to the Cyber enter: SEND filename 6. Finish the Kermit session as described in section 2. Transfering a file from the Cyber to the micro 1. Follow steps 1-4 above. 2. To transfer a file from the Cyber to the micro you should now enter: GET filename 3. Terminate the Kermit session as described in section 2.