MS-DOS KERMIT USER GUIDE FOR THE IBM PC FAMILY, COMPATIBLES, AND OTHER MS-DOS SYSTEMS C. Gianone, F. da Cruz J.R. Doupnik January 8, 1988 Copyright (C) 1981,1988 Trustees of Columbia University in the City of New York Permission is granted to any individual or institution to use, copy, or redistribute this document so long as it is not sold for profit, and provided this copyright notice is retained. -------- This document is formatted as an ordinary, plain text ASCII disk file, from SCRIBE text formatter source. Typeset copies are available from Columbia University. THIS IS AN ABRIDGED VERSION OF THE ORIGINAL, WITH AS MUCH MATERIAL DELETED AS REQUIRED TO MAKE IT FIT ON THE 360K MS-KERMIT DISTRIBUTION DISKETTE. UNDERLINING IS NOT SHOWN. -------- 1. MS-DOS KERMIT Program: Joe R. Doupnik (Utah State University), with contributions by James Harvey (Indiana/Purdue University), James Sturdevant (A.C. Nielson Company), and many others (see History). Language: Microsoft Macro Assembler (MASM) Version: 2.30 Released: January 8, 1988 Documentation: Christine Gianone, Frank da Cruz (Columbia University), Joe R. Doupnik (Utah State University) Dedicated To: Peppi MS-DOS Kermit, or "Kermit-MS" (or MS-Kermit), is a program that implements the Kermit file transfer protocol for the entire IBM PC family, including the PS/2 series, IBM compatibles, and several other machines based on the Intel 8086 processor series (8088, 80286, 80386, etc) and the DOS operating system family (PC-DOS or MS-DOS, henceforth referred to collectively as MS-DOS or simply DOS). It is assumed you are acquainted with your PC and with DOS, and that you are familiar with the general ideas of data communication and Kermit file transfer. A very brief overview is given here, but for details consult the early chapters of the Kermit User Guide (of which this document is a chapter), or the book Kermit, A File Transfer Protocol, by Frank da Cruz, Digital Press (1987), order number EY-6705E-DP (phone 1-800-343-8321), which also includes background tutorials on computers, file systems, and data communication (including modems, cabling, etc). For further information about Kermit documentation, updates, lists of current available versions, and ordering information, write to: Kermit Distribution Columbia University Center for Computing Activities 612 West 115th Street New York, NY 10025 (USA) 1.1. System Requirements Kermit-MS version 2.30 runs in as little as 70K of memory (about 55K contiguous), but will occupy up to 120K, if it can be found, for extra screen rollback memory. Versions not using screen rollback memory will not require the additional space. It will also try to leave 24 Kbytes free for a second copy of COMMAND.COM which is needed for execution of certain commands. (many details omitted) 1.2. History (omitted) 1.3. Using MS-Kermit MS-DOS Kermit performs two major functions, terminal emulation and file trans- fer. File transfer can be done using either the Kermit file transfer protocol, or else (without error checking), ASCII or XON/XOFF capture and transmission methods. To use Kermit for "raw" uploading or downloading of files, see the descriptions of the LOG SESSION and TRANSMIT commands. (examples omitted) 1.4. The MS-DOS File System (omitted, see your DOS manual.) 1.5. Program Setup and Invocation The MS-DOS Kermit program can be run from any disk without any special instal- lation procedure. On hard disk systems, it is convenient to store the program in one of the directories listed in your DOS PATH, and it is often desirable to customize Kermit's operation to your communications and computing environment by creating an initialization file. 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, and you may create it using any text editor capable of saving files in plain ASCII text format. Here is a sample: comment -- MSKERMIT.INI, MS-DOS Kermit initialization file comment -- Don't overwrite my files! set warning on comment -- Define macros for the systems I use... define unix set local-echo off,set par non,set flow xon,set timer off def ibm set par odd,set loc on,set hands xon,set flo none,set tim on def modem set port 2, set baud 1200 comment -- Define a macro for quickly adapting to noisy connections... def noisy set block-check 3, set send packet-length 40, set retry 20 comment -- I always start out by connecting to my UNIX system... set port 1 set baud 4800 do unix connect Interactive Operation: To run Kermit-MS interactively, invoke the program from DOS command level by typing its name, normally "kermit" (this means the program should be stored in your path with the name KERMIT.EXE). When you see the program's prompt, Kermit-MS> you may type Kermit commands repeatedly until you are ready to exit the program. Command Line Invocation: Kermit-MS may be invoked with command line arguments from DOS command level, for instance: A>kermit send peter.amy or A>kermit set port 1, set baud 9600, connect In this case, help and completion are not available (because the program that provides them won't start running until after you type the entire command line), and Kermit-MS will exit back to DOS after completing the specified com- mand 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. As of version 2.30, two new Kermit commands can be given on the DOS command line. First is the keyword STAY which prevents Kermit from exiting naturally when the last command has completed (unless, of course, EXIT or QUIT was among the commands). The second command is -F filename This means use the indicated filename as the initialization file rather than MSKERMIT.INI. The path will be searched for this file, if necessary. A space or tab must separate -F from the filename, and the F may be in upper or lower case. Example: kermit -f tuesday.ini, set port 2, do ibm, stay If -F is the only command line option, STAY is implied. Batch Operation: Like other MS-DOS programs, Kermit-MS may be operated under batch with command line arguments. If you invoke it without command line arguments, it will run interactively, reading commands from the keyboard and not the batch file. When it exits, batch processing will continue to the end of the batch file. Kermit-MS returns the "errorlevel" parameter used as program exit status. Present values are in the range 0 to 7 with three areas yielding success or failure reports for the entire Kermit session. The errorlevel values are: errorlevel Kermit session status 0 entirely successful operation 1 a Send command completed unsuccessfully 2 a Receive or GET command completed unsuccessfully 4 a REMOTE command completed unsuccessfully 3,5,6,7 combinations (addition) of the above conditions 1.6. Kermit-MS Commands A command keyword, such as SEND, RECEIVE, HELP, etc, may be abbreviated, so long as you have typed enough letters to distinguish it from other keywords that are valid in that position. For instance, you can type CLE for CLEAR and CLO for CLOSE. Several common commands also have special non-unique abbrevia- tions, like C for CONNECT, S for SEND, and R for RECEIVE. During interactive operation, you may edit the command you're currently typing using BACKSPACE to erase the character most recently typed, Ctrl-W to delete the most recent field, or Ctrl-U to delete the entire command. The editing characters may be used in any combination until the command is finally entered by typing RETURN (Carriage Return, Enter) or Ctrl-L. You may use the help ("?") and keyword completion (ESC) features freely while typing Kermit-MS commands. A question mark typed at almost any point in a com- mand produces a brief description, or "menu", of what is expected or possible at that point. ESC typed at any point, except 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 more characters. Kermit-MS recognizes only 7-bit ASCII characters when examining a Kermit com- mand line. The SET KEY and SHOW KEY commands can prompt for keyboard input and understand 8-bit characters but only at their interactive prompt. The SET KEY, INPUT, and OUTPUT commands accept "backslash number format" on the main Kermit command line. Thus, national characters which are full 8-bit codes can be ex- pressed on command lines in backslash number form (\ddd), provided the Kermit command itself can understand the form. Presently, INPUT, OUTPUT, ECHO, SET KEY, SET PROMPT, and DEFINE commands understand this notation. To enter characters in backslash number format, type a backslash ("\") followed by a number corresponding to the ASCII code for the character: \123 a decimal number (decimal is the default number base) \d249 a decimal number (also \D) \o177 an octal (base 8) number (also \O) \x0d a hexadecimal (base 16) number (also \X) Table 1-1 shows all of the 7-bit ASCII codes in decimal. Most Kermit commands understand backslash-ASCII codes, both imbedded within character strings, and alone, as when a single character or number is to be specified. Some Kermit-MS commands like GET, SHOW KEY, and 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 to get back to the main Kermit-MS> prompt. ------------------------------------------------------------------------------- Dec Name Ctrl Dec Char Dec Char Dec Char 0 NUL ^@ | 32 SP | 64 @ | 96 ` 1 SOH ^A | 33 ! | 65 A | 97 a 2 STX ^B | 34 " | 66 B | 98 b 3 ETX ^C | 35 # | 67 C | 99 c 4 EOT ^D | 36 $ | 68 D | 100 d 5 ENQ ^E | 37 % | 69 E | 101 e 6 ACK ^F | 38 & | 70 F | 102 f 7 BEL ^G beep | 39 ' | 71 G | 103 g 8 BS ^H backspace | 40 ( | 72 H | 104 h 9 HT ^I tab | 41 ) | 73 I | 105 i 10 LF ^J linefeed | 42 * | 74 J | 106 j 11 VT ^K | 43 + | 75 K | 107 k 12 FF ^L formfeed | 44 , | 76 L | 108 l 13 CR ^M return | 45 - | 77 M | 109 m 14 SO ^N shift out | 46 . | 78 N | 110 n 15 SI ^O shift in | 47 / | 79 O | 111 o 16 DLE ^P | 48 0 | 80 P | 112 p 17 DC1 ^Q XON | 49 1 | 81 Q | 113 q 18 DC2 ^R | 50 2 | 82 R | 114 r 19 DC3 ^S XOFF | 51 3 | 83 S | 115 s 20 DC4 ^T | 52 4 | 84 T | 116 t 21 NAK ^U | 53 5 | 85 U | 117 u 23 ETB ^W | 54 6 | 86 V | 118 v 22 SYN ^V | 55 7 | 87 W | 119 w 24 CAN ^X | 56 8 | 88 X | 120 x 25 EM ^Y | 57 9 | 89 Y | 121 y 26 SUB ^Z | 58 : | 90 Z | 122 z 27 ESC ^[ escape | 59 ; | 91 [ | 123 { 28 FS ^\ | 60 < | 92 \ | 124 | 29 GS ^] | 61 = | 93 ] | 125 } 30 RS ^^ | 62 > | 94 ^ | 126 ~ 31 US ^_ | 63 ? | 95 _ | 127 RUBOUT,DELETE Table 1-1: The US ASCII Character Set (ANSI X3.4-1977) ------------------------------------------------------------------------------- Equivalent to MS-DOS "?", but used in the first position of a filename only, so that "?" may be used to get help at the beginning of a filename field. RETURN Enters the command. On most keyboards, you may also use ENTER or Ctrl-M. Ctrl-L Clears the screen and enters the command. Liberal use of "?" allows you to feel your way through the commands and their fields. This feature is sometimes called "menu on demand" or "context sen- sitive help" -- unlike systems that force you to negotiate menus at every turn, menu-on-demand provides help only when it is needed. The notation used in command descriptions is as follows: Optional fields are in [square brackets], lists of alternatives are in {curly braces}, separated by commas. Parameters, such as numbers or filenames, are shown in italics (providing the printer is capable of printing italics), and in dialog examples user typein is underlined (on printers that can show it) to distinguish it from computer typeout. The following sections describe MS-Kermit's commands. Command descriptions may contain references to other commands that haven't been explained yet. You might find that this manual makes more sense on a second reading. 1.6.1. Program Management Commands "Program management" is a rubric for Kermit-MS commands like TAKE, EXIT, HELP, COMMENT, ECHO, and VERSION, that don't fall into any other category. HELP simply displays a short help message (the same one, in fact, that you would see if you typed a question mark in the same place). VERSION displays the MS-Kermit program version number, which you should know in case you are reporting bugs or seeking technical assistance. Other program management commands require a bit more explanation. The EXIT Command Syntax: EXIT or QUIT EXIT and QUIT are synonyms for each other. They cause MS-Kermit to return con- trol to DOS or whatever program invoked MS-Kermit. The specific actions taken are: - Close any open log or other files. - Close any open network connection. - Release all memory claimed by the program. - Disable interrupts for the currently selected communication device. - Terminate execution. The serial port RS-232 signals are left alone upon EXIT, so that modem connec- tions are not broken. Kermit-MS may be restarted with the connection intact. Use HANGUP to explicitly break a modem connection. The STAY Command Syntax: STAY The STAY command, if included among command line arguments, instructs MS-Kermit not to exit upon completion but rather to enter interactive mode, unless EXIT or QUIT was among the command arguments. STAY has no effect when entered in- teractively or from a TAKE file. The PUSH Command Syntax: PUSH PUSH is similar to EXIT, except it leaves MS-Kermit intact by invoking an MS-DOS command processor "under" Kermit-MS, either COMMAND.COM or whatever shell you have specified with COMSPEC (or SHELL, depending on the system) in your CONFIG.SYS file. You can return to Kermit-MS by typing the MS-DOS EXIT command, and you will find Kermit-MS as you left it, with all settings intact. The same function is invoked by the CONNECT escape-level command P. Example: Kermit-MS>push Push to DOS. Command v3.10 COMMAND.COM program herald. C>diskcopy a: b: Run a DOS program. DISKCOPY dialog here... C>dir b: More DOS commands... DOS session continues... C>exit When done, type DOS EXIT command. Kermit-MS> Back at Kermit. The TAKE Command Syntax: TAKE filespec The TAKE command gives you way a to collect MS-Kermit commands into a single file, so that you can execute many commands by typing a single (TAKE) command. TAKE instructs MS-Kermit to execute commands from the file that you specify. The current directory is searched for the file first, and then any directories listed in the PATH environment variable. The command file may include any valid Kermit-MS commands, including TAKE, but it cannot include characters to be sent to a remote host after a CONNECT command (use scripts for that, described below). Execution of a TAKE file may be cancelled by typing Control-C at the keyboard. Commands within TAKE files, unlike interactive commands, may include trailing comments, preceded by semicolons (if a real semicolon is needed in a command, express it as "\;" and it will not be mistaken for the start of a comment). set port 2 ; Select the modem port. set speed 1200 ; Set the baud rate for the modem. connect ; Conduct a terminal session. hangup ; Hang up the phone after escaping back. Note the HANGUP command after CONNECT. The HANGUP command is not executed un- til after you escape back from your CONNECT session. If this file were called MODEM.CMD, the following TAKE command would execute it: Kermit-MS>take modem.cmd This directs MS-Kermit to find the MODEM.CMD file, open it, execute the com- mands in it, close it, and return to the MS-Kermit> prompt when done. This process can take a while on floppy-disk based systems. Commands from the TAKE file will normally not be displayed on your screen during execution. If you want to see them as they are executing, you can SET TAKE-ECHO ON (for instance, at the beginning or end of your MSKERMIT.INI file). TAKE files may be nested to any reasonable level. A command file that was in- voked by another command file returns to its invoking command file, rather than to the MS-Kermit> prompt. There is currently no parameter substitution mechanism for TAKE files. Warnings: - An explicit query mark ("?") in a TAKE file will cause a help message to be displayed and the rest of the line will be read as another com- mand. - Since TAKE file processing discards all characters from a line begin- ning with the first semicolon, it is normally not possible to include semicolons as part of the commands themselves, e.g. get dska:foo.bar;6 To get around this restriction, you may precede such semicolons with a backslash: get dska:foo.bar\;6 The -F Command Syntax: -F filespec The "-f" command is effective only on the DOS command line. It instructs MS-Kermit to use the specified file as its initialization file, rather than MSKERMIT.INI. Unlike other command-line arguments, "-f" does not, of itself, cause MS-Kermit to exit upon completion. Example: C>kermit -f sunday.ini Kermit-MS> The -F command line option allows different MS-Kermit initialization files to coexist. You can create batch commands to invoke Kermit in different ways, for instance MONDAY.BAT might contain "kermit -f monday.ini", TUESDAY.BAT "kermit -f tuesday.ini", etc. The ECHO Command Syntax: ECHO [string] The ECHO command writes the string to the screen, without adding a carriage return or line feed. ECHO may be used to report progress during execution of a TAKE command file, or to issue prompts during the execution of a script. ECHO Part one completed...\13\10 The numbers at the end are "backslash codes" for ASCII control characters, in this case carriage return (\13) and linefeed (\10). The COMMENT Command Syntax: COMMENT text The COMMENT command lets you add comments to a TAKE command file. The word COMMENT (or any unique prefix thereof) must appear as the first word on the line. The DEFINE Command Syntax: DEFINE macro-name [command [, command [, ...]]] Command macros provide another way of collecting many commands into a single command. Kermit-MS command macros are constructed with the DEFINE command. Any Kermit-MS commands may be included. Example: define telenet set parity mark, set baud 1200, connect A macro can be undefined by typing an empty DEFINE command for it, like define telenet A macro definition may be no longer than 128 characters. Longer definitions can be accomplished by "chaining." Example: define setup set port 1, set speed 19200, set par even, do setup2 define setup2 set flo no, set handsh xon, set local on, do setup3 define setup3 set timer on, set terminal color 1 31 45, do setup4 define setup4 set warning on, set incomplete keep, connect DO SETUP will invoke all of these commands. The commas above stand for the carriage returns needed by individual commands. Commas must be used to separate commands in macro definitions; carriage returns (\13) cannot be used. When control or other special characters are needed in a macro they may be ex- pressed in backslash number form, \nnn. The SHOW MACROS command displays the value of all currently defined macros, and tells how much space is left for further definitions. The DO Command Syntax: DO macro-name A Kermit-MS command macro is invoked using the DO command. For instance, Kermit-MS comes with a predefined macro to allow convenient setup for IBM mainframe line-mode communications; to invoke it, you would type DO IBM. The IBM macro is defined as "set timer on, set local-echo on, set parity mark, handshake xon, set flow none". You can use the DEFINE command to redefine this macro or remove the definition altogether. There is no automatic way to undo the effect of a macro. If you need to ac- complish this effect, you should define another macro for that purpose. For instance, to undo the effect of "do ibm" so that you could connect to, say, a DEC VAX, you could: def vax set par none,set hand none,set flo x,set tim off,set loc off Then you can "do ibm" whenever you want to use the IBM system, and "do vax" whenever you want to use the VAX. If you wish to view the macro expansion whenever you issue a DO command, you can SET TAKE-ECHO ON. Local File Management Commands These commands are executed on your local PC, and generally invoke DOS ser- vices. This allows you to perform common DOS functions without leaving Kermit. All file specifications may include device and/or directory fields. The local file management commands are: CWD path - Like DOS CD, or you can use a disk letter. DELETE filespec DIRECTORY [filespec] SPACE - Runs CHKDSK. RUN command - Passes the command line to COMMAND.COM for execution. TYPE filespec - Displays the specified local file on the screen. 1.6.2. COMMANDS FOR TERMINAL CONNECTION The CONNECT command connects your PC as a terminal to the remote system so that you may conduct a session there, and the HANGUP command may be used to discon- nect your modem (if you have one) from the remote system. There is presently no DIAL command; modems may be dialed "manually" during CONNECT or by using scripts. Scripts are described in detail in subsequent sections. For completeness, the descriptions below contain copious reference to the SET commands, which let you modify all sorts of terminal and communication parameters (the SET commands are described in a later section). MS-Kermit is initially set up with the following parameters, so that you only need to issue SET commands for those that need to be changed: PORT 1 (in most cases, e.g. COM1 on the IBM PC family) TERMINAL VT102(*) emulation (on the IBM PC family and DEC Rainbow) SPEED Whatever the serial card is currently set to. PARITY None FLOW-CONTROL XON/XOFF HANDSHAKE None LOCAL-ECHO Off DISPLAY 7-bit characters INPUT TRANSLATION Off ESCAPE Control-Rightbracket (*) The VT102 terminal is compatible with the VT100, but includes a few ad- ditional functions. The CONNECT Command Syntax: CONNECT -or- C The CONNECT command establishes an interactive terminal connection to the remote system using the currently selected communications port (SET PORT COM1 or COM2) with all settings currently in effect for that port, emulating the currently selected type of terminal. During CONNECT, the characters you type are sent out the communication port, and the characters that arrive at the port are displayed on the screen or in- terpreted by the selected terminal emulator. If you SET LOCAL-ECHO ON, MS-Kermit will also display the characters you type on the screen. Before you issue the CONNECT command, be sure to set the correct communication speed (SET SPEED) and any other necessary communication parameters (e.g. SET PARITY, SET LOCAL-ECHO). If you have SET DEBUG ON, then (on certain systems, particularly the IBM PC), terminal emulation will be disabled and received con- trol characters will be displayed in special notation. By default, 7-bit ASCII characters are displayed on the screen. If you SET DISPLAY 8, then 8-bit characters will be used (useful for "national" character sets). Character translation will be done according to any SET TRANSLATION IN- PUT and SET KEY commands you have issued. In addition, characters that are sent to the screen will also be recorded in a disk file or on a printer if you have issued a LOG SESSION command. To get back to the PC, type the escape character followed by the letter C (for "Close connection"). On most MS-DOS systems the escape character is Ctrl-] (Control-Rightbracket). That means, hold down the Ctrl key, press "]", and then type the letter C. Kermit-MS>connect Connect to remote system. Conduct terminal session here... ^]c Escape back to PC. Kermit-MS> Prompt reappears. This is called "escaping back". You can use the SET ESCAPE command to change the escape character to something besides "^]", or you can assign the escaping- back operation to a single key or key combination with SET KEY (on the IBM PC the default for this is Alt-X). You can include the CONNECT command in a TAKE command file, but not "bare" text to be sent to the remote system during CONNECT (use scripts for that, see Sec- tion 1.7). When a TAKE file includes a CONNECT command, no further commands will be executed from the file until after you escape back. When you CONNECT, the program attempts to raise the DTR and RTS RS-232 signals, and it takes no specific action to lower them unless you explicitly issue the HANGUP command; thus you can EXIT from Kermit-MS and restart it without drop- ping a dialup connection. While CONNECTed, you can communicate directly with an autodialer or "smart modem" to control the communications line, hang it up, and the like, for instance, by typing AT commands to a Hayes-like modem. Kermit-MS>set speed 2400 Kermit-MS>connect AT Now you're talking to the modem. OK ATDT8765432 RINGING CONNECT 2400 Welcome to ... Now you're talking to the host computer. Please login: The HANGUP Command On serial port connections, the HANGUP command attempts to momentarily lower the modem signals DTR and RTS. It may be used to hang up the phone when dialed up through a modem, or to get the attention of port contention units or ter- minal concentrators that operate in this manner. On direct connections, it will probably have no effect. On local area network connections, the network session is fully terminated. TERMINAL EMULATION The IBM PC version of Kermit-MS emulates the DEC VT102 terminal by default, and may also be instructed to emulate the DEC VT52, the Heath/Zenith-19, the Tektronix 4010 graphics terminal, or no terminal at all, selectable with the SET TERMINAL command. Emulation of each of these terminals is nearly complete. VT102 emulation lacks only smooth scroll and 132 column mode (some EGA boards allow it). Double-height, double-width characters are supported, but simulated using ordinary characters. Escape-Level Commands The escape character, normally Control-], is used to regain the attention of Kermit-MS during CONNECT (you can change the escape character using SET ESCAPE). 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. This command is executed immediately; it may not be edited, and the program does not wait for a carriage return to confirm it. Table 1-2 shows CONNECT escape-level commands available in Kermit-MS. ------------------------------------------------------------------------------- ? Help -- Lists the available single-character commands. 0 (the digit zero) Transmit a NUL (ASCII 0). B Transmit a BREAK signal. L Transmit a Long BREAK signal (on some systems). C Close the connection and return to Kermit-MS prompt level. H Hangup the phone by lowering DTR and CTS momentarily. F File the current screen in the screen dump file. M Toggle the mode line, i.e. turn it off if it is on or vice versa. P Push to DOS; get back to CONNECT by typing EXIT. Q Temporarily quit logging the remote session. R Resume logging the remote session. S Show the status of the connection. ^] (or whatever you have set the escape character to be) Typing the escape character twice sends one copy of it to the connected host. Table 1-2: Kermit Single-Character CONNECT Escape Commands ------------------------------------------------------------------------------- The Mode Line When you first issue the CONNECT command, a message (on some systems, an in- verse video "mode line") will display the most important facts about the con- nection you've just established, so that you can quickly diagnose any problems. Here's what the IBM PC mode line looks like: Esc-chr:^] help:^]? port:1 speed:9600 parity:odd echo:rem VT102 .... PRN This shows that the escape character is Ctrl-Rightbracket, that you would type Ctrl-rightbracket followed by question mark ("^]?") to get help during CONNECT, that you are connected on port 1 at 9600 baud with odd parity and remote echo, and that a VT102 terminal is being emulated. The four dots represent the VT102s LEDs (they turn into the digits 1,2,3,4 when "lit") and PRN will show up if the printer is activated (e.g. by Ctrl-PrintScreen). Screen Rollback On the IBM PC and some other systems, Kermit-MS provides several pages of screen memory which let you recall earlier terminal screens. These may be scrolled up and down using keys as shown in Table 1-6. For instance, the IBM PC uses PgUp (previous screen), PgDn (next screen), Ctrl-PgUp and Ctrl-PgDn (one line at a time). Only lines that scroll off the top of the screen are saved. When an application clears the screen, that screen is not saved. These functions and others may be assigned to different keys with the SET KEY command. Screen Dump The screen dump feature writes the contents of the current screen to a file (KERMIT.SCN unless another file was selected by the SET DUMP command) when the CONNECT escape-level command F is typed. The screen dump file is appended to on each successive screen dump, with each screen separated by a formfeed (Ctrl-L). This feature may be used in conjunction with screen rollback -- a handy way to recapture screenfuls of laboriously typed-in text after a remote host has crashed without saving your work. The corresponding action verb is "dump". Screen dump does not function when in Tektronix graphics mode; instead one of many graphics screen capture programs may be used independently commonly via the DOS Shift PrtSc key combination or by LOGging the incoming byte stream. Printer Control During terminal emulation, 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 by DOS; holding down Ctrl while depressing Print Screen will alternately start and stop the spooling of incoming characters to the printer. On the IBM PC, the mode line will show PRN when the printer is activated in this manner. ^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 simu- lated with the Kermit-MS LOG PRN and CLOSE commands. VT102 (ANSI) style host-controlled transparent printing is also supported on the IBM PC. See sec- tion 1.16.6 for technical information about MS-Kermit's printer control. Graphics MS-Kermit on the IBM PC, compatibles, and several other systems, is capable of emulating a Tektronix 4010 graphics terminal, for use with host-based software that can generate Tektronix control codes. When you enter Tektronix emulation, your cursor will disappear. Don't be alarmed, this is how Tektronix terminals behave. The Tektronix emulator implements a mixture of Tek 4010 and 4014 features to draw characters, lines, and dots in graphics mode. These Tektronix terminals have a graphics display 780 dots high by 1024 dots wide. They use storage tube technology whereby a dot stays illuminated until the full screen is erased. They also lack cursor keys. Kermit's Tek emulator maps the 1024 by 780 dot display to the PC's current screen dimensions, say 640 across by 200 or 350 dots high, and retains limited use of the cursor keys. It automatically senses the active display adapter (EGA, CGA, Hercules, Mono, and AT&T/Olivetti 640x400) and retains screen coloring (EGA) and the current graphics image (EGA and Hercules) if the adapter has sufficient memory. Pure monochrome systems, of course, lack a graphics capability; in this case Kermit approximates the graphic image by writing dots as plus signs. Tektronix graphics mode is entered two different ways, automatically and volun- tarily: 1. Automatically (which you can prevent via the Kermit command DISABLE TEK). While emulating a VT102, VT52, or Heath-19, reception of the byte pair ESCAPE Control-L causes the PC to change to graphics mode, clear the screen, and obey new input as Tektronix commands. A second automatic entry is reception of the escape sequence "ESC [ ? 3 8 h" which does the same as above except the screen is not cleared. Automatic mode is exited by either reception of Control-X or "ESC [ ? 3 8 l" (lower case L), or by toggling the ter- minal type (ALT minus, Kermit verb\KTermtype) to VT102, or something other than TEK. (These "ESC [ ? 3 8 h/l" sequences derive from the DEC VT340 terminal.) 2. Voluntary mode is when terminal type TEK4010 is selected by the Ker- mit command SET TERMINAL TEK4010 or by toggling to it as above. It is exited by SET TERMINAL another-kind or by toggling to another kind. ENABLE or DISABLE TEK and the exit-Tek-mode escape sequences are not applicable to voluntary mode. The Tek emulator can display text characters from a built-in 8-by-8 dot font for characters Space through DELete (no control codes nor special characters). A backspace operation erases the character under the final cursor location (an extension beyond a real Tektronix 4010). Tabs are converted to single spaces. Only the low 7 bits of the character are used. While in Tek mode the emulator behaves as a simple TTY device for ordinary text and as a line or dot drawing Tektronix device for commands listed in Table 1-8. The screen resolution is governed by the kind of active display adapter and monitor in the PC (Table 1-3). Kermit senses this automatically when graphics mode is entered. Graphics are saved on page 1 of screen memory. Coloring is determined by the current terminal status, either the default screen or that overridden by the command SET TERMINAL COLOR. ------------------------------------------------------------------------------- Display Adapter Display Mode Screen Resolution and Coloring EGA w/256KB Hi res color 16 dec 640x350, graphics saved, 16 colors. Med res color 14 640x200, graphics saved, 8 colors. Monochrome 15 640x350, graphics saved, b/w. EGA w/64KB Hi res color 16 640x350, graphics not saved, 4 colors of red, white, blue, black. Med res color 14 640x200, graphics saved, 8 colors. Monochrome 15 640x350, graphics not saved. CGA Color 6 640x200, graphics not saved, b/w. Hercules Monochrome none 720x348, graphics saved if memory. Monochrome Monochrome 7 80 by 25 text, graphics not saved. AT&T/Olivetti any 72 640x400, grahics not saved, b/w. Table 1-3: Adapters Supported by IBM PC MS-Kermit for Tektronix Emulation ------------------------------------------------------------------------------- 1.6.3. COMMANDS FOR FILE TRANSFER MS-Kermit's SEND, GET, and RECEIVE invoke the Kermit file transfer protocol for error-checked transmission of files between MS-Kermit and another Kermit program on the other end of the connection. There are also commands for "raw" transfer of files (no error checking) with systems that don't have Kermit programs: LOG SESSION (for capturing text files on your PC) and TRANSMIT (for uploading text files to the remote system). During file transfer, MS-Kermit normally displays its progress on the screen as shown in Figure 1-1. The items in the right-hand column are updated more or less at random. In the current version, the percent done is filled in only when sending files, not when receiving. Several other display options are also available; see SET DISPLAY. ------------------------------------------------------------------------------- Kermit-MS: V2.30 8 Jan 88 File name: FOT. KBytes transferred: 7 Percent transferred: 52% Sending: In progress Number of packets: 74 Packet length: 93 Number of retries: 2 Last error: None Last warning: None Figure 1-1: MS-Kermit File Transfer Display Screen ------------------------------------------------------------------------------- Although MS-Kermit makes no distinction between text and binary files, most other Kermit programs do. Therefore, before you attempt to transfer binary files with another type of system (say, a VAX, or an IBM mainframe), be sure to give the appropriate command -- usually something like SET FILE TYPE BINARY -- to the Kermit on the remote end. 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. S is a special non-unique abbreviation for SEND. filespec1 may contain the wildcard characters "*" to match zero or more characters within a field, and/or "#" (first position) or "?" (elsewhere) to match any single character. 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 filespec2 begins with the first nonblank character after filespec1 and ends with the carriage return; thus it may contain blanks or other unusual charac- ters that may be appropriate on the target machine. The alphabetic case of text in filespec2 is preserved in transmission, so if case matters on the tar- get system, be sure to type filespec2 appropriately. If the SEND command is specified by itself on the command line, then you will be prompted separately for the name of the file to send, and the name to send it under: Kermit-MS>send Local Source File: c:\chris\xcom1.txt Remote Destination File: com1.txt 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. (^Z or even ^E is preferable.) ^E Like ^C, but send an Error packet to the remote Kermit in an attempt 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, Control-Z, and Control-E 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, possibly retransmit- ting its last packet over and over, up to its retry limit. You should only have to use Control-C in dire emergencies (the remote Kermit is stuck, the remote system crashed, etc), or at those times when you realize that you have given a file transfer command to Kermit-MS without first having told the remote Kermit about it. The RECEIVE Command Syntax: RECEIVE [filespec] The RECEIVE command tells Kermit-MS to receive a file or file group from the other system. The file is stored under the name it was transmitted with, ex- cept that any illegal characters are translated to X's. Kermit-MS passively 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 com- mand to the remote Kermit and escaped back to Kermit-MS before issuing the RECEIVE command. R is a special non-unique abbreviation for RECEIVE. If the optional filespec is provided, incoming files will be stored under that name. If the filespec is really just a path then files are stored where the path indicates. If it is an actual filename the first incoming file is renamed and any additional files either overwrite the first (if FILE WARNING is OFF) or are renamed slightly from the filespec (digits are added to the end of the main filename part before the dot and extension) if FILE WARNING is ON (the default). 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. In this case, ^E should always do what ^Z is supposed to do. Caution: If an incoming file's name (the part before the dot) corresponds 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. 1.6.5. Commands for Raw Uploading and Downloading MS-Kermit can be used to send files to, or capture files from, remote systems that do not have Kermit programs available. No error checking or correction is done, so the results can very likely contain corrupted characters, spurts of noise, gaps, or extraneous system messages or prompts. The command for upload- ing is TRANSMIT, and for downloading LOG SESSION. To minimize loss of data during these operations, be sure to SET the FLOW-CONTROL and HANDSHAKE parameters to match the characteristics of the sys- tem on the other end. The TRANSMIT Command Syntax: TRANSMIT filespec [prompt-character] The TRANSMIT command provides a basic raw upload (export) facility to send straight ASCII text files to the host without packets, error checking, or retransmissions, but using all the currently selected communication parameters for flow control, parity, etc. Information is read from the disk file a line at a time, sent out the serial port, and the command waits for a single charac- ter prompt (normally linefeed) from the host before sending the next file line. A disk file line ends with carriage-return-linefeed (CRLF), but only the car- riage return is sent, just as you only type carriage return at the end of a line, not CR and LF. Here's an example for VAX/VMS: Kermit-MS>set flow xon/xoff Set flow control to match VAX/VMS. Kermit-MS>connect Connect to VAX. $ edt foo.txt Start the EDT editor. *i Put it into "insert" mode. ^]c Escape back to Kermit-MS. Kermit-MS>transmit foo.txt Upload the file a line at a time. ... The lines are displayed on your screen. Kermit-MS>connect When done, connect back to the VAX. ^Z Type Ctrl-Z to exit EDT insert mode. *exit Exit from EDT to save the file. $ The LOG SESSION Command Syntax: LOG SESSION [filespec] The LOG SESSION command lets you copy the characters that appear on your screen during CONNECT into the specified file on the PC. You can use this command to download files by displaying (usually with a command like TYPE) the file on the remote system while logging is in effect. Example: Kermit-MS>set flow xon/xoff Set flow control to match VAX/VMS. Kermit-MS>connect Connect to the VAX. $ type foo.bar Give this command, but don't type CR yet. ^]c Escape back. Kermit-MS>log sess foo.bar Start logging. Kermit-MS>connect Connect back. Now type the carriage return. This is the file FOO.BAR. The file is displayed on your screen Blah blah ... and captured into PC file FOO.BAR. $ The prompt is captured too. ^]c When done, escape back Kermit-MS>close and close the log file. The PC file FOO.BAR now contains a (possibly mutilated) copy of the remote computer's FOO.BAR file. It probably has the remote system's prompt at the end, which you can edit out. 1.6.6. Kermit Server Commands Kermit-MS can act as a Kermit server, and can also interact with other Kermit servers. Normally, the remote Kermit is put into server mode. Then the local Kermit becomes a "client", and may issue repeated commands to the server with- out having to connect and escape back repeatedly. Servers can not only trans- fer files, but can also provide a variety of file management functions. The SERVER command puts MS-Kermit into server mode, and the DISABLE and ENABLE com- mands modify the behavior of the server. Kermit servers respond only to information sent as Kermit protocol packets and not to ordinary CONNECT-mode commands. When MS-Kermit is the client, it uses the SEND command (described above) to send files to a server, the GET command (not RECEIVE) to get files from a server, the REMOTE commands to invoke the file management functions of the server, and the BYE, FINISH, or LOGOUT com- mands to shut down the server. The MS-Kermit server can also be returned to interactive mode by typing Ctrl-C or Ctrl-Break on the PC's console keyboard. The SERVER Command Kermit-MS is capable of acting as a full-fledged Kermit server for users coming in through one of the communication ports or a local area network. To put Kermit-MS into server mode, first issue any desired SET commands to select and configure the desired port, then DISABLE any undesired functions, and then type the SERVER command. Kermit-MS will await all further instructions from the client Kermit on the other end of the connection, which may be hardwired, or connected through a network or autoanswer modem. In the following example, a Kermit server is set up for dialing in: Kermit-MS>set port 1 Kermit-MS>set baud 1200 Kermit-MS>connect ATA OK ^]c Kermit-MS>set timer on Kermit-MS>set warning on Kermit-MS>disable all Kermit-MS>server Before putting Kermit in server mode in this case, it was necessary to connect to the modem (in this example, a Hayes) and put it into autoanswer mode by typing the ATA command. MS-Kermit 2.30 server mode supports the following requests: SEND REMOTE CWD REMOTE SEND GET REMOTE DELETE REMOTE SPACE FINISH REMOTE DIRECTORY REMOTE TYPE BYE REMOTE HELP REMOTE WHO LOGO REMOTE HOST REMOTE CWD can be used to change both directories and devices. The REMOTE SEND command accepts a one line message on the command line which will be displayed on the operator's console. An MS-Kermit Server can DISABLE recognition of selected REMOTE commands to help reduce accidents. The DISABLE and ENABLE Commands For security purposes, it may be desirable to leave your PC in Kermit server mode so that it can be dialed in to, but with certain functions unavailable to those who dial in. The DISABLE and ENABLE commands provide this control. The DISABLE and ENABLE commands affect the following functions, with the effect of DISABLEs noted: CWD Changing of directories, disabled entirely. DEL Deletion of files confined to current directory. DIR Production of directory listings confined to current directory. FIN Shutting down the server (applies also to BYE) disabled entirely. GET Getting files from the server confined to current directory. HOST Execution of all REMOTE HOST (DOS) commands disabled entirely. SEND Forces files sent to server into current directory. SPACE Asking the server for a disk space report, disabled. TYPE REMOTE TYPE files confined to current directory. ALL All of the above. TEK Automatic invocation of Tektronix graphics mode by host commands. This function is not related to server mode, and is not included in the ALL term. 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 active 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 (or, in the case of LAN operation, a Kermit server must be running somewhere on the network). If the remote Kermit does not have a SERVER command, then you should use SEND and RECEIVE as described above. You may use the GET command in a special way to specify a different name for storing the incoming file. 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: a:xcom1.txt The local file name may contain a device field, and/or a directory specifica- tion. Device and directory specifications in the local destination file name work the same way as in the RECEIVE command. Once the file transfer begins, the GET command behaves exactly like the RECEIVE command. Warning: If the remote filespec is to contain a semicolon, and the GET command is being issued from a TAKE command file, you must prefix the semicolon with a backslash. Otherwise, all characters beginning with the semicolon will be ig- nored: get me.home\;0 1.6.7. Commands for Controlling Remote Kermit Servers The BYE, FINISH, and LOGOUT commands 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 locally from Kermit-MS to DOS. FINISH Like BYE, FINISH shuts down the remote server. However, FINISH does notlog out the server's job. LOGOUT The LOGOUT command is identical to the BYE command, except you will remain at Kermit-MS prompt level afterwards. The REMOTE Commands The REMOTE keyword is a prefix for a number of commands. It indicates that the command is to be performed by a remote Kermit server. Not all Kermit servers are capable of executing all of 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, if any, to your screen. Here are the REMOTE commands that Kermit-MS may issue: REMOTE CWD [directory] Ask the server to Change your Working Directory on the remote host, that is, the default source and destination area for file transfer and management. You will be prompted for a password, which will not echo 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 and you will not be prompted for a password. REMOTE DELETE filespec Ask the server to delete the specified file or files on the remote sys- tem. In response, the server may display a list of the files that were or were not successfully deleted. REMOTE DIRECTORY [filespec] Ask the server to display a directory listing of the specified files. If no files are specified, then the list should include all files in the current working directory. REMOTE HELP Ask the server to list the services it provides. REMOTE HOST [command] Ask the server to send the command to the remote system's command processor for execution. REMOTE SPACE [directory] Ask the server to provide a brief summary of disk usage in the specified area on the remote host or, if none specified, the default or current area. REMOTE TYPE filespec Ask the server to display the contents of the specified remote file or files on your screen. (and some others...) 1.6.8. The LOG and CLOSE Commands Syntax: LOG {PACKET, SESSION} [filespec] CLOSE LOG SESSION specifies that your terminal session during CONNECT will be recorded in the indicated file (whose name defaults to KERMIT.LOG in the cur- rent directory), with any input character translations applied according to SET TRANSLATION INPUT. The filespec may include a device specification and/or directory path. 1.6.9. The SET Command Syntax: SET parameter value -or- SET parameter parameter value The SET command establishes or modifies parameters for file transfer or ter- minal connection. You can examine their values with the STATUS command. The SET commands are now described in detail, in alphabetical order. SET BAUD Syntax: SET BAUD number Set the speed (in bits per second, commonly called baud) of the currently selected terminal communications port (COM1 by default) to 300, 1200, 1800, 2400, 4800, 9600, or other common speed, and on the IBM PC family, higher speeds including 19200, 38400, 57600, and 115200. Both connected systems, as well as any intervening communication equipment, must be able to support the specified baud rate, and both systems should be set to the same baud rate. SET BLOCK-CHECK-TYPE Syntax: SET BLOCK-CHECK-TYPE {1, 2, 3} Selects the error detection method: a 1-character 6-bit checksum (the normal case), a 2-character 12-bit checksum, or a 3-character 16-bit cyclic redundancy check (CRC). If the other Kermit program is not capable of type 2 or 3 check- ing methods, automatic fallback to type 1 will occur. The more secure type 2 and 3 block checks take essentially no more execution time than the simple 1 character checksum. SET BLOCK 3 is a stronger check than SET BLOCK 2. SET BLOCK 2 or 3 is recommended for use with long packets (see below), noisy com- munication lines, binary (8-bit data) files, and text files containing critical data (budgets, grades, etc). SET DEBUG Syntax: SET DEBUG {PACKET, SESSION, ON, OFF} With DEBUG PACKET, Kermit will display packet traffic on your screen during file transfer. With the normal file transfer display, regular-length packets sent and received are displayed in fixed-size slots. The display of extended-length packets, however (see SET RECEIVE PACKET-LENGTH), tends to overlap. If this bothers you, then also SET DISPLAY SERIAL, or LOG the packets rather than displaying them. With DEBUG SESSION, during terminal emulation (on the IBM PC, Rainbow, and a few others), control characters are displayed in uparrow ("^") notation and characters with the 8th bit set are preceded by the tilde ("~") sign, and your session log (if any) will record 8-bit bytes, rather than 7-bit ASCII, regard- less of SET DISPLAY or SET PARITY. Character translation (SET TRANSLATION INPUT) is not done during session debugging. The effect of SET DEBUG SESSION during terminal connection can be disconcerting, but it gives you a convenient line monitor equivalent to a specialized device that costs several thousand dollars, and it can prove very handy for tracking down data communication problems. SET DEBUG ON turns on both SESSION and PACKET debugging, and SET DEBUG OFF turns them both off. SET DEFAULT-DISK Syntax: SET DEFAULT-DISK x: Specify the default disk drive to use for file transfer, directory listings, and so forth. Equivalent to typing the DOS command for changing disks (A:, B:, etc). Affects Kermit and all inferior processes, but when you exit from Ker- mit, you will still have the same default disk as when you entered. SET DESTINATION Syntax: SET DESTINATION {DISK, PRINTER, SCREEN} SET DESTINATION PRINTER will cause incoming files to be sent directly to the printer; SCREEN will send output normally destined for the disk to the screen. The normal destination is DISK. SET DESTINATION affects only files transferred with SEND, GET, or RECEIVE; it cannot be used to reroute the output from REMOTE server commands. SET DISPLAY Syntax: SET DISPLAY {QUIET, REGULAR, SERIAL, 7-BIT, 8-BIT} During file transfer, MS-DOS Kermit's regular display is a formatted screen whose fields are randomly updated with file names, packet numbers, error counts, percent done, error messages, and so forth. 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 command SET REMOTE ON (which, currently at least, is equivalent to SET DISPLAY QUIET); this sup- presses the file transfer display screen, so that the display won't interfere with the file transfer itself. You can also use this command to suppress the display in local mode, in case you are using a system that allows you to do other work while file transfer proceeds in the background. If you have your PC connected to a speaking device (a common practice for visually impaired people), or you are logging the display screen to a printer (using DOS ^P or kermit > prn), the random nature of the regular display will make the results of little use. SET DISPLAY SERIAL is provided for this pur- pose; it causes the program to report progress "serially" on the screen. In serial mode, error messages are preceeded with the word "Error" and repeat mes- sages with the word "Retry". Packets are numbered as dots with every tenth be- ing a plus sign. The packet display is automatically broken across lines at every 70th packet. The serial display makes much more sense when spoken than does the regular display. The serial display does not show the percent and kilobytes transferred. It is the default display style for generic MS-DOS Kermit; REGULAR is the default for all others. The last two parameters, 7-BIT and 8-BIT, control the size of characters sent to the screen during terminal emulation. 7-BIT is the default and includes all ASCII characters. 8-BIT is useful with national and line drawing characters. SET END-OF-LINE Syntax: SET END-OF-LINE number If the remote system needs packets to be terminated by anything other than car- riage return, specify the decimal value, 0-31, of the desired ASCII character. Equivalent to SET SEND END-OF-LINE (SET END-OF-LINE is kept only for historical reasons, and the parameter really should be called END-OF-PACKET anyway.) SET EOF Syntax: SET EOF {CTRL-Z, NOCTRL-Z} Controls how the end of file is handled. CTRL-Z specifies a Control-Z charac- ter should be appended 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 the local file, and do not send it or any subsequent characters. NOCTRL-Z is the default; incoming files are stored, and MS-DOS files are sent, exactly as is, in their entirety. SET ESCAPE Syntax: SET ESCAPE character Specify the control character you want to use to "escape" from remote connec- tions back to Kermit-MS. On most systems the default is "^]" (Control- Rightbracket), which was chosen because it is a character you would otherwise rarely type. The character is entered literally after SET ESCAPE or in backslash number form (\29), and should be chosen from the ASCII control range. It is not possible to use non-ASCII characters (like function keys) for this purpose (but see SET KEY for a way around this restriction). SET FLOW-CONTROL Syntax: SET FLOW-CONTROL {XON/XOFF, NONE} Specify the full duplex flow control to be done on the currently selected port. The options are XON/XOFF and NONE. The specified type of flow control will be done during both terminal emulation and file transfer. By default, XON/XOFF flow control is selected. XON/XOFF should not be used on half-duplex (local echo) connections, or with other systems that do not support it. If XON/XOFF is used, HANDSHAKE should be set to NONE. SET HANDSHAKE Syntax: SET HANDSHAKE {CODE number, BELL, CR, LF, NONE, XOFF, XON} Specify any half-duplex line turnaround handshake character to be used during file transfer on the currently selected port. The CODE number form allows any ASCII character to be specified by its decimal ASCII code. Handshake is NONE by default; if set to other than NONE, then FLOW-CONTROL should be set to NONE. In operation the handshake character is sought at the end of each received packet, following the normal END-OF-LINE character, but is not sent for out- going packets. SET INCOMPLETE Syntax: SET INCOMPLETE {DISCARD, KEEP} Specifies what to do with files that arrive incompletely: discard them or keep them. They are normally discarded. SET INPUT Syntax: SET INPUT {CASE, DEFAULT-TIMEOUT, ECHO, TIMEOUT-ACTION} SET INPUT controls the behavior of the script INPUT command (see the section on scripts for more information): SET INPUT CASE {IGNORE, OBSERVE} Says whether or not to distinguish upper and lower case letters when doing a matchup in the INPUT command. OBSERVE causes upper and lower case let- ters to be distinguished. The default is to IGNORE case distinctions. SET INPUT DEFAULT-TIMEOUT seconds Changes the waiting time from one second to this new value. SET INPUT ECHO {ON, OFF} Show on the screen characters read from the serial port during the script operation, or not. Default is ON, show them. SET INPUT TIMEOUT-ACTION {PROCEED, QUIT} Determines whether or not the current TAKE command file is to be continued or exited if a timeout occurs. PROCEED is the default and means that timeouts are ignored. QUIT causes the current script file to be exited and control passed to either the next higher level script file (if there is one) or to Kermit's main prompt. SET KEY Syntax: SET KEY key-specifier [key-definition] Also: SET KEY {ON, OFF, CLEAR} The SET KEY command is one of the most useful -- and confusing -- features of MS-Kermit. A key can be defined to: - send a single character other than what it would normally send, - send a string of multiple characters, - invoke a CONNECT-mode Kermit action verb, - send itself again. SET KEY specifies that when the designated key is struck during terminal emula- tion, the specified character or string is sent or the specified Kermit action verb is performed. Key definitions operate only during CONNECT, not at Kermit-MS> or DOS command level. The key-specifier is the identification of the key expressed in system-depend- ent terms. This can be a letter, such as Q for the key which emits an upper case Q, or the numeric ASCII value of the letter in backslash notation (e.g. "\81"), or else the numerical "scan code" observed by the system when the key is pressed (e.g. "\3856" for Ctrl-Alt-Q on an IBM PC). Material printed on keycaps is not necessarily a guide to what the key-specifier should be. When the word CLEAR is used in place of a key-specifier, all key definitions are cleared and then any built-in definitions are restored. A string definition is one or more characters, including 8-bit values expressed in backslash form, such as SET KEY \315 top \13 list\13 IBM F1 key sends "top list" SET KEY S L S key sends upper case L SET KEY T \27[m T key sends three bytes ESC [ m The string begins with the first non-spacing character following the key iden- tification and continues until the end of line, exclusive of any trailing spaces. If a semicolon comment is used and the definition is given in a TAKE file, the line ends at the last non-spacing character before the semicolon. Curly braces, {...<}>, can be use to delimit the string in case you want the definition to include trailing spaces. All text after the closing bracket is ignored. SET KEY \315 {login } this extra text is ignored If you enter SET KEY by itself, with no key specifier, the command will prompt you to press the selected key and again for the definition string. Certain characters, like ESC and CR, may not be entered literally into the string, but can be included by inserting escape codes of the form \nnn, a backslash fol- lowed by a 1- to 4-digit number corresponding to the ASCII value of the desired character. Where an ASCII digit follows directly after a backslash number, confusion can be avoided by placing curly braces {} around the backslashed num- ber; thus, \{27}5 represents the two ASCII characters ESC 5. A more exact definition of SET KEY follows these construction rules: SET KEY [] where is: - a single ordinary printable ASCII character, or - the numerical equivalent of an ASCII character (ESC is \27), or - a scan code written as a backslashed number (e.g. \3856 for Ctrl-Alt-Q), or - keyword CLEAR which removes all current key definitions and then restores any built-in definitions. - ? (a question mark), which displays a help message. Scan codes, non-printing ASCII characters, 8-bit characters, and other binary codes are written in backslash form (see Table 1-1 for ASCII codes): \123 a decimal number (decimal is the default number base) \d789 a decimal number (also \D) \o177 an octal number (also \O) \x0d a hexadecimal number (also \X) \{b###} braces around material following the slash, where the numerical base letter b is d, o, x, or absent. is one or more spaces and or tabs. is: missing altogether which "undefines" a key. \number (a number in backslash notation between 0 and 255 decimal) - assigns a character with the corresponding 8-bit value. \Kverb for a Kermit action verb; upper or lower case K is OK. \{Kverb} Same. Verb is the name of an action verb. text a string with allowed embedded whitespace and embedded bi- nary chars as above. This kind of string may not commence with sequences \K or \{K. The string begins with the first non-whitespace character and ends at the end of the line (exclusive of trailing spaces and comments). {text} string confined to material within but excluding the braces. Note, where the number of opening braces exceeds the number of closing braces the end of line terminates the string: {ab{}{{c}d ==> ab{}{{c}d but {ab}{{c}d ==> ab ? Displays help message and lists all action verbs. Control-C Quits the Set Key command without making changes. Curly braces can be used to separate backslash numbers from regular ASCII text, such as when we want to send the two bytes ESC 8 (ESC is decimal 27): SET KEY T \{27}8 SET KEY L {words \{27}8 more words} trailing junk to be ignored If a string begins with a left curly brace then Kermit counts them and ends the string on the matching right curly brace (or end of line); the SET KEY L example above relies on brace matching to omit the trailing comment. The outer curly brace delimiters are not sent but the inner ones are; for example: SET KEY U {a {b}\{27}8} sends the 7 bytes "a {b}ESC8" SET KEY U a{ {b}\{27}8} sends the 9 bytes "a{ {b}ESC8}" SET KEY U a{ {b}\{{27}}8} sends the 15 bytes "a{ {b}\{{27}}8}" A definition is removed, that is a key is defined as itself, by giving an empty definition: SET KEY q q key sends q again SET KEY \331 IBM left arrow key is undefined. The keyboard can be restored to its startup state, that is all redefinitions removed and all built-in defitions restored, by using the keyword CLEAR in place of the key identification: SET KEY CLEAR Undefined keys which do not send ASCII characters are trapped by the keyboard translator and are rejected; a beep results from using an undefined non-ASCII key. SET KEY OFF directs MS-Kermit to read keycodes from DOS, rather than BIOS, so that console drivers like ANSI.SYS that operate at the DOS level may be used during Kermit CONNECT sessions. This would also apply to any special keyboard replacements that come with DOS-level drivers. SET KEY ON turns key definition back on, and returns Kermit to processing keystrokes at the BIOS level. Kermit Action Verbs: An action verb is the shorthand expression for a named Kermit procedure, such as "generate the proper sequence for a left arrow," "show status," "send a BREAK," and others; verbs are complex actions and each verb has a name. In a key definition the verb name is preceeded by backslash K (\K) to avoid being confused with a string. Verbs and strings cannot be used together on a key. SET KEY \331 \Klfarr SET KEY \2349 \Kexit makes the IBM keyboard left arrow key execute the verb named lfarr which sends the proper escape sequence for a VT102 left arrow key (which changes depending on the internal state of the VT102). The leading \K identifies the definition as a Kermit verb, so no string can start as \K or as \{K in upper or lower case (use \92K). The second example has Alt-X invoking the Leave-Connect-Mode verb "exit" (same as Kermit escape character "^]" followed by C). Each system has its own list of verbs and predefined keys. Table 1-4 shows those available for the IBM PC family. The SET KEY command shows the list of available verbs when a query mark (?) is given as a definition. SHOW KEY displays all currently defined keys or individually selected ones; SHOW KEY can be executed only interactively. ------------------------------------------------------------------------------- Verb Meaning \Kupscn Roll up (back) to previous screen \Kdnscn Roll down (forward) to next screen \Khomscn Roll up to top of screen memory \Kendscn Roll down to end of screen memory (current position) \Kupone Roll screen up one line \Kdnone Roll screen down one line \Kprtscn Print the current screen \Kdump Append the current screen to dump file \Klogoff Turn off session logging \Klogon Turn on session logging \Ktermtype Toggle terminal type \Kreset Reset terminal emulator to initial state \Kmodeline Toggle modeline off/on \Kbreak Send a BREAK signal \Klbreak Send a "long BREAK" signal \Khangup Drop DTR so modem will hang up phone \Knull Send a null (ASCII 0) \Kdos "Push" to DOS \Khelp Display CONNECT help message \Kstatus Display STATUS message \Kexit Escape back from CONNECT mode \Kgold,\Kpf1 VT102 keypad function key PF1 \Kpf2..\Kpf4 VT102 keypad function keys \Kkp0..\Kkp9 VT102 keypad numeric keys \Kkpdot,\Kkpminus,\Kkpcoma,\Kkpenter Other VT102 keypad keys \Kuparr,\Kdnarr,\Klfarr,\Krtarr VT102 cursor (arrow) keys Table 1-4: Kermit-MS Verbs for the IBM PC Family ------------------------------------------------------------------------------- SET LOCAL-ECHO Syntax: SET LOCAL-ECHO {ON, OFF} Specify how characters are echoed during terminal emulation on the currently 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. SET MODE-LINE Syntax: SET MODE-LINE {ON, OFF} Enables/disables display of the mode line during CONNECT. SET PARITY Syntax: SET PARITY {EVEN, ODD, MARK, SPACE, NONE} Specify the character parity to be used on the currently selected port. NONE means no parity processing is done, and the 8th bit of each character can be used for data when transmitting binary files. This is the normal case. If parity is other than none, then there will be 7 data bits (use of parity with 8 data bits is not supported). If you have set parity to ODD, EVEN, MARK, or SPACE, then Kermit-MS will re- quest that binary files be transferred using 8th-bit-prefixing. If the other Kermit knows how to do 8th-bit-prefixing (this is an optional feature of the Kermit protocol, and some implementations of Kermit don't have it), then 8-bit binary files can be transmitted successfully. If NONE is specified, 8th-bit- prefixing will not be requested. SET PORT Syntax: SET PORT {number, COM1, COM2, NET [nodename]} On machines with more than one communications port, select the port to use for file transfer and CONNECT. This command lets you use a different asynchronous adapter, or switch between two or more simultaneous remote sessions. Sub- sequent SET BAUD, PARITY, HANDSHAKE, FLOW, and LOCAL-ECHO commands will apply to this port only -- each port remembers its own parameters, so that you may set them for each port and then switch between ports conveniently with the SET PORT command. SET PROMPT Syntax: SET PROMPT [string] This command allows you to change the MS-DOS Kermit program's prompt. The string may be enclosed in curly braces. Control characters like ESC can be included as backslashed numbers like "\27". SET RECEIVE Syntax: SET RECEIVE parameter value This command lets you modify the ways in which MS-Kermit asks the other Kermit to behave. That is, it controls the file transfer protocol options for packets sent to MS-Kermit by the other Kermit. The parameters and values you specify in the SET RECEIVE command are sent to the other Kermit during initial negotia- tions. END-OF-LINE number ASCII value of packet terminator to look for on incoming packets. PACKET-LENGTH number Ask the remote Kermit to use the specified maximum length for packets that it sends to Kermit-MS. The normal length is 94 bytes. If a length greater than 94 is specified, a protocol option called "long packets" will be used, provided the other Kermit also supports it. Kermit-MS handles extended-length packets up to 1000 bytes long. TIMEOUT number 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 other Kermit's normal timeout interval. (and some others...) SET REMOTE Syntax: SET REMOTE {ON, OFF} SET REMOTE ON removes the file transfer display (as if you had given the com- mand SET DISPLAY QUIET). It should be used when you are running Kermit-MS in remote mode when coming in from another PC through the Kermit-MS's "back port", to which the console has been reassigned using the DOS CTTY command, e.g. CTTY COM1 SET RETRY Syntax: SET RETRY number Sets the number of times a packet is retransmitted before the protocol gives up. The number of retries can be between 1 and 63, and is 5 by default. SET SEND Syntax: SET SEND parameter value The SET SEND command is primarily used to override negotiated protocol options, or to establish them before they are negotiated. END-OF-LINE number ASCII value of packet terminator to put on outbound packets. Normally carriage return. Use this command if the other Kermit needs its pack- ets terminated with a nonstandard control character. PAUSE number How many milliseconds to pause before sending each packet, 0-127, nor- mally zero. This helps half-duplex systems prepare for reception of our packet. Padding characters are sent only after the time limit ex- pires. START-OF-PACKET number Mark the beginning of outbound packets with some control character other than Control-A. This will be necessary if the remote host or the communication channel cannot accept a Control-A as data, or if it echoes back your packets. The remote host must have been given the corresponding SET RECEIVE START-OF-PACKET command. TIMEOUT number Change Kermit-MS's normal timeout interval; this command is effective only if TIMER is set to be ON; it is normally ON so that both Kermits can control timeouts. When the timer is ON, the default interval is 13 seconds. (and some others...) SET SPEED (see SET BAUD) SET TAKE-ECHO Syntax: SET TAKE-ECHO {ON, OFF} Specifies whether screen display should occur during implicit or explicit TAKE operations on MSKERMIT.INI or other Kermit-MS command files, and during evaluation of macro definitions by the DO command. SET TERMINAL Syntax: SET TERMINAL parameter [value] This command controls most aspects of terminal emulation. Most of the parameters are only settable (or meaningful) on the IBM PC family and compatibles. The first group of parameters tells which kind of terminal to emulate: NONE Act as a dumb terminal. All incoming characters will be sent to the screen "bare", as-is, through DOS. VT52 The DEC VT-52 terminal. HEATH The Heath/Zenith-19 terminal (H19). VT102 The DEC VT102 (ANSI) terminal, which is the same as a VT100 but also supports line/character insert/delete editing functions and ANSI printer controls. TEK4010 A Tektronix 4010 graphics terminal. The remaining SET TERMINAL commands specify setup options for the selected ter- minal: COLOR number [, number [, number]] Several numbers, applied in left to right sequence, separated by commas or spaces: 0 Reset the colors to normal intensity white characters on a black background and use the "no-snow" mode on the IBM Color Graphics Adapter (CGA). 1 High intensity foreground 10 Request fast screen updating for use on the IBM Mono, EGA, or PGA (usually sensed and set internally by Kermit), and some non-IBM CGAs. 3x Foreground color 4x Background color where x is a single digit from 0 to 7, which is the sum of the desired colors: 1 Red 2 Green 4 Blue Example: 0, 1, 37, 44 on an IBM CGA would produce bold white characters on a blue field with no snow. The snow removal business has to do with whether the program should synchronize with vertical retrace when up- dating screen memory. This is necessary with certain color adaptors (like the CGA) and unnecessary for others (like the EGA). ROLL {ON, OFF} ON unrolls the screen to the bottom before adding new material if the screen had been rolled back, e.g. by Ctrl-PgUp. ROLL OFF (the default) displays new material on the current screen, possibly overwriting old material. SCREEN-BACKGROUND {NORMAL, REVERSE} NORMAL means dark background, light characters. REVERSE means light background, dark characters. WRAP {ON, OFF} ON automatically breaks screen lines (by inserting a CRLF) when they reach the right margin. OFF disables wrapping -- if a line is too long, the excess characters go off the screen. WRAP is OFF by default, since most hosts format lines to fit on your screen. (and some others...) SET TIMER Syntax: SET TIMER {ON, OFF} This command enables or disables the timer that is used during file transfer to break deadlocks that occur when expected packets do not arrive. SET TRANSLATION Syntax: SET TRANSLATION INPUT {ON, OFF, char1 char2} This command provides multi-language support (and perhaps other special effects) during CONNECT, and during execution of the INPUT, OUTPUT, PAUSE, and TRANSMIT script commands, but not during file transfer or at MS-Kermit command level. A character that arrives at the communication port (char1) will be translated to another character (char2) before display on the screen. As many as 256 characters may have translations specified concurrently. But to see characters with ASCII values higher than 127, you must also SET DISPLAY 8 and SET PARITY NONE. SET TRANSLATION INPUT ON enables translation (the keyword INPUT is required to allow future translation mechanisms). OFF disables the translation and is the default. Translation table entries are made by specifying byte pairs in ASCII or numeric backslash form: SET TRANS INPUT \3 \13 converts incoming ASCII ETX characters (decimal 3) to ASCII CR (decimal 13). 8-bit values are allowed. SET WARNING Syntax: SET WARNING {ON, OFF} Specify what to do when an incoming file is about to be stored under the same name as an existing file in the target device and directory. 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) any existing one. If OFF, the pre-existing file is destroyed, even if the incoming file does not arrive completely. WARNING is ON by default as a safety measure. The new name is formed by adding numbers to the part of the name before the dot. For instance, ABC.TXT becomes ABC00001.TXT, ABC00001.TXT becomes ABC00002.TXT, etc. The STATUS Command Syntax: STATUS The STATUS command displays the values of all the current SET options. There are currently no operands for the STATUS command. It always displays all the options, and the display fills the screen. The SHOW Command Syntax: SHOW option Most parameters that may be altered with SET commands are displayed by the STATUS command. The SHOW command is used for displaying macro definitions, key redefinitions, file transfer statistics, and translations: SHOW MACROS SHOW KEY SHOW MODEM SHOW STATISTICS SHOW TRANSLATION 1.7. SCRIPTS A script is a file containing Kermit commands to be executed. It is the same as a TAKE file, in Kermit terminology, but includes INPUT, OUTPUT, PAUSE, ECHO, and CLEAR commands to automatically detect and respond to information flowing though the serial port, actions which otherwise would be performed by the user during CONNECT. The login sequence of a host computer is a classical example. The script commands INPUT, OUTPUT, PAUSE, and ECHO may be terminated by typing Control-C at the keyboard. The CLEAR command Syntax: CLEAR The CLEAR command flushes the buffers of the serial port to forget any earlier material to help the INPUT command with a clean start. The INPUT command Syntax: INPUT [timeout] {search-string | @filespec} INPUT reads characters from the serial port continuously until one of two things occurs: the received characters match the search string or the time limit expires. Matching strings is the normal use, as in Kermit-MS>input 5 Login please: to recognize the phrase "Login please:", or else time out after trying for 5 seconds. The behavior of the INPUT command can be controlled by SET INPUT parameters: CASE, TIMEOUT-ACTION, DEFAULT-TIMEOUT, and ECHO. If the TIMEOUT-ACTION is PROCEED then failure to match strings is ignored and the script continues with the next command. Otherwise, QUIT causes the current script file to be exited immediately. When a script fails because an INPUT command did not encounter the desired string within the timeout interval, the message is "?Not confirmed". The OUTPUT command Syntax: OUTPUT {string | @filespec} The OUTPUT command writes the indicated character string to the serial port as ordinary text. The string may contain control or other special binary charac- ters by representing them in the backslash numerical form. Carriage Return (CR), for example, is \13 decimal, \o15 octal, or \x0D hexadecimal. The string may use 8-bit characters if the communications parity is type NONE. The PAUSE command Syntax: PAUSE [number] PAUSE simply waits one or more seconds before Kermit executes the next script command.