Google Git
Sign in
nest-open-source / nest-learning-thermostat / 5.0 / ckermit / f19e988f07610984dc8f3f64322601b3f072668e / . / ckermit-8.0.211 / ckermit70.txt
blob: 8aca397375de975899a38091da5d0639a0fafae2 [file] [log] [blame]
[ [1]Contents ] [ [2]C-Kermit ] [ [3]Kermit Home ]
Supplement to Using C-Kermit, Second Edition
For C-Kermit 7.0
As of C-Kermit version: 7.0.196
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: [4]kermit-support@columbia.edu
Web: [5]http://www.columbia.edu/kermit/
Or: [6]http://www.kermit-project.org/
Or: [7]http://www.columbia.nyc.ny.us/kermit/
_________________________________________________________________
NOTICES
This document:
Copyright © 1997, 2000, Frank da Cruz and Christine M. Gianone.
All rights reserved.
Kermit 95:
Copyright © 1995, 2000, Trustees of Columbia University in the
City of New York. All rights reserved.
C-Kermit:
Copyright © 1985, 2000,
Trustees of Columbia University in the City of New York. All
rights reserved. See the C-Kermit [8]COPYING.TXT file or the
copyright text in the [9]ckcmai.c module for disclaimer and
permissions.
When Kerberos(TM) and/or SRP(TM) (Secure Remote Password) and/or SSL
protocol are included:
Portions Copyright © 1990, Massachusetts Institute of
Technology.
Portions Copyright © 1991, 1993 Regents of the University of
California.
Portions Copyright © 1991, 1992, 1993, 1994, 1995 by AT&T.
Portions Copyright © 1997, Stanford University.
Portions Copyright © 1995-1997, Eric Young
<eay@cryptosoft.com>.
For the full text of the third-party copyright notices, see
[10]Appendix V.
_________________________________________________________________
WHAT IS IN THIS FILE
This file lists changes made to C-Kermit since the second edition of
the book [11]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 [12]CKCBWR.TXT ("C-Kermit
beware") file for hints, tips, tricks, restrictions, frequently asked
questions, etc, plus the system-specific "beware file", e.g.
[13]CKUBWR.TXT for UNIX, [14]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.
_________________________________________________________________
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: [15]ckubwr.txt, [16]ckermit70.txt, etc.
_________________________________________________________________
ADDITIONAL FILES
Several other files accompany this new Kermit release:
SECURITY.TXT
Discussion of Kermit's new authentication and encryption
features:
+ [17]Plain-text version
+ [18]HTML (hypertext) version
IKSD.TXT
How to install and manage an Internet Kermit Service Daemon.
+ [19]Plain-text version
+ [20]HTML (hypertext) version
Also see [21]cuiksd.htm for instructions for use.
TELNET.TXT
A thorough presentation of Kermit's new advanced Telnet
features and controls.
+ [22]Plain-text version
+ [23]HTML (hypertext) version
_________________________________________________________________
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 [24]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
[25]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 Holström, 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, 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
Vorländer, 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 ([26]http://www.opensource.org) 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
Jörg Wunsch.
_________________________________________________________________
NOTE TO KERMIT 95 USERS
Kermit 95 and C-Kermit share the same command and scripting language,
the same Kermit file-transfer protocol implementation, and much else
besides.
Like the book [27]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.
_________________________________________________________________
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 (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
_________________________________________________________________
CONTENTS
I. [28]C-KERMIT DOCUMENTATION
II. [29]NEW FEATURES
(0) [30]INCOMPATIBILITIES WITH PREVIOUS RELEASES
(1) [31]PROGRAM AND FILE MANAGEMENT AND COMMANDS
1.0. [32]Bug fixes
1.1. [33]Command Continuation
1.2. [34]Editor Interface
1.3. [35]Web Browser and FTP Interface
1.4. [36]Command Editing
1.5. [37]Command Switches
1.5.1. [38]General Switch Syntax
1.5.2. [39]Order and Effect of Switches
1.5.3. [40]Distinguishing Switches from Other Fields
1.5.4. [41]Standard File Selection Switches
1.5.5. [42]Setting Preferences for Different Commands
1.6. [43]Dates and Times
1.7. [44]Partial Completion of Keywords
1.8. [45]Command Recall
1.9. [46]EXIT Messages
1.10. [47]Managing Keyboard Interruptions
1.11. [48]Taming the Wild Backslash -- Part Deux
1.11.1. [49]Background
1.11.2. [50]Kermit's Quoting Rules
1.11.3. [51]Passing DOS Filenames from Kermit to Shell Commands
1.11.4. [52]Using Variables to Hold DOS Filenames
1.11.5. [53]Passing DOS Filenames as Parameters to Macros
1.11.6. [54]Passing DOS File Names from Macro Parameters to the
DOS Shell
1.11.7. [55]Passing DOS Filenames to Kermit from the Shell
1.12. [56]Debugging
1.13. [57]Logs
1.14. [58]Automatic File-Transfer Packet Recognition at the Command Pr
ompt
1.15. [59]The TYPE Command
1.16. [60]The RESET Command
1.17. [61]The COPY and RENAME Commands
1.18. [62]The MANUAL Command
1.19. [63]String and Filename Matching Patterns
1.20. [64]Multiple Commands on One Line
1.21. [65]What Do I Have?
1.22. [66]Generalized File Input and Output
1.22.1. [67]Why Another I/O System?
1.22.2. [68]The FILE Command
1.22.3. [69]FILE Command Examples
1.22.4. [70]Channel Numbers
1.22.5. [71]FILE Command Error Codes
1.22.6. [72]File I/O Variables
1.22.7. [73]File I/O Functions
1.22.8. [74]File I/O Function Examples
1.23. [75]The EXEC Command
1.24. [76]Getting Keyword Lists with '?'
(2) [77]MAKING AND USING CONNECTIONS
2.0. [78]SET LINE and SET HOST Command Switches
2.1. [79]Dialing
2.1.1. [80]The Dial Result Message
2.1.2. [81]Long-Distance Dialing Changes
2.1.3. [82]Forcing Long-Distance Dialing
2.1.4. [83]Exchange-Specific Dialing Decisions
2.1.5. [84]Cautions about Cheapest-First Dialing
2.1.6. [85]Blind Dialing (Dialing with No Dialtone)
2.1.7. [86]Trimming the Dialing Dialog
2.1.8. [87]Controlling the Dialing Speed
2.1.9. [88]Pretesting Phone Number Conversions
2.1.10. [89]Greater Control over Partial Dialing
2.1.11. [90]New DIAL-related Variables and Functions
2.1.12. [91]Increased Flexibility of PBX Dialing
2.1.13. [92]The DIAL macro - Last-Minute Phone Number Conversions
2.1.14. [93]Automatic Tone/Pulse Dialing Selection
2.1.15. [94]Dial-Modifier Variables
2.1.16. [95]Giving Multiple Numbers to the DIAL Command
2.2. [96]Modems
2.2.1. [97]New Modem Types
2.2.2. [98]New Modem Controls
2.3. [99]TELNET and RLOGIN
2.3.0. [100]Bug Fixes
2.3.1. [101]Telnet Binary Mode Bug Adjustments
2.3.2. [102]VMS UCX Telnet Port Bug Adjustment
2.3.3. [103]Telnet New Environment Option
2.3.4. [104]Telnet Location Option
2.3.5. [105]Connecting to Raw TCP Sockets
2.3.6. [106]Incoming TCP Connections
2.4. [107]The EIGHTBIT Command
2.5. [108]The Services Directory
2.6. [109]Closing Connections
2.7. [110]Using C-Kermit with External Communication Programs
2.7.0. [111]C-Kermit over tn3270 and tn5250
2.7.1. [112]C-Kermit over Telnet
2.7.2. [113]C-Kermit over Rlogin
2.7.3. [114]C-Kermit over Serial Communication Programs
2.7.4. [115]C-Kermit over Secure Network Clients
2.7.4.1. [116]SSH
2.7.4.2. [117]SSL
2.7.4.3. [118]SRP
2.7.4.4. [119]SOCKS
2.7.4.5. [120]Kerberos and SRP
2.8. [121]Scripting Local Programs
2.9. [122]X.25 Networking
2.9.1. [123]IBM AIXLink/X.25 Network Provider Interface for AIX
2.9.2. [124]HP-UX X.25
2.10. [125]Additional Serial Port Controls
2.11. [126]Getting Access to the Dialout Device
2.12. [127]The Connection Log
2.13. [128]Automatic Connection-Specific Flow Control Selection
2.14. [129]Trapping Connection Establishment and Loss
2.15. [130]Contacting Web Servers with the HTTP Command
(3) [131]TERMINAL CONNECTION
3.1. [132]CONNECT Command Switches
3.2. [133]Triggers
3.3. [134]Transparent Printing
3.4. [135]Binary and Text Session Logs
(4) [136]FILE TRANSFER AND MANAGEMENT
4.0. [137]Bug Fixes, Minor Changes, and Clarifications
4.1. [138]File-Transfer Filename Templates
4.1.1. [139]Templates in the As-Name
4.1.2. [140]Templates on the Command Line
4.1.3. [141]Post-Transfer Renaming
4.2. [142]File-Transfer Pipes and Filters
4.2.1. [143]Introduction
4.2.1.1. [144]Terminology
4.2.1.2. [145]Notation
4.2.1.3. [146]Security
4.2.2. [147]Commands for Transferring from and to Pipes
4.2.2.1. [148]Sending from a Command
4.2.2.2. [149]Receiving to a Command
4.2.3. [150]Using File-Transfer Filters
4.2.3.1. [151]The SEND Filter
4.2.3.2. [152]The RECEIVE Filter
4.2.4. [153]Implicit Use of Pipes
4.2.5. [154]Success and Failure of Piped Commands
4.2.6. [155]Cautions about Using Pipes to Transfer Directory Trees
4.2.7. [156]Pipes and Encryption
4.2.8. [157]Commands and Functions Related to Pipes
4.2.8.1. [158]The OPEN !READ and OPEN !WRITE Commands
4.2.8.2. [159]The REDIRECT Command
4.2.8.3. [160]Receiving Mail and Print Jobs
4.2.8.4. [161]Pipe-Related Functions
4.3. [162]Automatic Per-File Text/Binary Mode Switching
4.3.1. [163]Exceptions
4.3.2. [164]Overview
4.3.3. [165]Commands
4.3.4. [166]Examples
4.4. [167]File Permissions
4.4.1. [168]When ATTRIBUTES PROTECTION is OFF
4.4.1.1. [169]Unix
4.4.1.2. [170]VMS
4.4.2. [171]When ATTRIBUTES PROTECTION is ON
4.4.2.1. [172]System-Specific Permissions
4.4.2.1.1. [173]UNIX
4.4.2.1.2. [174]VMS
4.4.2.2. [175]System-Independent Permissions
4.5. [176]File Management Commands
4.5.1. [177]The DIRECTORY Command
4.5.2. [178]The CD and BACK Commands
4.5.2.1. [179]Parsing Improvements
4.5.2.2. [180]The CDPATH
4.5.3. [181]Creating and Removing Directories
4.5.4. [182]The DELETE and PURGE Commands
4.6. [183]Starting the Remote Kermit Server Automatically
4.7. [184]File-Transfer Command Switches
4.7.1. [185]SEND Command Switches
4.7.2. [186]GET Command Switches
4.7.3. [187]RECEIVE Command Switches
4.8. [188]Minor Kermit Protocol Improvements
4.8.1. [189]Multiple Attribute Packets
4.8.2. [190]Very Short Packets
4.9. [191]Wildcard / File Group Expansion
4.9.1. [192]In UNIX C-Kermit
4.9.2. [193]In Kermit 95
4.9.3. [194]In VMS, AOS/VS, OS-9, VOS, etc.
4.10. [195]Additional Pathname Controls
4.11. [196]Recursive SEND and GET: Transferring Directory Trees
4.11.1. [197]Command-Line Options
4.11.2. [198]The SEND /RECURSIVE Command
4.11.3. [199]The GET /RECURSIVE Command
4.11.4. [200]New and Changed File Functions
4.11.5. [201]Moving Directory Trees Between Like Systems
4.11.6. [202]Moving Directory Trees Between Unlike Systems
4.12. [203]Where Did My File Go?
4.13. [204]File Output Buffer Control
4.14. [205]Improved Responsiveness
4.15. [206]Doubling and Ignoring Characters for Transparency
4.16. [207]New File-Transfer Display Formats
4.17. [208]New Transaction Log Formats
4.17.1. [209]The BRIEF Format
4.17.2. [210]The FTP Format
4.18. [211]Unprefixing NUL
4.19. [212]Clear-Channel Protocol
4.20. [213]Streaming Protocol
4.20.1. [214]Commands for Streaming
4.20.2. [215]Examples of Streaming
4.20.2.1. [216]Streaming on Socket-to-Socket Connections
4.20.2.2. [217]Streaming on Telnet Connections
4.20.2.3. [218]Streaming with Limited Packet Length
4.20.2.4. [219]Streaming on Dialup Connections
4.20.2.5. [220]Streaming on X.25 Connections
4.20.3. [221]Streaming - Preliminary Conclusions
4.21. [222]The TRANSMIT Command
4.22. [223]Coping with Faulty Kermit Implementations
4.22.1. [224]Failure to Accept Modern Negotiation Strings
4.22.2. [225]Failure to Negotiate 8th-bit Prefixing
4.22.3. [226]Corrupt Files
4.22.4. [227]Spurious Cancellations
4.22.5. [228]Spurious Refusals
4.22.6. [229]Failures during the Data Transfer Phase
4.22.7. [230]Fractured Filenames
4.22.8. [231]Bad File Dates
4.23. [232]File Transfer Recovery
4.24. [233]FILE COLLISION UPDATE Clarification
4.25. [234]Autodownload Improvements
(5) [235]CLIENT/SERVER
5.0. [236]Hints
5.1. [237]New Command-Line Options
5.2. [238]New Client Commands
5.3. [239]New Server Capabilities
5.3.1. [240]Creating and Removing Directories
5.3.2. [241]Directory Listings
5.4. [242]Syntax for Remote Filenames with Embedded Spaces
5.5. [243]Automatic Orientation Messages upon Directory Change
5.6. [244]New Server Controls
5.7. [245]Timeouts during REMOTE HOST Command Execution
(6) [246]INTERNATIONAL CHARACTER SETS
6.0. [247]ISO 8859-15 Latin Alphabet 9
6.1. [248]The HP-Roman8 Character Set
6.2. [249]Greek Character Sets
6.3. [250]Additional Latin-2 Character Sets
6.4. [251]Additional Cyrillic Character Sets
6.5. [252]Automatic Character-Set Switching
6.6. [253]Unicode
6.6.1. [254]Overview of Unicode
6.6.2. [255]UCS Byte Order
6.6.2. [256]UCS Transformation Formats
6.6.3. [257]Conformance Levels
6.6.4. [258]Relationship of Unicode with Kermit's Other Character Sets
6.6.5. [259]Kermit's Unicode Features
6.6.5.1. [260]File Transfer
6.6.5.2. [261]The TRANSLATE Command
6.6.5.3. [262]Terminal Connection
6.6.5.4. [263]The TRANSMIT Command
6.6.5.5. [264]Summary of Kermit Unicode Commands
6.7. [265]Client/Server Character-Set Switching
(7) [266]SCRIPT PROGRAMMING
7.0. [267]Bug Fixes
7.1. [268]The INPUT Command
7.1.1. [269]INPUT Timeouts
7.1.2. [270]New INPUT Controls
7.1.3. [271]INPUT with Pattern Matching
7.1.4. [272]The INPUT Match Result
7.2. [273]New or Improved Built-In Variables
7.3. [274]New or Improved Built-In Functions
7.4. [275]New IF Conditions
7.5. [276]Using More than Ten Macro Arguments
7.6. [277]Clarification of Function Call Syntax
7.7. [278]Autodownload during INPUT Command Execution
7.8. [279]Built-in Help for Functions.
7.9. [280]Variable Assignments
7.9.1. [281]Assignment Operators
7.9.2. [282]New Assignment Commands
7.10. [283]Arrays
7.10.1. [284]Array Initializers
7.10.2. [285]Turning a String into an Array of Words
7.10.3. [286]Arrays of Filenames
7.10.4. [287]Automatic Arrays
7.10.5. [288]Sorting Arrays
7.10.6. [289]Displaying Arrays
7.10.7. [290]Other Array Operations
7.10.8. [291]Hints for Using Arrays
7.10.9. [292]Do-It-Yourself Arrays
7.10.10. [293]Associative Arrays
7.11. [294]OUTPUT Command Improvements
7.12. [295]Function and Variable Diagnostics
7.13. [296]Return Value of Macros
7.14. [297]The ASSERT, FAIL, and SUCCEED Commands.
7.15. [298]Using Alarms
7.16. [299]Passing Arguments to Command Files
7.17. [300]Dialogs with Timed Responses
7.18. [301]Increased Flexibility of SWITCH Case Labels
7.19. "[302]Kerbang" Scripts
7.20. [303]IF and XIF Statement Syntax
7.20.1. [304]The IF/XIF Distinction
7.20.2. [305]Boolean Expressions (The IF/WHILE Condition)
7.21. [306]Screen Formatting and Cursor Control
7.22. [307]Evaluating Arithmetic Expressions
7.23. [308]Floating-Point Arithmetic
7.24. [309]Tracing Script Execution
7.25. [310]Compact Substring Notation
7.26. [311]New WAIT Command Options
7.26.1. [312]Waiting for Modem Signals
7.26.2. [313]Waiting for File Events
7.27. [314]Relaxed FOR and SWITCH Syntax
(8) [315]USING OTHER FILE TRANSFER PROTOCOLS
(9) [316]COMMAND-LINE OPTIONS
9.0. [317]Extended-Format Command-Line Options
9.1. [318]Command Line Personalities
9.2. [319]Built-in Help for Command Line Options
9.3. [320]New Command-Line Options
(10) [321]C-KERMIT AND G-KERMIT
III. [322]APPENDICES
III.1. [323]Character Set Tables
III.1.1. [324]The Hewlett Packard Roman8 Character Set
III.1.2. [325]Greek Character Sets
III.1.2.1. [326]The ISO 8859-7 Latin / Greek Alphabet
III.1.2.2. [327]The ELOT 927 Character Set
III.1.2.3. [328]PC Code Page 869
III.2. [329]Updated Country Codes
IV. [330]ERRATA & CORRIGENDA: Corrections to "Using C-Kermit" 2nd Edition.
V. [331]ADDITIONAL COPYRIGHT NOTICES
_________________________________________________________________
I. C-KERMIT DOCUMENTATION
The user manual for C-Kermit is:
Frank da Cruz and Christine M. Gianone, [332]Using C-Kermit, Second
Edition, Digital Press / Butterworth-Heinemann, Woburn, MA, 1997,
622 pages, ISBN 1-55558-164-1.
[333]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 /
[334]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 [335]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 [336]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, [337]Kermit News. Subscriptions are free;
contact Columbia University at the address above.
Online news about Kermit is published in the
[338]comp.protocols.kermit.announce and
[339]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 [340]Using C-Kermit.
_________________________________________________________________
0. INCOMPATIBILITIES WITH PREVIOUS RELEASES
1. 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.
Usually SET PREFIXING ALL does the trick.
2. 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.
3. 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 [341]Section 4, especially [342]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.
4. 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 [343]Section 4.23 for additional
(important) information.
5. SET PREFIXING CAUTIOUS and MINIMAL now both prefix linefeed (10
and 138) in case rlogin, ssh, or cu are "in the middle", since
otherwise <LF>~ might appear in Kermit packets, and this would
cause rlogin, ssh, 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.
6. 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
[344]Section 4.5.1 for details.
7. 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 [345]Sections 1.5 and [346]4.7.1.
8. 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 [347]Section 4.9.
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 [348]Using C-Kermit, 2nd Edition. This allows any macro or
command file to SET QUIET ON or OFF without worrying about saving
and 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.
10. 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.
11. The syntax of the EVALUATE command has changed. See [349]Section
7.9.2. To restore the previous syntax, use SET EVALUATE OLD.
12. 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)data.tmp
to work across platforms that might have different directory
notation, such as UNIX, Windows, and VMS.
13. 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.
14. 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 are 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 [350]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 on UNIX
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
But none of the above is necessary if you make C-Kermit your default
Telnet client, which you can do by making a symlink called 'telnet' to
the C-Kermit 7.0 binary. See [351]Section 9.1 for details.
_________________________________________________________________
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 version 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 [352]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 equal to) 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 ([353]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 [354]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
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 [355]\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, and 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.
[356]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:
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).
_________________________________________________________________
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
[357]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 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).
_________________________________________________________________
1.11. Taming The Wild Backslash -- Part Deux
[358]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:
1. One or more characters must be set aside to denote replacement,
rather than acting as literal text.
2. We have only 96 printable characters to work with in ASCII, which
is still the only universally portable character set.
3. There is no single printable character that is unused everywhere.
4. Variables are not restricted to certain contexts, as they are in
formal programming languages like C and Fortran, but can appear
anywhere at all within a command, and therefore require special
syntax.
Thus there can be conflicts. To illustrate, the standard UNIX shell
uses dollar sign ($) to introduce variables. So the shell command:
echo $TERM
displays the value of the TERM variable, e.g. vt320. But suppose you
want to display a real dollar sign:
echo The price is $10.20
This causes the shell to evaluate the variable "$1", which might or
might not exist, and substitute its value, e.g.:
The price is 0.20
(in this case the $1 variable had no value.) This is probably not what
you wanted. To force the dollar sign to be taken literally, you must
apply a "quoting rule", such as "precede a character by backslash (\)
to force the shell to take the character literally":
echo The price is \$10.20
The price is $10.20
But now suppose you want the backslash AND the dollar sign to be taken
literally:
echo The price is \\$10.20
This doesn't work, since the first backslash quotes the second one,
thereby leaving the dollar sign unquoted again:
The price is \0.20
Quoting the dollar sign requires addition of a third backslash:
echo The price is \\\$10.20
The price is \$10.20
The first backslash quotes the second one, and the third backslash
quotes the dollar sign.
Every command language -- all UNIX shells, VMS DCL, DOS Batch, AOS/VS
CLI, etc etc -- has similar rules. UNIX shell rules are probably the
most complicated, since many printable characters -- not just one --
are special there: dollar sign, single quote, double quote, backslash,
asterisk, accent grave, number sign, ampersand, question mark,
parentheses, brackets, braces, etc -- practically every
non-alphanumeric character needs some form of quoting if it is to be
taken literally. And to add to the confusion, the UNIX shell offers
many forms of quoting, and many alternative UNIX shells are available,
each using slightly different syntax.
_________________________________________________________________
1.11.2. Kermit's Quoting Rules
Kermit's basic quoting rules are simple by comparison (there are, of
course, additional syntax requirements for macro definitions, command
blocks, function calls, etc, but they are not relevant here).
The following characters are special in Kermit commands:
Backslash (\)
Introduces a variable, or the numeric representation of a
special character, or a function, or other item for
substitution. If the backslash is followed by a digit or by any
of the following characters:
x, o, d, m, 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).
Semicolon (;)
(Only when at the beginning of a line or preceded by at least
one space or tab) Introduces a comment.
Number sign (#)
(Only when at the beginning of a line or preceded by at least
one space or tab) Just like semicolon; introduces a comment.
Question mark (?)
(Only at the command prompt - not in command files or macros)
Requests context-sensitive help.
To force Kermit to take any of these characters literally, simply
precede it by a backslash (\).
Sounds easy! And it is, except when backslash also has a special
meaning to the underlying operating system, as it does in DOS,
Windows, and OS/2, where it serves as the directory separator in
filenames such as:
D:\K95\KEYMAPS\READ.ME
Using our rule, we would need to refer to this file in Kermit commands
as follows:
D:\\K95\\KEYMAPS\\READ.ME
But this would not be obvious to new users of Kermit software on DOS,
Windows, or OS/2, and it would be annoying to seasoned ones. Thus
MS-DOS Kermit and Kermit 95 go to rather extreme lengths to allow the
more natural notation, as in:
send d:\k95\keymaps\read.me
The reason this is tricky is that we also need to allow for variables
and other expressions introduced by backslash in the same command. For
example, suppose \%a is a variable whose value is "oofa" (without the
quotes). What does the following command do?
send d:\%a
Does it send the file named "oofa" in the current directory of the D:
disk, or does it send a file named "%a" in the root directory of the
D: disk? This is the kind of trouble we get into when we attempt to
bend the rules in the interest of user friendliness. (The answer is:
if the variable \%a has definition that is the name of an existing
file, that file is sent; if a file d:\%a exists, it is sent; otherwise
if both conditions are true, the variable takes precedence, and the
literal filename can be forced by quoting: \\%a.)
In Kermit 95 (but not MS-DOS Kermit), we also bend the rules another
way by allowing you to use forward slash (/) rather than backslash (\)
as the directory separator:
send d:/k95/keymaps/read.me
This looks more natural to UNIX users, and in fact is perfectly
acceptable to the Windows 95/98/NT and OS/2 operating systems on the
API level. BUT (there is always a "but") the Microsoft shell,
COMMAND.COM, for Windows 95/98 and NT does not allow this notation,
and therefore it can not be used in any Kermit command -- such as RUN
-- that invokes the Windows command shell AND your command shell is
COMMAND.COM or any other shell that does not allow forward slash as
directory separator (some alternative shells do allow this).
NOTE: There exists a wide variety of alternative shells from third
parties that do not have this restriction. If you are using a shell
that accepts forward slash as a directory separator, you can stop
reading right now -- UNLESS (there is always an "unless") you want
your scripts to be portable to systems that have other shells. Also
note that some Windows shells might actually REQUIRE forward
slashes (instead of backslashes) as directory separators; we do not
treat this situation below, but the treatment is obvious -- use
slash rather backslash as the directory separator.
_________________________________________________________________
1.11.3. Passing DOS Filenames from Kermit to Shell Commands
The following Kermit commands invoke the system command shell:
RUN (and its synonyms ! and @)
REDIRECT
PIPE
Each of these commands takes a shell command as an operand. These
shell commands are not, and can not be, parsed by Kermit since Kermit
does not know the syntax of shell commands, and so can't tell the
difference between a keyword, a filename, a variable, a switch, or
other item. Therefore the rules can not be bent since Kermit doesn't
know where or how to bend them. To illustrate (using the regular
Windows shell):
run c:\\windows\\command\\chkdsk.exe
works OK, but:
run c:/windows/command/chkdsk.exe
is not accepted by COMMAND.COM. But:
run c:\windows\command\chkdsk.exe
results in Kermit applying its quoting rules before sending the text
to the shell. Since "w" and "c" are not in the list of backslash-item
codes, the backslash means "take the following character literally".
Thus, by the time this filename gets to the Windows shell, it has
become:
c:windowscommandchkdsk.exe
which is probably not what you wanted. (If "w" and "c" were in the
list, the results could be even stranger.) Even more confusing is the
case where a directory or filename starts with one or more digits:
run c:\123\lotus.exe
in which "\123" is the Kermit notation for ASCII character 123, which
happens to be left brace ({), resulting in "c:{lotus.exe".
So when passing filenames to a Windows shell, always use double
backslashes as directory separators, to ensure that the shell gets
single backslashes:
run c:\\windows\\command\\chkdsk.exe
run c:\\123\\lotus.exe
Similar problems might occur with the built-in EDIT, BROWSE, and FTP
commands. These commands result in Kermit building a shell command
internally to invoke the associated helper program; the form of this
command might conflict with the form demanded by certain alternative
shells.
_________________________________________________________________
1.11.4. Using Variables to Hold DOS Filenames
Now to the next level. Suppose you want to write a script in which
filenames are parameters, and therefore are stored in variables.
Example:
define \%f c:\windows\command\chkdsk.exe
...
run \%f
Obviously this won't work for the reasons just noted; the RUN command
requires directory separators be coded as double backslashes:
define \%f c:\\windows\\command\\chkdsk.exe
...
run \%f
This will work; no surprises here. However, if you had used ASSIGN
rather than DEFINE, you might have been surprised after all; review
pages 348-349 of [359]Using C-Kermit (2nd Ed) for the difference
between DEFINE and ASSIGN.
We have said that any Kermit 95 or MS-DOS Kermit command that parses
filenames itself -- SEND, for example -- does not require double
backslashes since it knows it is parsing a filename. So since the
following works:
send c:\windows\command\chkdsk.exe
Should the following also work?
define \%f c:\windows\command\chkdsk.exe
...
send \%f
Answer: No. Why? Because \%f is evaluated "recursively", to allow for
the possibility that its definition contains further variable
references. This is true of all "backslash-percent-letter" (or -digit)
variables, and also for array references. So \%f becomes
c:\windows\command\chkdsk.exe, which becomes
c:windowscommandchkdsk.exe.
The trick here is to use the "other" kind of variable, that is
evaluated only "one level deep" rather than recursively:
define filename c:\windows\command\chkdsk.exe
...
send \m(filename)
Similarly if you want to prompt the user for a filename:
ask filename { Please type a filename: }
Please type a filename: c:\windows\command\chkdsk.exe
send \m(filename)
_________________________________________________________________
1.11.5. Passing DOS Filenames as Parameters to Macros
Suppose you want to pass a DOS filename containing backslashes as a
parameter to a Kermit macro. This raises two issues:
1. Parameters to macros are "just text" and so are fully evaluated
before they are passed to the macro.
2. Once inside the macro, the formal parameters \%1, \%2, ... \%9 are
the type of variable that is evaluated recursively.
Thus a DOS filename is ruined once in the act of parsing the macro
invocation, and again when referring to it from within the macro. To
illustrate, suppose "test" is a macro. Then in the invocation:
test c:\mydir\blah.txt
"c:mydirblah.txt" is assigned to \%1. However, if we double the
backslashes:
test c:\\mydir\\blah.txt
"c:\mydir\blah.txt" is assigned to \%1. But then when you refer to \%1
in the macro, it is evaluated recursively, resulting in
"c:mydirblah.txt". To illustrate:
define test echo \%1
test c:\mydir\blah.txt
c:mydirblah.txt
test c:\\mydir\\blah.txt
c:mydirblah.txt
test c:\\\\mydir\\\\blah.txt
c:\mydir\blah.txt
Let's address each part of the problem separately. First, inside the
macro. You can use the \fcontents() function to force a
backslash-percent variable (such as a macro argument) to be evaluated
one level deep instead of recursively, for example:
define test echo { The filename is "\fcontents(\%1)"}
test c:\mydir\blah.txt ; We don't expect this to work
The filename is "c:mydirblah.txt" ; and it doesn't.
test c:\\mydir\\blah.txt ; But this does...
The filename is "c:\mydir\blah.txt"
Thus if the filename arrives inside the macro with single backslashes,
the backslashes are preserved if you always refer to the parameter
through the \fcontents() function.
Now how to ensure that backslashes are not stripped or misinterpreted
when passing a filename to a macro? This brings us back to what we
learned in earlier sections:
1. If it is a literal filename, either double the backslashes, or (if
the filename is to be used only within Kermit itself and not
passed to a DOS shell, or it is to be passed to an alternative
shell that accepts forward slash as a directory separator), use
forward slash instead of backslash as the directory separator.
2. If it is a variable that contains a filename, make sure you use a
macro-style variable name, rather than a
backslash-percent-character name.
Examples:
define test echo \fcontents(\%1)
define filename c:\mydir\blah.txt
test c:\\mydir\\blah.txt ; Literal filename with double backslashes
c:\mydir\blah.txt
test c:/mydir/blah.txt ; Literal filename with forward slashes
c:/mydir/blah.txt
test \m(filename) ; Variable
c:\mydir\blah.txt
But what if you don't like these rules and you still want to pass a
literal filename containing single backslashes to a macro? This is
possible too, but a bit tricky: turn command quoting off before
invoking the macro, and then turn it back on inside the macro.
Example:
define test set command quoting on, echo \fcontents(\%1)
set command quoting off
test c:\mydir\blah.txt
c:\mydir\blah.txt
Upon return from the macro, command quoting is back on (since the
macro turned it on).
Obviously this trick can not be used if the filename is stored in a
variable, since it prevents the variable from being evaluated.
_________________________________________________________________
1.11.6. Passing DOS File Names from Macro Parameters to the DOS Shell
Now suppose you need to pass a DOS filename to a macro, and the macro
needs to pass it, in turn, to the Windows shell via (say) Kermit's RUN
command. This works too:
define xrun run \fcontents(\%1)
xrun c:\\windows\\command\\chkdsk.exe
(or you can use the SET COMMAND QUOTING OFF / ON technique described
above to avoid the double backslashes.) But..
xrun c:/windows/command/chkdsk.exe
does not work if the Windows shell does not recognize "/" as a
directory separator. If there is a chance that a filename might be
passed to the macro in this form, the macro will need to convert it to
a form acceptable to the shell:
define xrun run \freplace(\fcontents(\%1),/,\\)
Here we replace all occurrences (if any) of "/" in the argument with
"\" prior to issuing the RUN command. Of course, in order to specify
"\" as a literal character in the \freplace() argument list, we have
to double it.
_________________________________________________________________
1.11.7. Passing DOS Filenames to Kermit from the Shell
As noted in the manual, the \&@[] array contains Kermit's command-line
arguments. Suppose one of these arguments, say \&@[3], is a DOS
filename such as C:\FOO\BAR\BAZ\OOFA.TXT. (Note: In C-Kermit 7.0 and
K95 1.1.18 and later, command-line arguments after "=" or "--" are
also available in the top-level \%1..9 variables; see [360]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 [361]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
([362]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 nis 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
[363]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 nis 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 [364]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.19 supports
patterns in several places:
* Filenames ([365]Section 4.9)
* SWITCH case labels ([366]Section 7.18)
* The new IF MATCH statement ([367]Section 7.4)
* TYPE /MATCH ([368]Section 1.15)
* SET FILE TEXT-PATTERNS and BINARY-PATTERNS ([369]Section 4.3)
* The \fsearch() and \farraylook() functions ([370]Sections 7.3 and
[371]7.10.7)
* The \fpattern() function used with [M,RE]INPUT ([372]Section 7.1)
Patterns are also called wildcards, especially when used for filename
matching. C-Kermit's pattern syntax is explained in [373]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:
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).
_________________________________________________________________
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 [374]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 [375]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:
1. Only one READ file and one WRITE file can be open at a time.
2. The READ and WRITE commands are strictly line oriented.
3. These commands can not be used with binary files.
4. They do not support read/write access or random access.
5. 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:
1. The session, packet, debug, transaction, and connection logs.
2. Reading and writing commands rather than files.
3. 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
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 [376]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 [377]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 Kermit exits,
or you close it explicitly. 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 [378]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 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 indicated number of
NUL bytes. If /SIZE was not given, this switch is ignored.
/RPAD[:value]
Like LPAD, but pads on the right.
/CHARACTER
Specifies that one character should be written. If the text is
empty or not given, a NUL character is written; otherwise the
first character of text is given. Synonym: /BYTE.
/STRING
Specifies that the text is to be written as-is, with no
terminator added.
Here's an example in which we copy a text file line by line:
file open /read \%c oofa.txt ; Open input file
if fail exit 1 Can't open input file ; Check that it's open
file open /write \%d new.txt ; Open output file
if fail exit 1 Can't open output file ; Check
while true { ; Loop to copy lines
file read /line \%c line ; Read a line
if fail break ; Assume failure = end of file
file write /line \%d {\m(line)} ; Write the line to output file
if fail exit 1 Write failure ; Failure here is fatal
}
file close \%c ; Close the two files
file close \%d
Note that since /LINE is the default for both FILE READ and FILE
WRITE, it can be omitted as in the following example, where we also
use the short names for the FILE commands.
fopen /read \%c oofa.txt ; Open input file
if fail exit 1 Can't open input file ; Check that it's open
fopen /write \%d new.txt ; Open output file
if fail exit 1 Can't open output file ; Check
while true { ; Loop to copy lines
fread \%c line ; Read a line
if fail break ; Assume failure = end of file
fwrite \%d {\m(line)} ; Write the line to output file
if fail exit 1 Write failure ; Failure here is fatal
}
fclose \%c ; Close the two files
fclose \%d
Here's the same example using "record i/o" (the open and close
sequences are are omitted since they are the same as above). The
result is the same, but execution is much faster:
while true { ; Loop to copy blocks
fread /size:512 \%c block ; Read a block into \%a
if fail break ; Assume failure = end of file
fwrite /string \%d {\m(block)} ; Write the block to output file
if fail exit 1 Write failure ; Failure here is fatal
}
Although record i/o is faster, it should not be used in line-oriented
applications, since it returns arbitrary chunks of the file to your
script, rather than lines. In this example, FWRITE /STRING is used
rather than FWRITE /SIZE:512 to avoid the last output block being
padded beyond the original file's length.
A file can also be copied character by character, but this is much
slower than line i/o and VERY much slower than block i/o:
while true { ; Loop to copy blocks
fread /char \%c c ; Read a character into c
if fail break ; Assume failure = end of file
fwrite /char \%d {\m(c)} ; Write character to output file
if fail exit 1 Write failure ; Failure is fatal
}
Although character i/o is slow, it is the only way to process files
that contain NUL characters (i.e. bytes composed of only zero bits).
In the example above, when "fread /char \%c c" returns a NUL, the c
variable is empty. But since the FREAD /CHAR command did not fail, we
know the result was really a NUL. FWRITE /CHAR, when given an empty
variable (or no variable at all) writes a NUL. Thus the loop above
will copy any file at all (very slowly). In non-copying applications,
NULs are detected like this:
fread /char \%c c
if fail (do something)
if not def c (a NUL byte was read)
Finally some advanced file operations:
FILE FLUSH channel
For output files only: commits all previous writes to disk, in
case the computer was buffering them. Synonym: FFLUSH.
FILE COUNT [ { /BYTES, /LINES, /LIST, /NOLIST } ] channel
By default, or if the /BYTES switch is given, counts the bytes
in the file, if any, open on the given channel. If the /LINES
switch is given, counts lines in the file. If the /LIST switch
is given, the result is printed. If the /NOLIST switch is
given, the result is not printed. /QUIET is a synonym for
/NOLIST. If neither /LIST nor /NOLIST is given, the result is
printed if the command is given at top level, i.e. not from a
command file or macro. In all cases, the result of the most
recent FILE COUNT command is stored in the variable
\v(f_count). Note that FILE COUNT /LINE works (and can only
work) by reading the entire file; expect it to take some time
if the file is large. Synonym: FCOUNT.
FILE REWIND channel
Moves the read/write pointer to the beginning of the file.
Equivalent to FILE SEEK channel 0. Synonym: FREWIND.
FILE SEEK [ switches ] channel { [{+,-}]number, LAST, EOF }
Moves the read/write pointer for the file on this channel to
the given position, which may be a byte (character) number or a
line number, expressed in either absolute or relative terms.
Switches:
/BYTE
The number given is a byte number. Synonym: /CHARACTER.
/LINE
The number given is a line number.
/ABSOLUTE
The number given is absolute.
/RELATIVE
The number given is relative to the current position.
By default, or if the /BYTE switch is given, the number is a
byte number (0 = first byte). If /LINE is given, the number is
a line number (0 = first line). EOF means to move to the end of
the file. LAST means to move to the last line or character of
the file, depending on whether it's a line or character seek.
If neither the /RELATIVE nor the /ABSOLUTE switch is given,
then if a signed number is given, the motion is relative to the
current position. An expression that evaluates to a negative
number is not considered signed for this purpose; that is, a
sign (+ or -) must be included as the first character of the
number in the command itself to force a relative seek (in the
absence of /RELATIVE or /ABSOLUTE).
If the number has no sign, or if the /ABSOLUTE switch is given,
the number represents an absolute position (relative to the
beginning of the file). Subsequent FILE READs or WRITEs will
take place at the new position.
If the read/write pointer is placed after the end of the file,
a subsequent FILE READ will fail, but a FILE WRITE will succeed
(possibly creating a file with "holes"). If a FILE SEEK /BYTE
command is given, the current line becomes unknown (unless the
position is 0) and subsequent FILE SEEK /RELATIVE /LINE
commands will fail until the next non-relative FILE SEEK /LINE
command is given. Synonym: FSEEK.
An absolute FILE SEEK to a negative position fails silently, as does a
relative seek to a position before the beginning of the file.
A caution about relative SEEKs: remember that the number is relative
to the current position. Whenever you read or write, this changes the
position. In each of the following examples, assume the file open on
channel \%c is positioned at line n (the FREAD target variable is
omitted for lack of space):
{ FREAD \%c, FSEEK /LINE \%c -1, FREAD \%c } <-- Reads line n twice
{ FREAD \%c, FSEEK /LINE \%c +0, FREAD \%c } <-- Reads lines n and n+1
{ FREAD \%c, FSEEK /LINE \%c +1, FREAD \%c } <-- Reads lines n and n+2
{ FREAD \%c, FSEEK /LINE \%c -2, FREAD \%c } <-- Reads lines n and n-1
{ FREAD \%c, FSEEK /LINE \%c -3, FREAD \%c } <-- Reads lines n and n-2
Another caution: Using FSEEK and FREAD /SIZE to repeatedly read the
same disk block (e.g. when sampling a database record that is
frequently updated) might not give you updated disk blocks due to the
internal buffering and caching of the C library (this probably varies
from one platform/compiler combination to another). If necessary you
can force a fresh disk read with a close/open sequence:
FCLOS \%c
FOPEN \%c samefilename
FSEEK \%c samespot
FREAD /SIZE:howmanybytes \%c variable
_________________________________________________________________
1.22.3. FILE Command Examples
To read the last 10 lines of a text file into an array:
fopen /read \%c oofa.txt ; Open the file
if fail exit 1 Can't open oofa.txt ; Always check for failure
dcl \&a[10] ; Declare a 10-element array
fcount /line \%c ; Count lines in the file
fseek /line \%c \v(f_count)-10 ; Seek to 10 lines from the end
if fail exit 1 Can't seek ; Check for failure
for \%i 1 10 1 { fread \%c \&a[\%i] } ; Read the last 10 lines
fclose \%c ; Close the file
Note that blank lines show up as empty (undefined) array elements, for
example if you give a "show array a" command at this point. This is
normal. You can still use these elements; e.g.:
for \%i 1 10 1 { echo \%i. \&a[\%i] } ; Display the 10 lines
Here is how to read the last line of a file (already open on channel
\%c):
fseek /line \%c last ; Seek directly to last line
Alternatively:
fseek /line \%c eof ; Seek to end of file
fseek /line \%c -1 ; Seek to beginning of last line
Alternatively:
fcount /line \%c ; Count the file's lines
fseek /line \%c \v(f_count)-1 ; Seek to last line
fread \%c ; Read it
To read every other line from the file (using relative SEEK), skipping
the first line:
fopen /read \%c oofa.txt ; Open the file
while ( success ) { ; Loop through lines
fseek /line \%c +1 ; Skip a line
if success fread \%c ; Read & display a line
}
fclose \%c ; Close the file
Here is how to read the lines of a file in reverse order:
fopen /read \%c oofa.txt ; Open
if fail exit 1 ; Check
fseek /line \%c last ; Seek to last line
while success { ; Loop
fread \%c ; Read line
fseek /line \%c -2 ; Seek backwards two lines
}
fclose \%c ; Close the file
The loop works because a relative SEEK outside the file fails.
It is also possible to use block i/o to manage random-access files
with fixed-length records (as long as they don't contain NUL
characters). Suppose, for example, you have a file of "card image"
records with fixed-field information about customers, such as:
Name: Columns 1-32 (column numbers are 1-based)
Address: Columns 33-72
Balance: Columns 73-80
The records are indexed by customer number, starting with 0. There are
no line terminators separating them. Therefore the record for customer
number n starts at position nx 80 (\%n*80).
Now suppose we received a payment from customer number 173 and want to
update the balance:
.\%n = 173 ; Customer (record) number
.\%a = 12.72 ; Amount
fopen /read /write \%c customer.db ; Open the file
if fail stop 1 OPEN FAILED: \f_errmsg() ; Check
fseek /byte \%c 80*\%n ; Seek to record
fread /size:80 \%c r ; Read the record
if fail stop 1 READ FAILED: \f_errmsg() ; Check (IMPORTANT)
.\%b := \fright(\m(r),8) ; Extract the balance
.\%b := \ffpadd(\%b,\%a,2) ; Add the new payment
if fail stop 1 ARITHMETIC ERROR: \%b/\%a ; Catch bad records
.r := {\fleft(\m(r),72)\flpad(\%b,8)} ; Update the record
fseek /byte \%c 80*\%n ; Reposition to same spot
fwrite /size:80 \%c {\m(r)} ; Replace the record
if fail stop 1 WRITE FAILED: \f_errmsg() ; Check
fclose \%c ; Close the file
REMEMBER: Using FILE SEEK to move beyond the end of file can result in
a file with holes when writing; when reading, an end-of-file error
will occur -- be sure to check for it.
_________________________________________________________________
1.22.4. Channel Numbers
C-Kermit's channel numbers are integers from 0 to some
platform-dependent limit, such as 46 or 1985 (the value of \v(f_max)).
This is the limit placed by the operating system on the number of
files that may be opened by one process or user or job, minus the
standard input, output, and error files, and minus the number of files
reserved by C-Kermit for logs, OPEN READ and WRITE, and file transfer
(and maybe some command files -- the \v(f_max) number can't be exact).
Although you must include a variable in the FILE OPEN command, to
which the channel number is assigned, you don't have to use a variable
in the other FILE commands if you know what the number is -- you can
just put the number. This saves you a few keystrokes when typing
commands at the prompt:
fopen \%c oofa.txt
flist
0. /usr/olga.oofa.txt (R) 0
This tells the channel number is 0 (the number on the left is the
channel file's channel number). Of course you can also find it by
echoing the variable:
echo \%c
0
Or with "fstatus \%c". Now you can type commands like:
fread 0
to read a line from the file. Obviously, however, using digits rather
than a variable for the channel number would be poor practice in a
script.
If in commands like:
fread \%c \%a
you have trouble remembering which variable is which, note that the
channel number is, indeed, a number. Anywhere C-Kermit accepts a
number it can also accept an expression, so you can put parentheses
around the channel number to remind you it's the channel number and
not the variable into which data is to be read:
fread (\%c) \%a
Normally channel numbers are assigned sequentially as 0, 1, 2, ... up
to the limit. However, once you start closing files, there can be
holes in the sequence. New channels are assigned to fill in the holes.
Thus you can't depend on channel numbers being in any particular
sequence.
_________________________________________________________________
1.22.5. FILE Command Errors
Each FILE command sets the variable \v(f_error) to one of the
following values:
0 = No error
-1 = System error
-2 = Attempt to read after end of file
-3 = Channel not open
-4 = Channel number out of range (negative or too large)
-5 = Numeric argument (size, ...) out of range
-6 = File not found
-7 = Bad or missing filename
-8 = Too many files are already open (FILE OPEN only)
-9 = Forbidden operation (e.g. write to a read-only file)
-10 = Access denied
-11 = Illegal combination of OPEN modes (FILE OPEN only)
-12 = Buffer overflow
-13 = Current line number unknown (for relative line seeks)
-14 through -98: Reserved.
-99 = Requested operation not implemented in this version of C-Kermit
-999 = Unknown error
When \v(f_error) is -1, this means the FILE command failed because
because of a system error, in which case you can examine the following
variables:
\v(errno) = System error number.
\v(errstring) = Error message corresponding to \v(errno).
A special function is available for translating the \v(f_error) code
to an error message string:
\f_errmsg([code])
If the code is -1, returns error message of the most recent system
error; otherwise if the code is a valid \v(f_error) value, the associated
message is returned. If the code is omitted, the status message
corresponding to the current \v(f_error) value is returned.
A FILE command that fails prints the appropriate error message
automatically, except when the command is READ or SEEK and the error
is -2 (end of file); in that case, the command still fails, but does
not print a message. This allows constructions such as:
fopen \%c oofa.txt
while success { fread \%c }
fclose \%c
to work as expected, i.e. without an annoying message when the end of
file is reached.
_________________________________________________________________
1.22.6. File I/O Variables
The variables associated with the file i/o package are:
\v(f_count)
Result of the most recent FILE COUNT (FCOUNT) command.
\v(f_error)
Numeric error code of most recent FILE command (0 = no error).
\v(f_max)
Maximum number of files open simultaneously.
_________________________________________________________________
1.22.7. File I/O Functions
Some of the FILE commands can also be issued as function calls, which
makes script writing a bit more convenient, especially for C
programmers. Also, several functions are provided that do not have
command equivalents. Each of these functions takes a channel number as
the first argument. These functions do not work for OPEN { READ,
!READ, WRITE, !WRITE, and APPEND } files.
\f_status(channel)
Returns 0 if the channel is not open, otherwise a number
between 1 and 15 which is the sum of the OPEN modes:
1 = /READ
2 = /WRITE
4 = /APPEND
8 = /BINARY
The remaining functions work only for open channels. Each of these
functions can fail for the applicable reasons listed in [379]Section
1.22.5. For instructions on handling function errors, see [380]Section
7.12.
\f_pos(channel)
Returns the file's current read/write pointer (0-based). There
is no FILE command equivalent.
\f_line(channel)
Returns the file's current line number (0-based), if known,
otherwise -1. There is no FILE command equivalent. The line
number is known as long as no character or block i/o has been
done on the channel.
\f_handle(channel)
Returns the "file handle" of the file. That is, it translates
the portable C-Kermit channel number into a system-specific
file handle or number that can be passed to other programs on
the same platform. In UNIX this is a file descriptor. There is
no FILE command equivalent.
\f_eof(channel)
Returns 1 if the read/write pointer of the file on the given
channel is at the end of the file, 0 otherwise. Convenient in
WHILE statements, e.g.:
while not \f_eof(\%c) { fread \%c }
\f_getchar(channel)
Equivalent to FREAD /CHAR. Returns the character actually read.
If \f_getchar() does not fail but the return value is empty,
this means a NULL character was read.
\f_getline(channel)
Equivalent to FREAD /LINE. Returns the line actually read, but
with the line terminator stripped. If \f_getline() does not
fail but the return value is empty, this normally means an
empty line was read.
\f_getblock(channel,n)
Equivalent to FREAD /SIZE:n. Returns the block of characters
actually read. If the returned block is smaller than n, it
indicates either that the end of file was reached or a NUL
character is in the block.
\f_putchar(channel,c)
Equivalent to FWRITE /CHARACTER. Writes the character c. If c
contains more than one character, only the first is written. If
c is empty a NUL is written. Returns the number of characters
written on success, or a negative error code upon failure.
\f_putline(channel,string)
Equivalent to FWRITE /LINE. Writes the string and adds the
appropriate line termination character or sequence. If the
string is empty or omitted, an empty line is written. Returns
the number of characters written on success, or a negative
error code upon failure.
\f_putblock(channel,string)
Equivalent to FWRITE /STRING. Writes the string as given. If
the string is empty or omitted, nothing is written. Returns the
number of characters written on success, or a negative error
code upon failure.
_________________________________________________________________
1.22.8. File I/O Function Examples
fopen /read \%c oofa.txt ; Open our favorite file for reading
if failure exit 1 ; Check that it's open
while not \f_eof(\%c) { ; Loop until EOF
.line := \f_getline(\%c) ; Get a line
if success echo {\m(line)} ; Echo it
}
if not \f_eof(\%c) { ; Check reason for loop exit
exit 1 File Error: \f_errmsg() ; If not EOF say so.
}
frewind \%c ; Rewind the file
while not \f_eof(\%c) { ; Same thing but with block i/o
.block := \f_getblock(\%c,256) ; (much faster than line i/o)
if success xecho {\m(block)}
}
frewind \%c ; Rewind again
while not \f_eof(\%c) { ; Same deal but with character i/o
.c := \f_getchar(\%c) ; (much slower than line i/o)
if success xecho {\m(c)}
}
close \%c
To close all open files (equivalent to FCLOSE ALL):
for \%i 0 \v(f_max)-1 1 {
if \f_status(\%i) fclose \%i
}
_________________________________________________________________
1.23. The EXEC Command
The EXEC command is available only in UNIX.
EXEC [ /REDIRECT ] command [ arg1 [ arg2 [ ... ] ]
Runs the given command with the arguments in such a way that
the command replaces C-Kermit in memory, and C-Kermit ceases to
execute. EXEC is like RUN, except instead of returning to
C-Kermit when finished, the command returns to whatever process
invoked Kermit.
In the normal case, no files are closed, so the EXEC'd command
inherits the open files, read/write pointers, working directory,
process ID, user ID (unless command is SUID), group ID (unless command
is SGID), groups, etc. (In UNIX, the EXEC command is simply a front
end for execvp().)
If the /REDIRECT switch is included, then if a connection is open (SET
LINE or SET HOST), it becomes the standard input and output of the
EXEC'd program. If no connection is open, the /REDIRECT switch has no
effect. For example to use C-Kermit for PPP dialing in Linux:
set modem type usr ; Specify the kind of modem you have
set line /dev/ttyS1 ; Specify the device it's connected to
set speed 57600 ; and the speed
set flow rts/cts ; and flow control.
set dial retries 100 ; Try the dial sequence up to 100 times.
dial {{9-212-555-1212}{9-212-555-1213}{9-212-555-1214}{9-212-555-1215}}
if fail exit 1
for \%i 1 16 1 { ; Try up to 16 times to get login prompt
input 10 Login: ; Wait 10 sec for it to appear
if success break ; Got it - proceed...
output \13 ; Send a carriage return and try again
}
if ( > \%i 16 ) stop 1 NO LOGIN PROMPT
lineout \(myuserid) ; Send user ID
input 30 assword: ; Wait for Password prompt
if fail stop 1 NO PASSWORD PROMPT
lineout \m(mypassword) ; Send the password.
exec /redirect pppd ; Replace ourselves with pppd.
In this example we assume that the script has already set up the
myuserid and mypassword variables -- normally the password should be
prompted for, rather than stored on disk. Notice the advantages over
the well-known "chat script":
* You don't have to control the modem itself with AT commands;
Kermit's DIAL command does this for you.
* You can have Kermit automatically redial as many times as you want
until it gets a connection (if this is legal in your country).
* You can have Kermit fetch the number or numbers from a dialing
directory.
* You can have Kermit cycle through a list of phone numbers (this is
new in C-Kermit 7.0; see [381]Section 2.1.16) without having to
enter the numbers in a dialing directory.
* Dialing is location-independent; you can use the same script to
dial from different areas or countries.
* Once the connection is made, the full power of Kermit's script
language is available to manage the dialog with the terminal
server or other device that answers the phone call.
NOTE: PPP and SLIP dialing are not available in Windows 95/98/NT/2000,
whose APIs do not provide a method for an application to hand over a
connection to the PPP or SLIP driver.
_________________________________________________________________
1.24. Getting Keyword Lists with '?'
Suppose you type "te" at the C-Kermit> 6.0 prompt and then Esc or Tab
to request keyword completion. Kermit beeps, indicating that more than
one command starts with "te". But if you type '?' to see what they
are, Kermit shows only "telnet". So why the beep? Because of invisible
keywords like "telopt", "terminal", and "text". Lots of keywords are
invisible because they are either synonyms for other keywords or else
esoteric options to be used only in special circumstances, so we don't
want them cluttering up the menus.
But then there is no way for you to discover them. So in C-Kermit 7.0,
if you type '?' AFTER the beginning of a keyword field, then invisible
keywords are shown too:
C-Kermit> te<Esc><BEEP>
C-Kermit> te? Command, one of the following:
telnet telopt terminal text
C-Kermit>te
But if '?' is typed at the beginning of a field, only visible keywords
are shown, as before (so, in this example, if '?' is typed at the
C-Kermit> prompt, "telnet" is the only command shown that starts with
"te").
_________________________________________________________________
2. MAKING AND USING CONNECTIONS The SET LINE, SET HOST, and SET PORT (a
synonym for SET LINE) commands have new synonyms, in which the word SET is
replaced by the word OPEN: OPEN LINE, etc. There is no new functionality
here, but OPEN is a better verb, since SET generally takes no action, whereas
these commands actually try to open a connection. Furthermore, there is the
symmetry with CLOSE.
________________________________________________________________________
2.0. SET LINE and SET HOST Command SwitchesThe SET LINE (SET PORT) and SET
HOST commands now allow switches before the device or host name, in most
cases, and under certain circumstances, also at the end. The new syntax is
backwards compatible with the previous syntax; thus SET LINE, SET PORT, and
SET HOST commands in command files written for C-Kermit 6.0 or earlier still
work. The expanded syntax is:
{ OPEN, SET } { LINE, PORT, HOST } [ switches ] device-or-address [ switches
]
The first group of switches is:
/NETWORK-TYPE:{TCP/IP,X.25,PIPE,PTY...}
When more than one network type is available, this lets you
specify the type of network to use for this connection without
affecting your global SET NETWORK TYPE. See [382]Section 2.7
about pipes and ptys.
/USERID:[string]
This switch is equivalent to SET LOGIN USERID. If a string is
given, it sent to host during Telnet negotiations; if this
switch is given but the string is omitted, no user ID is sent
to the host. If this switch is not given, your current LOGIN
USERID (\v(userid) value), if any, is sent. Unlike most other
switches, this one is "sticky", since the value must persist
throughout the session in case the server requests the ID
string at a later time.
/CONNECT
Enter CONNECT mode immediately and automatically after the
device or connection is open. On serial devices, however, when
CARRIER-WATCH is not OFF, wait up to 1 second for the Carrier
Detect signal to appear before trying to connect, to give the
device time to react DTR, which might have been off prior to
opening the device.
/SERVER
Enter server mode immediately and automatically after the
device or connection is open. Treatment of carrier is the same
as for /CONNECT.
/WAIT
/NOWAIT
For Telnet connections only: Like SET TELNET WAIT { ON, OFF },
but applies only to this connection, and in fact applies only
when OPENing this connection (which is usually the only place
it matters). Typically you would use TELNET /NOWAIT to make a
connection to a misbehaving Telnet server that does not reply
to negotiations as required by the Telnet protocol definition.
Note: /CONNECT and /SERVER switches are not available in the RLOGIN
and TELNET commands, since these commands already include an implicit
/CONNECT and preclude automatic entry into server mode.
The /CONNECT and /SERVER switches are especially useful with "set host
*" connections. For example, suppose you want to start a Kermit server
on socket 3000 of your TCP host. Normally you would have to give the
command:
set host * 3000
and then wait for a connection to come in, and only then could you
give the SERVER command (or else define a macro to do this, and then
execute the macro). Now you can do it in one step:
set host /server * 3000
This tells C-Kermit to wait for the connection and then enter server
mode once it comes in, no matter how long it takes. Similarly, "set
host /conn *" can be used to wait for a "chat" connection to come in.
Another set of switches is available in VMS only, for use only with
SET LINE:
/SHARE
Allows the SET LINE device to be opened in shared mode.
Normally it makes no sense to open a serial device in shared
mode, but it's necessary when C-Kermit is running in an
environment such as DECIntact, that opens your job's
controlling terminal in such a way that C-Kermit can't open it
too, unless it enables SHARE privilege. Note: SHARE privilege
is required.
/NOSHARE
Requires that the SET LINE device not be in use by any other
process in order for it to be successfully opened by C-Kermit.
If neither /SHARE nor /NOSHARE is specified, /NOSHARE is used.
The second group of switches is:
/NO-TELNET-INIT
Do not send initial Telnet negotiations even if this is a
Telnet port.
/RAW-SOCKET
This is a connection to a raw TCP socket ([383]Section 2.3.5).
/RLOGIN
Use Rlogin protocol even if this is not an Rlogin port.
/TELNET
Send initial Telnet negotiations even if this is not a Telnet
port.
As of C-Kermit 7.0 and K95 1.1.19, the TELNET command includes an
implicit /TELNET switch. So if you TELNET to a non-TELNET port, Kermit
sends initial Telnet negotiations. This makes sense, since that's what
"telnet" means.
If you want to make a connection to a non-Telnet port without sending
initial Telnet negotiations, use:
set host [ /connect ] name-or-address port
or:
telnet name-or-address port /no-telnet-init
Additional switches might be added in the future; type "set host ?" or
"set line ?" to see a current list.
_________________________________________________________________
2.1. Dialing
Automatic redialing is illegal or restricted in many countries, so
until C-Kermit 7.0, it was disabled by default, i.e. until a SET DIAL
RETRIES command was given. In C-Kermit 7.0, if no SET DIAL RETRIES
command has been given, a default is picked dynamically at DIAL time
based on the calling country code, if known. At this writing, the only
country code known to have no restrictions on automatic redialing is
1. So in this case a limit of 10 is chosen; otherwise 1. If you have
not given an explicit SET DIAL RETRIES command, SHOW DIAL shows the
value as "(auto)", and then the value actually used is shown when you
give the DIAL command.
As of C-Kermit 7.0, automatic redialing is automatically canceled if
the call could not be placed because no dialtone was detected.
_________________________________________________________________
2.1.1. The Dial Result Message
If DIAL DISPLAY is not ON, the "Call complete" message now shows the
modem's call result message, for example:
Dialing: ...
Call complete: "CONNECT 31200/ARQ/V32/LAPM/V42BIS"
The exact format and contents of this message, of course, depends on
the make, model, and configuration of your modem, so use your modem
manual to interpret it. The call result message is also available in
C-Kermit's \v(dialresult) variable.
C-Kermit> echo \v(dialresult)
CONNECT 31200/ARQ/V32/LAPM/V42BIS
C-Kermit> echo Speed = \fword(\v(dialresult),2)
Speed = 31200
C-Kermit>
Suppose your modem reports the modulation speed as shown above and you
want to ensure your call is completed at (say) 24000 bps or more. You
can use a little macro to do the job:
define HSDIAL { ; High Speed DIAL
local \%s
if < \v(argc) 1 if not def \v(dialnumber) end 1 Usage: \%0 number
set dial retries 100
set dial interval 1
while true {
dial \%*
if fail end 1 DIAL failed.
asg \%s \fword(\v(dialresult),2)
if def \%s if numeric \%s if not < \%s 24000 break
}
}
(See [384]Section 7.5 about the \%* variable.)
_________________________________________________________________
2.1.2. Long-Distance Dialing Changes
Due to the glut of cell phones, pagers, fax machines, ISPs, etc, area
codes and dialing rules are changing all the time. In the North
American Numbering Plan (NANP) countries (USA, Canada, etc), area
codes are split or overlayed with increasing frequency, and 10- and
11-digit dialing is gradually becoming the norm for local calls.
Changes are occurring In Europe, too, partly for these reasons and
partly because of some new EC rules.
In France, effective 18 October 1996, all calls, even local ones, must
be dialed with an area code. French area codes are presently 1-digit
numbers, 1-6, and the long-distance dialing prefix is 0. All calls
within France are considered long distance and begin with 01, 02, ...,
06.
Effective 1 May 1997, all calls within the US state of Maryland, even
local ones, must be dialed with an area code but without the
long-distance prefix -- this is the now widely-known North American
phenomenon of "ten digit dialing". The same is happening elsewhere --
many cities in Florida adopted 10-digit dialing in 1998.
In Italy beginning 19 June 1998, all calls to fixed (as opposed to
mobile) numbers must be prefixed by 0. When calling into Italy from
outside, the 0 must follow the country code (39). Calls to cell
phones, however, must be placed without the 0. Then on 29 December
2000, the 0 will become a 4 (for calling fixed numbers) and a prefix
of 3 must used for calling mobile phones. More info at:
http://www.telecomitalia.it/npnn/.
In Spain, effective 4 April 1998, with hard cutover on 18 July 1998,
all calls within the country must be dialed with 9 digits, and all
calls from outside Spain must also be dialed with 9 digits (after the
country code, 34). The new 9-digit numbers all begin with "9". More
info at: [385]http://www.telefonica.es/cambiodenumeracion/
Several new dialing features and commands have been added in version
6.1 and 7.0 to address these changes.
C-Kermit 6.0 and Kermit 95 1.1.11 and earlier handle the French
situation via a reasonable subterfuge (setting the local area code to
a nonexistent one), but did not handle "ten-digit dialing" well at
all; the recommended technique was to change the long-distance dialing
prefix to nothing, but this defeated Kermit's "list numbers for one
name" feature when the numbers were in different locations. For
example:
set dial ld-prefix
dial onlineservice
where "onlineservice" is a dialing directory entry name corresponding
to entries that are in (say) Maryland as well as other states, would
not correctly dial the numbers not in Maryland.
A new command lets you specify a list of area codes to be considered
local, except that the area code must be dialed:
SET DIAL LC-AREA-CODES [ areacode [ areacode [ areacode [ ... ] ] ] ]
The list may include up to 32 area codes. If a number is called
whose area code is in this list, it is dialed WITHOUT the
long-distance prefix, but WITH the area code.
So in Maryland, which (last time we looked) has two area codes, 410
and 301, the setup would be:
SET DIAL LC-AREA-CODES 410 301
Example:
SET DIAL LD-PREFIX 1
SET DIAL AREA-CODE 301
SET DIAL LC-AREA-CODES 410 301 <-- Area codes in 10-digit dialing region
DIAL +1 (301) 765-4321 <-- Dials 3017654321 (local with area code)
DIAL +1 (410) 765-4321 <-- Dials 4107654321 (local with area code)
DIAL +1 (212) 765-4321 <-- Dials 12127654321 (long distance)
The SET DIAL LC-AREA-CODES command does not replace the SET DIAL
AREA-CODE command. The latter specifies the area code you are dialing
from. If the called number is in the same area code, then the area
code is dialed if it is also in the LC-AREA-CODES list, and it is not
dialed otherwise. So if "301" had not appeared in the LC-AREA-CODES
list in the previous example:
SET DIAL LD-PREFIX 1
SET DIAL AREA-CODE 301
SET DIAL LC-AREA-CODES 410 <-- Area codes in 10-digit dialing region
DIAL +1 (301) 765-4321 <-- Dials 7654321 (local)
DIAL +1 (410) 765-4321 <-- Dials 4107654321 (local with area code)
DIAL +1 (212) 765-4321 <-- Dials 12127654321 (long distance)
The new Kermit versions also add a Local Call Prefix and Local Call
Suffix, in case you have any need for it. These are added to the
beginning and of local phone numbers (i.e. numbers that are not
long-distance or international). Examples:
SET DIAL LD-PREFIX 1
SET DIAL LC-PREFIX 9
SET DIAL LC-SUFFIX *
SET DIAL LC-AREA-CODES 410 <-- Area codes in 10-digit dialing region
SET DIAL AREA-CODE 301
DIAL +1 (301) 765-4321 <-- Dials 97654321* (local)
DIAL +1 (410) 765-4321 <-- Dials 94107654321* (local with area code)
DIAL +1 (212) 765-4321 <-- Dials 12127654321 (long distance)
_________________________________________________________________
2.1.3. Forcing Long-Distance Dialing
Suppose a number is in your country and area, but for some reason you
need to dial it long-distance anyway (as is always the case in
France). There have always been various ways to handle this:
1. Temporarily set your area code to a different (or nonexistent or
impossible) one (but this required knowledge of which area codes
were nonexistent or impossible in each country).
2. Dial the number literally instead of using the portable format,
but this defeats the purpose of the portable dialing directory.
Now there is also a new command that, very simply, can force
long-distance dialing:
SET DIAL FORCE-LONG-DISTANCE { ON, OFF }
If a call is placed to a portable phone number within the same
country code as the calling number, it is dialed with the
long-distance prefix and the area code if FORCE-LONG-DISTANCE
is ON. If OFF, the regular rules and procedures apply.
Example (France):
SET DIAL COUNTRY-CODE 33
SET DIAL AREA-CODE 6
SET DIAL FORCE-LONG-DISTANCE ON
(In fact, SET DIAL COUNTRY-CODE 33 automatically sets DIAL
FORCE-LONG-DISTANCE ON...)
Example (USA, for a certain type of reverse-charge calling in which
the called number must always be fully specified):
SET DIAL PREFIX 18002666328$ ; 1-800-COLLECT
SET DIAL COUNTRY-CODE 1
SET DIAL AREA-CODE 212
SET DIAL FORCE-LONG-DISTANCE ON
Example (Toronto, where calls to exchange 976 within area code 416
must be dialed as long distance, even when you are dialing from area
code 416):
SET DIAL COUNTRY-CODE 1
SET DIAL AREA-CODE 416
SET DIAL FORCE-LONG-DISTANCE ON
DIAL +1 (416) 976-xxxx
If dialing methods were consistent and sensible, of course it would be
possible to always dial every domestic call as if it were long
distance. But in many locations this doesn't work or if it does, it
costs extra. The following macro can be used for dialing any given
number with forced long-distance format:
define LDIAL {
local \%x
set dial force-long-distance on
dial \%*
asg \%x \v(success)
set dial force-long-distance off
end \%x
}
(See [386]Section 7.5 about the \%* variable.)
_________________________________________________________________
2.1.4. Exchange-Specific Dialing Decisions
This applies mainly to the North American Numbering Plan (NANP). Refer
to the section "Alternative notations" in [387]Using C-Kermit 2nd
Edition, pages 106-107, and the story about Toronto on page 110. Using
the new LC-AREA-CODES list, we can address the problem by treating the
exchange as part of the area code:
SET DIAL LD-PREFIX 1
SET DIAL AREA-CODE 416
SET DIAL LC-AREA-CODES 905276
DIAL +1 416 765 4321 <-- 7654321 (local)
DIAL +1 905 276 4321 <-- 9052764321 (local with area code)
DIAL +1 905 528 4321 <-- 19055284321 (long distance)
The same technique can be used in Massachusetts (story at top of page
111) and in any other place where dialing to some exchanges within a
particular area code is local, but to others in the same area code is
long distance.
_________________________________________________________________
2.1.5. Cautions about Cheapest-First Dialing
Kermit does not maintain a knowledge base of telephony information; it
only provides the tools to let you enter a phone number in a standard
format and dial it correctly from any location in most cases.
In particular, Kermit does not differentiate the charging method from
the dialing method. If a call that is DIALED as long-distance (e.g.
from 212 to 718 in country code 1) is not CHARGED as long distance, we
have no way of knowing that without keeping a matrix of charging
information for every area-code combination within every country, and
any such matrix would be obsolete five minutes after it was
constructed. Thus, "cheapest-first" sorting is only as reliable as our
assumption that the charging method follows the dialing method. A good
illustration would be certain online services that have toll-free
dialup numbers which they charge you a premium (in your online service
bill) for using.
_________________________________________________________________
2.1.6. Blind Dialing (Dialing with No Dialtone)
C-Kermit's init string for Hayes-like modems generally includes an X4
command to enable as many result codes as possible, so that Kermit can
react appropriately to different failure reasons. One of the result
codes that X4 enables is "NO DIALTONE". A perhaps not obvious side
effect of enabling this result code that the modem must hear dialtone
before it will dial.
It is becoming increasingly necessary to force a modem to dial even
though it does not hear a dialtone on the phone line; for example,
with PBXs that have strange dialtones, or with phone systems in
different countries, or with ISDN phones, etc. This is called "blind
dialing".
C-Kermit 7.0 has two new commands to cope with this situation:
SET DIAL IGNORE-DIALTONE { ON, OFF }
OFF (the default) means to tell the modem to wait for dialtone
before dialing. ON means to enable "blind dialing", i.e. tell
the modem NOT to wait for dialtone before dialing. Generally
this is accomplished by sending ATX3 to the modem just prior to
dialing. SET MODEM TYPE xxx and then SHOW MODEM displays
Kermit's built-in "ignore dialtone" command.
SET DIAL COMMAND IGNORE-DIALTONE text
This lets you change the built-in ignore-dialtone command (such
as ATX3) to whatever you choose, in case the built-in one does
not work, or another command works better.
Notes:
1. The ignore-dialtone command is not sent unless SET DIAL
IGNORE-DIALTONE is ON.
2. The ATX3 command generally disables not only NO DIALTONE, but also
BUSY. So this will prevent Kermit from detecting when the line is
busy. This is a property of the modem, not of Kermit.
_________________________________________________________________
2.1.7. Trimming the Dialing Dialog
The command:
SET MODEM COMMAND action [ command ]
is used to override Kermit's built-in modem commands for each action,
for each kind of modem in its internal database. If you include a
command, this is used instead of the built-in one. If you omit the
command, this restores the original built-in command.
If you want to omit the command altogether, so Kermit doesn't send the
command at all, or wait for a response, use:
SET MODEM COMMAND action {}
That is, specify a pair of empty braces as the command, for example:
SET MODEM COMMAND ERROR-CORRECTION ON {}
_________________________________________________________________
2.1.8. Controlling the Dialing Speed
The rate at which characters are sent to the modem during dialing is
normally controlled by the built-in modem database. You might want to
override this if Kermit seems to be dialing too slowly, or it is
sending characters to the modem faster than the modem handle them. A
new command was added for this in C-Kermit 7.0:
SET DIAL PACING number
Specifies the number of milliseconds (thousandths of seconds)
to pause between each character when sending commands to the
modem during DIAL or ANSWER command execution. 0 means no pause
at all, -1 (the default) or any other negative number means to
use the value from the database. Any number greater than 0 is
the number of milliseconds to pause.
HINT: You might also need to control the rate at which the modem
generates Touch Tones during dialing, for example when sending a
numeric page. There are two ways to do this. One way is to insert
pause characters into the dialing string. For modems that use the AT
command set, the pause character is comma (,) and causes a 2-second
pause. On most modems, you can use the S8 register to change the pause
interval caused by comma in the dialing string. The other way is to
set your modem's tone generation interval, if it has a command for
that. Most AT-command-set modems use S11 for this; the value is in
milliseconds. For example on USR modems:
ATS11=200
selects an interval of 200 milliseconds to separate each dialing tone.
Hint: To add S-Register settings or other commands to your dialing
procedure, use the new SET MODEM COMMAND PREDIAL-INIT command
([388]Section 2.2.2).
_________________________________________________________________
2.1.9. Pretesting Phone Number Conversions
The LOOKUP command now accepts telephone numbers as well as
directory-entry names, for example:
LOOKUP +1 (212) 7654321
When given a phone number, LOOKUP prints the result of converting the
phone number for dialing under the current dialing rules. For example,
if my country code is 1 and my area code is 212, and I am dialing out
from a PBX whose outside-line prefix is "93,":
C-Kermit> lookup +1 (212) 7654321
+1 (212) 7654321 => 93,7654321
C-Kermit>
You can also use the \fdialconvert(phone-number) function
([389]Section 2.1.11) to do this programmatically:
C-Kermit> echo "\fdialconvert(+1 (212) 7654321)"
"93,7654321"
C-Kermit>
So the new LOOKUP behaves as follows:
LOOKUP portable-format-phone-number
Displays how the number would actually be dialed Sets FAILURE
if there was a conversion error, otherwise SUCCESS.
LOOKUP literal-format-phone-number
Displays the same literal-format-phone-number Always sets
SUCCESS.
LOOKUP dialing-directory-name
Displays all matching entries and converts portable phone
numbers. Sets SUCCESS if at least one entry was found,
otherwise FAILURE.
LOOKUP =anything
Displays "=anything" and sets SUCCESS.
There is, at present, no programmatic way to fetch numbers from the
dialing directory. This will be considered for a future release.
_________________________________________________________________
2.1.10. Greater Control over Partial Dialing
The following rules now apply to partial dialing:
* Phone number transformations based on country and area code,
application of prefixes, etc, are performed only on the first
PDIAL.
* Each PDIAL argument is looked up in the dialing directory, so it
is possible have directory entries for pieces of phone numbers or
other information.
* Suffixes are not applied automatically, since there is no way for
C-Kermit to know in which PDIAL segment you want them to be
applied.
However, the suffix that *would* have been applied, based on the
dialing rules that were invoked when processing the first PDIAL
command, is stored in the variable:
\v(dialsuffix)
which you can include in any subsequent PDIAL or DIAL commands.
Example:
pdial {\m(my_long_distance_pager_number_part_1)}
pdial {\m(my_long_distance_pager_number_part_2)}
pdial {\v(dialsuffix)}
pdial {\m(my_long_distance_pager_number_part_3)}
pdial {@\m(numeric_pager_code)#}
_________________________________________________________________
2.1.11. New DIAL-related Variables and Functions
\fdialconvert(s)
s is a phone number in either literal or portable format (not a
dialing directory entry name). The function returns the dial
string that would actually be used by the DIAL command when
dialing from the current location, after processing country
code, area code, and other SET DIAL values, and should be the
same as the result of LOOKUP when given a telephone number.
\v(dialsuffix)
Contains the suffix, if any, that was applied in the most
recent DIAL command, or the suffix that would have been applied
in the most recent PDIAL command. Use this variable to send the
dial suffix at any desired point in a PDIAL sequence.
\v(dialtype)
A number indicating the type of call that was most recently
placed. Can be used after a normal DIAL command, or after the
first PDIAL command in a PDIAL sequence. Values are:
-2: Unknown because TAPI handled the phone number translation.
-1: Unknown because some kind of error occured.
0: Internal within PBX.
1: Toll-free.
2: Local within calling area.
3: Unknown (e.g. because a literal-format phone number was given).
4: Long distance within country.
5: International
\v(dialcount)
The current value of the DIAL retry counter, for use in a DIAL
macro ([390]Section 2.1.13).
\v(d$px)
PBX Exchange (see [391]Section 2.1.12).
Other dial-related variables, already documented in [392]Using
C-Kermit (or other sections of this document, e.g. [393]Section
2.1.1), include \v(dialnumber), \v(dialstatus), etc. A convenient way
to display all of them is:
show variable dial ; hint: abbreviate "sho var dial"
This shows the values of all the variables whose names start with
"dial". Also "show variable d$" (to show the \v(d$...) variables).
_________________________________________________________________
2.1.12. Increased Flexibility of PBX Dialing
Refer to [394]Using C-Kermit, 2nd Edition, pages 107-108. Recall that
three commands are needed to configure C-Kermit for dialing from a
PBX:
SET DIAL PBX-EXCHANGE number
SET DIAL PBX-INSIDE-PREFIX number
SET DIAL PBX-OUTSIDE-PREFIX number
Unfortunately, this model does not accommodate PBXs that have more
than one exchange. For example our PBX at Columbia University (which
must handle more than 10,000 phones) has 853-xxxx and 854-xxxx
exchanges.
Beginning in C-Kermit 7.0, the SET DIAL PBX-EXCHANGE command accepts a
list of exchanges, e.g.:
SET DIAL PBX-EXCHANGE 853 854
(multiple exchanges are separated by spaces, not commas).
So now when dialing a portable-format number that has the same country
and area codes as those of your dialing location, C-Kermit compares
the exchange of the dialed number with each number in the PBX Exchange
list (rather than with a single PBX Exchange number, as it did
formerly) to determine whether this is an internal PBX number or an
external call. If it is an external call, then the PBX Outside Prefix
is applied, and then the normal dialing rules for local or
long-distance calls.
If it is an inside call, the exchange is replaced by the PBX Inside
Prefix. But if the PBX has more than one exchange, a single fixed PBX
Inside Prefix is probably not sufficient. For example, at Columbia
University, we must dial 3-xxxx for an internal call to 853-xxxx, but
4-xxxx for a call to 854-xxxx. That is, the inside prefix is the final
digit of the exchange we are dialing. For this reason, C-Kermit 7.0
provides a method to determine the inside prefix dynamically at
dialing time, consisting of a new variable and new syntax for the SET
DIAL PBX-INSIDE-PREFIX command:
\v(d$px)
This variable contains the exchange that was matched when a PBX
internal call was detected. For example, if the PBX exchange
list is "853 854" and a call is placed to +1 (212) 854-9999,
\v(d$px) is set to 854.
SET DIAL PBX-INSIDE-PREFIX \fxxx(...)
If the PBX Inside Prefix is defined to be a function, its
evaluation is deferred until dialing time. Normally, this would
be a string function having \v(d$px) as an operand. Of course,
you can still specify a constant string, as before.
So given the following setup:
SET DIAL COUNTRY-CODE 1
SET DIAL AREA-CODE 212
SET DIAL PBX-OUTSIDE-PREFIX 93,
SET DIAL PBX-EXCHANGE 853 854
SET DIAL PBX-INSIDE-PREFIX \fright(\v(d$px),1)
The following numbers give the results indicated:
Number Result
+1 (212) 854-9876 4-9876
+1 (212) 853-1234 3-1234