home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / os9 / os9kerdoc.txt < prev    next >
Text File  |  2020-01-01  |  11KB  |  230 lines
  1.  
  2.  
  3.  
  4. Authors:    Bill Catchings, Bob Cattani, Chris Maio, Columbia University
  5.             Modified  from UNIX Kermit to Os9 Kermit By Glean Seaton and Robert
  6.             A. Larson
  7.             with fixes and contributions from many others.
  8. Documentation:
  9.             Walter Underwood, Ford Aerospace (Palo Alto, CA)
  10.             Changed for Os9 Kermit by Robert A. Larson
  11. Version:    1.5
  12. Date:       July 1985
  13.  
  14. A  sample,  working  implementation of the Kermit "kernel" was written in the C
  15. language, and widely distributed in the Kermit Protocol Manual.    This  kernel
  16. was  intended  merely  to  illustrate the protocol, and did not include a "user
  17. interface", nor some of the fancy features like server support, 8-bit  quoting,
  18. file  warning, timeouts, etc.  Several sites have added the necessary trappings
  19. to make this a production version of Kermit, usually under the  UNIX  operating
  20. system.  Limited server functions have also been added to the Os9 version.
  21.  
  22. The  keyword style of user/program interaction favored by Kermit (program types
  23. prompt, user types command followed by operands, program types another  prompt,
  24. etc)  is  contrary to the UNIX style, so UNIX implementations have a style more
  25. familiar to UNIX users.  The Os9 version has retained  this  style  of  command
  26. interface.    C  versions  of Kermit are running successfully on VAX and PDP-11
  27. UNIX systems, IBM 370-compatible mainframes  under  Amdahl  UTS,  and  the  SUN
  28. Microsystems MC68000-based and other workstations.
  29.  
  30. There  is  a  new version of Kermit written in C called C-Kermit.  (The current
  31. version as of July 1985 is 4c.)  It is recommended for  Unix  and  adapting  to
  32. other  operating  systems  if  memory  is  adiquate.    (It is being adapted to
  33. Os9/68000, but is probably to large for Os9/6809.)
  34.  
  35. Os9 filespecs are of the form 
  36.  
  37.     dir1/dir2/dir3/ ... /filename
  38.  
  39. where the tokens delimited by slashes form a path name, and are each limited to
  40. 29  characters  in  length.  The final token in a path is the actual file name.
  41. By convention, it is of the form name.type, but there is nothing special  about
  42. the dot separating name and type; to Os9 it's just another character, and there
  43. may be many dots in a filename.
  44.  
  45. In the tradition of UNIX, here's the Os9 KERMIT "man page".
  46.  
  47. NAME            kermit - file transfer, virtual terminal over tty link
  48.  
  49. SYNOPSIS        kermit cl[e] line [esc]
  50.  
  51.                 kermit r[ddifl] [line]
  52.  
  53.                 kermit s[ddifl] [line] file ...
  54.  
  55.                 kermit gl[ddif] line file ...
  56.                                        2
  57.  
  58.  
  59.                 kermit ql[ddif] line
  60.  
  61.                 kermit h[ddifl] [line]
  62.  
  63. DESCRIPTION     Kermit provides reliable file transfer  and  primitive  virtual
  64.                 terminal   communication   between   machines.    It  has  been
  65.                 implemented   on   many    different    computers,    including
  66.                 microprocessors  (see  below).    The  files transferred may be
  67.                 arbitrary ASCII data (7-bit  characters)  and  may  be  of  any
  68.                 length.    The file transfer protocol uses small (96 character)
  69.                 check summed packets, with  ACK/NACK  responses  and  timeouts.
  70.                 Os9 Kermit by defaults (changeable by compilation options) uses
  71.                 a fifteen "second" timeout and ten retries.
  72.  
  73.                 The arguments to kermit are a set of flags (no  spaces  between
  74.                 the flags), three optional args (which, if included, must be in
  75.                 the same order as the flags  which  indicate  their  presence),
  76.                 and,  if  this is a Send or Get operation a list of one or more
  77.                 files.
  78.  
  79.                 Kermit has six modes, Connect, Send, Receive,  Get,  Quit,  and
  80.                 Host.    Connect is for a virtual terminal connection, Send and
  81.                 Receive may be used to transfer files  in  a  non-server  mode,
  82.                 Send,  Get,  and Quit are used with a remote kermit server, and
  83.                 Host is used to make the Os9 system a  server  itself.    These
  84.                 modes are specified by the first flag, which should be c, s, r,
  85.                 g, q, or h respectively.  Exactly one mode must be specified.
  86.  
  87.                 The d flag (debug) makes kermit a bit more verbose.  The states
  88.                 kermit  goes through are printed along with other traces of its
  89.                 operation.  A second, third, and even fourth d flag will  cause
  90.                 kermit to give an even more detailed trace.
  91.  
  92.                 The i flag (image) allows slightly more efficient file transfer
  93.                 between Os9 machines.  Normally (on Kermits defined to  run  on
  94.                 Os9  systems)  return  is  mapped  to  CRLF on output, LF's are
  95.                 discarded on input, and bytes are masked to 7 bits.  If this is
  96.                 set,  no mapping is done on returns, and all eight bits of each
  97.                 byte are sent or received.
  98.  
  99.                 The l flag (line) specifies the tty line that kermit should use
  100.                 to  communicate with the other machine.  This is specified as a
  101.                 regular filename, like "/t2".  If no  l  option  is  specified,
  102.                 standard  input is used and kermit assumes it is running on the
  103.                 remote host (i.e.. NOT the machine to which  your  terminal  is
  104.                 attached).
  105.  
  106.                 The  e flag (escape) allows the user to set the first character
  107.                 of the two character escape sequence for Connect  mode.    When
  108.                 the escape character is typed, kermit will hold it and wait for
  109.                 the next character.  If the next character is c  or  C,  kermit
  110.                 will  close the connection with the remote host.  If the second
  111.                                        3
  112.  
  113.  
  114.                 character is the same  as  the  escape  character,  the  escape
  115.                 character  itself  is passed.  An exclamation mark ('!') as the
  116.                 second character will cause shell to be forked.  (Use your  EOF
  117.                 character to return to the kermit connect mode.)  Any character
  118.                 other than these two results in a bell being sent to the user's
  119.                 terminal  and  no  characters  passed  to the remote host.  All
  120.                 other typed characters  are  passed  through  unchanged.    The
  121.                 default  escape  character  is  tilde ('~').  (Control-3 on the
  122.                 standard Coco keyboard.)
  123.  
  124.                 The file arguments are only meaningful to a Send or Get kermit.
  125.                 The  Receiving  kermit  will attempt to store the file with the
  126.                 same name that was used to  send  it.    Os9  kermits  normally
  127.                 convert  outgoing  file names to uppercase and incoming ones to
  128.                 lower case (see the f flag).  If a filename  contains  a  slash
  129.                 (/) all outgoing kermits will strip off the leading part of the
  130.                 name through the last slash.  In  the  Get  command,  filenames
  131.                 will  be  sent  to the remote host as is and the filenames sent
  132.                 back will  be  converted  as  usual  for  a  receiving  kermit.
  133.                 (Wildcard characters may be expanded on the remote end.)
  134.  
  135.                 The  Quit  command  will  send a "Generic Finish" packet to the
  136.                 remote kermit server.
  137.  
  138.                 The Host command has not been fully implemented and  tested  as
  139.                 of this writing.
  140.  
  141. EXAMPLE         For  this  example  we  will  assume  two Os9 machines.  We are
  142.                 logged onto "Os9a" (the local machine), and want to communicate
  143.                 with "Os9b" (the remote machine).  There is a modem on "/t2".
  144.  
  145.                 We  want  to  connect  to "Os9b", then transfer "file1" to that
  146.                 machine.
  147.  
  148.                 We type:  
  149.  
  150.                     kermit cl /t2
  151.  
  152.                 Kermit answers:  
  153.  
  154.                     Kermit: connected...
  155.  
  156.                 Now we dial the remote machine and connect the modem.  Anything
  157.                 typed  on  the  terminal will be sent to the remote machine and
  158.                 any output from that machine will be displayed on our terminal.
  159.                 We hit RETURN, get a "login:" prompt and login.
  160.  
  161.                 Now  we need to start a kermit on the remote machine so that we
  162.                 can send the file over.  First we start up the remote, (in this
  163.                 case   receiving)   kermit,  then  the  local,  (sending)  one.
  164.                 Remember that we are talking to Os9b right now.
  165.                                        4
  166.  
  167.  
  168.                 We type:  
  169.  
  170.                     kermit r
  171.  
  172.                 (there is now a Receive kermit on Os9b)
  173.  
  174.                 We type ~ (the escape character) and then the letter c to  kill
  175.                 the local (Connecting) kermit:  ~c
  176.  
  177.                 Kermit answers:  
  178.  
  179.                     Kermit: disconnected.
  180.  
  181.                 We type:  
  182.  
  183.                     kermit sl /t2 file1
  184.  
  185.                 Kermit answers:  
  186.  
  187.                     Sending file1 as FILE1
  188.  
  189.                 When  the  transmission  is  finished,  kermit will type either
  190.                 "Send complete", or "Send failed.", depending on the success of
  191.                 the  transfer.    If we now wanted to transfer a file from os9b
  192.                 (remote) to os9a (local), we would use these commands:
  193.  
  194.                     kermit cl /t2
  195.                       (connected to Os9b)
  196.                     kermit s file9
  197.                       ~c (talking to Os9a again)
  198.                     kermit rl /t2
  199.  
  200.                 After all the transfers were done, we should connect again, log
  201.                 off of Os9b, kill the Connect kermit and hang up the phone.
  202.  
  203. FEATURES        Kermit can interact strangely with the tty driver.
  204.  
  205.                 The  KERMIT  Protocol  uses  only  printing  ASCII  characters,
  206.                 Ctrl-A, and CRLF.   Ctrl-S/Ctrl-Q  flow  control  can  be  used
  207.                 "underneath"   the   Kermit  protocol,  but  is  not  currently
  208.                 implemented in Os9 Kermit.
  209.  
  210.                 Since BREAK is not an ASCII character,  kermit  cannot  send  a
  211.                 BREAK  to the remote machine.  On some systems, a BREAK will be
  212.                 read as a NUL.
  213.  
  214.                 This kermit does have timeouts  when  run  under  Os9,  so  the
  215.                 protocol is stable when communicating with "dumb" kermits (that
  216.                 don't have timeouts).
  217.  
  218. DIAGNOSTICS     cannot open device
  219.                 The file named in the line argument did not exist  or  had  the
  220.                                        5
  221.  
  222.  
  223.                 wrong permissions.
  224.  
  225.                 Could not create file
  226.                 A Receive kermit could not create the file being sent to it.
  227.  
  228.                 nothing to connect to
  229.                 A Connect kermit was started without a line argument.
  230.