Columbia Kermit/kermit.zip/pub/wkermit/pckermitdoc.txt

Text File | 2020-01-01 | 39KB | 938 lines

PCKERMIT.DOC                                            12/10/85


PC-DOS Kermit with Sliding Windows                      Rev 1.18
----------------------------------                      12/10/85


1. Source Code Implementation Documentation
===========================================

By Larry Jordan and Jan van der Eijk
   Revised by John Mulligan

The Kermit software modules contained in this package are
modified versions of the C-KERMIT 4C modules distributed by
Columbia University in June, 1985.  The modules were modified to
work with the Lattice C compiler and The Greenleaf Functions to
produce Kermit software compatible with PC-DOS and MS-DOS.  They
were also modified to add two new features to the software--file
attributes and sliding windows.  File attributes have been in the
official Kermit Protocol specification for some time, but the
sliding windows concept has just been approved.


The 4C version of Kermit was chosen because it was written
for maximum portability to different operating systems, and it
was the most robust version available.  The 4C version was
written for Unix and Xenix operating systems, but the
similarities with PC-DOS made it relatively easy to port to that
system.  The 4C version contained all defined Kermit capabilities
except file attributes.  None of these capabilities were removed
during our port of 4C to PC-DOS.  Some functions had to be
rewritten for PC-DOS compatibility such as filename conventions
and wildcard filename expansion.  Server support and non-protocol
related code, such as terminal emulation, was removed from 4C
during the port to reduce the size and complexity of the PC-DOS
Kermit module.

The Lattice C compiler was chosen because of its
compatibility with Unix C and because of the quality of code it
produces.  The Microsoft C Version 3.0 would be a better choice
now because of its superior error-checking and Unix
compatibility;  it was not available when we started the 4C port.
The function calls are compatible with Lattice C Version 2.15.
The modules could be compiled under Microsoft C 3.0 with few
changes.  Microsoft provides the Lattice-to-Microsoft transition
header files.

[NOTE:  Their is a reported bug in the Microsoft C Compiler which causes an
 error in the Kermit Type 3 (CRC-16) Checksum algorithm.  Beware!]

[NOTE:  Lattice C allows nested comments, which are not allowed by Microsoft
 C compiler.  Their may be some instances of nested comments.  LCKFNS3
 has at least one area that was commented out that results in a nested
 comment.]

The Greenleaf Functions General and COMM Libraries were
chosen for file and communications I/O because the functions
provide all the necessary capabilities.  The functions are
modestly priced and include source code.  All uses of these
functions are noted in comments in the source code.  A software
vendor can substitute another vendor's functions in place of The
Greenleaf Functions or use functions generated inhouse.

Unlike most communications software software and protocols,
Kermit does check parity if parity is enabled, and the protocol
will not function properly unless the selected parity matches on
both ends of the communications link.

Implementation of PCKermit
---------------------------

The PC-DOS Kermit provided in this package can be
implemented in one of two ways.  A stand-alone version of the
software can be executed from the DOS command line or through a
software SYSTEM, FORK or SHELL call.  A linkable version of the
software can be linked to smart terminal object modules and the
protocol executed from within the smart terminal program.  The
linkable version can also be added to host or bulletin board
software.  The software for both options is provided in the
package.


Stand-Alone Kermit
------------------

A stand-alone version of the PC-DOS Kermit is included in
this package.  The file is called PCKERMIT.EXE.  This file was
created by linking the LCKMAIN.OBJ module to the other Kermit
modules.  Execution of the stand-alone Kermit program requires
the same command parameters and carrier conditions regardless of
the execution method.  The module runs as a "one-shot" execution
then returns to the caller.  A single file or multiple files
(wildcard filename) are transferred until execution is completed
or the transfer is abnormally aborted.  If execution is performed
by the user from the DOS command line, termination of PCKERMIT
returns control to PC-DOS.  If execution is performed from within
a software package using a SYSTEM, FORK or SHELL call,
termination of PCKERMIT returns control to the next executable
statement after the calling statement.

The command syntax of the stand-alone Kermit program is
shown in Figure 1.  An example of execution from the DOS command
line is as follows:

PCKERMIT -l COM1 -b 1200 -p n -m 8 -w -r

This same Kermit execution can be started from within a
Lattice C program with the following function call:

system(" PCKERMIT -l COM1 -b 1200 -p n -m 8 -w -r");

Both methods allow you to receive a file through serial port
COM1 at 1200 bps using no parity.  They also request an 8 packet
sliding window from the sender and allow overwriting of
existing files.  CRC-16 error-checking is automatically requested.
If sliding windows are not supported by the sending computer,
PCKERMIT reverts to "classic" half-duplex Kermit operation.  If
the sender cannot support CRC-16 the next best common error-check
technique is negotiated.


----------------------------------------------------------------

Options:

  PCKERMIT version 1.17, December 6, 1985
  Usage: PCKERMIT [-x arg [-x arg]...[-yyy]..]]
  x is an option that requires an argument, y an option with no argument:
     -s file(s)   send
     -r           receive
     -a name      alternate name, used with -s, -r
     -h           help - print this message
  settings --                                                        default
     -l line      communication line device ( COM1, COM2 )            [COM1]
     -b baud      line speed, e.g. 1200                               [1200]
     -p x         parity, x is one of e,o,m,s,n                        [N]
     -m size      maximum window size to use ( <= 31 )                 [31]
     -n           non binary file transfer, affect CR/LF
     -t           line turnaround handshake = xon, half duplex
     -w           write over preexisting files
     -q           be quiet during file transfer
     -c           carrier detect signal required to be present
                                                                              Fi

Note 1:  Use -d (debug) only if compiled with debug statements left in
         place. (hidden option)

Note 2:  If -t is used, -m should not be used.

Note 3:  The usage of -w is reversed from standard Columbia CKERMIT.

Figure 1. PCKERMIT command syntax.

----------------------------------------------------------------

Regardless of the technique used to initiate operation of
the stand-alone Kermit program, the software requires the same
serial port and modem conditions.  The Kermit module sets up its
own send and receive interupt buffers, but it does not establish a
carrier with a remote system.  The user must initialize a
selected serial port with bit rate, parity, and stop bits then
establish a carrier with a remote host based on these parameters.
After the carrier is established and the remote Kermit is
started, the user can start the local stand-alone Kermit.


Linkable PC-DOS Kermit
----------------------

The PC-DOS Kermit modules can be easily linked to existing
smart terminal or host software written in the C language.
Linking the modules to Pascal, compiled BASIC or assembly
language requires a thorough knowledge of both C and the terminal
or host program language.  Before the linking is performed some
software changes have to be made.

The special link module is the LCKLINK.C file.  This module
contains several local and global variables that must be
initialized.  The variables can be initialized by reference to
parameters selected or established in the smart terminal program
or they can be hard coded for specific applications.  All
variables that must be initialized are shown equal to question
marks.  For example, the parity variable is shown as parity=????.
It should be noted that the LCKCLINK.C module replaces the
LCKMAIN.C module used to create the stand-alone PCKERMIT.

Another required change to facilitate direct link of Kermit
to other software is in the module LCKUSER.C.  The function
"doexit()" must be modified to return to the smart terminal
program rather than exit to DOS.  Specifically, the "exit();"
statement must be changed to a "return;" statement.

An existing smart terminal program should already contain
functions or procedures to set up communication buffers and to
initialize communication ports.  A new software product may not
have these functions established.  In any event, the LCKTIO.C
module must be modified to match the existing smart terminal
communication functions.  The "ttopen()", "ttclose()" and
"ttvt()" functions should be studied, and the noted Greenleaf
communication functions modified as necessary.  Existing
functions may be used to replace these functions.  Code comments
and Greenleaf documentation should be studied before these
routines are modified--the sequence of the function calls in
these functions are sometimes critical to interupt buffer setup
and operation.  A change in the sequence can either cause buffer
setup problems or cause the interupt sending or receiving of
characters to malfunction.

Finally, screen I/O performed by PC-DOS Kermit is done in
the LCKUSER.C module.  A smart terminal vendor will probably want
to change the TTY style output to a special file transfer screen
format.  All screen I/O are contained in the screen function.
The vendor can use display functions from a third party (i.e.,
Greenleaf or Blaise) or use functions written by the vendor to
perform fast, full screen color output.  DOS or BIOS calls can be
used without slowing down the protocol as long as the calls do
not have to scroll the screen or produce elaborate I/O.

All PCKERMIT object files contained in this package were
compiled using the Lattice C small model.  This model uses NEAR
calls in its code segment.  If the PCKERMIT files are to be
linked to software compiled under other Lattice models, the C
source code must be recompiled using the selected model.


Files for PCKERMIT
------------------
[The LCK*.C naming convention stands for "Lattice C Kermit" files]

Filename                                  |    Description
------------------------------------------------------------------------------
LCKFIO   C                                /*  File I/O module */
LCKFNS1  C                                /*  Protocol specific module 1 */
LCKFNS2  C                                /*  Protocol specific module 2 */
LCKFNS3  C                                /*  Windowing specific module  */
LCKLINK  C                                /*  Module for linkable Kermit */
LCKMAIN  C                                /*  Main program for PCKERMIT */
LCKPROT  W                                /*  Protocol state table in Wart */
LCKPROT  C                                /*  Protocol state table in C */
LCKTIO   C                                /*  RS232 I/O and time module */
LCKUSER  C                                /*  User interface module */
LCKCMD   H                                /*  Command interface header */
LCKDEB   H                                /*  Debug header file */
LCKERM   H                                /*  PCKERMIT main header file */
LCKUSR   H                                /*  User interface header file */
STDIOS   H                                /*  Lattice and Greenleaf stdio.h */
PCKERMIT ARF                              /*  PCKERMIT  link file */
PCKERMIT EXE                              /*  EXE file */
PCKERMIT MAP                              /*  Map file */
LCKWART  C                                /*  Wart source code */
LCKWART  EXE                              /*  Wart EXE file */
LCKWART  DOC                              /*  Wart documentation */


Referenced Products
-------------------

The Greenleaf Functions

Greenleaf Software Inc.
2101 Hickory Drive
Carrollton, TX 75006
[phone]

Lattice C. Compiler

Lattice
P.O. Box 3148
Glen Ellyn, IL 60138
[phone]

Microsoft C. Compiler

Microsoft
10700 Northup Way
Bellevue, WA 98004

Asynch Manager

Blaise Computing Inc.
2034 Blake Street
Berkley, CA 94704
[phone]


2. PCKERMIT.EXE USER GUIDE
==========================

The following material supplements the section "Stand-Alone Kermit" (above):

CHARACTERS DISPLAYED DURING TRANSFER
------------------------------------

During operation of the standalone PCKERMIT it
may display the following:

    %   Resend of last packet
    .   Is printed every FOURTH data packet
    A   Attributes packet (file length and creation date)
    B   End of transmission packet
    F   File Header
    N   NAK packet
    Q   Bad checksum or other packet error
    S   Send-Init packet
    T   Timeout
    Z   End of file packet


KEYBOARD INTERRUPTS
-------------------

During a file transfer PCKERMIT responds (sometimes slowly) to
the following keystrokes:

CTRL-F to cancel File,  CTRL-R to Resend current packet .
CTRL-B to cancel Batch, CTRL-K to abort Kermit and exit
CTRL-A for status report:

These functions are available even at the start of PCKERMIT before it
tells you they are available.  In particular, Control-K can be used if
the "Send-Init" exchange does not seem to be working.

Please note that PCKERMIT checks the keyboard infrequently under some
conditions.  WAIT at least 20 - 30 seconds before repeating a keystroke
in order to avoid stacking up repeated commands.  This is particularly true
of CTRL-F (cancel file) where you might cancel more than one file.

Also, the Control-F and Control-B (cancel file and cancel batch) functions
sometimes require a NAK and a resend or a timeout before they actually
work.  This is not a protocol problem, but is due to the way PCKERMIT
flushes it buffer before sending the abort packet.  In some cases, the
flushing of the buffer truncates a packet and the following abort packet is
not seen as a separate packet.

Here is a more detailed explanation of the functions:

  CTRL-F will cancel an individual file in a wildcard transaction,
  but then continue with the next file in the batch.

  CTRL-B will cancel the entire batch of files, according to
  protocol, and then return you to the DOS prompt.

  CTRL-K will abort the file transfer and return you to the DOS
  prompt.  PCKERMIT sends an Error packet indicating it is
  aborting, but otherwise does not worry about protocol.

  CTRL-R will resend the current packet; this can be used as a
  manual timeout.  With windowing is in effect, this feature should be
  tried only as a last resort as it has not been fully tested.

  CTRL-A will give you a status report on the screen.  The items
  covere are:

CONTROL-A STATUS REPORT
-----------------------
                               COMMENTS
^A  Status report:
 file type: binary             ;Details unknown

 file number: 1                ;Indicates which file of a multiple file
                                wildcard batch transfer

 characters : 1291             ;On SEND: indicates number of characters
                                output to the buffer, but not necessarily
                                yet sent out the modem.

                                On RECEIVE: indicates characters actually
                                written to disk so far; others may already
                                have been received to memory.

 window size: 31               ;The window size agreed upon after negotiation
                                with the other Kermit.  By definition, 0 means
                                Classic (non-windowing) Kermit.  Otherwise,
                                the size may vary from 1 to 31.

 block check: 1                ;The block check type agreed upon after
                                negotiation with the other Kermit.
                                  Type 1 = 1 byte checksum
                                  Type 2 = 2 byte checksum
                                  Type 3 = 3 byte CRC-16 checksum

 compression: 0                ;Is data compression (repeat count prefixing)
                                in effect?
                                  0 = No compression
                                  1 = Compression

 8th-bit prefixing: 1          ;Is 8th bit prefixing being used?
                                  0 = No
                                  1 = Yes



FUNCTIONS SUPPORTED BY PCKERMIT (Subject to agreement by the other Kermit)
-------------------------------

   Windowing (full-duplex chanell required)
   Data Compression
   8-bit quoting (whenever parity is not "none")
   File Attributes:
     File Length
       On Receive: accepts either
          the attribute ! (Ascii 33) - Approximate File Length in K bytes
          the attribute 1 (Ascii 49) - Exact file length

       On Send:
          sends the attribute 1 (Ascii 49) - Exact File Length

     Time and Date:
       Both Receive and Send
          the attribute # (Ascii 35)  - Creation date

       NOTE: when PCKERMIT receives the creation date file attribute, it
       automatically writes the received file with that date, rather than
       the current date.


PCKERMIT AT A GLANCE
--------------------

  Local operation:                   Yes
  Remote operation:                  ???
  Transfers text files:              Yes
  Transfers binary files:            Yes
  Wildcard send:                     Yes
  ^X/^Y interruption:                Yes  (Different keystrokes, though)
  Filename collision avoidance:      Yes
  Can time out:                      Yes
  8th-bit prefixing:                 Yes
  Repeat count prefixing:            Yes
  Alternate block checks:            Yes
  Terminal emulation:                No
  Communication settings:            Yes
  Transmit BREAK:                    No
  IBM mainframe communication:       ???
  Transaction logging:               No
  Session logging:                   No
  Raw transmit:                      No
  Act as server:                     No
  Talk to server:                    No
  Advanced server functions:         No
  Advanced commands for servers:     NO
  Local file management:             ???
  Handle file attributes:            Yes
  Command/init files:                No
  Command macros:                    No



3. ADDENDUM TO KERMIT PROTOCOL MANUAL, FIFTH EDITION
====================================================
  The exact file size attribute is not covered in the Fifth
  Edition of the KERMIT PROTOCOL MANUAL.  This is an addendum to
  that manual from Frank da Cruz, who maintains the Kermit
  protocol:

"Date: Fri 2 Aug 85
 From: Frank da Cruz
 Subject: attribute packets

I was just looking at the protocol manual and realized that the current edition
does not contain something which might be useful to you, namely two new
attribute fields:  "1" specifies the exact byte count of the file, and "2"
specifies the byte size (e.g. "7" or "8").  This will be in the next edition.
Many people have asked for a somewhat finer-grained way to report the file
size than the number of K (e.g. some systems need to preallocate space, but in
some unit other than K).  - Frank"


4. ADDITIONAL PCKERMIT DEVELOPMENT NOTES
========================================

The following information supplements the "1. Source Code Implmentation
Documentation" section above:

NOTES ON THE WART PROGRAM
-------------------------

The module LCKPROT.C is produced by putting LCKPROT.W through the
LCKWART.EXE pre-preprocessor.

The utility LCKWART.EXE was produced by compiling LCKWART.C, using the
for Lattice C) Link automatic response file LCKWART.ARF.

The documentatiion for WART is LCKWART.DOC.

To summarize:
LCKPROT.W         Input file to LCKWART.EXE
LCKPROT.C         What we needed; WART was required only to
                  produce this file.


COMPILE.BAT FOR LATTICE C
-------------------------

This is a small batch file that will compile a .C module into a .OBJ module.
Messages/Errors are sent to a .ERR file.

The LC1 and LC2 are the compiler modules supplied by LATTICE C.

Here is the batch file, with comments to the right:


lc1 >%1.err %1 -mS  -b       ;LC1 is the first phase of the Lattice C Compiler
                             ;>%1 Messages/Errors are logged to filename.ERR
                             ;%1 is the file being compiled
                             ;-mS indicates the Small memory model
                             ;-b  indicates "force byte alignment"

type %1.err                  ;type out the .ERR file
lc2 %1                       ;LC2 is the second phase of the Lattice C Compiler
                             ;It's input is the .Q file produced by LC1
                             ;It's output is a .OBJ file to later be linked.


Note that the small memory model (-mS) is being used; therfore, when linking
later on use the CS.OBJ module and the LCMS.LIB and LCS.LIB library modules,
which are the corresponding Small modules.



PCKERMIT.ARF
------------

The following is the contents of the PCKERMIT.ARF file, which is an
automatic response file for the LINK procedure.  (This is for the LINKer
supplied with MS-DOS 3.0)  I have annotated on the right what each
line/module does:


cs+                           -LATTICE C OBJECT MODULE (Supplied by Lattice)
lckmain+                      -MAIN PROGRAM
lckprot+                      -PROTOCOL STATE TABLE
lckfns1+                      -PROTOCOL FUNCTIONS 1
lckfns2+                      -PROTOCOL FUNCTIONS 2
lckfns3+                      -PROTOCOL FUNCTIONS 3 (Windowing specific)
lckuser+                      -USER MODULE; CONTAINS SCREEN I/O
lckfio+                       -FILE I/O
lcktio                        -TERMINAL I/O
pckermit                      -.EXE file
pckermit                      -.MAP file
gfts+gfs+gfcs+                -GREENLEAF LIBRARIES (Supplied by Greenleaf)
lcms+lcs                      -LATTICE C LIBRARIES (Supplied by Lattice)



NOTE: The Greenleaf functions are available from:

Greenleaf Software Inc.
2101 Hickory Drive
Carrollton, TX 75006
[phone]


NOTE:  Lattice C is available from:

Lattice, Inc.     OR from   Lifeboat Assoc.
P.O. Box 3148               1651 Third Avenue
Glen Ellyn, IL 60138        New York, N.Y. 10028
[phone]              [phone]


THE DEVELOPMENT ENVIRONMENT
---------------------------

The development of this software was done using the following:

Lattice C (ver. 2.15)
Greenleaf Functions General Library Rev. L2-2.10
Greenleaf Functions Communications Library Rev. L3-1.2
MS-DOS 3.0 on an IBM/PC AT
The Microsoft Linker supplied with MS-DOS 3.0



DIRECTORY OF FILES USED
-----------------------

Here is a sample directory of files for version 1.17 of PCKERMIT.EXE:

LCKWART  ARF       43   8-14-85   3:11p
PCKERMIT ARF      133  11-26-85   3:24p
COMPILE  BAT       46   7-27-85   3:41p
PCKCOMP  BAT      513   8-26-85   4:32p
PCKLINK  BAT       21  11-26-85   3:30p
LCKFIO   C      16159  12-06-85  12:01p
LCKFNS1  C      28939  12-03-85   6:37p
LCKFNS2  C      12347   8-06-85  10:04p
LCKFNS3  C      11025  11-13-85   6:07p
LCKLINK  C       9806  11-16-85  12:21p
LCKMAIN  C       8064  10-31-85   4:35p
LCKPROT  C      14153  11-09-85   7:50p
LCKTIO   C      15302  11-06-85   9:45p
LCKUSER  C      22935  12-06-85  12:05p
LCKWART  C      13151   7-30-85  11:11a
KWCHANGE DOC     4190  12-05-85   1:43p
KWINDOW5 DOC    28020  12-05-85   1:20p
LCKWART  DOC     4119   6-05-85   5:06p
PCKERMIT DOC    37691  12-06-85   2:30p
LCKFIO   ERR       70  12-06-85   3:17p
LCKFNS1  ERR      128  12-06-85   3:14p
LCKFNS2  ERR      128  12-06-85   3:15p
LCKFNS3  ERR       70  12-06-85   3:15p
LCKMAIN  ERR      283  12-06-85   3:13p
LCKPROT  ERR       70  12-06-85   3:13p
LCKTIO   ERR       70  12-06-85   3:18p
LCKUSER  ERR       70  12-06-85   3:16p
LC1      EXE    68736   5-02-85   4:49p
LC2      EXE    70592   5-02-85   4:49p
LCKWART  EXE    31996   8-14-85   3:11p
PCKERMIT EXE    70236  12-06-85   3:19p
ASIC     H       9012  10-16-85   9:59p
ASIPORTS H      12017  10-16-85   9:03p
CDISK    H       4112  11-10-84  12:00p
CSTDIO   H       2139   7-27-85   3:44p
CTYPE    H       2198   5-02-85   4:49p
FCNTL    H        896   5-02-85   4:49p
LCKCMD   H       1625   7-29-85   4:17p
LCKDEB   H       2643   7-30-85  11:00a
LCKERM   H       3610  10-26-85   3:39p
LCKUSR   H       4460   7-30-85  11:00a
STDIOS   H       2031   7-27-85   3:38p
TIMEDATE H        553   8-17-84  12:00a
GFCS     LIB    21504   4-26-85   4:54p
GFS      LIB    60416  11-10-84  12:00p
GFTS     LIB     9216  11-10-84  12:00p
LCMS     LIB    68096   5-02-85   4:50p
LCS      LIB    78848   5-02-85   4:50p
PCKERMIT MAP    25696  12-06-85   3:19p
CS       OBJ     1675   5-02-85   4:50p
LCKFIO   OBJ     6605  12-06-85   3:17p
LCKFNS1  OBJ    12381  12-06-85   3:15p
LCKFNS2  OBJ     5598  12-06-85   3:15p
LCKFNS3  OBJ     5046  12-06-85   3:16p
LCKMAIN  OBJ     3035  12-06-85   3:13p
LCKPROT  OBJ     7611  12-06-85   3:13p
LCKTIO   OBJ     6472  12-06-85   3:18p
LCKUSER  OBJ    11453  12-06-85   3:16p
PCKERMIT UPD      584  12-06-85  12:14p
LCKPROT  W       6962  11-06-85   8:24p


DESCRIPTION OF FILES USED
-------------------------

LCKWART  ARF       LINK Automatic Response File to create LCKWART pre-processor
PCKERMIT ARF       LINK Automatic Response File to create PCKERMIT.EXE
COMPILE  BAT       COMPILE batch file for Lattice C and LCK?????.C modules
PCKCOMP  BAT       PCKermit COMPile all modules batch file
PCKLINK  BAT       PCKermit LINK batch file used with PCKERMIT.ARF
LCKFIO   C         File I/O module
LCKFNS1  C         Kermit Protocol Specific Module #1
LCKFNS2  C         Kermit Protocol Specific Module #2
LCKFNS3  C         Kermit Windowing Specific Module
LCKLINK  C         Module for linkable Kermit used in place of LCKMAIN.C
LCKMAIN  C         Main program for PCKERMIT
LCKPROT  C         Protocol State table in C (derived from LCKPROT.W)
LCKTIO   C         RS232 I/O and time module
LCKUSER  C         User interface module
LCKWART  C         Source code for LCKWART.EXE preprocessor used on *.W files
KWCHANGE DOC       Kermit Windowing - Changes to definition draft to draft
KWINDOW5 DOC       Kermit WINDOWing Definition - Add to Protocol Manual
LCKWART  DOC       LCKWART (WART preproccesor for *.W files) documenation
PCKERMIT DOC       PCKERMIT Sliding Window Kermit Documentation
LC1      EXE       Lattice C 1st phase
LC2      EXE       Lattice C 2nd phase
LCKWART  EXE       WART pre-processor: *.W files input   *.C files output
PCKERMIT EXE       PCKERMIT Sliding Window Executable code
ASIC     H         "include for things that use asi buffer structure"
ASIPORTS H         Greenleaf Comm Library Header for Asynch I/O ports
CDISK    H         Greenleaf Header
CSTDIO   H         "I/O for Lattice and Microsoft C and The Greenleaf Functions"
CTYPE    H         "defines various ASCII character manipulation macros"
FCNTL    H         "symbols used for "open, "creat", and "fcntl" functions"
LCKCMD   H         Command interface header
LCKDEB   H         Debug header file
LCKERM   H         PCKERMIT main header file
LCKUSR   H         User interface header file
STDIOS   H         Combination of Lattice C and Greenleaf Headers
TIMEDATE H         Greenleaf Header
GFCS     LIB       Greenleaf Library
GFS      LIB       Greenleaf Library
GFTS     LIB       Greenleaf Library
LCMS     LIB       Lattice C v. 2.15 Library
LCS      LIB       Lattice C Library
PCKERMIT MAP
CS       OBJ       CS.OBJ file supplied with Lattice C - Small model
LCKFIO   OBJ
LCKFNS1  OBJ
LCKFNS2  OBJ
LCKFNS3  OBJ
LCKMAIN  OBJ
LCKPROT  OBJ
LCKTIO   OBJ
LCKUSER  OBJ
PCKERMIT UPD       PCKERMIT UPDate list of changes version to version
LCKPROT  W         PROTOCOL State Table in WART pre-proccesor form.


COLUMBIA UNIVERSITY
-------------------

Columbia University maintains the Kermit protocol.  The
following is taken from their file COMMER.DOC, which describes
Columbia University's policy regarding commerical use of Kermit:

"              POLICY ON COMMERCIAL USE AND DISTRIBUTION OF KERMIT

                                 Frank da Cruz

              Columbia University Center for Computing Activities

                                   June 1984


The KERMIT file transfer protocol has always been open, available, and free to
all.  The protocol was developed at the Columbia University Center for
Computing Activities, as were the first several KERMIT programs.  Columbia has
shared these programs freely with the worldwide computing community since 1981,
and as a result many individuals and institutions have contributed their own
improvements or new implementations in the same spirit.  In this manner, the
number of different systems supporting KERMIT implementations has grown from
three to about sixty in less than three years.  If Columbia had elected to keep
the protocol secret, to restrict access to source code, or to license the
software, the protocol would never have spread to cover so many systems, nor
would the programs be in use at so many sites, nor would the quality of many of
the implemementations be so high.

Although KERMIT is free and available to anyone who requests it, it is not in
the "public domain".  The protocol, the manuals, the Columbia implementations,
and many of the contributed implementations bear copyright notices dated 1981
or later, and include a legend like

  Permission is granted to any individual or institution to copy or use
  this document and the programs described in it, except for explicitly
  commercial purposes.

This copyright notice is to protect KERMIT, Columbia University, and the
various contributors from having their work usurped by others and sold as a
product.  In addition, the covering letter which we include with a KERMIT tape
states that KERMIT can be passed along to others; "we ask only that profit not
be your goal, credit be given where it is due, and that new material be sent
back to us so that we can maintain a definitive and comprehensive set of KERMIT
implementations".

Within this framework, it is acceptable to charge a reproduction fee when
supplying KERMIT to others.  The reproduction fee may be designed to recover
costs of media, packaging, printing, shipping, order processing, or any
computer use required for reproduction.  The fee should not reflect any program
or documentation development effort, and it should be be independent of how
many implementations of KERMIT appear on the medium or where they came from.
It should not be viewed as a license fee.  For instance, when Columbia ships a
KERMIT tape, there is a $100.00 reproduction fee which includes a 2400' reel of
magnetic tape, two printed manuals, various flyers, a box, and postage; there
is an additional $100.00 order processing charge if an invoice must be sent.
The tape includes all known versions of KERMIT, including sources and
documentation.

Commercial institutions may make unlimited internal use of KERMIT.  However,
a question raised with increasing frequency is whether a company may
incorporate KERMIT into its products.  A hardware vendor may wish to include
KERMIT with its standard software.  A software house may wish to incorporate
KERMIT protocol into its communications package, or to distribute it along with
some other product.  A timesharing vendor or dialup database may wish to
provide KERMIT for downloading.  All these uses of KERMIT are permissible, with
the following provisos:

. A KERMIT program may not be sold as a product in and of itself.  In addition
  to violating the prevailing spirit of sharing and cooperation, commercial
  sale of a product called "KERMIT" would violate the trade mark which is held
  on that name by Henson Associates, Inc., creators of The Muppet Show.

. Existing KERMIT programs and documentation may be included with hardware or
  other software as part of a standard package, provided the price of the
  hardware or software product is not raised significantly beyond costs of
  reproduction of the KERMIT component.

. KERMIT protocol may be included in a multi-protocol communication package as
  one of the communication options, or as a communication feature of some
  other kind of software package, in order to enhance the attractiveness of the
  package.  KERMIT protocol file transfer and management should not be the
  primary purpose of the package.  The price of the package should not be
  raised significantly because KERMIT was included, and the vendor's literature
  should make a statement to this effect.

. Credit for development of the KERMIT protocol should be given to the Columbia
  University Center for Computing Activities, and customers should be advised
  that KERMIT is available for many systems for only a nominal fee from
  Columbia and from various user group organizations, such as DECUS and SHARE.

Columbia University holds the copyright on the KERMIT protocol, and may grant
permission to any person or institution to develop a KERMIT program for any
particular system.  A commercial institution that intends to distribute KERMIT
under the conditions listed above should be aware that other implementations of
KERMIT for the same system may appear in the standard KERMIT distribution at
any time.  Columbia University encourages all developers of KERMIT software and
documentation to contribute their work back to Columbia for further
distribution.

Finally, Columbia University does not warrant in any way the KERMIT software
nor the accuracy of any related documentation, and neither the authors of any
KERMIT programs or documentation nor Columbia University acknowledge any
liability resulting from program or documentation errors.

These are general guidelines, not a legal document to be searched for
loopholes.  To date, KERMIT has been freely shared by all who have taken the
time to do work on it, and no formal legalities have proven necessary.  The
guidelines are designed to allow commercial enterprises to participate in the
promulgation of KERMIT without seriously violating the KERMIT user community's
trust that KERMIT will continue to spread and improve at no significant cost to
themeselves.  The guidelines are subject to change at any time, should more
formal detail prove necessary.

Commercial organizations wishing to provide KERMIT to their customers should
write a letter stating their plans and their agreement to comply with the
guidelines listed above.  The letter should be addressed to:


        KERMIT Distribution
        Columbia University Center for Computing Activities
        612 West 115th Street
        New York, NY  10025"


PCKERMIT KNOWN PROBLEMS (BEWARE FILE)
-------------------------------------
12/10/85
PCKERMIT V1.18:

MAXIMUM PACKET SIZE LIMITED TO 90

The maximum packet send packet size is limited to 90.  This was done
as a work-around to an undetermined problem in the code from Columbia
which caused errors on some packets when a maximum packet size of
94 was requested by the receiver.  Even if the receiver allows a max
packet size of 94 in the Send-Init exchange, PCKERMIT limits the actual
size of packets it sends out to 90.  I believe this is done in one of the
.H header files.


TIMEOUT AVOIDANCE HEURISTIC

An additional heuristic is being added to the Kermit Sliding Window Definition
to avoid unnecessary timeouts due to lost ACKs or NAKs.  This additional
heuristic has not been implemented in V1.16 of PCKERMIT.EXE.
The substance of the additional heuristic will be:

"An additional heuristic will prevent most timeouts due to lost ACKs
or NAKs.  The sender re-sends the earliest packet (the packet blocking the
window) if the following conditions are true:

   1. The Sender's window is blocked.
   2. The Retry Count for the earliest packet is zero.
   3. An ACK (or optionally also NAK) for any later packet has been received."


This heuristic takes advantage of the fact that ACKs and NAKs should
normally be received in order.  Receipt of a later ACK implies that the
earliest ACK was lost.  Therefore, we can anticipate that a timeout is
likely to occur and avoid it by resending (once) the packet blocking the
window.  The packet is only sent once (i.e. if the retry count is
zero) to avoid complicating error recovery.


SOURCE CODE COMPATIBILITY WITH OTHER COMPILERS

 1. There is a reportedly a bug in the Microsoft C Compiler which causes an
    error in the Kermit Type 3 (CRC-16) Checksum algorithm.  Beware!

 2. Lattice C allows nested comments, which are not allowed by the Microsoft
    C compiler.  Their may be some instances of nested comments.  LCKFNS3
    has at least one area that was commented out that results in a nested
    comment.

FILE RENAMING WHEN DUPLICATE FILE NAME IS RECEIVED

Long filenames can duplicate existing filenames because they are not
evaluated by PCKERMIT.  The long filename is sent to DOS, which truncates
it to the first FILENAME.EXT characters.

In general, renaming works for most standard MS-DOS files.  However, there
are some remaining bugs which reflect the UNIX origins of this code.
Developers may wish to take a close look at this area.

The addition of ~1, etc, after the filename is not ideal in the MS-DOS
environment because the extension is completely lost.  Often files are being
received with same root but different extensions. If they are updates, it
may take a while to sort things out.

This logic is implemented in LCKFIO.C in the routine ZNEWN.

SLIDING WINDOW DEFINITION
-------------------------

The Kermit sliding window extension is defined in the file KWINDOW5.DOC.
If the definition is unclear or ambiguous to you in any respect, please
contact Columbia University or Source Telecomputing at the address below.


SLIDING WINDOW KERMIT STANDARDIZATION
-------------------------------------

The Kermit Sliding Window Definition is still labeled experimental by
Columbia University in order to help iron out all problems before the
final definition is published and to aid in coordinating efforts on
sliding window Kermits.

For the time being, we suggest developers can help the standardization
process by testing their implementations with the following Kermits:

   PCKERMIT.EXE                                   (Sliding window Kermit)
   The Source                                     (Sliding window Kermit)
   MSKERMIT version 2.28 from Columbia University (Classic Kermit)



TCOMM BBS
---------

   A bulletin board at 301-428-7931 (data only 300/1200/2400) is
   providing informal support for sliding window Kermit.
   This is a Maryland number.


CORRECTIONS, QUESTIONS, COMMENTS
--------------------------------

Please send all corrections, questions and comments to:

    John Mulligan
    Source Telecomputing Corporation
    1616 Anderson Road
    McLean, VA 22102
    703-734-7500
    SourceMail: STC356

    Columbia University System Mail: We are OC.SOURCE on system CU20B.