XENIA Software Michael Ziegler Jagdfeldring 16 D-85540 Haar, Germany Telephone ++49/89/4602746 GSZRZ ZMODEM Program Package for the ATARI ST/STE/TT/FALCON EXEMPTION FROM LIABILITY ------------------------ The programs have been tested exhaustively. XENIA Software shall not be liable for any damages that result from using programs of the GSZRZ package. If you find an error nevertheless, you can contact XENIA Software using the address given above or the following bulletin board system (BBS) net: - Michael Ziegler @ M in Mausnet SUMMARY ------- The GSZRZ program package comprises the X/Y/ZMODEM file transfer protocols for the ATARI ST/STE/TT/FALCON computers. The programs can be used in conjunction with almost any communication program. The transfer status is displayed in a dialog window. When leaving the program, the final message is written to STDERR output. If GSZRZ is used in conjunction with Michael Bernards' RUFUS or Wolfgang Wander's CoNnect, this message is written to the terminal window. GSZRZ can be used under Multi-TOS and MAG!X, too. FILES ----- The GSZRZ program package consists of these files: GSZRZ_30.PRG ATARI TT/FALCON version of the accessory or GEM program. Cannot be run on the ATARI ST! GSZRZ_ST.PRG ATARI ST version of the accessory or GEM program GSZRZENG.TXT this documentation file HISTORY.TXT GSZRZ history file (only in German) FSER096B.LZH Archive of Franz Sirl's serial patch for the ATARI MegaST/TT SERPTCH2.LZH Archive of ATARI Computer's RTS/CTS patch for the ATARI MegaST/TT HSMODA02.LZH Archive of Harun Scheutzow's excellent serial patch for all ATARIs. The GEM programs can be used as accessory programs by simply renaming the files to an extension ACC. INSTALLATION ------------ The installation depends on the communication program used. Here are some hints for installing with RUFUS. If your computer has enough memory available, you can install GSZRZ as an accessory: Copy GSZRZ_xx.ACC as GSZRZACC.ACC into the root directory, use the slot ZMODEM in RUFUS' dialog box 'Protokoll', and save the parameters using 'Parameter sichern'. If you want to use the TT/FALCON accessory, you have to rename it or enter the line ACCNAME=GSZRZ_30.ACC into the file RUFUS.RUF. This will not be necessary with CoNnect as it can search for the ACC's name. In CoNnect, you simply click on the button 'ACC suchen' in the dialog box Transfer. If GSZRZ_xx.ACC can be found, CoNnect will enter its name accordingly. If you want to use GSZRZ as a PRG, you have to rename the accessory to GSZRZ_xx.PRG and copy it into RUFUS' module directory. In RUFUS' dialog box 'Protokoll', enter a free slot, enter a protocol name, choose type EXTERN. At 'Sender', choose GSZRZxxx.PRG by clicking on the name. At 'Parameter', enter '-sz' and other parameters as needed separated by blanks. Then, at 'Empf„nger', choose GSZRZxxx.PRG by clicking on the name. At 'Parameter', enter '-rz' and other parameters as needed separated by blanks. Save the parameters using 'Parameter sichern'. To use GSZRZ with HARLEKIN III, GSZRZ_xx.ACC has to be renamed to GSZRZACC.ACC and copied into the root directory of the boot partition. In 'Optionen' 'ZMODEM' activate 'externes Modul anwenden'. In 'Senden' and 'Empfangen' you have to enter '-M', at least in HARLEKIN version 3.0 (see TROUBLE.TXT). MultiTOS -------- If You work with MultiTOS and GSZRZ is not used as program and if another serial device then MODEM1 is used, then You must specify parameter -H! COMMAND LINE PARAMETERS ----------------------- Please note that the case of the parameters is important (e.g., '-g' is different from '-G') and always use the parameters exactly as indicated. Multiple parameters have to be separated by blanks (see the examples below). File name have to be given AFTER the last parameter. If you are using CoNnect, the '$' has to be the last character of the parameters for sending. GSZRZ contains routines for sending and receiving. To tell GSZRZ to send or to receive, the FIRST parameter has to be '-sz' or '-rz'. If you are using GSZRZ as an accessory in conjunction with RUFUS or CoNnect, this will be done for you by RUFUS/CoNnect automatically. If you don't specify the parameter '-a', all transfers will be performed in binary mode. GSZRZ' ZMODEM routines default to the fastest transfer rate possible. If the phone line is rather noisy and you don't use MNP/V42, it is safer to specify block acknowledge mode by the parameter '-l 1024' (see parameter -l for sending). This will slow down the transfer somewhat. PARAMETERS FOR RECEIVING ------------------------ Translation of incoming newline characters -a This function is used in transferring ASCII files e.g. from UNIX systems to the ATARI. Incoming newline characters are translated into carriage return/line feed sequences. Include protocol end into CPS rate -A At the end of a file transmission an acknowledge between sender and receiver is done. Some people want to include this in the final calculation of the CPS rate. If -A is set, the last CPS-rate is calculated after the acknowledge. Receive buffer size -b SIZE This parameter is used to specify the size of the receive buffer of the serial interface. SIZE indicates the buffer's size in bytes. The default value of 1024 bytes should be sufficient for most cases. SIZE: default 1024 bytes, minimum 128, maximum 16384 Use CRC with XMODEM -c If this parameter is specified, the XMODEM routines use a 16 bit CRC instead of a simple checksum. While this is safer, don't expect every XMODEM protocol program to be able to work in this mode. Suppress carrier detect -D If this parameter is specified, the monitoring of the carrier detect line will be suppressed. Escaping of control characters -e If this parameter is specified, the 'escaping' of all control characters will be performed. (Often used in UNIX systems) File buffer size -F SIZE This parameter specifies the size of the file buffer. When receiving a file, all incoming characters are stored in a buffer. Whenever this buffer fills, it will be written to the hard disk/floppy disk. As this affects the transfer rate, this buffer's size can be specified. SIZE indicates the size of the buffer in bytes, the suffixes 'K' and 'M' indicate kilobyte and megabyte, e.g. '-F 16K' and '-F 2M'. '-F -1' results in a buffer that uses all available RAM except 100 KB. SIZE: default 8192 bytes, minimum 1024 bytes Stream mode in XMODEM/YMODEM -g If this parameter is specified, XMODEM and YMODEM transfers will use the stream mode, i.e. the acknowledging of each data block will be suppressed. Usually, after receiving every data block an acknowledgement is returned to the sender to signal that the block has been received successfully. If the connection is reliable (MNP5, V42bis), the transfer rate can be increased by omission of the acknowledgement. Audible indication of the end of the transfer -G The end of the transfer will be indicated by an audible signal ('pling'). Serial device -H n With this parameter You can select a serial device. This is usefull, if GSZRZ is used as accessory unter MultiTOS. ST MSTE TT FALCON 1 AUX AUX AUX AUX 3 MIDI MIDI MIDI MIDI 6 MODEM1 MODEM1 MODEM1 - 7 - MODEM2 MODEM2 MODEM2 8 - SERIAL2 SERIAL1 SERIAL2/LAN 9 - - SERIAL2 - Iconify the GSZRZ window on startup -I x,y With this parameter it is possible (only with MultiTOS with AES version > 4.0) to iconify the window of GSZRZ already at startup and position the window at x,y. Log file -L [x:\path\]filename.ext[,level] Log all activities to the file specified. On level 1, when GSZRZ stops it will write an entry to the file specified using the following format: SZ: HISTORY.TXT Len: 20408 Tim: 00.00.18 Err: 0 CPS: x RZ: ANSI.SYS Len: 1709 Tim: 00.00.02 Err: 0 CPS: x ^^ ^ ^ ^ ^ || file name bytes duration error code |X/Y/Z protocol S or R for Send / Receive On level 2, each message displayed on the line 'last status/error' is written to the logfile too. Use MIDI interface -m If this parameter is specified, the transfer will be performed via MIDI interface. If GSZRZ is used as an accessory in conjunction with RUFUS, this parameter is added by RUFUS and must not be specified (see example below). Disable mouse interrupt -M This parameter disables the mouse interrupt during the transfer. Use this parameter if moving the mouse disturbs the file transfer. In addition, this parameter causes the AES multitasking to be disabled to achieve maximum data rates on the ST. Reaction on existing file names In the YMODEM and ZMODEM protocols, the file name is specified by the sender. If a file of that name already exists, the receiver's reaction can be specified. -o FILE.EXT The file name specified by the sender will be replaced by FILE.EXT. CAUTION: You cannot specify a path here! -p The receiver will send SKIP to the sender effecting that the file will not be transferred. CAUTION: lower case 'p'! -E The extension of the ALREADY EXISTING file will be changed to .001, if that one is already existing to .002 etc. -y The already existing file will be deleted. -r If the sender can handle it, a CRC check is done on the existing part of the file. If the CRC's are identically, the transmission is resumed. If the file CRC's are different or the sender can't handle a CRC verification, an alert with the following possibi- lities is displayed: Rename give a new filename for the file to receive Delete delete the existing file Abort abort the receive -rr If the sender can handle it, a CRC check is done on the existing part of the file. If the CRC's are identically, the transmission is resumed. If the file CRC's are different or the sender can't handle a CRC verification, a Resume is done. If none of these parameters are in affect, an alert box is displayed in the way a different CRC is handled. Specify the download directory -P PATH This parameter specifies the target directory. If this parameter has not been specified, all files received will be stored in the current directory. If a file with path affixed to the file name is received, a possible drive specifier will be stripped off. The remaining path will be appended to the current path or, if a path was specified by '-P', to the specified path. Example: Let C:\MAIL\DOWNLOAD be the current directory. Receive a file J:\TEST\XYZ\FILE.EXT. The file stored will be: without '-P': C:\MAIL\DOWNLOAD\TEST\XYZ\FILE.EXT with '-P D:\RECEIVE': D:\RECEIVE\TEST\XYZ\FILE.EXT Non-existent directories will be created. -d If this parameter is specified, possible paths on the incoming file names will be stripped off. This safety precaution should be used with bulletin board systems (BBS). Suppress outputs to STDERR when leaving GSZRZ -q If this parameter is specified, the output of the final message to STDERR will be suppressed. Use this in conjunction with communication programs that do not redirect STDERR. Resume an interrupted transfer -r With this parameter, the sender tells the receiver that it is possible to handle a CRC protected resume. Set the file date -s Set the file date of the file received to the current date. This can be useful in BBS programs. Output the CPS rate to STDERR -S If this parameter is specified, the CPS rate will be written to STDERR at the end of the transfer. Set the time-out time -t TIM This parameter sets the time-out time to TIM/10 seconds. It has been implemented as some BBS take rather long to set up a ZMODEM transfer. Usually, there should be no problems with the default value of 100 (i.e. 10 seconds). Minimum 10, maximum 1000. Protocol for receiving The default protocol used is ZMODEM. If you want to use one of the other protocols, specify one of these parameters: -X Use XMODEM protocol -Y Use YMODEM protocol Checking the on-line time -U time on-line time remaining -C baud rate actual baud rate For the usage in BBS programs, the checking of the on-line time was implemented (key word: "NetCall Hour"). This needs two parameters -C and -U. The value following -C gives the remaining on-line time in seconds. The value following -U gives the actual baud rate. If the remaining time doesn't suffice for an upload, RZ will exit with an exit code 9 and the message 'not enough time for upload'. At that time, no files have been created. If the available on-line time is exceeded, the receive operation will be stopped with an error code 10. The partially received file will be closed, so that the transfer can be resumed later on. Example: -rz -C 19200 -U 100 EXAMPLES -------- Some examples of parameters for RZ: -rz receive using ZMODEM -rz -Y receive using YMODEM -rz -Y -g receive using YMODEM-1k-g -rz -X TEST.XYZ receive using XMODEM. NOTE: a file name MUST be specified as it cannot be transferred by XMODEM! -rz -y -o TEST.XYZ -P D:\MAIL\DOWNLOAD receive using ZMODEM, carrier detect disabled, target directory specified, file name specified, delete possibly existing file -rz -m receive via MIDI interface -rz -m -b 8192 -l 8192 receive via MIDI. The Rx buffer has to be set to 8 KB if you are using 8 KB blocks to avoid buffer overflow. PARAMETERS FOR SENDING ---------------------- REMEMBER: Please remember to specify the file name(s) after all the parameters have been given. Append to existing file -+ The receiver should append the file transferred to an existing file (ZMODEM only). ASCII Transfer -a ASCII Transfer. The receiver has to translate CR/LF (ZMODEM only) Include protocol end into CPS rate -A At the end of a file transmission an acknowledge between sender and receiver is done. Some people want to include this in the final calculation of the CPS rate. If -A is set, the last CPS-rate is calculated after the acknowledge. Suppress break -b At a retry, NO break will be sent to the modem (ZMODEM only). Usually, a break is sent to the modem at a block retry operation to empty the modem's buffer. Conversion of '.' -d Dots '.' in path names are converted to slashes '/' (Y/ZMODEM only). This is useful if the receiver isn't able to handle dots in file names. Suppress carrier detect -D If this parameter is specified, the monitoring of the carrier detect line will be suppressed. Escaping of control characters -e If this parameter is specified, the 'escaping' of all control characters will be performed as it is usually done on UNIX systems. Send path name to the receiver -f If this parameter is specified, the full path name is transmitted together with the file name (ZMODEM only). Note that '\' is converted to '/' as noted in the Zmodem Specification. Some Zmodem programs on PC's cannot accept this conversion! File buffer size -F SIZE This parameter specifies the size of the file buffer. When sending a file, this buffer is filled by reading from hard disk/floppy disk. SIZE indicates the size of the buffer in bytes, the suffixes 'K' and 'M' indicate kilobyte and megabyte, e.g. '-F 16K' and '-F 2M'. '-F -1' results in a buffer that uses all available RAM except 100 KB. SIZE: default 8192 bytes, minimum 1024 bytes Audible indication of the end of the transfer -G The end of the transfer will be indicated by an audible signal ('bell'). Serial device -H n With this parameter You can select a serial device. This is usefull, if GSZRZ is used as accessory unter MultiTOS. ST MSTE TT FALCON 1 AUX AUX AUX AUX 3 MIDI MIDI MIDI MIDI 6 MODEM1 MODEM1 MODEM1 - 7 - MODEM2 MODEM2 MODEM2 8 - SERIAL2 SERIAL1 SERIAL2/LAN 9 - - SERIAL2 - Iconify the GSZRZ window on startup -I x,y With this parameter it is possible (only with MultiTOS with AES version > 4.0) to iconify the window of GSZRZ already at startup and position the window at x,y. Block size for XMODEM/YMODEM -k Send 1024 byte packages. The X/YMODEM default value is 128 bytes. Request receiver acknowledge -l N Request an acknowledge from the receiver after N bytes (32 <= N <= 1024, 8192 if parameter -8 is used) have been transferred (ZMODEM only). The ZMODEM default is to use stream mode, i.e. the sender will send data blocks continuously and will be requested to repeat blocks in cases of errors only. This results in an increased data rate in the stream mode. If no hardware handshake is possible (e.g. MIDI interface), this parameter forces a software handshake to be performed. Use MIDI interface -m If this parameter is specified, the transfer will be performed via the MIDI interface. If GSZRZ is used as an accessory in conjunction with RUFUS, this is the default and this parameter need not be specified (see example below). As the MIDI interface does not have handshake lines, a software handshake has to be requested by specifying the parameter '-l 1024' or '-l 8192' if parameter -8 is used. Disable mouse interrupt -M This parameter disables the mouse interrupt during the transfer. Use this parameter if moving the mouse disturbs the file transfer. In addition, this parameter causes the multitasking to be disabled to achieve maximum data rates on the ST. Conditional transfer -n Send file only if it is newer or longer than the one that already exists at the receiver (ZMODEM only). -N Send file only if it has a different file date or is longer than the one that already exists at the receiver (ZMODEM only). 16 Bit CRC -o Use 16 Bit CRC only for ZMODEM transfers. Saves 2 bytes per block transferred. Some older ZMODEM programs use nothing but 16 Bit CRC. Protect an existing file -p If the file to be transferred already exists at the receiver, the transfer will NOT be performed (ZMODEM only). Suppress outputs to STDERR when leaving GSZRZ -q If this parameter is specified, the output of the final message to STDERR will be suppressed. Use this in conjunction with communication programs that do not redirect STDERR. Resume an interrupted transfer -r If this parameter is specified, the receiver is told that the sender is able to resume a partial transfer (ZMODEM only). Use script file for sending -s FILE.EXT The names of the files to be transferred are being read from the script file FILE.EXT (ZMODEM only). Useful for transferring the same files repeatedly. Output the CPS rate to STDERR -S If this parameter is specified, the CPS rate will be written to STDERR at the end of the transfer. Set the time-out time -t TIM Sets the time-out time to TIM/10 seconds. This is the time that will be waited for an answer from the receiver until an error is assumed. Usually, there should be no problems with the default value of 600 (i.e. 60 seconds). Minimum 10, maximum 1000. Delete file after transfer -u The file to be transferred will be deleted after the transfer has ended. Replace existing file -y The receiver will replace a file of the same name that possibly already exists with the file transferred (ZMODEM only) Protocol for sending The default protocol used is ZMODEM. If you want to use one of the other protocols, specify one of these parameters: -X Use XMODEM protocol -Y Use YMODEM protocol Checking the on-line time -U time on-line time remaining For the usage in BBS programs, the checking of the on-line time was implemented. The value following -C gives the remaining on-line time in seconds. If the available on-line time is exceeded, the send operation will be stopped with an error code 10. Example: -sz -U 100 Transfer big blocks -8 Use 8 KB blocks for transfer. CAUTION: Don't expect to find many ZMODEM programs that can use this option at the other end of the line! EXAMPLES -------- Some examples of parameters for sending: -sz TEST.XYZ send using ZMODEM -sz *.C *.H send all files with extensions .C and .H using ZMODEM -sz -Y TEST.XYZ send using YMODEM -sz -Y -k TEST.XYZ send using YMODEM-1k-g -sz -X TEST.XYZ send using XMODEM -sz -8 TEST.XYZ send using ZMODEM in 8 KB blocks -sz -m -l 1024 TEST.XYZ send via MIDI interface If the receiver uses GSZRZ, too, you can use 8 KB block transfers via MIDI interfaces, too, by specifying -sz -m -8 -l 8192 TEST.XYZ The receiver has to use these parameters: -rz -m -b 8192 EXIT CODES ---------- When exiting from the program, GSZRZ returns one of the following exit codes to the caller: 1 Argument error, command line parameters wrong, file not found 2 Initialization error (graf_handle, appl_init) 3 User break by entering Ctrl-C or clicking on 'closers' 4 Memory allocation error, not enough memory 5 Carrier lost 8 Invalid structure pointer (see ACC protocol) 9 Not enough time for upload 10 Time limit exceeded 11 No/wrong port handle 12 Disk full 16 Cancel received Aborted by other side 128+ Transfer error (for example, if 4 files are to be transferred and the receiver skips 2 files, 128 + 2 = 130 is returned. If no sync is established, 128 is returned) ACC PROTOKOLL OF GSZRZ ----------------------- GSZRZ used as an ACC is addressed using a special protocol via the application message function of GEM. msgbuf[0] contains an ID of the ACC protocol. It consists of the letters 'GZ'. i.e. the hex value 0x475A. msgbuf[1] contains the application ID, i.e. the value that is returned by appl_init(). msgbuf[2] always has to be 0. msgbuf[3] contains the length of the command line string. msgbuf[4] the lower 16 bits of the pointer to the command line string. msgbuf[5] the upper 16 bits of the pointer to the command line string. The command line string has to be terminated by 0x00. It contains the usual switches as in calls to the PRG, e.g. "-rz -D -P C:\\DOWNLOAD" RETURN CODES ------------ At exit, GSZRZ returns the following values to the calling program: msgbuf[0] = GZ_PRIVATE; msgbuf[1] = appl_id; msgbuf[2] = Exitcode; msgbuf[3] = (int) strlen(message); msgbuf[4] = (unsigned int) ((long) message & 0XFFFF); msgbuf[5] = (unsigned int) ((long) message >> 16); msgbuf[6] = 0; msgbuf[7] = 0; appl_write(msgbuf[1], 16, txmsgbuf); 'message' is a pointer to a string, that is written to STDOUT when exiting the program. RUFUS/CoNnect causes this string to be displayed as a GSZRZ message in the communication window. 'Exitcode' contains GSZRZ's return code. RTS/CTS HANDSHAKE ----------------- As the GSZRZ programs use the ST/TT's operating system routines, the RTS/CTS handshake has to be performed by the communication program (e.g. RUFUS) or using the control area. Because the TOS routines are faulty even in TOS 1.04 and TOS 3.05, a patch has to be installed. With the ATARI ST, I can recommend HSMODEM1 by Harun Scheutzow. With the TT, SERPTCH2 by ATARI is recommended, because it will repair all interfaces. With TOS 3.06, SERPTCH2 should no longer needed. SHAREWARE VERSIONS ------------------ The Shareware-Version of GSZRZ is restricted in some functions. The user can evaluate the programs for 3 weeks, copy them freely, and share them with other users. All registered versions are for single users and MUST NOT be copied and handed on to other users. If you use these programs more than 3 weeks, you MUST pay a ONE-TIME fee of DM 30.00 to the author (XENIA Software, Michael Ziegler). This fee is to be paid ONCE ONLY and even entitles you to use future versions of GSZRZ. If you pay via remittance order from abroad, please don't forget that the banks may subtract fees of up to DM 12.50. In Europe, the best way is to pay with an Euro-Cheque. THANKS TO --------- I would like to thank the many beta tester, especially: Jrgen Meyer and Carsten Meyer (Maus @HH2) for the devoted testing, Michael Bernards for the support by RUFUS, Wolfgang Wander for the support by CoNnect, Achim Wilhelm for supporting me in searching for bugs in the FALCON-TOS, Harun Scheutzow for the best RTS/CTS patch for serial devices on ATARI computers I ever seen. all users of GSZRZ whose suggestions and advice on new features further the development of the GSZRZ ZMODEM program package. UPDATE SERVICE -------------- For registered users of GSZRZ only, an update service has been installed in several bulletin board systems (BBS). Please allow for about 2 - 3 weeks after registration until you can use this service. The files containing the registration data in the BBS are updated irregularly. This service is free of charge. It has been established on request by BBS operators. Therefore, I cannot guarantee that this service and the latest version of the GSZRZ program package will be available at all times. For updating, you need the serial number of your GSZRZ program package. You can find it in the file SERIAL.NUM on your registered diskette. After logging on to the BBS, call the updater from the menu. The updater will answer with the following message in German: >> Registering GSZRZ-Files V 2.6 (c) 1991, 1992 mz << A C H T U N G: Nur fr REGISTRIERTE Benutzer erlaubt! aktuelle Version x.yy downloaden ? (J/N) Vorname: Nachname: Seriennummer: In English, this would read: >> Registering GSZRZ Files V 2.6 (c) 1991, 1992 mz << C A U T I O N: for REGISTERED users only download current version x.yy ? (Y/N) first name: last name: serial number: After you have entered the data requested, the updater will produce a version registered to you, compress it and send it to you using YMODEM or ZMODEM, whatever you choose. Please take care to enter the first and last names exactly as they are displayed in the dialog window or your request to update will be rejected. This update service is currently offered by the following German bulletin board systems (BBS): ------------------------------------------------------------------------ BBS : Turbo Tron Hamburg Baud rate : 2400 - 14400 V32 V32bis Telephone : ++49 / 40 / 890 11 62 Updater : Enter: GSZRZ,UPDATER or GSZ Download times : 00:00 - 08:00 CET ------------------------------------------------------------------------ BBS : Tuma Box Augsburg Baud rate : 1200 - 19200 V32 V32bis ZyXel-Mode Telephone : ++49 / 821 / 66 77 66 Updater : Enter: GSZRZ,UPDATER or GSZ Remarks : You can download one file per login, if you want more, you'll have to register ------------------------------------------------------------------------ ADDRESS BANK ACCOUNT ------- ------------ XENIA Software XENIA Software Michael Ziegler Michael Ziegler Jagdfeldring 16 Kreissparkasse Mnchen, Germany D-85540 Haar, Germany Bank Number: 702 501 50 Telephone ++49/89/4602746 Account Number: 420354680 ----------------------------------------------------------------------