1 1. CP/M-80 KERMIT Program: Bill Catchings, Columbia University, with contributions from Charles Carvalho (ACC), Bernie Eiben (DEC), Nick Bush (Stevens), John Bray (University of Tennessee), Bruce Tanner (Cerritos College), Greg Small (University of California at Berkeley), Kimmo Laaksonen (Helskini University of Technology), and many others. Language: 8080 Assembler or MAC80 Version: 4.03 Date: December 6, 1984 Documentation: Charles Carvalho, ACC; Frank da Cruz, Columbia KERMIT-80 Capabilities At A Glance: Local operation: Yes Remote operation: No Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Z interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: No Alternate block checks: Yes Terminal emulation: Yes, VT52 and others Communication settings: Yes; duplex, parity Transmit BREAK: Yes; some versions IBM communication: Yes Transaction logging: No Session logging (raw download): Yes Raw upload: Yes Act as server: No Talk to server: Yes; SEND, GET, FIN, BYE Advanced commands for servers: No Local file management: Yes; DIR, ERA, SET DEFAULT disk Handle file attributes: No Command/init files: No Printer control: Yes, limited 1.1. Summary of CP/M CP/M-80 (version 2.2) has only five built-in commands, and they all deal with files; other functions are done by invoking programs. CP/M file specifications are of the form DEV:XXXXXXXX.YYY, where DEV: is a device name, normally the A: or B: floppy. If omitted, the device name defaults to your connected dis- kette. XXXXXXXX is a filename of up to 8 characters. 2 YYY is the file type, up to 3 characters. File names and file types may contain letters, digits, and some special characters, including dash, dollar sign, and underscore, but no imbedded spaces. Upper and lower case letters are equivalent. "Wildcard" file-group specifications are permitted in file names and file types (but not device names) within certain contexts; a "*" matches a whole field, a "?" matches a single character, including space. Ex- amples: "*.F??" specifies all files whose types start with F and are 1, 2, or 3 characters long; "F?.*" specifies all files whose names start with F and are no more than two characters long (before the trailing spaces). The five CP/M commands are: DIR file Lists the the names of the specified files. The default file specification is "*.*". Example: "DIR B:*.FOR". ERA file Erases (deletes) the specified file(s); wildcards al- lowed. REN new old Changes the name of a file from old to new, e.g. "REN NEW.FOR=OLD.FOR". SAVE Saves the specified number of memory blocks into a file. TYPE file Types the specified file on the screen, e.g. "TYPE FOO.TXT". The most important programs are: STAT Gives statistics on disk usage; sets and displays IOBYTE. PIP Peripheral Interchange Program. Copies files. In response to the "*" prompt, give a command of the form disk:outfile=disk:infile Wildcards ("*" for a whole field or "?" for a letter) can be used. Examples: "A:=B:*.*" to copy a whole disk, "A:=B:*.FOR" to copy all the Fortran programs from disk B to disk A. If the disk specification is omitted, your "connected" disk is assumed. Command line arguments are also accepted, e.g. "PIP A:=B:*.*". For further information on CP/M, consult your microcomputer manual or a CP/M handbook. 3 1.2. Kermit-80 Description Since Kermit-80 runs on a standalone micro, it is always in control of the screen -- it is always local. Thus, it always keeps the screen up- dated with the file name and the packet number, whether sending or receiving. Kermit-80 is capable of an imprecise or "fuzzy" timeout on an input request, and can break deadlocks automatically. In most cases, this is not important, because the KERMIT on the other side is most likely able to handle the timeouts. The timeouts done by Kermit-80 are fuzzy because they depend on the speed of the processor and other fac- tors that can vary from system to system. 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 type carriage return 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 trans- fers could require this kind of manual intervention. File transfers may be interrupted in several ways. Control-C This will return you to Kermit-80 command level im- mediately, 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-80 will go on to the next one. When receiving a file, KERMIT-80 will send a sig- nal to the remote KERMIT to stop sending this file. If the remote KERMIT understands this signal (not all im- plementations of KERMIT do), it will comply, otherwise the file will keep coming. In any case, the remote KER- MIT will go on to the next file in the group, if any. Control-Z Like Control-X, except if a file group is being trans- mitted, this will stop the transmission of the entire group. If only a single file is being transmitted, it works exactly like Control-X. Carriage Return If you type a carriage return Kermit-80 will resend the current packet. You may do this repeatedly, up to the packet retry limit (somewhere between 5 and 16 times) for a particular packet. KERMIT-80 COMMANDS KERMIT-80 uses the DECSYSTEM-20 keyword style command language. Each keyword may be abbreviated to its minumum unique length. "?" may be typed to request a menu of the available options for the current field at any point in a command. ESC may be typed at any point in a command to fill out the current keyword or filename; if sufficient characters have not been typed to identify the current field uniquely, KERMIT-80 4 will sound a beep and allow you to continue from that point. CONNECT Establish a "virtual terminal" connection to any host that may be connected 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. (Some versions emulate other terminals.) The es- cape character differs from micro to micro; 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-backslash or CTRL-rightbracket, followed by a single letter "command". C Close Connection, return to Kermit-80> command level. S Display Status of connection, but maintain remote connec- tion. ? List available single-character commands. 0 (zero) Send a null (0) character. B Send a BREAK signal. Only some systems provide this func- tion. ^] (or whatever - a second copy of the escape character) Send the escape character itself to the remote host. SEND filespec Send file(s) specified by filespec to the remote Kermit. The filespec may contain CP/M 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 conflict, and FILE-WARNING is ON, warn the user and try to build a unique name for the file by adding "&" characters to the name. GET filespec When Kermit-80 is talking to a Kermit Server on the host, you should use the GET command to request the server to send files to you, for example: get hlp:k*.hlp Limitation: If you request an alternate block check type using the SET BLOCK command, the GET command will not communicate it to the remote server. If you want to have type 2 or 3 block checks done when getting files from the server, you have to is- sue the appropriate SET BLOCK command to the remote KERMIT be- fore putting it in server mode. LOG filespec When CONNECTed to a foreign host as a terminal, log the terminal session 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 5 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". TRANSMIT filespec Send the specified file to the system on the other end of the connection as though it were being typed at the terminal, one line at a time. No KERMIT protocol is involved. You must manually confirm each line. This is useful for sending files to systems that don't have a KERMIT program. During transmission, you may type the escape character followed by one of these single-character commands: C Cease transmission R Re-transmit the previous line BYE When talking to a remote Kermit Server, this command shuts down the server and logs it out, and also exits from Kermit-80 to CP/M command level. LOGOUT Like BYE, but leaves you at Kermit-80 command level. FINISH Like LOGOUT, but shuts down the remote server without logging it out. Leaves you at Kermit-80 command level; subsequent CONNECT commands will put you back at host system command level. VERSION Show the name, edit number, and edit date of several of the modules that make up Kermit-80. 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 adding "&" characters to the given name. ON by default. VT52-EMULATION ON (or OFF) When connected as a terminal to a foreign host, controls whether the micro emulates a VT52 or runs in "native mode". VT52 emulation is ON by default, except on micros that already have terminal functionality built in, such as the DEC VT180 and DECmate (these act as VT100-series terminals). Some systems emulate other terminals, like the ADM3A; see table 1-3. 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 connec- tions. Kermit-80 will prompt you for the new escape 6 character, which you enter literally. BAUD-RATE Change the baud rate of the communications port. This command only works on some systems. value is the numeric baud rate (300, 9600, etc.) desired. Type SET BAUD followed by a question mark for a list of supported baud rates. On systems that do not support this com- mand, you must set the port baud rate from CP/M or other setup mechanism outside of KERMIT-80. PARITY Sets parity for outgoing characters to one of the fol- lowing: 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 set- ting applies to both terminal connection and file trans- fer. If you set parity to anything other than none, KERMIT-80 will attempt to use "8th bit prefixing" to transfer binary files. If the other KERMIT is also capable of 8th bit prefixing, then binary files can be transferred successfully; if not, the 8th bit of each data byte will be lost (you will see a warning on your screen if this happens). TIMER ON (or OFF) Enable or disable the "fuzzy timer". The timer is off by default, because in the normal case KERMIT-80 is com- municating with a mainframe KERMIT that has its own timer. Mainframe KERMIT timers tend to be more precise or adaptable to changing conditions. You should SET TIMER ON if you are communicating with a KERMIT that does not have a timer. You should SET TIMER OFF if you are communicating over a network with long delays. IBM ON (or OFF) Allow the transfer of files to and from an IBM mainframe computer. This makes Kermit-80 wait for the IBM tur- naround character (XON), ignore parity on input, add ap- propriate parity to output, and use local echoing during CONNECT. As distributed, KERMIT-80 uses MARK parity for IBM communication. If you don't give this command, IBM mode is OFF. Since IBM VM/CMS KERMIT does not have timeout capability, SET IBM ON also turns on the "fuzzy timer" automatically. 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. 7 The 2 and 3 character options should only be used under conditions of extreme line noise. Many implementations of KERMIT only support the single character checksum. FILE-MODE Tells KERMIT-80 what kind of file it is sending, so that KERMIT can correctly determine the end of the file. SET FILE BINARY means to send all the 128-byte blocks of the file, including the last block in its entirety; SET FILE ASCII is used for text files, and transmission stops when the first Control-Z is encountered anywhere in the file (this is the CP/M convention for marking the end of a text file). SET FILE DEFAULT tells Kermit to attempt to determine the file type by examining the file being transmitted. If a Control-Z appears before the last block of the file, it is assumed to be BINARY; if, when the first Control-Z is encountered, the remainder of the file contains only control-Z's, it is assumed to be a text file. Unfortunately, not all programs fill the remainder of the last record of a text file with Control-Z's, so this algorithm is not always successful. If binary transmission is used on a text file, some ex- traneous characters (up to 127 of them) may appear at the end of the file on the target system. If ASCII transmission is used on a binary file, the entire file will not be sent if it happens to contain any data bytes that correspond to Control-Z. DEFAULT-DISK This allows you to set the default disk as source and destination of file transfers. In addition, issuing this command causes you to switch to the specified disk and log it in, write-enabled. The colon must be in- cluded in the disk name (A:). The selected disk appears in your KERMIT-80 prompt, for instance Kermit-80 A:> PORT Allows you to switch between different communication ports. This command is not available on all systems. Type SET PORT ? for a list of valid options for your system. PRINTER ON or OFF. Turns copying of CONNECT session to printer on and off. No attempt is made to do buffering or flow control; Kermit assumes the printer can keep up. DEBUG ON or OFF. Enables/disables displaying of packets on the screen during file transfer. DIRECTORY This provides a directory listing of the specified files. If no files are specified, all files on the default disk are listed. File sizes, in K, are included. You may interrupt the listing at any time by typing any character. The listing (even if interrupted) concludes with a display of the amount of free 8 storage left on the disk. ERASE This executes the CP/M ERA command on the specified file(s). The names of the files being erased are not displayed. 1.3. Kermit-80 Flavors Many of the systems supported use an external terminal, rather than a built-in console. Kermit may be further customized for these systems by defining (at assembly time) the terminal type to be used. If the ter- minal type is unknown or does not match any of the existing terminal op- tions, the generic "CRT" option may be selected. In this case, Kermit cannot do fancy screen control during file transfer; it simply types the file names, packet numbers, and messages in sequence across and down the screen. This works best if you can put your micro or terminal in "autowrap" mode; otherwise the packet numbers will pile up in the rightmost column; the filenames and messages will always appear on a new line, however. If no specific terminal has been selected, Kermit cannot do VT52 emulation; it can act as a "dumb terminal" (sometimes called a "glass TTY"), or else its own built in terminal firmware provides cursor control functions independent of the Kermit program. 1.3.1. Generic Kermit-80 "Generic Kermit-80" is an implementation of Kermit that should run on any 8080-compatible CP/M 2.2 system with no modification at all, or per- haps only a minor one. Unlike other Kermit-80 implementations, it con- tains no system-dependent manipulation of the serial port. All I/O is done with standard CP/M BIOS calls, and I/O redirection is done using the CP/M IOBYTE function, which, according to the Digital Research CP/M Operating System Manual, is an optional feature of any particular CP/M implementation. If your system does not provide the IOBYTE function, Generic Kermit-80 will not work; furthermore, not all systems that im- plement IOBYTE do so in the same way. The SET PORT command may be used to select the devices to be used for input and output. Table 1-1 lists the options to the SET PORT command and their effects. ------------------------------------------------------------------ SET PORT xxx input from output to CRT CRT: CRT: PTR PTR: PTP: TTY TTY: TTY: UC1 UC1: UC1: UR1 UR1: UP1: UR2 UR2: UP2: Table 1-1: Kermit-80 SET PORT Options ------------------------------------------------------------------ The default is SET PORT PTR. In all cases, the console (CON:) and list (LST:) devices used are those selected when Kermit is started. 9 The reason all Kermit-80 implementations aren't generic is that a good deal of speed is sacrificed by getting all services from the operating system. While a specific implementation of Kermit-80 may be able to operate at 4800, 9600, or even 19200 baud, Generic Kermit will fail to work on some systems at speeds in excess of 1200 baud. In addition, many features of Kermit require more specific knowledge of the hardware involved -- Generic Kermit cannot send a BREAK signal, or change the baud rate. 1.3.2. CP/M 3 Kermit CP/M 3 Kermit should run on most CP/M 3 (CP/M-Plus) systems. It uses the auxilliary port (AUX:) to communicate to the remote Kermit. The SET BAUD and SET PORT commands are not supported; nor can a BREAK be sent. Like Generic Kermit, a terminal may be selected at assembly time. 1.3.3. System-Specific Versions There are also many versions of Kermit-80 tailored to specific systems. Most of these operate uniformly, but some of them take advantage (or suffer limitations) of the specific system. Here are some of the spe- cial features for particular systems: Apple II -- two variations: APMMDM: Apple with Z80 Softcard and Micromodem II in slot 2 Dialout capability provided in connect command; user is prompted for phone number if carrier is not present. During connect mode, ^]D drops carrier. BYE command also causes carrier to be dropped. AP6551: Apple with Z80 Softcard, and one of several 6551-based com- munication cards; the slot number is a compile-time parameter (default is slot 2). SET BAUD-RATE supported; speeds are 110-19200 baud. BigBoard II: Uses serial port A. To use port B, change mnport, mnprts, and baudrt and reassemble. Can generate BREAK. SET BAUD-RATE supported; speeds are 300-38400 baud. Digicomp Delphi 100: SET BAUD-RATE supported; speeds are 50-19200 baud. CPT-85xx word processors: Can generate BREAK. SET BAUD-RATE supported; speeds are 50-9600 baud. DEC DECmate II word processor (with Z80 card): Can generate BREAK. DEC VT180 (Robin): 10 Three output ports, referred to as COMMUNICATIONS, GENERAL, and PRINTER. Can generate BREAK. Intertec SuperBrain: SET BAUD-RATE supported; speeds are 50-19200 baud. Kaypro: Should work on most Kaypro models, as well as some related systems (Ferguson BigBoard I, Xerox 820). For the newer Kaypros with mul- tiple ports, Kermit uses the one labeled "serial data"; it cannot use the serial printer or internal modem ports (but it should be possible to modify the values for mnport, mnprts, and baudrt to do this). Can generate BREAK. SET BAUD-RATE supported; speeds are 50-19200 baud. Morrow Decision I: Uses the Multi-I/O board. Port 1 is the console, port 3 is the com- munications line. SET BAUD-RATE supported; speeds are 75-56000 baud. Nokia MicroMikko: Will not echo control-O (which locks keyboard). SET BAUD-RATE sup- ported; speeds are 75-9600 baud. Ohio Scientific: Doesn't have screen control. Osborne 1:Uses serial line, not internal modem. Left-arrow key generates ("delete" or "rubout" character) during connect mode. SET BAUD-RATE supported; speeds are 300 and 1200 baud. TRS-80: Two versions, one for Lifeboat CP/M, one for Pickles & Trout CP/M. 1.4. Installation of Kermit-80 Kermit-80 was written originally for the Intertec SuperBrain in lowest- common-denominator 8080 code with the standard assembler, ASM (single source module, no macros, no advanced instructions), so that it could be assembled on any CP/M-80 system (the 8080 assembler is distributed as a standard part of CP/M-80, whereas the fancier Z80 or macro assemblers are normally commercial products). It has since been modified to run on many other systems as well. Kermit-80 should be able to run on any 8080-, 8085- or Z80-based microcomputer under CP/M with appropriate minor changes to reflect the port i/o and screen control for the system (see below). The proliferation of new systems supported by Kermit-80 made the program grow so large and complicated that it had to be broken up into system- independent and system-dependent modules, as of version 4 (this was done by Charles Carvalho of ACC). Each module is composed of multiple files. This has reduced the time and disk space necessary for assembly; Kermit-80 may once again be assembled on a CP/M system with roughly 150Kbytes of space. The majority of the code does not need to be reas- sembled to support a new system. Unfortunately, it can no longer be as- sembled with ASM, since ASM does not support multiple input files. To 11 allow it to be assembled on any CP/M system, the public-domain assembler LASM is included in the distribution kit; Kermit-80 may also be as- sembled with Microsoft's M80 (not supplied), or cross-assembled on a DEC-10 or DEC-20 with MAC80 (also supplied in the distribution kit). In theory, any 8080 assembler supporting the INCLUDE directive ought to work, as well. All versions of Kermit-80 are assembled from the same set of sources, with system dependencies taken care of by assembly-time conditionals within the system-dependent module (eventually, the system-dependent module will itself be broken up into multiple files, one for each system). The most important system dependencies are terminal emulation (when CONNECTed to the remote host) and screen handling, which are de- pendent on the individual micro's escape codes (these features are table driven and easily modified for other CP/M systems), and the lowest level i/o routines for the serial communications port. The port routines are best done only with BDOS calls, but some systems do not allow this, primarily because the BDOS routines strip the parity bit during port i/o, and the parity bit is used for data when transmitting binary files. Kermit-80's I/O routines must check the port status and go elsewhere if no input is available; this allows for virtual terminal connection, keyboard interruption of stuck transmissions, etc. On systems that fully implement I/O redirection via the optional CP/M IOBYTE facility, this may be done by switching the IOBYTE definition. On others, however, IN/OUT instructions explicitly referencing the port device registers must be used. CP/M-80 KERMIT versions 3.8 and later include a "fuzzy timer" that al- lows a timeout to occur after an interval ranging from 5 to 20 seconds (depending upon the speed of the processor and the operating system routines) during which expected input does not appear at the port. In this case, retransmission occurs automatically. In any case, you may type a carriage return during transmission to simulate a timeout when the transfer appears to be stuck. 1.4.1. Organization of Kermit-80 Kermit-80 consists of two modules, each of which is generated from mul- tiple source files. The first module contains the system-independent code; the second module is configured for a particular system and merged with the system-independent module to produce a customized Kermit-80. The distribution kit contains: - the system-independent module, CP4KER.HEX; - the system-dependent modules, CP4*.HEX (see table 1-2); - the source files, CP4*.ASM, - the DEC-10/DEC-20 cross-assembler and linker, MAC80.* and LINK80.*, - the public-domain CP/M assembler, LASM.*, - the public-domain CP/M load/patch utility, MLOAD.* 12 ------------------------------------------------------------------------ Symbol Filename System AP6551 CP4APL Apple II, Z80 Softcard, 6551 ACIA in serial interface APMMDM CP4APM Apple II, Z80 Softcard, Micromodem II in slot 2 BBII CP4BB2 BigBoard II (terminal required) BRAIN CP4BRN Intertec SuperBrain. CPM3 CP4CP3 "generic": CP/M 3.0 (CP/M Plus) systems (terminal req'd) DELPHI CP4DEL Digicomp Delphi 100 (terminal required) DMII CP4DM2 DECmate II with CP/M option GENER CP4GEN "Generic": CPM 2.2 systems with IOBYTE (terminal req'd) HEATH CP4H89 Heath/Zenith H89. KPII CP4KPR Kaypro-II (and 4; probably supports all Kaypro systems) MDI CP4MDI Morrow Decision I (terminal required) MIKKO CP4MIK MikroMikko MMDI CP4UDI Morrow Micro Decision I (terminal required) OSBRN1 CP4OSB Osborne 1 OSI CP4OSI Ohio Scientific ROBIN CP4ROB DEC VT180 TELCON CP4TEL TELCON Zorba portable TRS80LB CP4TLB TRS-80 model II with Lifeboat 2.25C CP/M Display TRS80PT CP4TPT TRS-80 model II with Pickles + Trout CP/M Display VECTOR CP4VEC Vector Graphics. Z100 CP4Z00 Z-100 under CP/M-85 "symbol" is the symbol used to select the target system, in CP4TYP.ASM; "filename" is the name under which the module is supplied in the distribution. Table 1-2: Systems supported by Kermit-80 ------------------------------------------------------------------------ 1.4.2. Downloading Kermit-80 You'll need either a pre-configured .COM file or the system-independent module, CP4KER, in binary (.COM) or hex (.HEX) format and the system-de- pendent overlay for your system (from table 1-2). If your system is not listed in the table, get the generic CP/M 2.2 Kermit or the generic CP/M 3 Kermit. If you already have a version of Kermit on your micro and you want to install a new version, simply use your present version to get the new files. Transfer the files to your system and skip ahead to "merging the modules". If you do not have a copy of Kermit on your micro, and you cannot borrow a Kermit floppy but you do have access to a mainframe computer with a copy of the Kermit-80 distribution, you should read this section. There are several ways to get Kermit from a host system to your micro. The easiest is to "download" the necessary "hex" files into your micro's memory and then save it on the disk. If you have a terminal emulator program on your micro which can save a copy of the session to disk, con- nect to your host, and type the necessary files. Exit from the emulator, saving the session log, and edit the session log to extract 13 the hex files. Skip ahead to "merging the files". The following is a procedure which, though far from foolproof, should allow you to get a version of Kermit to your CP/M based micro. It depends upon the host prompt, or at least the first character of the host prompt, being some character that cannot appear in a hex file (the valid characters for hex files are the digits 0-9, the upper case let- ters A-F, the colon ``:'', carriage return, and line feed). As soon the prompt character is encountered, the transfer will terminate. If your host does not issue a prompt that will accommodate this scheme, you can achieve the same effect by adding an atsign ``@'' to the very end of the hex file before sending it from the host. The program below looks for an atsign (the normal DEC-20 prompt, hex 40). DECSYSTEM-10 users would look for a dot, hex 2E. 1. On your micro, connect to a floppy disk with plenty of free space. Run DDT and type in the following (the comments should not be typed in; they are there just to tell you what's happening): -a100 ;Begin assembling code at 100. 0100 lxi h,ffe ;Where to put HEX file. 0103 shld 300 ;Save the address. 0106 mvi e,d ;Get a CR. 0108 mvi c,4 ;Output function. 010A call 5 010D mvi c,3 ;Input function. 010F call 5 0112 ani 7f ;Turn off the parity. 0114 cpi 40 ;Our DEC-20 prompt atsign? 0116 jz 124 ;Yes, we have whole file. 0119 lhld 300 ;Get the pointer. 011C mov m,a ;Else, store the char. 011D inx h ;Increment the pointer. 011E shld 300 ;Save the pointer. 011F jmp 10d ;Go around again. 0124 mvi a,1a ;Get a control-Z. 0126 lhld 300 ;Get the pointer. 0129 mov m,a ;Store the char. 012A shld 300 ;Save the pointer. 012D lxi h,1000 ;Pointer to file. 0130 shld 310 ;Save the pointer. 0133 mvi c,16 ;Make file. 0135 lxi d,5c 0138 call 5 013B lhld 310 ;Get the file pointer. 013E xchg ;Put it in DE. 013F mvi c,1a ;Set DMA. 0141 call 5 0144 mvi c,15 ;Write DMA to file. 0146 lxi d,5c 0149 call 5 014C lhld 310 ;Get the file pointer. 014F lxi d,80 ;Get the DMA size. 0152 dad d ;Adjust file pointer. 0153 shld 310 ;Save it. 14 0156 lda 301 ;Get high order byte. 0159 cmp h ;Have we passed the end? 015A jm 170 ;Yes. 015D jz 163 ;Maybe. 0160 jmp 13b ;No. 0163 lda 300 ;Get low order byte. 0166 cmp l ;Passed the end? 0167 jm 170 ;Yes. 016A jz 170 ;Yes. 016D jmp 13b ;Not quite. 0170 mvi c,10 ;Close file. 0172 lxi d,5c 0175 call 5 0178 ret 0179 -^C ;(control-C):Return to CP/M A>SAVE 1 FETCH.COM ;Save this program; ; we need to run it twice. 2. Connect to your host using a terminal or a terminal emulation facility. Ensure that your host does not have your terminal in "page mode". E.g. on the DEC-20, give the Exec command TERMINAL NO PAUSE END-OF-PAGE. 3. Tell the host to display the first hex file (the system-independent module) at your terminal. E.g. on the DEC-20, give the Exec command TYPE CP4KER.HEX, without a ter- minating carriage return. 4. Return to your micro. Make sure your IOBYTE is set so that RDR: and PUN: correspond to the I/O port that is connected to the DEC-20 (this would normally be the case unless you have done something special to change things). Load the program you entered in the first step with DDT, and use it to capture the first hex file: DDT FETCH.COM -icp4ker.hex ;Setup FCB for file CP4KER.HEX. -g100,179 ;Execute the program. Now there should be a file CP4KER.HEX on your connected disk. 5. Return to the host, and tell it to display the second hex file (the system-dependent module for your configuration). Again, do not type the terminating carraige return. 6. Return to your micro, and run the capture program again: DDT FETCH.COM -icp4ovl.hex ;Setup FCB to create CP4OVL.HEX -g100,179 ;Execute the program. Now there should be a file CP4OVL.HEX on your connected disk. Merging the files: 15 1. For purposes of illustration, we will assume the system-de- pendent overlay is called "cp4ovl.hex". The two hex files may be combined with MLOAD or DDT. If you already have a running Kermit, you can transfer MLOAD.HEX to your system and create MLOAD.COM by running LOAD. If you're bootstrapping Kermit, you could transfer MLOAD.HEX to your system the same way you got the other two .HEX files, but it's probably simpler to use DDT to get Kermit running, and get MLOAD later if you need it. 2. Using MLOAD, the two pieces may be easily merged: A>mload kermit40=cp4ker,cp4ovl [some messages about program size, etc.] A> 3. If you don't have MLOAD running, it's a bit more complex: A>ddt cp4ker.hex NEXT PC 3500 0100 -icp4ovl.hex -r NEXT PC xxxx 0000 -^C A>save dd kermit40.com The page count ("dd") used in the SAVE command is calculated from the last address ("xxxx") given by DDT in response to the R command: drop the last two digits and add 1 if they were not zero, then convert from hexadecimal (base 16) to decimal (base 10): 384F becomes 39 hex, which is 57 decimal (3 times 16 plus 9) -- but 3700 becomes 37 hex, or 55 decimal (consult an introductory computing book if you don't under- stand number base conversion). 4. Note that CP/M hex files have checksums on each line. If there were any transmission errors during the downloading process, MLOAD or DDT will notice a bad checksum and will report an error (something like "Illegal Format"). If you get any errors during loading, either fix the hex file lo- cally with an editor, or repeat the transfer. You now should have a running version of Kermit-80, called KERMIT40.COM. Test your new Kermit by running it. If it gives you a prompt, it might be OK. (don't delete your old one yet...). Instead of a prompt, you could get one of two messages indicating that the configuration infor- mation is invalid: ?Kermit has not been configured for a target system or ?Consistency check on configuration failed 16 Of course, neither of these messages should appear if you're building Kermit from the distribution kit. The first message indicates that the overlay was not found where the system-independent module expected to find it, probably because the overlay address is incorrect; the second indicates that the version of CP4LNK used in the system-dependent module is incompatible with the system-independent module. Once you are satisfied that KERMIT40 works correctly, you should rename your old KERMIT.COM to something else, like OKERMIT.COM, and rename KERMIT40.COM to KERMIT.COM. 1.4.3. Assembling Kermit-80 from the sources Kermit-80 is built in two pieces from the following 12 files: The system-independent files: CP4KER.ASM header file CP4DEF.ASM definitions for both KERMIT and KERSYS CP4MIT.ASM initialization, main loop, miscellaneous commands (BYE, EXIT, LOG, SET, SHOW, STATUS, and VERSION) CP4PKT.ASM the KERMIT protocol handler (SEND, RECEIVE, LOGOUT, and FINISH commands) CP4TT.ASM the transparent commands (TRANSMIT, CONNECT) CP4CPM.ASM CP/M commands (DIR, ERA) CP4WLD.ASM the wildcard handler CP4CMD.ASM the command parser CP4UTL.ASM utility routines and data CP4LNK.ASM linkage area description The system-dependent files: CP4TYP.ASM system selection CP4SYS.ASM system-specific code The system-independent module contains all of the system-independent files except for CP4LNK.ASM, which is assembled into the system-depend- ent module to provide the structures needed to connect the two modules. As distributed, the system-independent module is named CP4KER.HEX. If you have a copy of CP4KER.HEX, you do not need to reassemble the system- independent module to configure Kermit for your system. The system-dependent module consists of CP4TYP.ASM, CP4DEF.ASM, CP4LNK.ASM, and CP4SYS.ASM. One copy of the system-dependent module is supplied already assembled for each supported system; the filename may be obtained from table 1-2. After assembling the two pieces separately, they are combined with DDT or MLOAD into a system-specific Kermit. If you want to rebuild the system-independent module, the only change you may need to make is to select the assembler to be used, in CP4KER.ASM. Define one of MAC80, M80, or LASM to TRUE to select it as the assembler; the others should be defined FALSE. Assuming you have the Microsoft Macro Assembler package (M80/L80), you'll need to do the following: 17 A>m80 cp4ker=cp4ker.asm A>l80 /p:100,cp4ker,cp4ker/n/e This will produce CP4KER.COM. If you are using LASM instead, do this: A>lasm cp4ker LASM will generate CP4KER.HEX and CP4KER.PRN. LASM allows options to be specified in the same way as the standard assembler, ASM, so the command A>lasm cp4ker.abz will read the source files from drive A, send the .HEX file to drive B, and suppress the listing file. If you have access to a TOPS-10 or TOPS-20 system, you can cross-assemble Kermit there with MAC80, producing CP4KER.HEX: .run mac80 *=cp4ker.asm If you want to generate a system-dependent overlay for a particular sys- tem, or want to change the terminal supported, you'll need to check three areas in CP4TYP.ASM: First, the overlay start ADDRESS. The symbol "ovladr" is EQUated to the address of "LNKFLG" in the system-independent module, as the starting address of the overlay (3400H for version 4.03). You'll need to know this value if you're building the overlay with M80/L80. You won't nor- mally need to change this value. Second, the assembler being used. Again, define one of MAC80, M80, and LASM to be TRUE to select it, and define the others to be FALSE. The two modules (system-independent and system-dependent) do not need to be built with the same assembler. Third, the system configuration. Locate your system in table 1-2, then define the appropriate symbol TRUE, and the rest FALSE. If the system comes with a builtin console terminal, define all the terminal switches FALSE. If the system uses an external terminal as the console, locate the terminal in table 1-3 and define the appropriate symbol TRUE, and the remainder FALSE. If the terminal is not listed in table 1-3, use the CRT switch; in this case, VT52 emulation is not supported. In addition, there are a few general and system-specific symbols which may be altered to fit your system: APSLOT For Apple with 6551 ACIA, defines the slot number of the serial card CPUSPD Processor speed in units of 100KHz (currently used only for bbII and kpII for timing loops) TAC For users connecting through ARPAnet TACs: set to TRUE 18 if you wish the default TACTRAP status to be ON. (This may be overridden with the SET TACTRAP command). If you're not connecting through a TAC, set tac to FALSE and ignore tacval. TACVAL For ARPANET TAC users: defines the default TAC intercept character (may be overridden with the SET TACTRAP command) If you are just assembling an existing configuration, you'll need to edit CP4TYP.ASM only. If you are adding support for a new system, you should not modify CP4DEF.ASM or CP4LNK.ASM; if you do, you'll have to change the system- independent module also. Eventually, CP4SYS.ASM will be split into separate files, each of which will generate one or more related systems. When this happens, you'll want to pick the one closest to your system to use as a starting point. After editing CP4TYP.ASM as necessary, assemble and link the overlay as follows: - With M80 (where "xxxx" is the hex value of ovladr from CP4LNK.ASM): A>m80 cp4typ=cp4typ.asm A>l80 /p:xxxx,cp4typ,cp4typ/n/x/e - With LASM: A>lasm cp4typ - With MAC80 on TOPS-10: .run mac80 *=cp4typ.asm - With MAC80 on TOPS-20: @run mac80 *=cp4typ.asm The overlay (cp4typ.hex) may then be merged with the system-independent module as described above (creating a runnable Kermit from the distribu- tion kit). If you have a TOPS-10 or TOPS-20 system and already have a running Kermit-80 v3.9 or later, you can merge the two .HEX files into a .COM file with LINK80, and transfer the new .COM file to your micro with Ker- mit: - Tops-10: .copy kernew.hex=cp4ker.hex,cp4typ.hex .link80 kernew - Tops-20: 19 @append cp4ker.hex,cp4typ.hex (to) kernew.hex @link80 kernew producing KERNEW.COM. If LINK80 says "?Data overlaid", you have an old version of LINK80, and will have to transfer the .HEX files to the micro and merge them there. ------------------------------------------------------------------------ Symbol Terminal description crt Basic CRT, no cursor positioning adm3a ADM3A Display or lookalike smrtvd Netronics Smartvid-80 tvi925 TVI925, Freedom 100 vt52 VT52 or VT52 emulator such as Heath H19, H29, etc. vt100 VT100 or emulator (most ANSI terminals should work) Table 1-3: Terminals known to Kermit-80 ------------------------------------------------------------------------ 1.5. Adding Support For A New System Kermit-80 is built from a common set of source files; the system-depend- ent module makes heavy use of conditional assembly (this complication will be removed in future releases). The system dependencies arise from attempts to answer some questions: 1. What kind of terminal is to be supported? For many micros, the console is an integral part of the sys- tem, but others can use an external terminal. In either case, the commands to manipulate the screen (position the curser, erase the screen, etc) must be defined. 2. How is the serial line accessed? For systems supporting the IOBYTE function, this is straightforward; the symbol "IOBYT" is defined TRUE. If the serial line is accessed with IN and OUT instructions, it may be possible to use the simple I/O routines provided. In this case, the symbol "INOUT" is defined TRUE, the MNPORT and MNPRTS are defined to be the data and control addresses, respectively, and bit masks for testing for "input data available" and "output buffer empty" must be defined. If the interface is strange, leave IOBYT and INOUT set to FALSE, and provide the I/O routines. 3. What initialization is necessary? You may wish to set the baud rate or configure the serial line at startup. Examples for a number of devices are present. 20 4. What special features are to be supported? You may want to provide the capability to select one of several serial lines with the SET PORT command, or to change the speed of the serial line with the SET BAUD-RATE command. To do this, you'll need to build a command table, using the systems already supported as examples. The ability to send a BREAK signal is desirable. Again, examples for several dif- ferent interfaces (ACIA, SIO, etc) are present. 1.6. Notes on New Features in Kermit-80 Version 4 Debugging aids: SET DEBUG ON will add two fields to the SEND/RECEIVE display, labelled "Spack" and "Rpack". These display the last packet sent and received. Of course, this slows down the transfer, especially if the console is an external terminal. SET DEBUG OFF removes these fields. The VERSION command displays the name, edit number, and edit date of several of the modules that make up Kermit. TAC support: ARPAnet TACs (and many other communication devices such as terminal concentrators, modems, port contention units, network PADs, etc) use a printing character (normally "@") as an intercept character, to allow commands to be issued to the TAC. In order to send this character to the host, it must be typed twice. The command "SET TAC CHARACTER" to Kermit enables the TACtrap and asks the user to specify the TAC intercept character. This character will be automatically doubled when it appears in Kermit protocol messages (sent by the SEND or RECEIVE commands) or when it appears in a file being sent with the TRANSMIT command. It is not automatically doubled when typed by the user in CONNECT mode. "SET TAC ON" enables the TACtrap but does not change the TAC intercept character, which is initially "@". "SET TAC OFF" disables the TACtrap. (These comments apply equally to any com- munication device that uses a printable attention character which it will pass through if doubled.) File buffering: Previous versions of Kermit-80 buffered only one sector (128 bytes) at a time during file transfer operations. This version buffers 16Kbytes at a time, reducing the number of times the floppy drive must be spun up and down, and increasing the effective throughput of the link. If the disk transfer rate is too slow, howver, the remote Kermit may time out and retransmit packets. This will show up on the screen in the "Retries:" field; if this occurs after disk activity, you may want to increase the timeout value on the remote Kermit, or reas- semble Kermit with a smaller value for MAXSEC (in CP4SYS.ASM). This buffer is also used by the TRANSMIT command; the log file enabled by the LOG command is still written a sector at a time. 21 1.7. Future Work Work that needs to be done in future releases includes: - Merge in support for additional CP/M-80 systems, particularly those for which support was recently added to the monolithic v3.x source. - Break up CP4SYS into discrete source files, one for each sys- tem. These source files should serve as simple models for ad- ding support for new systems to Kermit-80 -- only the very basic screen definitions, flags, i/o primitives, initializa- tions, and so forth should appear in each system-dependent file. - Make the file-stepping mechanism faster (buffer the FCB's in th chunks of 16 or 32 or 64). Currently, to access the n file in a directory requires n(n+1)/2 lookups... - Addition of missing features -- compression of repeated characters during packet transmission, transmission of file attributes (particularly size, so that "percent done" can be displayed for both incoming and outbound files), advanced com- mands for servers (REMOTE DIRECTORY, etc), command macros and initialization files, login scripts, remote operation and server mode, etc etc. i Index 8080 8, 10 XON/XOFF 4 ARPAnet 20 Z80 10 Attention Character 20 Baud 6 BIOS 8 Block Check 6 Bootstrap 12 BYE 5 Connect 4 CP/M 10 Downloading 12 Eighth-Bit Prefix 6 Escape Character 4, 5 File-Warning 4 FINISH 5 Generic Kermit-80 8 GET 4 IBM 6 Intercept Character 20 Local 3 Local-Echo 5 LOG 4 LOGOUT 5 NAK 3 Parity 6 RECEIVE 4 SEND 4 SET 5 TAC 20 Timeout 3, 11 TIMER 6 TRANSMIT 5 VERSION 5 Virtual Terminal 4 VT100 5 VT52 5 Warning 5 i Table of Contents 1. CP/M-80 KERMIT 1 1.1. Summary of CP/M 1 1.2. Kermit-80 Description 3 1.3. Kermit-80 Flavors 8 1.3.1. Generic Kermit-80 8 1.3.2. CP/M 3 Kermit 9 1.3.3. System-Specific Versions 9 1.4. Installation of Kermit-80 10 1.4.1. Organization of Kermit-80 11 1.4.2. Downloading Kermit-80 12 1.4.3. Assembling Kermit-80 from the sources 16 1.5. Adding Support For A New System 19 1.6. Notes on New Features in Kermit-80 Version 4 20 1.7. Future Work 21 Index i ii List of Tables Table 1-1: Kermit-80 SET PORT Options 8 Table 1-2: Systems supported by Kermit-80 12 Table 1-3: Terminals known to Kermit-80 19