home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 3 Comm / 03-Comm.zip / xyz2-101.zip / CEXYZ2.DOC next >
Text File  |  1994-02-18  |  14KB  |  316 lines
  1.  
  2.                                CE-XYZ/2 v1.01
  3.                       A File Transfer Protocol Module
  4.            Supporting Xmodem, Ymodem, Zmodem, and their variants
  5.                          For OS/2 v2.00 and higher
  6.  
  7.              Copyright (C) 1993, 1994 by Cutting Edge Computing
  8.                             All Rights Reserved.
  9.  
  10.  
  11. ALSO AVAILABLE
  12. --------------
  13. A DOS version of CE-XYZ is also available.  CEXYZ100.ZIP is available
  14. from FidoNet node 1:2240/176, or by calling the BBS at 1-810-743-8464.
  15.  
  16.  
  17. LICENSE AGREEMENT
  18. -----------------
  19. This program is free for non-commercial use.  Commercial users are granted
  20. a license to use CE-XYZ if, and only if, the user has purchased a license
  21. to use The Blue Wave Offline Mail Door.  Your Blue Wave Offline Mail Door
  22. Registration Certificate is sufficient "proof" of license to use this
  23. protocol module.
  24.  
  25. If you are a commercial user and would like to use this protocol module for
  26. other purposes, please write to the address below with contact information
  27. so that we may negotiate a license fee.
  28.  
  29. Software authors that would like to distribute CE-XYZ in their distribution
  30. packages will be granted a license to do so for a reasonable, one-time
  31. licensing fee.  Please contact me at the address below for more
  32. information.  Special hooks are provided in the developer's edition for
  33. executing CE-XYZ directly from your applications, no matter what programming
  34. language you may be using.  Source code is NOT provided - however any minor
  35. cosmetic/color changes, default settings, and a customized title banner can
  36. be done with no extra fee (other than the licensing/redistribution fee).  All
  37. licensing is done with a one-time flat fee.  There are no "per-copy" or
  38. "royalty" fees involved.
  39.  
  40. Cutting Edge Computing
  41. PO Box 90476
  42. Burton, MI  48509
  43.  
  44. FidoNet : 1:2240/176
  45. InterNet: bwave@aol.com
  46. InterNet: george.hatchew@f176.n2240.z1.fidonet.org
  47.  
  48.  
  49. WARRANTY
  50. --------
  51. There is no warranty for this software, either expressed or implied.  The
  52. user assumes full responsibility for the use of this software.
  53.  
  54.  
  55. SUPPORT
  56. -------
  57. Because this is a "free for non-commercial use" program, no support will be
  58. given for this program, except in the following cases:
  59.  
  60.   1)  User has also registered one of The Blue Wave Offline Mail Doors,
  61.       produced by Cutting Edge Computing.
  62.  
  63.   2)  To commercial users who have paid the licensing fee to Cutting Edge
  64.       Computing.
  65.  
  66.   3)  BBS authors, after they have paid the one-time licensing fee to
  67.       Cutting Edge Computing.
  68.  
  69. General help with this protocol engine can be obtained through the
  70. International FidoNet BLUEWAVE Echo.  Netmail (except in the above cases)
  71. will not be answered, but bug reports will be worked on.
  72.  
  73.  
  74.  
  75.  
  76. PURPOSE
  77. -------
  78. The purpose of this program is to provide a file transfer protocol module
  79. specifically designed for use with OS/2 v2.0 and higher.  This application
  80. is written for OS/2 text mode, and does not use the Presentation Manager.
  81. It can be used in the place of ANY external protocol module.
  82.  
  83. The file transfer protocol module is excellent for use on BBS systems, as
  84. it provides security against users uploading files to a remote-defined
  85. path on the BBS system.  (The default, and only, mode of batch uploading
  86. is the same as DSZ/GSZ's "restrict" keyword).  Users will not be able to
  87. upload files to any path except for the path that you specify.  Also, the
  88. FTP does not allow the "overwriting" of an existing file.
  89.  
  90.  
  91. DESCRIPTION
  92. -----------
  93. The file transfer protocol (named "CE-XYZ/2", and referred to as the FTP
  94. throughout the rest of the document) currently supports the following
  95. protocols:
  96.  
  97.   - Zmodem with 32-bit CRC   1024 byte subpackets
  98.   - Zmodem with 16-bit CRC   1024 byte subpackets
  99.   - ZedZap with 32-bit CRC   8192 byte subpackets
  100.   - Ymodem-Batch              128 byte blocks (True Ymodem)
  101.   - Ymodem-1K                1024 byte blocks
  102.   - Ymodem-G                 1024 byte blocks
  103.   - Xmodem-1K                1024 byte blocks
  104.   - Xmodem CRC/Checksum (CRC is the default, fallback to Checksum if remote
  105.                          end doesn't seem to like the CRC method)
  106.  
  107. The FTP uses your installed OS/2 Communications driver (COMM.SYS, SIO.SYS)
  108. for communication with the serial port.  We highly recommend the use of Ray
  109. Gwinn's SIO drivers for high-speed modem communications over the drivers
  110. supplied by IBM in the distribution package of OS/2.
  111.  
  112. The FTP is command line driven;  it must be invoked with command line
  113. parameters specifying, at the very least, the "handle" of the active port
  114. and the protocol transfer method.  This protocol driver WILL NOT initialize
  115. and open a communications handle.  An active communications handle must be
  116. passed to CEXYZ/2 for file transfers to take place.
  117.  
  118. In order to accomodate terminal and BBS programs that require the use of
  119. a DSZ-style log file, the FTP will create/append to a DSZLOG-type log file
  120. if the following environment variable is set:
  121.  
  122.   SET CEXYZLOG=cexyz.log
  123.   SET DSZLOG=dsz.log
  124.  
  125. If the CEXYZLOG environment variable is not set, then the driver looks for
  126. the DSZLOG environment variable.  (CEXYZLOG always has precedence over
  127. DSZLOG).  If the DSZLOG environment variable is not set, then no protocol
  128. logging will take place.  The log file generated by CE-XYZ is 100% DSZ
  129. compatible.
  130.  
  131.  
  132. COMMAND LINE PARAMETERS
  133. -----------------------
  134. In order to successfully invoke the FTP, you must use at least the
  135. following command line parameters:
  136.  
  137.   /L or /B to specify either the locked speed or the line speed (or both).
  138.   /R or /S to specify send/receive mode
  139.   /P, to pass CEXYZ/2 the current communications "port" handle.
  140.  
  141. Below is a description of all available command line parameters.  Any
  142. command line parameter that does not start with a / or a - is assumed to
  143. be the file name(s) to send or receive.  More on file name parameters in
  144. the next section.  All command lines are case insensitive (capital
  145. letters and lower-case letters will do the same thing.)
  146.  
  147.  
  148. * EXAMPLE COMMAND LINE PARAMETERS ARE GIVEN AT THE VERY END OF THIS DOCUMENT *
  149.  
  150.  
  151.   /T<number>   -  By default, the FTP places its window and other
  152.                   information beginning on line number 8 of the display in
  153.                   order to "fit into" the window left by BW mail doors.  By
  154.                   using /T<number>, you can tell the FTP to place the first
  155.                   line of the window beginning on a different line.
  156.  
  157.                   /T1 through /T8 are valid.  If <number> is greater than
  158.                   8, 8 is used.  If <number> is less than 1, 1 is used.
  159.  
  160.   /N<1st_last> -  If you pass a User Name to the protocol engine, the name
  161.                   will be displayed on the screen so you know who is online
  162.                   (mainly for BBS usage).
  163.  
  164.                   /NGeorge_Hatchew would display my name on the left-most
  165.                   column of the display screen.  Please note that an
  166.                   underscore between names IS REQUIRED.
  167.  
  168.   /P<number>   -  Specifies the COM port handle to use for the file transfer.
  169.                   If no port is specified, the driver will abort.
  170.  
  171.   /L<number>   -  The LOCKED baud rate of the transfer session, if the serial
  172.                   port should be locked.  High speed modem users should use
  173.                   one of /L19200, /L38400, /L57600, or possibly /L9600.  If
  174.                   you do not specify the locked baud rate, the driver will
  175.                   try to open the port at the rate specified with the /B
  176.                   parameter.  If the /L command line parameter is NOT
  177.                   specified on the command line, CEXYZ/2 will read the
  178.                   current line speed from the serial driver.
  179.  
  180.   /B<number>   -  The actual line speed of the current connection.  If /L
  181.                   is also specified, /B is used for time and CPS
  182.                   estimations ONLY. If you do not have a locked serial
  183.                   port, you should specify the connect rate of modem with
  184.                   /B.  /B300, /B1200, /B2400, /B7200, etc. are some
  185.                   examples.
  186.  
  187.                   The use of the /B command line parameter is not
  188.                   absolutely required if you use a /L command line
  189.                   parameter, but transfer estimations will be wrong if you
  190.                   do not.  The use of /B with /L is much like the
  191.                   "estimate" command in DSZ/GSZ.
  192.  
  193.   /R<protocol> -  Use the /R parameter to receive files via one of the
  194.                   supported protocols.  The following /R switches are
  195.                   supported:
  196.  
  197.                   /Rx    - Receive file with Xmodem-CRC (Checksum fallback)
  198.                   /Rxcrc - Receive file with Xmodem-CRC
  199.                   /Rxchk - Receive file with Xmodem-Checksum
  200.                   /Rx1k  - Receive file with Xmodem-CRC (1024 byte blocks).
  201.                   /Ry    - Receive file(s) with Ymodem-Batch
  202.                   /Ry1k  - Receive file(s) with Ymodem-Batch (1024 byte blks).
  203.                   /Ryg   - Receive file(s) with Ymodem-G
  204.                   /Rz    - Receive file(s) with Zmodem
  205.                   /Rzap  - Receive file(s) with ZedZap (a mutant Zmodem that
  206.                            transfers up to 8K in one subpacket).
  207.  
  208.   /S<protocol> -  Use the /S parameter to send files via one of the
  209.                   supported protocols.  The following /S switches are
  210.                   supported:
  211.  
  212.                   /Sx    - Send file with Xmodem-CRC (Checksum fallback)
  213.                   /Sxcrc - Send file with Xmodem-CRC
  214.                   /Sxchk - Send file with Xmodem-Checksum
  215.                   /Sx1k  - Send file with Xmodem-CRC (1024 byte blocks).
  216.                   /Sy    - Send file(s) with Ymodem-Batch
  217.                   /Sy1k  - Send file(s) with Ymodem-Batch (1024 byte blks).
  218.                   /Syg   - Send file(s) with Ymodem-G
  219.                   /Sz    - Send file(s) with Zmodem
  220.                   /Szap  - Send file(s) with ZedZap
  221.  
  222.  
  223.  
  224.  
  225. Passing File Names to the FTP
  226. -----------------------------
  227. Any command line parameter not preceeded with a "/" or a "-" is assumed
  228. to be the file name to send or receive.
  229.  
  230.  
  231.     SEND Mode
  232.     ---------
  233.     To send files with the FTP, simply enter the name(s) of the files you
  234.     would like to send on the command line, with a full
  235.     drive:\path\filename.exe specification, if the file is not in the
  236.     current directory.  In SEND mode, a file name specification is
  237.     required.
  238.  
  239.     Wildcards (? and *) on the SEND command line are supported.  If the
  240.     requested protocol is a batch protocol (all but Xmodem and Xmodem-1K),
  241.     the FTP will locate all matches to the wildcard specification and then
  242.     begin a batch send.  If the requested protocol is Xmodem or Xmodem-1K,
  243.     only the first directory match to the wildcard specification will be
  244.     sent.  (Xmodem and its variants can only send or receive one file at a
  245.     time).
  246.  
  247.     In addition to wildcards, file LISTS are supported.  Suppose you had a
  248.     straight-ASCII text file containing the following:
  249.  
  250.     --- Contents of FILE.LST ---
  251.     D:\FILES\UPLOAD\ZIPPER.ZIP
  252.     D:\FILES\UPLOAD\FTP.EXE
  253.     E:\CPROG\MYFILE.C
  254.     H:\FD\NODELIST\NODELIST.*
  255.     C:\BWAVE\*.BW
  256.     ----- End of FILE.LST ------
  257.  
  258.     To send all of the files contained in this list, place an "@" symbol in
  259.     front of the list file name, as in:
  260.  
  261.     CEXYZ2.EXE /P10 /B14400 /Sz @FILE.LST
  262.  
  263.     Or, if FILE.LST is not in the current directory, use:
  264.  
  265.     CEXYZ2.EXE /P10 /B14400 /Sz @E:\SOMEWHER\FILE.LST
  266.  
  267.  
  268.     RECEIVE Mode
  269.     ------------
  270.     If the FTP is requested to receive files via one of the batch
  271.     protocols, a file name to receive is NOT required on the command line.
  272.     Files received will be placed in the current directory with the file
  273.     name given by the sending system.
  274.  
  275.     If you would like to place received files in a directory other than the
  276.     current directory in batch protocol mode, simply enter the name of the
  277.     directory on the command line to receive the file(s) to:
  278.  
  279.     CEXYZ2 /P11 /B2400 /Rz E:\Files\Download
  280.  
  281.     If the directory E:\Files\Download exists, the FTP will place the
  282.     received files there.
  283.  
  284.     Supposing you are downloading a file called THISFILE.ZIP via Zmodem,
  285.     and you would like to place it in the directory C:\FILES with the file
  286.     name of MY-DL.ZIP, simply specify the complete file name.  The file
  287.     name received from the sender will be overriden.  Example:
  288.  
  289.     CEXYZ2.EXE /P17 /B1200 /Rz C:\Files\My-DL.Zip
  290.  
  291.     If you are receiving files via Xmodem or Xmodem-1K, a full file name
  292.     specification is REQUIRED on the command line, since these 2 protocols
  293.     do not support the passing of a file name.  Example:
  294.  
  295.     CEXYZ2 /P14 /L38400 /B2400 /Rx E:\Files\Download\Myfile.arj
  296.  
  297.  
  298. EXAMPLE COMMAND LINES
  299. ---------------------
  300. Modem active on port handle 12, locked at 38400 bps, connected at 9600 bps
  301. with a user, receiving a batch upload with Ymodem-G to D:\BBS\FILES\UPLOAD
  302. directory:
  303.  
  304.     CEXYZ2.EXE /l38400 /b9600 /p12 /ryg d:\bbs\files\upload
  305.  
  306. Modem active on port handle 15, no locked port, connected at 1200bps, receiving
  307. a file via Xmodem:
  308.  
  309.     CEXYZ2.EXE /p15 /b1200 /rx filename.ext
  310.  
  311. Modem active on port handle 7, no locked port, connected at 2400bps,
  312. receiving files via Zmodem to the current directory:
  313.  
  314.     CEXYZ2.EXE /b2400 /rz
  315.  
  316.