home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / old / ckermit4e / ckuker.mss < prev    next >
Text File  |  2020-01-01  |  95KB  |  2,094 lines

  1. @Part(CKUNIX,root="kuser")
  2. @string(-ckversion="@q<4E(072)>")
  3. @define(exx=example,above 2,below 1)
  4. @Chapter<UNIX KERMIT>
  5. @index<C-Kermit>@index<UNIX Kermit>
  6.  
  7. @case(device,file="********@*
  8. This document is formatted as an ordinary, plain text ASCII disk file.
  9. Typeset copies are available in the Kermit User Guide from Columbia
  10. University.  Changes should be made to CKUKER.MSS.@*********")
  11.  
  12. @Begin<Description,Leftmargin +12,Indent -12,spread 0>
  13. @i(Program:)@\Frank da Cruz, Bill Catchings, Jeff Damens, Columbia
  14. University; Herm Fischer, Encino CA; contributions by many others.
  15.  
  16. @i(Language:)@\C
  17.  
  18. @i(Documentation:)@\Christine Gianone, Frank da Cruz
  19.  
  20. @i(Version:)@\@value(-ckversion)
  21.  
  22. @i(Date: )@\February 8, 1989
  23. @end<Description>
  24.  
  25. C-Kermit is an implementation of Kermit, written modularly and
  26. transportably in C.  The protocol state transition table is written in
  27. @i'wart', a (non-@|proprietary) lex-@|like preprocessor for C.
  28. System-@|dependent primitive functions are isolated into separately compiled
  29. modules so that the program should be easily portable among Unix systems and
  30. also to non-@|Unix systems that have C compilers, such as VAX/VMS, Data General
  31. AOS/VS, Apollo Aegis, the Apple Macintosh, and the Commodore Amiga.  This
  32. document applies to Unix implementations of C-Kermit, and in most ways also to
  33. the VMS, Data General, and other implementations.
  34.  
  35. @subheading<Unix Kermit Capabilities At A Glance:>
  36. @begin<format,leftmargin +2,above 1,below 1>
  37. @tabclear()@tabset(3.5inches,4.0inches)
  38. Local operation:@\Yes
  39. Remote operation:@\Yes
  40. Login scripts:@\Yes (UUCP style)
  41. Transfer text files:@\Yes
  42. Transfer binary files:@\Yes
  43. Wildcard send:@\Yes
  44. File transfer interruption:@\Yes
  45. Filename collision avoidance:@\Yes
  46. Can time out:@\Yes
  47. 8th-bit prefixing:@\Yes
  48. Repeat count prefixing:@\Yes
  49. Alternate block checks:@\Yes
  50. Terminal emulation:@\Yes
  51. Communication settings:@\Yes
  52. Transmit BREAK:@\Yes (most versions)
  53. Support for dialout modems:@\Yes
  54. IBM mainframe communication:@\Yes
  55. Transaction logging:@\Yes
  56. Session logging:@\Yes
  57. Debug logging:@\Yes
  58. Packet logging:@\Yes
  59. Act as server:@\Yes
  60. Talk to server:@\Yes
  61. Advanced server functions:@\Yes
  62. Local file management:@\Yes
  63. Command/Init files:@\Yes
  64. UUCP and multiuser line locking:@\Yes
  65. Long packets:@\Yes
  66. Sliding Windows:@\No
  67. File attributes packets:@\No
  68. Command macros:@\No
  69. Raw file transmit:@\No
  70. @end<format>
  71.  
  72. @i(All numbers in the C-Kermit documentation are decimal unless noted
  73. otherwise.)
  74.  
  75. @index(C-Kermit)@index(Unix Kermit)
  76. C-Kermit provides traditional Unix command line operation as well as
  77. interactive command prompting and execution.  The command line options
  78. provide access to a basic subset of C-Kermit's capabilities; the
  79. interactive command set is far richer.
  80.  
  81. On systems with dialout modems, C-Kermit's command file, DIAL command, and
  82. login script facilities provide a counterpart to UUCP for file transfer with
  83. non-UNIX operating systems, including the use of scheduled (e.g@. late night)
  84. unattended operation.
  85.  
  86. @section(The Unix File System)
  87.  
  88. Consult your Unix manual for details about the file system under your version
  89. of Unix.  In general, Unix files have lowercase names, possibly
  90. containing one or more dots or other special characters.  Unix directories are
  91. tree-@|structured.  Directory levels are separated by slash (@qq[/])
  92. characters.  For example,
  93. @example(/usr/foo/bar)
  94. denotes the file @q(bar) in the directory @q(/usr/foo).  Alphabetic case is
  95. significant in Unix file and directory names, i.e. @qq<a> is a different file
  96. (or directory) from @qq<A>.  Wildcard or "meta" characters allow groups of
  97. files to be specified.  @qq(*) matches any string; @qq(?) matches any single
  98. character.
  99.  
  100. When C-Kermit is invoked with file arguments specified on the Unix command
  101. line, the Unix shell (Bourne Shell, C-Shell, K-Shell, etc) expands the meta
  102. characters itself, and in this case a wider variety is available.  For example,
  103. @example(kermit -s ~/ck[uvm]*.{upd,bwr}]) is expanded by the Berkeley C-Shell
  104. into a list of all the files in the user's home directory (@q[~/]) that start
  105. with the characters "@q(ck)", followed by a single character @qq(u), @qq(v), or
  106. @qq(m), followed by zero or more characters, followed by a dot, followed by one
  107. of the strings @qq(upd) or @qq(bwr).  Internally, the C-Kermit program itself
  108. expands only the @qq(*) and @qq(?) meta characters.
  109.  
  110. Unix files are linear (sequential) streams of 8-bit bytes.  Text files consist
  111. of 7-bit ASCII characters, with the high-@|order bit off (0), and lines
  112. separated by the Unix newline character, which is linefeed (LF, ASCII 10).
  113. This distinguishes Unix text files from those on most other ASCII systems, in
  114. which lines are separated by a carriage-@|return linefeed sequence (CRLF, ASCII
  115. 13, followed by linefeed, ASCII 10).  Binary files are likely to contain data
  116. in the high bits of the file bytes, and have no particular line or record
  117. structure.
  118.  
  119. When transferring files, C-Kermit will convert between upper and lower
  120. case filenames and between LF and CRLF line terminators automatically,
  121. unless told to do otherwise.  When binary files must be transferred, the
  122. program must be instructed not to perform LF/CRLF conversion (@q[-i] on the
  123. command line or "set file type binary" interactively; see below).
  124.  
  125. @section(File Transfer)
  126.  
  127. If C-Kermit is in local mode, the screen (stdout) is continously updated to
  128. show the progress of the file transer.  A dot is printed for every four data
  129. packets, other packets are shown by type:
  130. @begin(description,leftmargin +6, indent -2, spread 0)
  131. I@\Exchange Parameter Information
  132.  
  133. R@\Receive Initiate
  134.  
  135. S@\Send Initiate
  136.  
  137. F@\File Header
  138.  
  139. G@\Generic Server Command
  140.  
  141. C@\Remote Host Command
  142.  
  143. N@\Negative Acknowledgement (NAK)
  144.  
  145. E@\Fatal Error
  146.  
  147. T@\Indicates a timeout occurred
  148.  
  149. Q@\Indicates a damaged, undesired, or illegal packet was received
  150.  
  151. @q<%>@\Indicates a packet was retransmitted
  152. @end(description)
  153. You may type certain "interrupt" commands during file transfer:
  154. @begin(description,leftmargin +16,indent -12,spread 0)
  155. Control-F:@\Interrupt the current File, and go on to the next (if any).
  156.  
  157. Control-B:@\Interrupt the entire Batch of files, terminate the transaction.
  158.  
  159. Control-R:@\Resend the current packet
  160.  
  161. Control-A:@\Display a status report for the current transaction.
  162. @end(description)
  163.  These interrupt characters differ from the ones used in other Kermit
  164. implementations to avoid conflict with commonly used Unix shell interrupt
  165. characters.  With Version 7, System III, and System V implementations of
  166. Unix, interrupt commands must be preceeded by the 'connect' escape character
  167. (e.g. normally-@q[\]).  Ctrl-F and Ctrl-B are effective only during the
  168. transfer of data (D) packets, and cannot be used to interrupt a transfer that
  169. has not yet reached that stage.
  170.  
  171. @begin(quotation)
  172. @i(CAUTION:)@index(Warning)@index<File Warning>
  173.  If Control-F or Control-B is used to cancel an incoming file,
  174. and a file of the same name previously existed, @i(and) the "file warning"
  175. feature is not enabled, then the previous copy of the file will disappear.
  176. @end(quotation)
  177.  
  178. @i(EMERGENCY EXIT:)@index<Emergency Exit>
  179.  When running Unix Kermit in remote mode, if you have started a protocol
  180. operation (sending or receiving a file, server command wait, etc), you will not
  181. be able to communicate with the terminal in the normal way.  In particular, you
  182. cannot stop the protocol by typing the normal Unix interrupt characters, since
  183. the terminal has been put in "raw mode".  If you need to regain control quickly
  184. -- for instance, because the protocol is stuck -- you can type two Control-C's
  185. directly to the Unix Kermit program ("connect" first if necessary):
  186. @display<Control-C Control-C>
  187. This will cause the program to display,
  188. @display<@q[^C^C...]>
  189. exit, and restore the terminal to normal.
  190.  
  191. @section(Command Line Operation)
  192.  
  193. The C-Kermit command line syntax conforms to the @ux(Proposed Syntax Standards
  194. for Unix System Commands) put forth by Kathy Hemenway and Helene Armitage of
  195. AT&T Bell Laboratories in @i(Unix/World), Vol.1, No.3, 1984.  The rules that
  196. apply are:
  197. @begin(itemize,spread 0)
  198. Command names must be between 2 and 9 characters ("kermit" is 6).
  199.  
  200. Command names must include lower case letters and digits only.
  201.  
  202. An option name is a single character.
  203.  
  204. Options are delimited by '@q(-)'.
  205.  
  206. Options with no arguments may be grouped (bundled) behind one delimiter.
  207.  
  208. Option-arguments cannot be optional.
  209.  
  210. Arguments immediately follow options, separated by whitespace.
  211.  
  212. The order of options does not matter.
  213.  
  214. '@q(-)' preceded and followed by whitespace means standard input.
  215. @end(itemize)
  216. A group of bundled options may end with an option that has an argument.
  217.  
  218. The following notation is used in command descriptions:
  219. @begin(description,leftmargin +8,indent -8)
  220. @i(fn)@\A Unix file specification, possibly containing the "wildcard"
  221. characters `@q[*]' or `@q[?]' (`@q[*]' matches all character strings, `@q[?]'
  222. matches any single character).
  223.  
  224. @i(fn1)@\A Unix file specification which may not contain `@q[*]' or `@q[?]'.
  225.  
  226. @i(rfn)@\A remote file specification in the remote system's own syntax, which
  227. may denote a single file or a group of files.
  228.  
  229. @i(rfn1)@\A remote file specification which should denote only a single file.
  230.  
  231. @i(n)@\A decimal number between 0 and 94.
  232.  
  233. @i(c)@\A decimal number between 0 and 127 representing the value of an
  234. ASCII character.
  235.  
  236. @i(cc)@\A decimal number between 0 and 31, or else exactly 127,
  237. representing the value of an ASCII control character.
  238.  
  239. @q([ ])@\Any field in square braces is optional.
  240.  
  241. @q({x,y,z})@\Alternatives are listed in curly braces.
  242. @end(description)
  243.  
  244. C-Kermit command line options may specify any combination of actions and
  245. settings.  If C-Kermit is invoked with a command line that specifies no
  246. actions, then it will issue a prompt and begin interactive dialog.  Action
  247. options specify either protocol transactions or terminal connection.
  248.  
  249. @begin<description,leftmargin +8,indent -8>
  250. @q(-s )@i(fn)@\Send the specified file or files.  If @i(fn) contains
  251. wildcard (meta) characters, the Unix shell expands it into a list.  If @i(fn)
  252. is '@q[-]' then kermit sends from standard input, which may
  253. come from a file:
  254. @example(kermit -s - < foo.bar)
  255. or a parallel process:
  256. @example(ls -l | grep christin | kermit -s -)
  257. You cannot use this mechanism to send
  258. terminal typein.  If you want to send a file whose actual name is @qq(-)
  259. you can precede it with a path name, as in
  260. @example(kermit -s ./-)
  261.  
  262. @q(-r)@\Receive a file or files.  Wait passively for files to arrive.
  263.  
  264. @q(-k)@\Receive (passively) a file or files, sending them to standard
  265. output.  This option can be used in several ways:
  266. @begin(description,leftmargin +4,indent -4)
  267. @q(kermit -k)@\Displays the incoming files on your screen; to be used only
  268. in "local mode" (see below).
  269.  
  270. @q(kermit -k > )@i(fn1)@\Sends the incoming file or files to the named file,
  271. @i(fn1).  If more than one file arrives, all are concatenated together
  272. into the single file @i(fn1).
  273.  
  274. @q(kermit -k | command)@\Pipes the incoming data (single or multiple
  275. files) to the indicated command, as in
  276. @example'kermit -k | sort > sorted.stuff'
  277. @end(description)
  278.  
  279. @q(-a )@i(fn1)@\If you have specified a file transfer option, you may give
  280. an alternate name for a single file with the @q(-a) ("as") option.  For
  281. example,
  282. @example'kermit -s foo -a bar'
  283. sends the file @q(foo) telling the receiver that its name is @q(bar).
  284. If more than one file arrives or is sent, only the first file is
  285. affected by the @q(-a) option:
  286. @example'kermit -ra baz'
  287. stores the first incoming file under the name @q(baz).
  288.  
  289. @q(-x)@\Begin server operation.  May be used in either local or remote mode.
  290. @end(description)
  291.  
  292. Before proceeding, a few words about remote and local operation are
  293. necessary.  C-Kermit is "local" if it is running on PC or workstation that
  294. you are using directly, or if it is running on a multiuser system and
  295. transferring files over an external communication line -- not your job's
  296. controlling terminal or console.  C-Kermit is remote if it is running on a
  297. multiuser system and transferring files over its own controlling terminal's
  298. communication line (normally @q</dev/tty>), connected to your PC or
  299. workstation.
  300.  
  301. If you are running C-Kermit on a PC, it is normally used in local mode,
  302. with the "back port" designated for file transfer and terminal connection.
  303. If you are running C-Kermit on a multiuser (timesharing) system, it is
  304. in remote mode unless you explicitly point it at an external line for
  305. file transfer or terminal connection.  The following command sets
  306. C-Kermit's "mode":
  307.  
  308. @begin(description,leftmargin +8,indent -8)
  309. @q(-l )@i(dev)@\Line  -- Specify a terminal line to use for file
  310. transfer and terminal connection, as in
  311. @example'kermit -l /dev/ttyi5'
  312. @end(description)
  313.  
  314. When an external line is being used, you will also need some additional
  315. options for successful communication with the remote system:
  316.  
  317. @begin(description,leftmargin +8,indent -8)
  318. @q(-b )@i(n)@\Baud  -- Specify the baud rate for the line given in the
  319. @q(-l) option, as in
  320. @example'kermit -l /dev/ttyi5 -b 9600'
  321. This option should always be included with the @q(-l) option, since the
  322. speed of an external line is not necessarily what you expect.
  323.  
  324. @q(-p )@i(x)@\Parity -- e,o,m,s,n (even, odd, mark, space, or none).  If parity
  325. is other than none, then the 8th-bit prefixing mechanism will be
  326. used for transferring 8-bit binary data, provided the opposite
  327. Kermit agrees.  The default parity is none.
  328.  
  329. @q(-t)@\Specifies half duplex, line turnaround with XON as the handshake
  330. character.
  331. @end(description)
  332.  
  333. The following commands may be used only with a C-Kermit which is local
  334. either by default or else because the @q<-l> option has been specified.
  335.  
  336. @begin(description,leftmargin +8,indent -8)
  337. @q(-g )@i(rfn)@\Actively request a remote server to send the named file
  338. or files; @i(rfn) is a file specification in the remote host's own syntax.  If
  339. @i(fn) happens to contain any special shell characters, like space, '@q(*)',
  340. '@q([)', etc, these must be quoted, as in
  341. @example'kermit -g x\*.\?'
  342. or
  343. @example'kermit -g "profile exec"'
  344.  
  345. @q(-f)@\Send a 'finish' command to a remote server.
  346.  
  347. @q(-c)@\Establish a terminal connection over the specified or default
  348. communication line, before any protocol transaction takes place.
  349. Get back to the local system by typing the escape character
  350. (normally Control-Backslash) followed by the letter 'c'.
  351.  
  352. @q(-n)@\Like @q(-c), but @i(after) a protocol transaction takes place;
  353. @q(-c) and @q(-n) may both be used in the same command.  The use of @q(-n)
  354. and @q(-c) is illustrated below.
  355. @end(description)
  356. If the other Kermit is on a remote system, the @q(-l) and @q(-b) options should
  357. also be included with the @q(-r), @q(-k), or @q(-s) options.
  358.  
  359. Several other command-line options are provided:
  360. @begin(description,leftmargin +8,indent -8)
  361. @q(-i)@\Specifies that files should be sent or received exactly "as is" with no
  362. conversions.  This option is necessary for transmitting binary files.  It may
  363. also be used in Unix-to-Unix transfers (it must be given to @i<both> Unix
  364. Kermit programs), where it will improve performance by circumventing the normal
  365. text-file conversions, and will allow mixture of text and binary files in a
  366. single file group.
  367.  
  368. @q(-w)@\Write-Protect -- Avoid filename collisions for incoming files.
  369.  
  370. @q(-e @i<n>)@\Extended packet length -- Specify that C-Kermit is allowed to
  371. receive packets up to length @i<n>, where @i<n> may be between 10 and some
  372. large number, like 1000, depending on the system.  The default maximum length
  373. for received packets is 90.  Packets longer than 94 will be used only if the
  374. other Kermit supports, and agrees to use, the "long packet" protocol extension.
  375.  
  376. @q(-q)@\Quiet -- Suppress screen update during file transfer, for instance
  377. to allow a file transfer to proceed in the background.
  378.  
  379. @q(-d)@\Debug -- Record debugging information in the file @q(debug.log) in 
  380. the current directory.  Use this option if you believe the program
  381. is misbehaving, and show the resulting log to your local
  382. Kermit maintainer.
  383.  
  384. @q(-h)@\Help -- Display a brief synopsis of the command line options.
  385. @end(description)
  386. The command line may contain no more than one protocol action option.
  387.  
  388. Files are sent with their own names, except that lowercase letters are raised
  389. to upper, pathnames are stripped off, certain special characters like (`@q[~]')
  390. and (`@q[#]') are changed to `@q(X)', and if the file name begins with a
  391. period, an `@q(X)' is inserted before it.  Incoming files are stored under
  392. their own names except that uppercase letters are lowered, and, if @q(-w) was
  393. specified, a "generation number" is appended to the name if it has the same
  394. name as an existing file which would otherwise be overwritten.  If the @q(-a)
  395. option is included, then the same rules apply to its argument.  The file
  396. transfer display shows any transformations performed upon filenames.
  397.  
  398. During transmission, files are encoded as follows:
  399. @begin(itemize)
  400. Control characters are converted to prefixed printables.
  401.  
  402. Sequences of repeated characters are collapsed via repeat counts, if
  403. the other Kermit is also capable of repeated-@|character compression.
  404.  
  405. If parity is being used on the communication line, data characters with 
  406. the 8th (parity) bit on are specially prefixed, provided the other Kermit
  407. is capable of 8th-bit prefixing; if not, 8-bit binary files cannot be
  408. successfully transferred.
  409.  
  410. Conversion is done between Unix newlines and carriage-@|return-@|linefeed 
  411. sequences unless the @q(-i) option was specified.
  412. @end(itemize)
  413.  
  414. @subheading(Command Line Examples:)
  415.  
  416. @exx(kermit -l /dev/ttyi5 -b 1200 -cn -r)
  417. This command connects you to the system on the other end of @q(ttyi5) at
  418. 1200 baud, where you presumably log in and run Kermit with a 'send'
  419. command.  After you escape back, C-Kermit waits for a file (or files) to
  420. arrive.  When the file transfer is completed, you are reconnected to
  421. the remote system so that you can logout.
  422.  
  423. @exx(kermit -l /dev/ttyi4 -b 1800 -cntp m -r -a foo)
  424. This command is like the preceding one, except the remote system in this
  425. case uses half duplex communication with mark parity.  The first file
  426. that arrives is stored under the name @q(foo).
  427.  
  428. @exx(kermit -l /dev/ttyi6 -b 9600 -c | tek)
  429. This example uses Kermit to connect your terminal to the system at the
  430. other end of @q(ttyi6).  The C-Kermit terminal connection does not
  431. provide any particular terminal emulation, so C-Kermit's standard i/o is
  432. piped through a (hypothetical) program called tek, which performs (say)
  433. Tektronix emulation.
  434.  
  435. @exx(kermit -l /dev/ttyi6 -b 9600 -nf)
  436. This command would be used to shut down a remote server and then connect
  437. to the remote system, in order to log out or to make further use of it.
  438. The @q(-n) option is invoked @i(after) @q(-f) (@q[-c] would have been invoked
  439. before).
  440.  
  441. @exx(kermit -l /dev/ttyi6 -b 9600 -qg foo.\* &)
  442. This command causes C-Kermit to be invoked in the background, getting a group
  443. of files from a remote server (note the quoting of the `@q[*]' character).  No
  444. display occurs on the screen, and the keyboard is not sampled for
  445. interruption commands.  This allows other work to be done while file
  446. transfers proceed in the background.
  447.  
  448. @exx(kermit -l /dev/ttyi6 -b 9600 -g foo.\* > foo.log < /dev/null &)
  449. This command is like the previous one, except the file transfer display has
  450. been redirected to the file @q(foo.log).  Standard input is also redirected, to
  451. prevent C-Kermit from sampling it for interruption commands.
  452.  
  453. @exx(kermit -iwx)
  454. This command starts up C-Kermit as a server.  Files are transmitted with no
  455. newline/@|carriage-@|return-@|linefeed conversion; the @q(-i) option is
  456. necessary for binary file transfer and recommended for Unix-@|to-@|Unix
  457. transfers.  Incoming files that have the same names as existing files are given
  458. new, unique names.
  459.  
  460. @exx(kermit -l /dev/ttyi6 -b 9600)
  461. This command sets the communication line and speed.  Since no action is
  462. specified, C-Kermit issues a prompt and enters an interactive dialog with
  463. you.  Any settings given on the command line remain in force during the
  464. dialog, unless explicitly changed.
  465.  
  466. @exx(kermit)
  467. This command starts up Kermit interactively with all default settings.
  468.  
  469. The next example shows how Unix Kermit might be used to send an entire
  470. directory tree from one Unix system to another, using the tar program as
  471. Kermit's standard input and output.  On the orginating system, in this case the
  472. remote, type (for instance):@label(-uxtar)
  473.  
  474. @exx(tar cf - /usr/fdc | kermit -is -)
  475. This causes tar to send the directory @q(/usr/fdc) (and all its files and all
  476. its subdirectories and all their files...) to standard output instead of to a
  477. tape; kermit receives this as standard input and sends it as a binary file.
  478. On the receiving system, in this case the local one, type (for instance):
  479.  
  480. @exx(kermit -il /dev/ttyi5 -b 9600 -k | tar xf -)
  481. Kermit receives the tar archive, and sends it via standard output to its own
  482. copy of tar, which extracts from it a replica of the original directory tree.
  483.  
  484. A final example shows how a Unix compression utility might be used to speed
  485. up Kermit file transfers:
  486. @begin(example)
  487. compress file | kermit -is -     (@i(sender))
  488. kermit -ik | uncompress          (@i(receiver))
  489. @end(example)    
  490.  
  491. @subheading(Exit Status Codes:)
  492.  
  493. Unix Kermit returns an exit status of zero, except when a fatal error is
  494. encountered, where the exit status is set to one.  With background
  495. operation (e.g., `@q(&)' at end of invoking command line) driven by scripted
  496. interactive commands (redirected standard input and/or take files),
  497. any failed interactive command (such as failed dial or script attempt)
  498. causes the fatal error exit.
  499.  
  500. @section(Interactive Operation)
  501.  
  502. C-Kermit's interactive command prompt is "@q(C-Kermit>)".  In response to this
  503. prompt, you may type any valid interactive C-Kermit command.  C-Kermit executes
  504. the command and then prompts you for another command.  The process continues
  505. until you instruct the program to terminate.
  506.  
  507. Commands begin with a keyword, normally an English verb, such as "send".  You
  508. may omit trailing characters from any keyword, so long as you specify
  509. sufficient characters to distinguish it from any other keyword valid in that
  510. field.  Certain commonly-@|used keywords (such as "send", "receive", "connect")
  511. also have special non-@|unique abbreviations ("s" for "send", "r" for
  512. "receive", "c" for "connect").
  513.  
  514. Certain characters have special functions during typein of interactive
  515. commands:
  516. @Begin(Description,leftmargin +8,indent -4)
  517. @q(?)@\Question mark, typed at any point in a command, will produce a
  518. message explaining what is possible or expected at that point.  Depending on
  519. the context, the message may be a brief phrase, a menu of keywords, or a list
  520. of files.
  521.  
  522. @q(ESC)@\(The Escape or Altmode key) -- Request completion of the current
  523. keyword or filename, or insertion of a default value.  The result will be a
  524. beep if the requested operation fails.
  525.  
  526. @q(TAB)@\(The horizontal Tab key) -- Same as ESC.
  527.  
  528. @q(DEL)@\(The Delete or Rubout key) -- Delete the previous character from the
  529. command.  You may also use BS (Backspace, Control-H) for this function.
  530.  
  531. @q(^W)@\(Control-W) -- Erase the rightmost word from the command line.
  532.  
  533. @q(^U)@\(Control-U) -- Erase the entire command.
  534.  
  535. @q(^R)@\(Control-R) -- Redisplay the current command.
  536.  
  537. @q(SP)@\(Space) -- Delimits fields (keywords, filenames, numbers) within
  538. a command.
  539.  
  540. @q(CR)@\(Carriage Return) -- Enters the command for execution.  LF (Linefeed)
  541. or FF (formfeed) may also be used for this purpose.
  542.  
  543. @q(\)@\(Backslash) -- Enter any of the above characters into the command,
  544. literally.  To enter a backslash, type two backslashes in a row (@q[\\]).
  545. A backslash at the end of a command line causes the next line to be treated
  546. as a continuation line; this is useful for readability in command files,
  547. especially in the 'script' command.
  548.  
  549. @q(^Z)@\(Control-Z) -- On systems (like Berkeley Unix, Ultrix) with job
  550. control, suspend Kermit, i.e. put it into the @index<Background> background in
  551. such a way that it can be brought back into the foreground (e.g. with an
  552. '@q<fg>' shell command) with all its settings intact.
  553. @End(Description)
  554. You may type the editing characters (@q[DEL], @q[^W], etc) repeatedly, to
  555. delete all the way back to the prompt.  No action will be performed until the
  556. command is entered by typing carriage return, linefeed, or formfeed.  If you
  557. make any mistakes, you will receive an informative error message and a new
  558. prompt -- make liberal use of `@q[?]' and ESC to feel your way through the
  559. commands.  One important command is "help" -- you should use it the first time
  560. you run C-Kermit.
  561.  
  562. A command line beginning with a percent sign @qq(%) is ignored.  Such
  563. lines may be used to include illustrative commentary in Kermit command dialogs.
  564.  
  565. Interactive C-Kermit accepts commands from files as well as from the keyboard.
  566. When you start C-Kermit, the program looks for the file @q(.kermrc) in your
  567. home or current directory (first it looks in the home directory, then in the
  568. current one) and executes any commands it finds there.  These commands must be
  569. in interactive format, not Unix command-@|line format.  A "take" command is
  570. also provided for use at any time during an interactive session, to allow
  571. interactive-format commands to be executed from a file; command files may be
  572. nested to any reasonable depth.
  573.  
  574. Here is a brief list of C-Kermit interactive commands:
  575. @begin(format,spread 0)
  576. @tabclear()@tabset(1.5inches,2.0inches,2.5inches)
  577. @>%@\  Comment
  578. @>!@\  Execute a Unix shell command, or start a shell.
  579. @>bye@\  Terminate and log out a remote Kermit server.
  580. @>close@\  Close a log file.
  581. @>connect@\  Establish a terminal connection to a remote system.
  582. @>cwd@\  Change Working Directory (also, cd).
  583. @>dial@\  Dial a telephone number.
  584. @>directory@\  Display a directory listing.
  585. @>echo@\  Display arguments literally.
  586. @>exit@\  Exit from the program, closing any open files.
  587. @>finish@\  Instruct a remote Kermit server to exit, but not log out.
  588. @>get@\  Get files from a remote Kermit server.
  589. @>hangup@\  Hang up the phone (for use in local mode).
  590. @>help@\  Display a help message for a given command.
  591. @>log@\  Open a log file -- debugging, packet, session, transaction.
  592. @>quit@\  Same as 'exit'.
  593. @>receive@\  Passively wait for files to arrive.
  594. @>remote@\  Issue file management commands to a remote Kermit server.
  595. @>script@\  Execute a login script with a remote system.
  596. @>send@\  Send files.
  597. @>server@\  Begin server operation.
  598. @>set@\  Set various parameters.
  599. @>show@\  Display values of 'set' parameters.
  600. @>space@\  Display current disk space usage.
  601. @>statistics@\  Display statistics about most recent transaction.
  602. @>take@\  Execute commands from a file.
  603. @end(format)
  604.  
  605. The 'set' parameters are:
  606. @begin(format,spread 0)
  607. @tabclear()@tabset(1.5inches,2.0inches,2.5inches)
  608. @>block-check@\  Level of packet error detection.
  609. @>delay@\  How long to wait before sending first packet.
  610. @>duplex@\  Specify which side echoes during 'connect'.
  611. @>escape-character@\  Prefix for "escape commands" during 'connect'.
  612. @>file@\  Set various file parameters.
  613. @>flow-control@\  Communication line full-duplex flow control.
  614. @>handshake@\  Communication line half-duplex turnaround character.
  615. @>incomplete@\  Disposition for incompletely received files.
  616. @>line@\  Communication line device name.
  617. @>modem-dialer@\  Type of modem-dialer on communication line.
  618. @>parity@\  Communication line character parity.
  619. @>prompt@\  The C-Kermit program's interactive command prompt.
  620. @>receive@\  Parameters for inbound packets.
  621. @>retry@\  Packet retransmission limit.
  622. @>send@\  Parameters for outbound packets.
  623. @>speed@\  Communication line speed.
  624. @>terminal@\  Terminal parameters.
  625. @end(format)
  626.  
  627. The 'remote' commands are:
  628. @begin(format,spread 0)
  629. @tabclear()@tabset(1.5inches,2.0inches,2.5inches)
  630. @>cwd@\  Change remote working directory.
  631. @>delete@\  Delete remote files.
  632. @>directory@\  Display a listing of remote file names.
  633. @>help@\  Request help from a remote server.
  634. @>host@\  A command to the remote host in its own command language.
  635. @>space@\  Display current disk space usage on remote system.
  636. @>type@\  Display a remote file on your screen.
  637. @>who@\  Display who's logged in, or get information about a user.
  638. @end(format)
  639.  
  640. Most of these commands are described adequately in the Kermit User Guide or the
  641. Kermit book.  Special aspects of certain Unix Kermit commands are described
  642. below.
  643.  
  644. @heading<The 'send' command>
  645.  
  646. Syntax:  @q<send >@i(fn)@q<@ @ - >@i<or>@q< -@ @ >@q<send >@i(fn1)@q< >@i<rfn1>
  647.  
  648. Send the file or files denoted by @i(fn) to the other Kermit, which should be
  649. running as a server, or which should be given the 'receive' command.  Each file
  650. is sent under its own name (as described above, or as specified by the 'set
  651. file names' command).  If the second form of the 'send' command is used, i.e.
  652. with @i(fn1) denoting a single Unix file, @i(rfn1) may be specified as a name
  653. to send it under.  The 'send' command may be abbreviated to 's', even though
  654. 's' is not a unique abbreviation for a top-level C-Kermit command.
  655.  
  656. The wildcard (meta) characters `@q[*]' and `@q[?]' are accepted in @i(fn).  If
  657. `@q[?]' is to be included, it must be prefixed by `@q[\]' to override its
  658. normal function of providing help.  `@q[*]' matches any string, `@q[?]' matches
  659. any single character.  Other notations for file groups, like `@q([a-z]og)', are
  660. not available in interactive commands (though of course they are available on
  661. the command line).  When @i(fn) contains `@q[*]' or `@q[?]' characters, there
  662. is a limit to the number of files that can be matched, which varies from system
  663. to system.  If you get the message "Too many files match" then you'll have to
  664. make a more judicious selection.  If @i(fn) was of the form
  665. @example(usr/longname/anotherlongname/*)
  666. then C-Kermit's string space will fill up rapidly -- try doing a cwd (see
  667. below) to the path in question and reissuing the command.
  668.  
  669. In interactive mode, C-Kermit does not presently understand "@q<~>" notation
  670. for "home directory", as used in the C-Shell and K-Shell, nor does it
  671. understand "@q<[abc]>" or "@q<{txt,doc}>" filename metacharacter notation.
  672.  
  673. @i<Note> -- C-Kermit sends only from the current or specified directory.  It
  674. does not traverse directory trees.  If the source directory contains
  675. subdirectories, they will be skipped.  By the same token, C-Kermit does not
  676. create directories when receiving files.  If you have a need to do this, you
  677. can pipe tar through C-Kermit, as shown in the example on page
  678. @pageref(-uxtar), or under System III/V Unix you can use cpio.
  679.  
  680. @i<Another Note> -- The 'send' command does not skip over "invisible" files
  681. that match the file specification; Unix systems usually treat files whose names
  682. start with a dot (like @q(.login), @q(.cshrc), and @q(.kermrc)) as invisible.
  683. Similarly for "temporary" files whose names start with "@q(#)".
  684.  
  685. @heading<The 'receive' command>
  686.  
  687. Syntax:  @q<receive@ @ - >@i<or>@q< -@ @ receive >@i<fn1>
  688.  
  689. Passively wait for files to arrive from the other Kermit, which must be given
  690. the 'send' command -- the 'receive' command does not work in conjunction with a
  691. server (use 'get' for that).  If @i(fn1) is specified, store the first incoming
  692. file under that name.  The 'receive' command may be abbreviated to 'r'.
  693.  
  694.  
  695. @heading<The 'get' command:>
  696.  
  697. Syntax:@q<  get >@i<rfn>
  698. @begin(example)
  699.     @i<or>: get
  700.             @i(rfn)
  701.             @i(fn1)
  702. @end(example)
  703. Request a remote Kermit server to send the named file or files.  Since a
  704. remote file specification (or list) might contain spaces, which normally
  705. delimit fields of a C-Kermit command, an alternate form of the command is
  706. provided to allow the inbound file to be given a new name: type 'get' alone
  707. on a line, and you will be prompted separately for the remote and local
  708. file specifications, for example
  709. @Begin(Example)
  710. C-Kermit>@ux(get)
  711.  Remote file specification: @ux(profile exec)
  712.  Local name to store it under: @ux(profile.exec)
  713. @End(Example)
  714. As with 'receive', if more than one file arrives as a result of the 'get'
  715. command, only the first will be stored under the alternate name given by
  716. @i(fn1); the remaining files will be stored under their own names if possible.
  717. If a `@q[?]' is to be included in the remote file specification, you must
  718. prefix it with `@q[\]' to suppress its normal function of providing help.
  719.  
  720. If you have started a multiline 'get' command, you may escape from its
  721. lower-@|level prompts by typing a carriage return in response to the prompt,
  722. e.g.
  723. @Begin(Example)
  724. C-Kermit>@ux(get)
  725.  Remote file specification: @ux(foo)
  726.  Local name to store it under: @i<(Type a carriage return here)>
  727. (cancelled)
  728. C-Kermit>
  729. @End(Example)
  730.  
  731. @heading(The 'server' command:)
  732.  
  733. The 'server' command places C-Kermit in "server mode" on the currently selected
  734. communication line.  All further commands must arrive as valid Kermit packets
  735. from the Kermit on the other end of the line.  The Unix Kermit server can
  736. respond to the following commands:
  737. @begin(format,spread 0,above 1,below 1)
  738. @tabclear()@tabset(2.25inches)
  739. @u<Command>@\@ux<Server Response>
  740.   get@\  Sends files
  741.   send@\  Receives files
  742.   bye@\  Attempts to log itself out
  743.   finish@\  Exits to level from which it was invoked
  744.   remote directory@\  Sends directory lising
  745.   remote delete@\  Removes files
  746.   remote cwd@\  Changes working directory (also, remote cd)
  747.   remote type@\  Sends files to your screen
  748.   remote space@\  Reports about its disk usage
  749.   remote who@\  Shows who's logged in
  750.   remote host@\  Executes a Unix shell command
  751.   remote help@\  Lists these capabilities
  752. @end(format)
  753. The Unix Kermit server cannot always respond properly to a BYE command.
  754. It will attempt to do so using "@q<kill()>", but this will not work
  755. on all systems or under all conditions because of the complicated process
  756. structures that can be set up under Unix.
  757.  
  758. If the Kermit server is directed at an external line (i.e. it is in "local
  759. mode") then the console may be used for other work if you have 'set file
  760. display off'; normally the program expects the console to be used to observe
  761. file transfers and enter status queries or interruption commands.  The way to
  762. get C-Kermit into background@index<Background> operation from interactive
  763. command level varies from system to system (e.g. on Berkeley Unix you would
  764. halt the program with @q(^Z) and then use the C-Shell 'bg' command to continue
  765. it in the background).  The more common method is to invoke the program with
  766. the desired command line arguments, including "@q(-q)", and with a terminating
  767. "@q(&)".
  768.  
  769. When the Unix Kermit server is given a 'remote host' command, it executes it
  770. using the shell invoked upon login, e.g. the Bourne shell or the Berkeley
  771. C-Shell.
  772.  
  773. @Heading(The 'remote', 'bye', and 'finish' commands:)
  774.  
  775. C-Kermit may itself request services from a remote Kermit server.  In
  776. addition to 'send' and 'get', the following commands may also be sent from
  777. C-Kermit to a Kermit server:
  778.  
  779. @begin(description,leftmargin +8,indent -4)
  780. remote cwd [@i(directory)]@\If the optional remote directory specification is
  781. included, you will be prompted on a separate line for a password, which will
  782. not echo as you type it.  If the remote system does not require a password
  783. for this operation, just type a carriage return.  'remote cd' is a synomym for
  784. this command.
  785. @end(description)
  786. @begin(description,leftmargin +28, indent -24,spread 0,above 1)
  787. remote delete rfn@\delete remote file or files.
  788.  
  789. remote directory [@i(rfn)]@\directory listing of remote files.
  790.  
  791. remote host @i(command)@\command in remote host's own command language.
  792.  
  793. remote space@\disk usage report from remote host.
  794.  
  795. remote type [@i(rfn)]@\display remote file or files on the screen.
  796.  
  797. remote who [@i(user)]@\display information about who's logged in.
  798.  
  799. remote help@\display remote server's capabilities.
  800. @end(description)
  801. @begin(description,leftmargin +8,indent -4)
  802. bye @i(and) finish:@\When connected to a remote Kermit server, these commands
  803. cause the remote server to terminate; 'finish' returns it to Kermit or system
  804. command level (depending on the implementation or how the program was invoked);
  805. 'bye' also requests it to log itself out.
  806. @end(description)
  807. @heading(The 'log' and 'close' commands:)
  808.  
  809. Syntax: @q<log {debugging, packets, session, transactions} >[ @i(fn1) ]
  810.  
  811. C-Kermit's progress may be logged in various ways.  The 'log' command
  812. opens a log, the 'close' command closes it.  In addition, all open logs
  813. are closed by the 'exit' and 'quit' commands.  A name may be specified for
  814. a log file; if the name is omitted, the file is created with a default
  815. name as shown below.
  816.  
  817. @begin(description,leftmargin +4,indent -4)
  818. log debugging@\This produces a voluminous log of the internal workings of
  819. C-Kermit, of use to Kermit developers or maintainers in tracking down suspected
  820. bugs in the C-Kermit program.  Use of this feature dramatically slows down the
  821. Kermit protocol.  Default name: @q(debug.log).
  822.  
  823. log packets@\This produces a record of all the packets that go in and out of
  824. the communication port.  This log is of use to Kermit maintainers who are
  825. tracking down protocol problems in either C-Kermit or any Kermit that
  826. C-Kermit is connected to.  Default name:  @q(packet.log).
  827.  
  828. log session@\This log will contain a copy of everything you see on your screen
  829. during the 'connect' command, except for local messages or interaction with
  830. local escape commands.  Default name:  @q(session.log).
  831.  
  832. log transactions@\The transaction log is a record of all the files that were
  833. sent or received while transaction logging was in effect.  It includes time
  834. stamps and statistics, filename transformations, and records of any
  835. errors that may have occurred.  The transaction log allows you to have
  836. long unattended file transfer sessions without fear of missing some
  837. vital screen message.  Default name:  @q(transact.log).
  838. @end(description)
  839. The 'close' command explicitly closes a log, e.g. 'close debug'.
  840.  
  841. @i<Note:>  Debug and Transaction logs are a compile-time option; C-Kermit may
  842. be compiled without these logs, in which case it will run faster, it will
  843. take up less space on the disk, and the commands relating to them will not
  844. be present.
  845.  
  846. @Heading(Local File Management Commands:)
  847.  
  848. Unix Kermit allows some degree of local file management from interactive
  849. command level:
  850. @begin(description,leftmargin +4,indent -4)
  851. directory [@i(fn)]@\
  852. Displays a listing of the names, modes, sizes, and dates of files
  853. matching @i(fn) (which defaults to `@q[*]').  Equivalent to `@q(ls -l)'.
  854.  
  855. cwd [directory-name]@\
  856. Changes Kermit's working directory to the one given, or to the
  857. default directory if the directory name is omitted.  This command affects only
  858. the Kermit process and any processes it may subsequently create.  You may also
  859. type "cd" instead of "cwd".
  860.  
  861. space@\
  862. Display information about disk space and/or quota in the current
  863. directory and device.
  864.  
  865. @q(! )[@i(command)]@\
  866. The command is executed by the Unix shell.  If no command is specified, then an
  867. interactive shell is started; exiting from the shell, e.g. by typing Control-D
  868. or 'exit', will return you to C-Kermit command level.  Use the `@q(!)' command
  869. to provide file management or other functions not explicitly provided by
  870. C-Kermit commands.  The `@q(!)' command has certain peculiarities:
  871. @begin(itemize,spread 0)    
  872. C-Kermit attempts to use your preferred, customary (login) shell.
  873.  
  874. At least one space must separate the '!' from the shell command.
  875.  
  876. A 'cd' (change directory) command executed in this manner will have no effect
  877. -- use the C-Kermit 'cwd' command instead. 
  878. @end(itemize)
  879. @end(description)
  880.  
  881. @heading(The 'set' and 'show' Commands:)
  882.  
  883. Since Kermit is designed to allow diverse systems to communicate, it is
  884. often necessary to issue special instructions to allow the program to adapt
  885. to peculiarities of the another system or the communication path.  These
  886. instructions are accomplished by the 'set' command.  The 'show' command may
  887. be used to display current settings.  Here is a brief synopsis of settings
  888. available in the current release of C-Kermit:
  889.  
  890. @begin(description,leftmargin +4,indent -4)
  891. block-check {1, 2, 3}@\ Determines the level of per-packet error detection.
  892. "1" is a single-@|character 6-bit checksum, folded to include the values of all
  893. bits from each character.  "2" is a 2-character, 12-bit checksum.  "3" is a
  894. 3-character, 16-bit cyclic redundancy check (CRC).  The higher the block check,
  895. the better the error detection and correction and the higher the resulting
  896. overhead.  Type 1 is most commonly used; it is supported by all Kermit
  897. implementations, and it has proven adequate in most circumstances.  Types 2 or
  898. 3 would be used to advantage when transferring 8-bit binary files over noisy
  899. lines.
  900.  
  901. delay @i(n)@\How many seconds to wait before sending the first packet after a
  902. 'send' command.  Used in remote mode to give you time to escape back to your
  903. local Kermit and issue a 'receive' command.  Normally 5 seconds.
  904.  
  905. duplex {full, half}@\For use during 'connect'.  Specifies which side is doing
  906. the echoing; 'full' means the other side, 'half' means C-Kermit must echo
  907. typein itself.
  908.  
  909. escape-character @i(cc)@\For use during 'connect' to get C-Kermit's attention.
  910. The escape character acts as a prefix to an 'escape command', for instance to
  911. close the connection and return to C-Kermit or Unix command level.
  912. The normal escape character is Control-Backslash (28).
  913. The escape character is also used in System III/V implementations
  914. to prefix interrupt commands during file transfers.
  915.  
  916. file {display, names, type, warning}@\
  917. Establish various file-related parameters:
  918. @begin(description,leftmargin +4,indent -4)
  919. display {on, off}@\Normally 'on'; when in local mode, display progress of file
  920. transfers on the screen (stdout), and listen to the keyboard (stdin)
  921. for interruptions.  If off (-q on command line) none of this is
  922. done, and the file transfer may proceed in the background oblivious
  923. to any other work concurrently done at the console terminal.
  924.  
  925. names {converted, literal}@\
  926. Normally converted, which means that outbound filenames have path
  927. specifications stripped, lowercase letters raised to upper,
  928. tildes and extra periods changed to X's, and an X inserted in
  929. front of any name that starts with period.  Incoming files have
  930. uppercase letters lowered.  Literal means that none of these
  931. conversions are done; therefore, any directory path appearing in a
  932. received file specification must exist and be write-accessible.
  933. When literal naming is being used, the sender should not use path
  934. names in the file specification unless the same path exists on the
  935. target system and is writable.
  936.  
  937. @begin<multiple>
  938. type {binary, text} [{7, 8}]@\The file type is normally text, which means that
  939. conversion is done between Unix newline characters and the
  940. carriage-@|return/@|linefeed sequences required by the canonical Kermit file
  941. transmission format, and in common use on non-@|Unix systems.  Binary means to
  942. transmit file contents without conversion.  Binary (`@q(-i)' in command line
  943. notation) is necessary for binary files, and desirable in all Unix-@|to-@|Unix
  944. transactions to cut down on overhead.
  945.  
  946. The optional trailing parameter tells the bytesize for file transfer.  It is
  947. 8 by default.  If you specify 7, the high order bit will be stripped from each
  948. byte of sent and received files.  This is useful for transferring text files
  949. that may have extraneous high order bits set in their disk representation (e.g.
  950. Wordstar or similar word processor files).
  951. @end<multiple>
  952.  
  953. warning {on, off}@\Normally off, which means that incoming files will silently
  954. overwrite existing files of the same name.  When on (`@q(-w)' on command line)
  955. Kermit will check if an arriving file would overwrite an existing file; if so,
  956. it will construct a new name for the arriving file, of the form @q(foo~)@i(n),
  957. where foo is the name they share and @i(n) is a "generation number"; if @i(foo)
  958. exists, then the new file will be called @q(foo~1).  If @q(foo) and @q(foo~1)
  959. exist, the new file will be @q(foo~2), and so on.  If the new name would be
  960. longer than the maximum length for a filename, then characters would be deleted
  961. from the end first, for instance, @q(thelongestname) on a system with a limit
  962. of 14 characters would become @q(thelongestn~1).
  963. @begin(quotation)
  964. @i(CAUTION:)  If Control-F or Control-B is used to cancel an incoming file,
  965. and a file of the same name previously existed, @i(and) the "file warning"
  966. feature is not enabled, then the previous copy of the file will disappear.
  967. @end(quotation)
  968. @end(description)
  969.  
  970. flow-control {none, xon/xoff}@\Normally xon/xoff for full duplex flow control.
  971. Should be set to 'none' if the other system cannot do xon/xoff flow control, or
  972. if you have issued a 'set handshake' command.  If set to xon/xoff, then
  973. handshake should be set to none.  This setting applies during both terminal
  974. connection and file transfer.  @i<Warning:> This command may have no effect
  975. on certain Unix systems, where Kermit puts the communication line into
  976. 'rawmode', and rawmode precludes flow control.
  977.  
  978. incomplete {discard, keep}@\Disposition for incompletely received files.
  979. If an incoming file is interrupted or an error occurs during transfer,
  980. the part that was received so far is normally discarded.  If you "set
  981. incomplete keep" then such file fragments will be kept.
  982.  
  983. handshake {xon, xoff, cr, lf, bell, esc, none}@\Normally none.  Otherwise,
  984. half-duplex communication line turnaround handshaking is done, which means Unix
  985. Kermit will not reply to a packet until it has received the indicated handshake
  986. character or has timed out waiting for it; the handshake setting applies only
  987. during file transfer.  If you set handshake to other than none, then flow
  988. should be set to none.
  989.  
  990. line [device-name]@\
  991. The device name for the communication line to be used for file transfer and
  992. terminal connection, e.g. @q(/dev/ttyi3).  If you specify a device name,
  993. Kermit will be in local mode, and you should remember to issue any other
  994. necessary 'set' commands, such as 'set speed'.  If you omit the device name,
  995. Kermit will revert to its default mode of operation.  If you specify
  996. @q(/dev/tty), Kermit will enter remote mode (useful when logged in through
  997. the "back port" of a system normally used as a local-mode workstation).  When
  998. Unix Kermit enters local mode, it attempts to synchronize with other programs
  999. (like uucp) that use external communication lines so as to prevent two
  1000. programs using the same line at once; before attempting to lock the specified
  1001. line, it will close and unlock any external line that was previously in use.
  1002. The method used for locking is the "uucp lock file", explained in more detail
  1003. later.
  1004.  
  1005. modem-dialer {direct, hayes, racalvadic, ventel, ...}@\The type of modem
  1006. @index<Autodialer>
  1007. dialer on the communication line.  "Direct" indicates either there is no
  1008. dialout modem, or that if the line requires carrier detection to open, then
  1009. 'set line' will hang waiting for an incoming call.  "Hayes", "Ventel", and the
  1010. others indicate that 'set line' (or the -l argument) will prepare for a
  1011. subsequent 'dial' command for the given dialer.  Support for new dialers is
  1012. added from time to time, so type 'set modem ?' for a list of those supported
  1013. in your copy of Kermit.  See the description of the 'dial' command.  @i<NOTE:>
  1014. the "set modem" command must be given @i<before> the "set line" command.
  1015.  
  1016. parity {even, odd, mark, space, none}@\Specify character parity for use in
  1017. packets and terminal connection, normally none.  If other than none, C-Kermit
  1018. will seek to use the 8th-bit prefixing mechanism for transferring 8-bit binary
  1019. data, which can be used successfully only if the other Kermit agrees; if not,
  1020. 8-bit binary data cannot be successfully transferred.
  1021.  
  1022. prompt [string]@\The given string will be substituted for "@q(C-Kermit)>" as
  1023. this program's prompt.  If the string is omitted, the prompt will revert to
  1024. "@q(C-Kermit>)".  If the string is enclosed in doublequotes, the quotes will
  1025. be stripped and any leading and trailing blanks will be retained.
  1026.  
  1027. send @i<parameter>@\
  1028. Establish parameters to use when sending packets.  These will be in effect
  1029. only for the initial packet sent, since the other Kermit may override these
  1030. parameters during the protocol parameter exchange (unless noted below).
  1031. @begin(description,leftmargin +4,indent -4)
  1032. end-of-packet @i(cc)@\Specifies the control character needed by the other
  1033. Kermit to recognize the end of a packet.  C-Kermit sends this character at the
  1034. end of each packet.  Normally 13 (carriage return), which most Kermit
  1035. implementations require.  Other Kermits require no terminator at all, still
  1036. others may require a different terminator, like linefeed (10).
  1037.  
  1038. packet-length @i(n)@\Specify the maximum packet length to send.  Normally 90.
  1039. Shorter packet lengths can be useful on noisy lines, or with systems or front
  1040. ends or networks that have small buffers.  The shorter the packet, the higher
  1041. the overhead, but the lower the chance of a packet being corrupted by noise,
  1042. and the less time to retransmit corrupted packets.  This command overrides
  1043. the value requested by the other Kermit during protocol initiation unless the
  1044. other Kermit requests a shorter length.
  1045.  
  1046. pad-character @i(cc)@\Designate a character to send before each packet.
  1047. Normally, none is sent.  Outbound padding is sometimes necessary for
  1048. communicating with slow half duplex systems that provide no other means of
  1049. line turnaround control.  It can also be used to send special characters
  1050. to communications equipment that needs to be put in "transparent" or
  1051. "no echo" mode, when this can be accomplished in by feeding it a certain
  1052. control character.
  1053.  
  1054. padding @i(n)@\How many pad characters to send, normally 0.
  1055.  
  1056. start-of-packet @i(cc)@\The normal Kermit packet prefix is Control-A (1); this
  1057. command changes the prefix C-Kermit puts on outbound packets.  The only
  1058. reasons this should ever be changed would be: Some piece of equipment somewhere
  1059. between the two Kermit programs will not pass through a Control-A; or, some
  1060. piece of of equipment similarly placed is echoing its input.  In the latter
  1061. case, the recipient of such an echo can change the packet prefix for outbound
  1062. packets to be different from that of arriving packets, so that the echoed
  1063. packets will be ignored.  The opposite Kermit must also be told to change the
  1064. prefix for its inbound packets.
  1065.  
  1066. timeout @i(n)@\Specifies the number of seconds you want the other Kermit
  1067. to wait for a packet before timing it out and requesting retransmission.
  1068. @end(description)
  1069.  
  1070. receive @i<parameter>@\
  1071. Establish parameters to request the other Kermit to use when sending packets.
  1072. @begin(description,leftmargin +4,indent -4)
  1073. end-of-packet @i(cc)@\Requests the other Kermit to terminate its packets with
  1074. the specified character.
  1075.  
  1076. packet-length @i(n)@\Specify the maximum packet length to that you want the
  1077. other Kermit to send, normally 90.  If you specify a length of 95 or greater,
  1078. then it will be used if the other Kermit supports, and agrees to use, the
  1079. Kermit protocol extension for long packets.  In this case, the maximum length
  1080. depends upon the systems involved, but there would normally be no reason for
  1081. packets to be more than about 1000 characters in length.  The 'show
  1082. parameters' command displays C-Kermit's current and maximum packet lengths.
  1083.  
  1084. pad-character @i(cc)@\C-Kermit normally does not need to have incoming packets
  1085. preceded with pad characters.  This command allows C-Kermit to request the
  1086. other Kermit to use @i(cc) as a pad character.  Default @i(cc) is NUL, ASCII 0.
  1087.  
  1088. padding @i(n)@\How many pad characters to ask for, normally 0.
  1089.  
  1090. start-of-packet @i(cc)@\Change the prefix C-Kermit looks for on inbound
  1091. packets to correspond with what the other Kermit is sending.
  1092.  
  1093. timeout @i(n)@\Normally, each Kermit partner sets its packet timeout interval
  1094. based on what the opposite Kermit requests.  This command allows you to
  1095. override the normal procedure and specify a timeout interval for Unix Kermit to
  1096. use when waiting for packets from the other Kermit.  If you specify 0, then no
  1097. timeouts will occur, and Unix Kermit will wait forever for expected packets to
  1098. arrive.
  1099. @end(description)
  1100.  
  1101. speed {0, 110, 150, 300, 600, 1200, 1800, 2400, 4800, 9600, 19200}@\The
  1102. transmission speed ("baud rate") for the external communication line.  This
  1103. command cannot be used to change the speed of your own console terminal.  Many
  1104. Unix systems are set up in such a way that you must give this command after a
  1105. 'set line' command before you can use the line.  'set baud' is a synomym for
  1106. 'set speed'.  Use 19200 with caution -- it may not work on all systems.
  1107.  
  1108. terminal@\Used for specifying terminal parameters.  Currently, 'bytesize' is
  1109. the only parameter provided, and it can be set to 7 or 8.  It's 7 by default.
  1110. @end(description)
  1111.  
  1112. @heading(The 'show' Command:)
  1113.  
  1114. Syntax: @q<show {parameters, versions}>
  1115.  
  1116. The "show" command with the default argument of "parameters" displays
  1117. the values of all the 'set' parameters described above.  If you type
  1118. "show versions", then C-Kermit will display the version numbers and
  1119. dates of all its internal modules.  You should use the "show versions"
  1120. command to ascertain the vintage of your Kermit program before reporting
  1121. problems to Kermit maintainers.
  1122.  
  1123. @heading(The 'statistics' Command:)
  1124.  
  1125. The statistics command displays information about the most recent Kermit
  1126. protocol transaction, including file and communication line i/o, timing
  1127. and efficiency, as well as what encoding options were in effect (such as
  1128. 8th-bit prefixing, repeat-@|count compression).
  1129.  
  1130. @heading(The 'take' and 'echo' Commands:)
  1131.  
  1132. Syntax: @q<take >@i<fn1>@*
  1133. @ @ @ @ @ @q<echo >@i<[text to be echoed]>
  1134.  
  1135. The 'take' command instructs C-Kermit to execute commands from the named
  1136. file.  The file may contain any interactive C-Kermit commands, including
  1137. 'take'; command files may be nested to any reasonable depth, but it may
  1138. not contain text to be sent to a remote system during the 'connect' command.
  1139. This means that a command file like this:
  1140. @begin(example)
  1141. set line /dev/tty17
  1142. set speed 9600
  1143. connect
  1144. login myuserid
  1145. mypassword
  1146. @i<etc>
  1147. @end(example)
  1148. will not send "login myserid" or any of the following text to the remote
  1149. system.  To carry on a canned dialog, use the 'script' command, described
  1150. later.
  1151.  
  1152. The '@q(%)' command is useful for including comments in take-command files.
  1153. It may only be used at the beginning of a line.
  1154.  
  1155. The 'echo' command may be used within command files to issue greetings,
  1156. announce progress, ring the terminal bell, etc.  The 'echo' command should not
  1157. be confused with the Unix 'echo' command, which can be used to show how meta
  1158. characters would be expanded.  The Kermit echo command simply displays its text
  1159. argument (almost) literally at the terminal; the argument may contain octal
  1160. escapes of the form @qq(\ooo), where @q(o) is an octal digit (0-7), and there
  1161. may be 1, 2, or 3 such digits, whose value specify an ASCII character, such as
  1162. @qq(\007) (or @qq(\07) or just @qq(\7)) for beep, @qq(\012) for newline, etc.
  1163. Of course, each backslash must be must be entered twice in order for it to be
  1164. passed along to the echo command by the Kermit command parser.
  1165.  
  1166. Take-command files are in exactly the same syntax as interactive commands.
  1167. Note that this implies that if you want to include special characters like
  1168. question mark or backslash that you would have to quote with backslash when
  1169. typing interactive commands, you must quote these characters the same way
  1170. in command files.  Long lines may be continued by ending them with a single
  1171. backslash.
  1172.  
  1173. Command files may be used in lieu of command macros, which have not been
  1174. implemented in this version of C-Kermit.  For instance, if you commonly
  1175. connect to a system called 'B' that is connected to ttyh7 at 4800 baud,
  1176. you could create a file called @q(b) containing the commands
  1177. @begin(example)
  1178. % C-Kermit command file to connect to System B thru /dev/ttyh7
  1179. set line /dev/ttyh7
  1180. set speed 4800
  1181. % Beep and give message
  1182. echo \\007Connecting to System B...
  1183. connect
  1184. @end(example)
  1185. and then simply type 'take b' (or 't b' since no other commands begin with
  1186. the letter 't') whenever you wish to connect to system B.  Note the
  1187. comment lines and the beep inserted into the 'echo' command.
  1188.  
  1189. @index<IBM>
  1190. For connecting to IBM mainframes, a number of 'set' commands are required;
  1191. these, too, can be conveniently collected into a 'take' file like this one:
  1192. @begin(example)
  1193. % Sample C-Kermit command file to set up current line
  1194. % for IBM mainframe communication
  1195. %
  1196. set parity mark
  1197. set handshake xon
  1198. set flow-control none
  1199. set duplex half
  1200. @end(example)
  1201.  
  1202. Note that no single command is available to wipe out all of these settings
  1203. and return C-Kermit to its default startup state; to do that, you can either
  1204. restart the program, or else make a command file that executes the necessary
  1205. 'set' commands:
  1206. @begin(example)
  1207. % Sample C-Kermit command file to restore normal settings
  1208. %
  1209. set parity none
  1210. set handshake none
  1211. set flow-control xon/xoff
  1212. set duplex full
  1213. @end(example)
  1214.  
  1215. An implicit 'take' command is executed upon your @q(.kermrc) file when C-Kermit
  1216. starts up, upon either interactive or command-line invocation.  The @q(.kermrc)
  1217. file should contain 'set' or other commands you want to be in effect at all
  1218. times.  For instance, you might want override the default action when incoming
  1219. files have the same names as existing files -- in that case, put the command
  1220. @example(set file warning on)
  1221. in your @q(.kermrc) file.  On some non-Unix systems that run C-Kermit, the
  1222. initialization file might have a different name, such as @q<kermit.ini>.
  1223.  
  1224. Errors encountered during execution of take files (such as failure to complete
  1225. dial or script operations) cause termination of the current take file, popping
  1226. to the level that invoked it (take file, interactive level, or the shell).
  1227. When kermit is executed in the background, errors during execution of a take
  1228. file are fatal.
  1229.  
  1230. Under Unix, you may also use the shell's redirection mechanism to cause
  1231. C-Kermit to execute commands from a file:
  1232. @example(kermit < cmdfile)
  1233. or you can even pipe commands in from another process:
  1234. @example(command | kermit)
  1235.  
  1236. @heading(The 'connect' Command:)
  1237.  
  1238. The 'connect' command ('c' is an acceptable non-unique abbreviation for
  1239. 'connect') links your terminal to another computer as if it were a local
  1240. terminal to that computer, through the device specified in the most recent 'set
  1241. line' command, or through the default device if your system is a PC or
  1242. workstation.  All characters you type at your keyboard are sent out the
  1243. communication line (and if you have 'set duplex half', also displayed on your
  1244. screen), and all characters arriving at the communication port are displayed on
  1245. the screen.  Current settings of speed, parity, duplex, and flow-@|control are
  1246. honored, and the data connection is 7 bits wide unless you have given the
  1247. command 'set terminal bytesize 8'.  If you have issued a 'log session' command,
  1248. everything you see on your screen will also be recorded to your session log.
  1249. This provides a way to "capture" files from remote systems that don't have
  1250. Kermit programs available.
  1251.  
  1252. To get back to your own system, you must type the escape character, which is
  1253. Control-@|Backslash (@q[^\]) unless you have changed it with the 'set escape'
  1254. command, followed by a single-@|character command, such as 'c' for "close
  1255. connection".  Single-@|character commands include:
  1256. @begin(description,leftmargin +8,indent -6,spread 0.4)
  1257. c@\Close the connection
  1258.  
  1259. b@\Send a BREAK signal
  1260.  
  1261. 0@\(zero) send a null
  1262.  
  1263. s@\Give a status report about the connection
  1264.  
  1265. h@\Hangup the phone
  1266.  
  1267. @q[^\]@\Send Control-Backslash itself (whatever you have defined the
  1268. escape character to be, typed twice in a row sends one copy of it).
  1269. @end(description)
  1270. Uppercase and control equivalents for (most of) these letters are also
  1271. accepted.  A space typed after the escape character is ignored.  Any other
  1272. character will produce a beep.
  1273.  
  1274. The connect command simply displays incoming characters on the screen.  It is
  1275. assumed any screen control sequences sent by the host will be handled by the
  1276. firmware or emulation software in your terminal or PC.  If special terminal
  1277. emulation is desired, then the 'connect' command can invoked from the Unix
  1278. command line (@q(-c) or @q(-n)), piped through a terminal emulation filter,
  1279. e.g.
  1280. @example(kermit -l /dev/acu -b 1200 -c | tek)
  1281.  
  1282. @heading(The 'hangup' command:)
  1283.  
  1284. The 'hangup' command attempts to hang up the modem on a local-mode dialout
  1285. connection.
  1286.  
  1287. @heading(The 'dial' command:)
  1288.  
  1289. Syntax: @q(dial )@i(telephone-number-string)
  1290.  
  1291. @index<Modem>@index<Dialout Modem>@index<Autodialer>
  1292. This command controls dialout modems; you should have already issued a "set
  1293. line" and "set speed" command to identify the terminal device, and a "set
  1294. modem" command to identify the type of modem to be used for dialing.  In the
  1295. "dial" command, you supply the phone number and the Kermit program feeds it to
  1296. the modem in the appropriate format and then interprets dialer return codes and
  1297. modem signals to inform you whether the call was completed.  The
  1298. telephone-@|number-@|string may contain imbedded modem-@|dialer commands, such
  1299. as comma for Hayes pause, or `@q(&)' for Ventel dialtone wait and `@q(%)' for
  1300. Ventel pause (consult your modem manual for details).
  1301.  
  1302. At the time of this writing, support is included for the following modems:
  1303. @begin(itemize,spread 0)
  1304. AT&T 7300 Internal Modem
  1305.  
  1306. Cermetek Info-Mate 212A
  1307.  
  1308. Concord Condor CDS 220
  1309.  
  1310. DEC DF03-AC
  1311.  
  1312. DEC DF100 Series
  1313.  
  1314. DEC DF200 Series
  1315.  
  1316. General DataComm 212A/ED
  1317.  
  1318. Hayes Smartmodem and compatibles
  1319.  
  1320. Penril
  1321.  
  1322. Racal Vadic
  1323.  
  1324. Rolm CBX
  1325.  
  1326. US Robotics 212A
  1327.  
  1328. Ventel
  1329. @end(itemize)
  1330. Support for new modems is added to the program from time to time; you
  1331. can check the current list by typing "@q<set modem ?>".
  1332.  
  1333. There are also two "generic" modem types -- "direct" (i.e. no modem at all,
  1334. so that no attempt is made to deal with modem signals), and "unknown" (which
  1335. tells C-Kermit to attempt to honor modem signals, but leaves the dialing
  1336. mechanism unspecified).
  1337.  
  1338. The device used for dialing out is the one selected in the most recent "set
  1339. line" command (or on a workstation, the default line if no "set line" command
  1340. was given).  The "dial" command calls attempts to lock the terminal device's
  1341. path (see the section on line locking below) and to establish a call on an
  1342. exclusive basis.  If it is desired to dial a call and then return to the shell
  1343. (such as to do kermit activities depending on standard in/out redirection), it
  1344. is necessary to place the dialed call under one device name (say,
  1345. "@q</dev/cua0>") and then escape to the shell @i<within Kermit> on a linked
  1346. device which is separate from the dialed line (say, "@q</dev/cul0>").  This is
  1347. the same technique used by uucp (to allow locks to be placed separately for
  1348. dialing and conversing).
  1349.  
  1350. Because modem dialers have strict requirements to override the carrier-@|detect
  1351. signal most Unix implementations expect, the sequence for dialing is more rigid
  1352. than most other C-Kermit procedures.
  1353.  
  1354. Example one:
  1355. @begin(example)
  1356. @ux<kermit -l /dev/cul0 -b 1200>
  1357. C-Kermit>@ux<set modem-dialer hayes>    @i(hint: abbreviate) set m h
  1358. C-Kermit>@ux<dial 9,5551212>
  1359. Connected!
  1360. C-Kermit>@ux<connect>            @i(hint: abbreviate) c
  1361. @i(logon, request remote server, etc.)
  1362. @ux<^\c>                @i(escape back)
  1363. C-Kermit> ...
  1364. C-Kermit>@ux<quit>            @i(hint: abbreviate) q
  1365. @end(example)
  1366. this disconnects modem, and unlocks line.
  1367.  
  1368. Example two:
  1369. @begin(example)
  1370. @u(kermit)
  1371. C-Kermit>@ux(set modem-dialer ventel)
  1372. C-Kermit>@ux(set line /dev/cul0)
  1373. C-Kermit>@ux(dial 9&5551212%)
  1374. Connected!
  1375. C-Kermit> ...
  1376. @end(example)
  1377. Example three:
  1378. @begin(example)
  1379. kermit
  1380. C-Kermit>@ux(take my-dial-procedure)
  1381. Connected!
  1382.  
  1383. @i(file my-dial-procedure):
  1384. set modem hayes
  1385. set line /dev/tty99
  1386. dial 5551212
  1387. connect
  1388. @end(example)
  1389. In general, C-Kermit requires that the modem provide the "carrier detect" (CD)
  1390. signal when a call is in progress, and remove that signal when the call
  1391. completes or the line drops.  If a modem switch setting is available to force
  1392. CD, it should normally not be in that setting.  C-Kermit also requires (on most
  1393. systems) that the modem track the computer's "data terminal ready" (DTR)
  1394. signal.  If a switch setting is available to simulate DTR asserted within the
  1395. modem, then it should normally not be in that setting.  Otherwise the modem
  1396. will be unable to hang up at the end of a call or when interrupts are received
  1397. by Kermit.
  1398.  
  1399. For Hayes 1200 @index<Hayes Modem> dialers, two important switch settings are
  1400. #1 and #6.  Switch #1 should be normally be UP so that the modem can act
  1401. according to your computer's DTR signal.  But if your computer, or particular
  1402. implementation of Kermit, cannot control DTR, then switch 1 should be DOWN.
  1403. Switch #6 should normally be UP so carrier-@|detect functions properly (but
  1404. put it DOWN if you have trouble with the UP position).  Switches #2 (English
  1405. versus digit result codes) and #4 (Hayes echoes modem commands) may be in
  1406. either position.  Hayes 2400 modems have equivalent "software" switches.
  1407.  
  1408. If you want to interrupt a dial command in progress (for instance, because
  1409. you just realize that you gave it the wrong number), type a Control-C to
  1410. get back to command level.
  1411.  
  1412. @heading(The 'script' Command:)
  1413.  
  1414. Syntax: @q(script )@i(expect send [expect send] . . .)
  1415.  
  1416. "expect" has the syntax: @i(expect[-send-expect[-send-expect[...]]])
  1417.  
  1418. The 'script' command carries on a "canned dialog" with a remote system, in
  1419. which data is sent according to the remote system's responses.  The typical use
  1420. is for logging in to a remote system automatically.
  1421.  
  1422. C-Kermit's script facility operates in a manner similar to that commonly
  1423. used by the Unix UUCP system's "@q(L.sys)" file entries.  A login script 
  1424. is a sequence of the form:
  1425. @example(@i<expect send [expect send] . . .>)
  1426. where @i(expect) is a prompt or message to be issued by the remote site, and
  1427. @i(send) is the string (names, numbers, etc) to return, and expects are
  1428. separated from sends by spaces.  The send may also be the keyword EOT, to send
  1429. Control-D, or BREAK, to send a break signal.  Letters in sends may be prefixed
  1430. by `@q[~]' to send special characters, including:
  1431. @begin(description,leftmargin +8,indent -4,spread 0)
  1432. @q(~b)@\backspace
  1433.  
  1434. @q(~s)@\space
  1435.  
  1436. @q(~q)@\`@q[?]'(trapped by Kermit's command interpreter)
  1437.  
  1438. @q(~n)@\linefeed
  1439.  
  1440. @q(~r)@\carriage return
  1441.  
  1442. @q(~t)@\tab
  1443.  
  1444. @q(~')@\single quote
  1445.  
  1446. @q(~~)@\tilde
  1447.  
  1448. @q(~")@\double quote
  1449.  
  1450. @q(~x)@\XON (Control-Q)
  1451.  
  1452. @q(~c)@\don't append a carriage return
  1453.  
  1454. @q(~)@i(o[o[o]])@ @ an octal character
  1455.  
  1456. @q(~d)@\delay approx 1/3 second during send
  1457.  
  1458. @q(~w)@i([d[d]])@ @ wait specified interval during expect, then time out
  1459. @end(description)
  1460. As with some UUCP systems, sent strings are followed by @q(~r) unless they have
  1461. a @q(~c).
  1462.  
  1463. Only the last 7 characters in each expect are matched.  A null @i(expect),
  1464. e.g. @q(~0) or two adjacent dashes, causes a short delay before proceeding
  1465. to the next send sequence.  A null expect always succeeds.
  1466.  
  1467. As with UUCP, if the expect string does not arrive, the script attempt
  1468. fails.  If you expect that a sequence might not arrive, as with UUCP, 
  1469. conditional sequences may be expressed in the form:
  1470. @example(@i<-send-expect[-send-expect[...]]>)
  1471. where dashed sequences are followed as long as previous expects fail.
  1472. Timeouts for expects can be specified using @q(~w); @q(~w) with no
  1473. arguments waits 15 seconds.
  1474.  
  1475. @i(Expect/send) transactions can be easily be debugged by logging
  1476. transactions.  This records all exchanges, both expected and actual.
  1477. The script execution will also be logged in the session log, if that is
  1478. activated.
  1479.  
  1480. Note that `@q[\]' characters in login scripts, as in any other C-Kermit
  1481. interactive commands, must be doubled up.  A line may be ended with a
  1482. single `@q[\]' for continuation.
  1483.  
  1484. Example one:
  1485.  
  1486. Using a modem, dial a UNIX host site.  Expect "login" (...gin), and if it
  1487. doesn't come, simply send a null string with a @q(~r).  (Some Unixes
  1488. require either an EOT or a BREAK instead of the null sequence, depending
  1489. on the particular site's "logger" program.)  After providing user id
  1490. and password, respond "x" to a question-mark prompt, expect the Bourne
  1491. shell "@q($)" prompt (and send return if it doesn't arrive).  Then cd to
  1492. directory kermit, and run the program called "wermit", entering the
  1493. interactive connect state after wermit is loaded.
  1494. @begin(example)
  1495. set modem ventel
  1496. set line /dev/tty77
  1497. set baud 1200
  1498. dial 9&5551212
  1499. script gin:--gin:--gin: smith ssword: mysecret ~q x $--$ \
  1500.  cd~skermit $ wermit
  1501. connect
  1502. @end(example)
  1503. Note that 'set line' is issued @i<after> 'set modem', but @i<before>
  1504. 'set baud' or other line-@|related parameters.
  1505.  
  1506. Example two:
  1507.  
  1508. @index(TELENET)
  1509. Using a modem, dial the Telenet network.  This network expects three returns
  1510. with slight delays between them.  These are sent following null expects.  The
  1511. single return is here sent as a null string, with a return appended by default.
  1512. Four returns are sent to be safe before looking for the prompt.  Then the
  1513. Telenet id and password are entered.  Then Telenet is instructed to connect to
  1514. a host site (c 12345).  The host has a data switch that asks "which system";
  1515. the script responds "myhost" (if the "which system" prompt doesn't appear, the
  1516. Telenet connect command is reissued).  The script waits for an @qq"@@" prompt
  1517. from the host, then sends the user ID ("joe") and password ("secret"), looks
  1518. for another @qq<@@> prompt, runs Kermit, and in response to the Kermit's prompt
  1519. (which ends in @qq[>]), gives the commands "set parity even" and "server".
  1520. Files are then exchanged.  The commands are in a take file; note the
  1521. continuation of the 'script' command onto several lines using the `@q[\]'
  1522. terminator.
  1523. @begin(example)
  1524. set modem hayes
  1525. set line /dev/acu
  1526. set speed 1200
  1527. set parity mark
  1528. dial 9,5551212
  1529. script ~0 ~0 ~0 ~0 ~0 ~0 ~0 ~0 @@--@@--@@ id~saa001122 = 002211 @@ \
  1530.     c~s12345 ystem-c~s12345-ystem myhost @@ joe~ssecret @@ kermit \
  1531.     > set~sparity~seven > server
  1532. send some.stuff
  1533. get some.otherstuff
  1534. bye
  1535. quit
  1536. @end(example)
  1537. Since these commands may be executed totally in the background, they
  1538. can also be scheduled.  A typical shell script, which might be scheduled
  1539. by cron, would be as follows (csh used for this example):
  1540.  
  1541. @begin(example)
  1542. #
  1543. #keep trying to dial and log onto remote host and exchange files
  1544. #wait 10 minutes before retrying if dial or script fail.
  1545. cd someplace
  1546. while ( 1 )
  1547.         kermit < /tonight.cmd >> nightly.log &
  1548.         if ( ! $status ) break
  1549.         sleep 600
  1550. end
  1551. @end(example)
  1552. File @q(tonight.cmd) might have two takes in it, for example, one to take
  1553. a file with the set modem, set line, set baud, dial, and script, and
  1554. a second take of a file with send/get commands for the remote server.
  1555. The last lines of @q(tonight.cmd) should be a bye and a quit.
  1556.  
  1557. @heading(The 'help' Command:)
  1558.  
  1559. @begin(example,leftmargin 0)
  1560. @r(Syntax:) help
  1561. @ @ @ @i(or): help @i(keyword)
  1562. @ @ @ @i(or): help {set, remote} @i(keyword)
  1563. @end(example)
  1564.  
  1565. Brief help messages or menus are always available at interactive command
  1566. level by typing a question mark at any point.  A slightly more verbose form
  1567. of help is available through the 'help' command.  The 'help' command with
  1568. no arguments prints a brief summary of how to enter commands and how to
  1569. get further help.  'help' may be followed by one of the top-level C-Kermit
  1570. command keywords, such as 'send', to request information about a command.
  1571. Commands such as 'set' and 'remote' have a further level of help.  Thus you
  1572. may type 'help', 'help set', or 'help set parity'; each will provide a
  1573. successively more detailed level of help.
  1574.  
  1575.  
  1576. @heading(The 'exit' and 'quit' Commands:)
  1577.  
  1578. These two commands are identical.  Both of them do the following:
  1579.  
  1580. @begin(itemize,spread 0)
  1581. Attempt to insure that the terminal is returned to normal.
  1582.  
  1583. Relinquish access to any communication line assigned via 'set line'.
  1584.  
  1585. Relinquish any uucp and multiuser locks on the communications line.
  1586.  
  1587. Hang up the modem, if the communications line supports data terminal ready.
  1588.  
  1589. Close any open logs or other files.
  1590. @end(itemize)
  1591. After exit from C-Kermit, your default directory will be the same as when
  1592. you started the program.  The 'exit' command is issued implicitly whenever
  1593. C-Kermit halts normally, e.g. after a command line invocation, or after certain
  1594. kinds of interruptions.
  1595.  
  1596. @section(UUCP Lock Files)
  1597.  
  1598. Unix has no standard way of obtaining exclusive access to an external
  1599. communication line.  When you issue the 'set line' command to Unix Kermit, Unix
  1600. would normally grant you access to the line even if some other process is
  1601. making use of it.  The method adopted by most Unix systems to handle this
  1602. situation is the "UUCP lock file".  UUCP, the Unix-@|to-@|Unix Copy program,
  1603. creates a file in its directory (usually @q(/usr/spool/uucp), on some systems
  1604. @q</etc/locks>) with a name like @q(LCK..)@i(name), where @i(name) is the
  1605. device name, for instance @q(tty07).
  1606.  
  1607. Unix Kermit uses UUCP lock files in order to avoid conflicts with UUCP,
  1608. tip, or other programs that follow this convention.  Whenever you attempt
  1609. to access an external line using the 'set line' command or `@q(-l)' on the
  1610. command line, Kermit looks
  1611. in the UUCP directory for a lock file corresponding to that device.  For
  1612. instance, if you 'set line /dev/ttyi6' then Kermit looks for the file
  1613. @example(/usr/spool/uucp/LCK..ttyi6)
  1614. If it finds this file, it gives you an error message and a directory
  1615. listing of the file so that you can see who is using it, e.g.
  1616. @begin(example)
  1617. -r--r--r--  1 fdc        4 May  7 13:02 /usr/spool/uucp/LCK..ttyi6
  1618. @end(example)
  1619. In this case, you would look up user fdc to find out how soon the line
  1620. will become free.
  1621.  
  1622. This convention requires that the uucp directory be publicly readable
  1623. and writable.  If it is not, the program will issue an appropriate warning
  1624. message, but will allow you to proceed at your own risk (and the risk of
  1625. anyone else who might also be using the same line).
  1626.  
  1627. If no lock file is found, Unix Kermit will attempt create one, thus preventing
  1628. anyone who subsequently tries to run Kermit, UUCP, tip, or similar programs on
  1629. the same line from gaining access until you release the line.  If Kermit could
  1630. not create the lock file (for instance because the uucp directory is
  1631. write-@|protected), then you will receive a warning message but will be allowed
  1632. to proceed at your -- and everyone else's -- risk.  When Kermit terminates
  1633. normally, your lock file is removed.
  1634.  
  1635. Even when the lock directory is writable and readable, the locking mechanism
  1636. depends upon all users using the same name for the same device.  If a device
  1637. has more than one path associated with it, then a lock can be circumvented by
  1638. using an alias.
  1639.  
  1640. When a lock-@|creating program abruptly terminates, e.g. because it crashes or
  1641. is killed via shell command, the lock file remains in the uucp directory,
  1642. spuriously indicating that the line is in use.  If the lock file is owned by
  1643. yourself, you may remove it.  Otherwise, you'll have to get the owner or the
  1644. system manager to remove it, or else wait for a system task to do so; uucp
  1645. supports a function (uuclean) which removes these files after a predetermined
  1646. age -- uucp sites tend to run this function periodically via crontab.
  1647.  
  1648. Locking is not needed, or used, if communications occur over the user's
  1649. login terminal line (normally @q[/dev/tty]).
  1650.  
  1651. It may be seen that line locking is fraught with peril.  It is included in Unix
  1652. Kermit only because other Unix communication programs rely on it.  While it
  1653. is naturally desirable to assure exclusive access to a line, it is also
  1654. undesirable to refuse access to a vacant line only because of a spurious lock
  1655. file, or because the uucp directory is not appropriately protected.
  1656.  
  1657. @section(C-Kermit under Berkeley or System III/V Unix:)
  1658.  
  1659. C-Kermit may be interrupted at command level or during file transfer by typing
  1660. Control-C.  The program will perform its normal exit function, restoring the
  1661. terminal and releasing any lock.  If a protocol transaction was in progress, an
  1662. error packet will be sent to the opposite Kermit so that it can terminate
  1663. cleanly.
  1664.  
  1665. C-Kermit may be invoked in the background ("@q(&)" on shell commmand line).
  1666. If a background process is "killed", the user will have to manually
  1667. remove any lock file and may need to restore the modem.  This is because 
  1668. the kill signal (@q<kill(@i[x],9)>) cannot be trapped by Kermit.
  1669.  
  1670. During execution of a system command ('directory', 'cwd', or `@q(!)'), C-Kermit
  1671. can often be returned to command level by typing a single Control-C.  (With
  1672. System III/V, the usual interrupt function (often the DEL key) is replaced by
  1673. Control-C.) 
  1674.  
  1675. Under Berkeley Unix only: C-Kermit may also be interrupted by @q(^Z) to put the
  1676. process in the background.
  1677.  
  1678. Control-C, Control-Z, and Control-@q(\) lose their normal functions during
  1679. terminal connection and also during file transfer when the controlling tty
  1680. line is being used for packet i/o.
  1681.  
  1682. If you are running C-Kermit in "quiet mode" in the foreground, then
  1683. interrupting the program with a console interrupt like Control-C will not
  1684. restore the terminal to normal conversational operation.  This is because
  1685. the system call to enable console interrupt traps will cause the program to
  1686. block if it's running in the background, and the primary reason for quiet
  1687. mode is to allow the program to run in the background without blocking, so
  1688. that you can do other work in the foreground.
  1689.  
  1690. If C-Kermit is run in the background ("&" on shell commmand line), then
  1691. the interrupt signal (Control-C) (and System III/V quit signal) are
  1692. ignored.  This prevents an interrupt signal intended for a foreground
  1693. job (say a compilation) from being trapped by a background Kermit session.
  1694.  
  1695. @section(C-Kermit on the DEC Pro-3xx with Pro/Venix Version 1)
  1696.  
  1697. The DEC Professional 300 series are PDP-11/23 based personal computers.  Venix
  1698. Version 1 is a Unix v7 derivative.  It should not be confused with Venix
  1699. Version 2, which is based on ATT System V; these comments apply to Venix
  1700. Version 1 only.  C-Kermit runs in local mode on the Pro-3@i(xx) when invoked
  1701. from the console; the default device is @q(/dev/com1.dout).  When connected to
  1702. a remote system (using C-Kermit's 'connect' command), Pro/Venix itself (not
  1703. Kermit) provides VT52 terminal emulation.  Terminal operation at high speeds
  1704. (like 9600 baud) requires xon/xoff flow control, which unfortunately interferes
  1705. with applications such as the EMACS that use Control-Q and Control-S as
  1706. commands.
  1707.  
  1708. When logging in to a Pro-3xx (or any workstation) through the "back port",
  1709. it may be necessary to give the command "set line /dev/tty" in order to get
  1710. C-Kermit to function correctly in remote mode (on a system in which it 
  1711. normally expects to be operating in local mode).
  1712.  
  1713. @section(C-Kermit under VAX/VMS)
  1714.  
  1715. C-Kermit can be built using VAX-11 C to run under VMS.  Most of the
  1716. descriptions in this manual hold true, but it should be noted that as of this
  1717. writing the VMS support is not thoroughly tested, and no explicit support
  1718. exists for the various types of VMS files and their attributes.
  1719.  
  1720. The C-Kermit init file for VMS is called @q<KERMIT.INI>.
  1721.  
  1722. @section(C-Kermit on the Macintosh and other Systems)
  1723.  
  1724. The "protocol kernel" of C-Kermit is also used by Columbia's Macintosh Kermit.
  1725. The user and system interface is entirely different, and is covered in a
  1726. separate document.
  1727.  
  1728. There is also a Kermit for the Commodore Amiga based on C-Kermit, as well
  1729. as versions for MS-DOS, Data General operating systems, etc.
  1730.  
  1731. @section(C-Kermit Restrictions and Known Bugs)
  1732.  
  1733. @begin(enumerate)
  1734. @ux(Editing characters):
  1735. The program's interactive command interrupt, delete, and kill characters are
  1736. Control-C, Delete (or Backspace), and Control-U, respectively.  There is
  1737. currently no way to change them to suit your taste or match those used by
  1738. your shell, in case those are different.
  1739.  
  1740. @ux(Flow control):
  1741. C-Kermit attempts to use XON/XOFF flow control during protocol operations,
  1742. but it also puts the communication line into "rawmode".  On many systems,
  1743. rawmode disables flow control, so even though you may have "set flow xon/xoff",
  1744. no flow control will be done.  This is highly system and Unix-version
  1745. dependent.
  1746.  
  1747. @ux(Modem controls):
  1748. If a connection is made over a communication line (rather than on the
  1749. controlling terminal line), and that line has modem controls, (e.g. data
  1750. terminal ready and carrier detection implementation), returning to the shell
  1751. level will disconnect the conversation.  In that case, one should use
  1752. interactive mode commands, and avoid use of piped shell-@|level operation
  1753. (also see 'set modem-dialer' and 'dial' commands.)
  1754.  
  1755. @ux(Login Scripts):  The present login scripts implementation follows
  1756. the Unix conventions of uucp's "@q(L.sys)" file, rather than the normal
  1757. Kermit "INPUT/@|OUTPUT" style.
  1758.  
  1759. @ux(Dial-out vs dial-in communications lines):
  1760. C-Kermit requires a dial-out or dedicated line for the "set line" or "-l"
  1761. options.  Most systems have some lines dedicated to dial-in, which they enable
  1762. "loggers" on, and some lines available for dial-out.  Recent releases of
  1763. Unix (ATT & Berkeley) have mechanisms for changing the directionality of a
  1764. line.
  1765.  
  1766. @begin(multiple)
  1767. @ux(Using C-Kermit on Local Area Networks):
  1768. C-Kermit can successfully operate at speeds up to 19200 baud over LANs,
  1769. provided the network buffers are big enough to accommodate Kermit packets.
  1770.  
  1771. When computers are connected to LANs through asynchronous terminal
  1772. interfaces, then the connection should be configured to do XON/XOFF flow
  1773. control between the network interface and the computer, rather than passing
  1774. these signals through transparently.  This can help prevent Kermit from
  1775. overrunning the LAN's buffers if they are small (or if the LAN is congested),
  1776. and will can also prevent the LAN from overrunning a slow Kermit's buffers.
  1777.  
  1778. If the network hardware cannot accept 100 characters at a time, and flow
  1779. control cannot be done between the network and the computer, then Kermit's
  1780. "set send/receive packet-length" command can be used to shorten the packets.
  1781. @end(multiple)
  1782.  
  1783. @ux(Resetting terminal after abnormal termination or kill): When C-Kermit
  1784. terminates abnormally (say, for example, by a kill
  1785. command issued by the operator) the user may need to reset the terminal state.
  1786. If commands do not seem to be accepted at the shell prompt, try
  1787. Control-J "stty sane" Control-J (use "reset" on Berkeley Unix).
  1788. That should take the terminal out of "raw mode" if it was stuck there.
  1789.  
  1790. @ux(Remote host commands may time-out on lengthy activity):
  1791. Using "remote host" to instruct the C-Kermit server to invoke Unix
  1792. functions (like "make") that might take a long time to produce output can cause
  1793. timeout conditions.
  1794.  
  1795. @ux(XOFF deadlocks):
  1796. When connecting back to C-Kermit after a transaction, or after finishing
  1797. the server, it may be necessary to type a Control-Q to clear up an XOFF
  1798. deadlock.  There's not much the program can do about this...
  1799. @end(enumerate)
  1800.  
  1801. @section(How to Build C-Kermit for a Unix System)
  1802.  
  1803. The C-Kermit files, as distributed from Columbia, all begin with the prefix
  1804. "ck".  You should make a directory for these files and then cd to it.  A
  1805. makefile is provided to build C-Kermit for various Unix systems (there are
  1806. separate makefiles for VMS and the Macintosh).  As distributed, the makefile
  1807. has the name "@q(ckuker.mak)".  You should rename it to "@q(makefile)" and then
  1808. type "make xxx", where xxx is the symbol for your system, for instance "make
  1809. bsd" to make C-Kermit for 4.x BSD Unix.  The result will be a program called
  1810. "wermit".  You should test this to make sure it works; if it does, then you can
  1811. rename it to "kermit" and install it for general use.  See the makefile for a
  1812. list of the systems supported and the corresponding "make" arguments.
  1813.  
  1814. @section(Adapting C-Kermit to Other Systems)
  1815.  
  1816. C-Kermit is designed for portability.  The level of portability is indicated
  1817. in parentheses after the module name: "C" means any system that has a C
  1818. compiler that conforms to the description in "The C Programming Language" by
  1819. Kernighan & Ritchie (Prentice-Hall, 1978).  "Cf" is like "C", but also
  1820. requires "standard" features like printf and fprintf, argument passing via
  1821. argv/argc, and so on, as described in Kernighan & Ritchie.  "Unix" means the
  1822. module should be useful under any Unix implementation; it requires features
  1823. such as fork() and pipes.  Anything else means that the module is particular
  1824. to the indicated system.  C-Kermit file names are of the form:
  1825.  
  1826. @q[ck<@i(system)><@i(what)>.<@i(type)>]
  1827.  
  1828. where the part before the dot is no more than 6 characters long, the part
  1829. after the dot no more than 3 characters long, and:
  1830.  
  1831. @q[<@i(type)>] is the file type:
  1832. @begin(description,leftmargin +8,indent -6,spread 0)
  1833. c:@\C language source
  1834.  
  1835. h:@\Header file for C language source
  1836.  
  1837. w:@\Wart preprocessor source, converted by Wart (or Lex) to a C program
  1838.  
  1839. nr:@\Nroff/Troff text formatter source
  1840.  
  1841. mss:@\Scribe text formatter source
  1842.  
  1843. doc:@\Documentation
  1844.  
  1845. ps:@\Documentation, Postscript format
  1846.  
  1847. hlp:@\Help text
  1848.  
  1849. bld:@\Instructions for building the program
  1850.  
  1851. bwr:@\A "beware" file - list of known bugs
  1852.  
  1853. upd:@\Program update log
  1854.  
  1855. mak:@\Makefile
  1856. @end(description)
  1857.  
  1858. @q[<@i(system)>] is a single character to tell what system the file applies to:
  1859. @begin(description,leftmargin +8,indent -6,spread 0)
  1860. 9:@\OS-9
  1861.  
  1862. a:@\Descriptive material, documentation
  1863.  
  1864. c:@\All systems with C compilers
  1865.  
  1866. d:@\Data General
  1867.  
  1868. h:@\Harris computers (reserved)
  1869.  
  1870. i:@\Commodore Amiga (Intuition)
  1871.  
  1872. m:@\Macintosh
  1873.  
  1874. o:@\OS/2
  1875.  
  1876. p:@\IBM PC, PC-DOS (reserved)
  1877.  
  1878. u:@\Unix and Unix-like systems
  1879.  
  1880. v:@\VAX/VMS
  1881.  
  1882. w:@\Wart
  1883. @end(description)
  1884.  
  1885. @q[<@i(what)>] is mnemonic (up to 3 characters) for what's in the file:
  1886. @begin(description,leftmargin +8,indent -6,spread 0)
  1887. aaa:@\A "read-me" file, like this one
  1888.  
  1889. cmd:@\Command parsing
  1890.  
  1891. con:@\Connect command
  1892.  
  1893. deb:@\Debug/Transaction Log formats, Typedefs
  1894.  
  1895. dia:@\Modem/Dialer control
  1896.  
  1897. fio:@\System-depdendent File I/O
  1898.  
  1899. fns:@\Protocol support functions
  1900.  
  1901. fn2:@\More protocol support functions
  1902.  
  1903. ker:@\General C-Kermit definitions, information, documentation
  1904.  
  1905. mai:@\Main program
  1906.  
  1907. pro:@\Protocol
  1908.  
  1909. scr:@\Script command
  1910.  
  1911. tio:@\System-dependent terminal i/o & control and interrupt handing
  1912.  
  1913. usr:@\User interface
  1914.  
  1915. us2:@\More user interface
  1916.  
  1917. us3:@\Still more user interface
  1918. @end(description)
  1919.  
  1920. Examples:
  1921.  
  1922. @begin(description,spread 0)
  1923. @q(ckufio.c)@\File i/o for Unix
  1924.  
  1925. @q(ckmtio.c)@\Terminal i/o for Macintosh
  1926.  
  1927. @q(ckuker.mss)@\Scribe source for for Kermit User Guide chapter
  1928.  
  1929. @q(ckuker.nr)@\Nroff source file for Unix C-Kermit man page
  1930. @end(description)
  1931.  
  1932. The following material discusses each of the C-Kermit modules briefly.
  1933. @begin(description,leftmargin +4, indent -4)
  1934. @q<ckcmai.c, ckcker.h, ckcdeb.h (Cf)>:@\This is the main program.  It contains
  1935. declarations for global variables and 
  1936. a small amount of code to initialize some variables and invoke the command
  1937. parser.  In its distributed form, it assumes that command line arguments are
  1938. passed to it via argc and argv.  Since this portion of code is only several
  1939. lines long, it should be easy to replace for systems that have different
  1940. styles of user interaction.  The header files define symbols and macros used
  1941. by the various modules of C-Kermit.  @q(ckcdeb.h) is the only header file
  1942. that is included by all the C-Kermit modules, so it contains not only the
  1943. debug format definitions, but also any compiler-@|dependent typedefs.
  1944.  
  1945. @q<ckwart.c (Cf), ckcpro.w (C)>:@\The ckcpro module embodies the Kermit
  1946. protocol state table and the code to accomplish state switching.  It is written
  1947. in "wart", a language which may be regarded as a subset of the Unix "lex"
  1948. lexical analyzer generator.  Wart implements enough of lex to allow the ckprot
  1949. module to function.  Lex itself was not used because it is proprietary.
  1950. The protocol module @q(ckcpro.w) is read by wart, and a
  1951. system-@|independent C program is produced.  The syntax of a Wart program is
  1952. illustrated by @q(ckcpro.w), and is described in @q(ckwart.doc).
  1953.  
  1954. @q<ckcfns.c (C)>:@\The module contains all the Kermit protocol support
  1955. functions -- packet formation, encoding, decoding, block check calculation,
  1956. filename and data conversion, protocol parameter negotiation, and high-@|level
  1957. interaction with the communication line and file system.  To accommodate small
  1958. systems, this module has been split into two -- @q(ckcfns.c) and @q(ckcfn2.c).
  1959.  
  1960. @q(ckutio.c):@\This module contains the system-@|dependent primitives for
  1961. communication line i/o, timers, and interrupts for the various versions of
  1962. Unix.  Certain important variables are defined in this module, which determine
  1963. whether C-Kermit is by default remote or local, what the default communication
  1964. device is, and so forth.  The tio module maintains its own private database of
  1965. file descriptors and modes for the console terminal and the file transfer
  1966. communication line so that other modules (like ckcfns or the terminal connect
  1967. module) need not be concerned with them.  The variations among Unix
  1968. implementations with respect to terminal control and timers are accommodated
  1969. via conditional compilation.
  1970.  
  1971. @q(ckufio.c):@\This module contains system-dependent primitives for file i/o,
  1972. wildcard (meta character) expansion, file existence and access checking, and
  1973. system command execution for the various versions of Unix.  It maintains an
  1974. internal database of i/o "channels" (file pointers in this case) for the files
  1975. C-Kermit cares about -- the input file (the file which is being sent), the
  1976. output file (the file being received), the various logs, the screen, and so
  1977. forth.  This module varies little among Unix implementations except for the
  1978. wildcard expansion code; the directory structure of 4.2bsd Unix is different
  1979. from that of other Unix systems.  Again, variation among Unix systems is
  1980. selected using conditional compilation.
  1981.  
  1982. @begin(multiple)
  1983. @q(ckuusr.h, ckuusr.c, ckuus2.c, ckuus3.c) (Unix):@\This is the "user
  1984. interface" for C-Kermit.  It includes the command parser,
  1985. the screen output functions, and console input functions.  The command
  1986. parser comes in two pieces -- the traditional Unix command line decoder
  1987. (which is quite small and compact), and the interactive keyword parser
  1988. (which is rather large).  This module is fully replacable; its interface to
  1989. the other modules is very simple, and is explained at the beginning of the
  1990. source file.  The ckuusr module also includes code to execute any commands
  1991. directly which don't require the Kermit protocol -- local file management,
  1992. etc.  The module is rated "Unix" because it makes occasional use of the
  1993. @q[system()] function.
  1994.  
  1995. Note that while @q(ckuusr) is logically one module, it has been split up into
  1996. three C source files, plus a header file for the symbols they share in common.
  1997. This is to accommodate small systems that cannot handle big modules.
  1998. @q(ckuusr.c) has the command line and top-@|level interactive command parser;
  1999. @q(ckuus2.c) has the help command and strings; @q(ckuus3) has the set
  2000. and remote commands along with the logging, screen, and "interrupt" functions.
  2001. @end(multiple)
  2002.  
  2003. @q(ckucmd.c, ckucmd.h) (Cf):@\This is an interactive command parsing package
  2004. developed for C-Kermit.  It is written portably enough to be usable on any
  2005. system that has a C compiler that supports functions like printf.  The file
  2006. name parsing functions depend upon primitives defined in the fio module; if
  2007. these primitives cannot be supplied for a certain system, then the filename
  2008. parsing functions can be deleted, and the package will still be useful for
  2009. parsing keywords, numbers, arbitrary text strings, and so forth.  The style of
  2010. interaction is the same as that found on the DECSYSTEM-20.
  2011.  
  2012. @q(ckucon.c) (Unix):@\This is the connect module.  As supplied, it should
  2013. operate in any Unix environment, or any C-based environment that provides the
  2014. fork() function.  The module requires access to global variables that specify
  2015. line speed, parity, duplex, flow control, etc, and invokes functions from the
  2016. tio module to accomplish the desired settings and input/output, and functions
  2017. from the fio module to perform session logging.  No terminal emulation is
  2018. performed, but since standard i/o is used for the console, this may be piped
  2019. through a terminal emulation filter.  The ckucon function may be entirely
  2020. replaced, so long as the global settings are honored by its replacement.  PC
  2021. implementations of C-Kermit may require the ck?con module to do screen control,
  2022. escape sequence interpretation, etc, and may also wish to write special code to
  2023. get the best possible performance.
  2024.  
  2025. @q(ckudia.c) (Unix):@\This is the dialer module.  As supplied, it handles
  2026. Hayes, Ventel, Penril, Racal-Vadic, and several other modems.
  2027.  
  2028. @q(ckuscr.c) (Unix):@\This is the login script module.  As supplied, it handles
  2029. uucp-@|style scripts. 
  2030. @end(description)
  2031.  
  2032. Moving C-Kermit to a new system entails:
  2033. @begin(enumerate)
  2034. Creating a new @q<ck?tio> module in C, assembler, or whatever language is
  2035. most appropriate for system programming on the new system.  If the system
  2036. is Unix-like, then support may be added within the @q<ckutio.c> module itself
  2037. using conditional compilation.
  2038.  
  2039. Creating a new @q<ck?fio> module, as above.
  2040.  
  2041. If the system is not Unix-like, then a new @q<ckuusr> module may be required,
  2042. as well as a different invocation of it from @q<ckcmai>.
  2043.  
  2044. If the distributed connect module doesn't work or performs poorly, then
  2045. it may be replaced.  For instance, interrupt-@|driven i/o may be required,
  2046. especially if the system doesn't have forks.
  2047. @end(enumerate)
  2048. Those who favor a different style of user/program interaction from that
  2049. provided in @q(ckuusr.c) may replace the entire module, for instance with one
  2050. that provides a mouse/@|window/@|icon environment, a menu/@|function-@|key
  2051. environment, etc.
  2052.  
  2053. A few guidelines should be followed to maintain portability:
  2054. @begin(itemize)
  2055. Keep variable and function names to 6 characters or less.  Don't use
  2056. identifiers that are distinguished from one another only by alphabetic
  2057. case.
  2058.  
  2059. Keep modules small.  For instance, on a PDP-11 it is necessary to keep
  2060. the code segment of each module below 8K in order to allow the segment
  2061. mapping to occur which is necessary to run programs larger than 64K on a
  2062. non-@|I-and-D-@|space machine.
  2063.  
  2064. Keep strings short; many compilers have restrictive maximum lengths; 128
  2065. is the smallest maximum string constant length we've encountered so far.
  2066.  
  2067. Keep (f,s)printf formats short.  If these exceed some compiler dependent
  2068. maximum (say, 128) memory will be overwritten and the program will probably
  2069. core dump.
  2070.  
  2071. Do not introduce system dependencies into @q(ckcpro.w) or @q(ckcfn*.c).
  2072.  
  2073. If a variable is a character, declare as CHAR, not int, to prevent the
  2074. various sign extension and byte swapping foulups that occur when characters
  2075. are placed in integer variables.
  2076.  
  2077. Remember that different systems may use different length words for different
  2078. things.  Don't assume an integer can be used as a pointer, etc.
  2079.  
  2080. Don't declare static functions; these can wreak havoc with systems that do
  2081. segment mapping.
  2082.  
  2083. In conditional compilations expressions, use @q(#ifdef) and @q(#ifndef) and
  2084. not @q(#if), which is not supported by some compilers.  Also, don't use any
  2085. operators in these expressions; many compilers will fail to understand
  2086. expressions like @w<@q(#ifdef FOO | BAR)>.  Also, don't put trailing tokens
  2087. on @q<#else>'s or @q<#endif>'s (use @q</*> comments @q<*/>).
  2088.  
  2089. Don't define multiline macros.
  2090. @End(Itemize)
  2091. In general, remember that this program will have to be compilable by old
  2092. compilers and runnable on small systems.
  2093.