The AGA Experience 2/agavol2.iso/software/utilities/comms/term/documentation/xpr_libs/xprkermit.doc

Text File | 1994-03-31 | 28KB | 554 lines

                              XPR Kermit
                             Version 2.36
                            March 14, 1993

                  Frank da Cruz - Columbia University
               Stephen R. Walton - Cal State Northridge

This is an implentation of an External Protocol (XPR) library for the
Kermit file transfer protocol.  In keeping with the Kermit documents,
here is a list of the items supported and not supported.

XPR Kermit Capabilities At A Glance:

  Local operation:                   Yes
  Remote operation:                  Yes
  Transfer text files:               Yes
  Transfer binary files:             Yes
  International text:                No
  Wildcard send:                     Yes, if supported by comm program
  File transfer interruption:        Yes
  Filename collision actions:        Yes
  Can time out:                      Yes
  8th-bit prefixing:                 Yes
  Repeat count prefixing:            Yes
  Alternate block checks:            Yes
  Automatic parity detection:        No
  Dynamic packet length:             Yes
  CONNECT mode:                      *
  Terminal emulation:                *
  Key mapping:                       *
  Communication settings:            *
  Transmit BREAK:                    *
  Support for dialout modems:        *
  TCP/IP support:                    *
  X.25 support:                      *
  IBM mainframe communication:       *
  Transaction logging:               No
  Session logging:                   No
  Debug logging:                     No
  Packet logging:                    No
  Act as server:                     No
  Talk to server:                    Yes
  Advanced server functions:         No
  Security for server:               No
  Local file management:             N/A
  Command/Init files:                N/A
  Long packets:                      Yes
  Sliding Windows:                   Yes
  File attributes packets:           Yes, but limited by XPR protocol
  Command macros:                    *
  Script programming language:       *
  Raw file transmit and capture:     *

The items marked with a '*' above are those which are to be provided by
the calling terminal emulation program.  Notice that, although XPR
Kermit itself cannot be a "Kermit server," often the communication
program's scripting capability will allow XPR Kermit to be used for the
unattended transfer of files between the Amiga and a remote machine.

I. Introduction
---------------

XPR Kermit implements the Kermit file transfer protocol in the form of
an Amiga External Protocol (XPR) library.  This allows the addition of
an up-to-date version of the Kermit protocol to any communications
program which supports the XPR specification.  For further information
on Kermit, read the book "Kermit:  A File Transfer Protocol" by Frank
da Cruz, 1986, Digital Press.

Please note that this document assumes you already have some
understanding of what the Kermit protocol is, and how to use it.  I
have tried to include a few hints about common problems, but there is
no substitute for obtaining and using a copy of the documentation for
the Kermit on the other system to which you will be talking.  In
addition, two commercial books are available.  "Kermit:  A File
Transfer Protocol" by Frank da Cruz describes the protocol in some
detail.  While aimed at those writing a Kermit program, it contains a
good deal of useful information about Kermit itself.  "C Kermit" by
Christine Gianone and Frank da Cruz, is a wealth of good introductory
information about any version of Kermit.  In addition, the latter book
is also the documentation for the standalone version of C Kermit which
is available for the Amiga.

The Kermit protocol, and XPR Kermit, are copyright by Columbia
University.  XPR Kermit is subject to the same restrictions as any
other version of Kermit.  In particular, XPR Kermit may be included as
part of a commercial package, provided the cost of said package is not
increased as a result.

I cannot resist saying a few words in support of Kermit.  Unlike many
other file transfer protocols such as the X/Y/ZMODEM family, the design
of the Kermit protocol started with the assumption that communication
lines are unreliable and quirky.  Kermit's slightly lower efficiency on
good lines is more than compensated for by the fact that it can often
successfully transfer files under conditions where other protocols
fail.  It can transfer binary files over a seven-bit-wide communication
line, or one which "eats" most control characters;  in fact, only two
binary characters, the start-of-packet and end-of-packet markers, need
be passed unchanged by the line.

II.  Installation
-----------------

To install XPR Kermit, simply copy the file "xprkermit.library" to your
LIBS: directory, and request your comm program to use XPRKERMIT as its
external file transfer protocol.

XPR Kermit supports Version 2.0 of the XPR Protocol specification.  For
more details on this, I recommend that you find a copy of the XPR
Zmodem library, version 2.0.  Its documentation contains a good deal of
the justification and philosophy of external protocol libraries, which
I won't repeat here.  Among the programs supporting the XPR
specification are the commercial programs A-Talk III and JRComm and the
free programs VLT, Term, and NComm.


III. Setting Options
--------------------

XPR Kermit supports the parts of the Kermit protocol outlined in the
table above.  There are currently nine user-settable parameters in XPR
Kermit, which cover the parameters which are most often necessary to
customize. If your communications problem is especially severe--for
example, your method of connection to another system swallows
characters which are special to Kermit, such as control-A--you may
need to get a copy of the stand-alone Kermit program, C Kermit for the
Amiga, distributed via many paths. The current version is 5A(189).

There are actually two sets of "setup" parameters in XPR Kermit.  The
first set are commands which XPR Kermit can send to a remote Kermit
server. These are not actually setups, but are in fact commands to XPR
Kermit which cause it to communicate with a remote Kermit server.  The
fourth command in this group is "Change Options," which causes no
communication.  Instead, you are requested for changes in the current
values of the parameters which Kermit will use for communication.

These items can be set in one of two ways.  One method is with a simple
character string which is sent to XPR Kermit by the comm program;  this
string will hereafter be referred to as the "init string."  This is
generally done if an environment variable named XPRKERMIT exists and
has a value, in which case XPR Kermit is sent the value when you first
select XPR Kermit as your protocol.  Some comm programs also allow an
initialization string to be sent in other ways, such as from a script;
VLT, for example, has an INITXPR script command.  The format of this
string is specified by the external protocol.

The second, more elegant method, is with some type of requester or set
of requesters.  In this case, you will be presented by your comm
program with a set of Intuition gadgets of some type which allow the
choice of XPR Kermit commands and the setting of the options.

However, the string method has the advantage of giving one the ability
to change external protocol settings non-interactively, such as from a
script. In the case of XPR Kermit, such a script can actually command
XPR Kermit to perform communication.  One obvious use of this is to
transfer an entire directory tree from your Amiga to a remote machine:
you can make the remote Kermit a server and command it to perform the
appropriate CD commands, then transfer files.

The currently supported XPR Kermit server commands are listed below.
The format of the init string is in parentheses, generally simply a
single letter.

    Kermit Finish (F):  Tells a Kermit server that you are done.  The
    remote server will stop being a server.

    Kermit Bye (B):  Tells a Kermit server that you are done;  the server
    will exit and log you off the remote machine.

    Kermit CD (C{dir}):  Change the default directory for files sent or
    received by the Kermit server.  Examples of the init string would
    be 'C/bin' or 'Cuser:[username.amiga]'.

For setting options via an init string, the first character of the init
string must be the letter O (for Options).  Following that letter can
be one or more of the option setting formats listed bellow;  these can
be separated by whitespace and/or commas.

There are three settings which are either "yes" or "no."  Your comm
program will give you some way of setting them interactively.  Simple
button gadgets will be labeled "yes" and "no;"  otherwise, you may see
a string gadget, into which you should type the word "yes" or "no" by
hand.  This string is case-insensitive.  In the init-string, "yes" is
represented by the single upper-case character Y.

    Convert FileName (C{Y|N}):  If "yes," then file names are
    converted from Amiga file names to a "least common denominator"
    form and back again.  On files which XPR Kermit sends, this
    means that any leading directory path is stripped, and the file
    name can consist of only upper case letters, numerals, and at
    most one period.  Lower case letters are translated to upper
    case, and non-alphanumeric characters, including extra periods,
    are translated to X.  Received file names are converted to
    lower case.  If "no," then none of these translations occur.
    NOTE:  This means that files will often be sent with a complete
    leading Amiga path name, and so you should make sure that you
    send files with the comm program's current directory set to the
    directory containing the file you're sending.  Default
    "yes."

    Host Server (G{Y|N}):  If "yes," then the host (remote) Kermit is
    assumed to be in server mode.  You will be prompted for file
    names when you request an XPR Kermit receive, and this file
    name will be sent to the server in the form of a Kermit GET
    command.  Default "no."

    Keep Incomplete (K{Y|N}) If "yes," then incomplete files will be
    kept.  An incomplete file can result from either an actual
    error in the transfer, or a user-requested cancellation of
    a transfer in process.  Default "no."

    Text File (T{Y|N}):  Flags whether the incoming file is text or binary.
    If "yes," then carriage-return/line-feed pairs in the incoming
    packets are converted to a single line-feed before writing the
    packet to a file, and the opposite conversion is made when a file
    is sent to a remote system.  Default "yes".

    If your communcations program supports its own text/binary flag
    (that is, if the xpr_finfo() function exists and can tell XPR
    Kermit whether a given file is text or binary), this option will
    not appear.  Also, it is possible using attribute packets for the
    sending Kermit to request switching from text to binary    and back
    again on a per-file basis.  XPR Kermit fully supports this.  It
    will switch if requested to by a sending Kermit.  When sending,
    XPR Kermit uses the xpr_finfo() function on a per-file basis.  The
    Amiga has no real way of determining whether a file is text or
    binary, however, so it is usually up to the user to choose the
    correct mode from a menu item or other setup in the comm
    program.

Numerical or alphabetic settings are as follows.  Here, the init string
key letter should be followed by a numerical or alphabetic value, as
indicated.

    Packet Length (P{length}):  The Long Packets extension to Kermit is
    fully supported. The longest possible packet is 9024;
    the default value is 94, the longest standard Kermit packet.

    Block Check (B{type}):  This can have the value of 1, 2, or 3, and
    chooses successively more stringent types of error checking on
    the incoming data:  6-bit checksum, 12-bit checksum, and 16-bit
    CRC, respectively.  Default is 1 (6-bit checksum).

    Timeout (O{seconds}):  The length of time the remote Kermit should wait
    for a packet from XPR Kermit before assuming it isn't coming. The
    default is 10 seconds.  See the extended discussion of timeouts
    below.
    (O is for Out, as in TimeOut;  T is already taken by the Text flag.)

     Retry Limit (R{number}):  The number of times XPR Kermit will attempt
    to send or receive the next packet of data before quitting.  Notice
    that if the remote end simply stops sending, a length of time equal
    to the retry limit times the timeout will elapse before XPR Kermit
    actually exits.  Default 5 retries.

     Window Size (W{number}):  The number of windows to use in the
    sliding window extension to the protocol.  This is the number
    of packets which XPR Kermit will send without waiting for an
    acknowledgement from the other end.  Default 1, meaning sliding
    windows are not used by default.

     File Name Collision action (N{X|A|D|R}):  What action to take if
    a received file has the same name as an already existing file.
    Each letter is a possible action, as follows:
    X - Replace.  Unconditionally replace the old file with the
    new one.
    A - Append.  Append the incoming file to the end of the old
    file.
    D - Discard. Refuse to accept the incoming file.
    R - Rename.  Rename the incoming file to a unique name by appending
    a tilde followed by a sequence number to its name.

    The default is Replace.

     Send Packet Size and Send Timeout (SPn and SOn):  These values
    override the ones requested by the Kermit at the other end for
    the packet size and timeout, respectively, for XPR Kermit to
    use when sending files to the other Kermit.  They should only
    be used if there is good reason to believe that the values
    requested by the other Kermit are not working well:  for
    example, that you know more about the connection than the other
    end does.  If these are zero, then the other end's requested
    packet size and timeout are used.  The default is zero.

Setting a packet length larger than 94 (the default) enters long packet
mode automatically.  If you use long packets, it is *strongly*
recommended that you use block check 2 or 3 if the host Kermit supports
them.  In addition, if binary files are to be transmitted, a higher
block check than 1 should be used as well.

As a practical matter, you will have better results transferring files
with relatively short packets and a larger number of windows, as
opposed to long packets and a small number of windows.  At 9600 baud, I
have found that 5 windows and 1000-byte packets keeps things humming
nicely.  Over a network link, the author of MS-DOS Kermit recommends 4
windows and 2000-byte packets as a good match to the packet sizes used
by the Internet itself.  You should also realize that in order for
sliding windows and/or long packets to be used, both ends must be told
to use them.  This means you must issue the commands "SET RECEIVE
PACKET-SIZE nnn" and "SET WINDOW nnn" to the remote Kermit before
using XPR Kermit to transfer files.

All of the above parameters, except the Send Overrides, correspond to
the numbers set in a typical standalone Kermit program via the SET
RECEIVE command. In the initial setup transaction for a Kermit file
transfer, these values are sent to the Kermit at the other end as a
request for it to use them when receiving packets from XPR Kermit.  The
values for block check, timeout, window size, and packet length which
XPR Kermit actually uses depend, in turn, on the ones requested by the
Kermit at the other end. The block check, packet size, and window size
used in the transaction will be the smaller of the values requested by
the other Kermit and the values set by you in the XPR Kermit
initialization.

Timeout settings are handled differently and are a bit confusing, I've
found. The timeout set via XPR Kermit's requester is the length of time
which XPR Kermit will request the other end to wait before assuming
that XPR Kermit has not responded. The length of time XPR Kermit should
wait for a packet from the remote end is requested by the remote end,
and is generally set by a SET RECEIVE TIMEOUT command typed by the user
to the remote Kermit. With long packets at low baud rates (say, 2048
bytes at 1200 baud), both these times should be long enough to ensure
an entire packet can be transferred in this time. The symptom if it is
too short is that each packet will be sent exactly twice.  The same
symptom can occur even if the connection between the remote Kermit and
XPR Kermit is fast but has long transmission delays;  this is often the
case when connected to a distant site via the Internet. If you have
problems such as these, try using the Send Overrides to change the
values which XPR Kermit uses when sending packets.

Options can be mixed and matched.  For instance, to talk to a Kermit
server with 750-byte packets, block check 2, keep incomplete files,
binary files, five windows, and a 10-second timeout, the init string
could be "OP750,B2,KY,TN,W5,O10".

III. Transferring Files
-----------------------

Once XPR Kermit is set up, transferring files is as simple as with any
of the protocols built in to your communication program.  Typically,
you will log into a remote computer, start up its Kermit program, and
issue the "send filename" or "receive" command to the remote Kermit.  A
message will be printed, something like "Escape back to your local
system and give a RECEIVE command" if you told the remote to send a
file.  Issue the Receive File command to your terminal program;
frequently, this is Right-Amiga-R.  Sit back and watch the file be
transferred.

The files received by XPR Kermit are placed in the comm program's idea
of its current directory;  that is, XPR Kermit asks the comm program to
create a file of the same name as the file on the sending system, but
leaves the directory in which the creation is to occur up to the comm
program.  For sending files, path information is stripped from the file
name before it is sent to the remote.

XPR Kermit supports multiple files on both send and receive.  Multiple
received files are handled by the sending Kermit.  One almost always
issues a wildcard send command, for example "send *.for" to send all
Fortran files.  For sending multiple files, XPR Kermit queries the
calling communication program for the names of the files to send, one
at a time.  Check your program documentation for its method of
supporting this.  Two common possibilities are simply the ability to
type a wildcard into a string requester specifying the files to send,
and being able to check multiple files in a list on a file requester.

If the "Host is Server" flag is set on the XPR Kermit options, it is
assumed that you started the remote Kermit and issued the "SERVER"
command to it.  When a remote Kermit is a server, it accepts incoming
requests of a special format about which file to send.  On a
command-line oriented version of Kermit, the command "GET filename"
would be typed to the local Kermit, which would request the remote
Kermit server to send that file.

XPR Kermit uses the protocol behind the Kermit GET command as well.  If
the comm program sends XPR Kermit the name of a file or files to GET,
for example from a script command, then that filename is used.  In the
case of VLT, for example, the script command 'XPR RECEIVE "file"' will
result in the file named "file" being used in XPR Kermit's GET command,
provided the "Host is Server" flag is set. If no file name is sent to
XPR Kermit by the comm program in this manner, the file or files to GET
is requested interactively by XPR Kermit through the comm program. This
will almost always happen when you issue an interactive "Receive File"
command to the comm program. A string requester is almost always used
here to prompt for the files to receive.  Note that this should be in
the format of the *remote* system, not the Amiga. This is important for
wildcards; SENDing a batch of Amiga files will generally use AmigaDOS
wildcards (#?.for for all Fortran files), while a Unix, VAX/VMS, or
MS/DOS system would use *.for for the same operation.

Most comm programs supply a nice status display, which XPR Kermit will
update regularly to keep the user apprised of the transfer's progress.
The name of the sent or received file will be shown.  If file name
conversion is on, the converted name will appear after the word "as;"
for example, 'Sending S:Startup-Sequence as STARTUPXSEQUENCE.'  The
current packet count, packet length, packet type, timeout count, error
count, number of file bytes transferred, elapsed time, and estimated
total time are all updated after each attempt to transfer file data,
whether the attempt is successful or not.  After the transfer
completes, the total number of files, number of file bytes, elapsed
time, and character-per-second (cps) transfer rate will be shown.

XPR Kermit supports three levels of transfer abort, out of the 33 which
can be part of an XPR-supporting comm program.  The lowest level of an
XPR abort is treated by XPR Kermit as a file abort, meaning that, if a
batch transfer is in effect, the current file's transfer is interrupted
but the protocol proceeds with the next file.  This is most useful in a
wildcard transfer, where the wildcard matches a long file which you
don't actually want transferred. The next higher level is treated as a
batch abort, meaning that all files are cancelled.  Both of these
aborts happen in a "graceful" way, which will not generally result in
the remote Kermit exiting with an error status.  The highest level XPR
Kermit abort, which is all many programs provide, is treated as an
immediate stop-dead.  An error packet containing the string "User
cancelled." is sent to the remote Kermit, the same message is echoed on
the comm program status display, and XPR Kermit exits.  In addition, if
the "Keep Incomplete Files" flag is OFF, the most recently received
file will be deleted, if the cancelled transfer was a receive.

IV.  Credits
------------

The following people had a hand in this code.  In chronological order,
they are:

-- Frank DaCruz of Columbia University, who deserves most of the credit
   here.  The system-independent code in  the ckcfn?.c files is his,
   and XPR Kermit is really just an interface to these files, which are
   identical to the ones used in every other C language implementation
   of Kermit.
-- Marco Papa of Felsina Software, for the first beta XPR version
-- Steve Walton, for second and subsequent XPR Kermit's.

Other acknowledgements go to Willy Langeveld for developing the XPR
spec, and to Rick Huebner, several of whose ideas in XPR Zmodem were
taken over into XPR Kermit by Steve Walton. Thank you all!

V.  Gripes
----------

The current author and babysitter of this code is:

    Stephen Walton
    Department of Physics and Astronomy
    Cal State Northridge
    18111 Nordhoff St.
    Northridge, CA 91330 USA
    [phone]

E-mail can go to:
    [e-mail] (Internet)

Thanks and congratulations gratefully accepted;  bug fixes and enhancements
even more so!

VII.  Changes
-------------

The following changes and improvements have been made to XPR Kermit since
the release of version 1.111:

1.  Attribute packets, file name collision handling, and sliding
windows are all new in this version.

2.  The system-independent C Kermit code is now used.  This means that,
absent changes in the system-dependent routines required, XPR Kermit
will automatically share in any improvements made to its big sister, C
Kermit 5A(189).

3.  The file transfer display code has been completely rewritten.  This
was only possible because C Kermit already contains a system-dependent
screen() function specification, which describes how to update the file
transfer status display.  In fact, the screen() function in XPR Kermit
is largely copied from the screenc() function in the Unix and Amiga
versions of C Kermit.

The following improvements were made between version 1.5, the first
release of XPR Kermit, and the second release, version 1.111.

1. The library is now re-entrant.  This re-entrancy uses a bit of a "trick"
   which depends on the mechanism used by Manx Aztec C to set up small
   model programs.  I have successfully run two simultaneous file
   transfers in XPR Kermit.

2. The timeout code has been improved;  in fact, it appears that it may
   not have worked at all in version 1.5.

3. Block check type 2 did not work in version 1.5.

3. A buffer overflow which could trash the high byte of an address on
   an Amiga 3000 or other 68030-based machine was fixed.  This would
   only be seen, normally, when sending a file with many repeated
   characters.

4. The "Keep incomplete file" feature is new.

5. The file status display has been cleaned up somewhat;  in particular,
   the previous file's final display should no longer show up when a
   new transfer is started.  Timeouts are now counted separately from
   other errors.

6. Local buffers (that is, within XPR Kermit) have been added for both file
   and communication line I/O.  This substantially reduces the number of
   callbacks between XPR Kermit and the comm program, improving performance
   under heavy multitasking. [Note added 3 Dec 1991:  an actual trial
   on the local buffer for serial I/O indicated *worse* performance, so
   the code is only compiled if the symbol MYREAD is #define'd in
   kermitproto.c.  This is not the case in the distributed binary.]

7. xpr_chkmisc() and xpr_chkabort() are now called properly.


VI.  BUGS AND LIMITATIONS
-------------------------

The file transfer cancellation button doesn't seem to work in Olaf
Barthel's Term 3.2.  I have sent him e-mail about it.

The XPR protocol does not allow for the XPR to rename existing files.
If it did, a "backup" option for file name collision detection would be
possible. In this case, if an existing file has the same name as a
received file, the existing file is renamed to a unique name and the
received file is stored under its own name.  This is my personal
preferred option, and is the default action with C Kermit.

The XPR protocol also does not allow one to find or set the
modification date of a file.  If it did, then several additional
features would become possible.  One would be  an "Update" option for
filename collision, which would replace the existing file but only if
the incoming file was newer.  XPR Kermit could also tell the receiving
Kermit the modification date of a sent file, and set the modification
date of a received file to agree with that on the sending system.

XPR Kermit is the largest of the XPR libraries, by a factor of three.
Because of this size, I have chosen not to implement one of the other
major improvements of the most recent version of the Kermit protocol,
namely support for international character sets.  If you need this
feature, for example if you regularly transfer text files between
machines in different countries, I recommend setting XPR Kermit to
binary mode and setting the sending Kermit to use "ISO Latin-1" as its
transfer character set.  Since the file character set of the Amiga is
ISO Latin-1, this should result in a file transfer with all
international characters intact, at the cost of a carriage return/line
feed pair at the end of each text line, which can be trimmed after the
file transfer.  If the remote system is a Unix system, or another
Amiga, a binary-to-binary transfer of text files should work also.

XPR Kermit uses more memory than is strictly necessary, because both
read-only and read-write data are copied for each comm program using
XPR Kermit.  However, all file and communication buffers are allocated
when needed, so this is not as important as it might first seem.  If
international character sets were implemented, the large translation
tables required would probably require an extensive rewrite of XPR
Kermit to keep its memory usage reasonable.