A1.3: COMMANDS FOR TERMINAL EMULATION

In this section we shall consider the commands that you can use to control
the terminal emulation facilities of BBC KERMIT.

CONNECT
~~~~~~~
This command changes BBC KERMIT from command mode into terminal emulation
mode. Once you have issued the command the screen will clear and will
become a 40 character or 80 character wide terminal screen. From this
point, anything you type will not be examined by BBC KERMIT, but will be
sent directly to the RS423 output and the system you are linked to.

You may now operate your BBC micro as if it were an ordinary terminal.
Depending on how you have set up BBC KERMIT, this will be either an
ordinary teletype device, or one compatible with the DEC VT52 standard.

At any time you can return to KERMIT command mode by pressing the CONTROL
and F0 keys together. You will then be able to issue KERMIT commands as
before: the CONNECT command will re-instate you as a terminal at the point
where you left off.

Note that if you have selected a terminal type that is not possible (for
example, you have selected a VT52 in the RAM version on a model B), the
command will produce  an  error message "Terminal not supported"

The command has no parameters.

Example:

  CONNECT

Whenever you  enter terminal mode with the CONNECT command, printer
logging will be off, disc logging will be deactivated, and any pause you
may have placed on screen output will be lifted.

LOGGING
~~~~~~~
This command is used to initiate or terminate terminal session logging,
the facility by which all characters appearing on the screen in terminal
mode are also written to a file.

The command has two formats:

  LOGGING ON <filename>
or
  LOGGING OFF

The first format initiates terminal session logging and opens a file of
name <filename>. The second format terminates logging and closes the file.

When you use the command to initiate logging, BBC KERMIT will open a file
on disc in readiness. At this point, though, no logging will take place.
To cause characters to be written to the files, you will need to press the
CONTROL and F1 keys from terminal mode (i.e. after using the CONNECT
command). Now characters appearing on screen will be written to the
further. Pressing CONTROL and F1 again will stop logging; a further press
will restart it, and so on.

You should remember to always use the

  LOGGING OFF

command when you have finished, or you may lose some data that has not yet
been written to the disc.

Example:

  LOGGING ON LOGFILE

opens a file LOGFILE for terminal logging.

SET IGNORE
~~~~~~~~~~
This command nominates one character that will be totally ignored when it
is received from the host.

The command format is

  SET IGNORE <number>

The parameters are:

  <number>
The numeric code of the character to be ignored. If you omit the value,
any previous setting will be cancelled and all characters will be
actioned.

By default, BBC KERMIT will display all characters with ASCII codes
greater than 31, and also the CR, LF, DEL, BS and FF control codes. TAB
characters are expanded into spaces, and ESCAPE is either displayed or
taken as starting a VT52 ESCAPE sequence. All other characters are always
ignored.

Example:

  SET IGNORE &7F

causes the DEL character (code &7F) to be ignored if the host sends it.

SET KEY-CLICK
~~~~~~~~~~~~~
This command controls whether an audible click is produced whenever you
press a key in terminal emulation mode.

The command format is

  SET KEY-CLICK <action>

The parameters are:

  <action>
This must be either ON or OFF

Setting key-click to ON will cause a click to be produced whenver you
press a key.

By default, key-click is OFF.

Example

  SET KEY-CLICK ON

will turn the audible key-click ON.

SET LOCAL-ECHO
~~~~~~~~~~~~~~
This command lets you define how characters you type on the keyboard in
terminal emulation mode are to be displayed on the screen. When you press
a key, the character is sent to the remote system, which may then echo it
back to your screen. Alternatively, it may not perform this echo: in this
case BBC KERMIT must put the character on the screen itself.

The command format is

  SET LOCAL-ECHO <action>

The parameters are:

  <action>
This must be either ON or OFF

If local echo is ON, BBC KERMIT itself will display characters on the
screen. If it is OFF, the remote system is expected to echo each character
back as you type it.

By default, local echo is OFF.

Example

  SET LOCAL-ECHO ON

will turn local echo on.

SET TERMINAL
~~~~~~~~~~~~
This command allows you to select the type of terminal emulation you
require in terminal mode.

The command format is

  SET TERMINAL <type>

The parameters are:

  <type>
This can be one of TT40, TT80 or VT52. The first two provide teletype
emulations using 40 or 80 character wide screens, and the last gives VT52
emulation. Some other types may be selectable by this command, but only
the three above are used in this release of BBC KERMIT.

Note that the command will allow you to select any type of emulation,
whether or not it can actually be provided. The CONNECT command will fail,
though, if the type required is not available.

By default, the sideways ROM version of BBC KERMIT provides VT52 emulation
on all machines. The RAM version of BBC KERMIT provides VT52 emulation on
the B+, B+128 and Master 128, and TT40 on the model B.

Example

  SET TERMINAL TT80

Makes the BBC micro appear as a simple teletype device using an 80 column
screen.

SET TV
~~~~~~
This command lets you specify whether BBC KERMIT should automatically
issue a *TV command when it enters terminal emulation mode or 80 character
command screen mode.

The command format is

  SET TV <number-1> <number-2>

The parameters are:

  <number-1>
The first *TV parameter to be used.

  <number-2>
The second *TV parameter to be used.

If you omit both parameters, BBC KERMIT will no longer issue a
*TV command: however, the effect of any previously issued command will
persist. By default, BBC KERMIT issues a *TV 0 1 to turn off interlace.

Example:

  SET TV 255 1

causes BBC KERMIT to issue a *TV 255 1 command on entering terminal mode
or 80 character command screen mode.

SET VDU-COLOUR
~~~~~~~~~~~~~~
This command, available in the sideways ROM version only, lets you select
the colour used for text in 80 character terminal emulation mode or 80
character command screen mode. The command has no effect for 40 character
terminal mode. The background colour cannot be changed, and will always be
black.

The command format is

  SET VDU-COLOUR <colour>

The parameters are:

  <colour>
Specifies the colour to be used, and must be one of RED, GREEN, YELLOW,
BLUE, MAGENTA, CYAN or WHITE.

By default, the text colour used is white.

Example:

  SET VDU-COLOUR GREEN

will select green text on a black background.

TRANSMIT
~~~~~~~~
This command allows you to send a text file from the BBC to a host that
does not have KERMIT. Binary files cannot normally be sent in this way.

The command format is

  TRANSMIT <filename>

The parameters are:

  <filename>
This specifies the file you wish to send.

When you issue this command, BBC KERMIT will automatically enter terminal
mode and will send the contents of the file to the host. It will remain in
terminal mode after all the data has been sent, and you will be able to
type at the keyboard as normal. Sending the file can be interruped at any
time by pressing ESCAPE.

Example:

  TRANSMIT DELEG8

will send the text file DELEG8 to the host in terminal mode.


A1.4 COMMANDS FOR CONTROL OF REMOTE SERVERS

This section specifies the command that you can use to control the
operation of a remote server.

It is important to note that servers vary in which commands they implement
from  this section, and also on the exact way in which they action others.
All servers should implement the BYE and FINISH commands, but some may
treat them both as FINISH and leave the terminal session logged in. Some
servers implement all the facilities described under the REMOTE command
below, some implement them partially or in different ways, and some don't
implement them at all. In particular, some servers may implement commands
such as REMOTE DIRECTORY but ignore any parameters you supply. The only
way to be sure is to consult the user guide for the server concerned.

If you do attempt to use a server command that is not available, an error
message such as "Unimplemented server command" will be displayed.

In all cases, you can interrupt a REMOTE command that is producing a large
amount of output by pressing CONTROL and Z. The techniques described in
chapter 5 for handling problems are also applicable here should the
transfer of the output stop for some reason: however the REMOTE command
does not provide you with any indication of the progress or otherwise of
the transfer.

Most of the REMOTE commands produce at least one line of output from the
remote server which is displayed on BBC KERMIT's command screen. Often
this output will be formatted assuming that the screen is 80 characters
wide: if you are using the sideways ROM version of BBC KERMIT, or are
using a B+, B+128 or Master 128, you can change the command screen width
from 40 to 80 characters with the command

  WIDTH 80

so that the output layout looks correct.

BYE
~~~
This command tells the remote server to cease operation, and also to log
out the terminal job in which it is running.

The command has no parameters.

Example:

  BYE

FINISH
~~~~~~
This command tells the remote server to cease operation, but to leave the
terminal session logged in.

The command has no parameters.

Example:

  FINISH

REMOTE COPY
~~~~~~~~~~~
This command instructs the server to copy one file to another, leaving the
source file unchanged.

The command format is

  REMOTE COPY <oldfile> <newfile>

The parameters are:

  <oldfile>
Specifies the source file for the copy operation.

  <newfile>
Specifies the name of the file the data is to be copied into.

Example:

  REMOTE COPY LURGI.ILL SICKNOTE.LIS

would copy the contents of file LURGI.ILL into a new file SICKNOTE.LIS.

REMOTE CWD
~~~~~~~~~~
This command instructs the server to change its current working directory
(or wherever it looks for files unless told otherwise).

The command format is

  REMOTE CWD <directory>

The parameters are:

  <directory>
This optional parameter specifies the name of the directory to be used in
future.

If you omit the directory name, the server should reset its current
directory to that in force when you logged in. If you do specify a name,
BBC KERMIT will prompt you for a password, in case the server system
requires one. You can either type the password, which will not be echoed
to the screen, then press RETURN; or, if no password is needed, simply
press RETURN.

Example:

  REMOTE CWD [.SUBDIR]

would tell a server running under VAX/VMS to set the current directory to
be [.SUBDIR]

REMOTE DELETE
~~~~~~~~~~~~~
This command instructs the server to delete the specified file.

The command format is

  REMOTE DELETE <filename>

The parameters are:

  <filename>
Specifies the file you wish deleted. The server may permit you to specify
a wildcarded name, or it may not.

Example:

  REMOTE DELETE /temp/notalotofgood

would ask the server to delete the file /temp/notalotofgood.

REMOTE DIRECTORY
~~~~~~~~~~~~~~~~
This command instructs the server to produce a directory listing, which is
displayed on BBC KERMIT's command screen.

The command format is

  REMOTE DIRECTORY <filespec>

The parameters are:

  <filespec>
This optional parameter gives a file specification or other string that
refines a directory listing selection. If you omit it, the server would
usually display a list of all files in the current directory.

Example:

  REMOTE DIRECTORY WORD*.LIS

would ask the server for a listing of the names of all the files with
names starting "WORD" and with file type "LIS".

REMOTE HELP
~~~~~~~~~~~
This command asks the server to display some help information about
itself.

The command format is

  REMOTE HELP <topic>

The parameters are:

  <topic>
This optional parameter specifies a specific topic on which help is
needed: the server may refine its output to suit, or it may ignore the
selection. If you omit it the server would usually output some general
information. Unlike other command parameters, <topic> consists of the
whole of the rest of the command line and so may include spaces.

Example:

  REMOTE HELP

asks the server for general help information.

REMOTE HOST
~~~~~~~~~~~
This command asks the server to pass a command string to the mainframe
operating system's command interpreter for execution.

The command format is

  REMOTE HOST <command>

The parameters are:

  <command>
This is the command you wish to be executed. Unlike other command
parameters it consists of the whole of the rest of the command line, and
so can contain spaces.

Some  care  is needed in the choice of command that you ask to be
executed. Since the operating system has no means of carrying on a
dialogue with you, commands that require interaction, or otherwise cannot
run in batch mode are unsuitable.

Example:

  REMOTE HOST %allow readaccess data.dat

would pass a command "%allow readaccess data.dat" to the server's
operating system for execution.

REMOTE RENAME
~~~~~~~~~~~~~
This command requests the server to change the name of a file.

The command format is

  REMOTE RENAME <oldname> <newname>

The parameters are:

  <oldname>
Specifies the file whose name is to be changed.

  <newname>
Specifies the new name to be given to the file.

Example:

  REMOTE RENAME napoleon snowball

asks the server to change the name of file "napoleon" to "snowball".

REMOTE SPACE
~~~~~~~~~~~~
This command asks the server to display details of your disc usage.

The command format is

REMOTE SPACE <selector>

The parameters are:

  <selector>
This optional parameter specifies some selector by which the server
refines its calculations of disc usage.

Example:

  REMOTE SPACE

produces a display of the disc space you are using.

REMOTE STATUS
~~~~~~~~~~~~~
This command requests the server to display details about its own status.

The command has no parameters.

Example:

  REMOTE STATUS

REMOTE TYPE
~~~~~~~~~~~
This command request the server to type a file on the BBC KERMIT command
screen.

The command format is

  REMOTE TYPE <filename>

The parameters are:

  <filename>
The name of the file you wish to be typed. The server may permit you to
specify wildcards, in which case the matching files will be displayed one
after the other.

Example:

  REMOTE TYPE DATA.LIS

would type the contents of file DATA.LIS.

REMOTE WHO
~~~~~~~~~~
This command requests the server to display details of other users logged
in to the system.

The command has no parameters.

Example:

  REMOTE WHO

A1.5: COMMANDS FOR DETAILED PROTOCOL CONTROL

The commands described in this section are used to exert detailed control
over the KERMIT protocol. As explained earlier, it is unlikely that you
would ever need to use them. You should consult the KERMIT Protocol Manual
for a detailed description of the facilities they control.

SET EIGHT-BIT-PREFIX
~~~~~~~~~~~~~~~~~~~~
This command defines the eight-bit-prefix character that BBC KERMIT will
ask the remote system to agree to use.

The command format is

  SET EIGHT-BIT-PREFIX <character>

The parameters are

  <character>
The printable character to be used.

By default, BBC KERMIT will attempt to use the "&" character as its
eight-bit prefix.

Example

  SET EIGHT-BIT-PREFIX %

sets the eight-bit prefix character to be "%".

SET PAUSE
~~~~~~~~~
This command defines a "turn-round" delay that BBC KERMIT will use in
packet transmission. It defines the time that BBC KERMIT will wait, after
receiving a packet from the remote system, before transmitting the next to
it. This overcomes problems with some systems that cannot accept input
that comes too soon after output.

The command format is

  SET PAUSE <number>

The parameters are

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

By default, BBC KERMIT does not pause (i.e. the pause value is 0).

Example

  SET PAUSE 1

causes BBC KERMIT to pause for 1 second after receiving a packet before
transmitting one.

SET RECEIVE END-OF-LINE
~~~~~~~~~~~~~~~~~~~~~~~
This command defines the value that BBC KERMIT requests the other end to
use to signal the end of a packet.

The command format is

  SET RECEIVE END-OF-LINE <number>

The parameters are

  <number>
The number of the control character in the range 0 to 31.

By default, BBC KERMIT asks for packets to be terminated with Carriage
Return (&0D).

Example

  SET RECEIVE END-OF-LINE &0A

requests the remote KERMIT to terminate packets with Line Feed (code &0A).

SET RECEIVE PACKET-LENGTH
~~~~~~~~~~~~~~~~~~~~~~~~~
This command defines the maximum packet size that BBC KERMIT will ask the
remote system to send. You can use this command to optimise transfers on a
noisy communications line: short packets will have a higher chance of
succesful transmission in such circumstances.

The command format is

  SET RECEIVE PACKET-LENGTH <number>

The parameters are

  <number>
The maximum size of packet wanted from the remote system, in the range 35
to 94.

By default, BBC KERMIT asks the remote system to use a maximum packet size
of 94 bytes.

Example

  SET RECEIVE PACKET-LENGTH 60

causes BBC KERMIT to request the remote system to use a maximum packet
size of 60 bytes.

SET RECEIVE PADCHAR
~~~~~~~~~~~~~~~~~~~
This command defines the character that BBC KERMIT requests the other to
use when padding before sending a packet.

The command format is

  SET RECEIVE PADCHAR <number>

The parameters are

  <number>
The numeric code of the character to be used for padding in the range 0 to
31.

By default, BBC KERMIT will ask for a pad character of code 0.

Example

  SET RECEIVE PADCHAR &07

requests the remote KERMIT to pad with &07 characters.

SET RECEIVE PADDING
~~~~~~~~~~~~~~~~~~~
This command defines the number of pad characters that BBC KERMIT will ask
the other end to send before each packet.

The command format is

  SET RECEIVE PADDING <number>

The parameters are

  <number>
The  number  of  pad characters to be requested, in the range 0 to 94.

By default, BBC KERMIT asks for no pad characters to be sent.

Example

  SET RECEIVE PADDING 10

will cause BBC KERMIT to request the remote system to precede each packet
with 10 pad characters.

SET RECEIVE START-OF-PACKET
~~~~~~~~~~~~~~~~~~~~~~~~~~~
This command defines to BBC KERMIT the character that the remote system
will use to indicate the start of each packet.

The command format is

  SET RECEIVE START-OF-PACKET <number>

The parameters are

  <number>
The numeric code of the character the remote system will use, in the range
0 to 31.

By default, BBC KERMIT will expect the remote system to precede each
packet with a &01 character.

Example

  SET RECEIVE START-OF-PACKET &03

tells BBC KERMIT that the remote system will precede each packet with a
&03 character.

SET RETRIES
~~~~~~~~~~~
This command defines the number of times BBC KERMIT will repeat an attempt
to transmit a packet to, or receive a packet from, the remote system. You
may need to increase the number of attempts allowed if you are using a
noisy communications line.

The command format is

  SET RETRIES <number>

The parameters are:

  <number>
The  number  of  retries  to be made, in the range 1 to 255.

By default, BBC KERMIT will make 5 retry attempts (i.e. a total of 6
attempts in all) before deciding that a packet cannot be transmitted or
received correctly and abandoning the file transfer.

Example:

  SET RETRIES 16

will cause BBC KERMIT to make 16 retry attempts before abandoning the
transfer.

SET SEND END-OF-LINE
~~~~~~~~~~~~~~~~~~~~
This command defines the character that BBC KERMIT will use to terminate
the first packet it sends to the remote system in each transfer.
Subsequent packets will be terminated by the character that the remote
system requests when it tells BBC KERMIT its requirements.

The command format is

  SET SEND END-OF-LINE <number>

The parameters are

  <number>
The numeric code of the character to be used, in the range 0 to 31.

By default, BBC KERMIT uses &0D (Carriage Return).

Example

  SET SEND END-OF-LINE &0A

causes the first packet sent in each transfer to be ended with Line Feed
(code &0A).

  SET SEND PADCHAR

This command defines the padding character with which BBC KERMIT will
precede the first packet to be sent in a transfer. Subsequent packets will
be preceded by the character requested by the remote system in its
SEND-INIT packet.

The command format is

  SET SEND PADCHAR <number>

The parameters are

  <number>
The numeric code of the character to be used, in the range 0 to 255.

By default, BBC KERMIT uses a pad character of NUL (code &00).

Example

  SET SEND PADCHAR &03

sets the pad character used to be &03.

SET SEND PADDING
~~~~~~~~~~~~~~~~
This command defines the number of pad characters BBC KERMIT will send
before the first packet in a transfer. Subsequent packets will be preceded
by the number requested by the remote system when it tells BBC KERMIT its
requirements.

The command format is

  SET SEND PADDING <number>

The parameters are

  <number>
The number of pad characters to be sent, in the range 0 to 255.

By default, BBC KERMIT sends no pad characters.

Example

  SET SEND PADDING 21

causes BBC KERMIT to send 21 pad characters before its first packet.

SET SEND QUOTE
~~~~~~~~~~~~~~
This command defines the character that BBC KERMIT will use to prefix
control characters in data packets that it sends. Since every occurence of
the quote character in a file must itself be preceded by a quote when
transmitted, this command lets you minimise the data to be moved if the
file contains a large number of the normal quote character.

The command format is

  SET SEND QUOTE <character>

The parameters are

  <character>
The printable character to be used.

By default, BBC KERMIT uses the "#" character.

Example

  SET SEND QUOTE $

causes BBC KERMIT to prefix control characters it sends in data packets
with a "$".

SET SEND START-OF-PACKET
~~~~~~~~~~~~~~~~~~~~~~~~
This command defines the character that BBC KERMIT will send to indicate
the start of every packet.

The command format is

  SET SEND START-OF-PACKET <number>

The parameters are

  <number>
The numeric code of the character to be sent, in the range 0 to 31.

By default, BBC KERMIT sends a &01 character in front of every packet.

Example

  SET SEND START-OF-PACKET &04

causes BBC KERMIT to precede every packet it sends with a &04 character.

