\documentstyle[12pt]{report}
\title{Keasy: A \kermit\ Primer}
\author{Barbara Rosi}
\date{}

%\renewcommand{\sc}{\bf}

\newcommand{\kermit}{{\sl Kermit}}
\newcommand{\kermits}{{\sl Kermits}}
\def\escape{\tt\char`^]}

\begin{document}
\maketitle

{\LARGE\bf Preface}

\bigskip
This document is excerpted from:
\bigskip

\begin{center}
Fifth Edition, Revision 1\\Frank da Cruz, editor\\Columbia University
Center for Computing Activities\\New York, New York 10027\\27 July 1984\\
~~~\\Copyright (C) 1981,1982,1983,1984\\Trustees of Columbia University in
the City of New York\\
~~~\\Permission is granted to any individual or institution to copy or\\use
this document and the programs described in it, except for\\explicitly
commercial purposes.
\end{center}

\medskip
Information specific to \kermit\ implementations  have been excluded.
\vfil
\eject

\tableofcontents

\chapter{Introduction}

This short introduction to the \kermit\ protocol --nothing more than a
summary of the exixting documents on the subject-- is meant to cover the
very basic requirements and to answer to the first simple questions
arising when using a \kermit\ program.

\section{What \kermit\ is about}

\kermit\ is the name of a \underline{protocol}\footnote{A protocol is a set
of conventions and of rules that computers follow in order to exchange
informations to one another: they must agree, f.i., on the speed, on the
form of ``greetings'' to be used at the beginning and the end of a
transmission, on how to distinguish between data and control
information, which arrive all intermixed, and so on.}
for transferring
files from one computer to another over ordinary asynchronous terminal
connections.  \kermit\ is an alternative solution to networks,
which are usually expensive,
 complex to install and often designed to work with only a particular
type of equipment.  \kermit\ programs instead allow any machine to establish
a connection to any other computer reachable via a cable or a telephone
modem.

\section{A short history}

The \kermit\ file transfer protocol was designed at the
Columbia University Center for Computing Activities (CUCCA) in 1981-82
mainly by Bill Catchings and Frank da Cruz.
\noindent
The initial objective was to allow users of DEC-20 and IBM timesharing
systems to archive their files on microcomputer floppy disks.

\kermit\ was then presented at conferences of user groups, and
began to be requested from other sites.  Since the creators had written
down a description of the protocol, some sites wrote their own
implementations for new computers, or adapted existing ones
to run on additional systems, and sent back these new versions to
Columbia University so that they could be shared with other people.

In this way now \kermit\ supports more than 100 different systems.

\section{Underlying ``conditions'' for \mbox{using} \space \mbox{\kermit}}

\kermit\ programs are produced on a voluntary basis and contributed
freely for public use, but without any kind of warranty or guarantee, or
any commitment to fix problems.  Sites are free to redistribute \kermit\
on their own terms, provided they

\begin{quote}
``bear in mind that the
philosophy of \kermit\ has always been that \kermit\ is not, and never
should become, a commercial product, sold for profit.  Its goal is to
promote communication and sharing, and \kermit\ itself should be freely
shared, and not sold.  Media and reproduction costs may be recouped if
desired, but profit should not be the motive\footnote{From the {\sl Kermit
Protocol Manual}.} \ldots''
\end{quote}

Moreover, the original
creators of \kermit\ encourage people to send new material back to
Columbia University at the address which is listed below so that it is
possible to maintain a definitive and comprehensive set of \kermit\
implementations for further distribution.

\vfil
\eject

\noindent Last but not least,
they ask for \kermit\ to be used only for peaceful purposes\footnote{See
the {\sl Kermit User Guide}.}.

\medskip
\begin{tabular}{l}
Kermit Distribution \\
Columbia University Center for Computing Activities \\
612 West 115th Street \\
New York, N.Y.  10025
\end{tabular}

\section{\kermit's solution to \mbox{transmission} \space \mbox{problems}}

When data is transmitted from one computer to another, the receiving
computer has to be instructed to take in the data and put it somewhere,
and it also needs a way of ensuring that the data has been received
correctly and completely in spite of several factors that will tend to
interfere with this process, like noise (which often corrupts data),
timing (data may come in faster than the receiving
machine can handle it),
or lines outages (a line may stop working
during short periods, with a resulting data loss).

The way \kermit\ overwhelms these problems is to break
data up into pieces and to encapsulate these pieces into packets.

The transfer is then achieved via {\bf two} \kermit\ programs,
 one running on each computer, that send messages to each other.

The \kermit\ protocol is ``character-oriented'', because data is
transmitted in the form of discrete characters, like A,B,C.  Most
computers agree on the characters representation: there are 128
characters, of which 95 are printable and the other 33 are reserved for
control or formatting purposes (ASCII character Set).

\chapter{How to Use Kermit}

\section{Making the basic connection}

Your task is just to get the two \kermits\ started.  {\bf You have
to use a single keyboard and screen to talk to two different computers,
two different programs}.

An example: you are sitting
at a personal computer (PC), which is connected to a host computer.
From system command level on your PC, first run the \kermit\
program.  Then tell \kermit\ to {\sc Connect} you to the host.
At this point you log in, and
then run \kermit\ on the host.  Now you have a \kermit\
on each end of the wire.

\medskip
\noindent Normally \kermit's prompt is

\medskip
\verb+Kermit-xx>+

\medskip
\noindent The {\tt xx} identifies the implementation of \kermit.  It is very
handy when you become confused about which one of the two
\kermits\ you are talking to.

\noindent In addition, most \kermits\ print an informative message like

\medskip
\verb+  [Connecting to remote host, type CTRL-]C to return]+

\medskip
\noindent when you {\sc Connect}, and type another message like

\medskip
\verb+  [Connection closed, back at PC]+

\medskip
\noindent when you return.

Having {\sc Connect}ed to the host, the way to get
back to the PC is the use of an \underline{escape sequence}.  The
escape character is normally a peculiar one, usually a control character,
such as Control-{\tt ]} (also written as {\escape} ).

\section{Transferring a File}

Let's consider the previous example again. The most direct way to proceed at
this point is to tell each \kermit\ what to do.  Suppose you
want to transfer a file from the host to the PC; first you tell
the host \kermit\ to {\sc Send} the file, then ``escape'' back to the
PC \kermit\ and tell it to {\sc Receive} the file.  The transfer
begins.  The PC \kermit\ will produce a running display on
your screen as the transfer proceeds, and will notify you when it is
complete.
The desired file is now on your PC's disk.  The \kermit\
protocol has ensured that the file arrived correctly and completely.

Now you must close the transmission: {\sc Connect} back to the host, exit
from \kermit\ on the host, log out from the host, ``escape''
back to PC \kermit\ and exit from it.

Transferring a file in the other direction works the same way, but with
the {\sc Send} and {\sc Receive} commands reversed.

\section{An alternative way: the \kermit\ server}

Most of the major implementations of \kermit\ can be servers
(not only mainframes
 but also some PC implementations can act as servers, notably MS-DOS and
Unix).

A \kermit\ server is a \kermit\ program that does
not interact directly with the user, but only with another \kermit\
program. The server is run on the remote computer.  You must still
{\sc Connect} to the remote host to log in and start the server, but you no
longer have to tell one side to {\sc Send} and the other to {\sc Receive}.

You give all the commands to the local \kermit. The \kermit\
server waits for a message from the local \kermit\ saying what to do.

After escaping back to the local
system, you can give as many {\sc Send} and {\sc Get} commands as you
like; at the end of the transmission procedure, you can give the {\sc Bye}
command, which sends a message to the remote \kermit\ server to log itself
out. However, if you want to {\sc Connect} back to the host, you can use the
{\sc Finish} command instead of {\sc Bye}, to shut down the \kermit\
server on the remote host without logging it off, allowing you to
{\sc Connect} back to your job there.

Some servers also provide additional services, such as directory
listings, file deletion, or disk usage inquiries.

Here's an example of the use of a \kermit\ server.  The user
is sitting at a CP/M-80 microcomputer and a DEC-20 is the remote host.

\begin{tabbing}
{\tt Kermit-80>send file.pas}   \={\sl Send another file.}          \kill
{\tt A>Kermit}             \>{\sl Run \kermit\ on the micro.}          \\
{\tt Kermit-80 V4.05}                                                  \\
                                                                       \\
{\tt Kermit-80>}           \>{\sl This is the micro \kermit 's prompt.}\\
{\tt Kermit-80>connect}    \>{\sl Connect to the DEC-20.}
\end{tabbing}

\verb+[Connecting to remote host.  Type CTRL-]C to return to micro.]+

\begin{tabbing}
{\tt Kermit-80>send file.pas}   \={\sl Send another file}             \kill
{\tt CU20E}                \>{\sl The DEC-20 prints its herald.}        \\
\verb+@login my-id password+ \>{\sl Log in normally.}
\end{tabbing}

\noindent (The DEC-20 prints various login messages here.)

\begin{tabbing}
{\tt Kermit-80>send file.pas}   \={\sl Send another file.}            \kill
\verb+@Kermit+             \>{\sl Run Kermit-20 normally}               \\
{\tt Kermit-20>server}     \>{\sl Tell it to be a server.}
\end{tabbing}

\begin{verbatim}
  Kermit Server running on DEC-20 host. Please type your escape
  sequence to return to your local machine. Shut down the server
  by typing the Kermit Bye command on your local machine.
\end{verbatim}

\begin{tabbing}
{\tt Kermit-80>send file.pas}   \={\sl Send another file.}            \kill
{\escape \tt C}                  \>{\sl Now escape back to the micro.}
\end{tabbing}

\verb+[Connection closed, back at micro.]+

\begin{tabbing}
{\tt Kermit-80>send file.pas}   \={\sl Send another file.}              \kill
{\tt Kermit-80>get $\ast$.pas}  \>{\sl Get all my DEC-20 Pascal programs.}\\
{\tt Kermit-80>send foo.$\ast$}\>{\sl Send all the ``foo'' files from my
micro}\\
{\tt Kermit-80>bye}         \>{\sl Shut down the \kermit\ server.}        \\
{\tt A>}                   \>{\sl Back at CP/M automatically.}
\end{tabbing}

\chapter{Kermit Commands}

No \kermit\ program will have all the following
commands  or  support  all the corresponding options.  The exact form of some
of the commands may differ from version to version.

\section{Remote and Local Operation}

In \kermit\ jargon the words ``local'' and ``remote'' have exactly the
same meaning as they do in everyday life.

``Local'' means ``nearby''. The local system is the closer of two
communicating systems; it can directly interact with you via the
keyboard and screen while it's transferring files.

``Remote'' means ``far away''; therefore of the two computer, the more
distant one is the remote. All file transfer is done over the line on which
you  logged in.

When the local \kermit\ is {\sc Connect}ed to the remote computer,
again running its own copy of \kermit, the local
\kermit\ is in control of the screen, whereas the remote \kermit\ has no
direct access to it.

Some commands make sense only for remote \kermits\, others only for local,
still  others can be used with either.

\section{Summary of \kermit\ Commands}

Each of the commands that you may type, possibly followed by additional
keywords or operands, is called a \underline{field}.  You can abbreviate
keywords (but not file  names) to any  length  that  makes  them
distinguishable from any other keyword valid for that field.  You can type
a question mark at any time to get information  about what's expected or
valid at that point.

Here is a brief list of \kermit\ commands as they can be found in most  \kermit\
programs.  The following sections will describe these commands in more detail.

\begin{itemize}
\item For exchanging files:
\begin{description}
\item[] {\sc Send, Receive, Get}
\end{description}

\item Connecting to a remote host:
\begin{description}
\item[] {\sc Connect, Set Line, Set Parity, Set Duplex, Set Handshake, Set
Escape, Set Flow-Control, Set Speed} (or {\sc Baud})
\end{description}

\item Acting as a server:
\begin{description}
\item[] {\sc Server}
\end{description}

\item Talking to a server:
\begin{description}
\item[] {\sc Bye, Finish, Get, Send, Remote}
\end{description}

\item Setting nonstandard transmission and file parameters:
\begin{description}
\item[] {\sc Set Block-Check, Set Debug, Set Delay, Set File, Set Incomplete,
Set Parity, Set Retry;}
\item[] {\sc Set Send} (or {\sc Receive}) {\sc: End-Of-Line, Start-Of-Packet,
Packet-Length, Pause, Timeout, Padding}
\end{description}

\item Defining ``macros'' of commands:
\begin{description}
\item[] {\sc Define}
\end{description}

\item Interrupting transmission:
\begin{description}
\item[] {\sc Control-X, Control-Z, Control-C, Control-E}
\end{description}

\item Getting information:
\begin{description}
\item[] {\sc Help, Statistics, Show}
\end{description}

\item Executing command files:
\begin{description}
\item[] {\sc Take}
\end{description}

\item Recording the history of a file transfer operation:
\begin{description}
\item[] {\sc Log: Transactions, Session, Debug}
\end{description}

\item Non-protocol file capture or transmission:
\begin{description}
\item[] {\sc Transmit, Input, Output, Pause, Clear, Script}
\end{description}

\item Closing log files:
\begin{description}
\item[] {\sc Close}
\end{description}

\item Leaving the program:
\begin{description}
\item[] {\sc Exit, Quit}
\end{description}

\end{itemize}

If you have a \kermit\ initialization file
in the appropriate location,
\kermit\ will execute an automatic {\sc Take} command
on it upon initial startup.  This file may contain any \kermit\ commands,
for instance {\sc Set} commands, or {\sc Define}s for macros to
configure \kermit\ to various systems or communications media.

\noindent The file name is system-dependent, i.e.

\medskip
\noindent MSKERMIT.INI in MS-DOS \\
\noindent .KERMRC in Unix \\

\section{Send}

\underline{Syntax}:  {\sc Send} filespec1 [filespec2]

\medskip
\noindent This command {\sc Send}s  the  file or file group\footnote{Some
implementations  of  \kermit\  may not support transfer of file
groups.}
specified by filespec
from this \kermit\ to the other.  The name of each file is passed to the other
\kermit\ so that it can be stored there with the same
name. A file group is usually specified by including ``wildcard'' characters
like  ``$\ast$''  in  the file specification.

If communication line parity is being used\footnote{See {\sc Set Parity}.},
the sending \kermit\ will request that the other \kermit\ accepts a
special kind of prefix notation for binary files.  This is an advanced
feature, and not all \kermits\ have it; if the other \kermit\ does not agree
to use this feature, binary files cannot be sent successfully.

Once you
give \kermit\ the {\sc Send} command, the name of each file is printed
on
 your screen as the transfer begins, and progress information will be
displayed. When the specified operation is
complete, the program will sound a beep, and the status of the operation
will be indicated by a message like OK, Complete, Interrupted, or
Failed.

If you see many packet retry indications, you are probably suffering
from a noisy connection, or the communication parameters may not be correct
\footnote{See the \kermit\ {\sl User Guide} for details.}.

You can cancel the {\sc Send} operation while it is taking place by
typing either \underline{Control-X} or \underline{Control-Z}.  If your are
{\sc Send}ing a file group, \underline{Control-X} will cause the current
file to be skipped, and \kermit\ will go on to the next file, whereas
\underline{Control-Z} will cancel {\sc Send}ing
the entire group and return you to \kermit\ command level.

\section{Receive}

\underline{Syntax}:  {\sc Receive} [filespec]

\medskip
\noindent The {\sc Receive} command tells \kermit\ to wait for the arrival
of a file or
file group sent by a {\sc Send} command from the other system.  If only
one file is being {\sc Receive}d, you may include the optional filespec
as the name under which to store the incoming file; otherwise, the
original name is maintained. If the name is
not a legal file name on the local system, \kermit\ will attempt to
transform it to a legal name.

If an incoming file has the same name as an existing file, \kermit\ will
either overwrite the old file or else try to create a new unique name,
depending on the Setting of {\sc File Warning}.

If an incoming file does not arrive in its entirety, \kermit\ will normally
discard it.

\section{Get (Local Only)}

\underline{Syntax}: {\sc Get} [remote-filespec]

\medskip
\noindent The {\sc Get} command requests a remote \kermit\ server to
Send the file or file group specified by remote-filespec.  Note the
distinction between the {\sc Receive} and {\sc Get} commands: {\sc
Receive} instructs the program to wait passively, whereas {\sc Get}
actively sends a request to a server.

The {\sc Get} command can be used only when \kermit\ is local, with a \kermit\
server on the other end of the line.  This means that you must have {\sc
Connect}ed to the other system, logged in, run \kermit\ there, issued the
{\sc Server} command, and escaped back to the local \kermit.

\section{Server}

\underline{Syntax}: {\sc Server}

\medskip
\noindent The {\sc Server} command is given to a remote \kermit\ so that
it may receive all further instructions
from the local \kermit:
after placing a remote \kermit\ in server mode, you must escape back to
the local \kermit\ and issue all further commands from there.
The local \kermit\ must
have commands for communicating with remote servers; these include {\sc
Get}, {\sc Send}, {\sc Finish}, and {\sc Bye}.

{\bf Any nonstandard parameters should be selected with {\sc Set} commands
before  putting \kermit\ in server mode}.

\section{Bye (Local Only)}

\underline{Syntax}: {\sc Bye}

\medskip
\noindent When running as a local \kermit\ talking to a \kermit\ server, the
{\sc Bye} command shuts down the remote server and exits from \kermit.  This
will cause the job at the remote end to log itsef out
(eventually closing any debugging log files).

\section{Finish (Local Only)}

\underline{Syntax}: {\sc Finish}

\medskip
\noindent When running as a local \kermit\ talking to a remote server, use this
command to shut  down  the  server  without  having it log itself out;
a subsequent {\sc Connect} command will put you back at your job on the
remote host, at system command level.

\section{Remote (Local Only)}

\underline{Syntax}: {\sc Remote} [command]

\medskip
\noindent When running as a local \kermit\ talking to a remote \kermit\
server, use the {\sc Remote} command to request special functions of the
remote server.  The server will send the results back, and they
will be displayed on the screen.  The {\sc Remote} commands are:

\begin{description}
\item[] {\sc Remote Cwd} [directory]
\begin{description}
\item[] Change Working Directory.  If no directory name is provided, the
server will  change to the default directory.
\end{description}

\item[] {\sc Remote Delete} [filespec]
\begin{description}
\item[] Delete the specified file or files.
\end{description}

\item[] {\sc Remote Directory} [filespec]
\begin{description}
\item[] The names of the files that match the given file specification will
be displayed on your screen, possibly along with additional information
about file sizes and dates.  If no file specification is given, all files
from the current directory will be listed.
\end{description}

\item[] {\sc Remote Space} [directory]
\begin{description}
\item[] Information about disk usage.
\end{description}

\item[] {\sc Remote Help}
\begin{description}
\item[] A list of available server functions is displayed.
\end{description}

\item[] {\sc Remote Host} [command]
\begin{description}
\item[] The given command is passed to the server's host command processor,
and the resulting output is displayed on your screen. Do not use for
interactive commands.
\end{description}

\item[] {\sc Remote kermit} [command]
\begin{description}
\item[] The given command, which is expressed in the server \kermit's own
interactive-mode command syntax, is passed to the server for
execution. This is useful for changing settings, logging, and other
functions\footnote{Few existing \kermits\ can implement this command}.
\end{description}

\item[] {\sc Remote Run} program-name [command-line-argument]
\begin{description}
\item[] The remote \kermit\ is asked to run the indicated program with the
indicated command line; the program's terminal output is sent back to your
screen.
\end{description}

\item[] {\sc Remote Program} [command]
\begin{description}
\item[] The command is sent to the program started by most recent
{\sc Remote Run} program, and the program's response is displayed on the
screen.  If no command is given, a newline character is sent.
\end{description}

\item[] {\sc Remote Type} filespec
\begin{description}
\item[] The contents of the specified file is displayed on your screen.
\end{description}

\end{description}

\section{Local}

\underline{Syntax}: {\sc Local} command

\medskip
\noindent It executes the specified command on the local system.
These commands provide some local file management capability without
having to leave the \kermit\ program, which is particularly useful on
microcomputers.  The {\sc Local} prefix for these commands can be omitted.

\begin{description}
\item[~~~] {\sc Cwd} [directory]
\begin{description}
\item[] ``Change Working Directory'' to the specified directory.
\end{description}

\item[~~~] {\sc Delete} filespec
\begin{description}
\item[] Delete the specified file or files.
\end{description}

\item[~~~] {\sc Directory} [filespec]
\begin{description}
\item[] Provide a directory listing of the specified files.
\end{description}

\item[~~~] {\sc Space}
\begin{description}
\item[] Display local disk usage and/or free space.
\end{description}

\item[~~~] {\sc Run} command [operands]
\begin{description}
\item[] Run the indicated program with the supplied command-line operands.
\end{description}

\item[~~~] {\sc Push}
\begin{description}
\item[] Invoke the local system command interpreter so that it
can return (or ``pop'' or ``exit'') back to \kermit.
\end{description}

\end{description}

\noindent Some \kermit\ programs may provide commands for these or other
functions in the syntax of their own system.

\section{Connect (Local Only)}

\underline{Syntax}: {\sc Connect}

\medskip
\noindent Make  a  ``virtual  terminal''  {\sc Connect}ion to the remote
system. To ``escape''
from a virtual terminal {\sc Connect}ion, type \kermit's  escape character
(e.g. {\escape}),  followed  by one of the single character ``commands''
listed below:

\begin{description}
\item[~~~~{\sc C}] Close the {\sc Connect}ion and return to the local \kermit.
\item[~~~~{\sc S}] Show status of the {\sc Connect}ion.
\item[~~~~{\sc B}] {\sc Send} a BREAK signal.
\item[~~~~{\sc 0}] (zero) {\sc Send} a NUL (ASCII 0) character.
\item[~~~~{\sc D}] Drop the line, hangup the modem.
\item[~~~~{\sc P}] Push to the local system command processor without
breaking  the  connection.
\item[~~~~{\sc Q}] Quit logging session transcript.
\item[~~~~{\sc R}] Resume logging session transcript.
\item[~~~~{\sc ?~}] List all the possible single-character arguments.
\item[~~~~{\escape}] \escape (or whatever you have {\sc Set} the escape
character to
be). Typing the escape character twice sends one copy of it to  the
{\sc Connect}ed host.
\end{description}

\section{Help}

\underline{Syntax}: {\sc Help}

\medskip
\noindent Type a summary of \kermit\ commands and what they do.

\section{?}

Typed almost anywhere within a \kermit\ command:  List the commands,
options, or operands that are possible at this point.  This command may or
may  not require a carriage return, depending on the host operating system.

\section{Take}

\underline{Syntax}: {\sc Take} filespec

\medskip
\noindent Execute \kermit\ commands from the specified file.  The file may
contain any valid \kermit\ commands, including other {\sc Take} commands.

\section{Exit, Quit}

\underline{Syntax}: {\sc Exit} or {\sc Quit}

\medskip
\noindent Exit from \kermit\ back to the host operating system.

\section{Set}

\underline{Syntax}: {\sc Set} parameter [option] [value]

\medskip
\noindent Establish  or  modify  various parameters for file transfer or
terminal connection.

Each \kermit\ program has its own pre{\sc Set}
``default'' values for communication parameters.
You can examine their values with the {\sc Show} command;
the {\sc Set} command is provided to allow you to change them .

Most of these parameters are of no great concern except under unusual
conditions. Three of them, however, are of great importance in all
circumstances and must be correctly set. They are Baud-Rate,
Parity and Port. Of particular importance is that both \kermits\ have
the same parity setting and that this is consistent with the operating
systems in use.

\noindent In general, the following parameters may be {\sc Set}:

\medskip
\begin{tabular}{rl}
{\sc Baud-Rate} & {\sc Set} the speed of the current communications port \\
{\sc Block-Check} & Packet transmission error detection method           \\
{\sc Debugging} & Mode or log file                                       \\
{\sc Delay} & How long to wait before starting to Send                   \\
{\sc Duplex} & For terminal connection, full (remote echo) or half (local
echo) \\
{\sc Escape} & Character for terminal Connection                         \\
{\sc File} & For {\sc Set}ting file parameters like name conversion and byte
size \\
{\sc Flow-Control} & Selecting flow control method, like XON/XOFF        \\
{\sc Handshake} & For turning around half duplex communication line      \\
{\sc IBM} & {\sc Set} things up for communicating with an IBM mainframe  \\
{\sc Incomplete} & What to do with an incomplete file                    \\
{\sc Line} & Terminal line to use for terminal connection or file
transfer \\
{\sc Modem} & Modem type or characteristics                              \\
{\sc Parity} & Character parity to use                                   \\
{\sc Port} & For switching communication ports                           \\
{\sc Prompt} & For changing the program's command prompt                 \\
{\sc Receive} & Various parameters for receiving files                   \\
{\sc Retry} & How many times to retry a packet before giving up          \\
{\sc Send} & Various parameters for sending files                        \\
{\sc Timer} & Enable/disable timeouts                                    \\
\end{tabular}

\medskip

\subsection{The fundamental {\sc Set} commands}

Of all the parameters available in the {\sc Set} command, listed in the
previous section, the most important ones will be now discussed.

\subsubsection{Set Baud-Rate}

\underline{Syntax}: {\sc Set Speed} [Baud Rate]

\medskip
\noindent {\sc Set}  or  change  the  baud rate (i.e. the transmission speed in
bits per second) on the currently selected communications device.  Ten bits per
second  is  equivalent to one character per second; 300 baud = 30 cps.  The way
of specifying the baud rate varies from system to system.

\noindent Common values are 300, 1200, 2400, 4800, 9600.

\subsubsection{Set Port}

\underline{Syntax}: {\sc Set Port} terminal-designator

\medskip
\noindent Specify  the communications port for file transfer or Connect.
This command is found on microcomputer \kermits\ that run in ``local'' mode.
{\sc Set Port} does  not
change  the  remote/local  status but simply selects a different port for local
operation.

\subsubsection{Set Parity}

\underline{Syntax}: {\sc Set Parity} (EVEN, ODD, MARK, SPACE, NONE)

\medskip
Parity is a technique used by communications equipment for detecting
errors on a per-character basis; the ``8th bit'' of each character acts
as a check bit for the other seven bits.  \kermit\ uses block checks to
detect errors on a per-packet basis, and it does not use character
parity.  However, some systems that \kermit\ runs on, or equipment
through which these systems communicate, may be using character parity.
If \kermit\ does not know about this, arriving data will have been
modified and the block check will appear to be wrong, and packets will
be rejected.  If parity is being used on the communication line, you
must inform both Kermits, so the desired parity can be added to outgoing
characters, and stripped from incoming ones.  {\sc Set Parity} should be
used for communicating with hosts that require character parity (IBM
mainframes are typical examples) or through devices or networks (like
GTE TELENET) that add parity to characters that pass through them.  Both
\kermits\ should be {\sc Set} to the same parity.  The specified parity
is used both for terminal connection ({\sc Connect}) and file transfer
({\sc Send, Receive, Get}).

\medskip
\noindent The choices for {\sc Set Parity} are:

\medskip
\begin{tabular}{rl}
\underline{NONE} & (the default) eight data bits and no parity bit        \\
\underline{EVEN} & seven data bits with the parity bit {\sc Set}  to  make \\
& the  overall parity even \\
\underline{ODD} & seven data bits with the parity bit {\sc Set} to make \\
& the overall parity odd \\
\underline{MARK} & seven data bits with the parity bit {\sc Set} to one \\
\underline{SPACE} & seven data bits with the parity bit {\sc Set} to zero
\end {tabular}

\medskip
\noindent If you have {\sc Set Parity} to \underline{ODD}, \underline{EVEN},
\underline{MARK}, or \underline{SPACE}, then
advanced versions  of
\kermit\   will   request   that   binary   files   will   be  transferred
using 8th-bit-prefixing\footnote{Not  all implementations of \kermit\ have
this option.}.
If \underline{NONE} is specified, 8th-bit-prefixing will not be
requested: in fact it means that no parity processing is done, and the 8th
bit of each character can be used for data when transmitting binary files.

\subsubsection{Set Duplex}

\underline{Syntax}: {\sc Set Duplex} (FULL, HALF)

\medskip
\noindent For  use  when connected to a remote system.  The keyword choices
are \underline{FULL} and \underline{HALF}.  \underline{FULL} means the
remote system echoes the characters you type, HALF  means
the  local system echoes them.  \underline{FULL} is the default, and is used
by most hosts.
\underline{HALF} is necessary when connecting to IBM  mainframes.    Half
duplex  is  also called ``local echo''.

\subsubsection{Set File}

\underline{Syntax}: {\sc Set File} parameter value

\medskip
\noindent Establish  file-related  parameters.
The actual parameters you can
specify in this command will vary from system to system, and you should consult
the  documentation  for your particular version of \kermit.  Some examples would
be file type (text or binary), end-of-file detection method (on
microcomputers) and file naming conversion option.

{\bf This can be a very important command if you intend to  transfer
binary  files, but is normally unecessary for transmitting textual files}.

\subsubsection{Set Line}

\underline{Syntax}: {\sc Set Line} [terminal-designator]

\medskip
\noindent Specify the terminal line to use for file transfer or Connect.
This command is found on mainframe \kermits, which normally run in ``remote
mode'' using their own controlling  terminal  for  file transfer.  The
specification of a separate line puts the
program in ``local mode''.  If no line is specified, revert  to  the  job's
controlling terminal, i.e. go back to ``remote mode''.

\section{Define}

\underline{Syntax}: {\sc Define} macroname [Set-parameters]

\medskip
\noindent Define a ``Set macro'' to  allow  convenient  association  of  one
or  more Set
parameters  with  a  mnemonic keyword of your choice.  The Set parameters are a
list of one or more Set options, separated by commas.

\section{Show}

\underline{Syntax}: {\sc Show} [parameter]

\medskip
\noindent Display the values of Set options. In some implementations, this
command is substituted by {\sc Status}.

\section{Statistics}

\underline{Syntax}: {\sc Statistics}

\medskip
\noindent Give  statistics  about the most recent file transfer, such as the
total number of characters transmitted, the effective baud rate, and so forth.

\section{Transmit}

\underline{Syntax}: {\sc Transmit} filespec

\medskip
\noindent Send the contents of the specified file to the  other  system
``bare'',  without
protocol,  packets,  error checking, or retransmission.  This command is useful
for sending  files  to systems  that don't have \kermit.
When receiving a file, the
target system would normally be running a text editor in text collection mode.

\chapter{When things go wrong}

\section{Basic connection problems}

If you have a version of \kermit\ on your microcomputer, but the {\sc
Connect} command doesn't seem to work at all, please make sure all the
required physical connections have been made.  Make sure that the port
is {\sc Set} to the right communication speed and baud rate.  Check if
the other communication line parameters, like parity, bits per
character, handshake, and flow control are {\sc Set} correctly.

If all settings and connections appear to be correct, and
communication still does not take place, the fault may be in your
modem.  Internal modems are  not  recommended  for  use  with \kermit\, because
 many microcomputer \kermit\ programs  are
written  to  control the communication hardware explicitly; internal modems can
interfere with that control.
But even external modems can cause trouble. Check the wiring on the
interface cable; this may take a guru.

\section{The Transfer doesn't start}

If \kermit 's terminal emulation seems to work correctly, but a file
transfer does not start at all, then something in the communication path
is probably interfering with the packet data.  Normally \kermit\ expects to
have full control of the communication port.  However, some
communications equipment might interfere with the \kermit\ file transfer
protocol in various ways, like parity mismatches\footnote{See the {\sc Set
Parity} command description.}
or communication processors echoing their input
and causing therefore confusion among packets going back and forth.  All
these problems may be easily solved\footnote{See \kermit\ {\sl User Guide}
for details.}.

\section{Special characters}

Some devices in the communication path may interpret certain characters
in the data stream as commands rather than as data to be passed them
along to the other side (it is the problem of ``special characters'').
Usually such equipment interferes only with the transmission of ASCII
control characters.

\section{The transfer starts but then gets interrupted}

A transfer in progress can become stuck for various reasons, such as a
hung micro (due, f.i.\ to power fluctuations), a broken connection, the
disk in which the files are sent being full (although usually \kermit\
informs you of this), terminal messages that could be mixed with your
terminal packet data (even if most \kermit\ programs attempt to disable
such intrusive messages automatically), transmission delays, noise
corruption, host errors\footnote{See the \kermit\ {\sl User Guide} for both
a more detailed description of these problems and an indication of the
possible solutions.}.

\section{File is garbage}

There are certain conditions under which \kermit\ can believe  it
transferred  a file  correctly when, in fact, it did not.
However, these difficulties usually show up only when sending
binary files.  Textual files should normally present no problem between any two
\kermit\ programs.

\section{Junk after end of file}

When transferring a text file from a microcomputer to a mainframe,
sometimes extraneous characters at the end of the file after it arrives
on the target system show up.  This is because many microcomputers don't
have a consistent way of indicating the end of a file.  To circumvent
this problem, most microcomputer \kermits\ have commands like {\sc Set
File Ascii}, {\sc Set File Text} or {\sc Set eof ctrl-Z} to instruct \kermit\
to choose the appropriate format.

\appendix

\chapter{References}

\begin{enumerate}
\item {One of the most complete sources of material, from which this
introductory notes have been consistently taken, is}\\
\noindent {\bf Kermit User Guide}{, Sixth Edition, Revision 1, Frank da Cruz
ed., Columbia University Center for Computing activities -New York (1985);}

\item{The protocol is specified sufficiently to allow new \kermit\ programs to
be written in}\\
\noindent {\bf Kermit Protocol Manual}{, Sixth Edition, Frank da Cruz, Columbia
University Center for Computing Activities, New York (1986);}

\item{A review article on the subject may be found in}\\
\noindent {\bf Kermit: A File Transfer Protocol for Universities}{, Frank
da Cruz and Bill Catchings, Byte Magazine, June-July 1984;}

\item{A very complete document on \kermit\ for any level users, rich of
references, is constituted by the book}\\
\noindent {\bf Kermit - A File Transfer Protocol}{, Frank da Cruz, Digital
Press, Bedford MA (1986).}
\end{enumerate}

\chapter{Kermit Implementations}

\kermit\ has been written for a wide variety of systems, both mainframes
and microcomputers.  \kermit\ is not written in a portable language;
rather, each implementation is written in a language suited for the
particular machine.  The specification, given in the {\sl Kermit Protocol
Manual}, is quite general and allows implementation on almost any
machine.

Here's a brief table summarizing a few of the \kermit\ implementations.
This  list is constantly growing.

\medskip
\noindent {\bf Versions for ``Portable Operating Systems'': OS; Language
(Machines)}

\begin{description}
\item[] CP/M-80; ASM (Kaypro, H/Z-89, H/Z-100, Osborne, DEC VT180)
\item[] CP/M-86; ASM86 (DEC Rainbow, NEC APC)
\item[] MS-DOS; MASM (IBM PC,XT,AT, DEC Rainbow, HP-150, NEC APC)
\item[] MUMPS (PDP-11)
\item[] Software Tools; Ratfor (HP3000, Sperry-Univac 1100)
\item[] UCSD p-System; Pascal (IBM PC, Terak, HP98x6, Pascal Microengine)
\item[] UNIX v7,4.xBSD,Sys III/V,Venix,Xenix,PC/IX; C (VAX, PDP-11, SUN)
\end{description}
\vfil
\eject

\noindent {\bf Host Versions: Machine (OS; Language)}

\nobreak

\begin{description}
\item[] Burroughs B6800 (Algol)
\item[] Cray-1, Cray-XMP (CTSS; Fortran-77)
\item[] CDC Cyber 170 (NOS, NOS/BE; Fortran-77)
\item[] Data General Nova (RDOS; Fortran-5)
\item[] Data General Eclipse (AOS; Fortran-5), MV Series (AOS/VS; Pascal)
\item[] DEC PDP-11, VAX-11, MICRO-VAX, SYSTEM-10, SYSTEM-11)
\item[] Harris 800 (VOS; Pascal)
\item[] Honeywell (MULTICS; PL/I), DPS-6,8 (GCOS; C)
\item[] Hewlett-Packard 1000 (RTE-6/VM; Fortran), HP3000 (MPE; SPL or Ratfor)
\item[] IBM 370 Series (VM/CMS, MVS/TSO, MVS/GUTS, MUSIC, MTS; Assembler)
\item[] Perkin Elmer 3200 Series (OS/32; Fortran)
\item[] PRIME (PRIMOS; PL/P)
\item[] Tandem (Nonstop; TAL)
\item[] Sperry/Univac-1100 (EXEC; Assembler or Ratfor or Pascal)
\end{description}

\noindent {\bf PC Versions: Machine (OS; Language)}

\begin{description}
\item[] Alpha Micro 68000 (Assembler)
\item[] Apollo (Aegis; Fortran or Pascal)
\item[] Apple II 6502 (Apple DOS; DEC-10/20 CROSS or Apple Assembler)
\item[] Apple Macintosh (SUMACC C)
\item[] Atari (DOS; Action!)
\item[] Commodore 64 (DEC-10/20 CROSS or FORTH)
\item[] DEC Pro-300 Series (P/OS; Bliss-16 or Macro-11), (Pro/RT; Macro),
(Venix; C)
\item[] Intel Development System (ISIS; PL/M)
\item[] Perq (Pascal)
\item[] TRS80 I, III, Model 4 (TRSDOS; ASM)
\item[] TRS-80 Color Computer (Radio Shack DOS)
\end{description}

\chapter{VAX-VMS Kermit Implementation}

In this Appendix a list of the commands for the \kermit-32
implementation is presented.

\medskip
\begin{tabular}{rl}
\verb+@+ & synonym for ``take'' \\
{\sc Bye} & to remote server \\
{\sc Connect} & as terminal to remote system \\
{\sc Exit} &  from \kermit-32 \\
{\sc Finish} &  Shut down remote server \\
{\sc Get} &  remote files from server \\
{\sc Help} &  with \kermit-32 \\
{\sc Local} &  prefix for local file management commands \\
{\sc Log} &  remote terminal session \\
{\sc Logout} &  remote server \\
{\sc Push} &  to DCL command level \\
{\sc Quit} &  from \kermit-32 \\
{\sc Receive} &  files from remote \kermit \\
{\sc Remote} &  prefix for remote file management commands \\
{\sc Send} &  files to remote \kermit \\
{\sc Server} &  mode of remote operation \\
{\sc Set} &  various parameters \\
{\sc Show} &  various parameters \\
{\sc Statistics} &  about most recent file transfer \\
{\sc Take} &  \kermit-32 commands from a file
\end{tabular}

\medskip
\noindent In particular, the possible options for the {\sc Set} command are the
following:

\nobreak

\medskip

\begin{tabular}{rl}
{\sc Block\_check} &  Packet transmission error detection method \\
{\sc Debugging} &  Record or display state transitions or packets \\
{\sc Delay} &  How long to wait before starting to send \\
{\sc Escape} &  Character for terminal connection \\
{\sc File} &  For setting file parameters like file type \\
{\sc Handshake} &  For establishing half duplex line turnaround
handshake \\
{\sc Ibm\_mode} &  For communicating with an IBM mainframe \\
{\sc Incomplete\_file} &  What to do with an incomplete file \\
{\sc Line} &  Terminal line to use for file transfer or {\sc Connect} \\
{\sc Local\_echo} &  For terminal connection, ON or OFF \\
{\sc Message} &  The type of typeout to be done during transfers \\
{\sc Parity} &  Character parity to use \\
{\sc Prompt} &  Change the program's command prompt \\
{\sc Receive} &  Various parameters for receiving files \\
{\sc Repeat\_quote} & Character to use for repeat compression \\
{\sc Retry} &  How many times to retry a packet before giving up \\
{\sc Send} &  Various parameters for sending files
\end{tabular}

\chapter{Unix Kermit Implementation}

\noindent Here is a brief list of C-\kermit\ interactive commands.

\medskip
\begin{tabular}{rl}
{\sc !} &  Execute a Unix shell command, or start a shell \\
{\sc Bye} &  Terminate and log out a remote \kermit\ server \\
{\sc Close} &  Close a log file \\
{\sc Connect} &  Establish a terminal connection to a remote system \\
{\sc Cwd} &  Change Working Directory \\
{\sc Dial} &  Dial a telephone number \\
{\sc Directory} &  Display a directory listing \\
{\sc Echo} &  Display arguments literally \\
{\sc Exit} &  Exit from the program, closing any open logs \\
{\sc Finish} &  Instruct a remote \kermit\ server to exit, but not log out \\
{\sc Get} &  Get files from a remote \kermit\ server \\
{\sc Help} &  Display a help message for a given command \\
{\sc Log} &  Open a log file -- debugging, packet, session, transaction \\
{\sc Quit} &  Same as 'exit' \\
{\sc Receive} &  Passively wait for files to arrive \\
{\sc Remote} &  Issue file management commands to a remote \kermit\ server \\
{\sc Script} &  Execute a login script with a remote system \\
{\sc Send} &  Send files \\
{\sc Server} &  Begin server operation \\
{\sc Set} &  Set various parameters \\
{\sc Show} &  Display values of 'set' parameters \\
{\sc Space} &  Display current disk space usage \\
{\sc Statistics} &  Display statistics about most recent transaction \\
{\sc Take} &  Execute commands from a file
\end{tabular}

\medskip
\noindent The '{\sc Set}' parameters are:

\nobreak

\medskip
\begin{tabular}{rl}
{\sc Block-Check} &  Level of packet error detection \\
{\sc Delay} &  How long to wait before sending first packet \\
{\sc Duplex} &  Specify which side echoes during 'connect' \\
{\sc Escape-Character} &  Prefix for ``escape commands'' during 'connect' \\
{\sc File} &  Set various file parameters \\
{\sc Flow-Control} &  Communication line full-duplex flow control \\
{\sc Handshake} &  Communication line half-duplex turnaround character \\
{\sc Incomplete} &  Disposition for incompletely received files \\
{\sc Line} &  Communication line device name \\
{\sc Modem-Dialer} &  Type of modem-dialer on communication line \\
{\sc Parity} &  Communication line character parity \\
{\sc Prompt} &  Change the C-\kermit\ program's prompt \\
{\sc Receive} &  Parameters for inbound packets \\
{\sc Send} &  Parameters for outbound packets \\
{\sc Speed} &  Communication line speed
\end{tabular}

\medskip
\noindent The '{\sc Remote}' commands are:

\nobreak

\medskip
\begin{tabular}{rl}
{\sc Cwd} &  Change remote working directory \\
{\sc Delete} &  Delete remote files \\
{\sc Directory} &  Display a listing of remote file names \\
{\sc Help} &  Request help from a remote server \\
{\sc Host} &  Issue a command to the remote host in its own command
language \\
{\sc Space} &  Display current disk space usage on remote system \\
{\sc Type} &  Display a remote file on your screen \\
{\sc Who} &  Display who's logged in, or get information about a user
\end{tabular}

\chapter{MS-DOS Kermit Implementation}

\medskip
\noindent MS-DOS \kermit\ implements a large subset of  the  commands  of
the ``ideal'' \kermit. Here's a brief summary.

\medskip
\begin{tabular}{rl}
{\sc Bye} &  to remote server \\
{\sc Clear} &  key redefinitions \\
{\sc Close} &  log file and stop logging remote session \\
{\sc Connect} &  as terminal to remote system \\
{\sc Cwd} &  change local working directory \\
{\sc Define} &  macros of \kermit-MS commands \\
{\sc Delete} &  local files \\
{\sc Directory} &  listing of local files \\
{\sc Do} &  a macro expansion \\
{\sc Exit} &  from \kermit-MS \\
{\sc Finish} &  Shut down remote server \\
{\sc Get} &  remote files from server \\
{\sc Help} &  about \kermit-MS \\
{\sc Local} &  prefix for local file management commands \\
{\sc Log} &  remote terminal session \\
{\sc Logout} &  remote server \\
{\sc Push} &  to MS-DOS command level \\
{\sc Quit} &  from \kermit-MS \\
{\sc Receive} &  files from remote \kermit \\
{\sc Remote} &  prefix for remote file management commands \\
{\sc Run} &  an MS-DOS program \\
{\sc Send} &  files to remote \kermit \\
{\sc Server} &  mode of remote operation \\
{\sc Set} &  various parameters \\
{\sc Show} &  various parameters \\
{\sc Space} &  inquiry \\
{\sc Status} &  inquiry \\
{\sc Take} &  commands from file \\
{\sc Type} &  display a local file \\
{\sc Version} &  display \kermit-MS program version number
\end{tabular}

\medskip
\noindent The {\sc Set} commands available in \kermit-MS are the
following:

\nobreak

\medskip
\begin{tabular}{rl}
{\sc Baud} &  Communications port line speed \\
{\sc Bell} &  Whether to beep at the end of a transaction \\
{\sc Block-Check-Type} &  Level of error checking for file transfer \\
{\sc Debug} &  Display packet contents during file transfer \\
{\sc Default-Disk} &  Default disk drive for file i/o \\
{\sc Destination} &  Default destination device for incoming files \\
{\sc End-Of-Line} &  Packet terminator \\
{\sc Eof} &  Method for determining or marking end of file \\
{\sc Escape} &  Escape character for {\sc Connect} \\
{\sc Flow-Control} &  Enable or disable XON/XOFF \\
{\sc Handshake} &  Half-duplex line turnaround option \\
{\sc Incomplete} &  What to do with an incompletely received file \\
{\sc Key} &  Specify key redefinitions, or ``keystroke macros'' \\
{\sc Local-Echo} &  Specify which host does the echoing during {\sc Connect} \\
{\sc Mode-Line} &  Whether to display a mode line in terminal emulation \\
{\sc Parity} &  Character parity to use \\
{\sc Port} &  Select a communications port \\
{\sc Prompt} &  Change the {\tt Kermit-MS}$\rangle$ prompt to something else \\
{\sc Receive} &  Request remote \kermit\ to use specified parameters \\
{\sc Remote} &  For running \kermit-MS interactively from back port \\
{\sc Send} &  Use the specified parameters during file transfer \\
{\sc Take-Echo} &  Control echoing of commands from {\sc Take} files \\
{\sc Terminal} & Various terminal settings and parameters \\
{\sc Timer} &  Enable/disable timeouts during file transfer \\
{\sc Warning} &  Specify how to handle filename collisions
\end{tabular}

\end{document}
