home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / archives / protocol.tar.gz / protocol.tar / kuser.mss < prev    next >
Text File  |  1988-11-08  |  119KB  |  2,536 lines

  1. @Comment(-*-SCRIBE-*-)
  2. @Comment(SCRIBE Text Formatter Input for the Kermit User Guide)
  3.  
  4. @Make<Manual>
  5. @Comment(Use /draft:F on command line to produce .LPT file w/cc in column 1)
  6.  
  7. @Style(Date="March 1952")
  8.  
  9. @case(device,postscript="@LibraryFile<Mathematics10>")
  10.  
  11. @String<Ellips="...">
  12.  
  13. @Style<Justification On, Hyphenation On, WidestBlank 1.4, Spacing 1,
  14.         Spread 1, Indent 0, HyphenBreak Off, SingleSided, PrintBlankPages Yes>
  15. @Use<Hyphendic="kuser.hyp">
  16.  
  17. @Modify<IndexEnv,Boxed,
  18.     Columns 2,ColumnMargin 0.4inch,LineWidth 3.35inch>
  19.  
  20. @Comment(Set desired spacing around various environments)
  21.  
  22. @Modify<Quotation,Indentation 0, Above 1, Below 1, Spacing 1>
  23. @Modify<Example, Above 1, Below 1, Blanklines Hinge>
  24. @Modify<Verbatim, Leftmargin 0>
  25. @Modify<Itemize, Above 1, Below 1, Spacing 1, Spread 1>
  26. @Modify<Enumerate, Above 1, Below 1, Spacing 1, Spread 1>
  27. @Modify<Description, Above 1, Below 1, Spacing 1>
  28.  
  29. @Define<MD,Use Display>
  30. @Define<Q,FaceCode R>
  31. @Define<QQ,FaceCode R,AfterEntry=["],BeforeExit=["]>
  32. @Define<SubH,Use Display,FaceCode R,Above 1.6,Below 1,need 6>
  33. @Define<SubU,Use UX,FaceCode R,Above 1.6,Below 1,need 6>
  34. @define<xx,use b>
  35. @define<yy,use i>
  36.  
  37. @Comment(Printing Device Dependencies)
  38.  
  39. @Case<Device,
  40.  LPT="@use(Auxfile='KERMLP.AUX')
  41.     @Case[Draft,F=`@Style(CarriageControl=FORTRAN)']
  42.     @Style(linewidth 72)
  43.     @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>",
  44.  Printronix="@use(AuxFile='KERMPX.AUX')
  45.     @Case[Draft,F=`@Style(CarriageControl=FORTRAN)']
  46.     @Style(LineWidth 74, PaperLength 11 inches,BottomMargin 5 spacings)",
  47.  PagedFile="@use(AuxFile='KERMPF.AUX')
  48.     @Style(LineWidth 79, PaperLength 10.8 inches)
  49.     @Style(TopMargin 3 spacings,BottomMargin 6 Spacings)
  50.     @Modify(Example,Leftmargin +2)",
  51.  Diablo="@Use(Auxfile='KERDIA.AUX')
  52.     @TypeWheel(Titan 10)
  53.     @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>",
  54.  Postscript="@Use(Auxfile='KERPS.AUX')
  55.     @Style<Doublesided>
  56.     @Style<Fontscale 10>
  57.     @Define<MD,Use Mathdisplay>
  58.     @String<Ellips='@Math(@Ldots)'>
  59.     @Define<xx,use b,Size 12>
  60.     @Define<yy,use i,Size 10>
  61.     @Define<Q,FaceCode T>
  62.     @Define(QQ,FaceCode T,AfterEntry=[@r<``>],BeforeExit=[@r<''>])
  63.     @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>
  64.     @Modify<Quotation,Size +0>
  65.     @Modify<Itemize,Spread 0.8>",
  66.  Imprint10="@Use(AuxFile='KERIMP.AUX')
  67.     @Define<Q,FaceCode U>
  68.     @Define(QQ,FaceCode U,AfterEntry=[@r<``>],BeforeExit=[@r<''>])
  69.     @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>
  70.     @Modify<Insert,Spacing 1>
  71.     @Modify<Verbatim,FaceCode U>
  72.     @Modify<Example,FaceCode U,spacing 1.2>
  73.     @Modify<Itemize,Spread 0.8>
  74.     @Style<FontFamily SmallRoman12,Spacing 1.6,SingleSided>",
  75.  Imagen300="@Use(AuxFile='KERIMP.AUX')
  76.     @Define<Q,FaceCode U>
  77.     @Define(QQ,FaceCode U,AfterEntry=[@r<``>],BeforeExit=[@r<''>])
  78.     @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>
  79.     @Modify<Insert,Spacing 1>
  80.     @Modify<Verbatim,FaceCode U>
  81.     @Modify<Example,FaceCode U,spacing 1.2>
  82.     @Modify<Itemize,Spread 0.8>
  83.     @Style<FontFamily SmallRoman12,Spacing 1.6,SingleSided>",
  84.  X9700="@Use<AuxFile='KERMX9.AUX'>
  85.     @Style<FontFamily Univers10, DoubleSided, Spacing 0.9, Spread 0.8>
  86.     @Style<Scriptpush No>
  87.     @define<xx,use b,font bodyfont>
  88.     @define<yy,use i,font bodyfont>
  89.     @Define<Q,FaceCode U>
  90.     @Define(QQ,FaceCode U,AfterEntry=[@r<``>],BeforeExit=[@r<''>])
  91.     @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>
  92.     @Modify<Description,Spacing 0.8,Spread 0.75> 
  93.     @Modify<Quotation,Spacing 0.8,Spread 0.75> 
  94.     @Modify<Enumerate,Spacing 0.8,Spread 0.75> 
  95.     @Modify(Verbatim,Spacing 0.8,Spread 0.75,FaceCode U)
  96.     @Modify<Example,FaceCode U, Spacing 1.1>
  97.     @Modify[Itemize, Numbered < @,- >, Spacing 0.8, Spread 0.5]",
  98.  X2700="@Use<AuxFile='KERMX2.AUX'>
  99.     @Style<FontFamily Times, DoubleSided On, Spacing 1, Spread 0.8>
  100.     @Style<Scriptpush No, WidowAction Force>
  101.     @define<xx,use b,font bodyfont>
  102.     @define<yy,use i,font bodyfont>
  103.     @Define<Q,FaceCode U>
  104.     @Define(QQ,FaceCode U,AfterEntry=[@r<``>],BeforeExit=[@r<''>])}
  105.     @comment{NYU specific - [at]Define(QQ,FaceCode U,
  106.     AfterEntry=[[at]Amr10<``>],BeforeExit=[[at]Amr10<''>])}
  107.     @Define<SubH,Use Display,FaceCode B,Above 1.6,Below 1>
  108.     @Modify<Description,Spacing 1,Spread 0.75> 
  109.     @Modify<Quotation,Spacing 1,Spread 0.75> 
  110.     @Modify<Enumerate,Spacing 1,Spread 0.75> 
  111.     @Modify(Verbatim,Spacing 1,Spread 0.75,FaceCode U)
  112.     @Modify<Example,FaceCode U, Spacing 1.1>
  113.     @Modify[Itemize, Numbered < @,- >, Spacing 1, Spread 0.5]"
  114.  >
  115. @Comment(Set spacing and paging requirements for chapter & section headings)
  116.  
  117. @Modify(Hdx,Above 2,Below 1,Need 8)
  118. @Modify(Hd0,Above 2,Below 1,Need 8)
  119. @Modify(Hd2,Above 2,Below 1,Need 8)
  120. @Modify(Hd3,Above 2,Below 1,Need 8)
  121. @Modify(Hd4,Above 2,Below 1,Need 8)
  122. @Modify<Heading, Above 2, Need 8>
  123. @Modify<Subheading, Above 1.5, Need 6>
  124.  
  125. @Pageheading<>
  126. @Begin(TitlePage,Initialize "@BlankSpace(2.4inches)",sink 0)
  127. @MajorHeading(KERMIT USER GUIDE)
  128.  
  129. @i<Seventh Edition>
  130.  
  131.  
  132.  
  133. Christine Gianone, Editor
  134.  
  135. Columbia University Center for Computing Activities
  136. New York, New York  10027
  137.  
  138.  
  139. May 26, 1988
  140.  
  141.  
  142.  
  143.  
  144.  
  145.  
  146.  
  147.  
  148.  
  149.  
  150.  
  151. Copyright (C) 1981,1988
  152. Trustees of Columbia University in the City of New York
  153.  
  154. @i<Permission is granted to any individual or institution to use, copy,
  155. or redistribute this document so long as it is not sold for profit, and
  156. provided this copyright notice is retained.>
  157.  
  158. @case[device, x9700 "@blankpage(1)"]@Comment{Duplex Kludge}
  159. @case[device, x2700 "@blankpage(1)"]@Comment{Duplex Kludge}
  160. @case[device, imprint10 "@blankpage(1)"]@Comment{Duplex Kludge}
  161. @end<titlepage>
  162. @PageHeading(Odd,Immediate,
  163.     Left="@xx<@Value[SectionNumber]. @Value[SectionTitle]>",
  164.     Right="@yy<Page @ref(page)>",
  165.     Line="@bar()@blankspace(2)")
  166. @PageHeading(Even,
  167.     Left="@yy<Page @ref(page)>",
  168.        Right="@xx<Kermit User Guide: @Title(Chapter) (@Value[SectionNumber])>",
  169.     Line="@bar()@blankspace(2)")
  170. @set(page=1)
  171. @PrefaceSection<PREFACE>
  172.  
  173. @i<Kermit> is the name of a protocol for transferring files from one computer
  174. to another over ordinary asynchronous terminal connections.  Kermit programs
  175. have been written for many different computers, and in general any two
  176. computers that have Kermit programs can exchange sequential files correctly and
  177. completely.  This manual gives a brief and general overview of what Kermit is
  178. and how to use it, but consists mostly of detailed instructions for use and
  179. installation of specific Kermit programs.
  180.  
  181. For a more detailed introduction to Kermit, complete with illustrations,
  182. diagrams, and tutorials, consult the book @i<Kermit, A File Transfer Protocol>,
  183. by Frank @w<da Cruz>, Digital Press, Bedford MA (1987), ISBN @w<0-932376-88-6>,
  184. DEC order number @w<EY-6705E-DP> (phone 1-800-343-8321).  The Kermit book
  185. describes Kermit in detail, from the points of view of the beginner, the user,
  186. the computer professional who must install Kermit programs or support their
  187. use, and the programmer who wishes to write new Kermit implementations.  Also
  188. included are general introductions to computers, data communications, and file
  189. organization, plus a detailed troubleshooting guide, bootstrapping hints, and
  190. various appendices and tables.  The latter half of the book is taken up by a
  191. complete description of the Kermit file transfer protocol, with programming
  192. examples in the C language, plus some analysis and comparisons of Kermit with
  193. other popular protocols such as Xmodem.
  194.  
  195. The seventh edition of the @i<Kermit User Guide> (May 1988) includes
  196. chapters on new releases of most major Kermit programs, including MS-DOS Kermit
  197. 2.30, VAX/VMS Kermit 3.3, Portable IBM Mainframe Kermit 4.0, Unix Kermit 4E,
  198. Macintosh Kermit, CP/M-80 Kermit 4.09, plus a new chapter on PDP-11 Kermit.
  199.  
  200. @Heading<History and Acknowledgements>
  201.  
  202. The Kermit file transfer protocol was designed at the Columbia University
  203. Center for Computing Activities (CUCCA) in 1981-82 by Bill Catchings and Frank
  204. @w<da@ Cruz>.  Bill wrote the first two programs, one for the DECSYSTEM-20 and
  205. one for a CP/M-80 microcomputer.
  206.  
  207. The initial objective was to allow users of our DEC-20 and IBM 370 timesharing
  208. systems to archive their files on microcomputer floppy disks.  The design owes
  209. much to the ANSI and ISO/OSI models, and some ideas were borrowed from similar
  210. projects at Stanford University and the University of Utah.  The protocol was
  211. designed to accommodate the "sensitive" communications front end of the
  212. full-@|duplex DEC-20 system as well as the peculiarities of half-@|duplex IBM
  213. mainframe linemode communications.  The protocol was soon implemented
  214. successfully on our IBM mainframe systems under VM/CMS by Daphne Tzoar of
  215. CUCCA.
  216.  
  217. Meanwhile it was becoming apparent that Kermit was useful for more than just
  218. file archiving; IBM PCs were beginning to appear in the offices and
  219. departments, and there arose a general need for file transfer among all our
  220. systems, as well as a need to use the IBM PCs as terminals.  Daphne soon had
  221. prepared an IBM PC implementation.
  222.  
  223. After our initial success with Kermit, we presented it at conferences of user
  224. groups like DECUS and SHARE, and began to get requests for it from other sites.
  225. Since we had written down a description of the protocol, some sites wrote their
  226. own implementations for new computers, or adapted one of our implementations to
  227. run on additional systems, and sent back these new versions to us so that we
  228. could share them with others.  In this way, Kermit has grown to support nearly
  229. 300 different machines and operating systems; it has been sent on magnetic tape
  230. or diskette from Columbia University to nearly ten thousand sites all over the
  231. world, and has reached many thousands more through various user groups and
  232. networks.
  233.  
  234. Thanks to the hundreds of individuals and institutions who have contributed
  235. to the Kermit storehouse over the years.
  236.  
  237. The Kermit protocol was named after Kermit the Frog, star of the television
  238. series @i<THE MUPPET SHOW>; the name Kermit is used by permission of Henson
  239. Associates, Inc., New York.
  240.  
  241. @Heading<Disclaimer>
  242.  
  243. Neither Columbia University, nor the editor, nor the authors of the individual
  244. chapters, nor any individual or institution contributing Kermit programs or
  245. documentation to the Columbia University Kermit Distribution, acknowledge any
  246. liability for any claims arising from use or misuse of Kermit programs or for
  247. inaccuracies in the documentation or bugs in the programs.  Kermit programs are
  248. produced on a voluntary basis and contributed freely for public use in the hope
  249. that they will be useful, but without any kind of warranty or guarantee, or
  250. any commitment to address or fix problems.  In practice, Kermit programs and
  251. documentation are contributed in good faith, and will be supported on a
  252. best-@|effort basis, time and other commitments permitting.
  253.  
  254. @Heading<Customizing This Manual>
  255.  
  256. Although the @i<Kermit User Guide> was produced at Columbia University, all
  257. attempts have been made to keep it free of site-@|specific information.
  258. However, due to the large number of Kermit implementations, descriptions of
  259. each one would make the manual prohibitively thick.  Therefore, the manual is
  260. sent from Columbia with specific documentation about a selection of systems.
  261. Some of these descriptions may not be of interest at your site, while others
  262. that are may be lacking.
  263.  
  264. Each site, upon receiving a Kermit tape, may decide which versions of Kermit
  265. are important to it, and include the appropriate documentation in this manual.
  266. This is most conveniently done if your site has the Scribe text formatting
  267. system (from UNILOGIC Ltd in Pittsburgh PA, USA), with which this manual was
  268. produced.  Scribe runs on a wide variety of systems.  There are also Scribe
  269. subsets, such as Perfect Writer and Final Word, that run on various
  270. microcomputers.  Many have asked why Scribe is used for Kermit manuals instead
  271. of TeX.  The answer is simply that TeX can only produce output for typesetters,
  272. not plain-text ASCII files, which are necessary for online documentation.
  273.  
  274. The system-specific parts of the Kermit User Guide are included with
  275. "@q<@@INCLUDE>" statements at the end of the Scribe source file for this
  276. manual, whose filename is @q<KUSER.MSS>.  You may add or delete @q<@@INCLUDE>
  277. statements to suit your needs, and run the result through the text formatter to
  278. produce a customized manual.  If you do this, you should include an indication
  279. on the title page that the manual has been customized for your site.
  280.  
  281. Not all system-specific documentation is provided in @q<.MSS> (Scribe input)
  282. format, since some Kermit contributors do not have Scribe at their sites.  In
  283. that case, you will either have to add Scribe formatting commands, or else
  284. enclose the whole subfile in @q<@@BEGIN(VERBATIM)...@@END(VERBATIM)> brackets
  285. (and replace all atsigns (@q<@@>) in the text with double atsigns (@q<@@@@>)).
  286.  
  287. If you do not have SCRIBE, you may still use an editor to delete or add
  288. sections to the finished documentation file, though the results will not be as
  289. satisfactory -- the table of contents, index, cross references, and page
  290. numbers will not be automatically adjusted.
  291.  
  292. If you are running a version of Kermit for which adequate documentation has not
  293. been provided (after all, this is a distributed, volunteer effort!), please
  294. feel free to write some, preferably in Scribe input format, and send it back to
  295. Columbia so that others may benefit from it.  Likewise if you produce a new
  296. implementation of Kermit.  If you don't know Scribe, you can use one of the
  297. existing chapters as a model.
  298.  
  299. @Unnumbered<How To Get Kermit>
  300.  
  301. The Kermit software is free and available to all, source code and documentation
  302. included, from a variety of sources.  For example, most universities are
  303. connected to academic computer networks from which the Kermit files at Columbia
  304. University can be reached.  The Kermit files are also available from many
  305. user groups, dialup information or bulletin board services, diskette
  306. reproduction services, and private volunteers.
  307.  
  308. Kermit software is not in the public domain.  The Kermit manuals and most
  309. Kermit programs bear copyright notices to protect Columbia University and the
  310. various contributors from having their work taken by others and sold as a
  311. product, for profit.  This is not to say that the Kermit file transfer protocol
  312. can never be included as a feature of a commercial product; the conditions
  313. under which this may be done are spelled out in a flyer @i<POLICY ON COMMERCIAL
  314. USE AND DISTRIBUTION OF KERMIT>.
  315.  
  316. Columbia University distributes Kermit programs by mail order on various
  317. magnetic media (primarily 9-track reel-to-reel tape and certain kinds of
  318. diskettes), charging a distribution fee to defray costs for media, printing,
  319. postage, materials, labor, and computing resources.  This is not a software
  320. license fee; no license is required.  To receive a current list of Kermit
  321. implementations, the statement on commercial policy, and a Kermit order form,
  322. write to:
  323.  
  324. @begin<format,leftmargin +4>
  325. Kermit Distribution
  326. Columbia University Center for Computing Activities
  327. 612 West 115th Street
  328. New York, NY  10025
  329. @end<format>
  330.  
  331. Everyone is free to copy and redistribute Kermit programs and documentation,
  332. and is encouraged to do so, with the following stipulations: Kermit programs
  333. should not be sold for commercial gain; credit should be given where it is due;
  334. and new material should be sent back to Columbia University at the address
  335. above so that we can maintain a definitive and comprehensive set of Kermit
  336. implementations for further distribution.
  337.  
  338. Since new Kermit programs are added -- and old ones improved -- so frequently,
  339. sites that use Kermit heavily are encouraged to contact Columbia for updates
  340. two or three times a year for news.
  341.  
  342. @blankspace(4)
  343. @Center(-- PLEASE USE KERMIT ONLY FOR PEACEFUL AND HUMANE PURPOSES --)
  344.  
  345. @Unnumbered<Organization of This Manual>
  346.  
  347. Chapter @ref<-using>, @i<How to Use Kermit>, describes the basics of text file
  348. transfer, and shows some specific examples.  If you follow the examples but you
  349. can't make a terminal connection or you can't transfer files successfully,
  350. consult Chapter @ref<-wrong>, @i<When Things Go Wrong>.
  351.  
  352. If you expect to be a heavy user of Kermit, you should read Section
  353. @ref<-commands>, @i<Kermit Commands>, which describes most of Kermit's features
  354. and commands.  You may find that familiarity with the material in this
  355. section will help you get past difficulties that can crop up when you are
  356. making new kinds of connections or transferring unusual kinds of files.
  357. You will also find descriptions of some advanced file management features
  358. that have been omitted from the earlier sections.
  359.  
  360. The subsequent chapters describe selected popular Kermit programs in detail.
  361. You should read the appropriate section for each system you expect to use; each
  362. section describes the file naming conventions and other system features that
  363. are important to Kermit users, and lists the Kermit commands for that system
  364. mainly in terms of their differences from the "ideal" Kermit described in
  365. section @ref<-commands>.
  366.  
  367. @Chapter<Introduction>
  368.  
  369. There is an ever-increasing need to move information from one computer to
  370. another.  Information can be exchanged using magnetic media -- tapes or disks
  371. -- or over networks.  Networks are expensive, and when your computer is not
  372. connected to one (or to the right one), you must find other means to transfer
  373. information.  In the early days of computing, magnetic media formats were
  374. relatively standardized, but with the arrival of microcomputers things have
  375. changed: most microcomputer users have no access to tapes, and disk formats
  376. are incompatible between most microcomputer makes and models.  Even when
  377. disk formats agree, the disk must be physically moved from one system to the
  378. other in order for information to be exchanged -- the effort and delay can be
  379. significant if the systems are widely separated.
  380.  
  381. The telecommunication line provides a cheap and widely available alternative to
  382. networks and magnetic media.  Asynchronous telecommunication is the method used
  383. by most terminals to connect to most computers.  When dedicated "hardwired"
  384. connections, such as those found between a timesharing computer and its local
  385. terminals, are not available, computer users can create their own dialup
  386. connections with a telephone and a modem.
  387.  
  388. Most computers come equipped with asynchronous telecommunications interfaces,
  389. or "serial ports", which allow them to act as, or communicate with, terminals.
  390. The question is how to use the serial port to exchange data.  Fortunately, the
  391. standards for connecting terminals to computers are almost universally
  392. followed: connector configuration (DB-25 or DB-9), transmission signals (EIA
  393. RS-232), a commonly accepted set of transmission speeds (baud rates), and a
  394. convention for encoding characters in storage and during transmission (ASCII).
  395. These standards provide the physical medium and the data format, but they do
  396. not specify a process for exchanging data.
  397.  
  398. @Section<Why Kermit?>
  399.  
  400. When data is transmitted from one computer to another; the receiving computer
  401. has to be instructed to take in the data and put it somewhere, and it also
  402. needs a way of ensuring that the data has been received correctly and
  403. completely in spite of several factors that will tend to interfere with this
  404. process:
  405.  @begin<enumerate>
  406. @i<Noise> -- @Index<Noise> It is rarely safe to assume that there will be no
  407. electrical interference on a line; any long or switched data communication line
  408. will have occasional interference, or noise, which typically results in garbled
  409. or extra characters.  Noise corrupts data, perhaps in subtle ways that might
  410. not be noticed until it's too late.
  411.  
  412. @i<Synchronization> -- Data must not come in faster than the receiving machine
  413. can handle it.  Although line speeds at the two ends of the connection must
  414. match before communication can take place, the receiving machine might not be
  415. able to process a steady stream of input at that speed.  Its central processor
  416. may be too slow or too heavily loaded, its buffers too full or too small, or
  417. its disk too slow.  The typical symptom of a timing problem is lost data; most
  418. operating systems will simply discard incoming data they are not prepared to
  419. receive.
  420. @End(Enumerate)
  421.  To prevent corruption of data and to synchronize communication, cooperating
  422. computers can send special messages to one another along with the data.
  423. Intermingling of control information with data together requires a set of rules
  424. for distinguishing messages from data, and specifying what the messages are and
  425. the actions associated with each message.  Such a set of rules is called a
  426. @i(protocol).
  427.  
  428. @Index[Kermit Protocol] Kermit is a file transfer protocol.  It is specifically
  429. designed for transfer of sequential files over ordinary telecommunication
  430. lines.  Kermit is not necessarily better than other terminal-@|oriented file
  431. transfer protocols but it is free, it is well documented, and it has been
  432. implemented compatibly on a wide variety of microcomputers, PCs, workstations,
  433. minicomputers, mainframes, and supercomputers.
  434.  
  435. @section<How Kermit Works>
  436.  
  437. Kermit transfers data by encapsulating it in @index<Packet> @i(packets) of
  438. control information.  This information includes a synchronization marker, a
  439. packet sequence number to allow detection of lost packets, a length indicator,
  440. and a "block check" to allow verification of the data, as shown in Figure
  441. @ref<-pktfig>.
  442. @begin(figure)
  443. @bar()
  444. @begin<example,leftmargin +4>
  445. +------+------+------+------+--------- - - - -+-------+
  446. | MARK | LEN  | SEQ  | TYPE | DATA            | CHECK |
  447. +------+------+------+------+--------- - - - -+-------+
  448. @End(Example)
  449. @caption(A Kermit Packet)
  450. @tag<-pktfig>
  451. @bar()
  452. @end(figure)
  453. The MARK (usually an ASCII Control-A character) appears at the beginning of the
  454. packet.  The next character is a length field (LEN), specifying how long the
  455. rest of the packet is.  The sequence number (SEQ) is used to detect lost or
  456. duplicated packets; retransmission is requested for lost packets and duplicate
  457. packets are discarded.  The TYPE field specifies whether the packet contains
  458. data or control information.  The CHECK field contains a quantity obtained by
  459. combining all the other characters in the packet together in one of several
  460. ways; the sender computes this value and sends it.  The packet receiver also
  461. computes the value and checks it against the value sent; if they agree, the
  462. packet is accepted; if they disagree, then the packet has been corrupted and
  463. retransmission is requested.  The DATA field contains up to 90 characters of
  464. data.  All fields except the mark are encoded as printable ASCII characters, to
  465. prevent host or network interference.  Figure @ref<-protofig> shows how a
  466. typical file transfer proceeds.
  467. @begin(figure)
  468. @bar()
  469. @begin(example,leftmargin +2)
  470. @u(Sender)                 @u(Receiver)
  471.  
  472. Send-Init ------------->         @i(Sender and Receiver exchange greetings)
  473.      <-------------------- ACK
  474.  
  475. File-Header ----------->         @i(Sender sends first file name to Receiver)
  476.      <-------------------- ACK   @i(Receiver acknowledges)
  477.  
  478. File-Data ------------->         @i(Sender sends first file data packet)
  479.      <-------------------- ACK   
  480.  
  481. File-Data ------------->         @i(Sender sends second file data packet)
  482.      <-------------------- ACK   
  483.  
  484. File-Data --xx~~~p'''-->         @i(Third data packet is corrupted by noise)
  485.      <-------------------- NAK   @i( and Receiver negatively acknowledges it)
  486.  
  487. File-Data ------------->         @i(Sender retransmits third packet)
  488.      <-------------------- ACK   
  489.  
  490. @i(File-Data packets are sent and acknowledged until the whole file is sent)
  491.  
  492. End-Of-File ----------->         @i(Sender indicates first file is complete)
  493.      <-------------------- ACK
  494.  
  495. File-Header ----------->         @i(Name second of file )
  496.      <-------------------- ACK
  497.  
  498. File-Data ------------->         @i(First data packet for second file)
  499.      <-------------------- ACK   
  500.  
  501. @i(File-Data packets are sent and ack'd until the whole file is sent)
  502.  
  503. End-Of-File ----------->         @i(Sender indicates second file is complete)
  504.      <-------------------- ACK
  505.  
  506. End-Of-Transaction ---->         @i(Sender indicates no more files to come)
  507.      <-------------------  ACK
  508. @end(example)
  509. @caption(Kermit File Transfer)
  510. @tag<-protofig>
  511. @bar()
  512. @end(figure)
  513. Figure @ref<-protofig> does not show how Kermit recovers from errors.
  514. Very briefly, here's how it works:
  515. @Begin(Itemize)
  516. If a packet is corrupted in transit by noise or loss of characters, the block
  517. check will be wrong.  A file receiver will NAK ("negatively acknowledge") a
  518. corrupted packet, which causes the sender to retransmit the same packet (or,
  519. alternatively, it will ACK the last correctly received packet again).  A
  520. file sender only receives ACKs and NAKs from the receiver; a corrupted ACK, or
  521. a NAK, from the receiver causes the sender to retransmit its most recent
  522. packet.
  523.  
  524. If the file sender does not receive an ACK within the prescribed timeout
  525. interval, it retransmits the same packet.  If the file receiver does not
  526. receive an expected packet within the timeout interval, it sends a NAK for the
  527. expected packet (or another ACK for the most recently correct packet).
  528. @End(Itemize)
  529. Many encoding, compression, block check, timeout, and packet length options
  530. are provided.  These options are automatically negotiated by the two Kermit
  531. programs when they initially make contact, and the greatest common set of
  532. features is used.  For this reason, any two Kermit programs should be able to
  533. communicate successfully, from the oldest, most bare-bones version, to the
  534. newest, most feature-laden version.  The protocol is described in detail in
  535. the Kermit book.
  536.  
  537. @Chapter<How to Use Kermit>
  538. @label<-using>
  539.  
  540. Kermit embodies a set of rules for transferring files reliably between two
  541. computers.  In general, one computer is a large system (a @i<host>, for
  542. instance a timesharing system with many terminals), and the other is a personal
  543. computer (PC).  The host believes that the PC is an ordinary terminal.  In
  544. order for the Kermit protocol to occur, a Kermit @i<program> must be running on
  545. each end of the communication line -- one on the host, one on the PC.
  546.  
  547. Your task is just to get the two Kermits started.  You have to use a single
  548. keyboard and screen to talk to two different computers, two different programs.
  549. Let's talk about a common case: you are sitting at a personal computer (PC),
  550. which has a serial communication port.  The serial port is connected to a host
  551. computer using, say, a dialup modem.
  552.  
  553.  Normally, when you use your PC, you are "talking" directly to it; your
  554. commands are interpreted directly by the PC's operating system (CP/M, MS-DOS,
  555. UNIX, etc), or by some program that runs on the PC (an editor, a text
  556. formatter, space invaders...).  The version of Kermit on your PC is a program
  557. like any other, but it has a special ability to either interpret your commands
  558. directly, like other programs, or to pass everything you type through to the
  559. other, remote computer.  When you tell Kermit to @index<CONNECT>CONNECT, it
  560. sends every character you type out the serial port, and it puts every character
  561. that comes in the serial port onto the screen.  This is called "terminal
  562. emulation" -- one computer acts as if it were a terminal to the other.  You are
  563. now "talking" to the remote computer, and the PC is (mostly) ignoring you.
  564.  
  565. Kermit, like most interactive programs, has a @i<prompt>@index<Prompt>.  The
  566. prompt is a string of characters it types on the left margin to indicate that
  567. it is ready for you to type a command.  Kermit's prompt is normally
  568. "@q<Kermit->@i<xx>@q(>)".  The @i<xx> identifies the implementation of Kermit;
  569. the Kermit that runs on MS-DOS systems is called "Kermit-MS" and its prompt is
  570. "@q(Kermit-MS>)"; the Kermit that runs on Z80 and 8080-@|based microcomputers
  571. is called "Kermit-80" and its prompt is "@q(Kermit-80>)", and so forth.  If you
  572. become confused about which Kermit you are talking to, the prompt should
  573. provide a clue.  In addition, most Kermits print an informative message like
  574.  @example<[Connecting to remote host, type CTRL-]C to return]>
  575.  when you CONNECT, and type another message like
  576.  @example<[Connection closed, back at PC]>
  577. when you return.
  578.  
  579. Having "connected" to the host, there must be a way for you to "get back" to
  580. the PC.  This is accomplished by an @i<escape sequence>@index<Escape Sequence>.
  581. As Kermit passes your characters through to the host, it checks each one to see
  582. if it's a special predefined @i<escape character>.  When the PC sees this
  583. character, it stops ignoring you -- you are once again "talking" to the PC, not
  584. to the host.  The escape character is normally chosen to be one that you will
  585. not need to type while talking to the host, and one that is hard to type by
  586. accident -- it's usually a @i<control character>@index<Control Characters>,
  587. such as Control-@q<]>, which is entered by holding down the key marked CTRL or
  588. CONTROL and typing the indicated character (in this case, a right bracket
  589. "@q<]>").  The CTRL key works just like a SHIFT key.  Control characters are
  590. written either as Ctrl-A or @q<^A>, where A is the character to be typed while
  591. holding down the Ctrl key.
  592.  
  593. @section<Transferring a File>
  594.  
  595. From system command level on your PC, first run the Kermit program.  Then tell
  596. Kermit to CONNECT you to the host.  Now you're talking to the remote host -- at
  597. this point you must log in, and then run Kermit on the host.
  598.  
  599. Now you have a Kermit program on each end of the connection.  The next step is
  600. to tell @i<each> Kermit what to do.  Suppose you want to transfer a file from
  601. the host to the PC; you would first tell the host Kermit to SEND the file, then
  602. "escape" back to the PC Kermit and tell it to RECEIVE the file.  The transfer
  603. begins -- you can sit back and watch, or go make yourself a sandwich.  The PC
  604. Kermit will produce a running display on your screen as the transfer proceeds,
  605. and will notify you when it is complete.
  606.  
  607. The desired file should now be on your PC's disk.  The Kermit protocol has
  608. ensured that the file arrived correctly and completely.  Now you must clean up
  609. after yourself: CONNECT back to the host, exit from Kermit on the host, log out
  610. from the host, "escape" back to PC Kermit and exit from it.  Now you can do
  611. whatever you had planned for your file -- edit it, print it on your PC printer,
  612. etc.  Transferring a file in the other direction works the same way, but with
  613. the SEND and RECEIVE commands exchanged.
  614.  
  615. The Kermit protocol, and most Kermit programs, allow you to send text files
  616. reliably from the host to the PC, from the PC to the host, from host to host,
  617. or PC to PC, usually without any special regard for the nature of the
  618. particular machines involved.  Most implementations also allow files to be sent
  619. in groups, with a single command, such as "@q<send *.*>"  The
  620. scenario for each of these is the same as above -- only the details of
  621. how to establish the actual connection differ.
  622.  
  623. Kermit works best with "printable" files -- files composed only of letters,
  624. digits, punctuation marks, carriage returns, tabs, and so forth -- since these
  625. can be represented on almost any kind of computer.  Kermit is also able to
  626. transfer "binary" files -- files such as executable programs -- composed of
  627. arbitrary bit patterns, but binary files normally are meaningful only to the
  628. kind of computer on which they are generated.  Nevertheless, Kermit can usually
  629. move such files from system A to system B (where they are not much use) and
  630. back to system A in their original condition, although in most cases special
  631. measures must be taken to accomplish this.
  632.  
  633. Let's look at some more concrete examples.  First you need to know what the
  634. basic Kermit commands are.
  635.  
  636. @section<Basic Kermit Commands>
  637. @Index[Kermit Commands]
  638.  
  639.  These are generic descriptions of the most basic Kermit commands.  Detailed
  640. descriptions will come later.  In these descriptions, @i<local>@index<Local>
  641. refers to the system that you are using directly, @i<remote>@index<Remote>
  642. refers to the system to which you are CONNECTed via Kermit.  Commands may take
  643. one or more operands on the same line, and are terminated by a carriage return.
  644.  
  645. @begin<description,leftmargin +4, indent -4>
  646. @Index[SEND]
  647. SEND @i(filespec)@\Send the file or file group specified by @i(filespec)
  648. from this Kermit to the other.  The name of each file is passed to the other
  649. Kermit in a special control packet, so it can be stored there with the same
  650. name.  A file group is usually specified by including
  651. "wildcard"@index<Wildcard> characters like "@q<*>" in the file specification.
  652. Examples:
  653. @begin(Example)
  654. send foo.txt
  655. send *.for
  656. @end(Example)
  657. Some implementations of Kermit may not support transfer of file groups; these
  658. versions would require a separate SEND command for each file to be transferred.
  659.  
  660. @Index[RECEIVE]
  661. RECEIVE@\Receive a file or file group from the other Kermit.  If an
  662. incoming file name is not legal, then attempt to transform it to a similar
  663. legal name.  Options are be provided for handling filename collisions.
  664.  
  665. @Index[CONNECT]@Index[Virtual Terminal]
  666. CONNECT@\Make a terminal connection to the remote system.  To "escape" from the
  667. terminal connection, type Kermit's @Index[Escape Character] @i<escape
  668. character> (e.g.@ @q<CTRL-]>, control-@|rightbracket), followed by the letter
  669. "C" for "Close Connection".
  670.  
  671. @Index[SET]
  672. SET@\Establish various nonstandard settings, such as CONNECT escape character,
  673. file characteristics, communication line number, speed (baud rate),
  674. parity, or flow control.  All of these are explained later.
  675.  
  676. SHOW@\@Index[SHOW](or STATUS) Display the values of SET options.
  677.  
  678. HELP@\Type a summary of Kermit commands and what they do.
  679.  
  680. EXIT@\Exit from Kermit back to the host operating system.
  681.  
  682. @q(?)@\Typed almost anywhere within a Kermit command: 
  683. List the commands, options, or operands that are possible at this point.
  684. This command may or may not require a carriage return, depending on the host
  685. operating system.
  686. @end<description>
  687.  
  688. @section<Real Examples>
  689.  
  690. Kermit can be used in several ways: from a PC that is connected to
  691. a larger host computer; from a host computer which is connected
  692. to another host; from one PC to another.
  693.  
  694. @SubSection<PC to Host>
  695. In this example, the user is sitting at an IBM Personal Computer (PC), which
  696. is connected through its serial port to a DEC VAX/VMS host computer.  The IBM
  697. PC is @i<local>, the VAX is @i<remote>.  This example will also apply almost
  698. literally to any other microcomputer implementation of Kermit.
  699.  
  700. You have started up your PC and have the Kermit program on your disk.  Begin by
  701. running Kermit on the PC.  Use Kermit's CONNECT command to become a terminal to
  702. the VAX.  In fact, the PC emulates the popular DEC VT-102 (VT-100), so
  703. so it is desirable to tell the host that your terminal is of this type.
  704. Login on the VAX and run Kermit there.  Here is an example of this procedure
  705. with commands you type underlined; the material lined up on the right is
  706. commentary, not system typeout or part of a command:
  707. @Begin<Example>
  708. @tabclear@tabDivide(3)
  709. A>@u[Kermit]@\@i(Run Kermit on the PC.)
  710. Kermit-MS V2.30
  711. IBM-PC Kermit-MS: V2.30  8 Jan 88
  712. Type ? for help
  713.  
  714. Kermit-MS>@\@i(This is the Kermit prompt for the PC.)
  715. Kermit-MS>@u[connect]@\@i(Connect to the VAX.)
  716. [Connecting to host, type Control-] to return to PC]
  717.  
  718. @\@i(You are now connected to the VAX.)
  719.  
  720. Welcome to CUMIN, MicroVMS V4.6@ @ @ @ i(The system prints its herald.)
  721.  
  722. Username: @ux<my-id>@\@i(Type your user ID.)
  723. Password: @ux<my-password>@\@i(Type your password.)
  724.  
  725. @i<(Various greeting or notice messages are displayed.)>
  726.  
  727. $ @\@i(This is the VMS system prompt.)
  728. $ @u[Kermit]@\@i(Run Kermit on the VAX.)
  729.  
  730. VMS Kermit-32 version 3.3.111
  731. Default terminal for transfers is: _TXA0:
  732. Kermit-32>@\@i(This is VMS Kermit's prompt.)
  733. @End<Example>
  734. You are now ready to transfer files between the two machines.
  735.  
  736. The following example illustrates how to send files from the VAX to
  737. the PC.  Note the use of the "*" @i<wildcard>@index<wildcard>
  738. character to denote a @i<file group>.
  739. @Begin<Example>
  740. @tabclear@tabDivide(3)
  741. Kermit-32>@ux[send *.for]@\@i(Send all my FORTRAN files.)
  742. @ux<^]c>@\@i(Now return back to the PC by)
  743. @\@i(typing the escape sequence, in this case)
  744. @\@q(^]C) @i((Control-@q(]) followed by "C"))
  745. [Back at PC.]
  746. Kermit-MS>@u[receive]@\@i(Tell the PC that files are coming.)
  747. @End<Example>
  748.  
  749. If you take more than about 5 seconds to get back to Kermit-MS and issue the
  750. @Index[RECEIVE] @c<receive> command, the first packets from Kermit-32 may
  751. arrive prematurely and appear on your screen, but no harm will be
  752. done because the packet will be retransmitted by the VAX until the PC
  753. acknowledges it.
  754.  
  755. Once the connection is established, the PC will show you what is happening --
  756. it first clears the screen and waits for incoming packets; as packets arrive,
  757. the current file name and packet number will be continuously displayed on the
  758. screen.  When the PC's @q("Kermit-MS>") prompt returns to your screen (with an
  759. accompanying beep to catch your attention) the transfer is done.  Notice the
  760. screen display; the status should be indicated as "complete".  If not, an error
  761. has occurred and an appropriate message should be displayed to tell you why.
  762.  
  763. After you're finished transferring files, you must CONNECT back to the VAX
  764. host, EXIT from Kermit there, logout, and "escape back" to the PC as you did
  765. previously:
  766. @Begin<Example>
  767. @tabclear@tabDivide(3)
  768. Kermit-MS>@ux[connect]@\@i(Get back to the VAX.)
  769. [Connecting to host. Type CTRL-]C to return to PC.]
  770. Kermit-32>@\@i(Here we are.)
  771. Kermit-32>@u[exit]@\@i(Get out of VMS Kermit.)
  772. $ @ux<logout>@\@i(Logout from the VAX.)
  773.  
  774. MY-ID   logged out at 25-JAN-1988 15:12:27.85
  775.  
  776. @ux<^]c>@\@i(Now "escape" back to the PC,)
  777. [Back at PC.]
  778. Kermit-MS>@ux<exit>@\@i(and exit from the PC's Kermit.)
  779. A>@\@i(Now you see the DOS prompt again.)
  780. @End<Example>
  781. The files you transferred should now be on your PC disk.
  782.  
  783. To send files from the PC to the VAX, follow a similar procedure.  First
  784. follow the instructions in the previous section to log in to the VAX through
  785. the PC.  Then in response to the host Kermit's "@q(Kermit-32>)" prompt you type
  786. @Index[RECEIVE] RECEIVE rather than SEND.  Now escape back to the PC and use
  787. the @Index[SEND] SEND command to send the local PC files to VAX.  The
  788. PC will show you the progress of the transmission on its screen.
  789.  
  790. When the "@q(Kermit-MS>)" prompt indicates that the transmission is complete
  791. you should follow the procedure shown above to logout from the VAX host,
  792. except that you may first wish to confirm that the files have been stored
  793. correctly in your directory on the VAX.
  794.  
  795. @SubSection<Host to Host>
  796. A "host" is considered to be a large or multi-user system, whose distinguishing
  797. characteristic is that it has multiple terminals.  Use of Kermit for
  798. host-@|to-@|host file transfers differs from the PC-@|to-@|host case in that
  799. the line your terminal is connected to is not the same as the line over which
  800. the data is being transferred, and that some special SET commands may have to
  801. be issued to allow one Kermit to conform to unusual requirements of the other
  802. host.
  803.  
  804. In this example, you are already logged in to a Unix system, and you use an
  805. @index<Autodialer>@i<autodialer> to connect to an IBM 370-@|series system
  806. running VM/CMS@index<VM/CMS> through Unix device @q</dev/tty12>.
  807. @Begin<Example>
  808. @tabclear@tabDivide(3)
  809. % @ux[kermit]
  810. C-Kermit, 4E(070) 24 Jan 88, 4.2 BSD
  811. Type ? for help
  812. C-Kermit>@ux[set modem hayes]
  813. C-Kermit>@ux[set line /dev/tty12]
  814. C-Kermit>@ux[set speed 1200]
  815. C-Kermit>@ux[dial 7654321]
  816. Connected!
  817. @End<Example>
  818. Other methods exist for connecting two hosts with a serial line.  For instance,
  819. dedicated hookups can be made by running an RS-232 "null modem" cable between
  820. TTY ports on the two systems (null modem cables, RS-232 signals, modems, and
  821. other data communication apparati are described in detail in the Kermit book).
  822. The following procedure would be the same in any case, once a connection is
  823. made.  The four "set" commands below are necessary when connecting to IBM
  824. mainframes in "linemode" (as opposed to full-screen 3270 mode; if you don't use
  825. IBM mainframes, you can ignore them for now).
  826. @Begin<Example>
  827. @tabclear@tabset(3inch)
  828. C-Kermit>@ux[set duplex half]@\@i(The IBM mainframe is half duplex.)
  829. C-Kermit>@ux[set flow none]@\@i(No full duplex XON/XOFF.)
  830. C-Kermit>@ux[set handshake xon]@\@i(Use XON for line turnaround handshake.)
  831. C-Kermit>@ux[set parity mark]@\@i(Our IBM system uses mark parity.)
  832. C-Kermit>@ux[connect]@\@i(Connect to the mainframe.)
  833. Connecting thru /dev/tty31, speed 1200.
  834. The escape character is CTRL-\ (28).
  835. Type the escape character followed by C to get back,
  836. or followed by ? to see other options.
  837. @\@i<(Type carriage return here.)>
  838. VM/370 ONLINE@\@i(The IBM system prints its herald.)
  839.  
  840. .@ux[login myuserid mypassword]@\@i(Login to IBM system.)
  841.  
  842. LOGON AT 15:33:02 EST MONDAY 02/08/88
  843. CUVMA CMS 3.1 8409 01/25/85
  844. .
  845. .@ux[Kermit]
  846. Kermit-CMS Version 4.0 (87/12/17)
  847. Enter ? for a list of valid commands
  848.  
  849. Kermit-CMS>.@ux[send profile exec]
  850. @ux<^\c>@\@i(C-Kermit's escape sequence typed here.)
  851. [Back at Local System]
  852. C-Kermit>@ux[receive]@\@i(Tell Unix Kermit to RECEIVE.)
  853. @End<Example>
  854. The transfer takes place now; Unix Kermit will print the names of incoming
  855. files, followed by dots or percents to indicate the packet traffic (a dot for
  856. every 4 packets successfully transferred, a percent for every timeout or
  857. retransmission).  The transfer is complete when when you see "@q<[OK]>", a beep
  858. is sounded, and the C-Kermit prompt next appears.  At that point we connect
  859. back to the remote IBM system, exit from the remote Kermit and log out.
  860. @Begin<Example>
  861. @tabclear@tabDivide(3)
  862. .
  863. profile.exec ..%%.[OK]
  864. C-Kermit>@ux[connect]@\@i(Get back to mainframe and clean up.)
  865.  
  866. Kermit-CMS>.
  867. Kermit-CMS>.@u[exit]
  868. R;
  869. .
  870. SP/CMS
  871. .logout
  872.  
  873. CONNECT= 00:03:01 VIRTCPU= 000:00.12 TOTCPU= 000:00.60
  874. LOGOFF AT 15:40:13 EST MONDAY 02/08/88
  875.  
  876. @ux[^\c]@\@i(Type C-Kermit's escape sequence)
  877. [Back at Local System]
  878. C-Kermit>@u[exit]@\@i(All done with Kermit.)
  879. @End<example>
  880. That's the whole procedure.  The file is in your Unix directory, completely
  881. readable, as @q<profile.exec> -- note that Kermit-CMS translated from the IBM
  882. EBCDIC character encoding into standard ASCII, and converted the space
  883. between the file name and file type to a dot.
  884.  
  885. To send a file from the local host to the remote host, we would merely have
  886. reversed the SEND and RECEIVE commands in the example above.
  887.  
  888. @subsection<Micro to Micro>
  889.  
  890. Kermit also works between personal computers (microcomputers, workstations).
  891. The difference here is that commands are typed on @i<two> keyboards, rather
  892. than a single one.  This is because a personal computer normally only accepts
  893. commands from its own keyboard.  If one PC Kermit CONNECTs to another, there
  894. will normally be no program on the other side to listen.
  895.  
  896. You can make the physical connection between two micros in two ways: direct or
  897. dialup.  If the two units are in close proximity (say, 50 feet or less), you
  898. can connect their serial ports with a null modem@index<Null Modem>
  899. cable@index<Cables>.
  900.  
  901. Connections at longer distances can be made via dialup, providing the required
  902. modems are available (one side needs @index<Autoanswer>autoanswer capability),
  903. or using any kind of dedicated or switched circuit that may be available --
  904. CBX, port contention unit, almost anything you can plug an EIA connector into.
  905.  
  906. In this example, a DEC VT180 "Robin" CP/M-80 microcomputer is connected to a
  907. Intertec "SuperBrain" CP/M-80 micro, using a female-@|to-@|male null modem
  908. cable (these systems have nostalgia value, being among the first for which
  909. Kermit programs were written).  The connection can be tested by running Kermit
  910. and issuing the CONNECT command on both ends: typein from each micro should
  911. appear on the screen of the other.
  912.  
  913. Suppose you want to send a file @q<FOO.HEX> from the Robin to the SuperBrain.
  914. Proceed as follows:
  915. @begin<enumerate>
  916. Run Kermit on the SuperBrain, and give the RECEIVE command:
  917. @begin[example]
  918. A>@u(Kermit)
  919. Intertec SuperBrain Kermit-80 - V4.09
  920. Kermit-80>@u<receive>
  921. @end[example]
  922.  
  923. Run Kermit on the Robin, and give the SEND command for @q<FOO.HEX>.
  924. @begin[example]
  925. A>@u(Kermit)
  926. DEC VT18X Kermit-80 - V4.09
  927. Kermit-80>@ux(send foo.hex)
  928. @end[example]
  929. Watch the packets fly.  When you get the next @q(Kermit-80>) prompt, the
  930. transfer is done, and you can EXIT from both Kermits.
  931. @end<enumerate>
  932. The key point is to start the @i<receiving> end first -- some microcomputer
  933. Kermits do not include a timeout facility, and if the receiver is not ready to
  934. receive when the sender first sends, there will be a protocol deadlock.
  935.  
  936. @section<Another Way -- The Kermit Server>
  937.  
  938. So far, we have been describing the bare-@|bones version of the Kermit
  939. protocol.  An optional extension to the protocol includes the concept of a
  940. @i<Kermit server>@index<Kermit server>@index<Server>.  A Kermit server is a
  941. Kermit program that does not interact directly with the user, but only with
  942. another Kermit program.  You do not type commands to a Kermit server, you
  943. merely start it at one end of the connection, and then type all further
  944. commands at the other end.
  945.  
  946. Not all implementations of Kermit can be servers, and not all know how to talk
  947. to servers -- but most of the major ones can and do.  The server is run on the
  948. remote computer, which would normally be a timesharing system, such as an IBM
  949. mainframe, a Unix system, or VAX/VMS, but may be a minicomputer or even a PC.
  950. It depends on whether the particular Kermit program has a "server" command.
  951. You must still connect to the remote host to log in and start the server, but
  952. you no longer have to tell one side to SEND and the other to RECEIVE, nor must
  953. you connect back to the remote side to clean up and log out when you're done.
  954. Using the server, you can do as many send and receive operations as you like
  955. without ever having to connect back to the remote host.  Some servers also
  956. provide additional services, such as directory listings, file deletion, or disk
  957. usage inquiries.
  958.  
  959. A Kermit server is just a Kermit program running in a special way.  It acts
  960. much like ordinary Kermit does after you give it a RECEIVE command -- it waits
  961. for a message from the other Kermit, but in this case the message is a command
  962. saying what to do, normally to send or to receive a file or group of files.
  963. After escaping back to the local system, you can give as many SEND and GET
  964. commands as you like, and when you're finished transferring files, you can give
  965. the @index<BYE>BYE command, which sends a message to the remote Kermit server
  966. to log itself out.  You don't have to connect back to the remote host and clean
  967. up.  However, if you @i<want> to connect back to the host, you can use the
  968. FINISH@index<FINISH> command instead of BYE, to shut down the Kermit server on
  969. the remote host without logging it off, allowing you to CONNECT back to your
  970. job there.
  971.  
  972. Here's an example of the use of a Kermit server.  The user is sitting at an
  973. IBM PC and a DECSYSTEM-20 is the remote host.
  974. @Begin<Example>
  975. @tabclear@tabDivide(3)
  976. A>@u[Kermit]@\@i(Run Kermit on the micro.)
  977. Kermit-MS V2.30
  978. IBM-PC Kermit-MS: V2.30  8 Jan 88
  979. Type ? for help
  980.  
  981. Kermit-MS>@\@i(This is the Kermit prompt for the PC.)
  982. Kermit-MS>@u[connect]@\@i(Connect to the VAX.)
  983.  
  984. CU20B@\@i(The DEC-20 prints its herald.)
  985. @@@ux[login my-id password]@\@i(Log in normally.)
  986. @end<example>
  987. @i<(The DEC-20 prints various login messages here.)>
  988. @Begin<Example>
  989. @tabclear@tabDivide(3)
  990. @@@u[Kermit]@\@i(Run Kermit-20 normally)
  991. Kermit-20>@u[server]@\@i(Tell it to be a server.)
  992.  
  993. Kermit Server running on DEC-20 host.  Please type your escape 
  994. sequence to return to your local machine.  Shut down the server by 
  995. typing the Kermit BYE command on your local machine.
  996.  
  997. @u<^]c>@\@i(Now escape back to the PC.)
  998.  
  999. Kermit-MS>@ux[get *.pas]@\@i(Get all my DEC-20 Pascal programs.)
  1000. Kermit-MS>@ux[send foo.*]@\@i(Send all the "foo" files from my PC.)
  1001. Kermit-MS>@ux[exit]@\@i(Exit from Kermit back to DOS.)
  1002. A>
  1003. @end<example>
  1004. @i<(Here you can do some work on the micro, edit files, whatever you like.)>
  1005. @Begin<Example>
  1006. @tabclear@tabDivide(3)
  1007. A>@u<Kermit>@\@i(Run Kermit-80 some more.)
  1008. Kermit-MS>@ux[send file.pas]@\@i(Send another file.)
  1009. Kermit-MS>@ux[bye]@\@i(That's all.  Shut down the Kermit server.)
  1010. A>@\@i(Back at DOS automatically.)
  1011. @End<Example>
  1012. This is @i<much> simpler.  Note that once you've started the Kermit Server
  1013. on the remote end, you can run Kermit as often as you like on the micro without
  1014. having to go back and forth any more; just make sure to shut the server down
  1015. when you're done by typing the BYE command.
  1016.  
  1017. If it's so much simpler, why not do it this way all the time?  You can,
  1018. provided your remote Kermit has a "server" command.  But server operation,
  1019. plus the special commands the local Kermit needs to communicate with the
  1020. server (GET, REMOTE, BYE, FINISH) are optional Kermit features, so some
  1021. Kermit programs might not have them.  All Kermit programs, however, should
  1022. provide the basic SEND/RECEIVE mode of operation.
  1023.  
  1024. Here are the basic commands available for talking to servers:
  1025. @begin<description>
  1026. @Index[SEND]
  1027. SEND @i(filespec)@\Sends a file or file group from the local host to the
  1028. remote host in the normal way.
  1029.  
  1030. @Index[GET]
  1031. GET @i(filespec)@\Ask the remote host to send a file or file group.
  1032. Example:
  1033. @example[get *.c]
  1034. This command is exactly equivalent to typing "@w[send @q<*.c>]" at the remote
  1035. host followed by "receive" on the local host.  Note that the local Kermit does
  1036. not attempt to validate the filespec.  If the server cannot access the
  1037. specified file(s), it will send back an appropriate error message.  Please note
  1038. that GET and RECEIVE are not the same!  RECEIVE tells Kermit to passively wait
  1039. for a file.  GET actively sends a request to a Kermit server to send the
  1040. named file.
  1041.  
  1042. @index<REMOTE>
  1043. REMOTE @i(command) [@i(argument)]@\Ask the server to perform the specified
  1044. command, and send the results to your screen.  Not all servers are capable of
  1045. performing REMOTE commands; those that can most commonly provide REMOTE
  1046. DIRECTORY, REMOTE DELETE, REMOTE SPACE, and similar file management services.
  1047.  
  1048. @index<BYE>
  1049. BYE@\Shut down the remote server and exit from Kermit.  This
  1050. will cause the job at the remote end to log itself out.  You need not connect
  1051. back and clean up unless you get an error message in response to this command.
  1052.  
  1053. @index<FINISH>
  1054. FINISH@\Shut down the server without having it log itself out, and don't
  1055. exit from Kermit.  A subsequent CONNECT command will put you back at your job
  1056. on the remote host, at system command level.
  1057. @end<description>
  1058.  
  1059. @index<Server>
  1060. Server operation is not limited to mainframes.  Some PC Kermit implementations
  1061. can also act as servers, notably MS-DOS and Unix.  For instance, an IBM PC at
  1062. the office with an autoanswer modem can be left in server mode at the end of
  1063. the day, and then dialed up from home in the evening for file transfer.
  1064.  
  1065. @Chapter<When Things Go Wrong>
  1066. @label<-wrong>
  1067. @Index[Error Recovery]
  1068. Connecting two computers can be a tricky business, and many things
  1069. can go wrong.  Before you can transfer files at all, you must first
  1070. establish terminal communication.  But successful terminal connection does not
  1071. necessarily mean that file transfer will also work.  And even when file
  1072. transfer seems to be working, things can happen to ruin it.  The following
  1073. sections treat a few basic problems.  See the troubleshooting section of the
  1074. Kermit book for greater detail.
  1075.  
  1076. @Section<Basic Connection Problems>
  1077.  
  1078. If you have a version of Kermit on your microcomputer, but the CONNECT command
  1079. doesn't seem to work at all, please:
  1080. @begin<itemize>
  1081. Make sure all the required physical connections have been made and have not
  1082. wiggled loose.  If you are using a modem, make sure the carrier light is on.
  1083.  
  1084. If you have more than one connector on your micro, make sure you are using the
  1085. right one.
  1086.  
  1087. Make sure that the port is set to the right communication speed, or @i<baud
  1088. rate>.  Some versions of Kermit have a built-@|in SET BAUD or SET SPEED
  1089. command, others require that you set the baud rate using a system command or
  1090. setup mode before you start the Kermit program.  Some versions of Kermit have
  1091. SHOW or STATUS commands that will tell you what the current baud rate is.
  1092.  
  1093. Make sure that the other communication line parameters, like parity, bits per
  1094. character, handshake, and flow control are set correctly.
  1095. @end<itemize>
  1096. You may have to consult the appropriate manuals for the systems and equipment
  1097. in question.
  1098.  
  1099. @index<Internal Modem>
  1100. If all settings and connections appear to be correct, and communication still
  1101. does not take place, the fault may be in your modem.  Internal modems (i.e.
  1102. those that plug in to a slot inside the microcomputer chassis) are @i<not>
  1103. recommended for use with Kermit unless they totally mimic the asynchronous
  1104. serial port hardware they purport to replace, or unless the Kermit program
  1105. claims to support the particular internal modem.  Many microcomputer Kermit
  1106. programs are written to control the communication hardware explicitly; internal
  1107. modems can interfere with that control.
  1108.  
  1109. Even external modems can cause trouble -- the "smarter" they are, the more
  1110. potential danger of disagreement between the modem and the microcomputer about
  1111. settings of baud rate, character framing, echo, and so forth.  Make sure your
  1112. modem is set up correctly (consult your modem manual).
  1113.  
  1114. @Section<Terminal Connection Works But The Transfer Won't Start>
  1115.  
  1116. Once you've made a terminal connection to the remote system, you will generally
  1117. also be able to transfer files.  But not always.  If Kermit's terminal
  1118. emulation seems to work correctly, but a file transfer will not start at all,
  1119. then something in the communication path is probably interfering with the
  1120. packet data:
  1121. @Begin(Description,leftmargin +4, indent -4)
  1122. PARITY:@\
  1123. A device can impose @i<parity> upon the communication line.  This means that
  1124. the 8th bit of each character is used by the equipment to check for correct
  1125. transmission.  Use of parity will:
  1126. @Begin(Itemize)
  1127. Cause packet checksums to appear incorrect to the receiver and foil any attempt
  1128. at file transfer.  In most cases, not even the first packet will get through.
  1129.  
  1130. @Index<Binary Files>
  1131. Prevent the use of the 8th bit for binary file data.
  1132. @End(Itemize)
  1133. If terminal connection works but file transfer does not, parity is the most
  1134. likely culprit.  To overcome this impediment, you should find out what parity
  1135. is being used, and inform the Kermits one side or both (using the SET PARITY
  1136. command) so that they can:
  1137. @Begin(Itemize)
  1138. Compose and interpret the checksums correctly.
  1139.  
  1140. Employ a special encoding to allow 8-bit data to pass through the 7-bit
  1141. communication channel.
  1142. @End(Itemize)
  1143. Many packet-switched networks, such as GTE TELENET, require parity to be 
  1144. set, as do IBM mainframes and their front end processors.
  1145.  
  1146. @index<Echo>
  1147. ECHOING:@\Some communication processors, typically front ends, echo their
  1148. input.  When this happens, every Kermit packet that is sent to it will bounce
  1149. right back, causing no end of confusion.  Some Kermit programs have been
  1150. designed to ignore echoed packets, but others have not.  If you encounter this
  1151. problem, there are several possible solutions:
  1152. @Begin(Itemize)
  1153. Disable the front end echoing by typing some special command, if such a command
  1154. is provided by the system.
  1155.  
  1156. Some front ends respond to certain escape or control sequences as commands
  1157. to turn off echoing, either from that point onward, or else on a per-@|line
  1158. basis.    In this case, the appropriate control sequence can be inserted between
  1159. packets by Kermit programs instructed to do so, for instance using the
  1160. SET PAD command.
  1161.  
  1162. If the echoing cannot be disabled, then the two Kermit programs should be
  1163. instructed to use differing packet start markers, using the SET START-OF-PACKET
  1164. command -- for instance, one Kermit uses Control-A as usual, and the other uses
  1165. Control-B.  This can only be done if both Kermits have this SET command.
  1166. @end(Itemize)
  1167. @End(Description)
  1168.  
  1169. @Section<Special Characters>
  1170.  
  1171. There is one problem that can prevent a file transfer from starting at all, or
  1172. may crop up after the file transfer is underway.  For instance, during a file
  1173. transfer operation you might find your smart modem suddenly hanging up your
  1174. current connection and placing a call to Tasmania.  Or you might find that
  1175. packets containing a certain character like "@q<@@>" cannot be transmitted
  1176. successfully.
  1177.  
  1178. This is the problem of "special characters".  Some device in the communication
  1179. path -- a front end, a port switcher, a multiplexer, a "smart" modem --
  1180. interprets certain characters in the data stream as commands rather than as
  1181. data to be passed them along to the other side.  Usually such equipment
  1182. interferes only with the transmission of ASCII control characters; so long as
  1183. Control-A and Carriage Return -- Kermit's normal packet start and end
  1184. delimiters -- are not molested, then Kermit can operate.  However, equipment
  1185. may exist which swallows even printable characters.  Since Kermit assumes that
  1186. ALL printable ASCII characters (ASCII 40 through 176, octal) can be transmitted
  1187. without interference or modification, such equipment will prevent Kermit file
  1188. transfer unless its printable-@|character-@|swallowing features can be
  1189. disabled.
  1190.  
  1191. @Section<The Transfer Starts But Then Gets Stuck>
  1192.  
  1193. Once a Kermit file transfer has begun, there are certain conditions under which
  1194. it can become stuck.  Since many hosts are capable of generating timeout
  1195. interrupts when input doesn't appear within a reasonable interval, they can
  1196. resend unacknowledged packets or request that missing packets be retransmitted.
  1197. But since not all Kermit programs are capable of timing out, a means for
  1198. manual intervention is provided in the local Kermit -- you can type a carriage
  1199. return on the keyboard of most micros to wake up and continue the transfer.
  1200.  
  1201. The following sections discuss various reasons why a transfer in progress could
  1202. become stuck.  Before examining these, first make sure that you really have a
  1203. Kermit on the other end of the line, and you have issued the appropriate
  1204. command: SEND, RECEIVE, or SERVER.  If the remote side is not a server,
  1205. remember that you must connect back between each transfer and issue a new SEND
  1206. or RECEIVE command.
  1207.  
  1208. @subSection<The Connection is Broken>
  1209.  
  1210. Check the connection.  Make sure no connectors have wiggled loose from their
  1211. sockets.  If you're using a modem, make sure you still have a carrier signal.
  1212. Reestablish your connection if you have to.
  1213.  
  1214. If upon reconnection you get no response, maybe the remote host or the remote
  1215. Kermit program @Index[Crash] crashed.  Get back to command level on the local
  1216. Kermit (on microcomputer implementations, you may be able to do this by typing
  1217. about five RETURNs, or one or more Control-C's).  Issue the CONNECT command so
  1218. that you can see what happened.  If the remote system has crashed then you will
  1219. have to wait for it to come back, and restart whatever file that was being
  1220. transferred at the time.
  1221.  
  1222. @subSection<The Disk is Full>
  1223. @Index[Diskette]
  1224. If your local floppy disk or remote directory fills up, the Kermit on the
  1225. machine where this occurs will inform you and then terminate the transfer.  You
  1226. can continue the transfer by repeating the whole procedure either with a fresh
  1227. floppy or after cleaning up your directory.  Some Kermits also have a feature
  1228. that allows you to keep incompletely received files; this would allow you go
  1229. back to the sending system, extract the unsent portion of the file, and send
  1230. it, and then append the two received portions together using an editor or other
  1231. system utility.  Kermit does not provide the ability to switch disks during a
  1232. file transfer.
  1233.  
  1234. @SubSection<Transmission Delays>
  1235.  
  1236. Packet transmission can be delayed by various agents: congested timesharing
  1237. systems or networks, earth satellites, etc.  When transmission delay exceeds
  1238. the per-packet timeout interval for a significant length of time, the transfer
  1239. could fail.  Most Kermit programs provide commands that allow you to adjust
  1240. the timeout interval or the packet transmission retry threshhold in order to
  1241. accommodate to severe transmission delays.
  1242.  
  1243. @SubSection<Noise Corruption>
  1244.  
  1245. If your connection is extremely noisy, packets will become corrupted -- and
  1246. require retransmission -- more often.  The probability that successive
  1247. retransmissions will fail because of corruption rises with the noise level
  1248. until it exceeds the retry threshhold, at which point the file transfer
  1249. fails.  There are several recourses.  First, try to establish a new connection.
  1250. If that is impractical, then use SET commands (when available) to reduce the
  1251. packet length and increase the retry threshhold.  Shorter packets reduce the
  1252. probability that a particular packet will be corrupted and the
  1253. retransmission overhead when corruption does occur, but they also increase
  1254. the overall protocol overhead.  In a noisy environment, you should also
  1255. request a higher level of error checking (SET BLOCK 2 or 3).
  1256.  
  1257. @subSection<Host Errors>
  1258.  
  1259. Various error conditions can occur on the remote host that could effect file
  1260. transmission.  Whenever any such error occurs, the remote Kermit normally
  1261. attempts to send an informative error message to the local one, and then breaks
  1262. transmission, putting you back at Kermit command level on the local system.
  1263.  
  1264. @Section<File is Garbage>
  1265.  
  1266.  There are certain conditions under which Kermit can believe it transferred a
  1267. file correctly when in fact, it did not.  The most likely cause has to do with
  1268. the tricky business of @i<file attributes>, such as text vs binary, 7-bit vs
  1269. 8-bit, blocked vs stream, and so forth.  Each system has its own peculiarities,
  1270. and each Kermit has special commands to allow you to specify how a file should
  1271. be sent or stored.  However, these difficulties usually crop up only when
  1272. sending binary files.  Textual files should normally present no problem between
  1273. any two Kermit programs.
  1274.  
  1275. @Chapter<Kermit Commands>
  1276. @label<-commands>
  1277.  
  1278. An "ideal" Kermit program will be described here, which has most of the
  1279. features specified in the Kermit book.  Few Kermit programs will have all these
  1280. commands or support all these options.  The exact form of some of the commands
  1281. may differ from version to version.  Some Kermit programs may support
  1282. system-@|dependent options not described here.  The intention of this
  1283. description is to provide a base from which specific Kermit programs can be
  1284. described in terms of their differences from the "ideal."
  1285.  
  1286. @Section<Remote and Local Operation>
  1287.  
  1288. @index[Remote]@index[Local]
  1289.  In any connection between two Kermit programs, one Kermit is @i<remote> and
  1290. the other is @i<local>.  The remote Kermit is usually running on a mainframe,
  1291. which you have CONNECTed to through a PC or other computer.  When Kermit runs
  1292. remotely, all file transfer is done over the job's controlling terminal line --
  1293. the same line over which you logged in, and to which you would type interactive
  1294. commands.  What the system thinks is your terminal is really another computer,
  1295. usually a microcomputer, running its own copy of Kermit.
  1296.  
  1297. When Kermit is in "local mode", file transfer is done over an external device,
  1298. such as a microcomputer's serial communication port, or an assigned terminal
  1299. line on a mainframe.  The local Kermit is connected in some way (like a dialout
  1300. mechanism) to another computer, again running its own copy of Kermit.  A local
  1301. Kermit is in control of the screen, a remote Kermit has no direct access to it.
  1302. Microcomputer Kermits are run in local mode unless instructed otherwise;
  1303. mainframe Kermits run remotely unless some special command places them in local
  1304. mode.  Some commands make sense only for remote Kermits, others only for local,
  1305. still others can be used with either.  Local and remote operation of Kermit is
  1306. shown schematically here:
  1307. @Begin(Figure)
  1308. @bar()
  1309. @i<PC is Local, Mainframe is Remote:>
  1310. @begin<example>
  1311.            Communication 
  1312.            Line                    (Packets)
  1313.            +---------------/  /-----------------+  Other terminals
  1314.            |                                    |  |  |  |
  1315.            |                                    |  |  |  |
  1316.  PC        |     LOCAL              Mainframe   |  |  |  |  REMOTE  
  1317. +----------+----------+            +------------+--+--+--+--------+
  1318. |   Serial Port       |            |            |                 |
  1319. |                     |            |            |                 |  
  1320. |                     |            |            |                 |  
  1321. |  +---------------+  |            |            Your job's        |
  1322. |  | Packets: 724  |  |            |            terminal line     |
  1323. |  | Retries:   7  |  |            |                              |  
  1324. |  | File: FOO.BAR |  |            |                              |  
  1325. |  +---------------+  |            |                              |  
  1326. |   Screen            |            |                              |  
  1327. |                     |            |                              |  
  1328. +---------------+-----+            +------------------------------+
  1329.                 |
  1330.                 | (Commands)
  1331.                 |
  1332.    +------------+---------+
  1333.     \       Keyboard       \
  1334.      +----------------------+
  1335.                 You
  1336. @end(example)
  1337. @caption(Local and Remote Kermits)
  1338. @tag(-localfig)
  1339. @bar()
  1340. @end<figure>
  1341. The Kermit program on the PC is a @i<local> Kermit.  It can control the screen,
  1342. the keyboard, and the port separately, thus it can update the screen with
  1343. status information, watch for interrupt signals from the keyboard, and transfer
  1344. packets on the communications port, all at the same time. 
  1345.  
  1346. The Kermit program running on the mainframe is a @i<remote> Kermit.
  1347. The user logs in to the mainframe through a terminal port.  The host computer
  1348. cannot tell that the user is really coming in through a microcomputer.  The
  1349. keyboard, screen, and port functions are all combined in user's mainframe
  1350. terminal line.  Therefore a remote Kermit is cut off from your screen and
  1351. keyboard during file transfer.
  1352.  
  1353. @section<The Command Dialog>
  1354.  
  1355. @index<Command Parsing>
  1356.  Most Kermit programs communicate with you through interactive keyword-@|style
  1357. command dialog (a prominent exception is Macintosh Kermit, which uses pulldown
  1358. menus that overlay the terminal emulation screen).  The program issues a
  1359. @i<prompt>, indicating that it is waiting for you to type a command.  The
  1360. prompt is usually of the form
  1361.  @example[@q(Kermit-)@i<xx>@q(>)]
  1362.  where @i<xx> indicates the version of Kermit -- @q(Kermit-MS>) for MS-DOS
  1363. Kermit, @q(Kermit-86>) for CP/M-86 Kermit, etc.
  1364.  
  1365. In response to the program's prompt you may type a keyword, such as SEND,
  1366. RECEIVE, or EXIT, possibly followed by additional keywords or operands, each of
  1367. which is called a @i<field>.  You can abbreviate keywords (but not file names)
  1368. to any length that makes them distinguishable from any other keyword valid for
  1369. that field.  You can type a question mark at any time to get information about
  1370. what's expected or valid at that point.  The ESC and "?"  features work best on
  1371. full duplex systems, where the program can "wake up" immediately and perform
  1372. the required function.  On half duplex or record-@|oriented systems, the ESC
  1373. feature is not available, and the "?" requires a carriage return to follow.
  1374.  
  1375. In this example, the user types "set" and then a question mark to find out what
  1376. the SET options are.  The user then continues the command at the point where
  1377. the question mark was typed, adding a "d" and another question mark to see what
  1378. set options start with "d".  The user then adds a "u" to select "duplex" (the
  1379. only SET option that starts with "du") followed by an ESC (shown here by a
  1380. dollar sign) to complete the current field, then another question mark to see
  1381. what the possibilities are for the next field, and so forth.  The command is
  1382. finally terminated by a carriage return.  Before carriage return is typed,
  1383. however, the command can be edited or erased using RUBOUT or other command
  1384. editing keys.  Finally, the same command is entered again with a minimum of
  1385. keystrokes, with each field abbreviated to its shortest unique length.  In the
  1386. example, the parts the user types are underlined; all the rest is system
  1387. typeout:
  1388.  
  1389. @begin<example,above 2,below 2>
  1390. Kermit-20>@ux<set ?> one of the following:
  1391.  debugging        delay             duplex            escape
  1392.  file             handshake         IBM               line
  1393.  parity           receive           send
  1394. Kermit-20>set @u<d?> one of the following:
  1395.  debugging   delay        duplex
  1396. Kermit-20>set d@u<u$>plex (to) @u<?> one of the following:
  1397.  full   half
  1398. Kermit-20>set duplex (to) @u<h$>alf
  1399. Kermit-20>@ux<set du h>
  1400. @end<example>
  1401.  
  1402. @section<Notation>
  1403.  
  1404. In the command descriptions, the following notation is used:
  1405.  @begin<description,leftmargin +12,indent -12>
  1406. @i<italics>@\A parameter - the symbol in italics is replaced by
  1407. an argument of the specified type (number, filename, etc).
  1408.  
  1409. [@i<anything>]@\A field enclosed in square brackets is optional.  If omitted,
  1410. the field defaults to an appropriate value.  You don't type the brackets.
  1411.  
  1412. {x,y,z}@\A list of alternatives is enclosed in curly braces; you type one
  1413. of the alternatives.
  1414.  
  1415. @i<number>@\A whole number, entered in prevailing notation of the system.
  1416.  
  1417. @i<character>@\A single character, entered literally, or as a number (perhaps
  1418. octal or hexadecimal) representing the ASCII value of the character.
  1419.  
  1420. @i<floating-point-number>@\A "real" number, possibly containing a decimal point
  1421. and a fractional part.
  1422.  
  1423. @i<filespec>@\A file specification, i.e. the name of a file, possibly including
  1424. a search path, device or directory name, or other qualifying information, and
  1425. possibly containing "wildcard" or pattern-@|matching characters to denote a
  1426. group of files.
  1427.  
  1428. @q<^X>@\A control character may be written using "uparrow" or "caret" notation,
  1429. since many systems display control characters this way.  Control characters are
  1430. produced by holding down the key marked CTRL or Control and typing the
  1431. appropriate character, e.g. X.  Control characters may also be written
  1432. Ctrl-X, CTRL-X, CTRL/X, etc.
  1433.  @end<description>
  1434. Commands are shown in upper case, but can be entered in any combination of
  1435. upper and lower case.
  1436.  
  1437. @newpage()
  1438. @Section<Summary of Kermit Commands>
  1439.  
  1440. Here is a brief list of Kermit commands as they are to be found in most Kermit
  1441. programs.  The following sections will describe these commands in detail.
  1442. @begin<description,leftmargin +4,indent -4,spread 0.5>
  1443. @i<For exchanging files:>@\
  1444. SEND, RECEIVE, GET
  1445.  
  1446. @i<For connecting to a remote host:>@\
  1447. CONNECT, SET LINE, SET PARITY, SET DUPLEX, SET HANDSHAKE, SET ESCAPE,
  1448. @w<SET FLOW-CONTROL>, SET SPEED (or BAUD) 
  1449.  
  1450. @i<For acting as a server:>@\SERVER
  1451.  
  1452. @i<For talking to a server:>@\BYE, FINISH, GET, SEND, REMOTE
  1453.  
  1454. @i<Setting nonstandard transmission and file parameters:>@\
  1455. SET BLOCK-CHECK, SET DEBUG, SET DELAY, SET FILE, SET INCOMPLETE, SET PARITY,
  1456. SET RETRY;@* 
  1457. SET SEND (or RECEIVE) END-OF-LINE, START-OF-PACKET, PACKET-LENGTH,
  1458. PAUSE, TIMEOUT, PADDING
  1459.  
  1460. @i<For defining and executing "macros" of commands:>@\
  1461. DEFINE, DO
  1462.  
  1463. @i<For interrupting transmission:>@\
  1464. Control-X, Control-Z, Control-C, Control-E
  1465.  
  1466. @i<Getting information:>@\
  1467. HELP, STATISTICS, SHOW
  1468.  
  1469. @i<Executing command files:>@\
  1470. TAKE    
  1471.  
  1472. @i<For recording the history of a file transfer operation:>@\
  1473. LOG TRANSACTIONS
  1474.  
  1475. @i<For non-protocol file capture or transmission:>@\
  1476. LOG SESSION, TRANSMIT, INPUT, OUTPUT, PAUSE, CLEAR, SCRIPT
  1477.  
  1478. @i<For closing log files:>@\
  1479. CLOSE
  1480.  
  1481. @i<Leaving the program:>@\
  1482. EXIT, QUIT 
  1483. @End(Description) 
  1484. If you have a file called @q<KERMIT.INI> in your default or home disk, Kermit
  1485. will execute an automatic TAKE command on it upon initial startup.
  1486. @q<KERMIT.INI> may contain any Kermit commands, for instance SET commands,
  1487. or DEFINEs for macros to configure Kermit to various systems or
  1488. communications media.  @i<Note:>  Your particular implementation of Kermit may
  1489. use a different name for this file, like @q<MSKERMIT.INI> for MS-DOS Kermit,
  1490. or @q<VMSKERMIT.INI> for VAX/VMS Kermit.
  1491.  
  1492. @newpage()
  1493. @Section<The SEND Command>
  1494. @Index[Initial Filespec]@Index[SEND]
  1495. Syntax: 
  1496.  
  1497. Sending a single file:
  1498.  @display(@q<SEND @i{filespec1} [@i{filespec2}]>)
  1499.  
  1500. Sending multiple files:
  1501.  @display(@q<SEND @i{wild-filespec1}>)
  1502.  
  1503. The SEND command causes a file or file group to be sent to the
  1504. other system.  There are two forms of the command, depending on whether
  1505. @i{filespec1} contains "wildcard" characters.  Use of wildcard characters is
  1506. the most common method of indicating a group of files in a single file
  1507. specification.  For instance if @q<FOO.FOR> is a single file, a FORTRAN program
  1508. named FOO, then @q<*.FOR> might be a group of FORTRAN programs.
  1509.  
  1510. @SubH<Sending a File Group -->
  1511.  
  1512. If @i{filespec1} contains wildcard characters then all matching files will be
  1513. sent, in directory-@|listing order by name.  If a file can't be opened for read
  1514. access, it will be skipped.
  1515.  
  1516. @SubH<Sending a Single File -->
  1517.  
  1518. If @i{filespec1} does not contain any wildcard characters, then the single file
  1519. specified by @i{filespec1} will be sent.  Optionally, @i{filespec2} may be used
  1520. to specify the name under which the file will arrive at the target system;
  1521. @i{filespec2} is not parsed or validated locally in any way.  If @i{filespec2}
  1522. is not specified, the file will be sent with its own name.
  1523.  
  1524. @SubH<SEND Command General Operation -->
  1525.  
  1526. Files will be sent with their filename and filetype (for instance
  1527. @q<FOO.BAR>, no device or directory field, no generation number or attributes).
  1528. @Index<Parity>@Index<Eighth-Bit Prefix>@Index<Binary Files>
  1529. If communication line parity is being used (see SET PARITY), the sending Kermit
  1530. will request that the other Kermit accept a special kind of prefix notation for
  1531. binary files.  This is an advanced feature, and not all Kermits have it; if the
  1532. other Kermit does not agree to use this feature, binary files cannot be sent
  1533. correctly.
  1534.  
  1535. @Index<Repeated Character Compression>
  1536. The sending Kermit will also ask the other Kermit whether it can handle a
  1537. special prefix encoding for repeated characters.  If it can, then files with
  1538. long strings of repeated characters will be transmitted very efficiently.
  1539. Columnar data, highly indented text, and binary files are the major
  1540. beneficiaries of this technique.
  1541.  
  1542. @SubH<SEND Remote Operation -->
  1543.  
  1544. If you are running Kermit remotely (for instance, from a microcomputer), you
  1545. should "escape back" to your local Kermit within a reasonable amount of time
  1546. and give the RECEIVE command.  Don't take more than a minute or two to complete
  1547. the switch, or Kermit may "time out" and give up (in that case, you'll have
  1548. to CONNECT back to the remote system and reissue the SEND command).
  1549.  
  1550. @SubH<SEND Local Operation -->
  1551.  
  1552. If you're running Kermit locally, for instance on a microcomputer,
  1553. you should have already run Kermit on the remote system and issued either a
  1554. RECEIVE or a SERVER command. 
  1555.  
  1556. Once you give Kermit the SEND command, the name of each file will be
  1557. printed on your screen as the transfer begins, and information will be
  1558. displayed to indicate the packet traffic.  When the specified 
  1559. operation is complete, the program will sound a beep, and the status of the
  1560. operation will be indicated by a message like OK, Complete, Interrupted, or
  1561. Failed. 
  1562.  
  1563. If you see many packet retry indications, you are probably suffering from a
  1564. noisy connection.  You may be able to cut down on the retransmissions by using
  1565. SET SEND PACKET-LENGTH to decrease the packet length; this will reduce the
  1566. probability that a given packet will be corrupted by noise, and reduce the time
  1567. required to retransmit a corrupted packet.
  1568.  
  1569. @index<Control-X>@index<Control-Z>@Index<Cancelling a File Transfer> If you
  1570. notice a file being sent which you do not really want to send, you may cancel
  1571. the operation immediately by typing either Control-X or Control-Z.  If your are
  1572. sending a file group, Control-X will cause the current file to be skipped, and
  1573. Kermit will go on to the next file, whereas Control-Z will cancel sending
  1574. the entire group and return you to Kermit-20 command level.
  1575.  
  1576. @Section<The RECEIVE Command>
  1577. @Index[RECEIVE]
  1578. Syntax:  @q<RECEIVE [@i{filespec}]>
  1579.  
  1580. The RECEIVE command tells Kermit to wait for the arrival a file or file group
  1581. sent by a SEND command from the other system.  If only one file is being
  1582. received, you may include the optional @i{filespec} as the name to store the
  1583. incoming file under; otherwise, the name is taken from the incoming file
  1584. header.  If the name in the header is not a legal file name on the local
  1585. system, Kermit will attempt to transform it to a legal name.
  1586.  
  1587. If an incoming file has the same name as an existing file, Kermit will either
  1588. overwrite the old file or else try to create a new unique name, depending on
  1589. the setting of FILE WARNING.
  1590.  
  1591. @Index<Parity>@Index<Eighth-Bit Prefix>@Index<Repeated Character Compression>
  1592. If you have SET PARITY, then 8th-bit prefixing will be requested.  If the other
  1593. side cannot do this, binary files cannot be transferred correctly.  The sending
  1594. Kermit may also request that repeated characters be compressed.
  1595.  
  1596. If an incoming file does not arrive in its entirety, Kermit will normally
  1597. discard it; it will not appear in your directory.  You may change this behavior
  1598. @Index<Incomplete File Disposition>
  1599. by using the command SET INCOMPLETE KEEP, which will cause as much of the file
  1600. as arrived to be saved in your directory. 
  1601.  
  1602. @SubH<RECEIVE Remote Operation -->
  1603.  
  1604. If your are running Kermit remotely, you should escape back to your local
  1605. Kermit and give the SEND command.  You should do this within about two minutes,
  1606. or the protocol may time out and give up; if this happens, you can CONNECT back
  1607. to the remote system and reissue the RECEIVE command.
  1608.  
  1609. @SubH<RECEIVE Local Operation -->
  1610.  
  1611. If you are running Kermit locally, you should already have issued a
  1612. SEND command to the remote Kermit, and then escaped back to DEC-20 Kermit
  1613. (you can not issue a RECEIVE command to a Kermit server, you must use the
  1614. GET command for that).
  1615.  
  1616. As files arrive, their names will be shown on your screen, along with
  1617. a continuous display the packet traffic.
  1618.  
  1619. @Index<Control-X>@Index<Control-Z>@Index<Cancelling a File Transfer>
  1620. If a file begins to arrives that you don't really want, you can attempt to
  1621. cancel it by typing Control-X; this sends a cancellation request to the
  1622. remote Kermit.  If the remote Kermit understands this request (not all
  1623. implementations of Kermit support this feature), it will comply;
  1624. otherwise it will continue to send.  If a file group is being sent, you can
  1625. request the entire group be cancelled by typing Control-Z.
  1626.  
  1627. @Section<The GET Command>
  1628. @index<The GET Command>
  1629. Syntax: @q<GET [@i{remote-filespec}]>
  1630.  
  1631. The GET command requests a Kermit @i<server> to send the file or file group
  1632. specified by @i<remote-filespec>.  Note the distinction between the RECEIVE 
  1633. and GET commands: RECEIVE instructs the program to wait passively, whereas GET
  1634. actively sends a request to a server.
  1635.  
  1636. The remote filespec is any character sequence that can be a legal file
  1637. specification for the remote system; it is not parsed or validated locally.  As
  1638. files arrive, their names will be displayed on your screen, along with a
  1639. continuous indication of the packet traffic.  As in the RECEIVE command, you
  1640. may type Control-X to request that the current incoming file be cancelled,
  1641. Control-Z to request that the entire incoming batch be cancelled.
  1642.  
  1643. @i<Optional Syntax:> If you are requesting a single file, you may type the GET
  1644. command without a filespec.  In that case, Kermit programs that implement the
  1645. optional GET syntax will prompt you for the remote filespec on the subsequent
  1646. line, and the name to store it under when it arrives on the line after that:
  1647. @begin(example)
  1648. Kermit-MS>@ux(get)
  1649.  Remote Source File: @ux<aux.txt>
  1650.  Local Destination File: @ux<auxfile.txt>
  1651. @end(example)
  1652.  
  1653. @Section<The SERVER Command>
  1654. @Index<SERVER Command>
  1655. Syntax: @q<SERVER>
  1656.  
  1657. The SERVER command instructs Kermit to cease taking commands from the keyboard
  1658. and to receive all further instructions in the form of Kermit packets from
  1659. another system.  The other Kermit must have commands for communicating with
  1660. remote servers; these include GET, SEND, FINISH, and BYE.
  1661.  
  1662. After issuing this command, return to the "client" system and issue SEND,
  1663. GET, BYE, FINISH, or other server-@|directed commands from there.  If your
  1664. local Kermit does not have a BYE command, then it does not have the full
  1665. ability to communicate with a Kermit server and you should not put the remote
  1666. Kermit into SERVER mode.  If your local Kermit does have a BYE command, use it
  1667. to shut down and log out the Kermit server when you are done with it.
  1668.  
  1669. Any nonstandard parameters should be selected with SET commands before putting
  1670. Kermit in server mode.
  1671.  
  1672. @Section<The BYE Command>
  1673. @index<BYE Command>
  1674. Syntax: @q<BYE>
  1675.  
  1676. When running talking to a Kermit server, use the BYE command to shut down the
  1677. server and, if the server is on a timesharing system, also log out the job.
  1678. This will also close any open log files and exit from the local Kermit.
  1679.  
  1680. @Section<The FINISH Command>
  1681. @index<FINISH Command>
  1682. Syntax: @q<FINISH>
  1683.  
  1684. When running as a local Kermit talking to a remote Kermit server use the FINISH
  1685. command to shut down the server without logging out the remote job, so that you
  1686. can CONNECT back to it.
  1687.  
  1688. @Section<The REMOTE Command>
  1689. @index<REMOTE Command>
  1690. Syntax: @q<REMOTE> @i<command>
  1691.  
  1692. When talking to a remote Kermit server, use the REMOTE command to request
  1693. special functions of the remote server.  If the server does not understand the
  1694. command or offer the requested service (all of these commands and services are
  1695. optional features of the Kermit protocol), it will reply with a message like
  1696. "Unknown Kermit server command".  If it does understand, it will send the
  1697. results back, and they will be displayed on the screen.  The REMOTE commands
  1698. include:
  1699. @begin<description, leftmargin +4, indent -4>
  1700. REMOTE CWD [@i<directory>]@\Change Working Directory.  If no directory name is
  1701. provided, the server will change to the default directory.  Otherwise, you will
  1702. be prompted for a password, and the server will attempt to change to the
  1703. specified directory.  If access is not granted, the server will provide a
  1704. message to that effect.  If the remote system does not require a password for
  1705. changing directories (UNIX is an example), then you can simply type a carriage
  1706. return in response to the password prompt.
  1707.  
  1708. REMOTE DELETE @i<filespec>@\Delete the specified file or files.  The names of
  1709. the files that are deleted should be displayed on your screen.
  1710.  
  1711. REMOTE DIRECTORY [@i<filespec>]@\The names of the files that match the given
  1712. file specification will be displayed on your screen, possibly along with
  1713. additional information about file sizes and dates.  If no file specification
  1714. is given, all files from the current directory will be listed.
  1715.  
  1716. REMOTE SPACE [@i<directory>]@\Information about disk usage in the
  1717. current remote directory -- quota, current storage, or amount of
  1718. remaining free space -- is displayed on your screen.
  1719.  
  1720. REMOTE HELP@\A list of available server functions is displayed.
  1721.  
  1722. REMOTE HOST [@i<command>]@\The given command is passed to the server's host
  1723. command processor, and the resulting output is displayed on your screen.
  1724.  
  1725. REMOTE KERMIT [@i<command>]@\The given command, which is expressed in the
  1726. server Kermit's own interactive-@|mode command syntax, is passed to the server
  1727. for execution.  This is useful for changing settings, logging, and other
  1728. functions.
  1729.  
  1730. REMOTE TYPE @i<filespec>@\The contents of the specified file is displayed on
  1731. your screen.
  1732.  
  1733. REMOTE WHO [@i<username>]@\List users, or a specified user, logged in on
  1734. the server's system.
  1735. @end<description>
  1736.  
  1737. @Section<Local Commands>
  1738. @index<Local Commands>
  1739. Syntax: @q<[LOCAL] @i{command}>
  1740.  
  1741. Execute the specified command on the local system -- on the system where Kermit
  1742. to which your are typing this command is running.  These commands provide some
  1743. local file management capability without having to leave the Kermit program,
  1744. which is particularly useful on microcomputers.  On most systems, the LOCAL
  1745. prefix for these commands can be omitted.
  1746. @begin<description, leftmargin +4, indent -4>
  1747. CWD [@i<directory>]@\"Change Working Directory" to the specified directory.
  1748. @index<CWD Command>
  1749.  
  1750. DELETE @i<filespec>@\Delete the specified file or files.
  1751. @index(DELETE Command)
  1752.  
  1753. DIRECTORY [@i<filespec>]@\Provide a directory listing of the specified files.
  1754. @index(DIRECTORY Command)
  1755.  
  1756. SPACE@\Display local disk usage and/or free space.
  1757. @index(SPACE Command)
  1758.  
  1759. RUN @i<filespec> [@i<operands>]@\Run the indicated program with the supplied
  1760. command-@|line operands.
  1761. @index(RUN Command)
  1762.  
  1763. PUSH@ @ Invoke the local system command interpreter in such a way that it can
  1764. return (or "pop" or "exit") back to Kermit.
  1765. @index(PUSH Command)
  1766. @end<description>
  1767. Some Kermit programs may provide commands for these or other functions in the
  1768. syntax of their own system, when this would cause no confusion.  For instance,
  1769. CP/M Kermit may use ERA in place of LOCAL DELETE.
  1770.  
  1771. @Section<The CONNECT Command>
  1772. @index<CONNECT Command>
  1773.  
  1774. @i<LOCAL ONLY> -- Syntax: @q<CONNECT [@i{terminal-designator}]>
  1775.  
  1776. Establish a terminal connection to the system at the other end of the
  1777. communication line.  On a microcomputer, this is normally the serial port.
  1778. On a mainframe, you will have to specify a terminal line number or other
  1779. identifier, either in the CONNECT command itself, or in a SET LINE command.
  1780. Get back to the local Kermit by typing the escape character followed by
  1781. a single character "command".
  1782. Several single-@|character commands are possible:
  1783. @Begin(Description,leftmargin +6,indent -4, spread 0, group)
  1784. @q<C>@\Close the connection and return to the local Kermit.
  1785.  
  1786. @q<S>@\Show status of the connection.
  1787.  
  1788. @q<B>@\Send a BREAK signal.
  1789.  
  1790. @q<0>@\(zero) Send a NUL (0) character.
  1791.  
  1792. @q<F>@\Copy the current screen into a disk file.
  1793.  
  1794. @q<D>@\Drop the line, hangup the modem.
  1795.  
  1796. @q<P>@\Push to the local system command processor without breaking the
  1797. connection.
  1798.  
  1799. @q<Q>@\Quit logging session transcript. 
  1800.  
  1801. @q<R>@\Resume logging session transcript. 
  1802.  
  1803. @q<?>@\List all the possible single-@|character arguments.
  1804.  
  1805. @q<^]> (or whatever you have set the escape character to be)@\Typing the escape
  1806. character twice sends one copy of it to the connected host.
  1807. @End(Description)
  1808. You can use the SET ESCAPE command to define a different escape character, and
  1809. SET PARITY, SET DUPLEX, SET FLOW-CONTROL, SET HANDSHAKE to establish or change
  1810. those parameters.
  1811.  
  1812. @Section<HELP>
  1813.  
  1814. Syntax: @q<The HELP Command>
  1815.  
  1816. Typing HELP alone prints a brief summary of Kermit and its commands, and
  1817. possibly instructions for obtaining more detailed help on particular topics.
  1818. Most Kermit implementations also allow the use of "?" within a command to
  1819. produce a short help message. 
  1820.  
  1821. @Section<The TAKE Command>
  1822. Syntax: @q<TAKE @i{filespec}>
  1823.  
  1824. Execute Kermit commands from the specified file.  The file may contain
  1825. contain any valid Kermit commands, including other TAKE commands.
  1826.  
  1827. @Section<The EXIT and QUIT Commands>
  1828. @Index<EXIT Command>
  1829.  
  1830. Exit from Kermit.  @Index<QUIT>@q<QUIT> is a synonym for EXIT.
  1831.  
  1832. @Section<The SET Command>
  1833. @index<SET Command>
  1834. Syntax: @q<SET @i{parameter} [@i{option}] [@i{value}]>
  1835.  
  1836. Establish or modify various parameters for file transfer or terminal
  1837. connection.
  1838.  
  1839. When a file transfer operation begins, the two Kermits automatically exchange
  1840. special initialization messages, in which each program provides the other with
  1841. certain information about itself.  This information includes the maximum packet
  1842. size it wants to receive, the timeout interval it wants the other Kermit to
  1843. use, the number and type of padding characters it needs, the end-@|of-@|line
  1844. character it needs to terminate each packet (if any), the block check type, the
  1845. desired prefixes for control characters, characters with the "high bit" set,
  1846. and repeated characters.  Each Kermit program has its own preset "default"
  1847. values for these parameters, and you normally need not concern yourself with
  1848. them.  You can examine their values with the SHOW command; the SET command is
  1849. provided to allow you to change them in order to adapt to unusual conditions.
  1850.  
  1851. The following parameters may be SET:
  1852. @Begin(Format,spread 0,above 1)
  1853. @tabclear()@tabset(1.25inches)
  1854. @>BAUD@\  Set the speed of the current communications port
  1855. @>BLOCK-CHECK@\  Packet transmission error detection method
  1856. @>DEBUG@\  Mode or log file
  1857. @>DELAY@\  How long to wait before starting to send
  1858. @>DUPLEX@\  For terminal connection, full (remote echo) or half (local echo)
  1859. @>END@\  Packet termination character (normally CR)
  1860. @>ESCAPE@\  Character for terminal connection
  1861. @>FILE@\  For setting file parameters like name conversion and byte size
  1862. @>FLOW-CONTROL@\  Selecting flow control method, like XON/XOFF
  1863. @>HANDSHAKE@\  For turning around half duplex communication line
  1864. @>IBM@\  Set parameters for IBM mainframe linemode connection
  1865. @>INCOMPLETE@\  What to do with an incomplete file
  1866. @>KEY@\  Establish a key redefinition or keyboard macro
  1867. @>LOCAL-ECHO@\  Specify who echoes during terminal connection
  1868. @>LINE@\  Terminal line to use for terminal connection or file transfer
  1869. @>MODEM@\  Modem type or characteristics
  1870. @>PARITY@\  Character parity to use
  1871. @>PORT@\  For switching communication ports
  1872. @>PROMPT@\  For changing the program's command prompt
  1873. @>RECEIVE@\  Various parameters for receiving files
  1874. @>RETRY@\  How many times to retry a packet before giving up
  1875. @>SEND@\  Various parameters for sending files
  1876. @>SPEED@\  Synomym for BAUD.
  1877. @>TERMINAL@\  Parameters for terminal emulation
  1878. @>TIMER@\  Enable/disable timeouts
  1879. @>WARNING@\  Filename collision protection
  1880. @End(Format)
  1881.  
  1882. The DEFINE command may be used to compose "macros" by combining SET and
  1883. possibly other commands.  The SET commands are now described in detail.
  1884.  
  1885. @Subheading<SET BAUD>
  1886. @Index<Baud Rate>
  1887.  Set or change the baud rate (approximate translation: transmission speed in
  1888. bits per second) on the currently selected communications device.  Ten bits per
  1889. second is usually equivalent to one character per second; 300 baud = 30 cps.
  1890. The way of specifying the baud rate varies from system to system; in most
  1891. cases, the actual number (such as 1200 or 9600) is typed.  Systems that do not
  1892. provide this command generally expect that the speed of the line has already
  1893. been set appropriately outside of Kermit.  Common values are 300, 1200, 2400,
  1894. 4800, 9600, 19200.
  1895.  
  1896. @Subheading<SET BLOCK-CHECK {1, 2, 3}>
  1897. @Index<Block Check>
  1898. Kermit normally uses a 1-character block check, or "checksum", on each packet.
  1899. The sender of the packet computes the block check based on the other characters
  1900. in the packet, and the receiver recomputes it the same way.  If these
  1901. quantities agree, the packet is accepted and transmission proceeds.  If
  1902. they disagree, the packet is rejected and retransmission is requsted.
  1903.  
  1904. However, the block check is not a foolproof method of error detection.  The
  1905. normal single-@|character Kermit block check is only a 6-bit quantity (the low
  1906. order 8 bits of the arithmetic sum folded upon itself).  With
  1907. only six bits of accuracy, the chances are one in 2@+<6> -- that is,
  1908. 1/64 -- that an error can occur which will not be detected in the checksum,
  1909. assuming that all errors are equally likely (they aren't).
  1910.  
  1911. You can decrease the probability that an error can slip through, at the expense
  1912. of transmission efficiency, by using the SET BLOCK-CHECK command to select more
  1913. rigorous block check methods.  Note that all three methods will detect any
  1914. single-@|bit error, or any error in an odd number of bits.  The options are:
  1915. @Begin(Description,leftmargin +4,indent -4)
  1916. 1-CHARACTER-CHECKSUM:@\The normal single-character 6-bit checksum.
  1917.  
  1918. 2-CHARACTER-CHECKSUM:@\A 2-character, 12-bit checksum.  Reduces the probability
  1919. of an error going undetected to 1/4096, but adds an extra character to each
  1920. packet.
  1921.  
  1922. 3-CHARACTER-CRC:@\A 3-character, 16-bit Cyclic Redundancy Check, CCITT format.
  1923. In addition to errors in any odd number of bits, this method detects double bit
  1924. errors, all error bursts of length 16 or less, and more than 99.99% of all
  1925. possible longer bursts.  Adds two extra characters to each packet.
  1926. @End(Description)
  1927. The single character checksum has proven to be quite adequate in practice, much
  1928. more effective than straightforward analysis would indicate, since all errors
  1929. are @i<not> equally likely, and a simple checksum is well suited to catching
  1930. the kinds of errors that are typical of telecommunication lines.  The
  1931. other methods should be requested only when the connection is @i<very> noisy
  1932. and/or when sending binary files, or when using "long packets" (see SET RECEIVE
  1933. PACKET-LENGTH).
  1934.  
  1935. Note that the 2- and 3-character block checks are not available in all versions
  1936. of Kermit; if the other Kermit is not capable of performing the
  1937. higher-@|precision block checks, the transfer will automatically use the
  1938. standard single-@|character method.
  1939.  
  1940. @Subheading<SET DEBUG {ON, OFF}>
  1941. @Index<Debugging>
  1942. Syntax: @q<SET DEBUG @i{options}>
  1943.  
  1944. Record debugging information, either on your terminal or in a file. 
  1945. Options are:
  1946. @Begin(Description,leftmargin +6,indent -4)
  1947. ON@\Turn on debugging.
  1948.  
  1949. OFF@\Don't display debugging information (this is the default).  If
  1950. debugging was in effect, turn it off and close any log file.
  1951. @End(Description)
  1952. or possibly others, like STATES, PACKETS, SESSION, etc., to select logging of
  1953. different phenomena.  Some Kermit programs may control debugging by use of the
  1954. LOG DEBUG command.
  1955.  
  1956. @Subheading<SET DELAY>
  1957. @Index<Delay>
  1958. Syntax: @q<SET DELAY @i{number}>
  1959.  
  1960. Specify how many seconds to wait before sending the first packet after a SEND
  1961. command.  Use when remote and SENDing files back to your local Kermit.  This
  1962. gives you time to "escape" back and issue a RECEIVE command.  The normal delay
  1963. is 5 seconds.  In local mode or server mode, Kermit does not delay before
  1964. sending the first packet.
  1965.  
  1966. @Subheading<SET DUPLEX>
  1967. @Index<Duplex>@Index<Local Echo>
  1968. Syntax: @q<SET DUPLEX {FULL, HALF}>
  1969.  
  1970. For use when CONNECTed to a remote system.  The keyword choices are FULL and
  1971. HALF.  FULL means the remote system echoes the characters you type, HALF means
  1972. the local system echoes them.  FULL is the default, and is used by most hosts.
  1973. HALF is necessary when connecting to IBM mainframes.  Half duplex is also
  1974. called "local echo"; in some Kermits, use SET LOCAL-ECHO ON instead of
  1975. SET DUPLEX HALF.
  1976.  
  1977. @Subheading<SET ESCAPE>
  1978. @Index<Escape Character for CONNECT>
  1979. Syntax: @q<SET ESCAPE @i{character}>
  1980.  
  1981. Specify or change the character you want to use to "escape" from remote
  1982. connections back to Kermit.  This would normally be a character you don't
  1983. expect to be using on the remote system, perhaps a control character like
  1984. @q<^\>, @q<^]>, @q<^^>, or @q<^_>.  Most versions of Kermit use one of these by
  1985. default.  After you type the escape character, you must follow it by a
  1986. single-character "argument", such as "C" for Close Connection.  The arguments
  1987. are listed above, under the description of the CONNECT command.
  1988.  
  1989. @Subheading<SET FILE>
  1990. Syntax: @q<SET FILE @i{parameter value}>
  1991.  
  1992. Establish file-related parameters.  Depending on the characteristics of the
  1993. system, it may be necessary to tell Kermit how to fetch an outbound file from
  1994. the disk, or how to store an incoming file.  The actual parameters you can
  1995. specify in this command will vary from system to system, and you should consult
  1996. the documentation for your particular version of Kermit.  Some examples would
  1997. be file type (text or binary), byte size (PDP-10 architecture), record length
  1998. or block size (record oriented systems), end-@|of-@|file detection method (on
  1999. microcomputers), file naming conversion option.
  2000.  
  2001. This can be a very important command if you intend to transfer binary
  2002. files, but is normally unecessary for transmitting textual files.
  2003.  
  2004. @Subheading<SET FLOW-CONTROL>
  2005. @Index<Flow Control>
  2006. Syntax: @q<SET FLOW-CONTROL {XON/XOFF,NONE}>
  2007.  
  2008. @index<XON/XOFF>
  2009. For communicating with full duplex systems.  System-@|level flow control is not
  2010. necessary to the Kermit protocol, but it can help to use it if the same method
  2011. is available on both systems.  The most common type of flow control on full
  2012. duplex systems is XON/XOFF.  When a system's input buffer comes close to being
  2013. full, it will send an XOFF character (Control-S) to request the other system to
  2014. stop sending.  When it has emptied sufficient characters from its input buffer,
  2015. it signals the other system to resume sending by transmitting an XON character
  2016. (Control-Q).  This process operates in both directions simultaneously.  The
  2017. options for the Kermit SET FLOW command are usually restricted to XON/XOFF and
  2018. NONE, which is used to disable this feature.
  2019.  
  2020. @Subheading<SET HANDSHAKE>
  2021. @Index<Handshake>
  2022. Syntax: @q<SET HANDSHAKE @i{option}>
  2023.  
  2024. For communicating with half duplex systems.  This lets you specify the line
  2025. turnaround character sent by the half duplex host to indicate it has ended
  2026. its transmission and is granting you permission to transmit.  When a
  2027. handshake is set, Kermit will not send a packet until the half duplex
  2028. host has sent the specified character (or a timeout has occurred).
  2029. The options may include:
  2030. @Begin(Description,leftmargin +12,indent -8,spread 0) 
  2031. NONE@\No handshake; undo the effect of any previous SET HANDSHAKE.
  2032.  
  2033. XOFF@\Control-S.
  2034.  
  2035. XON@\Control-Q.
  2036.  
  2037. BELL@\Control-G.
  2038.  
  2039. CR@\Carriage Return, Control-M.
  2040.  
  2041. LF@\Linefeed, Control-J.
  2042.  
  2043. ESC@\Escape, Control-@q([).
  2044. @End(Description)
  2045. Some Kermit programs may require the option to be specified by typing the
  2046. character literally or entering its numeric ASCII value.  If you use this
  2047. command to enable handshaking, you should also SET FLOW OFF.
  2048.  
  2049. @Subheading<SET INCOMPLETE>
  2050. @Index<Incomplete File Transfer>
  2051. Syntax: @q<SET INCOMPLETE {KEEP, DISCARD}>
  2052.  
  2053. Specify what to do when a file transfer fails before it is completed.
  2054. The options are DISCARD (the default) and KEEP.  If you choose KEEP, then if
  2055. a transfer fails to complete successfully, you will be able to keep the
  2056. incomplete part that was received.
  2057.  
  2058. @Subheading<SET LINE>
  2059. Syntax: @q<SET LINE [@i(terminal-designator)]>
  2060.  
  2061. Specify the terminal line to use for file transfer or CONNECT.
  2062. This command is found on mainframe Kermits, which normally run in "remote
  2063. mode" using their own controlling terminal for file transfer.  Specifying a
  2064. separate line puts the program in "local mode."  If no line is specified,
  2065. revert to the job's controlling terminal, i.e. go back to "remote mode."
  2066.  
  2067. @subheading<SET PORT>
  2068. Syntax: @q<SET PORT @i(terminal-designator)>
  2069.  
  2070. Specify the communications port for file transfer or CONNECT.  This command is
  2071. found on microcomputer Kermits that run in "local" mode.  SET PORT does not
  2072. change the remote/@|local status but simply selects a different port for local
  2073. operation.
  2074.  
  2075. @Subheading<SET PARITY>
  2076. @Index<Parity>
  2077. Syntax: @q<SET PARITY {EVEN, ODD, MARK, SPACE, NONE}>
  2078.  
  2079. Parity is a technique used by communications equipment for detecting errors on
  2080. a per-@|character basis; the "8th bit" of each character acts as a check bit
  2081. for the other seven bits.  Kermit uses block checks to detect errors on a
  2082. per-@|packet basis, and it does not use character parity.  However, some
  2083. systems that Kermit runs on, or equipment through which these systems
  2084. communicate, may be using character parity.  If Kermit does not know about
  2085. this, arriving data will have been modified and the block check will appear to
  2086. be wrong, and packets will be rejected.
  2087.  
  2088. @Index<TELENET>
  2089. If parity is being used on the communication line, you must inform both
  2090. Kermits, so the desired parity can be added to outgoing characters, and
  2091. stripped from incoming ones.  SET PARITY should be used for communicating with
  2092. hosts that require character parity (IBM mainframes are typical examples) or
  2093. through devices or networks (like GTE TELENET) that add parity to characters
  2094. that pass through them.  Both Kermits should be set to the same parity.  The
  2095. specified parity is used both for terminal connection (CONNECT) and file
  2096. transfer (SEND, RECEIVE, GET).
  2097.  
  2098. The choices for SET PARITY are:
  2099. @begin<description,leftmargin +8,indent -6,spread 0.25>
  2100. NONE@\(the default) eight data bits and no parity bit.
  2101.  
  2102. MARK@\seven data bits with the parity bit set to one.
  2103.  
  2104. SPACE@\seven data bits with the parity bit set to zero.
  2105.  
  2106. EVEN@\seven data bits with  the  parity  bit  set  to  make  the
  2107. overall parity even.
  2108.  
  2109. ODD@\seven data bits with the parity bit set to make the overall
  2110. parity odd.
  2111. @end<description>
  2112. NONE means no parity processing is done, and the 8th bit of each character can
  2113. be used for data when transmitting binary files.
  2114.  
  2115. @Index<Eighth-Bit Prefix>@Index<Binary Files> If you have set parity to ODD,
  2116. EVEN, MARK, or SPACE, then most versions of Kermit will request that binary
  2117. files be transferred using 8th-bit-prefixing.  If the Kermit on the other
  2118. side knows how to do 8th-bit-prefixing (this is an optional feature of the
  2119. Kermit protocol, and not all implementations of Kermit have it), then binary
  2120. files can be transmitted successfully.  If NONE is specified,
  2121. 8th-bit-@|prefixing will not be requested.
  2122.  
  2123. @Subheading<SET PROMPT>
  2124.  
  2125. Syntax: @q<SET PROMPT @i(string)>
  2126.  
  2127. @index<Prompt>
  2128. This allows you to change the program's prompt.  This is particularly useful
  2129. if you are using Kermit to transfer files between two systems of the same kind,
  2130. in which case you can change the prompts of the Kermit programs involved to
  2131. include appropriate distinguishing information.
  2132.  
  2133. @Subheading<SET SEND>
  2134.  
  2135. @q<SET SEND @i<parameter value>>
  2136.  
  2137. Establish parameters for outgoing packets.  This command is generally used to
  2138. override negotiated values, or to establish before negotiation takes place.
  2139. @Begin(Description,leftmargin +8,indent -8)
  2140. @Index<End Of Line>
  2141. END-OF-LINE @i<character>@\The ASCII character to be used as a line terminator
  2142. for outbound packets, if one is required by the other system, carriage return
  2143. by default.  You will only have to use this command for systems that require a
  2144. line terminator other than carriage return.
  2145.  
  2146. @Index<Packet Length>
  2147. PACKET-LENGTH @i{number}@\ Maximum packet length to send between 10 and 94
  2148. (decimal).  Shortening the packets might allow more of them to get through
  2149. through without error on noisy communication lines.  Lengthening the packets
  2150. increases the throughput on clean lines.  This command can be used to specify
  2151. a shorter length than the one requested by the other Kermit, but not a longer
  2152. one.
  2153.  
  2154. @Index<Timeout>
  2155. TIMEOUT @i<number>@\
  2156. How many seconds to wait for a packet before trying again.  A value of zero
  2157. means don't time out -- wait forever.
  2158.  
  2159. @Index<Pause Between Packets>
  2160. PAUSE @i<floating-point-number>@\ How many seconds to pause before sending each
  2161. data packet.  Setting this to a nonzero value may allow a slow system
  2162. enough time to consolidate itself before the next packet
  2163. arrives.  Normally, no per-packet pausing is done.
  2164.  
  2165. @Index<Padding>
  2166. PADDING @i<number>, PADCHAR @i<character>@\
  2167. How much padding to send before a packet, if the other side needs padding,
  2168. and what character to use for padding.  Defaults are no padding, and NUL
  2169. (0) for the padding character.  This command is also handy for inserting
  2170. special characters that may be required by communications equipment.
  2171.  
  2172. QUOTE @i<character>@\
  2173. What printable character to use for quoting of control characters,
  2174. "#" (43) by default.  There should be no
  2175. reason to change this. 
  2176.  
  2177. @Index<Start Of Packet>
  2178. START-OF-PACKET @i<character>@\
  2179. The start-of-packet character is the only control character used "bare"
  2180. by the Kermit protocol.  It is Control-A by default.  If a bare Control-A
  2181. causes problems for your communication hardware or software, you can use this
  2182. command to select a different control character to mark the start of a packet.
  2183. You must also issue the reciprocal command (SET RECEIVE START-OF-PACKET) to the
  2184. Kermit on the other system (providing it has such a command).
  2185. @End(Description)
  2186.  
  2187. @Subheading<SET RECEIVE>
  2188. Syntax: @q<SET RECEIVE @i<parameter value>>
  2189.  
  2190. Parameters to request or expect for incoming packets, as follows:
  2191. @Begin(Description,leftmargin +8,indent -8)
  2192. @Index<End Of Line>
  2193. END-OF-LINE @i<character>@\
  2194. Carriage return (15) by default.
  2195.  
  2196. @Index<Packet Length>
  2197. PACKET-LENGTH @i<number>@\ Maximum length packet for the other side to send,
  2198. decimal number, between 10 and 94, decimal.  Some Kermit programs also support
  2199. a "long packet" protocol extension for improved file transfer efficiency.  If
  2200. you specify a value greater than 94 (and normally less than 1000 or 2000), then
  2201. the two Kermits will attempt to negotiate the use of long packets in the
  2202. receiver's direction.  If the negotiation is unsuccessful (e.g. because the
  2203. sending Kermit does not support long packets), then ordinary packets will be
  2204. used automatically.
  2205.  
  2206. @Index<Timeout>
  2207. TIMEOUT @i<number>@\How many seconds the other Kermit should wait for a packet
  2208. before asking for retransmission.
  2209.  
  2210. @Index<Pause Between Packets>
  2211. PAUSE @i<floating-point-number>@\How many seconds to pause before acknowledging
  2212. a packet.  Setting this to a nonzero value will slow down the rate at which
  2213. data packets arrive, which may be necessary for systems that have "sensitive"
  2214. front ends and cannot accept input at a high rate.
  2215.  
  2216. @Index<Padding>
  2217. PADDING @i<number>, PADCHAR @i<character>@\How many padding characters to
  2218. request before each incoming packet, and what the padding character should be.
  2219. No Kermits are known to need padding, and if one did, it would request it
  2220. without your having to tell it to do so.  This command would only be necessary,
  2221. therefore, under very unusual circumstances.
  2222.  
  2223. QUOTE @i<character>@\What printable character to use for quoting of control
  2224. characters, "#" (43) by default.  There should be no reason to change this. 
  2225.  
  2226. @Index<Start Of Packet>
  2227. START-OF-PACKET @i<character>@\The control character to mark the beginning
  2228. of incoming packets.  Normally SOH (Control-A, ASCII 1) (see SET SEND
  2229. START-OF-PACKET, above).
  2230. @End(Description)
  2231.  
  2232. @Index<Retry Limit>
  2233. @Subheading<SET RETRY>
  2234. @q<SET RETRY @i<option number>>
  2235.  
  2236. Set the maximum number of retries allowed for:
  2237. @Begin(Description,leftmargin +8,indent -8)
  2238. INITIAL-CONNECTION@\How many times to try establishing the initial protocol
  2239. connection before giving up, normally something like 15. 
  2240.  
  2241. PACKETS@\How many times to try sending a particular packet before giving up,
  2242. normally 5.  If a line is very noisy, you might want to increase this number.
  2243. @End(Description)
  2244.  
  2245. @Index<Warning>@index<File Warning>
  2246. @Subheading<SET WARNING>
  2247. @q<SET WARNING {ON, OFF}>
  2248.  
  2249. Tell Kermit whether to let incoming files overwrite existing files of the same
  2250. name.  If WARNING is ON, then Kermit will warn you of filename collisions and
  2251. will attempt to construct a new, unique name for the arriving file, and inform
  2252. you what the new name is.  When OFF, Kermit silently overwrites existing files
  2253. when there's a name collision.  This command may also be called SET FILE
  2254. WARNING.
  2255.  
  2256. @Section<The DEFINE Command>
  2257. @Index<DEFINE Command>@index<Macros>
  2258. @q<DEFINE> @i<macroname> [@i<command> [, @i<command> [, ...] ] ]
  2259.  
  2260. Define a "macro" to allow convenient association of one or more Kermit commands
  2261. with a mnemonic keyword of your choice.  The definition consists of a list
  2262. a list of one or more Kermit commands, separated by commas.  If you use Kermit
  2263. to communicate with several different kinds of systems, you may set up a macro
  2264. for each, for instance:
  2265. @Begin(Example,leftmargin +1)
  2266. DEFINE IBM SET PARITY MARK, SET DUPLEX HALF, SET HANDSHAKE XON
  2267. DEFINE UNIX SET PARITY NONE, SET DUPLEX FULL, SET HANDSHAKE NONE 
  2268. @Index<TELENET>
  2269. DEFINE TELENET SET PARITY MARK, SET RECEIVE TIMEOUT 20
  2270. @End(Example)
  2271. You may then type DO IBM, DO UNIX, and so forth to set all the desired
  2272. parameters with a single command.  It is convenient to include these
  2273. definitions in your Kermit initialization file. 
  2274.  
  2275. Another other handy use for macros would be for rapid adaptation to
  2276. different conditions of line noise:
  2277. @Begin(Example,leftmargin +1)
  2278. DEFINE CLEAN SET BLOCK-CHECK 1, SET REC PACKET-LEN 94, SET RETRY 5
  2279. DEFINE NOISY SET BLOCK 2, SET SEND PACKET 60, SET RETRY 10
  2280. DEFINE VERY-NOISY SET BLOCK 3, SET SEND PACKET 40, SET RETRY 20
  2281. @End(Example)
  2282.  
  2283. You may redefine an existing macro in the same manner as you defined it.
  2284. You can undefine an existing macro by typing an empty DEFINE command for it,
  2285. for instance:
  2286. @Begin(Example,leftmargin +1)
  2287. DEFINE IBM
  2288. @End(Example)
  2289.  
  2290. You can list all your macros and their definitions with the SHOW MACROS 
  2291. command.  Syntax of SET and DO commands may vary among Kermit programs.
  2292.  
  2293. @Section<The SHOW Command>
  2294. @Index<SHOW Command>
  2295. Syntax: @q<SHOW> [@i<option>]
  2296.  
  2297. The SHOW command displays the values of the parameters settable by the SET
  2298. command.  If a particular option is not requested, a complete display will be
  2299. provided.  Type "show ?" for a list of what can be shown.
  2300.  
  2301. @Section<The STATISTICS Command>
  2302. @index<Statistics>
  2303. Give statistics about the most recent file transfer, such as the total number
  2304. of characters transmitted, the effective baud rate, and so forth.  On some
  2305. systems, this is SHOW STATISTICS.
  2306.  
  2307. @Section<The LOG Command>
  2308. @Index<LOG Command>
  2309. Syntax: @q<LOG> [@i<option>] [@i<filespec>]
  2310.  
  2311. Log the specified entity to the specified log file.
  2312. @begin<description>
  2313. TRANSACTIONS@\Direct Kermit to log transactions, such as files successfully
  2314. sent or  received or files that could not be successfully sent or received.  A
  2315. transaction is useful recording the progress of a long, unattended multifile
  2316. transfer.
  2317.  
  2318. SESSION@\Create a transcript of a CONNECT session, when running a local Kermit
  2319. connected to a remote system, in the specified file.  The log is closed when
  2320. connection is closed.  In some implementations, logging can be "toggled" by
  2321. typing the connect escape character followed by Q (Quit logging) or R (Resume
  2322. logging) or similar single-@|character commands.  Session-@|logging is useful
  2323. for recording dialog with an interactive system, and for "capturing"
  2324. @index<Capturing Files> from systems that don't have Kermit.  No guarantee can
  2325. be made that the file will arrive correctly or completely, since no error
  2326. checking takes place.
  2327.  
  2328. DEBUGGING@\Record debugging information in the specified file.  There may
  2329. be several options to select the desired information -- entire packets,
  2330. state transitions, internal program trace, etc -- available via the SET
  2331. DEBUGGING command.
  2332.  
  2333. PACKETS@\Record packets, and all communication line traffice during file
  2334. transfer, in the specified file.
  2335. @end<description>
  2336.  
  2337. @section<The TRANSMIT Command>
  2338. @index<TRANSMIT Command>
  2339. Syntax: @q<TRANSMIT> @i<filespec>
  2340.  
  2341. Send the contents of the specified file to the other system "bare", without
  2342. protocol, packets, error checking, or retransmission.  This command is useful
  2343. for sending files to systems that don't have Kermit.  No guarantee can be made
  2344. that the target system will receive the file correctly and completely.  When
  2345. receiving a file, the target system would normally be running a text editor in
  2346. text collection mode.
  2347.  
  2348. The current communication settings, such as parity, flow control, and
  2349. handshake, are obeyed by most Kermit versions that have a TRANSMIT command.
  2350. The action is normally line-at-a-time.  Each line of the file is sent,
  2351. terminated by a carriage return (no linefeed), just as you would type it.
  2352. Kermit waits for the remote system to echo a linefeed (as it does when you
  2353. type carriage return) before it sends the next line.
  2354.  
  2355. Thus TRANSMIT provides a "raw upload" capability.  The opposite, "raw
  2356. download", may be accomplished by using the LOG SESSION command.
  2357.  
  2358. @Section<Login Scripts: The INPUT, OUTPUT, CLEAR, and PAUSE Commands>
  2359.  
  2360. @index<Login Scripts>@index<INPUT>@index<OUTPUT>@index<PAUSE>
  2361.  
  2362. When running Kermit in local mode, you may use the INPUT, OUTPUT, CLEAR, and
  2363. PAUSE commands to carry on a dialog with the remote system.  When combined into
  2364. a "script" in a Kermit TAKE command file, these commands provide the ability to
  2365. initially connect and log in to a remote system, and to set it up for file
  2366. transfer.  While you may do this yourself manually using the CONNECT command,
  2367. the login script facility allows this often tedious task to be automated, and
  2368. more important, allows it to take place unattended -- perhaps late at night
  2369. when the phone rates are low and the system is faster.
  2370.  
  2371. @Heading<The CLEAR Command>
  2372.  
  2373. Syntax: @q<CLEAR>
  2374.  
  2375. @index<CLEAR>
  2376. Clear the input and output buffers of the currently selected line, and attempt
  2377. to clear any XOFF deadlock.
  2378.  
  2379. @heading<The PAUSE Command>
  2380. @Index<PAUSE Command>
  2381. Syntax: @q<PAUSE> [@i<interval>]
  2382.  
  2383. Pause the specified number of seconds before executing the next command.
  2384. The default interval is one second.
  2385.  
  2386. @Heading<The INPUT Command>
  2387. @index<INPUT Command>
  2388. Syntax: @q<INPUT> [@i<interval>] [@i<string>]
  2389.  
  2390. @index<Timeout> On the currently selected communication line, look for the
  2391. given string for the specified interval of time, which is specified in seconds.
  2392. If no interval is specified, then wait for the default interval, which may be
  2393. specified by SET INPUT DEFAULT-TIMEOUT, and is normally 5 seconds.  Specifying
  2394. an interval of 0 (or less) means no timeout -- wait forever for the specified
  2395. string.  An INPUT command can normally be interrupted by typing one or more
  2396. Control-C's, which will return you to Kermit prompt level.
  2397.  
  2398. Characters coming in from the line will be scanned for the search string, and
  2399. when a match is found, the command will terminate successfully; if the string
  2400. is not found within the given interval, the command will terminate
  2401. unsuccessfully.
  2402.  
  2403. The search string may contain any printable characters.  Control or other
  2404. special characters that you could not normally type as part of a command
  2405. may be included by preceding their ASCII values
  2406. with a backslash, for instance @q<foo\13> is "foo" followed by a carriage
  2407. return (ASCII 13, decimal).  (Some Kermit programs expect or allow other
  2408. number bases, such as octal or hexadecimal.)
  2409.  
  2410. While scanning, alphabetic case is ignored ("a" = "A") unless you have SET
  2411. INPUT CASE OBSERVE.  If no search string is given, then the INPUT command will
  2412. simply display all incoming characters on your screen until it times out or is
  2413. interrupted.
  2414.  
  2415. If the INPUT command finds the specified string within the alloted amount of
  2416. time, it terminates immediately, without an error message, and the next command
  2417. will be executed.  If the INPUT command fails to find the requested string, it
  2418. will "fail"; failure is only significant if the command was issued from a TAKE
  2419. command, and INPUT TIMEOUT-@|ACTION is SET to QUIT.  When a timeout occurs
  2420. under these conditions, the command file is immediately terminated and control
  2421. is returned to the invoking level, either Kermit prompt level or a superior
  2422. command file.  If INPUT TIMEOUT-@|ACTION is SET to PROCEED, then the next
  2423. command (if any) will be executed from the current command file.
  2424.  
  2425. In addition to otherwise untypable control characters (like Control-C),
  2426. certain printable characters in the search string may need to be "quoted" using
  2427. the backslash mechanism, including at-sign, question mark, or other characters
  2428. that are significat to Kermit's command processor.
  2429.  
  2430. @heading<The OUTPUT Command>
  2431.  
  2432. Syntax: @q<OUTPUT> @i<string>
  2433.  
  2434. The given string is sent out the currently selected communication line.  The
  2435. string is in the same form as the INPUT string; control or special characters
  2436. may be included by prefacing their octal ASCII value with a backslash.  Note
  2437. that any terminating carriage return must be included explicitly as @q<\13>
  2438. (decimal).
  2439.  
  2440. @Heading<How to Use Login Scripts>
  2441.  
  2442. Login scripts are useful on computers that have autodialers or TTY ports
  2443. hardwired or otherwise connected to terminal ports on other systems.
  2444. Scripts can be used to automate the task of connecting and logging in.  For
  2445. instance, suppose your PC is connected to a VAX Unix system through a
  2446. hardwired line on communication port 2.  To send a file to the VAX, you must
  2447. connect to the VAX through the port, log in, run Unix Kermit, escape back
  2448. to the PC, and issue the appropriate file transfer commands, then
  2449. connect back to the VAX and logout.  This may all be automated by means of
  2450. the following "script" stored in a PC file invoked by the Kermit TAKE
  2451. command:
  2452. @begin<example>
  2453. set port 2
  2454. output \13
  2455. input login:
  2456. out myuserid\13
  2457. in 10 Password:
  2458. out mypassword\13
  2459. in 20 %
  2460. out kermit -r\13
  2461. send foo.bar
  2462. out \4
  2463. input
  2464. @end<example>
  2465. The first line points Kermit at the communication line.  The next line sends
  2466. a carriage return, which makes Unix issue a "@q<login:>" prompt; the following
  2467. INPUT command waits for this prompt to appear.  When it does, Kermit outputs
  2468. "myuserid" followed by a carriage return.  Unix then prompts for a password;
  2469. after the prompt appears, Kermit supplies the password.  Then, Kermit
  2470. waits up to 20 seconds for the Unix shell's "@q<%>" prompt; this allows time
  2471. for various system messages to be displayed.  When the shell prompt appears,
  2472. Kermit sends the command "kermit -r", which tells Unix Kermit to receive a
  2473. file; then a SEND command is given to the local Kermit.  After the file is
  2474. successfully transferred, Kermit sends a logout command (Control-D, "\4") to
  2475. Unix.  The final INPUT command causes Kermit to display any typeout (in this
  2476. case the Unix system's logout message) that occurs up to the default timeout
  2477. interval.
  2478.  
  2479. @index<INPUT>@index<Typeahead>
  2480. The INPUT command is very important, because it ensures synchronization.  One
  2481. might expect to be able to simply send all the characters out the communication
  2482. line at once, and let the remote host's typeahead and buffering facilities take
  2483. care of the synchronization.  In rare or simple cases, this might work, but it
  2484. assumes that (a) the remote host allows typeahead, (b) the remote host's
  2485. typeahead buffers are big enough to accommodate all the characters, @i<and> (c)
  2486. that the remote host never clears pending typeahead.  These conditions rarely
  2487. hold.  For instance, Unix clears its input buffer @i<after> issuing the
  2488. "@q<Password:>" prompt; any typeahead will be lost.  Interactive users as well
  2489. as login script facilities must wait for the prompt before entering the
  2490. password.  This is the function of the INPUT command.  On half duplex systems,
  2491. this function is critical -- these systems cannot accept any input in advance
  2492. of a prompt; there is no typeahead.
  2493.  
  2494. @index<SET INPUT>
  2495. The Kermit script facility is not a programming language; there is no
  2496. conditional execution of commands, no branching, no labels.  Nevertheless, the
  2497. SET INPUT command provides a degree of control.  
  2498. If the Unix system were down in the sample script above, Kermit would
  2499. still proceed merrily through the entire script, sending its output into the
  2500. void and waiting the entire timeout interval on each INPUT command, then
  2501. attempting to send a file to a Kermit that wasn't there.  It could take several
  2502. minutes of timing out to terminate the script.  This could be avoided by
  2503. including the command
  2504. @example<SET INPUT TIMEOUT-ACTION QUIT>
  2505. at the top of the script.  When the "@q<login:>" prompt failed to appear within
  2506. the timeout interval, the rest of the script would be cancelled. 
  2507.  
  2508. See the chapters on MS-DOS and DEC-20 Kermit for further examples of login
  2509. scripts.
  2510.  
  2511. @Include<mskerm>
  2512. @Include<ckuker>
  2513. @Include<ckmker>
  2514. @Include<ik0ker>
  2515. @Include<ikcker>
  2516. @Include<iktker>
  2517. @Include<vmsmit>
  2518. @Include<k20mit>
  2519. @Include<k11mit>
  2520. @Include<apple>
  2521. @Include<cpkerm>
  2522. @Include<c86ker>
  2523. @Include(ascii)
  2524. @PageHeading(Odd,Immediate,
  2525.     Left="@xx<Kermit User Guide>",
  2526.     Right="@yy<Page @ref(page)>",
  2527.     Line="@bar()@blankspace(2)")
  2528. @PageHeading(Even,
  2529.     Left="@yy<Page @ref(page)>",
  2530.     Right="@xx<Kermit User Guide>",
  2531.     Line="@bar()@blankspace(2)")
  2532. @Case(Device,x9700="@Comment<Begin Duplex Kludge>
  2533. @SendEnd(#Index `@begin<Transparent,PageBreak UntilOdd>@end<Transparent>')
  2534. @Comment<End Duplex Kludge>")
  2535. @Process(PageHeadings)
  2536.