File CKCKER.UPD, Supplement to "Using C-Kermit". -*- text -*- As of C-Kermit version: 5A(190) This file last updated: October 4, 1994 Authors: Frank da Cruz and Christine M. Gianone Address: Watson Laboratory, Columbia University Academic Information Systems, 612 West 115th Street, New York, NY 10025-7221, USA. Phone: +1 212 854-5126 Fax: +1 212 662-6442 -- or -- +1 212 663-8202 E-Mail: kermit@columbia.edu Copyright (C) 1985, 1994, Trustees of Columbia University in the City of New York. The C-Kermit software may not be, in whole or in part, licensed or sold for profit as a software product itself, nor may it be included in or distributed with commercial products or otherwise distributed by commercial concerns to their clients or customers without written permission of the Office of Kermit Development and Distribution, Columbia University. This copyright notice must not be removed, altered, or obscured. ------------------------------ WHAT IS IN THIS FILE This file lists changes made to C-Kermit since version 5A(188) was released and the first edition of the book "Using C-Kermit" was published. Use this file as a supplement to "Using C-Kermit". If the "most recent update" shown above is long ago, contact Columbia University to see if there is a newer release. For further information, also see the CKCKER.BWR ("C-Kermit beware") file for hints, tips, tricks, restrictions, frequently asked questions, etc, plus the system-specific "beware file", e.g. CKUKER.BWR for UNIX, CKVKER.BWR for VMS, etc, and also any system-specific update files such as CKOKER.UPD for OS/2. ------------------------------ CONTENTS I. C-KERMIT DOCUMENTATION: Information about the C-Kermit manual. II. NEW FEATURES: Documentation for features added since 5A(188) -- (1) PROGRAM MANAGEMENT 1.1. Command Retry, Recall, and Typeahead 1.2. The System-Wide Initialization File 1.3. The SET EXIT Command (2) MAKING AND USING CONNECTIONS 2.1. Using the Services Directory 2.1.1. Login Macros 2.1.2. Connection Details (3) TERMINAL CONNECTION 3.1. Auto Up- and Download 3.2. The CONNECT Command 3.3. The SET KEY Command 3.4. The SET TERMINAL Command 3.5. The SET TELNET Command (4) FILE TRANSFER 4.1. File Transfer Recovery 4.1.1. The RESEND Command 4.1.2. Manual Recovery: The PSEND Command 4.2. Control-Character Unprefixing 4.3. Keyboard Cancellation of Packet Mode 4.4. New RECEIVE Command Features 4.5. Automatic Directory Creation 4.6. Pausing Between Packets 4.7. Fullscreen File Transfer Display Improvements 4.7.1. Thermometer 4.7.2. Repainting the Screen 4.8. Improved Status Codes (5) NEW CLIENT/SERVER FEATURES 5.1. New REMOTE Commands 5.2. "WHATAMI" -- Making Kermit GET more like FTP GET (6) INTERNATIONAL CHARACTER SETS 6.1. Hebrew File Transfer 6.2. Hebrew Terminal Emulation 6.3. The Hewlett Packard Roman8 Character Set (7) SCRIPT PROGRAMMING 7.1. New IF Commands 7.2. New \v() Variables 7.3. New \f() functions 7.4. INPUT and OUTPUT Command Improvements 7.5. The New MINPUT Command 7.6. Other New or Improved Script Programming Commands (8) EXTERNAL PROTOCOLS 8.1. The REDIRECT Command 8.2. New Macros (9) NEW COMMAND-LINE OPTIONS III. APPENDICES Appendix 1: UNIX C-KERMIT Appendix 2: VMS C-KERMIT Appendix 3: OS/2 C-KERMIT Appendix 4: MACINTOSH KERMIT Appendix 5: STRATUS VOS C-KERMIT IV. ERRATA & CORRIGENDA: Corrections to "Using C-Kermit" ------------------------------ I. C-KERMIT DOCUMENTATION The user manual for C-Kermit is: Frank da Cruz and Christine M. Gianone, "Using C-Kermit", Digital Press / Butterworth-Heinemann, Woburn, MA, 1993, 514 pages, ISBN 1-55558-108-0 US single-copy price: $34.95; quantity discounts available. Available in computer bookstores or directly from Columbia University: Kermit Development and Distribution Columbia University Academic Information Systems 612 West 115th Street New York, NY 10025 USA Telephone: (USA) +1 212 854-3703 Domestic and overseas orders accepted. Price: $34.95 (US, Canada, and Mexico), $45 elsewhere. Orders may be paid by MasterCard or Visa, or prepaid by check in US dollars. Add $35 bank fee for checks not drawn on a US bank. Price includes shipping. Do not include sales tax. Inquire about quantity discounts. You can also order by phone from the publisher, Digital Press / Butterworth-Heinemann, with MasterCard, Visa, or American Express: +1 800 366-2665 (Woburn, Massachusetts office for USA & Canada) +44 1865 314627 (Oxford, England distribution centre for UK & Europe) +61 03 9245 7111 (Melbourne, Vic, office for Australia & NZ) +65 356-1968 (Singapore office for Asia) A German-language edition is also available: Frank da Cruz and Christine M. Gianone, "C-Kermit - Einfuehrung und Referenz", Verlag Heinz Heise, Hannover, Germany (1994). ISBN 3-88229-023-4. Deutsch von Gisbert W. Selke. Price: DM 90,00. Verlag Heinz Heise GmbH & Co. KG, Helstorfer Strasse 7, D-30625 Hannover. Tel. +49 (05 11) 53 52-0, Fax. +49 (05 11) 53 53-1 29. The Kermit file transfer protocol is specified in: Frank da Cruz, "Kermit, A File Transfer Protocol", Digital Press, Bedford, MA, 1987, 379 pages, ISBN 0-932376-88-6. US single-copy price: $29.95. Availability as above. News and articles about Kermit software and protocol are published periodically in the journal, Kermit News. Subscriptions are free; contact Columbia University at the address above. Online news about Kermit is published in the Kermit Digest and in the comp.protocols.kermit newsgroup. ------------------------------ II. NEW FEATURES Items are grouped together by major topic, roughly corresponding to the chapters of "Using C-Kermit". (1) PROGRAM MANAGEMENT 1.1. Command Retry, Recall, and Typeahead These features apply only when you are typing commands at the C-Kermit> prompt, and not to command file or macro execution. They were added in edit 190. If you enter a command that contains a syntax error, C-Kermit now reprompts you automatically with the portion of the command that was correct, so you don't have to retype it. Example: C-Kermit>set block-check oofa ?No keywords match - oofa C-Kermit>set block-check _ "_" shows the position of the cursor after you are reprompted. At this point, you can type question mark (?) to find out what is legal here, or you can complete the command, or you can erase it with Ctrl-U, etc, just as if you had retyped the initial words yourself. If you want to disable this feature, tell C-Kermit to: SET COMMAND RETRY OFF C-Kermit versions that are built with the "DYNAMIC" memory allocation option now support command recall (type "show features" and look for DYNAMIC and/or CK_RECALL). C-Kermit saves your commands in a command recall (history) buffer, which, by default, holds your last 10 commands. To recall your previous command, type Ctrl-P (that is, hold down the Control or Ctrl key and press the P or p key) or Ctrl-B. Type Ctrl-P (or Ctrl-B) again to recall the command before that, and so on. If you try to go back too far, C-Kermit beeps at you. NOTE: In OS/2, you should use Ctrl-B rather than Ctrl-P because, at least in certain kinds of sessions, depending on your system's configuration, Ctrl-P is trapped by OS/2 itself as a "toggle printer" command, as in MS-DOS. Each time you recall a command, it appears before you as if you had typed it up to, but not including, the Enter (Carriage Return) that actually causes it to execute. If you want to execute the command, press the Enter (Carriage Return) key. If you want to edit it, use the editing keys, including Ctrl-U to erase it. When you are viewing recalled commands, you can also go forwards in the command recall buffer by typing Ctrl-N. This is handy in case (for example), you typed too many Ctrl-P's, and went back too far. NOTE: In general, arrow keys (and mice, etc) can not be used for command recall. Why? Because C-Kermit would have to grow to twice its size to include all the operating-system, version, hardware, keyboard, and terminal dependent code to make these devices work uniformly on all (or even some) of the computers where C-Kermit runs. EXCEPTION: The up- and down-arrow keys can be used in OS/2 to scroll up and down in the command recall buffer. You can change the size of the command recall buffer to hold any number of commands you like, subject to the memory limitations of your computer. The command is: SET COMMAND RECALL-BUFFER-SIZE number where "number" is the number of commands you want to keep. The more you keep, the more memory C-Kermit uses. If you enter a size of 0, the command recall feature is disabled. Whenever you give the SET COMMAND RECALL-BUFFER-SIZE command, your previous command history is lost. You can display the size of your command recall buffer, as well as your COMMAND RETRY setting, with: SHOW COMMAND (Note: SET CMD and SHOW CMD are synonyms for SET COMMAND and SHOW COMMAND) Typeahead is now permitted during entry of interactive commands. Typeahead is not preserved, however, over execution of command files or macros, because these might themselves require keyboard input, or might enter CONNECT or file transfer protocol mode. Edit 190. 1.2. The System-Wide Initialization File As of edit 190, C-Kermit can be configured to execute its initialization file from a single system-wide directory, rather than requiring a copy in each user's home directory. This is particularly important for UNIX; VMS C-Kermit already had a facility for this. A common initialization file saves disk space and management headaches. It is recommended that all the features of the standard initialization file (dialing directory and services directory setup, chaining to customization file, etc) be kept intact. 1.3. The SET EXIT Command SET EXIT WARNING { ON, OFF } tells whether C-Kermit should issue a warning message and require confirmation if an EXIT command, or a SET LINE (SET PORT), SET HOST, or TELNET command is given and a connection (dialed or network) still appears to be open, since any of these commands would close the currently open connection. The default is OFF, meaning no warnings. If SET EXIT WARNING is ON, a warning is issued if a network connection appears to be open: C-Kermit>exit A network connection to foo.bar.edu might still be active. OK to exit? at which point you can type Yes or No. You will also get a warning if the serial SET LINE device has the carrier (CD, DCD) signal and C-Kermit has not been told to SET CARRIER OFF: C-Kermit>set line /dev/acu A serial connection might still be active on /dev/ttyh6. OK to close? Note that not all versions of C-Kermit have access to the carrier signal; if your version of C-Kermit says "Modem signals not available" when you give a SHOW COMM command, then SET EXIT WARNING ON will always warn you about a possibly active serial connection when you try to exit after using a SET LINE / SET PORT connection. SET EXIT STATUS tells C-Kermit to use the given number as its program exit (return) code. This lets the user set program return code without actually having to exit; for example, the user can OR in various bits at different times. Display the SET EXIT values with SHOW EXIT. Edit 190. (2) MAKING AND USING CONNECTIONS 2.1 Using The Services Directory In the original release of C-Kermit, 5A(188), the services directory feature was provided mainly as an illustration of how C-Kermit's script programming language can be used to build handy communications tools, and so it was not presented or explained until Chapter 13 of "Using C-Kermit", and therefore was probably missed by a lot of readers (and users). Since then, the services directory feature has proven to be quite useful in its own right, and has also been improved in one small but important way. Here is a brief nontechnical explanation. The services directory is a plain-text file in your home directory, containing one line, or "entry", for each service that you want to access. Each service listed in your services directory can be connected to and logged in to automatically, no matter whether this involves dialing up a modem, making a network connection, or any other type of connection that C-Kermit can handle. The name of the services directory file is .ksd in UNIX and OS-9, and CKERMIT.KSD in OS/2, VMS, and elsewhere. The services directory can be used only if you are also using the standard C-Kermit initialization file. Each line in the services directory has the following parts: For example: HP9000 unixlogin olga net tcp/ip hp.xyzcorp.com where "HP9000" is the entry name, "unixlogin" is the login macro name, "olga" is the username, and "net tcp/ip hp.xyzcorp.com" are the connection details. To use this entry, you would give the following command at the C-Kermit prompt: access hp9000 or: access hp9000 xxxxxx where "xxxxxx" is your password on the computer you will be accessing. C-Kermit's ACCESS macro (defined in your C-Kermit initialization file) handles the connection details: "net" means it's a network connection; "tcp/ip" tells which type of network, and "hp.xyzcorp.com" tells the name or address (in this case, the name) of the computer or service on the network. If you don't supply a password to the ACCESS command, you are prompted for it. You do not (can not, and should not) include passwords in your services directory file. Here's another example, in which the connection is made by dialing a modem: COMPUSERVE cislogin 765,4321 call hayes /dev/cua 2400 93,876-5432 Here, "COMPUSERVE" is the entry name, "cislogin" is the name of the login macro, "765,4321" is your CompuServe user ID, and the connection details are: "call hayes /dev/cua 2400 93,876-5432". "Call" means we will be making a phone call; "hayes" tells which type of modem, "/dev/cua" is the name of the device that modem is connected to, "2400" tells the communication speed, and "93,876-5432" is the phone number to dial. 2.1.1. Login Macros Each login macro looks for the appropriate prompts from the host or service and responds accordingly with your username, password, and/or other information, and then waits until it sees the main prompt of the host or service, or other indication that you have been logged in successfully. The following login macros are available in the standard C-Kermit initialization file (.kermrc on UNIX and OS-9, CKERMIT.INI elsewhere): UNIXLOGIN For logging in to all types of UNIX systems: Solaris, HP-UX, Linux, IRIX, DG/UX, NeXTSTEP, OSF/1, SunOS, etc etc. The default system prompt (explained below) is "\13\10$\32"; that is, carriage return, linefeed, dollar sign, space. VMSLOGIN For logging in to DEC VAX/VMS or OpenVMS systems. The default system prompt is "\10\13$\32"; that is, linefeed, carriage return, dollar sign, space. This macro can also be used for logging in to DG AOS/VS systems if you specify a different prompt ("\13\10)\32"). NOTE: The VMSLOGIN macro has been updated to account for new procedures for use with VMS 6.0 and/or 6.1, while retaining comptability with earlier VMS releases. VMLINELOGIN For logging into IBM mainframes with VM/CMS over linemode connections. VMFULLOGIN For logging into IBM mainframes with VM/CMS over fullscreen connections. CISLOGIN For logging in to CompuServe. DOWLOGIN For logging in to Dow Jones News/Retrieval. DJNRSPRINT For logging in to Dow Jones News/Retrieval over SprintNet. NOLOGIN For accessing computers or services that do not require logging in. Each login macro name must be followed by a username, even NOLOGIN. For NOLOGIN, just include a "dummy" name, like "xxxx", that will not be used. Other login macros can be easily constructed, modeled on those above. Read Chapters 11-13 of "Using C-Kermit" for full instructions. If you add or modify login macros, you should put their definitions in your C-Kermit customization file (.mykermrc in UNIX and OS-9, CKERMOD.INI elsewhere). There was a problem with the login macros in C-Kermit 5A(188-189), namely that the system prompt was hard-coded into the macro. For example, the UNIXLOGIN macro assumed that the UNIX shell prompt was "$ " (dollar sign followed by space), but in many cases it might be something else, and the only way to allow for different prompts was to edit the macro itself. In C-Kermit 5A(190) and later, you may include the system prompt in your services directory by grouping it together in curly braces with the login macro name: {macroname prompt} For example: CSHELL {unixlogin \13\10%\32} olga net tcp/ip bsd.xyzcorp.com CHEMISTRY {vmslogin \10\13CHEM$} OLGA net tcp/ip chemlab.xyzcorp.com DG {vmslogin \13\10)\32} olga net tcp/ip aosvs.xyzcorp.com The first example specifies the C-Shell prompt, "% ", rather than using the default UNIX (Bourne Shell, K-Shell) prompt of "$ ". The second example accesses a system that has a custom prompt. The third uses the VMSLOGIN macro to access a Data General AOS/VS system by specifying the AOS/VS prompt, ") ", since otherwise the Username: and Password: prompts are the same as for VMS. The "backslash-number" notation is a way of including special (usually nonprintable) characters in C-Kermit commands and files, explained on pages 21-22 of "Using C-Kermit". The number is the ASCII character number, such as 10 for linefeed, 32 for space. 2.1.2. Connection Details The Connection Details part of a services directory entry starts with one of the following words: CALL - The connection is made with a phone call through a modem. SERIAL - The connection is a direct (dedicated) serial connection. NET - The connection is made on a network. The subsequent information depends on the type of connection. CALL must be followed by the following information, in this order: 1. The modem type (a valid SET MODEM value). 2. The name of the device on your computer that the modem is connected to. 3. The speed, in bits per second, at which to use the device. 4. The telephone number to dial. This can also be the name of an entry in your dialing directory. SERIAL must be followed by the following information, in this order: 1. The serial device name. 2. The communication speed. NET must be followed by: 1. The network type: TCP/IP, X.25, DECNET, etc (a valid SET NET value). 2. The name or address of the host or service you want to connect to. 3. Additional network-specific information, like a service or socket number. For TCP/IP network connections, you can include a socket number by appending to the IP name or address with a colon, for example: WEATHER nologin xxxx net tcp/ip madlab.sprl.umich.edu:3000 Create your services directory file using a text editor, as a plain-text (ASCII) file. If you are using a word processor, be sure to save your services directory as a plain text (ASCII) file. To use your services directory, just type "access" and the service name at the C-Kermit prompt, for example: C-Kermit> access hp9000 olga's password: __________ To list your services directory, type "list" at the C-Kermit prompt. To look up a particular services directory entry, type "list" and then the name, for example "list hp9000". (3) TERMINAL CONNECTION 3.1 Auto Up- and Download As of edit 190, the OS/2, UNIX, and VMS versions of C-Kermit are able to respond automatically to "autoupload", "autodownload", or auto-anything-else directives from the remote computer during CONNECT mode. These directives come in the form of an Application Program Command escape sequence, or APC. The APC is sent by a host application to a terminal emulator, containing one or more commands to be executed by the terminal emulation program. This mechanism lets the host application software control your communications software, allowing an unprecedented degree of automation and convenience. Good uses for this feature include: (a) automatic communications, protocol, terminal, keyboard, or other setups by the host application; (b) automatic initiation of file transfer by the host application. The form of an APC is "_text\", where "" is ASCII character 27 (Escape), and "text" is a command or a list of commands separated by commas. The APC sequence was originally defined by Digital Equipment Corporation for its VT300-series and higher terminals. There are two "ends" to an APC operation, and you need to understand how to control each end. Let's call the application which sends an APC escape sequence the "APC sender", and the application that receives it, and which is supposed to execute the commands it contains, the "APC receiver". Any host application can be an APC sender. To send an APC, all it needs to do is display the desired commands on your terminal screen, enclosed in _ and \. C-Kermit 5A(189) (and later) has a command for doing this: APC text where the "text" is a command (or commands) for the APC receiver. Leading and trailing spaces are removed from the text unless it is enclosed in braces: APC { text } Here's an example that sets MS-DOS Kermit parameters from the C-Kermit command line. It assumes that C-Kermit is being accessed from MS-DOS Kermit 3.13 or later, which is in CONNECT mode: C-Kermit>apc set receive packet-length 2000, set window 4 This command causes C-Kermit to send the following characters to the terminal (i.e. MS-DOS Kermit's terminal emulator): _set receive packet-length 2000, set window 4\ MS-DOS Kermit recognizes the APC sequence, extracts the commands from it, and processes them automatically, according to the rules listed below. Here's an example in which you define and then execute a C-Kermit macro to send a file from C-Kermit, causing MS-DOS Kermit to receive it automatically without your having to escape back and type "receive". You do not need to CONNECT again after the transfer is done, either; this too happens automatically. C-Kermit>define autosend apc receive, send \%1 C-Kermit>autosend oofa.txt A macro is used because if you type APC RECEIVE at the C-Kermit prompt, MS-DOS Kermit goes immediately into RECEIVE mode and you have no way to give the SEND command to C-Kermit. Conversely, if you type the SEND command first, C-Kermit goes into SEND mode, and you have no opportunity to give it an APC command. When the macro (or a TAKE command file) is the source of commands, the "Catch-22" is avoided because the keyboard is out of the picture. The APC receiver can be: . MS-DOS Kermit 3.13 or later . C-Kermit 5A(190) for OS/2 . C-Kermit 5A(190) for UNIX . C-Kermit 5A(190) for VMS When one of these Kermit programs is in CONNECT mode, and an APC escape sequence arrives, the commands it contains are executed if: 1. Terminal emulation is VT100, VT102, VT220, VT320, or ANSI, and: 2. SET TERMINAL APC is ON and the commands are not "dangerous", or: 3. SET TERMINAL APC is UNCHECKED. After processing the APC sequence, whether its commands are executed or not, the APC receiver returns to CONNECT mode automatically. The C-Kermit initialization file defines several macros to let you take advantage of the APC feature. They are to be used at the C-Kermit> prompt, when you are accessing C-Kermit through an APC receiver. They include: PCSEND [ ] Sends the file or files from C-Kermit to the "PC" that's on your desk. (Of course, the PC might also be a UNIX workstation, etc). If the does not contain wildcard characters (that is, it is the name of a single file), you can include the optional "as-name" to send it under a different name. The file or files are sent according to C-Kermit's current FILE TYPE setting, text or binary (except in VMS, where VMS C-Kermit determines the file type and transfer automatically for each file). In other words, the PCSEND macro is exactly like the SEND command, except it automatically puts your local Kermit program into RECEIVE mode, and then back into CONNECT mode again when the transfer is complete. This process is sometimes referred to as "autodownloading". PCGET [ ] This tells C-Kermit to get the specified file or files from your "PC". It puts your local Kermit program into server mode, GETs the specified files from it, then sends it a FINISH command and puts it back in CONNECT mode automatically. The transfer type is governed by C-Kermit's current FILE TYPE setting. This process can be called "autouploading". C-Kermit's response to APC sequences is controlled by the following command: SET TERMINAL APC { ON, OFF, UNCHECKED } The default setting is OFF, meaning that C-Kermit ignores APC sequences unless you tell it otherwise. In the OS/2 version, they are harmlessly absorbed and not displayed. In the UNIX and VMS versions of C-Kermit, they are passed through transparently, in case you want them acted upon by your actual terminal or terminal emulator. To activate the APC feature, use: SET TERMINAL APC ON This allows execution of all commands received in APC sequences except those considered dangerous, such as: PUSH, RUN, !, REDIRECT, DELETE, RENAME, OUTPUT, ENABLE, DISABLE, SCRIPT, and SET TERMINAL APC. With this setting, for example, it would not be possible for someone to send you a "letter bomb" or screen message that contained an APC sequence to execute a command on your computer (because RUN and ! are disabled). The commands allowed by SET TERMINAL APC ON are only the ones which affect Kermit itself, including the initiation of Kermit file transfers. Should you want to enable APC execution off ALL commands, which can be dangerous and is therefore not recommended unless you know exactly what you are doing, you can: SET TERMINAL APC UNCHECKED Use UNCHECKED at your own risk. Note that when TERMINAL APC is not OFF, the CONNECT command might run a bit slower than when TERMINAL APC is OFF. 3.2. The CONNECT Command The CONNECT command now has an optional "switch", /QUIETLY, to suppress the verbose CONNECT message on versions of C-Kermit (such as UNIX, VMS, etc) that normally give one: C-Kermit>CONNECT /QUIETLY or: C-Kermit>C /Q or even just: C-Kermit C / This switch has no effect on versions of C-Kermit that contain true terminal emulators, such as the OS/2 and Macintosh versions. 3.3. The SET KEY Command The SET KEY command now allows you to press the Return or Enter key after the word KEY to be prompted for a keystroke and then a definition separately. Using this form of the command lets you assign material to a key or key combination without having to know its key code. After you press the key to be assigned, you are shown its current definition, if any. You can cancel by typing Ctrl-C, restore the default definition by pressing the Return or Enter key, or enter a new definition. Example: C-Kermit>set key Press key: Key code \16 => Character: \16 (self, no translation) Definition: blah C-Kermit> NOTE: There are many changes and additions to the key mapping facility in OS/2 C-Kermit. Please refer to the OS/2-specific update file for details. 3.4. The SET TERMINAL Command SET TERMINAL DEBUG { ON, OFF } SET TERMINAL DEBUG ON is a synonym for SET DEBUG SESSION. SET TERMINAL DEBUG OFF turns off session debugging without interfering with any other debugging that might be active (such as LOG DEBUG). Session debugging status is displayed in the SHOW TERMINAL display. Edit 190. NOTE: There are numerous other new SET TERMINAL commands for OS/2 C-Kermit. Please refer to the OS/2-specific update file for details. 3.4. The SET TELNET Command SET TELNET NEWLINE-MODE { ON, OFF, RAW } This command tells C-Kermit what to send during CONNECT mode on a TELNET connection when you type Carriage Return (Return or Enter key). ON (the default) means to send Carriage Return and Linefeed (CRLF); OFF means to send Carriage Return and NUL (ASCII 0). The TELNET protocol Network Virtual Terminal specification says that Carriage Return must always be followed by LF or NUL. However, certain TCP/IP services do not like CRLF or CR-NUL, and so in edit 190, the RAW option was added, which means to send CR as itself, i.e. a plain carriage return. (4) FILE TRANSFER 4.1. File Transfer Recovery C-Kermit 5A(190) (the UNIX, OS/2, AOS/VS, and Amiga versions) and MS-DOS Kermit 3.14 now have the ability to continue interrupted binary-mode file transfers, and also allow you to "manually" recover from certain other types of failures. 4.1.1. The RESEND Command The new RESEND command lets you continue a file transfer from the point where it was interrupted (for example, because of a telephone disconnection) without having to retransmit the data that was already successfully transmitted. Imagine, for example, transferring a ten-megabyte file over a 2400-bps modem connection when, after 9 megabytes have been sent, your call-waiting feature kicks in and drops the modem connection. 9 megabytes at 240 cps takes about 11 hours. The remaining megabyte would take about 1.2 hours. The recovery feature lets you complete the failed transfer in the amount of time it takes to send the as-yet-untranmsitted part of the file, rather than sending the entire file again from the beginning -- in this example, a savings of 11 hours. Before seeing how to use this feature, let's look at the restrictions: 1. Recovery works only for binary-mode transfers between computers that have Kermit programs that support this feature. It does not work with any other transfer modes, including text or labeled. In other words, if you want to be able to use the recovery feature, you must tell the file sender to: SET FILE TYPE BINARY In VMS, C-Kermit will switch to binary mode automatically if the file has a fixed record format. You can also force binary-mode transfer in VMS via SET FILE TYPE IMAGE. 2. The original transfer must have been done with SET FILE INCOMPLETE KEEP in effect at the receiver, meaning that incompletely received files are kept rather than discarded. In C-Kermit 5A(190) and later, this is the default, which is a change from previous releases. 3. Recovery only works between two Kermit programs that have this capability and negotiate it successfully. As of this writing, these programs include C-Kermit 5A(190) and later for UNIX, OS/2, VMS, VOS, and the Commodore Amiga, and MS-DOS Kermit 3.14 and later for DOS and Windows. (But see below for a way around this.) 4. You should never use SET FILE COLLISION RENAME if you intend to use the recovery feature (see the CKCKER.BWR file for an explanation). Hint: You can also resend text files as long as you transfer them in binary mode. You can transfer text files in binary mode as long as (a) both computers represent text files in stream-CRLF format, and (b) you do not need character-set translation. To recover a failed upload: reestablish the connection, access the same account and directory to which you were sending the file previously, start Kermit there and put it in RECEIVE or SERVER mode. Then escape back to the local Kermit program and give it these commands: SET FILE TYPE BINARY RESEND filename [ as-name ] The RESEND command should use exactly the same names (and SET FILE NAME options) as the SEND command that was interrupted. When you RESEND a file, the receiving Kermit, upon getting the filename, looks up the file and gets its size; it sends the size back to the sending Kermit, and the sending Kermit resumes sending from that point; the receiving Kermit appends incoming material to the partial file rather than creating a new file. You can recover a failed download in the same way. Just make sure you are accessing the same directories as before, and the files have (or are being sent with) the same names as before. The RESEND command ignores your SET FILE COLLISION setting; thus you need not change your FILE COLLISION setting when RESENDing, and you will not find it altered afterwards either. (But please, as mentioned earlier, do not use SET FILE COLLISION RENAME if you ever intend to use the RESEND command.) If the RESEND command is used, but a partial file of the same name does not exist on the receiving end, RESEND behaves just like SEND -- it sends the whole file. If the file on the receiving is the same size as the sender's copy, RESEND does nothing; both files are left alone (exception: when VMS C-Kermit is receiving a resend, it will replace the file's final block). These properties let you resume the interrupted transfer of a group of files. Suppose you had originally done this: Receiver: Sender: SET FILE INCOMPLETE KEEP SET FILE TYPE BINARY RECEIVE (or SERVER) SEND *.ZIP and the phone hung up in the middle of one of the ZIP files. Just reestablish the connection, and recover this way: Receiver: Sender: SET FILE INCOMPLETE KEEP SET FILE TYPE BINARY RECEIVE (or SERVER) RESEND *.ZIP The files that were already sent are skipped, the file that was partially sent is recovered, and the files that were not sent yet are sent. In order for the recovery feature feature to be useful at all, the default for SET FILE INCOMPLETE was changed from DISCARD to KEEP when the RESEND command was added in edit 190. Otherwise an interrupted transfer would leave no partial file behind unless you had remembered to change the default. But now you have to pay closer attention to Kermit's messages to know whether a transfer succeeded or failed -- previously, if it failed, the file would not show up on the receiving end at all; in edit 190 and later, you'll get a partial file which could easily be mistaken for the complete file unless you change the default back to DISCARD or read the screen messages, or keep a transaction log. Watch out for SET FILE COLLISION RENAME, especially when used in conjunction with recovery. Recall that this option (which is NOT the default) renames the incoming file if a file already exists with the same name (the default is to rename the previously existing file, and store the incoming file with its own name). It is strongly recommended that you do not use SET FILE COLLISION RENAME if you ever intend to use the recovery feature: . When the file is first received by C-Kermit, its name will be changed if another file already has the same name. When you RESEND the same file after a failure, C-Kermit will probably try to append the re-sent portion to the wrong file. . Assuming that you get RESEND to work with FILE COLLISION RENAME, C-Kermit, when receiving the remainder of the file during a RESEND operation, will report back the wrong name. Nothing can be done about this because the name is reported back before the receiving Kermit program finds out that it is a recovery operation. Using RESEND, you can write a script program to REALLY, REALLY send a file. Here is a sample, in which we dial up to a UNIX computer and send the MS-DOS Kermit distribution ZIP file. This script program runs under C-Kermit 5A(190) or later on OS/2 (and with a change in the dialout device name, under UNIX too), and under MS-DOS Kermit 3.14 or later. If the transfer fails, we reestablish the connection and restart the transfer from the point of failure, as many times as it takes to get the file across. ---(cut here)--- ask \%u { username: } askq \%p { \%u's password: } ; ; Settings for entire session. ; define \%s 20 ; Seconds to pause between each try define \%n 7654321 ; Phone number set modem hayes ; Modem type set port com1 ; Communication port (use /dev/whatever for UNIX) set speed 19200 ; Speed set file type binary ; File transfer mode must be binary set input timeout quit ; This is just to keep the script program short... set count 50 ; Try up to 50 times to send the file goto nomsg ; Skip message the first time :LOOP ; Come here to redial hangup ; Give the phone a rest echo CONNECTION BROKEN. echo Pausing for \%s seconds... sleep \%s Echo redialing... :NOMSG dial \%n ; Dial the phone number if fail goto AGAIN ; Keep trying... output \13 ; System answered, send a carriage return input 15 login: ; Get login prompt output \%u\13 ; Send user ID input 8 Password: ; Get password prompt output \%p\13 ; Send password input 60 {$ } ; Get system prompt cd /kermit ; CD to desired source directory output cd mskermit\13 ; and destination directory input 8 {$ } ; Get system prompt out kermit -r\13 ; kermit -r(eceive) on remote system input 10 KERMIT READY ; Wait for READY message pause 1 ; Plus a second for safety resend msvibm.zip ; RESEND the file if success goto done ; Success means file is completely transferred :AGAIN if count goto LOOP ; Otherwise, try again. Stop 1 Too many tries. ; Too many tries, give up. :DONE echo File transferred OK ; Success, give message output exit\13 ; Log out from remote computer pause 5 ; Give it time... hangup ; Hang up stop 0 Script succeeded ; Finished, the end. ---(cut here)--- 4.1.2. Manual Recovery: The PSEND Command The PSEND ("partial send") command is like the SEND command, but it begins sending from a specified position in the file: PSEND [ ] must refer to a single file, not a file group. is the byte position in (offset into) the file; 0 means the beginning, 1000 means the 1001st byte. As with the SEND command, the file is sent under its own name unless you specify an "as-name". Unlike RESEND, PSEND can be used for both text and binary transfers, and no special capabilities are required of the Kermit program on the receiving end. The PSEND command can be viewed as part of a "do-it-yourself" recovery feature to be used when the other Kermit program does not support recovery. For example, suppose you were sending a file called OOFA when the connection hung up, and that the receiving Kermit program had been instructed to keep incompletely received files (SET FILE INCOMPLETE KEEP). If the transfer was in binary mode, you could note the length of the partial file on the receiving end; let's say it was 123456. Then tell the file receiver to: SET FILE COLLISION APPEND RECEIVE and tell the sender to: SET FILE TYPE BINARY PSEND OOFA 123456 If the receiver does not support SET FILE COLLISION APPEND, you could just use PSEND to create a new file: SET FILE TYPE BINARY PSEND OOFA 123456 OOFA.NEW and then, after the transfer is complete, join the two pieces together on the receiving end, using a system command or utility. 4.2. Control-Character Unprefixing This feature allows you to improve C-Kermit's file transfer performance on connections that you know are transparent to certain control characters. It lets you tell C-Kermit exactly which control characters need to be prefixed and encoded, and which ones can be transmitted "bare" when sending files. SET { SEND, RECEIVE } CONTROL-PREFIX Sets the control-character prefix which C-Kermit uses to the ASCII character represented by the numeric . The must be in the range 33-63 or 96-126. Normally it is 35 (#, number sign). SEND is the one that C-Kermit should use in packets it is sending. RECEIVE should normally never be used, except to override some kind of protocol negotiation foulup with a buggy commercial or shareware Kermit implementation. Synonym: SET { SEND, RECEIVE } QUOTE. SET CONTROL-CHARACTER UNPREFIXED { ..., ALL } Says you think it's safe to include the control character represented by without prefixing in packets which C-Kermit sends. The is the numeric ASCII code for a control character, 1-31, 127-159, or 255. For example, linefeed (code 10) is normally sent as two printable characters, #J. SET CONTROL UNPREFIXED 10 lets linefeed be sent literally. Include the word ALL to unprefix all control characters (except 0). Or you can specify a list of one or more numeric values, separated by spaces, e.g.: SET CONTROL UNPREFIXED 2 4 5 18 20 If you can safely declare a lot of control characters to be UNPREFIXED, you can send binary files (esp. precompressed ones) up to about 20-25% faster. If you include a control character in this category that causes trouble, however, the transfer will fail, so experimentation is necessary. This command will not let you "unprefix" the NUL character (0), nor the following characters if C-Kermit's current FLOW-CONTROL setting is XON/XOFF: 17, 19, 145, 147. Nor can you unprefix character 255 on a TELNET connection (if C-Kermit *knows* it's a TELNET connection). SET CONTROL-CHARACTER PREFIXED { ..., ALL } Says that the given control character(s) must be prefixed in Kermit packets. By default, all control characters, 0-31, 127-159, and 255, are prefixed. SHOW CONTROL-PREFIXING Displays the current control prefix and a table of all control-character values, showing 1 for each one that will be prefixed and 0 for each one that will not be prefixed. SET REPEAT PREFIX Sets the repeat-count prefix to the ASCII character represented by the numeric . Normally it is 126 (tilde). The must be in the range 33-63 or 96-126. SET REPEAT COUNTS { OFF, ON } Turns the repeat-count compression mechanism off and on. REPEAT COUNTS are ON by default. Turn them OFF in case they cause trouble when used against a faulty Kermit implementation in a shareware or commercial communications program. Or when transferring precompressed files (like .ZIP or .Z files), since it is very rare to find runs of repeated characters, and disabling the repeat-count mechanism frees another character from prefixing, thus resulting in slightly more efficient transfers. The purpose of the SET CONTROL UNPREFIX command is to UNILATERALLY configure C-Kermit to skip prefixing and printable encoding of selected control characters to achieve higher performance when sending files. This feature takes advantage of the fact that most Kermit programs will accept control characters within packet data-fields literally, provided they get through at all, and provided they do not have a special meaning to the receiving Kermit program (such as, in many cases, the packet-start and packet-end characters). There is no protocol negotiation between the two Kermit programs to determine a "safe set" of control characters, and in fact any such negotiation would be largely meaningless, because in most cases the two Kermit programs don't have all the needed information. For example, there might be a terminal server or PAD between them that is sensitive to a particular control character, even though the two Kermit programs are not. If you include in your SET CONTROL UNPREFIXED list one or more control characters that are unsafe, any of several things might happen: 1. Transfer of any file containing these characters will fail. 2. The receiving Kermit program might be interrupted or halted. 3. Your connection might become hung, stuck, or broken. For example because a control character causes a PAD, terminal server, modem, or similar device to go from online mode to command mode. The set of safe control characters depends on the two Kermit programs, their settings, the host operating systems and their settings, the communication and flow control methods, and all the devices, drivers, and protocols that lie between the two Kermit programs. Therefore, this feature is recommended only for use on well-known and often-used connections, so the time invested in finding an optimal unprefixed control-character set will pay off over many file transfers. You must be willing to experiment in order to achieve the optimal safe set. Here is one way. Create a short file containing all 256 possible bytes in sequence and also in pairs, as well as several text strings surrounded by CRLFs; for example, compile and run the following program, redirecting its output to a file: ---(cut here)--- #include main() { int i; puts("\r\n256-byte test pattern:\r\n"); for (i = 0; i < 256; i++) putchar(i); /* singles */ puts("\r\n256-double-byte test pattern:\r\n"); for (i = 0; i < 256; i++) { putchar(i); putchar(i); } /* in pairs */ puts("\r\nEnd of test patterns\r\n"); } ---(cut here)--- To send the file to MS-DOS Kermit from either C-Kermit or MS-DOS Kermit, try the following settings: SET CONTROL UNPREFIXED ALL ; Turn prefixing off for all but 0 SET CONTROL PREFIXED 1 ; Turn it back on for packet-start character SET CONTROL PREFIXED 129 ; and 8-bit version thereof (HINT: Abbreviate SET CON U and SET CON P) Or to send the file from MS-DOS Kermit to C-Kermit, tell MS-DOS Kermit to: SET CON U ALL ; Turn prefixing off for all SET CON P 0 ; Turn it back on for NUL SET CON P 3 ; and for Ctrl-C SET CON P 131 ; as well as Ctrl-C + parity bit NOTE 1: 3 and 131 normally need not be prefixed when sending to C-Kermit 5A(190) or later, nor to 5A(189) if you have SET TRANSFER CANCELLATION OFF. NOTE 2: 1 and 129 need not be prefixed when sending files *to* C-Kermit, but must be prefixed when sending files to MS-DOS Kermit. NOTE 3: 13 (carriage return, the customary packet terminator) normally need not be prefixed when sending files to either C-Kermit or MS-DOS Kermit, except on a TELNET connection (because TELNET servers are likely to change CRLF into CR). Try to send the test file in binary mode. If it works, fine. If not, try prefixing some of the other likely control characters (see below). Once you find the minimum set of prefixed control characters for the test file, it is likely they will also work for any other file on the same connection. Try sending a large precompressed (e.g. ZIP or .Z or GZIP) file. And, of course, for maximum performance, also use a window size greater than 1 (say, 3) and a packet length of 1000 or more. Under ideal conditions (totally transparent and clean serial connection, no Xon/Xoff, and C-Kermit has been told to SET TRANSFER CANCELLATION OFF, see below), the minimum set of control characters that need to be prefixed is: SENDER RECEIVER PREFIXED CONTROLS MS-DOS Kermit MS-DOS Kermit 1 129 MS-DOS Kermit C-Kermit 0 C-Kermit MS-DOS Kermit 0 1 129 C-Kermit C-Kermit 0 For example, to set up C-Kermit to unprefix the minimum set of prefixed control characters for sending files to MS-DOS Kermit, tell C-Kermit to: SET FLOW NONE ; Or SET FLOW RTS/CTS SET CONTROL UNPREFIX ALL SET CONTROL PREFIX 1 129 ; C-Kermit always prefixes character 0 When the mininum set doesn't work, consult this list of control characters that are apt to cause trouble and are therefore likely candidates for prefixing. In particular, note that unprefixing of the packet-start character (normally 1 and 129), can cause problems when sending to C-Kermit if the communication link (including device input buffers) is noisy or apt to lose characters. set con p 0 ; Ctrl-@ = NUL, internal string terminator in C-Kermit. ; Also, often discarded as padding. set con p 1 ; Ctrl-A = Packet-start character. set con p 3 ; Ctrl-C = Packet breakout for remote-mode C-Kermit, ; packet breakout for server-mode MS-DOS Kermit, ; likely to cause interruptions on other systems. set con p 13 ; Ctrl-M = Carriage return, packet-end character. ; Always prefix on TELNET connections. set con p 14 ; Ctrl-N = Shift Out set con p 15 ; Ctrl-O = Shift In set con p 16 ; Ctrl-P = Commonly-used X.25/X.3 PAD escape character set con p 17 ; Ctrl-Q = XON, must be prefixed with Xon/Xoff flow control set con p 19 ; Ctrl-S = XOFF, must be prefixed with Xon/Xoff flow control set con p 27 ; Ctrl-[ = ESC, prefix if going through some kind of ANSI device set con p 28 ; Ctrl-\ = CONNECT-mode escape for C-Kermit set con p 29 ; Ctrl-] = CONNECT-mode escape for TELNET set con p 30 ; Ctrl-^ = Cisco terminal server escape. set con p 127 ; Ctrl-? = DEL, often discarded as padding. ; Also becomes TELNET IAC if parity bit is added. set con p 128 ; = NUL + 128 (i.e. NUL + parity bit) set con p 129 ; = Ctrl-A + 128 set con p 131 ; = Ctrl-C + 128 set con p 141 ; = CR + 128 set con p 145 ; = XON + 128 set con p 147 ; = XOFF + 128 set con p 255 ; 255 = TELNET IAC, must be prefixed on TCP/IP TELNET connections INCLUDING TELNET connections through terminal servers! Note, by the way, that nothing special need be done for SLIP connections, since the four special SLIP characters are in the G1 printable range: 192 SLIP END character 219 SLIP ESC character 220 SLIP END quote 221 SLIP ESC quote Here is a suggested (conservative) starting point for experimenting with control-character unprefixing. Tell the file sender to: SET CONTROL UNPREFIX ALL SET CONTROL PREFIX 0 1 3 13 17 19 127 129 131 141 145 147 255 Perhaps some of these can be removed, depending on the connection, and maybe others need to be added. If you are going through a terminal server or an intermediate Kermit or TELNET program, also add the appropriate escape character values (bare, and plus 128). PREFIXING NOTES: If C-Kermit or MS-DOS Kermit has initiated a TELNET connection, prefixing of 255 (TELNET IAC) is forced automatically. IMPORTANT WARNING: When you have a TELNET connection through a terminal server, neither one of the Kermit programs knows that it's a TELNET connection, and in this case unprefixing of 255 is NOT automatically disabled. This can cause file transfer failures. When in doubt, do not unprefix 255. Kermit will not let you unprefix XON (17), XOFF (19), XON+128 (145), or XOFF+128 (147) if its FLOW-CONTROL setting is XON/XOFF. If you want to unprefix these, make sure *both* Kermits have first been told to SET FLOW NONE (or RTS/CTS), and that XON/XOFF flow control is not in effect anywhere along the communication path between the two Kermits. When sending files to C-Kermit 189 or earlier, and C-Kermit is in remote mode, you should normally tell the file sender to SET CONTROL PREFIX 3 and SET CONTROL PREFIX 131, because C-Kermit 189 and earlier (by default) takes two Ctrl-C's (3 or 131) in a row as cancellation of packet-mode. However, you can UNPREFIX these characters if you know your files do not contain two Ctrl-C's in a row, or if you tell C-Kermit to SET TRANSFER CANCELLATION OFF, or SET TRANSFER CANCELLATION ON when you know that copies of do not occur in a row in the data. When sending files to edit 190 of C-Kermit and later, you can leave 3 and 131 unprefixed unless you have disabled repeat-count compression. 4.3. Keyboard Cancellation of Packet Mode When C-Kermit is in remote mode and in packet mode, the user no longer has normal control of the terminal. Characters typed at the keyboard do not echo, commands have no effect, etc. This is because C-Kermit is trying to read file-transfer protocol packets from your local Kermit program. If you have put C-Kermit into packet mode by giving a SEND, RECEIVE, SERVER, BYE, or similar command, but you did not mean to do this, or you do not have a local Kermit handy to exchange packets with (for example, because you neglected to give a SET LINE or SET HOST command first), you can force C-Kermit back to its prompt by typing a special sequence of characters. By default, the packet-mode interruption character is Control-C (ASCII 3). In edits 189 and earlier, two consecutive copies of this character were required to get out of packet mode, and the parity bit was always ignored. In edit 190 and later, three copies are required by default, and the parity bit is ignored if C-Kermit's PARITY setting is not NONE. On noisy connections, two or three Control-C's might show up as noise; or you might want to allow C-Kermit to accept Control-C characters literally in data packets during file transfer. The following command lets you control this feature: SET TRANSFER CANCELLATION { OFF, ON [ [ is the ASCII code for the control character (0 through 31 or 127) to be used for interruption (the default is 3 = Ctrl-C), and the optional is the number of consecutive copies of the character required to cause interruption. For example, "SET XFER CANCEL ON 6 5" tells C-Kermit to break out of packet mode upon receipt of 5 consecutive Ctrl-F (ASCII 6) characters. Note that the parity bit is ignored for this purpose, so (for example) 3 and 131 are treated the same. If you SET TRANSFER CANCELLATION OFF, you might still need a manual method of getting remote-mode C-Kermit out of packet mode. This can be accomplished by escaping back to your local Kermit and giving a RECEIVE command, then typing E (or Ctrl-E) to send an error packet. Or just type the following Kermit packet: # E* <-- This is a "fatal error" packet. If the remote Kermit is in server mode, you can send a FINISH command, or if you don't have a local Kermit to escape back to, type: $ GF4 <-- This is a FINISH command packet, for the server. The SET TRANSFER CANCELLATION command was installed for the UNIX, VMS, and DG versions of C-Kermit 5A(189). Use SHOW PROTOCOL to find out the current settings. It has affect only when C-Kermit is in remote mode; when C-Kermit has been used to establish a connection to another computer (i.e. when C-Kermit is in local mode), this feature is inactive -- there is no need for it because you have control of the program via the file-transfer interruption characters (X, Z, C, E, etc). In edit 190, the default number of packet-mode cancellation characters was raised from two to three. That is, if you are looking at a remote C-Kermit in packet mode, and have no other way to get back to the C-Kermit> prompt, you'll have to type three consecutive Control-C's (or whatever your transfer cancellation character is), instead of two, by default. This was done to allow SET CONTROL UNPREFIX n (where n = the ASCII code for the cancellation character) to work, even with the default TRANSFER CANCELLATION settings; three or more consecutive copies of any character are transformed by Kermit protocol into a repeat count plus one copy of the character, thus preventing three consecutive Control-C's from appearing as data in a Kermit packet, provided the other Kermit supports repeat-count compression (all popular Kermit implementations do) and it has been successfully negotiated (which it will be unless you take special measures to prevent it; see SET REPEAT above). 4.4. New RECEIVE Command Features In edit 190 and later, the RECEIVE command can accept a device or directory name as an argument, and all incoming files will go into the specified device or directory under the names they were sent with. If the argument is not a device or directory name, it is treated as before: as a name under which to store the (first) incoming file. This change also affects the '-a' ("as-name") command-line option. This feature depends on the symbol CK_TMPDIR being defined at compile time, plus the supporting code for each operating system. Type SHOW FEATURES to see if CK_TMPDIR is defined in your version. As of edit 190, this feature is available in the UNIX, OS/2, and VMS versions of C-Kermit. 4.5. Automatic Directory Creation File names are treated according to the SET FILE NAMES command (see p.114 of "Using C-Kermit"), CONVERTED (the default) or LITERAL. SET FILE NAMES LITERAL means: . When sending files, put the filespec into the outgoing file header packet exactly as the user typed it. What happens on the receiving end is entirely up to the receiver. . When receiving files, use the file specification from the incoming file header exactly as given, so if it happens to include a device or directory specification, C-Kermit attempts to use it, and if the device and/or directory does/do not exist or are not write-accessible, the transfer fails. SET FILE NAMES CONVERTED, which is the default, transforms outgoing filenames by (a) removing device, directory, and other "extraneous" information, (b) uppercasing all lowercase letters, (c) making sure there is no more than one period, and (d) translating all "uncommon" characters to X's. A new command allows us to strike a compromise between these two methods: SET { SEND, RECEIVE } PATHNAMES { ON, OFF } SET SEND PATHNAMES ON means to leave pathnames ON outbound file names, which is the default for compatibility with earlier behavior. Note, however, that PATHNAMES are always stripped from outbound filenames when FILE NAMES are CONVERTED, and in OS/2, disk letters are always stripped. SET SEND PATHNAMES OFF means to strip OFF path information, leaving only the file's name. SET SEND PATHNAME applies only to the filename given directly to a SEND or MSEND command, and not to the "as-name", which is always sent literally and without modification, regardless of SEND PATHNAME or FILE NAMES settings. SET RECEIVE PATHNAMES applies to the filenames in incoming file header packets; ON means to leave the name alone and attempt to use it as-is, OFF means to attempt to strip the path information ON THE ASSUMPTION that any path information found there would be in the notation of the local file system, and therefore recognizable. If not, the results are unpredictable; for example, if a file called MYVAX::DUA0:[OLAF.PICS]MONA_LISA.GIF;17 arrives on a UNIX system, UNIX C-Kermit can not be expected to distinguish the path information from the name (it is a general principle of communication protocols that a particular computer must not be expected to understand the conventions and formats of some other kind of computer). In VMS, UNIX, and OS/2, SET RECEIVE PATHNAMES has an additional meaning: If the incoming file name contains directory information (such as [.KERMIT]OOFA.TXT, kermit/oofa.txt, or C:\TEXT\LETTERS\ANGRY\OOFA.TXT) -- either absolute or relative, then, if the named directory, or any of its ancestors, does not exist, Kermit attempts to create it (or them) before opening the output file. For example, suppose your current directory (in UNIX) is /usr/olga/budget, and a file arrives under the name "aaa/bbb/ccc/ddd/bankrupt.txt", and that the /usr/olga/budget/aaa directory already exists, but it does not have a bbb subdirectory. Then Kermit will create the bbb subdirectory, and then the ccc subdirectory under bbb, and then the ddd subdirectory under ccc, and then it will store the bankrupt.txt file in the /usr/olga/budget/aaa/bbb/ccc/ddd directory. In UNIX, tilde notation for usernames (like "~olga") is recognized, and any directories that are created inherit the permissions of their parents, and the owner and group of the user who is running the Kermit program. Naturally, directory creation fails if the user lacks the appropriate permissions. Directory creation fails in OS/2 if a disk letter is included for a nonexistent or non-writable disk. Use SHOW FILE to display the SEND/RECEIVE PATHNAME settings. 4.6. Pausing Between Packets The new command: SET { SEND, RECEIVE } PAUSE tells C-Kermit to pause the given number of milliseconds (thousandths of seconds) before sending each packet. This might be necessary when communicating with certain devices or over certain kinds of connections. Don't use this except as a final resort, since it slows transfers down. SHOW PROTOCOL displays the current setting. SET SEND PAUSE and SET RECEIVE PAUSE do exactly the same thing. Edit 190. 4.7. Fullscreen File Transfer Display Improvements 4.7.1. Thermometer Versions of Kermit that support SET FILE DISPLAY FULLSCREEN now are able to show a file-transfer "thermometer" (percent bar-graph) to graphically represent the progress of the file transfer. It can be explicitly selected or deselected via the new trailing argument to this command: SET FILE DISPLAY FULLSCREEN { THERMOMETER, NO-THERMOMETER } A running display of the transfer speed in characters per second (CPS) is also shown; it is computed once per second as the total actual file characters transferred so far versus elapsed time. 4.7.2. Repainting the Screen On multiuser operating systems like UNIX and VMS, it is possible for messages to be sent to your terminal screen while Kermit is in the middle of transferring a file. If you are using the fullscreen file transfer display, this will jumble the formatting. C-Kermit has no way to know this has happened. In edit 190 and later, however, you can make C-Kermit clear and repaint the file transfer display screen by typing Ctrl-L (or L or R or r) while the display is active. Control-W is also accepted for this purpose. This will result in either a full or partial reconstruction of the display, depending on the underlying operating system. Edit 190. 4.8. Improved Status Codes Like most other C-Kermit commands, file transfer commands such as SEND, RECEIVE, GET, etc, return a status code for use with IF SUCCESS, IF FAILURE, etc. Prior to edit 190, these codes were not always accurate. In particular, if a file was rejected (for any reason at all) via the attribute refusal mechanism, success was always indicated. In edit 190, the status codes have been improved as follows: . If the transfer completes successfully, the status is success. . If a file is refused via the attribute refusal mechanism, the status is failure UNLESS the reason was "date" or "name", in which case the file was not transferred because it was already there (SET FILE COLLISION UPDATE or DISCARD), and so the transfer is considered successful. . It the transfer terminates with an error (E packet), loss of connection, etc, the status is failure. You can use SHOW STATUS after any command to test its success or failure. Also, the \v(status) variable is set to 0 if the most recent command succeeded, and to a nonzero value if it failed. (5) NEW CLIENT/SERVER FEATURES 5.1. New REMOTE Commands The following features are all new to edit 190. REMOTE PWD Allows the client to ask for the server's current directory in system-independent way. Formerly, this could only be done via system- dependent REMOTE HOST commands. The response is displayed on the screen. REMOTE SET FILE TYPE { TEXT, BINARY, LABELED } The LABELED option has been added to this command in the VMS and OS/2 versions only. Also, the file type specified in this command also takes effect locally. Previously, it was only sent to the server. Edit 190. REMOTE QUERY { KERMIT, SYSTEM, USER } Asks the server to send the value of the variable of the given type that has the given name. If the query succeeds, the value is displayed on your screen and it is also stored in a local read-only Kermit variable, \v(query) If the query fails, an error message is printed and the \v(query) variable is set to the empty string. In C-Kermit and MS-DOS Kermit, "KERMIT" variables are the \v(name) kind, such as \v(time), \v(version), \v(date), etc. "SYSTEM" variables are DOS or UNIX environment variables, such as PATH, USER, HOME, or VMS logical names, etc. USER variables are everything else -- \%a-z, \%1-9, and macro names used as long variable names. The of a KERMIT or SYSTEM variable must be given in an implementation-independent format without special syntax, e.g. TIME, DATE, VERSION, PATH, USER, etc, rather than (say) \v(time), \$(PATH). However, in most cases, case matters in system variables. The of a USER variable is given in the syntax of the server, e.g. \%a. Examples: C-Kermit>remote query kermit time 13:25:18 C-Kermit>echo The server's time is: \v(query) The server's time is: 13:25:18 C-Kermit>rem q k dir ; Note, abbreviations allowed. /usr/olga/letters C-Kermit>echo The server's current directory is: \v(query) The server's current directory is: /usr/olga/letters C-Kermit>rem q system USER olga C-Kermit>echo user = \v(query) user = olga REMOTE ASSIGN [ ] Asks the server to assign the given to the remote user variable denoted by . The is fully evaluated LOCALLY before being sent to the Kermit server. The maximum length for the value is governed by the maximum negotiated packet length, i.e. the server's RECEIVE PACKET-LENGTH. Synonym: REMOTE ASG. Examples: C-Kermit>remote assign \%a \v(time) ; Assign client's time to server's \%a C-Kermit>remote query user \%a 13:41:18 ; This is the client's time C-Kermit>rem asg myname Olga ; Assign my name to server's myname macro To force a string corresponding to a local variable name to be sent literally, use two backslashes: C-Kermit>remote assign \%a \\v(time) ; Assign "\v(time)" to server's \%a. C-Kermit>remote query user \%a 13:41:18 ; This is the server's time. C-Kermit> You can disable and enable the server's handling of REMOTE QUERY and ASSIGN with the commands: DISABLE QUERY The server should not respond to REMOTE QUERY commands DISABLE ASSIGN The server should not respond to REMOTE ASSIGN commands ENABLE QUERY The server should respond to REMOTE QUERY commands ENABLE ASSIGN The server should respond to REMOTE ASSIGN commands By default, like all other ENABLE/DISABLE items, the initial state is ENABLEd. 5.2. "WHATAMI" -- Making Kermit GET more like FTP GET Those who are accustomed to using client/server applications such as FTP expect that certain kinds of commands, when given to the client, will affect the server correspondingly. Most notable among these commands (in FTP's case) are those that set the transfer mode: BINARY, ASCII, etc. In Kermit, however, the transfer mode has always been determined by the file sender, a concept totally unrelated to the client/server distinction, and less than obvious to most people. Furthermore, Kermit programs do not always have a client/server relationship -- there is also the send/receive arrangement. C-Kermit 5A(190) and MS-DOS Kermit 3.14 (when it becomes available) implement a new "What Am I" feature, which operates transparently to the user (i.e. there are no commands to control it), and results in FTP-like operation when: 1. One Kermit program is in SERVER mode, the other is a client, AND: 2. Both Kermit programs support the WHATAMI feature. Currently, these are limited to C-Kermit 5A(190), MS-DOS Kermit 3.14. A forthcoming release of IBM Mainframe Kermit will support it too. Presently, the WHATAMI feature affects only the GET command, and addresses the following scenario: 1. User starts a Kermit server, giving it no special settings. 2. User tells the client to: SET FILE TYPE BINARY SET FILE NAMES LITERAL GET cku190.tar.Z 3. The file is transferred in text mode when the user expected a binary transfer, and the name was converted even though the user wanted it not to be changed. At the beginning of any protocol transaction, the two Kermits exchange "What Am I" information as part of the S or I packet data. This information includes (a) whether I am a client or server; (b) my transfer mode (text or binary); and (c) my file name handling (literal or converted). Then, when the server receives a GET-command packet from the client, AND if WHATAMI information has been successfully exchanged, then the server switches its file transfer mode and file name handling to the client's corresponding modes. Nothing special happens when files are sent TO the server, since this works right anyway, using the previous mechanisms. Hopefully this change will result in more pleasant surprises than unpleasant ones. One Beta tester (a seasoned Kermit user), however, was unpleasantly surprised when he sent the following commands from a client to a server: REMOTE SET FILE TYPE BINARY GET OOFA.ZIP The file arrived in text mode because the client was in text mode. The user was relying of the old rule, by which the file sender informs the file receiver of the transfer mode via the attribute packet, but since the WHATAMI exchange took place after the REMOTE SET, it changed the server's mode back to text. To cure this situation, REMOTE SET FILE TYPE now sets the local file transfer mode too. Should all this sound confusing, remember that the WHATAMI feature (and the other mechanisms for reconciling file transfer mode) make a difference only when the sender and receiver's file transfer modes do not agree. The rules can be summarized like this: 1. To be certain of the file transfer mode, give the same SET FILE TYPE command to both Kermits (exception: when VMS C-Kermit is sending a file, it determines the transfer mode for each file automatically). In case you did not do this, and the transfer modes of the two Kermit programs disagree when the file transfer starts: 2. If the file sender is VMS C-Kermit, it determines the file type automatically unless its file type has been set to IMAGE or LABELED. Otherwise: 3. If both Kermits have the WHATAMI feature, the client program's transfer mode prevails. Otherwise: 4. If both Kermit programs have Attribute-packet capability, the sender will inform the receiver of the transfer mode, and the receiver will switch to the sender's transfer mode automatically. Otherwise: 5. The transfer proceeds with each Kermit program using the transfer mode that the user has told it to use. This can result in mismatches, which are usually not what was intended. Since not all Kermit implementations -- particularly those found in commercial or shareware software packages -- implement the WHATAMI feature or Attribute packets, it is always safest to inform both Kermit programs of the transfer mode prior to file transfer. (6) INTERNATIONAL CHARACTER SETS Since "Using C-Kermit" was published: . Edit 189 of C-Kermit added support for Hebrew character sets. . Edit 190 added Hebrew terminal emulation to OS/2 C-Kermit. . Edit 190 added support for the Hewlett-Packard Roman8 character set. 6.1. Hebrew File Transfer C-Kermit 5A(189) has the following new commands for Hebrew file transfer: SET TRANSFER CHARACTER-SET HEBREW-ISO = ISO 8859-8 Latin/Hebrew Alphabet SET FILE CHARACTER-SET HEBREW-ISO = ISO 8859-8 Latin/Hebrew Alphabet SET FILE CHARACTER-SET CP862 = Hebrew PC Code Page SET FILE CHARACTER-SET HEBREW-7 = DEC 7-Bit (VT100) Hebrew These commands work just like the corresponding commands for Cyrillic character sets, described in Chapter 9 of "Using C-Kermit". When receiving files, C-Kermit recognizes Hebrew files automatically if the file sender tags the file as Hebrew in the Attribute packet, which the file sender should do if it has been given the SET TRANSFER CHARACTER-SET HEBREW command; C-Kermit does not, however, switch automatically to a Hebrew file character-set, so you must choose one in advance if that's what you want. The tag is "I6/138" (these are ISO registration numbers). When sending files in Hebrew mode, of course, C-Kermit includes the same tag. An invertible translation table between Latin/Hebrew and CP862 is used during both terminal emulation and file transfer. The translation table between Hebrew-7 and Latin/Hebrew, however, is not invertible because these character sets are different sizes. Here is an example of uploading a Hebrew file from a PC to UNIX. The PC version is coded in the Hebrew PC code page, and the UNIX version is to be stored in the 7-bit Hebrew character-set so it can be sent as network e-mail: C-Kermit> set file character-set hebrew-7 ; I want a 7-bit version for email C-Kermit> receive ; Wait for the file. ; Escape back to the PC MS-Kermit> set file type text ; Make sure we are in text mode MS-Kermit> set file character-set cp862 ; File coded in Hebrew PC code page MS-Kermit> set xfer character-set hebrew ; Send using ISO Latin/Hebrew MS-Kermit> send rab.oof ; Send the file The file sender automatically tells the file receiver that the transfer character-set is Hebrew. The three Hebrew character sets are also available for use in C-Kermit's TRANSLATE command, which translates a local file from one character-set to another. Thus you can use C-Kermit to convert a local file from, say, Latin/Hebrew to Hebrew-7. C-Kermit's Hebrew file transfer features can be used in conjunction with MS-DOS Kermit 3.13 and later (with which C-Kermit shares the same translation tables to ensure consistent translations) and IBM Mainframe Kermit 4.2 or later, which translates between Latin/Hebrew and IBM CECP 424 (the Hebrew EBCDIC Country Extended Code Page). 6.2. Hebrew Terminal Emulation NOTE: See the OS/2 C-Kermit section of this document (below) for details about Hebrew terminal emulation in OS/2 C-Kermit. There is no support for right-to-left screen-writing direction or other terminal emulation features in C-Kermit, since C-Kermit (except the OS/2 and Macintosh versions) does not do terminal emulation itself, but just provides a terminal-independent "pipe" to your terminal emulator. However, you can still have C-Kermit provide the character translations during CONNECT mode: SET TERMINAL CHARACTER-SET { HEBREW-ISO, HEBREW-7, CP862 } [ local-cset ] The terminal character-set affects not only CONNECT mode, but also the session log and the TRANSMIT command. You can test for the presence of Hebrew support in your version of C-Kermit using the CHECK HEBREW command or the SHOW FEATURES command. 6.3. The Hewlett Packard Roman8 Character Set C-Kermit 5A(190) adds support for Hewlett Packard ROMAN8 as a file character-set and a terminal character-set. This is an 8-bit character-set roughly equivalent, but not identical, to Latin-1, and (of course) with entirely different encoding. The translations between HP ROMAN8 and Latin-1 are invertible. (7) SCRIPT PROGRAMMING 7.1. New IF Commands IF DIRECTORY succeeds if is the name of a directory or a file-structured device, fails otherwise. Available, as of edit 190, in UNIX, VMS, and OS/2. IF NEWER compares modification (or creation) date/times of two files, succeeds if first file is newer than second file. Edit 190. IF REMOTE-ONLY succeeds if C-Kermit was started with the -R (uppercase) command-line option, fails otherwise. This lets you advise C-Kermit that you only intend to use it in remote mode; the initialization and customization files can (and the standard ones do) include IF REMOTE-ONLY commands to skip over time-and-space-consuming items, such as the dialing and services directories, that will not be used in remote mode. This allows Kermit to start more quickly. For examples of use, see the standard initialization file, ckermit.ini / .kermrc. Edit 190. IF EQUAL, IF LLT, IF LGT string comparison commands, as of edit 190, allow the use of braces around comparands that contain imbedded spaces, for example: IF EQUAL {\%a} {sentence with four words} echo They are equal. Prior to edit 190, constructions like this would cause a parse error (see p.239, "Using C-Kermit"). Be sure to use braces around both items. 7.2. New \v() Variables \v(charset) C-Kermit's local character set. Use this (e.g.) in scripts for deciding which character set to use when printing screen messages. \v(connection) When C-Kermit has made a SET LINE or SET HOST connection, this variable tells the connection type: "serial", "tcp/ip telnet", "decnet lat", "decnet cterm", "x.25", etc. If C-Kermit is in remote mode -- i.e. it has not made a connection to another computer -- the value of this variable is "remote". \v(cps) gives speed in characters (bytes) per second of the most recent file transfer. If a group of files was transferred, the figure applies to the whole group. \v(dialstatus) contains a numeric result code for the most recent DIAL command: -1 No DIAL command given yet 0 DIAL succeeded 1 Modem type not specified 2 Communication device not specified 3 Device can't be opened 4 Communication speed not specified 5 Hangup failure 6 Internal error (memory allocation, etc) 7 Device input/output error 8 DIAL TIMEOUT expired 9 Dialing interrupted by user 10 Modem not ready 11-19 (reserved) 20 Modem command error 21 Failure to initialize modem 22 Phone busy 23 No carrier 24 No dialtone 25 Ring (incoming call) 26 No answer 27 Disconnected 28 Answered by voice 29 Access denied, forbidden call 98 Unknown error 99 Unspecified failure detected by modem \v(evaluate) = result of most recent EVALUATE command \v(ftype) = current FILE TYPE setting: "text" or "binary". In OS/2 and VMS, also "labeled". In VMS only, also "image". \v(keyboard) (OS/2 only), the keyboard model: "88", "101", or "122". \v(modem) = current modem type (SET MODEM value). \v(parity) = current PARITY setting: "even", "odd", "mark", "none", or "space". \v(newline) is the newline character or sequence appropriate to the operating system where C-Kermit is running, for example linefeed (\10) for UNIX, carriage return (\13) for OS-9, carriage-return linefeed (\13\10) for OS/2. \v(minput) = number telling which MINPUT search string was matched: 0 = none of them; 1 = the first one, etc. (see section on MINPUT below). \v(rexx) (os/2 32-bit only) = the return value from the last Rexx command issued. \v(rows) = the number of rows (lines) on the console terminal / screen, i.e. its length, -1 if unknown. \v(cols) = the number of columns on the console terminal / screen, i.e. its width, -1 if unknown.. \v(terminal) = terminal type, if known, otherwise "unknown". \v(query) = result of most recent REMOTE QUERY command. \v(space) = number of free bytes on current storage device (OS/2 only). \v(startup) (OS/2 only) Disk:Directory from which C-Kermit was started. \v(sysid) = Kermit system/OS code, from pp.275-278 of the Kermit book: U8 = MS-DOS (and Windows) U1 = UNIX D7 = VMS UD = OS-9 L3 = Amiga A3 = Macintosh UO = OS/2 F3 = AOS/VS K2 = Atari ST MV = Stratus VOS etc... 7.3. New \f() Functions \Fdate(filename) returns the modification (or creation) date of the given file in "yyyymmdd hh:mm:ss" format, or else the empty string upon failure. As of edit 190, available in UNIX, VMS, and OS/2 versions. \Freplace(s1,s2,s3). This function replaces all occurrences of the string s2 in the string s1 by the string s3. s1 and s2 must be at least one character long. s3 can be omitted, in which case all occurrences of s2 are removed from s1. If s2 is omitted, s1 is returned unchanged. Examples: \freplace(oofa,o,O) = OOfa \freplace(oofa,o,oo) = oooofa \freplace(oofa,o) = fa \freplace(oofa) = oofa or (more practically for OS/2): \freplace(\v(cmdfile),\\,/) ; replace backslashes by forward slashes \Fsize(filename) tells the size, in characters (bytes), of the given file. 7.4. INPUT and OUTPUT Command Improvements As of edit 190, the INPUT and OUPUT commands are buffered, which results in greater speed of execution. The new command: SET OUTPUT PACING causes C-Kermit to pause for (at least) the indicated number of milliseconds (thousandths of a second) between each character in the OUTPUT string. Use this option when OUTPUT'ing characters to a device that can't receive characters at the full communication speed without losing or garbling them. The default OUTPUT PACING is 0, i.e. no pauses. Display with SHOW SCRIPTS. Edit 189. The OUTPUT command accepts three special notations for sending special signals or characters: \B or \b or \\B or \\b Send a BREAK signal. On serial connections, this is a 250 millisecond spacing condition. On network connections, it is a network-specific BREAK protocol message, such as a TELNET BREAK. \L or \l or \\L or \\l Send a Long BREAK signal. On serial connections, this is a 1.5-second spacing condition. On network connections, it is the same as \B (BREAK). \N or \n Send a NUL (ASCII 0) character. \0 can't be used for this because it is the terminator for C-language strings. (\N is new to edit 190.) If you need to send \B, \L, or \N literally (e.g. to configure certain kinds of modems), you can use either: OUTPUT \fliteral(\B) (or \fliteral(\L) or \fliteral(\N)) or: OUTPUT \\\\B (or \\\\L or \\\\N) (yes, four backslashes). Note: \fliteral() can be abbreviated, e.g. \flit(\N). 7.5. The New MINPUT Command The new command, MINPUT ("multiple input") is a version of the INPUT command that looks for more than one string. Syntax: MINPUT [ string1 [ string2 [ string2 [ ... ] ] ] ] Strings are separated by spaces. If any of the search strings is encountered within the timeout interval, the command succeeds and the \v(minput) variable is set to the number of the string that was found: 1, 2, 3, etc. If none of the search strings is found, the command times out, fails, and \v(minput) is set to 0. All SET INPUT paramaters apply - SET INPUT CASE, etc. Example: minput 30 Login:, Username:, Ready if success goto LBL\v(minput) end 1 Prompt didn't arrive. looks for any of the three strings "Login:", "Username:", or "Ready" and then goes to one of the labels "LBL1", "LBL2", or "LBL3", depending on which string was matched. To include a space in a string, enclose it in { braces }. minput 20 {a b} c This searches for either "a b" or "c". As in the regular INPUT and REINPUT commands, leading and trailing spaces are stripped from each search string unless it is enclosed in { braces }. Example: minput 20 { abc }, {{ def }}, ghi searches for " abc ", "{ def }", or "ghi". 7.6. Other New or Improved Script Programming Commands EVALUATE The new EVALUATE command evaluates arithmetic expressions for you, printing the answer. It is exactly like the \feval() function described in the book, but for interactive use: you can type the expression directly, and the answer is printed, e.g.: C-Kermit> evaluate 1+1 2 C-Kermit> eval 6! 720 C-Kermit> def \%a (7 + 8) C-Kermit> ev (1 + 2) * (\%a - 3) 36 FORWARD