PCKERMIT.HLP                                            Jan. 16, 1985

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

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

Introduction
------------

PCKERMIT version 1.18 is the first implementation of the "Sliding Window
Extension" to Kermit (the extension is popularly called SuperKermit).  This
extension allows data packets to be sent continuosly under most conditions,
unlike "Kermit Classic" or XMODEM, both of which must wait for the other
side to return an acknowledgment after each data packet has been sent.

This continuous transmission of data is especially helpful when there are
delays in the communications path, such as via satelite transmission or
over the public data networks (Telenet, Uninet, Tymnet, etc).


NOT A TERMINAL PROGRAM
----------------------

PCKERMIT.EXE is not a terminal program.  It simply implements the Kermit
protocol, including the sliding window extension.  It will work with
older "Kermit Classic" implemenations as well, via automatic negotiation
between the two Kermit programs.

PCKERMIT.EXE 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.


USE OF PCKERMIT.EXE
-------------------

PCKERMIT does not establish a carrier with a remote system.  The connection
must be established using a separate terminal program, and the remote
Kermit selected using the separate terminal program.

Then you return to the MSDOS prompt and start PCKERMIT for the actual file
transfer.

Here is a sample transfer taken from my screen, receiving a file using
parity of mark.  (The file was being sent from The Source.)

---------------Start of example------------------

{On The Source}

-> kermit -s l-steve.txt               {send me the file "l-steve.txt"}
Kermit send started

{Exit from my terminal package to MS-DOS}

A:\>PCKERMIT -P M -R
NSF
L-STEVE.TXT => L-STEVE.TXT
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: A
File creation date: 12/18/85 - 14:17:16

File size (bytes): 1132
....Z [OK]B                            {Dots .... are put up for every 4th
                                        packet received.  Z indicates the
                                        end-of-file packet.  [OK] means the
                                        file was received and written to
                                        disk OK.  B indicates the end-of-
                                        batch packet, the conclusion of the
                                        transfer}

A:\>                                   {Back to MSDOS}

{Start my terminal program again}


---------------End of example--------------------


The command syntax of the stand-alone Kermit program is shown in Figure 1.
Here are examples of execution from the DOS command line:

PCKERMIT
   or
PCKERMIT -H               Help: Will give you the screen of figure 1 below

PCKERMIT -R               Receive: Will receive a file using the PCKERMIT
                          defaults of 1200 baud, parity none, on COM1.

PCKERMIT -S FILENAME.EXT  Send: Will send a file using the PCKERMIT
                          defaults of 1200 baud, parity none, on COM1.


PCKERMIT -R -P M          Receive: Will receive a file using Parity Mark


PCKERMIT -L COM2 -B 2400 -P M -R

                          This will use serial line COM2 at 2400 baud and
                          parity of mark to receive a file.

Upper or lower case does not matter; neither does the order of the options
(i.e., PCKERMIT -R -P M  will do the same thing as PCKERMIT -P M -R)



--------------Start of Figure 1-------------------------------------------

Figure 1. PCKERMIT command syntax.

  PCKERMIT version 1.18, December 10, 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


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

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


--------------End of Figure 1---------------------------------------------



USE OF BATCH FILES
------------------

Two small batch files can greatly simplify use of PCKERMIT:


SEND.BAT would look like this using Mark parity at 1200 baud on COM1:

PCKERMIT -P M -S %1


REC.BAT would look like this using Mark parity at 1200 baud on COM1:

PCKERMIT -P M -R

This makes it easy to send a file by just typing

SEND filename.ext

and receive a file by typing

REC

at the MSDOS prompt.  Change the PCKERMIT command line to reflect your
communications setup (add -B 300 for 300 baud, etc.).

You could include the name of your terminal software at the end of the
batch file so you went directly back to your terminal software when
finished with the transfer.


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 channel 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.


FILE RENAMING
-------------

PCKERMIT will rename received files to avoid conflicting with an existing
file. (If you wish to overwrite files of the same name, use the -W option
on the command line.)

The first duplicate filename received is renamed to with a .~1 extension,
then .~2  and so on.

The addition of ~1, etc, after the filename is not ideal 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.


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:                      ???
  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



PCKERMIT KNOWN PROBLEMS (BEWARE FILE)
-------------------------------------

PCKERMIT version 1.18
1. 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.

2. COMM port parameters possibly not returned to previous state:

The commercial comm library used in creating this program reportedly
contains a bug which may cause PCKERMIT to leave the comm port in a
different state than it found it.  This is not a problem when using
PCKERMIT from the MSDOS prompt.  However, if you call PCKERMIT from
WITHIN a terminal package, when you RETURN to the terminal package from
PCKERMIT the serial port may not be set the way that terminal package
expects.  This is unconfirmed.  You may wish to always run version 1.18 from
DOS until this problem can be verified, and if needed corrected.


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 more information, send SourceMail to STC356 on The Source.


PCKERMIT.DOC
------------

PCKERMIT was created to be used by developers to aid them in implementing
KERMIT and the new, faster "Sliding Window Kermit".  Complete documentation
for developers is in the file PCKERMIT.DOC.


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"
