home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / hp3000st / stkermitdoc.txt < prev    next >
Text File  |  2020-01-01  |  13KB  |  531 lines
  1. #-h-  kermit.doc                 363  ascii   06/11/84  13:54:13
  2. .so manhdr.doc.tools
  3. .hd KERMIT (1) 6/7/84
  4. reliable file transfer over terminal connection
  5. .sy
  6. kermit [ifd]
  7.  
  8. kermit r[ifd]
  9.  
  10. kermit s[ifd] [file [-as remote_name]]...
  11. .## future:
  12. .## kermit g[ifd] [file]...
  13. .##
  14. .## ON ANYTHING OTHER THAN THE 3000, DOCUMENT THE 'x' OPTION:
  15. .##   kermit [xfid]   etc
  16. .##
  17. .ds
  18. Kermit provides reliable file transfer between machines.
  19. It has been implemented on many different computers, 
  20. including many microprocessors (see below).
  21.  
  22. The files transferred may be arbitrary
  23. ASCII data (full 7-bit characters) and may be of any length.
  24. This kermit implementation is capable of transmitting binary data
  25. as well (8-bit bytes), even over a 7-bit communication link.
  26. (To use this, the other kermit program must also have this capability.)
  27. Files are sent in small (96 character) checksummed packets.
  28.  
  29. This version of kermit does not include terminal emulation.
  30. .## ifdef HP3000
  31. (In fact, good terminal emulation is not possible from the HP 3000.)
  32. .## enddef
  33. Therefore, this kermit assumes it is running on the remote computer 
  34. (ie. NOT the machine to which your terminal is attached).
  35. Standard input and output is used for all packet transmissions.
  36.  
  37. Kermit has three modes: Send, Receive and Server.
  38. Kermit invoked without arguments comes up in server mode:
  39. it is ready to receive or send files on command from another kermit,
  40. i.e., the kermit running on the user's local machine.
  41. The 'r' flag places kermit in Receive mode which is a subset
  42. of Server mode; it is included only for compatability with
  43. older versions.
  44. The 's' flag places kermit in Send mode:
  45. this flag must be followed by the names of the file(s) to be sent
  46. to the other kermit.
  47. Each filename in a Send command may be followed by an
  48. optional flag '-as' which must then be followed by
  49. the filename which will be sent with the file to the
  50. other kermit.
  51.  
  52. In Server or Receive modes, the 'f' flag suppresses conversion of
  53. incoming filenames as described below.
  54.  
  55. In all states,
  56. .## ifnotdef HP3000
  57. .## the 'x' flag specifies that THIS kermit is to wait for the XON
  58. .## character from the OTHER kermit before sending data out.
  59. .##
  60. .## enddef
  61. the 'i' flag ("image mode") specifies that all files 
  62. are to be treated as binary files.
  63. When receiving files with the 'i' flag turned on,
  64. new files are created as fixed record binary files.
  65. When sending binary files (or when the 'i' flag is on),
  66. only the file contents will be sent;
  67. no indication of end-of-record is sent.
  68. Thus, information will be lost if variable-record
  69. binary files are sent.
  70.  
  71. Adding 'd' flags (debug) makes kermit progressively more verbose.
  72. Up to three d's may be used.
  73. The states kermit goes through are printed along with other
  74. traces of it's operation.
  75. For debugging a remote kermit, this information may be
  76. saved in a file by redirecting the error output.
  77. For instance,
  78.  
  79. .ti +5
  80. kermit dd ?logfile
  81.  
  82. will save the diagnostic output in the file 'logfile'.
  83. To view such log files (which may contain control characters), 
  84. it is most informative to use show(1) or ed(1) with the 'l' command.
  85.  
  86. The file transfer protocol uses small (96 character) checksummed
  87. packets, with ACK/NACK responses and timeouts.
  88. This Kermit uses a ten second timeout and five retries.
  89.  
  90. When using kermit as a remote server,
  91. kermit may be exited by typing an interrupt
  92. .## ifdef HP3000
  93. (^Y on the HP 3000)
  94. .## enddef
  95. or an end-of-file
  96. .## ifdef HP3000
  97. (^D and return on the HP 3000).
  98. .## enddef
  99. The server 'finish' command (sent from the local kermit)
  100. has the same effect.
  101.  
  102. When receiving files, kermit deletes any files which are
  103. not complete (due to some error or interruption of the transfer).
  104. .sp
  105. .ti -7
  106. FILENAMES
  107. .br
  108. When receiving a file, kermit will first attempt to store the file with the
  109. same name that was used to send it.
  110. If that is not possible and the 'f' flag was
  111. .ul
  112. not
  113. given, Kermit makes whatever name translations are necessary to
  114. make this name legal.
  115. .## ifdef HP3000
  116. (The HP3000 kermit must compress names into 8 alphanumeric
  117. characters with no extension.)
  118. .## enddef
  119.  
  120. If a file by that name already exists, kermit simply overwrites it,
  121. and no error message is given.
  122. .## ifdef HP3000
  123. (Kermit on the HP 3000 may be run with "-environ noclobber" at the end of the
  124. command line to avoid this.
  125. In this case, appending ":clob" to the filename overrides this protection.)
  126. .## enddef
  127.  
  128. In Send mode, Kermit will change the name to the "normal form" for sending:
  129. directory specifications are stripped off, and a name of the form
  130. NAME.EXT is sent.
  131. The extension .EXT is optional, and both parts
  132. are contain only letters and digits and are capitalized.
  133. .## ifdef HP3000
  134. (The HP3000 kermit does not send an extension.)
  135. .## enddef
  136. The "-as name" construction may be used to send files
  137. with names that are different from the names on the originating
  138. system; 'name' is NOT changed to normal form.
  139. .## ifdef HP3000
  140.  
  141. When sending files to the HP3000 kermit, it is possible
  142. to use the full Software Tools filename syntax.
  143. A few useful examples:
  144.  
  145. .in +2
  146. .nf
  147. name:fix80      create an 80-char fixed record file
  148. .br
  149. name:dev=lp     print the file on the HP3000 lineprinter
  150. .br
  151. name:code=prog  create an HP3000 program file (binary)
  152. .br
  153. name:disc=8000  create a large file (8000 => ~10 Mbyes)
  154. .in -2
  155. .fi
  156. .## enddef
  157. .sp
  158. .ti -7
  159. EXAMPLE
  160. .br
  161. For this example we will assume that we are calling the HP 3000 
  162. from a Unix system,
  163. i.e., a Unix system is our local system.
  164. (In many cases, a PC may be the local system.)
  165. Assume we are
  166. logged onto "Local" (the local machine), and want to communicate
  167. with "Remote" (the HP 3000).
  168.  
  169. We first want to connect to "Remote".
  170. On "Local", we type:   
  171.  
  172.       % kermit xlb /dev/tty4 9600
  173.       [Local] C-Kermit> c
  174.  
  175. to set up the connection (using the Unix kermit's 'connect' mode
  176. for terminal emulation, and assuming that there is a 9600 baud
  177. connection on tty4 to the 3000).
  178. (Note that '%' is the Unix prompt, '[Local] C-Kermit' is the local Kermit's
  179. prompt.)
  180. "Local"s kermit answers:   
  181.  
  182. .nf
  183.       [Local] C-Kermit: connected...  type ^]c to return to Local
  184. .fi
  185.  
  186. and we are talking to "Remote".
  187. We hit RETURN, get a login prompt from "Remote" and login.
  188.  
  189.       :hello user.tools
  190.       (MPE login message...)
  191.  
  192. Now we start the kermit server on the remote machine:
  193. Remember that we are talking to "Remote" right now.  We type:   
  194.  
  195. .nf
  196.       :run kermit.pub.tools
  197.       [Remote] ST Kermit:  Software Tools Kermit (HP 3000)
  198.       [Remote] ST Kermit Server Mode
  199. .fi
  200.  
  201. and there is now a Server kermit on "Remote"
  202. We type "^]c"  to return to the Local Kermit
  203. and come back to the Local prompt.
  204. Kermit answers:   
  205.  
  206.       [Local] C-Kermit: returned.  Line is still open.
  207.  
  208. We are now ready to send and receive files.
  209. To get files from the other side, we may type:
  210.  
  211.       [Local] C-Kermit> g data.user.tools junk.pub.acct
  212.       [Local] C-Kermit: Saving DATA as data
  213.       [Local] C-Kermit: Saving JUNK as junk
  214.       [Local] C-Kermit: Done.
  215.  
  216. We may send files with the send command:
  217.  
  218.       [Local] C-Kermit> s data.dat file1 -as file.user
  219.       [Local] C-Kermit: Sending data.dat as DATA.DAT
  220.       [Local] C-Kermit: Sending file1 as FILE.USER
  221.       [Local] C-Kermit: Done.
  222.  
  223. After each command, Kermit will type either
  224. "Send complete", or "Send failed", depending on the success
  225. of the transfer.
  226.  
  227. After all the transfers were done, we should connect again,
  228. log off of Remote and leave the Local Kermit.
  229.  
  230. Details on other implementations and on the protocol is given
  231. in the 
  232. .ul
  233. Kermit Users Guide, 
  234. and the 
  235. .ul
  236. Kermit Protocol Manual.
  237. .sp
  238. .ti -7
  239. FLOW CONTROL
  240. .br
  241. The KERMIT Protocol uses only printing ASCII characters (decimal 32-126)
  242. and Ctrl-A.
  243. The communications channel between kermits
  244. .ul
  245. must not change or swallow any of these characters.
  246. CR is used as the default line-terminator character, though that may be
  247. renegotiated by the protocol.
  248. Ctrl-S/Ctrl-Q (XOFF/XON) flow control can be used
  249. "underneath" the Kermit protocol if the operating system supports it.
  250. .## ifdef HP3000
  251.  
  252. The HP3000 kermit makes use of XON/XOFF handshaking
  253. by sending Ctrl-S at the appropriate times (after sending out a packet).
  254. The 3000 tty driver sends the Ctrl-Q when it is ready for more data.
  255. This will work if the other machine's operating system recognizes XOFF/XON.
  256. (This is the case for TOPS-20 and Unix System III and V.)
  257.  
  258. If it does not, the local kermit should wait for the XON character
  259. before sending each packet.
  260. The Unix Kermit (the version distributed with the 3000 version)
  261. does this if the 'x' flag is given.
  262. Many micros' kermits recognize a 'SET IBM' or 'SET HANDSHAKE XON'
  263. command which accomplishes the same thing.
  264. The 3000 kermit should NOT be given the 'x' flag unless it
  265. is talking to another machine that sends out XONs,
  266. i.e., an IBM 370.
  267.  
  268. If it is not possible for the other kermit
  269. to do this, packets sent to the 3000 kermit
  270. may be missed if they are sent before the 3000 is ready (and isssues the
  271. prompt character XON).
  272. This may occur when the 3000 loading is high;
  273. it is characterized by multiple packet timeouts, and possibly,
  274. a "Send failed" message from the local kermit.
  275.  
  276. A partial solution is to have the 3000 kermit ask the local kermit
  277. to send 'padding' before sending a packet.
  278. This may be done by 
  279. using the '-pad N' flag, where N may be from 0 to 94.
  280.  
  281. If a packet is missed,
  282. a timeout occurs and the packet will be retransmitted,
  283. so file transfer should proceed, but if every packet needs
  284. to be transmitted more than once, file transfer will become exceedingly slow.
  285. Running the local kermit with debugging on will allow monitoring
  286. this situation.
  287. .## enddef
  288. .## ifdef HP3000
  289.  
  290. This kermit has timeouts, so the
  291. protocol is stable when communicating with "dumb" kermits
  292. (that don't have timeouts) as long as they can wait for XON.
  293. Even with non-XON kermits, it will usually be stable.
  294. .## enddef
  295. .sp
  296. .ti -7
  297. OTHER IMPLEMENTATIONS
  298. .br
  299. Kermits have been written for TOPS-20, TOPS-10, IBM VM/CMS,
  300. Unix, VAX/VMS, RT-11, MS-DOS, CP/M, and Apple DOS.
  301. More information is given on page 45 of the 
  302. .ul
  303. Kermit Users Guide.
  304.  
  305. The Software Tools kermit runs on the Univac 1100 and the HP 3000,
  306. and should be portable to nearly any other system that supports
  307. the Software Tools package.
  308. .sp
  309. .ti -7
  310. ENVIRONMENT VARIABLES
  311. .br
  312. The ST environment variable 'kermitheader' sets the prefix to kermit's
  313. message banner.
  314. It defaults to 'ST '.
  315. See env(3:HP3000) for more information on environment variables.
  316. .sp
  317. .ti -7
  318. SEE ALSO
  319. .br
  320. .ul
  321. Kermit Users Guide,
  322. Fifth Edition (2 March 1984), Frank da Cruz, 
  323. Columbia University Center for Computing Activities, New York, New York, 10027
  324. .br
  325. (usemandf.kermit.tools on the HP 3000)
  326.  
  327. .ul
  328. Kermit Protocol Manual, 
  329. Fifth Edition (30 March 1984), 
  330. Frank da Cruz,
  331. Columbia University Center for Computing Activities, New York, New York, 10027
  332. .br
  333. (promandf.kermit.tools on the HP 3000)
  334.  
  335. .au
  336. KERMIT kernel by Bill Catchings, Columbia University Center
  337. for Computing Activities
  338.  
  339. KERMIT-Unix adaptation by Chris Maio and Bob Cattani, Columbia
  340. University Computer Science Dept.
  341.  
  342. Translation from C into Software Tools Ratfor on the Univac 1100 by
  343. Kendall Tidwell and Allen Cole, University of Utah, Computer Center.
  344.  
  345. Fixes, enhancements and port to the HP 3000 by Ken Poulton.
  346. .di
  347. Cant open filename
  348. .in +5
  349. sent to the local kermit (as an error packet) when that condition
  350. occurs.
  351. .in -5
  352. .bu
  353. .## ifdef HP3000
  354. Use of terminal type 13 may (according to HP) crash a Series 33.
  355. If you have a Series 33, alter the TERMTYPE definition
  356. in kermitde.src to use terminal type 4
  357. and recompile it using maknew.scripts.
  358.  
  359. When receiving files of more than ~ 1 Mbyte, the sending kermit is likely
  360. to time out while the 3000 kermit extends the file.
  361. This may be gotten around by sending the file with
  362. a 'disc' specification appended to the name.
  363. For example, "file1:disc=8000" is good for ~10 Mbytes.
  364. .## enddef
  365. #-t-  kermit.doc                 363  ascii   06/11/84  13:54:13
  366. #-h-  manhdr.doc                  163  ascii   06/11/84  13:54:16
  367. .de ##     # comment
  368. .en
  369. .##
  370. .de HD
  371. .hd $1 $2 $3 $4 $5 $6 $7 $8 $9
  372. .en
  373. .de hd
  374. .bp 1
  375. .in
  376. .rm 
  377. .he '$1 $2'$3 $4 $5 $6 $7 $8'$1 $2'
  378. .fo ''-#-''
  379. .fi
  380. .in 7
  381. .ti -7
  382. NAME
  383. .br
  384. $1 -
  385. .en
  386. .##
  387. .de SY
  388. .sy
  389. .en
  390. .de sy
  391. .sp 1
  392. .ti -7
  393. SYNOPSIS
  394. .br
  395. .nf
  396. .en
  397. .##
  398. .de DE
  399. .ds
  400. .en
  401. .de ds
  402. .fi
  403. .sp
  404. .ti -7
  405. DESCRIPTION
  406. .br
  407. .en
  408. .##
  409. .de fu
  410. .fi
  411. .sp 1
  412. .ti -7
  413. FUNCTION
  414. .br
  415. .en
  416. .##
  417. .de DIagnostics
  418. .di
  419. .en
  420. .de di
  421. .fi
  422. .sp
  423. .ti -7
  424. DIAGNOSTICS
  425. .br
  426. .en
  427. .##
  428. .de REturns
  429. .re
  430. .en
  431. .de re
  432. .fi
  433. .sp
  434. .ti -7
  435. RETURNS
  436. .br
  437. .en
  438. .##
  439. .de FIles
  440. .fl
  441. .en
  442. .de fl
  443. .fi
  444. .sp
  445. .ti -7
  446. FILES
  447. .br
  448. .en
  449. .##
  450. .de ENvironment
  451. .fi
  452. .sp
  453. .ti -7
  454. ENVIRONMENT
  455. .br
  456. .en
  457. .##
  458. .de EXamples
  459. .ex
  460. .en
  461. .de ex
  462. .fi
  463. .sp
  464. .ti -7
  465. EXAMPLES
  466. .nf
  467. .br
  468. .en
  469. .de IMplementation
  470. .im
  471. .en
  472. .de im
  473. .fi
  474. .sp
  475. .ti -7
  476. IMPLEMENTATION
  477. .br
  478. .en
  479. .##
  480. .de SEe also
  481. .sa
  482. .en
  483. .de sa
  484. .fi
  485. .sp
  486. .ti -7
  487. SEE ALSO
  488. .br
  489. .en
  490. .##
  491. .de am
  492. .fi
  493. .sp
  494. .ti -7
  495. ARGUMENTS MODIFIED
  496. .br
  497. .en
  498. .##
  499. .de ca
  500. .fi
  501. .sp
  502. .ti -7
  503. CALLS
  504. .br
  505. .en
  506. .##
  507. .de BUgs
  508. .bu
  509. .en
  510. .de bu
  511. .fi
  512. .sp
  513. .ti -7
  514. BUGS/DEFICIENCIES
  515. .br
  516. .en
  517. .##
  518. .de AUTHORS
  519. .au
  520. .en
  521. .de au
  522. .fi
  523. .sp
  524. .ti -7
  525. AUTHORS
  526. .br
  527. .en
  528. .de comment
  529. .en
  530. #-t-  manhdr.doc                  163  ascii   06/11/84  13:54:16
  531.