5: TRANSFERRING FILES WITH BBC KERMIT The primary use of BBC KERMIT is to transfer files between it and a mainframe computer, or between it and another microcomputer. The methods used will be substantially the same whatever the other system is, since any KERMIT system should be able to communicate with any other. Though the general techniques will be the same, the exact commands used to control the remote KERMIT will vary from one system to another. You will need to consult the user guide for the remote system to discover how it should be controlled. In this section we shall cover in detail how BBC KERMIT is controlled. 5.1 PRINCIPLES KERMIT differs from other "dumb" file transfer systems (such as you might find in a terminal emulator ROM, for instance) in that it aims to transfer files not only reliably, but also in a usable way between systems. Thus, if you have a program source on your BBC discs that you can edit with some BBC micro editor, and transfer this to a mainframe, the resulting file should also be editable on the mainframe's editors. KERMIT will resolve all the differences in how files are stored on your behalf, so that, in this example, the mainframe file will not contain extra line-feed characters at inconvenient places that the mainframe editors cannot handle. Transferring files with KERMIT involves several discrete steps. We shall consider here the most common case of transfer to and from a mainframe and look at the several steps involved in a general way. 1. You start BBC KERMIT is and set it up for the transfer. In particular, you may wish to tell it what types of file are to be moved. You will also need to set the parameters for terminal emulation, and, depending on the needs of the communications system and the remote KERMIT, you may need to change some of the more detailed aspects of BBC KERMIT's operation (though this is unlikely). 2. You enter terminal emulation mode, and log the BBC system in to the mainframe as though it were an ordinary terminal. 3. Using the BBC system as a terminal, you start the mainframe's own KERMIT program running. 4. You can now give commands to the mainframe KERMIT (from terminal emulation mode) and to the BBC KERMIT (from KERMIT command mode) to transfer your files. The two KERMIT systems will communicate with each other using the standard KERMIT protocol. 5. After the transfers are done, you can log the BBC system out from the mainframe. In practice, the steps taken will range up and down this list as required. For example, BBC KERMIT parameters can be changed at any time, not only at the start, and if you are moving several types of file you will need to change them frequently. Also, things may be made much simpler if the mainframe KERMIT provides what is known as "server mode operation" - we shall discuss this later. The following sections will discuss the various aspects of file transfer in more detail. 5.2 FILE TYPE The most important thing that you will need to consider when transferring files using BBC KERMIT is the file type of the files involved. As we saw in the overview of KERMIT in chapter 2, one of the facilities that KERMIT provides is that files are transferred in a usable way, with the method the sending system uses to denote the end of a line being automatically translated into the method the receiving end uses. Many operating systems (for example MS-DOS) don't care at all how you denote the end of a printable line, and will raise no objections whether your file uses Carriage-Return bytes, Line-Feed bytes or anything else. Mainframes, though, are usually much more choosy, and can be quite perverse. Some mainframe systems store actual byte sequences (such as an actual Carriage-Return byte) in the file to mark the end of a line. Others may assume a line is finished when some byte such as Carriage-Return is input, but don't store the actual byte in the file, using instead some method of recording the number of characters in the line. And even worse, some mainframe systems expect you to decide what they should do - this can be particularly awkward if you are transferring binary files that don't contain printable, separate records anyway. The way the KERMIT system in general handles this is that all KERMITs, when sending a file, translate their own system's end-of-file indication into a standard form. The KERMIT that receives the file then knows exactly where each record ends, and translates the data into whatever format its system needs. Now this would be perfectly simple and easy, except for the fact that on the BBC Computer there is no uniform way of denoting the end of a record. Each program or ROM you may use can use whatever bytes it likes to denote the end of a record, and these are likely to be different. Thus a file you produce with *SPOOL contains Line-Feed/Carriage-Return pairs at the end of a line, but a spooled Wordwise file contains only Carriage-Returns. There is no way at all for BBC KERMIT to know what bytes are used, so it is up to you to tell it by setting a "file type". How end-of-record is denoted is also of importance when you move files to BBC KERMIT from another system. Here you will want BBC KERMIT to translate the KERMIT standard end-of-record indicator into something suitable for whatever program or ROM you are going to process the file with. In the sections below we shall look at the possible file types you can select, then examine how you can work out what the type should be for a particular file. 5.2.1 Binary files These files contain data that is not primarily printable text, such as SAVEd BASIC programs, machine-code programs, screen dumps or *SAVEd areas of memory. When you transfer these files, you wish every byte in the file on one system to appear unchanged in the file on the other system, regardless of what it is. You tell BBC KERMIT that you are handling binary files with the command SET FILE TYPE BINARY which tells it not to change any data that it either sends or receives. You may need to issue a comparable command to the remote KERMIT, to prevent it trying to manipulate the data itself. Some remote KERMITs may not allow you to send pure binary data, though, and you will not be able to send binary files to them in this case. 5.2.2 Printable text (ASCII) files These files contain printable text, such as you might produce with the *BUILD command, or by spooling a BASIC program listing to disc. When you transfer one of these files, you will want the two KERMITs to translate the way end-of-record is indicated, rather than transfer every byte exactly as it is. You tell BBC KERMIT that ASCII text files are to be transferred with the SET FILE TYPE ASCII command. This specifies that the files are text, but BBC KERMIT will also need to know how the end of a printed line is indicated in this file. The command shown above sets the end-of-line indication to the default of Line-Feed followed by Carriage-Return (LFCR), but this may not be what you require. You can tell BBC KERMIT your needs with a further parameter, which is one of the strings LFCR, CRLF, LF or CR. Thus, for example, SET FILE TYPE ASCII CR tells BBC KERMIT that files are text, and end-of-line is indicated by a Carriage-Return byte on its own. When you then send a file, every CR byte is translated into the internal KERMIT represenation of end-of-line. On receiving a file, the internal KERMIT form will be translated into a CR for you. 5.2.3 How to decide on the file type to use There is, unfortunately, no easy way of telling how the end of a printed line is denoted in a file. However, you can inspect the file with the *DUMP command with, for instance *DUMP FILE This will print a file in hex and character form on the screen. You can then locate the end of a line of text and see what characters follow in the hex area of the dump: a CR byte appears as 0D, and an LF will appear as 0A. In this example, if your file contained only the lines ABCDE FGH IJKL you might see the dump looking like this 0000: 41 42 43 44 45 0D 46 47 ABCDE.FG 0008: 48 0D 49 4A 4B 4C 0D ** H.IJKL.. which would indicate that the file starts with a line "ABCDE", terminated by one CR byte, then has a line "FGH" terminated by a CR byte, then a line "IJKL" terminated with a CR byte. You would then need SET FILE TYPE ASCII CR to transfer such a file. The sequences you should look for in the dump are then: 0D CR 0A LF 0D 0A CR LF 0A 0D LF CR If you ever encounter a sequence such as 0D 0D (CR CR) this indicates that one line terminates with a CR, and the next line, also terminating with a CR, is blank. Some of the common files you will come across have the following file type: SAVEd BASIC BINARY Spooled BASIC listings ASCII LFCR Saved WORDWISE files BINARY Spooled WORDWISE text ASCII CR *BUILD files ASCII CR ADE editor files ASCII LFCR *SAVEd files BINARY Machine code programs BINARY37 5.3 SENDING EIGHT BIT DATA As we saw in chapter 2, characters are stored in a file in "bytes", and each byte consists of 8 separate binary digits or bits. Each byte can contain a number between 0 and 255, and so there are 256 possible characters that you can write into a file. Unfortunately, it is common for communications systems to let through only 7 bits from each byte, using the eighth bit for their own purposes. Thus you can normally send only characters whose ASCII codes are in the range 0 to 127. Many text files on the BBC, though, and every binary file will contain bytes from the whole character set, with codes from 0 to 255, so there is a potential problem in transferring such data correctly. KERMIT in general has a technique for overcoming this restriction, by encoding characters in the range 128 to 255 into special sequences that can be sent down any communications line. Almost all modern KERMITs will use this technique, which is known as "eighth bit prefixing", but you may encounter an older implementation on some machine that does not support it. In this case your data will be garbled in transmission. There is, regrettably, no way round this problem from within KERMIT, but BBC KERMIT will warn you when the problem is detected: a message "WARNING : Non ASCII data encountered" will appear on the display screen. In order that the amount of data sent down the communication line is not unnecessarily large, there are some rules governing when BBC KERMIT and the remote KERMIT will perform eighth-bit-prefixing, since the technique increases the amount of data that must be sent whenever characters that use the eighth bit are encountered. 1. If the remote system has been set up with its own commands to ask for eighth-bit-prefixing, BBC KERMIT will always use it. 2. If you have used the SET PARITY command to select a value that implies that only 7 data bits can be sent down the communication line (i.e. if you have set the value to SPACE, EVEN, ODD or MARK) then BBC KERMIT will attempt to use eighth-bit-prefixing. Whenever you send a file from the BBC, BBC KERMIT will request the remote system to use eighth-bit- prefixing; whenever the remote sends a file to the BBC, BBC KERMIT will use eighth-bit-prefixing unless the remote KERMIT has said that it does not implement it. The status screen will tell you whether or not eighth-bit-prefixing is in use during a transfer so that you will know when you might expect problems. 5.4 STARTING UP THE MAINFRAME KERMIT In order to run the KERMIT program on the mainframe system, you will need to log your BBC computer in as a terminal, using BBC KERMIT's terminal emulation facilities. This is described in detail in Chapter 4. Once you have logged in, you can start the mainframe's KERMIT program. How this is done is of course dependent on the other system, but the command is probably "KERMIT" or something similar. You should consult the user guide for the mainframe system to find exactly what to do. The mainframe KERMIT will certainly be able to operate as a normal KERMIT (termed non-server mode). In this mode, you will need to give commands both to it and to BBC KERMIT for every file transfer (here a transfer of a group of files in one go counts as one operation), which will involve you in continual changes between BBC KERMIT command mode and terminal mode. Alternatively, more sophisticated mainframe KERMITs may operate in "server" mode. Here you issue one command to the mainframe KERMIT (usually "SERVER" or something similar) to put it into server mode. Now you can control all operations from BBC KERMIT command mode: you do not need to continually switch to terminal mode to give commands to the mainframe KERMIT. You can start file transfers, and even, with some mainframe KERMITs, manipulate files and obtain directory listings from the mainframe side simply by giving commands to BBC KERMIT. In general, you should always set the mainframe KERMIT into server mode if this is possible. The exact way in which you transfer files will depend on whether you are talking to a server or a non-server, and we shall consider each in turn. 5.5 USING BBC KERMIT WITH A REMOTE SERVER As we have seen, you should put the remote KERMIT into server mode with a command such as "SERVER". You will then probably see a message telling you something like "use your micro's local escape sequence to return to command mode": the exact text (and whether it appears at all) depends on the remote system in use. You should press CONTROL and F0 together, and BBC KERMIT will enter command mode, showing you the command mode screen. You can now control the whole operation from BBC KERMIT command mode. 5.5.1. Sending files to a server To send a file to a server you simply use the command SEND. The reference section describes the use of the command, its side-effects and facilities, in detail, and you should consult it for further information. The basic use of the command is simple. To send, for example, a file called BEEBLE, you would type SEND BEEBLE You will now see the file transfer status screen appear, and information about the transfer will be displayed. Normally, BBC KERMIT will pause for 30 seconds here - this is because it has to cater for the requirements of a non-server remote system as described below. You can either wait the full time, after which the transfer will start, or you can press any key to force the transfer to begin at once. You can alter this pause period if you wish with the SET DELAY command - this is described in the reference section. In this example, BBC KERMIT will ask the remote system to call the file it receives BEEBLE.BBC (although the remote system doesn't have to if it doesn't want to or if that isn't a legal filename for it to use). If you wanted the file on the other system to be called something else, you can use a different format of the SEND command, putting SEND BEEBLE /44d/frogspawn/pudding Here BBC KERMIT will ask the remote system to store the data in "/44d/frogspawn/pudding". You can put what you like in the filename, providing that it does not contain spaces and is not more than 48 characters long. Alternatively, you can make BBC KERMIT add a different suffix from ".BBC" when it is forming the remote file name. The command SET FILE SUFFIX TOAD would cause BBC KERMIT to add ".TOAD" to the name, for example. The command also allows you to stop any suffix at all being added: you should consult the reference section for further details. You can, if you wish, send a group of files in one operation by specifying "wildcard" characters in the name. BBC KERMIT will then send all the files whose names match, one after the other automatically. Two different wildcard characters can be used, as follows: 1. The "*" character can be used to match against any number of characters in the names of the files in the directory. Thus, if you specified a name B*S then files called BIRDS, BLINKS, BUS and BS would be transferred. If you specify a name simply as "*", then all files will be transferred. 2. The "#" wildcard character can be used to match against exactly one character in the real filenames. Thus, if you specified a name B#G then files BUG and BIG would be transferred, but files BANG and BG would not be. BBC KERMIT uses the facilities of the curently selected filing system to locate files whose names match a wildcarded one, and depending on its operation there may be restrictions on where you can make it search. If you using the Acorn DFS or DNFS, for example, only the current directory is searched, so that although a wildcarded name such as DAT* is acceptable, a name such as :1.DAT* cannot be used, and no matching files will be found for it. 5.5.2. Fetching files from a server Fetching files from a server is also simple. If the remote system has a file called GROMMET.TXT, you can move it to the BBC with GET GROMMET.TXT The file transfer status screen will appear, and the transfer will start immediately. In this example, the data will be stored in a file called GROMMET in the current directory and drive. If you want a different name, you could put, for instance, GET GROMMET.TXT :3.B.PLUG and the data will be stored in file :3.B.PLUG. In the first example, there is of course a risk that you may already have a file called GROMMET: this risk is increased if BBC KERMIT has to change the file name a lot to make it acceptable to the BBC filing system. Accordingly, by default BBC KERMIT will try to amend the name it uses if there is a clash. Characters will be changed, starting from the right, into "&" characters until a unique name is formed. You will be told whenever this occurs. If you wish, you can change this facility: issuing the command SET FILE WARNING OFF will turn this check off, and BBC KERMIT will overwrite any file whose name is the same as the new file, losing its original contents. Note that BBC KERMIT will transform unacceptable names to make them legal to the Acorn filing system standard: it will not take advantage of filing systems that allow, for example, file names longer than 7 characters. You can fetch a group of files from the server in one operation by including the remote system's wildcard character in the name. The remote system will then send each file in turn automatically. 5.5.3 Controlling a remote server Many of the more modern mainframe KERMITs that support server mode operation allow the micro KERMIT to perform a number of useful operations on mainframe files through them. If the mainframe KERMIT you are using is one of these, you will be able to do things such as listing files and directories, deleting and renaming files, all with commands issued to BBC KERMIT without the need to enter terminal emulation mode. These operations are all initiated with the BBC KERMIT command REMOTE, which passes a request to the mainframe system for some action. The command is always followed by some parameters to specify the action you are requesting, and we shall look at the various possibilities below. You should note, though, that not all servers implement all the facilities described here (some implement none at all), and some interpret the commands differently from others. You should consult the user guide for the server in use to see the precise details. Note here that some mainframes may take a long time to respond to these commands, so that you may need to turn timeouts off if you have been using them. You can interrupt any REMOTE command producing a large amount of output by pressing CONTROL and Z. 1. Listing a directory The command REMOTE DIR will produce a directory listing from the server. The exact layout and selection of names will depend on the server: some will allow you to specify, for example REMOTE DIR ABC* to list all files with names starting "ABC". 2. Changing the current directory The command REMOTE CWD will request the server to change the default place in which it looks for files. Typing the command on its own will reset the directory to whatever the default value is: if, though, you typed something like REMOTE CWD [.SUBDIR] you would change the directory to [.SUBDIR]. If you do specify a name here, BBC KERMIT will ask you for a password: if your mainframe system requires one you should type it, then press RETURN. The password will not be echoed on the screen as you type. If your system does not require a password, simply press RETURN here. 3. Displaying a file The command REMOTE TYPE will display a file owned by the mainframe on the BBC screen. You could, for example, type REMOTE TYPE MYLIST.LIS to examine a file called MYLIST.LIS. 4. Obtaining help The command REMOTE HELP requests the server to display some help information to you. You can either type the command by itself, or, on some systems, you can specify a topic. Thus REMOTE HELP will normally provide you with a "first level" display, and REMOTE HELP files for example might produce some help on the specific topic of "files". 5. Displaying server status Issuing the command REMOTE STATUS will produce a display giving details of the server's operation. 6. Examining who is logged in Issuing the command REMOTE WHO will produce a list of all the users currently logged in. 7. Copying a file The command REMOTE COPY requests the server to copy a file on the mainframe. You could type, for example REMOTE COPY LUMBER.TXT DUTCHELM.DED to copy file LUMBER.TXT to a new file called DUTCHELM.DED. 8. Renaming a file The command REMOTE RENAME requests the server to change the name of a file on the mainframe. You could type, for instance REMOTE RENAME /wondrous/thing /old/hat to change the name of /wondrous/thing to /old/hat. 9. Deleting a file The command REMOTE DELETE requests the server to delete a file on the mainframe. Thus, typing REMOTE DELETE DOCTOR.WHO would delete the file DOCTOR.WHO. 10. Interrogating disc space usage The command REMOTE SPACE requests the server to report on your current disc usage. Some servers may allow you to specify a selection parameter: thus you might be able to type REMOTE SPACE //disc99 to see how much space you have available on a specific disc drive. 11. Issuing a host command The command REMOTE HOST requests the server to issue a command to the command interpreter of the host. The command to be issued is whatever follows REMOTE HOST on the line: thus if you were to type REMOTE HOST CREATE/DIR [.FRED] when using a VAX/VMS server, the command CREATE/DIR [.FRED] would be issued to the command interpreter to create a directory. Note that care is needed in the choice of command: it must be one that requires no input from the terminal, since of course, there is no terminal available to provide the input. 5.5.4. Closing down the server Once you have finished moving data, you can close down the remote KERMIT server. Again, you do this from BBC KERMIT command mode. Typing the command BYE will tell the server to close down, and your terminal will be automatically logged out. Typing FINISH will tell the remote KERMIT to cease operating, but here the terminal will still be logged in.