A1.2 COMMANDS FOR TRANSFERRING DATA

In this section we shall look at the detailed format of the commands that
you use to transfer files using BBC KERMIT, and to control how BBC KERMIT
will perform the transfers.

GET
~~~
This command should only be used if the remote KERMIT is running in server
mode. BBC KERMIT will send the server a command, requesting it to transfer
a file: the effect is to "pull" a file from the remote server to BBC
KERMIT.

The format of the command is this:

  GET <remote-file> <local-file>

The parameters are as follows:

  <remote-file>
This parameter is mandatory, and specifies the name of the file on the
remote machine. The format of the name will, of course, be that required
by the remote machine.

  <local-file>
This parameter is optional, and specifies the name of the file on the BBC
system into which you wish data to be transferred. This name may include
drive and directory specifications if you wish the file to be on a drive
and directory other than the current default.

When this command is issued, BBC KERMIT will send a command to the remote
server to pull the file from it. The transfer will take place
automatically, and you need do nothing further.

There are several points to be considered about the format and use of the
filename parameters.

1. If you have used the SET DESTINATION MEMORY or SET DESTINATION PRINTER
commands to transfer data into the BBC's RAM or to a printer instead of
into a file, you must omit the <local-file> parameter.

2. If the destination of the data is a file, and you omit the <local-file>
parameter, BBC KERMIT will try to generate a legal BBC filename from the
<remote-file> you supplied. If this name is the same as a file that
already exists, then by default BBC KERMIT will try to alter it until
there is no clash. The display will tell you what is happening, and give
you the name of the file that is actually going to be written. You may
prevent this renaming operation with the SET FILE WARNING command: if you
turn the facility off, any existing file will be overwritten.

3. If you do specify a <local-file> parameter, then BBC KERMIT will use
this file for the received data whether or not it exists already. It will
not attempt to rename the file to miss an existing one.

4. You may GET a group of files from the remote server by putting that
system's wildcard characters into the <remote-file>. The remote server
will send each file in turn automatically, and you need take no action
until the group transfer is complete. Note that, if you do include
wildcards in the <remote-file> parameter, you must omit the <local-file>
parameter or all the files from the remote server will be placed in the
same BBC file.

RECEIVE
~~~~~~~
This command should be used only if the remote KERMIT is not running in
server mode, and causes BBC KERMIT to wait for a file transfer to be
started by the remote system. You will thus need to issue a SEND command
to the other KERMIT in order to make something happen.

The command format is this:

  RECEIVE <local-file>

The parameters are:

  <local-file>
This parameter is optional, and specifies the name of a file on the BBC
system into which you wish data to be transferred. It must be a legal BBC
filename, and can include drive and directory specifications.

When the command is issued, BBC KERMIT will wait passively for a signal
from the remote KERMIT that a file transfer is beginning. This signal will
include the name of the file that is being sent: if you have included the
<local-file> parameter, this name is for information only, and the data
will be written to the file you have identified.

If you do omit the <local-file> parameter, BBC KERMIT will attempt to
generate a suitable BBC filename from the name supplied by the remote
system. The actions taken are the same as those described above in the GET
command.

Some points that must be considered when using the RECEIVE command are:

1. If you have used the SET DESTINATION MEMORY or SET DESTINATION PRINTER
commands to transfer data into the BBC's RAM or to a printer instead of
into a file, youmust  omit the <local-file> parameter.

2. If you have directed the remote system to send a group of files by
including a wildcard in the filename, you should omit the <local-file>
parameter, or all the data will end up in the one BBC file, each file
overwriting the previous ones.

SEND
~~~~
This command is used whether or not the remote KERMIT is a server, and
sends a file or group of files to it.

The command has two possible formats:

  SEND <local-file> <remote-file>

used if you are transferring data from a BBC file, and

  SEND <remote-file>

  if you are sending data from the BBC's memory.

The parameters are as follows:

  <local-file>
This parameter specifies the name of the file on the BBC that you wish to
send, and can be any legal BBC filename.

  <remote-file>
This parameter is optional if you are sending data from a file, and
mandatory if you are sending data from the BBC's memory. It specifies the
filename that BBC KERMIT will send to the remote system to identify the
file: this may be used by the remote system as the name of the file that
it puts the data into, but this is entirely up to the remote system. If
the filename is legal for the remote system, the file would normally be
called by this name.

If the remote KERMIT is not running in server mode, you must issue a
RECEIVE command to the remote system to prepare it for this SEND. You can
either do this before you issue the SEND command, or you can issue the
SEND first and then issue the RECEIVE to the other system. To allow you to
do this latter option, BBC KERMIT will pause after you issue the SEND
command (by default for 30 seconds) before it actually starts sending. You
can change this pause interval with the SET DELAY command; alternatively,
pressing any key while BBC KERMIT is waiting will make it start the
transfer immediately.

Some points to note about the SEND command are:

1. If you omit the <remote-file> parameter, BBC KERMIT will generate a
"generally acceptable" name from the <local-file> parameter and pass this
to the remote system. It forms this name by stripping off any drive and
directory specifications, then adding a filename suffix in the form ".XXX"
to what remains. By default, the suffix added is ".BBC", but the SET FILE
SUFFIX command allows you to change this, or suppress it altogether.

2. You may send a group of files in one operation by including the "*" or
"#" wildcard characters in <local-file>. BBC KERMIT will then send all
files in the current directory whose names match. You should not specify
drive or directory details in the name if you include wildcards: you may
select different drives or directories with the *DIR command before you
issue the SEND if you need to. You must omit the <remote-file> name if you
include wildcards in <local-file>.

SET DELAY
~~~~~~~~~
This command sets the period for which BBC KERMIT will wait after you
issue a SEND command.

The command format is

  SET DELAY <number>

The parameters are

  <number>
The delay in seconds, in the range 0 to 255.

When you issue a SEND command, BBC KERMIT will do nothing for the
specified period to enable you to issue commands to a remote system. You
can interrupt the delay and make BBC KERMIT proceed by pressing any key.

By default, BBC KERMIT will delay for 30 seconds after you issue a SEND
command.

Example:

  SET DELAY 5

will cause BBC KERMIT to wait after a SEND command for 5 seconds, or until
a key is pressed.

SET DESTINATION FILE
~~~~~~~~~~~~~~~~~~~~
This command specifies that any data received by BBC KERMIT is to be
stored in a file, rather than placed into the BBC's memory or sent
directly to the parallel printer.

The command format is

  SET DESTINATION FILE

This is the default condition when BBC KERMIT is entered.

SET DESTINATION MEMORY
~~~~~~~~~~~~~~~~~~~~~~
This command, available in the sideways ROM version only, specifies that
data received by BBC KERMIT is to be placed into the BBC's memory rather
than being stored in a file.

The command format is

  SET DESTINATION MEMORY <address>

The parameters are:

  <address>
This specifies the address where you want the first byte received to be
placed. The value must be from 1 to 4 hexadecimal digits, optionally
preceded by "X", "$" or "&".

After issuing this command, any data that you receive is placed in memory
instead of a file. The first byte is placed at the specified address, and
subsequent bytes are placed at higher addresses. BBC KERMIT will not allow
the received data to overflow into the mode 7 file transfer status display
screen, so that the highest address available is &7BFF.

BBC KERMIT makes no checks on the address supplied: it is up to you to
ensure that you direct data to a sensible place. The destination for
incoming data will remain the BBC's memory until you specify otherwise.

Note that BBC KERMIT will process the data received according to the
currently defined file type, even though the destination is not a file.

The default condition for BBC KERMIT is to place data in files.

The RAM version of BBC KERMIT always uses destination FILE.

Example:

  SET DESTINATION MEMORY 1900

will cause incoming data to go to memory, starting at address &1900 (the
default value of PAGE for Acorn DFS systems).

SET DESTINATION PRINTER
~~~~~~~~~~~~~~~~~~~~~~~
This command specifies that data received by BBC KERMIT is to be
transferred directly to a printer rather that stored in a file or in
memory.

The command format is

  SET DESTINATION PRINTER

The default condition is for BBC KERMIT to transfer data into files.

Note that BBC KERMIT will process the data received according to the
currently defined file type, even though no file is involved.

SET INCOMPLETE
~~~~~~~~~~~~~~
This command defines what BBC KERMIT will do if either you interrupt the
reception of a file, or if an error occurs while a file is being received.

The command format is

  SET INCOMPLETE <action>

The parameters are

  <action>
This must be either KEEP or DELETE.

If the action is set to DELETE, BBC KERMIT will delete any file whose
reception is interrupted and is thus incomplete. If the action is set to
KEEP, BBC KERMIT will close the file normally, and you will be able to use
whatever data was received before the interruption or error.

By default, BBC KERMIT will DELETE an incomplete file.

Example:

  SET INCOMPLETE KEEP

causes BBC KERMIT to leave an incomplete file on the disc after the
transfer.

SET FILE BUFFER-SIZE
~~~~~~~~~~~~~~~~~~~~
This command, available in the sideways ROM version only, defines the size
of buffer BBC KERMIT uses when reading or writing files.

The command format is

  SET FILE BUFFER-SIZE <number>

The parameters are:

  <number>
This specifies the size of the buffer, in 256 byte pages. It must be a
value from 1 to 64.

BBC KERMIT uses the file buffer to read and write files in large chunks,
which can improve performance in some cases. However, with large buffers,
although BBC KERMIT will access the discs less frequently, it will take
longer when it does, so the remote KERMIT may mistakenly think that
contact has been lost. If this occurs, the buffer size can be reduced.

By default, BBC KERMIT uses a buffer of 16 pages (4K bytes).

The RAM version of BBC KERMIT uses a file buffer of 8 pages (2K bytes).

Example:

  SET FILE BUFFER-SIZE 1

changes the file buffer to be 1 256 byte page long.

SET FILE SUFFIX
~~~~~~~~~~~~~~~
This command defines the characters that BBC KERMIT will add to a BBC
filename when generating a "generally acceptable" filename to send to the
remote system.

The command format is

  SET FILE SUFFIX <string>

The parameters are

  <string>
This is the suffix you wish added, consisting of up to 8 characters. The
"." is not part of the suffix and should not be included.

BBC KERMIT will, when generating a "generally acceptable" filename, take
the final part of the BBC filename, add a ".", then add the suffix defined
by this command. This command lets you change the suffix to suit your
requirements. If you omit the string, BBC KERMIT will not add anything to
the BBC filename at all (not even the ".")

By default, the suffix added to the BBC filename is "BBC".

Examples:

  SET FILE SUFFIX ADE

will cause BBC KERMIT to add ".ADE" to BBC filenames for the remote name.

  SET FILE SUFFIX

will cause it not to add anything at all to the BBC filename.

SET FILE NAME
~~~~~~~~~~~~~
This command controls how BBC KERMIT handles the filename given it by a
remote system when it is receiving a file.

The command format is

  SET FILE NAME <action>

The parameters are

  <action>
This can be one of NORMAL or UNTRANSLATED.

If you set the action to NORMAL, BBC KERMIT will assume that the name
given by the remote system has the standard "name.type" form, and will
generate a BBC filename from it. If the action is UNTRANSLATED, BBC KERMIT
will use the exact name to create the file: it is up to you to ensure that
what the remote system gives it really is a valid BBC file name.

By default, BBC KERMIT will translate filenames sent by the remote system.
(action NORMAL).

Example:

  SET FILE NAME UNTRANSLATED

causes BBC KERMIT to use the name sent exactly as it is.

SET FILE TYPE ASCII
~~~~~~~~~~~~~~~~~~~
This command tells BBC KERMIT that files it transmits and receives are to
taken as containing printable ASCII text and to transform them
accordingly.

The command format is

  SET FILE TYPE ASCII <end-of-line>

The parameters are

  <end-of-line>
This optional parameter tells BBC KERMIT how a file you are sending
denotes the end of a line of text, or how you wish this to be denoted in a
file you receive. It can be one of LFCR, CRLF, CR or LF, where LF stands
for the Line Feed character, and CR for Carriage Return. If you omit the
parameter, BBC KERMIT assumes LFCR.

After using this command, BBC KERMIT treats all files as containing
printable ASCII text, with the end of each line indicated by the specified
sequence of control characters. When sending a file, it will transform
every occurrence of the specified sequence into KERMIT's standard
"endofline" indicator, and the remote KERMIT should then change this into
whatever the standard representation of end-of-line is on its own system.
When receiving files, BBC KERMIT will change every occurrence of the
standard KERMIT indicator into the specified sequence of bytes.

Note that this command has effect even if the source or destination of
data is memory rather than files. Also, you may need to give an equivalent
command to the remote KERMIT system to make it treat the data correctly.

By default, BBC KERMIT treats files as ASCII, with end of line indicated
by LFCR bytes.

Example:

  SET FILE TYPE ASCII CR

specifies a file type of ASCII, with lines being terminated with a CR
(&0D) byte.

SET FILE TYPE BINARY
~~~~~~~~~~~~~~~~~~~~
This command tells BBC KERMIT that all files it receives or sends should
be treated as containing binary data.

The command format is

  SET FILE TYPE BINARY

After using this command, BBC KERMIT will transmit the bytes from a file
exactly as they are, and will not change any of them. Similarly, the data
it receives will be written to file with no alteration.

Note that this command has effect even if the source or destination of
data is the BBC's memory or the parallel printer rather than a file. Also,
you may need to give an equivalent command to the remote KERMIT system to
make it treat the data correctly.

By default, BBC KERMITs treats files as ASCII text.

Example:

  SET FILE TYPE BINARY

makes BBC KERMIT treat files as containing binary data.

SET FILE WARNING
~~~~~~~~~~~~~~~~
This command specifies the action that BBC KERMIT must take on receiving a
file if the name it tries to store the data under clashes with that of an
existing file.

The command format is

  SET FILE WARNING <action>

The parameters are

  <action>
This must be either ON or OFF.

If the file warning facility is ON, BBC KERMIT will check whether the name
it wishes to use to store incoming data clashes with an existing file
name. If it does, a warning is displayed on the screen, and BBC KERMIT
will change the right-most character of the name to a "+" and check again.
If this still clashes, the next right-most characer is changed, and so on.
An error will occur if no unique name is found by the time the name has
been changed to be entirely "+" characters.

If file warning is OFF, BBC KERMIT will make no checks. Any existing file
will be overwritten with the new data.

By default, file warning is ON.

Example:

  SET FILE WARNING OFF

turns off the file warning facility.

SET RECEIVE TIMEOUT
~~~~~~~~~~~~~~~~~~~
This command defines the interval after which BBC KERMIT will take action
if it has received no data from the remote system.

The command format is

  SET RECEIVE TIMEOUT <interval>

The parameters are

  <interval>
Specifies the timeout period in seconds, in the range 0 to 255.

The command defines the timeout that BBC KERMIT is to use. Note, though,
that BBC KERMIT will not perform any timeout at all unless you have used
the SET TIMER command to turn the facility on - by default it is OFF.

The choice of the timeout period will depend on many factors. Regard
should be paid to how fast the remote system is running - if it is
mainframe, it could be running slowly due to heavy use - and also to the
delays that operating over a network may impose. Care should be taken not
to set the value too low, or BBC KERMIT will repeatedly timeout
unnecessarily.

By default, a timeout interval of 15 seconds is set.

Example:

  SET RECEIVE TIMEOUT 10

causes BBC KERMIT to timeout if no data has been received after 10
seconds, providing that the timeout facility is turned on.

SET SEND TIMEOUT
~~~~~~~~~~~~~~~~
This command sets the timeout interval that BBC KERMIT asks the remote
system to use. The remote system should timeout if no data has been
received from BBC KERMIT after this interval.

The command format is

  SET SEND TIMEOUT <interval>

The parameters are

  <interval>
specifies the interval required in seconds, in the range 0 to 94.

BBC KERMIT will pass this value to the remote system at the beginning of
every file transfer. Note, though, that it is entirely up to the remote
system  whether it uses this value, ignores it, or uses a value of its
own. You may need to give the remote system commands to turn its timeout
facility on.

By default, BBC KERMIT requests the remote system to time out after 15
seconds.

Example

  SET SEND TIMEOUT 10

causes BBC KERMIT to ask the remote system to time out after 10 seconds if
no data has been received from the BBC system

SET SOURCE FILE
~~~~~~~~~~~~~~~
This command, available in the sideways ROM version only, specifies that
data transmitted to the remote system is taken from files rather than the
BBC's memory.

The command format is

  SET SOURCE FILE

This is the default condition when BBC KERMIT is entered.

The RAM version of BBC KERMIT always uses source FILE.

SET SOURCE MEMORY
~~~~~~~~~~~~~~~~~
This command, available in the sideways ROM version only, causes data
transmitted to the remote system to be taken from the BBC's memory rather
than from files.

The command format is

  SET SOURCE MEMORY <start-address> <end-address>

The parameters are

  <start-address>
Specifies the address of the first byte to be transferred. The value must
be from 1 to 4 hexadecimal digits, optionally preceded by "X", "$" or "&".

  <end-address>
Specifies the address of the last byte to be transferred plus one. The
value must be from 1 to 4 hexadecimal digits, optionally preceded by "X",
"$" or "&".

After issuing this command, BBC KERMIT will send data from the BBC's
memory instead of from a file. The area of memory to be transmitted is
defined by the two command parameters: it is up to you to ensure that the
addresses are sensible.

Note that BBC KERMIT will still process the data transmitted according to
the defined file type, even though the source of data is not a file.

By default, BBC KERMIT will use source FILE.

The RAM version of BBC KERMIT always uses source FILE.

Example

  SET SOURCE MEMORY 1B00 3200

will cause BBC KERMIT to send the data between memory addresses &1B00 and
&31FF inclusive in a SEND command.

SET TIMER
~~~~~~~~~
This command controls whether BBC KERMIT will timeout if no data is
received from the remote system after the timeout period has expired.

The command format is

  SET TIMER <action>

The parameters are

  <action>
This must be either ON or OFF.

If the timer facility is turned ON, BBC KERMIT will use the value defined
by SET RECEIVE TIMEOUT to time the remote system out. If it is OFF, the
value is ignored, and BBC KERMIT will wait for ever for data.

By default, the timer is OFF.

Example

  SET TIMER ON

turns the timeout facility on.
