CE-XYZ/2 v1.00 A File Transfer Protocol Module Supporting Xmodem, Ymodem, Zmodem, and their variants For OS/2 v2.00 and higher Copyright (C) 1993 by Cutting Edge Computing All Rights Reserved. ALSO AVAILABLE -------------- A DOS version of CE-XYZ is also available. CEXYZ100.ZIP is available from FidoNet node 1:2240/176, or by calling the BBS at 1-313-743-8464. LICENSE AGREEMENT ----------------- This program is free for non-commercial use. Commercial users are granted a license to use CE-XYZ if, and only if, the user has purchased a license to use The Blue Wave Offline Mail Door. Your Blue Wave Offline Mail Door Registration Certificate is sufficient "proof" of license to use this protocol module. If you are a commercial user and would like to use this protocol module for other purposes, please write to the address below with contact information so that we may negotiate a license fee. Software authors that would like to distribute CE-XYZ in their distribution packages will be granted a license to do so for a reasonable, one-time licensing fee. Please contact me at the address below for more information. Special hooks are provided in the developer's edition for executing CE-XYZ directly from your applications, no matter what programming language you may be using. Source code is NOT provided - however any minor cosmetic/color changes, default settings, and a customized title banner can be done with no extra fee (other than the licensing/redistribution fee). All licensing is done with a one-time flat fee. There are no "per-copy" or "royalty" fees involved. Cutting Edge Computing PO Box 90476 Burton, MI 48509 FidoNet : 1:2240/176 InterNet: george.hatchew@f176.n2240.z1.fidonet.org WARRANTY -------- There is no warranty for this software, either expressed or implied. The user assumes full responsibility for the use of this software. SUPPORT ------- Because this is a "free for non-commercial use" program, no support will be given for this program, except in the following cases: 1) User has also registered one of The Blue Wave Offline Mail Doors, produced by Cutting Edge Computing. 2) To commercial users who have paid the licensing fee to Cutting Edge Computing. 3) BBS authors, after they have paid the one-time licensing fee to Cutting Edge Computing. General help with this protocol engine can be obtained through the International FidoNet BLUEWAVE Echo. Netmail (except in the above cases) will not be answered, but bug reports will be worked on. PURPOSE ------- The purpose of this program is to provide a file transfer protocol module specifically designed for use with OS/2 v2.0 and higher. This application is written for OS/2 text mode, and does not use the Presentation Manager. It can be used in the place of ANY external protocol module. The file transfer protocol module is excellent for use on BBS systems, as it provides security against users uploading files to a remote-defined path on the BBS system. (The default, and only, mode of batch uploading is the same as DSZ/GSZ's "restrict" keyword). Users will not be able to upload files to any path except for the path that you specify. Also, the FTP does not allow the "overwriting" of an existing file. DESCRIPTION ----------- The file transfer protocol (named "CE-XYZ/2", and referred to as the FTP throughout the rest of the document) currently supports the following protocols: - Zmodem with 32-bit CRC 1024 byte subpackets - Zmodem with 16-bit CRC 1024 byte subpackets - ZedZap with 32-bit CRC 8192 byte subpackets - Ymodem-Batch 128 byte blocks (True Ymodem) - Ymodem-1K 1024 byte blocks - Ymodem-G 1024 byte blocks - Xmodem-1K 1024 byte blocks - Xmodem CRC/Checksum (CRC is the default, fallback to Checksum if remote end doesn't seem to like the CRC method) The FTP uses your installed OS/2 Communications driver (COMM.SYS, SIO.SYS) for communication with the serial port. We highly recommend the use of Ray Gwinn's SIO drivers for high-speed modem communications over the drivers supplied by IBM in the distribution package of OS/2. The FTP is command line driven; it must be invoked with command line parameters specifying, at the very least, the "handle" of the active port and the protocol transfer method. This protocol driver WILL NOT initialize and open a communications handle. An active communications handle must be passed to CEXYZ/2 for file transfers to take place. In order to accomodate terminal and BBS programs that require the use of a DSZ-style log file, the FTP will create/append to a DSZLOG-type log file if the following environment variable is set: SET CEXYZLOG=cexyz.log SET DSZLOG=dsz.log If the CEXYZLOG environment variable is not set, then the driver looks for the DSZLOG environment variable. (CEXYZLOG always has precedence over DSZLOG). If the DSZLOG environment variable is not set, then no protocol logging will take place. The log file generated by CE-XYZ is 100% DSZ compatible. COMMAND LINE PARAMETERS ----------------------- In order to successfully invoke the FTP, you must use at least the following command line parameters: /L or /B to specify either the locked speed or the line speed (or both). /R or /S to specify send/receive mode /P, to pass CEXYZ/2 the current communications "port" handle. Below is a description of all available command line parameters. Any command line parameter that does not start with a / or a - is assumed to be the file name(s) to send or receive. More on file name parameters in the next section. All command lines are case insensitive (capital letters and lower-case letters will do the same thing.) * EXAMPLE COMMAND LINE PARAMETERS ARE GIVEN AT THE VERY END OF THIS DOCUMENT * /T - By default, the FTP places its window and other information beginning on line number 8 of the display in order to "fit into" the window left by BW mail doors. By using /T, you can tell the FTP to place the first line of the window beginning on a different line. /T1 through /T8 are valid. If is greater than 8, 8 is used. If is less than 1, 1 is used. /N<1st_last> - If you pass a User Name to the protocol engine, the name will be displayed on the screen so you know who is online (mainly for BBS usage). /NGeorge_Hatchew would display my name on the left-most column of the display screen. Please note that an underscore between names IS REQUIRED. /P - Specifies the COM port handle to use for the file transfer. If no port is specified, the driver will abort. /L - The LOCKED baud rate of the transfer session, if the serial port should be locked. High speed modem users should use one of /L19200, /L38400, /L57600, or possibly /L9600. If you do not specify the locked baud rate, the driver will try to open the port at the rate specified with the /B parameter. If the /L command line parameter is NOT specified on the command line, CEXYZ/2 will read the current line speed from the serial driver. /B - The actual line speed of the current connection. If /L is also specified, /B is used for time and CPS estimations ONLY. If you do not have a locked serial port, you should specify the connect rate of modem with /B. /B300, /B1200, /B2400, /B7200, etc. are some examples. The use of the /B command line parameter is not absolutely required if you use a /L command line parameter, but transfer estimations will be wrong if you do not. The use of /B with /L is much like the "estimate" command in DSZ/GSZ. /R - Use the /R parameter to receive files via one of the supported protocols. The following /R switches are supported: /Rx - Receive file with Xmodem-CRC (Checksum fallback) /Rxcrc - Receive file with Xmodem-CRC /Rxchk - Receive file with Xmodem-Checksum /Rx1k - Receive file with Xmodem-CRC (1024 byte blocks). /Ry - Receive file(s) with Ymodem-Batch /Ry1k - Receive file(s) with Ymodem-Batch (1024 byte blks). /Ryg - Receive file(s) with Ymodem-G /Rz - Receive file(s) with Zmodem /Rzap - Receive file(s) with ZedZap (a mutant Zmodem that transfers up to 8K in one subpacket). /S - Use the /S parameter to send files via one of the supported protocols. The following /S switches are supported: /Sx - Send file with Xmodem-CRC (Checksum fallback) /Sxcrc - Send file with Xmodem-CRC /Sxchk - Send file with Xmodem-Checksum /Sx1k - Send file with Xmodem-CRC (1024 byte blocks). /Sy - Send file(s) with Ymodem-Batch /Sy1k - Send file(s) with Ymodem-Batch (1024 byte blks). /Syg - Send file(s) with Ymodem-G /Sz - Send file(s) with Zmodem /Szap - Send file(s) with ZedZap Passing File Names to the FTP ----------------------------- Any command line parameter not preceeded with a "/" or a "-" is assumed to be the file name to send or receive. SEND Mode --------- To send files with the FTP, simply enter the name(s) of the files you would like to send on the command line, with a full drive:\path\filename.exe specification, if the file is not in the current directory. In SEND mode, a file name specification is required. Wildcards (? and *) on the SEND command line are supported. If the requested protocol is a batch protocol (all but Xmodem and Xmodem-1K), the FTP will locate all matches to the wildcard specification and then begin a batch send. If the requested protocol is Xmodem or Xmodem-1K, only the first directory match to the wildcard specification will be sent. (Xmodem and its variants can only send or receive one file at a time). In addition to wildcards, file LISTS are supported. Suppose you had a straight-ASCII text file containing the following: --- Contents of FILE.LST --- D:\FILES\UPLOAD\ZIPPER.ZIP D:\FILES\UPLOAD\FTP.EXE E:\CPROG\MYFILE.C H:\FD\NODELIST\NODELIST.* C:\BWAVE\*.BW ----- End of FILE.LST ------ To send all of the files contained in this list, place an "@" symbol in front of the list file name, as in: CEXYZ2.EXE /P10 /B14400 /Sz @FILE.LST Or, if FILE.LST is not in the current directory, use: CEXYZ2.EXE /P10 /B14400 /Sz @E:\SOMEWHER\FILE.LST RECEIVE Mode ------------ If the FTP is requested to receive files via one of the batch protocols, a file name to receive is NOT required on the command line. Files received will be placed in the current directory with the file name given by the sending system. If you would like to place received files in a directory other than the current directory in batch protocol mode, simply enter the name of the directory on the command line to receive the file(s) to: CEXYZ2 /P11 /B2400 /Rz E:\Files\Download If the directory E:\Files\Download exists, the FTP will place the received files there. Supposing you are downloading a file called THISFILE.ZIP via Zmodem, and you would like to place it in the directory C:\FILES with the file name of MY-DL.ZIP, simply specify the complete file name. The file name received from the sender will be overriden. Example: CEXYZ2.EXE /P17 /B1200 /Rz C:\Files\My-DL.Zip If you are receiving files via Xmodem or Xmodem-1K, a full file name specification is REQUIRED on the command line, since these 2 protocols do not support the passing of a file name. Example: CEXYZ2 /P14 /L38400 /B2400 /Rx E:\Files\Download\Myfile.arj EXAMPLE COMMAND LINES --------------------- Modem active on port handle 12, locked at 38400 bps, connected at 9600 bps with a user, receiving a batch upload with Ymodem-G to D:\BBS\FILES\UPLOAD directory: CEXYZ2.EXE /l38400 /b9600 /p12 /ryg d:\bbs\files\upload Modem active on port handle 15, no locked port, connected at 1200bps, receiving a file via Xmodem: CEXYZ2.EXE /p15 /b1200 /rx filename.ext Modem active on port handle 7, no locked port, connected at 2400bps, receiving files via Zmodem to the current directory: CEXYZ2.EXE /b2400 /rz