MS-DOS KERMIT Page 90 10. MS-DOS KERMIT Program: Daphne Tzoar and Jeff Damens, Columbia University; contribu- tions by many others. Language: Microsoft Macro Assembler (MASM) Documentation: Frank da Cruz, Columbia University; Herm Fischer, Litton Data Systems, Van Nuys CA. Version: 2.26 Date: July 1984 Kermit-MS Capabilities At A Glance: Local operation: Yes Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Y interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: Yes Alternate block checks: Yes Terminal emulation: Yes Communication settings: Yes Transmit BREAK: Yes IBM mainframe communication: Yes Transaction logging: No Session logging: Yes Raw transmit: No Act as server: Yes Talk to server: Yes Advanced server functions: No Advanced commands for servers: Yes Local file management: Yes Handle file attributes: No Command/init files: Yes Command macros: Yes Kermit-MS is a program that implements the KERMIT file transfer protocol for the IBM PC and several other machines using the same processor family (Intel 8088 or 8086) and operating system family (PC-DOS or MS-DOS, henceforth referred to collectively as MS-DOS, versions 1.1, 2.0, and 2.1, and thereafter). This section will describe the things you should know about the MS-DOS file system in order to make effective use of Kermit, and then it will describe the Kermit-MS program. Version 2 of MS-DOS Kermit runs on a variety of systems, including the IBM PC and XT, the HP-150, the DEC Rainbow 100 and 100+ (MS-DOS 2.05 and above), the Wang PC, and there is a "generic" MS-DOS version. Version 1 was adapted at various stages of development to run on other systems as well, including the Heath/Zenith 100, Tandy 2000, Victor 9000 (Sirius-1), and Seequa Chameleon, and is still available for those sys- tems until support for them and others is added to version 2. MS-DOS KERMIT Page 91 The program operates under version 1.1 or 2.0 and above of DOS, although some features require the functionality of 2.0. It runs in ap- proximately 80K of memory -- over and above the memory used by DOS -- which means that your system should have at least 128K of RAM to use version 2 of MS-DOS Kermit; smaller systems may still use Version 1. 10.1. The MS-DOS File System The features of the MS-DOS file system of greatest interest to KERMIT users are the form of the file specifications, and the distinction be- tween pre-MS-DOS 2.0 file names and newer file names which allow direc- tory paths. 10.1.1. File Specifications MS-DOS 2.x file specifications are of the form DEVICE:\PATHNAME\NAME.TYPE where the DEVICE is a single character identifier (for instance, A for the first floppy disk, C for the first fixed disk, D for a RAM disk emulator), PATHNAME is up to 63 characters of identifier(s) (up to 8 characters each) surrounded by reverse slashes, NAME is an identifier of up to 8 characters, and TYPE is an identifier of up to 3 characters in length. Device and pathname may be omitted. The first backslash in the pathname may be omitted if the specified path is relative to the current directory. In the path field, "." means current directory, ".." means parent directory. Some DOS implementations (like Wang) may use slash "/" rather than backslash in the path field. Pathname is normally omitted, and cannot be specified for MS-DOS 1.x or with those commands which allow MS-DOS 1.x use. Device and directory pathnames, when omitted, default to either the user's current disk and directory, or to the current directory search path as specified in the DOS PATH environment variable, depending on the context in which the file name appears. When this manual says that a file is searched for "in the cur- rent path," it means that the PATH is searched first, and if the file is not found, then Kermit-MS looks on the current disk and directory. If the PATH environment variable is empty, Kermit looks only at the current disk and directory. NAME.TYPE is normally sufficient to specify a file, and only this infor- mation is sent along by Kermit-MS with an outgoing file. The device, path, name, and type fields may contain uppercase letters, digits, and the special characters "-" (dash), "_" (underscore), and "$" (dollar sign). (For use only among MS-DOS processors, additional filename special characters allowed are "#&!%'`(){}". DOS 1.x allows others as well.). There are no imbedded or trailing spaces. Other characters may be not be included; there is no mechanism for "quoting" otherwise illegal characters in filenames. The fields of the file specification are set off from one another by the punctuation indicated MS-DOS KERMIT Page 92 above. The name field is the primary identifier for the file. The type, also called the extension or suffix, is an indicator which, by convention, tells what kind of file we have. For instance FOO.BAS is the source of a BASIC program named FOO; FOO.OBJ might be the relocatable object module produced by compiling FOO.BAS; FOO.EXE could be an executable program produced by linking FOO.OBJ, and so forth. .EXE and .COM are the normal suffixes for executable programs. The MS-DOS allows a group of files to be specified in a single file specification by including the special "wildcard" characters, "*" and "? ". A "*" matches any string of characters from the current position to the end of the field, including no characters at all; a "?" matches any single character. Here are some examples: *.BAS All files of type BAS (all BASIC source files) in the current directory. FOO.* Files of all types with name FOO. F*.* All files whose names start with F. F?X*.* All files whose names start with F and contain X in the third position, followed by zero or more characters. ?.* All files whose names are exactly one character long. Wildcard notation is used on many computer systems in similar ways, and it is the mechanism most commonly used to instruct Kermit to send a group of files. Note: Kermit-MS uses the "?" character for help while commands are being typed, so the single-character wildcard in Kermit-MS commands is "=" rather than "?". For example Kermit-MS>send =.* would send files of all types whose names were exactly one character long. Kermit-MS users should bear in mind that other (non-MS-DOS) systems may use different wildcard characters. For instance the DEC-20 uses "%" in- stead of "?" as the single character wildcard; when using Kermit-MS to request a wildcard file group from a KERMIT-20 server, the Kermit-MS "=" must be replaced by the DEC-20 "%". 10.1.2. File Formats MS-DOS systems store files as bulk collections of 8 bit bytes, with no particular differences between text, program code, and binary files. ASCII text files consist of lines separated by carriage-return-linefeed sequences (CRLFs), which conforms exactly to the way Kermit represents text files during transmission. Since a non-MS-DOS receiving system might need to make distinctions as to file type, you may need to use MS-DOS KERMIT Page 93 various SET functions on the remote system to inform it that the incom- ing file is of some particular (non-default) type, such as binary. In transmitting files between Kermit-MS's, regardless of file contents, the receiving MS-DOS system is equally capable of processing text, code, and data, and in fact has no knowledge of how the bytes in the file are used. MS-DOS (unlike CP/M) is capable of pinpointing the end of file with precision by keeping a byte count in the directory, so one would expect no particular confusion in this regard. However, certain MS-DOS programs continue to use the CP/M convention of terminating a text file with a Control-Z character, and won't operate correctly unless this ter- minating byte is present. Therefore, Kermit-MS users should be aware of a special SET EOF option for both incoming and outbound files, described below. Non-MS-DOS systems may well be confused by nonstandard ASCII files from Kermit-MS. Files produced by Easywriter or Word Star, for example, may need to be converted to conventional ASCII format prior to transmission by commonly available "exporter" programs. Spreadsheet or database files usually need special formatting to be meaningful to non-MS-DOS recipients (though they can be transmitted between MS-DOS systems with Kermit-MS). Furthermore, files created by word processors (such as BLUE or Easy Writer) that store formatting data at the end of the file, after the control-Z and before physical end, will require special processing via SET EOF to strip the formatting data, lest they confuse non-MS-DOS recipients. 10.2. Program Operation Kermit-MS can be run interactively, from a batch file, or as an "external" DOS command. Commands consist of one or more fields, separated by "whitespace" -- one or more spaces or tabs. Upon initial startup, the program executes any commands found in the file MSKERMIT.INI in the current path. This initialization file may contain command macro definitions, communications settings for one or more ports, or any other Kermit-MS commands. Here is a sample MSKERMIT.INI file: set warning on ; Enable filename collision avoidance. ; ; Define some macros ; define unix set local-echo off, set flow xon, set timer off def ibm set parity odd, set local on, set handsh xon, set timer on def modem set port 2, set baud 1200 def noisy set block-check 3, set send packet-length 40 ; ; Select a port ; set port 1 ; Select COM1 for communications, set baud 4800 ; setting the speed to 4800 baud, connect ; and make a terminal connection. MS-DOS KERMIT Page 94 Note that comments may be included by prefixing them with a semicolon. The program can be run in several ways. Interactive Operation: To run Kermit-MS interactively, invoke the program from DOS command level by typing its name. When you see the command's prompt, Kermit-MS> you may type Kermit commands repeatedly until you are ready to exit the program, for example: A> A>kermit IBM PC Kermit-MS V2.26 Type ? for help Kermit-MS>send foo.* informational messages about the files being sent Kermit-MS>get bar.* informational messages about the files being received Kermit-MS>exit A> During interactive operation, you may edit the command you're currently typing to erase the character most recently typed (BACKSPACE or DEL), the most recent field (CTRL-W), or the entire command (CTRL-U). In ad- dition, you may use the help ("?") and recognition (ESC) features freely while typing Kermit-MS commands. A question mark typed at almost any point in a command produces a brief description of what is expected or possible at that point; for this reason, Kermit-MS uses "=" for the single-character match wildcard in local filenames. ESC typed at any point, even in a local filename, will cause the current field to be filled out if what you have typed so far is sufficient to identify it, and will leave you in position to type the next field (or to type a "?" to find out what the next field is); otherwise, the program will beep at you and wait for you to type further characters. Some Kermit-MS commands, like GET, SHOW KEY, SET KEY, may prompt for ad- ditional information on subsequent lines. If you have reached one of these prompts and then wish to cancel the command, you may type Control-C. Summary of Kermit-MS Command Characters: BACKSPACE Delete the character most recently typed. May be typed repeatedly to delete backwards. You may also use DELETE, RUBOUT, or equivalent keys. MS-DOS KERMIT Page 95 CTRL-W Delete the most recent "word", or field, on the command line. May be typed repeatedly. CTRL-U Delete the entire command line. CTRL-C Cancel the current command and return to the "Kermit-MS>" prompt. ? Type a brief message describing what you are expected to type in the current field. ESC If enough characters have been supplied in the current field (keyword or file name) to uniquely identify it, supply the remainder of the field and position to the next field of the command. Otherwise, sound a beep. = Wildcard character for matching single characters in filenames, equivalent to MS-DOS "?". Command Line Invocation: Kermit-MS may also be invoked with command line arguments from DOS com- mand level, for instance: A>kermit send foo.bar or A>kermit set port 1, set baud 9600, connect In this case, help and recognition are not available (because the program won't start running until after you type the entire command line), and Kermit-MS will exit after completing the specified command or commands. Therefore, when invoked with command line arguments, Kermit-MS will behave as if it were an external DOS command, like MODE. Note that several commands may be given on the command line, separated by commas. Batch Operation: Like other MS-DOS programs, Kermit-MS may be operated under batch with either command line arguments and/or TAKE files; Kermit will also run interactively if invoked from batch, but it will read commands from the keyboard and not the batch file. 10.3. Kermit-MS Commands MS-DOS Kermit implements a large subset of the commands of "ideal" Ker- mit. Here's a brief summary: BYE to remote server. CLOSE log file and stop logging remote session. CONNECT as terminal to remote system. MS-DOS KERMIT Page 96 DEFINE macros of Kermit-MS commands. DELETE local files. DIRECTORY listing of local files. DO a macro expansion. EXIT from Kermit-MS. FINISH Shut down remote server. GET remote files from server. HELP about Kermit-MS. LOCAL prefix for local file management commands. LOG remote terminal session. LOGOUT remote server. PUSH to MS-DOS command level. QUIT from Kermit-MS RECEIVE files from remote Kermit. REMOTE prefix for remote file management commands. RUN an MS-DOS program. SEND files to remote Kermit. SERVER mode of remote operation. SET various parameters. SHOW various parameters. SPACE inquiry. STATUS inquiry. TAKE commands from file. The remainder of this section concentrates on the commands that have special form or meaning for MS-DOS Kermit. Not all of the following commands are necessarily available on all MS-DOS systems, and some of the commands may work somewhat differently between DOS versions. 10.3.1. Commands for File Transfer The file transfer commands are SEND, GET, and RECEIVE. THE SEND COMMAND Syntax: SEND filespec1 [filespec2] The SEND command causes a file or file group to be sent from the local MS-DOS system to the Kermit on the remote system. The remote Kermit may be running in either server or interactive mode; in the latter case, you should already have given it a RECEIVE command and escaped back to your PC. filespec1 may contain a device designator, like "A:" and the wildcard characters "*" and/or "=". The current release of Kermit-MS, however, does not allow pathnames in the SEND command file specification. If filespec1 contains wildcard characters then all matching files will be sent, in the same order that MS-DOS would show them in a directory listing. If filespec1 specifies a single file, you may direct Kermit-MS to send that file with a different name, given in filespec2. For in- stance, in the command Kermit-MS>send foo.bar framus.widget MS-DOS KERMIT Page 97 filespec2 begins with the first nonblank character after filespec1 and ends with the carriage return; thus it may contain blanks or other un- usual characters that may be appropriate on the target machine. Lower case letters in filespec2 are raised to upper case for transmission. If a file can't be opened for read access, standard MS-DOS recovery procedures will take place. For example: Not ready error reading drive A Abort, Retry, Ignore? If you select "Abort," you will be returned to DOS. Files will be sent with their MS-DOS filename and filetype (for instance FOO.TXT, no device or pathname). Each file is sent as is, with no con- versions done on the data, except for possibly adding or deleting a ter- minating Control-Z character (see the SET EOF command). Once you give Kermit-MS the SEND command, the name of each file will be displayed on your screen as the transfer begins; packet, retry, and other counts will be displayed along with informational messages during the transfer. If the file is successfully transferred, you will see "Complete", otherwise there will be an error message. When the specified operation is done, the program will sound a beep. Several single-character commands may be given while a file transfer is in progress: ^X (Control-X) Stop sending the current file and go on to the next one, if any. ^Z Stop sending this file, and don't send any further files. ^C Return to Kermit-MS command level immediately without sending any kind of notification to the remote system. ^E Like ^C, but send an Error packet to the remote Kermit in an at- tempt to bring it back to server or interactive command level. CR Simulate a timeout: resend the current packet, or NAK the expected one. Control-X and Control-Z send the proper protocol messages to the remote Kermit to bring it gracefully to the desired state. Control-C leaves the remote Kermit in whatever state it happens to be in. Control-E "aborts" any protocol that is taking place. THE RECEIVE COMMAND Syntax: RECEIVE [filespec] The RECEIVE command tells Kermit-MS to receive a file or file group from the other system. Kermit-MS simply waits for the file to arrive; this command is not to be used when talking to a Kermit server (use GET for that). You should already have issued a SEND command to the remote Ker- MS-DOS KERMIT Page 98 mit and escaped back to Kermit-MS before issuing the RECEIVE command. If the optional filespec is provided, store the incoming file under that name. The filespec may include a device designator, or may consist of only a device designator. The incoming file is stored on the default or specified device (current directory in DOS 2.0 and thereafter). If no name was specified, the name from the incoming file header packet is used; if that name is not a legal MS-DOS file name, Kermit-MS will delete excessive characters from it, and will change illegal characters to the letter X. If the optional filespec was provided, but more than one file arrives, the first file will be stored under the given filespec, and the remainder will be stored under their own names, but on the specified device. If an incoming file does not arrive in its entirety, Kermit-MS will nor- mally discard it; it will not appear in your directory. You may change this behavior by using the command SET INCOMPLETE KEEP, which will cause as much of the file as arrived to be saved in your directory. The same single-character commands are available as during SEND: ^X Request that the remote Kermit stop sending the current file, and proceed to the next one immediately. Since this is an optional feature of the Kermit protocol, the remote Kermit might not honor the request. ^Z Request that the remote Kermit terminate the entire transfer; this is also an optional feature that may or may not be supported by the remote Kermit. ^C, ^E, and CR operate in the same way as they do during SEND. If the incoming file has the same name as a file that already exists, and WARNING is set ON, Kermit-MS will change the incoming name (and in- form you how it renamed it) so as not to obliterate the pre-existing file. If WARNING is OFF, the original file will be overwritten; if you type ^X or ^Z to interrupt the transfer, you'll either get a partial new file, or else both the old and the new file of that name will be lost, depending on SET INCOMPLETE. In any case, when WARNING is off, files with the same name as incoming files will not survive. Caution: If an incoming file's name (the part before the dot) cor- responds to an MS-DOS device name, such as NUL, COM1, CON, AUX, or PRN, output will go to that device, rather than to a file with that name. This is a feature of MS-DOS. MS-DOS KERMIT Page 99 THE GET COMMAND Syntax: GET remote-filespec The GET command requests a remote KERMIT server to send the file or file group specified by remote-filespec. This command can be used only when Kermit-MS has a KERMIT server on the other end of the connection. This means that you must have CONNECTed to the other system, logged in, run KERMIT there, issued the SERVER command, and escaped back (e.g. ^]C) to the local Kermit-MS. If the remote Kermit does not have a SERVER com- mand, then you should use SEND and RECEIVE as described above. You may use the GET command to specify a different name for storing the incoming. Just type GET alone on a line, and you will be prompted separately for the remote filespec and the local filespec: Kermit-MS>get Remote Source File: com1.txt Local Destination File: xcom1.txt If more than one file arrives, only the first will be renamed. The remote filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. It can contain whatever wildcard or file-group notation is valid on the remote system. As files arrive, their names will be displayed on your screen, along with packet traffic statistics and status messages. You may type ^X to request that the current incoming file be cancelled, ^Z to request that the entire incoming batch be cancelled, and ^C or ^E to return im- mediately to the Kermit-MS> prompt, exactly as described for the RECEIVE command. 10.3.2. Commands for Connecting and Disconnecting The CONNECT command connects your PC as a terminal to the remote system, so that you can start up Kermit there. The BYE, FINISH, and LOGOUT com- mands allow you to shut down a remote Kermit server. BYE When communicating with a remote KERMIT server, use the BYE command to shut down the server, log out its job, and exit from Kermit-MS to DOS. FINISH Like BYE, FINISH shuts down the remote server. However, FINISH does not log out the server's job. You are left at Kermit-MS prompt level so that you can connect back to the job on the remote system. LOGOUT The LOGOUT command is identical to the BYE command, ex- cept you will remain at Kermit-MS prompt level, rather than exit to DOS, so that you can establish another con- nection. MS-DOS KERMIT Page 100 The CONNECT Command Establish an interactive terminal connection to the system connected to the currently selected communications port (e.g. COM1 or COM2) using full duplex (remote) echoing and no parity unless otherwise specified in previous SET commands. Get back to Kermit-MS by typing the escape character followed by the letter C. The escape character is Control-] by default. You can use the SET ESCAPE command to define a different escape charac- ter, and on some systems (including the PC and XT) you can SET BAUD to change the baud rate, and SET PORT to switch between ports. Terminal emulation is described in greater detail in section 10.4 below. 10.3.3. Commands for File Management Kermit-MS provides commands or managing both local and remote files. THE REMOTE COMMANDS The REMOTE keyword is a prefix for a number of commands. It indicates that the command is to be performed by the remote Kermit, which must be running as a server. Note that not all Kermit servers are capable of executing all these commands, and some Kermit servers may be able to perform functions for which Kermit-MS does not yet have the correspond- ing commands. In case you send a command the server cannot execute, it will send back a message stating that the command is unknown to it. If the remote server can execute the command, it will send the results to your screen. Here are the REMOTE commands which Kermit-MS may issue: CWD [directory] Change Working Directory on the remote host. Change the default source and destination area for file transfer and management. You will be prompted for a password, which will be erased as you type it. If you do not supply a password (i.e. you type only a carriage return), the server will attempt to access the specified directory without a password. If you do not supply a directory name, your default or login directory on the remote system will be assumed. DELETE filespec Delete the specified file or files on the remote system. In response, the remote host should display a list of the files that were or were not successfully deleted. DIRECTORY [filespec] The remote system will provide a directory listing of the specified files. If no files are specified, then all files in the default area (the current working directory) will be listed. HELP The remote host tells what server functions it is capable of. HOST [command] Send the command to the remote system's command proces- MS-DOS KERMIT Page 101 sor for execution. SPACE [directory] Provide a brief summary of disk usage in the specified area on the remote host. If none specified, the default or current area will be summarized. TYPE filespec Display the contents of the specified remote file or files on the screen. THE LOCAL COMMAND The LOCAL keyword is a prefix for a number of commands. It indicates that the specified command is to be executed on the local MS-DOS system. The LOCAL prefix may be omitted. The local commands available are: DELETE filespec Deletes the specified file or files. As in DOS, the names of the deleted files are not listed, only the mes- sage "file(s) deleted" or "file(s) not found", and if you give the command "delete *.*", Kermit-MS will prompt "Are you sure?", like DOS. DIRECTORY [filespec] Lists the names, sizes, and creation dates of files that match the given file specification. If no filespec is given, the command is equivalent to DIR *.*. SPACE Performs the MS-DOS CHKDSK function by running the CHKDSK program from the current path, or default disk under DOS 1.1. RUN filespec Runs the specified file, which must be in .EXE or .COM format, from the specified path or according to the value of the PATH variable if no path was included in the filespec. This command requires MS-DOS 2.0 or higher. PUSH Invokes an MS-DOS command processor "under" Kermit-MS, either COMMAND.COM or whatever shell you have specified with COMSPEC. When you return to Kermit-MS (for in- stance, by typing the MS-DOS EXIT command), you will find Kermit-MS as you left it, with all settings intact. This command only works in MS-DOS 2.0 or higher. The local RUN command has various uses, one of which is to supplement the features of Kermit-MS. For instance, suppose there is an involved procedure that you regularly perform on a certain remote system -- this might include giving commands to a modem to dial the system, looking for a particular herald or prompt, performing a login command sequence, run- ning a selected application, and then running Kermit to send the results back to your PC. You could write a program in the compiled language of your choice, say C or BASIC, to send the desired commands to your modem and the remote system and to look for the appropriate responses. You could put all this in a Kermit-MS TAKE command file (see below), like MS-DOS KERMIT Page 102 run update.com receive The program, called UPDATE in this case, does everything up to and in- cluding starting Kermit sending from the remote system. When the program terminates, the next Kermit-MS command, "receive," is executed from the command file. When the end of the command file is reached, in- teractive operation is resumed. THE TAKE COMMAND Syntax: TAKE filespec Execute Kermit commands from the specified file, which may include an explicit path; if no path is specified, the value of the PATH variable is used; if PATH has no value, then the current disk and directory are searched. The command file may include TAKE commands, but it cannot in- clude characters to be sent to a remote host during terminal emulation (i.e. after a CONNECT command). A command file may include comments prefixed by semicolons. THE LOG COMMAND Syntax: LOG filespec Specifies that all characters that appear on your screen during CONNECT will be recorded in the specified file. This allows you to "capture" files from a remote system that doesn't have Kermit, as well as to record remote command typescripts. The log is closed when you EXIT from Kermit-MS or when you issue an explicit CLOSE command. 10.3.4. The SERVER Command Kermit-MS is capable of acting as a Kermit server, providing file trans- fer for users coming in through one of the communication ports. The current version of Kermit-MS can send files (the user on the other end types the GET command), receive files (the user types SEND), and ter- minate, giving control back to the console (user types BYE). To put Kermit-MS into server mode, first issue any desired SET commands to select and configure the desired port, and then type the SERVER com- mand. Kermit-MS will await all further instructions from the user Ker- mit on the other end of the connection, which may be hardwired or con- nected through an autoanswer modem. For example: Kermit-MS>set port 1 Kermit-MS>set baud 1200 Kermit-MS>set timer on Kermit-MS>set warning on Kermit-MS>server MS-DOS KERMIT Page 103 10.3.5. The SET Command Syntax: SET parameter [value] Establish or modify various parameters for file transfer or terminal connection. You can examine their values with the SHOW command. Note that there is no "set ibm" command; IBM mainframe communication parameters may be selected with a command macro (see below). The fol- lowing SET commands are available in Kermit-MS: BAUD Communications port line speed BELL Whether to beep at the end of a transaction BLOCK-CHECK-TYPE Level of error checking for file transfer DEBUG Display packet contents during file transfer DEFAULT-DISK Default disk drive for file i/o DESTINATION Default destination device for incoming files END-OF-LINE Packet terminator EOF Method for determining or marking end of file ESCAPE Escape character for CONNECT FLOW-CONTROL Enable or disable XON/XOFF HANDSHAKE Half-duplex line turnaround option HEATH19 Heath/Zenith-19 terminal emulation INCOMPLETE What to do with an incompletely received file KEY Specify key redefinitions, or "keystroke macros" LOCAL-ECHO Specify which host does the echoing during CONNECT PARITY Character parity to use PORT Select a communications port PROMPT Change the "Kermit-MS>" prompt to something else RECEIVE Request remote Kermit to use specified parameters REMOTE For running Kermit-MS interactively from back port SEND Use the specified parameters during file transfer TAKE-ECHO Control echoing of commands from TAKE files TIMER Enable/disable timeouts during file transfer WARNING Specify how to handle filename collisions The SET commands that are peculiar to MS-DOS Kermit are now described in greater detail. The others behave as in "ideal" Kermit. SET BAUD Syntax: SET BAUD rate Set the speed of the currently selected terminal communications port (COM1 by default) to 300, 1200, 1800, 2400, 4800, 9600 or other common baud rate. Some implementations do not support this command. In any case, Kermit-MS leaves the current communication port settings alone un- less you issue explicit SET commands to change them. SET BELL Syntax: SET BELL ON or OFF Specifies whether bell (beeper) should sound upon completion of a file transfer operation. MS-DOS KERMIT Page 104 SET DEBUG Syntax: SET DEBUG ON or OFF ON Display the Kermit packet traffic on your screen during file transfer. If the debugger is loaded, transfer control to it when CTRL-C is typed. In Heath-19 terminal emulation on the IBM PC, display unusual control characters in uparrow notation. OFF Don't display debugging information (this is the default). If debugging was in effect, turn it off. SET DEFAULT-DISK Syntax: SET DEFAULT-DISK x: Specify the default disk drive to use for file transfer, directory list- ings, and so forth. Equivalent to typing the DOS command for changing disks. SET DESTINATION Syntax: SET DESTINATION device Specify the device for incoming files, DISK or PRINTER. SET DESTINATION PRINTER will cause incoming files to be spooled directly to the printer. The normal destination is DISK. END-OF-LINE Syntax: SET END-OF-LINE number If the remote system needs packets to be terminated by anything other than carriage return, specify the decimal value of the desired ASCII character. SET EOF Syntax: SET EOF option Controls how the end of file is handled. The options are: CTRL-Z Append a Control-Z character to the end of an incoming file, unless it already ends with a Control-Z. Certain MS-DOS text editors and other applications require files to be in this format. For outbound files, treat the first Control-Z as the end of file, and do not send it nor any characters following it. NOCTRL-Z (Default) Store incoming files exactly as is, and send MS DOS files exactly as is (according to their byte count). MS-DOS KERMIT Page 105 SET ESCAPE Syntax: SET ESCAPE character Specify the control character you want to use to "escape" from remote connections back to Kermit-MS. The default is normally ^] (Control- Rightbracket). The character is entered literally, and should normally be chosen from the ASCII control range. SET FLOW-CONTROL Syntax: SET FLOW-CONTROL option Specify the full duplex flow control to be done on the currently selected port. The current options are XON/XOFF and NONE. The specified type of flow control will be done during both terminal emula- tion and file transfer. If set to XON/XOFF, HANDSHAKE is automatically set to OFF. SET HANDSHAKE Syntax: SET HANDSHAKE option Specify any half-duplex handshaking to be done on the currently selected port. The options are BELL, CR, LF, NONE, XOFF, or XON. The specified handshaking will be done during file transfer only. If HANDSHAKE is set to anything other than NONE, FLOW-CONTROL is automatically set to OFF. SET HEATH19 Syntax: SET HEATH19 ON or OFF Specify whether Kermit-MS should use its built-in software facility for emulating a Heath/Zenith-19 (H19) terminal. ON During CONNECT, incoming characters are to be examined for H19 terminal screen control commands (escape sequences), and if en- countered, the commands are to be emulated on the PC screen. The H19 codes are a superset of the popular DEC VT52 codes, so if your system does not support the Heath-19, you may tell it that your terminal type is VT52 (or one of the many VT52 compatibles). The Heath-19 codes are listed in section 10.10, below. OFF All incoming characters will be sent to the screen "bare", through DOS. If you have loaded a device driver into DOS for the CON: device, such as ANSI.SYS, then that driver will be able to interpret the codes itself. Most non-IBM systems have their own screen control code interpreter built into DOS or firmware, or available as a loadable device driver. See section 10.4 for details about terminal emulation. MS-DOS KERMIT Page 106 SET KEY Syntax: SET KEY key-specifier Specifies that when the designated key is struck during terminal emula- tion, the associated character string is sent. The key-specifier is one of the keywords F1, F2, ..., or SCAN followed by a scan code. Systems that have a BACKSPACE key also include BACKSPACE as a keyword. If SCAN is used, it is followed by a decimal number to indicate the scan code of the key, which you would ascertain from your system reference manual, or else by using the Kermit-MS SHOW KEY command. SET KEY prompts you on a new line for the definition string. Certain charac- ters, like ESC and CR, may not be entered literally into the string, but can be included by inserting escape codes of the form \ooo, a backslash followed by a 2- or 3-digit octal number corresponding to the ASCII value of the desired character. If some other key redefinition package, like ProKey, has been loaded, then its redefinitions will take precedence over Kermit's. The SET KEY command is illustrated in the terminal emulation section, 10.4, below. SET LOCAL-ECHO Syntax: SET LOCAL-ECHO option Specify how characters are echoed during terminal emulation on the cur- rently selected port. ON specifies that characters are to be echoed by Kermit-MS (because neither the remote computer nor the communications circuitry has been requested to echo), and is appropriate for half- duplex connections. LOCAL-ECHO is OFF by default, for full-duplex, remote echo operation. When you SET LOCAL-ECHO ON, the current HANDSHAKE (if any) is automati- cally enabled and full-duplex FLOW-CONTROL is automatically turned off. When you SET LOCAL-ECHO OFF, HANDSHAKE is also disabled, and the current mode of FLOW-CONTROL (if any) is enabled. If this behavior is un- desired, you may override it by typing explicit SET HANDSHAKE or SET FLOW commands after entering the SET LOCAL-ECHO command. SET PARITY Syntax: SET PARITY keyword Specify the character parity to be used on the currently selected port. The choices for SET PARITY are NONE (the default), ODD, EVEN, MARK, and SPACE. NONE means no parity processing is done, and the 8th bit of each character can be used for data when transmitting binary files. You will need to SET PARITY to ODD, EVEN, MARK, or possibly SPACE when communicating with a system, or over a network, or through modems, con- centrators, multiplexers, or front ends that require or impose character parity on the communication line. For instance, GTE Telenet requires MS-DOS KERMIT Page 107 MARK parity. If you neglect to SET PARITY when the communications equi- pment requires it, the symptom may be that terminal emulation works par- tially, and file transfer does not work at all. If you have set parity to ODD, EVEN, MARK, or SPACE, then Kermit-MS will request that binary files will be transferred using 8th-bit-prefixing. If the other side knows how to do 8th-bit-prefixing (this is an optional feature of the KERMIT protocol, and not all implementations of KERMIT have it), then binary files can be transmitted successfully. If NONE is specified, 8th-bit-prefixing will not be requested. Note that there is no advantage to using parity; it only slows Kermit file transfer down. The SET PARITY command is provided only to allow Kermit to adapt to hardware that insists upon using parity. SET PORT Syntax: SET PORT number On machines with more than one communications port, select the port to use for file transfer and CONNECT. This command lets you use a dif- ferent asynchronous adapter, or switch between two or more simultaneous remote sessions. Subsequent SET BAUD, PARITY, HANDSHAKE, FLOW, and LOCAL-ECHO commands will apply to this port only. SET PORT 1 selects COM1, SET PORT 2 selects COM2. SET REMOTE Syntax: SET REMOTE ON or OFF If you wish to run Kermit-MS interactively through the back port, for instance after the operator has done CTTY COM1, you must give the com- mand SET REMOTE ON; this suppresses the file transfer display screen, so that the display won't interfere with the file transfer itself. SET RECEIVE Syntax: SET RECEIVE parameter value At the beginning of a protocol operation, request the remote Kermit to use the given value specified parameter, or inform Kermit-MS that the remote Kermit will be using it. PACKET-LENGTH Ask the remote Kermit to use the specified maximum length for packets that it sends to Kermit-MS. The nor- mal (and maximum) length is 94. Use this command to shorten packets if the communication line is noisy; this will decrease the probability that a particular packet will be corrupted, and will reduce the retransmission overhead when corruption occurs, but it will increase the protocol overhead. PADCHAR Ask the remote Kermit to use the given character for in- terpacket padding. Kermit-MS should never require any MS-DOS KERMIT Page 108 padding. PADDING Ask the remote Kermit to insert the given number of pad- ding characters before each packet it sends. This should never be necessary. START-OF-PACKET The remote Kermit will be marking the beginning of pack- ets with something other than Control-A. This will be necessary only if the hosts or communication equipment involved cannot pass a Control-A through as data. TIMEOUT Ask the remote Kermit to time out after the given number of seconds if a packet expected from Kermit-MS has not arrived. Use this command to change the normal timeout interval. SET SEND Syntax: SET SEND parameter value PACKET-LENGTH Use the specified maximum length for outbound packets. Normally, Kermit-MS uses whatever length the other Ker- mit requests. PADCHAR Use the specified character for interpacket padding. Some hosts may require some padding characters (normally NUL or DEL) before a packet. PADDING How many padding characters to use between packets, nor- mally zero. QUOTE Use the indicated printable character for prefixing (quoting) control characters and other prefix charac- ters. The only reason to change this would be for send- ing a very long file that contains very many "#" charac- ters (the normal control prefix) as data. START-OF-PACKET Mark the beginning of outbound packets with some control character other than Control-A. This will be necessary only if the remote host or the communication channel in- volved cannot accept a Control-A as data. The remote host must have been given the corresponding SET RECEIVE START-OF-PACKET command. TIMEOUT Change Kermit-MS's normal timeout interval; this command is effective only if TIMER is set to be ON; it is nor- mally OFF so that the remote KERMIT can control timeouts. MS-DOS KERMIT Page 109 SET TAKE-ECHO Syntax: SET TAKE-ECHO ON or OFF Specifies whether screen display should occur during implicit or ex- plicit TAKE operations on MSKERMIT.INI or other Kermit-MS command files, and during evaluation of macro definitions. Handy for finding errors in command files. SET TIMER Syntax: SET TIMER ON or OFF Enable or disable the timer that is used during file transfer to break the deadlock that occurs when an expected packet does not arrive. By default, the timer is OFF, because Kermit-MS is usually used in conjunc- tion with a mainframe that is doing its own timeouts. During a file transfer, it is sufficient for one side to do the timing out and the mainframe is usually better equipped to adjust timeout intervals based on system load or other conditions. The timer should be set ON if you are communicating with a system that cannot do timeouts, such as IBM VM/CMS Kermit. SET WARNING Syntax: SET WARNING option Specify what to do when an incoming file has the same name as an exist- ing file in the default directory of the default device. If ON, Kermit will warn you when an incoming file has the same name as an existing file, and automatically rename the incoming file (as indicated in the warning message) so as not to destroy (overwrite) the pre-existing one. If OFF, the pre-existing file is destroyed, even if the incoming file does not arrive completely. 10.3.6. The SHOW Command Syntax: SHOW option Currently, most parameters that may be altered with SET commands are displayed by the STATUS command. The SHOW command is used for display- ing macro definitions and key redefinitions. The SHOW MACROS command displays the definitions of all currently defined macros. The SHOW KEY command allows you to determine the scan code produced by pressing a given key, so that you can construct a SET KEY command to redefine the key. If the key already has a redefinition in effect, that too will be displayed. In this example, a DEC Rainbow user determines the scan code for the accent grave key, and then redefines that key to send ESC: MS-DOS KERMIT Page 110 Kermit-MS>show key Press a key: ` Scan Code: 96 Definition: Kermit-MS>set key scan 96 Definition string: \33 Kermit-MS>show key Press a key: ` Scan Code: 96 Definition: \33 Kermit-MS> The SHOW KEY command only works on certain systems. 10.3.7. Command Macros Kermit-MS provides a facility for combining commands into "macros." Command macro definitions may be included in your MSKERMIT.INI file, TAKEn explicitly from a specified file, or typed interactively, and may be invoked with the DO command. THE DEFINE COMMAND Kermit-MS command macros are constructed with the DEFINE command. The syntax is DEFINE macro-name [command [, command [, ...]]] Any Kermit-MS commands may be included. Example: define telenet set parity mark, set baud 1200, connect THE DO COMMAND A Kermit-MS command macro is invoked using the DO command. For in- stance, Kermit-MS comes with a predefined macro to allow convenient setup for IBM communications; to invoke it, you would type do ibm The IBM macro is defined as "parity mark, handshake xon, local-echo on, timer on". You can delete or replace this definition by adding a new (perhaps null) definition, such as define ibm parity even, handshake cr, local-echo on, timer on or define ibm MS-DOS KERMIT Page 111 10.4. Terminal Emulation When you issue the CONNECT command, your PC acts as a terminal connected to a remote computer through the currently selected port. The charac- ters you type are sent out the port, and characters that arrive at the port are displayed on your screen. If you have not previously issued a SET PORT command, COM1 is used. If you have SET LOCAL-ECHO ON for the selected port, then Kermit-MS will display characters on the screen as you type them. If LOCAL-ECHO is OFF, then XON/XOFF flow control will be done unless you have SET FLOW-CONTROL OFF. If you have SET PARITY to anything other than NONE, Kermit-MS will add the appropriate parity to each outbound character, and strip any parity from incoming ones. While CONNECTed, you can also communicate with an autodialer or "smart modem" to control the communications line, hang it up, and the like; for in- stance, typing +++ to a Hayes-like modem will allow you to follow that by dialing or hangup commands. If Heath-19 emulation is being done, incoming characters will be monitored for H19/VT52 escape sequences. These will be interpreted ac- cording to the table in section 10.10. In addition, keys on the numeric keypad will send H19/VT52 sequences unless you disable this feature in some way, for instance by pressing Num Lock on the IBM PC keyboard, or with key redefinitions. Caution: On some systems, such as the IBM PC and XT, Kermit-MS accesses the screen memory memory directly to perform certain H19 emulation functions such as character insert/delete and screen scroll. Without direct screen memory access, these func- tions would be painfully slow. Although Kermit-MS has been tested successfully on a variety of monochrome and color adap- ters and monitors, there may be combinations for which this method could cause video problems, such as snow. Should this occur, you can alleviate the problem by setting HEATH19 emula- tion OFF. In that case, however, you remove not only the problems, but also the desirable features of emulation. But Kermit-MS does permit you to load an external console device driver, such as IBM's ANSI.SYS, to provide any desired screen control. Here are the terminal emulation options for the systems presently sup- ported by Kermit-MS: System EscChar Cabilities Terminal Service IBM PC, XT ^] R M P K Heath19 emulation DEC Rainbow ^] R P K VT102 firmware HP-150 ^] R HP-2623 firmware Wang PC ^A Wang firmware Generic DOS ^] Depends on system Under Capabilities, R means rollback, M means mode line, P means printer control, and K means key redefinition. IBM PC/XT Kermit can disable Heath-19 emulation and use an external con- sole device driver like ANSI.SYS instead. When you first issue the CONNECT command, a message (on some systems, an MS-DOS KERMIT Page 112 inverse video "mode line") will display the most important facts about the connection you've just established, so that you can quickly diagnose any problems. The items displayed in the mode line include the escape character, port number, the baud rate, the parity, the echo, and how to get help, for instance: +---------------------------------------------------------------------+ |EscChar:^],Port:1,Baud:9600,Parity:None,Echo:Remote,Type ^]? for Help| +---------------------------------------------------------------------+ The escape character is used to regain the attention of Kermit-MS. When you type the escape character, Kermit-MS waits for you to follow it with a single character command. For instance, the single-character-command "?" produces a list of available single character commands, such as this: ? Help -- prints the available single-character commands. C Close the connection and return to Kermit-MS prompt level. S Show the status of the connection. B Send a BREAK signal to the port. 0 (the digit zero) Send a NUL (ASCII 0) to the port. Q Temporarily quit logging the remote session. R Resume logging the remote session. M Toggle the mode line, i.e. turn it off if it is on & vice versa. ^] (or whatever you have set the escape character to be) Typing the escape character twice sends one copy of it to the con- nected host. Typing any other character (except the space bar, which is the "null command") after the escape character will cause Kermit-MS to beep, but will do no harm. The escape character can be changed to something other than Control-Rightbracket by using the SET ESCAPE command. Kermit-MS includes several advanced features for use during terminal emulation, including screen scroll, printer control, and key redefini- tions. Screen Scroll Kermit-MS provides several pages of screen memory, which may be scrolled up and down using keys as follows: Function IBM PC/XT Rainbow HP-150 Screen Down PgDn PrevScreen Prev Line Down Ctrl-PgDn Ctrl-PrevScreen Shift-UpArrow Screen Up PgUp NextScreen Next Line Up Ctrl-PgUp Ctrl-NextScreen Shift-DownArrow Top of Memory Home Bottom of Memory End There is presently no way to assign these functions to other keys. MS-DOS KERMIT Page 113 Printer Control A locally attached printer may be controlled in the normal manner, on most systems. Pushing the "Print Screen" key (shifted on some systems) will cause the current contents of the screen to be printed or spooled; holding down CTRL while depressing Print Screen will start or stop the spooling of incoming characters to the printer. ^P or ^N are sent to the host during terminal emulation, and do not toggle printing, as they do when you're talking directly to DOS. CTRL-Print-Screen can be simulated with the Kermit-MS LOG PRN and CLOSE commands. Key Redefinitions Key redefinitions are useful for defining "keystroke macros" of login sequences, frequently issued commands, and so forth, and for setting up the terminal for use with host resident software designed to work with terminals that send predefined sequences from their function keys. For instance, here's a key redefinition file for arranging the DEC Rainbow keyboard into the normal ASCII keyboard layout: ; Make shift-comma send a left angle bracket set key scan 556 < ; Shift-period sends a right angle bracket set key scan 558 > ; Accent grave is where ESC is supposed to be set key scan 96 \33 ; Put accent grave on the ESC function key set key f11 ` The SET KEY facility may be used provide the PC with a "meta" key for use with editors like EMACS or TVEDIT that can use "meta characters" as commands. A meta key is a shift key whose effect is to turn on the 8th (parity) bit of the character. For instance, on the IBM PC the scan codes produced by holding down ALT together with other keys can be determined using SHOW KEY, and then 8-bit ASCII equivalents with the 8th bit turned on can be defined using SET KEY; if the scan code produced by typing ALT-a, i.e. the letter "a" (ASCII 141, octal) with the ALT key held down, is 2078 (decimal), you would set the META equivalent to 141+200=341 (octal), or "\341" in octal SET KEY notation: Kermit-MS>sho key Press a key: ALT-a Scan Code: 2078 Definition: Kermit-MS>set key scan 2078 Definition String: \341 Whenever you type ALT-a with this definition in effect, Kermit-MS will transmit octal 341, rather than 141. MS-DOS KERMIT Page 114 10.5. Installation of Kermit-MS by Bill Catchings, Columbia University If you already have Kermit on your PC, you can use it to obtain new ver- sions of Kermit-MS when they appear on the central system at your site. If you do not have Kermit or any other reliable file capture facility on your PC, and there is no one from whom you can borrow a floppy disk to copy Kermit, then you should read the following instructions for in- itially "bootstrapping" Kermit-MS from a mainframe where it is stored onto your microcomputer. There are at least three methods of initially getting Kermit-MS onto your PC: 1. Try again to find a copy on diskette. 2. Use another file capture facility to get it. 3. Type in and run a bootstrapping program. 10.5.1. Try Again To Find A Kermit Disk Before explaining how to bootstrap Kermit onto your PC, a disclaimer must be made. Although a fair amount of thought and time has gone into these procedures, they are far from error free. If they were foolproof, there would be no need for a protocol such as Kermit. There are many places where things can go wrong, from something as simple as a typing mistake to something as unavoidable and probably inevitable as a com- munications line failure. By far the easiest and best way to install Kermit is from a floppy disk. Before you embark on any of the following procedures it is a good idea to check once again for a diskette to copy, even it it contains an old version of Kermit. The time you spend searching is likely to be far less frustrating than the time you spend trying to bootstrap Kermit by the methods described below. 10.5.2. Bootstrapping From the Communication Line If you can't find a diskette with Kermit on it, there are two other methods available for bootstrapping MS-DOS Kermit onto your PC. The first method is to use a file capture method or other file transfer protocol to transfer the file to your PC. Some systems come supplied with facilities like this, and various public domain or commercial packages are available. The second method requires you to type in your own downloading program. In either case, you must transmit the file from the system where it resides over a communication line and into your PC. Since version 2 of MS-DOS Kermit is much larger than version 1, it comes with a new bootstrapping procedure in which the executable program is encoded much more compactly than in the earlier "fix" files. The new encoding packs 3 .EXE file bytes into 4 printable characters in the MSxxx.BOO file, and also compresses adjacent zero bytes (of which there are many). The .BOO file contains only printable characters, to ensure that downloading can MS-DOS KERMIT Page 115 take place regardless of parity or other peculariaries of the communica- tion channel. 10.5.2.1. Use An Existing File Capture Facility In the rest of this discussion of bootstrapping, the host-resident boot .BOO file will be referred to as MSKERMIT.BOO. In fact, the actual name will depend on which MS-DOS system you are using -- MSIBMPC.BOO for the IBM PC or XT, MSRB100.BOO for the Rainbow 100, etc. Use your file capture facility, whatever it may be, to get the file MSKERMIT.BOO onto your PC's disk, but first make sure you have enough room for it. Once the file is on your disk, you must run the BASIC program MSPCTRAN.BAS to decode the file back into KERMIT.EXE. This program can be downloaded by the same method you used with MSKERMIT.BOO. The program looks on your current disk and directory for the file MSKERMIT.BOO and outputs KERMIT.EXE to the same place. KERMIT.EXE is about 80K bytes, so make sure there is space for it on your disk or else you will have to start the program over. Since the program will take about twenty minutes to completely translate the file you will want to avoid running it more than once. 10.5.2.2. Type In Your Own Bootstrap If you can't find some method for downloading the .BOO file and the BASIC program, the second way of bootstrapping Kermit is to use the programs MSPCBOOT.BAS and MSBOOT.FOR to download via your PC's asynchronous port from your host and translate it directly, "on the fly." You run the program MSBOOT.FOR on your host and then run the program MSPCBOOT.BAS in BASIC on your PC. The FORTRAN program sends the encoded .EXE file to the BASIC program, which decodes it and stores it in executable form on your current directory as KERMIT.EXE. A very rudimentary form of error checking is done to allow obviously corrupted records to be retransmitted. Follow this procedure: 1. First, you must establish a connection from your PC to the host system. A high speed connection is preferable; a "clean" line is preferable to a noisy one. In fact, a clean line is essential for this procedure. You must be able to log in to the host system over this connection. If your PC already has a terminal emulation facility, use that. If not, you might need to put your PC next to a real terminal and use that for logging in, then switch the connector to the PC at the crucial moment. If you are using a terminal, make sure the terminal and PC have their communication ports set to the same speed. 2. Ensure that the files MSBOOT.FOR and MSKERMIT.BOO are present on the host system. MSBOOT.FOR is listed below, in case you need to type it in. 3. Get back to your PC and type in MSPCBOOT.BAS on your PC; a listing appears below. There is no need to type in the com- ments (anything following an apostrophe); they are only there MS-DOS KERMIT Page 116 to clarify what the program is doing. Check very carefully for errors. You should check line 80 in the program to see that it reflects the way your system is actually set up. If necessary, substitute the correct baud rate for the supplied rate of 9600, and if you are not using COM1: make that change as well. If you are downloading from an IBM or other half- duplex mainframe, leave line 1000 as it is; otherwise, replace it by a RETURN statement. If you type it in directly to BASIC make sure you save the program before you run it, so you won't have to type it in again in case of error. 4. Get back to your host system and compile MSBOOT.FOR, if it needs compiling. Define logical unit numbers 5 and 6 to be the controlling terminal, and logical unit 7 to be the file MSKERMIT.BOO. On VAX/VMS systems, for example, use these commands: $assign sys$input for005 $assign sys$output for006 $assign mskermit.boo for007 On a DECSYSTEM-20, do: @define 5: tty: @define 6: tty: @define 7: mskermit.boo On a DECsystem-10, do something like this: .assign tty: 5: .assign tty: 6: .assign dsk: 7: .rename for007.dat=mskerm.boo On an IBM system under VM/CMS, do this: .filedef 5 term ( lrecl 80 recfm v .filedef 6 term ( lrecl 80 recfm v .filedef 7 disk mskermit boo ( lrecl 77 recfm f perm 5. Set your host system up for downloading: - Ensure that your terminal does not automatically pause at the end of a screenful of output. For instance, on a DEC-20 you would issue the command "terminal no pause end-of-page". - Do whatever you can to disable messages from appearing at your terminal while these programs are running. This would include messages from other users, mail notifica- tion, alarms or alerts, system messages, and so forth. Such messages will interfere with the procedure, and probably render the result useless. - You should put your host terminal in "local echo" or "half duplex" mode, if possible. MS-DOS KERMIT Page 117 6. Start the MSBOOT program on your host system. 7. Get back to the PC. If you have been using a terminal, switch the connector to the PC. 8. Now run the BASIC program, MSPCBOOT.BAS. This procedure will take at least twenty minutes and possibly longer depending on line speed. Watch your modem and/or disk lights for reas- surance that something is happening. By using one of these installation methods, you should now have a work- ing version of Kermit. If you experience any problems or quirky be- havior with the program, it's possible that some part of it was cor- rupted during the downloading procedure. Perhaps enough usable code remains to allow you to transfer MSKERMIT.EXE from the host. If not, you will have to repeat the downloading procedure. Once you have Kermit-MS on your disk, you should make the disk available to other users for copying, so that they can be spared the tedium of this bootstrap procedure. Here is a listing of MSPCBOOT.BAS. The "outdented" PRINT statements with line numbers ending in 5 may be included if you want incoming records to be displayed on the screen. You don't need to include the comments. 1 'Run this program on the PC in conjunction with a Fortran program 2 '(MSBOOT.FOR) on the mainframe to download Kermit to the PC. This 3 'program will run for about thirty minutes, depending on line speed. 4 ' Bill Catchings, June 1984 5 ' Columbia University Center for Computing Activities 10 t$ = time$ ' Save the time. 20 defint a-z ' All integer to gain some speed. 30 n$ = chr$(0) 40 z = asc("0") 50 t = asc("~")-z 60 def fnuchr%(a$)=asc(a$)-z 70 open "com1:9600,s,7,1,cs,ds,cd" as #1 100 print#1,"O ," ' Char constants "O", " " and "," 110 input#1,f$ 120 if len(f$) < 5 then goto 110 ' In case the host echos the ACK. 130 input#1,n 135 print f$+" "+str$(n) 140 if n > 20 then goto 900 150 open f$ for output as #2 160 print "Outputting to "+f$ 170 goto 300 ' Correct version of the file. 200 gosub 1000 ' Do turnaround char processing 210 print#1,"NO" ' Tell host data was incorrect. 220 goto 320 MS-DOS KERMIT Page 118 300 gosub 1000 ' Do turnaround char processing 310 print#1,"OK" ' Say the line was all right. 320 input#1,x$ 330 if len(x$) < 5 then goto 320 ' In case the host echos ACK/NAK 340 input#1,n 345 print x$+" "+str$(n) 350 if len(x$) <> n then goto 200 ' Length doesn't match, NAK it. 360 if x$ = "&&&&&&&&&&" then goto 800 ' End of file? 370 y$ = "" ' Set output string to null. 380 goto 500 400 print#2,y$; ' Print the output string. 410 goto 300 ' Go get another line. 500 if len(x$) = 0 goto 400 ' Done with input string? 510 a = fnuchr%(x$) 520 if a = t then goto 700 ' Null repeat character? 530 q$=mid$(x$,2,3) ' Get the quadruplet to decode. 540 x$=mid$(x$,5) 550 b = fnuchr%(q$) 560 q$ = mid$(q$,2) 570 c = fnuchr%(q$) 580 q$ = mid$(q$,2) 590 d = fnuchr%(q$) 600 y$ = y$ + chr$(((a * 4) + (b \ 16)) and 255) ' Decode the quad. 610 y$ = y$ + chr$(((b * 16) + (c \ 4)) and 255) 620 y$ = y$ + chr$(((c * 64) + d) and 255) 630 goto 500 ' Get another quad. 700 x$ = mid$(x$,2) ' Expand nulls. 710 r = fnuchr%(x$) ' Get the number of nulls. 715 print " Null: ",r 720 x$ = mid$(x$,2) 730 for i=1 to r ' Loop, adding nulls to string. 740 y$ = y$ + n$ 750 next 760 print#2,y$; ' Print the nulls. 770 y$ = "" ' Clear the output buffer. 780 goto 500 800 print "Processing complete, elapsed time: "+t$+" to "+time$ 810 print "Output in "+f$ 820 close #1,#2 830 goto 9999 900 print "?The format of the BOO file is incorrect" 910 goto 820 1000 x$ = input$(1,#1) ' Make this line RETURN for full-duplex 1010 if x$ <> chr$(17) then goto 1000 ' Loop for a turn around char. 1020 return 9999 end MS-DOS KERMIT Page 119 Here is a listing of MSBOOT.FOR, in case you can't find it on your host system: C This Fortran program should be run on the mainframe in conjunction C with a Basic program (MSPCBOOT.BAS) on the PC to transfer C MSKERMIT.BOO to the PC and translate it into KERMIT.EXE. This C program uses a very rudimentary technique to try to insure that C the characters it sends arrive correctly. It just sends a count C of the number of characters sent after each line. In this way any C errors of character loss or insertion will be caught. If a C character is just corrupted it will not be caught. Hopefully if C this happens it will be in a non-critical part of the KERMIT.EXE C file. The reason a simple checksum was not used was so that this C program could run on machines using either EBCIDIC or ASCII C characters. This program should take about thirty minutes to run. C This program assumes that 5 and 6 are directed to the terminal and C 7 is directed to the file MSKERMIT.BOO. INTEGER LINE(77), ACK(4), CHECK, OK, SPACE, COMMA WRITE(6,100) 100 FORMAT(' Ready to transfer data, now run MSPCBOOT.BAS on the PC.') C Get characters for constants (character constants are rough in C some FORTRANs!) READ (5,200) OK, SPACE, COMMA, ACK 200 FORMAT(4A1) GO TO 30 C Get terminal handshake. 10 READ (5,200)ACK C Did the other side like it? (Did they send OK?) IF (ACK(1) .NE. OK) GO TO 50 C Yes, get new line from file. 20 READ (7,300,END=99)LINE 300 FORMAT(77A1) C Count the characters as some rudimentary check for noise. I = 1 30 IF (LINE(I) .EQ. SPACE) GO TO 40 I = I + 1 GO TO 30 C Put in a comma followed by the count. 40 LINE(I) = COMMA C Write to TTY. 50 WRITE (6,400)LINE,I-1 400 FORMAT(' ',77A1,I2) GOTO 10 MS-DOS KERMIT Page 120 C Send good-bye message. 99 WRITE (6,500) 500 FORMAT(' ',10('&'),',10') STOP END 10.6. Compatibility with Older Versions of MS-DOS Kermit MS-DOS Kermit supports many different systems. Like CP/M-80 KERMIT, this support was added to the program piecemeal, at many sites, using conditional assembly. However, before allowing the program to grow into a complicated monolith like CP/M-80 KERMIT, we have broken the program up into separate modules, with system dependencies isolated into a single module consisting of compact collections of low-level primitives for console and port i/o. The last monolithic (single source file) release of MS-DOS Kermit was 1.20. To this and earlier versions was added support for systems like the Seequa Chameleon, the Tandy 2000, the Victor 9000, the Heath/Zenith 100, and others. Eventually, support for these systems may be in- tegrated with the new modular version. Meanwhile, implementations based on these old versions will have at least the following incompatibilies from the version described here: - RECEIVE filespec is used instead of GET filespec. There is no GET command in older versions, and no way to specify a new name for an incoming file. - No LOCAL or REMOTE commands. - No 8th-bit prefixing, repeat counts, CRCs or 2-character checksums. - No TAKE or initialization files. - No command macros or command line arguments. - No terminal session logging. and others, depending on the specific version. 10.7. What's Missing Kermit-MS has plenty of room for improvement. Features that need to be improved or added include: - A built-in facility for sending files "raw" to the remote sys- tem, obeying current settings for parity, flow control, hand- shake, and so forth. This might include a script interpreta- tion facility to allow remote sessions to be conducted automatically. For the present, this can be accomplished with a user-supplied program invoked with the Kermit-MS RUN com- mand. - Additional functionality when running in server mode -- directory listings, file deletion, execution of DOS com- mands, etc. MS-DOS KERMIT Page 121 - More commands when talking to remote servers -- REMOTE RENAME, COPY, STATUS, WHO, etc. - Filename conversion options (normal form, handling of fully qualified filespecs, etc.). - Transaction file logging. - Improved command parsing; for instance, accept default values for omitted trailing fields. - A better built-in help facility. - Support for Kermit file attribute packets. - The Kermit-MS program is quite large. Much of the size is due to the deliberate decision to provide support for versions of MS-DOS prior to 2.0. At some point, this support should be removed. This will not only reduce the size of the program considerably, but also provide much more flexibility. 10.8. Program Organization Kermit-MS version 2 is composed of separate assembler source files, as- sembled separately, and linked together. The modules are: System/Device Independent: MSKERM.ASM Main program MSSEND.ASM File sender MSRECV.ASM File receiver MSSERV.ASM Server operation MSFILE.ASM File i/o MSCMD.ASM Command parser MSTERM.ASM CONNECT command MSCOMM.ASM Communications port buffering & flow control MSSET.ASM SET, SHOW, and STATUS commands MSDEFS.H Data structure definitions and equates System/Device Dependent: MSXxxx.ASM System-dependent code for system xxx MSYxxx.ASM System-dependent screen and keyboard code MSZxxx.ASM Modem control (modem-dependent) The modular organization allows easier modification of the program, quicker transfer of modified portions from system-to-system. The modules are designed to be well-defined and self-contained, such that they can be easily replaced. For instance, someone who prefers windows and mice to typing commands could replace the command parsing module without having to worry about the effect on the other modules. To assemble any of the kermit modules, file MSDEFS.H must be on the default disk. MS-DOS KERMIT Page 122 All the Kermit implementations require the modules MSCMD, MSCOMM, MSFILE, MSKERM, MSRECV, MSSEND, MSSERV, MSSET, MSTERM. The IBM PC version requires MSXIBM and MSYIBM as well. The Rainbow version requires MSXRB and MSXDMB; MSXDMB must be the first object file given to the linker for Kermit to link properly for the Rainbow. The HP150 version requires MSXHP150, the Wang version requires MSXWNG, and the generic version requires MSXGEN. Once all the required object modules exist, they may be linked together to produce Kermit. For example, on the Rainbow: A>link Microsoft Object Linker V2.00 (C) Copyright 1982 by Microsoft Inc. Object Modules [.OBJ]: msxdmb mskerm msxrb mscomm msset mssend + msrecv msserv msfile msterm mscmd Run File [MSXDMB.EXE]: kermit List File [NUL.MAP]: kermit A> 10.9. Adding Support For New Systems You can bring Kermit-MS to systems that are not explicitly supported in one of two ways -- attempt to run the "generic" MS-DOS Kermit on it, or add explicit code to support your system. 10.9.1. Generic MS-DOS Kermit To get started with Kermit on a new system, try running "generic" MS-DOS Kermit; in many cases, it will run as is. The generic version ac- complishes all its port and console i/o through DOS calls, and during terminal connection does not attempt to emulate any particular kind of terminal. In some cases, the generic version may still require some fiddling to run on a new system; for instance, different systems refer to their communication ports in different ways -- COM1, AUX, etc. It attempts to do this automatically by trying various DOS file handles for the communication port, and asking you to supply one if it does not succeed. Generic MS-DOS Kermit will probably run no faster than 1200 baud, and it only works with DOS 2.0 or later. MS-DOS KERMIT Page 123 10.9.2. Adding System-Dependent Code The following is a guide to the system dependent module of Kermit-MS. SPECIFICATION FOR KERMIT SYSTEM-DEPENDENT MODULES by Jeff Damens, Columbia University All the system-independent global data structures used in Kermit-MS are defined in the file MSDEFS.H. The routine MSXxxx.ASM contains system-dependent support for system xxx, except for terminal emulation, which is in MSXxxx.ASM, described below. The routines in the MSX module may change any registers but the stack pointer and segment registers, unless otherwise noted. A routine that returns via a RET instruction is said to return normally; a routine that skip returns is one that returns to three bytes past the normal return address. Global variables that must be defined in the system-dependent module: XOFSNT byte. This should be set to a non-zero value if we are doing flow control and have sent an XOFF character to the remote host, zero otherwise. MACHNAM byte. A $-terminated string identifying the machine this version of Kermit is for; it is printed when Kermit starts up. SETKTAB byte. A keyword table associating terminal key names to 16-bit scan code values, used in the set key command. If the kermit version can accept arbitrary decimal values as scan codes, the word "SCAN" should appear in the table with a scan value of -1. If key redefinition is not implemented, the first byte of the table should be a zero. SETKHLP byte. A $-terminated string to be printed when ? is typed in the SET KEY command. This is usually simply a list of the key names in SETKTAB. SETKHLP must be defined even if key redefinition is not implemented, to satisfy the linker; if key redefinition is not imple- mented, SETKHLP will never be displayed. COUNT word. The number of characters in the serial input buffer, if known. This is how Kermit knows to send an XON if the serial handler has sent an XOFF. If the num- ber of characters in the buffer isn't known, COUNT should be 0. These are the required entry points for the system dependent dependent module MSXxxx.ASM. MS-DOS KERMIT Page 124 SERINI Parameters None. Returns Normally, no return value. Description Perform any initialization that must be done before the serial port can be used, including setting baud rate, interrupt vectors, etc. Parity and baud rate should be set according to the values in the PORTINFO structure. The external variable PORTVAL points to the PORTINFO structure for the current port. Calling SERINI more than once without an intervening call to SERRST should have no effect. SERRST Parameters None. Returns Normally, no return value. Description Undoes any initialization done by SERINI, including resetting the serial port, restoring any interrupt vec- tors changed by SERINI, etc. Calling this more than once without an intervening call to SERINI should be harmless. CLRBUF Parameters None. Returns Normally, no return value. Description Remove and discard from the serial port's input buffer any characters sent by the remote host that have not yet been read by Kermit, and set COUNT to 0. This is used before a file transfer to flush NAK's that accumulate in the buffer when the remote host is in server mode. MS-DOS KERMIT Page 125 OUTCHR Parameters A character in AH. Returns Skip returns if the character has been transmitted; returns normally if the character can not be transmitted because of a hardware error. Description Sends the character in AH out the currently selected serial port. OUTCHR can assume that SERINI will have been called previously. OUTCHR should call the external routine DOPAR to set the parity of the character if the communications hardware doesn't automatically set parity. Flow control should be honored; the external variable PORTVAL contains a pointer to a PORTINFO struc- ture (as defined in MSDEFS.H) containing the current flow control definitions. COMS Parameters None. Returns Normally if a parse error is encountered, skip returns otherwise. Description Called by the SET PORT command. On a machine with mul- tiple serial ports, COMS should parse for the name or number of a serial port and make that the port used by succeeding calls to SERINI, PRTCHR, OUTCHR, and SERRST. It should set the external variable PORTVAL to point to one of the external port structures PORT1 or PORT2, and set COMFLG in the FLAGS structure to 1 for port one, 0 for port 2. For implementations that use only one serial port, COMS should print a message to that effect and skip return. VTS Parameters None. Returns Normally if a parse error is encountered, skip returns otherwise. Description Parses for an ON or OFF, sets HEATH-19 emulation while in terminal emulation appropriately. The VTFLG field of the FLAGS structure should be set non-zero if HEATH-29 emulation is on, zero otherwise. If HEATH-19 emulation is not done, VTS should print a message and skip return. MS-DOS KERMIT Page 126 DODEL Parameters None. Returns Normally, no return value. Description Erases the character immediately to the left of the cur- sor from the screen, then backs up the cursor. CTLU Parameters None. Returns Normally, no return value. Description Move the cursor to the left margin, then clear the line. CMBLNK Parameters None. Returns Normally, no return value. Description Clears the screen and homes the cursor. LOCATE Parameters None. Returns Normally, no return value. Description Homes the cursor. LCLINI Parameters None. Returns Normally, no return value. Description Performs any system-dependent initialization required by this implementation. MS-DOS KERMIT Page 127 PRTCHR Parameters None. Returns Normally, with the next character from the currently selected serial port in AL. Skip returns if no charac- ter is available. Description Reads the next character from the current serial port. PRTCHR can assume SERINI has been called previously, and should handle flow control correctly. DOBAUD Parameters None. Returns Normally, no return value. Description Sets the baud rate for the current port. The baud rate should be obtained from the BAUD field of the PORTINFO structure, pointed to by the external variable PORTVAL. CLEARL Parameters None. Returns Normally, no return value. Description Clears from the cursor to the end of the current line. DODISK Parameters None. Returns Normally, no return value. Description Sets the external variable DRIVES to the number of disk drives attached to the machine. GETBAUD Parameters None. Returns Normally, no return value. Description Store current baud rate of the currently selected port in the BAUD field of the current PORTINFO structure, which is pointed to by PORTVAL. If the baud rate is to default to a particular value, this routine can store that value into the BAUD field instead. MS-DOS KERMIT Page 128 BEEP Parameters None. Returns Normally, no return value. Description Rings the terminal bell. PUTHLP Parameters A pointer to a string in AX. Returns Normally, no return value. Description Writes the null-terminated string given in AX to the terminal. This is used to display help and status mes- sages. The IBM and Rainbow versions write the string in a reverse video box. PUTMOD Parameters A pointer to a string in AX. Returns Normally, no return value. Description Writes the null-terminated string given in AX to the last line of the screen, in inverse video if possible. CLRMOD Parameters None. Returns Normally, no return value. Description Clears the line written by PUTMOD. POSCUR Parameters Row in DH, column in DL. Returns Normally, no return value. Description Positions the cursor to the row and column given in DX. Rows and columns both originate at 0 (not 1!). MS-DOS KERMIT Page 129 SENDBR Parameters None. Returns Normally, no return value. Description Send a break to the current serial port. SHOWKEY Parameters Pointer to a terminal argument block in AX (see TERM below). Returns Normally, with a string pointer in AX and the length of the string in CX. Description Called by the SHOW KEY command. Reads a key from the terminal and returns a string containing implementation-dependent information about the key. In the usual case, the string contains the key's (machine-dependent) scan code, and the key's definition (if any) from the terminal argument block. The length of the returned string should be returned in CX. The string may contain any characters; unprintable charac- ters will be quoted when the string is printed. If the implementation does not support key redefinition, SHOW- KEY may return a static string saying so. TERM Parameters Pointer to terminal argument block in AX. Returns Normally, no return value. Description Do terminal emulation, based on argument block described below... The terminal emulator is supplied in the file MSYxxx.ASM. The terminal argument block passed to the terminal emulator has the following fields: FLGS Byte containing flags. Flags are: SCRSAM (80H) If on, the terminal emulator shouldn't re-display the screen when entered. CAPT (40H) Capture output. If on, the routine passed in field CAPTR is called with each character sent to the screen. EMHEATH (20H) Emulate a Heath-19 terminal if on. MS-DOS KERMIT Page 130 HAVTT (10H) A key redefinition table is present. TRNCTL (08H) Print control character X as ^X (useful for debugging). MODOFF (04H) Do not display emulator mode line if on. LCLECHO (01H) Echo keyboard characters on the screen in addition to sending them to the port. PRT Port to use for terminal emulation, used only in mode line. This is just a copy of COMFLG in FLAGS. COLS Number of columns on screen. ROWS Number of rows on screen. CAPTR Routine to call to with each character sent to the screen if CAPT flag is on. Characters are passed in AL. BELLD Bell divisor (used only on IBM). KLEN Number of keys in key redefinition table, if HAVTT flag is on. KTAB Address of key redefinition table. The key redefinition table is a table of KLEN 16-bit scan codes. Each (machine dependent) scan code represents a key that is redefined. KRPL Address of key replacement table. The key replacement table parallels the key redefinition table given in KTAB. Entries in the replacement table are 16-bit pointers to redefinitions. Each redefinition has a one-byte length, followed by the definition. ESCC Escape character (single byte). When this character is typed to the emulator, it should return. BAUDB byte. Bits describing the baud rate so it can be printed on the mode line. This is a copy of the BAUD field in the PORTINFO structure. Currently used only on the IBM. See MSDEFS.H for possible values. PARITY byte. Current parity to print on the mode line. This is a copy of PARFLG in the PORTINFO structure. Cur- rently used only on the IBM. See MSDEFS.H for possible values. MS-DOS KERMIT Page 131 10.10. Heath/Zenith-19 Control Codes The Heath/Zenith-19 terminal is equivalent to the DEC VT52 with exten- sions for line and character insertion and deletion. Items marked with an asterisk are not currently supported by Kermit-MS H19 emulation. Cursor Functions Sequence Mnemonic Definition ESC H HCUH Cursor Home ESC C HCUF Cursor Forward ESC D HCUB Cursor Backward ESC B HCUD Cursor Down ESC A HCUU Cursor Up ESC I HRI Reverse Index *ESC n HCPR Cursor Position Report *ESC j HSCP Save Cursor Position *ESC k HRCP Set Cursor to Previously Saved Position ESC Y HDCA Direct Cursor Addressing, 1-based: 31+line# 31+col# (same as VT52) Erasing and Editing Sequence Mnemonic Definition ESC E HCD Clear Display (Shift Erase) ESC b HBD Erase Beginning of Display ESC J HEOP Erase to End of Page (Erase Key) ESC l HEL Erase Entire Line ESC o HEBL Erase Beginning of Line ESC K HEOL Erase to End of Line ESC L HIL Insert Line ESC M HDL Delete Line ESC N HDCH Delete Character ESC @ HEIM Enter Insert Character Mode ESC O HERM Exit Insert Character Mode Configuration Sequence Mnemonic Definition *ESC z HRAM Reset to Power-Up Configuration *ESC r Bn HMBR Modify Baud Rate: Bn= A=110, B=150, C=300, D=600, E=1200, F=1800, G=2000, H=2400, I=3600, J=4800, K=7200, L=9600, M=19200 *ESC x Ps HSM Set Mode(s): Ps= 1 = Enable 25th line 2 = No key click 3 = Hold screen mode 4 = Block cursor 5 = Cursor off MS-DOS KERMIT Page 132 6 = Keypad shifted 7 = Alternate keypad mode 8 = Auto line feed on CR 9 = Auto CR on line feed *ESC y Ps HRM Reset mode(s): Ps= 1 = Disable 25th line 2 = Enable key click 3 = Exit hold screen mode 4 = Underscore cursor 5 = Cursor on 6 = Keypad unshifted 7 = Exit alternate keypad mode 8 = No auto line feed 9 = No auto CR *ESC < HEAM Enter ANSI Mode Modes of Operation Sequence Mnemonic Definition *ESC [ HEHS Enter Hold Screen Mode *ESC \ HXHS Exit Hold Screen Mode ESC p HERV Enter Reverse Video Mode ESC q HXRV Exit Reverse Video Mode *ESC F HEGM Enter Graphics Mode *ESC G HXGM Exit Graphics Mode *ESC t HEKS Enter Keypad Shifted Mode *ESC u HXKS Exit Keypad Shifted Mode *ESC = HAKM Enter Alternare Keypad Mode *ESC > HXAM Exit Alternate Keypad Mode Additional Operations Sequence Mnemonic Definition *ESC } HDK Keyboard Disable *ESC { HEK Keyboard Enable ESC v HEWA Wrap Around at End of Line ESC w HXWA Discard at End of Line ESC Z HID Identify as VT52 (ESC / K) *ESC ] HX25 Transmit 25th Line *ESC # HXMP Transmit Page The Heath-19 transmits the following sequences, but it will not respond to them if they are received. Kermit-MS will transmit them only if they are programmed with SET KEY. ESC S HF1 Function Key #1 ESC T HF2 Function Key #2 ESC U HF3 Function Key #3 ESC V HF4 Function Key #4 ESC W HF5 Function Key #5 MS-DOS KERMIT Page 133 ESC P HF7 Function Key #7 ESC Q HF8 Function Key #8 ESC R HF9 Function Key #9 CP/M-80 KERMIT Page 134 11. CP/M-80 KERMIT Program: Bill Catchings, Columbia University, with contributions from 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: 3.9A Date: 6 June 1984 Documentation: Frank da Cruz, Columbia University KERMIT-80 Capabilities At A Glance: Local operation: Yes Remote operation: No Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Y 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 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. CP/M-80 KERMIT Page 135 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. 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. CP/M-80 KERMIT Page 136 KERMIT-80 DESCRIPTION Implementations of Kermit-80 presently exist for the DEC VT180 (Robin), the DECmate II, the Intertec Superbrain, the Heath/Zenith 89 and Z100, the Apple II with the Z80 SoftCard, the Osborne 1, the TRS-80 II with CP/M, the Telcon Zorba, the Kaypro, the Vector Graphics CP/M system, the Morrow Decision I, the Nokia MikroMikko, and others. There is also a "generic" CP/M version that should run on most 8080-compatible CP/M 2.2 systems, but which may provide less performance, and another for CP/M 3.0. 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 Z80 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 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 Returns If you type carriage return repeatedly Kermit-80 will retry the current packet up to its retry limit (somewhere between 5 and 16 times) and then, if no valid response was received, return to Kermit-80 command CP/M-80 KERMIT Page 137 level. 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 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 issue the appropriate SET CP/M-80 KERMIT Page 138 BLOCK command to the remote KERMIT before 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 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. 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. LOCAL-ECHO ON (or OFF) When you CONNECT to a remote host, you must set LOCAL- CP/M-80 KERMIT Page 139 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 character, which you enter literally. BAUD Change the baud rate of the communications port. This command only works on some systems, and its actual operation can vary from system to system. Type SET BAUD followed by a question mark, and follow the directions. 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 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. CP/M-80 KERMIT Page 140 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 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). 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 destination of file transfers. In addition, issuing this command causes you to switch to the specified disk and log it in, write-enabled. 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. PRINTER ON or OFF. Turns copying of CONNECT session to printer on and off. No attempt is made to do buffering or flow control; it is assumed printer can keep up. DIR 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. ERA This executes the CP/M ERA command on the specified file(s). The names of the files being erased are not displayed. CP/M-80 KERMIT Page 141 11.1. Generic KERMIT-80 "Generic Kermit-80" is a implementation of Kermit that should run on any 8080-compatible CP/M system 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 or screen. 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 implement IOBYTE do so in the same way. 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. Generic Kermit also differs from other Kermit-80 implementations in that it does not 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 ter- minal 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. Neither does generic Kermit-80 do termimal emula- tion; thus a generic Kermit-80 acts either 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. Note that VT180 and DECmate-II Kermit are simply adaptations of Generic Kermit that do VT100 (ANSI) screen control during file transfer. 11.2. Installation Kermit-80 was written originally for the Intertec SuperBrain in lowest- common-denominator 8080 code with the standard assembler, ASM (no mac- ros, no advanced instructions), so that it can be assembled on any 16 CP/M-80 system . It has since been modified to run on many other sys- tems as well. Kermit-80 should be able to run on any 8080-, 8085- or Z80-based microcomputer under CP/M with only minor modifications (see below). All versions of Kermit-80 are assembled from the same source, with sys- tem dependencies taken care of by assembly-time conditionals. The most important system dependencies are terminal emulation (when CONNECTed to _______________ 16 The 8080 assembler is distributed as a standard part of CP/M-80, whereas the fancier Z80 or macro assemblers are normally a commercial product CP/M-80 KERMIT Page 142 the remote host) and screen handling, which are dependent on the in- dividual 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. Also, using BDOS calls, there's no way to poll the serial port; you must hang until input appears. 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 version 3.8 and above includes 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. 11.2.1. Downloading Kermit-80 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 one. If it's stored in the form of a .COM file, you can run it directly. If it's stored as a .HEX file, you must first LOAD it on your micro to produce a .COM file. 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 precompiled "hex" file into your micro's memory and then save it on the disk. The following is a proce- dure 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 letters A-F, the colon ``:'', carriage return, and line feed). As soon as any other 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. Look for the appropriate hex file in the host's KERMIT area. The name will be something like CPMROBIN.HEX, CPMHEATH.HEX, CP/M-80 KERMIT Page 143 CPMOSBORN.HEX, etc. If you don't find it, but you do find a corresponding .ASM or .M80 file, you'll either have to build a new hex file on the host using a cross assembler (see below for how to do this on a DEC-10 or DEC-20), or else bring the M80 source file to your micro and assemble it there. 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 hex file at your terminal. E.g. on the DEC-20, give the Exec command TYPE KERMIT.HEX, without a terminating carriage return. 4. Return to your micro. Connect to a floppy disk with plenty of free space. 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). Run DDT and type in the following (the comments should not be typed in; they are there just to tell you what's happening): -ikermit.hex ;Setup FCB for file KERMIT.HEX. -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 CP/M-80 KERMIT Page 144 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. 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 -g100,179 ;Execute the program. - ;Reboot Now there should be a file KERMIT.HEX on your connected disk. 5. Load this using the CP/M command LOAD to produce KERMIT.COM. This should be a runnable version of Kermit. Note that CP/M hex files have checksums on each line. If there were any transmission errors during the downloading process, the CP/M loader 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 previous step. You now should have a running version of Kermit-80. 11.2.2. Building KERMIT.HEX The source for Kermit-80 should be available on your host computer. It is written using 8080 assembler mnemonics, so it can be assembled on most 8080s and Z80s using the standard 8080 assembler provided with CP/M. If you have KERMIT.ASM on your CP/M system, you can assemble it directly on the micro using ASM, setting the desired assembly switches as explained below. If you don't have it, you can attempt to download the source file from the host using the procedure outlined above. A cross assembler is provided that runs on the DEC-10 and DEC-20, called MAC80, contributed by Bruce Tanner at Cerritos College, that may be used for cross assembling KERMIT-80 as shown in this example (for TOPS-20): 1. Copy PS:CPMKxx.M80 to your directory, as KERMIT.M80. TOPS-10 filename rules must be followed. This is the 8080 assembler source file; xx is the current version number; for instance version 3.8 would be stored as CPMK38.M80. 2. Edit KERMIT.M80 to set the conditional assembly switch for CP/M-80 KERMIT Page 145 your machine. These are right near the top of the file. The switch for your machine should be set to TRUE and all the others to FALSE. 3. The "ibm-flag" setting is site dependent. As shipped from Columbia, it turns on half duplex line handshaking, using CTRL-Q as the turnaround character, sets LOCAL-ECHO ON, TIMER ON, and PARITY MARK. Make any changes required for your site. 4. The default FILE-MODE is ASCII as shipped from Columbia. This means that when text files are sent from the CP/M sys- tem, no extraneous characters will be sent after the end, but that outgoing binary files may be truncated erroneously if the user forgets to SET FILE BINARY. You can change the default to BINARY, so that no data is ever lost from any file, but text files will usually have extraneous junk at the end. 5. Run MAC80: @mac80 *kermit=kermit *^Z The result will be in your directory as KERMIT.HEX. 6. Use Kermit, MODEM, or any other downloading mechanism to transfer KERMIT.HEX to the micro, or download it using the DDT program shown above. 7. On the micro, load the hex file: A>load kermit KERMIT.COM will appear on the floppy. 8. The new Kermit should be ready to run. 11.2.3. Generic Kermit-80 If your CP/M 2.2 system implements i/o redirection via the (optional) IOBYTE mechanism, you can probably run Generic Kermit on it, either without modification, or by a very simple change to the program. The standard CP/M IOBYTE is set up as follows: I/O Byte assignments (four 2-bit fields for 4 devices at location 3) : bits 6+7 LIST field 0 LIST is Teletype device (TTY:) 1 LIST is CRT device (CRT:) 2 LIST is Lineprinter (LPT:) 3 LIST is user defined (UL1:) CP/M-80 KERMIT Page 146 bits 4+5 PUNCH field 0 PUNCH is Teletype device (TTY:) 1 PUNCH is high speed punch (PUN:) 2 PUNCH is user defined #1 (UP1:) 3 PUNCH is user defined #2 (UP2:) bits 2+3 READER field 0 READER is Teletype device (TTY:) 1 READER is high speed reader (RDR:) 2 READER is user defined #1 (UR1:) 3 READER is user defined #2 (UR2:) bits 0+1 CONSOLE field 0 CONSOLE is console printer (TTY:) 1 CONSOLE is CRT device (CRT:) 2 CONSOLE in Batch-mode (BAT:);READER=Input,LIST=Output 3 CONSOLE is user defined (UC1:) (Here, bit zero is the least significant, "rightmost", bit). I/O redirection is accomplished by switching the IOBYTE between two values, "batch i/o" and "normal i/o". In normal i/o mode, the keyboard is defined to be the console. In batch i/o mode, the serial port is defined to be the console. This switching is necessary because the con- sole is the only device that can be tested to see if input is available, but KERMIT must shuttle back and forth between the keyboard and the serial port looking for input. Here are the batch and default i/o mode definitions used in "standard" Generic KERMIT-80: batio EQU 056H ;I/O byte CON=BAT,LIST=CRT,READER=RDR defio EQU 095H ;I/O byte CON=CRT,LIST=LPT,READER=RDR Other systems may have other logical devices that point to the serial port, in which case you'll need to redefine these symbols to point to those devices and then reassemble the program (with assembly switch GENER set to TRUE, all others FALSE). If your system runs CP/M 3.0, then the CPMPLUS version of KERMIT should run on your system without modification, except perhaps for screen con- trol or baud rate setting. CP/M-86 KERMIT Page 147 12. CP/M-86 KERMIT Authors: Bill Catchings, Columbia University; Ron Blanford, Univer- sity of Washington; Richard Garland, Columbia University. Language: Digital Research ASM86 Version: 2.7 Date: May 1984 Documentation: Frank da Cruz, Columbia This version of KERMIT is designed to support any CP/M-86 system. So far it supports the DEC Rainbow-100 and the NEC Advanced Personal Com- puter (APC). It is very similar to CP/M-80 and MS DOS KERMIT. CP/M-86 KERMIT-86 Capabilities At A Glance: Local operation: Yes Remote operation: No Transfers text files: Yes Transfers binary files: Yes Wildcard send: Yes ^X/^Y interruption: Yes Filename collision avoidance: Yes Can time out: Yes 8th-bit prefixing: Yes Repeat count prefixing: No Alternate block checks: No Terminal emulation: Yes, uses PC firmware (VT100) Communication settings: Yes; duplex, parity Transmit BREAK: Yes IBM communication: Yes Transaction logging: No Session logging (raw download): Yes Raw upload: No Act as server: No Talk to server: Yes; SEND, GET, FIN, BYE Advanced commands for servers: No Local file management: No Handle file attributes: No Command/init files: Yes Printer control: No CP/M-86 Kermit closely resembles CP/M-80 Kermit, just as CP/M-86 is very similar to CP/M-80. In some respects, KERMIT-86 is superior to KERMIT-80: the program is better modularized to facilitate easy addition of support for new systems, alternate style user interfaces, etc; the port i/o is fully buffered and XON/XOFF is done to allow high-speed com- munication and accurate session logging. On the other hand, the current version does not include the CP/M-80 Kermit's local file management com- mands. CP/M-86 KERMIT Page 148 CP/M-86 KERMIT DESCRIPTION Since Kermit-86 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-86 is capable of timing out an input request, and can thus break deadlocks automatically. In most cases, however, this is not desirable because the KERMIT on the other side is most likely better able to handle the timeouts; therefore, Kermit-86's timer is normally not used. 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 long 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-86 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-86 will go on to the next one. When receiving a file, KERMIT-86 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 either 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 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 Returns If you type carriage return repeatedly Kermit-86 will retry the current packet up to its retry limit (somewhere between 5 and 16 times) and then, if no valid response was received, return to Kermit-86 command level. When KERMIT-86 is started, it looks for the file KERMIT.INI. If found, it executes KERMIT-86 commands from it before prompting you for com- mands. CP/M-86 KERMIT Page 149 12.1. Kermit-86 Commands KERMIT-86 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-86 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, using the system's own built-in support for ANSI (VT100- like) screen control. When you issue the CONNECT command, the PC will print a message telling you how to get back by typing an an escape sequence, an uncommonly-used control character, nor- mally CTRL-backslash, followed by a single letter "command". C Close Connection, return to Kermit-86> command level. ? List available single-character commands. B Send a BREAK signal. Q Quit logging the remote session. R Resume logging the remote session. L Toggle logging. ^\ (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, using the prevailing file mode (ASCII or BINARY; see SET). 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-86 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 BYE When talking to a remote Kermit Server, this command shuts down the server and logs it out, and also exits from Kermit-86 to CP/M command level. LOGOUT Like BYE, but leaves you at Kermit-86 command level. FINISH Like LOGOUT, but shuts down the remote server without logging it out. Leaves you at Kermit-86 command level; a subsequent CON- NECT command should put you back at host system command level. CP/M-86 KERMIT Page 150 EXIT Exit from KERMIT-86 back to CP/M. QUIT Synonym for EXIT. SET parameter [value] Set the specified parameter to the specified value. Possible settings: BAUD Change the baud rate of the communications port. This command only works on some systems, and its actual operation can vary from system to system. Type SET BAUD followed by a question mark, and follow the directions. 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-86. DEBUG ON or OFF. If ON, displays incoming and outbound pack- ets during file transfer. OFF by default. ESCAPE Change the escape character for virtual terminal connec- tions. Select a character in the control range that you will not be likely to need at the remote host; type the new character literally. Certain characters, like Control-X, cannot be specified. FILE-TYPE Tells KERMIT-86 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). 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. ASCII is the default. FLOW-CONTROL Select the desired type of flow control to be used on the communication line. The choices are NONE and XON/XOFF. XON/XOFF is the default. If the remote sys- tem is not full duplex or cannot do XON/XOFF, you should use NONE. IBM ON (or OFF) Allow the transfer of files to and from an IBM mainframe computer. This makes Kermit-86 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-86 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 CP/M-86 KERMIT Page 151 timeout capability, SET IBM ON also turns on the timeout facility automatically, as if you had typed "SET TIMER ON". 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. LOG Specify a log file on the current CP/M disk into which to record incoming characters during CONNECT. If the remote host can do XON/XOFF, then the log file will nor- mally capture every character shown on the screen. When connected to the remote system, several single-character arguments to the connect escape character can be used to control logging -- Q (quit), R (resume), L (toggle). If you use R or L during connect without having previously specified a log file name, then KERMIT.LOG is used. An open log is closed when you escape back to the PC. 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-86 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). PORT Allows you to switch between different communication ports on the PC. This command is not available on all systems. TIMER ON (or OFF) Enable or disable the timeout facility. The timer is off by default, because in the normal case KERMIT-86 is communicating 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 another KERMIT that does not have a timer. You should SET TIMER OFF if you are communicating over a network with long delays. 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. OFF by default. SHOW Show the current settings of the SET parameters. TAKE Take KERMIT-86 commands from the specified file. The file CP/M-86 KERMIT Page 152 should not contain any TAKE commands; nested command files do not work. 12.2. Installation: CP/M-86 KERMIT is broken up into several source modules: 86KERCMD.A86 Command parser 86KERFIL.A86 File handler 86KERIO.xxx System Dependent I/O 86KERMIT.A86 Main Program 86KERPRO.A86 Protocol Module 86KERTRM.A86 Terminal Emulation 86KERUTL.A86 Utilities The main program module, 86KERMIT.A86, contains INCLUDE directives for the other files. The 86KERIO module is stored with suffixes that denote the machine for which the program is being built -- RB for Rainbow, APC for NEC APC. The program may be built on the CP/M-86 system by obtain- ing all the source files listed above, storing them on the current disk with the names indicated, renaming the appropriate 86KERIO.xxx file to be 86KERIO.A86, and then doing: ASM86 86KERMIT $PZ (takes about 6 minutes on the Rainbow) GENCMD 86KERMIT (takes less than a minute) and, if desired, REN KERMIT.CMD=86KERMIT.CMD 12.3. DEC Rainbow 100 Support KERMIT-86 runs on the DEC Rainbow 100 or 100+ under CP/M-86/80, version 1 or 2, on the 8088 side. It uses the built-in firmware to emulate a VT102 ANSI terminal during CONNECT, and runs well at speeds up to 9600 baud. You should be able to download the program using the old KERMIT on the Z80 side (Rainbow Kermit, VT180 Kermit, or generic CP/M-80 Kermit will do the job, but only under DEC CP/M-86/80 version 1.0), or an earlier version of KERMIT-86. If you don't have an earlier version of KERMIT, then follow the direc- tions for installing KERMIT-80 (yes, KERMIT-80) in the KERMIT-80 section of the KERMIT User Guide, but send the KERMIT-86 hex file instead. This works because the Rainbow can run CP/M-80 programs like DDT. Another way to get KERMIT onto your Rainbow for the first time would be from a DEC VT-180 diskette. A VT-180 can use its own KERMIT to load RBKERMIT onto its disk, which can then be read directly by a Rainbow. Also, note that VT-180 KERMIT-80 can actually run on the Rainbow on the Z80 side under DEC CP/M-86/80 version 1 (but not version 2 or higher), at speeds of 1800 baud or lower. CP/M-86 KERMIT Page 153 12.4. NEC Advanced Personal Computer Support (Contributed by Ron Blanford, University of Washington) Currently only the standard serial port is supported, and not the H14 auxiliary port. The SET PORT command is not implemented. While in Kermit's terminal emulation mode, local commands are initiated by a two-character sequence consisting of the "escape character" fol- lowed by one other character identifying the command. (Make the second character a '?' to see a list of the valid commands.) As distributed, the standard Kermit-86 uses the control-backslash character as the es- cape character in terminal mode. The trouble is that the CP/M-86 BIOS in the APC ignores a keyboard entry of Control-\ (i.e. holding down the CTRL key while striking the '\' key), making it difficult (impossible) to use this method to get out of terminal mode. One solution is to perform a "SET ESCAPE ^" command before entering ter- minal mode to change the escape character to a caret (or any other character the APC keyboard will generate). This command could be placed in your KERMIT.INI file for automatic execution every time Kermit is started. The simpler solution is to realize that the character code for a Control-\ is a hexadecimal 1C, and that this is the code generated by the INS key on the numeric keypad. Once you can remember that every reference to Control-\ should be interpreted as a reference to the INS key, this is actually easier to use than the two-key Control-\ sequence. In the standard CP/M-86 BIOS, the unshifted DEL key generates a Control-X character (hexadecimal 18). This is the CP/M command to erase the current input line, and is very useful for local processing. Most mainframes do not use the Control-X character at all, so it becomes much less useful during terminal emulation. The DEL character (hexadecimal 7F), on the other hand, is often used by mainframes and can only be generated on the APC by holding down the SHIFT key while striking the DEL key (this capability is not mentioned anywhere in the documentation). Because the Control-X character is so seldom used while the DEL charac- ter is commonly used, the initialization procedure in Kermit-86 modifies the CP/M-86 BIOS so that the DEL key generates the DEL character whether shifted or not. Control-X can still be generated if necessary by hold- ing down the CTRL key while striking the 'X' key. The CP/M-86 BIOS is returned to its original state when Kermit terminates. The APC uses escape sequences which have been standardized by the American National Standards Institute (ANSI) to control cursor movement, screen erasing, and character attribute manipulation. Perhaps the best- known other terminal which follows ANSI guidelines is the DEC VT100. The APC only recognizes a few of the more important ANSI commands, and not the complete set which the VT100 supports. The ANSI/VT100 features that the NEC APC supports are: - direct cursor addressing (by row and column) CP/M-86 KERMIT Page 154 - relative cursor addressing (up, down, left, right) - line erasing (cursor to end, beginning to cursor, entire line) - screen erasing (cursor to end, beginning to cursor, entire screen) - character attributes (underline, reverse video, blink, but not bold) In addition, the first four grey function keys (unshifted) generate the escape sequences associated with PF1 through PF4 on the VT100 keyboard. The arrow keys and numeric keypad DO NOT generate the corresponding VT100 sequences. These functions are enough to support simple command line editing on most systems, and allow mailers or paged file display programs to clear the screen before each display. Underlining and reverse video are also useful in some applications. This is not enough to support the more sophisticated screen control required by screen editors such as EMACS or KED. In addition, due to a bug in the implementation of the CP/M-86 BIOS, the sequence ordinarily used to home the cursor (esc [ H) does not work correctly; a patch for CP/M to correct this problem is distributed with APC Kermit-86. APPLE-DOS KERMIT Page 155 13. APPLE-DOS KERMIT Authors: Antonino N. J. Mione, Stevens Institute of Technology Peter Trei, Columbia University Documentation: Antonino N.J. Mione, Stevens Institute of Technology Peter Trei, Columbia University Version: 2.1(45) Date: July 1984 Kermit-65 Capabilities At A Glance: Local operation: Yes Remote operation: Yes Transfers text files: Yes Transfers binary files: Yes Wildcard send: No ^X/^Y interruption: No Filename collision avoidance: Yes Can time out: No 8th-bit prefixing: Yes Repeat count prefixing: No Alternate block checks: No Terminal emulation: Yes (VT52) Communication settings: Yes; local echo, parity Transmit BREAK: Yes IBM communication: Yes Transaction logging: No Session logging (raw download): No Raw upload: No Act as server: No Talk to server: Yes Advanced commands for servers: No Local file management: No Handle file attributes: No Command/init files: No Printer control: No KERMIT-65 is a program that implements the KERMIT file transfer protocol for the Apple ][ micro computer system. It is written in 6502 assembly language and should run on any Apple ][ or Apple ][ Plus system running DOS 3.3. This section will describe the things you should know about the DOS 3.3 file system in order to make effective use of KERMIT, and then it will describe the special features of the KERMIT-65 program. 13.1. The DOS 3.3 File System Items of importance which will be discussed in this section include Filenames and File Characteristics. APPLE-DOS KERMIT Page 156 Apple DOS Filenames Filenames under Apple DOS may contain almost any ASCII character (including space). It is not recommended that special characters, (i.e. control characters or spaces) be used in a filename to be transferred by Kermit-65 since they may cause problems when parsing the filename. Filenames may be up to 40 characters in length. No wildcarding of any kind can be done in KERMIT-65. Apple DOS File Characteristics All files in Apple DOS have a file type associated with them which is contained in the directory entry for the file but is not part of the filename itself. There are four types of files in DOS 3.3. They are: - APPLESOFT BASIC - INTEGER BASIC - BINARY - TEXT All file types have their data stored in eight-bit bytes although not all of them need the eighth bit. The two file types containing basic programs required the eighth bit due to the nature of the data being stored. BINARY files are images of memory copied into a file. Often, these are machine code programs. These files require all eight bits. TEXT files normally contain only printable or carriage control charac- ters. They are stored in the form of seven-bit ASCII characters but the eighth bit should always be set since Apples manipulate all text inter- nally as 'NEGATIVE ASCII'. When transmitting text files, the byte size should be set to seven-bit. When transmitting anything else, the user must insure that both Kermits are handling eight bit data so that no information is lost. If an eight-bit data path is not available (i.e. the remote Kermit needs to do parity checking with the eigth bit), then eight-bit quoting should be used. Of course, BINARY files as well as Apple BASIC files will not have much meaning on a different system. If the user desires to edit a BASIC file on a mainframe, for instance, he must convert it to a TEXT file be- fore sending it over. After receiving the file back on the Apple, the user may convert it back to BASIC once again. The reason BASIC files would be meaningless to a different machine is that the Apple stores BASIC keywords as single character tokens to save space and processing time. To convert a BASIC program to and from a TEXT file, consult the Apple DOS 3.3 Manual. File information can be obtained by issuing the CATALOG command. For ex- ample: ]CATALOG DISK VOLUME 010 APPLE-DOS KERMIT Page 157 *A 002 HELLO B 078 KERMIT A 002 READER T 005 TESTFILE ] When KERMIT-65 is receiving a file, the file it creates on diskette will be of the type indicated by the FILE-TYPE parameter. The file will al- ways be left in an unlocked state after it is closed by KERMIT-65. When sending a file, KERMIT-65 will use the FILE-TYPE parameter to determine how to detect an End-of-file condition. Thus, it is important to have this set properly in all cases. Recommendations for archiving files When using a large system for archiving purposes, there is no reason to convert Apple Basic programs into text files before sending them since there is no need to edit them on the mainframe. The FILE-TYPE parameter must always be set correctly when sending and receiving files. Also, when sending files which require eight-bit FILE-BYTE-SIZEs, this parameter must also be set properly since KERMIT-65 does not change it automatically based on FILE-TYPE. The procedure for archiving TEXT files is: - Run Kermit on remote system - SET FILE-BYTE-SIZE SEVEN-BIT ! On KERMIT-65 - SET FILE-TYPE-MODE TEXT ! On KERMIT-65 - Send files The procedure for archiving APPLESOFT, INTEGER, and BINARY files is: - Run Kermit on remote system - Set File-byte-size to Eight-bit ! On Remote Kermit - SET FILE-BYTE-SIZE EIGHT-BIT ! On KERMIT-65 - SET FILE-TYPE-MODE APPLESOFT ! (or INTEGER, or BINARY) On KERMIT-65 - Send files APPLE-DOS KERMIT Page 158 13.2. Program Operation HARDWARE CONSIDERATIONS Prior to using KERMIT-65 for transferring files, the modem interface must be set to handle data in a certain manner. Firstly, the data format should be 8 data bits and 1 stop bit. Secondly, the card should be set to no parity. The baud rate (if adjustable) must be set to whatever rate the modem can handle. For the Apple Com card and the D.C. Hayes Micromodem, these parameters are set correctly by default, so very lit- tle has to be done. For the Apple Super Serial Card, however, these have to be set before using KERMIT-65. In all cases, use the same procedure to connect to the mainframe host as is indicated in the section below on Installing KERMIT. Some mainframes cannot handle data in the format of 8 data bits and 1 stop bit because they may need parity checking (i.e. most IBM machines). In this case, 7 data bits and 1 stop bit plus some parity setting (other than none) will usually work. When talking with such mainframes, binary and basic files on the Apple cannot be transferred unless Eighth-bit-quoting is used. CONVERSING WITH KERMIT-65 KERMIT-65's prompt is "KERMIT-65>". To run KERMIT-65 and issue commands to it, type the following: ]BRUN KERMIT STEVENS/CU - APPLE ][ KERMIT-65 - VER 2.1 Kermit-65>SEND TESTFILE file is sent Kermit-65>STATUS performance statistics are printed Kermit-65>Other commands . . . Kermit-65>EXIT ] KERMIT-65 uses a TOPS-20 style command parser. During interactive operation, you may use the ?-prompting help feature ("?") and recognition (ESC) features while typing commands. A question mark typed at any point in a command displays the options available at APPLE-DOS KERMIT Page 159 that point; typing an ESC character causes the current keyword to be completed (or default value to be supplied). If you have not typed suf- ficient characters to uniquely specify the keyword or filename (or if there is no default value) then a beep will be sounded and you may con- tinue typing. Keywords may be abbreviated to any prefix that is unique. There are several different Apple]['s which can run KERMIT-65. Kermit will have no problems running on an Apple ][ or Apple ][+ system. It will run on the Apple //e as well, however, the 80-column board cannot be used at this time. Of the different communication devices available for the Apple ][, three are supported: - Apple Com Card - D.C. Hayes Micromodem - Apple Super Serial Card It is possible that other cards may have operational characteristics very similar or identical to one of the devices above. If this is the case, it may work using one of the currently available device drivers. The user may want to try each of the above options to see if any of them work. KERMIT-65 must be told which device is being used so that it may run with the correct device driver. It also must be told in which slot the card resides. This may be done with the 'SET' command (documented below). 13.3. Remote and Local Operation KERMIT-65 is normally run in local mode. It may be run as a remote Ker- mit as well although there is no advantage to doing things that way. KERMIT-65 supports User-mode commands for talking to a Server. It does not currently support server mode. 13.4. KERMIT-65 Commands THE SEND COMMAND Syntax: SEND filespec The SEND command causes a file to be sent from the Apple to the remote system. The Filespec is the name of the file on the Apple diskette to be sent. The parser will not accept control characters and certain special characters in a filename (i.e. a comma), so the user may have to rename the file before it is sent. The user may also have problems in filename compatibility with remote Kermits. If the remote Kermit does not have the facilities to beat the filename into a format that its system likes, the user may have to rename the file before sending it. The default disk drive used for file transfers is the drive used to boot the system APPLE-DOS KERMIT Page 160 or the last drive accessed with a DOS command. This can be changed with the 'SET DEFAULT-DISK' command (explained below). Either the slot or the drive or both may be altered. As a file is being sent, the screen displays either 'SENDING PACKET...' or 'WAITING PACKET...' followed by the absolute packet number since start of transmission. If a packet must be transmitted several times and it reaches the maximum retry count, the transfer will fail and the 'KERMIT-65>' prompt will return. If the remote Kermit sends an error packet, the text of the packet will be displayed on the screen and the prompt will return. Currently, a packet can be retransmitted manually by typing anything on the keyboard. If a 'Q' is typed, the entire transmission will be aborted. THE RECEIVE COMMAND Syntax: RECEIVE [filespec] The RECEIVE command tells KERMIT-65 to receive a file or file group from the other system. If only one file is being received, you may include the optional filespec as the name to store the incoming file under; otherwise, the name is taken from the incoming file header. If the name in the header is not a legal filename in DOS 3.3, KERMIT-65 will attempt to change it into something legal. There are very few things that are illegal in DOS 3.3. If FILE-WARNING is on and an incoming file has a name identical to a file already existing on the diskette, KERMIT-65 will issue a warning to the user and attempt to modify the filename to make it unique. GET Syntax: GET remote-filespec The GET command requests a remote KERMIT server to send the file or file group specified by remote-filespec. This command can be used with a KERMIT server on the other end. The remote filespec is any string that can be a legal file specification for the remote system; it is not parsed or validated locally. If the remote KERMIT is not capable of server functions, then you will probably get an error message back from it like "Illegal packet type". In this case, you must connect to the other Kermit, give a SEND command, escape back, and give a RECEIVE command. APPLE-DOS KERMIT Page 161 THE CONNECT COMMAND Syntax: CONNECT Establish a terminal connection to the remote system. Get back to KERMIT-65 by typing the escape character followed by the letter C. The escape character is Control-@ by default. When you type the escape character, several single-character commands are possible: B Send a BREAK Signal. C Close the connection and return to KERMIT-65. S Show status of the connection. 0 Send a null. Connect-escape Send the Connect-escape character itself. ? List all the possible single-character arguments. You can use the SET ESCAPE command to define a different escape charac- ter. When 'CONNECTED', KERMIT-65 will be passing characters entered on the keyboard to the remote system, and passing characters from the remote system to the Apple screen. If VT52-EMULATION is turned on, Kermit will trap escape codes and simulate the appropriate functions of a VT52 ter- minal. On an Apple ][+ with an incomplete keyboard, special characters can be obtained by prefixing regular characters with a right-arrow. Also, Up- percase is shown in inverse and lowercase characters are displayed as normal uppercase characters. Here are the rules for using the special 2/2+ input, to get all print- able ASCII characters, and how they appear on the screen: Special meanings are applied in various contexts to certain characters. The left and right arrow keys do special things, and sometimes the es- cape key does as well. For letters, the keyboard is always in either default UPPERCASE mode or default lowercase mode. When in UPPERCASE, all letters typed are sent out as uppercase. In lowercase, all letters are sent as lowercase. To reverse the case for the next character only, hit the right-arrow ("prefix") key. To switch the default case, hit the prefix-key twice in a row. For funny characters, the prefix key is also used to get the unusual punctuation characters which are not on the Apple keyboard. Here they are: (To represent the prefix character I am using the letter p). To get Type Appearence Left Square Bracket p( [ Right Square Bracket p) ] Left Curly Bracket p< { Right Curly Bracket p> } Underline p- _ APPLE-DOS KERMIT Page 162 Backslash p/ \ Tilde (wiggle) p^ ~ Vertical Line p. | The left-arrow key sends a rubout. With left-arrow and right arrow doing special things, its a little hard to enter their characters (^H and ^U respectivly). There is therefore an escape from prefix mode sequence. If you type prefix-ESC, the next character is sent without any interpretation. Currently, it is impossible to turn this special input and display on and off, so its a bit of a pain if you are on a Apple 2e. THE HELP COMMAND Syntax: HELP Typing HELP alone prints a brief summary of the KERMIT-65 commands. THE EXIT AND QUIT COMMANDS Syntax: EXIT Exit from KERMIT-65. You can restart the program, provided you haven't run anything else, by typing 'CALL 2049'. Syntax: QUIT This is merely a synonym for EXIT. THE SET COMMAND Syntax: SET parameter [option] [value] Establish or modify various parameters for file transfer or terminal connection. You can examine their values with the SHOW command. The following parameters may be SET: DEBUGGING TERSE or VERBOSE packet information. DEFAULT-DISK Which Diskette drive is used for file transfer? DEVICE-DRIVER Which communication device is being used? EIGHT-BIT-QUOTING Should eight-bit-quoting be used? ESCAPE Character for terminal connection. FILE-BYTE-SIZE SEVEN or EIGHT significant bits in a byte. FILE-TYPE Of Apple DOS file being sent/received. APPLE-DOS KERMIT Page 163 FILE-WARNING Warn users if incoming file exists? IBM For communicating with an IBM mainframe KEYBOARD ][+ or //e keyboard. LOCAL-ECHO Full or half duplex switch. PARITY Character parity to use RECEIVE Various parameters for receiving files SEND Various parameters for sending files SLOT Which slot # is communication device in? VT52-EMULATION Should Kermit emulate a VT52 when connected? SET DEBUGGING Syntax: SET DEBUGGING options Record the packet traffic on your terminal. Options are: TERSE Show packet info only (brief). VERBOSE Display packet field descriptions with packet info (lengthy). OFF Don't display debugging information (this is the default). SET DEFAULT-DISK Syntax: SET DEFAULT-DISK parameter value This command will tell KERMIT-65 which disk drive should be used for file transfers. The two parameters which may be set separately are SLOT and DRIVE. The value for SLOT ranges from 1 to 7. The value for DRIVE is either 1 or 2. SET DEVICE-DRIVER Syntax: SET DEVICE-DRIVER parameter keyword This command will tell KERMIT-65 what type of communication device is being used. Currently, three different cards are supported, however, other unsupported cards may work similar enough to one of the three available that it may be possible to use them. KERMIT-65 must also be told where the card is in the machine (see the SET SLOT command). The options for this set command are: APPLE-COM-CARD The old Apple communication card (300 baud). APPLE-DOS KERMIT Page 164 DC-HAYES The D.C. Hayes Micromodem II (300 baud). SUPER-SERIAL-CARD The Apple Super Serial Card (300-19.2k baud). SET ESCAPE Syntax: SET ESCAPE hexidecimal-number Specify the control character you want to use to "escape" from remote connections back to KERMIT-65. The default is 0 (Control-@). The num- ber is the hex value of the ASCII control character, 1 to 37, for in- stance 2 is Control-B. SET FILE-BYTE-SIZE Syntax: SET FILE-BYTE-SIZE parameter Byte size for Apple DOS file I/O. The choices are SEVEN-BIT or EIGHT-BIT. SEVEN-BIT When sending a file, shut the H.O. bit. When receiving, turn the H.O. bit on. This is done since text files are the only files which should be sent as SEVEN-BIT files and text files only make sense to the Apple if they are encoded in 'negative ascii' values. EIGHT-BIT Always send and receive the bytes intact. All 8 bits are sig- nificant. SET FILE-TYPE Syntax: SET FILE-TYPE parameter keyword This will inform KERMIT-65 what type of DOS file is being sent or received. It is important that this is set correctly since KERMIT-65 must create a file of the appropriate type when receiving (and it has no way of knowing what kind of file it is). When KERMIT-65 is sending, it must also know the type of file since that tells it how to detect the actual end-of-file. The options for this parameter are APPLESOFT, IN- TEGER, TEXT and BINARY. APPLESOFT The file being sent/received is an Applesoft Basic program. INTEGER The file being sent/received is an Integer Basic program. TEXT The file being sent/received is an ASCII Text file. BINARY The file being sent/received is a Binary image. APPLE-DOS KERMIT Page 165 SET FILE-WARNING Syntax: SET FILE-WARNING ON or OFF This tells KERMIT-65 whether to warn the user about incoming filenames conflicting with existing files or not. SET IBM Syntax: SET IBM ON or OFF SET IBM actually sets a number of parameters. When setting it on, the command also turns on LOCAL-ECHO (half-duplex) and sets PARITY to MARK. When setting IBM OFF, LOCAL-ECHO will revert back to OFF and PARITY will be set to NONE. It should be used when doing file transfers with an IBM or similar mainframe. SET KEYBOARD Syntax: SET KEYBOARD 2P or 2E SET KEYBOARD tells KERMIT-65 if the user has a full keyboard (2E) or not (2P). If the user is on an Apple ][+, this should be set to 2P (which is the default). When set to that, certain character translations are available by using the right-arrow key as a prefix character. SET SLOT Syntax: SET SLOT parameter This option tells KERMIT-65 in which slot the communication device is located. The range for the parameter is 1-7. THE SHOW COMMAND Syntax: SHOW [option] The SHOW command displays various information: ALL All parameter settings (this is quite long). DEBUGGING Debugging mode. DEFAULT-DISK Which Diskette drive is used for file transfer? DEVICE-DRIVER Which communication device is being used? EIGHT-BIT-QUOTING Should eight-bit-quoting be used? ESCAPE Character for terminal connection. APPLE-DOS KERMIT Page 166 FILE-BYTE-SIZE SEVEN or EIGHT significant bits in a byte. FILE-TYPE Of Apple DOS file being sent/received. FILE-WARNING Warn users if incoming file exists? IBM For communicating with an IBM mainframe KEYBOARD ][+ or //e keyboard. LOCAL-ECHO Full or half duplex switch. PARITY Character parity to use RECEIVE Various parameters for receiving files SEND Various parameters for sending files SLOT Which slot # is communication device in? VT52-EMULATION Should Kermit emulate a VT52 when connected? The above options are analogous to the equivalent SET commands. THE STATUS COMMAND Give statistics about the most recent file transfer. This includes in- formation such as number of characters sent/received, number of data characters sent/received, and last error encountered. 13.5. Customizing, Building, and Installing KERMIT-65 STANDARD INSTALLATION The Procedure The procedure to bootstrap an assembled KERMIT object file to the Apple is as follows: 1. On the Apple, Type in the APPLBT.BAS program supplied (See below). It is recommended that the user save this program as it may be needed to bootstrap newer versions of KERMIT or APPHXL in the future. Also, type the APPLESOFT program in with none of the REMs. It will execute quicker and take up less room. 2. Call and login to the mainframe on which the KERMIT-65 object file resides. Do the following: - ]IN#n ! Where n is between 1 and 7 - For Communication card, do the following: APPLE-DOS KERMIT Page 167 * Dial number for computer system. * Seat phone receiver in modem cradle. * ] !Full duplex, 300 baud - For the D.C. Hayes Micromodem, do the following: * ] ! Full duplex, 300 baud * MICROMODEM II: BEGIN TERM * MICROMODEM II: DIALING: nnn-nnnn ! nnn-nnnn is number of computer system - For the Apple Super Serial Card, do the following: * ] * APPLE SSC:0D ! 8 data bits, 1 stop bit * ] * APPLE SSC:0P ! Force no parity * ] * APPLE SSC:nB ! n = 6 for 300 baud, n = 8 for 1200 baud * Dial number for computer system. * Seat phone receiver in modem cradle. * ] * APPLE SSC:T ! Terminal mode, now talking to remote host 3. In your directory on the mainframe, the following files should be present: - APPLBT.FOR - APPHXL.HEX - APPLEK.HEX Compile and execute APPLBT.FOR. This will be used along with APPLBT.BAS on the Apple to load the APPHXL program. Once AP- PLBT is executing on the mainframe, give control back to the Apple and then run APPLBT.BAS on the Apple. For either the Communication Card or the D.C. Hayes Micromodem, the proce- dure is: - ! Give control to Apple's Brain APPLE-DOS KERMIT Page 168 - ]LOAD APPLBT.BAS - ]LOMEM:9500 - ]RUN 4. Relocate and save APPHXL. Type the following: - ]CALL -151 ! Enter Apple's system monitor - *9000<2000.2280M ! Move APPHXL from $2000 to $9000 - * ! Reenter APPLESOFT - ]BSAVE APPHXL,A$9000,L$280 ! Save APPHXL to disk 5. Now simply start executing APPHXL. - ]CALL -151 ! Enter monitor - *9000G ! Start APPHXL - SLOT FOR MODEM CARD? (1 TO 7 )n ! 'n' is slot # of card (no ) - ENTER FILENAME TO LOAD APPLEK.HEX ! Tell APPHXL what to load APPHXL will print the byte count and load address for each line it is receiving as it loads it into memory. At the end of each line, it will print '[OK]' if the line was received properly or '[CHECKSUM ERROR]' if there was a problem with it. 6. When APPHXL finishes type the following to the Apple: ]BSAVE KERMIT,A$801,L$4E00 ! Save KERMIT to disk 7. The user may set up a turn-key system by having the hello file on the disk load and run KERMIT. The user may also run KERMIT-65, change the defaults which are supplied in the program such as SLOT and DEVICE-DRIVER, and then resave KERMIT-65. The next time it is run, the user will not have to set these values again. If the user does not set up a turn-key system, he must start KERMIT-65 by typing: ]BRUN KERMIT ! Execute KERMIT-65 on the Apple The Apple will display the following: STEVENS/CU - APPLE ][ KERMIT-65 VER. 2.1 KERMIT-65> The user is now ready to transfer files. NOTE: For those users with the Apple Super Serial Card, the APPLE-DOS KERMIT Page 169 intercept character should be shut off by typing Z to the card before Kermit is run. The reason for this is that Kermit uses as a Start-of-Header character and this character may never reach the program if the card is taking it to be a command. APPLBT.BAS - The APPLESOFT Bootstrap program 10 REM - LOADER FOR HXLOAD 11 OAD = 0 100 N$ = "0123456789ABCDEF" 110 D$ = CHR$ (4) 130 PRINT D$;"IN#2" : REM CHANGE '2' TO SLOT OF COMM. CARD IF NECESSARY 135 PRINT CHR$ (1); CHR$ (6) 136 PRINT D$;"PR#2" : REM CHANGE '2' TO SLOT OF COMM. CARD IF NECESSARY 137 PR#2 : REM THIS LINE SHOULD BE HERE ONLY FOR THE APPLE COMM. CARD 140 C3 = 0 150 HOME 199 REM - REQUEST NEXT LINE 200 REM - PUT A DOT ON THE SCREEN FOR EACH LINE RECEIVED 201 C3 = C3 + 1: POKE 1024 + C3, ASC (".") 202 L$ = "":Y2% = 1: PRINT 203 GET A$:L$ = L$ + A$:Y2% = Y2% + 1: IF Y2% < 81 THEN 203 205 C1 = 0:C2 = 0:I = 0 208 IF LEFT$ (L$,1) > = "0" AND LEFT$ (L$,1) < = "9" THEN 220 210 L$ = RIGHT$ (L$, LEN (L$) - 1): GOTO 208 220 LL = LEN (L$) 249 REM - FETCH THE DATA BYTE COUNT FOR THIS LINE 250 GOSUB 1000:C1 = C1 + B:CO = B 255 IF CO = 0 THEN 990 259 REM - CONSTRUCT THE LOAD ADDRESS FOR THIS LINE 260 GOSUB 1000:C1 = C1 + B:AD = B: GOSUB 1000:C1 = C1 + B :AD = AD * 256 + B 265 REM - IF THE LATEST VERSION OF CROSS IS USED, THIS SHOULD NOT BE NEEDED : REM AD = AD - 28672 266 IF AD < OAD THEN 990 267 OAD = AD 270 FOR X = 0 TO CO - 1 275 REM - GO GET A BYTE AND PUT IT IN THE NEXT MEMORY LOCATION 280 GOSUB 1000:C1 = C1 + B 290 POKE AD + X,B 300 NEXT X 310 GOSUB 1000:C2 = B: GOSUB 1000:C2 = C2 * 256 + B 320 IF C1<>C2 THEN POKE 1024+C3,ASC("E") 330 GOTO 201 990 FOR X = 1 TO 1000: NEXT X 995 PRINT D$;"IN#0": PRINT D$;"PR#0": HOME : END 999 REM - GET BYTE 1000 GOSUB 1501:B = N1: GOSUB 1501:B = B * 16 + N1 1010 RETURN 1500 REM - GET NIBBLE 1501 IF LEN (L$) = 0 THEN N1 = 0: RETURN 1510 H$ = LEFT$ (L$,1) 1511 IF LEN (L$) = 1 THEN L$ = "": GOTO 1525 1515 L$ = RIGHT$ (L$, LEN (L$) - 1) 1520 REM - RETURN VALUE OF HEX NIBBLE APPLE-DOS KERMIT Page 170 1525 FOR X1 = 1 TO 16 1530 IF H$ = MID$ (N$,X1,1) THEN 1610 1540 NEXT X1 1550 REM - DIGIT WAS NOT FOUND, RETURN ZERO 1560 N1 = 0: RETURN 1600 REM 1610 N1 = X1 - 1: RETURN APPLBT.FOR - The Mainframe Bootstrap program CHARACTER LINE*80,SENTNL*1 OPEN (UNIT=00,FILE='APPHXL.HEX',MODE='ASCII') 10 READ (UNIT=05,FMT=20) SENTNL 20 FORMAT (A1) READ (UNIT=00,FMT=25,END=999) LINE 25 FORMAT(A80) WRITE (UNIT=05,FMT=30) LINE 30 FORMAT(A80) GO TO 10 999 READ (UNIT=05,FMT=20) SENTNL STOP END ALTERNATIVE INSTALLATION PROCEDURES HEXloading from Diskette Once the user has a working version of KERMIT-65 on his system, he can use this to load the .HEX files of future versions of KERMIT. There is another hexload program available called APPDXL. This program will load a hex file from an Apple diskette into memory. To use this procedure, do the following: 1. Start executing APPHXL. - ]BLOAD APPHXL ! Get APPHXL into memory - ]CALL -151 ! Enter monitor - *9000G ! Start APPHXL - SLOT FOR MODEM CARD? (1 TO 7 )n ! 'n' is slot # of card (no ) - ENTER FILENAME TO LOAD APPDXL.HEX ! Tell APPHXL what to load APPHXL will print what it is receiving on the screen as well as loading it into memory. 2. Relocate and save APPDXL. Type the following: APPLE-DOS KERMIT Page 171 - ]CALL -151 ! Enter Apple's system monitor - *9000<2000.2500M ! Move APPDXL from $2000 to $9000 - * ! Reenter APPLESOFT - ]BSAVE APPDXL,A$9000,L$500 ! Save APPDXL to disk 3. Use Kermit-65 to transfer the new version of itself over. Make the Apple file a Text file. WARNING: This file will take LOTS of space (about 180 sectors) so make sure the disk is reasonably empty. The transfer takes a LONG time also, so please be patient. 4. Start executing APPDXL. - ]BRUN APPDXL ! Start APPDXL - ENTER FILENAME TO LOAD APPLEK.HEX ! Tell APPDXL what to load 5. When APPDXL finishes type the following to the Apple: ]BSAVE KERMIT,A$801,L$4E00 ! Save KERMIT to disk The new version of Kermit is now on disk. Using KERMIT-65 to transfer APPLEK.BIN There is yet another way to Bootstrap a new version of KERMIT onto an Apple. If the user has an older version of KERMIT-65 and has access to a machine with a valid copy of APPLEK.BIN, they can simply transfer APPLEK.BIN using their version of KERMIT. Be sure to set the File-byte-size to Eight-bit, and the File-type-mode to Binary before transfering the file since this is the actual object code. No special loading or conversion is needed. The file will be placed on the disk and ready to run. FILES SUPPLIED FOR KERMIT-65 The following files should be supplied on the distribution tape: - APPLBT.BAS - Initial bootstrap program to load APPHXL - APPLBT.FOR - Program on mainframe to talk to APPLBT.BAS - APPHXL.M65 - Source of program to load KERMIT-65 - APPHXL.HEX - Assembled version of Hex load program - APPDXL.M65 - Source of program to load KERMIT-65 from Apple diskette - APPDXL.HEX - Assembled version of Disk Hex load program APPLE-DOS KERMIT Page 172 - APPLEK.M65 - Source for the KERMIT-65 program - APPLEK.HEX - Assembled version of KERMIT-65 - APPLEK.BIN - Assembled version of KERMIT-65 (Eight-bit Binary object code) - CROSS.MAC - CROSS Microprocessor Assembler (Source) - CROSS.EXE - CROSS Microprocessor Assembler (Object) CUSTOMIZING AND BUILDING KERMIT-65 The source code to KERMIT-65 is in 6502 Assembler. It has been formatted for CROSS which is a micro-Cross Assembler program which runs on DECsystem-10s and DECSYSTEM-20s. Customizations would be made the easiest if CROSS were available. KERMIT-65 currently supports the following communications devices: - FTASER - The Apple Communication card - FTHAYS - The D.C. Hayes Micromodem. - FTSSC - The Apple Super Serial Card All device drivers are included in the assembled version and may be used by issuing a 'SET DEVICE-DRIVER' command to Kermit. If any of the device drivers are not needed, it(they) may be excluded by setting the ap- propriate feature test to zero in the Feature test section of the source code. Excluding one or more device drivers can reduce the size of the object code greatly. DO NOT disable all device drivers since KERMIT-65 will then have no way of talking over the communication device. The feature test FTCOM must be set to the type of computer for which KERMIT-65 is being assembled. The only machine KERMIT-65 is available for currently is the Apple ][. This parameter must be set to FTAPPL. After setting any options necessary in APPLEK.M65, rename it to KERMIT.M65, and do the following: - .R CROSS ! Run CROSS Microprocessor Assembler - *KERMIT.HEX/PTP:KIM=KERMIT.M65/M65 ! Generate .HEX file This command will produce an ASCII HEX file which can be downline loaded onto the Apple using APPHXL. If a listing is desired, one can be produced by adding ",KERMIT.LST" after the "/PTP:KIM" in the command line to CROSS. KERMIT User Guide Page 173 I. The ASCII Character Set ASCII Code (ANSI X3.4-1968) There are 128 characters in the ASCII (American national Standard Code for Information Interchange) "alphabet". The characters are listed in order of ASCII value; the columns are labeled as follows: Bit Even parity bit for ASCII character. ASCII Dec Decimal (base 10) representation. ASCII Oct Octal (base 8) representation. ASCII Hex Hexadecimal (base 16) representation. EBCDIC Hex EBCDIC hexadecimal equivalent for Kermit translate tables. Char Name or graphical representation of character. Remark Description of character. The first group consists of nonprintable 'control' characters: .....ASCII.... EBCDIC Bit Dec Oct Hex Hex Char Remarks 0 000 000 00 00 NUL ^@, Null, Idle 1 001 001 01 01 SOH ^A, Start of heading 1 002 002 02 02 STX ^B, Start of text 0 003 003 03 03 ETX ^C, End of text 1 004 004 04 37 EOT ^D, End of transmission 0 005 005 05 2D ENQ ^E, Enquiry 0 006 006 06 2E ACK ^F, Acknowledge 1 007 007 07 2F BEL ^G, Bell, beep, or fleep 1 008 010 08 16 BS ^H, Backspace 0 009 011 09 05 HT ^I, Horizontal tab 0 010 012 0A 25 LF ^J, Line feed 1 011 013 0B 0B VT ^K, Vertical tab 0 012 014 0C 0C FF ^L, Form feed (top of page) 1 013 015 0D 0D CR ^M, Carriage return 1 014 016 0E 0E SO ^N, Shift out 0 015 017 0F 0F SI ^O, Shift in 1 016 020 10 10 DLE ^P, Data link escape 0 017 021 11 11 DC1 ^Q, Device control 1, XON 0 018 022 12 12 DC2 ^R, Device control 2 1 019 023 13 13 DC3 ^S, Device control 3, XOFF 0 020 024 14 3C DC4 ^T, Device control 4 1 021 025 15 3D NAK ^U, Negative acknowledge 1 022 026 16 32 SYN ^V, Synchronous idle 0 023 027 17 26 ETB ^W, End of transmission block 0 024 030 18 18 CAN ^X, Cancel 1 025 031 19 19 EM ^Y, End of medium 1 026 032 1A 3F SUB ^Z, Substitute 0 027 033 1B 27 ESC ^[, Escape, prefix, altmode 1 028 034 1C 1C FS ^\, File separator 0 029 035 1D 1D GS ^], Group separator 0 030 036 1E 1E RS ^^, Record separator 1 031 037 1F 1F US ^_, Unit separator The last four are usually associated with the control version of back- KERMIT User Guide Page 174 slash, right square bracket, uparrow (or circumflex), and underscore, respectively, but some terminals do not transmit these control charac- ters. The following characters are printable: First, some punctuation characters. .....ASCII.... EBCDIC Bit Dec Oct Hex Hex Char Remarks 1 032 040 20 40 SP Space, blank 0 033 041 21 5A ! Exclamation mark 0 034 042 22 7F " Doublequote 1 035 043 23 7B # Number sign, pound sign 0 036 044 24 5B $ Dollar sign 1 037 045 25 6C % Percent sign 1 038 046 26 50 & Ampersand 0 039 047 27 7D ' Apostrophe, accent acute 0 040 050 28 4D ( Left parenthesis 1 041 051 29 5D ) Right parenthesis 1 042 052 2A 5C * Asterisk, star 0 043 053 2B 4E + Plus sign 1 044 054 2C 6B , Comma 0 045 055 2D 60 - Dash, hyphen, minus sign 0 046 056 2E 4B . Period, dot 1 047 057 2F 61 / Slash Numeric characters: .....ASCII.... EBCDIC Bit Dec Oct Hex Hex Char Remarks 0 048 060 30 F0 0 Zero 1 049 061 31 F1 1 One 1 050 062 32 F2 2 Two 0 051 063 33 F3 3 Three 1 052 064 34 F4 4 Four 0 053 065 35 F5 5 Five 0 054 066 36 F6 6 Six 1 055 067 37 F7 7 Seven 1 056 070 38 F8 8 Eight 0 057 071 39 F9 9 Nine More punctuation characters: .....ASCII.... EBCDIC Bit Dec Oct Hex Hex Char Remarks 0 058 072 3A 7A : Colon 1 059 073 3B 5E ; Semicolon 0 060 074 3C 4C < Left angle bracket 1 061 075 3D 7E = Equal sign 1 062 076 3E 6E > Right angle bracket 0 063 077 3F 6F ? Question mark 1 064 100 40 7C @ "At" sign KERMIT User Guide Page 175 Upper-case alphabetic characters (letters): .....ASCII.... EBCDIC Bit Dec Oct Hex Hex Char Remarks 0 065 101 41 C1 A 0 066 102 42 C2 B 1 067 103 43 C3 C 0 068 104 44 C4 D 1 069 105 45 C5 E 1 070 106 46 C6 F 0 071 107 47 C7 G 0 072 110 48 C8 H 1 073 111 49 C9 I 1 074 112 4A D1 J 0 075 113 4B D2 K 1 076 114 4C D3 L 0 077 115 4D D4 M 0 078 116 4E D5 N 1 079 117 4F D6 O 0 080 120 50 D7 P 1 081 121 51 D8 Q 1 082 122 52 D9 R 0 083 123 53 E2 S 1 084 124 54 E3 T 0 085 125 55 E4 U 0 086 126 56 E5 V 1 087 127 57 E6 W 1 088 130 58 E7 X 0 089 131 59 E8 Y 0 090 132 5A E9 Z More punctuation characters: .....ASCII.... EBCDIC Bit Dec Oct Hex Hex Char Remarks 1 091 133 5B AD [ Left square bracket 0 092 134 5C E0 \ Backslash 1 093 135 5D BD ] Right square bracket 1 094 136 5E 5F ^ Circumflex, up arrow 0 095 137 5F 6D _ Underscore, left arrow 0 096 140 60 79 ` Accent grave KERMIT User Guide Page 176 Lower-case alphabetic characters (letters): .....ASCII.... EBCDIC Bit Dec Oct Hex Hex Char Remarks 1 097 141 61 81 a 1 098 142 62 82 b 0 099 143 63 83 c 1 100 144 64 84 d 0 101 145 65 85 e 0 102 146 66 86 f 1 103 147 67 87 g 1 104 150 68 88 h 0 105 151 69 89 i 0 106 152 6A 91 j 1 107 153 6B 92 k 0 108 154 6C 93 l 1 109 155 6D 94 m 1 110 156 6E 95 n 0 111 157 6F 96 o 1 112 160 70 97 p 0 113 161 71 98 q 0 114 162 72 99 r 1 115 163 73 A2 s 0 116 164 74 A3 t 1 117 165 75 A4 u 1 118 166 76 A5 v 0 119 167 77 A6 w 0 120 170 78 A7 x 1 121 171 79 A8 y 1 122 172 7A A9 z More punctuation characters: .....ASCII.... EBCDIC Bit Dec Oct Hex Hex Char Remarks 0 123 173 7B C0 { Left brace (curly bracket) 1 124 174 7C 4F | Vertical bar 0 125 175 7D D0 } Right brace (curly bracket) 0 126 176 7E 7E ~ Tilde Finally, one more nonprintable character: 0 127 177 7F 07 DEL Delete, rubout KERMIT User Guide Page 177 Index DEFINE 65, 110 8080 141 Define SET Macros 43 Delay 38 ?-prompting 158 DELETE 56 DEVICE-DRIVER 163 ANSI.SYS 105 Dialup 15 APC 153 Diskette 22 APPLE ][+ 155 DO Command 110 APPLESOFT 164 DOS 3.3 155 ARPANET 65 Downloading 142 ASCII 173 Duplex 38 Autoanswer 17 Autodialer 14, 111 EBCDIC 173 Eighth-Bit Prefix 29, 30, 40, 55, Batch Operation of Kermit-MS 95 56, 107, 139, 151 Baud 139, 150 EMACS 113 Baud Rate 36, 103 End Of File 50, 93, 104 Beeper 103 End Of Line 41, 42 Bell 103 End-Of-Line (EOL) 82 BINARY 164 EOF 104 Binary Files 21, 29, 40, 55, 56, 107Error Recovery 20 BIOS 141 Escape Character 11, 137, 139, 149, Block Check 36, 139 150 Bootstrap 142 Escape Character for CONNECT 38, 62, BREAK Simulation 61, 65 105, 164 BYE 18, 19, 138, 149 Escape Sequence 10 Byte Size 49, 57, 63, 164 EXIT 35, 61, 162 Expunging Deleted Files 62 Cables 14, 16 Cancelling a File Transfer 30, 31,File Renaming 109 55, 56, 97, 98 File Warning 109 Capturing Files 44 FILE-BYTE-SIZE 164 Checksum 6 FILE-TYPE 164 Command Files 109 File-Warning 137, 149, 165 Command Macro 110 Filespec 159 Command Parsing 25 FINISH 18, 19, 138, 149 CONNECT 9, 11, 111, 137, 149, 161 Flow Control 39, 105, 150 CONTINUE 35, 61 Control Characters 10, 173 Generation 56 Control-A 55 Generic Kermit-80 141, 145 Control-C 35, 61 Generic MS-DOS Kermit 122 Control-V 56 GET 19, 137, 149, 160 Control-X 30, 31, 55, 56, 97, 98 Control-Z 30, 31, 55, 56, 97, 98 Handshake 39, 105 CP/M 50, 141 Heath-19 Terminal Emulation 105, Crash 22 111, 131 Cross Assembler 144 Help 51, 94, 158, 162 Hex File 145 Deadlock 22 Debugging 37, 62, 104, 150, 163 IBM 63, 81, 139, 150, 165 DEC Rainbow 152 IBM PC 90 DECsystem-10 144 Incomplete File Disposition 31, 56, DECSYSTEM-20 46, 144 98 DEFAULT-DISK 163 Incomplete File Transfer 39 KERMIT User Guide Page 178 Initial Filespec 22, 29, 53, 54 Remote 11, 24 INTEGER 164 Repeated Character Compression 29, Interference 52 30, 55, 56 Internal Modem 20 Retry Limit 42 IOBYTE 145 ITS-Binary Format 63 SEND 11, 14, 19, 22, 29, 53, 81, 137, 149, 159 Kermit Commands 11 Server 17, 32, 57 KERMIT Protocol 6 SET 11, 82, 138, 150 Kermit server 17 SHOW 12, 43, 66, 82, 151, 165 Key Redefinition 106 SLOT 165 KEYBOARD 165 Smart Modem 20, 21, 111 Speed 65, 66 Line Sequence Numbers 55 Start Of Packet 41, 42 Local 11, 24, 136, 148 Superbrain 141 Local Echo 38 Local Echoing 106 TAC Binary Mode 65 Local-Echo 138, 151 TAKE 151 LOG 44, 138, 151 TELENET 40, 43, 106 LOGOUT 138, 149 TERSE 163 LRECL 82 TEXT 164 Timeout 41, 42, 81, 109, 136, 142, MAC80 145 148 Macro 110 TIMER 139, 151 Message Interference 52 TOPS-20 46 META Key 113 TRANSMIT 138 Mode Line 111 TVT-Binary 65 Modem 20, 111 MS-DOS 90 UNDELETE 56 NAK 21, 136, 148 VERBOSE 163 NEC Advanced Personal Computer 153 Virtual Terminal 9, 11, 137, 149 Network 20 VM/CMS 14, 81 Noise 6 VT100 138 Normal Form for File Names 54, 63 VT52 138 Null Modem 14, 16 Warning 109, 138, 151 Packet 6, 8 Wildcard 11, 13, 47, 92 Packet Length 41, 42 Word Size 49 Packet-Length 82 Padding 41, 42 XON/XOFF 138, 173 Parity 20, 29, 30, 40, 55, 56, 106, 139, 151, 173 Z80 141 Pause Between Packets 41, 42 PC-DOS 90 Prompt 9, 41 Protocol 6 QUIT 35, 61, 162 Quote 82 Rainbow 100 152 RECEIVE 11, 13, 14, 30, 55, 82, 97, 137, 149, 160 RECFM 82 Recognition 51, 94, 158 KERMIT User Guide Page i Table of Contents Ordering Information 4 1. Introduction 6 2. How to Use KERMIT 8 2.1. The KERMIT Program 8 2.2. Talking to Two Computers at Once 9 2.3. Transferring a File 10 2.4. Basic KERMIT Commands 11 2.5. Real Examples 12 2.5.1. PC to Host 12 2.5.2. Host to Host 14 2.5.3. Micro to Micro 16 2.6. Another Way -- The KERMIT Server 17 3. When Things Go Wrong 20 3.1. Communication Line Problems 20 3.2. The Transfer is Stuck 21 3.3. The Micro is Hung 22 3.4. The Remote Host Went Away 22 3.5. The Disk is Full 22 3.6. Message Interference 23 3.7. Host Errors 23 3.8. File is Garbage 23 3.9. Junk after End of File 23 4. KERMIT Commands 24 4.1. Remote and Local Operation 24 4.2. Command Interface 25 4.3. Notation 26 4.4. Summary of KERMIT Commands 28 4.5. The SEND Command 29 4.6. The RECEIVE Command 30 4.7. GET 31 4.8. SERVER 32 4.9. BYE 32 4.10. FINISH 33 4.11. REMOTE 33 4.12. LOCAL 34 4.13. CONNECT 34 4.14. HELP 35 4.15. TAKE 35 4.16. EXIT, QUIT 35 4.17. The SET Command 35 4.18. DEFINE 43 4.19. SHOW 43 KERMIT User Guide Page ii 4.20. STATISTICS 43 4.21. LOG 44 4.22. TRANSMIT 44 5. KERMIT Implementations 45 6. DECSYSTEM-20 KERMIT 46 6.1. The DEC-20 File System 46 6.2. Program Operation 51 6.3. Remote and Local Operation 52 6.4. Conditioning Your Job for Kermit 53 6.5. KERMIT-20 Commands 53 6.6. Examples 68 6.7. Installation 71 7. VAX/VMS KERMIT 72 8. IBM VM/CMS KERMIT 81 9. UNIX KERMIT 86 10. MS-DOS KERMIT 90 10.1. The MS-DOS File System 91 10.1.1. File Specifications 91 10.1.2. File Formats 92 10.2. Program Operation 93 10.3. Kermit-MS Commands 95 10.3.1. Commands for File Transfer 96 10.3.2. Commands for Connecting and Disconnecting 99 10.3.3. Commands for File Management 100 10.3.4. The SERVER Command 102 10.3.5. The SET Command 103 10.3.6. The SHOW Command 109 10.3.7. Command Macros 110 10.4. Terminal Emulation 111 10.5. Installation of Kermit-MS 114 10.5.1. Try Again To Find A Kermit Disk 114 10.5.2. Bootstrapping From the Communication Line 114 10.5.2.1. Use An Existing File Capture Facility 115 10.5.2.2. Type In Your Own Bootstrap 115 10.6. Compatibility with Older Versions of MS-DOS Kermit 120 10.7. What's Missing 120 10.8. Program Organization 121 10.9. Adding Support For New Systems 122 10.9.1. Generic MS-DOS Kermit 122 10.9.2. Adding System-Dependent Code 123 10.10. Heath/Zenith-19 Control Codes 131 11. CP/M-80 KERMIT 134 KERMIT User Guide Page iii 11.1. Generic KERMIT-80 141 11.2. Installation 141 11.2.1. Downloading Kermit-80 142 11.2.2. Building KERMIT.HEX 144 11.2.3. Generic Kermit-80 145 12. CP/M-86 KERMIT 147 12.1. Kermit-86 Commands 149 12.2. Installation: 152 12.3. DEC Rainbow 100 Support 152 12.4. NEC Advanced Personal Computer Support 153 13. APPLE-DOS KERMIT 155 13.1. The DOS 3.3 File System 155 13.2. Program Operation 158 13.3. Remote and Local Operation 159 13.4. KERMIT-65 Commands 159 13.5. Customizing, Building, and Installing KERMIT-65 166 I. The ASCII Character Set 173 Index 177