> <BBCTape$Dir>.!Help

                    !BBCTape - BBC to Arc file copier
                    =================================

!BBCTape is an application to transfer files from a cassette-based BBC micro
to an Archimedes. It may also work with a disc system (see Technical file in
the !BBCTape directory), but better things exist for discs (e.g. Beebug's
serial link).

  To use the program you need a serial lead to join the Arc and Beeb,
appropriately wired. You can get this from e.g. Beebug for 11.50 (why is a
piece of wire so expensive?) At the Beeb end the connector seems to be able
to go into the socket in two different ways; mine works with the cutout in
the outer metal ring at the top.

  You also need to set the baud rates and serial protocols to be the same,
which they aren't by default; the program has an option to set the Arc to
the Beeb default (see below).

  Note that the maximum file length you can load with this program is about
27.5 Kbytes; normally you won't have anything longer than this, but if you
happen to have a large data file you'll either have to split it up, or
modify the program (e.g. to use sideways RAM for extra storage).

  Note also that locked files cannot be loaded by this program; it seems,
however, that comparatively few programs are locked (possibly relating to
the ease with which you can copy a tape using two tape recorders!).

  When attempting to use copied programs, bear in mind that in addition to
the difficulties associated with using any Beeb program on the Arc, there
are two particular features of tape systems which have no analogue with
discs; namely that you can have any number of files with the same name, and
that you can load a file with a null name to get the next file on the tape.
You may also find that some files are too long to load into 65Host, but you
should be able to get them into 65Tube.
                 
Program Instructions
====================

  After starting the program click <menu> over the icon. The menu tree is as
follows:

Misc      Info          Program information box
           File          File information box
           Status ...     Pops up a status window
           9600, 8n1      Set Arc serial port to BBC defaults
           Reset          Reset program to its initial state
           Clear          As reset, but also clears a file from memory

Save      Standard save box

Options   File type     Set filetype (text or hex)
           Load address  Set load address
           Exec address  Set execution address
           CR  LF        Swap carriage return and line feed
           Guess type     Guess a file type
           Auto load      Load several files
           Fast load      Slightly faster transfer, slower wimp response
           Use BGET       Load with BGET rather than OSFILE

Upload    File name      Ask the Beeb to load a file and send it

Download   Send the loader program to the Beeb

Quit       Quit!                                                       

  The most important options are <Upload> and <Download>. The first thing to
do is click on <Download>; a message* appears telling you to type "*FX 2,1"
on the Beeb keyboard, and after doing this and clicking on "OK" a program is
sent to the beeb - you should see it appear on the screen if the Beeb is
connected to a display (this isn't necessary, but it helps). While it does
this the <Upload> option is shaded. After the download finishes click on
<Upload>; a message* appears telling you to press play on the tape recorder;
the cassette motor light on the Beeb should come on, and the next file on
the tape will be loaded. Alternatively, type a file name into the <File
name> menu item, and that file will be loaded. When the load finishes a
message appears; the file can then be saved by dragging the save box to a
directory viewer or another application in the usual way.

* The message boxes for <Upload> and <Download> don't appear if you click
with <menu> or <adjust>.

 While uploading both <Upload> and <Download> options are shaded.
Downloading just shades the <Upload> option. Use <Reset> to get them back if
something goes wrong. Pressing <escape> on the Beeb keyboard will stop the
program at that end; if you want to re-start, press <ctrl-BREAK> before
sending the loader program again. The Arc program can be quit and re-started
without disturbing the Beeb, as long as you don't do it while a file is
loading.

  Alternatively, click on <Auto load> and then <Upload>. Files will then be
loaded and sent one after another, and automatically saved in the BBCFiles
directory within the !BBCTape directory (double click on the !BBCTape
directory icon with <shift> held down to see inside). Note that transferring
a file over the serial link takes some time, so you will have to turn off
the tape recorder when the cassette motor light goes out if you don't have
automatic motor control.

  The program will always ask for confirmation before saving a file if a
file of the same name already exists; this can easily  happen with a tape
system, as you may have several files on a tape with the same name.
If you don't confirm an overwrite while in <Auto load> mode the program
will drop out of that mode, and you can then use the normal save box.

  To monitor the progress of a transfer, click on <Status ...> or click on
the icon bar icon with <select>. This pops up a window which tells you
whether a file is being uploaded or downloaded; the size of the file; the
number of bytes transferred; the transfer rate; and the number of CRC
(cyclic redundancy check) errors. If the latter is non-zero the serial link
is not entirely reliable; I haven't found this to be a problem, but the file
should still transfer intact unless the link is very bad.

  Transferred files can be saved with load and execution addresses or with
filetypes; the former (which is the default) is better for files to be used
with the BBC emulator, and the latter is better for files to be used on the
Arc. This can be set by clicking on the <Load/Exec address> or <File type>
menu options respectively. The load and execution addresses are read from
the Beeb, but can be altered in the menu items. The file type defaults to
Text, but can also be set either as a name (e.g. BASIC) or a hex number
(e.g. FFB). Alternatively, click on <Guess type> to have a file type guessed
from the load and execution addresses. The guessing algorithm only chooses
from Text, BASIC, BBC ROM and Data at the moment; see the Technical file for
details of how to improve it.

  BBC text files are stored with a carriage return (CR) at the end of each
line, while most Arc programs (including !Edit) expect a line feed (LF).
Clicking on <CR  LF> swaps these over for a file in memory, and if the
option is ticked will do it for any new file loaded. Make sure you only do
this with text files! There is also an option in !Edit to do the same thing.

  The file information box shows various pieces of information; a file type
icon (as in the save box); whether CR  LF has been done; whether the file
has been saved; the file type or <untyped> for a file with load and
execution addresses; the load and execution addresses read from the Beeb
(as in the relevant menu items); the filename (as in the save box); the
original file name on the Beeb; and the file size.

  As explained below, turning off the <Fast load> option may improve the
wimp reponse if you're working on something else, at the expense of a
slower transfer rate.

  The <Use BGET> option is rather obscure; it makes the Beeb load files with
OSBGET rather than OSFILE, but it shouldn't make any difference, except
that you won't be able to re-try files which have loading errors.

  All options can be changed while a file is loading, and should give the
expected results. You can even save a file which has only partly loaded,
although I wouldn't recommend it!

Note for experts:
=================

  With a baud rate of 9600, you might expect a transfer rate of about
1 Kbyte/sec (I certainly did) and be surprised at the low rate achieved by
this program (about 100 bytes/sec). I don't think this is my fault (but I
could be wrong!); it seems to be due to three things:

1) The beeb can apparently only transmit data at about 100 bytes/sec
   (although it can receive faster). The beeb-end program is written in
   machine code, so there isn't much scope for a speed-up, except maybe
   by poking the serial buffer directly.

2) Even if it could go faster, the Arc OS_SerialOp calls only go at about
   230 bytes/sec - this is the speed of the machine code call, not Basic
   (which is much faster - a SYS "OS_WriteC",0 takes 358 s) and is about 
   the same if you use OS_Byte 145 or BGET# after opening "serial:" as
   an input file. Considering the relative power of Arc and Beeb, this
   is pathetic!

3) The consequence of 2) is that, to match the Beeb, the Arc has to spend
   half of its time just doing OS_SerialOp calls. In a Wimp program,
   this means that you either have to slow the Wimp down or make the
   transfer take longer. I've chosen the former as a default, but you can
   select a slow(er) mode (see above). Both modes go at about the same rate,
   except that if you do something in the foreground which holds the
   transfer up it will "catch up" in fast mode, putting up the hourglass.
   Downloading always uses the fast mode, which means that the wimp becomes
   almost unusable, but you only need to do it once per session.

If anyone can tell me why serial transfer is so slow, or what you can
do about it, I'd be quite interested to know!


  Finally, the boring bit. This program is FreeWare, but I retain copyright.
You can copy it freely, as long as you don't sell it for profit, and as long
as this file goes with it. If you make any changes, add a comment to that
effect in both the "Program information" box and in this file. You can
freely use bits of the code in your own applications, as long as they are
credited to me in any code that you distribute. I make no warranty for the
performance of the program, fitness for any purpose, or absence of bugs, and
I take no responsibility for files erased, computers blown up, nuclear wars
started, or any other consequence of the use of the program. Basically, I've
done the best I can to make it bug free, but beyond that (as with all PD
programs) you should use it with care.

  If you find the program useful you might like to make a donation to Oxfam
- say 5 (less than half the price of a serial lead!)

  I can be contacted by e-mail on Janet (the UK academic network) as
SB2 @ UK.AC.RL.IB, or by snail mail:

       Stephen Burke,
   c/o 7, Egdon Drive,
       Luton,
       Beds
       LU2 7AZ
