Multics Technical Bulletin                                MTB-676
Kermit Protocol

To:       Distribution

From:     Maureen Mallmes

Date:     14 September 1984

Subject:  Kermit File Transfer Protocol

1.  Abstract

     This MTB  describes the file transfer  protocol, Kermit, and
its implementation on the Multics system.

Comments on this MTB should be sent to the author -

     via Multics mail to:

        Mallmes.Multics on System M

     via posted mail to:

        Maureen Mallmes
        Advanced Computing Technology Center
        Foothills Professional Building
        Room #301, 1620 - 29th Street N.W.
        Calgary, Alberta T2N 4L7
        CANADA

     via telephone to:

        (403)-270-5400
        (403)-270-5411

     via forum on System-M to:

        >user_dir_dir>Multics>Mallmes>mtgs>Multics_pc_protocols
        (pc_protocols)

________________________________________

Multics project  internal documentation; not to  be reproduced or
distributed outside the Multics project.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

                        TABLE OF CONTENTS

Section    Page  Subject
=======    ====  =======

1             i  Abstract
2             1  Introduction
3             1  Goals
4             2  Kermit
4.1           3  . . Remote Versus Local Operation
5             4  Basic Kermit
5.1           4  . . File Transfer
5.1.1         4  . . . . Setting Up
5.1.2         4  . . . . Packet Exchange
5.1.3         5  . . . . Timeouts, NAKs, and Retries
5.1.4         6  . . . . Errors
5.1.5         6  . . . . Interpacket Data
5.1.6         7  . . . . Multiple File Transfer
5.1.7         7  . . . . Basic KERMIT Protocol State Table
5.2          10  . . Files
5.2.1        10  . . . . Text Files
5.2.2        10  . . . . Binary Files
5.2.3        10  . . . . Filenames
5.3          10  . . Character set
5.4          11  . . Conversion Functions
5.5          12  . . Packet Format
5.5.1        12  . . . . Control Fields
5.5.2        12  . . . . Data Field
5.5.3        12  . . . . Fields
5.5.4        14  . . . . Send_Init Packets
6            18  Optional Features
6.1          18  . . Optional Features on Multics
6.1.1        18  . . . . 8th-Bit   Prefixing  and   Repeat  Count
                 Prefixing
6.2          20  . . Other Optional Features
6.2.1        20  . . . . Alternate Block Check Types
6.2.2        22  . . . . Interrupting a File Transfer
6.2.3        22  . . . . Transmitting File Attributes
7            22  Kermit Server
7.1          23  . . Server Commands
7.2          26  . . The R Command
7.3          26  . . Exchanging Parameters Before Server Commands
7.4          27  . . Short and Long Replies
7.5          27  . . Additional Server Commands
7.6          30  . . Host Commands
8            31  Implementation on Multics
9            36  Documentation
10           40  Kermit Requests
10.1         40  . . The log Request
10.2         40  . . The quit Request


Multics Technical Bulletin                                MTB-676
Kermit Protocol

10.3         40  . . The quit_log Request
10.4         41  . . The receive Request
10.5         41  . . The send Request
10.6         42  . . The server Request
10.7         42  . . The set Request
10.8         43  . . The statistics Request
10.9         44  . . The show request
11           45  General Information Segments
11.1         45  . . kermit_modes.gi.info
11.2         46  . . kermit_server_commands.gi.info
12           47  APPENDIX A.  Advanced Kermit
12.1         47  . . Alternate Block Check Types
12.2         50  . . Interrupting a File Transfer
12.3         51  . . Transmitting File Attributes
13           59  APPENDIX  B.   Advanced  Kermit  Protocol  State
                 Table


Multics Technical Bulletin                                MTB-676
Kermit Protocol

2.  Introduction

     The  basic  Kermit  file  transfer  protocol  was originally
designed  at  Columbia  University  to allow  for  file transfers
between their DECSYSTEM-20, IBM 370-series mainframes and various
microcomputers.   As  its  popularity  increased,  more  advanced
implementations were developed to simplify the user interface and
provide  additional  functionality and  optional  features.  Such
implementations used basic  Kermit as a building block,  and as a
result, any basic Kermit can talk to any other Kermit.
     This paper  discusses the implementation of  a Kermit server
on Multics.  It  includes a description of the  basic Kermit file
transfer  protocol,  the basic  Kermit  server, and  the optional
features presently  available for each.  Most  of the information
was  obtained  directly  from  the  "Kermit  Protocol  Manual"(1)
distributed  by   Columbia  University,  except   where  specific
references to Multics are made.

3.  Goals

     It is important to note that  the intent of this document is
not  to design  a Kermit for  Multics, but  to implement Columbia
University's  design  of Kermit  on  Multics.  The  goals  are as
follows:

     1.  Implement a "remote" basic Kermit file transfer protocol
         on  Multics  that  will include  the  following advanced
         features:
             a.  8th-bit prefixing
             b.  repeat prefixing

     2.  Implement the "remote" basic Kermit server on Multics.

________________________________________

(1) Frank  da Cruz,  ed., Kermit Protocol  Manual, Fifth Edition.
    New York, Trustees of Columbia University, March 30, 1984.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

4.  Kermit

     The   Kermit   protocol   is   specifically   designed   for
character-oriented transmission over  serial communication lines.
All implementations of Kermit  transmit and receive characters in
ASCII.  Kermit  is most commonly  run with the user  sitting at a
microcomputer,  connected  through  a  communications  port  to a
remote timesharing system.  The protocol is carried out by Kermit
programs  on each  end of  the serial  connection sending packets
back and forth.   The sender sends file names,  file contents and
control  information;  the   receiver  positively  or  negatively
acknowledges each packet.

The Kermit protocol requires that:

   - The host can  send and receive characters using  7- or 8-bit
     ASCII  encoding  over  an  EIA  RS-232  physical connection,
     either hardwired or dialup.

   - All  printable ASCII  characters are acceptable  as input to
     the host and will not be transformed in any way.

   - A single ASCII control character can pass from one system to
     the  other without  transformation.  This  character is used
     for  packet  synchronization.   The  character  is  normally
     CTRL-A (SOH, ASCII 1), but can be redefined.

   - If  a host  requires a  line terminator  for terminal input,
     that  terminator must  be a single  ASCII control character,
     such as  CR or LF, distinct  from the packet synchronization
     character.

   - The mainframe can disable such  services as echoing (on full
     duplex systems), wrapping lines by inserting carriage return
     linefeed sequences at the terminal width, pausing at the end
     of  a  screen  or  page  full  of  text,  displaying  system
     messages,  alphabetic  case  conversion,  control  character
     intepretation,  and  so  forth.   These  services  should be
     disabled before packet communication begins, and restored to
     their  original  condition  at  the  end  of  a transaction.
     Disabling  these services  is usually known  as "putting the
     terminal in binary mode."

   - The  host's terminal  input processor  should be  capable of
     receiving a single  burst of 40 to 100  characters at normal
     transmission speeds.  This is the typical size of a packet.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

Kermit does not require:

   - That the connection run at any particular baud rate.

   - That the  system can do  XON/XOFF or any other  kind of flow
     control.  System-  or hardware-level flow  control can help,
     but it's not necessary.

   - That the  system is capable  of full duplex  operation.  Any
     mixture of half and full duplex systems is supported.

   - That the system can transmit or receive 8-bit bytes.  Kermit
     will  take  advantage of  8-bit  connections to  send binary
     files; if  an 8-bit connection is  not possible, then binary
     files may be sent using an optional prefix encoding.

     4.1.  Remote Versus Local Operation

     Kermit programs can be run in two ways, remote and/or local.
A remote Kermit  usually runs on a mainframe  and is connected to
through a PC  or other computer.  When Kermit  runs remotely, all
file transfer  is done over the  job's controlling terminal line.
i.e.   the  same  line  through which  the  connection  was made.
During file transfer  a remote Kermit is cut  off from the screen
and keyboard.
     For local  Kermits, file transfer  is done over  an external
device,  such  as  a  microcomputer's  communication  port  or an
assigned terminal line on a mainframe.  Unlike a remote Kermit, a
local Kermit  can control the  screen, the keyboard  and the port
separately;   thus,  it   can  update  the   screen  with  status
information, watch for interrupt signals and transfer packets all
at  the same  time.  Due to  these differences  some commands are
applicable to local Kermit's only, others to remote Kermit's, and
still others for both.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

5.  Basic Kermit

5.1.  File Transfer

     Basic  Kermit provides  sequential file  transfer only.  The
file  transfer  protocol  takes  place  over  a  transaction.   A
transaction is an exchange of  packets beginning with a Send-Init
(S) packet, and ending with a Break Transmission (B) or Error (E)
packet , and  may include the transfer of one  or more files, all
in the same direction.

5.1.1.  Setting Up

     Connections between systems are  established by the ordinary
user.    In  a   typical  case,  the   user  runs   Kermit  on  a
microcomputer,  enters terminal  emulation, connects  to a remote
host computer , logs in, runs Kermit on the remote host, and then
issues  commands  to  that  Kermit  to  start  a  file  transfer,
"escapes" back to  the micro, and issues commands  to that Kermit
to start its side of the file transfer.

5.1.2.  Packet Exchange

     The following sequence characterizes basic Kermit operation;
the sender is the machine that  is sending files; the receiver is
the machine receiving the files.

   1. The sender transmits a  Send-Initiate (S) packet to specify
      its  parameters.  (packet  length, timeout,  etc; these are
      explained below).

   2. The  receiver  sends  an  ACK  (Y)  packet,  with  its  own
      parameters in the data field.

   3. The  sender  transmits  a  File-Header  (F)  packet,  which
      contains the  file's name in the  data field.  The receiver
      ACKs the  F packet, with no  data in the data  field of the
      ACK.

   4. The  sender sends  the contents  of the  file, in  Data (D)
      packets.  Any  data not in the  printable range is prefixed
      and replaced  by a printable equivalent.   Each D packet is
      acknowledged before the next one is sent.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

   5. When all the  file data has been sent,  the sender sends an
      End-Of- File (Z) packet.  The receiver ACKs it.

   6. If there is  another file to send, the  process is repeated
      beginning at step 3.

   7. When no more files remain  to be sent, the sender transmits
      an End- Of-Transmission (B)  packet.  The receiver ACKs it.
      This   ends  the   transaction,  and   closes  the  logical
      connection (the physical connection remains open).

     Each packet has  a sequence number, starting with  0 for the
Send Init.  The acknowledgment (ACK or  NAK) for a packet has the
same  packet number  as the  packet being  acknowledged.  Once an
acknowledgment  is  successfully  received the  packet  number is
increased by one, modulo 64.
     If the  sender is remote,  it waits for a  certain amount of
time (somewhere in the 5-30 second range) before transmitting the
Send-Init,  to give  the user  time to  escape back  to the local
Kermit and tell it to receive files.

5.1.3.  Timeouts, NAKs, and Retries

     A Kermit program should set a time limit whenever attempting
to read a packet from  the communication line, whether sending or
receiving files.   Having read a  packet, it should  turn off the
timer.

     If the  sender times out waiting  for an acknowledgement, it
should  send  the  same  packet again,  repeating  the  process a
certain  number  of  times  up  to a  retry  limit,  or  until an
acknowledgement is  received.  If the receiver  times out waiting
for a  packet, it can send  either a NAK packet  for the expected
packet or another ACK for the last packet it got.

     If  a  packet  from  the   sender  is  garbled  or  lost  in
transmission  (the latter  is detected  when the  sequence number
increases  by  more  than  1,  modulo 64,  the  former  by  a bad
checksum), the  receiver sends a  NAK for the  garbled or missing
packet.  If an ACK or a NAK from the receiver is garbled or lost,
the sender ignores  it; in that case, one side  or the other will
time out and retransmit.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

     A retry count is maintained, and there is a retry threshold,
normally set around 5.  Whenever a packet is resent, because of a
timeout  or  because it  was NAK'd,  the counter  is incremented.
When it reaches the threshold,  the transaction is terminated and
the counter reset.

5.1.4.  Errors

     During file transfer, the sender  may encounter an i/o error
on the  disk, or the receiver  may attempt to write  to a full or
write-protected   device.   Any   condition  that   will  prevent
successful transmission  of the file  is called a  "fatal error".
Fatal  errors  should be  detected,  and the  transfer  shut down
gracefully, with the pertinent  information provided to the user.
Error packets provide a mechanism to do this.
    If  a  fatal  error  takes place  on  either  the  sending or
receiving side, the side which  encountered the error should send
an Error (E) packet.  The E packet contains a brief textual error
message in the  data field.  Both the sender  and receiver should
be  prepared to  receive an Error  packet at any  time during the
transaction.  Both  the sender and  receiver of the  Error packet
should  halt, or  go back into  into user command  mode (a server
should return  to server command  wait).  The side  that is local
should print the error message on the screen.

5.1.5.  Interpacket Data

     Any line  terminator that is  required by the  system may be
appended  to the  packet; this is  carriage return  (ASCII 15) by
default.  Line terminators are not considered part of the packet,
and are not  included for in the count  or checksum.  Terminators
are not  necessary to the  protocol, and are invisible  to it, as
are any  characters that may  appear between packets.   If a host
cannot  do  single  character  input  from  a  TTY  line,  then a
terminator  will  be required  when  sending to  that  host.  The
terminator can be specified in the initial connection exchange.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

5.1.6.  Multiple File Transfer

     A  major feature  of the Kermit  protocol is  the ability to
transfer multiple files.  Whether a particular Kermit program can
actually send  multiple files depends on  the capabilities of the
program  and the  host operating  system (any  Kermit program can
receive multiple files).
     If a Kermit program can  send multiple files, it should make
every attempt to send the entire group specified.  If it fails to
send a particular file, it should not terminate the entire batch,
but should go  on the the next one, and  proceed until an attempt
has been made to send each file in the group.
     Operating in  this robust manner,  however, gives rise  to a
problem:   the user  must be  notified of  a failure  to send any
particular file.  Unfortunately, it is  not sufficient to print a
message  to  the  screen since  the  user may  not  be physically
present.   A  better  solution  would   be  to  have  the  sender
optionally keep a log of the transaction, giving the name of each
file  for  which an  attempt  was made,  and stating  whether the
attempt was successful, and if not, the reason.

5.1.7.  Basic KERMIT Protocol State Table

     The KERMIT protocol can be described  as a set of states and
transitions,  and rules  for what  to do  when changing  from one
state  to  another.  State  changes  occur based  on the  type of
packets  that are  sent or  received, or  errors that  may occur.
Packets  always go  back and forth;  the sender of  a file always
sends  data packets  of some  kind (init,  header, data)  and the
receiver always returns ACK or NAK packets.
     Upon  entering a  given state, a  certain kind  of packet is
either being  sent or is expected  to arrive -- this  is shown on
top of the description of that state.  As a result of the action,
various responses may occur; these are shown in the EVENT column.
For each event, an appropriate  ACTION is taken, and the protocol
enters a NEW STATE.
     The  following  table   specifies  basic  KERMIT  operation.
Timeouts  and  error  conditions   have  been  omitted  from  the
following table  for simplicity, but  the action is  as described
above.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

  STATE   EVENT           ACTION                      NEW STATE

       -- SEND STATES --

  Send Send-Init Packet
  S       Get NAK,bad ACK (None)                          S
          Get good ACK    Set remote's params, open file  SF
          (Other)         (None)                          A

  Send File-Header Packet
  SF      Get NAK,bad ACK (None)                          SF
          Get good ACK    Get bufferful of file data      SD
          (Other)         (None)                          A

  Send File-Data Packet
  SD      Get NAK,bad ACK (None)                          SD
          Get good ACK    Get bufferful of file data      SD
          (End of file)   (None)                          SZ
          (Other)         (None)                          A

  Send EOF Packet
  SZ      Get NAK,bad ACK (None)                          SZ
          Get good ACK    Get next file to send           SF
          (No more files) (None)                          SB
          (Other)         (None)                          A

  Send Break (EOT) Packet
  SB      Get NAK,bad ACK (None)                          SB
          Get good ACK    (None)                          C
          (Other)         (None)                          A


Multics Technical Bulletin                                MTB-676
Kermit Protocol

  STATE   EVENT           ACTION                      NEW STATE

       -- RECEIVE STATES --

  Wait for Send-Init Packet
  R       Get Send-Init   ACK w/local params              RF
          (Other)         (None)                          A

  Wait for File-Header Packet
  RF      Get Send-Init   ACK w/local params
                           (previous ACK was lost)        RF
          Get Send-EOF    ACK (prev ACK lost)             RF
          Get Break       ACK                             C
          Get File-Header Open file, ACK                  RD
          (Other)         (None)                          A

  Wait for File-Data Packet
  RD      Get previous
           packet(D,F)    ACK it again                    RD
          Get EOF         ACK it, close the file          RF
          Get good data   Write to file, ACK              RD
          (Other)         (None)                          A

       -- STATES COMMON TO SENDING AND RECEIVING --

  C       (Send Complete)                                 start
  A       ("Abort")                                       start


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

5.2.  Files

     The Kermit protocol is  capable of transmitting or receiving
multiple files.  There are no  restrictions on the type of files,
they may be binary or text.

5.2.1.  Text Files

     Printable files  are transmitted as  7-bit ASCII characters,
with lines delimited by CRLF's.

5.2.2.  Binary Files

     Binary files are transmitted as  though they were a sequence
of characters.  For binary files, 8-bit character transmission is
permissible  as  long as  the  two Kermit  programs  involved can
control the value of the parity bit.  In that case the 8th bit of
a  transmitted  character will  match that  of the  original data
byte, after any control-prefixing has  been done.  If one or both
sides cannot  control the parity bit,  a special prefix character
may  be inserted  to allow  for transfer  of binary  files.  Such
prefixing is outside the definition of the basic Kermit protocol.
See Section 6.2, "Other Optional Features".

5.2.3.  Filenames

     The  syntax  for filenames  can vary  widely from  system to
system.    To  avoid   problems  relating   to  various  systems'
filenaming conventions, only filenames will be represented in the
file header (F) packet.

5.3.  Character set

     All   implementations   of  Kermit   transmit   and  receive
characters in  ASCII only.  A control  character is considered to
be any byte whose low order 7 bits are in the range 0 through 31,
or equal to 127.  A printable ASCII character is any character in
the range 32 (SP) through 126 (TILDE).


Multics Technical Bulletin                                MTB-676
Kermit Protocol

5.4.  Conversion Functions

The  machine that  Kermit runs  on need  operate only  on integer
data.  The following are functions  that operate upon the numeric
value of single ASCII characters.

     char(x) = x+32
          Transforms the  integer x, which  is assumed to  lie in
          the range 0 to 94,  into a printable ASCII character; 0
          becomes SP, 1 becomes "!", 3 becomes "#", etc.

     unchar(x) = x-32
          Transforms the  character x, which is  assumed to be in
          the printable range (SP through tilde), into an integer
          in the range 0 to 94.

     ctl(x) = x XOR 64
          Maps  between  control characters  and  their printable
          representations, preserving  the high-order bit.   If x
          is a control character, then x = ctl(ctl(x)).  That is,
          the   same   function  is   used  to   controllify  and
          uncontrollify.   The argument  is assumed to  be a true
          control character (0  to 31, or 127), or  the result of
          applying CTL  to a true control  character (i.e.  63 to
          95).   The  transformation is  a mnemonic  one:  CTRL-A
          becomes A and vice versa.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

5.5.  Packet Format

     A packet is the unit of transmission in the Kermit protocol.
It  is  a clearly  delimited string  of characters,  comprised of
"control fields"  nested around data; the  control fields allow a
Kermit program to determine whether the data has been transmitted
correctly  and  completely.  Kermit  packets  do not  contain any
control  characters except  one specially designated  to mark the
beginning  of  a  packet.   Except for  the  packet  marker, only
printable characters are transmitted.

5.5.1.  Control Fields

     MARK, LEN, SEQ, TYPE, and CHECK are control fields.  Control
fields  are always  literal single-character  fields, except that
the CHECK  field may be  extended by one or  two additional check
characters.   Each control  field is  encoded by  char() or taken
literally, but never prefixed.   The control fields never contain
8-bit data.

5.5.2.  Data Field

      The  DATA  field contains  a string  of data  characters in
which any  control characters are encoded  printably and preceded
with the control  prefix.  The decision to prefix  a character in
this way  depends upon whether  its low order  7 bits are  in the
ASCII control  range, i.e.  0-31 or  127.  Prefix characters that
appear  in the  data must themselves  be prefixed  by the control
prefix, but unlike control characters, these retain their literal
value in the packet.

5.5.3.  Fields

The Kermit  protocol is built  around exchange of  packets of the
following format:

  +------+-----------+-----------+------+------------+-------+
  | MARK | char(LEN) | char(SEQ) | TYPE |    DATA    | CHECK |
  +------+-----------+-----------+------+------------+-------+

where all fields consist of ASCII characters.  The fields are:


Multics Technical Bulletin                                MTB-676
Kermit Protocol

MARK    The synchronization character that marks the beginning of
        the packet.   This should normally be  CTRL-A, but may be
        redefined.

LEN     The  number of  ASCII characters  within the  packet that
        follow this field, in other words the packet length minus
        two.   Since  this  number  is  transformed  to  a single
        character  via  the  char()  function,  packet  character
        counts  of  0  to  94  (decimal)  are  permitted,  and 96
        (decimal) is the maximum total packet length.  The length
        does  not  include  end- of-line  or  padding characters,
        which  are outside  the packet  and are  strictly for the
        benefit  of   the  operating  system   or  communications
        equipment,   but   it  does   include  the   block  check
        characters.

SEQ     The packet sequence number, modulo  64, ranging from 0 to
        63.  Sequence numbers "wrap around" to 0 after each group
        of 64 packets.

TYPE    The packet type, a single ASCII character.  The following
        packet types are required:

                D   Data packet
                Y   Acknowledge (ACK)
                N   Negative acknowledge (NAK)
                S   Send initiate (exchange parameters)
                B   Break transmission (EOT)
                F   File header
                Z   End of file (EOF)
                E   Error
                T   Reserved for internal use

DATA    The  "contents"  of  the  packet,  if  any  contents  are
        required  in  the  given   type  of  packet,  interpreted
        according  to  the packet  type.  Control  characters are
        preceded  by  a  special  prefix  character  as specified
        above.   A  prefixed sequence  may  not be  broken across
        packets.    Logical  records   in  printable   files  are
        delimited with  CRLFs, suitably prefixed  (e.g.  "#M#J").
        Logical  records  need  not correspond  to  packets.  Any
        prefix characters are included in the count.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

CHECK   A block  check on the  characters in the  packet between,
        but not  including, the mark and  the block check itself.
        The check for each packet  is computed by both hosts, and
        must   agree  if   a  packet   is  to   be  accepted.   A
        single-character  arithmetic checksum  is the  normal and
        required  block check.   Only six bits  of the arithmetic
        sum  are included.   In order that  all the  bits of each
        data character contribute to this  quantity, bits 6 and 7
        of the  final value are  added to the  quantity formed by
        bits 0-5.  Thus  if s is the arithmetic  sum of the ASCII
        characters, then
                  check = char((s + ((s AND 192)/64)) AND 63)

        This is the default block check, and all Kermit's must be
        capable  of  performing it.   Other optional  block check
        types are described later.

        The block check  is based on the ASCII  values of all the
        characters  in the  packet, including  control fields and
        prefix characters.

        5.5.4.  Send_Init Packets

     The  Send-Init  packet  contains a  string  of configuration
information in its  data field.  The data field  of the Send-Init
and the  ACK to the Send-Init  are literal, that is,  there is no
prefix encoding.  This  is because the two parties  will not know
how to do  prefix encoding until after the  configuration data is
exchanged.
     It is important to note that newly invented fields are added
at the right,  so that old Kermit programs that  do not have code
to handle the new fields will act as if they were not there.  For
this reason, the default value for any field, indicated by blank,
should result in the behavior  that occurred before the new field
was defined or added.

   1      2      3     4     5     6     7     8     9     10...
  +-----+-----+-----+-----+-----+-----+-----+-----+-----+------
  |MAXL |TIME |NPAD |PADC |EOL  |QCTL |QBIN |CHKT |REPT |CAPAS
  +-----+-----+-----+-----+-----+-----+-----+-----+-----+------

     The fields are  as follows (the first and  second person "I"
and  "you" are  used to distinguish  the two  sides).  Fields are
encoded  printably  using  the char()  function  unless indicated
otherwise.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

MAXL    The maximum length packet I  want to receive, a number up
        to 94  (decimal).  You respond with  the maximum you want
        me  to  send.   This  allows systems  to  adjust  to each
        other's  buffer  sizes,  or   to  the  condition  of  the
        transmission medium.

TIME   The number  of seconds after  which I want you  to time me
        out while waiting for a packet from me.  You respond with
        the amount  of time I  should wait for  packets from you.
        This  allows the  two sides  to accommodate  to different
        line  speeds  or other  factors  that could  cause timing
        problems.   Only  one side  needs to  time out.   If both
        sides time out, then the  timeout intervals should not be
        close together.

NPAD    The number  of padding characters I  want to precede each
        incoming  packet; you  respond in  kind.  Padding  may be
        necessary  when  sending  to  a half  duplex  system that
        requires   some   time   to  change   the   direction  of
        transmission, although in practice this situation is more
        commonly handled by a "handshake" mechanism.

PADC    The  control  character  I  need  for  padding,  if  any,
        transformed by  ctl() (not char()) to  make it printable.
        You  respond  in  kind.   Normally  NUL  (ASCII  0), some
        systems use DEL (ASCII 127).  This field is to be ignored
        if the value NPAD is zero.

EOL     The character I need to  terminate an incoming packet, if
        any.  You  respond in kind.  Most  systems that require a
        line terminator for terminal input accept carriage return
        for  this  purpose  (note,  because there  is  no  way to
        specify that  no EOL should  be sent, it  would have been
        better to  use ctl() for  this field rather  than char(),
        but it's too late now).

QCTL    The printable ASCII character I will use to quote control
        characters,  normally  and by  default "#".   You respond
        with the one you will use.

        The  following  fields  relate  to  the  use  of OPTIONAL
        features   of   the  Kermit   protocol.    See  "Optional
        Features".


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

QBIN    The  printable  ASCII character  I want  to use  to quote
        characters which  have the 8th bit  set, for transmitting
        binary files when the parity bit cannot be used for data.
        Since this  kind of quoting increases  both processor and
        transmission overhead, it is  normally to be avoided.  If
        used,  the  quote character  must be  in the  range ASCII
        33-62 ("!"  through ">") or 96-126 ("`" through "~"), but |
        different from the control-quoting character.  This field
        is interpreted as follows:

              Y   I agree to 8-bit quoting if you request it.
              N   I will not do 8-bit quoting.
              &   (or any  other character in the  range 33-62 or
                  96-126) I  want to do 8-bit  quoting using this
                  character (it will be  done if the other Kermit
                  puts a  Y in this  field, or responds  with the
                  same  prefix   character,  sich  as   &).   The
                  recommended 8th-bit quoting prefix character is
                  "&".
                  Anything  Else  :   8-bit quoting  will  not be
                  done.

        Note that this scheme allows  either side to initiate the
        request, and the order does  not matter.  For instance, a
        microcomputer   capable   of  8-bit   communication  will
        normally put a "Y" in this field whereas a mainframe that
        uses parity will always put  an "&".  No matter who sends
        first,  this  combination  will  result  in  election  of
        8th-bit quoting.

CHKT    Check  Type, the  method for  detecting errors.   "1" for
        single-character   checksum  (the   normal  and  required
        method), "2"  for two-character checksum  (optional), "3"
        for   three-character  CRC-CCITT   (optional).   If  your
        response  agrees,  the  designated method  will  be used;
        otherwise the single-character checksum will be used.

REPT    The prefix  character I will  use to indicate  a repeated
        character.   This can  be any printable  character in the
        range  ASCII  33-62  or  96-126, but  different  from the
        control and 8th-bit prefixes.   SP (32) denotes no repeat
        count  processing  is to  be  done.  Tilde  ("~")  is the |
        recommended  and  normal  repeat  prefix.   If  you don't
        respond  identically,  repeat  counts will  not  be done.
        Groups  of at  least 3 or  4 identical  characters may be
        transmitted more efficiently using a repeat count, though
        an individual implementation may  wish to set a different
        threshhold.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

CAPAS   A bit mask,  in which each bit position  corresponds to a
        capability of Kermit, and is  set to 1 if that capability
        is present, or 0 if it is not.  Each character contains a
        6-bit field (transformed by  CHAR()), whose low order bit
        is set to 1 if another  capability byte follows, and to 0
        in the last capability byte.  The capabilities defined so
        far are:
             #1  Reserved
             #2  Reserved
             #3  Ability to accept "A" packets (file attributes)
        The  capability byte  as defined  so far  would then look
        like:

        bit5 bit4 bit3 bit2 bit1 bit0
        +----+----+----+----+----+----+
        | #1 | #2 | #3 | -- | -- |  0 |
        +----+----+----+----+----+----+

        If  all these  capabilities were  "on", the  value of the
        byte would be  70 (octal).  When capabilities 4,  5 and 6
        are added, the capability mask will look like this:

        bit5  4   3   2   1   0     bit5  4   3   2   1   0
        +---+---+---+---+---+---+   +---+---+---+---+---+---+
        |#1 |#2 |#3 |#4 |#5 | 1 |   |#6 |-- |-- |-- |-- | 0 |
        +---+---+---+---+---+---+   +---+---+---+---+---+---+

Next 4: Reserved  Fields  Sites  that   wish  to  add  their  own
        parameters  to  the initial  connection  negotiation must
        start at  the 5th field  after the last  capability byte.
        Any intervening  fields may be left  blank (that is, they
        may  contain  the  space  character).   These  fields are
        reserved for future use by the standard Kermit protocol.

        The  control,  8th-bit,  and   repeat  prefixes  must  be
        distinct.  All  Send-Init fields are  optional.  The data
        field may be left  totally empty.  Similarly, intervening
        fields may be defaulted by setting them to blank.  Kermit
        implementations  should know  what to do  in these cases,
        namely apply appropriate defaults.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

        The defaults should be:

        MAXL:   80
        NPAD:   0, no padding
        PADC:   0 (NUL)
        EOL:    CR (carriage return)
        QCTL:   the character "#"
        QBIN:   none, don't do 8-bit quoting
        CHKT:   "1", single-character checksum
        REPT:   No repeat count processing
        MASK:   All zeros (no special capabilities)

6.  Optional Features

     The  foregoing  sections   have  discussed  basic,  required
operations for any Kermit  implementation.  The following section
discusses optional and advanced features.

6.1.  Optional Features on Multics

     This  section discusses  the optional features  that will be
included in the Kermit implementation for Multics.

6.1.1.  8th-Bit Prefixing and Repeat Count Prefixing

     Prefix  quoting  of  control  characters  is  mandatory.  In
addition,  prefixing  may also  be used  for 8-bit  quantities or
repeat counts, when both Kermit programs agree to do so.  8th-bit
prefixing can allow 8-bit binary data pass through 7-bit physical
links.   Repeat  count prefixing  can  improve the  throughput of
certain kinds of files dramatically.
     When more than one type of  prefixing is in effect, a single
data character can be preceded by more than one prefix character.
A receiver will  never do any kind of  prefixing, since prefixing
can only occur in the data  field, and the receiver only responds
with  ACKs and  NAKs with empty  or special  data fields.  Repeat
count processing  can only be  requested by the  sender, and will
only  be  used by  the  sender if  the receiver  agrees.  8th-bit
prefixing  is  a special  case  because its  use is  normally not
desirable,  since it  increases both  processing and transmission
overhead.   However,   since  it  is   the  only  straightforward


Multics Technical Bulletin                                MTB-676
Kermit Protocol

mechanism  for binary  file transfer  available to  those systems
that usurp the parity bit, a receiver must be able to request the
sender  to  do  8th-bit  quoting,  since  most  senders  will not
normally do it by default.
     The   repeat   prefix   is   followed   immediately   by   a
single-character  repeat  count,  encoded  printably  via char(),
followed by the character itself  (perhaps prefixed by control or
8th  bit  quotes,  as  explained below).   The  repeat  count may
express values from 0 to 94.  If a character appears more than 94
times  in a  row, it must  be "cut  off" at 94,  emitted with all
appropriate  prefixes,  and  "restarted".   The  following  table
should clarify  Kermit's quoting mechanism (the  final line shows
how a sequence of 120 consecutive NULs would be encoded):

               Quoted             With
  Character    Representation     Repeat Count for 6
     A            A                ~(A  ["(" is ASCII 40-32=6]    |
     ^A           #A               ~(#A                           |
     'A           &A               ~(&A                           |
     '^A          &#A              ~(&#A                          |
     #            ##               ~(##                           |
     '#           &##              ~(&##                          |
     &            #&               ~(#&                           |
     '&           &#&              ~(&#&                          |
     ~            #~               ~(#~                           |
     '~           &#~              ~(&#~                          |
     NUL          #@               ~~#@~:#@ [120 NULs]            |

     A  represents  any  printable character,  ^A  represents any
control character,  'x represents any character  with the 8th bit
set.  The # character is  used for control-character quoting, and
the & character for 8-bit  quoting.  The repeat count must always
precede any  other prefix character.   The repeat count  is taken
literally (after transformation by unchar(); for instance "#" and
"&" immediately following a "~" denote repeat counts, not control |
characters or 8-bit characters.   The control quote character "#"
is  most  closely bound  to  the data  character, then  the 8-bit
prefix,  then the  repeat count;  in other  words, the  order is:
repeat prefix and count, 8-bit quote, control quote, and the data
character itself.  To illustrate, note that &#A is not equivalent
to #&A.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

     When  the  parity bit  is available  for data,  then 8th-bit
quoting  should  not be  done, and  the 8th  bit of  the prefixed
character will have the same value as the 8th bit of the original
data byte.  In that case, the table looks like this:
               Quoted             With
  Character    Representation     Repeat Count for 6
     'A           'A               ~('A                           |
     '^A          #'A              ~(#'A                          |
     '#           #'#              ~(#'#                          |
     '&           '&               ~('&                           |
     '~           #'~              ~(#'~                          |

     Note that  since 8th bit  quoting is not being  done, "&" is
not being  used as an  8th bit prefix  character, so it  does not
need to be  quoted with "#".  Also, note that  the 8th bit is set
on the final argument of the repeat sequence, no matter how long,
and not on any of the prefix characters.

Finally, remember the following rules:
   - Prefixed sequences must not be broken across packets.

   - Control,  8th-bit,   and  repeat  count   prefixes  must  be
     distinct.

   - Data  fields  of all  packets must  pass through  the prefix
     encoding mechanism, except for S, I, and A packets, and ACKs
     to those packets.

    In the first rule above,  note that a prefixed sequence means
a  single  character  and all  its  prefixes, like  ~%&#X,  not a |
sequence like #M#J, which is two prefixed sequences.

6.2.  Other Optional Features

     This  section briefly  discusses the  optional features that
will  not  be included  in the  initial Kermit  implementation on
Multics.  For a more detailed explanation, refer to Appendix A.

6.2.1.  Alternate Block Check Types

There are two optional kinds of block checks:
Type 2
    A two-character  checksum based on  the low order  12 bits of
    the arithmetic sum  of the characters in the  packet from the
    LEN field through the last data character, inclusive.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

Type 3
    A three-character 16-bit CRC-CCITT.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

6.2.2.  Interrupting a File Transfer

     A  mechanism  is  provided  whereby interruption  of  a file
transfer may be triggered by typing an interrupt character at the
console.

6.2.3.  Transmitting File Attributes

     The optional Attributes (A)  packet provides a mechanism for
the sender of a file  to provide additional information about it.
This packet can be sent if the receiver has indicated its ability
to  process it  by setting the  Attributes bit  in the capability
mask.  If both sides set this  bit in the Kermit capability mask,
then the sender, after sending the filename in the "F" packet and
receiving an acknowledgement, may (but  does not have to) send an
"A" packet to provide  file attribute information.  The Attribute
packet conveys information about the  size of the file, creator's
ID, block size, data packet format, protection code, etc.

7.  Kermit Server

     A Kermit server is a Kermit program running remotely with no
"user interface".   All commands to the  server arrive in packets
from the local Kermit.  SERVER  operation is much more convenient
than basic  operation, since the  user need never  again interact
directly with the remote Kermit program after once starting it up
in server  mode, and therefore need  not issue complementary SEND
and  RECEIVE commands  on the  two sides  to get  a file transfer
started; rather,  a single command  (such as SEND or  GET) to the
local Kermit suffices.  Kermit  servers can also provide services
beyond file transfer.
     Server operation must be implemented  in two places:  in the
server  itself,   and  in  any   Kermit  program  that   will  be
communicating with a  server.  The server must have  code to read
the server commands  from packets and respond to  them.  The user
Kermit  must  have  code   to  parse  the  user's  server-related
commands, to form  the server command packets, and  to handle the
responses to those server commands.
     Between  transactions,  a  Kermit server  waits  for packets
containing server commands.  The packet sequence number is always
set back  to 0 after  a transaction.  A Kermit  server in command
wait should be looking for packet  0, and command packets sent to
servers should  also be packet  0.  Certain server  commands will
result  in the  exchange of  multiple packets.   Those operations
proceed exactly like file transfer.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

   A Kermit server  program waiting for a command  packet is said
to  be in  "server command wait".   Once put  into server command
wait, the  server should never  leave it until it  gets a command
packet  telling  it  to  do   so.   This  means  that  after  any
transaction  is  terminated, either  normally or  by any  kind of
error,  the  server must  go  back into  command wait.   While in
command wait,  a server may  elect to send out  periodic NAKs for
packet  0,  the  expected  command packet.   The  NAKS  should be
transmitted every  30 to 60  seconds and always contain  a type 1
checksum.

7.1.  Server Commands

     Server commands are listed below.  Not all of them have been
implemented,  and  some may  never  be, but  their use  should be
reserved.   Although server-mode  operation is  optional, certain
commands  should be  implemented in every  server.  These include
Send-Init  (S),  Receive-Init (R),  and  the Generic  Logout (GL)
and/or Finish (GF) commands.  If the server receives a command it
does not understand, or cannot execute, it should respond with an
Error (E) packet containing  a message like "Unimplemented Server
Command"  and both  sides should  set the  packet sequence number
back to 0,  and the server should remain  in server command wait.
Only a GL or GF command should terminate server operation.

Server commands are as follows:

     S   Send Initiate  (exchange parameters, server  waits for a
         file).
     R   Receive Initiate  (ask the server to  send the specified
         files).
     I   Initialize (exchange parameters).
     X   Text  header.   Allows transfer  of  text to  the user's
         screen in  response to a generic  or host command.  This
         works   just   like  file   transfer  except   that  the
         destination "device"  is the screen rather  than a file.
         Data  field  may  contain  a filename,  title,  or other
         heading.
     C   Host Command.   The data field  contains a string  to be
         executed  as  a  command  by  the  host  system  command
         processor.
     K   Kermit Command.  The data field contains a string in the
         interactive  command  language   of  the  Kermit  server
         (normally a  SET command) to  be executed as  if it were
         typed in at command level.
     G   Generic Kermit Command.  Single  character in data field
         (possibly  followed  by  operands,  shown  in  {braces},


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

         optional fields in [brackets]) specifies the command:
         I   Login [{*user[*password[*account]]}]
         C   CWD,
              Change Working Directory [{*directory[*password]}]
         L   Logout, Bye
         F   Finish (Shut down the server, but don't logout).
         D   Directory [{*filespec}]
         U   Disk Usage Query [{*area}]
         E   Erase (delete) {*filespec}
         T   Type {*filespec}
         R   Rename {*oldname*newname}
         K   Copy {*source*destination}
         W   Who's logged in?
              (Finger) [{*user ID or network host[*options]}]
         M   Send a short Message {*destination*text}
         H   Help [{*topic}]
         Q   Server Status Query
         P   Program {*[program-filespec][*program-commands]}
         J   Journal {*command[*argument]}
         V   Variable {*command[*argument[*argument]]}

     Asterisk as  used above ("*")  represents a single-character
length field, encoded using char(),  for the operand that follows
it;  thus lengths  from 0  to 94  may be  specified.  This allows
multiple  operands to  be clearly  delimited regardless  of their
contents.   Note that  field length  encoding is  used within the
data  field of  all Generic command  packets, but  not within the
data fields of the other packets, such as S, I, R, X, K, and C.
     All server commands that send arguments in their data fields
should  pass through  the prefix  encoding mechanism.   Thus if a
data character or length field happens to correspond to an active
prefix character,  it must itself be  prefixed.  The field length
denotes  the  length  of  the field  before  prefix  encoding and
(hopefully)  after  prefix  decoding.   For  example,  to  send a
generic command with two fields, "ABC" and "ZZZZZZZZ", first each
field  would be  prefixed by char()  of its length,  in this case
char(3)  and  char(8), giving  "#ABC(ZZZZZZZZ".   But "#"  is the
normal control  prefix character so  it must be  prefixed itself,
and the eight Z's can be condensed to 3 characters using a repeat
prefix  (if repeat  counts are  in effect),  so the  result after
encoding  would  be "##ABC(~(Z"  (assuming  the repeat  prefix is |
tilde  ("~").   The recipient  would  decode this  back  into the |
original  "#ABC(ZZZZZZZZ"  before attempting  to extract  the two
fields.
     Since a generic  command must fit into a  single packet, the


Multics Technical Bulletin                                MTB-676
Kermit Protocol

program  sending  the  command  should  ensure  that  the command
actually fits,  and should not  include length fields  that point
beyond  the  end  of  the packet.   Servers,  however,  should be
defensive and  not attempt to  process any characters  beyond the
end of  the data field,  even if the argument  length field would
lead them to do so.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

7.2.  The R Command

      The  R  packet, generally  sent by  a local  Kermit program
whose  user typed  a GET  command, tells  the server  to send the
files specified  by the name in  the data field of  the R packet.
Since we  can't assume that  the two Kermits are  running on like
systems,   the   local  (user)   Kermit   must  parse   the  file
specification as a  character string and let the  server to check
it.  If the server can open and read the specified file, it sends
a Send-Init (S) packet, not  an acknowledgement, to the user, and
then completes  the file-sending transaction,  as described above
in Basic Kermit.
    If the server cannot send the file, it should respond with an
error (E)  packet containing a  reason, like "File  not found" or
"Read access required" and return to server command wait.

7.3.  Exchanging Parameters Before Server Commands

In basic  Kermit, the Send-Init exchange  is always sufficient to
configure the two sides to  each other.  During server operation,
on  the  other  hand,  some transactions  may  not  begin  with a
Send-Init packet.  For instance, when  the user sends an R packet
to ask the  server to send a file, the  server chooses what block
check  option  to  use.   Or if  the  user  requests  a directory
listing, the server does not know what packet length to use.

The solution to  this problem is the "I"  (Init-Info) packet.  It
is exactly  like a Send-Init  packet, and the ACK  works the same
way  too.   However,  receipt  of  an  I  packet  does  not cause
transition  to  file-send  state.  The  I-packet  exchange simply
allows the two sides to  set their parameters, in preparation for
the next transaction.

Servers  should be  able to receive  and ACK "I"  packets when in
server  command wait.   User Kermits  need not  send "I" packets,
however; in  that case, the  server will assume  all the defaults
for the user listed on page  18, or whatever parameters have been
set by other means (e.g.  SET commands typed to the server before
it was put in server mode).


Multics Technical Bulletin                                MTB-676
Kermit Protocol

7.4.  Short and Long Replies

    Any request made of a server may be answered in either of two
ways, and  any local Kermit  that makes such a  request should be
prepared for either kind of reply:

     - A  short  reply.  This  consists of  a single  ACK packet,
       which may  contain text in its  data field.  For instance,
       the user might send a disk  space query to the server, and
       the server  might ACK the  request with a  short character
       string in the  data field, such as "12K  bytes free".  The
       user Kermit should display this text on the screen.

     - A long reply.  This proceeds  exactly like a file transfer
       (and in some cases it may  be a file transfer).  It begins
       with one of the following:

         * A File-Header (F) packet.

         * A Text-Header (X) packet.

         * A Send-Init (S) Packet, followed by an X or F packet.

            After the X or F  packet comes an arbitrary number of
       Data  (D)  packets, then  an  End-Of-File (Z)  packet, and
       finally a  Break-Transmission (B) packet,  as for ordinary
       file transfer.

7.5.  Additional Server Commands

     The following server commands  request the server to perform
tasks other than sending or receiving files.  Almost any of these
can have either short or long replies.  For instance, the Generic
Erase  (GE)  command may  elicit  a simple  ACK,  or a  stream of
packets  containing  the names  of  all the  files it  erased (or
didn't erase).  These commands are  now described in more detail;
arguments are  as provided in  commands typed to  the user Kermit
(subject to  prefix encoding); no transformations  to any kind of
normal or canonic  form are done -- filenames  and other operands
are in the syntax of the server's host system.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

I   Login.   For  use when  a Kermit  server is  kept perpetually
    running on a dedicated line.  This  lets a new user obtain an
    identity on the  server's host system.  If the  data field is
    empty,  this removes  the user's  identity, so  that the next
    user does not  get access to it.  A  dedicated server such as
    this should  probably disallow the L  and F generic commands,
    listed below.

L   Logout,  Bye.  This  shuts down the  server entirely, causing
    the server  itself to log out  its own job.  This  is for use
    when the server has been started up manually by the user, who
    then wishes to shut it down remotely.

F   Finish.  This is  to allow the user to  shut down the server,
    putting its  terminal back into normal  (as opposed to binary
    or  raw) mode,  and putting the  server's job  back at system
    command level, still logged in,  so that the user can connect
    back to the job.

C   CWD.   This  sets  the  default directory  or  area  for file
    transfer  on  the  server's  host.   With  no  operands, this
    command sets  the default area  to be the  user's own default
    area.

D   Directory.  Send  a directory listing to  the user.  The user
    program can display it on the terminal or store it in a file,
    as  it chooses.   The directory  listing should  contain file
    sizes and creation dates as  well as file names, if possible.
    A wildcard or other file-group designator may be specified to
    ask  the  server list  only  those files  that match.   If no
    operand  is given,  all files in  the current  area should be
    shown.

U   Disk  Usage Query.   The server  responds with  the amount of
    space used  and the amount left  free to use, in  K bytes (or
    other units, which should be specified).

E   Erase (delete).  Delete the specified file or file group.

T   Type.  Send the specified file  or file group, indicating (by
    starting with an X packet rather than an F packet, or else by
    using the Type attribute) that the file is to be displayed on
    the screen, rather than stored.

R   Rename.  Change the  name of the file or  files as indicated.
    The  string  indicating  the   new  name  may  contain  other
    attributes,  such  as  protection  code,  permitted  in  file
    specifications by the host.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

K   Copy.   Produce  a new  copy of  the file  or file  group, as
    indicated, leaving the source file(s) unmodified.

W   Who's logged in?  (Finger).  With  no arguments, list all the
    users who are  logged in on the server's  host system.  If an
    argument is  specified, provide more  detailed information on
    the specified user or network host.

M   Short Message.  Send the  given short (single-packet) message
    to the indicated user's screen.

P   Program.   This  command  has  two  arguments,  program  name
    (filespec), and command(s) for  the program.  The first field
    is required, but may be left null (i.e.  zero length).  If it
    is null, the currently loaded  program is "fed" the specified
    command.  If  not null, the  specified program is  loaded and
    started;  if  a program  command is  given it  is fed  to the
    program  as an  initial command  (for instance,  as a command
    line argument on systems that  support that concept).  In any
    case, the  output of the  program is sent back  in packets as
    either a long or short reply, as described above.

J   Journal.  This  command controls server  transaction logging.
    Transaction logging is the recording  of the progress of file
    transfers.   It should  contain entries  showing the  name of
    each  file transferred,  when the  transfer began  and ended,
    whether it completed successfully, and if not, why.  The data
    field contains one of the following:

    +   Begin  logging  transactions.   If a  filename  is given,
        close  any currently  open transaction and  then open the
        specified file as the new transaction log.  If no log was
        open and no filename was  given, the server should open a
        log with a default name, like TRANSACTION.LOG.

    -   Stop  logging transactions,  but don't  close the current
        transaction log file.

    C   Stop logging and close the current log.

S   Send the transaction log.  If it was open, close it first.

    V   Set or Query a variable.  The command can be S or Q.  The
        first  argument   is  the  variable   name.   The  second
        argument, if any, is the value.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

    S   Set  the specified  variable to the  specified value.  If
        the value  is null, then  undefine the variable.   If the
        variable is  null then do  nothing.  If the  variable did
        not exist  before, create it.  The  server should respond
        with an ACK whose data field contains a Y to indicate the
        variable  was set,  or N to  indicate it was  not set; an
        empty data field is equivalent to Y.

    Q   Query the value of the named variable.  If no variable is
        supplied, display the value of all active variables.  The
        server  responds with  either a  short or  long reply, as
        described above.  If a queried variable does not exist, a
        null value is returned.

        Variables  are  named  by  character  strings,  and  have
        character string values, which  may be static or dynamic.
        For instance, a server might have built-in variables like
        "system name"  which never changes, or  others like "mail
        status" which, when queried, cause the server to check to
        see if the user has any new mail.

7.6.  Host Commands

     Host commands  are conceptually simple,  but may be  hard to
implement on some  systems.  The C packet contains  a text string
in its data field which is simply fed to the server's host system
command processor; any output from  the processor is sent back to
the user in Kermit packets, as either a short or long reply.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

8.  Implementation on Multics

    As  mentioned previously,  various implementations  of Kermit
exist   for  a   variety  of  machines   and  operating  systems.
Individual  implementations all  have the  functionality of basic
Kermit  as described  in section 5,  but differ in  the number of
optional features they contain.  It  is proposed that for MR11, a
release of Kermit exist on Multics  that is capable of talking to
any  other   Kermit.   To  achieve  this   end,  Kermit  must  be
implemented  in such  a way  as to  include the  basic operations
required for any file transfer or Kermit server, and to allow for
the addition of optional features.  Following is a description of
Kermit as it will be for MR11.
    A Kermit server is useful only to those microcomputer (local)
implementations  of  Kermit  that  are capable  of  talking  to a
server.   To avoid  restricting the  use of  Multics Kermit  to a
particular microcomputer implementation, it is necessary to allow
both  the basic  and server modes  of operation  on Multics.  The
basic Kermit was defined in section 5 and is to be implemented on
Multics  with  the  advanced   features  of  8th-bit  and  repeat
prefixing.
    In addition a Kermit server  is to be implemented on Multics.
The initial version  for MR11 will be able  to both interpret and
respond to  the Send-Init (S), the  Receive-Init (R), the Generic
Logout (GL)  and the Generic Finish  (GF) packets.  Additionally,
the  Multics  Kermit server  will  be capable  of  processing the
Init-Info (I) packet.

The following  is a state  table for the full  Kermit protocol on
Multics for MR11, including both server mode and sending commands
to a server  Kermit.  Those states whose names  start with "Send"
always send  a packet each  time they are entered  (even when the
previous  state  was the  same).  States  whose name  starts with
"Rec", always wait for a packet to be received (up to the timeout
value), and  process the received packet.   States whose names do
not  include  either  send  or  receive  do  not  process packets
directly.   These are  states which perform  some local operation
and then change to another state.

The  initial  state  is  determined  by  the  user's  command.  A
"server"  command  enters at  Rec_Server_Idle.  A  "send" command
enters  at Send_Init.   A "receive"  command (the  old non-server
version, not a "get" command) enters at Rec_Init.

Under  "Rec'd Msg",  the packet type  of the  incoming message is
shown, followed  by the packet  number in parentheses;  (n) means
the current packet number, (n-1)  and (n+1) mean the previous and
next packet numbers (modulo 64), (0) means packet number zero.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

Under "Action",  "r+" means that  the retry count  is incremented
and compared with a threshhold; if the threshhold is exceeded, an
Error  packet is  sent and  the state  changes to  "Abort".  "n+"
means that the  packet number is incremented, modulo  64, and the
retry count, r, is set back to zero.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

State   Rec'd Msg       Action                  Next state

Rec_Server_Idle -- Server idle, waiting for a message

    Set n and r to 0

        I(0)            Send ACK                Rec_Server_Idle
        S(0)            Process params,
                         ACK with params, n+    Rec_File
        R(0)            Save file name          Send_Init

        K, C(0)         Send E(Not Implemented) abort
        GL(0)           Send ACK(0)             logout
        GF(0)           Send ACK(0)             exit
        Timeout         Send NAK(0)             Rec_Server_Idle
        Other           Error                   Rec_Server_Idle

Rec_Init -- Entry point for non-server RECEIVE command

    Set n and r to 0

        S(0)            Process params, send
                         ACK with params, n+    Rec_File
        Timeout         Send NAK(0), r+         Rec_Init
        Other           NAK                     Abort

Rec_File -- Look for a file header or EOT message

        F(n)            Open file, ACK, n+      Rec_Data
        X(n)            E(Not Implemented)      Abort
        B(n)            ACK                     Complete
        S(n-1)          ACK with params, r+     Rec_File
        Z(n-1)          ACK, r+                 Rec_File
        Timeout         NAK, r+                 Rec_File
        Other           NAK                     Abort

Rec_Data -- Receive data up to end of file

        D(n)            Store data, ACK, n+;    Rec_Data
        D(n-1)          Send ACK, r+            Rec-Data
        Z(n)            Close file, ACK, n+     Rec_File
        F(n-1)          Send ACK, r+            Rec_Data
        X(n-1)          E(Not Implemented), r+  Rec_Data
        Timeout         Send NAK, r+            Rec_Data
        Other           Send E                  Abort


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

Send_Init -- Also entry for SEND command

    Set n and r to 0, send S(0) with parameters

        Y(0)            Process params, n+      Open_File
        N, Timeout      r+                      Send_Init
        Other           r+                      Send_Init

Open_File -- Open file or set up text to send

                                                Send_File

Send_File -- Send file or text header

    Send F

        Y(n), N(n+1)    Get first buffer of     Send_Data or
                         data, n+                Send_Eof if
                                                 empty file or
                                                 text
        N, Timeout      r+                      Send_File
        Other                                   Abort

Send_Data -- Send contents of file or textual information

    Send D(n) with current buffer

        Y(n), N(n+1)    n+, Get next buffer     Send_Data or
                                                 Send_Eof if at
                                                 end of file or
                                                 text
        N, Timeout      r+                      Send_Data
        Other                                   Abort

Send_Eof -- Send end of file indicator

    Send Z(n)

        Y(n), N(n+1)    Open next file, n+      Send_File if
                                                 more, or
                                                 Send_Break if no
                                                 more
        N, Timeout      r+                      Send_Eof
        Other                                   Abort


Multics Technical Bulletin                                MTB-676
Kermit Protocol

Send_Break -- End of Transaction

    Send B(n)

        Y(n), N(0)                              Complete
        N(n), Timeout                           Send_Break
        Other                                   Abort

Complete -- Successful Completion of Transaction

        Set n and r to 0;
        If server, reset params, enter Rec_Server_Idle
        otherwise exit

Abort -- Premature Termination of Transaction

    Reset any open file, set n and r to 0

        If server, reset params, enter Rec_Server_Idle
        otherwise exit

Exit, Logout states
        Exit or Logout

Note  that  the  generic  commands determine  the  next  state as
follows:

   1. If the  command is not  supported, an error  packet is sent
      and the next state is "Abort".

   4. If the command is Logout, an  ACK is sent and the new state
      is Logout.

   5. If the command is Exit, an ACK is sent and the new state is
      Exit.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

9.  Documentation

    The following is MPM-style  documentation for the Kermit file
transfer command.  The syntax is based on the command description
for Kermit's  on the CP/M-80 and  MSDOS systems.(1)  For commands
differing  between   the  two  systems,  the   one  most  closely
conforming to Multics standards was chosen.

________________________________________

(1) Frank da  Cruz, ed., Kermit  User Guide, Fifth  Edition.  New
    York, Trustees of Columbia University, March 2, 1984.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

kermit

Syntax:  kermit {-control_args}

Function:  Allows   a  process   to  transfer   files  from/to  a
           microcomputer.

Control arguments:
-request STR, -rq STR
    executes  STR as  a kermit  request line  before entering the
    request loop.

-quit
    exits  kermit after  performing any  operations given  by the
    -request control argument.

List of requests:
    Following is  a summary of  kermit requests.  For  a complete
    description of any request, issue the kermit request:
                 help request_name

.  prints a line describing the current invocation of kermit.
?  prints a list of requests available in kermit.
abbrev {-ca}, ab {-ca}
   controls abbreviation processing of request lines.
do rq_str {args}, [do rq_str args]
   executes/returns a request line with argument substitution.
exec_com ec_path {ec_args},
ec ec_path {ec_args},
[exec_com ec_path {ec_args}],
[ec ec_path {ec_args}]
   executes a file of kermit requests which may return a value.
execute cmd_line,
e cmd_line,
[execute active_str],
[e active_str]
   executes a Multics command line/evaluates a Multics active
   string.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

help {topics} {-ca}
   prints information about kermit requests and other topics.
list_help {topics}, lh {topics}
   displays the name of all kermit info segments on given topics.
list_requests {STRs} {-ca}, lr {STRs} {-ca}
   prints a brief description of selected kermit requests.
log {path}
   direct kermit to start logging transactions.
quit, q
   exits kermit.
quit_log
   direct kermit to stop logging transactions.
receive {path}
   receive a file or file group from the other system.
send paths
   sends a file or file group to the other system.
server
   instructs  kermit to  cease taking commands  from the keyboard
   and to receive  all further instruction in the  form of kermit
   packets.
set mode|? {STR}
   establish or modify various modes for file transfers.
show {modes}
   display mode values.
statistics, st
   show statistics about the most recent file transfer.
subsystem_name, [subsystem_name]
   prints/returns the name of this subsystem.
subystem_version, [subsystem_version]
   prints/returns the version number of this subsystem.

Usage:

The  standard  usage  of  kermit  to  transfer  files  takes  the
following form:
   1.  Start kermit on the microcomputer.
   2.  Set any desired modes.
   3.  Connect  to   Multics  via  the   CONNECT  command.   Once
       connected, you will see the standard Multics banner.
   4.  Login to Multics.
   5.  Start  kermit   on  Multics.   It  will   respond  with  a
       Multics-kermit> prompt.
   6.  Set any desired modes.
   7.  Execute either a SEND or RECEIVE command.
   8.  Use the appropriate escape sequence  to get back to kermit
       command level on the microcomputer.
   9.  Execute  the corresponding  command on  the microcomputer.
       i.e.  if you issued the SEND command to Multics, issue the
       RECEIVE to the microcomputer, or vice versa.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

  10.  File transfer begins.  The  microcomputer will display the
       status of the file transfer.
  11.  To transfer more files, CONNECT back to Multics-kermit and
       enter a carriage return to get the Multics-kermit> prompt.
       Go to step 7.
  12.  Exit  Multics-kermit  by  issuing  the  quit  command  and
       logout.
  13.  Use the appropriate escape sequence  to get back to kermit
       command level on the microcomputer.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

10.  Kermit Requests

10.1.  The log Request

kermit_request: log

Syntax: log {path}

Function:  Instructs  kermit  to   start  logging  file  transfer
           information  listing  files sent/received  to/from the
           microcomputer and whether the transfer was successful.

Arguments:

path
    The name of the segment  to be used for logging transactions.
    If  no path  is specified, logging  is defaulted  to the file
    kermit.log.

10.2.  The quit Request

kermit_request: quit, q

Syntax: q

Function:  Exits kermit, returning to Multics command level.

10.3.  The quit_log Request

kermit_request: quit_log

Syntax: quit_log

Function:  Instructs  kermit   to  stop  logging   file  transfer
           information.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

10.4.  The receive Request

kermit_request:  receive, r

Syntax:  r {path}

Function:  Receives a file or file group from the microcomputer.

Arguments:
path
    specifies the name  of the segment in which  an incoming file
    is to be stored on Multics.

Notes:
If  path  is  specified  when receiving  a  file  group  from the
microcomputer, the  first file received will  be stored under the
given  path, and  the remainder  will be  stored under  their own
names.

10.5.  The send Request

kermit_request: send, s

Syntax: s paths

Function:  Sends  the  file or  files  specified by  path  to the
           microcomputer.

Arguments:
paths
    are  the  pathnames  of  segments.   The  star  convention is
    allowed.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

10.6.  The server Request

kermit_request: server

Syntax: server

Function:  Instructs Multics kermit to cease taking commands from
           the  keyboard and  to receive  all further instruction
           from the microcomputer.  For  a generic description of
           valid     server    commands     for    Multics    see
           kermit_server_commands.gi.info.

Usage:
       1)  Invoke kermit on Multics.
       2)  Issue the kermit request:  server
       3)  Using   an  escape   sequence,  escape   back  to  the
           microcomputer kermit.
       4)  Issue  kermit  server commands  to  the microcomputer.
           Server command syntax varies  from system to system so
           you'll have  to refer to  the Kermit User's  Guide for
           your implementation of kermit.

10.7.  The set Request

kermit_request: set

syntax: set mode|? {STR}

Function:  Establish or modify modes for file transfer.

Arguments:

mode
    is the mode  being changed where STR is the  value to be set.
    For  a  description  of  valid  modes  and  their  values see
    kermit_modes.gi.info
?
    prints  a  list of  valid modes  and the  values that  may be
    associated with each.  Not to  be used when specifying a mode
    and value.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

10.8.  The statistics Request

kermit_request: statistics, st

syntax:    st

Function:  Gives statistics about the most recent file transfer.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

10.9.  The show request

kermit_request: show

Syntax: show {modes}

Function:  displays the  current modes and their  values for file
           transfer.

Arguments:

modes
    is  any valid  kermit mode.  For  a list of  kermit modes see
    kermit_modes.gi.info.  If no mode  is specified all modes and
    their corresponding values are displayed.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

11.  General Information Segments

11.1.  kermit_modes.gi.info

Kermit Modes Operation

The  following list  of modes are  recognized by  the kermit file
transfer protocol,  and the kermit requests:   set and show.  The
values associated with each mode are also given.

List of modes:
file_warning STR
     indicates the action to be  taken when an incoming file name
     has the  same name as  an existing file name  in the default
     directory  when receiving  files from  a microcomputer.  STR
     may be one of "on" or  "off".  If file_warning is on, kermit
     will rename  the file to avoid  overwriting the pre-existing
     one.  If file_warning is off  the incoming file will replace
     the pre-existing one.  If logging transactions, the log will
     indicate either the replacement or the new name of the file.
     Default is on.
incomplete STR
     indicates  the  action  to  be  taken  if  a  file  was  not
     completely  transferred.   STR  may  be  one  of  "keep"  or
     "discard".  If  keep is specified, all  incomplete files are
     saved.   If discard  is specified, incomplete  files will be
     discarded.  Default is discard.

parity STR
     should  be used  for communicating with  systems or networks
     that  require character  parity.  If  parity is  being used,
     both kermits must be informed.  STR may be one of:
          "none"    eight data bits and no parity.
          "mark"    seven data bits with the parity bit set to
                    one.
          "space"   seven data bits with the parity bit set to
                    zero.
          "even"    seven data bits with the parity bit set to
                    make the overall parity even.
          "odd"     seven data bits with the parity bit set to
                    one to make the overall parity odd.

     Default is none.
file_type STR
     indicates the  type of file  being transferred.  STR  may be
     one of "binary" or "ascii".  Default is ascii.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

11.2.  kermit_server_commands.gi.info

Kermit Server Commands

The following generic commands can be issued from a microcomputer
kermit  to a  Multics kermit  server.  Actual  syntax varies from
system  to  system.   See  the   "Kermit  User  Guide"  for  your
implementation of kermit.

List of generic commands:
SEND filespec
    sends a file or file group from the microcomputer to Multics.
GET filespec
    ask   Multics  to   send  a  file   or  file   group  to  the
    microcomputer.
BYE
    shuts  down  the  Multics  kermit server  and  logs  out from
    Multics.
FINISH
    shuts  down the  Multics server, returning  to kermit command
    level  on  the microcomputer.   A subsequent  CONNECT command
    will put you back to the Multics kermit command level.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

12.  APPENDIX A. Advanced Kermit

     The  following  extracts from  the "Kermit  Protocol Manual"
discusses  those optional  features to the  basic Kermit protocol
that  will not  be implemented  on Multics  for MR11,  but may be
desirable in future releases.

12.1.  Alternate Block Check Types

There are two optional kinds of block checks:

Type 2
    A two-character  checksum based on  the low order  12 bits of
    the arithmetic sum of the  characters in the packet (from the
    LEN  field  through the  last  data character,  inclusive) as
    follows:

               1              2
      --------+--------------+-------------+
      ...data | char(b6-b11) | char(b0-b5) |
      --------+--------------+-------------+

For instance, if the 16-bit result  is 154321 (octal), then the 2
character block check would be "C1".

Type 3
    Three-character 16-bit CRC-CCITT.  The CRC calculation treats
    the data  it operates upon as  a string of bits  with the low
    order bit of the first character first and the high order bit
    of the last character last.  The  initial value of the CRC is
    taken as  0; the 16-bit  CRC is the  remainder after dividing
    the data bit string  by the polynomial (X**16)+(X**12)+(X**5)
    +1 (this  calculation can actually  be done a  character at a
    time, using a simple table  lookup algorithm).  The result is
    represented as  three printable characters at  the end of the
    packet, as follows:

               1               2              3
      --------+---------------+--------------+-------------+
      ...data | char(b12-b15) | char(b6-b11) | char(b0-b5) |
      --------+---------------+--------------+-------------+


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

For instance, if the 16-bit result  is 154321 (octal), then the 3
character block  check would be "-C1".   The CRC technique chosen
here agrees with many hardware implementations (e.g.  the VAX CRC
instruction).    A   useful   reference   on   table-driven   CRC
calculations can be found in "Byte-wise CRC Calculations" by Aram
Perez in IEEE MICRO, June 1983, p.40.

The  single-character  checksum  has  proven  quite  adequate  in
practice.  The other options can be used only if both sides agree
to  do  so  via Init  packet  (S or  I)  exchange.  The  2  and 3
character block  checks should only  be used under  conditions of
severe line noise and packet corruption.

Since type 2 and 3 block checks are optional, not all KERMITs can
be  expected  to  understand  them.   Therefore,  during  initial
connection,  communication  must  begin  using the  type  1 block
check.  If type 2 or 3 block  checks are agreed to during the "I"
or  "S" packet  exchange, the  switch will  occur only  after the
Send-Init  has been  sent and  ACK'd with  a type  1 block check.
This means that  the first packet with a type  2 or 3 block check
must  always  be an  "F"  or "X"  packet.   Upon completion  of a
transaction, both sides must switch back  to type 1 (to allow for
the fact that neither side has  any way of knowing when the other
side has  been stopped and  restarted).  The transaction  is over
after a "B"  or "E" packet has been sent  and ACK'd, or after any
error that terminates the transaction prematurely or abnormally.

A  consequence of  the foregoing rule  is that  if a type  2 or 3
block check is  to be used, a long reply  sent by the server must
begin with a  Send-Init (S) packet, even if  an I packet exchange
had already occurred.  If type 1 block checks are being used, the
S packet can be skipped and the transfer can start with an X or F
packet.

A server that  has completed a transaction and  is awaiting a new
command may send  out periodic NAKs for that  command (packet 0).
Those NAKs must have type 1 block checks.

The  use  of  alternate  block  check  types  can  cause  certain
complications.  For instance, if the server gets a horrible error
(so bad that it doesn't even send an error packet) and reverts to
command  wait, sending  NAKs for  packet 0  using a  type 1 block
check, while  a transfer using  type 2 or  3 block checks  was in
progress, neither side will be  able to read the other's packets.
Communication  can also  grind to a  halt if A  sends a Send-Init
requesting,  say,  type  3  block  checks,  B  ACKs  the request,


Multics Technical Bulletin                                MTB-676
Kermit Protocol

switches to type 3 and waits for the  X or F packet with a type 3
block check, but the ACK was lost, so A resends the S packet with
a  type  1 block  check.   Situations like  this  will ultimately
resolve  themselves after  the two  sides retransmit  up to their
retry threshhold, but can be rectified  earlier by the use of two
heuristics:

   - The packet reader can assume that if the packet type is "S",
     the block check type is 1.

   - A  NAK  packet  never  has   anything  in  its  data  field.
     Therefore, the block check type can always be deduced by the
     packet reader from  the length field of a  NAK.  In fact, it
     is  the  value  of the  length  field  minus 2.   A  NAK can
     therefore   be   thought  of   as   a  kind   of  "universal
     synchronizer".

These heuristics tend violate the layered nature of the protocol,
since  the packet  reader should normally  be totally unconcerned
with  the packet  type (which is  of interest  to the application
level which  invokes the packet  reader).  A better  design would
have had each packet include an  indicator of the type of its own
block check; this  would have allowed the block  check type to be
changed  dynamically during  a transaction  to adapt  to changing
conditions.  But it's too late for that now...


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

12.2.  Interrupting a File Transfer

This section describes an optional feature of the KERMIT protocol
to allow graceful interruption of file transfer.  This feature is
unrelated to server operation.

To interrupt sending a file, send an EOF ("Z") packet in place of
the next data  packet, including a "D" (for  Discard) in the data
field.  The  recipient ACKs the  Z packet normally,  but does not
retain the file.   This does not interfere with  older Kermits on
the receiving end; they will not  inspect the data field and will
close  the  file normally.   The  mechanism can  be  triggered by
typing  an  interrupt character  at  the console  of  the sending
KERMIT program.  If a (wildcard) file  group is being sent, it is
possible  to skip  to the  next file  or to  terminate the entire
batch; the protocol  is the same in either  case, but the desired
action could be selected  by different interrupt characters, e.g.
CTRL-X to skip  the current file, CTRL-Z to skip  the rest of the
batch.

To interrupt receiving a file, put an "X" in the data field of an
ACK  for a  data packet.  To  interrupt receiving  an entire file
group,  use  a "Z".   The  user could  trigger this  mechanism by
typing an interrupt character by  typing, say, CTRL-X and CTRL-Z,
respectively, at  the receiving KERMIT's console.   A sender that
was aware  of the new  feature, upon finding one  of these codes,
would act as described above, i.e.   send a "Z" packet with a "D"
code; a sender  that did not implement this  feature would simply
ignore the codes and continue sending.   In this case, and if the
user wanted the whole batch to be cancelled (or only one file was
being sent), the receiving KERMIT program, after determining that
the sender had  ignored the "X" or "Z" code,  could send an Error
(E) packet to stop the transfer.

The sender  may also choose to  send a Z packet  containing the D
code when it  detects that the file it is  sending cannot be sent
correctly  and  completely --  for  instance, after  sending some
packets correctly, it gets an i/o error reading the file.  Or, it
notices that the "8th bit" of a file byte is set when the file is
being  sent as  a text  file and no  provision has  been made for
transmitting the 8th bit.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

12.3.  Transmitting File Attributes

The optional  Attributes (A) packet provides  a mechanism for the
sender  of  a file  to provide  additional information  about it.
This packet can be sent if the receiver has indicated its ability
to  process it  by setting the  Attributes bit  in the capability
mask.  If both sides set this  bit in the Kermit capability mask,
then the sender, after sending the filename in the "F" packet and
receiving an acknowledgement, may (but  does not have to) send an
"A" packet to provide file attribute information.

Setting  the  Attributes  bit  in the  capability  mask  does not
indicate  support for  any particular  attributes, only  that the
receiver is prepared to accept the "A" packet.

The  attributes are  given in the  data field of  the "A" packet.
The data field  consists of 0 or more  subfields, which may occur
in any order.  Each subfield is of the following form:

  +-----------+--------------+------+
  | ATTRIBUTE | char(LENGTH) | DATA |
  +-----------+--------------+------+

where

ATTRIBUTE is a single printable character other than space,

LENGTH    is the length of the data characters (0 to 94), with 32
          added to produce a single printable character, and

DATA      is  length  characters  worth  of  data,  all printable
          characters.

No quoting or prefixing is done on any of this data.

More than one attribute packet may be sent.  The only requirement
is that all the A packets  for a file must immediately follow its
File header (or X) packet, and precede the first Data packet.

There  may be  93 different  attributes, one  for each  of the 93
printable ASCII characters other  than space.  These are assigned
in ASCII order.

! (ASCII 33)
          Length.  The  data field gives  the length in  K (1024)
          bytes,  as a  printable decimal  number, e.g.  "!#109".
          This  will allow  the receiver to  determine in advance
          whether there  is sufficient room for  the file, and/or
          how long the transfer will take.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

" (ASCII 34)
          Type.  The data field can contain some indicator of the
          nature of the file.  Operands are enclosed in {braces},
          optional items in [brackets].

          A[{xx}] ASCII  text,  containing  no  8-bit quantities,
                  logical   records  (lines)   delimited  by  the
                  (quoted)   control  character   sequence  {xx},
                  represented  here by  its printable counterpart
                  (MJ  = CRLF,  J =  LF, etc).   For instance AMJ
                  means that  the appearance of  #M#J (the normal
                  prefixed CRLF  sequence) in a  file data packet
                  indicates  the  end of  a record,  assuming the
                  current  control  prefix  is "#".   If  {xx} is
                  omitted, MJ will be assumed.

          B[{xx}] Binary.  {xx} indicates in what manner the file
                  is binary:

                  8   (default) The  file is a  sequence of 8-bit
                      bytes, which must be  saved as is.  The 8th
                      bit  may   be  sent  "bare",   or  prefixed
                      according  to   the  Send-Init  negotiation
                      about 8th-bit prefixing.

                  36  The file is a PDP-10 format binary file, in
                      which  five  7-bit bytes  are fit  into one
                      36-bit  word,  with the  final bit  of each
                      word being represented  as the "parity bit"
                      of every 5th character (perhaps prefixed).

          D{x}    Moved from here to FORMAT attribute

          F{x}    Moved from here to FORMAT attribute

          I[{x}]  Image.  The file is being sent exactly as it is
                  represented on  the system of  origin.  For use
                  between  like  systems.  There  are  {x} usable
                  bits  per  character,  before  prefixing.   For
                  instance,  to  send binary  data from  a system
                  with  9-bit  bytes, it  might be  convenient to
                  send three 6-bit characters for every two 9-bit
                  bytes.  Default {x} is 8.

# (ASCII 35)
          Creation  Date, expressed  as "[yy]yymmdd[ hh:mm[:ss]]"
          (ISO standard julian format),  e.g.  831009 23:59.  The
          time  is optional;  if given,  it should  be in 24-hour
          format, and  the seconds may  be omitted, and  a single
          space should separate the time from the date.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

$ (ASCII 36)
          Creator's  ID, expressed  as a character  string of the
          given length.

% (ASCII 37)
          Account to charge the file to, character string.

& (ASCII 38)
          Area in which to store the file, character string.

' (ASCII 39)
          Password for above, character string.

( (ASCII 40)
          Block Size.  The file has, or is to be stored with, the
          given block size.

) (ASCII 41)
          Access:

          N   New, the  normal case --  create a new  file of the
              given name.
          S   Supersede (overwrite) any file of the same name.
          A   Append to file of the given name.

* (ASCII 42)
          Encoding:

          A   ASCII,  normal  ASCII encoding  with  any necessary
              prefixing, etc.
          H   Hexidecimal "nibble" encoding.
          E   EBCDIC (sent as if it were a binary file).
          S   Sixbit Character set (equivalent to I6).
          R   Radix50
          X   Encrypted.
          Q{x}
              Huffman Encoded for compression.   First x bytes of
              the file are the key.

    # (ASCII 43)
              Disposition (operands  are specified in  the syntax
              of the receiver's host system):

          M{user(s)}      Send the file as  Mail to the specified
                          user(s).

          O{destination}  Send  the  file   as  a  long  terminal
                          message  to  the  specified destination
                          (terminal, job, or user).


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

          S[{options}]    Submit  the file  as a  batch job, with
                          any specified options.

          P[{options}]    Print  the  file on  a  system printer,
                          with  any specified  options, which may
                          specify  a  particular  printer, forms,
                          etc.

          T               Type the file on the screen.

          L[{aaa}]        Load the file into  memory at the given
                          address, if any.

          X[{aaa}]        Load the file into  memory at the given
                          address and execute it.

          A               Archive   the   file;  save   the  file
                          together  with  the  attribute  packets
                          that  preceded  it, so  that it  can be
                          sent back to the  system of origin with
                          all  its  attributes  intact.   A  file
                          stored in this  way should be specially
                          marked so that the KERMIT that sends it
                          back   will  recognize   the  attribute
                          information  as distinct  from the file
                          data.

, (ASCII 44)
          Protection.   Protection  code  for  the  file,  in the
          syntax  of the  receiver's host  file system.   With no
          operand,  store  according   to  the  system's  default
          protection for the destination area.

- (ASCII 45)
          Protection.  Protection code for  the file with respect
          to the "public" or  "world", expressed generically in a
          6-bit quantity (made printable by char()), in which the
          bits have the following meaning:

          inl 10
          b0: Read Access
          b1: Write Access
          b2: Execute Access
          b3: Append Access
          b4: Delete Access
          b5: Directory Listing


Multics Technical Bulletin                                MTB-676
Kermit Protocol

          A one in the bit position means allow the corresponding
          type of access, a zero means prohibit it.  For example,
          the letter "E" in this field would allow read, execute,
          and directory listing access  (unchar("E") = 69-32 = 37
          = 100101 binary).

. (ASCII 46)
          Machine and operating system of origin.  This is useful
          in conjunction with  the archive disposition attribute.
          It  allows  a file,  once  archived, to  be transferred
          among different types of systems, retaining its archive
          status, until  it finds its  way to a  machine with the
          right  characteristics to  de-archive it.   The systems
          are denoted by codes; the  first character is the major
          system designator,  the second designates  the specific
          model  or operating  system.  A third  character may be
          added  to  make   further  distinctions,  for  instance
          operating  system  version.  The  systems below  do not
          form a complete collection;  many more can and probably
          should be added.

                        A   Apple microcomputers

                        1   Apple II, DOS
                        2   Apple III
                        3   Macintosh
                        4   Lisa

                    B   Sperry (Univac) mainframes

                        1   1100 series, EXEC

                    C   CDC mainframes

                        1   Cyber series, NOS

                    D   DEC Systems

                        1   DECsystem-10/20, TOPS-10
                        2   DECsystem-10/20, TOPS-20
                        3   DECsystem-10/20, TENEX
                        4   DECsystem-10/20, ITS
                        5   DECsystem-10/20, WAITS
                        6   DECsystem-10/20, MAXC
                        7   VAX-11, VMS


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

                        8   PDP-11, RSX-11
                        9   PDP-11, IAS
                        A   PDP-11, RSTS/E
                        B   PDP-11, RT-11
                        C   Professional-300, P/OS
                        D   Word Processor (WPS or DECmate), WPS

                    D   Honeywell mainframes

                        1   MULTICS systems
                        2   DPS series, running CP-6

                    F   Data General machines

                        1   RDOS
                        2   AOS

                    G   PR1ME machines, PRIMOS

                    H   Hewlett-Packard machines

                        1   HP-1000, RTE
                        2   HP-3000, MPE

                    I   IBM 370-series and compatible mainframes

                        1   VM/CMS
                        2   MVS/TSO
                        3   DOS
                        4   MUSIC
                        5   GUTS
                        6   MTS

                    J   Tandy microcomputers, TRSDOS

                    K   Atari micros, DOS

                    L-T Reserved

                    U   Portable Operating or File Systems


Multics Technical Bulletin                                MTB-676
Kermit Protocol

                        1   UNIX
                        2   Software Tools
                        3   CP/M-80
                        4   CP/M-86
                        5   CP/M-68K
                        6   MP/M
                        7   Concurrent CP/M
                        8   MS-DOS
                        9   UCSD p-System
                        A   MUMPS

/ (ASCII 47)
          Format of the data within the packets.

          A{xx}           Variable   length   delimited  records,
                          terminated  by  the  character sequence
                          {xx},  where xx  is a string  of one or
                          more  control  characters,  represented
                          here  by   their  unprefixed  printable
                          equivalents, e.g.  MJ for ^M^J (CRLF).

          D{x}            Variable  length  undelimited  records.
                          Each  logical  record  begins  with  an
                          {x}-character   ASCII   decimal  length
                          field  (similar  to  ANSI  tape  format
                          "D").  For example, "D$" would indicate
                          4-digit length fields, like "0132".

          F{xxxx}         Fixed-length undelimited records.  Each
                          logical record is {xxxx} bytes long.

          R{x}            For  record-oriented  transfers,  to be
                          used  in  combination  ith  one  of the
                          formats   given  above.    Each  record
                          begins (in the case  of D format, after
                          the  length field)  with an x-character
                          long position field indicating the byte
                          position within the  file at which this
                          record is to be stored.

0 (ASCII 48)
          Special  system-dependent  parameters  for  storing the
          file  on  the system  of  origin, for  specification of
          exotic attributes not covered  explicitly by any of the
          KERMIT  attribute  descriptors.  These  are given  as a
          character  string  in  the system's  own  language, for
          example  a list  of DCB  parameters in  IBM Job Control
          Language.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

1-@ (ASCII 49-64)
          Reserved

Other  attributes  can be  imagined,  and can  be added  later if
needed.  However, two important points should be noted:

   - The receiver may have absolutely no way of honoring, or even
     recording, a given attribute.   For instance, CP/M-80 has no
     slot  for  creation date  or  creator's ID  in its  FCB; the
     DEC-20 has no concept of block size, etc.

   - The sender may have no way of determining the correct values
     of any  of the attributes.   This is particularly  true when
     sending files of foreign origin.

The  "A" packet  mechanism only  provides a  way to  send certain
information about  a file to  the receiver, with  no provision or
guarantee  about  what  the  receiver   may  do  with  it.   That
information  may be  obtained directly from  the file's directory
entry (FCB, FDB, ...), or specified via user command.

The ACK  to the "A"  packet may in  turn have information  in its
data  field.   However,  no complicated  negotiations  about file
attributes may take place, so the net result is that the receiver
may either refuse the file or  accept it.  The receiver may reply
to the  "A" packet with  any of the  following codes in  the data
field of the ACK packet:

<null>  (empty data field)  I accept the file, go  ahead and send
        it.

N[{xxx}]
        I refuse the file as specified, don't send it; {xxx} is a
        string of zero or more of the attribute characters listed
        above, to specify what attributes  I object to (e.g.  "!"
        means it's too long, "&"  means I don't have write access
        to the specified area, etc).

Y[{xxx}]
        I  agree  to  receive  the   file,  but  I  cannot  honor
        attributes {xxx},  so I will store  the file according to
        my own defaults.

Y       (degenerate case of Y{xxx}, equivalent to <null>, above)

How the receiver actually  replies is an implementation decision.
A NAK  in response to the  "A" packet means, of  course, that the
receiver did not  receive the "A" correctly, not  that it refuses
to receive the file.


Multics Technical Bulletin                                MTB-676
Kermit Protocol

13.  APPENDIX B. Advanced Kermit Protocol State Table

     This section  provides the state  table for the  full Kermit
protocol as defined by Columbia  University.  It is included as a
reference for post-MR11 implementations of Kermit.

     The following is a state table for the full Kermit protocol,
including  both  server mode  and  sending commands  to  a server
Kermit.   It  does not  include handling  of the  file attributes
packet  (A).   Note that  states  whose names  start  with "Send"
always send  a packet each  time they are entered  (even when the
previous  state  was the  same).  States  whose name  starts with
"Rec", always wait for a packet to be received (up to the timeout
value), and  process the received packet.   States whose names do
not  include  either  send  or  receive  do  not  process packets
directly.   These are  states which perform  some local operation
and then change to another state.
     The initial  state is determined  by the user's  command.  A
"server"  command  enters at  Rec_Server_Idle.  A  "send" command
enters  at Send_Init.   A "receive"  command (the  old non-server
version, not  a "get" command)  enters at Rec_Init.   Any generic
command,  the  "get" command,  and  the "host"  command  enter at
either  Send_Server_Init  or  Send_Gen_Cmd,  depending  upon  the
expected response.

Under  "Rec'd Msg",  the packet type  of the  incoming message is
shown, followed  by the packet  number in parentheses;  (n) means
the current packet number, (n-1)  and (n+1) mean the previous and
next packet  numbers (modulo 64),  (0) means packet  number zero.
Following the packet number may be slash and a letter, indicating
some  special  signal in  the  data field.   For  instance Z(n)/D
indicates a Z (EOF) packet, sequence  number n, with a "D" in the
data field.

Under "Action",  "r+" means that  the retry count  is incremented
and compared with a threshhold; if the threshhold is exceeded, an
Error  packet is  sent and  the state  changes to  "Abort".  "n+"
means that the  packet number is incremented, modulo  64, and the
retry count, r, is set back to zero.


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

State   Rec'd Msg       Action                  Next state

Rec_Server_Idle -- Server idle, waiting for a message

    Set n and r to 0

        I(0)            Send ACK                Rec_Server_Idle
        S(0)            Process params,
                         ACK with params, n+    Rec_File
        R(0)            Save file name          Send_Init

        K, C or G(0)    Short reply:
                         ACK(0)/reply           Rec_Server_Idle
                        Long reply:
                         init needed            Send_Init
                         init not needed, n+    Open_File

        Timeout         Send NAK(0)             Rec_Server_Idle
        Other           Error                   Rec_Server_Idle

Rec_Init -- Entry point for non-server RECEIVE command

    Set n and r to 0

        S(0)            Process params, send
                         ACK with params, n+    Rec_File
        Timeout         Send NAK(0), r+         Rec_Init
        Other           NAK                     Abort

Rec_File -- Look for a file header or EOT message

        F(n)            Open file, ACK, n+      Rec_Data
        X(n)            Prepare to type on
                         screen, ACK, n+        Rec_Data
        B(n)            ACK                     Complete
        S(n-1)          ACK with params, r+     Rec_File
        Z(n-1)          ACK, r+                 Rec_File
        Timeout         NAK, r+                 Rec_File
        Other           NAK                     Abort


Multics Technical Bulletin                                MTB-676
Kermit Protocol

Rec_Data -- Receive data up to end of file

        D(n)            Store data, ACK, n+;
                         If interruption wanted
                         include X or Z in ACK  Rec_Data
        D(n-1)          Send ACK, r+            Rec-Data
        Z(n)            Close file, ACK, n+     Rec_File
        Z(n)/D          Discard file, ACK, n+   Rec_File
        F(n-1)          Send ACK, r+            Rec_Data
        X(n-1)          Send ACK, r+            Rec_Data
        Timeout         Send NAK, r+            Rec_Data
        Other           Send E                  Abort

Send_Init -- Also entry for SEND command

    Set n and r to 0, send S(0) with parameters

        Y(0)            Process params, n+      Open_File
        N, Timeout      r+                      Send_Init
        Other           r+                      Send_Init

Open_File -- Open file or set up text to send

                                                Send_File

Send_File -- Send file or text header

    Send F or X(n)

        Y(n), N(n+1)    Get first buffer of     Send_Data or
                         data, n+                Send_Eof if
                                                 empty file or
                                                 text
        N, Timeout      r+                      Send_File
        Other                                   Abort

Send_Data -- Send contents of file or textual information

    Send D(n) with current buffer


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

        Y(n), N(n+1)    n+, Get next buffer     Send_Data or
                                                 Send_Eof if at
                                                 end of file or
                                                 text
        Y(n)/X or Z     n+                      Send_Eof
        N, Timeout      r+                      Send_Data
        Other                                   Abort


Multics Technical Bulletin                                MTB-676
Kermit Protocol

Send_Eof -- Send end of file indicator

    Send Z(n); if interrupting send Z(n)/D

        Y(n), N(n+1)    Open next file, n+      Send_File if
                                                 more, or
                                                 Send_Break if no
                                                 more, or if
                                                 interrupt "Z".
        N, Timeout      r+                      Send_Eof
        Other                                   Abort

Send_Break -- End of Transaction

    Send B(n)

        Y(n), N(0)                              Complete
        N(n), Timeout                           Send_Break
        Other                                   Abort

Send_Server_Init - Entry for Server commands which expect large
                   response.

    Send I(0) with parameters

        Y(0)            Process params          Send_Gen_Cmd
        N, Timeout      r+                      Send_Server_Init
        E               Use default params      Send_Gen_Cmd
        Other                                   Abort

Send_Gen_Cmd - Entry for Server commands which expect short
               response (ACK)

    Send G, R or C(0)

        S(0)            Process params,
                         ACK with params, n+    Rec_File
        X(1)            Setup to type on
                         terminal, n+           Rec_Data
        Y(0)            Type data on TTY        Complete
        N, Timeout      r+                      Send_Gen_Cmd
        Other                                   Abort


MTB-676                                Multics Technical Bulletin
                                                  Kermit Protocol

Complete -- Successful Completion of Transaction

        Set n and r to 0;
        If server, reset params, enter Rec_Server_Idle
        otherwise exit

Abort -- Premature Termination of Transaction

    Reset any open file, set n and r to 0

        If server, reset params, enter Rec_Server_Idle
        otherwise exit

Exit, Logout states
        Exit or Logout

Note  that  the  generic  commands determine  the  next  state as
follows:

   1. If the  command is not  supported, an error  packet is sent
      and the next state is "Abort".

   2. If the command  generates a response which can  be fit into
      the data  portion of an ACK,  an ACK is sent  with the text
      (quoted as necessary) in the data portion.

   3. If the  command generates a  large response or  must send a
      file, nothing  is sent from the  Rec_Server_Idle state, and
      the next state is either  Send_Init (if either no I message
      was received  or if alternate  block check types  are to be
      used), or Open_File  (if an I message was  received and the
      single character block check is to be used).

   4. If the command is Logout, an  ACK is sent and the new state
      is Logout.

   5. If the command is Exit, an ACK is sent and the new state is
      Exit.