CP/M

home *** CD-ROM | disk | FTP | other *** search

/ CP/M / CPM_CDROM.iso / cpm / modems / modem / cp405src.ark / CP4KER.DOC < prev next >

Wrap

Text File | 1986-12-26 | 55.2 KB | 1,220 lines

12. 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.05 Date: February 1985 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 12.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 diskette. XXXXXXXX is a filename of up to 8 characters. YYY is the file type, up to 3 characters. File names and file types may contain letters, digits, and some special charac- ters, including dash, dollar sign, and underscore, but no imbedded spaces. Up- per 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. Examples: "*.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 charac- ters 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 allowed. 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 as- sumed. 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. 12.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 updated 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 factors 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 transfers could require this kind of manual inter- vention. File transfers may be interrupted in several ways. Control-C This will return you to Kermit-80 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-80 will go on to the next one. When receiving a file, KERMIT-80 will send a signal to the remote KERMIT to stop sending this file. If the remote KERMIT understands this sig- nal (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 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 will sound a beep 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. (Some versions emulate other terminals.) The escape 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 connection. ? List available single-character commands. 0 (zero) Send a null (0) character. B Send a BREAK signal. Only some systems provide this function. ^] (or whatever - a second copy of the escape character) Send the es- cape 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 con- flict, 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 ex- ample: 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 issue the appropriate SET BLOCK com- mand to the remote KERMIT before putting it in server mode. 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 connec- tion 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 connec- tion 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 fol- lowed 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 12-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 connections. Kermit-80 will prompt you for the new escape 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 ques- tion mark for a list of supported baud rates. On systems that do not support this command, 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 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. 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 suc- cessfully; 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 communicating with a mainframe KERMIT that has its own timer. Mainframe KER- MIT 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 com- puter. This makes Kermit-80 wait for the IBM turnaround character (XON), ignore parity on input, add appropriate parity to output, and use local echoing during CONNECT. As dis- tributed, 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. 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. 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 en- countered 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 be- ing 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. Unfor- tunately, 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 extraneous 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 destina- tion 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 included 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; Ker- mit 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 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. 12.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 terminal type is unknown or does not match any of the existing terminal options, the generic "CRT" op- tion may be selected. In this case, Kermit cannot do fancy screen control during file transfer; it simply types the file names, packet numbers, and mes- sages 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 can- not 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 con- trol functions independent of the Kermit program. 12.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 perhaps only a minor one. Unlike other Kermit-80 implementations, it contains 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, ac- cording 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 sys- tems that implement 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 12-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 12-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. 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. 12.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. 12.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 special 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 car- rier is not present. During connect mode, ^]D drops carrier. BYE com- mand also causes carrier to be dropped. AP6551: Apple with Z80 Softcard, and one of several 6551-based communication 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): 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 multiple 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 communica- tions line. SET BAUD-RATE supported; speeds are 75-56000 baud. Nokia MicroMikko: Will not echo control-O (which locks keyboard). SET BAUD-RATE supported; speeds are 75-9600 baud. Ohio Scientific: Doesn't have screen control. Osborne 1:Uses serial line, not internal modem. Left-arrow key generates <DEL> ("delete" or "rubout" character) during connect mode. SET BAUD-RATE sup- ported; speeds are 300 and 1200 baud. TRS-80: Two versions, one for Lifeboat CP/M, one for Pickles & Trout CP/M. 12.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 Car- valho 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 as- sembled on a CP/M system with roughly 150Kbytes of space. The majority of the code does not need to be reassembled to support a new system. Unfortunately, it can no longer be assembled with ASM, since ASM does not support multiple in- put files. To 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 sys- tem 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 depen- dencies are terminal emulation (when CONNECTed to the remote host) and screen handling, which are dependent 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 in- put is available; this allows for virtual terminal connection, keyboard inter- ruption of stuck transmissions, etc. On systems that fully implement I/O redirection via the optional CP/M IOBYTE facility, this may be done by switch- ing 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 allows 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 ex- pected 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. 12.4.1. Organization of Kermit-80 Kermit-80 consists of two modules, each of which is generated from multiple 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 12-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.* ------------------------------------------------------------------------------- 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 12-2: Systems supported by Kermit-80 ------------------------------------------------------------------------------- 12.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-dependent overlay for your system (from table 12-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 Ker- mit 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, connect to your host, and type the necessary files. Exit from the emulator, saving the session log, and edit the session log to extract 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 charac- ter that cannot appear in a hex file (the valid characters for hex files are the digits 0-9, the upper case letters 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,2FE ;Where to store in memory 0103 SHLD 200 ;Keep pointer there 0106 MVI E,D ;Get a CR 0108 MVI C,4 ;Output to PUNCH {send to HOST} 010A CALL 5 010D MVI C,3 ;Input from READER {read from HOST} 010F CALL 5 0112 ANI 7F ;Strip parity bit 0114 PUSH PSW ;save a and flags 0115 MOV E,A ;move char to e for echo 0116 MVI C,2 ;Output to screen 0118 CALL 5 011B POP PSW ;restore a and flags 011C CPI 40 ;Is it our DEC-20 prompt? 011E JZ 127 ;Yes, have whole file in memory 0121 CALL 17A ;no , store another byte 0124 JMP 10D ;read another byte 0127 MVI A,1A ;Get a Control-Z {CP/M EOF mark} 0129 CALL 17A ;store it in memory 012C LXI H,300 ;Get memory pointer 012F SHLD 202 ;Store as DMA pointer 0132 LDA 201 ;Get 'HI' byte of memory pointer 0135 STA 200 ;and store it as 'LO' one 0138 XRA A 0139 STA 201 ;Zero 'HI' byte {slow *256} 013C MVI C,16 ;Make NEW file 013E LXI D,5C ;With FCB1 0141 CALL 5 0144 CALL 15E ;Write 128 bytes {sector} 0147 CALL 15E ;Write another sector 014A LXI H,FFFF ;Get a 16-bit Minus One 014D XCHG ;into DE 014E LHLD 200 ;Get 256-byte counter 0151 DAD D ;decrement 0152 SHLD 200 ;and store back 0155 MVI A,2 ;Check if 0157 CMP L ; 256-byte counter down to offset 0158 JZ 183 ;Yes, wer'e done 015B JMP 144 ;Keep writing.. 015E LHLD 202 ;Get file-pointer 0161 XCHG ;into DE 0162 MVI C,1A ;Set DMA-address 0164 CALL 5 0167 MVI C,15 ;Write sector {128 bytes} 0169 LXI D,5C ;using FCB1 016C CALL 5 016F LHLD 202 ;Get file-pointer 0172 LXI D,80 ;128-bytes 0175 DAD D ;added to file-pointer 0176 SHLD 202 ;and save 0179 RET ;and return 017A LHLD 200 ;Get Memory-pointer 017D MOV M,A ;store character 017E INX H ;Increment Pointer 017F SHLD 200 ;and save 0182 RET ;and return 0183 MVI C,10 ;CLOSE file 0185 LXI D,5C ;using FCB1 0188 CALL 5 018B JMP 0 ;Force WARM BOOT 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 terminating 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 spe- cial 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: 1. For purposes of illustration, we will assume the system-dependent 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 con- vert 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 understand 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 locally 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 information is invalid: ?Kermit has not been configured for a target system or ?Consistency check on configuration failed 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 be- cause 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. 12.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 ex- cept for CP4LNK.ASM, which is assembled into the system-dependent 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 con- figure 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 as- sembled for each supported system; the filename may be obtained from table 12-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: 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 Ker- mit there with MAC80, producing CP4KER.HEX: .run mac80 *=cp4ker.asm If you want to generate a system-dependent overlay for a particular system, 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 ad- dress of "LNKFLG" in the system-independent module, as the starting address of the overlay (3400H for version 4.05). You'll need to know this value if you're building the overlay with M80/L80. You won't normally 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 12-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 sys- tem uses an external terminal as the console, locate the terminal in table 12-3 and define the appropriate symbol TRUE, and the remainder FALSE. If the ter- minal is not listed in table 12-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 if you wish the default TACTRAP status to be ON. (This may be overrid- den 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 hap- pens, 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 fol- lows: - 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 distribution 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 Kermit: - Tops-10: .copy kernew.hex=cp4ker.hex,cp4typ.hex .link80 kernew - Tops-20: @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 12-3: Terminals known to Kermit-80 ------------------------------------------------------------------------------- 12.5. Adding Support For A New System Kermit-80 is built from a common set of source files; the system-dependent 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 system, 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 inter- face 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. 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 different interfaces (ACIA, SIO, etc) are present. 12.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 exter- nal terminal. SET DEBUG OFF removes these fields. The VERSION command dis- plays 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 ter- minal 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 in- tercept character, which is initially "@". "SET TAC OFF" disables the TACtrap. (These comments apply equally to any communication 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 reassemble 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. 12.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 system. These source files should serve as simple models for adding support for new systems to Kermit-80 -- only the very basic screen defini- tions, flags, i/o primitives, initializations, and so forth should appear in each system-dependent file. - Make the file-stepping mechanism faster (buffer the FCB's in chunks th 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 commands for servers (REMOTE DIRECTORY, etc), command macros and initialization files, login scripts, remote operation and server mode, etc etc. Index , 8080 221, 223 XON/XOFF 218 ARPAnet 233 Z80 223 Attention Character 233 Baud 219 BIOS 221 Block Check 220 Bootstrap 225 BYE 218 Connect 217 CP/M 224 Downloading 225 Eighth-Bit Prefix 219 Escape Character 217, 219 File-Warning 218 FINISH 219 Generic Kermit-80 221 GET 218 IBM 220 Intercept Character 233 Local 216 Local-Echo 219 LOG 218 LOGOUT 218 NAK 217 Parity 219 RECEIVE 218 SEND 218 SET 219 TAC 233 Timeout 216, 217, 224 TIMER 219 TRANSMIT 218 VERSION 219 Virtual Terminal 217 VT100 219 VT52 219 Warning 219 Table of Contents 12. CP/M-80 KERMIT 215 12.1. Summary of CP/M 215 12.2. Kermit-80 Description 216 12.3. Kermit-80 Flavors 221 12.3.1. Generic Kermit-80 221 12.3.2. CP/M 3 Kermit 222 12.3.3. System-Specific Versions 222 12.4. Installation of Kermit-80 223 12.4.1. Organization of Kermit-80 224 12.4.2. Downloading Kermit-80 225 12.4.3. Assembling Kermit-80 from the sources 229 12.5. Adding Support For A New System 232 12.6. Notes on New Features in Kermit-80 Version 4 233 12.7. Future Work 233 Index i List of Tables Table 12-1: Kermit-80 SET PORT Options 222 Table 12-2: Systems supported by Kermit-80 225 Table 12-3: Terminals known to Kermit-80 232