home *** CD-ROM | disk | FTP | other *** search
/ Power Programming / powerprogramming1994.iso / progtool / modem / clink120.arc / SEALINK.DOC < prev   
Text File  |  1987-08-24  |  14KB  |  361 lines

  1.                                      SEALINK
  2.  
  3.                              File Transfer Protocol
  4.  
  5.                                  August 24, 1987
  6.  
  7.  
  8.  
  9.             Copyright 1986,87 by System Enhancement Associates, Inc.
  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,  while  retaining  full
  20.      compatibility with XMODEM.  Unlike other high-speed protocols, SEAlink
  21.      does not "side step" to avoid using XMODEM,  but instead works with an
  22.      XMODEM driver to establish the fastest possible  link,  thus  reducing
  23.      startup delays in both SEAlink and XMODEM transfers.
  24.  
  25.      Actual  tests  of  the  enclosed  routines  has  shown that SEAlink is
  26.      capable of virtually eliminating  propagation  delays  and  turnaround
  27.      delays.  File transfers between New Jersey and Hawaii,  which normally
  28.      suffer a degradation of 50% or more due to satellite  relays,  proceed
  29.      as  fast as local transfers.  Even transfers within the local exchange
  30.      are speeded up by up to  20%  at  2400  baud  by  the  elimination  of
  31.      turnaround delays.  Large volume tests show that SEAlink is capable of
  32.      coming to within 2% of the theoretical minimum time for data transfer.
  33.  
  34.  
  35.  
  36.      The developers' package contains the following files:
  37.  
  38.          SEALINK.DOC    This document.
  39.          SEALINK.C      A set of C routines for implementing SEAlink.
  40.          CLINK.EXE      A sample TTY program that implements SEAlink.
  41.  
  42.  
  43.  
  44.      You are granted a license to use this code in your  programs,  and  to
  45.      adapt  it to your particular situation and needs,  subject only to the
  46.      following conditions:
  47.  
  48.       1) You  must  refer to it as the SEAlink protocol,  and you must give
  49.          credit to System Enhancement Associates.
  50.  
  51.       2) If you modify it in such a way that your version  cannot  converse
  52.          with the original code as supplied by us, then you should refer to
  53.          it as "SEAlink derived", or as a "variation of SEAlink",  or words
  54.          to that effect.
  55.  
  56.      In  short,  we're not asking for any money,  but we'd like to get some
  57.      credit for our work.
  58.  
  59.  
  60.  
  61.      This document is  not  meant  to  be  a  rigorous  definition  of  the
  62.      protocol.  The  code provided should serve to document the details and
  63.      fine points of implementing  SEAlink.  We  will,  however,  present  a
  64.      brief synopsis of how SEAlink adds sliding windows to XMODEM,  and why
  65.      XMODEM doesn't mind.
  66.  
  67.      First of all,  SEAlink adds a block number to the ACK and NAK used  in
  68.      XMODEM.(1)  We  thus  create  "ACK/NAK  packets",  with  the following
  69.      structure:
  70.  
  71.          Byte 0:   ACK, NAK, or C
  72.          Byte 1:   Block number
  73.          Byte 2:   One's compliment of block number
  74.  
  75.      This is identical in form to the first three bytes of a  data  packet,
  76.      except that the SOH has been replaced with an ACK or NAK.(2)
  77.  
  78.      From  the  receiver's point of view,  it does not matter if the trans-
  79.      mitter is using sliding window or not.  The receiver simply sends  ACK
  80.      and NAK packets as appropriate.  Any XMODEM driver tested to date will
  81.      simply ignore this excess data behind the ACK or NAK.
  82.  
  83.      From  the  transmitter's point of view,  it just barely matters if the
  84.      receiver can handle sliding window.  The transmitter always acts as if
  85.      it is sending sliding window,  but varies the window size.  If  it  is
  86.      seeing  valid  block numbers and check values behind the received ACKs
  87.      and NAKs,  it sets the window size to six blocks.  Otherwise,  it sets
  88.      the  window  size  to  one  block.  The  result is that it only "sends
  89.      ahead" if the receiver can handle it.
  90.  
  91.      It should be a fairly simple matter to apply  the  underlying  SEAlink
  92.      logic to almost any variant of XMODEM.
  93.  
  94.  
  95.      The  SEAlink  routines  provided  in  this package are also capable of
  96.      passing system dependent information,  such as true file size and time
  97.      of  last modification.  This data is passed in a special header block.
  98.      The header block looks exactly like any other block, except that it is
  99.      block number zero.
  100.  
  101.      This is still backwards compatible with XMODEM,  as a SEAlink receiver
  102.      does  not  mind if block zero is missing,  and any XMODEM receiver yet
  103.      tested will regard block zero as a duplicate block and ACK it.
  104.  
  105.  
  106.  
  107.  
  108.  
  109.  
  110.  
  111.  
  112.  
  113.  
  114.  
  115.  
  116.      (1) XMODEM/CRC uses a "C" in place of a  NAK  to  indicate  CRC  error
  117.          detection.  SEAlink  follows this convention,  and supports either
  118.          checksum or CRC.  For brevity, this document will use the term NAK
  119.          to mean either a true NAK (hex 15) or a C (hex 43).
  120.      (2) See previous footnote.
  121.      The data portion of block zero contains the following fields:
  122.  
  123.  
  124.          Offset    Size      Contents
  125.          ======    ====      ========
  126.  
  127.             0        4       Original file length.
  128.             4        4       Date and  time  file  was  last  mofified,  in
  129.                              seconds since 1979.
  130.             8       17       Original  file  name,  as  a  null  terminated
  131.                              string.
  132.            25       15       Name  of  transmitting  program,   as  a  null
  133.                              terminated string.
  134.            40        1       Overdrive flag.
  135.            41       87       Null filler and expansion area.
  136.  
  137.  
  138.      Any  field  which  the transmitter cannot support should be set to all
  139.      zeros.  Conversly,  the receiver should ignore any  null  fields.  The
  140.      receiver may ignore any field which he cannot support.
  141.  
  142.      Of special interest is the byte flag at offset 40 in block zero.  This
  143.      is  the  "Overdrive  flag",  and is used to trigger streaming mode for
  144.      high-speed,  half duplex modems.  In Overdrive mode the receiver stops
  145.      sending  ACKs  for  the  bulk of the file transfer,  thus facilitating
  146.      transfers over a half-duplex connection.  Overdrive is never  required
  147.      over a full duplex connection.  Overdrive requires that the basic link
  148.      be effectively error free.
  149.  
  150.      Overdrive is disengaged in either of the following conditions:
  151.  
  152.        o  The  transmitter will disengaged overdrive if it detects that the
  153.           receiver has dropped  out  of  overdrive,  or  does  not  support
  154.           overdrive.
  155.  
  156.        o  The   receiver  will  disengage  overdrive  if  it  finds  itself
  157.           receiving  an  excessive  number  of  bad  blocks,  as  Overdrive
  158.           requires an error-free link.
  159.  
  160.  
  161.  
  162.      The  routines  enclosed  in  this package should be reasonably easy to
  163.      implement in your application.  We have attempted to exclude  compiler
  164.      dependent and system dependent logic from these routines.
  165.  
  166.  
  167.      You  will need to alter our references to our communications driver to
  168.      conform to your own driver.  The communications  related  routines  we
  169.      use are:
  170.  
  171.          com_putc(c)         Output character c to comm port.
  172.  
  173.          int com_getc(t)     Get  character  from comm port within t tenths
  174.                              of  a  second.   Return  EOF  if  time   limit
  175.                              expires.
  176.  
  177.          com_dump()          Discard any pending output without sending it.
  178.  
  179.  
  180.  
  181.      In  addition,  we  use  the  following  routines for controlling timed
  182.      loops:
  183.  
  184.          long timerset(t)    Set a timer.  Returns a timer value which will
  185.                              expire in t tenths of a second.
  186.  
  187.          int timeup(z)       Check a timer.  Returns true if  timer  z  has
  188.                              expired yet, or false otherwise.
  189.  
  190.  
  191.      These  routines  also  make  reference  to the following functions for
  192.      system dependent information, which is optional:
  193.  
  194.          filestat(name,&fs)  Read directory entry for  a  file  and  return
  195.                              system dependent information.
  196.  
  197.          setstamp(f,dtg)     Set a file's date/time of last modification.
  198.  
  199.  
  200.      The  SEAlink  implementation  provided  in  this  package  is  used by
  201.      invoking the two primary routines:
  202.  
  203.          int xmtfile(name)             /* transmit a file */
  204.          char *name;                   /* name of file to transmit */
  205.  
  206.      This routine is used to send a file.  One file is sent at a  time.  If
  207.      the  name  is blank (name is null or *name points to a null),  then an
  208.      end of transmission marker is sent.
  209.  
  210.      This routine returns a one if the file is successfully transmitted, or
  211.      a zero if a fatal error occurs.
  212.  
  213.          char *rcvfile(name)           /* receive a file */
  214.          char *name;                   /* name of file (optional) */
  215.  
  216.      This routine is used to receive a file.  One file is  received.  If  a
  217.      name is specified for the file,  then that name WILL be used,  and any
  218.      name sent by the transmitter will be ignored.  If the  name  is  blank
  219.      (name  is  null or *name points to a null),  then the transmitter must
  220.      provide a name for the file.
  221.  
  222.      This routine returns a pointer to  the  name  of  the  file  that  was
  223.      received.  If the file transfer is not successful, then a null pointer
  224.      is returned.
  225.  
  226.      The  pointer  returned  by  rcvfile()  points to a static data buffer.
  227.      This does not have to be freed (and should not be),  but  it  will  be
  228.      overwritten the next time rcvfile() is called.
  229.  
  230.      The  rcvfile()  function  works  on a temporary file whose name is the
  231.      same as the final file,  but with a dash ("-") added at the beginning.
  232.      If  a  file  transfer  is  aborted,  then  this temporary file will be
  233.      retained.  An aborted file transfer will not harm a pre-existing  file
  234.      of the same name.
  235.  
  236.  
  237.  
  238.  
  239.  
  240.  
  241.      In  addition,  this set of routines includes two global variables that
  242.      may be set to affect the SEAlink driver.  These are:
  243.  
  244.          int ackless;        This is used  to  control  the  overdrive.  It
  245.                              should  be  set  to  a  non-zero  value before
  246.                              calling the SEAlink transmitter  if  overdrive
  247.                              is  desired.  We  recommend using overdrive at
  248.                              link rates greater  than  2400  bps,  and  not
  249.                              otherwise.
  250.  
  251.          char *progname;     This  is used to set the "name of transmitting
  252.                              program" field in block  zero.  It  should  be
  253.                              set to point to a string constant.
  254.  
  255.  
  256.      The  SEAlink  routines  can be used for either single or multiple file
  257.      transfers.
  258.  
  259.      To send multiple files,  send each file one  by  one  until  either  a
  260.      transmit  fails  or  all files are sent.  If all files are sent,  then
  261.      signal the end by calling xmtfile() with a null pointer.
  262.  
  263.      To receive multiple files,  call rcvfile() repeatedly until it returns
  264.      a null pointer.
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.  
  273.  
  274.  
  275.  
  276.  
  277.  
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.      This  package includes a demonstration program named CLINK (pronounced
  302.      "clink"),  which is a  simple  TTY  program  for  doing  SEAlink  file
  303.      transfers.  CLINK  does  not  perform  any  sort of terminal emulation
  304.      whatsoever.  However,  she will make use of the ANSI.SYS screen driver
  305.      if you have it installed.
  306.  
  307.      CLINK  may be used in either of two ways:  interactive mode or command
  308.      mode.
  309.  
  310.      To use CLINK in the interactive mode, give the command "CLINK" with no
  311.      arguments.  Press the "ESCape" key to give a  command  to  CLINK.  The
  312.      command  "?" (question mark) instructs CLINK to tell you what commands
  313.      she understands.
  314.  
  315.      To use CLINK in the command mode,  give the command  "CLINK"  with  an
  316.      argument.  There are three arguments you can give CLINK in the command
  317.      mode.  These are:
  318.  
  319.       1) Receive files;  Do this with a command of the form:
  320.  
  321.               CLINK R
  322.  
  323.          CLINK  will  attempt  to receive one or more files from COM1,  and
  324.          will terminate as soon as all files  are  received,  or  when  the
  325.          transfer aborts.
  326.  
  327.       2) Transmit files; Do this with a command of the form:
  328.  
  329.               CLINK T <filename> ...
  330.  
  331.          CLINK  will  attempt  to transmit the listed files over COM1,  and
  332.          will terminate as soon as all files are sent,  or the transfer  is
  333.          aborted.  <filename> may be one or more file names with or without
  334.          drive and path specifiers.  Wildcards may be used.
  335.  
  336.       3) Give help;  If you type:
  337.  
  338.               CLINK ?
  339.  
  340.          or any invalid command,  CLINK will display a  brief  reminder  of
  341.          what arguments she understands in command mode.
  342.  
  343.  
  344.      When CLINK is invoked in the command mode it normally uses COM1,  does
  345.      not  alter  the  baud  rate,  and does not transmit in Overdrive mode.
  346.      This can be altered by using any or all of the following command  line
  347.      switches:
  348.  
  349.          /P1       to use COM1: (default)
  350.          /P2       to use COM2:
  351.          /B<baud>  to set baud rate
  352.          /O        for Overdrive
  353.  
  354.  
  355.      CLINK comes with her own serial driver built in for the IBM PC  family
  356.      and true compatibles,  but she is capable of using any standard FOSSIL
  357.      driver.
  358.  
  359.  
  360.  
  361.