Synchronet External X/Y/Zmodem (SEXYZ) File Transfer Protocol Driver
--------------------------------------------------------------------

$Id: sexyz.txt,v 1.16 2005/06/12 10:11:12 rswindell Exp $

Overview
--------
SEXYZ was developed as a native (32-bit) TCP/socket-based replacement for the
16-bit DOS file transfer drivers (e.g. FDSZ, CE-XYZ, etc.) that we've been
stuck with on Win32 BBSes for *far* too long. While SEXYZ was designed with
Synchronet BBSes in mind, it should also work with other Win32 BBS packages
that have the ability to pass socket descriptors to external file transfer
protocol drivers.

SEXYZ behaves much like DSZ/FDSZ and CE-XYZ:

    o Familiar command-line syntax
    o Supports the DSZLOG environment variable for result logging
    o Supports batch transfer file lists

SEXYZ has several advantages over legacy drivers like FDSZ and CE-XYZ:

    o Faster (native, multi-threaded design)
    o Socket-based (no need for FOSSIL drivers or virtual COM ports/UARTs)
    o Multi-tasking friendly (does not needlessly consume CPU cycles)
    o Supports long filenames (e.g. not just DOS "8.3" formatted names)
    o Supports Ymodem-G (FDSZ does not)
    o Handles Telnet IAC escaping and option negotiations
    o Transfers files over fast connections (e.g. 100KB/sec) without issue
    o Actively developed and supported
    o Open source (at cvs.synchro.net)!


Distribution
------------
SEXYZ is freeware, licensed under the GNU General Public License (GPL)
http://www.fsf.org/licensing/licenses/gpl.txt
with portions licensed under the GNU Lesser General Public License (LGPL)
http://www.fsf.org/licensing/licenses/lgpl.txt.

You can find the current source code (in C) in the CVS repository at
cvs.synchro.net.

The latest and greatest build will be included in Synchronet-Win32 releases.
You should be able to find/download the latest general release of SEXYZ-Win32
(sexyzNNN.zip) at one or all of the following locations:

http://www.synchro.net
ftp://ftp.synchro.net
ftp://vert.synchro.net
telnet://vert.synchro.net


Command-line Syntax
-------------------
Just running "sexyz" by itself will display the supported command-line usage
(options and commands):

usage: sexyz <socket> [-opts] <cmd> [file | path | @list]

socket = TCP socket descriptor (or leave blank for "stdio" mode on Unix)

opts   = -y  to overwrite files when receiving
         -o  disable Zmodem CRC-32 mode (use CRC-16)
         -s  disable Zmodem streaming (Slow Zmodem)
         -2  set maximum Zmodem block size to 2K
         -4  set maximum Zmodem block size to 4K
         -8  set maximum Zmodem block size to 8K (ZedZap)
         -!  to pause after abnormal exit (error)
         -telnet to enable Telnet mode (the default)
         -rlogin to enable RLogin (pass-through) mode

cmd    = v  to display detailed version information
         sx to send Xmodem     rx to recv Xmodem
         sX to send Xmodem-1K  rc to recv Xmodem-CRC
         sy to send Ymodem     ry to recv Ymodem
         sY to send Ymodem-1K  rg to recv Ymodem-G
         sz to send Zmodem     rz to recv Zmodem

file   = filename to send or receive
path   = directory to receive files into
list   = name of text file with list of filenames to send or receive


NOTE: SEXYZ actually supports either "+list" or "@list" syntax for specifying
      a file list on the command-line. If the list file doesn't exist, it'll
      treat the '+' or '@' as part of the filename to send or receive.

NOTE: SEXYZ also supports "rzsz" command-line syntax for some commands.
      Examples: "sexyz rx -c" to recv Xmodem-CRC
                "sexyz sx -k" to send Xmodem-1K
                "sexyz rb"    to recv Ymodem
                "sexyz sb -k" to send Ymodem-1K


Example configuration for Synchronet v3.12-Win32
------------------------------------------------

SCFG:File Options->Transfer Protocols:

[File Transfer Protocol]
 1: Mnemonic (Command Key)        X
 2: Protocol Name                 Xmodem (SEXYZ)
 3: Access Requirements           !UNIX
 4: Upload Command Line           %!sexyz %h -%p rC %f
 5: Download Command Line         %!sexyz %h -%p sX %f
 6: Batch Upload Command Line
 7: Batch Download Command Line
 8: Bi-dir Command Line
 9: Native (32-bit) Executable    Yes
10: Supports DSZLOG               Yes

[File Transfer Protocol]
 1: Mnemonic (Command Key)        Y
 2: Protocol Name                 Ymodem (SEXYZ)
 3: Access Requirements           !UNIX
 4: Upload Command Line           %!sexyz %h -%p ry %f
 5: Download Command Line         %!sexyz %h -%p sY %f
 6: Batch Upload Command Line     %!sexyz %h -%p ry %g
 7: Batch Download Command Line   %!sexyz %h -%p sY @%f
 8: Bi-dir Command Line
 9: Native (32-bit) Executable    Yes
10: Supports DSZLOG               Yes

[File Transfer Protocol]
 1: Mnemonic (Command Key)        G
 2: Protocol Name                 Ymodem-G (SEXYZ)
 3: Access Requirements           !UNIX
 4: Upload Command Line           %!sexyz %h -%p rg %f
 5: Download Command Line         %!sexyz %h -%p sY %f
 6: Batch Upload Command Line     %!sexyz %h -%p rg %g
 7: Batch Download Command Line   %!sexyz %h -%p sY @%f
 8: Bi-dir Command Line
 9: Native (32-bit) Executable    Yes
10: Supports DSZLOG               Yes

[File Transfer Protocol]
 1: Mnemonic (Command Key)        Z
 2: Protocol Name                 Zmodem (SEXYZ)
 3: Access Requirements           !UNIX
 4: Upload Command Line           %!sexyz %h -%p rz %f
 5: Download Command Line         %!sexyz %h -%p sz %f
 6: Batch Upload Command Line     %!sexyz %h -%p rz %g
 7: Batch Download Command Line   %!sexyz %h -%p sz @%f
 8: Bi-dir Command Line
 9: Native (32-bit) Executable    Yes
10: Supports DSZLOG               Yes


Example configuration for Mystic v1.08-Win32
--------------------------------------------
(provided by Dream Master)

A. Active     : Yes
B. HotKey     : Z
C. Description: Zmodem
D. Batch      : No
E. Send Cmd   : c:\mystic\prots\sexyz.exe %0 sz %3
F. Receive Cmd: c:\mystic\prots\sexyz.exe %0 rz %3

A. Active     : Yes
B. HotKey     : Z
C. Description: Zmodem batch
D. Batch      : Yes
E. Send Cmd   : c:\mystic\prots\sexyz.exe %0 sz @%3
F. Receive Cmd: c:\mystic\prots\sexyz.exe %0 rz @%3


Note Regarding Synchronet for Unix
----------------------------------
Synchronet for Unix does not yet support socket-based file transfer protocols,
so SEXYZ is only currently supported on Synchronet for Unix in "stdio" mode.
You can enable "stdio" mode in SEXYZ by removing '%h' (the socket descriptor)
from the above command-lines and changing the access requirements from
"!UNIX" to "UNIX". However, since (l)rzsz comes with most Unix distributions
and works quite well, SEXYZ is not recommended for use on Unix BBSes for the
time-being. See docs/sbbsunix.txt for details on configuring (l)rzsz on
Synchronet if it's not already configured in SCFG:File Options->Transfer
Protocols.


Optional Initialization File (sexyz.ini)
----------------------------------------
If the file sexyz.ini exists in the same directory as the sexyz executable
(e.g. C:\sbbs\exec\sexyz.ini), it will be loaded and used to over-ride the
default operating parameters shown below. Like all Synchronet .ini files,
you can have a unique .ini file for different local systems by embedding
the local hostname (sexyz[.host].ini) or platform (sexyz[.platform].ini)
in the filename. The filenames are *not* case sensitive. Examples:

    C:\sbbs\exec\sexyz.dadscomputer.ini
    C:\sbbs\exec\sexyz.win32.ini
    /sbbs/exec/sexyz.linux.ini

Example .ini file (with default values given):

    Telnet=TRUE                 ; set to FALSE to change the default mode
    TCP_NoDelay=TRUE            ; disable the TCP Nagle algorithm
    Debug=FALSE                 ; enable debug logging
    DebugTx=FALSE               ; debug transmitted characters
    DebugRx=FALSE               ; debug received characters
    DebugTelnet=FALSE           ; debug Telnet commands
    PauseOnExit=FALSE           ; wait for key-press on exit
    PauseOnAbend=FALSE          ; wait for key-press on abnormal exit
    OutbufSize=8192             ; bytes (between 1024 and 65536)
    OutbufHighwaterMark=1100    ; bytes before auto-flush
    OutbufDrainTimeout=10       ; milliseconds before auto-flush
    ProgressInterval=1          ; interval (in seconds) of progress display

    [Xmodem]
    SendTimeout=10  ; seconds
    RecvTimeout=10  ; seconds
    ByteTimeout=3   ; seconds
    AckTimeout=10   ; seconds
    BlockSize=1024  ; 128 or 1024
    MaxErrors=10
    G_Delay=1       ; millisecond yield between sent Ymodem-G blocks

    [Zmodem]
    InitTimeout=10      ; seconds
    SendTimeout=15      ; seconds
    RecvTimeout=20      ; seconds
    CrcTimeout=60       ; seconds
    BlockSize=1024      ; 1024 is usually best to start with
    MaxBlockSize=1024   ; 1024 is "true" Zmodem, 8192 for Zmodem-8K (ZedZap)
    MaxErrors=10        ; maximum number of consecutive errors
    RecvBufSize=0       ; specify non-zero for partial streaming receives
    Streaming=TRUE      ; set to FALSE to disable streaming (block-at-a-time)
    CRC32=TRUE          ; set to FALSE to force CRC-16 instead
    EscapeTelnetIAC=TRUE    ; send ZDLE/ZRUB1 instead of 0xff with -telnet
    Escape8thBit=FALSE      ; ZDLE-escape all bytes with bit-7 set
    EscapeCtrlChars=FALSE   ; ZDLE-escape all control characters (< 20h)


Compatibility
-------------
The Xmodem, Ymodem, and Zmodem file transfers should be compatible with any
terminal programs or remote protocol drivers that conform to the public
specifications for these protocols written by Chuck Forsberg (Xmodem was
actually written by Ward Christensen, but was extended and documented by our
friend, Chuck).

SEXYZ supports the following protocols and their popular permutations:

Xmodem:     128 byte blocks, 8-bit checksum error detection
Xmodem-CRC: 128 byte blocks, 16-bit CRC error detection
Xmodem-1K:  1024 byte blocks, 16-bit CRC error detection
Ymodem:     128 byte blocks, 16-bit CRC error detection, batch file transfers
Ymodem-1K:  1024 byte blocks, 16-bit CRC error detection, batch file transfers
Ymodem-G:   1024 byte blocks, 16-bit CRC error detection, batch file transfers
            and streaming (no acknowledgements)
Zmodem:     1024 byte blocks, 16-bit or 32-bit CRC error detection, batch file
            transfers, resume, auto-download, and more
Zmodem-8K:  8192 byte blocks, 16-bit or 32-bit CRC error detection, batch file
            transfers, resume, auto-download, and more (a.k.a. ZedZap)

If you want the absolute fastest, lowest overhead protocol, use Ymodem-G.

As of this writing, the current version of SEXYZ and the X/Zmodem modules are:

	sexyz.c  1.65
	xmodem.c 1.24	<-- Includes Ymodem
	zmodem.c 1.61

SEXYZ for Win32 has been tested successfully with the following Telnet clinets
/terminal programs:

[ztelnet]
OS: Linux
Version: 1.2.2
URL: ftp://ibiblio.org/pub/Linux/system/network/telnet/
Tested: Zmodem uploads and downloads
Failed: none

[HyperTerminal Private Edition]
By: Hilgraeve, Inc.
OS: Win32
Version: 6.3
URL: http://www.hilgraeve.com/htpe/
Tested: Xmodem (checksum and CRC), Xmodem-1K, Ymodem-1K, Ymodem-G and Zmodem
        both uploads and downloads
Failed: Zmodem uploads (CRC errors detected): appears to be the fault of
        HyperTerminal and can be reproduced with any protocol driver on the 
        BBS/server side (even FDSZ)

[mTelnet]
By: enigma
OS: Win32
Version: 1.0 (beta 12)/w32
URL: http://ozone.eesc.com
Tested: Zmodem uploads and downloads
Failed: none

[NetRunner]
By: Mystic Software Development (James Coyle/g00r00)
OS: Win32
Version: 0.09
URL: www.mysticbbs.com
Tested: Zmodem uploads and downloads
Failed: Zmodem uploads (CRC errors detected): appears to be the fault of
        NetRunner and can be reproduced with any protocol driver on the 
        BBS/server side (FDSZ and CEXYZ both failed in the same manner)

[ZOC]
By: EmTec, Innovative Software, Markus Schmidt
OS: Win32
Version: 5.02
URL: http://www.emtec.com
Tested: Xmodem, Ymodem, Zmodem uploads and downloads
Failed: none


Support
-------
For technical support (including bug reports), see 
http://www.synchro.net/docs/support.html for details.

When submitting problem/bug reports, please include the version output from
"sexyz v" command. We're also very interested in reports of compatibility
(or incompatibility) with terminal programs or telnet clients.


Credits
-------
The Xmodem (a.k.a. MODEM, MODEM2, XMODEM) protocol was originally developed by
Ward Christensen in 1977.

The Ymodem (a.k.a. YMODEM) and Zmodem (a.k.a. ZMODEM) protocols were developed
and documented (poorly) by Chuck Forsberg; Ymodem being primarily a set of
enhancements to Ward's Xmodem protocol. Ymodem-G was also developed by Chuck.

The X/Ymodem code used in SEXYZ was written by Rob Swindell <rob [at] synchro
[dot] net>, migrated from the Synchronet Transfer Protocols (STP) program
circa 1997.

The Unix "stdio" mode support in SEXYZ was written by Stephen Hurd (a.k.a.
Deuce) of Synchronix/FreeBSD Synchronet stardom and "scary code" infamy.

The Zmodem code in SEXYZ is based on zmtx/zmrx v1.02 (C) Mattheij Computer
Service 1994 by Jacques Mattheij <jacquesm [at] hacktic [dot] nl>. Although
SEXYZ's Zmodem code no longer resembles zmtx/zmrx much, it served as a good
starting point, and Jacques' version of Chuck's ZMODEM.DOC was very helpful!

The 16-bit CRC table and calculation macro was (unwittingly) contributed by
Mark G. Mendel and Stephen Satchell.

The 32-bit CRC table and calculation macro was (unwittingly) contributed by
Gary S. Brown.

SEXYZ includes portions of the Synchronet XPDEV and SMBLIB libraries which
are licensed under the GNU Lesser General Public License (LGPL).
http://www.fsf.org/licensing/licenses/lgpl.txt

Synchronet BBS software is written by and copyright 2005 Rob Swindell.
http://www.synchro.net/docs/copyright.html
