Grafik-CD/Grafik-CD.iso/libs/xprkermit.doc

Text File | 1994-03-30 | 18KB | 381 lines

                              XPR Kermit
                         Version 1.111 - RELEASE
                           December 21, 1991

                     Marco Papa - Felsina Software
                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:                  No
  Login scripts:                     *
  Transfer text files:               Yes
  Transfer binary files:             Yes
  Wildcard send:                     Yes
  File transfer interruption:        Yes
  Filename collision avoidance:      No
  Can time out:                      Yes
  8th-bit prefixing:                 Yes
  Repeat count prefixing:            Yes
  Alternate block checks:            Yes
  Terminal emulation:                *
  Communication settings:            Yes
  Transmit BREAK:                    *
  Support for dialout modems:        *
  IBM mainframe communication:       *
  Transaction logging:               No
  Session logging (raw download):    No
  Debug logging:                     No
  Packet logging:                    No
  Act as server:                     No
  Talk to server:                    Yes
  Advanced server functions:         No
  Local file management:             *
  Command/Init files:                *
  UUCP and multiuser line locking:   *
  Long packets:                      Yes
  Sliding Windows:                   No
  File attributes packets:           No
  Command macros:                    *
  Raw file transmit:                 *

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

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.

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.  "MS-DOS Kermit"
by Christine Gianone is, despite its title, a wealth of good
introductory information about any version of Kermit.

II. Setting Options
-------------------

XPR Kermit supports the parts of the Kermit protocol outlined in the table
above.  There are currently seven 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 '#' or '&'--you may need to get a copy of the stand-alone
Kermit program, C Kermit for the Amiga, distributed via many paths.

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's
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 incoming file names are
    converted to a form acceptable to the Amiga.  Currently, this
    means simply translating them to lower case.  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.

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

    Packet Length (P{length}):  The Long Packets extension to Kermit is
    fully supported. The current limit is 2048 for XPR Kermit;
    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.
    (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.

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.

Timeout settings are a bit confusing, I've found. The timeout set via
XPR Kermit's requester is what standalone Kermit programs normally call
the "receive timeout," and is the length of time which XPR Kermit will
request the other end to wait before assuming that XPR Kermit is not
sending any response to the most recently sent packet.  The "send
timeout" is the length of time XPR Kermit should wait for a packet from
the remote end and is requested by the remote end. It is generally set
at that end by a "set send timeout" command. 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.

These 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, and a 10-second timeout, the init string could be
"OP750,B2,KY,TN,O10".  Cryptic, but usable.

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.  This modifies XPR Kermit's behavior on receiving files.
Since you can no longer tell the remote host which files to send, XPR
Kermit uses the Kermit GET command instead.  The file to GET is
requested by the comm program when you issue a "Receive File" command.
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.

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. Future Extensions
----------------------

This is probably the last release of XPR Kermit in its current form. At
some future point, XPR Kermit will, I hope, become an interface to
Columbia University's C Kermit code.  This will allow XPR Kermit to
always contain the latest version of the Kermit protocol, provided that
I or someone writes the required machine-dependent functions. Among
other things, such a rewrite would automatically include both the
sliding windows and attribute packets extensions to the Kermit protocol
into XPR Kermit, since they are in the current version of C Kermit.

Incidentally, I (Stephen Walton) am the co-supporter of C Kermit for
the Amiga.  As of this writing, version 5A of this program is in alpha
test.

V.  Other information
----------------------

The file "kermitproto.doc" describes the code contained in the file
"kermitproto.w," which actually implements the Kermit protocol.  It is
somewhat out of data, and "kermitproto.w" is pretty XPR Kermit-specific
at this point (it was originally intended as a small, stand-alone
Kermit implementation in C).

VI.  Credits
-----------

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

-- Frank DaCruz of Columbia University, who wrote the original code and
   published it in his book.
-- Steve Walton of Cal State Northridge, who got Frank's code actually
   working in the form of the original "kermitproto.w" module.
-- 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!

VI.  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.5:

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 library.]

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