, 2nd Edition| [ Home ] [ Kermit 95 ] [ C-kermit ] [ Scripts ] [ Current ] [ New ] [ FAQ ] [ Support ] |
, 2nd Edition
As of C-Kermit version: 7.0.196
This file created: 8 February 2000
This file last updated:
Thu Jul 3 15:23:27 2008
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/
For the full text of the third-party copyright notices, see Appendix V.
For further information, also see the CKCBWR.TXT ("C-Kermit beware") file for hints, tips, tricks, restrictions, frequently asked questions, etc, plus the system-specific "beware file", e.g. CKUBWR.TXT for UNIX, CKVBWR.TXT for VMS, etc, and also any system-specific update files such as KERMIT95.HTM for Kermit 95 (in the DOCS\MANUAL\ subdirectory of your K95 directory).
This Web-based copy of the C-Kermit 7.0 update notes supersedes the plain-text CKERMIT2.TXT file. All changes after 19 January 2000 appear only here in the Web version. If you need an up-to-date plain-text copy, use your Web browser to save this page as plain text.
Several other files accompany this new Kermit release:
Like the book Using C-Kermit, this file concentrates on the aspects of C-Kermit that are common to all versions: UNIX, VMS, Windows, OS/2, 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.19.
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 (1) 5A(189) September 1993 Control-char unprefixing 5A(190) October 1994 Recovery 5A(191) April 1995 OS/2 only 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
(*) Never formally released (4.0 was a total rewrite)
(1) Using C-Kermit, 1st Edition
(2) Using C-Kermit, 2nd Edition
I. C-KERMIT DOCUMENTATION
II. NEW FEATURES
(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. Minor 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 File 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
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.
CLICK HERE for reviews.
The present document is a supplement to Using C-Kermit 2nd Ed, not a replacement for it.
US single-copy price: $52.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) 662-6442
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 - Einführung 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.
Specific changes and additions are grouped together by major topic, roughly corresponding to the chapters of Using C-Kermit.
cd \v(dir)data.tmp
to work across platforms that might have different directory notation, such as UNIX, Windows, and VMS.
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.
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:
echo foo\-
This prints "foo-". The command is not continued.
echo foo - ; this is a comment
interactively and they are properly treated as continued commands. Previously this worked only in command files.
Related variables: \v(editor), \v(editopts), \v(editfile).
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:
The Web browser interface is covered in the following subsections.
Related variables: \v(browser), \v(browsopts), \v(browsurl).
Also see Section 2.15: Contacting Web Servers with the HTTP Command.
The method for doing this depends, of course, on your browser. Here are some examples:
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.
#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
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.
As of version 7.0, C-Kermit's command parser supports a new type of field, called a "switch". This is an optional command modifier.
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.
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.
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.
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
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.
send /after:{8-Feb-2000 10:28:01}
Various date-time formats are acceptable. The rules for the date are:
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:
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
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.
set alarm \fntime(48:00:00) ; set alarm 48 hours from now.
\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).
\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(2000185) = 20000704 \fdoy2(2000185 3pm) = 20000704 15:00:00
\fmjd(4 Jul 2000) = 50998 \fmjd(17 Nov 1858) = 0 \fmjd(16 Nov 1858) = -1
\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).
C-Kermit> send /n<Tab>
which matches /NOT-BEFORE and /NOT-AFTER, now completes up to the dash:
C-Kermit> send /n<Tab>ot-<Beep>
Partial completion works for filenames too (as it has for some years).
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).
{ 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 $
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:
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 if interruption is to be re-enabled.
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).
Thus there can be conflicts. To illustrate, the standard UNIX shell uses dollar sign ($) to introduce variables. So the shell command:
echo $TERM
displays the value of the TERM variable, e.g. vt320. But suppose you want to display a real dollar sign:
echo The price is $10.20
This causes the shell to evaluate the variable "$1", which might or might not exist, and substitute its value, e.g.:
The price is 0.20
(in this case the $1 variable had no value.) This is probably not what you wanted. To force the dollar sign to be taken literally, you must apply a "quoting rule", such as "precede a character by backslash (\) to force the shell to take the character literally":
echo The price is \$10.20 The price is $10.20
But now suppose you want the backslash AND the dollar sign to be taken literally:
echo The price is \\$10.20
This doesn't work, since the first backslash quotes the second one, thereby leaving the dollar sign unquoted again:
The price is \0.20
Quoting the dollar sign requires addition of a third backslash:
echo The price is \\\$10.20 The price is \$10.20
The first backslash quotes the second one, and the third backslash quotes the dollar sign.
Every command language -- all UNIX shells, VMS DCL, DOS Batch, AOS/VS CLI, etc etc -- has similar rules. UNIX shell rules are probably the most complicated, since many printable characters -- not just one -- are special there: dollar sign, single quote, double quote, backslash, asterisk, accent grave, number sign, ampersand, question mark, parentheses, brackets, braces, etc -- practically every non-alphanumeric character needs some form of quoting if it is to be taken literally. And to add to the confusion, the UNIX shell offers many forms of quoting, and many alternative UNIX shells are available, each using slightly different syntax.
The following characters are special in Kermit commands:
x, o, d, m, s, 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).
To force Kermit to take any of these characters literally, simply precede it by a backslash (\).
Sounds easy! And it is, except when backslash also has a special meaning to the underlying operating system, as it does in DOS, Windows, and OS/2, where it serves as the directory separator in filenames such as:
D:\K95\KEYMAPS\READ.ME
Using our rule, we would need to refer to this file in Kermit commands as follows:
D:\\K95\\KEYMAPS\\READ.ME
But this would not be obvious to new users of Kermit software on DOS, Windows, or OS/2, and it would be annoying to seasoned ones. Thus MS-DOS Kermit and Kermit 95 go to rather extreme lengths to allow the more natural notation, as in:
send d:\k95\keymaps\read.me
The reason this is tricky is that we also need to allow for variables and other expressions introduced by backslash in the same command. For example, suppose \%a is a variable whose value is "oofa" (without the quotes). What does the following command do?
send d:\%a
Does it send the file named "oofa" in the current directory of the D: disk, or does it send a file named "%a" in the root directory of the D: disk? This is the kind of trouble we get into when we attempt to bend the rules in the interest of user friendliness. (The answer is: if the variable \%a has definition that is the name of an existing file, that file is sent; if a file d:\%a exists, it is sent; otherwise if both conditions are true, the variable takes precedence, and the literal filename can be forced by quoting: \\%a.)
In Kermit 95 (but not MS-DOS Kermit), we also bend the rules another way by allowing you to use forward slash (/) rather than backslash (\) as the directory separator:
send d:/k95/keymaps/read.me
This looks more natural to UNIX users, and in fact is perfectly acceptable to the Windows 95/98/NT and OS/2 operating systems on the API level. BUT (there is always a "but") the Microsoft shell, COMMAND.COM, for Windows 95/98 and NT does not allow this notation, and therefore it can not be used in any Kermit command -- such as RUN -- that invokes the Windows command shell AND your command shell is COMMAND.COM or any other shell that does not allow forward slash as directory separator (some alternative shells do allow this).
NOTE: There exists a wide variety of alternative shells from third parties that do not have this restriction. If you are using a shell that accepts forward slash as a directory separator, you can stop reading right now -- UNLESS (there is always an "unless") you want your scripts to be portable to systems that have other shells. Also note that some Windows shells might actually REQUIRE forward slashes (instead of backslashes) as directory separators; we do not treat this situation below, but the treatment is obvious -- use slash rather backslash as the directory separator.
RUN (and its synonyms ! and @) REDIRECT PIPE
Each of these commands takes a shell command as an operand. These shell commands are not, and can not be, parsed by Kermit since Kermit does not know the syntax of shell commands, and so can't tell the difference between a keyword, a filename, a variable, a switch, or other item. Therefore the rules can not be bent since Kermit doesn't know where or how to bend them. To illustrate (using the regular Windows shell):
run c:\\windows\\command\\chkdsk.exe
works OK, but:
run c:/windows/command/chkdsk.exe
is not accepted by COMMAND.COM. But:
run c:\windows\command\chkdsk.exe
results in Kermit applying its quoting rules before sending the text to the shell. Since "w" and "c" are not in the list of backslash-item codes, the backslash means "take the following character literally". Thus, by the time this filename gets to the Windows shell, it has become:
c:windowscommandchkdsk.exe
which is probably not what you wanted. (If "w" and "c" were in the list, the results could be even stranger.) Even more confusing is the case where a directory or filename starts with one or more digits:
run c:\123\lotus.exe
in which "\123" is the Kermit notation for ASCII character 123, which happens to be left brace ({), resulting in "c:{lotus.exe".
So when passing filenames to a Windows shell, always use double backslashes as directory separators, to ensure that the shell gets single backslashes:
run c:\\windows\\command\\chkdsk.exe run c:\\123\\lotus.exe
Similar problems might occur with the built-in EDIT, BROWSE, and FTP commands. These commands result in Kermit building a shell command internally to invoke the associated helper program; the form of this command might conflict with the form demanded by certain alternative shells.
define \%f c:\windows\command\chkdsk.exe ... run \%f
Obviously this won't work for the reasons just noted; the RUN command requires directory separators be coded as double backslashes:
define \%f c:\\windows\\command\\chkdsk.exe ... run \%f
This will work; no surprises here. However, if you had used ASSIGN rather than DEFINE, you might have been surprised after all; review pages 348-349 of Using C-Kermit (2nd Ed) for the difference between DEFINE and ASSIGN.
We have said that any Kermit 95 or MS-DOS Kermit command that parses filenames itself -- SEND, for example -- does not require double backslashes since it knows it is parsing a filename. So since the following works:
send c:\windows\command\chkdsk.exe
Should the following also work?
define \%f c:\windows\command\chkdsk.exe ... send \%f
Answer: No. Why? Because \%f is evaluated "recursively", to allow for the possibility that its definition contains further variable references. This is true of all "backslash-percent-letter" (or -digit) variables, and also for array references. So \%f becomes c:\windows\command\chkdsk.exe, which becomes c:windowscommandchkdsk.exe.
The trick here is to use the "other" kind of variable, that is evaluated only "one level deep" rather than recursively:
define filename c:\windows\command\chkdsk.exe ... send \m(filename)
Similarly if you want to prompt the user for a filename:
ask filename { Please type a filename: }
Please type a filename: c:\windows\command\chkdsk.exe
send \m(filename)
Thus a DOS filename is ruined once in the act of parsing the macro invocation, and again when referring to it from within the macro. To illustrate, suppose "test" is a macro. Then in the invocation:
test c:\mydir\blah.txt
"c:mydirblah.txt" is assigned to \%1. However, if we double the backslashes:
test c:\\mydir\\blah.txt
"c:\mydir\blah.txt" is assigned to \%1. But then when you refer to \%1 in the macro, it is evaluated recursively, resulting in "c:mydirblah.txt". To illustrate:
define test echo \%1 test c:\mydir\blah.txt c:mydirblah.txt test c:\\mydir\\blah.txt c:mydirblah.txt test c:\\\\mydir\\\\blah.txt c:\mydir\blah.txt
Let's address each part of the problem separately. First, inside the macro. You can use the \fcontents() function to force a backslash-percent variable (such as a macro argument) to be evaluated one level deep instead of recursively, for example:
define test echo { The filename is "\fcontents(\%1)"}
test c:\mydir\blah.txt ; We don't expect this to work
The filename is "c:mydirblah.txt" ; and it doesn't.
test c:\\mydir\\blah.txt ; But this does...
The filename is "c:\mydir\blah.txt"
Thus if the filename arrives inside the macro with single backslashes, the backslashes are preserved if you always refer to the parameter through the \fcontents() function.
Now how to ensure that backslashes are not stripped or misinterpreted when passing a filename to a macro? This brings us back to what we learned in earlier sections:
Examples:
define test echo \fcontents(\%1) define filename c:\mydir\blah.txt test c:\\mydir\\blah.txt ; Literal filename with double backslashes c:\mydir\blah.txt test c:/mydir/blah.txt ; Literal filename with forward slashes c:/mydir/blah.txt test \m(filename) ; Variable c:\mydir\blah.txt
But what if you don't like these rules and you still want to pass a literal filename containing single backslashes to a macro? This is possible too, but a bit tricky: turn command quoting off before invoking the macro, and then turn it back on inside the macro. Example:
define test set command quoting on, echo \fcontents(\%1) set command quoting off test c:\mydir\blah.txt c:\mydir\blah.txt
Upon return from the macro, command quoting is back on (since the macro turned it on).
Obviously this trick can not be used if the filename is stored in a variable, since it prevents the variable from being evaluated.
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.
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])
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).
Here are some examples for UNIX (always remember the importance of getting the UNIX shell quoting rules right):
See Section 2.12 for information about the new connection log.
COMMAND AUTODOWNLOAD is the command-mode equivalent of TERMINAL AUTODOWNLOAD, which is effective during CONNECT mode.
Syntax: TYPE [ switches... ] filename
Variables:
Switches:
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".
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).
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.
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.
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.
C-Kermit> { echo One, echo Two, echo Three }
C-Kermit> 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).
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:
See the ckccfg.txt file for details.
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:
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:
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:
The FILE OPEN switches are:
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 Kermit exits, or you close it explicitly. The command to close a file is:
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:
Next come the commands for reading and writing files:
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: