Modula-2 Kermit
Users-Manual
Program & Documentation: Matthias Aebi, Inistitut fuer Informatik,
University
of Zuerich
Language: Modula-2
Version: 1.0 (Lilith implementation)
Date: March 1986
1. M2-KERMIT CAPABILITIES AT A GLANCE
Local operation: Yes
Remote operation: No
Transfers text files: Yes
Transfers binary files:
Yes
Wildcard send:
Yes
User interruption:
Yes
Filename collision avoidance:
Can time out:
Yes
8th-bit prefixing:
No
Repeat count prefixing:
No
Alternate block checks:
No
Terminal emulation:
Yes
Communication settings:
Yes
Transmit BREAK: No
Transaction logging:
No
Session logging: No
Raw transmit:
No
Act as server:
Yes
Talk to server: Yes
Advanced server functions:
No
Advanced commands for servers:
Local file management: Yes
Handle file attributes:
No
Command/init files:
No
Command macros: No
Yes
No
M2-Kermit is a program that implements the Kermit file transfer protocol
mainly
for the Lilith workstation. It is entirely written in Modula-2. Therefore
it
should be no problem to adabt it for other systems that have a Modula-2
compiler. In fact this has been done already for a CP/M computer. This
section
will describe the things you should know about Medos, the operating
system of
the Lilith, in order to make effective use of Kermit, and then it will
describe
breefly how to use the M2-Kermit program. For more information refer to
the
'Kermit Users Guide' and the article 'Kermit, a simple file transfer
protocol',
both available from Columbia University. This manual is based on the MSDOS
Kermit users manual.
2. THE MEDOS FILE SYSTEM
The feature of the Medos file system of greatest interest to Kermit users
is
the form of the file specifications.
Medos file specifications are normally of the form
DEVICE.NAME.TYPE
If DEVICE is omitted, DK is assumed. The Medos filesystem is nonhierarchical
and therefore no pathnames are possible. You will never have to specify
the
devicename because the current implementation of M2-Kermit will always
use the
system-disk (DK) as its working device. So NAME.TYPE is normally
sufficient to
specify a file, and only this information is sent along by M2-Kermit with
an
outgoing file.
The NAME and TYPE fields may contain upper- and lowercase letters,
digits, but
no special characters. There may be no imbedded or trailing spaces. Other
characters may not be included; there is no mechanism for "quoting"
otherwise
illegal characters in filenames. The fields of the file specification are
set
off from one another by the punctuation indicated above. Upper- and
lowercase
characters are treated as different by Medos but not by M2-Kermit.
The NAME field is the primary identifier for the file. The TYPE, also
called
the extension or suffix, is an indicator which, by convention, tells what
kind
of file we have. For instance FOO.MOD is the source of a Modula-2 program
named
FOO; FOO.OBJ might be the executable program produced by compiling
FOO.MOD.
Medos allows a group of files to be specified in a single file
specification by
including the special "wildcard" characters, "*" and "%". A "*" matches
any
string of characters from the current position to the end of the field,
including no characters at all; a "%" matches any single character. Here
are
some examples:
*.MOD
All files of type MOD (all Modula-2 source files) on the
system-disk.
FOO.*
Files of all types with name FOO.
F*.* All files whose names start with F.
F%X*.*
All files whose names start with F and contain X in the third
position,
followed by zero or more characters.
%.*
All files whose names are exactly one character long.
Wildcard notation is used on many computer systems in similar ways, and
it is
the mechanism most commonly used to instruct Kermit to send a group of
files.
M2-Kermit users should bear in mind that other systems may use different
wildcard characters. For instance MS-DOS uses "?" instead of "%" as the
single
character wildcard; when using M2-Kermit to request a wildcard file group
from
a MS-DOS server, the M2-Kermit "%" must be replaced by the MS-DOS "?".
Non-Medos systems may well be confused by nonstandard ASCII files from
M2-Kermit. Files produced by Lara for example, may need to be converted
to
conventional ASCII format prior to transmission by commonly available
"exporter" programs. Spreadsheet or database files usually need special
formatting to be meaningful to non-Medos recipients (though they can be
transmitted between Lilith systems with M2-Kermit).
3. PROGRAM OPERATION
M2-Kermit can be run interactively from Medos like any other program. To
run
M2-Kermit, invoke the program from Medos command level by typing
M2Kermit. When
you see the command's prompt,
M2-Kermit>
you may type Kermit commands repeatedly until you are ready to exit the
program, for example:
*M2Kermit
Modula-2 Kermit, Version 1.0 / Lilith
For a list of commands type 'Help'
M2-Kermit>send foo.*
(informational messages about the files being sent)
M2-Kermit>get bar.*
(informational messages about the files being received)
M2-Kermit>exit
*
During interactive operation, you may edit the command you're currently
typing.
To erase the character most recently typed press the DEL key. In
addition, you
may use the help ("?") feature freely while typing M2-Kermit commands. A
question mark typed at almost any point in a command produces a brief
description of what is expected or possible at that point.
4. M2-KERMIT COMMANDS
Modula-2 Kermit implements a subset of the commands of "ideal" Kermit.
Here's a
brief summary:
BYE
to remote server.
CONNECT
as terminal to remote system.
DELETE
local files.
DIRECTORY listing of local files.
EXIT from M2-Kermit.
FINISH
Shut down remote server.
GET
remote files from server.
HELP about M2-Kermit.
LOGOUT
remote server.
QUIT from M2-Kermit
RECEIVE
files from remote Kermit.
SEND files to remote Kermit.
SERVER
mode of remote operation.
SET
various parameters.
SHOW various parameters.
TYPE display a local file.
VERSION
display M2-Kermit program version number.
4.1. COMMANDS FOR FILE TRANSFER
The file transfer commands are SEND, GET, and RECEIVE.
4.1.1. THE SEND COMMAND
Syntax: SEND filespec1 [filespec2]
The SEND command causes a file or file group to be sent from the local
system
to the Kermit on the remote system. The remote Kermit may be running in
either
server or interactive mode; in the latter case, you should already have
given
it a RECEIVE command and escaped back to your machine.
filespec1 may not contain a device designator but the wildcard characters
"*"
and/or "%". If filespec1 contains wildcard characters then all matching
files
will be sent, in the same order that M2-Kermit would show them in a
directory
listing. If filespec1 specifies a single file, you may direct M2-Kermit
to send
that file with a different name, given in filespec2. For instance, in the
command
M2-Kermit>send foo.bar framus.widget
filespec2 begins with the first nonblank character after filespec1 and
ends
with the carriage return; thus it may contain blanks or other unusual
characters that may be appropriate on the target machine. Lower case
letters in
filespec2 are raised to upper case for transmission. This feature may be
disabled. See SET command.
If a file can't be opened for read access, standard Medos error message
will be
displayed at the screen. For example:
FOO.MOD not supported
Files will be sent with their filename and filetype (for instance
FOO.TXT, no
devicename). Each file is sent as is, with no conversions done on the
data.
Once you give M2-Kermit the SEND command, the name of each file will be
displayed on your screen as the transfer begins; packet, retry, and other
counts will be displayed along with informational messages during the
transfer.
If the file is successfully transferred, you will see "Send successful",
otherwise there will be an error message.
To abort while a file transfer is in progress press the ESC key. This
will
cause M2-Kermit to return to command level after sending an Error packet
to the
remote Kermit in an attempt to bring it back to server or interactive
command
level.
Press CR to simulate a timeout: resend the current packet, or NAK the
expected
one.
4.1.2. THE RECEIVE COMMAND
Syntax: RECEIVE [filespec]
The RECEIVE command tells M2-Kermit to receive a file or file group from
the
other system. M2-Kermit passively waits for the file to arrive; this
command
is not to be used when talking to a Kermit server (use GET for that). You
should already have issued a SEND command to the remote Kermit and
escaped back
to M2-Kermit before issuing the RECEIVE command.
If the optional filespec is provided, store the incoming file under that
name.
The filespec may not include a device designator. The incoming file is
stored
on the system-device. If no name was specified, the name from the
incoming file
header packet is used; if that name is not a legal Medos file name, M2Kermit
will delete excessive characters from it, and will change illegal
characters to
the letter X.
If the optional filespec was provided, but more than one file arrives,
the
first file will be stored under the given filespec, and the remainder
will be
stored under their own names.
If an incoming file does not arrive in its entirety, M2-Kermit will
discard it;
it will not appear in your directory.
The same single-character commands are available as during SEND:
ESC aborts a file transfer in progress and returns to command level after
sending an Error packet to the remote Kermit in an attempt to bring it
back to
server or interactive command level.
CR simulates a timeout: resend the current packet, or NAK the expected
one.
If the incoming file has the same name as a file that already exists, and
WARNING is set ON, M2-Kermit will change the incoming name (and inform
you how
it renamed it) so as not to obliterate the pre-existing file. If WARNING
is
OFF, the original file will be overwritten.
4.4. THE GET COMMAND
Syntax: GET
[filespec] remote-filespec
The GET command requests a remote Kermit server to send the file or file
group
specified by remote-filespec. This command can be used only when M2Kermit has
a Kermit server active on the other end of the connection. This means
that you
must have CONNECTed to the other system, logged in, run Kermit there,
issued
the SERVER command, and escaped back (e.g. ^\ C) to the local M2-Kermit.
If the
remote Kermit does not have a SERVER command, then you should use SEND
and
RECEIVE as described above.
If you provide the optional filespec the incoming file will be stored
under
that name.
The local file name may not contain a device field. If more than one file
arrives, only the first will be renamed.
The remote filespec is any string that can be a legal file specification
for
the remote system; it is not parsed or validated locally. It can contain
whatever wildcard or file-group notation (including blanks) is valid on
the
remote system. As files arrive, their names will be displayed on your
screen,
along with packet traffic statistics and status messages. You may type
ESC to
return immediately to the M2-Kermit> prompt, exactly as described for the
RECEIVE command.
4.2. COMMANDS FOR TERMINAL CONNECTION
The CONNECT command connects your Lilith as a terminal to the remote
system, so
that you can start up Kermit there. The BYE, FINISH, and LOGOUT commands
allow
you to shut down a remote Kermit server:
4.2.1. THE BYE COMMAND
When communicating with a remote Kermit server, use the BYE command to
shut
down the server, log out its job, and exit locally from M2-Kermit to
Medos.
4.2.2. THE FINISH COMMAND
Like BYE, FINISH shuts down the remote server. However, FINISH does not
log out
the server's job. You are left at M2-Kermit prompt level so that you can
connect back to the job on the remote system.
4.2.3. THE LOGOUT COMMAND
The LOGOUT command is identical to the BYE command, except you will
remain at
M2-Kermit prompt level, rather than exit to Medos, so that you can
establish
another connection.
4.2.4. THE CONNECT COMMAND
Establish an interactive terminal connection to the system connected to
the
currently selected communications port (on the Lilith there is only one
port)
using full duplex (remote) echoing and no parity unless otherwise
specified in
previous SET commands. Get back to M2-Kermit by typing the escape
character
followed by the letter C. On most systems the escape character is
Control-\ by
default.
You can use the SET ESCAPE command to define a different escape character
and
SET BAUD to change the baud rate, and SET PORT to switch between ports
(SET
PORT has no effect on a Lilith). For more information refer to the SET
command
description.
4.3. COMMANDS FOR FILE MANAGEMENT
M2-Kermit offers three commands for managing local files.
4.3.1. THE DELETE COMMAND
Syntax: DELETE filespec
Deletes the specified file or files. As in Medos, the names of the
deleted
files are listed, and you are prompted for yes or no for each single
file.
Upper- and lower-case characters are treated equal. Wildcards are
allowed.
4.3.2.
THE DIRECTORY COMMAND
Syntax: DIRECTORY [filespec]
Lists the names of files that match the given file specification. If no
filespec is given, the command is equivalent to DIR *. Upper- and lowercase
characters are treated equal.
4.3.3. THE TYPE COMMAND
Syntax: TYPE filespec
Displays the specified local file on the screen. Do not try to display a
binary
file because this may lead to a system crash. The display of a file may
be
stopped and resumed by pressing any key. ESC aborts the command.
4.4. THE SERVER COMMAND
M2-Kermit is capable of acting as a Kermit server, providing file
transfer for
users coming in through one of the communication ports. The current
version of
M2-Kermit can send files (the user on the other end types the GET
command),
receive files (the user types SEND), and terminate, giving control back
to the
console (user types BYE).
To put M2-Kermit into server mode, first issue any desired SET commands
to
select and configure the desired port, and then type the SERVER command.
M2-Kermit will await all further instructions from the user Kermit on the
other
end of the connection, which may be hardwired or connected through an
autoanswer modem. For example:
M2-Kermit>set baud 1200
M2-Kermit>set timer on
M2-Kermit>set warning on
M2-Kermit>server
4.5. THE SET COMMAND
Syntax: SET parameter value
Establish or modify various parameters for file transfer or terminal
connection. You can examine their values with the SHOW command. The
following
SET commands are available in M2-Kermit:
BAUD Communications port line speed
CHECK-TYPE Level of error checking for file transfer
DEBUG Display packet contents during file transfer
END-OF-LINE Packet terminator
ESCAPE
Escape character for CONNECT
FILE-TYPE Specify the type of file to be transmitted (Text or Binary)
LOCAL-ECHO Specify which host does the echoing during CONNECT
NAME-CONVERSION Specify whether filenames should be 'normalized' or not
PACKET-LENTH
Maximum length of a Kermit packet
PADCHAR
Use this character for padding
PADDING
How many padding characters should be sent
PARITY
Character parity to use
PORT Select a communications port
PREFIX
Specify prefix character for 8-th bit prefixing
PROMPT
Change the "M2-Kermit>" prompt to something else
RETRIES
Maximum number of retries before abort
SET QUOTE Specify character for prefixing (quoting) control characters
START-OF-PACKET Strart each packet with this character (nomally ASCII
01)
TIMEOUT
Timeout after how many seconds
TIMER Enable/disable timeouts during file transfer
WARNING
Specify how to handle filename collisions
The SET commands are now described in greater detail.
4.5.1. THE SET BAUD COMMAND
Syntax: SET BAUD rate
Set the speed of the communications port to 300, 600, 1200, 2400, 4800,
9600
bit/s. M2-Kermit initializes the communication port baud rate to 9600
bit/s.
4.5.2. THE SET CHECK-TYPE COMMAND
Syntax: SET CHECK-TYPE 1 or 2 or 3
Set the block check type to level 1 to 3. Check type 1 is a one byte
checksum.
This is currently the only level of block checking supported by M2-Kermit
and
therefore default.
4.5.3. THE SET DEBUG COMMAND
Syntax: SET DEBUG ON or OFF
ON Display the Kermit packet traffic on your screen during file transfer.
OFF Don't display debugging information (this is the default). If
debugging was
in effect, turn it off.
Be careful not to select debugging mode when transmitting binary files.
The
Screen I/O Module will not like characters with high bit on. Therefore do
not
set DEBUG ON while transferring binary data.
4.5.4. THE SET END-OF-LINE COMMAND
Syntax: SET END-OF-LINE number
If the remote system needs packets to be terminated by anything other
than
carriage return, specify the decimal value of the desired ASCII
character.
4.5.5. THE SET ESCAPE COMMAND
Syntax: SET ESCAPE character
Specify the control character you want to use to "escape" from remote
connections back to M2-Kermit. The default is normally ^\ (ControlBackslash).
The character is entered literally, and should normally be chosen from
the
ASCII control range.
4.5.6. THE SET FILE-TYPE COMMAND
Syntax: SET FILE-TYPE BINARY or TEXT
If you specify the file type to be a text file, Kermit will automatically
convert between the different end of line representations on different
computer
systems. Besides this it will also strip the high bit of each character
which
is necessary because this bit is used for parity information. If you
specify a
file to be binary, it will be sent or received without any changes.
4.5.7. THE SET LOCAL-ECHO COMMAND
Syntax: SET LOCAL-ECHO ON or OFF
Specify how characters are echoed during terminal emulation. ON specifies
that
characters are to be echoed by M2-Kermit (because neither the remote
computer
nor the communications circuitry has been requested to echo), and is
appropriate for half-duplex connections. LOCAL-ECHO is OFF by default,
for
full-duplex, remote echo operation.
4.5.8. THE SET NAME-CONVERSION COMMAND
Syntax: SET NAME-CONVERSION ON or OFF
Because different computer systems have different rules for filenames,
Kermit
normally converts these names to a standard representation which means
there
are no special characters and only uppercase letters. If you transfer
files
between the two computers using the same operating system, they have the
same
filename rules anyway. In this case you may specify NAME-CONVERSION off
to
transmit the filenames without any changes.
4.5.9. THE SET PACKET-LENGTH COMMAND
Syntax: SET PACKET-LENGTH value
The maximal packetsize for a Kermit packet is normally 94 including the
checksum bytes (always one for M2-Kermit). If you use a communications
line
without frequent distortions this will give you a minimum of overhead for
packet frames. If the line you have to use isn't very reliable you may
use
shorter packets to reduce the overhead for retransmitting packets which
have
been corrupted. Normally, M2-Kermit uses whatever length the other Kermit
requests.
4.5.10. THE SET PADCHAR COMMAND
Syntax: SET PADCHAR value
Use the specified character for interpacket padding. Some hosts may
require
some padding characters (normally NUL) before a packet. Specify the
decimal
value of the desired ASCII character.
4.5.11. THE SET PADDING COMMAND
Syntax: SET PADDING value
Specify the number of padding characters to be sent between packets. This
is
may be useful if the remote system is slow and needs some extra time to
handle
each packet sent to it. PADDING is normally zero.
4.5.12. THE SET PARITY COMMAND
Syntax: SET PARITY keyword
Specify the character parity to be used. The choices for SET PARITY are
NONE
(the default), ODD, EVEN, MARK, and SPACE. NONE means no parity
processing is
done, and the 8th bit of each character can be used for data when
transmitting
binary files.
You will need to SET PARITY to ODD, EVEN, MARK, or possibly SPACE when
communicating with a system, or over a network, or through modems,
concentrators, multiplexers, or front ends that require or impose
character
parity on the communication line. For instance, GTE Telenet requires MARK
parity. If you neglect to SET PARITY when the communications equipment
requires
it, the symptom may be that terminal emulation works partially, and file
transfer does not work at all.
If you have set parity to ODD, EVEN, MARK, or SPACE, then M2-Kermit will
request that binary files will be transferred using 8th-bit-prefixing. If
the
other side knows how to do 8th-bit-prefixing (this is an optional feature
of
the Kermit protocol, and not all implementations of Kermit have it), then
binary files can be transmitted successfully. If NONE is specified, 8thbitprefixing will not be requested. Note that there is no advantage to using
parity; it only slows Kermit file transfer down. The SET PARITY command
is
provided only to allow Kermit to adapt to hardware that insists upon
using
parity. M2-Kermit does currently not allow 8-bit prefixing. Therefore if
you
want to transmit binary files you must set PARITY to NONE or the
transmission
will not work correctly. M2-Kermit is not yet able to handle 8-th bit
prefixing.
4.5.13. THE SET PORT COMMAND
Syntax: SET PORT number
On machines with more than one communications port, select the port to
use for
file transfer and CONNECT. This command lets you use a different
asynchronous
adapter, or switch between two or more simultaneous remote sessions.
Subsequent
SET BAUD, PARITY and LOCAL-ECHO commands will apply to this port only.
SET PORT
has currently no effect for the Lilith which has only one port.
4.5.14. THE SET PREFIX COMMAND
Syntax: SET PREFIX character
Use the indicated printable character for 8th-bit prefixing. This has an
effect
only if you try to transmit a binary file over a 7 bit data path, i.e. a
line
which needs parity. Because M2-Kermit is not able to handle 8-th
prefixing SET
PREFIX has currently no effect.
4.5.15. THE SET PROMPT COMMAND
Syntax: SET PROMPT character-string
Change the prompt string (Kermit-M2) to the given character-string.
4.5.16. THE SET QUOTE COMMAND
Syntax: SET QUOTE character
Use the indicated printable character for prefixing (quoting) control
characters and other prefix characters. The only reason to change this
would be
for sending a very long file that contains very many "#" characters (the
normal
control prefix) as data.
4.5.17. THE SET RETRIES COMMAND
Syntax: SET RETRIES value
Set the number of retries before a command is to be aborted. This is set
to 13
by default.
4.5.18. THE SET START-OF-PACKET COMMAND
Syntax: SET START-OF-PACKET value
Mark the beginning of outbound packets with some control character other
than
Control-A. This will be necessary only if the remote host or the
communication
channel involved cannot accept a Control-A as data.
4.5.19. THE SET TIMEOUT COMMAND
Syntax: SET TIMEOUT value
Change M2-Kermit's normal timeout interval; this command is effective
only if
TIMER is set to be ON; it is normally ON so that M2-Kermit can control
timeouts. The timeout interval is specified in seconds.
4.5.20. THE SET TIMER COMMAND
Syntax: SET TIMER ON or OFF
Enable or disable the timer that is used during file transfer to break
the
deadlock that occurs when an expected packet does not arrive. By default,
the
timer is ON. If M2-Kermit is used in conjunction with a mainframe that is
doing
its own timeouts it should be set OFF. During a file transfer, it is
sufficient
for one side to do the timing out and the mainframe is usually better
equipped
to adjust timeout intervals based on system load or other conditions. The
timer
should be set ON if you are communicating with a mainframe that cannot do
timeouts, such as IBM VM/CMS Kermit.
4.5.21. THE SET WARNING COMMAND
Syntax: SET WARNING ON or OFF
Specify what to do when an incoming file has the same name as an existing
file.
If ON, Kermit will warn you when an incoming file has the same name as an
existing file, and automatically rename the incoming file (as indicated
in the
warning message) so as not to destroy (overwrite) the pre-existing one.
If OFF,
the pre-existing file is destroyed, even if the incoming file does not
arrive
completely.
The new name is formed by appending '.V' and a version number to the name
until
a unique name is found. For instance, ABC.TXT becomes ABC.TXT.V1, then
ABC.TXT.V2, ABC.TXT.V3, ..., ABC.TXT.V10, ABC.TXT.V11, etc.
4.6. THE SHOW COMMAND
Syntax: SHOW
Most parameters that may be altered with SET commands are displayed by
the SHOW
command.
4.7 TERMINAL EMULATION
When you issue the CONNECT command, your Lilth acts as a terminal
connected to
a remote computer through the serial I/O port. The characters you type
are sent
out the port, and characters that arrive at the port are displayed on
your
screen. If you have SET LOCAL-ECHO ON, then M2-Kermit will display
characters
on the screen as you type them. If LOCAL-ECHO is OFF, then XON/XOFF flow
control will be done. If you have SET PARITY to anything other than NONE,
M2-Kermit will add the appropriate parity to each outbound character, and
strip
any parity from incoming ones. While CONNECTed, you can also communicate
with
an autodialer or "smart modem" to control the communications line, hang
it up,
and the like; for instance, typing +++ to a Hayes-like modem will allow
you to
follow that by dialing or hangup commands.
The terminal currently emulated by M2-Kermit is only a dumb terminal
without
any screen control features.
The escape character is used to regain the attention of M2-Kermit. When
you
type the escape character, M2-Kermit waits for you to follow it with a
single
character command. For instance, the single-character-command "?"
produces a
list of available single character commands, such as this:
?
Help -- prints the available single-character commands.
C
Close the connection and return to M2-Kermit prompt level.
S
Show the status of the connection.
0
(the digit zero) Transmit a NUL (ASCII 0).
^\
(or whatever you have set the escape character to be) Typing the
escape
character twice sends one copy of it to the connected host.
The escape character can be changed to something other than ControlBackslash
by using the SET ESCAPE command.
5. WHAT'S MISSING
M2-Kermit has plenty of room for improvement. Features that may be
improved or
added include:
%
A built-in facility for sending files "raw" to the remote system,
obeying current settings for parity, flow control, handshake, and
so
forth.
This might include a script interpretation facility to
allow
remote sessions to be conducted automatically.
%
Additional functionality when running in server mode -- help,
directory
listings, file deletion, listing files, execution of local
commands,
etc.
%
Possibility to use remote commands when talking to servers -REMOTE
RENAME, HELP, DIR, COPY, STATUS, WHO, etc.
%
Allowance for file specifications, including device names, in all
commands.
%
Transaction file logging.
%
Improved command parsing; for instance, accept default values for
omitted trailing fields.
%
Support for Kermit file attribute packets.
%
8-th bit prefixing
%
Repeat count prefixing
%
Alternate block checks
%
More sophisticated terminal emulation
%
Session logging
%
Allowance for command / init files
%
Command macros
%
Use of pulldown-menus and windows