File CKERMIT2.TXT, Supplement to "Using C-Kermit", Second Edition D R A F T As of C-Kermit version: 7.0.197 This file last updated: 8 February 2000 Authors: Frank da Cruz and Christine M. Gianone Address: The Kermit Project Columbia University 612 West 115th Street New York NY 10025-7799 USA Fax: +1 (212) 662-6442 E-Mail: kermit-support@columbia.edu Web: http://www.columbia.edu/kermit/ Or: http://www.kermit-project.org/ Or: http://www.columbia.nyc.ny.us/kermit/ NOTICES: This document: Copyright (C) 1997, 2000, Frank da Cruz and Christine M. Gianone. All rights reserved. Kermit 95: Copyright (C) 1995, 2000, Trustees of Columbia University in the City of New York. All rights reserved. C-Kermit: Copyright (C) 1985, 2000, Trustees of Columbia University in the City of New York. All rights reserved. See the C-Kermit COPYING.TXT file or the copyright text in the ckcmai.c module for disclaimer and permissions. When Kerberos(TM) and/or SRP(TM) (Secure Remote Password) and/or SSL protocol are included: Portions Copyright (C) 1990, Massachusetts Institute of Technology. Portions Copyright (C) 1991, 1993 Regents of the University of California. Portions Copyright (C) 1991, 1992, 1993, 1994, 1995 by AT&T. Portions Copyright (C) 1997, Stanford University. Portions Copyright (C) 1995-1997, Eric Young . For the full text of the third-party copyright notices, see Appendix V. ------------------------------ WHAT IS IN THIS FILE This file lists changes made to C-Kermit since the second edition of the book "Using C-Kermit" was published and C-Kermit 6.0 was released in November 1996. Use this file as a supplement to the second edition of "Using C-Kermit" until the third edition is published some time in 2000. 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 CKCBWR.TXT ("C-Kermit beware") file for hints, tips, tricks, restrictions, frequently asked questions, etc, plus the system-specific "beware file", e.g. CKUBWR.TXT for UNIX, CKVBWR.TXT for VMS, etc, and also any system-specific update files such as KERMIT95.HTM for Kermit 95 (in the DOCS\MANUAL\ subdirectory of your K95 directory). IMPORTANT: A major new feature of C-Kermit 7.0 is its ability to be an Internet Kermit Services Daemon (IKSD), as well as an IKSD client. All of this is described in a separate file, IKSD.TXT. --------------- ABOUT FILENAMES In this document, filenames are generally shown in uppercase, but on file systems with case-sensitive names such as UNIX, OS-9, and AOS/VS, lowercase names are used: ckcbwr.txt, ckermit2.txt, etc. ---------------- ADDITIONAL FILES Several other files accompany this new Kermit release: SECURITY.TXT Discussion of Kermit's new authentication and encryption features. IKSD.TXT How to install and manage an Internet Kermit Service Daemon. TELNET.TXT A thorough presentation of Kermit's new advanced Telnet features and controls. ------------------------ THE NEW C-KERMIT LICENSE The C-Kermit license was rewritten for version 7.0 to grant automatic permission to packagers of free operating-system distributions to include C-Kermit 7.0. Examples include Linux (GNU/Linux), FreeBSD, NetBSD, etc. The new license is in the COPYING.TXT file, and is also displayed by C-Kermit itself when you give the VERSION or COPYRIGHT command. The new C-Kermit license does not apply to Kermit 95. --------------- ACKNOWLEDGMENTS Thanks to Jeff Altman, who joined the Kermit Project in 1995, for much of what you see in C-Kermit 7.0, especially in the networking and security areas, and his key role in designing and implementing the Internet Kermit Service Daemon. And special thanks to Lucas Hart for lots of help with the VMS version; to Peter Eichhorn for continuous testing on the full range of HP-UX versions and for a consolidated set of HP-UX makefile targets; and to Colin Allen, Mark Allen, Roger Allen, Ric Anderson, William Bader, Mitch Baker, Mitchell Bass, Nelson Beebe, Gerry Belanger, Jeff Bernsten, Mark Berryman, John Bigg, Volker Borchert, Jonathan Boswell, Tim Boyer, Frederick Bruckman, Kenneth Cochran, Jared Crapo, Bill Delaney, Igor Sobrado Delgado, Clarence Dold, Joe Doupnik, John Dunlap, Max Evarts, Patrick French, Carl Friedberg, Carl Friend, Hirofumi Fujii, Andrew Gabriel, Gabe Garza, Boyd Gerber, David Gerber, George Gilmer, Hunter Goatley, DJ Hagberg, Kevin Handy, Andy Harper, Randolph Herber, Sven Holstrum, Michal Jaegermann, Graham Jenkins, Dick Jones, Terry Kennedy, Robert D Keys, Nick Kisseberth, Igor Kovalenko, David Lane, Adam Laurie, Jeff Liebermann, Eric Lonvick, Hoi Wan Louis, Arthur Marsh, Gregorie Martin, Peter Mauzey, Dragan Milicic, Todd Miller, Christian Mondrup, Daniel Morato, Dat Nguyen, Herb Peyerl, Jean-Pierre Radley, Mitchell Pilot, Steve Rance, Stephen Riehm, Nigel Roles, Larry Rosenman, Jay S Rouman, David Sanderson, John Santos, Michael Schmitz, Steven Schultz, Bob Shair, Richard Shuford, Fred Smith, Michael Sokolov, Jim Spath, Peter Szell, Ted T'so, Brian Tillman, Linus Torvalds, Patrick Volkerding, Martin Vorlaender, Steve Walton, Ken Weaverling, John Weekley, Martin Whitaker, Jim Whitby, Matt Willman, Joellen Windsor, Farrell Woods, and many others for binaries, hosting, reviews, suggestions, advice, bug reports, and all the rest over the 3+ year C-Kermit 7.0 development cycle. Thanks to Russ Nelson and the board of the Open Software Initiative for their cooperation in developing the new C-Kermit license and to the proprietors of those free UNIX distributions that have incorporated C-Kermit 7.0 for their cooperation and support, especially FreeBSD's Joerg Wunsch. ----------------------- NOTE TO KERMIT 95 USERS Like the book "Using C-Kermit", this file concentrates on the aspects of C-Kermit that are common to all versions: UNIX, VMS, VOS, AOS/VS, etc. Please refer to your Kermit 95 documentation for information that is specific to Kermit 95. C-Kermit 7.0 corresponds to Kermit 95 1.1.18. ------------------------------------- C-KERMIT VERSIONS AND VERSION NUMBERS "C-Kermit" refers to all the many programs that are compiled in whole or in part from common C-language source code, comprising: . A Kermit file transfer protocol module . A command parser and script execution module . A modem-dialing module . A network support module . A character-set translation module. and several others. These "system-independent" modules are combined with system-dependent modules for each platform to provide the required input/output functions, and also in some cases overlaid with an alternative user interface, such as Macintosh Kermit's point-and-click interface, and in some cases also a terminal emulator, as Kermit 95. The C-Kermit version number started as 1.0, ... 3.0, 4.0, 4.1 and then (because of confusion at the time with Berkeley UNIX 4.2), 4B, 4C, and so on, with the specific edit number in parentheses, for example 4E(072) or 5A(188). This scheme was used through 5A(191), but now we have gone back to the traditional numbering scheme with decimal points: major.minor.edit; for example 7.0.196. Internal version numbers (the \v(version) variable), however, are compatible in C-Kermit 5A upwards. Meanwhile, C-Kermit derivatives for some platforms (Windows, Macintosh) might go through several releases while C-Kermit itself remains the same. These versions have their own platform-specific version numbers, such as Kermit 95 1.1.1, 1.1.2, and so on. C-Kermit Version History: 1.0 1981-1982 Command-line only, 4.2 BSD UNIX only 2.0 (*) (who remembers...) 3.0 May 1984 Command-line only, supports several platforms 4.0-4.1 Feb-Apr 1985 (*) First interactive and modular version 4C(050) May 1985 4D(060) April 1986 4E(066) August 1987 Long packets 4E(068) January 1988 4E(072) January 1989 4F(095) August 1989 (*) Attribute packets 5A(188) November 1992 Scripting, TCP/IP, sliding windows, ANSI C (1) 5A(189) September 1993 Control-char unprefixing 5A(190) October 1994 Recovery 5A(191) April 1995 OS/2 only - VT220 emulation 6.0.192 September 1996 Intelligent dialing, autodownload, lots more (2) 6.1.193 1997-98 (*) Development only 6.1.194 June 1998 K95 only - switches, directory recursion, more 7.0.195 August 1999 IKSD + more (CU only as K95 1.1.18-CU) 7.0.196 1 January 2000 Unicode, lots more 7.0.197 8 February 2000 Same as 196 but builds on additional platforms(3) (*) Never formally released (4.0 was a total rewrite) (1) "Using C-Kermit", 1st Edition. (2) "Using C-Kermit", 2nd Edition. (3) There is no functional difference between 196 and 197, not even bug fixes. The only changes are to #ifdefs, declarations, and the makefile, sufficient to make it build on several platforms where 196 did not build. Binaries that announce themselves as 197 are functionally identical to 196 binaries. ------------------------------ CONTENTS I. C-KERMIT DOCUMENTATION: Information about the C-Kermit manual II. NEW FEATURES: Documentation for Features Added Since C-Kermit 6.0 (0) INCOMPATIBILITIES WITH PREVIOUS RELEASES (1) PROGRAM AND FILE MANAGEMENT AND COMMANDS 1.0. Bug fixes 1.1. Command Continuation 1.2. Editor Interface 1.3. Web Browser and FTP Interface 1.4. Command Editing 1.5. Command Switches 1.5.1. General Switch Syntax 1.5.2. Order and Effect of Switches 1.5.3. Distinguishing Switches from Other Fields 1.5.4. Standard File Selection Switches 1.5.5. Setting Preferences for Different Commands 1.6. Dates and Times 1.7. Partial Completion of Keywords 1.8. Command Recall 1.9. EXIT Messages 1.10. Managing Keyboard Interruptions 1.11. Taming the Wild Backslash -- Part Deux 1.11.1. Background 1.11.2. Kermit's Quoting Rules 1.11.3. Passing DOS Filenames from Kermit to Shell Commands 1.11.4. Using Variables to Hold DOS Filenames 1.11.5. Passing DOS Filenames as Parameters to Macros 1.11.6. Passing DOS File Names from Macro Parameters to the DOS Shell 1.11.7. Passing DOS Filenames to Kermit from the Shell 1.12. Debugging 1.13. Logs 1.14. Automatic File-Transfer Packet Recognition at the Command Prompt 1.15. The TYPE Command 1.16. The RESET Command 1.17. The COPY and RENAME Commands 1.18. The MANUAL Command 1.19. String and Filename Matching Patterns 1.20. Multiple Commands on One Line 1.21. What Do I Have? 1.22. Generalized File Input and Output 1.22.1. Why Another I/O System? 1.22.2. The FILE Command 1.22.3. FILE Command Examples 1.22.4. Channel Numbers 1.22.5. FILE Command Error Codes 1.22.6. File I/O Variables 1.22.7. File I/O Functions 1.22.8. File I/O Function Examples 1.23. The EXEC Command 1.24. Getting Keyword Lists with '?' (2) MAKING AND USING CONNECTIONS 2.0. SET LINE and SET HOST Command Switches 2.1. Dialing 2.1.1. The Dial Result Message 2.1.2. Long-Distance Dialing Changes 2.1.3. Forcing Long-Distance Dialing 2.1.4. Exchange-Specific Dialing Decisions 2.1.5. Cautions about Cheapest-First Dialing 2.1.6. Blind Dialing (Dialing with No Dialtone) 2.1.7. Trimming the Dialing Dialog 2.1.8. Controlling the Dialing Speed 2.1.9. Pretesting Phone Number Conversions 2.1.10. Greater Control over Partial Dialing 2.1.11. New DIAL-related Variables and Functions 2.1.12. Increased Flexibility of PBX Dialing 2.1.13. The DIAL macro - Last-Minute Phone Number Conversions 2.1.14. Automatic Tone/Pulse Dialing Selection 2.1.15. Dial-Modifier Variables 2.1.16. Giving Multiple Numbers to the DIAL Command 2.2. Modems 2.2.1. New Modem Types 2.2.2. New Modem Controls 2.3. TELNET and RLOGIN 2.3.0. Bug Fixes 2.3.1. Telnet Binary Mode Bug Adjustments 2.3.2. VMS UCX Telnet Port Bug Adjustment 2.3.3. Telnet New Environment Option 2.3.4. Telnet Location Option 2.3.5. Connecting to Raw TCP Sockets 2.3.6. Incoming TCP Connections 2.4. The EIGHTBIT Command 2.5. The Services Directory 2.6. Closing Connections 2.7. Using C-Kermit with External Communication Programs 2.7.0. C-Kermit over tn3270 and tn5250 2.7.1. C-Kermit over Telnet 2.7.2. C-Kermit over Rlogin 2.7.3. C-Kermit over Serial Communication Programs 2.7.4. C-Kermit over Secure Network Clients 2.7.4.1. SSH 2.7.4.2. SSL 2.7.4.3. SRP 2.7.4.4. SOCKS 2.7.4.5. Kerberos and SRP 2.8. Scripting Local Programs 2.9. X.25 Networking 2.9.1. IBM AIXLink/X.25 Network Provider Interface for AIX 2.9.2. HP-UX X.25 2.10. Additional Serial Port Controls 2.11. Getting Access to the Dialout Device 2.12. The Connection Log 2.13. Automatic Connection-Specific Flow Control Selection 2.14. Trapping Connection Establishment and Loss 2.15. Contacting Web Servers with the HTTP Command (3) TERMINAL CONNECTION 3.1. CONNECT Command Switches 3.2. Triggers 3.3. Transparent Printing 3.4. Binary and Text Session Logs (4) FILE TRANSFER AND MANAGEMENT 4.0. Bug Fixes, Minor Changes, and Clarifications 4.1. File-Transfer Filename Templates 4.1.1. Templates in the As-Name 4.1.2. Templates on the Command Line 4.1.3. Post-Transfer Renaming 4.2. File-Transfer Pipes and Filters 4.2.1. Introduction 4.2.1.1. Terminology 4.2.1.2. Notation 4.2.1.3. Security 4.2.2. Commands for Transferring from and to Pipes 4.2.2.1. Sending from a Command 4.2.2.2. Receiving to a Command 4.2.3. Using File-Transfer Filters 4.2.3.1. The SEND Filter 4.2.3.2. The RECEIVE Filter 4.2.4. Implicit Use of Pipes 4.2.5. Success and Failure of Piped Commands 4.2.6. Cautions about Using Pipes to Transfer Directory Trees 4.2.7. Pipes and Encryption 4.2.8. Commands and Functions Related to Pipes 4.2.8.1. The OPEN !READ and OPEN !WRITE Commands 4.2.8.2. The REDIRECT Command 4.2.8.3. Receiving Mail and Print Jobs 4.2.8.4. Pipe-Related Functions 4.3. Automatic Per-File Text/Binary Mode Switching 4.3.1. Exceptions 4.3.2. Overview 4.3.3. Commands 4.3.4. Examples 4.4. File Permissions 4.4.1. When ATTRIBUTES PROTECTION is OFF 4.4.1.1. Unix 4.4.1.2. VMS 4.4.2. When ATTRIBUTES PROTECTION is ON 4.4.2.1. System-Specific Permissions 4.4.2.1.1. UNIX 4.4.2.1.2. VMS 4.4.2.2. System-Independent Permissions 4.5. File Management Commands 4.5.1. The DIRECTORY Command 4.5.2. The CD and BACK Commands 4.5.2.1. Parsing Improvements 4.5.2.2. The CDPATH 4.5.3. Creating and Removing Directories 4.5.4. The DELETE and PURGE Commands 4.6. Starting the Remote Kermit Server Automatically 4.7. File-Transfer Command Switches 4.7.1. SEND Command Switches 4.7.2. GET Command Switches 4.7.3. RECEIVE Command Switches 4.8. Kermit Protocol Improvements 4.8.1. Multiple Attribute Packets 4.8.2. Very Short Packets 4.9. Wildcard / File Group Expansion 4.9.1. In UNIX C-Kermit 4.9.2. In Kermit 95 4.9.3. In VMS, AOS/VS, OS-9, VOS, etc. 4.10. Additional Pathname Controls 4.11. Recursive SEND and GET: Transferring Directory Trees 4.11.1. Command-Line Options 4.11.2. The SEND /RECURSIVE Command 4.11.3. The GET /RECURSIVE Command 4.11.4. New and Changed Functions 4.11.5. Moving Directory Trees Between Like Systems 4.11.6. Moving Directory Trees Between Unlike Systems 4.12. Where Did My File Go? 4.13. File Output Buffer Control 4.14. Improved Responsiveness 4.15. Doubling and Ignoring Characters for Transparency 4.16. New File-Transfer Display Formats 4.17. New Transaction Log Formats 4.17.1. The BRIEF Format 4.17.2. The FTP Format 4.18. Unprefixing NUL 4.19. Clear-Channel Protocol 4.20. Streaming Protocol 4.20.1. Commands for Streaming 4.20.2. Examples of Streaming 4.20.2.1. Streaming on Socket-to-Socket Connections 4.20.2.2. Streaming on Telnet Connections 4.20.2.3. Streaming with Limited Packet Length 4.20.2.4. Streaming on Dialup Connections 4.20.2.5. Streaming on X.25 Connections 4.20.3. Streaming - Preliminary Conclusions 4.21. The TRANSMIT Command 4.22. Coping with Faulty Kermit Implementations 4.22.1. Failure to Accept Modern Negotiation Strings 4.22.2. Failure to Negotiate 8th-bit Prefixing 4.22.3. Corrupt Files 4.22.4. Spurious Cancellations 4.22.5. Spurious Refusals 4.22.6. Failures during the Data Transfer Phase 4.22.7. Fractured Filenames 4.22.8. Bad File Dates 4.23. File Transfer Recovery 4.24. FILE COLLISION UPDATE Clarification 4.25. Autodownload Improvements (5) CLIENT/SERVER 5.0. Hints 5.1. New Command-Line Options 5.2. New Client Commands 5.3. New Server Capabilities 5.3.1. Creating and Removing Directories 5.3.2. Directory Listings 5.4. Syntax for Remote Filenames with Embedded Spaces 5.5. Automatic Orientation Messages upon Directory Change 5.6. New Server Controls 5.7. Timeouts during REMOTE HOST Command Execution (6) INTERNATIONAL CHARACTER SETS 6.0. ISO 8859-15 Latin Alphabet 9 6.1. The HP-Roman8 Character Set 6.2. Greek Character Sets 6.3. Additional Latin-2 Character Sets 6.4. Additional Cyrillic Character Sets 6.5. Automatic Character-Set Switching 6.6. Unicode 6.6.1. Overview of Unicode 6.6.2. UCS Byte Order 6.6.2. UCS Transformation Formats 6.6.3. Conformance Levels 6.6.4. Relationship of Unicode with Kermit's Other Character Sets 6.6.5. Kermit's Unicode Features 6.6.5.1. File Transfer 6.6.5.2. The TRANSLATE Command 6.6.5.3. Terminal Connection 6.6.5.4. The TRANSMIT Command 6.6.5.5. Summary of Kermit Unicode Commands 6.7. Client/Server Character-Set Switching (7) SCRIPT PROGRAMMING 7.0. Bug Fixes 7.1. The INPUT Command 7.1.1. INPUT Timeouts 7.1.2. New INPUT Controls 7.1.3. INPUT with Pattern Matching 7.1.4. The INPUT Match Result 7.2. New or Improved Built-In Variables 7.3. New or Improved Built-In Functions 7.4. New IF Conditions 7.5. Using More than Ten Macro Arguments 7.6. Clarification of Function Call Syntax 7.7. Autodownload during INPUT Command Execution 7.8. Built-in Help for Functions. 7.9. Variable Assignments 7.9.1. Assignment Operators 7.9.2. New Assignment Commands 7.10. Arrays 7.10.1. Array Initializers 7.10.2. Turning a String into an Array of Words 7.10.3. Arrays of Filenames 7.10.4. Automatic Arrays 7.10.5. Sorting Arrays 7.10.6. Displaying Arrays 7.10.7. Other Array Operations 7.10.8. Hints for Using Arrays 7.10.9. Do-It-Yourself Arrays 7.10.10. Associative Arrays 7.11. OUTPUT Command Improvements 7.12. Function and Variable Diagnostics 7.13. Return Value of Macros 7.14. The ASSERT, FAIL, and SUCCEED Commands. 7.15. Using Alarms 7.16. Passing Arguments to Command Files 7.17. Dialogs with Timed Responses 7.18. Increased Flexibility of SWITCH Case Labels 7.19. "Kerbang" Scripts 7.20. IF and XIF Statement Syntax 7.20.1. The IF/XIF Distinction 7.20.2. Boolean Expressions (The IF/WHILE Condition) 7.21. Screen Formatting and Cursor Control 7.22. Evaluating Arithmetic Expressions 7.23. Floating-Point Arithmetic 7.24. Tracing Script Execution 7.25. Compact Substring Notation 7.26. New WAIT Command Options 7.26.1. Waiting for Modem Signals 7.26.2. Waiting for File Events 7.27. Relaxed FOR and SWITCH Syntax (8) USING OTHER FILE TRANSFER PROTOCOLS (9) COMMAND-LINE OPTIONS 9.0. Extended-Format Command-Line Options 9.1. Command Line Personalities 9.2. Built-in Help for Command Line Options 9.3. New Command-Line Options (10) C-KERMIT AND G-KERMIT III. APPENDICES III.1. Character Set Tables III.1.1. The Hewlett Packard Roman8 Character Set III.1.2. Greek Character Sets III.1.2.1. The ISO 8859-7 Latin / Greek Alphabet III.1.2.2. The ELOT 927 Character Set III.1.2.3. PC Code Page 869 III.2. Updated Country Codes IV. ERRATA & CORRIGENDA: Corrections to "Using C-Kermit" 2nd Edition. V. ADDITIONAL COPYRIGHT NOTICES ------------------------------ I. C-KERMIT DOCUMENTATION The user manual for C-Kermit is: Frank da Cruz and Christine M. Gianone, "Using C-Kermit", Second Edition, Digital Press / Butterworth-Heinemann, Woburn, MA, 1997, 622 pages, ISBN 1-55558-164-1. The present document is a supplement to "Using C-Kermit" 2nd Ed, not a replacement for it. US single-copy price: $44.95; quantity discounts available. Available in bookstores or directly from Columbia University: The Kermit Project Columbia University 612 West 115th Street New York NY 10025-7799 USA Telephone: +1 (212) 854-3703 Fax: +1 (212) 663-8202 Domestic and overseas orders accepted. Price: US $44.95 (US, Canada, and Mexico). Shipping: $4.00 within the USA; $15.00 to all other countries. Orders may be paid by MasterCard or Visa, or prepaid by check in US dollars. Add $65 bank fee for checks not drawn on a US bank. 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) +27 (31) 2683111 (Durban office for South Africa) A German-language edition of the First 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 88,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 52-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: $39.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 comp.protocols.kermit.announce and comp.protocols.kermit.misc newsgroups. ------------------------------ II. NEW FEATURES Support for the Bell Labs Plan 9 operating system was added to version 6.0 too late to be mentioned in the book (although it does appear on the cover). Specific changes and additions are grouped together by major topic, roughly corresponding to the chapters of "Using C-Kermit". (0) INCOMPATIBILITIES WITH PREVIOUS RELEASES C-Kermit 7.0 uses FAST Kermit protocol settings by default. This includes "unprefixing" of certain control characters. Because of this, file transfers that worked with previous releases might not work in the new release (but it is more likely that they will work, and much faster). If a transfer fails, you'll get a context-sensitive hint suggesting possible causes and cures. C-Kermit 7.0 transfers files in BINARY mode by default. To restore the previous behavior, put SET FILE TYPE TEXT in your C-Kermit initialization file. No matter whether FILE TYPE is BINARY or TEXT by default, C-Kermit 7.0 now switches between text and binary mode automatically on a per-file basis according to various criteria, including (a) which kind of platform is on the other end of the connection (if known), (b) the version of Kermit on the other end, and (c) the file's name (see Sections 4 and 4.3). To disable this automatic switching and restore the earlier behavior, put SET TRANSFER MODE MANUAL in your C-Kermit initialization file. To disable automatic switching for a particular transfer, include a /TEXT or /BINARY switch with your SEND or GET command. The RESEND and REGET commands automatically switch to binary mode; previously if RESEND or REGET were attempted when FILE TYPE was TEXT, these commands would fail immediately, with a message telling you they work only when the FILE TYPE is BINARY. Now they simply do this for you. See section 4.23 for additional (important) information. SET PREFIXING CAUTIOUS and MINIMAL now both prefix linefeed (10 and 138) in case rlogin or cu are "in the middle", since otherwise ~ might appear in Kermit packets, and this would rlogin or cu to disconnect, suspend, escape back, or otherwise wreck the file transfer. Xon and Xoff are now always prefixed too, even when Xon/Xoff flow control is not in effect, since unprefixing them has proven dangerous on TCP/IP connections. In UNIX, VMS, Windows, and OS/2, the DIRECTORY command is built into C-Kermit itself rather than implemented by running an external command or program. The built-in command might not behave the way the platform-specific external one did, but many options are available for customization. Of course the underlying platform-specific command can still be accessed with "!", "@", or "RUN" wherever the installation does not forbid. In UNIX, the "ls" command can be accessed directly as "ls" in C-Kermit. See Section 4.5.1 for details. SEND ? prints a list of switches rather than a list of filenames. If you want to see a list of filenames, use a (system-dependent) construction such as SEND ./? (for UNIX, Windows, or OS/2), SEND []? (VMS), etc. See Sections 1.5 and 4.7.1. In UNIX, OS-9, and Kermit 95, the wildcard characters in previous versions were * and ?. In C-Kermit 7.0 they are *, ?, [, ], {, and }, with dash used inside []'s to denote ranges and comma used inside {} to separate list elements. If you need to include any of these characters literally in a filename, precede each one with backslash (\). See Section 4.9. SET QUIET { ON, OFF } is now on the command stack, just like SET INPUT CASE, SET COUNT, SET MACRO ERROR, etc, as described on p.458 of "Using C-Kermit", 2nd Edition. This allows any macro or command file to SET QUIET ON or OFF without worrying about saving & restoring the global QUIET value. For example, this lets you write a script that tries SET LINE on lots of devices until it finds one free without spewing out loads of error messages, and also without disturbing the global QUIET setting, whatever it was. Because of the new "." operator (which introduces assignments), macros whose names begin with "." can not be invoked "by name". However, they still can be invoked with DO. The syntax of the EVALUATE command has changed. See Section 7.9.2. To restore the previous syntax, use SET EVALUATE OLD. The \v(directory) variable now includes the trailing directory separator; in previous releases it did not. This is to allow constructions such as: cd \v(dir)tmp to work across platforms that might have different directory notation, such as UNIX, Windows, and VMS. Prior to C-Kermit 7.0, the FLOW-CONTROL setting was global and sticky. In C-Kermit 7.0, there is an array of default flow-control values for each kind of connection, that are applied automatically at SET LINE/PORT/HOST time. Thus a SET FLOW command given before SET LINE/PORT/HOST is likely to be undone. Therefore SET FLOW can be guaranteed to have the desired effect only if given after the SET LINE/PORT/HOST command. Character-set translation works differently in the TRANSMIT command when (a) the file character-set is not the same as the local end of the terminal character-set, or (b) when the terminal character-set is TRANSPARENT. (1) PROGRAM AND FILE MANAGEMENT AND COMMANDS 1.0. Bug Fixes The following patches were issued to correct bugs in C-Kermit 6.0. These are described in detail in the 6.0 PATCHES file. All of these fixes have been incorporated in C-Kermit 6.1 (never released except as K95 1.1.16-17) and 7.0. 0001 All UNIX C-Kermit mishandles timestamps on files before 1970 0002 Solaris 2.5++ Compilation error on Solaris 2.5 with Pro C 0003 All VMS CKERMIT.INI Fix for VMS 0004 VMS/VAX/UCX 2.0 C-Kermit 6.0 can't TELNET on VAX/VMS with UCX 2.0 0005 All C-Kermit Might Send Packets Outside Window 0006 All MOVE from SEND-LIST does not delete original files 0007 Solaris 2.5++ Higher serial speeds on Solaris 2.5 0008 All C-Kermit application file name can't contain spaces 0009 AT&T 7300 UNIXPC setuid and hardware flow-control problems 0010 Linux on Alpha Patch to make ckutio.c compile on Linux/Alpha 0011 OS-9/68000 2.4 Patch to make ck9con.c compile on OS-9/68000 2.4 0012 MW Coherent 4.2 Patches for successful build on Coherent 4.2 0013 SINIX-Y 5.43 "delay" variable conflicts with 0014 VMS/VAX/CMU-IP Subject: Patches for VAX/VMS 5.x + CMU-IP 0015 All XECHO doesn't flush its output 0016 VMS CD and other directory operations might not work 0017 Linux 1.2.x++ Use standard POSIX interface for high serial speeds 0018 UNIX SET WILDCARD-EXPANSION SHELL dumps core 0019 All Hayes V.34 modem init string problem 0020 All READ command does not fail if file not open 0021 All Problems with long function arguments 0022 All Certain \function()s can misbehave 0023 All X MOD 0 crashes program 0024 All Internal bulletproofing for lower() function 0025 OpenBSD Real OpenBSD support for C-Kermit 6.0 0026 All Incorrect checks for macro/command-file nesting depth 0027 All ANSWER doesn't automatically CONNECT 0028 All Overzealous EXIT warning 0029 All OUTPUT doesn't echo when DUPLEX is HALF 0030 All Minor problems with REMOTE DIRECTORY/DELETE/etc 0031 All CHECK command broken 0032 All Problem with SET TRANSMIT ECHO 0033 UNIX, VMS, etc HELP SET SERVER says too much 0034 All READ and !READ too picky about line terminators 0035 All END from inside SWITCH doesn't work 0036 All Problem telnetting to multihomed hosts 0037 All Redirection failures in REMOTE xxx > file REDIRECT was missing in many UNIX C-Kermit implementations; in version 7.0, it should be available in all of them. 1.1. Command Continuation Comments that start with ";" or "#" can no longer be continued. In: ; this is a comment - echo blah the ECHO command will execute, rather than being taken as a continuation of the preceding comment line. This allows easy "commenting out" of commands from macro definitions. However, the text of the COMMENT command can still be continued onto subsequent lines: comment this is a comment - echo blah As of version 6.0, backslash is no longer a valid continuation character. Only hyphen should be used for command continuation. This is to make it possible to issue commands like "cd a:\" on DOS-like systems. As of version 7.0: . You can quote a final dash to prevent it from being a continuation character: echo foo\- This prints "foo-". The command is not continued. . You can enter commands such as: echo foo - ; this is a comment interactively and they will be properly treated as continued commands. Previously this worked only in command files. 1.2. Editor Interface SET EDITOR [ ] Lets you specify a text-editing program. The can be a fully specified pathname like /usr/local/bin/emacs19/emacs, or it can be the name of any program in your PATH, e.g. "set editor emacs". In VMS, it must be a DCL command like "edit", "edit/tpu", "emacs", etc. If an environment variable EDITOR is defined when Kermit starts, its value is the default editor. You can also specify options to be included on the editor command line. Returns to Kermit when the editor exits. EDIT [ ] If the EDIT command is given without a filename, then if a previous filename had been given to an EDIT command, it is used; if not, the editor is started without a file. If a filename is given, the editor is started on that file, and the filename is remembered for subsequent EDIT commands. SHOW EDITOR Displays the full pathname of your text editor, if any, along with any command line options, and the file most recently edited (and therefore the default filename for your next EDIT command). Related variables: \v(editor), \v(editopts), \v(editfile). 1.3. Web Browser and FTP Interface C-Kermit includes an FTP command, which simply runs the FTP program; C-Kermit does not include any built-in support for Internet File Transfer Protocol, nor any method for interacting directly with an FTP server. In version 7.0, however, C-Kermit lets you specify your FTP client: SET FTP-CLIENT [ [ ] Starts your preferred Web browser on the URL, if one is given, otherwise on the most recently given URL, if any. Returns to Kermit when the browser exits. SET BROWSER [ [ ] ] Use this command to specify the name of your Web browser program, for example: "set browser lynx". The must be in your PATH, or else it must be a fully specified filename; in VMS it must be a DCL command. SHOW BROWSER Displays the current browser, options, and most recent URL. Related variables: \v(browser), \v(browsopts), \v(browsurl). Also see Section 2.15: Contacting Web Servers with the HTTP Command. 1.3.2. Invoking C-Kermit from your Browser The method for doing this depends, of course, on your browser. Here are some examples: Netscape on UNIX (X-based): In the Options->Applications section, set your Telnet application to: xterm -e /usr/local/bin/kermit/kermit -J %h %p (replace "/usr/local/bin/kermit/kermit" by C-Kermit's actual pathname). -J is C-Kermit's command-line option to "be like Telnet"; %h and %p are Netscape placeholders for hostname and port. Lynx: As far as we know, this can be done only at compile time. Add the following line to the Lynx userdefs.h file before building the Lynx binary: #define TELNET_COMMAND "/opt/bin/kermit -J" And then add lines like the following to the Lynx.cfg file: DOWNLOADER:Kermit binary download:/opt/bin/kermit -i -V -s %s -a %s:TRUE DOWNLOADER:Kermit text download:/opt/bin/kermit -s %s -a %s:TRUE UPLOADER:Kermit binary upload:/opt/bin/kermit -i -r -a %s:TRUE UPLOADER:Kermit text upload:/opt/bin/kermit -r -a %s:TRUE UPLOADER:Kermit text get:/opt/bin/kermit -g %s:TRUE UPLOADER:Kermit binary get:/opt/bin/kermit -ig %s:TRUE 1.4. Command Editing Ctrl-W ("Word delete") was changed in 7.0 to delete back to the previous non-alphanumeric, rather than all the way back to the previous space. 1.5. Command Switches As of 7.0, C-Kermit's command parser supports a new type of field, called a "switch". This is an optional command modifier. 1.5.1. General Switch Syntax A switch is a keyword beginning with a slash (/). If it takes a value, then the value is appended to it (with no intervening spaces), separated by a colon (:) or equal sign (=). Depending on the switch, the value may be a number, a keyword, a filename, a date/time, etc. Examples: send oofa.txt ; No switches send /binary oofa.zip ; A switch without a value send /protocol:zmodem oofa.zip ; A switch with a value (:) send /protocol=zmodem oofa.zip ; A switch with a value (=) send /text /delete /as-name:x.x oofa.txt ; Several switches Like other command fields, switches are separated from other fields, and from each other, by whitespace, as shown in the examples just above. You can not put them together like so: send/text/delete/as-name:x.x oofa.txt (as you might do in VMS or DOS, or as we might once have done in TOPS-10 or TOPS0-20, or PIP). This is primarily due to ambiguity between "/" as switch introducer versus "/" as UNIX directory separator; e.g. in: send /delete/as-name:foo/text oofa.txt Does "foo/text" mean the filename is "foo" and the transfer is to be in text mode, or does it mean the filename is "foo/text"? Therefore we require whitespace between switches to resolve the ambiguity. (That's only one of several possible ambiguities -- it is also conceivable that a file called "text" exists in the path "/delete/as-name:foo/"). In general, if a switch can take a value, but you omit it, then either a reasonable default value is supplied, or an error message is printed: send /print:-Plaserwriter oofa.txt ; Value included = print options send /print oofa.txt ; Value omitted, OK send /mail:kermit@columbia.edu oofa.txt ; Value included = address send /mail oofa.txt ; Not OK - address required ?Address required Context-sensitive help (?) and completion (Esc or Tab) are available in the normal manner: C-Kermit> send /pr? Switch, one of the following: /print /protocol C-Kermit> send /protocol:? File-transfer protocol, one of the following: kermit xmodem ymodem ymodem-g zmodem C-Kermit> send /protocol:kermit If a switch takes a value and you use completion on it, a colon (:) is printed at the end of its name to indicate this. If it does not take a value, a space is printed. Also, if you type ? in a switch field, switches that take values are shown with a trailing colon; those that don't take values are shown without one. 1.5.2. Order and Effect of Switches The order of switches should not matter, except that they are evaluated from left to right, so if you give two switches with opposite effects, the rightmost one is used: send /text /binary oofa.zip ; Sends oofa.zip in binary mode. Like other command fields, switches have no effect whatsoever until the command is entered (by pressing the Return or Enter key). Even then, switches affect only the command with which they are included; they do not have global effect or side effects. 1.5.3. Distinguishing Switches from Other Fields All switches are optional. A command that uses switches lets you give any number of them, including none at all. Example: send /binary oofa.zip send /bin /delete oofa.zip send /bin /as-name:mupeen.zip oofa.zip send oofa.zip But how does Kermit know when the first "non-switch" is given? It has been told to look for both a switch and for something else, the data type of the next field (filename, number, etc). In most cases, this works well. But conflicts are not impossible. Suppose, for example, in UNIX there was a file named "text" in the top-level directory. The command to send it would be: send /text But C-Kermit would think this was the "/text" switch. To resolve the conflict, use braces: send {/text} or other circumlocutions such as "send //text", "send /./text", etc. The opposite problem can occur if you give an illegal switch that happens to match a directory name. For example: send /f oofa.txt There is no "/f" switch (there are several switches that begin with "/f", so "/f" is ambiguous). Now suppose there is an "f" directory in the root directory; then this command would be interpreted as: Send all the files in the "/f" directory, giving each one an as-name of "oofa.txt". This could be a mistake, or it could be exactly what you intended; C-Kermit has no way of telling the difference. To avoid situations like this, spell switches out in full until you are comfortable enough with them to know the minimum abbreviation for each one. Hint: use ? and completion while typing switches to obtain the necessary feedback. 1.5.4. Standard File Selection Switches The following switches are used on different file-oriented commands (such as SEND, DIRECTORY, DELETE, PURGE) to refine the selection of files that match the given specification. /AFTER: Select only those files having a date-time later than the one given. See Section 1.6 for date-time formats. Synonym: /SINCE. /NOT-AFTER: Select only those files having a date-time not later than (i.e. earlier or equal to) the one given. Synonym: /NOT-SINCE. /BEFORE: Select only those files having a date-time earlier than the one given. /NOT-BEFORE: Select only those files having a date-time not earlier than (i.e. later or equalto) the one given. /DOTFILES UNIX and OS-9 only: The filespec is allowed to match files whose names start with (dot) period. Normally these files are not shown. /NODOTFILES (UNIX and OS-9 only) Don't show files whose names start with dot (period). This is the opposite of /DOTFILES, and is the default. Note that when a directory name starts with a period, the directory and (in recursive operations) all its subdirectories are skipped. /LARGER-THAN: Only select files larger than the given number of bytes. /SMALLER-THAN: Only select files smaller than the given number of bytes. /EXCEPT:pattern Specifies that any files whose names match the pattern, which can be a regular filename, or may contain "*" and/or "?" metacharacters (wildcards), are not to be selected. Example: send /except:*.log *.* sends all files in the current directory except those with a filetype of ".log". Another: send /except:*.~*~ *.* sends all files except the ones that look like Kermit or EMACS backup files (such as "oofa.txt.~17~") (of course you can also use the /NOBACKUP switch for this). The pattern matcher is the same one used by IF MATCH (Section 7.4), so you can test your patterns using IF MATCH. If you need to match a literal * or ? (etc), precede it by a backslash (\). If the pattern contains any spaces, it must be enclosed in braces: send /except:{Foo bar} *.* The pattern can also be a list of up to 8 patterns. In this case, the entire pattern must be enclosed in braces, and each sub-pattern must also be enclosed in braces; this eliminates the need for designating a separator character, which is likely to also be a legal filename character on some platform or other, and therefore a source of confusion. You may include spaces between the subpatterns but they are not necessary. The following two commands are equivalent: send /except:{{ck*.o} {ck*.c}} ck*.? send /except:{{ck*.o}{ck*.c}} ck*.? If a pattern is to include a literal brace character, precede it with \. Also note the apparent conflict of this list format and the string-list format described in section 4.9.1. In case you want to include a wildcard string-list with braces on its outer ends as an /EXCEPT: argument, do it like this: send /except:{{{ckuusr.c,ckuus2.c,ckuus6.c}}} ckuus*.c 1.5.5. Setting Preferences for Different Commands Certain oft-used commands offer lots of switches because different people have different requirements or preferences. For example, some people want to be able to delete files without having to watch a list of the deleted files scroll past, while others want to be prompted for permission to delete each file. Different people prefer different directory-listing styles. And so on. Such commands can be tailored with the SET OPTIONS command: SET OPTIONS [ switch [ switch [ ... ] ] ] Sets each switch as the default for the given command, replacing the "factory default". Of course you can also override any defaults established by the SET OPTIONS command by including the relevant switches in the affected command any time you issue it. SHOW OPTIONS Lists the commands that allows option-setting, and the options currently in effect, if any, for each. Switches that have synonyms are shown under their primary name; for example. /LOG and /VERBOSE are shown as /LIST. Commands for which options may be set include DIRECTORY, DELETE, PURGE, and TYPE. Examples: SET OPTIONS DIRECTORY /PAGE /NOBACKUP /HEADING /SORT:DATE /REVERSE SET OPTIONS DELETE /LIST /NOHEADING /NOPAGE /NOASK /NODOTFILES SET OPTIONS TYPE /PAGE Not necessarily all of a command's switches can be set as options. For example, file selection switches, since these would normally be different for each command. Put the desired SET OPTIONS commands in your C-Kermit customization file for each command whose default switches you want to change every time you run C-Kermit. 1.6. Dates and Times Some commands and switches take date-time values, such as: send /after:{8-Feb-2000 10:28:01} Various date-time formats are acceptable. The rules for the date are: . The year must have 4 digits. . If the year comes first, the second field is the month. . The day, month, and year may be separated by spaces, /, -, or underscore. . The month may be numeric (1 = January) or spelled out or abbreviated in English. If the date-time string contains any spaces, it must be enclosed in braces. Examples of legal dates: Interpretation: 2000-Feb-8 8 February 2000 {2000 Feb 8} 8 February 2000 2000/Feb/8 8 February 2000 2000_Feb_8 8 February 2000 2000-2-8 8 February 2000 2000-02-08 8 February 2000 8-Feb-2000 8 February 2000 08-Feb-2000 8 February 2000 12/25/2000 25 December 2000 25/12/2000 25 December 2000 The last two examples show that when the year comes last, and the month is given numerically, the order of the day and month doesn't matter as long as the day is 13 or greater (mm/dd/yyyy is commonly used in the USA, whereas dd/mm/yyyy is the norm in Europe). However: 08/02/2000 Is ambiguous and therefore not accepted. If a date is given, the time is optional and defaults to 00:00:00. If the time is given with a date, it must follow the date, separated by space, /, -, or underscore, and with hours, minutes, and seconds separated by colon (:). Example: 2000-Feb-8 10:28:01 Represents 8 February 2000, 10:28:01am If a date is not given, the current date is used and a time is required. Time format is hh:mm:ss or hh:mm or hh in 24-hour format, or followed by "am" or "pm" (or "AM" or "PM") to indicate morning or afternoon. Examples of times that are acceptable: Interpretation: 3:23:56 3:23:56am 3:23:56am 3:23:56am 3:23:56pm 3:23:56pm = 15:23:56 15:23:56 3:23:56pm = 15:23:56 3:23pm 3:23:00pm = 15:23:00 3:23PM 3:23:00pm = 15:23:00 3pm 3:00:00pm = 15:00:00 Examples of legal date-times: send /after:{8 Feb 2000 10:28:01} send /after:8_Feb_2000_10:28:01 send /after:8-Feb-2000/10:28:01 send /after:2000/02/08/10:28:01 send /after:2000/02/08_10:28:01 send /after:2000/02/08_10:28:01am send /after:2000/02/08_10:28:01pm send /after:2000/02/08_10:28pm send /after:2000/02/08_10pm send /after:10:00:00pm send /after:10:00pm send /after:10pm send /after:22 Finally, there is a special all-numeric format you can use: yyyymmdd hh:mm:ss For example: 20000208 10:28:01 This is Kermit's standard date-time format (based on ISO 8601), and is accepted (among other formats) by any command or switch that requires a date-time, and is output by any function whose result is a calendar date-time. There are no optional parts to this format and it must be exactly 17 characters long, punctuated as shown (except you can substitute underscore for space in contexts where a single "word" is required). The time is in 24-hour format (23:00:00 is 11:00pm). This is the format returned by \fdate(filename), so you can also use constructions like this: send /after:\fdate(oofa.txt) which means "all files newer than oofa.txt". Besides explicit dates, you can also use the any of the following shortcuts: TODAY Stands for the current date at 00:00:00. TODAY 12:34:56 Stands for the current date at the given time. YESTERDAY Stands for yesterday's date at 00:00:00. A time may also be given. TOMORROW Stands for tomorrow's date at 00:00:00. A time may also be given. + { DAYS, WEEKS, MONTHS, YEARS } [ time ] Is replaced by the future date indicated, relative to the current date. If the time is omitted, 00:00:00 is used. Examples: +3days, +2weeks, +1year, +37months. - { DAYS, WEEKS, MONTHS, YEARS } [ time ] Is replaced by the past date indicated, relative to the current date. If the time is omitted, 00:00:00 is used. The time can be separated from the date shortcut by any of the same separators that are allowed for explicit date-times: space, hyphen, slash, period, or underscore. In switches and other space-delimited fields, use non-spaces to separate date/time fields, or enclose the date-time in braces, e.g.: purge /before:-4days_12:00:00 or: purge /before:{- 4 days 12:00:00} Of course you can also use variables: define \%n 43 purge /before:-\%ndays_12:00:00 Shortcut names can be abbreviated to any length that still distinguishes them from any other name that can appear in the same context, e.g. "TOD" for today, "Y" for yesterday. Also, the special abbreviation "wks" is accepted for WEEKS, and "yrs" for "YEARS". (To see how to specify dates relative to a specific date, rather than the current one, see the \fmjd() function description below.) You can check date formats with the DATE command. DATE by itself prints the current date and time in standard format: yyyymmdd hh:mm:ss. DATE followed by a date and/or time (including shortcuts) converts it to standard format if it can understand it, otherwise it prints an error message. The following variables and functions deal with dates and times; any function argument designated as "date-time" can be in any of the formats described above. \v(day) The first three letters of the English word for the current day of the week, e.g. "Wed". \fday(date-time) The first three letters of the English word for day of the week of the given date. If a time is included, it is ignored. Example: \fday(8 Feb 1988) = "Mon". \v(nday) The numeric day of the week: 0 = Sunday, 1 = Monday, ..., 6 = Saturday. \fnday(date-time) The numeric day of the week for the given date. If a time is included, it is ignored. Example: \fnday(8 Feb 1988) = "1". \v(date) The current date as dd mmm yyyy, e.g. "08 Feb 2000" (as in this example, a leading zero is supplied for day-of-month less than 10). \v(ndate) The current date in numeric format: yyyymmdd, e.g. "20000208". \v(time) The current time as hh:mm:ss, e.g. "15:27:14". \ftime(time) The given free-format date and/or time (e.g. "3pm") returns the time (without the date) converted to hh:mm:ss 24-hour format, e.g. "15:00:00" (the date, if given, is ignored). \v(ntime) The current time as seconds since midnight, e.g. "55634". \v(tftime) The elapsed time of the most recent file-transfer operation in seconds. \v(intime) The elapsed time for the most recent INPUT command to complete, in milliseconds. \fntime(time) The given free-format date and/or time is converted to seconds since midnight (the date, if given, is ignored). This function replaces \ftod2secs(), which is now a synonym for \fntime(). Unlike \ftod2secs(), \fntime() allows a date to be included, and it allows the time to be in free format (like 3pm), and it allows the amount of time to be more than 24 hours. E.g. \fntime(48:00:00) = 172800. Example of use: set alarm \fntime(48:00:00) ; set alarm 48 hours from now. \fn2time(seconds) The given number of seconds is converted to hh:mm:ss format. \fdate(filename) Returns the modification date-time of the given file in standard format: yyyymmdd hh:mm:ss. \fcvtdate(date-time) Converts a free-format date and/or time to Kermit standard format: yyyymmdd hh:mm:ss. If no argument is given, returns the current date-time in standard format. If a date is given but no time, the converted date is returned without a time. If a time is given with no date, the current date is supplied. Examples: \fcvtdate(4 Jul 2000 2:21:17pm) = 20000704 14:21:17 \fcvtdate() = 20000704 14:21:17 (on 4 Jul 2000 at 2:21:17pm). \fcvtd(4 Jul 2000) = 20000704 \fcvtd(6pm) = 20000704 18:00:00 (on 4 Jul 2000 at 6:00pm). \fdayofyear(date-time) \fdoy(date-time) Converts a free-format date and/or time to yyyyddd, where ddd is the 3-digit day of the year, where 1 January is Day 1. If a time is included with the date, it is returned in standard format. If a date is included but no time, the date is returned without a time. If a time is given with no date, the time is converted and the current date is supplied. If no argument is given, the current date-time is returned. Synonym: \fdoy(). Examples: \fddayofyear(4 Jul 2000 2:21:17pm) = 2000185 14:21:17 \fdoy() = 2000185 14:21:17 (on 4 Jul 2000 at 2:21:17pm). \fdoy(4 Jul 2000) = 2000185 \fdoy(6pm) = 2000185 18:00:00 (on 4 Jul 2000 at 6:00pm). Note: The yyyyddd day-of-year format is often erroneously referred to as a Julian date. However, a true Julian date is a simple counting number, the number of days since a certain fixed day in the past. See \fmjd() below. \fdoy2date(date-time) Converts a date or date-time in day-of-year format to a standard format date. A yyyyddd-format date must be supplied; time is optional. The given date is converted to yyyymmdd format. If a time is given, it is converted to 24-hour format. Examples: \fdoy2date(2000185) = 20000704 \fdoy2(2000185 3pm) = 20000704 15:00:00 \fmjd(date-time) Converts free-format date and/or time to a Modified Julian Date (MJD), the number of days since 17 Nov 1858 00:00:00. If a time is given, it is ignored. Examples: \fmjd(4 Jul 2000) = 50998 \fmjd(17 Nov 1858) = 0 \fmjd(16 Nov 1858) = -1 \fmjd2date(mjd) Converts an MJD (integer) to standard date format, yyyymmdd: \fmjd2(50998) = 4 Jul 1998 \fmjd2(0) = 17 Nov 1858 \fmjd2(-1) = 16 Nov 1858 \fmjd2(-365) = 17 Nov 1857 MJDs are normal integers and, unlike DOYs, may be added, subtracted, etc, with each other or with other integers, to obtain meaningful results. For example, to find out the date 212 days ago: echo \fmjd2date(\fmjd()-212) Constructions such as this can be used in any command where a date-time is required, e.g.: send /after:\fmjd2date(\fmjd()-212) to send all files that are not older than 212 days (this is equivalent to "send /after:-212days"). MJDs also have other regularities not exhibited by other date formats. For example, \fmodulus(\fmjd(any-date),7) gives the day of the week for any date (where 4=Sun, 5=Mon, ..., 3=Sat). (However, it is easier to use \fnday() for this purpose, and it gives the more conventional result of 0=Sun, 1=Mon, ..., 6=Sat). Note that if MJDs are to be compared, they must be compared numerically (IF <, =, >) and not lexically (IF LLT, EQUAL, LGT), whereas DOYs must be compared lexically if they include a time (which contains ":" characters); however, if DOYs do not include a time, they may also be compared numerically. In any case, lexical comparison of DOYs always produces the appropriate result, as does numeric comparison of MJDs. The same comments apply to sorting. Also note that DOYs are fixed length, but MJDs can vary in length. However, all MJDs between 3 April 1886 and 30 Aug 2132 are 5 decimal digits long. (MJDs become 6 digits long on 31 Aug 2132, and 7 digits long on 13 Oct 4596). 1.7. Partial Completion of Keywords Partial completion of keywords was added in C-Kermit 7.0. In prior versions, if completion was attempted (by pressing the Esc or Tab key) on a string that matched different keywords, you'd just get a beep. Now Kermit completes up to the first character where the possibly matching keywords differ and then beeps. For example: send /n which matches /NOT-BEFORE and /NOT-AFTER, now completes up to the dash: send /not- Partial completion works for filenames too (as it has for some years). 1.8. Command Recall C-Kermit has had a command history buffer for some time, which could be scrolled interactively using control characters or (in Kermit 95 only) arrow keys. Version 7.0 adds a REDO command that allows the most recent command matching a given pattern to be re-executed: { REDO, RR, ^ } [ ] Search the command history list for the most recent command that matches the given pattern, and if one is found, execute it again. The pattern can be a simple string (like "send"), in which case the last SEND command is re-executed. Or it can contain wildcard characters "*" and/or "?", which match any string and any single character, respectively (note that "?" must be preceded by backslash to override its normal function of giving help), and in most C-Kermit versions may also include [] character lists and {} string lists (see Section 4.9). The match works by appending "*" to the end of the given pattern (if you didn't put one there yourself). Thus "redo *oofa" becomes "redo *oofa*" and therefore matches the most recent command that contains "oofa" anywhere within the command. If you want to inhibit the application of the trailing "*", e.g. to force matching a string at the end of a command, enclose the pattern in braces: redo {*oofa} matches the most recent command that ends with "oofa". REDO commands themselves are not entered into the command history list. If no pattern is given, the previous (non-REDO) command is re-executed. The REDOne command is reinserted at the end of the command history buffer, so the command scrollback character (Ctrl-P, Ctrl-B, or Uparrow) can retrieve it. Examples: C-Kermit>echo foo foo C-Kermit>show alarm (no alarm set) C-Kermit>echo blah blah C-Kermit>redo ; Most recent command blah C-Kermit>redo s ; Most recent command starting with "s" (no alarm set) C-Kermit>redo echo f ; Most recent command starting with "echo f" foo C-Kermit>redo *foo ; Most recent command that has "foo" in it foo C-Kermit> ; Scroll back C-Kermit>echo foo ; The REDOne command is there C-Kermit>redo {*foo} ; Most recent command that ends with "foo" foo C-Kermit> Since REDO, REDIAL, and REDIRECT all start the same way, and RED is the designated non-unique abbreviation for REDIAL, REDO must be spelled out in full. For convenience, RR is included as an invisible easy-to-type synonym for REDO. You can also use the "^" character for this: C-Kermit>^ ; Most recent command C-Kermit>^ s ; Most recent command starting with "s" C-Kermit>^s ; Ditto (space not required after "^"). C-Kermit>^*foo ; Most recent command that has "foo" in it. C-Kermit>^{*foo} ; Most recent command ends with "foo". Unlike the manual command-history-scrolling keys, the REDO command can be used in a script, but it's not recommended (since the command to be REDOne might not be found, so if the REDO command fails, you can't tell whether it was because REDO failed to find the requested command, or because the command was found but it failed). 1.9. EXIT Messages The EXIT and QUIT commands now accept an optional message to be printed. This makes the syntax of EXIT and QUIT just like END and STOP: { EXIT, QUIT, END, STOP } [ [ ] ] where is a number (0 indicating success, nonzero indicating failure). This is handy in scripts that are never supposed to enter interactive mode: dial 7654321 if fail exit 1 Can't make connection - try again later. Previously this could only be done in two steps: dial 7654321 xif fail { echo Can't make connection - try again later, exit 1 } A status code must be included in order to specify a message. In the case of EXIT and QUIT, the default status code is contained in the variable \v(exitstatus), and is set automatically by various events (file transfer failures, etc; it can also be set explicitly with the SET EXIT STATUS command). If you want to give an EXIT or QUIT command with a message, but without changing the exit status from what it normally would have been, use the \v(exitstatus) variable, e.g.: exit \v(existatus) Goodbye from \v(cmdfile). The EXIT status is returned to the system shell or whatever other process invoked C-Kermit, e.g. in UNIX: C-Kermit> exit 97 bye bye bye bye $ echo $? 97 $ 1.10. Managing Keyboard Interruptions When C-Kermit is in command or file-transfer mode (as opposed to CONNECT mode), it can be interrupted with Ctrl-C. Version 7.0 adds the ability to disarm the Ctrl-C interrupt: SET COMMAND INTERRUPT { ON, OFF } COMMAND INTERRUPT is ON by default, meaning the Ctrl-C can be used to interrupt a command or a file transfer in progress. Use OFF to disable these interruptions, and use it with great caution for obvious reasons. SET TRANSFER INTERRUPT { ON, OFF } This can be used to disable keyboard interruption of file transfer when C-Kermit is in local mode, or to re-enable it after it has been disabled. This applies to the X, Z, E, and similar keys as well as to the system interrupt character, usually Ctrl-C. This is distinct from SET TRANSFER CANCELLATION, which tells whether packet mode can be exited by sending a special sequence of characters. Several other commands can be interrupted by pressing any key while they are active. Version 7.0 adds the ability to disable this form of interruption also: SET INPUT CANCELLATION { ON, OFF } Whether an INPUT command in progress can be interrupted by pressing a key. Normally ON. Setting INPUT CANCELLATION OFF makes INPUT commands uninterruptible except by Ctrl-C (unless COMMAND INTERRUPTION is also OFF). SET SLEEP CANCELLATION { ON, OFF } Whether a SLEEP, PAUSE, or WAIT command in progress can be interrupted by pressing a key. Normally ON. Setting SLEEP CANCELLATION OFF makes these commands uninterruptible except by Ctrl-C (unless COMMAND INTERRUPTION is also OFF). Synonyms: SET PAUSE CANCELLATION, SET WAIT CANCELLATION. So to make certain a script is not interruptible by the user, include these commands: SET TRANSFER INTERRUPT OFF SET SLEEP CANCELLATION OFF SET INPUT CANCELLATION OFF SET COMMAND INTERRUPTION OFF Make sure to turn them back on afterwards. When a PAUSE, SLEEP, WAIT, or INPUT command is interrupted from the keyboard, the new variable \v(kbchar) contains a copy of the (first) character that was typed and caused the interruption, provided it was not the command interrupt character (usually Ctrl-C). If these commands complete successfully or time out without a keyboard interruption, the \v(kbchar) variable is empty. The \v(kbchar) variable (like any other variable) can be tested with: if defined \v(kbchar) The is executed if the variable is not empty. The \v(kbchar) variable can be reset with WAIT 0 (PAUSE 0, SLEEP 0, etc). 1.11. Taming The Wild Backslash -- Part Deux "Using C-Kermit", 2nd Edition, contains a brief section, "Taming the Wild Backslash", on page 48, which subsequent experience has shown to be inadequate for Kermit users intent on writing scripts that deal with Windows, DOS, and OS/2 filenames, in which backslash (\) is used as the directory separator. This section fills in the blanks. 1.11.1. Background The Kermit command language shares a certain unavoidable but annoying characteristic with most other command languages that are capable of string replacement, namely the necessity to "quote" certain characters when you want them to be taken literally. This is a consequence of the facts that: a. One or more characters must be set aside to denote replacement, rather than acting as literal text. b. We have only 96 printable characters to work with in ASCII, which is still the only universally portable character set. c. There is no single printable character that is unused everywhere. d. Variables are not restricted to certain contexts, as they are in formal programming languages like C and Fortran, but can appear anywhere at all within a command, and therefore require special syntax. Thus there can be conflicts. To illustrate, the standard UNIX shell uses dollar sign ($) to introduce variables. So the shell command: echo $TERM displays the value of the TERM variable, e.g. vt320. But suppose you want to display a real dollar sign: echo The price is $10.20 This causes the shell to evaluate the variable "$1", which might or might not exist, and substitute its value, e.g.: The price is 0.20 (in this case the $1 variable had no value.) This is probably not what you wanted. To force the dollar sign to be taken literally, you must apply a "quoting rule", such as "precede a character by backslash (\) to force the shell to take the character literally": echo The price is \$10.20 The price is $10.20 But now suppose you want the backslash AND the dollar sign to be taken literally: echo The price is \\$10.20 This doesn't work, since the first backslash quotes the second one, thereby leaving the dollar sign unquoted again: The price is \0.20 Quoting the dollar sign requires addition of a third backslash: echo The price is \\\$10.20 The price is \$10.20 The first backslash quotes the second one, and the third backslash quotes the dollar sign. Every command language -- all UNIX shells, VMS DCL, DOS Batch, AOS/VS CLI, etc etc -- has similar rules. UNIX shell rules are probably the most complicated, since many printable characters -- not just one -- are special there: dollar sign, single quote, double quote, backslash, asterisk, accent grave, number sign, ampersand, question mark, parentheses, brackets, braces, etc -- practically every non-alphanumeric character needs some form of quoting if it is to be taken literally. And to add to the confusion, the UNIX shell offers many forms of quoting, and many alternative UNIX shells are available, each using slightly different syntax. 1.11.2. Kermit's Quoting Rules Kermit's basic quoting rules are simple by comparison (there are, of course, additional syntax requirements for macro definitions, command blocks, function calls, etc, but they are not relevant here). The following characters are special in Kermit commands: Backslash (\) Introduces a variable, or the numeric representation of a special character, or a function, or other item for substitution. If the backslash is followed by a digit or by any of the following characters: x, o, d, m, f, v, $, %, &, { this indicates a special substitution item; otherwise the following character is to be taken literally (exceptions: \ at end of line is taken literally; \n, \b, and \n are special items in the OUTPUT command only). Semicolon (;) (Only when at the beginning of a line or preceded by at least one space or tab) Introduces a comment. Number sign (#) (Only when at the beginning of a line or preceded by at least one space or tab) Just like semicolon; introduces a comment. Question mark (?) (Only at the command prompt - not in command files or macros) Requests context-sensitive help. To force Kermit to take any of these characters literally, simply precede it by a backslash (\). Sounds easy! And it is, except when backslash also has a special meaning to the underlying operating system, as it does in DOS, Windows, and OS/2, where it serves as the directory separator in filenames such as: D:\K95\KEYMAPS\READ.ME Using our rule, we would need to refer to this file in Kermit commands as follows: D:\\K95\\KEYMAPS\\READ.ME But this would not be obvious to new users of Kermit software on DOS, Windows, or OS/2, and it would be annoying to seasoned ones. Thus MS-DOS Kermit and Kermit 95 go to rather extreme lengths to allow the more natural notation, as in: send d:\k95\keymaps\read.me The reason this is tricky is that we also need to allow for variables and other expressions introduced by backslash in the same command. For example, suppose \%a is a variable whose value is "oofa" (without the quotes). What does the following command do? send d:\%a Does it send the file named "oofa" in the current directory of the D: disk, or does it send a file named "%a" in the root directory of the D: disk? This is the kind of trouble we get into when we attempt to bend the rules in the interest of user friendliness. (The answer is: if the variable \%a has definition that is the name of an existing file, that file is sent; if a file d:\%a exists, it is sent; otherwise if both conditions are true, the variable takes precedence, and the literal filename can be forced by quoting: \\%a.) In Kermit 95 (but not MS-DOS Kermit), we also bend the rules another way by allowing you to use forward slash (/) rather than backslash (\) as the directory separator: send d:/k95/keymaps/read.me This looks more natural to UNIX users, and in fact is perfectly acceptable to the Windows 95/98/NT and OS/2 operating systems on the API level. BUT (there is always a "but") the Microsoft shell, COMMAND.COM, for Windows 95/98 and NT does not allow this notation, and therefore it can not be used in any Kermit command -- such as RUN -- that invokes the Windows command shell AND your command shell is COMMAND.COM or any other shell that does not allow forward slash as directory separator (some alternative shells do allow this). NOTE: There exists a wide variety of alternative shells from third parties that do not have this restriction. If you are using a shell that accepts forward slash as a directory separator, you can stop reading right now -- UNLESS (there is always an "unless") you want your scripts to be portable to systems that have other shells. Also note that some Windows shells might actually REQUIRE forward slashes (instead of backslashes) as directory separators; we do not treat this situation below, but the treatment is obvious -- use slash rather backslash as the directory separator. 1.11.3. Passing DOS Filenames from Kermit to Shell Commands The following Kermit commands invoke the system command shell: RUN (and its synonyms ! and @) REDIRECT PIPE Each of these commands takes a shell command as an operand. These shell commands are not, and can not be, parsed by Kermit since Kermit does not know the syntax of shell commands, and so can't tell the difference between a keyword, a filename, a variable, a switch, or other item. Therefore the rules can not be bent since Kermit doesn't know where or how to bend them. To illustrate (using the regular Windows shell): run c:\\windows\\command\\chkdsk.exe works OK, but: run c:/windows/command/chkdsk.exe is not accepted by COMMAND.COM. But: run c:\windows\command\chkdsk.exe results in Kermit applying its quoting rules before sending the text to the shell. Since "w" and "c" are not in the list of backslash-item codes, the backslash means "take the following character literally". Thus, by the time this filename gets to the Windows shell, it has become: c:windowscommandchkdsk.exe which is probably not what you wanted. (If "w" and "c" were in the list, the results could be even stranger.) Even more confusing is the case where a directory or filename starts with one or more digits: run c:\123\lotus.exe in which "\123" is the Kermit notation for ASCII character 123, which happens to be left brace ({), resulting in "c:{lotus.exe". So when passing filenames to a Windows shell, always use double backslashes as directory separators, to ensure that the shell gets single backslashes: run c:\\windows\\command\\chkdsk.exe run c:\\123\\lotus.exe Similar problems might occur with the built-in EDIT, BROWSE, and FTP commands. These commands result in Kermit building a shell command internally to invoke the associated helper program; the form of this command might conflict with the form demanded by certain alternative shells. 1.11.4. Using Variables to Hold DOS Filenames Now to the next level. Suppose you want to write a script in which filenames are parameters, and therefore are stored in variables. Example: define \%f c:\windows\command\chkdsk.exe ... run \%f Obviously this won't work for the reasons just noted; the RUN command requires directory separators be coded as double backslashes: define \%f c:\\windows\\command\\chkdsk.exe ... run \%f This will work; no surprises here. However, if you had used ASSIGN rather than DEFINE, you might have been surprised after all; review pages 348-349 of "Using C-Kermit" (2nd Ed) for the difference between DEFINE and ASSIGN. We have said that any Kermit 95 or MS-DOS Kermit command that parses filenames itself -- SEND, for example -- does not require double backslashes since it knows it is parsing a filename. So since the following works: send c:\windows\command\chkdsk.exe Should the following also work? define \%f c:\windows\command\chkdsk.exe ... send \%f Answer: No. Why? Because \%f is evaluated "recursively", to allow for the possibility that its definition contains further variable references. This is true of all "backslash-percent-letter" (or -digit) variables, and also for array references. So \%f becomes c:\windows\command\chkdsk.exe, which becomes c:windowscommandchkdsk.exe. The trick here is to use the "other" kind of variable, that is evaluated only "one level deep" rather than recursively: define filename c:\windows\command\chkdsk.exe ... send \m(filename) Similarly if you want to prompt the user for a filename: ask filename { Please type a filename: } Please type a filename: c:\windows\command\chkdsk.exe send \m(filename) 1.11.5. Passing DOS Filenames as Parameters to Macros Suppose you want to pass a DOS filename containing backslashes as a parameter to a Kermit macro. This raises two issues: 1. Parameters to macros are "just text" and so are fully evaluated before they are passed to the macro. 2. Once inside the macro, the formal parameters \%1, \%2, ... \%9 are the type of variable that is evaluated recursively. Thus a DOS filename is ruined once in the act of parsing the macro invocation, and again when referring to it from within the macro. To illustrate, suppose "test" is a macro. Then in the invocation: test c:\mydir\blah.txt "c:mydirblah.txt" is assigned to \%1. However, if we double the backslashes: test c:\\mydir\\blah.txt "c:\mydir\blah.txt" is assigned to \%1. But then when you refer to \%1 in the macro, it is evaluated recursively, resulting in "c:mydirblah.txt". To illustrate: define test echo \%1 test c:\mydir\blah.txt c:mydirblah.txt test c:\\mydir\\blah.txt c:mydirblah.txt test c:\\\\mydir\\\\blah.txt c:\mydir\blah.txt Let's address each part of the problem separately. First, inside the macro. You can use the \fcontents() function to force a backslash-percent variable (such as a macro argument) to be evaluated one level deep instead of recursively, for example: define test echo { The filename is "\fcontents(\%1)"} test c:\mydir\blah.txt ; We don't expect this to work The filename is "c:mydirblah.txt" ; and it doesn't. test c:\\mydir\\blah.txt ; But this does... The filename is "c:\mydir\blah.txt" Thus if the filename arrives inside the macro with single backslashes, the backslashes are preserved if you always refer to the parameter through the \fcontents() function. Now how to ensure that backslashes are not stripped or misinterpreted when passing a filename to a macro? This brings us back to what we learned in earlier sections: 1. If it is a literal filename, either double the backslashes, or (if the filename is to be used only within Kermit itself and not passed to a DOS shell, or it is to be passed to an alternative shell that accepts forward slash as a directory separator), use forward slash instead of backslash as the directory separator. 2. If it is a variable that contains a filename, make sure you use a macro-style variable name, rather than a backslash-percent-character name. Examples: define test echo \fcontents(\%1) define filename c:\mydir\blah.txt test c:\\mydir\\blah.txt ; Literal filename with double backslashes c:\mydir\blah.txt test c:/mydir/blah.txt ; Literal filename with forward slashes c:/mydir/blah.txt test \m(filename) ; Variable c:\mydir\blah.txt But what if you don't like these rules and you still want to pass a literal filename containing single backslashes to a macro? This is possible too, but a bit tricky: turn command quoting off before invoking the macro, and then turn it back on inside the macro. Example: define test set command quoting on, echo \fcontents(\%1) set command quoting off test c:\mydir\blah.txt c:\mydir\blah.txt Upon return from the macro, command quoting is back on (since the macro turned it on). Obviously this trick can not be used if the filename is stored in a variable, since it prevents the variable from being evaluated. 1.11.6. Passing DOS File Names from Macro Parameters to the DOS Shell Now suppose you need to pass a DOS filename to a macro, and the macro needs to pass it, in turn, to the Windows shell via (say) Kermit's RUN command. This works too: define xrun run \fcontents(\%1) xrun c:\\windows\\command\\chkdsk.exe (or you can use the SET COMMAND QUOTING OFF / ON technique described above to avoid the double backslashes.) But.. xrun c:/windows/command/chkdsk.exe does not work if the Windows shell does not recognize "/" as a directory separator. If there is a chance that a filename might be passed to the macro in this form, the macro will need to convert it to a form acceptable to the shell: define xrun run \freplace(\fcontents(\%1),/,\\) Here we replace all occurrences (if any) of "/" in the argument with "\" prior to issuing the RUN command. Of course, in order to specify "\" as a literal character in the \freplace() argument list, we have to double it. 1.11.7. Passing DOS Filenames to Kermit from the Shell As noted in the manual, the \&@[] array contains Kermit's command-line arguments. Suppose one of these arguments, say \&@[3], is a DOS filename such as C:\FOO\BAR\BAZ\OOFA.TXT. (Note: In C-Kermit 7.0 and K95 1.1.18 and later, command-line arguments after "=" or "--" are also available in the top-level \%1..9 variables; see Section 7.5.) Of course you can eliminate any problems by using forward slashes rather than backslashes in the filename, but sometimes this is not possible, as when the Kermit command line is being generated by another program than can only generate "native" format DOS filenames. As noted in the manual, "\%x" variables and \&x[] arrays are always evaluated "all the way" (recursively). If the contents of one of these variables contains backslashes, this causes another level of evaluation. There is another kind of variable, which is evaluated only "one level deep". You can use this to prevent interpretation of the backslashes in the filenames. Example: assign filename \fcontents(\&@[3]) ; Transfer contents ... send \m(filename) Or, more simply: send \fcontents(\&@[3]) 1.12. Debugging The debug log is produced when you give a "log debug" command. This is normally done at the request of the Kermit help desk, for forwarding to the Kermit developers for analysis as a last resort in troubleshooting problems. (Last resort because it can grow quite huge in a very short time.) In cases where timing information is critical to understanding a problem, you can tell C-Kermit to put a timestamp on each debug log line by giving the command: SET DEBUG TIMESTAMP ON At any time before or after activating the debug log (SET DEBUG TIMESTAMP OFF turns off timestamping). Timestamps can be turned off and on as desired while logging. Obviously, they increase the size and growth rate of the log significantly, and so should be used sparingly. Timestamps are of the form hh:mm:ss.xxx, where .xxx is thousands of a second (but is included only on platforms that include this feature). 1.13. Logs In UNIX C-Kermit and in K-95, you can now direct any log to a pipe. This not only lets you send your logs to places other than disk files, but also lets you customize them to any desired degree. LOG { DEBUG, PACKETS, SESSION, TRANSACTION, CONNECTION } { file, pipe } ... A "pipe" is the name of a command, preceded by a vertical bar. If the pipe contains any spaces, it must be enclosed in braces. Here are some examples for UNIX (always remember the importance of getting the UNIX shell quoting rules right): LOG TRANSACTIONS |lpr This sends the transaction log to the default UNIX printer, rather than to a file (use "lp" rather than "lpr" if necessary). LOG TRANSACTIONS {| myfilter > t.log} For those who don't like the format of the transaction log, or want to extract certain information from it; write your own output filter. LOG SESSION {| lpr -Plaserwriter} This sends the session log to a specific UNIX printer, rather than to a file. Note the braces around the pipeline. These are required because it contains spaces. LOG DEBUG {| tail -100 > debug.log} This causes the debug log file to contain only the final 100 lines. Suppose C-Kermit crashes under some unpredictable circumstances, and you need a debug log to catch it in the act. But the debug log can grow to huge proportions very quickly, possibly filling up the disk. Piping the debug log through "tail" results in keeping only the last 100 lines (or other number of your choice). LOG DEBUG {| grep "^TELNET" > debug.log} This one shows how to log only Telnet negotiations. Piping the debug log through grep or egrep lets you log only specific information, rather than everything. "man grep" for further info. LOG DEBUG {| gzip -c > debug.log.gz} Creates a full debug log, but compressed by gzip to save space. LOG PACKETS {| tr "\\01" "X" | cut -c9- > packet.log} This one writes the regular packet log, but translates the Ctrl-A that starts each packet to the letter "X" and removes the s-nn-nn- notation from the beginning of each line. Note the double backslash (normal Kermit quoting rules). "man tr" and "man cut" for further info. See Section 2.12 for information about the new connection log. 1.14. Automatic File-Transfer Packet Recognition at the Command Prompt Beginning in version 7.0, C-Kermit can recognize Kermit (and in some cases also Zmodem) file-transfer packets while at its command prompt. This is convenient (for example), if you escaped back from a remote Kermit program and told the local Kermit program to send a file, but forgot to tell the remote Kermit program to receive it (and the local Kermit did not have the "send a Kermit receive command" feature available). This feature is controlled by the following command: SET COMMAND AUTODOWNLOAD { ON, OFF } When ON, which is the default, the command parser recognizes Kermit packets when Kermit is in remote mode. An S packet makes it go into receive mode, an I packet makes it go into server mode. When OFF, packet recognition is disabled and the behavior when a packet is received at the command prompt is as it was in C-Kermit 6.1 and earlier (namely to print an error message). COMMAND AUTODOWNLOAD is the command-mode equivalent of TERMINAL AUTODOWNLOAD, which is effective during CONNECT mode. 1.15. The TYPE Command The TYPE command now accepts a selection of optional switches (Section 1.5), and also sets several variables. Syntax: TYPE [ switches... ] filename Variables: \v(ty_ln) Line number of current line (during TYPE command; see /PREFIX) \v(ty_lc) Line count of file most recently TYPEd. \v(ty_mc) Match count of file most recently TYPEd (see /MATCH). Switches: /PAGE If /PAGE is included, Kermit pauses at the end of each screenful and issues a "more?" prompt. You may press the space bar to view the next page (screenful), or press "q" or "n" to return to the C-Kermit prompt. If this switch is given, it overrides the COMMAND MORE-PROMPTING setting for this command only. If it is not given, paging is according to COMMAND MORE-PROMPTING. /NOPAGE Do not pause at the end of each screenful; show the whole file (or all selected lines) at once. If this switch is given, it overrides the COMMAND MORE-PROMPTING setting for this command only. If it is not given, paging is according to COMMAND MORE-PROMPTING. /HEAD[:n] Only show the first "n" lines of the file (where n is a number). If n is omitted, 10 is used. /TAIL[:n] Only show the last "n" lines of the file (where n is a number). If n is omitted, 10 is used. Note: /HEAD and /TAIL can't be combined; if you give both switches, only the most recent one is used. /MATCH:pattern Only type lines from the file that match the given pattern (see Section 4.9.1 for pattern notation). UNIX users familiar with grep should note a significant difference: there is no implied "*" at the beginning and end of the pattern. Thus: TYPE /MATCH:foo Lists lines whose entire contents are "foo". TYPE /MATCH:foo* Lists lines that start with "foo". TYPE /MATCH:*foo Lists lines that end with "foo". TYPE /MATCH:*foo* Lists lines that have "foo" anywhere in them. /HEAD and /TAIL apply after /MATCH, so "type /tail:20 /match:x*" shows the last 20 lines in the file that start with "x". /PREFIX:string Print the given string at the beginning of each line. The string may be a constant, a variable, or a quoted variable. If it's an unquoted variable, its value at the time the TYPE command was given is used as a constant. If it is a quoted variable, it is re-evaluated for each line; a useful variable for this context is \v(ty_ln) (the line number of the current line being typed). If the prefix is to include spaces, it must be enclosed in braces. Examples: type /prefix:{oofa.txt: } /match:*thing* oofa.txt Prints all lines in oofa.txt that contain "thing" with the filename itself as the prefix (similar to UNIX grep). type /prefix:{\v(time). } oofa.txt Prefixes each line of oofa.txt with the time at which the TYPE command was given (one backslash) type /prefix:{\\v(time). } oofa.txt Prefixes each line of oofa.txt with the time at which that line is being typed (two backslashes). type /prefix:{\\v(ty_ln). } oofa.txt Prefixes each line of oofa.txt with its line number. type /prefix:{\\flpad(\\v(ty_ln),4). } oofa.txt Same as the previous example, except the line number is right-adjusted in a 4-column field. /WIDTH[:n] Truncates each line at column "n" (which must be a number) prior to printing it. This option can be used for long lines when you don't want them to wrap. If n is omitted, your current screen width is used. /COUNT Counts lines and -- if /MATCH was included, matches -- but does not print any lines from the file. The line and match count is shown at the end, and the variables \v(ty_lc) and \v(ty_lm) are set accordingly. SET OPTIONS TYPE { /PAGE, /NOPAGE, /WIDTH:n } Sets the paging default for TYPE commands, which can be overridden in any particular TYPE command by including the desired switch. If a TYPE command is given with no switch, and no SET OPTIONS TYPE selection is in effect, paging is according to your COMMAND MORE-PROMPTING setting (SHOW COMMAND). 1.16. The RESET Command The RESET command, added in 7.0, closes all open files and logs, but does not affect the open connection (if any). 1.17. The COPY and RENAME Commands As of C-Kermit 7.0, in the UNIX version only, the COPY and RENAME commands are built in and do not call the underlying platform's COPY or RENAME command. This allows them to work in "NOPUSH" versions and other circumstances where it can't access system commands, and it allows file copying and renaming to be done portably in scripts. The characteristics of the built-in COPY or RENAME include: . It fails if the source file is a directory or is wild or lacks read access. . It fails if the source file is the destination file. . It allows the destination file to be a directory, in which case the source file is copied (or renamed) into it with the same name. . It overwrites an existing destination file if its permission allows. . It sets the new file's permission according to umask but also carries forward the source file's execute permission bits if the destination file did not already exist. . It fails if interrupted by Ctrl-C. . Upon error, it prints an appropriate message. . It returns standardized error codes that can be tested by IF SUCCESS / FAIL. These commands now also accept the following switches: /LIST (/LOG, /VERBOSE) = Print "file1 => file2 (OK)" (or error message). /NOLIST (/NOLOG, /QUIET) = Don't print anything (except error messages). /NOLIST is the default. The same built-in code is used by the UNIX C-Kermit server to execute REMOTE COPY commands (except in this case no switches are available). The COPY command also accepts the following additional switches. When any of these are given (and they can be used in any combination except /SWAP and /APPEND), some of the checks listed above are relaxed, and thus it might be possible to get into trouble in certain cases, e.g. when the source and target files are the same file: /APPEND = Append source file to destination file. /SWAP-BYTES = Swap bytes (see Section 6.6.5). /FROMB64 = Decode the source file from Base64 encoding. /TOB64 = Encode the target file in Base64. Base64 is the encoding commonly used for enclosures in Internet email. 1.18. The MANUAL Command The MANUAL command can be used to access the appropriate Kermit manual or other manual. The general syntax is: MANUAL [ string ] If the string is omitted, C-Kermit asks the underlying system to access the C-Kermit manual using whatever method is appropriate for the system. The specific action depends on the system. In UNIX, a "man" command is issued; "kermit" is the default argument but other manual topics may be specified. If the "man" command allows index or string searching, the appropriate syntax may be included. In Kermit 95, the MANUAL command brings up the HTML online K95 manual. In VMS and elsewhere, "man" is simply translated to "help", with a default argument of "kermit"; other and/or additional arguments may be included according to the definition of the system's "help" command. Correct operation of the "man" command in C-Kermit depends on the appropriate man page or help topic having been installed in the right place with the right permissions and format. 1.19. String and Filename Matching Patterns A pattern is a string that includes special notation for matching classes or sequences of characters. C-Kermit 7.0 / K95 1.1.18 supports patterns in several places: . Filenames (Section 4.9) . SWITCH case labels (Section 7.18) . The new IF MATCH statement (Section 7.4) . TYPE /MATCH (Section 1.15) . SET FILE TEXT-PATTERNS and BINARY-PATTERNS (Section 4.3) . The \fsearch() and \farraylook() functions (Sections 7.3 and 7.10.7) . The \fpattern() function used with [M,RE]INPUT (Section 7.1) Patterns are also called wildcards, especially when used for filename matching. C-Kermit's pattern syntax is explained in Section 4.9.1, and also by the HELP WILDCARDS command. 1.20. Multiple Commands on One Line As of C-Kermit 7.0, commands can be grouped together on one line by separating the commands with commas and enclosing the list in braces. For example: { echo One, echo Two, echo Three } or: do { echo One, echo Two, echo Three } Command lists can be nested: [ do ] { echo One, echo Two, if true { echo A, echo B}, echo Three } and the END command works as it does in macros: [ do ] { echo One, echo Two, if true end, echo Three } The "one line" stricture is, of course, pliant to line-continuation conventions, namely that lines ending in hyphen (-) or left brace ({) are to be continued. Thus the first example can also be rendered: [ do ] { echo One echo Two echo Three } (the "do" is optional). 1.21. What Do I Have? C-Kermit can be built for hundreds of different platforms with practically countless configuration options. Certain commands might not be available in certain configurations, etc. Even on the same platform, different builds are possible: "maximum functionality", "minimum size", "maximum performance", and so on. You can find out a lot about the configuration of your C-Kermit program with the SHOW FEATURES command. Of course, a lot of what it says, especially in the bottom part, might seem like gibberish, but can be deciphered with a Rosetta Stone (such as the C-Kermit source or the ckccfg.txt file). In any case, the output from SHOW FEATURES might easily explain why some expected feature is missing, or some buffer is smaller than expected. Here's a sample of the bottom section for the SunOS version: C-Kermit 7.0.196, 1 Jan 2000 Major optional features included: Network support (type SHOW NET for further info) Telnet Kermit Option Hardware flow control External XYZMODEM protocol support Latin-1 (West European) character-set translation Latin-2 (East European) character-set translation Cyrillic (Russian, Ukrainian, etc) character-set translation Greek character-set translation Hebrew character-set translation Japanese character-set translation Unicode character-set translation Pseudoterminal control REDIRECT command RESEND command Fullscreen file transfer display Control-character unprefixing Streaming Autodownload Major optional features not included: No Kerberos(TM) authentication No SRP(TM) (Secure Remote Password) protocol No Secure Sockets Layer (SSL) protocol No Transport Layer Security (TLS) protocol No encryption No X Windows forwarding Host info: Machine: sun4m Model: (unknown) OS: SunOS OS Release: 4.1.3_U1 OS Version: 4 Target: sunos41gsc GCC version: 2.7.2 Compiled Dec 31 1999 10:38:54, options: __GNUC__ __STDC__ _POSIX_JOB_CONTROL _SC_JOB_CONTROL ARRAYREFLEN=1024 BIGBUFOK BROWSER BSD4 CK_ANSIC CK_APC CK_AUTODL CK_CURSES CK_DNS_SRV CK_ENVIRONMENT CK_FAST CK_LOGIN CK_MKDIR CK_NAWS CK_PCT_BAR CK_PERMS CK_RECALL CK_RTSCTS CK_SPEED CK_TIMERS CK_TMPDIR CK_TTGWSIZ CK_TTYFD CK_WREFRESH CKEXEC CKFLOAT=double CKGHNLHOST ckmaxfiles=64 CKMAXOPEN=64 CKMAXPATH=1023 CKREALPATH CKREGEX CKSYSLOG CKTUNING CMDBL=32763 CMDDEP=64 CONGSPD DCMDBUF DIRENT DYNAMIC FNFLOAT FORDEPTH=32 GFTIMER HADDRLIST HDBUUCP IFDEBUG IKS_OPTION IKSDB IKSDCONF INBUFSIZE=32768 INPBUFSIZ=4096 MAC_MAX=16384 MACLEVEL=128 MAXDDIR=32 MAXDNUMS=4095 MAXGETPATH=128 MAXTAKE=54 MAXWLD=102400 MSENDMAX=1024 NETCMD NETCONN NETPTY NOKVERBS NOSETBUF OBUFSIZE=32768 PARSENSE PATTERNS PIPESEND RENAME RLOGCODE SAVEDUID SELECT SIG_V SOL_SOCKET sparc STREAMING sun SUNOS4 SYSTIMEH TCPSOCKET TIMEH TLOG TNCODE TTLEBUF TTSPDLIST UIDBUFLEN=256 UNIX UNPREFIXZERO USE_LSTAT USE_MEMCPY VNAML=4096 WHATAMI XFRCAN Z_MAXCHAN=46 z_maxchan=46 ZXREWIND byte order: big endian sizeofs: int=4 long=4 short=2 char=1 char*=4 float=4 double=8 floating-point: precision=16 rounding=1 Without going into detail about what all the notation means, notice a couple things: . The Options section shows symbols ("macros") in effect during compilation, together with their values (for those that have values). The options are listed in alphabetical order to make any particular option easier to find. . MAXWLD is the maximum number of files that a wildcard can expand to. . Anything starting with "NO" is a feature (or something other than a feature) that has been deliberately "compiled out", or omitted. . Important items for script writers include: CMDBL=32763 (the size of the command buffer and therefore the maximum length for a macro or variable definition; CMDDEP=64 (the limit on recursion depth); FORDEPTH=32 (the nesting limit on FOR loops); INBUFSIZE=32768 (the size of the INPUT command circular buffer); MAC_MAX=16384 (the maximum number of macros), etc. See the ckccfg.txt file for details. 1.22. Generalized File Input and Output C-Kermit 7.0 adds a new generalized I/O system for stream files, augmenting (and to some extent, overlapping with) the older OPEN, READ, WRITE, and CLOSE commands. In the new file i/o system, which can be used simultaneously with the old one, all commands are grouped together under the new FILE keyword, and some related functions and variables are added. 1.22.1. Why Another I/O System? The well-known LOG, OPEN, READ, WRITE, and CLOSE commands have the following restrictions: a. Only one READ file and one WRITE file can be open at a time. b. The READ and WRITE commands are strictly line oriented. c. These commands can not be used with binary files. d. They do not support read/write access or random access. e. The syntax is a bit counterintuitive for programmers. The new file i/o system allows multiple files to be open at once, in any desired combination of modes (read/write/append) supported by the operating system, for line, block (record), or character i/o, for sequential or random access, using consistent syntax and conventions. The new system, however, does not replace the old one, since the old system still must be used for: a. The session, packet, debug, transaction, and connection logs. b. Reading and writing commands rather than files. c. Existing scripts. The new system works only with regular files, not with commands or pipes or mailboxes or pseudoterminals. No special provisions are made in the FILE commands for handling devices or network connections, nor for preventing you from trying to open them; if the underlying operating system treats them like regular stream disk files, the FILE commands (except, of course SEEK, REWIND, and COUNT) might work with them. (In C programming terms, the FILE commands are, at present, nothing more than a front end to fopen() / fread() / fwrite() / fclose() and friends, which are a portable API to sequential files, but this might change in the future for platforms like VMS and VOS that have more complicated file systems.) Definitions: Channel A number assigned to a file when it is opened, by which it must be referred to in all input/output operations. Read/Write Pointer The current position in an open file, expressed as the 0-based byte count from the beginning. 1.22.2. The FILE Command The FILE command has the following syntax: FILE [ ] [ ] The specifies the function: FILE OPEN, FILE READ, FILE WRITE, FILE CLOSE, etc. For convenience (and for familiarity to C programmers), the two-word FILE commands can be shortened to the single words FOPEN, FREAD, FWRITE, FCLOSE, and so on. Switches are optional, and modify or amplify the requested file function. As in C, Fortran, and other programming languages, open files are referred to by "channels", integers such as 0, 1, 2, 3, and so on. A channel number is assigned when you open a file. The number of available channels depends on the underlying operating system, and can be seen in the variable: \v(f_max) or by giving the FILE LIST (FLIST) command. Channels are discussed in greater detail in Section 1.22.4. FILE command errors can be caught with IF FAIL after the FILE command. In addition, the \v(f_error) variable is set to the completion code of the command: 0 if no error, or a negative number if there was an error. The error codes are listed in Section 1.22.5. The command to open a file is: FILE OPEN [ switches ] Opens a file for the type of access specified by the switches, or for read-only access if no switches are given. Upon success, a channel number is assigned to this file and stored in the given variable so you can refer to the open file in subsequent i/o commands. If the file can not be opened, the FILE OPEN command fails. Synonym: FOPEN. The FILE OPEN switches are: /READ Open the file for read access. If no switches are given, /READ is assumed. If the file does not exist or can't be opened for read access, the FILE OPEN command fails. /WRITE Allow writing. If a file of the same name already exists, it is overwritten unless /READ or /APPEND is also included. If a file of the given name does not exist, it is created. /APPEND Equivalent to /WRITE, except that if the file exists, it is not destroyed. The read/write pointer is set to the end of the file, so unless you change it with FILE SEEK or REWIND (see below), the first FILE WRITE command adds to the end of the file, preserving what was there already. If /WRITE is also given, it is ignored. /BINARY Open the file in "binary" mode, rather than text mode. This switch is meaningless (but still can be used) in UNIX. In VMS, Windows, and OS/2, it inhibits end-of-line processing and conversion, and so should be used for binary files and/or files that are to be accessed in record or character mode rather than line by line. The variable for the channel number can be any kind of variable: the \%x kind, a macro name, or an array element. But it must be a variable, not a number -- C-Kermit assigns the channel number; you can't tell it what number to use. Example: FILE OPEN \%c oofa.txt ; Open oofa.txt for reading. IF FAIL exit 1 Can't open oofa.txt ; Always check to see if it worked. ECHO oofa.txt: channel = \%c If the file oofa.txt is opened successfully, a channel number is assigned to the variable \%c. Here's another example using a macro name for the channel number: FILE OPEN channel oofa.txt ; Open oofa.txt for reading. IF SUCCESS ECHO oofa.txt: channel = \m(channel) Switches can be combined when it makes sense and the underlying operating system allows it. For example, to open a file in binary mode for reading and writing (sometimes called "update"): FILE OPEN /READ /WRITE /BINARY \%c budget.db Some combinations might be allowed, others not. For example /READ /APPEND will usually not be allowed. /WRITE /APPEND is treated as /APPEND. A major advantage of the new system over the older one is that you can have multiple files open at once. Suppose, for example, that you want to open all the files in a certain directory at once: .\%n := \ffiles(/usr/olga*,&f) ; Get file list into array. if ( > \%n \v(f_max) ) { ; Make sure there aren't too many. exit 1 {\v(dir): \%n = Too many files} } declare \&c[\%n] ; Make array for channel numbers. for \%i 1 \%n 1 { ; Loop to open every file... file open \&c[\%i] \&f[\%i] ; Try to open this one if fail exit 1 Open error: \&f[\%i] ; Check for failure } If this loop completes successfully, the \&c[] array will contain \%n channel numbers of open files in elements 1 through \%n. Any file that you open with FILE OPEN stays open until you close it. The command to close a file is: FILE CLOSE { ALL, } If a channel number is given and the channel refers to an open file, the file is closed and the channel is freed for reuse; if the channel does not refer to an open file, an error message is printed and the command fails. If ALL is specified instead of a specific channel, all files opened with FILE OPEN are closed and if all open files were closed successfully (even if no files were open), the command succeeds; if any open file could not be closed, the command fails; however, all open files that could be closed are still closed. Synonym: FCLOSE. FILE CLOSE might fail because, for example, the disk filled up or a quota was exceeded. Example: fopen /write \%c new.txt ; Open new.txt for writing. if fail exit 1 ; Check for error. fclose \%c ; Close the file we just opened. This creates a 0-length file called new.txt. Note that FILE OPEN /WRITE (without /READ or /APPEND) always creates a new file, and therefore destroys any file with the same name that might already exist (assuming you have permission to delete it). To avoid overwriting existing files, simply check first: if exist new.txt exit 1 {Fatal - new.txt already exists} fopen /write \%c new.txt if fail ... The next two commands give information about open files: FILE STATUS Tells the name of the file, if any, open on the given channel and the switches it was opened with. The read/write pointer is also shown; this is where the next read or write will occur; "[EOF]" is shown if the current position in the open file is the end -- i.e. the next read will fail if the file was opened in /READ mode; the next write will add material to the end. The current line number (0-based) is also shown if known. The FILE STATUS command succeeds if the is open, and fails if there is no open file on the given channel, or if the channel number is invalid or out of range. Synonym FSTATUS. FILE LIST Lists the channel number and name of each open file, along with its OPEN modes (R, W, A, B, RW, etc) and its current read/write pointer or "[EOF]" if it is at the end. Also tells the number of files currently opened with FILE OPEN, plus the maximum number of open files allowed by the system and the maximum number allowed for FILE OPEN. Synonym: FLIST. Next come the commands for reading and writing files: FILE READ [ switches ] [ ] Reads data from the file on the given channel number into the , if one was given; if no variable was given, the result is printed on the screen. IMPORTANT: The variable should normally be a macro name rather than a \%x or \&x[] variable if you want backslash characters in the file to be taken literally (see pp.408-412 of "Using C-Kermit" for an explanation; you can also read into a \%x or \&x[] variable, but then you must remember to protect future references to it by \fcontents() if you don't want C-Kermit to process any backslashes it might contain). The desired amount of data (according to the switches) is read from the file at the current read/write pointer, and upon completion the read/write position is updated to first byte after the data that was read, no matter what switches were given. Synonym: FREAD. FILE WRITE [ switches ] Writes the given text to the file on the given channel number. The , of course, can be literal text or a variable, or any combination. If the text might contain leading or trailing spaces, it must be enclosed in braces if you want to preserve them. Synonym: FWRITE. Before proceeding, a caution about the NUL character. C-Kermit is so named because it is a Kermit program written in the C language. In C, character strings are represented as a sequence of non-NUL bytes terminated by a NUL byte (a byte in which all bits are 0). Thus a C string can not contain NUL bytes; it always ends with the first NUL byte. C-Kermit variables are implemented as C strings and therefore can't contain NUL bytes either, so the FILE READ and FILE WRITE commands do not handle files or strings that contain NUL bytes, except when the /CHARACTER switch is included with the FILE READ or WRITE command, or when /LPAD:0 or /RPAD:0 is given with the FILE WRITE command; these switches are explained below. Also note that Kermit can not be used read or write binary numbers in the machine's internal format (integer or floating-point); in general, numbers can be processed only when represented as numeric or floating-point strings. FILE READ switches are: /LINE Specifies that a line of text is to be read. A line is defined according to the underlying operating system's text-file format. For example, in UNIX a line is a sequence of characters up to and including a linefeed, or the end of the file, which ever comes first. The line terminator (if any) is removed before assigning the text to the variable. If no switches are included with the FILE READ command, /LINE is assumed. Normally this switch should not be used with files opened in /BINARY mode (but nothing prevents it either). /SIZE:number Specifies that the given number of bytes (characters) is to be read. The actual number of bytes returned will be less if the end of file is reached (or a NUL byte is encountered). For example, if a file is 514 bytes long, FILE READ /SIZE:512 returns 512 bytes the first time and 2 bytes the second time. FILE READ /SIZE provides a kind of "record i/o" for files that do not necessarily contain lines. The resulting block of characters is assigned to the variable without any editing. Synonym: /BLOCK. /CHARACTER Equivalent to /SIZE:1. If FILE READ /CHAR succeeds but the is empty, this indicates a NUL byte was read. Synonym: BYTE. FILE WRITE switches are: /LINE Specifies that an appropriate line terminator is to be added to the end of the . If no switches are included, /LINE is assumed. /SIZE:number Specifies that the given number of bytes (characters) is to be written. If the given is longer than the requested size, it is truncated; if is shorter, it is padded according /LPAD and /RPAD switches. Synonym: /BLOCK. /LPAD[:value] If /SIZE was given, but the is shorter than the requested size, the text is padded on the left with sufficient copies of the character whose ASCII value is given to write the given length. If no value is specified, 32 (the code for Space) is used. The value can also be 0 to write the indicated number of NUL bytes. If /SIZE was not given, this switch is ignored. /RPAD[:value] Like LPAD, but pads on the right. /CHARACTER Specifies that one character should be written. If the is empty or not given, a NUL character is written; otherwise the first character of is given. Synonym: /BYTE. /STRING Specifies that the is to be written as-is, with no terminator added. Here's an example in which we copy a text file line by line: file open /read \%c oofa.txt ; Open input file if fail exit 1 Can't open input file ; Check that it's open file open /write \%d new.txt ; Open output file if fail exit 1 Can't open output file ; Check while true { ; Loop to copy lines file read /line \%c line ; Read a line if fail break ; Assume failure = end of file file write /line \%d {\m(line)} ; Write the line to output file if fail exit 1 Write failure ; Failure here is fatal } file close \%c ; Close the two files file close \%d Note that since /LINE is the default for both FILE READ and FILE WRITE, it can be omitted as in the following example, where we also use the short names for the FILE commands. fopen /read \%c oofa.txt ; Open input file if fail exit 1 Can't open input file ; Check that it's open fopen /write \%d new.txt ; Open output file if fail exit 1 Can't open output file ; Check while true { ; Loop to copy lines fread \%c line ; Read a line if fail break ; Assume failure = end of file fwrite \%d {\m(line)} ; Write the line to output file if fail exit 1 Write failure ; Failure here is fatal } fclose \%c ; Close the two files fclose \%d Here's the same example using "record i/o" (the open and close sequences are are omitted since they are the same as above). The result is the same, but execution is much faster: while true { ; Loop to copy blocks fread /size:512 \%c block ; Read a block into \%a if fail break ; Assume failure = end of file fwrite /string \%d {\m(block)} ; Write the block to output file if fail exit 1 Write failure ; Failure here is fatal } Although record i/o is faster, it should not be used in line-oriented applications, since it returns arbitrary chunks of the file to your script, rather than lines. In this example, FWRITE /STRING is used rather than FWRITE /SIZE:512 to avoid the last output block being padded beyond the original file's length. A file can also be copied character by character, but this is much slower than line i/o and VERY much slower than block i/o: while true { ; Loop to copy blocks fread /char \%c c ; Read a character into c if fail break ; Assume failure = end of file fwrite /char \%d {\m(c)} ; Write character to output file if fail exit 1 Write failure ; Failure is fatal } Although character i/o is slow, it is the only way to process files that contain NUL characters (i.e. bytes composed of only zero bits). In the example above, when "fread /char \%c c" returns a NUL, the c variable is empty. But since the FREAD /CHAR command did not fail, we know the result was really a NUL. FWRITE /CHAR, when given an empty variable (or no variable at all) writes a NUL. Thus the loop above will copy any file at all (very slowly). In non-copying applications, NULs are detected like this: fread /char \%c c if fail (do something) if not def c (a NUL byte was read) Finally some advanced file operations: FILE FLUSH For output files only: commits all previous writes to disk, in case the computer was buffering them. Synonym: FFLUSH. FILE COUNT [ { /BYTES, /LINES, /LIST, /NOLIST } ] By default, or if the /BYTES switch is given, counts the bytes in the file, if any, open on the given channel. If the /LINES switch is given, counts lines in the file. If the /LIST switch is given, the result is printed. If the /NOLIST switch is given, the result is not printed. /QUIET is a synonym for /NOLIST. If neither /LIST nor /NOLIST is given, the result is printed if the command is given at top level, i.e. not from a command file or macro. In all cases, the result of the most recent FILE COUNT command is stored in the variable \v(f_count). Note that FILE COUNT /LINE works (and can only work) by reading the entire file; expect it to take some time if the file is large. Synonym: FCOUNT. FILE REWIND Moves the read/write pointer to the beginning of the file. Equivalent to FILE SEEK 0. Synonym: FREWIND. FILE SEEK [ switches ] { [{+,-}], LAST, EOF } Moves the read/write pointer for the file on this channel to the given position, which may be a byte (character) number or a line number, expressed in either absolute or relative terms. Switches: /BYTE - The number given is a byte number. Synonym: /CHARACTER. /LINE - The number given is a line number. /ABSOLUTE - The number given is absolute. /RELATIVE - The number given is relative to the current position. By default, or if the /BYTE switch is given, the is a byte number (0 = first byte). If /LINE is given, the is a line number (0 = first line). EOF means to move to the end of the file. LAST means to move to the last line or character of the file, depending on whether it's a line or character seek. If neither the /RELATIVE nor the /ABSOLUTE switch is given, then if a signed number is given, the motion is relative to the current position. An expression that evaluates to a negative number is not considered signed for this purpose; that is, a sign (+ or -) must be included as the first character of the in the command itself to force a relative seek (in the absence of /RELATIVE or /ABSOLUTE). If the number has no sign, or if the /ABSOLUTE switch is given, the number represents an absolute position (relative to the beginning of the file). Subsequent FILE READs or WRITEs will take place at the new position. If the read/write pointer is placed after the end of the file, a subsequent FILE READ will fail, but a FILE WRITE will succeed (possibly creating a file with "holes"). If a FILE SEEK /BYTE command is given, the current line becomes unknown (unless the position is 0) and subsequent FILE SEEK /RELATIVE /LINE commands will fail until the next non-relative FILE SEEK /LINE command is given. Synonym: FSEEK. An absolute FILE SEEK to a negative position fails silently, as does a relative seek to a position before the beginning of the file. A caution about relative SEEKs: remember that the number is relative to the current position. Whenever you read or write, this changes the position. In each of the following examples, assume the file open on channel \%c is positioned at line "n" (the FREAD target variable is omitted for lack of space): { FREAD \%c, FSEEK /LINE \%c -1, FREAD \%c } <-- Reads line n twice { FREAD \%c, FSEEK /LINE \%c +0, FREAD \%c } <-- Reads lines n and n+1 { FREAD \%c, FSEEK /LINE \%c +1, FREAD \%c } <-- Reads lines n and n+2 { FREAD \%c, FSEEK /LINE \%c -2, FREAD \%c } <-- Reads lines n and n-1 { FREAD \%c, FSEEK /LINE \%c -3, FREAD \%c } <-- Reads lines n and n-2 Another caution: Using FSEEK and FREAD /SIZE to repeatedly read the same disk block (e.g. when sampling a database record that is frequently updated) might not give you updated disk blocks due to the internal buffering and caching of the C library (this probably varies from one platform/compiler combination to another). If necessary you can force a fresh disk read with a close/open sequence: FCLOS \%c FOPEN \%c FSEEK \%c FREAD /SIZE: \%c 1.22.3. FILE Command Examples To read the last 10 lines of a text file into an array: fopen /read \%c oofa.txt ; Open the file if fail exit 1 Can't open oofa.txt ; Always check for failure dcl \&a[10] ; Declare a 10-element array fcount /line \%c ; Count lines in the file fseek /line \%c \v(f_count)-10 ; Seek to 10 lines from the end if fail exit 1 Can't seek ; Check for failure for \%i 1 10 1 { fread \%c \&a[\%i] } ; Read the last 10 lines fclose \%c ; Close the file Note that blank lines show up as empty (undefined) array elements, for example if you give a "show array a" command at this point. This is normal. You can still use these elements; e.g.: for \%i 1 10 1 { echo \%i. \&a[\%i] } ; Display the 10 lines Here is how to read the last line of a file (already open on channel \%c): fseek /line \%c last ; Seek directly to last line Alternatively: fseek /line \%c eof ; Seek to end of file fseek /line \%c -1 ; Seek to beginning of last line Alternatively: fcount /line \%c ; Count the file's lines fseek /line \%c \v(f_count)-1 ; Seek to last line fread \%c ; Read it To read every other line from the file (using relative SEEK), skipping the first line: fopen /read \%c oofa.txt ; Open the file while ( success ) { ; Loop through lines fseek /line \%c +1 ; Skip a line if success fread \%c ; Read & display a line } fclose \%c ; Close the file Here is how to read the lines of a file in reverse order: fopen /read \%c oofa.txt ; Open if fail exit 1 ; Check fseek /line \%c last ; Seek to last line while success { ; Loop fread \%c ; Read line fseek /line \%c -2 ; Seek backwards two lines } fclose \%c ; Close the file The loop works because a relative SEEK outside the file fails. It is also possible to use block i/o to manage random-access files with fixed-length records (as long as they don't contain NUL characters). Suppose, for example, you have a file of "card image" records with fixed-field information about customers, such as: Name: Columns 1-32 (column numbers are 1-based) Address: Columns 33-72 Balance: Columns 73-80 The records are indexed by customer number, starting with 0. There are no line terminators separating them. Therefore the record for customer number n starts at position n x 80 (\%n*80). Now suppose we received a payment from customer number 173 and want to update the balance: .\%n = 173 ; Customer (record) number .\%a = 12.72 ; Amount fopen /read /write \%c customer.db ; Open the file if fail stop 1 OPEN FAILED: \f_errmsg() ; Check fseek /byte \%c 80*\%n ; Seek to record fread /size:80 \%c r ; Read the record if fail stop 1 READ FAILED: \f_errmsg() ; Check (IMPORTANT) .\%b := \fright(\m(r),8) ; Extract the balance .\%b := \ffpadd(\%b,\%a,2) ; Add the new payment if fail stop 1 ARITHMETIC ERROR: \%b/\%a ; Catch bad records .r := {\fleft(\m(r),72)\flpad(\%b,8)} ; Update the record fseek /byte \%c 80*\%n ; Reposition to same spot fwrite /size:80 \%c {\m(r)} ; Replace the record if fail stop 1 WRITE FAILED: \f_errmsg() ; Check fclose \%c ; Close the file REMEMBER: Using FILE SEEK to move beyond the end of file can result in a file with holes when writing; when reading, an end-of-file error will occur -- be sure to check for it. 1.22.4. Channel Numbers C-Kermit's channel numbers are integers from 0 to some platform-dependent limit, such as 46 or 1985 (the value of \v(f_max)). This is the limit placed by the operating system on the number of files that may be opened by one process or user or job, minus the standard input, output, and error files, and minus the number of files reserved by C-Kermit for logs, OPEN READ and WRITE, and file transfer (and maybe some command files -- the \v(f_max) number can't be exact). Although you must include a variable in the FILE OPEN command, to which the channel number is assigned, you don't have to use a variable in the other FILE commands if you know what the number is -- you can just put the number. This saves you a few keystrokes when typing commands at the prompt: fopen \%c oofa.txt flist 0. /usr/olga.oofa.txt (R) 0 This tells the channel number is 0 (the number on the left is the channel file's channel number). Of course you can also find it by echoing the variable: echo \%c 0 Or with "fstatus \%c". Now you can type commands like: fread 0 to read a line from the file. Obviously, however, using digits rather than a variable for the channel number would be poor practice in a script. If in commands like: fread \%c \%a you have trouble remembering which variable is which, note that the channel number is, indeed, a number. Anywhere C-Kermit accepts a number it can also accept an expression, so you can put parentheses around the channel number to remind you it's the channel number and not the variable into which data is to be read: fread (\%c) \%a Normally channel numbers are assigned sequentially as 0, 1, 2, ... up to the limit. However, once you start closing files, there can be holes in the sequence. New channels are assigned to fill in the holes. Thus you can't depend on channel numbers being in any particular sequence. 1.22.5. FILE Command Errors Each FILE command sets the variable \v(f_error) to one of the following values: 0 = No error -1 = System error -2 = Attempt to read after end of file -3 = Channel not open -4 = Channel number out of range (negative or too large) -5 = Numeric argument (size, ...) out of range -6 = File not found -7 = Bad or missing filename -8 = Too many files are already open (FILE OPEN only) -9 = Forbidden operation (e.g. write to a read-only file) -10 = Access denied -11 = Illegal combination of OPEN modes (FILE OPEN only) -12 = Buffer overflow -13 = Current line number unknown (for relative line seeks) -14 through -98: Reserved. -99 = Requested operation not implemented in this version of C-Kermit -999 = Unknown error When \v(f_error) is -1, this means the FILE command failed because because of a system error, in which case you can examine the following variables: \v(errno) = System error number. \v(errstring) = Error message corresponding to \v(errno). A special function is available for translating the \v(f_error) code to an error message string: \f_errmsg([code]) If the code is -1, returns error message of the most recent system error; otherwise if the code is a valid \v(f_error) value, the associated message is returned. If the code is omitted, the status message corresponding to the current \v(f_error) value is returned. A FILE command that fails prints the appropriate error message automatically, except when the command is READ or SEEK and the error is -2 (end of file); in that case, the command still fails, but does not print a message. This allows constructions such as: fopen \%c oofa.txt while success { fread \%c } fclose \%c to work as expected, i.e. without an annoying message when the end of file is reached. 1.22.6. File I/O Variables The variables associated with the file i/o package are: \v(f_count) - Result of the most recent FILE COUNT (FCOUNT) command. \v(f_error) - Numeric error code of most recent FILE command (0 = no error). \v(f_max) - Maximum number of files open simultaneously. 1.22.7. File I/O Functions Some of the FILE commands can also be issued as function calls, which makes script writing a bit more convenient, especially for C programmers. Also, several functions are provided that do not have command equivalents. Each of these functions takes a channel number as the first argument. These functions do not work for OPEN { READ, !READ, WRITE, !WRITE, and APPEND } files. \f_status(channel) Returns 0 if the channel is not open, otherwise a number between 1 and 15 which is the sum of the OPEN modes: 1 = /READ 2 = /WRITE 4 = /APPEND 8 = /BINARY The remaining functions work only for open channels. Each of these functions can fail for the applicable reasons listed in Section 1.22.5. For instructions on handling function errors, see Section 7.12. \f_pos(channel) Returns the file's current read/write pointer (0-based). There is no FILE command equivalent. \f_line(channel) Returns the file's current line number (0-based), if known, otherwise -1. There is no FILE command equivalent. The line number is known as long as no character or block i/o has been done on the channel. \f_handle(channel) Returns the "file handle" of the file. That is, it translates the portable C-Kermit channel number into a system-specific file handle or number that can be passed to other programs on the same platform. In UNIX this is a file descriptor. There is no FILE command equivalent. \f_eof(channel) Returns 1 if the read/write pointer of the file on the given channel is at the end of the file, 0 otherwise. Convenient in WHILE statements, e.g.: while not \f_eof(\%c) { fread \%c } \f_getchar(channel) Equivalent to FREAD /CHAR. Returns the character actually read. If \f_getchar() does not fail but the return value is empty, this means a NULL character was read. \f_getline(channel) Equivalent to FREAD /LINE. Returns the line actually read, but with the line terminator stripped. If \f_getline() does not fail but the return value is empty, this normally means an empty line was read. \f_getblock(channel,n) Equivalent to FREAD /SIZE:n. Returns the block of characters actually read. If the returned block is smaller than n, it indicates either that the end of file was reached or a NUL character is in the block. \f_putchar(channel,c) Equivalent to FWRITE /CHARACTER. Writes the character c. If c contains more than one character, only the first is written. If c is empty a NUL is written. Returns the number of characters written on success, or a negative error code upon failure. \f_putline(channel,string) Equivalent to FWRITE /LINE. Writes the string and adds the appropriate line termination character or sequence. If the string is empty or omitted, an empty line is written. Returns the number of characters written on success, or a negative error code upon failure. \f_putblock(channel,string) Equivalent to FWRITE /STRING. Writes the string as given. If the string is empty or omitted, nothing is written. Returns the number of characters written on success, or a negative error code upon failure. 1.22.8. File I/O Function Examples fopen /read \%c oofa.txt ; Open our favorite file for reading if failure exit 1 ; Check that it's open while not \f_eof(\%c) { ; Loop until EOF .line := \f_getline(\%c) ; Get a line if success echo {\m(line)} ; Echo it } if not \f_eof(\%c) { ; Check reason for loop exit exit 1 File Error: \f_errmsg() ; If not EOF say so. } frewind \%c ; Rewind the file while not \f_eof(\%c) { ; Same thing but with block i/o .block := \f_getblock(\%c,256) ; (much faster than line i/o) if success xecho {\m(block)} } frewind \%c ; Rewind again while not \f_eof(\%c) { ; Same deal but with character i/o .c := \f_getchar(\%c) ; (much slower than line i/o) if success xecho {\m(c)} } close \%c To close all open files (equivalent to FCLOSE ALL): for \%i 0 \v(f_max)-1 1 { if \f_status(\%i) fclose \%i } 1.23. The EXEC Command The EXEC command is available only in UNIX. EXEC [ /REDIRECT ] [ [ [ ... ] ] Runs the given command with the arguments in such a way that the replaces C-Kermit in memory, and C-Kermit ceases to execute. EXEC is like RUN, except instead of returning to C-Kermit when finished, the returns to whatever process invoked Kermit. In the normal case, no files are closed, so the EXEC'd command inherits the open files, read/write pointers, working directory, process ID, user ID (unless is SUID), group ID (unless command is SGID), groups, etc. (In UNIX, the EXEC command is simply a front end for execvp().) If the /REDIRECT switch is included, then if a connection is open (SET LINE or SET HOST), it becomes the standard input and output of the EXEC'd program. If no connection is open, the /REDIRECT switch has no effect. For example to use C-Kermit for PPP dialing in Linux: set modem type usr ; Specify the kind of modem you have set line /dev/ttyS1 ; Specify the device it's connected to set speed 57600 ; and the speed set flow rts/cts ; and flow control. set dial retries 100 ; Try the dial sequence up to 100 times. dial {{9-212-555-1212}{9-212-555-1213}{9-212-555-1214}{9-212-555-1215}} if fail exit 1 for \%i 1 16 1 { ; Try up to 16 times to get login prompt input 10 Login: ; Wait 10 sec for it to appear if success break ; Got it - proceed... output \13 ; Send a carriage return and try again } if ( > \%i 16 ) stop 1 NO LOGIN PROMPT lineout \(myuserid) ; Send user ID input 30 assword: ; Wait for Password prompt if fail stop 1 NO PASSWORD PROMPT lineout \m(mypassword) ; Send the password. exec /redirect pppd ; Replace ourselves with pppd. In this example we assume that the script has already set up the myuserid and mypassword variables -- normally the password should be prompted for, rather than stored on disk. Notice the advantages over the well-known "chat script": . You don't have to control the modem itself with AT commands; Kermit's DIAL command does this for you. . You can have Kermit automatically redial as many times as you want until it gets a connection (if this is legal in your country). . You can have Kermit fetch the number or numbers from a dialing directory. . You can have Kermit cycle through a list of phone numbers (this is new to C-Kermit 7.0; see Section 2.1.16) without having to enter the numbers in a dialing directory. . Dialing is location-independent; you can use the same script to dial from different areas or countries. . Once the connection is made, the full power of Kermit's script language is available to manage the dialog with the terminal server or other device that answers the phone call. 1.24. Getting Keyword Lists with '?' Suppose you type "te" at the C-Kermit> prompt and then Esc or Tab to request keyword completion. Kermit beeps, indicating that more than one command starts with "te". But if you type '?' to see what they are, Kermit shows only "telnet". So why the beep? Because of invisible keywords like "telopt", "terminal", and "text". Lots of keywords are invisible because they are either synonyms for other keywords or else esoteric options to be used only in special circumstances, so we don't want them cluttering up the menus. But then there is no way for you to discover them. So in C-Kermit 7.0, if you type '?' AFTER the beginning of a keyword field, then invisible keywords are shown too: C-Kermit>te C-Kermit>te? Command, one of the following: telnet telopt terminal text C-Kermit>te But if '?' is typed at the beginning of a field, only visible keywords are shown, as before (so, in this example, if '?' is typed at the C-Kermit> prompt, "telnet" is the only command shown that starts with "te"). (2) MAKING AND USING CONNECTIONS The SET LINE, SET HOST, and SET PORT (a synonym for SET LINE) commands have new synonyms, in which the word SET is replaced by the word OPEN: OPEN LINE, etc. There is no new functionality here, but OPEN is a better verb, since SET generally takes no action, whereas these commands actually try to open a connection. Furthermore, there is the symmetry with CLOSE. 2.0. SET LINE and SET HOST Command Switches The SET LINE (SET PORT) and SET HOST commands now allow switches before the device or host name, in most cases, and under certain circumstances, also at the end. The new syntax is backwards compatible with the previous syntax; thus SET LINE, SET PORT, and SET HOST commands in command files written for C-Kermit 6.0 or earlier still work. The expanded syntax is: { OPEN,SET } { LINE,PORT,HOST } [ switches ] [ switches ] The first group of switches is: /NETWORK-TYPE:{TCP/IP,X.25,PIPE,PTY...} When more than one network type is available, this lets you specify the type of network to use for this connection without affecting your global SET NETWORK TYPE. See Section 2.7 about pipes and ptys. /USERID:[string] This switch is equivalent to SET LOGIN USERID. If a string is given, it sent to host during Telnet negotiations; if this switch is given but the string is omitted, no user ID is sent to the host. If this switch is not given, your current LOGIN USERID (\v(userid) value), if any, is sent. Unlike most other switches, this one is "sticky", since the value must persist throughout the session in case the server requests the ID string at a later time. /CONNECT Enter CONNECT mode immediately and automatically after the device or connection is open. On serial devices, however, when CARRIER-WATCH is not OFF, wait up to 1 second for the Carrier Detect signal to appear before trying to connect, to give the device time to react DTR, which might have been off prior to opening the device. /SERVER Enter server mode immediately and automatically after the device or connection is open. Treatment of carrier is the same as for /CONNECT. /WAIT /NOWAIT For Telnet connections only: Like SET TELNET WAIT { ON, OFF }, but applies only to this connection, and in fact applies only when OPENing this connection (which is usually the only place it matters). Typically you would use TELNET /NOWAIT to make a connection to a misbehaving Telnet server that does not reply to negotiations as required by the Telnet protocol definition. Note: /CONNECT and /SERVER switches are not available in the RLOGIN and TELNET commands, since these commands already include an implicit /CONNECT and preclude automatic entry into server mode. The /CONNECT and /SERVER switches are especially useful with "set host *" connections. For example, suppose you want to start a Kermit server on socket 3000 of your TCP host. Normally you would have to give the command: set host * 3000 and then wait for a connection to come in, and only then could you give the SERVER command (or else define a macro to do this, and then execute the macro). Now you can do it in one step: set host /server * 3000 This tells C-Kermit to wait for the connection and then enter server mode once it comes in, no matter how long it takes. Similarly, "set host /conn *" can be used to wait for a "chat" connection to come in. Another set of switches is available in VMS only, for use only with SET LINE: /SHARE Allows the SET LINE device to be opened in shared mode. Normally it makes no sense to open a serial device in shared mode, but it's necessary when C-Kermit is running in an environment such as DECIntact, that opens your job's controlling terminal in such a way that C-Kermit can't open it too, unless it enables SHARE privilege. Note: SHARE privilege is required. /NOSHARE Requires that the SET LINE device not be in use by any other process in order for it to be successfully opened by C-Kermit. If neither /SHARE nor /NOSHARE is specified, /NOSHARE is used. The second group of switches is: /NO-TELNET-INIT Do not send initial Telnet negotiations even if this is a Telnet port. /RAW-SOCKET This is a connection to a raw TCP socket (Section 2.3.5). /RLOGIN Use Rlogin protocol even if this is not an Rlogin port. /TELNET Send initial Telnet negotiations even if this is not a Telnet port. As of C-Kermit 7.0 and K95 1.1.18, the TELNET command includes an implicit /TELNET switch. So if you TELNET to a non-TELNET port, Kermit sends initial Telnet negotiations. This makes sense, since that's what "telnet" means. If you want to make a connection to a non-Telnet port without sending initial Telnet negotiations, use: set host [ /connect ] or: telnet /no-telnet-init Additional switches might be added in the future; type "set host ?" or "set line ?" to see a current list. 2.1. Dialing Automatic redialing is illegal or restricted in many countries, so until C-Kermit 7.0, it was disabled by default, i.e. until a SET DIAL RETRIES command was given. In C-Kermit 7.0, if no SET DIAL RETRIES command has been given, a default is picked dynamically at DIAL time based on the calling country code, if known. At this writing, the only country code known to have no restrictions on automatic redialing is 1. So in this case a limit of 10 is chosen; otherwise 1. If you have not given an explicit SET DIAL RETRIES command, SHOW DIAL shows the value as "(auto)", and then the value actually used is shown when you give the DIAL command. As of C-Kermit 7.0, automatic redialing is automatically canceled if the call could not be placed because no dialtone was detected. 2.1.1. The Dial Result Message If DIAL DISPLAY is not ON, the "Call complete" message now shows the modem's call result message, for example: Dialing: ... Call complete: "CONNECT 31200/ARQ/V32/LAPM/V42BIS" The exact format and contents of this message, of course, depends on the make, model, and configuration of your modem, so use your modem manual to interpret it. The call result message is also available in C-Kermit's \v(dialresult) variable. C-Kermit> echo \v(dialresult) CONNECT 31200/ARQ/V32/LAPM/V42BIS C-Kermit> echo Speed = \fword(\v(dialresult),2) Speed = 31200 C-Kermit> Suppose your modem reports the modulation speed as shown above and you want to ensure your call is completed at (say) 24000 bps or more. You can use a little macro to do the job: define HSDIAL { ; High Speed DIAL local \%s if < \v(argc) 1 if not def \v(dialnumber) end 1 Usage: \%0 number set dial retries 100 set dial interval 1 while true { dial \%* if fail end 1 DIAL failed. asg \%s \fword(\v(dialresult),2) if def \%s if numeric \%s if not < \%s 24000 break } } (See section 7.5 about the \%* variable.) 2.1.2. Long-Distance Dialing Changes Due to the glut of cell phones, pagers, fax machines, ISPs, etc, area codes and dialing rules are changing all the time. In the North American Numbering Plan (NANP) countries (USA, Canada, etc), area codes are split or overlayed with increasing frequency, and 10- and 11-digit dialing is gradually becoming the norm for local calls. Changes are occurring In Europe, too, partly for these reasons and partly because of some new EC rules. In France, effective 18 October 1996, all calls, even local ones, must be dialed with an area code. French area codes are presently 1-digit numbers, 1-6, and the long-distance dialing prefix is 0. All calls within France are considered long distance and begin with 01, 02, ..., 06. Effective 1 May 1997, all calls within the US state of Maryland, even local ones, must be dialed with an area code but WITHOUT the long-distance prefix -- this is the now widely-known North American phenomenon of "ten digit dialing". The same is happening elsewhere -- many cities in Florida adopted 10-digit dialing in 1998. In Italy beginning 19 June 1998, all calls to fixed (as opposed to mobile) numbers must be prefixed by 0. When calling into Italy from outside, the 0 must follow the country code (39). Calls to cell phones, however, must be placed without the 0. Then on 29 December 2000, the 0 will become a 4 (for calling fixed numbers) and a prefix of 3 must used for calling mobile phones. More info at: http://www.telecomitalia.it/npnn/. In Spain, effective 4 April 1998, with hard cutover on 18 July 1998, all calls within the country must be dialed with 9 digits, and all calls from outside Spain must also be dialed with 9 digits (after the country code, 34). The new 9-digit numbers all begin with "9". More info at: http://www.telefonica.es/cambiodenumeracion/ Several new dialing features and commands have been added in version 6.1 and 7.0 to address these changes. C-Kermit 6.0 and Kermit 95 1.1.11 and earlier handle the French situation via a reasonable subterfuge (setting the local area code to a nonexistent one), but did not handle "ten-digit dialing" well at all; the recommended technique was to change the long-distance dialing prefix to nothing, but this defeated Kermit's "list numbers for one name" feature when the numbers were in different locations. For example: set dial ld-prefix dial onlineservice where "onlineservice" is a dialing directory entry name corresponding to entries that are in (say) Maryland as well as other states, would not correctly dial the numbers not in Maryland. A new command lets you specify a list of area codes to be considered local, except that the area code must be dialed: SET DIAL LC-AREA-CODES [ areacode [ areacode [ areacode [ ... ] ] ] ] The list may include up to 32 area codes. If a number is called whose area code is in this list, it is dialed WITHOUT the long-distance prefix, but WITH the area code. So in Maryland, which (last time we looked) has two area codes, 410 and 301, the setup would be: SET DIAL LC-AREA-CODES 410 301 Example: SET DIAL LD-PREFIX 1 SET DIAL AREA-CODE 301 SET DIAL LC-AREA-CODES 410 301 <-- Area codes in 10-digit dialing region DIAL +1 (301) 765-4321 <-- Dials 3017654321 (local with area code) DIAL +1 (410) 765-4321 <-- Dials 4107654321 (local with area code) DIAL +1 (212) 765-4321 <-- Dials 12127654321 (long distance) The SET DIAL LC-AREA-CODES command does not replace the SET DIAL AREA-CODE command. The latter specifies the area code you are dialing from. If the called number is in the same area code, then the area code is dialed if it is also in the LC-AREA-CODES list, and it is not dialed otherwise. So if "301" had not appeared in the LC-AREA-CODES list in the previous example: SET DIAL LD-PREFIX 1 SET DIAL AREA-CODE 301 SET DIAL LC-AREA-CODES 410 <-- Area codes in 10-digit dialing region DIAL +1 (301) 765-4321 <-- Dials 7654321 (local) DIAL +1 (410) 765-4321 <-- Dials 4107654321 (local with area code) DIAL +1 (212) 765-4321 <-- Dials 12127654321 (long distance) The new Kermit versions also add a Local Call Prefix and Local Call Suffix, in case you have any need for it. These are added to the beginning and of local phone numbers (i.e. numbers that are not long-distance or international). Examples: SET DIAL LD-PREFIX 1 SET DIAL LC-PREFIX 9 SET DIAL LC-SUFFIX * SET DIAL LC-AREA-CODES 410 <-- Area codes in 10-digit dialing region SET DIAL AREA-CODE 301 DIAL +1 (301) 765-4321 <-- Dials 97654321* (local) DIAL +1 (410) 765-4321 <-- Dials 94107654321* (local with area code) DIAL +1 (212) 765-4321 <-- Dials 12127654321 (long distance) 2.1.3. Forcing Long-Distance Dialing Suppose a number is in your country and area, but for some reason you need to dial it long-distance anyway (as is always the case in France). There have always been various ways to handle this: 1. Temporarily set your area code to a different (or nonexistent or impossible) one (but this required knowledge of which area codes were nonexistent or impossible in each country). 2. Dial the number literally instead of using the portable format, but this defeats the purpose of the portable dialing directory. Now there is also a new command that, very simply, can force long-distance dialing: SET DIAL FORCE-LONG-DISTANCE { ON, OFF } If a call is placed to a portable phone number within the same country code as the calling number, it is dialed with the long-distance prefix and the area code if FORCE-LONG-DISTANCE is ON. If OFF, the regular rules and procedures apply. Example (France): SET DIAL COUNTRY-CODE 33 SET DIAL AREA-CODE 6 SET DIAL FORCE-LONG-DISTANCE ON (In fact, SET DIAL COUNTRY-CODE 33 automatically sets DIAL FORCE-LONG-DISTANCE ON...) Example (USA, for a certain type of reverse-charge calling in which the called number must always be fully specified): SET DIAL PREFIX 18002666328$ ; 1-800-COLLECT SET DIAL COUNTRY-CODE 1 SET DIAL AREA-CODE 212 SET DIAL FORCE-LONG-DISTANCE ON Example (Toronto, where calls to exchange 976 within area code 416 must be dialed as long distance, even when you are dialing from area code 416): SET DIAL COUNTRY-CODE 1 SET DIAL AREA-CODE 416 SET DIAL FORCE-LONG-DISTANCE ON DIAL +1 (416) 976-xxxx If dialing methods were consistent and sensible, of course it would be possible to always dial every domestic call as if it were long distance. But in many locations this doesn't work or if it does, it costs extra. The following macro can be used for dialing any given number with forced long-distance format: define LDIAL { local \%x set dial force-long-distance on dial \%* asg \%x \v(success) set dial force-long-distance off end \%x } (See section 7.5 about the \%* variable.) 2.1.4. Exchange-Specific Dialing Decisions This applies mainly to the North American Numbering Plan (NANP). Refer to the section "Alternative notations" in "Using C-Kermit" 2nd Edition, pages 106-107, and the story about Toronto on page 110. Using the new LC-AREA-CODES list, we can address the problem by treating the exchange as part of the area code: SET DIAL LD-PREFIX 1 SET DIAL AREA-CODE 416 SET DIAL LC-AREA-CODES 905276 DIAL +1 416 765 4321 <-- 7654321 (local) DIAL +1 905 276 4321 <-- 9052764321 (local with area code) DIAL +1 905 528 4321 <-- 19055284321 (long distance) The same technique can be used in Massachusetts (story at top of page 111) and in any other place where dialing to some exchanges within a particular area code is local, but to others in the same area code is long distance. 2.1.5. Cautions about Cheapest-First Dialing Kermit does not maintain a knowledge base of telephony information; it only provides the tools to let you enter a phone number in a standard format and dial it correctly from any location in most cases. In particular, Kermit does not differentiate the charging method from the dialing method. If a call that is DIALED as long-distance (e.g. from 212 to 718 in country code 1) is not CHARGED as long distance, we have no way of knowing that without keeping a matrix of charging information for every area-code combination within every country, and any such matrix would be obsolete five minutes after it was constructed. Thus, "cheapest-first" sorting is only as reliable as our assumption that the charging method follows the dialing method. A good illustration would be certain online services that have toll-free dialup numbers which they charge you a premium (in your online service bill) for using. 2.1.6. Blind Dialing (Dialing with No Dialtone) C-Kermit's init string for Hayes-like modems generally includes an X4 command to enable as many result codes as possible, so that Kermit can react appropriately to different failure reasons. One of the result codes that X4 enables is "NO DIALTONE". A perhaps not obvious side effect of enabling this result code that the modem must hear dialtone before it will dial. It is becoming increasingly necessary to force a modem to dial even though it does not hear a dialtone on the phone line; for example, with PBXs that have strange dialtones, or with phone systems in different countries, or with ISDN phones, etc. This is called "blind dialing". C-Kermit 7.0 has two new commands to cope with this situation: SET DIAL IGNORE-DIALTONE { ON, OFF } OFF (the default) means to tell the modem to wait for dialtone before dialing. ON means to enable "blind dialing", i.e. tell the modem NOT to wait for dialtone before dialing. Generally this is accomplished by sending ATX3 to the modem just prior to dialing. SET MODEM TYPE xxx and then SHOW MODEM displays Kermit's built-in "ignore dialtone" command. SET DIAL COMMAND IGNORE-DIALTONE This lets you change the built-in ignore-dialtone command (such as ATX3) to whatever you choose, in case the built-in one does not work, or another command works better. Notes: 1. The ignore-dialtone command is not sent unless SET DIAL IGNORE-DIALTONE is ON. 2. The ATX3 command generally disables not only NO DIALTONE, but also BUSY. So this will prevent Kermit from detecting when the line is busy. This is a property of the modem, not of Kermit. 2.1.7. Trimming the Dialing Dialog The command: SET MODEM COMMAND [ ] is used to override Kermit's built-in modem commands for each action, for each kind of modem in its internal database. If you include a , this is used instead of the built-in one. If you omit the , this restores the original built-in command. If you want to omit the command altogether, so Kermit doesn't send the command at all, or wait for a response, use: SET MODEM COMMAND {} That is, specify a pair of empty braces as the command, for example: SET MODEM COMMAND ERROR-CORRECTION ON {} 2.1.8. Controlling the Dialing Speed The rate at which characters are sent to the modem during dialing is normally controlled by the built-in modem database. You might want to override this if Kermit seems to be dialing too slowly, or it is sending characters to the modem faster than the modem handle them. A new command was added for this in C-Kermit 7.0: SET DIAL PACING Specifies the number of milliseconds (thousandths of seconds) to pause between each character when sending commands to the modem during DIAL or ANSWER command execution. 0 means no pause at all, -1 (the default) or any other negative number means to use the value from the database. Any number greater than 0 is the number of milliseconds to pause. HINT: You might also need to control the rate at which the modem generates Touch Tones during dialing, for example when sending a numeric page. There are two ways to do this. One way is to insert pause characters into the dialing string. For modems that use the AT command set, the pause character is comma (,) and causes a 2-second pause. On most modems, you can use the S8 register to change the pause interval caused by comma in the dialing string. The other way is to set your modem's tone generation interval, if it has a command for that. Most AT-command-set modems use S11 for this; the value is in milliseconds. For example on USR modems: ATS11=200 selects an interval of 200 milliseconds to separate each dialing tone. Hint: To add S-Register settings or other commands to your dialing procedure, use the new SET MODEM COMMAND PREDIAL-INIT command (Section 2.2.2). 2.1.9. Pretesting Phone Number Conversions The LOOKUP command now accepts telephone numbers as well as directory-entry names, for example: LOOKUP +1 (212) 7654321 When given a phone number, LOOKUP prints the result of converting the phone number for dialing under the current dialing rules. For example, if my country code is 1 and my area code is 212, and I am dialing out from a PBX whose outside-line prefix is "93,": C-Kermit> lookup +1 (212) 7654321 +1 (212) 7654321 => 93,7654321 C-Kermit> You can also use the \fdialconvert(phone-number) function (Section 2.1.11) to do this programmatically: C-Kermit> echo "\fdialconvert(+1 (212) 7654321)" "93,7654321" C-Kermit> So the new LOOKUP behaves as follows: LOOKUP Displays how the number would actually be dialed Sets FAILURE if there was a conversion error, otherwise SUCCESS. LOOKUP Displays the same Always sets SUCCESS. LOOKUP Displays all matching entries and converts portable phone numbers. Sets SUCCESS if at least one entry was found, otherwise FAILURE. LOOKUP =anything Displays "=anything" and sets SUCCESS. There is, at present, no programmatic way to fetch numbers from the dialing directory. This will be considered for a future release. 2.1.10. Greater Control over Partial Dialing The following rules now apply to partial dialing: . Phone number transformations based on country and area code, application of prefixes, etc, are performed only on the first PDIAL. . Each PDIAL argument is looked up in the dialing directory, so it is possible have directory entries for pieces of phone numbers or other information. . Suffixes are not applied automatically, since there is no way for C-Kermit to know in which PDIAL segment you want them to be applied. However, the suffix that *would* have been applied, based on the dialing rules that were invoked when processing the first PDIAL command, is stored in the variable: \v(dialsuffix) which you can include in any subsequent PDIAL or DIAL commands. Example: pdial {\m(my_long_distance_pager_number_part_1)} pdial {\m(my_long_distance_pager_number_part_2)} pdial {\v(dialsuffix)} pdial {\m(my_long_distance_pager_number_part_3)} pdial {@\m(numeric_pager_code)#} 2.1.11. New DIAL-related Variables and Functions \fdialconvert(s) s is a phone number in either literal or portable format (not a dialing directory entry name). The function returns the dial string that would actually be used by the DIAL command when dialing from the current location, after processing country code, area code, and other SET DIAL values, and should be the same as the result of LOOKUP when given a telephone number. \v(dialsuffix) Contains the suffix, if any, that was applied in the most recent DIAL command, or the suffix that would have been applied in the most recent PDIAL command. Use this variable to send the dial suffix at any desired point in a PDIAL sequence. \v(dialtype) A number indicating the type of call that was most recently placed. Can be used after a normal DIAL command, or after the first PDIAL command in a PDIAL sequence. Values are: -2: Unknown because TAPI handled the phone number translation. -1: Unknown because some kind of error occured. 0: Internal within PBX. 1: Toll-free. 2: Local within calling area. 3: Unknown (e.g. because a literal-format phone number was given). 4: Long distance within country. 5: International \v(dialcount) The current value of the DIAL retry counter, for use in a DIAL macro (Section 2.1.13). \v(d$px) PBX Exchange (see Section 2.1.12). Other dial-related variables, already documented in "Using C-Kermit" (or other sections of this document, e.g. 2.1.1), include \v(dialnumber), \v(dialstatus), etc. A convenient way to display all of them is: show variable dial ; hint: abbreviate "sho var dial" This shows the values of all the variables whose names start with "dial". Also "show variable d$" (to show the \v(d$...) variables). 2.1.12. Increased Flexibility of PBX Dialing Refer to "Using C-Kermit", 2nd Edition, pages 107-108. Recall that three commands are needed to configure C-Kermit for dialing from a PBX: SET DIAL PBX-EXCHANGE SET DIAL PBX-INSIDE-PREFIX SET DIAL PBX-OUTSIDE-PREFIX Unfortunately, this model does not accommodate PBXs that have more than one exchange. For example our PBX at Columbia University (which must handle more than 10,000 phones) has 853-xxxx and 854-xxxx exchanges. Beginning in C-Kermit 7.0, the SET DIAL PBX-EXCHANGE command accepts a list of exchanges, e.g.: SET DIAL PBX-EXCHANGE 853 854 (multiple exchanges are separated by spaces, not commas). So now when dialing a portable-format number that has the same country and area codes as those of your dialing location, C-Kermit compares the exchange of the dialed number with each number in the PBX Exchange list (rather than with a single PBX Exchange number, as it did formerly) to determine whether this is an internal PBX number or an external call. If it is an external call, then the PBX Outside Prefix is applied, and then the normal dialing rules for local or long-distance calls. If it is an inside call, the exchange is replaced by the PBX Inside Prefix. But if the PBX has more than one exchange, a single fixed PBX Inside Prefix is probably not sufficient. For example, at Columbia University, we must dial 3-xxxx for an internal call to 853-xxxx, but 4-xxxx for a call to 854-xxxx. That is, the inside prefix is the final digit of the exchange we are dialing. For this reason, C-Kermit 7.0 provides a method to determine the inside prefix dynamically at dialing time, consisting of a new variable and new syntax for the SET DIAL PBX-INSIDE-PREFIX command: \v(d$px) This variable contains the exchange that was matched when a PBX internal call was detected. For example, if the PBX exchange list is "853 854" and a call is placed to +1 (212) 854-9999, \v(d$px) is set to 854. SET DIAL PBX-INSIDE-PREFIX \fxxx(...) If the PBX Inside Prefix is defined to be a function, its evaluation is deferred until dialing time. Normally, this would be a string function having \v(d$px) as an operand. Of course, you can still specify a constant string, as before. So given the following setup: SET DIAL COUNTRY-CODE 1 SET DIAL AREA-CODE 212 SET DIAL PBX-OUTSIDE-PREFIX 93, SET DIAL PBX-EXCHANGE 853 854 SET DIAL PBX-INSIDE-PREFIX \fright(\v(d$px),1) The following numbers give the results indicated: Number Result +1 (212) 854-9876 4-9876 +1 (212) 853-1234 3-1234 +1 (212) 765-4321 93,765-4321 +1 (333) 765-4321 93,1333765-4321 Furthermore, the K_PBX_XCH environment variable may now be set to a list of exchanges to automatically initialize C-Kermit's PBX exchange list, for example (in UNIX ksh or bash): export K_PBX_XCH="853 854" (Quotes required because of the space.) Of course, this variable can also be set to a single exchange, as before: export K_PBX_XCH=853 2.1.13. The DIAL macro - Last-Minute Phone Number Conversions After a DIAL or LOOKUP command is given, a list of phone numbers is assembled from the dialing directory (if any), with all location-dependent conversion rules applied as described in Chapter 5 of "Using C-Kermit". However, additional conversions might still be required at the last minute based on local or ephemeral conditions. So that you can have the final word on the exact format of the dial string, C-Kermit 7.0 lets you pass the converted string through a macro of your own design for final processing before dialing. The relevant command is: SET DIAL MACRO [ name ] Specifies the name of a macro to be run on each phone number after all built-in conversions have been applied, just before the number is dialed. If no name is given, no macro is run. The phone number, as it would have been dialed if there were no dial macro, is passed to the macro. The dial macro can do anything at all (except start a file transfer). However, the normal use for the macro would be to modify the phone number. For this reason the phone number is passed to the macro as argument number 1 (\%1). To cause a modified number to be dialed, the macro should terminate with a RETURN statement specifying a return value. To leave the number alone, the macro should simply end. Example: define xxx return 10108889999$\%1 set dial macro xxx dial xyzcorp This defines a DIAL MACRO called xxx, which puts an access code on the front of the number. Another example might be: def xxx if equal "\v(modem)" "hayes-1200" return \freplace(\%1,$,{,,,,,}) set dial macro xxx dial xyzcorp which replaces any dollar-sign in the dial string by a series of five commas, e.g. because this particular modem does not support the "wait for bong" feature (remember that commas that are to be included literally in function arguments must be enclosed in braces to distinguish them from the commas that separate the arguments) and when the IF condition is not satisfied, the macro does not return a value, and so the number is not modified. Then when a DIAL command is given referencing a dialing directory entry, "xyzcorp". The macro is automatically applied to each matching number. Numerous dial-, modem-, communications-, and time-related variables are available for decision making your dial macro. Type SHOW VARIABLES for a list. Of particular interest is the \v(dialcount) variable, which tells how many times the DIAL command gone through its retry loop: 1 on the first try, 2 on the second, 3 on the third, and so on, and the \v(dialresult) and \v(dialstatus) variables. Here are some other applications for the DIAL MACRO (from users): . Phone numbers in the dialing directory are formatted with '-' for readability, but some modems don't like the hyphens, so the DIAL macro is used to remove them before dialing; e.g 0090-123-456-78-99 becomes 00901234567899: "def xxx return \freplace(\%1,-)". . To set some specific modem (or other) options depending on the called customer or telephone number. . Choosing the most appropriate provider based on (e.g.) time of day, or cycling through a list of providers in case some providers might be busy. To illustrate the final item, suppose you have a choice among many phone service providers; the provider is chosen by dialing an access code before the number. Different providers might be better (e.g. cheaper) for certain times of day or days of the week, or for dialing certain locations; you can use the DIAL macro to add the access for the most desirable provider. Similarly, when the same number might be reached through multiple providers, it's possible that one provider might not be able to complete the call, but another one can. In that case, you can use the DIAL macro to switch providers each time through the DIAL loop -- that's where the \v(dialcount) variable comes in handy. The following command can be used to debug the DIAL macro: SET DIAL TEST { ON, OFF } Normally OFF, so the DIAL command actually dials. When ON, the DIAL command performs all lookups and number conversions, and then goes through the number list and retry loop, but instead of actually dialing, lists the numbers it would have called if none of the DIAL attempts succeeded (or more precisely, every number was always busy). 2.1.14. Automatic Tone/Pulse Dialing Selection SET DIAL METHOD { AUTO, DEFAULT, PULSE, TONE } Chooses the dialing method for subsequent calls. Prior to version 7.0, C-Kermit's DIAL METHOD was DEFAULT by default, meaning it does not specify a dialing method to the modem, but relies on the modem to have an appropriate default dialing method set. So, for example, when using Hayes compatible modems, the dial string would be something like ATD7654321, rather than ATDT7654321 or ATDP7654321. In C-Kermit 7.0 and K95 1.1.18, the dial method can be set from the environment variable: K_DIAL_METHOD when Kermit starts. The values can be TONE, PULSE, or DEFAULT, e.g. (UNIX): set K_DIAL_METHOD=TONE; export K_DIAL_METHOD In the absence of a K_DIAL_METHOD definition, the new default SET DIAL METHOD is AUTO rather than DEFAULT. When DIAL METHOD is AUTO and the local country code is known, then if tone dialing is universally available in the corresponding area, tone dialing is used; if dialing from a location where pulse dialing is mandatory, pulse dialing is used. The "tone country" and "pulse country" lists are preloaded according to our knowledge at the time of release. You can see their contents in the SHOW DIAL listing. You can change the lists with: SET DIAL TONE-COUNTRIES [ cc [ cc [ ... ] ] ] Replaces the current TONE-COUNTRIES list with the one given. Each cc is a country code; separate them with spaces (not commas). Example: set dial tone-countries 1 358 44 46 49 If no country codes are given, the current list, if any, is removed, in which case SET DIAL METHOD AUTO is equivalent to SET DIAL METHOD DEFAULT. SET DIAL PULSE-COUNTRIES [ cc [ cc [ ... ] ] ] Replaces the current PULSE-COUNTRIES list with the one give. Syntax and operation is like SET DIAL TONE-COUNTRIES. If the same country code appears in both lists, Pulse takes precedence. The SET DIAL TONE- and PULSE-COUNTRIES commands perform no verification whatsoever on the cc's, since almost any syntax might be legal in some settings. Furthermore, there is no facility to edit the lists; you can only replace the whole list. However, since the only purpose of these lists is to establish a basis for picking tone or pulse dialing automatically, all you need to override the effect of the list is to set a specific dialing method with SET DIAL METHOD TONE or SET DIAL METHOD PULSE. 2.1.15. Dial-Modifier Variables As of C-Kermit 7.0, dial modifiers are available in the following variables: \v(dm_lp) Long pause \v(dm_sp) Short pause \v(dm_pd) Pulse dial \v(dm_td) Tone dial \v(dm_wa) Wait for answer \v(dm_wd) Wait for dialtone \v(dm_rc) Return to command mode You can use these in your dial strings in place of hardwired modifiers like "@", ",", etc, for increased portability of scripts. Example: C-Kermit>set modem type usrobotics C-Kermit>sho variables dm \v(dm_lp) = , \v(dm_sp) = / \v(dm_pd) = P \v(dm_td) = T \v(dm_wa) = @ \v(dm_wd) = W \v(dm_rc) = ; C-Kermit>exit 2.1.16. Giving Multiple Numbers to the DIAL Command Prior to C-Kermit 7.0, the only way to give a DIAL command a list of phone numbers to try until one answers was to create a dialing directory that had multiple entries under the same name, and then use that entry name in the DIAL command. Now a list of numbers can be given to the DIAL command directly in the following format: dial {{number1}{number2}{number3}...} This is the same list format used by SEND /EXCEPT: and other commands that allow a list where normally a single item is given. Restrictions on this form of the DIAL command are: . The first two braces must be adjacent; spacing is optional thereafter. . Each number must be an actual number to dial, not a dialing directory entry. . Dialing directory entries may not contain number lists in this format. In all other respects, the numbers are treated as if they had been fetched from the dialing directory; they can be in literal or portable format, etc. Example: dial {{7654321} {+1 (212) 5551212} { 1-212-5556789 }} The list can be any length at all, within reason. This feature is especially handy for use with the K95 Dialer, allowing a list of phone numbers to be specified in the Telephone Number box without having to set up or reference a separate dialing directory. You can also use it to add commonly-dialed sequences as variables in your C-Kermit customization file, e.g.: define work {{7654321}{7654322}{7654323}} and then: dial {\m(work)} (the variable name must be enclosed in braces). Or more simply: define work dial {{7654321}{7654322}{7654323}} and then: work 2.2. Modems 2.2.1. New Modem Types Since C-Kermit 6.0: atlas-newcom-33600ifxC Atlas/Newcom 33600 att-keepintouch AT&T KeepinTouch PCMCIA V.32bis Card Modem att-1900-stu-iii AT&T Secure Data STU-III Model 1900 att-1910-stu-iii AT&T Secure Data STU-III Model 1910 bestdata Best Data cardinal Cardinal V.34 MVP288X series. compaq Compaq Data+Fax (e.g. in Presario) fujitsu Fujitsu Fax/Modem Adapter generic-high-speed Any modern error-correcting data-compressing modem itu-t-v25ter/v250 ITU-T (CCITT) V.25ter (V.250) standard command set megahertz-att-v34 Megahertz AT&T V.34 megahertz-xjack Megahertz X-Jack motorola-codex Motorola Codex 326X Series motorola-montana Motorola Montana mt5634zpx Multitech MT5634ZPX rockwell-v90 Rockwell V.90 56K rolm-244pc Siemens/Rolm 244PC (AT command set) rolm-600-series Siemens/Rolm 600 Series (AT command set) spirit-ii QuickComm Spirit II suprasonic SupraSonic V288+ supra-express-v90 Supra Express V.90 One of the new types, "generic-high-speed" needs a bit of explanation. This type was added to easily handle other types that are not explicitly covered, without going through the bother of adding a complete user-defined modem type. This one works for modern modems that use the AT command set, on the assumption that all the default ("factory") settings of the modem (a) are appropriate for Kermit, (b) include error correction, data compression, and speed buffering; and (c) are recallable with the command AT&F. If the command to recall your modem's profile is not AT&F, use the SET MODEM COMMAND INIT-STRING command to specify the appropriate modem command. The default init-string is AT&F\13 (that is, AT, ampersand, F, and then carriage return); a survey of about 20 modern modem types shows they all support this, but they might mean different things by it. For example, the USR Sportster or Courier needs AT&F1 (not AT&F, which is equivalent to AT&F0, which recalls an inappropriate profile), so for USR modems: set modem type generic-high-speed set modem command init AT&F1\13 Of course, USR modems already have their own built-in modem type. But if you use this one instead, it will dial faster because it has fewer commands to give to the modem; in that sense "&F1" is like a macro that bundles numerous commands into a single one. See your modem manual for details about factory profiles and commands to recall them. WARNING: Do not use the generic-high-speed modem type in operating systems like VMS where hardware flow control is not available, at least not unless you change the init string from AT&F\13 to something else that enables local Xon/Xoff or other appropriate type of flow control. Also see Section 2.1.7 for additional hints about making dialing go faster. 2.2.2. New Modem Controls SET MODEM CAPABILITIES In C-Kermit 7.0, this command automatically turns MODEM SPEED-MATCHING OFF if SB (Speed Buffering) is in the , and turns it ON if SB is absent. SET MODEM COMMAND PREDIAL-INIT [ ] Commands to be sent to the modem just prior to dialing. Normally none. SET MODEM SPEAKER { ON, OFF } Determines whether modem speaker is on or off while call is being placed. ON by default. Note: This command does not provide fine-grained control over when the speaker is on or off. Normally, ON means while the call is being placed, until the point at which carrier is successfully established. If your modem has a different speaker option that you want to choose, then use the SET MODEM COMMAND SPEAKER ON command to specify this option. SET MODEM COMMAND SPEAKER { ON, OFF } [ ] Specify or override the commands to turn your modem's speaker on and off. SET MODEM VOLUME { LOW, MEDIUM, HIGH } When MODEM SPEAKER is on, select volume. Note: In some modems, especially internal ones, these commands have no effect; this is a limitation of the particular modem, not of Kermit. SET MODEM COMMAND VOLUME { LOW, MEDIUM, HIGH } [ ] Specify or override the commands to set your modem's speaker volume. SET MODEM COMMAND IGNORE-DIALTONE [ ] The command to enable blind dialing (section 2.1.6). SET MODEM ESCAPE-CHARACTER Has been augmented to allow codes of 0 or less: < 0 means the escape mechanism is disabled. = 0 means to use (restore) the default value from the modem database. > 0 and < 128 is a literal value to be used instead of the default one. > 127 means the escape mechanism is disabled. This affects "modem hangup". When the escape mechanism is disabled, but SET MODEM HANGUP-METHOD is MODEM-COMMAND, it sends the hangup command immediately, without the +++ business first. This is useful (for example) when sending lots of numeric pages, a process in which we never go online, and so never need to escape back. Eliminating the unnecessary pauses and escape sequence allows a lot more pages to be sent per unit time. Recall that C-Kermit can dial modems to which it is connected via TCP/IP (Telnet or Rlogin) as described on page 126 of "Using C-Kermit", 2nd Ed. In this case the MODEM HANGUP-METHOD should be MODEM-COMMAND, since RS-232 signals don't work over TCP/IP connections. As noted in the manual, such connections are set up by the following sequence: set host [ ] set modem type dial But this can cause complications when you use Kermit to switch between serial and TCP/IP connections. In the following sequence: set host set modem type set port the first two commands obey the rules for dialing out over Telnet. However, the SET PORT command requires that Kermit close its current (Telnet) connection before it can open the serial port (since Kermit can only have one connection open at a time). But since a modem type was set after the "set host" command was given, Kermit assumes it is a Telnet dialout connection and so sends the modem's hangup sequence is sent to the Telnet host. To avoid this, close the network connection explicitly before opening the serial one: set host close set modem type set port 2.3. TELNET and RLOGIN For additional background, please also read the TELNET.TXT file. Cautions: If making a Telnet connection with C-Kermit takes a very long time, like over a minute, whereas the system Telnet program makes the same connection immediately, try including the /NOWAIT switch: C-Kermit> telnet /nowait hostname See TELNET.TXT for details. If it also takes a very long time to make a Telnet connection with system Telnet, then the delay is most likely caused by reverse DNS lookups when your host is not properly registered in DNS. When supplying numeric IP addresses to C-Kermit or to any other application (regular Telnet, Rlogin, etc), do not include leading 0's in any fields unless you intend for those fields to be interpreted as octal (or hex) numbers. The description of the Internet address interpreter (the sockets library inet_addr() routine) includes these words: All numbers supplied as "parts" in a "." notation may be decimal, octal, or hexadecimal, as specified in the C language (that is, a leading 0x or 0X implies hexadecimal; otherwise, a leading 0 implies octal; otherwise, the number is interpreted as decimal). To illustrate, 128.59.39.2 and 128.059.039.002 are NOT the same host! Even though most of the fields contain non-octal digits. Using system Telnet (not Kermit): $ telnet 128.059.039.002 Trying 128.49.33.2 ... Of course the same thing happens with Kermit because it uses (as it must) the same system service for resolving network addresses that Telnet, FTP, and all other TCP/IP applications use. The RLOGIN section on page 123 does not make it clear that you can use the SET TELNET TERMINAL-TYPE command to govern the terminal type that is reported by C-Kermit to the RLOGIN server. Note that the SET TCP commands described on pages 122-123 might be absent; some platforms that support TCP/IP do not support these particular controls. New commands: TELOPT { AO, AYT, BREAK, CANCEL, EC, EL, EOF, EOR, GA, IP, DMARK, DO, DONT, NOP, SB, SE, SUSP, WILL, WONT } This command was available previously, but supported only DO, DONT, WILL, and WONT. Now it lets you send all the Telnet protocol commands. Note that certain commands do not require a response, and therefore can be used as nondestructive "probes" to see if the Telnet session is still open; e.g.: set host xyzcorp.com ... telopt nop if fail stop 1 Connection lost SET TCP ADDRESS [ ] Specifies the IP address of the computer that C-Kermit is running on. Normally this is not necessary. The exception would be if your machine has multiple network adapters (physical or virtual) with a different address for each adapter AND you want C-Kermit to use a specific address when making outgoing connections or accepting incoming connections. SET TCP DNS-SERVICE-RECORDS {ON, OFF} Tells C-Kermit whether to try to use DNS SRV records to determine the host and port number upon which to find an advertised service. For example, if a host wants regular Telnet connections redirected to some port other than 23, this feature allows C-Kermit to ask the host which port it should use. Since not all domain servers are set up to answer such requests, this feature is OFF by default. SET TCP REVERSE-DNS-LOOKUP { ON, OFF, AUTO } Tells Kermit whether to perform a reverse DNS lookup on TCP/IP connections. This allows Kermit to determine the actual hostname of the host it is connected to, which is useful for connections to host pools, and is required for Kerberos connections to host pools and for incoming connections. If the other host does not have a DNS entry, the reverse lookup could take a long time (minutes) to fail, but the connection will still be made. Turn this option OFF for speedier connections if you do not need to know exactly which host you are connected to and you are not using Kerberos. AUTO, the default, means the lookup is done on hostnames, but not on numeric IP addresses. SET TELNET WAIT-FOR-NEGOTIATIONS { ON, OFF } Each Telnet option must be fully negotiated either On or Off before the session can continue. This is especially true with options that require sub-negotiations such as Authentication, Encryption, and Kermit; for proper support of these options Kermit must wait for the negotiations to complete. Of course, Kermit has no way of knowing whether a reply is delayed or not coming at all, and so will wait a minute or more for required replies before continuing the session. If you know that Kermit's Telnet partner will not be sending the required replies, you can set this option of OFF to avoid the long timeouts. Or you can instruct Kermit to REFUSE specific options with the SET TELOPT command. SET TELOPT [ { /CLIENT, /SERVER } ]