home *** CD-ROM | disk | FTP | other *** search
/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / BEEHIVE / COMMS / SEALINK.ARC / SEALINK.DOC < prev   
Text File  |  1988-05-23  |  11KB  |  246 lines
  1.                                      SEALINK
  2.  
  3.                              File Transfer Protocol
  4.  
  5.                                 5 September 1986
  6.  
  7.  
  8.  
  9.                (C) COPYRIGHT 1986 by System Enhancement Associates
  10.  
  11.  
  12.  
  13.      This document describes briefly the  SEAlink  file  transfer  protocol
  14.      developers' package.  SEAlink is a sliding  window  protocol  that  is
  15.      fully  backwards compatible with XMODEM in all tested implementations.
  16.  
  17.      The intent of SEAlink is to provide a file transfer protocol that does
  18.      not  suffer  from  propagation  delays,  such  as  are  introduced  by
  19.      satellite relays or packet switched  networks.  Actual  tests  of  the
  20.      enclosed  routines  has  shown  that  SEAlink  is capable of virtually
  21.      eliminating propagation delays and turnaround delays.  File  transfers
  22.      between New Jersey and Hawaii,  which normally suffer a degradation of
  23.      50% or more  due  to  satellite  relays,  proceed  as  fast  as  local
  24.      transfers.  Even transfers within the local exchange are speeded up by
  25.      up to 20% at 2400 baud by the elimination of turnaround delays.  Large
  26.      volume  tests  show  that SEAlink is capable of coming to within 2% of
  27.      the theoretical minimum time for data transfer.
  28.  
  29.  
  30.  
  31.      The developers' package contains the following files:
  32.  
  33.          SEALINK.DOC         This document.
  34.          SEALINK.C           A set of C routines for implementing SEAlink.
  35.          DTTY.EXE            A sample TTY program that implements SEAlink.
  36.  
  37.  
  38.  
  39.      You are granted a license to use this code in your  programs,  and  to
  40.      adapt  it to your particular situation and needs,  subject only to the
  41.      following conditions:
  42.  
  43.      1) You must refer to it as the SEAlink protocol,  and  you  must  give
  44.         credit to System Enhancement Associates.
  45.  
  46.      2) If  you  modify  it in such a way that your version cannot converse
  47.         with the original code as supplied by us,  then you should refer to
  48.         it as "SEAlink derived",  or as a "variation of SEAlink",  or words
  49.         to that effect.
  50.  
  51.      In short,  we're not asking for any money,  but we'd like to get  some
  52.      credit for our work.
  53.  
  54.  
  55.  
  56.      This  document  is  not  meant  to  be  a  rigorous  definition of the
  57.      protocol.  The code provided should serve to document the details  and
  58.      fine  points  of  implementing SEAlink.  We will,  however,  present a
  59.      brief synopsis of how SEAlink adds sliding windows to XMODEM,  and why
  60.      XMODEM doesn't mind.
  61.  
  62.      First of all,  SEAlink adds a block number to the ACK and NAK used  in
  63.      XMODEM.*  We  thus  create  "ACK/NAK  packets",   with  the  following
  64.      structure:
  65.  
  66.          Byte 0:   ACK, NAK, or C
  67.          Byte 1:   Block number
  68.          Byte 2:   One's compliment of block number
  69.  
  70.      This is identical in form to the first three bytes of a  data  packet,
  71.      except that the SOH has been replaced with an ACK or NAK.**
  72.  
  73.      From the receiver's point of view,  it does not matter if  the  trans-
  74.      mitter  is using sliding window or not.  The receiver simply sends ACK
  75.      and NAK packets as appropriate.  Any XMODEM driver tested to date will
  76.      simply ignore this excess data behind the ACK or NAK.
  77.  
  78.      From the transmitter's point of view,  it just barely matters  if  the
  79.      receiver can handle sliding window.  The transmitter always acts as if
  80.      it  is  sending sliding window,  but varies the window size.  If it is
  81.      seeing valid block numbers and check values behind the  received  ACKs
  82.      and NAKs, then it sets the window size to four blocks.  Otherwise,  it
  83.      sets  the window size to one block.  The result is that it only "sends
  84.      ahead" if the receiver can handle it.
  85.  
  86.      It  should  be  a fairly simple matter to apply the underlying SEAlink
  87.      logic to almost any variant of XMODEM.
  88.  
  89.  
  90.  
  91.      The  SEAlink  routines  provided  in  this package are also capable of
  92.      passing system dependent information,  such as true file size and time
  93.      of  last modification.  This data is passed in a special header block.
  94.      The header block looks exactly like any other block, except that it is
  95.      block number zero.
  96.  
  97.      This is still backwards compatible with XMODEM,  as a SEAlink receiver
  98.      does  not  mind if block zero is missing,  and any XMODEM receiver yet
  99.      tested will regard block zero as a duplicate block and ACK it.
  100.  
  101.      The data portion of block zero contains the following fields:
  102.  
  103.          ______    ____      ________
  104.          Offset    Size      Contents
  105.  
  106.             0        4       Original file length.
  107.             4        4       Date  and  time  file  was  last mofified,  in
  108.                              seconds since 1979.
  109.             8       17       Original  file  name,  as  a  null  terminated
  110.                              string.
  111.            25       15       Name  of  transmitting  program,   as  a  null
  112.                              terminated string.
  113.            40       88       Null filler and expansion area.
  114.  
  115.      Any field which the transmitter cannot support should be  set  to  all
  116.      zeros.  Conversly,  the  receiver  should ignore any null fields.  The
  117.      receiver may ignore any field which he cannot support.
  118.  
  119.       * XMODEM/CRC uses a "C" in place of  a  NAK  to  indicate  CRC  error
  120.         detection.  SEAlink  follows  this convention,  and supports either
  121.         checksum or CRC.  For brevity,  this document will use the term NAK
  122.         to mean either a true NAK (hex 15) or a C (hex 43).
  123.      ** See previous footnote.
  124.  
  125.  
  126.      The  routines  enclosed  in  this package should be reasonably easy to
  127.      implement in your application.  We have attempted to exclude  compiler
  128.      dependent and system dependent logic from these routines.
  129.  
  130.      You will need to alter our references to our communications driver  to
  131.      conform  to  your  own driver.  The communications related routines we
  132.      use are:
  133.  
  134.          com_putc(c)         Output character c to comm port.
  135.  
  136.          int com_getc(t)     Get character from comm port within  t  tenths
  137.                              of   a  second.   Return  EOF  if  time  limit
  138.                              expires.
  139.  
  140.          com_dump()          Discard any pending output without sending it.
  141.  
  142.      In  addition,  we  use  the  following  routines for controlling timed
  143.      loops:
  144.  
  145.          long timerset(t)    Set a timer.  Returns a timer value which will
  146.                              expire in t tenths of a second.
  147.  
  148.          int timeup(z)       Check a timer.  Returns true if  timer  z  has
  149.                              expired yet, or false otherwise.
  150.  
  151.  
  152.  
  153.      The SEAlink  implementation  provided  in  this  package  is  used  by
  154.      invoking the two primary routines:
  155.  
  156.          int xmtfile(name)             /* transmit a file */
  157.          char *name;                   /* name of file to transmit */
  158.  
  159.      This  routine is used to send a file.  One file is sent at a time.  If
  160.      the name is blank (name is null or *name points to a null),  then only
  161.      an end of transmission marker is sent.
  162.  
  163.      This routine returns a one if the file is successfully transmitted, or
  164.      a zero if a fatal error occurs.
  165.  
  166.          char *rcvfile(name)           /* receive a file */
  167.          char *name;                   /* name of file (optional) */
  168.  
  169.      This  routine  is  used to receive a file.  One file is received.  The
  170.      name, if given, takes precedence and will be the name of the resulting
  171.      file.  If the name is blank (name is null or *name points to a  null),
  172.      then  the  name  given by the transmitter is used.  If the transmitter
  173.      does not give a name, then a default name is used.
  174.  
  175.      This routine returns a pointer to  the  name  of  the  file  that  was
  176.      received.  If the file transfer is not successful, then a null pointer
  177.      is returned.
  178.  
  179.      The  pointer  returned  by  rcvfile()  points to a static data buffer.
  180.      This does not have to be freed (and should not be),  but  it  will  be
  181.      overwritten the next time rcvfile() is called.
  182.  
  183.      The  rcvfile()  function  works  on a temporary file whose name is the
  184.      same as the final file,  but with a dash ("-") added at the beginning.
  185.      If  a  file  transfer  is  aborted,  then  this temporary file will be
  186.      retained.  An aborted file transfer will not harm a pre-existing  file
  187.      of the same name.
  188.  
  189.  
  190.  
  191.      These  routines  can  be  used  for  either  single  or  multiple file
  192.      transfers.
  193.  
  194.      To send multiple files,  send each one one at a time  until  either  a
  195.      transmit  fails  or  all files are sent.  If all files are sent,  then
  196.      signal the end by calling xmtfile() with a null pointer.
  197.  
  198.      To receive multiple files,  call rcvfile() repeatedly until it returns
  199.      a null pointer.
  200.  
  201.  
  202.  
  203.      This  package  includes a demonstration program named DTTY (pronounced
  204.      "DEE tee"),  which is a simple TTY  program  for  doing  SEAlink  file
  205.      transfers.  DTTY  does  not  perform  any  sort  of terminal emulation
  206.      whatsoever.  Press  the  "ESCape"  key to give a command to DTTY.  The
  207.      command "?" (question mark) instructs DTTY to tell you  what  commands
  208.      she understands.
  209.  
  210.      For reasons of personal convenience, DTTY starts up looking for SEAdog
  211.      configuration files.  If you do not  have  SEAdog  installed  on  your
  212.      system,  then all you need do is create a skeleton configuration file.
  213.      This is a file named CONFIG.DOG,  which is a normal  ASCII  file.  For
  214.      purposes  of  making  DTTY happy,  all you need in this file is a BAUD
  215.      statement, like this:
  216.  
  217.          BAUD <maxbaud>
  218.  
  219.      where <maxbaud> is the maximum baud rate which your modem can  handle.
  220.      For example, if you have a 2400 baud modem, your CONFIG.DOG file would
  221.      contain the statement:
  222.  
  223.          BAUD 2400
  224.  
  225.      You cannot use the "C" (Call) command unless you have SEAdog installed
  226.      on your system.  If you do,  then "C" will get DTTY to ask you who you
  227.      wish to call.  You may enter anything that you  would  normally  enter
  228.      when  telling  SEAdog  where to send a message.  If you enter multiple
  229.      addresses,  then they will be called in rotation until  a  carrier  is
  230.      detected.
  231.  
  232.  
  233.  
  234.  
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.  
  242.  
  243.  
  244.  
  245.  
  246.