XMODEM PTDOS Device Drivers READ ME **************** * Introduction * **************** This directory contains the combined source code for three PTDOS Device Drivers: * XMODEM is a generic XMODEM Device Driver for binary files * TXTMODEM is a version specifically for text files * RXMOD is a stripped-down receive-only version of TXTMODEM, intended to be used during bootstrapping only ************ * Features * ************ XMODEM is designed for binary files, and simply transmits and receives all bytes as they are. If the last block is not exactly 128 bytes long during transmission, it gets padded at the end with nulls. TXTMODEM is designed to allow you to create or edit PTDOS text files on a PC, using normal PC software such as notepad. when receiving a file, TXTMODEM will convert the file to the way that PTDOS likes it, by deleting all linefeeds and all MSDOS EOFs (1Ah). When sending a file, TXTMODEM will convert the file to the way MSDOS likes it, by inserting a linefeed after every carriage return,and pading the end of the last block with MSDOS EOFs (1Ah). Both of these programs will negotiate with the sender or receiver to transfer data using the Xmodem-CRC protocol or the original Xmodem protocol with checksums. (This negotiation is done as per the xmodem-CRC specification.) XMODEM and TXTMODEM are complete PTDOS Device Drivers, meaning that they can be used as the source or destination for most PTDOS operations, including COPY, GET, and SAVE (discussed in further detail later). They can also be used with other PTDOS programs, for example as a list device for the assembler: *ASSM PROG.A,TXTMODEM,PROG.O ...will assemble PROG.A, producing the object file PROG.O, and send the listing to the serial port with Xmodem protocol. You could then capture the listing file on a PC using Hyperterm, and send that listing file to a printer on your PC. When done transferring data, both programs will print the total number of Xmodem blocks transfered, as well as the number of retry transmissions. TXTMODEM will also print progress marks on the Sol-20 console as blocks are transfered. Each '+' represents a successfully transfered block; each '-' represents a retry. Transmission will abort if there are too many retries on any single Xmodem block. Transmission can be aborted by the user, by pressing the ESCAPE key. RXMOD is a stripped-down receive-only version of TXTMODEM, which is intended to be used only as you bootstrap your sytem. See Bootstrapping section below. The LOCAL key on the Sol-20 keyboard disconnects the serial port from the serial connector on the back of the Sol-20 and instead shunts the serial port transmit to the serial port receive - local mode. These programs can detect this state, and will request that the user turn LOCAL mode off. *************** * Limitations * *************** *-------------* * File Length * *-------------* PTDOS expects file lengths to be exact - there is no real EOF character, even for library files created by the SAVE command. Unfortunately, the Xmodem protocol only allows 128-byte blocks - so every file will be a multiple of 128 bytes. This means that the last xmodem block must be padded with something - in this case, either nulls (with XMODEM) or MSDOS's EOF character, 1Ah (with TXTMODEM). Microsoft's Hyperterm will also pad the last block of your files with EOFs (1Ah) when it sends the file with xmodem protocol. This EOF padding works ok with text files, because TXTMODEM can remove the EOF characters when receiving a file. But there is no recognizable EOF character in a binary file - all values can be used as data. Nulls are as good a choice as any - at least PTDOS won't try to create a file with a string of nulls as its name. But the nulls at the end of binary files can cause some minor annoyances. If you have created a library file with PTDOS's SAVE command like this: *SAVE O=XMODEM, ...and then you read this library file with PTDOS's GET command like this: *GET I=XMODEM ...then the pad characters at the end will cause a PTDOS error message on the console, after all of the files in the library file have been saved and closed. Annoying, but no harmful outcome results from this error message. *-----------------------------------* * Copying Device Drivers with PTDOS * *-----------------------------------* The copy command (and some versions of the SAVE command) cannot copy device drivers. You must first RETYPE any device driver that you wish to transfer, and then RETYPE it back when done. For example, to send the device driver SOL3 via XMODEM: *RETYPE SOL3,I *COPY SOL3,XMODEM *RETYPE SOL3,D (This is true even if you just want to copy a device driver from one disk to another, without using XMODEM.) **************** * Using XMODEM * **************** XMODEM sends and receives files without any interpretation. It works with any program that can send or receive data from a device driver, such as IMG2HEX, HEX2IMG, COPY, GET, and SAVE. You can cancel XMODEM file transfer at any time by pressing the ESCAPE key on the keyboard. XMODEM works nicely with HEX2IMG, allowing you to load a program that was assembled on another system, with an assembler that produces a HEX file, such as Digital Research's ASM: *HEX2IMG XMODEM,MYPROG And for device drivers: *HEX2IMG XMODEM,MYDRVR,T=D The result of these operations will be an executable program, MYPROG, or an executable device driver, MYDRIVR. This XMODEM device driver is useful for saving and retrieving archive files - especially so using the PTDOS SAVE and GET commands. These commands will create library files that include the important PTDOS metadata (block size, file type, and file attributes). A library file can contain several (or many) PTDOS files of any sort, and can even archive device drivers, which cannot be copied using the PTDOS COPY command. Here is an example of how you would save all non-hidden files on a disk that start with 'XM': *SAVE O=XMODEM,XM> Then, you could restore these files to disk this way: *GET I=XMODEM If you wanted to just restore one file, for example XMODMN.A, you would type: *GET I=XMODEM,XMODMN.A ...and only XMODMN.A would be read from the library file and written to disk. Note that any file that has read protection set (e.g. PTDOS RESIDENT) cannot be SAVEd, and will generate an error if you try to do so. Further, Processor Technology protected RESIDENT from having its attributes changed - making it tough to archive the operating system, RESIDENT. Fortunately, Processor Technology released a little hack of a program called ZAP, and its inverse, UNZAP. ZAP essentially disables all attribute checking. You can use it to remove read protection for RESIDENT (or any other file) like this: *ZAP ZAPed! *REATR RESIDENT,-R *UNZAP Then you can create a library file to archive an entire disk, including all its hidden files: *SAVE O=XMODEM,S=-I ****************** * Using TXTMODEM * ****************** TXTMODEM is useful if you want to edit text files (such as assembly language source files) on a PC. You can send a text file to the PC like this: *COPY ,TXTMODEM ...and then use Hyperterm on the PC to receive the file, using Hyperterm's xmodem protocol option. (Transfer>Receive File...>Receive Protocol) Then you can edit the file on the PC. Note that your editor might not deal well with the EOF characters at the end of the file. You can easily delete them though. To send a text file back to the Sol-20, use hyperterm to set up the transmission, again selecting the xmodem protocol. Then type on the Sol-20: *COPY TXTMODEM. should now be in an acceptable format for PTDOS EDIT, ASSM, and any other program that expects text input. You can cancel TXTMODEM file transfer at any time by pressing the ESCAPE key on the keyboard. *********************** * System Requirements * *********************** These XMODEM drivers are designed to run under PTDOS on a Sol-20 computer, or on any S-100 computer equiped with Processor Technology's Subsystem B and Helios II subsystem. Communication is through the Sol-20 serial port, and does not require any hardware handshaking. You must set up the serial port for 8 bits, no parity (See SW-4 on the Sol-20.) Make sure that software handshaking (e.g. XON/XOFF) is NOT enabled on your PC. You can use whatever baud rate you like - faster is better. *********************** * Memory Requirements * *********************** These drivers assemble to run in 4K of high memory at address D000h, above the VDM memory. If your Sol-20 does not have memory there, then you can change the driver's memory location in the header files, XMODHD.A (for XMODEM) and TXTMHD.A (for TXTMODEM). If you do change the memory location of a driver, note that PTDOS programs that you will use with the driver (such as COPY, GET, and SAVE) reside in low memory, usually occupying the first 4K to 8K. Also note that PTDOS needs its own buffer to be large enough for an entire disk block. Disk blocks are variable sized in PTDOS. if the disk block is very large (for example for the file RESIDENT, which is PTDOS itself), then you will need to allocate more memory than normal for PTDOS's buffer with the SET command: *SET BU=7000 Therefore, if you locate these device drivers in the low memory, a good address would be the 4K block from 6000h on, above most PTDOS programs, and well below PTDOS's worst-case buffer requirement. ************ * Assembly * ************ To assemble this code, the following files should be present: FILE NAME FUNCTION ASSM PTDOS Assembler EXTRACT PTDOS command to make a binary file executable RETYPE PTDOS command to change a file type XMODEM.A.txt Top-level code for creating XMODEM XMODHD.A.txt Header file for XMODEM TXTMDM.A.txt Top-level code for creating TXTMODEM TXTMHD.A.txt Header file for TXTMODEM XMODMN.A.txt Main code for both programs XMODSB.A.txt All of the subroutines for both programs XMODST.A.txt All of the test strings for both programs To assemble this code, follow these steps: 1) Use hyperterm's XMODEM facility to send all of the files to the Sol-20. Receive the files on the Sol-20 either with TXTMODEM or with the stripped-down RXMOD: for each of the above *COPY RXMOD, or *COPY TXTMODEM, For example, *COPY RXMOD,XMODEM.A 2) To create a new XMODEM: *ASSM XMODEM.A,,XMODEM *EXTRACT XMODEM,S *RETYPE XMODEM,D You should now have a new file called XMODEM, which is type D (which is a device driver). 3) To create a new TXTMODEM: *ASSM TXTMDM.A,,TXTMODEM *EXTRACT TXTMODEM,S *RETYPE TXTMODEM,D You should now have a new file called TXTMODEM, which is type D (which is a device driver). ***************** * Bootstrapping * ***************** If you don't have a way to load a file into your Sol-20 through its serial port, you can use PTDOS's EDIT to type in the file RXMOD.A. This is a stripped-down receive-only, checksum-only text-oriented XMODEM device driver, good enough to load the real XMODEM source code files above. Once you have typed in RXMOD.A, you can build the device driver: *ASSM RXMOD.a,,RXMOD *EXTRACT RXMOD,S *RETYPE RXMOD,D And then use RXMOD (and Hyperterm on your PC) to load the 5 TXMODEM source files like this: *COPY RXMOD,XMODEM.A *COPY RXMOD,TXTMDM.A *COPY RXMOD,TXTMHD.A *COPY RXMOD,XMODMN.A *COPY RXMOD,XMODSB.A *COPY RXMOD,XMODST.A Then, build the more robust TXTMODEM device driver, as described above, and use it to load the remaining 2 files. Once you have a working version of TXTMODEM, you should delete the RXMOD files, as TXTMODEM is a more thorough program for the same job. *********** * Credits * *********** Thanks to Ward Christenson for creating the Xmodem protocol, and for keeping it simple. Thanks to Wikipedia and its contributors for publishing the specifications for Xmodem and Xmodem-CRC. Thanks to Processor Technology for the decent PTDOS documentation. These Xmodem device drivers were written by Martin Eberhard in February, 2013. You are free to use them as you see fit.