通讯/手机编程

开发平台：

Windows_Unix

ckermit2.txt：源码内容

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:
Kermit 95:
C-Kermit:
Trustees of Columbia University in the City of New York.
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:
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 DOCSMANUAL 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 <LF>~ 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 <sys/clock.h>
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 <name> [ <options> ]
Lets you specify a text-editing program. The <name> 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 [ <filename> ]
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 [ <name> [ <options ] ]
The name is the name of the FTP executable. In UNIX, Windows, or OS/2, it
can be the filename of any executable program in your PATH (e.g. "ftp.exe" in
Windows, "ftp" in UNIX); elsewhere (or if you do not have a PATH definition),
it must be the fully specified pathname of the FTP program. If the name
contains any spaces, enclose it braces. Include any options after the
filename; these depend the particular ftp client.
The Web browser interface is covered in the following subsections.
1.3.1. Invoking your Browser from C-Kermit
BROWSE [ <url> ]
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 [ <name> [ <options> ] ]
Use this command to specify the name of your Web browser program, for
example: "set browser lynx". The <name> 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 /pro<ESC>tocol:? File-transfer protocol,
one of the following:
kermit xmodem ymodem ymodem-g zmodem
C-Kermit> send /protocol:k<TAB>ermit
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:<date-time>
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:<date-time>
Select only those files having a date-time not later than (i.e. earlier or
equal to) the one given. Synonym: /NOT-SINCE.
/BEFORE:<date-time>
Select only those files having a date-time earlier than the one given.
/NOT-BEFORE:<date-time>
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:<number>
Only select files larger than the given number of bytes.
/SMALLER-THAN:<number>
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 <string> <pattern>
(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 <command> [ 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.
+ <number> { 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.
- <number> { 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<Tab>
which matches /NOT-BEFORE and /NOT-AFTER, now completes up to the dash:
send /n<Tab>ot-<Beep>
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, ^ } [ <pattern> ]
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><Ctrl-P> ; 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 } [ <status-code> [ <message> ] ]
where <status-code> 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) <command>
The <command> 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 .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:K95KEYMAPSREAD.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:k95keymapsread.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:windowscommandchkdsk.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:123lotus.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:windowscommandchkdsk.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:windowscommandchkdsk.exe
Should the following also work?
define %f c:windowscommandchkdsk.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:windowscommandchkdsk.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:windowscommandchkdsk.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:windowscommandchkdsk.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:mydirblah.txt
"c:mydirblah.txt" is assigned to %1. However, if we double the backslashes:
test c:\mydir\blah.txt
"c:mydirblah.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:mydirblah.txt
c:mydirblah.txt
test c:\mydir\blah.txt
c:mydirblah.txt
test c:\\mydir\\blah.txt
c:mydirblah.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:mydirblah.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:mydirblah.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:mydirblah.txt
test c:\mydir\blah.txt ; Literal filename with double backslashes
c:mydirblah.txt
test c:/mydir/blah.txt ; Literal filename with forward slashes
c:/mydir/blah.txt
test m(filename) ; Variable
c:mydirblah.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:mydirblah.txt
c:mydirblah.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:FOOBARBAZOOFA.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 <keyword> [ <switches> ] <channel> [ <data> ]
The <keyword> 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 ] <variable> <filename>
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, <channel> }
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 <channel>
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 <channel> 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 ] <channel> [ <variable> ]
Reads data from the file on the given channel number into the <variable>,
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 ] <channel> <text>
Writes the given text to the file on the given channel number. The <text>,
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 <variable> 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 <text>. 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 <text> 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 <text> 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