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.
