| |
| [ [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 |
| |