Columbia Kermit/kermit.zip/protocol/kuser.mss

Text File | 2020-01-01 | 119KB | 2,536 lines

@Comment(-*-SCRIBE-*-)
@Comment(SCRIBE Text Formatter Input for the Kermit User Guide)

@Make<Manual>
@Comment(Use /draft:F on command line to produce .LPT file w/cc in column 1)

@Style(Date="March 1952")

@case(device,postscript="@LibraryFile<Mathematics10>")

@String<Ellips="...">

@Style<Justification On, Hyphenation On, WidestBlank 1.4, Spacing 1,
        Spread 1, Indent 0, HyphenBreak Off, SingleSided, PrintBlankPages Yes>
@Use<Hyphendic="kuser.hyp">

@Modify<IndexEnv,Boxed,
    Columns 2,ColumnMargin 0.4inch,LineWidth 3.35inch>

@Comment(Set desired spacing around various environments)

@Modify<Quotation,Indentation 0, Above 1, Below 1, Spacing 1>
@Modify<Example, Above 1, Below 1, Blanklines Hinge>
@Modify<Verbatim, Leftmargin 0>
@Modify<Itemize, Above 1, Below 1, Spacing 1, Spread 1>
@Modify<Enumerate, Above 1, Below 1, Spacing 1, Spread 1>
@Modify<Description, Above 1, Below 1, Spacing 1>

@Define<MD,Use Display>
@Define<Q,FaceCode R>
@Define<QQ,FaceCode R,AfterEntry=["],BeforeExit=["]>
@Define<SubH,Use Display,FaceCode R,Above 1.6,Below 1,need 6>
@Define<SubU,Use UX,FaceCode R,Above 1.6,Below 1,need 6>
@define<xx,use b>
@define<yy,use i>

@Comment(Printing Device Dependencies)

@Case<Device,
 LPT="@use(Auxfile='KERMLP.AUX')
    @Case[Draft,F=`@Style(CarriageControl=FORTRAN)']
    @Style(linewidth 72)
    @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>",
 Printronix="@use(AuxFile='KERMPX.AUX')
    @Case[Draft,F=`@Style(CarriageControl=FORTRAN)']
    @Style(LineWidth 74, PaperLength 11 inches,BottomMargin 5 spacings)",
 PagedFile="@use(AuxFile='KERMPF.AUX')
    @Style(LineWidth 79, PaperLength 10.8 inches)
    @Style(TopMargin 3 spacings,BottomMargin 6 Spacings)
    @Modify(Example,Leftmargin +2)",
 Diablo="@Use(Auxfile='KERDIA.AUX')
    @TypeWheel(Titan 10)
    @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>",
 Postscript="@Use(Auxfile='KERPS.AUX')
    @Style<Doublesided>
    @Style<Fontscale 10>
    @Define<MD,Use Mathdisplay>
    @String<Ellips='@Math(@Ldots)'>
    @Define<xx,use b,Size 12>
    @Define<yy,use i,Size 10>
    @Define<Q,FaceCode T>
    @Define(QQ,FaceCode T,AfterEntry=[@r<``>],BeforeExit=[@r<''>])
    @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>
    @Modify<Quotation,Size +0>
    @Modify<Itemize,Spread 0.8>",
 Imprint10="@Use(AuxFile='KERIMP.AUX')
    @Define<Q,FaceCode U>
    @Define(QQ,FaceCode U,AfterEntry=[@r<``>],BeforeExit=[@r<''>])
    @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>
    @Modify<Insert,Spacing 1>
    @Modify<Verbatim,FaceCode U>
    @Modify<Example,FaceCode U,spacing 1.2>
    @Modify<Itemize,Spread 0.8>
    @Style<FontFamily SmallRoman12,Spacing 1.6,SingleSided>",
 Imagen300="@Use(AuxFile='KERIMP.AUX')
    @Define<Q,FaceCode U>
    @Define(QQ,FaceCode U,AfterEntry=[@r<``>],BeforeExit=[@r<''>])
    @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>
    @Modify<Insert,Spacing 1>
    @Modify<Verbatim,FaceCode U>
    @Modify<Example,FaceCode U,spacing 1.2>
    @Modify<Itemize,Spread 0.8>
    @Style<FontFamily SmallRoman12,Spacing 1.6,SingleSided>",
 X9700="@Use<AuxFile='KERMX9.AUX'>
    @Style<FontFamily Univers10, DoubleSided, Spacing 0.9, Spread 0.8>
    @Style<Scriptpush No>
    @define<xx,use b,font bodyfont>
    @define<yy,use i,font bodyfont>
    @Define<Q,FaceCode U>
    @Define(QQ,FaceCode U,AfterEntry=[@r<``>],BeforeExit=[@r<''>])
    @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>
    @Modify<Description,Spacing 0.8,Spread 0.75>
    @Modify<Quotation,Spacing 0.8,Spread 0.75>
    @Modify<Enumerate,Spacing 0.8,Spread 0.75>
    @Modify(Verbatim,Spacing 0.8,Spread 0.75,FaceCode U)
    @Modify<Example,FaceCode U, Spacing 1.1>
    @Modify[Itemize, Numbered < @,- >, Spacing 0.8, Spread 0.5]",
 X2700="@Use<AuxFile='KERMX2.AUX'>
    @Style<FontFamily Times, DoubleSided On, Spacing 1, Spread 0.8>
    @Style<Scriptpush No, WidowAction Force>
    @define<xx,use b,font bodyfont>
    @define<yy,use i,font bodyfont>
    @Define<Q,FaceCode U>
    @Define(QQ,FaceCode U,AfterEntry=[@r<``>],BeforeExit=[@r<''>])}
    @comment{NYU specific - [at]Define(QQ,FaceCode U,
    AfterEntry=[[at]Amr10<``>],BeforeExit=[[at]Amr10<''>])}
    @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>
    @Modify<Description,Spacing 1,Spread 0.75>
    @Modify<Quotation,Spacing 1,Spread 0.75>
    @Modify<Enumerate,Spacing 1,Spread 0.75>
    @Modify(Verbatim,Spacing 1,Spread 0.75,FaceCode U)
    @Modify<Example,FaceCode U, Spacing 1.1>
    @Modify[Itemize, Numbered < @,- >, Spacing 1, Spread 0.5]"
 >
@Comment(Set spacing and paging requirements for chapter & section headings)

@Modify(Hdx,Above 2,Below 1,Need 8)
@Modify(Hd0,Above 2,Below 1,Need 8)
@Modify(Hd2,Above 2,Below 1,Need 8)
@Modify(Hd3,Above 2,Below 1,Need 8)
@Modify(Hd4,Above 2,Below 1,Need 8)
@Modify<Heading, Above 2, Need 8>
@Modify<Subheading, Above 1.5, Need 6>

@Pageheading<>
@Begin(TitlePage,Initialize "@BlankSpace(2.4inches)",sink 0)
@MajorHeading(KERMIT USER GUIDE)

@i<Seventh Edition>



Christine Gianone, Editor

Columbia University Center for Computing Activities
New York, New York  10027


May 26, 1988











Copyright (C) 1981,1988
Trustees of Columbia University in the City of New York

@i<Permission is granted to any individual or institution to use, copy,
or redistribute this document so long as it is not sold for profit, and
provided this copyright notice is retained.>

@case[device, x9700 "@blankpage(1)"]@Comment{Duplex Kludge}
@case[device, x2700 "@blankpage(1)"]@Comment{Duplex Kludge}
@case[device, imprint10 "@blankpage(1)"]@Comment{Duplex Kludge}
@end<titlepage>
@PageHeading(Odd,Immediate,
    Left="@xx<@Value[SectionNumber]. @Value[SectionTitle]>",
    Right="@yy<Page @ref(page)>",
    Line="@bar()@blankspace(2)")
@PageHeading(Even,
    Left="@yy<Page @ref(page)>",
       Right="@xx<Kermit User Guide: @Title(Chapter) (@Value[SectionNumber])>",
    Line="@bar()@blankspace(2)")
@set(page=1)
@PrefaceSection<PREFACE>

@i<Kermit> is the name of a protocol for transferring files from one computer
to another over ordinary asynchronous terminal connections.  Kermit programs
have been written for many different computers, and in general any two
computers that have Kermit programs can exchange sequential files correctly and
completely.  This manual gives a brief and general overview of what Kermit is
and how to use it, but consists mostly of detailed instructions for use and
installation of specific Kermit programs.

For a more detailed introduction to Kermit, complete with illustrations,
diagrams, and tutorials, consult the book @i<Kermit, A File Transfer Protocol>,
by Frank @w<da Cruz>, Digital Press, Bedford MA (1987), ISBN @w<0-932376-88-6>,
DEC order number @w<EY-6705E-DP> (phone [phone]).  The Kermit book
describes Kermit in detail, from the points of view of the beginner, the user,
the computer professional who must install Kermit programs or support their
use, and the programmer who wishes to write new Kermit implementations.  Also
included are general introductions to computers, data communications, and file
organization, plus a detailed troubleshooting guide, bootstrapping hints, and
various appendices and tables.  The latter half of the book is taken up by a
complete description of the Kermit file transfer protocol, with programming
examples in the C language, plus some analysis and comparisons of Kermit with
other popular protocols such as Xmodem.

The seventh edition of the @i<Kermit User Guide> (May 1988) includes
chapters on new releases of most major Kermit programs, including MS-DOS Kermit
2.30, VAX/VMS Kermit 3.3, Portable IBM Mainframe Kermit 4.0, Unix Kermit 4E,
Macintosh Kermit, CP/M-80 Kermit 4.09, plus a new chapter on PDP-11 Kermit.

@Heading<History and Acknowledgements>

The Kermit file transfer protocol was designed at the Columbia University
Center for Computing Activities (CUCCA) in 1981-82 by Bill Catchings and Frank
@w<da@ Cruz>.  Bill wrote the first two programs, one for the DECSYSTEM-20 and
one for a CP/M-80 microcomputer.

The initial objective was to allow users of our DEC-20 and IBM 370 timesharing
systems to archive their files on microcomputer floppy disks.  The design owes
much to the ANSI and ISO/OSI models, and some ideas were borrowed from similar
projects at Stanford University and the University of Utah.  The protocol was
designed to accommodate the "sensitive" communications front end of the
full-@|duplex DEC-20 system as well as the peculiarities of half-@|duplex IBM
mainframe linemode communications.  The protocol was soon implemented
successfully on our IBM mainframe systems under VM/CMS by Daphne Tzoar of
CUCCA.

Meanwhile it was becoming apparent that Kermit was useful for more than just
file archiving; IBM PCs were beginning to appear in the offices and
departments, and there arose a general need for file transfer among all our
systems, as well as a need to use the IBM PCs as terminals.  Daphne soon had
prepared an IBM PC implementation.

After our initial success with Kermit, we presented it at conferences of user
groups like DECUS and SHARE, and began to get requests for it from other sites.
Since we had written down a description of the protocol, some sites wrote their
own implementations for new computers, or adapted one of our implementations to
run on additional systems, and sent back these new versions to us so that we
could share them with others.  In this way, Kermit has grown to support nearly
300 different machines and operating systems; it has been sent on magnetic tape
or diskette from Columbia University to nearly ten thousand sites all over the
world, and has reached many thousands more through various user groups and
networks.

Thanks to the hundreds of individuals and institutions who have contributed
to the Kermit storehouse over the years.

The Kermit protocol was named after Kermit the Frog, star of the television
series @i<THE MUPPET SHOW>; the name Kermit is used by permission of Henson
Associates, Inc., New York.

@Heading<Disclaimer>

Neither Columbia University, nor the editor, nor the authors of the individual
chapters, nor any individual or institution contributing Kermit programs or
documentation to the Columbia University Kermit Distribution, acknowledge any
liability for any claims arising from use or misuse of Kermit programs or for
inaccuracies in the documentation or bugs in the programs.  Kermit programs are
produced on a voluntary basis and contributed freely for public use in the hope
that they will be useful, but without any kind of warranty or guarantee, or
any commitment to address or fix problems.  In practice, Kermit programs and
documentation are contributed in good faith, and will be supported on a
best-@|effort basis, time and other commitments permitting.

@Heading<Customizing This Manual>

Although the @i<Kermit User Guide> was produced at Columbia University, all
attempts have been made to keep it free of site-@|specific information.
However, due to the large number of Kermit implementations, descriptions of
each one would make the manual prohibitively thick.  Therefore, the manual is
sent from Columbia with specific documentation about a selection of systems.
Some of these descriptions may not be of interest at your site, while others
that are may be lacking.

Each site, upon receiving a Kermit tape, may decide which versions of Kermit
are important to it, and include the appropriate documentation in this manual.
This is most conveniently done if your site has the Scribe text formatting
system (from UNILOGIC Ltd in Pittsburgh PA, USA), with which this manual was
produced.  Scribe runs on a wide variety of systems.  There are also Scribe
subsets, such as Perfect Writer and Final Word, that run on various
microcomputers.  Many have asked why Scribe is used for Kermit manuals instead
of TeX.  The answer is simply that TeX can only produce output for typesetters,
not plain-text ASCII files, which are necessary for online documentation.

The system-specific parts of the Kermit User Guide are included with
"@q<@@INCLUDE>" statements at the end of the Scribe source file for this
manual, whose filename is @q<KUSER.MSS>.  You may add or delete @q<@@INCLUDE>
statements to suit your needs, and run the result through the text formatter to
produce a customized manual.  If you do this, you should include an indication
on the title page that the manual has been customized for your site.

Not all system-specific documentation is provided in @q<.MSS> (Scribe input)
format, since some Kermit contributors do not have Scribe at their sites.  In
that case, you will either have to add Scribe formatting commands, or else
enclose the whole subfile in @q<@@BEGIN(VERBATIM)...@@END(VERBATIM)> brackets
(and replace all atsigns (@q<@@>) in the text with double atsigns (@q<@@@@>)).

If you do not have SCRIBE, you may still use an editor to delete or add
sections to the finished documentation file, though the results will not be as
satisfactory -- the table of contents, index, cross references, and page
numbers will not be automatically adjusted.

If you are running a version of Kermit for which adequate documentation has not
been provided (after all, this is a distributed, volunteer effort!), please
feel free to write some, preferably in Scribe input format, and send it back to
Columbia so that others may benefit from it.  Likewise if you produce a new
implementation of Kermit.  If you don't know Scribe, you can use one of the
existing chapters as a model.

@Unnumbered<How To Get Kermit>

The Kermit software is free and available to all, source code and documentation
included, from a variety of sources.  For example, most universities are
connected to academic computer networks from which the Kermit files at Columbia
University can be reached.  The Kermit files are also available from many
user groups, dialup information or bulletin board services, diskette
reproduction services, and private volunteers.

Kermit software is not in the public domain.  The Kermit manuals and most
Kermit programs bear copyright notices to protect Columbia University and the
various contributors from having their work taken by others and sold as a
product, for profit.  This is not to say that the Kermit file transfer protocol
can never be included as a feature of a commercial product; the conditions
under which this may be done are spelled out in a flyer @i<POLICY ON COMMERCIAL
USE AND DISTRIBUTION OF KERMIT>.

Columbia University distributes Kermit programs by mail order on various
magnetic media (primarily 9-track reel-to-reel tape and certain kinds of
diskettes), charging a distribution fee to defray costs for media, printing,
postage, materials, labor, and computing resources.  This is not a software
license fee; no license is required.  To receive a current list of Kermit
implementations, the statement on commercial policy, and a Kermit order form,
write to:

@begin<format,leftmargin +4>
Kermit Distribution
Columbia University Center for Computing Activities
612 West 115th Street
New York, NY  10025
@end<format>

Everyone is free to copy and redistribute Kermit programs and documentation,
and is encouraged to do so, with the following stipulations: Kermit programs
should not be sold for commercial gain; credit should be given where it is due;
and new material should be sent back to Columbia University at the address
above so that we can maintain a definitive and comprehensive set of Kermit
implementations for further distribution.

Since new Kermit programs are added -- and old ones improved -- so frequently,
sites that use Kermit heavily are encouraged to contact Columbia for updates
two or three times a year for news.

@blankspace(4)
@Center(-- PLEASE USE KERMIT ONLY FOR PEACEFUL AND HUMANE PURPOSES --)

@Unnumbered<Organization of This Manual>

Chapter @ref<-using>, @i<How to Use Kermit>, describes the basics of text file
transfer, and shows some specific examples.  If you follow the examples but you
can't make a terminal connection or you can't transfer files successfully,
consult Chapter @ref<-wrong>, @i<When Things Go Wrong>.

If you expect to be a heavy user of Kermit, you should read Section
@ref<-commands>, @i<Kermit Commands>, which describes most of Kermit's features
and commands.  You may find that familiarity with the material in this
section will help you get past difficulties that can crop up when you are
making new kinds of connections or transferring unusual kinds of files.
You will also find descriptions of some advanced file management features
that have been omitted from the earlier sections.

The subsequent chapters describe selected popular Kermit programs in detail.
You should read the appropriate section for each system you expect to use; each
section describes the file naming conventions and other system features that
are important to Kermit users, and lists the Kermit commands for that system
mainly in terms of their differences from the "ideal" Kermit described in
section @ref<-commands>.

@Chapter<Introduction>

There is an ever-increasing need to move information from one computer to
another.  Information can be exchanged using magnetic media -- tapes or disks
-- or over networks.  Networks are expensive, and when your computer is not
connected to one (or to the right one), you must find other means to transfer
information.  In the early days of computing, magnetic media formats were
relatively standardized, but with the arrival of microcomputers things have
changed: most microcomputer users have no access to tapes, and disk formats
are incompatible between most microcomputer makes and models.  Even when
disk formats agree, the disk must be physically moved from one system to the
other in order for information to be exchanged -- the effort and delay can be
significant if the systems are widely separated.

The telecommunication line provides a cheap and widely available alternative to
networks and magnetic media.  Asynchronous telecommunication is the method used
by most terminals to connect to most computers.  When dedicated "hardwired"
connections, such as those found between a timesharing computer and its local
terminals, are not available, computer users can create their own dialup
connections with a telephone and a modem.

Most computers come equipped with asynchronous telecommunications interfaces,
or "serial ports", which allow them to act as, or communicate with, terminals.
The question is how to use the serial port to exchange data.  Fortunately, the
standards for connecting terminals to computers are almost universally
followed: connector configuration (DB-25 or DB-9), transmission signals (EIA
RS-232), a commonly accepted set of transmission speeds (baud rates), and a
convention for encoding characters in storage and during transmission (ASCII).
These standards provide the physical medium and the data format, but they do
not specify a process for exchanging data.

@Section<Why Kermit?>

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:
 @begin<enumerate>
@i<Noise> -- @Index<Noise> It is rarely safe to assume that there will be no
electrical interference on a line; any long or switched data communication line
will have occasional interference, or noise, which typically results in garbled
or extra characters.  Noise corrupts data, perhaps in subtle ways that might
not be noticed until it's too late.

@i<Synchronization> -- Data must not come in faster than the receiving machine
can handle it.  Although line speeds at the two ends of the connection must
match before communication can take place, the receiving machine might not be
able to process a steady stream of input at that speed.  Its central processor
may be too slow or too heavily loaded, its buffers too full or too small, or
its disk too slow.  The typical symptom of a timing problem is lost data; most
operating systems will simply discard incoming data they are not prepared to
receive.
@End(Enumerate)
 To prevent corruption of data and to synchronize communication, cooperating
computers can send special messages to one another along with the data.
Intermingling of control information with data together requires a set of rules
for distinguishing messages from data, and specifying what the messages are and
the actions associated with each message.  Such a set of rules is called a
@i(protocol).

@Index[Kermit Protocol] Kermit is a file transfer protocol.  It is specifically
designed for transfer of sequential files over ordinary telecommunication
lines.  Kermit is not necessarily better than other terminal-@|oriented file
transfer protocols but it is free, it is well documented, and it has been
implemented compatibly on a wide variety of microcomputers, PCs, workstations,
minicomputers, mainframes, and supercomputers.

@section<How Kermit Works>

Kermit transfers data by encapsulating it in @index<Packet> @i(packets) of
control information.  This information includes a synchronization marker, a
packet sequence number to allow detection of lost packets, a length indicator,
and a "block check" to allow verification of the data, as shown in Figure
@ref<-pktfig>.
@begin(figure)
@bar()
@begin<example,leftmargin +4>
+------+------+------+------+--------- - - - -+-------+
| MARK | LEN  | SEQ  | TYPE | DATA            | CHECK |
+------+------+------+------+--------- - - - -+-------+
@End(Example)
@caption(A Kermit Packet)
@tag<-pktfig>
@bar()
@end(figure)
The MARK (usually an ASCII Control-A character) appears at the beginning of the
packet.  The next character is a length field (LEN), specifying how long the
rest of the packet is.  The sequence number (SEQ) is used to detect lost or
duplicated packets; retransmission is requested for lost packets and duplicate
packets are discarded.  The TYPE field specifies whether the packet contains
data or control information.  The CHECK field contains a quantity obtained by
combining all the other characters in the packet together in one of several
ways; the sender computes this value and sends it.  The packet receiver also
computes the value and checks it against the value sent; if they agree, the
packet is accepted; if they disagree, then the packet has been corrupted and
retransmission is requested.  The DATA field contains up to 90 characters of
data.  All fields except the mark are encoded as printable ASCII characters, to
prevent host or network interference.  Figure @ref<-protofig> shows how a
typical file transfer proceeds.
@begin(figure)
@bar()
@begin(example,leftmargin +2)
@u(Sender)                 @u(Receiver)

Send-Init ------------->         @i(Sender and Receiver exchange greetings)
     <-------------------- ACK

File-Header ----------->         @i(Sender sends first file name to Receiver)
     <-------------------- ACK   @i(Receiver acknowledges)

File-Data ------------->         @i(Sender sends first file data packet)
     <-------------------- ACK

File-Data ------------->         @i(Sender sends second file data packet)
     <-------------------- ACK

File-Data --xx~~~p'''-->         @i(Third data packet is corrupted by noise)
     <-------------------- NAK   @i( and Receiver negatively acknowledges it)

File-Data ------------->         @i(Sender retransmits third packet)
     <-------------------- ACK

@i(File-Data packets are sent and acknowledged until the whole file is sent)

End-Of-File ----------->         @i(Sender indicates first file is complete)
     <-------------------- ACK

File-Header ----------->         @i(Name second of file )
     <-------------------- ACK

File-Data ------------->         @i(First data packet for second file)
     <-------------------- ACK

@i(File-Data packets are sent and ack'd until the whole file is sent)

End-Of-File ----------->         @i(Sender indicates second file is complete)
     <-------------------- ACK

End-Of-Transaction ---->         @i(Sender indicates no more files to come)
     <-------------------  ACK
@end(example)
@caption(Kermit File Transfer)
@tag<-protofig>
@bar()
@end(figure)
Figure @ref<-protofig> does not show how Kermit recovers from errors.
Very briefly, here's how it works:
@Begin(Itemize)
If a packet is corrupted in transit by noise or loss of characters, the block
check will be wrong.  A file receiver will NAK ("negatively acknowledge") a
corrupted packet, which causes the sender to retransmit the same packet (or,
alternatively, it will ACK the last correctly received packet again).  A
file sender only receives ACKs and NAKs from the receiver; a corrupted ACK, or
a NAK, from the receiver causes the sender to retransmit its most recent
packet.

If the file sender does not receive an ACK within the prescribed timeout
interval, it retransmits the same packet.  If the file receiver does not
receive an expected packet within the timeout interval, it sends a NAK for the
expected packet (or another ACK for the most recently correct packet).
@End(Itemize)
Many encoding, compression, block check, timeout, and packet length options
are provided.  These options are automatically negotiated by the two Kermit
programs when they initially make contact, and the greatest common set of
features is used.  For this reason, any two Kermit programs should be able to
communicate successfully, from the oldest, most bare-bones version, to the
newest, most feature-laden version.  The protocol is described in detail in
the Kermit book.

@Chapter<How to Use Kermit>
@label<-using>

Kermit embodies a set of rules for transferring files reliably between two
computers.  In general, one computer is a large system (a @i<host>, for
instance a timesharing system with many terminals), and the other is a personal
computer (PC).  The host believes that the PC is an ordinary terminal.  In
order for the Kermit protocol to occur, a Kermit @i<program> must be running on
each end of the communication line -- one on the host, one on the PC.

Your task is just to get the two Kermits started.  You have to use a single
keyboard and screen to talk to two different computers, two different programs.
Let's talk about a common case: you are sitting at a personal computer (PC),
which has a serial communication port.  The serial port is connected to a host
computer using, say, a dialup modem.

 Normally, when you use your PC, you are "talking" directly to it; your
commands are interpreted directly by the PC's operating system (CP/M, MS-DOS,
UNIX, etc), or by some program that runs on the PC (an editor, a text
formatter, space invaders...).  The version of Kermit on your PC is a program
like any other, but it has a special ability to either interpret your commands
directly, like other programs, or to pass everything you type through to the
other, remote computer.  When you tell Kermit to @index<CONNECT>CONNECT, it
sends every character you type out the serial port, and it puts every character
that comes in the serial port onto the screen.  This is called "terminal
emulation" -- one computer acts as if it were a terminal to the other.  You are
now "talking" to the remote computer, and the PC is (mostly) ignoring you.

Kermit, like most interactive programs, has a @i<prompt>@index<Prompt>.  The
prompt is a string of characters it types on the left margin to indicate that
it is ready for you to type a command.  Kermit's prompt is normally
"@q<Kermit->@i<xx>@q(>)".  The @i<xx> identifies the implementation of Kermit;
the Kermit that runs on MS-DOS systems is called "Kermit-MS" and its prompt is
"@q(Kermit-MS>)"; the Kermit that runs on Z80 and 8080-@|based microcomputers
is called "Kermit-80" and its prompt is "@q(Kermit-80>)", and so forth.  If you
become confused about which Kermit you are talking to, the prompt should
provide a clue.  In addition, most Kermits print an informative message like
 @example<[Connecting to remote host, type CTRL-]C to return]>
 when you CONNECT, and type another message like
 @example<[Connection closed, back at PC]>
when you return.

Having "connected" to the host, there must be a way for you to "get back" to
the PC.  This is accomplished by an @i<escape sequence>@index<Escape Sequence>.
As Kermit passes your characters through to the host, it checks each one to see
if it's a special predefined @i<escape character>.  When the PC sees this
character, it stops ignoring you -- you are once again "talking" to the PC, not
to the host.  The escape character is normally chosen to be one that you will
not need to type while talking to the host, and one that is hard to type by
accident -- it's usually a @i<control character>@index<Control Characters>,
such as Control-@q<]>, which is entered by holding down the key marked CTRL or
CONTROL and typing the indicated character (in this case, a right bracket
"@q<]>").  The CTRL key works just like a SHIFT key.  Control characters are
written either as Ctrl-A or @q<^A>, where A is the character to be typed while
holding down the Ctrl key.

@section<Transferring a File>

From system command level on your PC, first run the Kermit program.  Then tell
Kermit to CONNECT you to the host.  Now you're talking to the remote host -- at
this point you must log in, and then run Kermit on the host.

Now you have a Kermit program on each end of the connection.  The next step is
to tell @i<each> Kermit what to do.  Suppose you want to transfer a file from
the host to the PC; you would first tell the host Kermit to SEND the file, then
"escape" back to the PC Kermit and tell it to RECEIVE the file.  The transfer
begins -- you can sit back and watch, or go make yourself a sandwich.  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 should now be on your PC's disk.  The Kermit protocol has
ensured that the file arrived correctly and completely.  Now you must clean up
after yourself: 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.  Now you can do
whatever you had planned for your file -- edit it, print it on your PC printer,
etc.  Transferring a file in the other direction works the same way, but with
the SEND and RECEIVE commands exchanged.

The Kermit protocol, and most Kermit programs, allow you to send text files
reliably from the host to the PC, from the PC to the host, from host to host,
or PC to PC, usually without any special regard for the nature of the
particular machines involved.  Most implementations also allow files to be sent
in groups, with a single command, such as "@q<send *.*>"  The
scenario for each of these is the same as above -- only the details of
how to establish the actual connection differ.

Kermit works best with "printable" files -- files composed only of letters,
digits, punctuation marks, carriage returns, tabs, and so forth -- since these
can be represented on almost any kind of computer.  Kermit is also able to
transfer "binary" files -- files such as executable programs -- composed of
arbitrary bit patterns, but binary files normally are meaningful only to the
kind of computer on which they are generated.  Nevertheless, Kermit can usually
move such files from system A to system B (where they are not much use) and
back to system A in their original condition, although in most cases special
measures must be taken to accomplish this.

Let's look at some more concrete examples.  First you need to know what the
basic Kermit commands are.

@section<Basic Kermit Commands>
@Index[Kermit Commands]

 These are generic descriptions of the most basic Kermit commands.  Detailed
descriptions will come later.  In these descriptions, @i<local>@index<Local>
refers to the system that you are using directly, @i<remote>@index<Remote>
refers to the system to which you are CONNECTed via Kermit.  Commands may take
one or more operands on the same line, and are terminated by a carriage return.

@begin<description,leftmargin +4, indent -4>
@Index[SEND]
SEND @i(filespec)@\Send the file or file group specified by @i(filespec)
from this Kermit to the other.  The name of each file is passed to the other
Kermit in a special control packet, so it can be stored there with the same
name.  A file group is usually specified by including
"wildcard"@index<Wildcard> characters like "@q<*>" in the file specification.
Examples:
@begin(Example)
send foo.txt
send *.for
@end(Example)
Some implementations of Kermit may not support transfer of file groups; these
versions would require a separate SEND command for each file to be transferred.

@Index[RECEIVE]
RECEIVE@\Receive a file or file group from the other Kermit.  If an
incoming file name is not legal, then attempt to transform it to a similar
legal name.  Options are be provided for handling filename collisions.

@Index[CONNECT]@Index[Virtual Terminal]
CONNECT@\Make a terminal connection to the remote system.  To "escape" from the
terminal connection, type Kermit's @Index[Escape Character] @i<escape
character> (e.g.@ @q<CTRL-]>, control-@|rightbracket), followed by the letter
"C" for "Close Connection".

@Index[SET]
SET@\Establish various nonstandard settings, such as CONNECT escape character,
file characteristics, communication line number, speed (baud rate),
parity, or flow control.  All of these are explained later.

SHOW@\@Index[SHOW](or STATUS) Display the values of SET options.

HELP@\Type a summary of Kermit commands and what they do.

EXIT@\Exit from Kermit back to the host operating system.

@q(?)@\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.
@end<description>

@section<Real Examples>

Kermit can be used in several ways: from a PC that is connected to
a larger host computer; from a host computer which is connected
to another host; from one PC to another.

@SubSection<PC to Host>
In this example, the user is sitting at an IBM Personal Computer (PC), which
is connected through its serial port to a DEC VAX/VMS host computer.  The IBM
PC is @i<local>, the VAX is @i<remote>.  This example will also apply almost
literally to any other microcomputer implementation of Kermit.

You have started up your PC and have the Kermit program on your disk.  Begin by
running Kermit on the PC.  Use Kermit's CONNECT command to become a terminal to
the VAX.  In fact, the PC emulates the popular DEC VT-102 (VT-100), so
so it is desirable to tell the host that your terminal is of this type.
Login on the VAX and run Kermit there.  Here is an example of this procedure
with commands you type underlined; the material lined up on the right is
commentary, not system typeout or part of a command:
@Begin<Example>
@tabclear@tabDivide(3)
A>@u[Kermit]@\@i(Run Kermit on the PC.)
Kermit-MS V2.30
IBM-PC Kermit-MS: V2.30  8 Jan 88
Type ? for help

Kermit-MS>@\@i(This is the Kermit prompt for the PC.)
Kermit-MS>@u[connect]@\@i(Connect to the VAX.)
[Connecting to host, type Control-] to return to PC]

@\@i(You are now connected to the VAX.)

Welcome to CUMIN, MicroVMS V4.6@ @ @ @ i(The system prints its herald.)

Username: @ux<my-id>@\@i(Type your user ID.)
Password: @ux<my-password>@\@i(Type your password.)

@i<(Various greeting or notice messages are displayed.)>

$ @\@i(This is the VMS system prompt.)
$ @u[Kermit]@\@i(Run Kermit on the VAX.)

VMS Kermit-32 version 3.3.111
Default terminal for transfers is: _TXA0:
Kermit-32>@\@i(This is VMS Kermit's prompt.)
@End<Example>
You are now ready to transfer files between the two machines.

The following example illustrates how to send files from the VAX to
the PC.  Note the use of the "*" @i<wildcard>@index<wildcard>
character to denote a @i<file group>.
@Begin<Example>
@tabclear@tabDivide(3)
Kermit-32>@ux[send *.for]@\@i(Send all my FORTRAN files.)
@ux<^]c>@\@i(Now return back to the PC by)
@\@i(typing the escape sequence, in this case)
@\@q(^]C) @i((Control-@q(]) followed by "C"))
[Back at PC.]
Kermit-MS>@u[receive]@\@i(Tell the PC that files are coming.)
@End<Example>

If you take more than about 5 seconds to get back to Kermit-MS and issue the
@Index[RECEIVE] @c<receive> command, the first packets from Kermit-32 may
arrive prematurely and appear on your screen, but no harm will be
done because the packet will be retransmitted by the VAX until the PC
acknowledges it.

Once the connection is established, the PC will show you what is happening --
it first clears the screen and waits for incoming packets; as packets arrive,
the current file name and packet number will be continuously displayed on the
screen.  When the PC's @q("Kermit-MS>") prompt returns to your screen (with an
accompanying beep to catch your attention) the transfer is done.  Notice the
screen display; the status should be indicated as "complete".  If not, an error
has occurred and an appropriate message should be displayed to tell you why.

After you're finished transferring files, you must CONNECT back to the VAX
host, EXIT from Kermit there, logout, and "escape back" to the PC as you did
previously:
@Begin<Example>
@tabclear@tabDivide(3)
Kermit-MS>@ux[connect]@\@i(Get back to the VAX.)
[Connecting to host. Type CTRL-]C to return to PC.]
Kermit-32>@\@i(Here we are.)
Kermit-32>@u[exit]@\@i(Get out of VMS Kermit.)
$ @ux<logout>@\@i(Logout from the VAX.)

MY-ID   logged out at 25-JAN-1988 15:12:27.85

@ux<^]c>@\@i(Now "escape" back to the PC,)
[Back at PC.]
Kermit-MS>@ux<exit>@\@i(and exit from the PC's Kermit.)
A>@\@i(Now you see the DOS prompt again.)
@End<Example>
The files you transferred should now be on your PC disk.

To send files from the PC to the VAX, follow a similar procedure.  First
follow the instructions in the previous section to log in to the VAX through
the PC.  Then in response to the host Kermit's "@q(Kermit-32>)" prompt you type
@Index[RECEIVE] RECEIVE rather than SEND.  Now escape back to the PC and use
the @Index[SEND] SEND command to send the local PC files to VAX.  The
PC will show you the progress of the transmission on its screen.

When the "@q(Kermit-MS>)" prompt indicates that the transmission is complete
you should follow the procedure shown above to logout from the VAX host,
except that you may first wish to confirm that the files have been stored
correctly in your directory on the VAX.

@SubSection<Host to Host>
A "host" is considered to be a large or multi-user system, whose distinguishing
characteristic is that it has multiple terminals.  Use of Kermit for
host-@|to-@|host file transfers differs from the PC-@|to-@|host case in that
the line your terminal is connected to is not the same as the line over which
the data is being transferred, and that some special SET commands may have to
be issued to allow one Kermit to conform to unusual requirements of the other
host.

In this example, you are already logged in to a Unix system, and you use an
@index<Autodialer>@i<autodialer> to connect to an IBM 370-@|series system
running VM/CMS@index<VM/CMS> through Unix device @q</dev/tty12>.
@Begin<Example>
@tabclear@tabDivide(3)
% @ux[kermit]
C-Kermit, 4E(070) 24 Jan 88, 4.2 BSD
Type ? for help
C-Kermit>@ux[set modem hayes]
C-Kermit>@ux[set line /dev/tty12]
C-Kermit>@ux[set speed 1200]
C-Kermit>@ux[dial 7654321]
Connected!
@End<Example>
Other methods exist for connecting two hosts with a serial line.  For instance,
dedicated hookups can be made by running an RS-232 "null modem" cable between
TTY ports on the two systems (null modem cables, RS-232 signals, modems, and
other data communication apparati are described in detail in the Kermit book).
The following procedure would be the same in any case, once a connection is
made.  The four "set" commands below are necessary when connecting to IBM
mainframes in "linemode" (as opposed to full-screen 3270 mode; if you don't use
IBM mainframes, you can ignore them for now).
@Begin<Example>
@tabclear@tabset(3inch)
C-Kermit>@ux[set duplex half]@\@i(The IBM mainframe is half duplex.)
C-Kermit>@ux[set flow none]@\@i(No full duplex XON/XOFF.)
C-Kermit>@ux[set handshake xon]@\@i(Use XON for line turnaround handshake.)
C-Kermit>@ux[set parity mark]@\@i(Our IBM system uses mark parity.)
C-Kermit>@ux[connect]@\@i(Connect to the mainframe.)
Connecting thru /dev/tty31, speed 1200.
The escape character is CTRL-\ (28).
Type the escape character followed by C to get back,
or followed by ? to see other options.
@\@i<(Type carriage return here.)>
VM/370 ONLINE@\@i(The IBM system prints its herald.)

.@ux[login myuserid mypassword]@\@i(Login to IBM system.)

LOGON AT 15:33:02 EST MONDAY 02/08/88
CUVMA CMS 3.1 8409 01/25/85
.
.@ux[Kermit]
Kermit-CMS Version 4.0 (87/12/17)
Enter ? for a list of valid commands

Kermit-CMS>.@ux[send profile exec]
@ux<^\c>@\@i(C-Kermit's escape sequence typed here.)
[Back at Local System]
C-Kermit>@ux[receive]@\@i(Tell Unix Kermit to RECEIVE.)
@End<Example>
The transfer takes place now; Unix Kermit will print the names of incoming
files, followed by dots or percents to indicate the packet traffic (a dot for
every 4 packets successfully transferred, a percent for every timeout or
retransmission).  The transfer is complete when when you see "@q<[OK]>", a beep
is sounded, and the C-Kermit prompt next appears.  At that point we connect
back to the remote IBM system, exit from the remote Kermit and log out.
@Begin<Example>
@tabclear@tabDivide(3)
.
profile.exec ..%%.[OK]
C-Kermit>@ux[connect]@\@i(Get back to mainframe and clean up.)

Kermit-CMS>.
Kermit-CMS>.@u[exit]
R;
.
SP/CMS
.logout

CONNECT= 00:03:01 VIRTCPU= 000:00.12 TOTCPU= 000:00.60
LOGOFF AT 15:40:13 EST MONDAY 02/08/88

@ux[^\c]@\@i(Type C-Kermit's escape sequence)
[Back at Local System]
C-Kermit>@u[exit]@\@i(All done with Kermit.)
@End<example>
That's the whole procedure.  The file is in your Unix directory, completely
readable, as @q<profile.exec> -- note that Kermit-CMS translated from the IBM
EBCDIC character encoding into standard ASCII, and converted the space
between the file name and file type to a dot.

To send a file from the local host to the remote host, we would merely have
reversed the SEND and RECEIVE commands in the example above.

@subsection<Micro to Micro>

Kermit also works between personal computers (microcomputers, workstations).
The difference here is that commands are typed on @i<two> keyboards, rather
than a single one.  This is because a personal computer normally only accepts
commands from its own keyboard.  If one PC Kermit CONNECTs to another, there
will normally be no program on the other side to listen.

You can make the physical connection between two micros in two ways: direct or
dialup.  If the two units are in close proximity (say, 50 feet or less), you
can connect their serial ports with a null modem@index<Null Modem>
cable@index<Cables>.

Connections at longer distances can be made via dialup, providing the required
modems are available (one side needs @index<Autoanswer>autoanswer capability),
or using any kind of dedicated or switched circuit that may be available --
CBX, port contention unit, almost anything you can plug an EIA connector into.

In this example, a DEC VT180 "Robin" CP/M-80 microcomputer is connected to a
Intertec "SuperBrain" CP/M-80 micro, using a female-@|to-@|male null modem
cable (these systems have nostalgia value, being among the first for which
Kermit programs were written).  The connection can be tested by running Kermit
and issuing the CONNECT command on both ends: typein from each micro should
appear on the screen of the other.

Suppose you want to send a file @q<FOO.HEX> from the Robin to the SuperBrain.
Proceed as follows:
@begin<enumerate>
Run Kermit on the SuperBrain, and give the RECEIVE command:
@begin[example]
A>@u(Kermit)
Intertec SuperBrain Kermit-80 - V4.09
Kermit-80>@u<receive>
@end[example]

Run Kermit on the Robin, and give the SEND command for @q<FOO.HEX>.
@begin[example]
A>@u(Kermit)
DEC VT18X Kermit-80 - V4.09
Kermit-80>@ux(send foo.hex)
@end[example]
Watch the packets fly.  When you get the next @q(Kermit-80>) prompt, the
transfer is done, and you can EXIT from both Kermits.
@end<enumerate>
The key point is to start the @i<receiving> end first -- some microcomputer
Kermits do not include a timeout facility, and if the receiver is not ready to
receive when the sender first sends, there will be a protocol deadlock.

@section<Another Way -- The Kermit Server>

So far, we have been describing the bare-@|bones version of the Kermit
protocol.  An optional extension to the protocol includes the concept of a
@i<Kermit server>@index<Kermit server>@index<Server>.  A Kermit server is a
Kermit program that does not interact directly with the user, but only with
another Kermit program.  You do not type commands to a Kermit server, you
merely start it at one end of the connection, and then type all further
commands at the other end.

Not all implementations of Kermit can be servers, and not all know how to talk
to servers -- but most of the major ones can and do.  The server is run on the
remote computer, which would normally be a timesharing system, such as an IBM
mainframe, a Unix system, or VAX/VMS, but may be a minicomputer or even a PC.
It depends on whether the particular Kermit program has a "server" command.
You must still connect to the remote host to log in and start the server, but
you no longer have to tell one side to SEND and the other to RECEIVE, nor must
you connect back to the remote side to clean up and log out when you're done.
Using the server, you can do as many send and receive operations as you like
without ever having to connect back to the remote host.  Some servers also
provide additional services, such as directory listings, file deletion, or disk
usage inquiries.

A Kermit server is just a Kermit program running in a special way.  It acts
much like ordinary Kermit does after you give it a RECEIVE command -- it waits
for a message from the other Kermit, but in this case the message is a command
saying what to do, normally to send or to receive a file or group of files.
After escaping back to the local system, you can give as many SEND and GET
commands as you like, and when you're finished transferring files, you can give
the @index<BYE>BYE command, which sends a message to the remote Kermit server
to log itself out.  You don't have to connect back to the remote host and clean
up.  However, if you @i<want> to connect back to the host, you can use the
FINISH@index<FINISH> command instead of BYE, to shut down the Kermit server on
the remote host without logging it off, allowing you to CONNECT back to your
job there.

Here's an example of the use of a Kermit server.  The user is sitting at an
IBM PC and a DECSYSTEM-20 is the remote host.
@Begin<Example>
@tabclear@tabDivide(3)
A>@u[Kermit]@\@i(Run Kermit on the micro.)
Kermit-MS V2.30
IBM-PC Kermit-MS: V2.30  8 Jan 88
Type ? for help

Kermit-MS>@\@i(This is the Kermit prompt for the PC.)
Kermit-MS>@u[connect]@\@i(Connect to the VAX.)

CU20B@\@i(The DEC-20 prints its herald.)
@@@ux[login my-id password]@\@i(Log in normally.)
@end<example>
@i<(The DEC-20 prints various login messages here.)>
@Begin<Example>
@tabclear@tabDivide(3)
@@@u[Kermit]@\@i(Run Kermit-20 normally)
Kermit-20>@u[server]@\@i(Tell it to be a server.)

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.

@u<^]c>@\@i(Now escape back to the PC.)

Kermit-MS>@ux[get *.pas]@\@i(Get all my DEC-20 Pascal programs.)
Kermit-MS>@ux[send foo.*]@\@i(Send all the "foo" files from my PC.)
Kermit-MS>@ux[exit]@\@i(Exit from Kermit back to DOS.)
A>
@end<example>
@i<(Here you can do some work on the micro, edit files, whatever you like.)>
@Begin<Example>
@tabclear@tabDivide(3)
A>@u<Kermit>@\@i(Run Kermit-80 some more.)
Kermit-MS>@ux[send file.pas]@\@i(Send another file.)
Kermit-MS>@ux[bye]@\@i(That's all.  Shut down the Kermit server.)
A>@\@i(Back at DOS automatically.)
@End<Example>
This is @i<much> simpler.  Note that once you've started the Kermit Server
on the remote end, you can run Kermit as often as you like on the micro without
having to go back and forth any more; just make sure to shut the server down
when you're done by typing the BYE command.

If it's so much simpler, why not do it this way all the time?  You can,
provided your remote Kermit has a "server" command.  But server operation,
plus the special commands the local Kermit needs to communicate with the
server (GET, REMOTE, BYE, FINISH) are optional Kermit features, so some
Kermit programs might not have them.  All Kermit programs, however, should
provide the basic SEND/RECEIVE mode of operation.

Here are the basic commands available for talking to servers:
@begin<description>
@Index[SEND]
SEND @i(filespec)@\Sends a file or file group from the local host to the
remote host in the normal way.

@Index[GET]
GET @i(filespec)@\Ask the remote host to send a file or file group.
Example:
@example[get *.c]
This command is exactly equivalent to typing "@w[send @q<*.c>]" at the remote
host followed by "receive" on the local host.  Note that the local Kermit does
not attempt to validate the filespec.  If the server cannot access the
specified file(s), it will send back an appropriate error message.  Please note
that GET and RECEIVE are not the same!  RECEIVE tells Kermit to passively wait
for a file.  GET actively sends a request to a Kermit server to send the
named file.

@index<REMOTE>
REMOTE @i(command) [@i(argument)]@\Ask the server to perform the specified
command, and send the results to your screen.  Not all servers are capable of
performing REMOTE commands; those that can most commonly provide REMOTE
DIRECTORY, REMOTE DELETE, REMOTE SPACE, and similar file management services.

@index<BYE>
BYE@\Shut down the remote server and exit from Kermit.  This
will cause the job at the remote end to log itself out.  You need not connect
back and clean up unless you get an error message in response to this command.

@index<FINISH>
FINISH@\Shut down the server without having it log itself out, and don't
exit from Kermit.  A subsequent CONNECT command will put you back at your job
on the remote host, at system command level.
@end<description>

@index<Server>
Server operation is not limited to mainframes.  Some PC Kermit implementations
can also act as servers, notably MS-DOS and Unix.  For instance, an IBM PC at
the office with an autoanswer modem can be left in server mode at the end of
the day, and then dialed up from home in the evening for file transfer.

@Chapter<When Things Go Wrong>
@label<-wrong>
@Index[Error Recovery]
Connecting two computers can be a tricky business, and many things
can go wrong.  Before you can transfer files at all, you must first
establish terminal communication.  But successful terminal connection does not
necessarily mean that file transfer will also work.  And even when file
transfer seems to be working, things can happen to ruin it.  The following
sections treat a few basic problems.  See the troubleshooting section of the
Kermit book for greater detail.

@Section<Basic Connection Problems>

If you have a version of Kermit on your microcomputer, but the CONNECT command
doesn't seem to work at all, please:
@begin<itemize>
Make sure all the required physical connections have been made and have not
wiggled loose.  If you are using a modem, make sure the carrier light is on.

If you have more than one connector on your micro, make sure you are using the
right one.

Make sure that the port is set to the right communication speed, or @i<baud
rate>.  Some versions of Kermit have a built-@|in SET BAUD or SET SPEED
command, others require that you set the baud rate using a system command or
setup mode before you start the Kermit program.  Some versions of Kermit have
SHOW or STATUS commands that will tell you what the current baud rate is.

Make sure that the other communication line parameters, like parity, bits per
character, handshake, and flow control are set correctly.
@end<itemize>
You may have to consult the appropriate manuals for the systems and equipment
in question.

@index<Internal Modem>
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 (i.e.
those that plug in to a slot inside the microcomputer chassis) are @i<not>
recommended for use with Kermit unless they totally mimic the asynchronous
serial port hardware they purport to replace, or unless the Kermit program
claims to support the particular internal modem.  Many microcomputer Kermit
programs are written to control the communication hardware explicitly; internal
modems can interfere with that control.

Even external modems can cause trouble -- the "smarter" they are, the more
potential danger of disagreement between the modem and the microcomputer about
settings of baud rate, character framing, echo, and so forth.  Make sure your
modem is set up correctly (consult your modem manual).

@Section<Terminal Connection Works But The Transfer Won't Start>

Once you've made a terminal connection to the remote system, you will generally
also be able to transfer files.  But not always.  If Kermit's terminal
emulation seems to work correctly, but a file transfer will not start at all,
then something in the communication path is probably interfering with the
packet data:
@Begin(Description,leftmargin +4, indent -4)
PARITY:@\
A device can impose @i<parity> upon the communication line.  This means that
the 8th bit of each character is used by the equipment to check for correct
transmission.  Use of parity will:
@Begin(Itemize)
Cause packet checksums to appear incorrect to the receiver and foil any attempt
at file transfer.  In most cases, not even the first packet will get through.

@Index<Binary Files>
Prevent the use of the 8th bit for binary file data.
@End(Itemize)
If terminal connection works but file transfer does not, parity is the most
likely culprit.  To overcome this impediment, you should find out what parity
is being used, and inform the Kermits one side or both (using the SET PARITY
command) so that they can:
@Begin(Itemize)
Compose and interpret the checksums correctly.

Employ a special encoding to allow 8-bit data to pass through the 7-bit
communication channel.
@End(Itemize)
Many packet-switched networks, such as GTE TELENET, require parity to be
set, as do IBM mainframes and their front end processors.

@index<Echo>
ECHOING:@\Some communication processors, typically front ends, echo their
input.  When this happens, every Kermit packet that is sent to it will bounce
right back, causing no end of confusion.  Some Kermit programs have been
designed to ignore echoed packets, but others have not.  If you encounter this
problem, there are several possible solutions:
@Begin(Itemize)
Disable the front end echoing by typing some special command, if such a command
is provided by the system.

Some front ends respond to certain escape or control sequences as commands
to turn off echoing, either from that point onward, or else on a per-@|line
basis.    In this case, the appropriate control sequence can be inserted between
packets by Kermit programs instructed to do so, for instance using the
SET PAD command.

If the echoing cannot be disabled, then the two Kermit programs should be
instructed to use differing packet start markers, using the SET START-OF-PACKET
command -- for instance, one Kermit uses Control-A as usual, and the other uses
Control-B.  This can only be done if both Kermits have this SET command.
@end(Itemize)
@End(Description)

@Section<Special Characters>

There is one problem that can prevent a file transfer from starting at all, or
may crop up after the file transfer is underway.  For instance, during a file
transfer operation you might find your smart modem suddenly hanging up your
current connection and placing a call to Tasmania.  Or you might find that
packets containing a certain character like "@q<@@>" cannot be transmitted
successfully.

This is the problem of "special characters".  Some device in the communication
path -- a front end, a port switcher, a multiplexer, a "smart" modem --
interprets certain characters in the data stream as commands rather than as
data to be passed them along to the other side.  Usually such equipment
interferes only with the transmission of ASCII control characters; so long as
Control-A and Carriage Return -- Kermit's normal packet start and end
delimiters -- are not molested, then Kermit can operate.  However, equipment
may exist which swallows even printable characters.  Since Kermit assumes that
ALL printable ASCII characters (ASCII 40 through 176, octal) can be transmitted
without interference or modification, such equipment will prevent Kermit file
transfer unless its printable-@|character-@|swallowing features can be
disabled.

@Section<The Transfer Starts But Then Gets Stuck>

Once a Kermit file transfer has begun, there are certain conditions under which
it can become stuck.  Since many hosts are capable of generating timeout
interrupts when input doesn't appear within a reasonable interval, they can
resend unacknowledged packets or request that missing packets be retransmitted.
But since not all Kermit programs are capable of timing out, a means for
manual intervention is provided in the local Kermit -- you can type a carriage
return on the keyboard of most micros to wake up and continue the transfer.

The following sections discuss various reasons why a transfer in progress could
become stuck.  Before examining these, first make sure that you really have a
Kermit on the other end of the line, and you have issued the appropriate
command: SEND, RECEIVE, or SERVER.  If the remote side is not a server,
remember that you must connect back between each transfer and issue a new SEND
or RECEIVE command.

@subSection<The Connection is Broken>

Check the connection.  Make sure no connectors have wiggled loose from their
sockets.  If you're using a modem, make sure you still have a carrier signal.
Reestablish your connection if you have to.

If upon reconnection you get no response, maybe the remote host or the remote
Kermit program @Index[Crash] crashed.  Get back to command level on the local
Kermit (on microcomputer implementations, you may be able to do this by typing
about five RETURNs, or one or more Control-C's).  Issue the CONNECT command so
that you can see what happened.  If the remote system has crashed then you will
have to wait for it to come back, and restart whatever file that was being
transferred at the time.

@subSection<The Disk is Full>
@Index[Diskette]
If your local floppy disk or remote directory fills up, the Kermit on the
machine where this occurs will inform you and then terminate the transfer.  You
can continue the transfer by repeating the whole procedure either with a fresh
floppy or after cleaning up your directory.  Some Kermits also have a feature
that allows you to keep incompletely received files; this would allow you go
back to the sending system, extract the unsent portion of the file, and send
it, and then append the two received portions together using an editor or other
system utility.  Kermit does not provide the ability to switch disks during a
file transfer.

@SubSection<Transmission Delays>

Packet transmission can be delayed by various agents: congested timesharing
systems or networks, earth satellites, etc.  When transmission delay exceeds
the per-packet timeout interval for a significant length of time, the transfer
could fail.  Most Kermit programs provide commands that allow you to adjust
the timeout interval or the packet transmission retry threshhold in order to
accommodate to severe transmission delays.

@SubSection<Noise Corruption>

If your connection is extremely noisy, packets will become corrupted -- and
require retransmission -- more often.  The probability that successive
retransmissions will fail because of corruption rises with the noise level
until it exceeds the retry threshhold, at which point the file transfer
fails.  There are several recourses.  First, try to establish a new connection.
If that is impractical, then use SET commands (when available) to reduce the
packet length and increase the retry threshhold.  Shorter packets reduce the
probability that a particular packet will be corrupted and the
retransmission overhead when corruption does occur, but they also increase
the overall protocol overhead.  In a noisy environment, you should also
request a higher level of error checking (SET BLOCK 2 or 3).

@subSection<Host Errors>

Various error conditions can occur on the remote host that could effect file
transmission.  Whenever any such error occurs, the remote Kermit normally
attempts to send an informative error message to the local one, and then breaks
transmission, putting you back at Kermit command level on the local system.

@Section<File is Garbage>

 There are certain conditions under which Kermit can believe it transferred a
file correctly when in fact, it did not.  The most likely cause has to do with
the tricky business of @i<file attributes>, such as text vs binary, 7-bit vs
8-bit, blocked vs stream, and so forth.  Each system has its own peculiarities,
and each Kermit has special commands to allow you to specify how a file should
be sent or stored.  However, these difficulties usually crop up only when
sending binary files.  Textual files should normally present no problem between
any two Kermit programs.

@Chapter<Kermit Commands>
@label<-commands>

An "ideal" Kermit program will be described here, which has most of the
features specified in the Kermit book.  Few Kermit programs will have all these
commands or support all these options.  The exact form of some of the commands
may differ from version to version.  Some Kermit programs may support
system-@|dependent options not described here.  The intention of this
description is to provide a base from which specific Kermit programs can be
described in terms of their differences from the "ideal."

@Section<Remote and Local Operation>

@index[Remote]@index[Local]
 In any connection between two Kermit programs, one Kermit is @i<remote> and
the other is @i<local>.  The remote Kermit is usually running on a mainframe,
which you have CONNECTed to through a PC or other computer.  When Kermit runs
remotely, all file transfer is done over the job's controlling terminal line --
the same line over which you logged in, and to which you would type interactive
commands.  What the system thinks is your terminal is really another computer,
usually a microcomputer, running its own copy of Kermit.

When Kermit is in "local mode", file transfer is done over an external device,
such as a microcomputer's serial communication port, or an assigned terminal
line on a mainframe.  The local Kermit is connected in some way (like a dialout
mechanism) to another computer, again running its own copy of Kermit.  A local
Kermit is in control of the screen, a remote Kermit has no direct access to it.
Microcomputer Kermits are run in local mode unless instructed otherwise;
mainframe Kermits run remotely unless some special command places them in local
mode.  Some commands make sense only for remote Kermits, others only for local,
still others can be used with either.  Local and remote operation of Kermit is
shown schematically here:
@Begin(Figure)
@bar()
@i<PC is Local, Mainframe is Remote:>
@begin<example>
           Communication
           Line                    (Packets)
           +---------------/  /-----------------+  Other terminals
           |                                    |  |  |  |
           |                                    |  |  |  |
 PC        |     LOCAL              Mainframe   |  |  |  |  REMOTE
+----------+----------+            +------------+--+--+--+--------+
|   Serial Port       |            |            |                 |
|                     |            |            |                 |
|                     |            |            |                 |
|  +---------------+  |            |            Your job's        |
|  | Packets: 724  |  |            |            terminal line     |
|  | Retries:   7  |  |            |                              |
|  | File: FOO.BAR |  |            |                              |
|  +---------------+  |            |                              |
|   Screen            |            |                              |
|                     |            |                              |
+---------------+-----+            +------------------------------+
                |
                | (Commands)
                |
   +------------+---------+
    \       Keyboard       \
     +----------------------+
                You
@end(example)
@caption(Local and Remote Kermits)
@tag(-localfig)
@bar()
@end<figure>
The Kermit program on the PC is a @i<local> Kermit.  It can control the screen,
the keyboard, and the port separately, thus it can update the screen with
status information, watch for interrupt signals from the keyboard, and transfer
packets on the communications port, all at the same time.

The Kermit program running on the mainframe is a @i<remote> Kermit.
The user logs in to the mainframe through a terminal port.  The host computer
cannot tell that the user is really coming in through a microcomputer.  The
keyboard, screen, and port functions are all combined in user's mainframe
terminal line.  Therefore a remote Kermit is cut off from your screen and
keyboard during file transfer.

@section<The Command Dialog>

@index<Command Parsing>
 Most Kermit programs communicate with you through interactive keyword-@|style
command dialog (a prominent exception is Macintosh Kermit, which uses pulldown
menus that overlay the terminal emulation screen).  The program issues a
@i<prompt>, indicating that it is waiting for you to type a command.  The
prompt is usually of the form
 @example[@q(Kermit-)@i<xx>@q(>)]
 where @i<xx> indicates the version of Kermit -- @q(Kermit-MS>) for MS-DOS
Kermit, @q(Kermit-86>) for CP/M-86 Kermit, etc.

In response to the program's prompt you may type a keyword, such as SEND,
RECEIVE, or EXIT, possibly followed by additional keywords or operands, each of
which is called a @i<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.  The ESC and "?"  features work best on
full duplex systems, where the program can "wake up" immediately and perform
the required function.  On half duplex or record-@|oriented systems, the ESC
feature is not available, and the "?" requires a carriage return to follow.

In this example, the user types "set" and then a question mark to find out what
the SET options are.  The user then continues the command at the point where
the question mark was typed, adding a "d" and another question mark to see what
set options start with "d".  The user then adds a "u" to select "duplex" (the
only SET option that starts with "du") followed by an ESC (shown here by a
dollar sign) to complete the current field, then another question mark to see
what the possibilities are for the next field, and so forth.  The command is
finally terminated by a carriage return.  Before carriage return is typed,
however, the command can be edited or erased using RUBOUT or other command
editing keys.  Finally, the same command is entered again with a minimum of
keystrokes, with each field abbreviated to its shortest unique length.  In the
example, the parts the user types are underlined; all the rest is system
typeout:

@begin<example,above 2,below 2>
Kermit-20>@ux<set ?> one of the following:
 debugging        delay             duplex            escape
 file             handshake         IBM               line
 parity           receive           send
Kermit-20>set @u<d?> one of the following:
 debugging   delay        duplex
Kermit-20>set d@u<u$>plex (to) @u<?> one of the following:
 full   half
Kermit-20>set duplex (to) @u<h$>alf
Kermit-20>@ux<set du h>
@end<example>

@section<Notation>

In the command descriptions, the following notation is used:
 @begin<description,leftmargin +12,indent -12>
@i<italics>@\A parameter - the symbol in italics is replaced by
an argument of the specified type (number, filename, etc).

[@i<anything>]@\A field enclosed in square brackets is optional.  If omitted,
the field defaults to an appropriate value.  You don't type the brackets.

{x,y,z}@\A list of alternatives is enclosed in curly braces; you type one
of the alternatives.

@i<number>@\A whole number, entered in prevailing notation of the system.

@i<character>@\A single character, entered literally, or as a number (perhaps
octal or hexadecimal) representing the ASCII value of the character.

@i<floating-point-number>@\A "real" number, possibly containing a decimal point
and a fractional part.

@i<filespec>@\A file specification, i.e. the name of a file, possibly including
a search path, device or directory name, or other qualifying information, and
possibly containing "wildcard" or pattern-@|matching characters to denote a
group of files.

@q<^X>@\A control character may be written using "uparrow" or "caret" notation,
since many systems display control characters this way.  Control characters are
produced by holding down the key marked CTRL or Control and typing the
appropriate character, e.g. X.  Control characters may also be written
Ctrl-X, CTRL-X, CTRL/X, etc.
 @end<description>
Commands are shown in upper case, but can be entered in any combination of
upper and lower case.

@newpage()
@Section<Summary of Kermit Commands>

Here is a brief list of Kermit commands as they are to be found in most Kermit
programs.  The following sections will describe these commands in detail.
@begin<description,leftmargin +4,indent -4,spread 0.5>
@i<For exchanging files:>@\
SEND, RECEIVE, GET

@i<For connecting to a remote host:>@\
CONNECT, SET LINE, SET PARITY, SET DUPLEX, SET HANDSHAKE, SET ESCAPE,
@w<SET FLOW-CONTROL>, SET SPEED (or BAUD)

@i<For acting as a server:>@\SERVER

@i<For talking to a server:>@\BYE, FINISH, GET, SEND, REMOTE

@i<Setting nonstandard transmission and file parameters:>@\
SET BLOCK-CHECK, SET DEBUG, SET DELAY, SET FILE, SET INCOMPLETE, SET PARITY,
SET RETRY;@*
SET SEND (or RECEIVE) END-OF-LINE, START-OF-PACKET, PACKET-LENGTH,
PAUSE, TIMEOUT, PADDING

@i<For defining and executing "macros" of commands:>@\
DEFINE, DO

@i<For interrupting transmission:>@\
Control-X, Control-Z, Control-C, Control-E

@i<Getting information:>@\
HELP, STATISTICS, SHOW

@i<Executing command files:>@\
TAKE

@i<For recording the history of a file transfer operation:>@\
LOG TRANSACTIONS

@i<For non-protocol file capture or transmission:>@\
LOG SESSION, TRANSMIT, INPUT, OUTPUT, PAUSE, CLEAR, SCRIPT

@i<For closing log files:>@\
CLOSE

@i<Leaving the program:>@\
EXIT, QUIT
@End(Description)
If you have a file called @q<KERMIT.INI> in your default or home disk, Kermit
will execute an automatic TAKE command on it upon initial startup.
@q<KERMIT.INI> may contain any Kermit commands, for instance SET commands,
or DEFINEs for macros to configure Kermit to various systems or
communications media.  @i<Note:>  Your particular implementation of Kermit may
use a different name for this file, like @q<MSKERMIT.INI> for MS-DOS Kermit,
or @q<VMSKERMIT.INI> for VAX/VMS Kermit.

@newpage()
@Section<The SEND Command>
@Index[Initial Filespec]@Index[SEND]
Syntax:

Sending a single file:
 @display(@q<SEND @i{filespec1} [@i{filespec2}]>)

Sending multiple files:
 @display(@q<SEND @i{wild-filespec1}>)

The SEND command causes a file or file group to be sent to the
other system.  There are two forms of the command, depending on whether
@i{filespec1} contains "wildcard" characters.  Use of wildcard characters is
the most common method of indicating a group of files in a single file
specification.  For instance if @q<FOO.FOR> is a single file, a FORTRAN program
named FOO, then @q<*.FOR> might be a group of FORTRAN programs.

@SubH<Sending a File Group -->

If @i{filespec1} contains wildcard characters then all matching files will be
sent, in directory-@|listing order by name.  If a file can't be opened for read
access, it will be skipped.

@SubH<Sending a Single File -->

If @i{filespec1} does not contain any wildcard characters, then the single file
specified by @i{filespec1} will be sent.  Optionally, @i{filespec2} may be used
to specify the name under which the file will arrive at the target system;
@i{filespec2} is not parsed or validated locally in any way.  If @i{filespec2}
is not specified, the file will be sent with its own name.

@SubH<SEND Command General Operation -->

Files will be sent with their filename and filetype (for instance
@q<FOO.BAR>, no device or directory field, no generation number or attributes).
@Index<Parity>@Index<Eighth-Bit Prefix>@Index<Binary Files>
If communication line parity is being used (see SET PARITY), the sending Kermit
will request that the other Kermit accept 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
correctly.

@Index<Repeated Character Compression>
The sending Kermit will also ask the other Kermit whether it can handle a
special prefix encoding for repeated characters.  If it can, then files with
long strings of repeated characters will be transmitted very efficiently.
Columnar data, highly indented text, and binary files are the major
beneficiaries of this technique.

@SubH<SEND Remote Operation -->

If you are running Kermit remotely (for instance, from a microcomputer), you
should "escape back" to your local Kermit within a reasonable amount of time
and give the RECEIVE command.  Don't take more than a minute or two to complete
the switch, or Kermit may "time out" and give up (in that case, you'll have
to CONNECT back to the remote system and reissue the SEND command).

@SubH<SEND Local Operation -->

If you're running Kermit locally, for instance on a microcomputer,
you should have already run Kermit on the remote system and issued either a
RECEIVE or a SERVER command.

Once you give Kermit the SEND command, the name of each file will be
printed on your screen as the transfer begins, and information will be
displayed to indicate the packet traffic.  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.  You may be able to cut down on the retransmissions by using
SET SEND PACKET-LENGTH to decrease the packet length; this will reduce the
probability that a given packet will be corrupted by noise, and reduce the time
required to retransmit a corrupted packet.

@index<Control-X>@index<Control-Z>@Index<Cancelling a File Transfer> If you
notice a file being sent which you do not really want to send, you may cancel
the operation immediately by typing either Control-X or Control-Z.  If your are
sending a file group, Control-X will cause the current file to be skipped, and
Kermit will go on to the next file, whereas Control-Z will cancel sending
the entire group and return you to Kermit-20 command level.

@Section<The RECEIVE Command>
@Index[RECEIVE]
Syntax:  @q<RECEIVE [@i{filespec}]>

The RECEIVE command tells Kermit to wait for the arrival a file or file group
sent by a SEND command from the other system.  If only one file is being
received, you may include the optional @i{filespec} as the name to store the
incoming file under; otherwise, the name is taken from the incoming file
header.  If the name in the header 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 FILE WARNING.

@Index<Parity>@Index<Eighth-Bit Prefix>@Index<Repeated Character Compression>
If you have SET PARITY, then 8th-bit prefixing will be requested.  If the other
side cannot do this, binary files cannot be transferred correctly.  The sending
Kermit may also request that repeated characters be compressed.

If an incoming file does not arrive in its entirety, Kermit will normally
discard it; it will not appear in your directory.  You may change this behavior
@Index<Incomplete File Disposition>
by using the command SET INCOMPLETE KEEP, which will cause as much of the file
as arrived to be saved in your directory.

@SubH<RECEIVE Remote Operation -->

If your are running Kermit remotely, you should escape back to your local
Kermit and give the SEND command.  You should do this within about two minutes,
or the protocol may time out and give up; if this happens, you can CONNECT back
to the remote system and reissue the RECEIVE command.

@SubH<RECEIVE Local Operation -->

If you are running Kermit locally, you should already have issued a
SEND command to the remote Kermit, and then escaped back to DEC-20 Kermit
(you can not issue a RECEIVE command to a Kermit server, you must use the
GET command for that).

As files arrive, their names will be shown on your screen, along with
a continuous display the packet traffic.

@Index<Control-X>@Index<Control-Z>@Index<Cancelling a File Transfer>
If a file begins to arrives that you don't really want, you can attempt to
cancel it by typing Control-X; this sends a cancellation request to the
remote Kermit.  If the remote Kermit understands this request (not all
implementations of Kermit support this feature), it will comply;
otherwise it will continue to send.  If a file group is being sent, you can
request the entire group be cancelled by typing Control-Z.

@Section<The GET Command>
@index<The GET Command>
Syntax: @q<GET [@i{remote-filespec}]>

The GET command requests a Kermit @i<server> to send the file or file group
specified by @i<remote-filespec>.  Note the distinction between the RECEIVE
and GET commands: RECEIVE instructs the program to wait passively, whereas GET
actively sends a request to a server.

The remote filespec is any character sequence that can be a legal file
specification for the remote system; it is not parsed or validated locally.  As
files arrive, their names will be displayed on your screen, along with a
continuous indication of the packet traffic.  As in the RECEIVE command, you
may type Control-X to request that the current incoming file be cancelled,
Control-Z to request that the entire incoming batch be cancelled.

@i<Optional Syntax:> If you are requesting a single file, you may type the GET
command without a filespec.  In that case, Kermit programs that implement the
optional GET syntax will prompt you for the remote filespec on the subsequent
line, and the name to store it under when it arrives on the line after that:
@begin(example)
Kermit-MS>@ux(get)
 Remote Source File: @ux<aux.txt>
 Local Destination File: @ux<auxfile.txt>
@end(example)

@Section<The SERVER Command>
@Index<SERVER Command>
Syntax: @q<SERVER>

The SERVER command instructs Kermit to cease taking commands from the keyboard
and to receive all further instructions in the form of Kermit packets from
another system.  The other Kermit must have commands for communicating with
remote servers; these include GET, SEND, FINISH, and BYE.

After issuing this command, return to the "client" system and issue SEND,
GET, BYE, FINISH, or other server-@|directed commands from there.  If your
local Kermit does not have a BYE command, then it does not have the full
ability to communicate with a Kermit server and you should not put the remote
Kermit into SERVER mode.  If your local Kermit does have a BYE command, use it
to shut down and log out the Kermit server when you are done with it.

Any nonstandard parameters should be selected with SET commands before putting
Kermit in server mode.

@Section<The BYE Command>
@index<BYE Command>
Syntax: @q<BYE>

When running talking to a Kermit server, use the BYE command to shut down the
server and, if the server is on a timesharing system, also log out the job.
This will also close any open log files and exit from the local Kermit.

@Section<The FINISH Command>
@index<FINISH Command>
Syntax: @q<FINISH>

When running as a local Kermit talking to a remote Kermit server use the FINISH
command to shut down the server without logging out the remote job, so that you
can CONNECT back to it.

@Section<The REMOTE Command>
@index<REMOTE Command>
Syntax: @q<REMOTE> @i<command>

When talking to a remote Kermit server, use the REMOTE command to request
special functions of the remote server.  If the server does not understand the
command or offer the requested service (all of these commands and services are
optional features of the Kermit protocol), it will reply with a message like
"Unknown Kermit server command".  If it does understand, it will send the
results back, and they will be displayed on the screen.  The REMOTE commands
include:
@begin<description, leftmargin +4, indent -4>
REMOTE CWD [@i<directory>]@\Change Working Directory.  If no directory name is
provided, the server will change to the default directory.  Otherwise, you will
be prompted for a password, and the server will attempt to change to the
specified directory.  If access is not granted, the server will provide a
message to that effect.  If the remote system does not require a password for
changing directories (UNIX is an example), then you can simply type a carriage
return in response to the password prompt.

REMOTE DELETE @i<filespec>@\Delete the specified file or files.  The names of
the files that are deleted should be displayed on your screen.

REMOTE DIRECTORY [@i<filespec>]@\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.

REMOTE SPACE [@i<directory>]@\Information about disk usage in the
current remote directory -- quota, current storage, or amount of
remaining free space -- is displayed on your screen.

REMOTE HELP@\A list of available server functions is displayed.

REMOTE HOST [@i<command>]@\The given command is passed to the server's host
command processor, and the resulting output is displayed on your screen.

REMOTE KERMIT [@i<command>]@\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.

REMOTE TYPE @i<filespec>@\The contents of the specified file is displayed on
your screen.

REMOTE WHO [@i<username>]@\List users, or a specified user, logged in on
the server's system.
@end<description>

@Section<Local Commands>
@index<Local Commands>
Syntax: @q<[LOCAL] @i{command}>

Execute the specified command on the local system -- on the system where Kermit
to which your are typing this command is running.  These commands provide some
local file management capability without having to leave the Kermit program,
which is particularly useful on microcomputers.  On most systems, the LOCAL
prefix for these commands can be omitted.
@begin<description, leftmargin +4, indent -4>
CWD [@i<directory>]@\"Change Working Directory" to the specified directory.
@index<CWD Command>

DELETE @i<filespec>@\Delete the specified file or files.
@index(DELETE Command)

DIRECTORY [@i<filespec>]@\Provide a directory listing of the specified files.
@index(DIRECTORY Command)

SPACE@\Display local disk usage and/or free space.
@index(SPACE Command)

RUN @i<filespec> [@i<operands>]@\Run the indicated program with the supplied
command-@|line operands.
@index(RUN Command)

PUSH@ @ Invoke the local system command interpreter in such a way that it can
return (or "pop" or "exit") back to Kermit.
@index(PUSH Command)
@end<description>
Some Kermit programs may provide commands for these or other functions in the
syntax of their own system, when this would cause no confusion.  For instance,
CP/M Kermit may use ERA in place of LOCAL DELETE.

@Section<The CONNECT Command>
@index<CONNECT Command>

@i<LOCAL ONLY> -- Syntax: @q<CONNECT [@i{terminal-designator}]>

Establish a terminal connection to the system at the other end of the
communication line.  On a microcomputer, this is normally the serial port.
On a mainframe, you will have to specify a terminal line number or other
identifier, either in the CONNECT command itself, or in a SET LINE command.
Get back to the local Kermit by typing the escape character followed by
a single character "command".
Several single-@|character commands are possible:
@Begin(Description,leftmargin +6,indent -4, spread 0, group)
@q<C>@\Close the connection and return to the local Kermit.

@q<S>@\Show status of the connection.

@q<B>@\Send a BREAK signal.

@q<0>@\(zero) Send a NUL (0) character.

@q<F>@\Copy the current screen into a disk file.

@q<D>@\Drop the line, hangup the modem.

@q<P>@\Push to the local system command processor without breaking the
connection.

@q<Q>@\Quit logging session transcript.

@q<R>@\Resume logging session transcript.

@q<?>@\List all the possible single-@|character arguments.

@q<^]> (or whatever you have set the escape character to be)@\Typing the escape
character twice sends one copy of it to the connected host.
@End(Description)
You can use the SET ESCAPE command to define a different escape character, and
SET PARITY, SET DUPLEX, SET FLOW-CONTROL, SET HANDSHAKE to establish or change
those parameters.

@Section<HELP>

Syntax: @q<The HELP Command>

Typing HELP alone prints a brief summary of Kermit and its commands, and
possibly instructions for obtaining more detailed help on particular topics.
Most Kermit implementations also allow the use of "?" within a command to
produce a short help message.

@Section<The TAKE Command>
Syntax: @q<TAKE @i{filespec}>

Execute Kermit commands from the specified file.  The file may contain
contain any valid Kermit commands, including other TAKE commands.

@Section<The EXIT and QUIT Commands>
@Index<EXIT Command>

Exit from Kermit.  @Index<QUIT>@q<QUIT> is a synonym for EXIT.

@Section<The SET Command>
@index<SET Command>
Syntax: @q<SET @i{parameter} [@i{option}] [@i{value}]>

Establish or modify various parameters for file transfer or terminal
connection.

When a file transfer operation begins, the two Kermits automatically exchange
special initialization messages, in which each program provides the other with
certain information about itself.  This information includes the maximum packet
size it wants to receive, the timeout interval it wants the other Kermit to
use, the number and type of padding characters it needs, the end-@|of-@|line
character it needs to terminate each packet (if any), the block check type, the
desired prefixes for control characters, characters with the "high bit" set,
and repeated characters.  Each Kermit program has its own preset "default"
values for these parameters, and you normally need not concern yourself with
them.  You can examine their values with the SHOW command; the SET command is
provided to allow you to change them in order to adapt to unusual conditions.

The following parameters may be SET:
@Begin(Format,spread 0,above 1)
@tabclear()@tabset(1.25inches)
@>BAUD@\  Set the speed of the current communications port
@>BLOCK-CHECK@\  Packet transmission error detection method
@>DEBUG@\  Mode or log file
@>DELAY@\  How long to wait before starting to send
@>DUPLEX@\  For terminal connection, full (remote echo) or half (local echo)
@>END@\  Packet termination character (normally CR)
@>ESCAPE@\  Character for terminal connection
@>FILE@\  For setting file parameters like name conversion and byte size
@>FLOW-CONTROL@\  Selecting flow control method, like XON/XOFF
@>HANDSHAKE@\  For turning around half duplex communication line
@>IBM@\  Set parameters for IBM mainframe linemode connection
@>INCOMPLETE@\  What to do with an incomplete file
@>KEY@\  Establish a key redefinition or keyboard macro
@>LOCAL-ECHO@\  Specify who echoes during terminal connection
@>LINE@\  Terminal line to use for terminal connection or file transfer
@>MODEM@\  Modem type or characteristics
@>PARITY@\  Character parity to use
@>PORT@\  For switching communication ports
@>PROMPT@\  For changing the program's command prompt
@>RECEIVE@\  Various parameters for receiving files
@>RETRY@\  How many times to retry a packet before giving up
@>SEND@\  Various parameters for sending files
@>SPEED@\  Synomym for BAUD.
@>TERMINAL@\  Parameters for terminal emulation
@>TIMER@\  Enable/disable timeouts
@>WARNING@\  Filename collision protection
@End(Format)

The DEFINE command may be used to compose "macros" by combining SET and
possibly other commands.  The SET commands are now described in detail.

@Subheading<SET BAUD>
@Index<Baud Rate>
 Set or change the baud rate (approximate translation: transmission speed in
bits per second) on the currently selected communications device.  Ten bits per
second is usually equivalent to one character per second; 300 baud = 30 cps.
The way of specifying the baud rate varies from system to system; in most
cases, the actual number (such as 1200 or 9600) is typed.  Systems that do not
provide this command generally expect that the speed of the line has already
been set appropriately outside of Kermit.  Common values are 300, 1200, 2400,
4800, 9600, 19200.

@Subheading<SET BLOCK-CHECK {1, 2, 3}>
@Index<Block Check>
Kermit normally uses a 1-character block check, or "checksum", on each packet.
The sender of the packet computes the block check based on the other characters
in the packet, and the receiver recomputes it the same way.  If these
quantities agree, the packet is accepted and transmission proceeds.  If
they disagree, the packet is rejected and retransmission is requsted.

However, the block check is not a foolproof method of error detection.  The
normal single-@|character Kermit block check is only a 6-bit quantity (the low
order 8 bits of the arithmetic sum folded upon itself).  With
only six bits of accuracy, the chances are one in 2@+<6> -- that is,
1/64 -- that an error can occur which will not be detected in the checksum,
assuming that all errors are equally likely (they aren't).

You can decrease the probability that an error can slip through, at the expense
of transmission efficiency, by using the SET BLOCK-CHECK command to select more
rigorous block check methods.  Note that all three methods will detect any
single-@|bit error, or any error in an odd number of bits.  The options are:
@Begin(Description,leftmargin +4,indent -4)
1-CHARACTER-CHECKSUM:@\The normal single-character 6-bit checksum.

2-CHARACTER-CHECKSUM:@\A 2-character, 12-bit checksum.  Reduces the probability
of an error going undetected to 1/4096, but adds an extra character to each
packet.

3-CHARACTER-CRC:@\A 3-character, 16-bit Cyclic Redundancy Check, CCITT format.
In addition to errors in any odd number of bits, this method detects double bit
errors, all error bursts of length 16 or less, and more than 99.99% of all
possible longer bursts.  Adds two extra characters to each packet.
@End(Description)
The single character checksum has proven to be quite adequate in practice, much
more effective than straightforward analysis would indicate, since all errors
are @i<not> equally likely, and a simple checksum is well suited to catching
the kinds of errors that are typical of telecommunication lines.  The
other methods should be requested only when the connection is @i<very> noisy
and/or when sending binary files, or when using "long packets" (see SET RECEIVE
PACKET-LENGTH).

Note that the 2- and 3-character block checks are not available in all versions
of Kermit; if the other Kermit is not capable of performing the
higher-@|precision block checks, the transfer will automatically use the
standard single-@|character method.

@Subheading<SET DEBUG {ON, OFF}>
@Index<Debugging>
Syntax: @q<SET DEBUG @i{options}>

Record debugging information, either on your terminal or in a file.
Options are:
@Begin(Description,leftmargin +6,indent -4)
ON@\Turn on debugging.

OFF@\Don't display debugging information (this is the default).  If
debugging was in effect, turn it off and close any log file.
@End(Description)
or possibly others, like STATES, PACKETS, SESSION, etc., to select logging of
different phenomena.  Some Kermit programs may control debugging by use of the
LOG DEBUG command.

@Subheading<SET DELAY>
@Index<Delay>
Syntax: @q<SET DELAY @i{number}>

Specify how many seconds to wait before sending the first packet after a SEND
command.  Use when remote and SENDing files back to your local Kermit.  This
gives you time to "escape" back and issue a RECEIVE command.  The normal delay
is 5 seconds.  In local mode or server mode, Kermit does not delay before
sending the first packet.

@Subheading<SET DUPLEX>
@Index<Duplex>@Index<Local Echo>
Syntax: @q<SET DUPLEX {FULL, HALF}>

For use when CONNECTed to a remote system.  The keyword choices are FULL and
HALF.  FULL means the remote system echoes the characters you type, HALF means
the local system echoes them.  FULL is the default, and is used by most hosts.
HALF is necessary when connecting to IBM mainframes.  Half duplex is also
called "local echo"; in some Kermits, use SET LOCAL-ECHO ON instead of
SET DUPLEX HALF.

@Subheading<SET ESCAPE>
@Index<Escape Character for CONNECT>
Syntax: @q<SET ESCAPE @i{character}>

Specify or change the character you want to use to "escape" from remote
connections back to Kermit.  This would normally be a character you don't
expect to be using on the remote system, perhaps a control character like
@q<^\>, @q<^]>, @q<^^>, or @q<^_>.  Most versions of Kermit use one of these by
default.  After you type the escape character, you must follow it by a
single-character "argument", such as "C" for Close Connection.  The arguments
are listed above, under the description of the CONNECT command.

@Subheading<SET FILE>
Syntax: @q<SET FILE @i{parameter value}>

Establish file-related parameters.  Depending on the characteristics of the
system, it may be necessary to tell Kermit how to fetch an outbound file from
the disk, or how to store an incoming file.  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), byte size (PDP-10 architecture), record length
or block size (record oriented systems), end-@|of-@|file detection method (on
microcomputers), file naming conversion option.

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

@Subheading<SET FLOW-CONTROL>
@Index<Flow Control>
Syntax: @q<SET FLOW-CONTROL {XON/XOFF,NONE}>

@index<XON/XOFF>
For communicating with full duplex systems.  System-@|level flow control is not
necessary to the Kermit protocol, but it can help to use it if the same method
is available on both systems.  The most common type of flow control on full
duplex systems is XON/XOFF.  When a system's input buffer comes close to being
full, it will send an XOFF character (Control-S) to request the other system to
stop sending.  When it has emptied sufficient characters from its input buffer,
it signals the other system to resume sending by transmitting an XON character
(Control-Q).  This process operates in both directions simultaneously.  The
options for the Kermit SET FLOW command are usually restricted to XON/XOFF and
NONE, which is used to disable this feature.

@Subheading<SET HANDSHAKE>
@Index<Handshake>
Syntax: @q<SET HANDSHAKE @i{option}>

For communicating with half duplex systems.  This lets you specify the line
turnaround character sent by the half duplex host to indicate it has ended
its transmission and is granting you permission to transmit.  When a
handshake is set, Kermit will not send a packet until the half duplex
host has sent the specified character (or a timeout has occurred).
The options may include:
@Begin(Description,leftmargin +12,indent -8,spread 0)
NONE@\No handshake; undo the effect of any previous SET HANDSHAKE.

XOFF@\Control-S.

XON@\Control-Q.

BELL@\Control-G.

CR@\Carriage Return, Control-M.

LF@\Linefeed, Control-J.

ESC@\Escape, Control-@q([).
@End(Description)
Some Kermit programs may require the option to be specified by typing the
character literally or entering its numeric ASCII value.  If you use this
command to enable handshaking, you should also SET FLOW OFF.

@Subheading<SET INCOMPLETE>
@Index<Incomplete File Transfer>
Syntax: @q<SET INCOMPLETE {KEEP, DISCARD}>

Specify what to do when a file transfer fails before it is completed.
The options are DISCARD (the default) and KEEP.  If you choose KEEP, then if
a transfer fails to complete successfully, you will be able to keep the
incomplete part that was received.

@Subheading<SET LINE>
Syntax: @q<SET LINE [@i(terminal-designator)]>

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.  Specifying 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."

@subheading<SET PORT>
Syntax: @q<SET PORT @i(terminal-designator)>

Specify the communications port for file transfer or CONNECT.  This command is
found on microcomputer Kermits that run in "local" mode.  SET PORT does not
change the remote/@|local status but simply selects a different port for local
operation.

@Subheading<SET PARITY>
@Index<Parity>
Syntax: @q<SET PARITY {EVEN, ODD, MARK, SPACE, NONE}>

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.

@Index<TELENET>
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.  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 set to the same parity.  The
specified parity is used both for terminal connection (CONNECT) and file
transfer (SEND, RECEIVE, GET).

The choices for SET PARITY are:
@begin<description,leftmargin +8,indent -6,spread 0.25>
NONE@\(the default) eight data bits and no parity bit.

MARK@\seven data bits with the parity bit set to one.

SPACE@\seven data bits with the parity bit set to zero.

EVEN@\seven data bits with  the  parity  bit  set  to  make  the
overall parity even.

ODD@\seven data bits with the parity bit set to make the overall
parity odd.
@end<description>
NONE means no parity processing is done, and the 8th bit of each character can
be used for data when transmitting binary files.

@Index<Eighth-Bit Prefix>@Index<Binary Files> If you have set parity to ODD,
EVEN, MARK, or SPACE, then most versions of Kermit will request that binary
files be transferred using 8th-bit-prefixing.  If the Kermit on 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.

@Subheading<SET PROMPT>

Syntax: @q<SET PROMPT @i(string)>

@index<Prompt>
This allows you to change the program's prompt.  This is particularly useful
if you are using Kermit to transfer files between two systems of the same kind,
in which case you can change the prompts of the Kermit programs involved to
include appropriate distinguishing information.

@Subheading<SET SEND>

@q<SET SEND @i<parameter value>>

Establish parameters for outgoing packets.  This command is generally used to
override negotiated values, or to establish before negotiation takes place.
@Begin(Description,leftmargin +8,indent -8)
@Index<End Of Line>
END-OF-LINE @i<character>@\The ASCII character to be used as a line terminator
for outbound packets, if one is required by the other system, carriage return
by default.  You will only have to use this command for systems that require a
line terminator other than carriage return.

@Index<Packet Length>
PACKET-LENGTH @i{number}@\ Maximum packet length to send between 10 and 94
(decimal).  Shortening the packets might allow more of them to get through
through without error on noisy communication lines.  Lengthening the packets
increases the throughput on clean lines.  This command can be used to specify
a shorter length than the one requested by the other Kermit, but not a longer
one.

@Index<Timeout>
TIMEOUT @i<number>@\
How many seconds to wait for a packet before trying again.  A value of zero
means don't time out -- wait forever.

@Index<Pause Between Packets>
PAUSE @i<floating-point-number>@\ How many seconds to pause before sending each
data packet.  Setting this to a nonzero value may allow a slow system
enough time to consolidate itself before the next packet
arrives.  Normally, no per-packet pausing is done.

@Index<Padding>
PADDING @i<number>, PADCHAR @i<character>@\
How much padding to send before a packet, if the other side needs padding,
and what character to use for padding.  Defaults are no padding, and NUL
(0) for the padding character.  This command is also handy for inserting
special characters that may be required by communications equipment.

QUOTE @i<character>@\
What printable character to use for quoting of control characters,
"#" (43) by default.  There should be no
reason to change this.

@Index<Start Of Packet>
START-OF-PACKET @i<character>@\
The start-of-packet character is the only control character used "bare"
by the Kermit protocol.  It is Control-A by default.  If a bare Control-A
causes problems for your communication hardware or software, you can use this
command to select a different control character to mark the start of a packet.
You must also issue the reciprocal command (SET RECEIVE START-OF-PACKET) to the
Kermit on the other system (providing it has such a command).
@End(Description)

@Subheading<SET RECEIVE>
Syntax: @q<SET RECEIVE @i<parameter value>>

Parameters to request or expect for incoming packets, as follows:
@Begin(Description,leftmargin +8,indent -8)
@Index<End Of Line>
END-OF-LINE @i<character>@\
Carriage return (15) by default.

@Index<Packet Length>
PACKET-LENGTH @i<number>@\ Maximum length packet for the other side to send,
decimal number, between 10 and 94, decimal.  Some Kermit programs also support
a "long packet" protocol extension for improved file transfer efficiency.  If
you specify a value greater than 94 (and normally less than 1000 or 2000), then
the two Kermits will attempt to negotiate the use of long packets in the
receiver's direction.  If the negotiation is unsuccessful (e.g. because the
sending Kermit does not support long packets), then ordinary packets will be
used automatically.

@Index<Timeout>
TIMEOUT @i<number>@\How many seconds the other Kermit should wait for a packet
before asking for retransmission.

@Index<Pause Between Packets>
PAUSE @i<floating-point-number>@\How many seconds to pause before acknowledging
a packet.  Setting this to a nonzero value will slow down the rate at which
data packets arrive, which may be necessary for systems that have "sensitive"
front ends and cannot accept input at a high rate.

@Index<Padding>
PADDING @i<number>, PADCHAR @i<character>@\How many padding characters to
request before each incoming packet, and what the padding character should be.
No Kermits are known to need padding, and if one did, it would request it
without your having to tell it to do so.  This command would only be necessary,
therefore, under very unusual circumstances.

QUOTE @i<character>@\What printable character to use for quoting of control
characters, "#" (43) by default.  There should be no reason to change this.

@Index<Start Of Packet>
START-OF-PACKET @i<character>@\The control character to mark the beginning
of incoming packets.  Normally SOH (Control-A, ASCII 1) (see SET SEND
START-OF-PACKET, above).
@End(Description)

@Index<Retry Limit>
@Subheading<SET RETRY>
@q<SET RETRY @i<option number>>

Set the maximum number of retries allowed for:
@Begin(Description,leftmargin +8,indent -8)
INITIAL-CONNECTION@\How many times to try establishing the initial protocol
connection before giving up, normally something like 15.

PACKETS@\How many times to try sending a particular packet before giving up,
normally 5.  If a line is very noisy, you might want to increase this number.
@End(Description)

@Index<Warning>@index<File Warning>
@Subheading<SET WARNING>
@q<SET WARNING {ON, OFF}>

Tell Kermit whether to let incoming files overwrite existing files of the same
name.  If WARNING is ON, then Kermit will warn you of filename collisions and
will attempt to construct a new, unique name for the arriving file, and inform
you what the new name is.  When OFF, Kermit silently overwrites existing files
when there's a name collision.  This command may also be called SET FILE
WARNING.

@Section<The DEFINE Command>
@Index<DEFINE Command>@index<Macros>
@q<DEFINE> @i<macroname> [@i<command> [, @i<command> [, ...] ] ]

Define a "macro" to allow convenient association of one or more Kermit commands
with a mnemonic keyword of your choice.  The definition consists of a list
a list of one or more Kermit commands, separated by commas.  If you use Kermit
to communicate with several different kinds of systems, you may set up a macro
for each, for instance:
@Begin(Example,leftmargin +1)
DEFINE IBM SET PARITY MARK, SET DUPLEX HALF, SET HANDSHAKE XON
DEFINE UNIX SET PARITY NONE, SET DUPLEX FULL, SET HANDSHAKE NONE
@Index<TELENET>
DEFINE TELENET SET PARITY MARK, SET RECEIVE TIMEOUT 20
@End(Example)
You may then type DO IBM, DO UNIX, and so forth to set all the desired
parameters with a single command.  It is convenient to include these
definitions in your Kermit initialization file.

Another other handy use for macros would be for rapid adaptation to
different conditions of line noise:
@Begin(Example,leftmargin +1)
DEFINE CLEAN SET BLOCK-CHECK 1, SET REC PACKET-LEN 94, SET RETRY 5
DEFINE NOISY SET BLOCK 2, SET SEND PACKET 60, SET RETRY 10
DEFINE VERY-NOISY SET BLOCK 3, SET SEND PACKET 40, SET RETRY 20
@End(Example)

You may redefine an existing macro in the same manner as you defined it.
You can undefine an existing macro by typing an empty DEFINE command for it,
for instance:
@Begin(Example,leftmargin +1)
DEFINE IBM
@End(Example)

You can list all your macros and their definitions with the SHOW MACROS
command.  Syntax of SET and DO commands may vary among Kermit programs.

@Section<The SHOW Command>
@Index<SHOW Command>
Syntax: @q<SHOW> [@i<option>]

The SHOW command displays the values of the parameters settable by the SET
command.  If a particular option is not requested, a complete display will be
provided.  Type "show ?" for a list of what can be shown.

@Section<The STATISTICS Command>
@index<Statistics>
Give statistics about the most recent file transfer, such as the total number
of characters transmitted, the effective baud rate, and so forth.  On some
systems, this is SHOW STATISTICS.

@Section<The LOG Command>
@Index<LOG Command>
Syntax: @q<LOG> [@i<option>] [@i<filespec>]

Log the specified entity to the specified log file.
@begin<description>
TRANSACTIONS@\Direct Kermit to log transactions, such as files successfully
sent or  received or files that could not be successfully sent or received.  A
transaction is useful recording the progress of a long, unattended multifile
transfer.

SESSION@\Create a transcript of a CONNECT session, when running a local Kermit
connected to a remote system, in the specified file.  The log is closed when
connection is closed.  In some implementations, logging can be "toggled" by
typing the connect escape character followed by Q (Quit logging) or R (Resume
logging) or similar single-@|character commands.  Session-@|logging is useful
for recording dialog with an interactive system, and for "capturing"
@index<Capturing Files> from systems that don't have Kermit.  No guarantee can
be made that the file will arrive correctly or completely, since no error
checking takes place.

DEBUGGING@\Record debugging information in the specified file.  There may
be several options to select the desired information -- entire packets,
state transitions, internal program trace, etc -- available via the SET
DEBUGGING command.

PACKETS@\Record packets, and all communication line traffice during file
transfer, in the specified file.
@end<description>

@section<The TRANSMIT Command>
@index<TRANSMIT Command>
Syntax: @q<TRANSMIT> @i<filespec>

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.  No guarantee can be made
that the target system will receive the file correctly and completely.  When
receiving a file, the target system would normally be running a text editor in
text collection mode.

The current communication settings, such as parity, flow control, and
handshake, are obeyed by most Kermit versions that have a TRANSMIT command.
The action is normally line-at-a-time.  Each line of the file is sent,
terminated by a carriage return (no linefeed), just as you would type it.
Kermit waits for the remote system to echo a linefeed (as it does when you
type carriage return) before it sends the next line.

Thus TRANSMIT provides a "raw upload" capability.  The opposite, "raw
download", may be accomplished by using the LOG SESSION command.

@Section<Login Scripts: The INPUT, OUTPUT, CLEAR, and PAUSE Commands>

@index<Login Scripts>@index<INPUT>@index<OUTPUT>@index<PAUSE>

When running Kermit in local mode, you may use the INPUT, OUTPUT, CLEAR, and
PAUSE commands to carry on a dialog with the remote system.  When combined into
a "script" in a Kermit TAKE command file, these commands provide the ability to
initially connect and log in to a remote system, and to set it up for file
transfer.  While you may do this yourself manually using the CONNECT command,
the login script facility allows this often tedious task to be automated, and
more important, allows it to take place unattended -- perhaps late at night
when the phone rates are low and the system is faster.

@Heading<The CLEAR Command>

Syntax: @q<CLEAR>

@index<CLEAR>
Clear the input and output buffers of the currently selected line, and attempt
to clear any XOFF deadlock.

@heading<The PAUSE Command>
@Index<PAUSE Command>
Syntax: @q<PAUSE> [@i<interval>]

Pause the specified number of seconds before executing the next command.
The default interval is one second.

@Heading<The INPUT Command>
@index<INPUT Command>
Syntax: @q<INPUT> [@i<interval>] [@i<string>]

@index<Timeout> On the currently selected communication line, look for the
given string for the specified interval of time, which is specified in seconds.
If no interval is specified, then wait for the default interval, which may be
specified by SET INPUT DEFAULT-TIMEOUT, and is normally 5 seconds.  Specifying
an interval of 0 (or less) means no timeout -- wait forever for the specified
string.  An INPUT command can normally be interrupted by typing one or more
Control-C's, which will return you to Kermit prompt level.

Characters coming in from the line will be scanned for the search string, and
when a match is found, the command will terminate successfully; if the string
is not found within the given interval, the command will terminate
unsuccessfully.

The search string may contain any printable characters.  Control or other
special characters that you could not normally type as part of a command
may be included by preceding their ASCII values
with a backslash, for instance @q<foo\13> is "foo" followed by a carriage
return (ASCII 13, decimal).  (Some Kermit programs expect or allow other
number bases, such as octal or hexadecimal.)

While scanning, alphabetic case is ignored ("a" = "A") unless you have SET
INPUT CASE OBSERVE.  If no search string is given, then the INPUT command will
simply display all incoming characters on your screen until it times out or is
interrupted.

If the INPUT command finds the specified string within the alloted amount of
time, it terminates immediately, without an error message, and the next command
will be executed.  If the INPUT command fails to find the requested string, it
will "fail"; failure is only significant if the command was issued from a TAKE
command, and INPUT TIMEOUT-@|ACTION is SET to QUIT.  When a timeout occurs
under these conditions, the command file is immediately terminated and control
is returned to the invoking level, either Kermit prompt level or a superior
command file.  If INPUT TIMEOUT-@|ACTION is SET to PROCEED, then the next
command (if any) will be executed from the current command file.

In addition to otherwise untypable control characters (like Control-C),
certain printable characters in the search string may need to be "quoted" using
the backslash mechanism, including at-sign, question mark, or other characters
that are significat to Kermit's command processor.

@heading<The OUTPUT Command>

Syntax: @q<OUTPUT> @i<string>

The given string is sent out the currently selected communication line.  The
string is in the same form as the INPUT string; control or special characters
may be included by prefacing their octal ASCII value with a backslash.  Note
that any terminating carriage return must be included explicitly as @q<\13>
(decimal).

@Heading<How to Use Login Scripts>

Login scripts are useful on computers that have autodialers or TTY ports
hardwired or otherwise connected to terminal ports on other systems.
Scripts can be used to automate the task of connecting and logging in.  For
instance, suppose your PC is connected to a VAX Unix system through a
hardwired line on communication port 2.  To send a file to the VAX, you must
connect to the VAX through the port, log in, run Unix Kermit, escape back
to the PC, and issue the appropriate file transfer commands, then
connect back to the VAX and logout.  This may all be automated by means of
the following "script" stored in a PC file invoked by the Kermit TAKE
command:
@begin<example>
set port 2
output \13
input login:
out myuserid\13
in 10 Password:
out mypassword\13
in 20 %
out kermit -r\13
send foo.bar
out \4
input
@end<example>
The first line points Kermit at the communication line.  The next line sends
a carriage return, which makes Unix issue a "@q<login:>" prompt; the following
INPUT command waits for this prompt to appear.  When it does, Kermit outputs
"myuserid" followed by a carriage return.  Unix then prompts for a password;
after the prompt appears, Kermit supplies the password.  Then, Kermit
waits up to 20 seconds for the Unix shell's "@q<%>" prompt; this allows time
for various system messages to be displayed.  When the shell prompt appears,
Kermit sends the command "kermit -r", which tells Unix Kermit to receive a
file; then a SEND command is given to the local Kermit.  After the file is
successfully transferred, Kermit sends a logout command (Control-D, "\4") to
Unix.  The final INPUT command causes Kermit to display any typeout (in this
case the Unix system's logout message) that occurs up to the default timeout
interval.

@index<INPUT>@index<Typeahead>
The INPUT command is very important, because it ensures synchronization.  One
might expect to be able to simply send all the characters out the communication
line at once, and let the remote host's typeahead and buffering facilities take
care of the synchronization.  In rare or simple cases, this might work, but it
assumes that (a) the remote host allows typeahead, (b) the remote host's
typeahead buffers are big enough to accommodate all the characters, @i<and> (c)
that the remote host never clears pending typeahead.  These conditions rarely
hold.  For instance, Unix clears its input buffer @i<after> issuing the
"@q<Password:>" prompt; any typeahead will be lost.  Interactive users as well
as login script facilities must wait for the prompt before entering the
password.  This is the function of the INPUT command.  On half duplex systems,
this function is critical -- these systems cannot accept any input in advance
of a prompt; there is no typeahead.

@index<SET INPUT>
The Kermit script facility is not a programming language; there is no
conditional execution of commands, no branching, no labels.  Nevertheless, the
SET INPUT command provides a degree of control.
If the Unix system were down in the sample script above, Kermit would
still proceed merrily through the entire script, sending its output into the
void and waiting the entire timeout interval on each INPUT command, then
attempting to send a file to a Kermit that wasn't there.  It could take several
minutes of timing out to terminate the script.  This could be avoided by
including the command
@example<SET INPUT TIMEOUT-ACTION QUIT>
at the top of the script.  When the "@q<login:>" prompt failed to appear within
the timeout interval, the rest of the script would be cancelled.

See the chapters on MS-DOS and DEC-20 Kermit for further examples of login
scripts.

@Include<mskerm>
@Include<ckuker>
@Include<ckmker>
@Include<ik0ker>
@Include<ikcker>
@Include<iktker>
@Include<vmsmit>
@Include<k20mit>
@Include<k11mit>
@Include<apple>
@Include<cpkerm>
@Include<c86ker>
@Include(ascii)
@PageHeading(Odd,Immediate,
    Left="@xx<Kermit User Guide>",
    Right="@yy<Page @ref(page)>",
    Line="@bar()@blankspace(2)")
@PageHeading(Even,
    Left="@yy<Page @ref(page)>",
    Right="@xx<Kermit User Guide>",
    Line="@bar()@blankspace(2)")
@Case(Device,x9700="@Comment<Begin Duplex Kludge>
@SendEnd(#Index `@begin<Transparent,PageBreak UntilOdd>@end<Transparent>')
@Comment<End Duplex Kludge>")
@Process(PageHeadings)