3: CONTROLLING BBC KERMIT

In this section we shall look at how you start and stop BBC KERMIT, and
also how its command language operates.

3.1 ENTERING BBC KERMIT

BBC KERMIT exists in two versions: one that runs as an ordinary program in
the BBC Computer's main memory, and one that is programmed into an EPROM
and runs as a sideways ROM. The versions have the same file transfer
facilities, but the version that runs in memory provides only a
40-character terminal emulation on the model B as opposed to an
80-character VT52 emulation.  On models B+ and B+128, and the Master 128,
both versions give identical terminal emulation facilities.

BBC KERMIT is not compatible with the 6502 second processor, so if you 
have been using one you will need to power it off and press CONTROL-BREAK
to reset the system. Similarly it will not run on the Master Turbo-Card:
you will need to use the control panel or *CONFIGURE command to disable
the card before using BBC KERMIT.

3.1.1 The RAM version

The RAM version of BBC KERMIT will be kept on a disc, and it is up to you
what you call the file. Assuming it is called KERMIT, you could enter it
with the command

  *RUN KERMIT

If the file is in the default or library directory, you could run it by
simply typing

  *KERMIT

The BBC Computer User Guide and the guide for the Disc Filing System you
are using will explain this in more detail if you wish to consult them.

3.1.2 The sideways ROM version

The EPROM containing the sideways ROM version of BBC KERMIT should be
fitted into one of the sideways ROM sockets on your machine in the same
way as other sideways ROMs such as Wordwise. If you are using a model B or
B+ with a sideways RAM board, or have a B+128 or Master 128, you will be
able to load the BBC KERMIT sideways ROM version to sideways RAM and run
it there, as the program is completely unprotected.

If you fit the BBC KERMIT ROM as the highest priority language ROM in the
machine, you will find that the KERMIT command mode screen will appear
when you power the machine on. Otherwise, you will need to give an
operating system command to enter KERMIT: simply type

  *KERMIT

and the KERMIT command mode screen will appear.

The command you give can be abbreviated if you wish, but you must follow
the abbreviation with a ".". The minimum abbreviation possible is "*KER.",
so you could type any one of

  *KER.
  *KERM.
  *KERMI.
  or *KERMIT if you wished.

3.2 LEAVING BBC KERMIT

To leave either the RAM or sideways ROM versions of BBC KERMIT you would
normally use the EXIT command. This will reset the parts of the system
that KERMIT has been using, and will enter BASIC.

Alternatively, you can issue an operating system command such as *WORDWISE
if you wish to enter another language ROM. Here, though, you may need to
press the BREAK key to reset the screen if the new language ROM does not
do this itself.

Note that the RAM version of BBC KERMIT adjusts OSHWM so that commands
such as *COMPACT will not corrupt the KERMIT program. OSHWM is reset when
you use the EXIT command or press CONTROL-BREAK; however, if you leave
KERMIT with, for example, *BASIC, OSHWM is not reset, so you will find
that you have very little memory left for programs. Pressing CONTROL-BREAK
will correct this.

3.3 BBC KERMIT COMMAND LANGUAGE

You control what you want BBC KERMIT to do, and how it should do it, by
giving it commands in its "command language". The format of the command
language closely follows that used on most other KERMIT implementations on
other machines.

There are some differences in what commands are available between the
sideways ROM version and the RAM version of BBC KERMIT. These differences
will be noted in the following sections of this guide, and are marked
clearly in Appendix 1.

3.3.1. Command format

When you start BBC KERMIT, you will see a MODE 7 screen known as the
"command screen" appear. This will be showing a prompt line saying

  BBC>

in yellow, indicating that BBC KERMIT is expecting you to type a command.
You can type either a KERMIT command, or an operating system command
preceded as usual by a "*". This allows you, for instance, to look at a
disc catalogue, or to delete files from within KERMIT. Like operating
system commands, KERMIT commands can be typed in upper case, lower case,
or any mixture of the two as you please.

KERMIT's own commands are not preceded by an asterisk. They all take the
form of a command name, such as "SET", sometimes followed by one or more
further pieces of information or "parameters", which must be separated
from each other by spaces. For example, one command you might use is

  SET PARITY EVEN

to set one of the values used for communicating with the other system.
Here the command is "SET", and "PARITY" and "EVEN" are parameters to the
command. Since there are a large number of variations to the SET command,
these are often referred to in this guide as separate commands. Thus you
will see references  to the "SET FILE TYPE" command, for instance. You can
regard this as either a command whose name has spaces in it, or as a form
of the SET command with its first parameters "FILE" and "TYPE". In either
case, the effect will be the same.

At the end of each command you should press the RETURN key to send the
line to KERMIT for action. If you have made a typing mistake you can use
the cursor keys and the DELETE key exactly as for other BBC micro
languages. Pressing CONTROL and U together will cancel the entire input
line.

Appendix 1 gives the complete specification of all the BBC KERMIT
commands. The commands are grouped according to their function (such as
"file transfer control"), rather than in one alphabetical list. Thus you
will find variations of the SET command appearing in many places, grouped
with other commands that function in the same area.

Sometimes, not all the parameters of some commands need be typed. In these
cases, BBC KERMIT will take a "default" value for the parameter you did
not supply. The reference section will tell you which parameters can be
omitted, and what values BBC KERMIT will assume if they are omitted.

3.3.2. Abbreviating commands and parameters

To reduce the amount of typing that you need to do, BBC KERMIT allows you
to abbreviate all commands and most parameters. You may abbreviate to as
few characters as you wish, provided that what you type is unique. Thus

  TAKE
  TAK
  TA

are legal, but

  S

is not, since it could stand for either SET, SAVE or SHOW. To take a full
example, you could type either

  SET FILE TYPE BINARY

or abbreviate it as far as

  SE FI T B

3.3.3. Numeric parameters

Except where explicitely stated, numeric parameters to commands can be
typed in either decimal or hexadecimal. By default, BBC KERMIT expects the
value to be decimal, but you can indicate a hexadecimal number by
preceding the parameter with either "X", "$" or "&". Thus

  123

is a decimal value, and

  &123

is a hexadecimal value.


As an example: the number 28 (decimal) is expressed in hexadecimal as 1C,
so the two commands

  SET SEND PADDING 28

and

  SET SEND PADDING &1C

will have the same effect.

3.3.4. Obtaining help

Quite often, you may wish a reminder as to what parameters or commands you
can give. BBC KERMIT has an "auto-help" facility that will act as an
"aide-memoire" for you.

To use auto-help, simply type a "?" at any place in an input line while
typing a command. BBC KERMIT will immediately give you a list of the
commands or parameters that you can use at that place in the line, or will
output a short message explaining the use of that parameter. It then
retypes the command line up to the place where you typed the question
mark, so that you can type in one of the options. You can, of course,
change your mind and rub out all or part of the line at this point, or
press ESCAPE to cancel it altogether.

For example, if you type a question mark after the prompt thus:

  BBC> ?

BBC KERMIT will output a list of the commands you can use. If you choose
the LOGGING command, you might then type

  BBC> LOGGING ?

BBC KERMIT will now tell you that you can type either ON or OFF at this
point, and will retype your line, so you will now see

  BBC> LOGGING

with the cursor positioned after "LOGGING", ready for more input. If you
type a question mark at a place where there are no more possible
parameters, BBC KERMIT will output

  No more parameters for this command

to indicate that here you can only either type RETURN to obey the command,
or change the line to something else.

The examples above have shown the "?" character as the "help-trigger" that
invokes auto-help. There may, though, be times when you require to type a
"?" without it causing this action - for example, as part of a remote
filename. BBC KERMIT lets you redefine the character that will trigger
auto-help with the SET HELP-TRIGGER command: you can set it to any of the
characters "?", "&", "/", "#", or "@".

Automatic line retyping will also occur if you make a mistake in a
command. BBC KERMIT will retype the line up to the point where it found
the error, so you will not need to type the entire line again.

3.4 READING COMMANDS FROM A FILE

As an alternative to typing commands in on the keyboard, you can place
them in a file (for example using *BUILD or a word processor) known as a
"TAKE file", and tell BBC KERMIT to read the commands from there instead
of from the keyboard. This is done with the TAKE command.

BBC KERMIT will read the file in as though the characters were coming from
the keyboard, and will obey its contents as commands. You can include
either KERMIT commands or operating system commands in the file, the only
exception being another TAKE command, which is not allowed. Additionally,
you can place comment lines in the file to describe what it does: any line
that starts with a colon (":") will be ignored by KERMIT. Blank lines are
also ignored.

The SET TAKE-ECHO command allows to you specify whether you wish KERMIT to
display the lines it reads from the file as it goes. By default you will
see the commands on the screen before they are obeyed.

If an error occurs in a TAKE file, KERMIT will close it and revert to
reading input from the keyboard. You can yourself stop the execution of a
TAKE file at any time by pressing the ESCAPE key.

The most common use of a TAKE file is to save you typing a number of SET
commands to configure BBC KERMIT every time you start it: the job of
configuration can then be done with one TAKE command. (Note, though, that
the LOAD and SAVE commands provide an even better way of doing this).

3.5 STORING PARAMETER SETTINGS

Once you have changed a number of parameters with the SET command, it is
useful to be able to store them to avoid repitition of the commands at a
later time. The SAVE command lets you record the values of all the BBC
KERMIT parameters in a disc file: subsequently the LOAD command will read
these values back and make them operative. You could, for example, keep a
number of sets of parameters in various files to suit varying needs.

If you are running the sideways ROM version BBC KERMIT in sideways RAM on
an expansion board instead of in EPROM, you have the further option of
permanently changing the default settings. The FIX command will replace
the default values stored within BBC KERMIT with the values currently in
use. This command is not available in the RAM version.

3.6 SETTING THE COMMAND SCREEN WIDTH

The normal command screen used by BBC KERMIT uses the BBC Computer's MODE
7, giving you a 40 character wide screen in colour. This is quite adequate
for operating BBC KERMIT normally, but there are occasions, such as when
you are using *TYPE to examine a file, or when you are displaying output
from a remote KERMIT server program (described in section 5.4.3), when it
is convenient to have a line of 80 characters.

If you have the sideways ROM version of BBC KERMIT on a model B, or are
using a B+, B+128 or Master 128 with either version, you may change the
width of the command screen to suit your needs with the WIDTH command.
Typing

  WIDTH 80

will change the command screen into an 80 character screen, and

  WIDTH 40

will return to a 40 character screen.


The characteristics of the 80 byte command screen are controlled by the
same commands as for the 80 byte terminal emulation screen: thus the
commands

  SET VDU-COLOUR

and

  SET TV

control the text colour and whether a *TV command is automatically issued.

Remember, though, that the 80 character command screen will use the BBC
Computer's main memory down to address &4000 on all models, so you should
not use it if you have prepared data for transfer from memory above that
address. The status screen used to display the progress of file transfers
will always be in MODE 7, regardless of the use of the WIDTH command.

3.7 FUNCTION AND CURSOR KEYS

In command mode, the 10 red function keys on the BBC Computer keyboard
behave as they do in BASIC. You can program strings onto the keys using
the *KEY command as described in the BBC Computer User Guide, and pressing
the keys will produce the strings. The four cursor keys also  have their
normal function, and you can use them, the COPY key and the DELETE key to
edit your command lines as you would lines of BASIC.

3.8 USING AN AUTOBOOT FILE

One way of starting BBC KERMIT up and automatically setting the parameters
to suitable values is to create a !BOOT file (using *BUILD or a word
processor, for example) on a disc containing the appropriate commands. You
should consult your Disc Filing System user guide for details of how to
set up the system so you can use autoboot.

For example, you might create the file to hold

  *KERMIT
  SET BAUD 1200 RECEIVE
  SET BAUD 75 TRANSMIT

Then, when you press SHIFT-BREAK, the commands in the file will enter BBC
KERMIT, then set the baud rates up before returning control to you.

