File Transfers

 There are the functions that perform file transfers:

     Protocol        Send            Receive
     --------------------------------------------
     Xmodem          tp_sxmodem()    tp_rxmodem()
     Xmodem/CRC      tp_sxmodem()    tp_rxcrc()
     Xmodem/1K       tp_sx1k()       tp_rx1k()
     Ymodem          tp_symodem()    tp_rymodem()
     Ymodem-G        tp_symodem()    tp_ryg()
     Zmodem          tp_szmodem()    tp_rzmodem()
     Kermit          tp_skermit()    tp_rkermit()

 There are a number of additional functions that control the file
 transfer functions.  They are:

 tp_gmtoff()     Sets time-zone offset for Ymodem and Zmodem
                 timestamps.
 tp_kparam()     Sets Kermit protocol parameters.
 tp_xbufsize()   Sets the size of the file I/O buffer.
 tp_xdcd()       Decides whether loss of DCD terminates a file
                 transfer.
 tp_xyparam()    Sets Xmodem and Ymodem protocol parameters.
 tp_zblklen()    Sets Zmodem subpacket (block) length.
 tp_zfconv()     Sets Zmodem file conversion option.
 tp_zparam()     Sets Zmodem protocol parameters.

 Progress Functions

 During a file transfer, the protocol transfer function calls a user-
 defined progress function to let your program keep track of the
 status of the transfer, and to let it know when errors occur.

 You pass the name of your progress function to the protocol transfer
 function when you start the transfer.  The progress function will be
 called with four parameters: a numeric code for the current status,
 the name of the file being transferred, the size of the file (or
 number of bytes sent so far), and an error code.

 Return Value.  The progress function should normally return 0.  If it
 returns 1 (or, usually, any non-zero value), the transfer will be
 aborted.  See the description of TXS_SFILE below for some other
 special return codes.

 Parameters.  The progress function declaration might look like this
 in Clipper 5.0:

     function Progress(nCode, cFile, nLength, nError)

 or like this in Summer '87:

     function Progress
         parameters nCode, cFile, nLength, nError

 The possible values of the nCode parameter are:

     Value       Name            Meaning
     ----------------------------------------------------------------
       1         TXS_START       Start of transfer.
       2         TXS_SFILE       Start of file.  A batch transfer may
                                 contain more than one file.
       3         TXS_NEWNAME     The name of the file being received
                                 conflicts with one that already exists.
                                 The new file is being renamed to avoid
                                 conflict.
       4         TXS_SDATA       Starting to send or receive file data.
                                 See note concerning Zmodem below.
       5         TXS_BLOCK       Block successfully sent or received.
       6         TXS_ERROR       An error has occurred.
       7         TXS_ABFILE      Giving up on the current file.
       8         TXS_ABORT       Giving up on the transfer.
       9         TXS_WEND        File finished, waiting for end-of-file
                                 acknowledgement.
      10         TXS_EFILE       End of file.
      11         TXS_END         End of transfer.

 [5.0] In Clipper 5.0, the constants in the "Name" column are defined in
 the telepath.ch header file.

 TXS_START.  Sent at the very start of the transfer, before any
 handshaking has taken place.  None of the other progress function
 parameters contain any useful values.

 TXS_SFILE.  cFile contains the name of the file being sent or received.
 nLength contains the size of the file, except that when the size is not
 known (Xmodem or Kermit receive), nLength will be -1.

 When receiving a file, the progress function can return 2 to tell the
 transfer function to overwrite an existing file of the same name.
 Another way to get the same effect is to erase the existing file when
 you get this before the protocol function notices that it exists.

 When receiving a file using Zmodem, the progress function return values
 have these meanings:

     Value       Meaning
     ----------------------------------------------------------------
       0         If the file already exists, assume that it is the
                 result of an aborted download, and try to resume the
                 transfer.  If the transfer cannot be resumed, download
                 the file under a new name.
       1         Abort the transfer.
       2         Same as 0, except if the file already exists and the
                 transfer cannot be resumed, overwrite the existing
                 file.
       3         Skip this file.
       4         Do not try to resume the transfer.  If the file already
                 exists, pick a new name and start from the beginning.
       5         Do not try to resume the transfer.  If the file already
                 exists, delete the existing file and start from the
                 beginning.

 TXS_NEWNAME.  cFile contains the new filename.  nLength contains the
 same value it had for the TXS_SFILE message.

 TXS_SDATA.  cFile contains the filename.  nLength is the offset (number
 of bytes into the file) where the sender is starting.  This will be
 zero except for a resumed Zmodem transfer.

 For Zmodem, there may be several TXS_SDATA messages during a transfer.
 The first for a given file is the real "start of data" message.  The
 others occur when an error forces the sender and receiver to back up
 and resynchronize.  For these messages, nLength is the offset where the
 sender has backed up to restart.

 TXS_BLOCK.  cFile is the filename.  nLength is the number of bytes sent
 or received so far, relative to the start of the file.

 TXS_ERROR.  cFile is the filename, nLength is 0.  nError is an error
 code, as defined in the Error Codes reference.  A fatal error will be
 followed by...

 TXS_ABFILE.  cFile is the filename, nLength is 0, nError is the error
 code.  This message is also sent during a Zmodem transfer when the
 sender has been told to skip a file.  In that case the error code is 0.
 Otherwise, TXS_ABFILE will usually be followed by...

 TXS_ABORT.  cFile and nLength are empty, but nError is an error code.
 This is the last message before the protocol transfer function returns.

 TXS_WEND.  cFile is the filename, nLength and nError are 0.  This
 message means that the sender is waiting for the receiver to
 acknowledge the end-of-file.  It does not mean much to the receiver,
 but is sent anyway, just before the TXS_EFILE message.

 TXS_EFILE.  cFile is the filename, nLength and nError are 0.  The next
 message will be either another TXS_SFILE, if there are more files, or
 TXS_END.

 TXS_END.  All of the other parameters are empty or zero.  This is the
 last message before the protocol transfer function returns.