X-FTS - X-Modem protocol File Transmission System TABLE OF CONTENTS General Information 1 Invoking X-FTS 2 Using X-FTS 3 X-FTS Parameters 5 RS-232 Parameter Settings 7 JCL Execution of X-FTS 7 Using Filters on the RS-232 Device 7 Operating System Peculiarities 7 X-FTS/CMD: Copyright 1984 by Rick C. Francis, All rights reserved. X-FTS is published by MISOSYS, Inc., Sterling VA 22170. LDOS and LS-DOS are trademarks of Logical Systems Inc. TRSDOS is a trademark of Tandy Corp. DOS PLUS is a trademark of Micro Systems Software General Information This documentation covers the Model I/III version of X-FTS which functions under the LDOS 5.1 operating system. It also covers the TRSDOS 6.x or LS-DOS 6.x version of X-FTS called PRO-X-FTS. The PRO version also operates under DOS PLUS IV. The specific version of X-FTS is noted on the diskette label supplied with this package. X-FTS provides the user with a communications tool to transmit and receive disk files via an industry standard protocol which effectively supports error-free transmission. Invoking X-FTS X-FTS is a general purpose file transmission utility for use with LS-DOS 6.X, TRSDOS 6.X and DOS PLUS IV (PRO-X-FTS), or LDOS 5.1 (X-FTS). It allows you to send any file to another computer error-free via the RS-232. The program is compatible with the Christensen or XMODEM protocol which is very popular with CP/M and MS-DOS users. The syntax is: FTS x filespec (parameters) FTS *x filespec (parameters) x S to send or R to receive *S or *R Forces JCL mode of execution filespec Name of file to send or receive Parameters: ABS=sw If specified in receive mode, existing files will be replaced without prompting. Default is OFF. BLOCK=b Specifies the size (in bytes) of the data blocks. Default is 128. DEVICE=s Specify alternate RS-232 device. Default is "CL". EOF=sw If specified in send mode, the end-of-file will be properly maintained to the byte level. Default is OFF. FAST=sw Turns interrupts off during block receive for high baud rates. Default is OFF. KEY=b Specifies a data encryption key. Default is 0 (no encryption). LRL=b In receive mode this value will be used as the Logical Record Length for new files. Default is 0 (256 byte LRL). Parameters continued on next page. NOTIFY=b Specifies the number of audible beeps to sound when the program terminates. Default is 0. If given without a value, 3 is used. QUIET=sw If specified, nothing will be on the screen during file transfer. Default is OFF. RETRY=b Specifies the maximum number of retries allowed on one block. Default is 9. Abbr: All parameters except ABS may be abbreviated to one letter. Notes: - "sw" is a switch value (ON or OFF). - "b" is a byte value in the range 0 to 255. - "s" is a string (i.e. "CL" or "*CL"). - NOTIFY not supported under LDOS 5.1. - ABS and LRL valid in receive mode only. - EOF valid in send mode only. - For Christensen protocol, use default for BLOCK and EOF. Using X-FTS X-FTS may be used to transfer any file to another computer provided that the other computer is running X-FTS or a compatible program. We will refer to your computer as the "local" computer and the other computer as the "remote" computer. The two computers may be side-by-side connected directly to each other with an RS-232 cable or they may be hundreds of miles apart connected by telephone lines. For simplicity, we'll assume that both computers are running TRSDOS 6.2 with X-FTS and that they are connected with 300 baud modems. Suppose we want to send the file "MYFILE/DAT" from the local computer to the remote computer: 1. LOCAL: SET *CL COM REMOTE: SET *CL COM 2. LOCAL: SETCOM (B=300,P=OFF,S=1,W=8) REMOTE: SETCOM (B=300,P=OFF,S=1,W=8) 3. LOCAL: COMM *CL REMOTE: LINK *KI *CL and LINK *DO *CL The remote computer is now set up as a "HOST" computer and the local computer acts as a terminal to the remote. The local user can now give commands to the remote computer and see the results as though he were using the remote computer, directly. From this point on, the transfer of files can be totally controlled by the local user. The following commands are issued by the local user: 4. FTS R MYFILE/DAT (QUIET) 5. <0> (COMM function to enter system command) 6. FTS S MYFILE/DAT The file transfer will now take place. During the transfer, the local computer's screen will show the number of each block as it is transferred. It will also indicate the number of errors detected during the transfer. Each time an error is detected, the block is re-transmitted until the block is sent error-free. When the file transfer is complete, the local computer will be returned to the COMM program, and the remote computer will return to TRSDOS Ready. Under LDOS 5.1, the command sequence above would be as follows: 1. LOCAL: SET *CL RS232x (B=300,W=8,P=OFF,S=1) REMOTE: SET *CL RS232x (B=300,W=8,P=OFF,S=1) 2. LOCAL: LCOMM *CL REMOTE: Same as step 3 above. The local computer now controls the transfer of files. 3. FTS R MYFILE/DAT (QUIET) 4. <=> (Exit LCOMM to LDOS Ready) 5. FTS S MYFILE/DAT 6. LCOMM *CL In step 1, RS232x should be replaced with the RS-232 driver name appropriate for your computer (RS232T, RS232R, RS232M, or RS232L for the Model III, Model I R/S interface, MAX-80, or Model I LX-80 interface, respectively). X-FTS Parameters ABS When receiving files with X-FTS, this parameter may be used to force X-FTS to replace an existing file without prompting the user. The ABS parameter defaults to "OFF" unless X-FTS is running in JCL mode in which case it defaults to "ON". When sending files, this parameter has no effect. BLOCK The BLOCK parameter allows the user to set the size, in bytes, of the data blocks. The sending and receiving side must use the same value for this parameter. The default block size is 128. This is the block size used by the XMODEM protocol. DEVICE X-FTS normally uses the device "*CL" for RS-232 communications. If you use a different device name for the RS-232, you must specify this with the DEVICE parameter. Under DOS PLUS IV, the RS-232 device is defined as "@RS" and the DEVICE parameter has no effect. EOF The CP/M operating system does not maintain its end-of-file marker down to the byte level. CP/M files are always some integer multiple of 128 bytes. Usually, a CONTROL-Z is used to mark the end of a text file but binary files have no byte-level EOF marker. The XMODEM protocol was first designed for CP/M systems so it provides no method of maintaining the EOF to the byte level. Under the TRSDOS family of operating systems, byte level EOF is maintained in the directory. By using the EOF parameter on the sending side, X-FTS will maintain the EOF marker during the transfer. EOF mode detection is automatic on the receiving side. The EOF parameter defaults to "OFF". FAST During block transfer, X-FTS normally allows interrupts to occur. This keeps the system clock accurate and allows for BREAK key detection. For high speed transfers, the RTC interrupt can cause characters coming from the RS-232 to be lost. Use the FAST parameter to cause X-FTS to disable interrupts during block receive. CAUTION: using the FAST parameter will cause the system clock to lose time and will make BREAK key detection sluggish. The FAST parameter has no effect in send mode. Note: Due to the nature of the RS-232 driver for the Model III and MAX-80 (under LDOS 5.1), the FAST parameter must NOT be used. These drivers, with their large (128 byte) interrupt driven RS-232 buffer, will have no problem with high-speed transfers (9600 baud or less). KEY The KEY parameter can be used to encode data being sent or decode data being received. If it is necessary to use a public access bulletin board to send a private file to another user, the sender can encode the file with KEY=N where N is a number from 1 to 255. At some later time, the receiver can download the private file from the bulletin board using the same KEY value used to send the file. The data encryption method is a very simple one and could be broken fairly easily. However, it should deter the casual snoop. The default value for KEY is 0 which produces no encryption. LRL The XMODEM protocol provides no means of passing file attributes (i.e. protection level, logical record length, visible/in visible status, etc.) from the sender to the receiver. The LRL parameter is used in receive mode to set the logical record length of the received file which did not already exist on the receiver's system. This value can be obtained from the sender's directory. The default value for LRL is 0 (256 byte logical record length). The LRL parameter has no effect in send mode. NOTIFY If the NOTIFY parameter is specified, X-FTS will provide an audible indication of the transfer status at the termination of the transfer. If the file transfer was successful, the beep(s) will be short and high pitched. If the file transfer was aborted due to some error, the beep(s) will be of longer duration and lower pitch. This parameter is ideal for long files or for multi-file JCL controlled transfers. The NOTIFY parameter defaults to "OFF" if it is left out of the parameter list. If NOTIFY is specified with no value or if NOTIFY=ON is specified, then NOTIFY defaults to 3 beeps. Any value from 0 to 255 may be specified. NOTE: This parameter is not supported under LDOS 5.1 QUIET When X-FTS is running on a "HOST" computer, output sent to the display also goes to the RS-232 device. Since X-FTS normally displays the block number and error count on the screen, this information would be intermixed with the data being sent to the RS-232. Therefore, when X-FTS is being run on a computer in host mode, this parameter must be specified to prevent this intermixing of data. Since X-FTS will be used quite often by a computer running in host mode, it is set-up to allow the user to change the program to force QUIET mode to default to "ON". Simply COPYing FTS/CMD to XFTS/CMD (or RENAMEing FTS/CMD to XFTS/CMD) will cause X-FTS to default to QUIET mode. To avoid using the QUIET parameter, use XFTS/CMD in host mode, and FTS/CMD when not in host mode. With either program, you can override the default by explicitly specifying the QUIET option. RETRY The RETRY parameter allows the user to set the maximum number of attempts that should be made in sending any one block before the transfer is aborted. This parameter also directly affects the amount of "silence" that can occur between blocks before X-FTS declares a "time-out error". The default value for this parameter is 9 which allows up to nine attempts to send a particular block and allows about 25 seconds of delay between blocks. Specifying RETRY=0 will allow an infinite number of block-send attempts and about 6400 seconds of delay between blocks. RS-232 Parameter Settings X-FTS uses a binary transfer protocol so any byte value from zero to 255 (decimal) is perfectly valid. Therefore, the RS-232 hardware must be set for 8-bit word size, and no parity. Number of stop bits and baud rate are not critical to the operation of X-FTS. JCL Execution of X-FTS X-FTS may be used within a JCL file to transfer several files without operator intervention. X-FTS detects that JCL execution is active and modifies its execution somewhat. During JCL execution, nothing will be sent to the screen including the start-up banner. You may override this with the the parameter "QUIET=N". A simple JCL procedure could be created using the PARMDIR program from MISOSYS to allow single command multi-file transfers. (See MFTS/JCL on the distribution diskette). Using Filters on the RS-232 Device Any filtering of the data input from or output to the RS-232 device, will interfere with the proper operation of X-FTS. PRO-X-FTS will detect the presence of any filter(s) and will skip past each filter in the device chain until it finds the actual RS-232 driver. Under LDOS 5.X, there must be no filter on the RS-232 device during the X-FTS transfer. Operating System Peculiarities TRSDOS 6.2 Under TRSDOS 6.2, the COMM program uses only the hardware interrupt function provided by the Radio Shack RS-232 interface to receive incoming characters. On entry to X-FTS, the COMM interrupt function is disabled -so that no characters are "stolen" by the COMM program. Since PRO-X-FTS uses the Library Overlay Region of memory (x'2600' - x'3000'), it can be executed from within COMM by pressing the three keys , , and <0> together. When the transfer is complete, control will be returned to COMM. TRSDOS 6.1 & 6.0 Prior to TRSDOS 6.2, the COMM program used a combination of hardware interrupts and real time clock interrupts to pickup characters from the RS-232. Because of this, X-FTS can not be executed from within COMM. You must exit COMM and execute X-FTS then return to COMM after the file transfer is complete. When receiving files under these versions of TRSDOS, key detection will seem sluggish. Since there is no way to disable KFLAG$ support (when a 80H is received from the RS-232, a system is simulated) under these systems, key detection is turned off during block receive so that if the file being received contains a byte equal to the current SETCOM (BREAK=value), the transmission won't be terminated. Under all versions of TRSDOS 6, X-FTS may be executed during the execution of a BASIC program with the SYSTEM command: SYSTEM "RUN FTS R filename (parameters)" DOS PLUS IV The most common terminal program used under DOS PLUS is the MTERM program sold by Micro Systems Software. Unfortunately, this program uses the RTC interrupt to receive RS-232 characters. X-FTS can not be executed from within MTERM. As with the COMM program on TRSDOS 6.1 & 6.0, you must exit MTERM to execute X-FTS. Under DOS PLUS, X-FTS may be executed from within a running BASIC program with the SYSTEM command, however the DOS library command "RUN" does not exist under DOS PLUS and is not needed: SYSTEM "FTS R filename (parameters)" LDOS 5.1.X The LCOMM terminal package supplied with LDOS 5 does not have the provision for executing a DOS command while running LCOMM. Therefore, you will have to exit LCOMM to execute X-FTS and then return to LCOMM when the file transfer is complete. Do not specify the BREAK parameter when you invoke the RS232x/DVR driver as this will invariably result in a false detection as described in the TRSDOS 6.0/6.1 discussion above. X-FTS may be executed from LBASIC as follows: CMD"FTS R filename (parameters)"