APPENDIX 1 : BBC KERMIT COMMANDS

This appendix lists in full detail all the commands available in BBC
KERMIT. The commands are grouped in sections appropriate to their usage.

Throughout the appendix, commands are presented in a formal way that shows
you exactly what you may or must type at each point. For example, you
might see a command described as having a format

  SET PAUSE <number>

Here the fixed parts, that you must type, are shown in capitals (although,
of course, you can type the command in either upper or lower case if you
wish). The third part of this particular command, "<number>" is shown
enclosed in "<>" brackets: this indicates that you must provide some sort
of value yourself, rather than type the actual word shown. The fact that
the parameter is described as "number" tells you that a number of some
sort is needed: the description of the command will tell you what sort of
number, why you should supply it, and whether you could leave it out and
let BBC KERMIT itself provide a suitable value. You shouldn't include the
"<>" brackets in the command that you type.

Thus, a valid way of typing the command in this example would be

  SET PAUSE 10

where you have supplied the numeric value "10" in the expected place. BBC
KERMIT will always tell you if you either omit a necessary parameter or
supply too many parameters.

All commands, and most parameters, can be abbreviated to their first few
characters, provided that what you type uniquely identifies the command or
parameter you mean. The command specification will tell you about the few
cases where parameters must always be typed in full.

A1.1 COMMANDS FOR GENERAL CONTROL OF BBC KERMIT

The commands listed in this section are used to control the general
operation of BBC KERMIT.

CLOSE
~~~~~
This command closes any files that may be open. The only circumstance in
which this command is needed is if you have entered BBC KERMIT when the
maximum number of permitted files is already open: in such a case you
would not be able to transfer any data until the files were closed.

The command has no parameters.

Example:

  CLOSE

DISPLAY
~~~~~~~
This command displays whatever follows it on the command line to the
screen. It is mostly for use within TAKE files, where it can be used to
indicate progress, etc.

The command format is:

  DISPLAY <message>

The parameters are:

  <message>
The text to be displayed. Unlike other command parameters, spaces are not
taken as delimiters here: everything from the first non-space after the
command to the end of the line is output.

Example:

  DISPLAY About to start

will output "About to start" on the screen.

EXIT
~~~~
This command causes BBC KERMIT to return to BASIC at the end of a session.

The command has no parameters.

Example:

  EXIT

FIX
~~~
This command, available in the sideways ROM version only, updates the
default parameter table within BBC KERMIT with the values currently
established with the SET command. Since the command needs write access to
the address area &8000 to &BFFF where the BBC KERMIT code is held, it can
be used only if you have BBC KERMIT in sideways RAM.

The command will ask if you are sure that you wish to do this: if you
reply "Y" the default table will be changed. The new values will then be
the defaults used when you enter BBC KERMIT again.

The command has no parameters.

Example:

  FIX

JSR
~~~
This command, available in the sideway ROM version only, allows you to
call some machine code routines you may have written yourself and loaded
into memory. The code is entered with a JSR instruction and should exit
with an RTS.

The command format is:

  JSR <address>

The parameters are as follows:

  <address>
Specifies the address of the code to be entered.

Example:

  JSR &2000

enters some of your code at address &2000.

LOAD
~~~~
This command loads a complete set of BBC KERMIT parameters (i.e. the
values established by the SET command) from a file on disc produced by the
SAVE command. You could use this command to avoid having to type a large
number of SET commands every time you start BBC KERMIT up.

The command format is:

  LOAD <filename>

The parameters are as follows:

  <filename>
Specifies the name of a file produced by the SAVE command.

If the file is in the correct format, BBC KERMIT will load its contents
into memory, overwriting all the previous control values established by
the SET command.

Example:

  LOAD :1.K.PARAMS

would set all the KERMIT control values from the data held in file
:1.K.PARAMS.

RESET
~~~~~
This command restores all the KERMIT control values (i.e. the values
controlled by the SET command) to the values they had when BBC KERMIT was
started.

Using this command enables you to instantly restore the control values to
their initial state after changes without needing to use the SET command.

The command has no parameters.

Example:

  RESET

SAVE
~~~~
This command records all the current KERMIT control values (i.e. the
values established by the SET command) in a file on disc. You may
subsequently use the LOAD command to re-establish the saved values.

This command enables you to configure BBC KERMIT to your exact
requirements once only, record the new settings, then, whenever you start
BBC KERMIT again, you can reset these values in one operation.

The command format is:

  SAVE <filename>

The parameters are :

  <filename>
This is the name of a file on disc into which the control values will be
written.

Example:

  SAVE :1.K.PARAMS

will write the current control values to the file :1.K.PARAMS.

SET BAUD
~~~~~~~~
This command allows you to define the line speed ("baud rate") that BBC
KERMIT will use on the RS423 port. BBC KERMIT allows you to set the
receive and transmit rates to the same, or different, values as you wish.
The command format is:

  SET BAUD <number> <direction>

The parameters are:

  <number>
This  specifies the baud rate to be used. It can be any of the baud rates
supported by the BBC micro, that is, any of the values 75, 110, 300, 1200,
2400, 4800, 9600 or 19200.

  <direction>
This specifies whether you wish to set the receive rate, the  transmit
rate, or both and can be one of RECEIVE, TRANSMIT or BOTH. If you omit the
parameter, BBC KERMIT assumes you mean BOTH.

The command takes immediate effect. By default, BBC KERMIT uses a baud
rate of 9600 baud for transmit and receive.

Examples:

  SET BAUD 1200

will set the baud rate to 1200 baud for transmit and receive.

  SET BAUD 75 TRANSMIT

will set the baud rate to 75 baud for transmitting data, but leaves the
receive baud rate unchanged.

SET DEBUGGING
~~~~~~~~~~~~~
This command allows you turn the BBC KERMIT debugging facility on or off.
The command format is:

  SET DEBUGGING <action>

The parameters are:

  <action>
This must be either ON or OFF.

If debugging is on, BBC KERMIT will output information during all file
transfers to enable you to trace errors. It will record the protocol
state, the contents of all packets received and transmitted, plus
indications of its internal operations. This information is output to the
printer.

When debugging is on it can be suspended or activated during a file
transfer at will. Pressing CONTROL and D when the file transfer status
display is showing will suspend debugging; pressing it again will restart
it.

By default, debugging is OFF.

Example:

  SET DEBUGGING ON

will turn the debugging facility ON.

SET FLOW-CONTROL
~~~~~~~~~~~~~~~~
This command defines how BBC KERMIT controls the flow of data in and out
of the RS423 port, in order to stop either it or the remote system
becoming overloaded.

The command format is

  SET FLOW-CONTROL <type>

The parameters are:

  <type>
This defines the type of flow control you wish. It can be either XON/XOFF
if you wish flow control to be by the method of sending XON and XOFF
control characters, or CTS/RTS if you wish flow control to be done by
hardware signals.

The type of flow control you should select will depend on the system you
are connected to: consult your systems support personnel if you are unsure
what to use.

By default, BBC KERMIT uses XON/XOFF flow control.

Example:

  SET FLOW-CONTROL CTS/RTS

will select hardware flow control.

SET HANDSHAKE
~~~~~~~~~~~~~
This command specifies whether "handshaking" is to be done in file
transfer mode. This operation is needed if BBC KERMIT is linked to some
IBM mainframes, and causes it to wait for a "handshake" character to be
sent from the mainframe before it attempts to send a data packet.

The command format is

  SET HANDSHAKE <type>

The parameters are:

  <type>
The type of handshake byte the mainframe is using. The value should be one
of NONE, BELL, CR, LF, XON or XOFF. The first value specifies that no
handshaking is to be done: the others specify that it is to be done with
handshake bytes of &07, &0D, &0A, &11 or &13 respectively.

By default, BBC KERMIT uses a value of NONE and handshaking is not
performed.

Example:

  SET HANDSHAKE XON

will turn handshaking on, and specify that an XON byte (code &13) is to be
used.

SET MUX-WAIT
~~~~~~~~~~~~
This command is used in cases where the communications system that BBC
KERMIT is connected to is slow to respond to characters. It causes BBC
KERMIT to wait for a specified number of byte periods before checking that
it is clear to transmit each byte. This delay is independent of the type
of flow-control selected.

The command format is:

  SET MUX-WAIT <number>

The parameters are:

  <number>
The number of byte periods for which BBC KERMIT will wait, in the range 0
to 255.

By default, a value of 0 is used, so BBC KERMIT imposes no delay before
transmitting each byte.

Example:

  SET MUX-WAIT 1

causes BBC KERMIT to delay for one byte period before testing that it is
clear to send a character.

SET PARITY
~~~~~~~~~~
This command lets you define how characters are sent and received on the
RS423 port in terms of what happens to the eighth or "parity" bit of each
byte.

The command format is

  SET PARITY <type>

The parameters are:

  <type>
This selects the type of parity you wish to be applied. It can be one of
MARK, SPACE, ODD, EVEN or NONE.

The setting of parity you select is dependent on the system you are
connected to: you should consult your systems support personnel for advice
if you are unsure of what to use.

The setting of parity also affects how the file transfer mechanism copes
with data whose ASCII codes are in the range 128..255. If parity is
anything other than NONE, BBC KERMIT will assume that it cannot send such
data directly, and will try to arrange with the remote system to encode it
in a way that can be transmitted correctly. If parity is NONE, however,
BBC KERMIT will assume that all data can be transmitted, and will only use
the encoding technique if the remote system explicitely asks for it. In
the case of some networks this may cause confusion, since the network may
not use parity, and the recommended way of using terminals might then be
with parity NONE. However, the mainframe system itself may operate with,
say, SPACE parity, and may discard the parity bit from every byte it sends
or receives. This requires BBC KERMIT to encode bytes in the range
128..255, but if parity is NONE it will do this only if the other system
asks for it. To be safe, you would normally set parity to SPACE in such
cases.

By default, BBC KERMIT sets parity to SPACE.

Example:

  SET PARITY EVEN

selects EVEN parity.

SET TAKE-ECHO
~~~~~~~~~~~~~
This command defines whether the commands that BBC KERMIT obeys from a
TAKE file instead of the keyboard are displayed on the screen as they are
executed.

The command format is

  SET TAKE-ECHO <action>

The parameters are

  <action>
This must be either ON or OFF

Setting TAKE-ECHO to ON will cause all the commands from the TAKE file to
be displayed on screen before they are obeyed. If it is set to OFF, the
commands will be obeyed, but you will not see them on the screen.

By default, TAKE-ECHO is ON.

Example:

  SET TAKE-ECHO OFF

will turn off the display of commands from TAKE files.

SHOW
~~~~
This command displays the values of all the KERMIT control values. The
display is broken up into several screens full: after each screen you are
given the option of pressing the RETURN key to see the next screen, or the
ESCAPE key to quit and input another command.

The output of the SHOW command uses a 40 byte MODE 7 screen whether or not
you have used the WIDTH command to select an 80 byte wide command screen.

The command has no parameters.

Example:

  SHOW

TAKE
~~~~
This command causes BBC KERMIT to read all further commands from a file
instead of from the keyboard. The file can be constructed with an editor,
a word-processing system, or with the *BUILD command as you prefer.

The command format is:

  TAKE <filename>

The parameters are:

  <filename>
This specifies the name of a file containing BBC KERMIT commands, in the
same format as if they were typed at the keyboard.

Once you issue the TAKE command, BBC KERMIT will read characters from the
specified file instead of the keyboard. Any KERMIT or Operating System
command can be issued from within a TAKE file, except a further TAKE
command. By default, BBC KERMIT will display each command on the screen as
it is obeyed, but you can switch this echo off with the SET TAKE-ECHO
command.

You may stop the use of the TAKE file at any point by pressing the ESCAPE
key. Execution will also stop if any command within the TAKE file causes
an error, or if you interrupt a file transfer with by pressing CONTROL and
Z (but not CONTROL and X).

Example:

  TAKE :3.THINGS

will read subsequent commands from the file :3.THINGS.

WAIT
~~~~
This command, primarily used within TAKE files, causes BBC KERMIT to wait
before proceeding with the next command. You can specify an indefinite
wait, or nominate a length of time: in either case pressing any key will
terminate the command.

The command format is:

  WAIT <time>

The parameters are:

  <time>
The interval in seconds for which BBC KERMIT will wait, in the range 0 to
255. If you omit the value, BBC KERMIT waits until a key is pressed.

Example:

  WAIT 30

causes BBC KERMIT to wait for 30 seconds, or until a key is pressed.

WIDTH
~~~~~
This command allows you to choose between a 40 character and an 80
character command screen. It may not be used in the RAM version on a model
B.

Normally, BBC KERMIT uses a MODE 7 command screen, but if you wish to
*TYPE a BBC file or are using the REMOTE command to obtain information
from a remote  server then an 80 byte wide screen can be more convenient.
The text colour used for the 80 character screen is controlled by the SET
VDU-COLOUR command, and the SET TV command determines whether a *TV
command is issued automatically on changing from 40 character to 80
character screens.

The command format is

  WIDTH <width>

The parameters are:

  <width>
Specifies the width of the command screen. The value can be either 40 or
80.

By default, BBC KERMIT uses a 40 character command screen.

Example:

  WIDTH 80

selects an 80 character command screen.
