SEXYZ

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

Overview

SEXYZ was developed as a native (32-bit or 64-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 32-bit BBSes for FAR too long.

While SEXYZ was designed with Synchronet BBSes in mind, it should also work with other 32-bit 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:

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

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

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

Distribution

SEXYZ is freeware, licensed under the GNU General Public License (GPL) with portions licensed under the GNU Lesser General Public License (LGPL).

You can find the current source code (in C) in the Synchronet 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:

SEXYZ can also be built from the C source code for use (natively) on Linux and other Unix variants (e.g. FreeBSD).

For a client implementation of SEXYZ, use the SyncTerm Telnet/RLogin/SSH terminal program (http://syncterm.net/), available for many platforms, including Win32, *nix, and Mac OS-X.

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 (leave blank for stdio mode)

opts   = -y  allow overwriting of existing files when receiving
         -k  enable X/YMODEM-1K send mode
         -c  enable XMODEM-CRC receive mode
         -g  enable X/YMODEM-G receive mode (no error recovery)
         -o  disable ZMODEM CRC-32 mode (use CRC-16)
         -s  use segmented ZMODEM (disable streaming)
         -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)
         -w# set maximum ZMODEM transmit window size (default=0, unlimited)
         -m# set maximum receive file size to # bytes (default=0, unlimited)
         -l  lowercase received filenames
         -!  to pause after abnormal exit (error)
         -telnet to enable Telnet mode (the default except in stdio mode)
         -rlogin or -ssh or -raw to disable Telnet mode

cmd    = v  to display detailed version information
         sx to send XMODEM     rx to receive XMODEM
         sX to send XMODEM-1K  rc to receive XMODEM-CRC
         sy to send YMODEM     ry to receive YMODEM
         sY to send YMODEM-1K  rg to receive YMODEM-G
         sz to send ZMODEM     rz to receive 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.

RZ/SZ Style

SEXYZ also supports “rz/sz style” command-line syntax for some commands.

Examples:

rz/sz style Operation Protocol Same As
sexyz -c rx receive XMODEM-CRC sexyz rc
sexyz -k sx send XMODEM-1K sexyz sX
sexyz rb receive YMODEM sexyz ry
sexyz -k sb send YMODEM-1K sexyz sY
sexyz -g ry receive YMODEM-G sexyz rg
sexyz -g rx receive XMODEM-G

Install

Copy sexyz[.exe] into your Synchronet exec directory, if it's not already. Installation for other uses/systems likely just means copying the executable file somewhere that may be invoked from the application or server as needed.

Configure

Synchronet

In Synchronet v3.14+ SCFG:File Options->Transfer Protocols:

[File Transfer Protocol]
 1: Mnemonic (Command Key)        X
 2: Protocol Name                 XMODEM-Original (SEXYZ)
 3: Access Requirements           
 4: Upload Command Line           %!sexyz%. %h -%p rx %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
11: Socket I/O                    Yes

[File Transfer Protocol]
 1: Mnemonic (Command Key)        1
 2: Protocol Name                 XMODEM-1K/CRC (SEXYZ)
 3: Access Requirements           
 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
11: Socket I/O                    Yes

[File Transfer Protocol]
 1: Mnemonic (Command Key)        Y
 2: Protocol Name                 YMODEM (SEXYZ)
 3: Access Requirements           
 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
11: Socket I/O                    Yes

[File Transfer Protocol]
 1: Mnemonic (Command Key)        G
 2: Protocol Name                 YMODEM-G (SEXYZ)
 3: Access Requirements           
 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
11: Socket I/O                    Yes

[File Transfer Protocol]
 1: Mnemonic (Command Key)        Z
 2: Protocol Name                 ZMODEM (SEXYZ)
 3: Access Requirements           
 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
11: Socket I/O                    Yes

Optional/Advanced

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

[File Transfer Protocol]
 1: Mnemonic (Command Key)        S
 2: Protocol Name                 ZMODEM-Synchronous(SEXYZ)
 3: Access Requirements           
 4: Upload Command Line           %!sexyz%. %h -%p rz %f
 5: Download Command Line         %!sexyz%. %h -%p -s sz %f
 6: Batch Upload Command Line     %!sexyz%. %h -%p rz %g
 7: Batch Download Command Line   %!sexyz%. %h -%p -s sz @%f
 8: Bi-dir Command Line
 9: Native (32-bit) Executable    Yes
10: Supports DSZLOG               Yes
11: Socket I/O                    Yes

NOTE: It is suggested you remove existing FDSZ, CE-XYZ, or sz/rz transfer protocol entries as they are no longer needed.

Synchronet for Unix

Synchronet for Unix (prior to v3.14) did not support socket-based file transfer protocols, so SEXYZ is only currently supported on Synchronet for Unix (v3.13 and older) in “stdio” mode.

You can use “stdio” mode in SEXYZ by removing '%h' (the socket descriptor) from the above command-lines. If you're using Synchronet for Unix v3.14 or later, socket I/O mode is preferred (do not use “stdio” mode).

Mystic

Example configuration for Mystic BBS v1.08-Win32 (provided by Dream Master and Jack Phlash)

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

EleBBS

Example configuration for EleBBS-Win32 (provided by Mike Ehlert, aka pcm)

Name            ZMODEM (SEXYZ)
Key             Z
Ext ctl file    No
Batch           Yes
Status          Always available
Log file        DSZ.LOG
Control file    DSZ.CTL
DL command line c:\bbs\sexyz.exe *W -quotes sz @DSZ.CTL
UL command line c:\bbs\sexyz.exe *W -quotes rz
DL ctl string   @
UL ctl string   @
DL log keyword  z
UL log keyword  Z
Log name word   10
Log desc word   0

You will need to have the environment variable DSZLOG set to DSZ.LOG. It should *not* have a path of course, so that it's created in the current node's directory.

Once you define that under control panel > system > env variables > system variables, be sure to close the window running eleserv or telsrv and reopen it for the environment variable to become active.. Otherwise there will be no log of the transfer and EleBBS will assume it failed.

Note: To support long filenames with EleBBS, you'll need Sexyz v1.74 or later and set Quotes=true in the [DSZLOG] section of your sexyz.ini file or use the secret -quotes command-line option.

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
LogLevel=INFO               ; set display/log output level
SysLog=FALSE                ; log to syslog (*nix only)
Debug=FALSE                 ; enable debug logging (overrides LogLevel)
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=16384            ; 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
MaxFileSize=0               ; maximum receive file size in bytes (0=unlimited)
 
[XMODEM]
SendTimeout=10      ; seconds
RecvTimeout=10      ; seconds
ByteTimeout=3       ; seconds
AckTimeout=10       ; seconds
BlockSize=1024      ; 128 or 1024
MaxBlockSize=1024   ; 128 or 1024   
MaxErrors=9
G_Delay=1           ; millisecond yield between sent X/YMODEM-G blocks
SendG=TRUE          ; Support G-mode for X/YMODEM sends
SendCRC=TRUE        ; Support CRC-16 error detection for X/YMODEM sends
 
[YMODEM]
FallbackToXMODEM=0  ; Failed send attempts before falling back to XMODEM
 
[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=9         ; maximum number of consecutive errors
RecvBufSize=0       ; specify non-zero for segmented receives
Streaming=TRUE      ; set to FALSE to disable streaming (segmented receives)
CRC32=TRUE          ; set to FALSE to force CRC-16 instead
FullDuplex=TRUE     ; set to FALSE to disable window support (on receive)
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)
MaxWindowSize=0         ; Set to non-zero number of bytes to use window management
TargetWindowSize=0      ; Set to a duration (e.g. in seconds) to enable auto-adjusting window size
 
[DSZLOG]
Path=true           ; include full path to filename in log
Short=false         ; use Micros~1 short path/filename in log (Windows)
Quotes=false        ; enclose filename in "quotes" (for EleBBS)
 
[SOCKOPTS]

Notes:

  • The defaults and sexyz.ini specified values can be over-ridden via command-line options.
  • Older versions of SEXYZ did not support comments on some of the sexy.ini lines shown above.
  • See ctrl/sockopts.ini for the Socket Options that can be set in the [SOCKOPTS] section.
  • Versions of SEXYZ prior to 3.0 recognized a global TCP_NODELAY key. Now that key, if it is to be set, must be in the optional [SOCKOPTS] section (for advanced uses only).

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 by others and documented by our good 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
XMODEM-G 1024-byte blocks, 16-bit CRC error detection, and streaming (no acknowledgements or error recovery) (a.k.a. QMODEM-G)
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 or error recovery)
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)

SEXYZ will automatically fall back from 1024-byte block XMODEM/YMODEM send mode to 128-byte block XMODEM/YMODEM send mode if the receiver does not appear to support 1024-byte blocks.

SEXYZ also supports automatically falling back from XMODEM/YMODEM-CRC to XMODEM/YMODEM-Checksum mode when sending to a receiver that does not support CRC-16 error detection.

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

ztelnet

HyperTerminal Private Edition

  • By: Hilgraeve, Inc.
  • OS: Win32
  • Version: 6.3
  • 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
  • Tested: ZMODEM uploads and downloads
  • Failed: none

NetRunner

  • By: Mystic Software Development (James Coyle/g00r00)
  • OS: Win32
  • Version: 0.09
  • 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
  • Tested: XMODEM, YMODEM, ZMODEM uploads and downloads
  • Failed: none

ZMODEM Streaming

The ZMODEM protocol supports multiple methods of data streaming and error recovery. SEXYZ supports the following ZMODEM streaming modes, in order of decreasing successful data transfer assurance:

  • Segmented: a “block at a time” mode, each data subpacket acknowledged by the receiver (whom can request this mode). Can be enabled when sending via the -s option or by setting Streaming=false in sexyz.ini.
  • Window Management: limiting the amount of data “in-flight” between the sender and receiver using asynchronous status reporting by the receiver. Can be controlled when sending via the -w option or by setting MaxWindowSize (and optionally TargetWindowSize) in sexyz.ini.
  • Full Streaming: the default, subject to large send-buffering on the sending side potentially resulting in failed error-recovery or completion-acknowledgment timeouts.

Window Management mode was added in SEXYZ v3.0 to support very asymmetric send-operations where the sender is a modern system, potentially with multiple-megabyte send-buffers, sending to a receiver that can only consume data at a rate of 115200bps (about 10KBytes/second) or less.

Support

For technical support (including bug reports), see support for details.

When submitting problem/bug reports, please include the version output from the 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) protocol was originally created by Ward Christensen in 1977.
  • The XMODEM-CRC protocol (XMODEM derivative using a 16-CRC for error detection rather than XMODEM's 8-bit checksum) was created by John Mahr.
  • The YMODEM, YMODEM-G and ZMODEM protocols were created and documented by Chuck Forsberg; YMODEM being primarily a set of enhancements to Ward's XMODEM and Mahr's XMODEM-CRC protocols.
  • The X/YMODEM code used in SEXYZ was written by Rob Swindell, migrated from the Synchronet Transfer Protocols (STP) program circa 1997.
  • The Unix “stdio” mode support and other optimizations in SEXYZ were written by Stephen Hurd 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 project (e.g. XPDEV) which are licensed under the GNU Lesser General Public License (LGPL).

See Also

util/sexyz.txt · Last modified: 2023/12/22 12:16 by digital man
Back to top
CC Attribution 4.0 International
Driven by DokuWiki Recent changes RSS feed Valid CSS Valid XHTML 1.0