TRS-80 KERMIT Program: Stan Barber, Rice University developed from the CP/M-80 version by Bill Catchings and others. Language: Z80 Assembler, compatable with M80 and EDAS from Mysosys Version: 3.5 (adapted from that version of CP/M 80 Kermit) Date: March 1984 Documentation: Stan Barber, Rice University Summary of TRSDOS and TRSDOS-bases Operating Systems TRSDOS (The Radio Shack Disk Operating System) has a large library of built in commands dealing with files, directory maintenance, device I/O, etc. Programs are also used for some functions on some TRSDOS-bases DOS's. Only those of major interest will be discussed here. TRSDOS file specifications are of the form FILESPEC/EXT.PASSWORD:D, where: FILESPEC is the filename up to eight characters. EXT is the file type, up to three characters. PASSWORD is the password for that file. D is a numerical drive specification (0-9). Filenames, file types and passwords may contain letters and numbers, but the first character in each must be a letter. No special characters or spaces are allowed. All fields are optional except the filespec. Any field added must be preceeded by its special delimiter (/ for file type, . for passwords and : for drive specifications). Upper and lower case characters are equivalent. Wildcard file-group specifications are supported on some of the TRSDOS-based DOS's but is not a standard feature. Consult your DOS manual for more specific information. It should be noted that TRSDOS has no concept of a default drive when no drive specification is given in the file specification. It will search for an existing file on all available drives before it will open a new file. Further, it will not open a file on a disk that is already full, instead it will generate a disk full error (if all disks in the system are full or write protected). TRSDOS commands of interest include: DIR :D [other options] lists the names of all visible files on the specified drive. If no drive is specified, some DOS's give the directories of all mounted drives. Some give the directory of the system drive (drive 0). FREE gives statistics on disk usage. KILL file removes the file from the directory and frees the space allocated to the file for reassignment. LIST file lists the file on the display. RENAME oldfile newfile changes the name of oldfile to newfile if newfile is a unique file name on that disk. To duplicate files and disks, there are a variety of commands available. Which one is available will depend on the operating system you are using. A sampling is given below: COPY file1 file2 will copy file1 and name the copy file2. If file2 exists, it will be replaced. BACKUP :D :E will make a copy of the disk in drive D on the the disk in drive E. In some DOS's, this is part of the COPY command (e.g. COPY :D :E or COPY 0 1). FORMAT :D will format the disk in drive D. It will ready for any normal read or write operation following successful completion of this operation. This operation must be performed before use of a blank disk. Reformatting a previously formatted disk will cause all previously stored information to be lost. FORMAT is usually a program but on some DOS's, it is a part of the DOS command library. KERMIT-TRS80 Description This implementation of the Kermit protocol is compatable with all DOS's available for the TRS80 Model I or Model III (and the Model 4 running in Model III mode). It has been checked out under the following DOS's: TRSDOS 2.3 (Model I), TRSDOS 1.3 (Model III), NEWDOS/80 V 2.0, LDOS 5.1.3, DOS+ 3.5 and VTOS 3.0 (Model I). Since Kermit-TRS80 runs on a TRS-80, it is always local. The screen is contantly updated with the filename and the packet number, whether sending or receiving. Kermit-TRS80 will also automatically translate file names to conform with the Kermit standard when sending and the TRSDOS standard when receiving. (This does not apply to the GET command.) If despite the timeout capability, the transmission appears to be stuck (and you can tell that this has happened if the screen fails to change for a while) you can hit to have the micro do what it would have done on a timeout, namely NAK the expected packet to cause to foreign host to send it again (or, if the micro is sending, to retransmit the last packet). Micro/Micro or Micro/IBM-mainframe transfers could require this kind of manual intervention. File transfers may be interrupted in several ways. [A reminder: Control characters are generated by holding down the Left-shift and the down arrow keys while striking the alpha key corresponding to the control character that you wish to generate.] Control-C This will return you to Kermit-TRS80 command level immediately, so that you can connect back to the remote system, or take any other desired action. Control-X When sending a file, this will terminate the sending of the current file with a signal to the KERMIT on the other side to discard what it got so far. If there are more files to be sent, KERMIT-TRS80 will go on to the next one. When receiving a file, KERMIT-TRS80 will send a signal to the remote KERMIT to stop sending this file. If the remote KERMIT understands this signal (not all implementations of KERMIT do), it will comply, otherwise the file will keep coming. In any case, the remote KERMIT will go on to the next file in the group, if any. Control-Z Like Control-X, except if a file group is being transmitted, this will stop the transmission of the entire group. If only a single file is being transmitted, it is exactly like Control-X. s If you type repeatedly Kermit-TRS80 will retry the current packet up to its retry limit (something like 16 times) and then, if no valid response was received, return to Kermit-TRS80 command level. KERMIT-TRS80 COMMANDS KERMIT-TRS80 uses the DECSYSTEM-20 keyword style command language. Each keyword may be abbreviated to its minimum unique length. "?" may be typed to request a menu of the available options for the current field at any point in a command. This must be followed by an . If sufficient characters have not been typed to identify the current field uniquely, KERMIT-TRS80 will reprompt and allow you to continue from that point. CONNECT Establish a "virtual terminal" connection to any host that may be con- nected to the serial port, i.e. pass all typein to the serial port and display all input from the serial port on the screen. Also, emulate a DEC VT52 to allow cursor control, screen clearing, etc., if VT52-EMULATION is ON (see below), in which case you should also set your terminal type on the remote host to VT52. The escape character defaults to CTRL-underbar (which is generated by on the keyboard). When you issue the CONNECT command, the micro will print a message telling you how to get back. The escape sequence is generally an uncommonly-used control character, like CTRL-underbar or CTRL-uparrow, followed by a single letter "command". C Close Connection, return to Kermit-TRS80> command level. S Display Status of connection, but maintain remote connection. ? List available single-character commands. 0 (zero) Send a null (0) character. ^_ (or whatever - a second copy of the escape character) Send the es- cape character itself to the remote host. SEND filespec Send file specified by filespec to the remote Kermit. The filespec may not contain wildcards. RECEIVE Receive file(s) from the remote Kermit. Store them under the names provided in the file headers supplied by the remote host. If the names aren't legal, use as many legal characters from the name as possible (see the description of SET FILE-WARNING below). If there's a con- flict, and FILE-WARNING is ON, warn the user and try to build a unique name for the file. GET filespec When Kermit-TRS80 is talking to a Kermit Server on the host, you may include a file wildcard IF the host supports wildcards. The filespec must be in a legal form for the HOST system. LOG filespec When CONNECTed to a foreign host as a terminal, log the terminal ses- sion to the specified diskette file. This functionality depends to some extent on the remote host's ability to do XON/XOFF flow control, and does not guarantee a complete transcript (after all, that's what the KERMIT protocol is for). The log file is closed when the connection is closed by typing the escape character followed by the single-character command "C". BYE When talking to a remote Kermit Server, this command shuts down the server and logs it out, and also exits from Kermit-TRS80 to DOS command level. LOGOUT Like BYE, but leaves you at Kermit-TRS80 command level. FINISH Like LOGOUT, but shuts down the remote server without logging it out. Leaves you at Kermit-TRS80 command level; subsequent CONNECT commands will put you back at host system command level. SET parameter [value] Set the specified parameter to the specified value. Possible settings: WARNING ON (or OFF) Warn user of filename conflicts when receiving files from remote host, and attempt to generate a unique name by modifying the given one. ON by default. VT52-EMULATION ON (or OFF) When connected as a terminal to a foreign host, controls whether the TRS80 emulates a VT52 or runs in "native mode". VT52 emulation is ON by default. DEBUGGING ON (or OFF) When transmitting or receiving packets, controls whether the packets are displayed on the local screen. Debugging is OFF by default. LOCAL-ECHO ON (or OFF) When you CONNECT to a remote host, you must set LOCAL-ECHO ON if the host is half duplex, OFF if full duplex. OFF by default. ESCAPE Change the escape character for virtual terminal connections. Kermit-TRS80 will prompt you for the new escape character, which you type in locally. BAUD Change the baud rate of the communications port. Type SET BAUD followed by a question mark, and follow the directions. PARITY Sets parity for outgoing characters to one of the following: NONE, SPACE, MARK, EVEN, or ODD. On input, if parity is NONE, then the 8th bit is kept (as data), otherwise it is stripped and ignored. The parity setting applies to both terminal con- nection and file transfer. IBM ON (or OFF) Allow the transfer of files to and from an IBM mainframe com- puter. This makes Kermit-TRS80 wait for the IBM turnaround character (XON), ignore parity on input, add appropriate parity to output, and use local echoing during CONNECT. If you don't give this command, IBM mode is OFF. FILE-TYPE (ASCII/BINARY/DEFAULT) Tells KERMIT-TRS80 how to deal with the file being send/received. IT IS IMPORTANT to tell KERMIT if the is in ASCII when sending to a non-TRS80 KERMIT. DEFAULT is the same as BINARY in this version. BLOCK-CHECK-TYPE The options are: 1-CHARACTER-CHECKSUM Normal, default, standard 6-bit checksum. 2-CHARACTER-CHECKSUM A 12-bit checksum encoded as two characters. 3-CHARACTER-CRC-CCITT A 16-bit CCITT-format Cyclic Redundancy Check, encoded as 3 characters. The 2 and 3 character options should only be used under con- ditions of extreme line noise. Many implementations of KERMIT only support the single character checksum. PORT Allows you to switch between different communication ports. This command is not available at this time. PRINTER ON or OFF. Turns copying of CONNECT session to printer on and off. No attempt is made to do buffering or flow control; it is assumed printer can keep up. Printer is OFF by default. DIR Provides a directory for the specified drive. If no drive is specified, the directory display will be as if you had entered the command from DOS command level. See the discussion of DIR above. KILL This executes the DOS KILL command on the specified file. Installation Kermit-TRS80 is easily installed. Simply download the program KERMAKE/BAS (KERMAKE.BAS on the mainframe), enter BASIC, load and run the program. KERMAKE/BAS is in ASCII format and will keep a running checksum while creating KERMIT/CMD. If there was some error in the downloading process, you will be notified by the program when it attempts to make KERMIT/CMD. Once this process is complete, you will have a running version of Kermit-TRS80. Building Kermit-TRS80 from the Source. The Source for Kermit-TRS80 is in seven modules. KERMIT/SRC is the main source module. It will call the other source files into the assembly as needed. If any system calls needed to be changed, they are defined here and all labels for system calls start with an @. This would be useful for assembling a version for the Model 4 or a version for a TRS-80 work alike that has some hardware differences (MAX-80, etc.). All serial I/O routines are in this section as well. GET/SRC and SEND/SRC contain the code for the RECEIVE (GET) and SEND commands. XFER/SRC contains the common code used by RECIEVE and SEND. MORE/SRC contains code for the other commands (with two exceptions) described above. KILLDIR/SRC contains the code for the KILL and DIR commands. This code would have to be modified for use on the Model 4. KERSTR/SRC contains the strings and storage area. It should be noted that KERMIT/CMD loads into RAM at 7000H. This avoids conflicts with the DOS overlays that may be called by invoking the DIR command. Assembly at a lower address is possible if other methods are used to call for a DIR. I chose this method to be compatable with as many DOS's as possible without writing code specific to each. Getting a binary copy of KERMIT-TRS80 If you wish to have a binary copy of KERMIT-TRS80, you can call the SOBBS TEST MODE at (713) 660-9252 to download an binary copy with KERMIT or the Chistensen (XMODEM) protocol. At the "First Name or User Number?" prompt, enter KERMIT. At the "Last Name?" prompt, enter KERMIT. At the "Password?" prompt, enter KERMIT (will not echo). Select G at the "Command>" prompt. Just follow the instructions given following that. Stan Barber May 1984 (thanks to Frank da Cruz for the documentation for Kermit and Stan Hanks for the encouragement.)