Columbia Kermit/kermit.zip/lilith/m2kermdoc.txt

Text File | 2020-01-01 | 28KB | 699 lines

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:    Yes
    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:    No
    Local file management:    Yes
    Handle file attributes:    No
    Command/init files:    No
    Command macros:    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 MS-DOS
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 non-hierarchical
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, M2-Kermit
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 M2-Kermit 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 lower-case
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 ^\ (Control-Backslash).
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, 8th-bit-
prefixing 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 Control-Backslash
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