home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 3 Comm / 03-Comm.zip / OS2FTP15.ZIP / OS2FTP.DOC < prev    next >
Text File  |  1993-02-06  |  9KB  |  259 lines
  1. OS/2 File Transfer Protocol driver 1.5          (c) 1992 by Mikael Wahlgren
  2. ===========================================================================
  3.  
  4. This is an external file transfer protocol driver, designed to supply
  5. other programs with file transfer capabilities.  It is specially
  6. designed with Os2You (OS/2 Remote Access Facility by Mikael Wahlgren)
  7. and the Maximus/2 BBS program in mind.
  8.  
  9. This protocol driver supports the following file transfer protocols:
  10.  
  11. Xmodem/ChSum
  12. Xmodem/CRC
  13. Xmodem-1K
  14. Ymodem (batch)
  15. Ymodem-G (batch)
  16. Zmodem
  17. Kermit (*)
  18.  
  19. (*) The Kermit file transfer protocol is supported in combination with
  20.     the CKermit file transfer program (tested with CK5A188 release).
  21.     CKOKER16.EXE must be available in the PATH.
  22.  
  23. To install this program you copy all *.EXE and *.MSG in a directory
  24. specified by your PATH and DPATH statements.  You copy the ZIP.DLL
  25. file into a directory specified by your LIBPATH statement.
  26.  
  27.  
  28.  
  29. Possible return codes (ERRORLEVELs)
  30. ===================================
  31.   ERR_NO_ERROR          = 0
  32.   ERR_OPEN_FILE         = 1
  33.   ERR_INIT_SESS         = 2
  34.   ERR_DISK_READ         = 3
  35.   ERR_DISK_WRITE        = 4
  36.   ERR_COM_READ          = 5
  37.   ERR_COM_WRITE         = 6
  38.   ERR_CANCEL            = 7
  39.   ERR_FATAL_COM         = 8
  40.   ERR_NO_DCD            = 9
  41.   ERR_LOCAL_CANCEL      = 10
  42.   ERR_TIMEOUT           = 255;
  43.  
  44. (these error codes are only valid for Xmodem and Ymodem family protocols.
  45. For return codes of Zmodem and Kermit, see the M2Zmodem and CKermit
  46. documentations)
  47.  
  48.  
  49. Special instructions to run the program with Os2You
  50. ===================================================
  51. This program is especially designed with Os2You in mind.  The recommended
  52. protocol is Ymodem, which is default.  To use this protocol driver with
  53. Os2You, just copy the files into a pathed directory and run the following
  54. commands:
  55.  
  56. Os2FTP -sC:\Files\*.DAT  (to transfer files C:\Files\*.DAT)
  57. Os2FTP -rC:\Download     (to receive files into C:\Download directory)
  58.  
  59. If you want to use another protocol, like YmodemG, the commands will look
  60. like:
  61.  
  62. Os2FTP -YMODEMG -sC:\Files\*.DAT
  63. Os2FTP -YMODEMG -rC:\Download
  64.  
  65.  
  66.  
  67. Instructions on use with BBS
  68. ============================
  69. Copy all of the distributed files into your Maximus home directory.
  70. To interface these protocols with the BBS (Maximus/2) you will have
  71. to add the following lines to your PROTOCOL.CTL file:
  72.  
  73. ------------------------------- cut here -----------------------
  74. Protocol Ymodem
  75.          Type            Batch
  76.  
  77.          LogFile         Ymodem%K.Log
  78.          ControlFile     Ymodem%K.Ctl
  79.          DownloadCmd     OS2FTP.Exe -nosts -s#Ymodem%K.Ctl
  80.          UploadCmd       OS2FTP.Exe -nosts -r#Ymodem%K.Ctl
  81.          DownloadString  Send %s
  82.          UploadString    Get %s
  83.          DownloadKeyword Sent
  84.          UploadKeyword   Got
  85.          FilenameWord    1
  86.          DescriptWord    0
  87. End Protocol
  88.  
  89.  
  90. Protocol G-Ymodem
  91.          Type            Batch
  92.  
  93.          LogFile         YmodG%K.Log
  94.          ControlFile     YmodG%K.Ctl
  95.          DownloadCmd     OS2FTP.Exe -ymodemg -nosts -s#YmodG%K.Ctl
  96.          UploadCmd       OS2FTP.Exe -ymodemg -nosts -r#YmodG%K.Ctl
  97.          DownloadString  Send %s
  98.          UploadString    Get %s
  99.          DownloadKeyword Sent
  100.          UploadKeyword   Got
  101.          FilenameWord    1
  102.          DescriptWord    0
  103. End Protocol
  104.  
  105.  
  106. Protocol M2-Zmodem
  107.          Type            Batch
  108.  
  109.          LogFile         M2Z%K.Log
  110.          ControlFile     M2Z%K.Ctl
  111.          DownloadCmd     OS2FTP.Exe -zmodem -s#M2Z%K.Ctl
  112.          UploadCmd       OS2FTP.Exe -zmodem -r#M2Z%K.Ctl
  113.          DownloadString  Send %s
  114.          UploadString    Get %s
  115.          DownloadKeyword Z-Sent:
  116.          UploadKeyword   Z-Received:
  117.          FilenameWord    1
  118.          DescriptWord    0
  119. End Protocol
  120.  
  121.  
  122. Protocol Kermit
  123.          Type            Batch
  124.  
  125.          LogFile         KERM%K.Log
  126.          ControlFile     KERM%K.Ctl
  127.          DownloadCmd     OS2FTP.Exe -kermit -tmp\KERM%K -s#KERM%K.Ctl
  128.          UploadCmd       OS2FTP.Exe -kermit -tmp\KERM%K -r#KERM%K.Ctl
  129.          DownloadString  Send %s
  130.          UploadString    Get %s
  131.          DownloadKeyword Sent
  132.          UploadKeyword   Got
  133.          FilenameWord    1
  134.          DescriptWord    0
  135. End Protocol
  136.  
  137.  
  138. ------------------------------- cut here -----------------------
  139.  
  140. You should also ensure that the PROTOCOL.CTL file is included in
  141. your MAX.CTL file (i.e. ensure that the MAX.CTL file is ended with
  142. a line like "include PROTOCOL.CTL")
  143.  
  144. The Xmodem protocols should be possible to use in this way as well, but
  145. I can't see the use of this.
  146.  
  147. There is no guarantee that these file transfer protocols work in all
  148. situations.  Especially the Zmodem protocol is untested for this kind
  149. of usage.  I am not legally responsible for any harm that your system
  150. may suffer from, by the use of this program.
  151.  
  152. NOTE that if you use the Kermit protocol, the CKOKER16.EXE file MUST be
  153. available in the PATH (it is _NOT_ sufficient that it is in the current
  154. directory!).  This version of OS2FTP is built to work together with
  155. CKermit version 5A188 released 25 January 1993.  The CKermit package
  156. includes two different Kermit implementations CKOKER16.EXE for 16 or 32-
  157. bit OS/2 and CKOKER32.EXE for 32-bit OS/2.  HOWEVER there seems to be
  158. a serious bug in CKOKER32.EXE (the 32-bit version) which prevents it
  159. from working for this kind of use.  OS2FTP is built to first look for
  160. CKOKER32.EXE and if that can't be loaded try with CKOKER16.EXE.  Thus
  161. I recommend you to REMOVE CKOKER32.EXE and ensure that ONLY CKOKER16.EXE
  162. is available.  This as long as the bug in the 32-bit implementation
  163. remains unfixed.  Also note that becuase the Kermit protocol is
  164. implemented using an external program, there are some limitations with
  165. regard to this.  These limitations are (when using Kermit protocols):
  166.  
  167. *  All files are transfered to/from a temporary directory created by
  168.    OS2FTP.  This directory will normally be maintained automaticly
  169.    by OS2FTP.  This means that if a user request a file transfer batch
  170.    of 3.5 Mbytes to/from the system, this will require 3.5 Mb of temporary
  171.    disk space.
  172.  
  173. *  If a user cancels a Kermit download, the BBS will still treat this as
  174.    a completed download (when adding to the download counters and so on).
  175.  
  176. *  The Kermit protocol can not be aborted by pressing Ctrl-X several
  177.    times, as stated by Maximus before a file transfer begins.
  178.  
  179.  
  180.  
  181.  
  182. Programming information
  183. =======================
  184. If you want to use OS2FTP with your own application you can easily interface
  185. to OS2FTP.  To send files with XModem, Ymodem, Ymodem-G, Zmodem or Kermit
  186. from your application, you create a text file (let's call it OUT.TXT) like
  187. this:
  188.  
  189. Send C:\MyPath\MyFile.TXT
  190. Send C:\MyPath\Package.ZIP
  191. Send C:\Another\Demo.TXT
  192.  
  193. To start the file transfer you invoke OS2FTP with the following command:
  194.  
  195. For Xmodem:   OS2FTP -xmodem -nosts -s#OUT.TXT
  196. For Ymodem:   OS2FTP -nosts -s#OUT.TXT
  197. For Ymodem:   OS2FTP -ymodemg -nosts -s#OUT.TXT
  198. For Zmodem:   OS2FTP -zmodem -s#OUT.TXT
  199. For Kermit:   OS2FTP -kermit -tmp\TMPDIR -s#OUT.TXT
  200.  
  201. To receive files with Xmodem, Ymodem, Ymodem-G, Zmodem or Kermit to your
  202. application (into the directory C:\InPath you create a text file (let's
  203. call it IN.TXT) like this:
  204.  
  205. Get C:\InPath
  206.  
  207. To start the receive you invoke OS2FTP with the following command:
  208.  
  209. For Xmodem:   OS2FTP -xmodem -nosts -r#IN.TXT
  210. For Ymodem:   OS2FTP -nosts -r#IN.TXT
  211. For Xmodem:   OS2FTP -ymodemg -nosts -r#IN.TXT
  212. For Zmodem:   OS2FTP -zmodem -r#IN.TXT
  213. For Xmodem:   OS2FTP -kermit -tmp\TMPDIR -r#IN.TXT
  214.  
  215. After a successful transfer a log file will be created called OUT.LOG
  216. (if the filename OUT.TXT was used) or IN.LOG (if the filename IN.TXT
  217. was used).  If the file transfer operation was done with Xmodem, Ymodem
  218. or Kermit each row in the log file should be scanned for the following
  219. keywords (there is no guarantee that the keyword will be placed first on
  220. the row):
  221.  
  222. Sent yyy\xxx        (yyy\xxx is the complete path to file received)
  223. Got yyy\xxx         ( d:o )
  224.  
  225. If the file transfer was performed using Zmodem, the keywords are:
  226.  
  227. Z-Sent: yyy\xxx     (yyy\xxx is the complete path to file received)
  228. Z-Received: yyy\xxx ( d:o )
  229.  
  230. The log file should be erased before using OS2FTP again.
  231.  
  232.  
  233.  
  234. Release log
  235. ===========
  236. 1.3   Modified for BBS usage
  237.  
  238. 1.4   Ymodem-G transfers can now be cancelled correctly with Ctrl-X.
  239.       Ymodem-G didn't detect carrier loss, this is fixed.
  240.  
  241.       Kermit protocol added.
  242.  
  243. 1.5   Kermit handling modified to work with CKermit 5A188 from
  244.       25 January 1993.
  245.  
  246.  
  247. Licensing information
  248. =====================
  249. If you haven't registered the Os2You/M2Zmodem/OS2FTP file transfer option,
  250. this program will introduce an intentional delay before transfering any
  251. files.  Note that the Ymodem protocol used in this protocol driver is exactly
  252. the same driver that is built in Os2You, available via the Service functions
  253. menu.
  254.  
  255. To register, use the included order form and specify the
  256. Os2You/M2Zmodem/OS2FTP item.
  257.  
  258. Mikael Wahlgren
  259.