From f2a22fc8c271bcbf60cbda5f07387c15ff09e0cf Mon Sep 17 00:00:00 2001 From: Ian Beckwith Date: Wed, 12 May 2010 01:38:49 +0100 Subject: [PATCH] fixed "specifed" spelling error --- .pc/060_speeling.patch/ckermit80.txt | 10349 +++++++++++++++++++++++++++++++++ ckermit80.txt | 2 +- ckuus2.c | 2 +- debian/patches/060_speeling.patch | 24 +- 4 files changed, 10374 insertions(+), 3 deletions(-) create mode 100644 .pc/060_speeling.patch/ckermit80.txt diff --git a/.pc/060_speeling.patch/ckermit80.txt b/.pc/060_speeling.patch/ckermit80.txt new file mode 100644 index 0000000..493338a --- /dev/null +++ b/.pc/060_speeling.patch/ckermit80.txt @@ -0,0 +1,10349 @@ + + C-Kermit 8.0 Update Notes + + [ [1]Contents ] [ [2]C-Kermit ] [ [3]Kermit Home ] + + Second Supplement to Using C-Kermit, Second Edition + +For C-Kermit 8.0 + + As of C-Kermit version: 8.0.211 + Date of C-Kermit release: 10 April 2003 + This file last updated: Sat Apr 10 16:36:11 2004 + + * IF YOU ARE READING A PLAIN-TEXT version of this document, note + that it is a plain-text dump of a Web page. You can visit the + original (and possibly more up-to-date) Web page here: + [4]http://www.columbia.edu/kermit/ckermit80.html + * If you are reading the HTML version of this file with a GUI Web + browser, the features added since C-Kermit 8.0.201 are shown in + red if your browser and monitor permit. Features that were new to + versions 8.0.200 and 201 are in black. + +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: [5]kermit-support@columbia.edu +Web: [6]http://www.columbia.edu/kermit/ +Or: [7]http://www.kermit-project.org/ +Or: [8]http://www.columbia.nyc.ny.us/kermit/ + _________________________________________________________________ + + NOTICES + + This document: + Copyright © 1997, 2002, Frank da Cruz and Christine M. Gianone. + All rights reserved. + + Kermit 95: + Copyright © 1995, 2002, Trustees of Columbia University in the + City of New York. All rights reserved. + + C-Kermit: + Copyright © 1985, 2002, + Trustees of Columbia University in the City of New York. All + rights reserved. See the C-Kermit [9]COPYING.TXT file or the + copyright text in the [10]ckcmai.c module for disclaimer and + permissions. + + When Kerberos(TM) and/or SRP(TM) (Secure Remote Password) and/or + SSL/TLS 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 + . + + For the full text of the third-party copyright notices, see + [11]Appendix V. + _________________________________________________________________ + + WHAT IS IN THIS FILE + + This file lists changes made to C-Kermit since version 7.0 was + released in January 2000. Use this file as a supplement to: + + * The second edition of [12]Using C-Kermit; and: + * The [13]C-Kermit 7.0 Update Notes. Also available in plain-text + form as [14]ckermit70.txt. + + until the third edition of Using C-Kermit is published. We apologize + for the scattered documentation and will consolidate it when we are + able. + _________________________________________________________________ + + ADDITIONAL FILES Several other files accompany this new Kermit + release: + + [15]ckututor.html + C-Kermit Tutorial (for Unix). Also distributed in Nroff form as + [16]ckuker.nr, the Unix C-Kermit manual page. + + [17]security.htm + Discussion of Kermit's new authentication and encryption + features, updated for C-Kermit 8.0. + + [18]telnet.htm + Detailed documentation of Kermit's Telnet client, updated for + C-Kermit 8.0. + + [19]ftpscripts.html + Tutorial: Writing FTP automation scripts + + [20]ckcbwr.html + Platform-independent C-Kermit hints and tips. Also distributed + in plain text form as [21]ckcbwr.txt + + [22]ckubwr.html + Unix-specific C-Kermit hints and tips. Also distributed in + plain text form as [23]ckubwr.txt. + + [24]ckvbwr.html + VMS-specific C-Kermit hints and tips. Also distributed in plain + text form as [25]ckvbwr.txt. + + [26]ckuins.html + Unix C-Kermit installation instructions. Also distributed in + plain text form as [27]ckuins.txt. + + [28]ckvins.html + VMS C-Kermit installation instructions. Also distributed in + plain text form as [29]ckvins.txt. + + [30]ckccfg.html + Compile-time configuration options. Also distributed in plain + text form as [31]ckccfg.txt. + + [32]ckcplm.html + C-Kermit Program Logic Manual. Also distributed in plain text + form as [33]ckcplm.txt. + + [34]iksd.html + Internet Kermit Service Aministrators Guide for Unix. + + [35]skermit.html + C-Kermit as an SSH Subsystem (SFTP server replacement). + + [ [36]Top ] [ [37]C-Kermit ] [ [38]Kermit Home ] + __________________________________________________________________________ + +CONTENTS + + [39]0. WHAT'S NEW + [40]1. FIXES SINCE VERSION 7.0.196 + [41]2. SSH AND HTTP + [42]2.1. SSH Connections + [43]2.2. HTTP Connections + [44]2.2.1. HTTP Command Switches + [45]2.2.2. HTTP Action Commands + [46]2.2.3. HTTP Headers + [47]2.2.4. Secure HTTP Connections + [48]2.2.5. HTTP Variables + [49]2.2.6. The HTTP Command-Line Personality + [50]3. THE BUILT-IN FTP CLIENT + [51]3.1. Making and Managing FTP Connections + [52]3.1.1. Kermit Command-Line Options for FTP + [53]3.1.2. The FTP Command-Line Personality + [54]3.1.3. The FTP URL Interpreter + [55]3.1.4. Interactive FTP Session Establishment + [56]3.2. Making Secure FTP Connections + [57]3.3. Setting FTP Preferences + [58]3.4. Managing Directories and Files + [59]3.5. Uploading Files With FTP + [60]3.5.1. FTP PUT Switches + [61]3.5.2. Update Mode + [62]3.5.3. Recovery + [63]3.6. Downloading Files With FTP + [64]3.6.1. FTP GET Switches + [65]3.6.2. Filename Collisions + [66]3.6.3. Recovery + [67]3.7. Translating Character Sets + [68]3.7.1. Character Sets and Uploading + [69]3.7.2. Character Sets and Downloading + [70]3.8. FTP Command Shortcuts + [71]3.9. Dual Sessions + [72]3.10. Automating FTP Sessions + [73]3.10.1. FTP-Specific Variables and Functions + [74]3.10.2. Examples + [75]3.10.3. Automating Secure FTP Connections + [76]3.11. Advanced FTP Protocol Features [77]4. FILE SCANNING + [78]5. FILE AND DIRECTORY NAMES CONTAINING SPACES + [79]6. OTHER COMMAND PARSING IMPROVEMENTS + [80]6.1. Grouping Macro Arguments + [81]6.2. Directory and File Name Completion + [82]6.3. Passing Arguments to Command Files + [83]6.4. More-Prompting + [84]6.5. Commas in Macro Definitions + [85]6.6. Arrow Keys + [86]7. NEW COMMANDS AND SWITCHES + [87]8. SCRIPTING IMPROVEMENTS + [88]8.1. Performance and Debugging + [89]8.2. Using Macros as Numeric Variables + [90]8.3. New IF Conditions + [91]8.4. The ON_UNKNOWN_COMMAND and ON_CD Macros + [92]8.5. The SHOW MACRO Command + [93]8.6. Arrays + [94]8.7. New or Improved Built-in Variables and Functions + [95]8.8. The RETURN and END Commands + [96]8.9. UNDEFINing Groups of Variables + [97]8.10. The INPUT and MINPUT Commands + [98]8.11. Learned Scripts + [99]8.12. Pattern Matching + [100]8.13. Dates and Times + [101]8.14. Trapping Keyboard Interruption + [102]9. S-EXPRESSIONS + [103]9.1. What is an S-Expression? + [104]9.2. Integer and Floating-Point-Arithmetic + [105]9.3. How to Use S-Expressions + [106]9.4. Summary of Built-in Constants and Operators + [107]9.5. Variables + [108]9.6. Assignments and Scope + [109]9.7. Conditional Expressions + [110]9.8. Extensibility + [111]9.9. Examples + [112]9.10. Differences from Algebraic Notation + [113]9.11.Differences from Lisp + [114]10. FILE TRANSFER + [115]11. MODEMS AND DIALING + [116]12. TERMINAL CONNECTION + [117]13. CHARACTER SETS + [118]14. DIALOUT FROM TELNET TERMINAL SERVERS + [119]15. COPING WITH BROKEN KERMIT PARTNERS + [120]16. NEW COMMAND-LINE OPTIONS + [121]17. LOGS + + [ [122]Top ] [ [123]C-Kermit ] [ [124]Kermit Home ] + __________________________________________________________________________ + +0. WHAT'S NEW + + The Initialization and Customization Files + C-Kermit 8.0 now supports specification of the initialization + file name (path) in an environment variable, CKERMIT_INI. It + also relies far less than before on the initialization for + functioning. See [125]Section 5 of the Unix C-Kermit + [126]installation instructions for details. As of version + 8.0.201, C-Kermit also executes your customization file (if you + have one) even if the initialization file was not found. + Previously, the customization file was executed by a TAKE + command in the initialization file (and it still is, if an + initialization is found). + + Incompatible Changes + As always, we do our best to avoid changes that break existing + scripts. However, C-Kermit 8.0 does include a rather pervasive + syntax change that might alter the behavior of scripts that + depend on the previous behavior. As described in [127]Section + 5, C-Kermit now accepts doublequotes in most contexts where you + previously had to use braces to group multiple words into a + single field, or to force inclusion of leading or trailing + blanks. Most noticeably, in C-Kermit 7.0 and earlier: + + echo {this is a string} + + would print: + + this is a string + + whereas: + + echo "this is a string" + + printed: + + "this is a string" + + In C-Kermit 8.0, both print: + + this is a string + + To force the doublequotes to be treated as part of the string, + use either of the following forms: + + echo {"this is a string"} + echo ""this is a string"" + + Similarly, to force braces to be treated as part of the string: + + echo "{this is a string}" + echo {{this is a string}} + + Other incompatibilities: + + 1. Using the SET HOST command to make HTTP connections is no + longer supported. Instead, use the new HTTP OPEN command, + described in [128]Section 2.2. + + C-Kermit 7.1 Alpha.01 (8 December 2000) + + Its major new features are those listed in the [129]Table of + Contents: the FTP client, file scanning, command parsing and + scripting improvements, S-Expressions, and support for the + Telnet Com Port Option, plus wider availability of the + Kerberos, SSL/TLS, and SRP security options for secure Internet + connections. + + C-Kermit 7.1.199 Alpha.02 (4 January 2001) + + + C-Kermit now accepts [130]FTP, TELNET, and IKSD URLs as its + first command-line argument. + + Character-set translation added to the FTP client for + [131]filenames. + + Optional [132]setting of date of incoming files by FTP [M]GET + from the server date. + + [133]FTP CHECK filename added to let FTP client check the + existence of a file on the server. + + [134]FTP GET /NAMELIST:filename added to get list of server + filenames into a local file. + + [135]FTP [M]PUT /SERVER-RENAME:template added to make server + rename a file as indicated by the template after it has + arrived completely. + + FTP [M]GET /SERVER-RENAME:template added to make server + rename a file as indicated by the template after it has been + sent completely. + + FTP [136]VDIRECTORY added for getting verbose directory + listings from TOPS-20. + + [137]FTP TYPE TENEX added for transferring 8-bit binary files + with PDP-10s. + + Added [138]automatic text/binary mode switching for FTP + [M]GET, based on filename patterns (e.g. *.zip, *.gz, *.exe + are binary; *.txt, *.c are text). + + [139]SET SEND I-PACKETS OFF added for coping with Kermit + servers that do not support I packets. + + A new option was added to [140]\fword() and \fsplit() for + parsing comma-separated lists that might contain empty + elements. + + Bug fixes including: + o {} or "" could not be used as expected to represent the + empty string. + o ,- on a line by itself in a macro definition caused + subsequent statements to be skipped. + o FTP [M]GET didn't work right if path segments were + included in the filespec. + o FTP MGET, if interrupted, did not clear its file list. + o Various problems with FTP PUT /AS-NAME that nobody + noticed. + o Some FTP messages and displays interfered with each + other. + o Parsing of YESTERDAY, TODAY, and TOMORROW in date-time + fields was broken. + o Automatic old-to-new dialing directory format conversion + was broken on VMS. + o Various source-code portability problems fixed. + + Improvement of various HELP and SHOW messages. + + C-Kermit 7.1.199 Alpha.04 (1 April 2001) + + + Big changes: + o Changed default modem type from NONE to GENERIC. + o Generic dialing now sends no init string at all. + o Changed default terminal bytesize from 7 to 8. + + New features: + o SET SESSION-LOG TIMESTAMPED-TEXT for timestamped session + log. + + New modem types: + o Conexant modem family + o Lucent VENUS chipset + o PCTel V.90 chipset + o Zoom V.90 + o Zoom V.92 + + FTP client: + o FTP OPEN /PASSIVE and /ACTIVE switches added. + o Now works with servers that that don't include path in + NLST response. + o Fixed SEND /RECURSIVE not to follow symlinks (UNIX). + o SET FTP VERBOSE-MODE default is now OFF instead of ON. + + Kermit protocol: + o Fixed what I hope is the last "Receive window full" + error. + o SET PREFIXING or SET CONTROL PREFIX now automatically + sets CLEARCHANNEL OFF. + o Fixed incorrect report of number of files transferred at + end of transfer. + o Fixed SEND /RECURSIVE not to follow symlinks (UNIX). + + UNIX: + o HTTP and shadow passwords enabled for SCO 5.0.6. + o Even with SET FILENAMES CONVERTED, spaces were still + accepted in incoming filenames; now they are converted + to underscores. + o Added support for compile-time mktemp()/mkstemp() + selection. + + VMS: + o Session-log format for scripted sessions fixed. + + Scripting: + o Fixed \frdir() not to follow symlinks (UNIX). + o Fixed \fday() not to dump core for dates prior to 17 Mar + 1858. + + General: + o "Closing blah..." message upon exit could not be + surpressed. + o Added /PAGE and /NOPAGE to DELETE switches. + o Added GO response for DELETE /ASK (delete all the rest + without asking). + o Added GO response to "more?" prompt (for multi-page + screen output). + o Updated HELP texts. + + C-Kermit 7.1.199 Beta.01 (10 May 2001) + + + FTP client verbosity adjustments. + + Bug with generic modem dialing pausing several secs fixed. + + SET HOST /USER:, SET LOGIN USERID, etc, fixed when given no + user ID. + + A couple \v(dm_blah) dial modifier variables added. + + "--version" command-line switch added. + + Fixed NetBSD serial-port DTR handling. + + Lots of syntax cleanups for Flexelint and gcc -Wall. + + Fixed modem-type aliases to not take precedence over real + names. + + Fixed funny treatment of doublequotes by ECHO command. + + Enabled SET SESSION-LOG for VMS and other non-UNIX platorms. + + Fixed changing direction in command history buffer. + + Fixed handling of IKSD URLs. + + Made sure DELETE prints a message if it got any errors. + + C-Kermit 8.0.200 Beta.02 (28 June 2001) + + + Major version number increased from 7 to 8. + + [141]SSH command. + + More-consistent Kermit protocol defaults. + + CONNECT idle timeout and action selection. + + CONNECT status variable. + + A way to allocate more space for filename lists. + + Pseudoterminal handler fixed for late-model Linuxes. + + Command-line option -dd for timestamped debug log. + + Download directory now works for external protocols too. + + GREP /COUNT:variable. + + SET ATTRIBUTE RECORD-FORMAT { OFF, ON }. + + Bug fixes. + + C-Kermit 8.0.200 Beta.03 (9 Sep 2001) + + + [142]HTTP 1.1 connections and scripting + + [143]ON_CTRLC macro for trapping Ctrl-C in scripts + + [144]Date-time parsing improvements, timezones, comparison, + arithmetic + + [145]Pattern-matching improvements + + FTP improvements + + SET EXIT HANGUP { ON, OFF } + + SET FILE EOF { CTRL-Z, LENGTH } + + ASK[Q] /TIMEOUT + + Bug fixes + + New platforms + + C-Kermit 8.0.200 Beta.04 (16 Nov 2001) + + + [146]New Unix man page + + [147]New Unix installation instructions + + SET TELOPT policies are now enforced on non-Telnet ports if + the server begins Telnet negotiations. + + SET TERMINAL IDLE-ACTION { TELNET-NOP, TELNET-AYT }. + + UUCP lockfile creation race condition fixed. + + Dialout, modem signals, hangup, hardware flow control, etc, + tested extensively on many platforms, numerous problems + fixed. + + Improved hints when dialing fails. + + SET STOP-BITS 2 can now be given without SET FLOW HARDWARE. + + Major improvements in RFC 2217 Telnet Com-Port Control. + + Improved ability to REDIAL a modem server port. + + kermit -h now shows the command name in the usage usage + string. + + kermit -h now shows ALL command-line options. + + kermit -s blah, where blah is a symlink, now works. + + --noperms command-line option = SET ATTRIBUTE PERMISSIONS + OFF. + + HTTP and HTTPS URLs now supported on the command line. + + An http command-line personality is now available. + + Initialization file streamlined to load faster, anachronisms + removed. + + Updated NEWS, INTRO, HELP text, SHOW commands. In particular, + see SHOW COMM, HELP SET LINE, HELP WAIT. + + Date/time arithmetic routines converted from floating-point + to integer arithmetic (internally) for greater accuracy and + portability. + + Quoted strings containing commas no longer break macro + execution. + + Dynamic Kermit file-transfer timeouts are now much more + aggressive. + + New "hot keys" to turn debug.log on/off during file transfer. + + Improved hints when file transfer fails. + + FTP CD orientation messages are now printed. + + -R now accepted on the FTP command line to request Recursion. + + -m allows Active or Passive mode to be chosen on the FTP + command line. + + -dd on the FTP command line creates a timestamped debug.log. + + FTP command-line security options filled in. + + Improved automatic text/binary mode switching for MGET. + + Removed spurious error messages that sometimes occur during + MGET. + + DIRECTORY, GREP, TYPE, HEAD, and TAIL now have a /OUTPUT:file + option. + + TYPE /NUMBER adds line numbers. + + CAT = TYPE /NOPAGE; MORE = TYPE /PAGE. + + GETOK ?-help fixed. + + \v(timestamp) (= "\v(ndate) \v(time)") + + \v(hour) (hour of the day, 0-23) + + \funix2dospath() converts a UNIX path (/) to a DOS one (\). + + \fdos2unixpath() converts a DOS (Windows, OS/2) path to a + UNIX one. + + \fkeywordval() parses name=value pair, allows macro keyword + parameters. + + We now make every attempt to not write passwords to the + debug.log. + + New Certficate Authority certificates file, includes the + Kermit Project at Columbia University so you can access our + IKSD securely. + + Secure targets improved and better documented in Unix + makefile. + + All Linux (libc and glibc) builds consolidated under "make + linux". + + HP-UX makefile targets now have consistent names. + + New aix50 and aix51 targets added. + + C-Kermit 8.0.200 Final (12 Dec 2001) + + + Remote/local-mode confusion on some platforms introduced in + Beta.04, fixed. + + Many of the makefile targets adjusted, new ones added. + + New "make install" target should please most people. + + New command: SHOW IKSD. + + FTP over TLS. + + Last-minute touchups to text messages, HELP text, etc. + + Enable modem-signal reading for SCO OSR5 and Unixware 7. + + Special superfast TRANSMIT /BINARY /NOECHO /NOWAIT mode + added. + + Fixed PBX dialing in unmarked-area-code case. + + Improved SHOW COMMUNICATIONS tells lockfile directory, + typical dialout device name. + + Some FTP OPEN command parsing problems fixed. + + Some errors in date arithmetic fixed. + + New command: SET TERMINAL AUTODOWNLOAD { ..., ERROR { STOP, + CONTINUE } } + + New command: HELP FIREWALL. + + SET MODEM HANGUP-METHOD DTR added as synomym for RS232-SIGNAL + + Support for secure URL protocols added: telnets:, ftps:, + https:. + + C-Kermit 8.0.201 (8 Feb 2002) + + + Installability as an [148]SSH v2 Subsystem. + + [149]SET LOCUS command. + + [150]L-versions of CD, DIR, DELETE, MKDIR, etc, to force + local execution. + + [151]USER and ACCOUNT added as synonyms for FTP USER and FTP + ACCOUNT. + + [152]SHOW VARIABLES now accepts a list of variables. + + Rudimentary support for [153]Caller ID when receiving phone + calls. + + Up/Down [154]Arrow-key navigation of command history buffer. + + [155]Automatic execution of customization file if init file + is missing. + + C-Kermit 8.0.206 Beta.01 (11 Oct 2002) + + New commands: + + o ORIENTATION lists location-related variables and their + values. + o KCD changes to special directories by their symbolic + names ("kcd ?" for a list). + o SET CD HOME path to specify home directory for CD and + KCD commands. + o CONTINUE given at top level is equivalent to END -- + handy when PROMPT'ed out of a script, to continue the + script. + + New switches or operands for existing commands: + + o GETOK /TIMEOUT + o ASK, ASKQ, GETOK /QUIET (suppresses error message on + timeout) + o COPY /APPEND now allows concatenating multiple source + files into one dest file. + o SET TCP { HTTP-PROXY, SOCKS-SERVER } /USER, /PASSWORD. + o DIRECTORY command now accepts multiple filespecs, e.g. + "dir a b c". + + SET QUIET ON now also applies to: + + o SET HOST connection progress messages. + o "Press the X or E key to cancel" file-transfer message. + o REMOTE CD response. + o REMOTE LOGIN response. + + Improvements and new features: + + o Numerous FTP client fixes and new features, listed + below. + o C-Kermit, when in remote mode at the end of a file + transfer, now prints a one-line "where" message. Control + with SET TRANSFER REPORT. + o Unix makefile "install" target now creates an UNINSTALL + script. + o Improved operation and performance on RFC 2217 Telnet + connections. + o Improved CONNECT (interactive terminal connection) + performance. + o HELP text updated for many commands. + + New or fixed makefile targets: + + o Solaris 9 (several variations) + o Concurrent PowerMAX + o Mac OS X 10.2 + o FreeBSD 1.0 + o FreeBSD 4.6, 5.0 + o AIX 5.2, 5.3 + + Bugs fixed (general): + + o Failure to run in VMS Batch fixed. + o LDIRECTORY fixed to run Kermit's built-in DIRECTORY + command rather than an external one. + o Fixed Solaris and other SVORPOSIX builds to find out + their full hostnames rather than just the "uname -n" + name. + o Fixed some problems matching strings that start with + ".". + o Fixed some problems matching pattern that contain + {a,b,c} lists. + o Fixed erroneous reporting of text-mode reception as + binary when sender did not report the file size + (cosmetic only). + o Many problems with SWITCH statements fixed. + o Fixed SET OPTIONS DIRECTORY /DOTFILES to work for server + too. + o Fixed DELETE to print an error message if the file was + not found. + o Fixed SET CONTROL UNPREFIX ALL and SET PREFIXING NONE to + do the same thing. + o Fixed bugs executing macros from within the ON_EXIT + macro. + o \fday() and \fnday() fixed for dates prior to 17 Nov + 1858. + o Serial speed-changing bug in Linux fixed. + o "Unbalanced braces" script parsing errors when using + \{number} fixed. + o "if defined \v(name)" fixed to behave as described in + the book. + o Fixed Problems caused by LOCAL variables whose names are + left substrings of macro names. + o The INPUT command was fixed to honor the PARITY setting. + o Fixed bug with COPY to existing file that is longer than + source file. + o REINPUT command failed to strip braces/quotes around its + target string. + o Network directory lookups didn't work for SSH + connections. + o REMOTE SET { FILE, TRANSFER } CHARACTER-SET fixed. + o Closed some holes whereby an incompletely received file + was not deleted when SET FILE INCOMPLETE is DISCARD, + e.g. when the Kermit is hung up upon. + o SET XFER CHARACTER-SET TRANSPARENT fixed to do the same + as SET XFER TRANSLATION OFF. + o SET HOST PTY (e.g. SSH) connection fixed to pass along + window-size changes. + o C-Kermit search path for TAKE files was accidentally + disabled. + + FTP client bugs fixed: + + o Character set translation was broken on little-endian + (e.g. PC) architectures. + o FTP PUT /SERVER-RENAME:, /RENAME-TO:, /MOVE-TO: switches + were sticky. + o Make SET TRANSFER MODE MANUAL apply to FTP. + o Make SET FILE INCOMPLETE { KEEP, DISCARD } apply to FTP. + o FTP MGET /UPDATE handled equal times incorrectly. + o FTP MGET /RECOVER fixed to ignore file dates, use only + size. + o FTP MGET /RECOVER sometimes downloaded files it didn't + need to. + o FTP downloads with TRANSFER DISPLAY BRIEF could give + misleading error messages. + o FTP MGET temp file not deleted if FTP DEBUG set to OFF + after it was ON. + o LOCUS not switched back when FTP connection is lost. + o Set incoming file date even if it was not completely + received. + o FTP MGET sent SIZE and MDTM commands even when it didn't + have to. + o FTP MGET sent SIZE and MDTM commands even when it knew + they wouldn't work. + o FTP MGET failed if no files were selected for download. + o FTP MGET a* b* c* would fail to get any c*'s if no b*'s + existed. + o Big problems canceling MGET with Ctrl-C. + o Some extraneous LOCUS dialogs squelched. + o Some inconsistencies in SET FTP FILENAMES AUTO fixed. + o Fixed file-descriptor pileup after multiple MGETs when + using mkstemp(). + o Fixed "mget foo", where foo is a directory name. + + FTP improvements: + + o New [156]FTP protocol features added (FEAT, MLSD). + o FTP MGET /RECURSIVE now works as expected if server + supports MLSD. + o FTP MGET /DATES-DIFFER to download if local and remote + file dates differ. + o FTP DATES default changed to ON. + o FTP MPUT, MGET /EXCEPT now allows up to 64 patterns (up + from 8). + o Top-level SITE and PASSIVE commands added for + convenience. + o MGET /COLLISION:APPEND /AS-NAME:newfile *.* puts all + remote files into one local file. + o SET FTP SERVER-TIME-OFFSET for when server has wrong + timezone set. + o Allow for alternative server interpretations of [M]MPUT + /UNIQUE. + o SET FTP ANONOMOUS-PASSWORD lets you specify the default + anonymous password. + o Allow "GET /RECURSIVE path/file" to force local + subdirectory creation. + o SET FTP DISPLAY is like SET TRANSFER DISPLAY but applies + only to FTP. + o FTP { ENABLE, DISABLE } new-protocol-feature-name. + o FTP MGET /NODOTFILES. + o Debug log now records FTP commands and responses in + grep-able format. + + [ [157]Top ] [ [158]Contents ] [ [159]C-Kermit ] [ [160]Kermit Home ] + __________________________________________________________________________ + +1. FIXES SINCE VERSION 7.0.196 First, the changes from 7.0.196 to 7.0.197... +Source and makefile tweaks to get successful builds on platforms that were not +available in time for the 7.0 release: + + * 4.2BSD + * 4.3BSD + * AIX 4.3 + * AT&T 3B2 and 3B20 + * BeOS 4.5 + * CLIX + * Interactive UNIX System V/386 R3.2 V4.1.1 + * OS-9/68000 + * OSF/1 1.3. + * PS/2 AIX 1.2.1 + * SCO OSR5.0.x + * SCO Xenix 2.3.4 + * SINIX 5.41/Intel + * Stratus FTX + * Stratus VOS + * SunOS 4.1 with X.25 + * Ultrix 4.2 + * Unixware 2.0 + + There were no functional changes from 196 to 197. + + Fixes applied after C-Kermit 7.0.197 was released: + + Source code: Big flexelint and "gcc -Wall" audit and cleanup. + + Configuration: + * Solaris RTS/CTS (hardware flow control) didn't work. + * BSDI RTS/CTS worked only in one direction. + * FreeBSD 4.0 with ncurses 5.0 broke interactive command parsing. + * QNX-32 build lacked -DBIGBUFOK so couldn't execute big macros. + + Connections: + * SET HOST /PTY didn't work on some platforms. + * Broken SET HOST /USER:xxx /PASSWORD:yyy /ACCOUNT:zzz switches + fixed. + * Transparent printing was broken in Unix. + * ANSWER 0 (wait forever) didn't work. + * Some problems in Multitech modem command strings. + * Spurious "?Sorry, can't condition console terminal" errors. + * Disabling modem command strings by setting them to nothing broke + dialing. + * SET DIAL TIMEOUT value was usually ignored. + * SET DIAL METHOD PULSE didn't work. + * Certain modem commands, if changed, not refreshed if modem type + changed. + * SET SESSION-LOG command was missing from VMS. + * VMS session log format fixed for scripts. + * HANGUP by dropping DTR didn't work in NetBSD. + * SET FLOW /AUTO versus SET FLOW confusion fixed. + * Spurious secondary Solaris lockfile removed. + * SCO OSR5 DTR On/Off hangup. + * UUCP lockfile race condition. + + Commands and scripts: + * Missing CAUTIOUS and FAST commands restored. + * Broken PTY command in late-model Linuxes fixed (API changed). + * Fixed off-by-one error in command recall when switching direction. + * Fixed recall of commands that contain '?'. + * COPY /SWAP-BYTES didn't work on some architectures. + * Various combinations of COPY switches didn't work. + * Various problems with COPY or RENAME with a directory name as + target. + * SHIFT didn't decrement \v(argc) if used within IF, ELSE, or SWITCH + block. + * SHIFT didn't affect the \%* variable. + * Divide by zero improperly handled in some \function()s. + * Problems with RETURN from right-recursive functions. + * FSEEK /LINE \%c LAST didn't work if already at end. + * Some buffer vulnerabilities and potential memory leaks were + discovered and fixed. + * \frdirectory() fixed not to follow symbolic links. + * SET EXIT WARNING OFF fixed to work when EXIT given in a script. + * Missing DELETE and MKDIR error message fixed. + * \fday() core dump for ancient dates fixed. + + File transfer: + * SEND /COMMAND was broken. + * CRECEIVE was broken (but RECEIVE /COMMAND was OK). + * Quoting wildcard chars in filenames didn't work. + * Problems canceling streaming file transfers with X or Z. + * Problems shifting between streaming and windowing file transfer. + * Non-FULL file-transfer displays erroneously said STREAMING when + not. + * An active SEND-LIST prevented GET from working. + * SET SERVER GET-PATH interpretation of relative names like "." was + wrong. + * The MAIL command was broken. + * "kermit -s *" might have skipped some files. + * Transaction log entries were not made for external protocol + transfers. + * File count report fixed to show number of files actually + transferred. + * Fixed filename conversion to convert spaces to underscores. + * Made SET PREFIXING / SET CONTROL PREFIX also adjust CLEARCHANNEL. + * More "Receive window full" errors fixed. + * Broken terminal buffering after curses display in Solaris fixed. + * SET FILE INCOMPLETE DISCARD did not work in all cases. + * Packet log changed to reformat the start-of-packet character + printably. + * Dynamic timeouts could grow ridiculously large. + + Character sets: + * Hebrew-7 translations missed the letter Tav. + * C1 area of CP1252 was ignored. + * SET TRANSFER CHARACTER-SET TRANSPARENT could give garbage + translations. + * TRANSLATE might not work on Little Endian architectures. + * Insufficient range checking in certain TRANSLATE operations. + + The following bugs in C-Kermit 8.0.200 were fixed in 8.0.201: + + * An obscure path through the code could cause the Unix version of + C-Kermit to dump core during its startup sequence. This happened + to only one person, but now it's fixed. + * When C-Kermit 8.0 is in Kermit server mode and the client says + "get blah", where blah (on the server) is a symlink rather than a + real file, the server unreasonably refused to send the linked-to + file. + * When C-Kermit is an FTP client and says "get foo/bar" (i.e. a + filename that includes one or more path segments), it failed to + accept the incoming file (this happened only with GET, not MGET). + * Array references should be case insensitive but only lowercase + array letters were accepted. + * SHOW VARIABLES dumped core on \v(sexpression) and \v(svalue). + * Spurious refusals of remote directory listings if the remote + server's date was set in the past. + * In AIX, and maybe elsewhere too, Kermit's COPY command always + failed with "Source and destination are the same file" when the + destination file didn't exist. + * The VMS version of C-Kermit did not work in Batch or when SPAWN'd. + To compound the problem, it also pretty much ignored the -B and -z + command-line options, whose purpose is to work around such + problems. + * C-Kermit 8.0 could not be built on IRIX 5.x. + * The C-Kermit 8.0 build for QNX6 said it was an "(unknown + version)". + + Other fixes are listed in the [161]previous section. + + [ [162]Top ] [ [163]Contents ] [ [164]C-Kermit ] [ [165]Kermit Home ] + __________________________________________________________________________ + +2. SSH AND HTTP + + 2.1. SSH Connections + + This section does not apply to [166]Kermit 95 2.0, which has its + own built-in SSH client, which is documented [167]SEPARATELY. + + On most UNIX platforms, C-Kermit can make SSH (Secure SHell) + connection by running the external SSH command or program through its + pseudoterminal interface. The command is: + + SSH text + Tells Kermit to start the external SSH client, passing the + given text to it on the command line. Normally the text is just + the hostname, but it can be anything else that is acceptable to + the ssh client. If the command succeeds, the connection is made + and Kermit automatically enters CONNECT (terminal) mode. You + can use the SSH command to make a connection to any host that + has an SSH server. + + Kermit's SSH command gives you all the features of Kermit on an SSH + connection: command language, file transfer, character-set + translation, scripting, and all the rest. By default, C-Kermit invokes + SSH with "-e none", which disables the ssh escape character and makes + the connection transparent for purposes of file transfer. You can, + however, change the SSH invocation to whatever else you might need (an + explicit path, additional command-line arguments, etc) with: + + SET SSH COMMAND text + Specifies the system command that Kermit's SSH command should + use to invoke the external SSH client. Use this command to + supply a specific path or alternative name, or to include + different or more command-line options. + + In most cases, these connections work quite well. They can be scripted + like any other connection, and file transfer goes as fast as, or + faster than, on a regular Telnet connection. In some cases, however, + the underlying pseudoterminal driver is a limiting factor, resulting + in slow or failed file transfers. Sometimes you can work around such + problems by reducing the Kermit packet length. Note that Kermit does + not consider SSH connections to be reliable, so it does not offer to + use streaming in Kermit protocol transfers (but you can force it with + SET RELIABLE or SET STREAMING if you wish). + + The SSH command is like the TELNET command: it enters CONNECT mode + automatically when the connection is made. Therefore, to script an SSH + connection, use: + + set host /pty ssh -e none [ other-options ] host + if fail ... + + to make the connection. + + Here's a sequence that can be used to make a connection to a given + host using Telnet if the host accepts it, otherwise SSH: + + if not defined \%1 exit 1 Usage: \%0 host + set quiet on + set host \%1 23 /telnet + if fail { + set host /pty ssh -l \m(user) -e none \%1 + if fail exit 1 \%1: Telnet and SSH both fail + echo SSH connection to \%1 successful + } else { + echo Telnet connection to \%1 successful + } + + In SSH v2, it is possible to make an SSH connection direct to a Kermit + server system if the host administrator has configured the SSH server + to allow this; [168]CLICK HERE for details. + + Since Kermit uses external ssh client software, and since there are + different ssh clients (and different releases of each one), the exact + command to be used to make an SSH/Kermit connection can vary. Here is + the command for the OpenSSH 3.0.2p1 client: + +set host /pipe ssh -e none [ -l username ] -T -s hostname kermit + + Example: + +set host /pipe ssh -e none -l olga -T -s hq.xyzcorp.com kermit + + The SSH client might or might not prompt you for a password or other + information before it makes the connection; this depends on your SSH + configuration (your public and private keys, your authorized hosts + file, etc). Here's a brief synopsis of the OpenSSH client command + syntax ("man ssh" for details): + + -e none + This tells the SSH client to use no escape character. Since we + will be transferring files across the connection, we don't want + the connection to suddenly block because some character in the + data. + + -l username + This is the username on the remote host. You can omit the -l + option and its argument if your local and remote usernames are + the same. If they are different, you must supply the remote + username. + + -T + This tells the SSH client to tell the SSH server not to + allocate a pseudoterminal. We are not making a terminal + connection, we don't need a terminal, and in fact if a terminal + were allocated on the remote end, the connection would not + work. + + -s ... kermit + This tells the SSH client to tell the SSH server to start the + specified subsystem ("kermit") once the connection is made. The + subsystem name comes after the hostname. + + hostname + The IP host name or address of the desired host. + + You might want to include other or additional ssh command-line + options; "man ssh" explains what they are. Here are some examples for + the OpenSSH 3.0.2p1 client: + + -oClearAllForwardings yes + -oForwardAgent no + -oForwardX11 no + -oFallbackToRsh no + These ensure that a secure connection is used and that the + connection used for file transfer is not also used for + forwarding other things that might be specified in the + ssh_config file. + + -oProtocol 2 + (i.e. SSH v2) Ensures that the negotiated protocol supports + subsystems. + + Once you have an SSH connection to a Kermit server, it's just like any + other connection to a Kermit server (and very similar to a connection + to an FTP server). You give the client file transfer and management + commands for the server, and the server executes them. Of course you + can also give the client any other commands you wish. + + [ [169]SSH Kermit Server Subsystem ] [ [170]Kermit 95 Built-in SSH + Client ] + _________________________________________________________________ + + 2.2. HTTP Connections + + Hypertext Transfer Protocol, or HTTP, is the application protocol of + the World Wide Web (WWW), used between Web browsers (clients) and Web + servers. It allows a client to get files from websites, upload files + to websites, delete files from websites, get information about website + directories and files, and interact with server-side CGI scripts. + C-Kermit includes an HTTP client capable of both clear-text and secure + HTTP connections, that can do all these tasks and can be automated + through the Kermit scripting language. + + Although C-Kermit 7.0 could make HTTP connections to Web servers, it + could do so only when no other connection was open, and the procedure + was somewhat awkward. C-Kermit 8.0 improves matters by: + + * Allowing an HTTP connection to be open at the same time as a + regular SET LINE or SET HOST connection, and also at the same time + as an FTP connection ([171]Section 3); + * Upgrading the HTTP protocol level from 1.0 to 1.1, thus allowing + for persistent connections, in which a series of commands can be + sent on the same connection, rather than only one as in HTTP 1.0 + (and C-Kermit 7.0); + * Providing for "one-shot" URL-driven HTTP operations such as GET or + PUT. + * Providing a distinct HTTP command-line personality. + + Persistent HTTP connections are managed with the following commands: + + HTTP [ switches ] OPEN [ security-options ] host-or-url [ port ] + Opens a persistent connection to the specified host (IP host + name or address) on the specified port. If any switches + (options, listed in the next section) are included, their + values are saved and used for all subsequent HTTP action + commands on the same connection. If no port is specified, HTTP + (80) is used. A Uniform Resource Locator (URL, [172]RFC 1738) + can be given instead of a hostname (or address) and port (but + the URL can not include a directory/file path). The security + options are explained [173]below. The HTTP OPEN command + replaces the C-Kermit 7.0 SET HOST hostname HTTP command, which + no longer works with HTTP GET and related commands. + + HTTP CLOSE + Closes any open HTTP connection and clears any saved switch + values. + + A URL starts with a protocol name, which must be http or https in this + case; optionally includes a username and password; and must contain a + host name or address: + + protocol://[user[.password]]@host[:port][URI] + + HTTP is Hypertext Transfer Protocol. HTTPS is the secure (SSL/TLS) + version of HTTP. The TCP service port is derived from the protocol + prefix (so normally the ":port" field is omitted). Thus the URL + protocol name specifies a default TCP service port and the URL user + and password fields can take the place of the /USER and /PASSWORD + switches ([174]Section 2.2.1). The optional URI is a "compact string + of characters for identifying an abstract or physical resource" + ([175]RFC 2396), such as a file. It must begin with a slash (/); if + the URI is omitted, "/" is supplied. Examples: + + http open http://www.columbia.edu/ + Equivalent to http open www.columbia.edu or http open + www.columbia.edu http. + + http open https://olga.secret@www1.xyzcorp.com/ + Equivalent to http /user:olga /pass:secret open + www1.xyzcorp.com https. + + Persistence is accomplished unilaterally by C-Kermit 8.0. An HTTP 1.0 + server closes the connection after each action. Although HTTP 1.1 + allows multiple actions on the same connection, an HTTP 1.1 server + tends to close the connection if it is idle for more than a few + seconds, to defend itself against denial-of-service attacks. But when + you use Kermit's HTTP OPEN command to create a connection, Kermit + reopens it automatically (if necessary) for each HTTP action until you + close it with HTTP CLOSE, regardless of the server's HTTP protocol + version, or how many times it closes the connection. + + Firewalls can be negotiated through proxies with the following + commands: + + SET TCP HTTP-PROXY [ host[:port] ] + If a host (by hostname or IP address) is specified, Kermit uses + it as a proxy server when attempting outgoing TCP connections + -- not only HTTP connections, but all TCP/IP connections, + Telnet and FTP included. This allows Kermit to adapt to the + HTTP firewall penetration method (as opposed to other methods + such as SOCKS4). If no hostname or ip-address is specified, any + previously specified Proxy server is removed. If no port number + is specified, the "http" service is used. This command must be + given before the HTTP OPEN command if a proxy is to be used or + canceled. + + HTTP [ switches ] CONNECT host[:port] + Instructs the HTTP server to act as a proxy, establishing a + connection to the specified host (IP hostname or address) on + the given port (80 = HTTP by default) and to redirect all data + transmitted between Kermit and itself to the given host for the + life of the connection. This command is to be used only for + debugging HTTP proxy connections. If a proxy connection is + required, instruct Kermit to use the proxy with the SET TCP + HTTP-PROXY command. + + 2.2.1. HTTP Command Switches + + HTTP switches, like all other switches, are optional. When HTTP + switches are included with the HTTP OPEN command, they apply + automatically to this and all subsequent HTTP actions (GET, PUT, ...) + on the same connection until an HTTP CLOSE command is given. So if you + include switches (or the equivalent URL fields, such as user and + password) in the HTTP OPEN command, you can omit them from subsequent + commands on the same connection. If the connection has closed since + your last command, it is automatically reopened with the same options. + + If you include switches with an HTTP action command (such as GET or + PUT), they apply only to that command. + + /USER:name + To be used in case a page requires a username for access. The + username is sent with page requests. If it is given with the + OPEN command it is saved until needed. If a username is + included in a URL, it overrides the username given in the + switch. CAUTION: Username and password (and all other + information, including credit card numbers and other material + that you might prefer to protect from public view) are sent + across the network in clear text on regular HTTP connections, + but authentication is performed securely on HTTPS connections. + + /PASSWORD:text + To be used in case a web page requires a password for access. + The password is sent with page requests. If it is given with + the OPEN command it is saved until needed. If a password is + given in a URL, it overrides the one given here. CAUTION: (same + as for /USER:). + + /AGENT:user-agent + Identifies the client to the server. Overrides the default + agent string, which is "C-Kermit" (for C-Kermit) or "Kermit-95" + (for Kermit 95). + + /ARRAY:array-designator + Tells Kermit to store the response headers in the given array, + one line per element. The array need not be declared in + advance. Example: /array:&a. + + /TOSCREEN + Tells Kermit to display any response text on the screen. It + applies independently of the output file specification; thus it + is possible to have the server response go to the screen, a + file, both, or neither. + + /HEADER:header-item(s) + Used for specifying any optional headers to be sent with HTTP + requests. + + /HEADER:tag:value + + To send more than one header, use braces for grouping: + + /HEADER:{{tag:value}{tag:value}...} + + For a list of valid tags and value formats see [176]RFC 2616, + "Hypertext Transfer Protocol -- HTTP/1.1". A maximum of eight + headers may be specified. + + 2.2.2. HTTP Action Commands + + HTTP actions can occur within a persistent connection, or they can be + self-contained ("connectionless"). A persistent HTTP connection begins + with an HTTP OPEN command, followed by zero or more HTTP action + commands, and is terminated with an HTTP CLOSE command: + + http open www.columbia.edu + if failure stop 1 HTTP OPEN failed: \v(http_message) + http get kermit/index.html + if failure stop 1 HTTP GET failed: \v(http_message) + (more actions possible here...) + http close + + A self-contained HTTP action occurs when a URL is given instead of a + remote file name to an HTTP action command. In this case, Kermit makes + the HTTP connection, takes the action, and then closes the connection. + If an HTTP connection was already open, it is closed silently and + automatically. + + http get http://www.columbia.edu/kermit/index.html + + Kermit's HTTP action commands are as follows. Switches may be included + with any of these to override switch (or default) values given in the + HTTP OPEN command. + + HTTP [ switches ] GET remote-filename [ local-filename ] + Retrieves the named file from the server specified in the most + recent HTTP OPEN command for which a corresponding HTTP CLOSE + command has not been given. The filename may not include + wildcards (HTTP protocol does not support them). If no HTTP + OPEN command is in effect, this form of the HTTP GET command + fails. The default local filename is the same as the remote + name, but with any pathname stripped. For example, the command + http get kermit/index.html stores the file in the current local + directory as index.html. If the /HEADERS: switch is included, + information about the file is also stored in the specified + array (explained in [177]Section 2.2.3). All files are + transferred in binary mode. HTTP does not provide for + record-format or character-set conversion. + + HTTP [ switches ] GET url [ local-filename ] + When HTTP GET is given a URL rather than a filename, Kermit + opens a connection to the designated server (closing any + previously open HTTP connection), gets the file, and then + closes the connection. If the URL does not include a filename, + index.html is supplied. This is the self-contained one-step + "connectionless" method for getting a file from a Web server. + The data is not interpreted; HTTP GET is like "lynx -source" + rather than "lynx -dump". + + In the remaining HTTP action commands, the distinction between a + remote filename and a URL are the same as in the HTTP GET command. + + HTTP [ switches ] HEAD remote-filename-or-url [ local-filename ] + Like GET except without actually getting the file; instead it + retrieves only the headers. If the /ARRAY: or /TOSCREEN switch + is included, there is no default local output filename but you + can still specify one. If neither of these switches is + included, the default local filename is the same as the remote + filename, but with any path stripped and with ".head" appended. + The HEAD command can be used in a script with the /ARRAY: + switch to retrieve information about the requested resource to + determine whether the resource should actually be retrieved + with a subsequent GET request. + + HTTP [ switches ] INDEX remote-directory-or-url [ local-filename ] + Asks the server to send a listing of the files in the given + server directory. This command is not supported by most Web + servers. Even when it is supported, there is no standard format + for the listing. + + HTTP [ switches ] POST [ /MIME-TYPE:type ] source-file + remote-path-or-url [ result-file ] + Sends data to a process running on the remote host; the result + is usually an HTML file but could be anything. The data to be + posted must be read from a local file (the source-file). If a + result file is specified, Kermit stores the server's response + in it. + + HTTP [ switches ] PUT [ MIME-TYPE:type ] local-file [ + remote-file-or-url [ result-file ] ] + Uploads a local file to the server. Only the name of a single + file can be given; wildcards (and group transfers) are not + supported by HTTP protocol. If no remote filename is given, the + file is sent with the same name as the local file, but with any + pathname stripped. + + HTTP [ switches ] DELETE remote-file-or-url [ local-result-file ] + Asks the server to delete the specified single file. If a + result file is specified, it will contain any response data + returned by the server. + + Note the limitations of HTTP protocol compared to (say) FTP or Kermit. + There is no command for changing directories, no standard way to get + file or directory lists, no way to transfer file groups by using + wildcard notation, etc, and therefore no good way to (say) fetch all + pages, descend through subdirectories, perform automatic updates, etc. + There is no assurrance a connection will stay open and, as noted, + there is no provision for data conversion between unlike platforms. + The data's MIME headers can be used for postprocessing. + + 2.2.3. HTTP Headers + + Each HTTP request and response contains a set of name/value pairs + called headers. HTTP headers are specified in [178]RFC 2616. For + example, an HTTP GET request for /index.html on www.columbia.edu + contains the following headers: + + GET /index.html HTTP/1.1 + Host: www.columbia.edu:80 + User-agent: C-Kermit 8.0 + Authorization: Basic base64-encoded-username-password + + These might be followed by any others specified with a /HEADERS: + switch: + + Accept: image/gif, image/x-xbitmap, image/jpeg, *.* + Accept-Encoding: gzip + Accept-Language: en + Accept-Charset: iso-8859-1,utf-8 + Cookie: cookie-data + + The server sends back a short report about the file prior to sending + the file contents. Example: + + HTTP/1.1 200 OK + Date: Fri, 24 Aug 2001 21:09:39 GMT + Server: Apache/1.3.4 (Unix) + Last-Modified: Mon, 06 Aug 2001 21:16:13 GMT + ETag: "1fa137-10d7-3b6f091d" + Accept-Ranges: bytes + Content-Length: 4311 + Content-Type: text/html + + If you want to have this information available to a Kermit script you + can use the /ARRAY switch to have Kermit put it in array, one line per + array element. Example: + + set exit warning off + http open www.columbia.edu + if fail exit 1 Can't reach server + http /array:&a get /index.html + if fail exit 1 Can't get file + echo Header lines: \fdim(&a) + for \%i 1 \fdim(&a) 1 { + echo \%i. \&a[\%i] + } + + Note that the "Date:" item is the current date and time; the + "Last-Modifed:" item is the file's modification date and time. An + example showing how to use this information is presented in + [179]Section 8.13.7. + + 2.2.4. Secure HTTP Connections + + SSL/TLS (Secure Sockets Layer / Transport Layer Security) is the + protocol used to secure HTTP, SMTP, and other Internet applications. + See the [180]C-Kermit Reference Section 5.4 for an introduction to + SSL/TLS. To make a secure HTTP connection, you need: + + 1. A secure client (a version of C-Kermit or Kermit 95 with SSL/TLS + security built in). Type "check ssl" at the Kermit prompt to make + sure you have it. + 2. A secure server to connect to. + 3. The CA Root Certificate used to authenticate the server to the + client. (see [181]Section 15 of the security reference for an + introduction to certificates). + + And you must make a connection to the secure HTTP port: service name + HTTPS, port number 443 (as opposed to service HTTP, port 80). You can + also make secure connections to other ports by including the /TLS or + /SSL switch with the HTTP OPEN command, if the host supports SSL/TLS + on the given port: + + The quality of the SSL/TLS connection depends on the cipher suite. + There are several possibilities: + + Anonymous cipher suite: + If an anonymous cipher suite is negotiated, the connection is + encrypted but there is no authentication. This connection is + subject to a Man-In-The-Middle (MITM) attack. + + X.509 certificate on the server: + When you connect to certain secure servers, an X.509 + certificate is returned. This certificate is issued to a + special hostname, something like www1.xyzcorp.com or + wwws.xyzcorp.com (rather than the normal www.xyzcorp.com). It + is signed by the host's Certificate Authority (CA). If the host + certificate is configured on the client, it can be used to + verify the certificate received from the server. If the + certificate it verified as authentic, a check is made to ensure + it has not expired and it was issued to the host you were + attempting to connect to. If you had asked to connect to (say) + www.xyzcorp.com but were given a certificate for + www1.xyzcorp.com, you would be prompted for permission to + continue. + + If the verification succeeded, the connection would be + encrypted with one-way (server-to-client) authentication. This + connection is not subject to a MITM attack. + + If a username and password are transmitted over this + connection, they are not subject to interception. However, the + standard risks associated with passing the password to the host + for verification apply; for example, if the host has been + compromised, the password will be compromised. + + X.509 client certificate: + If a connection has been established with an X.509 server + certificate, the server can ask the client to send a + certificate of its own. This certificate must be verified + against a CA Root certificate. The certificate itself (or + subject info from the certificate) is used to determine the + authorization for the client, and if successful, the username + and password need not be sent to the server. + + Kerberos 5: + Instead of using X.509 certifcates, Kerberos 5 can be used to + perform the authentication and key exchange. In this situation, + there is mutual authentication between the client and server. + The Kerberos 5 principal is used by the server to look up the + appropriate authorization data. There is no need to send + username and password. + + An HTTP connection is made with the HTTP OPEN command: + + HTTP [ switches ] OPEN [ { /SSL, /TLS } ] host [ port ] + If /SSL or /TLS switches are included (these are synonyms), or + if the service is HTTPS or the port is 443, a secure connection + is attempted using the current authentication settings; see + HELP SET AUTHENTICATION for details ([182]Section 6.2 of the + security reference). If the no /SSL or /TLS switch is included + but the port is 443 or the service is HTTPS, a secure + connection is attempted. If an /SSL or /TLS switch is included + but a port is not specified, an SSL/TLS connection is attempted + on the default port (80). + + Certificates are covered in the separate [183]Kermit Security + Reference for C-Kermit 8.0. You should let Kermit know to verify + certificates with the SET AUTHENTICATION TLS command. For example: + + SET AUTHENTICATION TLS CRL-DIR directory + Specifies a directory that contains certificate revocation + files where each file is named by the hash of the certificate + that has been revoked. + + SET AUTHENTICATION TLS CRL-FILE filename + Specifies a file that contains a list of certificate + revocations. + + SET AUTHENTICATION TLS VERIFY-DIR directory + Specifies a directory that contains root CA certificate files + used to verify the certificate chains presented by the peer. + Each file is named by a hash of the certificate. + + SET AUTHENTICATION TLS VERIFY-FILE filename + Specifies a file that contains root CA certificates to be used + for verifying certificate chains. + + SET AUTHENTICATION TLS VERIFY OFF + Tells Kermit not to require a certificate and accept any + certificate that is presented regardless of whether it is + valid. + + There are many other options; see the security document for details. + + Now suppose you need need to fetch the file denoted by the following + URL: + + https://myuserid:mypassword@wwws.xyzcorp.com/clients/info/secret.html + + Once you have set up the handling of certificates as desired, you can + use the following Kermit commands: + + http /user:myuserid /password:mypassword open www1.xyzcorp.com https + if success { + http get /clients/info/secret.html + http close + } + + As another example, let's say that you have a web form you need to + populate with three fields: red,white and blue. + +
+ + + +
+ + You can handle this with the HTTP POST command. The data to be posted + is stored in the local file data.txt. + + Red=seven stripes&White=six stripes&Blue=fifty stars + + and the response from the server will be stored into response.txt. + + http open www.xyzcorp.com http + if success { + http /array:c post data.txt /cgi-bin/form.cgi response.txt + http close + } + + In this scenario, the Common Gateway Interface (CGI) sends a response + whether it succeeds or fails in a script-dependent manner. The script + can either report success and enclose the response data; or it might + send a 302 Found error which indicates that the "Location:" header + should be used to determine the URL at which the data can be found. + + 2.2.5. HTTP Variables + + \v(http_code) + The HTTP protocol code number of the most recent server reply, + e.g. 404 for "not found". + + \v(http_connected) + 1 when an HTTP connection is open, 0 when there is no HTTP + connection. + + \v(http_host) + If an HTTP connection is open, the hostname:port, e.g. + www.columbia.edu:80; otherwise, empty. + + \v(http_message) + Server error message, if any, from most recent HTTP command. + + \v(http_security) + A list of the security parameters and values for the current + connection, if any. Empty if the connection is not to a secure + server, or there is no connection. + + To display all the HTTP variables at once, type SHOW VAR HTTP: + + C-Kermit> http open www.columbia.edu + C-Kermit> http get lkjlkjlkjlkj + C-Kermit> sho var http + \v(http_code) = 404 + \v(http_connected) = 1 + \v(http_host) = www.columbia.edu:80 + \v(http_message) = Not Found + \v(http_security) = NULL + C-Kermit> + + 2.2.6. The HTTP Command-Line Personality + + If you invoke C-Kermit with the name "http" or "https", you can use a + special set of HTTP-specific command-line options. You can do this by + creating a symbolic linke "http" or "https" to the C-Kermit 8.0 + executable, or by having a separate copy of it called "http" or + "https". Here's the usage message ("http -h"): + + Usage: ./http host [ options... ] + -h This message. + -d Debug to debug.log. + -S Stay (issue command prompt when done). + -Y Do not execute Kermit initialization file. + -q Quiet (suppress most messages). + -u name Username. + -P password Password. + -g pathname Get remote pathname. + -p pathname Put remote pathname. + -H pathname Head remote pathname. + -l pathname Local path for -g, -p, and -H. + -z opt[=value] Security options... + cert=file Client certificate file + certsok Accept all certificates + key=file Client private key file + secure Use SSL + verify=n 0 = none, 1 = peer , 2 = certificate required + + The "host" argument is the name of a Web host, e.g. www.columbia.edu. + The action options are -p, -g, and -H. If you give an action option, + Kermit does the action and then exits. If you give a host without an + action option, Kermit makes an HTTP connection to the host and then + gives you the C-Kermit prompt. Here's a simple example that fetches a + publicly readable Web page: + + http www.columbia.edu -g kermit/index.html + + If you need to access a website for which a username and password are + required, you can supply them on the command line with -u and -P. If + you include a username but omit the password, Kermit prompts you for + it: + + http www.columbia.edu -u olga -p kermit/index.html -l index.html + Password: + + Note that when PUT'ing files to websites, you have to supply both the + -p (remote pathname) and -l (local path) options. + + If your version of Kermit is built with SSL/TLS security, you can also + use the -z option to make secure HTTP (https) connections. + + Finally, as noted in [184]Section 16, you can also give a URL instead + of a host name and options. + + [ [185]Top ] [ [186]Contents ] [ [187]C-Kermit Home ] [ [188]Kermit + Home ] + __________________________________________________________________________ + +3. THE BUILT-IN FTP CLIENT + + 3.1. [189]Making and Managing FTP Connections + 3.2. [190]Making Secure FTP Connections + 3.3. [191]Setting FTP Preferences + 3.4. [192]Managing Directories and Files + 3.5. [193]Uploading Files With FTP + 3.6. [194]Downloading Files With FTP + 3.7. [195]Translating Character Sets + 3.8. [196]FTP Command Shortcuts + 3.9. [197]Dual Sessions + 3.10. [198]Automating FTP Sessions + 3.11. [199]Advanced FTP Protocol Features + + Earlier versions of C-Kermit and K95 included an FTP command, but it + simply invoked an external FTP client. Now, by popular demand, Kermit + includes its own built-in FTP client that offers the following + advantages over traditional FTP clients (and its previous interface to + them): + + * Any of Kermit's built-in [200]security methods can be used to + establish and conduct secure FTP sessions with [201]FTP servers + that support these methods. (Security modules can be subject to + export restrictions.) + * Kermit's FTP client uses "passive mode" by default to avoid + blockage by firewalls and network address translators. Of course + active mode can be chosen too when needed. + * [202]Character sets can be translated as part of the transfer + process even when the FTP server does not support character-set + translation, including to/from the new Internet standard + international character set, [203]Unicode UTF-8. This includes + both the file's name and (for text files only) its contents. + * All of C-Kermit's [204]file-selection mechanisms are available: + size, date, name patterns and lists, exception lists, etc. + * [205]Atomic file movement capabilities are provided (delete, move, + or rename files automatically after successful transfer). + * The correct file type, "ascii" (i.e. text) or binary, is chosen + automatically for each file (explained in [206]Section 4), and any + mixture of text and binary files can be sent in a single + operation, even across platforms. + * Update mode ("don't bother transferring files that didn't change + since last time") and recovery (resumption of an interrupted + transfer from the point of failure) are available in both + directions. + * When uploading files from UNIX to UNIX, the file's permissions can + be preserved if desired. + * Recursive directory-tree PUTs are supported between any two + platforms that have tree-structured file systems. Recursive GETs + are supported between like platforms if the server cooperates and + between like or unlike platforms if the server supports MLSD + ([207]Section 3.11). + * When receiving files, all of Kermit's file collision actions are + available: backup, update, refuse, rename, etc. + * Multi-file transfers can be interrupted on a per-file basis, + automatically skipping to the next file. + * FTP sessions are [208]fully scriptable. + * An entire FTP session (connect, login, CD, upload or download, + logout) can be specified on the command line without using a + script. + * All of Kermit's logging options and formats are available to keep + an accurate and complete record of each connection and file + transfer, and to aid in troubleshooting. + * All of Kermit's file-transfer display options are available + (fullscreen, brief, CRT, serial, none). + + And best of all: + * Kermit doesn't give you those annoying per-file prompts every time + you start a multi-file transfer without remembering to give a + "prompt" command first :-). + + [ [209]Top ] [ [210]FTP Top ] [ [211]FTP Client Overview ] [ [212]FTP + Script Tutorial ] [ [213]C-Kermit Home ] [ [214]Kermit Home ] + _________________________________________________________________ + + 3.1. Making and Managing FTP Connections + + Each copy of Kermit can have one FTP connection open at a time. FTP + connections are independent of regular terminal connections; a + terminal connection (serial or network via SET LINE, DIAL, SET HOST, + TELNET, etc) may be, but need not be, open at the same time as an FTP + connection, and terminal connections can also be closed, and new + connections opened, without interfering with the FTP connection (and + vice versa). Thus, for example, Kermit can have an FTP connection and + a TELNET connection open to the same host simultaneously, using the + TELNET connection (e.g.) to send mail or take other desired actions as + various FTP actions complete. Of course, each copy of Kermit can do + only one thing at a time, so it can't (for example) transfer a file + with FTP and another file with Kermit protocol simultaneously. + + A Kermit FTP session can be established by [215]command-line options, + by [216]URL, or by [217]interactive commands. + + 3.1.1. Kermit Command-Line Options for FTP + + The new command-line option '-9' (sorry, we're out of letters) can be + used when starting C-Kermit, telling it to make an FTP connection: + + kermit -9 hostname + + or if a non-default FTP port is needed: + + kermit -9 hostname:port + + You can also specify the username on the command line with the -M ("My + User ID") option that was already there for other connection types: + + kermit -9 hostname -M olga + + If you specify the username on the command line, Kermit uses it when + making the connection and does not prompt you for it (but it does + prompt you for the password if one is required). + + Once the connection is made, you get the regular Kermit prompt, and + can give interactive commands such as the ones described below. When + you give a BYE command, Kermit closes the session and exits, just as a + regular FTP client would do. If you don't want Kermit to exit when you + give a BYE command, include the -S ("Stay") option on the command + line. + + Other Kermit command-line options that are not specific to non-FTP + connections should affect the FTP session in the expected ways; for + example, -i and -T force binary and text mode transfers, respectively. + + File transfers can not be initiated on the "kermit -9" command line; + for that you need to use Kermit's FTP personality (next section) or + you can use URLs ([218]Section 3.1.3). + _________________________________________________________________ + + 3.1.2. The FTP Command-Line Personality + + If you want to replace your regular FTP client with C-Kermit, you can + make a link called "ftp" to the C-Kermit binary (or you can store a + copy of the C-Kermit binary under the name "ftp"). When C-Kermit is + invoked with a program name of "ftp" (or "FTP", case doesn't matter), + it assumes the command-line personality of the regular FTP client: + + ftp [ options ] hostname [ port ] + + In this case the options are like those of a regular FTP client: + + -d Debug: enables debug messages and creates a debug.log file. + -n No autologin: Kermit should not send your user ID automatically. + -t Packet trace: accepted but is treated the same as -d. + -v Verbose: accepted but ignored (operation is verbose by default). + -i Not interactive: accepted but ignored. + + and the hostname can also be a URL (explained in [219]Section 3.1.3). + To specify a non-default TCP port for the FTP server, include the port + number or name after the hostname. + + There are also some bonus options that allow you to execute an entire + FTP session from the shell command line, as long as you don't include + the -n option. These are not available with regular FTP clients, and + at least one of these options (-g) conflicts with UNIX ftp (where -g + means "no globbing", which does not apply to Kermit), and some of them + (like the options above) also conflict with regular Kermit + command-line options: + + -m mode = "passive" (default) or "active" + -Y Don't execute the Kermit initialization file [1] + -q Quiet, suppresses all but error messages [1] + -S Stay, don't exit automatically [1] + -A Autologin anonymously [2] + -u name Username for autologin [2] (synonym: -M [1]) + -P password Password for autologin (see cautions below) [2] + -D directory cd after autologin [2] + -b Binary mode [2] + -a Text ("ascii") mode [2] (synonym: -T [1]) + -R Recursive (works with -p) [4] + -p files Files to put (upload) after autologin [2] (synonym: -s [1]) + -g files Files to get (download) after autologin [3] + + [1] Same as Kermit, not available in regular FTP clients. + [2] Conflicts with Kermit, not available in regular FTP clients. + [3] Same as Kermit, conflicts with regular FTP clients. + [4] Conflicts with Kermit, available in some FTP clients. + + Fancier options such as restart, character-set translation, filename + collision selection, automatic move/rename/delete, etc, are not + available from the command line; for these you can use the commands + described in the following sections. The -R option might also work + with -g (GET) but that depends on the server. + + The following security options are also available, explained in + [220]Section 3.2: + + -k realm Kerberos 4 realm [4] + -f Kerberos 5 credentials forwarding [4] + -x autoencryption mode [4] + -c cipher SRP cipher type [4] + -H hash SRP encryption hash [4] + -z option Security options [4] + + If you include -A or specify a name of "anonymous" or "ftp", you are + logged in anonymously and, in the absence of -P, Kermit automatically + supplies a password of "user@host", where "user" is your local user + ID, and "host" is the hostname of the computer where Kermit is + running. If you do not include -p or -g, Kermit enters command mode so + you can type commands or execute them from a script. + + If you include -p or -g, Kermit attempts to transfer the specified + files and then exits automatically at the end of the transfer unless + you also included -S (Stay). It uses the "brief" file transfer display + (one line per file) unless you include the -q option to suppress it. + + When uploading files with -p, Kermit switches automatically between + text and binary mode for each file. + + When downloading, you can either specify a particular mode (text or + binary) to be used for all the files, or you can let Kermit select the + type for each file automatically, based on its name (see [221]Sections + 3.5 and [222]3.6 for greater detail). In UNIX be sure to quote any + wildcard characters to prevent the shell from expanding them, as shown + in the examples just below. Filename collisions are handled according + Kermit's FILE COLLISION setting (if specified in your Kermit + customization file; otherwise the default, which is BACKUP). + + It should go without saying that the -P option should be used with + caution. In addition to the well-known risks of transmitting plaintext + passwords over the Internet, in this case the password also echos to + the screen if you type it, and can be seen in ps and w listings that + show the user's currently active command and command-line arguments. + Thus command-line FTP sessions are most appropriate for secure or + anonymous connections (those that do not require passwords). + + Here's an example in which you download the latest C-Kermit "tarball" + from the Columbia University FTP archive: + + ftp -A kermit.columbia.edu -bg kermit/archives/ckermit.tar.gz + + This assumes that "ftp" is a symbolic link to C-Kermit. It logs you in + anonymously and gets the ckermit.tar.gz file in binary mode from the + kermit/archives directory. + + Here's a slightly more ambitious example that illustrates CD'ing to + the desired server directory to get a group of files in text mode (in + this case the C-Kermit source files): + + ftp -A kermit.columbia.edu -D kermit/f -ag "ck[cuw]*.[cwh]" makefile + + In this case we CD to the kermit/f directory so we don't have to + include it in each file specification, and we quote the ck[cuw]*.[cwh] + specification so the shell doesn't expand it, since we have to pass it + as-is to the server. Note also that the quotes don't go around the + entire file list; only around each file specification that needs to be + quoted. + + Here's one more example, that uploads a debug log file in binary mode + to the Kermit incoming directory (as we might ask you to do when + following up on a problem report): + + ftp -A kermit.columbia.edu -D kermit/incoming -bp debug.log + + In this case the -D option is required to tell the server where to put + the incoming file. + + Unless the -Y option is included, your Kermit initialization file + (.mykermrc in UNIX, K95.INI in Windows) is executed before the command + line options, so you can set any FTP-related preferences there, as + described in the subsequent sections. + _________________________________________________________________ + + 3.1.3. The FTP URL Interpreter + + If Kermit is invoked with either its regular personality (as "kermit") + or its FTP personality (as "ftp"), you can also give a URL + (Universal Resource Locator) instead of a hostname and options, + with or without a username and password: + ftp ftp://user:password@host/path + ftp ftp://user@host/path + ftp ftp://@host/path (or ftp://:@host/path) + ftp ftp://host/path + kermit ftp://host/path + + If the FTP personality is used, the service must be "ftp". In all + cases, a hostname or address must be included. If a user is included + but no password, you are prompted for the password. If a path + (filename) is included: + * If "@" is included without a user, Kermit prompts for the username + and password. + * If no user and no "@" are included, "anonymous" is used. + * GET is assumed. + + If no path (and no action options) are included, an interactive FTP + session is started, as in this example: + ftp ftp://kermit.columbia.edu + + If a path is included, but a username is not included, "anonymous" is + used and an appropriate user@host password is supplied automatically. + If authentication is successful, Kermit attempts to GET the file + indicated by the path or, if the path is the name of a directory, it + asks the server for a directory listing. In both cases, Kermit + disconnects from the server and exits after the operation is complete + (unless you have included the -S option on the command line). + + Here's an example that gets a listing of the Kermit directory at the + Kermit ftp site: + ftp ftp://kermit.columbia.edu/kermit/ + + This example gets the top-level READ.ME file from the same directory: + ftp ftp://kermit.columbia.edu/kermit/READ.ME + + Here's the same example, but requesting a text-mode transfer: + ftp -T ftp://kermit.columbia.edu/kermit/READ.ME + This illustrates that you can mix command-line options and URLs + if you desire. + + Here's an example that logs in as a (fictitious) real user to get a + file: + ftp ftp://olga@ftp.xyzcorp.com/resume.txt + The password is not included, so Kermit prompts for it. + + This scheme allows Kermit to be used as the FTP helper of other + applications, such as Web browsers, with all its advantages over other + FTP clients (especially the ones that are built in to most Web + browsers), e.g. that it can be given wildcards, and it can pick text + and binary mode automatically for each file. + + HINT: suppose somebody sends you an FTP URL in email, or you see it in + some text. If your terminal screen supports copy/paste, copy the url, + and then at the shell prompt type "kermit", a space, and then paste + the URL, e.g.: + + $ kermit ftp://alpha.greenie.net/pub/mgetty/source/1.1/mgetty1.1.27-O + + "$ is the shell prompt; the part you type is underlined, the rest is + pasted in. Kermit does the rest. + _________________________________________________________________ + + 3.1.4. Interactive FTP Session Establishment + + As you read this and the following sections, bear in mind that any + command that can be given at the prompt can also be used in a script + program. Kermit's script programming language is the same as its + interactive command language. [223]CLICK HERE if you would like to + learn a bit more about script writing. + + An FTP session is established with the FTP OPEN command: + + FTP [ OPEN ] [ { /SSL, /TLS } ] hostname [ switches ] [ port ] + Opens an FTP connection to the given host on the given port + and, if FTP AUTOLOGIN is ON, also logs you in to the server, + prompting for username and password if necessary. If no port is + specified, the regular FTP protocol port (21) is used. The OPEN + keyword is optional (unless the hostname conflicts with one of + the FTP command keywords, which you can list by typing "ftp + ?"). + + The hostname can be an IP host name, numeric IP address, or if you + have a network directory active (SET NETWORK DIRECTORY; see Chapter 6 + of [224]Using C-Kermit), an entry name in the directory. In the latter + case, if the given hostname matches exactly one entry, the associated + name or address is used; if it matches more than one, Kermit cycles + through them until one is found that can be opened; if it matches + none, then the hostname is used as-is. If a directory is active but + you want to bypass directory lookup, include an "=" sign at the + beginning of the hostname, and/or use a numeric IP address. + + When an FTP connection is opened, the default file-transfer mode is + set to binary if the client and server platforms are alike (e.g. both + of them are some kind of UNIX), and to text ("ascii") if they are not + alike. This has no particular effect for uploading since Kermit + automatically switches between text and binary mode for each file, but + might be important for downloading. The connection is also set to + Stream mode and File structure. Record- or page-oriented file + transfers are not supported by C-Kermit's FTP client. + + The optional FTP OPEN switches are: + + /ANONYMOUS + Logs you in anonymously, automatically supplying username + "anonymous" and user@host as the password, based on your local + user and host names. + + /NOLOGIN + + Overrides SET FTP AUTOLOGIN ON for this connection only. + + /USER:name + Uses the given username to log you in, thus avoiding the Name: + prompt. + Overrides SET FTP AUTOLOGIN OFF for this connection only. + + /PASSWORD:text + Uses the given text as your password, thus avoiding the + Password: prompt. This switch is not recommended for use in + script files, which would be a security risk. + + /ACCOUNT:text + Uses the given text as your account (or secondary password, + depending on the requirements of the server; most servers do + not require or accept an account name). If an account is not + supplied, you are not prompted for one. + + /PASSIVE + Opens the connection in passive mode. Passive mode is the + default in Kermit's FTP client, unlike in most others, since it + works better through firewalls. The /PASSIVE and /ACTIVE + switches apply only to the connection that is being opened, and + do not affect the global FTP PASSIVE-MODE setting. + + /ACTIVE + Opens the connection in active mode. Use this switch if the + server does not support passive mode, or use the command SET + FTP PASSIVE-MODE OFF. + + /NOINIT + Added in C-Kermit 8.0.201. Tells C-Kermit not to send REST, + STRU, FEAT, and MODE commands to the server when the connection + is opened, since these have been reported to cause confusion in + certain servers. + + When a username or password is missing, a prompt is issued at the + controlling terminal and you must type the response; the response can + not be scripted. Use the switches to avoid prompts, or one of the + secure authentication methods described in the next section, or see + [225]SET FTP AUTOLOGIN and the [226]FTP USER and similar commands + described later in this section. + + Examples: + + ftp open kermit.columbia.edu /anonymous ; Open and log in anonymously + ftp kermit.columbia.edu /anonymous ; The OPEN keyword can be omitted + ftp xyzcorp.com ; Open and maybe prompt for username + ftp xyzcorp.com /user:olga ; Open and log in as olga + ftp testing.abccorp.com 449 ; Specify a special TCP port number + ftp testing.abccorp.com /user:olaf /password:secret 449 + + The FTP OPEN command succeeds if a connection was opened to the server + (even if the given username and password were not valid) and fails + otherwise (see [227]Section 3.8 for details). + + When your FTP session is complete, you can terminate it as follows: + + FTP BYE + Closes the FTP connection if one was open. The FTP prefix can + be omitted if no other connection is open at the same time (see + [228]Section 3.8 for details). If a connection log is active, + an FTP record is written to it. If Kermit was started with the + -9 command-line option or with its FTP command-line + personality, and the -S (Stay) option was not given, AND there + is no other active connection, the FTP BYE command also exits, + just as it does on a regular FTP client. Synonyms: FTP CLOSE, + FTP QUIT (but if the FTP prefix is omitted from QUIT, this + becomes the regular Kermit QUIT command, which is equivalent to + EXIT; i.e. it closes the connection and exits from Kermit). + + The following commands can be used to achieve greater control over the + connection and login process: + + SET FTP ANONYMOUS-PASSWORD text + Allows you to choose the password text to be sent automatically + by Kermit when you open an FTP connection with the /ANONYMOUS + switch. + + SET FTP AUTOLOGIN { ON, OFF } + If you give this command prior to opening an FTP connection, it + controls whether Kermit tries to log you in automatically as + part of the connection process. Normally ON, which means the + username and password are sent automatically (and prompted for + if they are not yet known). When OFF, FTP OPEN connects to the + server without logging in. OFF is equivalent to the -n + command-line option when using Kermit's FTP command-line + personality. + + FTP USER name [ password [ account ] ] + Used to log in to an FTP server to which a connection has been + made without autologin, or when autologin failed. If the + password is furnished on the command line, it is used; + otherwise you are prompted for a password. An account may also + be furnished if required by the server; it is not required by + Kermit and is not prompted for if omitted. Synonyms: USER, FTP + LOGIN. + + FTP ACCOUNT text + Sends an account name to a server that supports accounts. If + the server does not support accounts, an error response occurs. + If the server does support accounts, the account is accepted if + it is valid and rejected if it is not. The account might be + used for charging purposes or it might be a secondary password, + or it might be used for any other purpose, such as an access + password for a particular disk. Servers that support accounts + might or might not allow or require the account to be sent + prior to login; usually it is sent after login, if at all. + Synonym: ACCOUNT. + + Example: + +set ftp autologin off ; One thing at a time please +ftp xyzcorp.com ; Try to make the connection +if fail exit 1 FTP connection failed ; Check that it was made +ftp user olga secret ; Now log in to the server +if fail exit 1 FTP login failed ; Check that it worked +ftp account 103896854 ; Login OK - send account +if fail echo WARNING - FTP ACCT failed ; Warn if problem +... ; (have session here) +bye ; Log out and disconnect + + The following commands are used to control or get information about + the FTP connection. Any particular FTP server does not necessarily + support all of them. + + FTP RESET + Terminates a user session but leaves the connection open, + allowing a new login via FTP USER. + + FTP IDLE [ number ] + Most FTP servers automatically log you out and and disconnect + your session if there has been no activity for a certain amount + of time. Use this command to ask the server to set its idle + limit to the given number of seconds. Omit the number to ask + the server to inform you of its current idle limit. + + FTP STATUS [ filename ] + Asks the FTP server to send information about the current + session. The result is a free-format report that might include + server identification, username and login time, FTP protocol + settings, and file-transfer statistics. If a filename is given, + the server is supposed to send detailed information about the + file. + + FTP SYSTEM + Asks the FTP server to identify its operating system (Listed in + Internet Assigned Numbers, Operating System Names). Examples: + UNIX, VMS, VM/CMS, WINDOWS-NT. Unfortunately many variations + are allowed (e.g. LINUX-2.0, LINUX-2.2, FREEBSD, ULTRIX, etc, + instead of UNIX; WINDOWS-NT-3, WINDOWS-NT-3.5, WINDOWS-NT-3.51, + WINDOWS-NT-4, etc). The report might also include other + information like "Type L8", "Type I", or "Type A", indicating + the file-transfer mode. + + FTP HELP [ keyword [ keyword [ ... ] ] + Asks the server to list the commands it supports. The response + is usually cryptic, listing FTP command mnemonics, not the + commands used by the client (since the server has no way of + knowing anything about the client's user interface). For + example, the PUT command is STOR in FTP protocol. If a keyword + is given, which should be an FTP protocol command, + slightly-more- detailed help is given about the corresponding + command (if the FTP server supports this feature). Examples: + "ftp help", "ftp help stor". + + FTP SITE text + (Advanced) Sends an FTP SITE (site-specific) command. Usually + this means that the FTP server is asked to run an external + command with the given arguments. You might be able to find out + what SITE commands are available by sending "ftp help site" to + the server, but in general the availability of and response to + SITE commands is (not surprisingly) site specific. + + FTP QUOTE text + (Advanced) Sends an FTP command in FTP protocol format. Use + this command to send commands to the server that the FTP client + might not know about. + + SHOW FTP + Lists client (Kermit) FTP settings and information. Also SHOW + CONNECTION, SHOW COMMUNICATIONS. + + HELP FTP [ keyword ] + Asks Kermit to list and describe its built-in FTP commands. + + HELP SET FTP [ keyword ] + Asks Kermit to list and describe its built-in SET FTP commands. + + [ [229]Top ] [ [230]FTP Top ] [ [231]C-Kermit Home ] [ [232]Kermit + Home ] + _________________________________________________________________ + + 3.2. Making Secure FTP Connections + + Also see: [233]Accessing IBM Information Exchange with Kermit. + + In the previous section, you can see several examples of traditional + insecure authentication: username and password sent across the network + in clear text. Of course this is bad practice on at least two counts: + (1) storing passwords in files (such as script files) gives access to + the target systems to anybody who can obtain read access to your + scripts; and (2) sending this information over the network leaves it + open to interception by network sniffers or compromised hosts. + + Because of the increasing need for security on the Internet, FTP + servers are beginning to appear that offer secure forms of + authentication, in which no information is sent over the network that + would allow anyone who intercepts it to usurp your identity and gain + your access rights. + + Kermit provides an equivalent form of FTP security for each type of + IETF standard security implemented in Telnet. These include + GSSAPI-KERBEROS5, KERBEROS4, Secure Remote Password (SRP), and + Transport Layer Security (SSL and TLS). It does not presently include + SSL tunneling nor any form of SSH v1 or v2. When Kermit is built with + the necessary libraries, secure FTP connections are attempted by + default, in which all connections are authenticated and the command + and data channels are private. + + The use of authentication and encryption for FTP connections can be + adjusted with the commands listed below, which are available only if + your version of Kermit was built with the corresponding security + options and libraries: + + SET FTP AUTHTYPE { AUTOMATIC, GSSAPI-KRB5, KERBEROS4, SRP, SSL, TLS } + Specifies an ordered list of authentication methods to be + attempted when AUTOAUTHENTICATION is ON. The default list is: + GSSAPI-KRB5, SRP, KERBEROS_V4, TLS, SSL. If none of the + selected methods are supported by the server, an insecure login + is used as a fallback. Note, by the way, that SSL or TLS can be + used to secure an anonymous connection. + + SET FTP AUTOAUTHENTICATION { ON, OFF } + Tells whether authentication should be negotiated by the FTP + OPEN command. Default is ON. Use SET FTP AUTOAUTHENTICATION OFF + to force a clear-text, unencrypted connection to FTP servers + (such as the one at the Kermit FTP site) that normally would + try to negotiate secure authentication and encryption. + + SET FTP AUTOENCRYPTION { ON, OFF } + Tells whether encryption (privacy) should be negotiated by the + FTP OPEN command, which can happen only if secure + authentication is also negotiated. Default is ON. + + SET FTP AUTOLOGIN { ON, OFF } + Tells Kermit whether to try logging in automatically when you + make an FTP connection, as opposed to letting you do it "by + hand" with the FTP USER command. + + SET FTP COMMAND-PROTECTION-LEVEL { CLEAR, CONFIDENTIAL, PRIVATE, SAFE + } + Determines the level of protection applied to the command + channel: + + CLEAR Data is sent in plaintext and not protected against tampering. + CONFIDENTIAL Data is encrypted but not protected against tampering. + PRIVATE Data is encrypted and is protected against tampering. + SAFE Data is sent in plaintext but protected against tampering. + + The default is PRIVATE. + + SET FTP CREDENTIAL-FORWARDING { ON, OFF } + Tells whether end-user credentials are to be forwarded to the + server if supported by the authentication method (GSSAPI-KRB5 + only). This is often required to allow access to distributed + file systems (e.g. AFS.) + + SET FTP DATA-PROTECTION-LEVEL { CLEAR, CONFIDENTIAL, PRIVATE, SAFE } + Tells what level of protection is applied to subsequent data + channels. The meanings of the protection-level keywords are the + same as for SET FTP COMMAND-PROTECTION-LEVEL. The default is + PRIVATE. + + SET FTP SRP CIPHER name + Specifies the cipher to be used for encryption when SRP + authentication is in use. The list of possible choices is + computed based on the capabilities of the local SRP library and + includes NONE plus zero or more of the following: + + BLOWFISH_ECB CAST5_ECB DES_ECB DES3_ECB + BLOWFISH_CBC CAST5_CBC DES_CBC DES3_CBC + BLOWFISH_CFB64 CAST5_CFB64 DES_CFB64 DES3_CFB64 + BLOWFISH_OFB64 CAST5_OFB64 DES_OFB64 DES3_OFB64 + + The default is DES3_ECB. + + SET FTP SRP HASH name + Specifies the hash to be used for data protection when SRP + authentication is in use. The choices are MD5 and SHA. The + default is SHA. + + Command-line options: + + -k name + Specifies the realm to be used with Kerberos 4 authentication + (= SET AUTH K4 REALM name). + + -f + Enables forwarding of Kerberos 5 credentials to the host when + using GSSAPI authentication (= SET AUTH K5 FORWARDABLE ON). + + -x + Enables autoencryption (= SET FTP AUTOENCRYPTION ON). + + -c cipher + Specifies the kind of cipher to be used for encryption with SRP + authentication. Equivalent to SET FTP SRP CIPHER, with the same + choices. If this option is not given, CAST5_CBC is used. + + -H hash + Specifies the hash to be used for encryption with SRP + authentication. Equivalent to SET FTP SRP HASH, with the same + choices. If this option is not given, SHA is used. + + -z debug + Turns on SSL/TLS debugging. + + -z secure + Requires secure connection. + + -z certsok + Says to accept all certificates without checking validity. + + -z verify=n + Sets certificate verification mode to the given number, n: + 0 = no verification + 1 = verify certificate if presented + 2 = require verification of certificate + + -z cert=filename + Specifies a file containing a client certificate to be + presented to the FTP server. + + -z key=filename + Specifies a file containing a private key matching the client + certificate. + + -z !krb4 + (nokrb4) Disables the use of Kerberos 4. + + -z !gss + -z nogss + Disables the use of GSSAPI - Kerberos 5. + + -z !srp + -z nosrp + Disables use of SRP. + + -z !ssl + -z nossl + Disables the use of SSL. + + -z !tls + -z notls + Disables the use of TLS. + + Caution: If your FTP connection is secured via AUTH TLS, it is not + possible to interrupt a file transfer. This is a limitation of all + known FTP servers that support AUTH TLS. + + Note that when using certain security methods, such as SSL or TLS, you + may be prompted to confirm or verify certain actions or conditions, + for example, whether to accept self-signed certificates. This can + interfere with unattended operation of scripts; see [234]Section 3.10. + + [ [235]Top ] [ [236]FTP Top ] [ [237]C-Kermit Home ] [ [238]Kermit + Home ] + _________________________________________________________________ + + 3.3. Setting FTP Preferences FTP preferences can be set globally and + persistently with the commands in the following sections; many of + these can also be overridden on a per-command basis with switches that + have the same name. + + 3.3.1. Logs, Messages, and Other Feedback + + You can control the amount of feedback received from your FTP session + with the commands in this section. First, you can create a log of your + FTP transfers with the following commands: + + SET TRANSACTION-LOG { VERBOSE, FTP, BRIEF } + Selects the log format. VERBOSE is the default, and is + described in [239]the manual. FTP chooses a WU-FTPD format, the + same as is used by the popular FTP server. BRIEF creates + per-file records in comma-separated-list format. For greater + detail, see [240]Section 4.17 of the [241]C-Kermit 7.0 Update + Notes. + + LOG TRANSACTIONS filename + Records FTP (or Kermit, or any other protocol) uploads and + downloads in the given file using the format selected by the + most recent SET TRANSACTION-LOG command, if any, or else the + default format. + + FTP screen messages and displays are controlled by the following + commands: + + SET TRANSFER DISPLAY { FULLSCREEN, CRT, SERIAL, BRIEF, NONE, OFF } + FTP transfers use Kermit's normal file-transfer display styles. + Use this command to choose the desired format; the default on + most platforms is FULLSCREEN. The display is automatically + disabled if Kermit is running in the background or in batch. + BRIEF is always used for command-line initiated transfers + (unless suppressed by -q). While a file-transfer is in + progress, you can interrupt it in the normal Kermit way by + typing one of the following keys or key combinations: + X - Cancel current file but go on to the next one (if any). + Z - Cancel the entire transfer. Ctrl-L or Ctrl-W - Refresh + the file-transfer display (if any). + + SET FTP DISPLAY { FULLSCREEN, CRT, SERIAL, BRIEF, NONE, OFF } + Like SET TRANSFER DISPLAY, but applies only to FTP connections, + and does not affect Kermit- or other protocol file transfers. + + SET QUIET { ON, OFF } + This command applies to Kermit in general, not just FTP. OFF by + default; when ON, it surpresses most messages from most + commands as well as the file-transfer display. + + SET FTP PROGRESS-MESSAGES { ON, OFF } + Tells whether Kermit should print locally-generated feedback + messages for each non-file-transfer command. ON by default. + + SET FTP VERBOSE-MODE { ON, OFF } + Tells whether to display all responses from the FTP server. OFF + by default. This shows all responses to all commands, except + when the file-transfer display is active, and unless you have + SET QUIET ON. When OFF, responses are shown only for commands + such as FTP PWD whose purpose is to display a response. + + SET FTP DEBUG { ON, OFF } + Tells whether local client debugging information should be + displayed. OFF by default. When ON, the commands that are sent + to the server are shown, as well as its responses (even if + VERBOSE-MODE is OFF), plus additional informational messages + are printed regarding the progress of secure operations. Also, + the temporary file created by the [242]MGET command is not + deleted so you can see what's in it. + + Set all of these to OFF when silent running is desired. + + 3.3.2. Operational Preferences + + FTP DISABLE new-protocol-feature-name + FTP ENABLE new-protocol-feature-name + Explained in [243]Section 3.11. + + SET FTP AUTOLOGIN { ON, OFF } + If you give this command prior to opening an FTP connection, it + controls whether Kermit tries to log you in automatically as + part of the connection process. Normally ON, which means the + username and password are sent automatically (and prompted for + if they are not yet known). When OFF, FTP OPEN connects to the + server without logging in. OFF is equivalent to the -n + command-line option when using Kermit's FTP command-line + personality. See [244]Section 3.1.4 for usage. + + SET FTP PASSIVE-MODE { ON, OFF } + ON by default, to avoid random TCP port assignment for data + connections, which can prevent FTP protocol from working + through firewalls and network address translators (for more on + these topics, see the [245]Kermit security reference. Set to + OFF in case the FTP server does not support passive mode, or in + case the client has problems with it (it has been observed, for + example, that when using passive mode, the SCO XENIX 2.3.4 + TCP/IP stack hangs in the connect() call forever). Synonyms: + PASSIVE [ ON ], PASSIVE OFF, PASV [ ON ], PASV OFF. + + SET FTP SEND-PORT-COMMANDS { ON, OFF } + This command determines whether the FTP client sends a new PORT + command to the server when accepting incoming data connections + (as when not using passive mode.) When PASSIVE-MODE is OFF and + SET SEND-PORT is OFF, the port that was originally specified is + reused. This is the default behavior for normal FTP clients but + it is not compatible with many firewalls. + + SET FTP CHARACTER-SET-TRANSLATION { ON, OFF } + Whether to translate character sets when transferring files + with FTP (explained in [246]Section 3.7). OFF by default. + + SET FTP SERVER-CHARACTER-SET name + Tells Kermit the character set used by the FTP server, UTF-8 by + default ([247]Section 3.7). + + SET FTP SERVER-TIME-OFFSET delta-time + Tells Kermit to apply the given [248]delta time to file + timestamps provided by the server for its files; for use when + (for example) the server does not have its timezone set + correctly. + + SET FTP ERROR-ACTION { PROCEED, QUIT } + When transferring a group of files with FTP, and an error + occurs with one of the files, Kermit normally goes on the next + file. Use SET FTP ERROR-ACTION to QUIT to make Kermit stop the + transfer immediately and fail if an error occurs with any + single file in the group. Example: you have given Kermit a list + of files to send, and one of the files can not be found, or + read permission is denied. Note that cancelling a file by + typing 'X' during transfer is not considered an error (if you + want to cancel the entire transfer, type 'Z' or Ctrl-C). + + SET FTP PERMISSIONS { AUTO, ON, OFF } + When uploading files with PUT or MPUT, this tells whether + Kermit should send each file's permissions. The default is OFF, + which means not to send permissions, in which case the uploaded + file's permissions are set by the FTP server according to its + own criteria. ON means to send them, AUTO means to send them + only if the client (Kermit) and server are on like platforms + (e.g. both UNIX). This command has no effect when downloading, + since the FTP protocol does not include a way for the server to + inform the client of a file's permissions. Also see [249]FTP + PUT /PERMISSIONS. Note that setting permissions after uploading + is likely to work (correctly or at all) only when the client + and server platforms are alike (e.g. both of them are some form + of UNIX). Also note that Windows files don't have permissions. + Also see [250]FTP CHMOD. + + SET FTP DATES { ON, OFF } + When downloading files with GET or MGET, this tells whether + Kermit should try to set the received file's date from the + server's date. FTP DATES is ON by default. Note, however, that + FTP protocol does not allow date preservation when uploading. + So at best, SET FTP DATES ON can work only when downloading, + and then only when the server agrees to furnish file dates. + + SET FTP FILENAMES { AUTO, CONVERTED, LITERAL } + When uploading (sending) files, this tells whether to convert + outbound filenames to "common form". This means allowing only + one period in a name, uppercasing any lowercase letters, + replacing spaces by underscores, etc. AUTOMATIC is the default, + meaning LITERAL when client and server are the same type of + system (e.g. UNIX) and CONVERTED otherwise. Special case: if + the setting is AUTOMATIC and the client is not UNIX and the + server identifies itself as UNIX, Kermit uses a less-strict + form of conversion, in which lowercase letters are not + uppercased and the filename can contain any number of periods, + but spaces are still converted to underscore. When receiving, + conversion generally means to change all-uppercase names to + lowercase and spaces to underscore. + + SET FTP UNIQUE-SERVER-NAMES { ON, OFF } + Applies only to uploads. Tells the server to create new, unique + names for incoming files that have the same names as existing + files. OFF by default, in which case the server overwrites + existing files with new files of the same name. When ON, the + server uses its own built-in method for creating new names for + incoming files; for example, appending a period (.) and a + number to the name. CAUTION: Use this option only if you do not + need to refer to the file after it is uploaded, since FTP + protocol provides no mechanism for the client to find out what + name was assigned by the server. + + SET FTP COLLISION { ... } + When downloading, what to do if an incoming file has the same + name as an existing file. Options are the same as for SET FILE + COLLISION. If this command is not given, Kermit's regular FILE + COLLISION setting is used. If this command is given, it + overrides the FILE COLLISION setting for FTP transfers only. + See [251]Section 3.6.2 for details. + + SET FTP TYPE { TEXT, BINARY, TENEX } + Changes the default transfer mode. When sending (uploading) + files, this command has no effect unless you disable automatic + text/binary mode switching ([252]Section 4) with SET FILE SCAN + OFF or SET TRANSFER MODE MANUAL. When receiving (downloading) + files, this command establishes the transfer mode to be used + when a filename does not match any of Kermit's text or binary + filename patterns, unless you use SET FTP + GET-FILETYPE-SWITCHING or SET TRANSFER MODE MANUAL to disable + automatic switching, in which case, this command establishes + the transfer mode for all downloaded files. In all cases, + however, the FTP TYPE can be overridden in any GET or PUT + command by including a /TEXT (/ASCII), /BINARY, or /TENEX + switch. The FTP TYPE is independent of the Kermit FILE TYPE + setting. TENEX is used for sending 8-bit binary files to 36-bit + platforms such as TOPS-10, TOPS-20, and TENEX, and getting them + back again. Synonym: ASCII = TEXT. Note: there is also an FTP + TYPE command, which does what SET FTP TYPE does but also sends + a TYPE command to the server immediately if the given type is + different from the current one. + + If you want want specific FTP preference settings to be in effect for + all your Kermit FTP sessions, put the desired SET FTP commands in your + Kermit customization file (~/.mykermrc in UNIX, K95CUSTOM.INI in + Windows). + + [ [253]Top ] [ [254]FTP Top ] [ [255]C-Kermit Home ] [ [256]Kermit + Home ] + _________________________________________________________________ + + 3.4. Managing Directories and Files + + In Kermit, commands for directory and file management can refer to: + + * The local computer + * A remote computer when you have a connection to a Kermit server or + IKSD. + * A remote computer when you have a connection to an FTP server. + + (There can also be an HTTP connection, but the commands in this + section don't apply to HTTP connections.) + + Thus in general, each such command comes in three forms: + + 1. With no prefix in C-Kermit 8.0.200, it refers to the local + computer (CD, DIR, etc). In C-Kermit 8.0.201 and later, however, + the "locus" switches to automatically to the remote FTP server + when you make an FTP connection (see the SET LOCUS description + [257]Section 7); thus C-Kermit 8.0.201 acts almost exactly like a + regular FTP client when it has an FTP connection, yet still acts + like itself on other kinds of connections. + 2. With the REMOTE prefix, it is for a Kermit server (REMOTE CD, + REMOTE DIR). + 3. With the FTP prefix, it's for an FTP server (FTP CD, FTP DIR). + 4. Also see [258]Section 3.8, which explains "R-commands" and + "L-commands". + + Kermit's FTP file and directory management commands are as follows. + When an R-command is included in the Synonyms list, be sure to read + [259]Section 3.8 about rules for use of R-commands. + + FTP CD [ directory ] + Tells the FTP server to change its default (working) directory + to the one given, which usually must be expressed in the syntax + of the server platform (UNIX, VMS, etc). If the directory is + not specified, the result depends on the FTP server -- it might + complain that the command is illegal, or it might change to + your original login directory. Synonyms: FTP CWD (Change + Wording Directory); RCD. + + FTP CDUP + Tells the FTP server to change its default (working) directory + to the parent directory of its current one (equivalent to + "cd .." in UNIX, or "cd [-]" in VMS). Synonyms: RCDUP, FTP UP. + + FTP PWD + Asks the FTP server to report ("print") its current working + directory. Synonym: RPWD. + + FTP MKDIR directory + Asks the FTP server to create the directory whose name is + given. In general, the name must be in the syntax of the + server's file system, and it must be either absolute (a full + pathname) or relative to the server's current (working) + directory. This command fails if the directory can't be created + for any reason, including that it exists already. Synonym: + RMKDIR. + + FTP RMDIR directory + Asks the FTP server to remove the directory whose name is + given. The rules are the same as for MKDIR, plus in most cases, + the server will not remove any directory unless it is empty. + Synonym: RRMDIR. + + FTP DIRECTORY [ filespec ] [ redirectors ] + Tells the FTP server to send a directory listing of the + specified files. If no filespec is given, the server lists all + files in its current working directory. The results are in + whatever format the server chooses to send them. You can use + UNIX-like redirectors to send the listing to a file or a + pipeline, exactly as with the regular Kermit client/server + REMOTE DIRECTORY command ([260]Using C-Kermit, Chapter 11). + Synonym: RDIRECTORY. Examples: + + ftp dir ; Show listing of all files on screen + ftp dir *.txt ; List *.txt files on screen + ftp dir *.txt > somefile ; Put listing in somefile + ftp dir *.txt >> somefile ; Append listing to somefile + ftp dir *.txt | sort > somefile ; Put sorted listing in somefile + ftp dir | more ; Runs list through "more" + ftp dir | sort | more ; Runs list through "sort" and "more" + + FTP VDIRECTORY [ filespec ] [ redirectors ] + "Verbose" directory. This is an alternative FTP DIRECTORY + command primarily for use with DECSYSTEM-20 (TOPS-20) FTP + servers, which send only filenames when given a DIRECTORY + command; the VDIRECTORY command makes them also send file + sizes, dates, and attributes. + + FTP CHECK filespec + Asks the FTP server whether the given file exists or, if the + filespec contains wildcards, if any files match, and this + command succeeds or fails accordingly. + + FTP MODTIME filename + Asks the FTP server, via the not-yet-standard FTP MDTM command, + to send the modification date and time of the given file. The + response should be a numeric string in the format: + yyyymmddhhmmssxxxxx... where yyyy is the year, mm is the month, + dd is the day, hh is the hour (0-23), mm is the minute, ss is + the second, and xxx... is the optional fraction of the second + (0 or more digits). The date and time is expressed in UTC (GMT, + Zulu, Zero-Meridian). The result is available programmatically + in the [261]\v(ftp_message) variable, and is understandable by + Kermit's date-time switches and functions. For example, suppose + we want to upload all local files that are newer than a + particular file on the server: + + C-Kermit> ftp modtime signpost + C-Kermit> echo \v(ftp_message) + 20010807113542.014 + C-Kermit> ftp mput /after:\v(ftp_message)GMT * + + Note that we must append "GMT" to the date-time string to let + the /AFTER switch know the time is GMT rather than local. + + FTP SIZE filename + Asks the FTP server to send the size (in bytes) of the given + file. The result might vary depending on whether the current + FTP TYPE is binary or text ("ascii"). For a reliable byte + count, do FTP TYPE BINARY first. The result is available + programmatically in the [262]\v(ftp_message) variable. + + FTP CHMOD permissions filename + Tells the FTP server to set the permissions (protection) of the + given file to the ones given. The permissions and filename must + be given in whatever syntax is required by the server. Example + (for a UNIX-based FTP server): + + ftp chmod 664 oofa.txt + + Not all servers support this command. For non-UNIX-based + servers, you might need to use FTP QUOTE or FTP SITE and the + appropriate platform-specific FTP server command. + + FTP UMASK [ number ] + This command is probably specific to UNIX-based servers; it + sets the UNIX "umask", which is the default permissions mask + for new (in this case, incoming) files. Crudely put, the UNIX + umask is an octal representation of a binary number in in which + a 1 bit stands for a permission bit that must be 0, and a 0 bit + stands for a permission bit that can be 0 or 1 depending on + other factors, such as the permissions of the parent directory. + Example: "umask 007" requires that new files are created + without read/write/execute world permission. If the number is + not specified, the server's current umask is reported. + + FTP RENAME filename newname + Asks the FTP server to rename the file whose name is "filename" + to "newname". Works only for one file; can not be used with + wildcards. The server's interpretation of "newname" can vary + (in some cases it must be a filename, in others perhaps it can + also be a directory name, in which case if the filename denote + a regular file, the file might be moved to the given + directory). Some servers might allow files to be renamed + ("moved") between physical disks or partitions, others might + not. Synonym: RRENAME. + + FTP DELETE [ switches ] filespec [ filespec [ ... ] ] + Tells the FTP server to delete the file or files listed. Each + file specification may, but need not, contain wildcard + characters to match multiple files. File specifications and + wildcard syntax must be those of the server. Any file + specifications that contain spaces must be enclosed in braces + or doublequotes. FTP DELETE switches are: + + /ERROR-ACTION: /FILENAMES: /NOBACKUPFILES /QUIET + /EXCEPT: /LARGER-THAN: /NODOTFILES /NOPAGE + /PAGE /RECURSIVE /SMALLER-THAN: + + When used with FTP DELETE, the /RECURSIVE switch deletes files + but not directories, and furthermore depends on the server + providing recursive file lists, which is not the normal + behavior. For further details, see the decriptions of these + switches in [263]Section 3.6. Synonyms: FTP MDELETE (Kermit + makes no distinction between DELETE and MDELETE); RDELETE. + + FTP TYPE { TEXT, BINARY, TENEX } + Tells the FTP server to change its file-transfer type to the + one given, immediately. See [264]SET FTP TYPE for details. + + [ [265]Top ] [ [266]FTP Top ] [ [267]C-Kermit Home ] [ [268]Kermit + Home ] + _________________________________________________________________ + + 3.5. Uploading Files With FTP + + Uploading means sending files from the client (Kermit) to the FTP + server. The basic command for uploading files with FTP is PUT: + + FTP PUT [ switches ] [ filespec [ as-name ] ] + Uploads (sends) the file or files that match the file + specification, which may include wildcards, to the server. If + no filespec is given, the names of files to send are taken from + the /LISTFILE: file, if any, otherwise from the SEND-LIST, if + any. Unless you go out of your way to prevent it, Kermit + determines the transfer mode (text or binary) for each file + automatically, and switches automatically on a per-file basis. + If an as-name is given, the file is sent under that name + instead of its own (if an as-name is given with a wildcard + filespec, the result is a bit more complicated, and is + explained later in this section). + + Unlike normal FTP clients, Kermit does not prompt you by default (or + at all) for each file; it just sends them, just as it does with Kermit + protocol. The filespec can be a literal filename or a Kermit pattern, + described in: + + [269]http://www.columbia.edu/kermit/ckermit70.html#x4.9 + + Kermit patterns are equivalent to C-Shell patterns and provide a fair + amount of flexibility in selecting which files to send, which is + augmented by the file-selection switches presented in [270]Section + 3.5.1. + + FTP MPUT [ switches ] filespec [ filespec [ ... ] ] + FTP MPUT is just like FTP PUT except it allows you to give more + than one file specification, and it does not allow an as-name + in the file list. However, as-names can be given to either PUT + or MPUT with the /AS-NAME: switch. + + If a PUT or MPUT command results in one file being uploaded, it + succeeds if the file is uploaded completely and fails otherwise. If + more than one file is selected for upload, success or failure depends + on the [271]FTP ERROR-ACTION setting; if it is PROCEED (the default + setting), then the [M]PUT command succeeds if at least one of the + files was completely uploaded, and fails otherwise, If FTP + ERROR-ACTION is QUIT, the [M]PUT command succeeds if all selected + files were uploaded successfully, and fails if any file failed. + + FTP uploads may be interrupted just like Kermit uploads. While the + transfer is in progress, type: + + X to interrupt the current file and go on to the next file. + Z to cancel the current file and all remaining files. + ^C (Control-C): Like Z, but might act more quickly. + + MPUT may be used as in regular FTP clients, but it is not required to + send multiple files; in Kermit it is required only if you want to give + multiple file specifications. Examples: + + ftp put oofa.txt ; Send a single file oofa.txt + ftp put oofa.txt budget.txt ; Send single file oofa.txt as budget.txt + ftp put *.txt ; Send all *.txt files + ftp mput *.txt ; Send all *.txt files (same as "put *.txt") + ftp mput *.txt foo.bar ; Send all *.txt files plus foo.bar + + The distinction between PUT and MPUT is important only when more than + one filespec is given, just like the distinction between Kermit SEND + and MSEND: + + ftp put oofa.txt budget.txt ; Send oofa.txt AS budget.txt + ftp mput oofa.txt budget.txt ; Send oofa.txt AND budget.txt + + If the source file specification includes any path segments, for + example: + + put /tmp/oofa.txt + put subdir/another/andanother/oofa.txt + + the path portion is stripped from the filename that is sent to the + server. However, if an as-name contains a path, it is retained. + Examples: + + ftp put /usr/doc/oofa.txt ; Send as "oofa.txt". + ftp put oofa.txt /tmp/oofa.txt ; Send as "/tmp/oofa.txt" + + The latter example sends the file oofa.txt from your current local + directory to the server's /tmp directory. This works only if the + server uses the same directory notation that you used in the as-name + AND the given directory already exists on the server AND if you have + write access to it. + + Use caution when uploading from a case-sensitive file system, such as + UNIX, to a file system that is not case sensitive, such as Windows or + VMS. If you have two files in UNIX, AA and aa and upload both of them, + the second one will overwrite the first. The only way around this + provided by FTP protocol is its "unique server names" feature (SET FTP + UNIQUE-SERVER-NAMES or the /UNIQUE switch described below). + _________________________________________________________________ + + 3.5.1. FTP PUT Switches + + FTP PUT and MPUT are similar in format and behavior to the regular + Kermit SEND and MSEND commands, and they allow most of the same + optional switches: + +C-Kermit>ftp put ? Filename, or switch, one of the following: + /after: /larger-than: /rename-to: + /array: /listfile: /server-character-set: + /as-name: /local-character-set: /server-rename-to: + /before: /move-to: /simulate + /binary /nobackupfiles /smaller-than: + /command /nodotfiles /tenex + /delete /nofollowlinks /text + /dotfiles /not-after: /transparent + /error-action: /not-before: /type: + /except: /permissions: /update + /filenames: /quiet /unique-server-names + /filter: /recover + /followlinks /recursive + + Since most of these switches are common to Kermit's SEND and MSEND + commands, they described only briefly here. For greater detail see: + + [272]http://www.columbia.edu/kermit/ckermit70.html#x1.5 (explanation + of switches) + [273]http://www.columbia.edu/kermit/ckermit70.html#x4.7 + (file-transfer switches) + + First the file-selection switches: + + /AFTER:date-time + /BEFORE:date-time + /NOT-AFTER:date-time + /NOT-BEFORE:date-time + Only send those files modified on or after or before the given + date and time. These switches can be combined to select files + modified between two date/times. Various date-time formats are + accepted; if the date-time contains spaces, it must be enclosed + in braces or doublequotes. See + [274]http://www.columbia.edu/kermit/ckermit70.html#x1.6 and + [275]Section 8.13 of this document for details about date-time + formats. Examples: + + ftp put /after:{1 jan 2000 0:00:00} * + ftp put /after:-5days * + + /LARGER-THAN:number + /SMALLER-THAN:number + Only send files larger (smaller) than the given number of bytes + (octets). These switches can be combined to select files in a + certain size range. + + /TYPE:{TEXT,BINARY} + Only send files that are the given type, which is determined + for each file just before sending it by file scanning. BINARY + includes TENEX; if you have included a /TENEX switch, or + previously given a [SET] FTP TYPE TENEX command, binary files + are sent in TENEX, rather than BINARY mode. + + /[NO]DOTFILES + [Don't] include files whose names begin with dot (.). By + default, such files are not included unless your filespec + explicitly mentions them. + + /NOBACKUPFILES + Don't include files whose names end with .~nnn~, where nnn is a + number, e.g. oofa.txt.~27~. These are backup files created by + Kermit, EMACS, and other applications. By default, backup files + are included. + + /NOFOLLOWLINKS + (UNIX only) Skip over symbolic links rather than following them + (default). This applies to wildcard and/or recursive [M]PUTs; + if a single filename is given, and it happens to be a symbolic + link, the file it points to is sent. + + /FOLLOWLINKS + (UNIX only) Always follow (resolve) symbolic links, even in + wildcard or recursive [M]PUTs. Use with caution. Watch out for + circular links, endless loops, etc. + + /EXCEPT:pattern + Exception list -- don't send files whose names match the given + pattern. See [276]Section 1.5.4 of the [277]C-Kermit 7.0 Update + Notes for details. If you want to exclude a directory from a + recursive [M]PUT, use /EXCEPT:{dirname/*}. + + /RECURSIVE + Sends the desired files from the current (or given) directory, + plus all directories beneath it, including empty directories, + replicating the directory structure on the server. No special + capabilities are required in the server, but of course your + login ID on the server must have the appropriate access and + permission to create directories. Recursive PUTs work not only + between like platforms (e.g. UNIX to UNIX) but also between + unlike ones (e.g. UNIX to VMS or Windows), in which case + text-file format differences are handled by Kermit's automatic + text/binary mode switching ([278]Section 4) and character-set + translation ([279]Section 3.7). Synonym: /SUBDIRECTORIES. + + /UPDATE + Send only files that have changed since last time ([280]Section + 3.5.2). + + /ARRAY:arrayname + The "file" to be sent is an array, or a segment of one, rather + than a real file. In this case the other selection switches + don't apply. The array contents are sent in text mode, and each + array element is treated as a line. Example: + + ftp put /as-name:array.txt /array:&a + + (or, to send a segment of the array, /array:&a[100:199]). If + you don't include an /AS-NAME, a name of "_array_x_" is used + (where x is the array letter). If you include this switch, most + other switches are meaningless and ignored. + + /COMMAND + The "file" to be sent is the standard output of a command, + rather than a real file. It is sent in text or binary mode + according to the prevailing FTP TYPE, which can be overridden + with a /TEXT or /BINARY switch. Example: Example: + + ftp put /command /as-name:{userlist} {finger | sort -r} + + /LISTFILE:filename + Tells Kermit to obtain the list of files to be sent from the + file whose name is given. This file must contain one file + specification (which may be wild) per line. If the list + includes files from different directories, such as a recursive + listing of a directory tree, the paths are recreated on the + server (if possible) if you include the /RECURSIVE switch; + otherwise all the files are sent to the current directory on + the server. + + Now the other switches: + + /AS-NAME:text + If a single file is being sent, send it with the given text as + its name. If multiple files are being sent, the text must be a + template that includes variables such as \v(filename), + \v(filenumber), \v(ntime), to allow dynamic creation of each + name. The same applies to the as-name field of the FTP PUT + command. If this switch is not included (and an as-name is not + included as the second filename to PUT), each file is sent with + its own name. + + /BINARY + /TEXT + /TENEX + Forces this upload to take place in the given mode, regardless + of the current FTP TYPE setting, and without automatic + text/binary switching. /ASCII is a synonym for /TEXT. + + /FILTER:command + Specifies that the file(s) is/are to be passed through the + given command or pipeline on their way to the server. Example: + + ftp put /binary /filter:{gzip -c \v(filename)} /as-name:\v(filename).gz * + + /TRANSPARENT + /LOCAL-CHARACTER-SET:name + /SERVER-CHARACTER-SET:name + Character-set translation for text files, explained in + [281]Section 3.7. + + /ERROR-ACTION:{PROCEED,QUIT} + Overrides the prevailing [282]FTP ERROR-ACTION for the duration + of this PUT or MPUT command only. + + /RECOVER + Resume an interrupted transfer where from the point of + interruption (explained in [283]Section 3.5.2). Synonym: + /RESTART. + + /DELETE + Tells Kermit to delete each source file immediately after, and + only if, it has been uploaded completely and successfully. + This, in effect, moves the file from the client to the server. + + /MOVE-TO:directory + Tells Kermit to move each source file to the named local + directory after, and only if, it has been uploaded completely + and successfully. + + /RENAME-TO:template + Tells Kermit to rename each (local) source file according to + the given template after, and only if, it has been uploaded + completely and successfully. The template works as in /AS-NAME. + + /SERVER-RENAME-TO:template + Tells Kermit to ask the server to rename each file according to + the given template as soon as, and only if, it has been + received completely and successfully. The template works as in + /AS-NAME. Requires write and rename access on the server, so + doesn't usually work with (e.g.) anonymous uploads to public + incoming areas where the permissions don't allow renaming. + Examples: + + ftp mput /server-rename:\v(filename).ok * + Appends ".ok" to each filename on the server when it's + finished uploading. + + ftp mput /as-name:\v(filename).tmp /server-rename:\v(filename) * + This is the reverse of the previous example; it uses a + temporary name while uploading is in progress and reverts + the file to its real name when uploading is complete. + + ftp mput /as-name:\v(filename) + /server-rename:../final/\v(filename) * + Moves the file from the working directory to a final + directory when the upload is complete, but in this case + you have to know the pathname syntax of the server. If + the rename fails, the [M]PUT command fails according to + the [284]FTP ERROR-ACTION selection. + + /FILENAMES:{AUTOMATIC,CONVERTED,LITERAL} + Overrides the [285]FTP FILENAMES setting for this upload only. + + /PERMISSIONS:{ON,OFF} + Overrides the [286]FTP PERMISSIONS setting for this upload + only. + + /UNIQUE + Tells Kermit to tell the server to give [287]unique names to + incoming files that would otherwise overwrite existing files + that have the same name. This switch conflicts with /UPDATE, + /RECOVER, /PERMISSIONS, and /SERVER-RENAME since the client has + no way of knowing the name assigned by the server. + + /QUIET + Don't display file-transfer progress or statistics. + + /SIMULATE + Shows which files would be sent without actually sending them. + Useful (for example) with /UPDATE (next section). The results + are shown in the file-transfer display (if it is not disabled) + and in the transaction log (if one is active). Hint: use SET + TRANSFER DISPLAY BRIEF. + _________________________________________________________________ + + 3.5.2. Update Mode + + When you include the /UPDATE switch, this means to skip sending any + file that already exists on the server if the local file's + modification date/time is not later than that of the corresponding + file on the server. Here is a typical application for update mode: + Suppose that on Computer A, you maintain a large set of files (say, a + collection of Web pages and graphics images, or the source files for a + software application), and you need to keep a parallel copy on another + Computer, B. Of course you could upload the entire collection every + day: + + cd source-directory + ftp computerb.xyzcorp.com + ( authentication details... ) + ftp cd target-directory + ftp put [ switches ] * + + But if the total size is large or the network slow, this would be + unnecessarily time-consuming. Worse, if other users or sites had to + update whenever new files appeared in B's directory, this would cause + them unnecessary work. By including the /UPDATE switch: + + ftp put /update [ other-switches ] * + + only those files that changed since last time are uploaded. Here's how + it works. For each local file that is selected for uploading: + + * The remote filename is determined in the normal way, according to + the [288]FTP FILENAMES setting, /FILENAMES switch, or the as-name, + if any. + * Kermit sends an MDTM (modification time) command for the + corresponding remote filename to the server. + * If the server does not understand the MDTM command, the file is + sent. + * If the server can't find a file with the given name, the file is + sent. + * If the local file's modification time is later than that of the + remote file, the file is sent. + * Otherwise -- the remote file exists but its modification time is + equal to or earlier than that of the local file -- the file is + skipped. + + All time comparisons take place in Coordinated Universal Time + (UTC)([289]1), also known as GMT or Zulu time: Timezone 0; standard + time, without daylight savings. + + WARNING: Some FTP servers, such as Novell NWFTPD.NLM, ignore or + misimplement the FTP specification and send local time rather than + UTC. + + Update mode is useful only when always used in the same direction. + When you upload (PUT) a file with FTP, the destination file receives + the current timestamp on the server's computer, not the original + file's timestamp ([290]2). If you try to FTP PUT /UPDATE the same file + again, it will be skipped (as expected) since the remote copy is + newer. However, if you try to FTP GET /UPDATE the same file + ([291]Section 3.6), it will be transferred for the same reason. + + To check the availability of PUT /UPDATE on a particular connection, + issue an FTP MODTIME command for a file that is known to exist on the + server. If it succeeds, PUT /UPDATE should work and in that case, you + can run a procedure like the one above every day: the first time, it + sends all the files; after that, it sends only the ones that changed. + If a transaction log is active, a notation is included for any files + that are skipped. + + Notes: + 1. Why is Coordinated Universal Time abbreviated UTC? From the + [292]National Institute of Standards and Technology FAQ: "In 1970 + the Coordinated Universal Time system was devised by an + international advisory group of technical experts within the + International Telecommunication Union (ITU). The ITU felt it was + best to designate a single abbreviation for use in all languages + in order to minimize confusion. Since unanimous agreement could + not be achieved on using either the English word order, CUT, or + the French word order, TUC, the acronym UTC was chosen as a + compromise." + 2. The Kermit FTP client is unusual in that, when downloading only, + it can set the received file's date from the file's date on the + server, but this should not affect the update feature. When + uploading to an FTP server, however, there is no mechanism for the + client to set the date of the uploaded file on the server. + _________________________________________________________________ + + 3.5.3 Recovery + + Suppose that while you are uploading a large file over a slow + connection, the connection is lost before the entire file is + transferred. With most FTP clients, you would have to start over, thus + resending the portion of the file that was sent already, and that is + already on the server. But Kermit's /RECOVER switch (Synonym: + /RESTART) lets you continue an interrupted transfer from the point of + failure, thus transferring only the part that wasn't sent already. The + prerequisites for recovery are: + + * The transfer must be in BINARY mode, or else the client and server + must reside on like systems (e.g. both on some form of UNIX). + * The FTP server must support the SIZE command. + + Here's how it works. When you include the /RECOVER switch: + + * Kermit checks for conflicting switches, such as /UPDATE and + /UNIQUE; if /RECOVER is given with these switches an error occurs. + If /RECOVER is given in other circumstances where it could serve + no useful purpose (e.g. with arrays, pipes, or filters), it is + ignored. + + If the switch is accepted, then for each selected file: + + * If it is not binary (determined by scanning) and the client and + server are not on like platforms, recovery is canceled (the entire + file is sent). Otherwise: + * A SIZE command is sent for the file (using its remote name). If + the reply indicates the file was not found, or the SIZE command + was not understood, or any other kind of error, recovery is + canceled. Otherwise: + * A MDTM (modification time) command is sent for the file. If a + valid reply is received, and the modification time of the local + file is later than that of the remote file, recovery is canceled. + Otherwise: + * If the sizes of the two files are identical, the file is not sent. + Otherwise: + * Kermit seeks to the recovery spot in the local file, tells the + server to APPEND the data which is about to arrive to the remote + file, and then sends the data starting at the recovery point. + + To safeguard file integrity, recovery is not attempted unless all the + preconditions are met. For the widest possible usefulness, APPEND is + used rather than RESTART. For stream transfers (the only kind that + Kermit supports) the results are the same. + + By design, the /RECOVER switch can be included with any FTP PUT or + MPUT command, even if it specifies a group of files. This allows you + to resume an interrupted batch transfer from where it left off. The + files that were already completely sent are skipped, the file that was + interrupted is recovered, and the remaining files are uploaded. + + By the way, it doesn't matter how the original partial file was + uploaded -- FTP, Kermit, Zmodem, etc: as long as the preconditions are + met, it can be recovered with FTP PUT /RECOVER, or for that matter + also using Kermit protocol and SEND /RECOVER. + + A word of caution, however, when the original upload was in text mode + with character-set translation ([293]Section 3.7): + + * If the original upload involved a translation from one single-byte + character set to another (e.g. Code Page 850 to Latin-1), recovery + is safe if you specify the same translations for the recovery. If + you don't, the resulting file will contain a mixture of character + sets. + * If the original upload involved a translation that changed the + size of the file (e.g. from an alphabetic Code Page or Latin + Alphabet to Unicode, or vice versa), recovery is NOT safe, even if + you specify the same translations. + + Kermit has no way of knowing anything about the previous upload. As a + safeguard, an error occurs if you include /RECOVER and also specify a + character-set of UCS2 or UTF8, since recovery can't possibly work in + that situation. Otherwise, it's up to you to avoid unsafe recovery + operations. + + [ [294]Top ] [ [295]FTP Top ] [ [296]C-Kermit Home ] [ [297]Kermit + Home ] + _________________________________________________________________ + + 3.6. Downloading Files With FTP + + Although uploading files with Kermit's FTP client is just as easy and + flexible as sending files with Kermit protocol, the same is not always + true for downloading because FTP servers lack some of the capabilities + of a Kermit server: + + * If you want to get more than one file, you have to use MGET, not + GET, since the underlying FTP protocol is different in the two + cases. Kermit can't "autodetect" which one you mean, as it can + with PUT and MPUT, since it can't be expected to know the wildcard + syntax of the remote platform and/or FTP server (the same is true + for all other FTP clients). To complicate matters, FTP protocol + now includes two underlying mechanisms (NLST and MLSD) for + accomplishing MGET operations and, as explained in [298]Section + 3.11, the two behave differently. + * Automatic text-binary mode switching is not done by the server. It + can be done by the client (Kermit), but in this case it is not + based on a file scan (since there is no way for Kermit prescan a + server file), but rather on the filename, using C-Kermit 7.0 + [299]filename patterns. + * Some options that are available with FTP PUT can not be used with + FTP [M]GET or don't work the same way: + /PERMISSIONS (FTP protocol has no mechanism for this). + /[NOT-]BEFORE, /[NOT-]AFTER (because of the timezone problem). + /RECOVER works only in binary mode. /RECURSIVE has limited + utility. + + The commands for downloading are: + + SET FILE DOWNLOAD-DIRECTORY [ directory ] + As with Kermit transfers, this command, if given, tells + C-Kermit where to store incoming files in the absence of a + specific as-name. If not given, incoming files are stored as + indicated by the as-name, if any, otherwise in the current + directory, just as with Kermit transfers. The more verbose + transfer display formats give the full pathname of each + received file, and, in case you have trouble finding a + downloaded file afterwards, its full path is also listed in the + transaction log (if you kept one), and you can also ask Kermit + where it went with the [300]WHERE command. + + SET FTP GET-FILETYPE-SWITCHING { ON, OFF } + ON by default, causing Kermit to switch automatically into text + or binary mode for each file based on whether its name matches + a text pattern or binary pattern. Set this OFF, or use a /TEXT, + /BINARY, or /TENEX switch to defeat this feature. Use SHOW + PATTERNS to see the current pattern list. + + [ FTP ] GET [ switches ] filename [ as-name ] + Asks the server to send the given file, and if it comes, stores + it locally under the given as-name, if any, otherwise under its + original name (modified according to the selected filename + conversion option), in your download directory, if you have + specified one, otherwise in the directory indicated in the + as-name, if any, otherwise in your current directory. If you + accidentally use a wildcard in the filename ("get *.txt") the + server will reply with a message like "File not found" (unless + there is a file whose name actually is "*.txt"). If FTP + GET-FILETYPE-SWITCHING is ON, and in the absence of any GET + switches to override it, the file is transferred in binary mode + if it matches any of Kermit's binary name patterns, and in text + mode if it matches any of Kermit's text name patterns, and in + the prevailing FTP TYPE if it matches none of these patterns. + + [ FTP ] MGET [ switches ] filespec [ filespec [ filespec [ ... ] ] ] + Like GET, but for multiple files. One or more file + specifications can be given, and any or all (or none) of them + can contain wildcards or can be directory names. The file list + may not include an as-name, but you can still give one with the + /AS-NAME: switch. + + In both the FTP GET and MGET commands, any filenames that contain + spaces must be enclosed in braces or doublequotes (see [301]Section 5 + for details). + + FTP downloads may be interrupted just like Kermit transfers. While the + transfer is in progress, type: + + * X to interrupt the current file and go on to the next file. + * Z (or Control-C) to cancel the current file and all remaining + files. + + Before proceeding, a brief word about temporary files. In FTP + protocol, the MGET command works by requesting a file list from the + server, and then (internally) issuing a GET command (FTP RETR protocol + directive) for each file. The file list returned by the server can be + any size at all, so in case it is huge, we don't store it in memory; + instead we put it in a temporary file. For troubleshooting purposes, + you should be aware of two points: + + 1. The location of the temporary file is chosen according the TMP or + TEMP environment variables. If neither of these variables is + defined, you might need to define it. In case there is not enough + space on the indicated disk or partition for the server's file + list, you might need to either clean up the temporary area, or + redefine the environment variable to indicate a different area + that has sufficient space. + 2. If you want to look at the list yourself, use SET FTP DEBUG ON. + This tells Kermit to (a) give you the full pathname of the + temporary file at the end of each MGET command, and (b) not to + delete it, as it normally does. + _________________________________________________________________ + + 3.6.1. FTP GET Switches + + The following switches are available with FTP GET and MGET: + + /TEXT + Specifies a text-mode transfer. Overrides the global FTP TYPE + setting and filename pattern-matching for the duration of the + current command only, All files are downloaded in text mode. + Synonym: /ASCII. + + /BINARY + Specifies a binary-mode transfer. Overrides the global FTP TYPE + setting and filename pattern-matching for the duration of the + current command only. All files are downloaded in binary mode. + + /TENEX + Like /BINARY but specifies a special binary transfer mode to be + used when getting 8-bit binary files from a 36-bit platform + such as TOPS-10, TOPS-20, or TENEX. All files are downloaded in + the special binary mode. + + /RECOVER + This instructs Kermit to try to recover an incomplete download + from the point of failure. Works only in binary mode, and only + if the server supports the (not-yet-standard) FTP "REST" + directive. See [302]Section 3.6.3 for details. Synonym: + /RESTART. + + /FILENAMES:{CONVERTED,LITERAL} + Overrides the [303]FTP FILENAMES (filename conversion) setting + for this download only, forcing incoming filenames to be either + converted or taken literally. + + /AS-NAME:text + For GET, this is equivalent to giving an as-name after the + filename. For MGET, this is the only way to specify alternative + names for the incoming files. With MGET, the /AS-NAME text + should (must) contain a Kermit variable, usually \v(filename) + or \v(filenumber). Example: + + mget /text /as-name:\v(filename).new *.c + + This gets all ".c" files and stores them with " + + .new" appended to their names. See the [304]C-Kermit 7.0 Update + Notes for details. + + /COMMAND + This specifies that the incoming file is to be written to the + standard input of a command, rather than to a file. The command + name is the as-name from the GET command or the /AS-NAME + argument. If you need to refer to the incoming file's name in + the command, use \v(filename). See the description of the + regular Kermit [305]GET /COMMAND command for details and + examples. + + /QUIET + Transfers the files quietly; don't put up a file-transfer + display. + + /ERROR-ACTION:{QUIT,PROCEED} + This switch affects only MGET. If an error occurs with a + particular file, this tells whether to go on to the next file + (PROCEED) or to stop right away and fail (QUIT). The default is + PROCEED. + + The file selection switches are: + + /EXCEPT:{pattern} or /EXCEPT:{{pattern}{pattern}{...}} + Exception list for MGET; skip downloading any file whose name + matches any of the given patterns (when using the second + format, up to 64 patterns may be specified). [306]CLICK HERE + for syntax details. + + /SMALLER-THAN:number + Download only files whose size is smaller than the given number + of bytes (octets). Requires that the FTP server support the + SIZE or MLSD directive. + + /LARGER-THAN:number + Download only files whose size is greater than the given number + of bytes. Requires that the FTP server support the SIZE or MLSD + directive. + + /NOBACKUPFILES + During MGET, don't download any files whose names end with + backup suffixes (.~n~ where n is a number). + + /NODOTFILES + During MGET, don't download any files whose names begin with + period (.). Equivalent to /EXCEPT:{.*}. + + /LISTFILE:local-filename + The given file contains a list of files to GET, one per line. + Filenames in the listfile can contain wildcard characters in + the syntax of the server. There is no limit on the number of + lines in the listfile. + + /NAMELIST:local-filename + If this switch is given, then instead of actually retrieving + the selected files, the GET command retrieves a list of the + names of the files that would be retrieved, and places it in + the specifed file. The resulting file is an ordinary text file, + with one filename per line, suitable for reading by a person, + or processing by a computer program, including Kermit itself + (FOPEN / FREAD / FWRITE / FCLOSE), and as /FILELIST: file. If + the filename is omitted or given as "-" (dash, hyphen), the + list goes to the screen. NOTE: if you want a copy of the + complete list sent by the server, use SET FTP DEBUG ON, perform + an MGET, and the temporary file containing the list will be + kept rather than deleted (and Kermit tells you its name). + + /UPDATE, /COLLISION:keyword + Explained in [307]Section 3.6.2. + + /RECURSIVE + This means to try to download an entire directory tree, rather + than just files from a particular directory. In fact, FTP + protocol does not provide a method to request a recursive + download (unless the server supports MLSD; see [308]Section + 3.11), so this works only if the FTP server does it anyway, + without being asked, as some do. In this case, Kermit detects + that names in the returned file list contain directory + separators, and therefore attempts to create the needed + directories as the files arrive. But this can work only if the + server is on the same kind of platform as the client, so the + pathname syntax can be recognized, and also because the server + does not switch between text and binary mode, which would be + vital for cross-platform transfers. Use with caution. Synonym: + /SUBDIRECTORIES. + + Even when the server does not provide recursive file lists, + [M]GET /RECURSIVE forces Kermit to replicate any directory + structure implied or expressed by the server's file list. For + example: + + get somepath/somefile + + Gets the file named somefile from the server's somepath + directory and puts it Kermit's current (or download) directory, + whereas: + + get /recursive somepath/somefile + + creates the path locally and then puts the file in it. + Similarly for MGET: + + mget */data/* + + downloads all the files in all the data subdirectories of all + the subdirectories of the server's current directory and stores + them locally in Kermit's current (or download) directory, + whereas: + + mget /recursive */data/* + + re-creates the server's directory structure locally. + + The FTP protocol does not include explicit mechanisms for recursion, + so Kermit builds upon what is available. Although an Internet draft + describes a mechanism ("MLSD") that would allow protocol-driven + recursion, similar to Kermit's File Attribute packets (circa 1984), it + has not yet attained RFC or standard status, and servers are not yet + widely available that offer this feature. In the meantime, the + effectiveness of MGET /RECURSIVE depends on the FTP server + implementation. If the server returns a recursive list in response to + the standard NLST command (whose behavior is ill-defined), Kermit's + FTP MGET /RECURSIVE command uses it to re-create the remote directory + tree locally. If the server supports MLSD, C-Kermit 8.0.206 and Kermit + 95 2.1 and later are able to sense it automatically and use it, as + described below in [309]Section 3.11. + + The /BEFORE:, /AFTER:, /NOT-BEFORE:, and /NOT-AFTER: switches are not + available for downloading because of the confusion with timezones. + Would the given times be in the local timezone, the server's timezone, + or GMT? The FTP server's directory listings show its own local times + but since we don't know what timezone the server is in, there's no way + to reconcile our local times with the server's. Similarly, + /PERMISSIONS can't be preserved in downloads because FTP protocol + provides no means of querying the server for a file's permission. + + Source-file disposition switches: + + /DELETE + Each file that is downloaded successfully is to be deleted from + the server. Requires the appropriate file access rights on the + server. + + /SERVER-RENAME-TO:template + Asks the server to rename each (remote) source file immediately + after, and only if, it is sent correctly. See [310]PUT + /SERVER-RENAME-TO: for details. + + Destination-file disposition switches: + + /TO-SCREEN + Displays the incoming file on the screen rather than storing it + on disk. If this switch is given, the /RENAME-TO and /MOVE-TO + switches are ignored, the file-transfer display is suppressed, + and the given file(s) is/are shown on the screen. Can be used + with /FILTER, e.g. + + get /text /to-screen /filter:more oofa.txt + + In fact, you should always use /TO-SCREEN with /FILTER or + /COMMAND when the command would result in displaying the + incoming file on the screen; otherwise C-Kermit would have no + way of knowing to suppress its file transfer display (since it + can't be expected to know what the command or filter does). + + /RENAME-TO:template + Each file that is downloaded is to be renamed as indicated if + and only if it was received completely and without error. The + template can be literal text or can contain variables that are + evaluated for each file. For MGET, the text must contain + variables; for GET it can be a literal string. The \v(filename) + variable contains the name of the current file, so: + + ftp mget /rename-to:\v(filename).ok * + + causes each file that is successfully downloaded to have ".ok" + appended to its name. For details see [311]Section 4.1 of the + [312]C-Kermit 7.0 Update Notes. + + /MOVE-TO:text + Just like /RENAME-TO:, except the text denotes the name of a + directory to which successfully downloaded files are to be + moved. If the directory does not exist, it is created. + + The file transfer display does not show the /MOVE-TO or /RENAME-TO + value, since the incoming file has not yet been moved or renamed. + _________________________________________________________________ + + 3.6.2. Filename Collisions + + What should happen if an incoming file has the same name as an + existing file in the same directory? By default, Kermit's FILE + COLLISION setting applies: BACKUP, RENAME, UPDATE, DISCARD, etc, as + described in [313]Using C-Kermit. Kermit's default FILE COLLISION + setting is BACKUP (rename the existing file and store the incoming + file under its own name) and therefore this is also the default FTP + collision action. + + The name under which an incoming file is to be stored is determined as + follows: + + * If an as-name was given, the as-name is used. Otherwise: + * If the client and server platforms are alike or [314]FTP FILENAMES + is set to LITERAL (or the /FILENAMES:LITERAL switch was given for + this download), the incoming filename is used literally. + Otherwise: + * The incoming filename is converted to a form that is friendly to + the local platform. For UNIX, for example, incoming filenames that + are all uppercase (as they might be from, say, VMS or an IBM + mainframe) are converted to lowercase. + + If the resulting name coincides with the name of a local file that + already exists, we have a filename collision. Collisions are handled + according to the currently selected collision action: + + SET FTP COLLISION { BACKUP, RENAME, UPDATE, DISCARD, APPEND, OVERWRITE + } + This establishes a filename collision for FTP, separate from + the Kermit one. The initial FTP collision setting is inherited + from Kermit's FILE COLLISION setting when the first FTP command + is given, but subsequent changes to Kermit's FILE COLLISION + setting do not affect the FTP COLLISION setting. SHOW FTP tells + the current FTP COLLISION setting. + + FTP GET /COLLISION:{BACKUP,RENAME,UPDATE,DISCARD,APPEND,OVERWRITE} + Overrides the current FTP COLLISION action for this download + only. + + FTP GET /UPDATE + This is equivalent to GET /COLLISION:UPDATE, and is included + for symmetry with PUT /UPDATE + + FTP GET /UPDATE and /COLLISION:UPDATE mean to download only those + files whose modification dates on the server are later than those on + the client. Date-time comparisons are done in Coordinated Universal + Time (UTC, GMT, ZULU). The command: + + FTP MGET /COLLISION:APPEND /AS-NAME:newfilename *.* + + Downloads all matching remote files into a single local file (in + whatever order the server sends them). + _________________________________________________________________ + + 3.6.3. Recovery + + Recovery is available for downloads too, but there are some + differences from the uploading case described in [315]Section 3.5.3: + + * The transfer must be in BINARY mode. It can not be in text mode, + even if the FTP server is on the same kind of platform as Kermit, + and even if there is no character-set translation. The original + download must also have been in binary mode. + * The FTP server must support the REST ("restart") directive. + Unfortunately, this is not a standard command; at this writing, it + is described only in an Internet Draft, not an RFC or Internet + Standard, but nevertheless it is found in several popular FTP + servers, such as [316]ProFTPD. + + Here's how download recovery works: + + * Kermit checks for conflicting switches, such as /UPDATE, /COMMAND, + or /FILTER. If /RECOVER is given with these switches an error + occurs. + * The prevailing transfer mode (SET FTP TYPE) must be BINARY. If it + is not, the /BINARY switch must have been included with the FTP + [M]GET command. + + If the /RECOVER switch is accepted, then for each selected file: + + * A SIZE command is sent for the file (using its remote name). If + the reply indicates the file was not found, or the SIZE command + was not understood, or any other kind of error, recovery is + canceled (i.e. the entire file is downloaded). + * If the sizes of the two files are identical, the file is not sent. + Otherwise: + * Kermit sends the REST directive to the server, indicating the size + of the local file. If the server responds affirmatively, Kermit + opens the local file in append mode and appends the incoming data + to it. Otherwise, recovery is canceled and the entire file is + downloaded. + + The /RECOVER switch can be included with any FTP GET or MGET command, + even if it specifies a group of files. This lets you resume an + interrupted batch transfer from where it left off. The files that were + already completely sent are skipped, the file that was interrupted is + recovered, and the remaining files are uploaded. BUT... unlike with + uploading, where this can be done with any mixture of text and binary + files, when downloading, it can only be done if all the files are + binary. + + It doesn't matter how the original partial file was downloaded -- FTP, + Kermit, HTTP, Zmodem, etc: as long as the preconditions are met, it + can be recovered with FTP [M]GET /RECOVER, or for that matter also + with GET /RECOVER (using Kermit protocol). + + [ [317]Top ] [ [318]FTP Top ] [ [319]C-Kermit Home ] [ [320]Kermit + Home ] + _________________________________________________________________ + + 3.7. Translating Character Sets + + A possibly unique feature of Kermit's FTP client is its ability to + convert character sets when transferring files in text mode, + independent of the capabilites of the FTP server, as well as to + translate the character sets of filenames regardless of transfer mode. + For compatibility with existing FTP clients, and because there is a + certain performance penalty, Kermit won't do this unless you ask for + it. If you enable this feature, you need to inform Kermit of the + character set (to be) used on the server and in some cases (explained + below) also the local file character set. This discussion assumes you + know a bit about character sets (as you must if you have to use them); + see Chapter 16 of [321]Using C-Kermit for a detailed treatment. The + Kermit commands for FTP character-set conversion are: + + SET FTP CHARACTER-SET-TRANSLATION { ON, OFF } + Whether to translate character sets when transferring text + files with FTP. OFF by default. Set this to ON to enable + character-set translation for subsequent FTP uploads and + downloads. + + SET FTP SERVER-CHARACTER-SET [322]name + Text character set (to be) used by the server. Most FTP servers + are ignorant of character sets, so all translations are done + unilaterally by Kermit's FTP client. This means that when + downloading files, you must know in advance the character-set + used in the files you are downloading (and in their names). + When uploading, you must specify the character-set to which + local filenames and text-file contents are to be translated for + transmission to the server. If you SET FTP + CHARACTER-SET-TRANSLATION ON but do not specify an FTP + SERVER-CHARACTER-SET, [323]UTF8 is used, since this is the new + Internet standard international character set; it is upwards + compatible with ASCII and it encompasses most written languages + and therefore does not favor any particular group of people, as + any other default would do. If you SET FTP SERVER-CHARACTER-SET + to something (anything) when FTP CHARACTER-SET TRANSLATION is + OFF, this also sets the latter ON. + + SET FILE CHARACTER-SET [324]name + This is the regular Kermit (non-FTP-specific) command for + identifying the character set (to be) used in local text files + and filenames. + + TO REITERATE: If you SET FTP CHARACTER-SET TRANSLATION ON but do not + specify an FTP SERVER-CHARACTER-SET, outbound text files are converted + to UTF-8 and inbound text files are assumed to be UTF-8. If this is + not appropriate, be sure to also specify the desired FTP + SERVER-CHARACTER-SET. + + You can use "special" (non-ASCII) characters in filenames in all the + client / server file management commands (FTP MKDIR, RMDIR, DIRECTORY, + VDIRECTORY, DELETE, etc), and also in file-transfer commands. When + giving commands such as FTP DIR (RDIR) and FTP PWD (RPWD), the reply + is translated too, so you can read it. In this example, the client and + server use entirely different codes to represent the special + characters of German: + + C-Kermit> ftp xyzcorp.de /anonymous + C-Kermit> set ftp server-character-set latin1 + C-Kermit> set file character-set german + C-Kermit> rcd Städte + C-Kermit> rpwd + "/pub/ftp/Städte is current directory" + C-Kermit> rdir + -rw-rw---- 1 olaf 54018 Jan 6 17:58 Adenbüttel.txt + -rw-rw---- 1 ursula 373 Jan 5 15:19 Aßlar.txt + -rw-rw---- 1 gisbert 482 Jan 5 15:20 Blowatz.txt + -rw-rw---- 1 gudrun 124 Jan 5 15:19 Böblingen.txt + -rw-rw---- 1 olga 14348 Jan 7 14:23 Köln.txt + + When the client and server file systems use different character sets, + you should take care to use only those characters that the two sets + share in common when creating filenames or text-file contents. For + example, PC code pages contain a lot line- and box-drawing characters, + and sometimes "smart quotes", etc, that are not found in ISO standard + 8-bit character sets. You should be especially careful to avoid using + such characters in filenames. + + [ [325]C-Kermit Character Sets ] + _________________________________________________________________ + + 3.7.1. Character Sets and Uploading + + Kermit's PUT and MPUT commands include full file-scanning + capabilities, as described in [326]Section 4. Thus if FTP + CHARACTER-SET-TRANSLATION is ON and your character-set associations + are set up appropriately, Kermit automatically switches on a per-file + basis between text and binary mode, and for each text file between + your chosen 7-bit text character set (e.g. ASCII or ISO 646 German), + 8-bit text (e.g. Latin-1 or Japanese EUC), UCS-2, and UTF-8, and + converts each of these automatically to the server character-set, and + furthermore automatically differentiates between the Little and Big + Endian forms of UCS-2, always sending in Big Endian form. + + WARNING: It is not advisable to use UCS-2 (or any Unicode + transformation other than UTF-8) "on the wire", i.e. as a server + character set. Most FTP servers are not able to cope with it, since + it contains lots of 0 (NUL) characters. If you do use it, Kermit + does not translate filenames to or from UCS-2, for reasons well + known to C programmers (for example, UNIX APIs assume filename + strings are NUL-terminated). [327]UTF-8 is the preferred (and + standard) Unicode format for the Internet. + + FTP character-set translations differ from the regular Kermit ones by + not restricting translations to a file-character-set / + transfer-character-set pair. You can have Kermit's FTP client + translate between any pair of character sets it knows about. You can + see the list of supported character sets by typing either of the + following: + + set ftp server-character-set ? + set file character-set ? + + A typical list looks like this ([328]CLICK HERE for an explanation of + the names): + + C-Kermit>set file char ? One of the following: + ascii cp869-greek hebrew-7 mazovia-pc + british cyrillic-iso hebrew-iso next-multinational + bulgaria-pc danish hp-roman8 norwegian + canadian-french dec-kanji hungarian portuguese + cp1250 dec-multinational iso2022jp-kanji shift-jis-kanji + cp1251-cyrillic dg-international italian short-koi + cp1252 dutch jis7-kanji spanish + cp437 elot927-greek koi8 swedish + cp850 elot928-greek koi8r swiss + cp852 euc-jp koi8u ucs2 + cp855-cyrillic finnish latin1-iso utf8 + cp858 french latin2-iso + cp862-hebrew german latin9-iso + cp866-cyrillic greek-iso macintosh-latin + C-Kermit> + + Thus you can translate not only between private sets (like PC code + pages) and standard ones (like Latin-1) as in Kermit protocol, but + also between any given pair of private sets (e.g. CP852 and Mazovia). + All conversions go through Unicode as the intermediate character set, + resulting in a minimum of character loss, since Unicode is a superset + of all other character sets known to Kermit. + + In addition to the SET commands listed above, the FTP PUT and MPUT + commands include switches that apply only to the current command: + + /LOCAL-CHARACTER-SET:name + /SERVER-CHARACTER-SET:name + Use these switches to force a particular translation. These + switches override the global FTP CHARACTER-SET-TRANSLATION and + SERVER-CHARACTER-SET settings and also character-set + differentiation by file scanning for the duration of the PUT or + MPUT command. The file scan is still performed, however, to + determine whether the file is text or binary; thus these + switches do not affect binary files unless you also include the + /TEXT switch to force all files to be treated as text. + + In other words, if you include one or both of these switches with a + PUT or MPUT command, they are used. Similarly, the /TRANSPARENT switch + disables character-set translation for the PUT or MPUT command despite + the prevailing FTP CHARACTER-SET-TRANSLATION and SERVER-CHARACTER-SET + settings. + + When uploading, the FILE CHARACTER-SET setting is ignored unless you + have forced Kermit not to [329]scan local files by including a /TEXT + or /BINARY switch with your [M]PUT command, or by disabling automatic + text/binary switching in some other way. + + Examples: + + 1. Suppose you have a CP852 (East European) text file that you want + to upload and store in ISO Latin Alphabet 2 encoding: + ftp put /local-char:cp852 /server-char:latin2 magyar.txt + 2. Suppose you always want your text files converted to Latin-2 when + uploading with FTP. Then put: + set ftp server-character-set latin2 + in your Kermit customization file, and then you can omit the + /SERVER-CHARACTER-SET: switch from your FTP PUT commands: + ftp put /local-char:cp852 magyar.txt + 3. Now suppose that all the text files on your PC are written in + Hungarian, but they have a variety of encodings, and you don't + want to have to include the /LOCAL-CHARACTER-SET: switch on every + FTP PUT command, or (more to the point) you want to be able to + send a mixture of these files all at once. Put these commands in + your Kermit customization file: + set ftp server-character-set latin2 ; ISO 8859-2 + set file default 7-bit-character-set hungarian ; ISO 646 Hungarian + set file default 8-bit-character-set cp852 ; PC East European Code Page + and now PUT and MPUT will automatically detect and switch among + ISO 646 Hungarian, Code Page 852, UTF-8, and UCS-2 encodings, + translating each one to Latin-2 for uploading: + ftp put *.txt + + And since binary files are also detected automatically, the latter can + be simplified to: + + ftp put * + + even when "*" matches a diverse collection of binary and text files, + because translations are skipped automatically for binary files. + _________________________________________________________________ + + 3.7.2. Character Sets and Downloading + + The commands and switches are the same as for uploading, but automatic + character-set switching works differently, since Kermit can't scan the + server files in advance. Instead, the transfer mode (text or binary) + is based on the filenames; each name is compared with Kermit's list of + text name patterns and binary name patterns. If the name matches a + binary pattern (for example, if the filename is oofa.tar.gz and one of + the filename patterns is "*.gz"), the file is downloaded in binary + mode; otherwise if it matches a text pattern (e.g. oofa.txt matches + "*.txt"), it is transferred in text ("ascii") mode. Otherwise, it is + transferred in the prevailing FTP TYPE. + + In C-Kermit 8.0, the pattern lists used with FTP GET are not the same + lists used with Kermit transfers, and can not be viewed with SHOW + PATTERNS, nor adjusted with ADD and REMOVE TEXT-PATTERNS and + BINARY-PATTERNS, or SET FILE TEXT-PATTERNS and BINARY-PATTERNS. + Configuration of the FTP patterns list will be added in a future + release. + + Examples: + + get /server-char:latin1 /local-char:cp850 Grüße.txt + In this command, the filename contains special characters, + which you enter using whatever character set your local + computer uses, in this case PC Code Page 850 (cp850). The + command tells Kermit (in case it didn't know already from its + FILE CHARACTER-SET setting) that the local character set is + cp850 and the server's character-set is ISO 8859-1 Latin + Alphabet 1 (latin1). Kermit translates the filename from cp850 + to latin1 and sends the latin1 name to the server. Since it's a + text file (matches "*.txt"), its contents are translated to + cp850 on arrival, and it is saved with a cp850 name. + + mget /text /server:latin1 /local:utf8 *.txt + This command: + + + Tells C-Kermit that the server's files are encoded in ISO + 8859-1 Latin Alphabet 1. + + Tells C-Kermit to translate the incoming files into Unicode + UTF-8 for storage. + + Asks the server to send all ".txt" files in text mode. + + mget /server:latin1 /local:utf8 * + Tells Kermit to get all files from the server's directory, + switching between text and binary mode based on the filename. + The names of all the files are translated (to UTF-8 in this + case), but contents are translated (also to UTF-8) only for + text files. + + Note that any pair of 8-bit character sets is likely to have some + incompatibilities. Any characters in the source file that do not have + equivalents in the destination file's character set are converted to + question marks. This applies to both filenames and to text file + contents. + + Also note that the server's ability to accept special characters in + filenames depends on the particular server. For example: + + get Grüße.txt + + works with WU-FTPD, but: + + mget Grüß*.txt + + does not. + _________________________________________________________________ + + 3.7.3. RFC2640 + + [330]RFC2640, July 1999, specifies a method by which the FTP client + and server can negotiate the use of UTF8. However, RFC2640-capable + servers are rare to nonexistent at this writing, and in any case you + don't need them to be able to transfer text in UTF8. C-Kermit lets you + upload and download text files in any character set it knows about, + converting to or from any other character set it knows about, without + the knowledge, permission, or cooperation of the server, and + regardless of its capabilities. + + [ [331]Top ] [ [332]FTP Top ] [ [333]C-Kermit Home ] [ [334]Kermit + Home ] + _________________________________________________________________ + + 3.8. FTP Command Shortcuts + + C-Kermit's FTP client coexists with other C-Kermit functions by + requiring the "ftp" prefix for each FTP-related command: FTP OPEN, FTP + GET, FTP BYE, and so on. For interactive use, however, this can be + rather awkward and sometimes surprising, for example when a GET + command starts a Kermit GET rather than an FTP GET. In fact, many + Kermit commands might just as easily apply to an FTP connection: GET, + PUT (SEND), BYE, and CLOSE. The following command lets you choose how + these commands are interpreted: + + SET GET-PUT-REMOTE { AUTO, KERMIT, FTP } + Controls the orientation of GET, PUT, REMOTE and other + file-transfer and client/server commands that might apply to + either Kermit or FTP. The default setting is AUTO, meaning that + these commands apply to FTP if an FTP connection is open, and + to Kermit otherwise. KERMIT means they always apply to Kermit, + FTP means they always apply to FTP. + + Here is a complete list of affected commands: + + Kermit Command FTP Equivalent + (none) FTP [ OPEN ] + LOGIN FTP USER + LOGOUT FTP RESET + BYE FTP BYE + FINISH FTP BYE + CLOSE FTP BYE + HANGUP FTP BYE + BINARY FTP TYPE BINARY + TEXT (or ASCII) FTP TYPE ASCII + SEND (or PUT) FTP PUT + MSEND (or MPUT) FTP MPUT + RESEND FTP PUT /RECOVER + CSEND FTP PUT /COMMAND + GET FTP GET + MGET FTP MGET + REGET FTP GET /RECOVER + REMOTE HELP (RHELP) FTP HELP + REMOTE CD (RCD) FTP CD (CWD) + REMOTE PWD (RPWD) FTP PWD + REMOTE DIRECTORY (RDIR) FTP DIRECTORY + REMOTE DELETE (RDEL) FTP DELETE + REMOTE MKDIR (RMKDIR) FTP MKDIR + REMOTE RMDIR (RRMDIR) FTP RMDIR + REMOTE RENAME (RRENAME) FTP RENAME + REMOTE TYPE (RTYPE) FTP TYPE + REMOTE EXIT (REXIT) FTP BYE + + The commands in the right-hand column always access FTP. The commands + in the left column can access either Kermit protocol or FTP: + + * When GET-PUT-REMOTE is set to KERMIT, or to AUTO when there is no + FTP connection, the commands in the left-hand column access Kermit + protocol, and those right-hand column are required for FTP. + * When GET-PUT-REMOTE is set to FTP, or to AUTO when there is an + active FTP connection, the commands in the left-hand column access + the FTP connection and can not be used to access Kermit protocol. + In this case, if you want to be able to use both Kermit protocol + and the FTP connection, you must SET GET-PUT-REMOTE KERMIT, and + then use the FTP commands in the right-hand column to access the + FTP connection. + + Note that file-management commands such as DIRECTORY, DELETE, CD, PWD, + MKDIR, RMDIR, HELP, RENAME, COPY, TYPE, and so on, always apply + locally, no matter what kind of connection you have. This is the + opposite of most FTP clients, where these commands are intended for + the server, and require an "L" prefix for local execution (e.g. "dir" + gets a directory listing from the server, "ldir" gets a local + directory listing). To illustrate with the CD command and a typical + UNIX FTP client: + + Client Server Change Local Directory Change Remote Directory + FTP FTP lcd cd (cwd) + Kermit Kermit cd rcd, remote cd + Kermit FTP cd ftp cd, rcd, remote cd + + Also note that not all REMOTE commands are useful with FTP, since FTP + servers do not offer the corresponding functions. These include: + + * REMOTE ASSIGN - FTP servers don't have variables + * REMOTE COPY - FTP servers don't copy files + * REMOTE HOST - FTP servers don't execute host (shell) commands + * REMOTE KERMIT - FTP servers don't execute Kermit commands + * REMOTE PRINT - FTP servers don't print files + * REMOTE QUERY - FTP servers don't have variables + * REMOTE SET - FTP servers don't have Kermit settings + * REMOTE WHO - FTP servers don't send user lists + + Finally note that command shortcuts do not apply to the HELP command. + For help about an FTP command, use (for example) "help ftp delete", + not "help delete" or "help rdelete". + + [ [335]Top ] [ [336]FTP Top ] [ [337]C-Kermit Home ] [ [338]Kermit + Home ] + _________________________________________________________________ + + 3.9. Dual Sessions + + You can have an FTP session open at the same time as a regular Kermit + SET LINE or SET HOST (terminal) session. In this case, the default SET + GET-PUT-REMOTE AUTO setting should ensure that all "two-faced" + commands like GET, PUT, REMOTE, HANGUP, BYE, etc, apply to the Kermit + session, and all commands for the FTP session must include the FTP + prefix. To be absolutely certain, you can use SET GET-PUT-REMOTE + KERMIT. + + ftp foo.bar.baz.com + if fail ... + (log in) + set host foo.bar.baz.com + if fail ... + (log in) + + Now you have both an FTP and Telnet connection to the same host (of + course they could also be to different hosts, and you could also have + a direct or dialed serial connection instead of a Telnet connection). + Now assuming you have a Kermit server on the far end of the Kermit + connection: + + rcd incoming ; Changes Kermit server's directory (= REMOTE CD) + ftp cd incoming ; Changes FTP server's directory + put oofa.txt ; Sends a file on the Kermit connection + ftp put oofa.txt ; Sends a file on the FTP connection + bye ; Shuts down the Kermit connection + ftp bye ; Shuts down the FTP connection + + Note that PUT and SEND are synonyms for both FTP and Kermit + connections. + + You can also establish dual sessions on the Kermit command line: + + kermit -j host1 -9 host2 + + This makes a Telnet connection to host1 and an FTP connection to + host2. + + [ [339]Top ] [ [340]FTP Top ] [ [341]C-Kermit Home ] [ [342]Kermit + Home ] + _________________________________________________________________ + + 3.10. Automating FTP Sessions + + Most of Kermit's scripting features can be used to make and control + FTP sessions: FOR and WHILE loops, IF-ELSE and SWITCH constructions, + variables, arrays, built-in functions, and all the rest. You can't use + INPUT, MINPUT, OUTPUT, CLEAR, or SCRIPT on an FTP session, but these + are not needed since the FTP protocol is well defined. + + [343]CLICK HERE for an FTP scripting tutorial. + + 3.10.1. FTP-Specific Variables and Functions + + The following variable tells whether an FTP connection is open: + + \v(ftp_connected) + 1 if there is an active FTP connection, 0 if there isn't. + + The FTP OPEN command sets: + + \v(ftp_host) + The host to which the most recent FTP connection was made. + + \v(ftp_security) + The security method negotiated for the current FTP session. The + value is "NULL" when no security is used. See [344]3.2. Making + Secure FTP Connections. + + \v(ftp_server) + The OS type (UNIX, VMS, etc) of the FTP server host. + + The FTP USER command (or FTP OPEN /USER:, or FTP with automatic login) + sets: + + \v(ftp_loggedin) + 1 if you are logged in to an FTP server, 0 if you are not. + + The current COMMAND-PROTECTION-LEVEL and DATA-PROTECTION-LEVEL values + are reflected in: + + \v(ftp_cpl) + \v(ftp_dpl) + The values are "clear", "confidential", "safe" or "private". + See [345]3.2. Making Secure FTP Connections. + + The FTP GET-PUT-REMOTE setting is reflected in: + + \v(ftp_getputremote) + The values are "auto", "ftp", or "kermit". + + Every FTP command sets the \v(success) variable, as well as the + following two FTP-specific variables: + + \v(ftp_code) + The standardized numeric FTP protocol code from the server's + response to the last client command, a 3-digit decimal number + defined in [346]RFC959. Briefly: + + 1xx = Positive Preliminary Reply + 2xx = Positive Completion Reply + 3xx = Positive Intermediate Reply + 4xx = Transient Negative Completion Reply + 5xx = Permanent Negative Completion Reply + + \v(ftp_message) + The text message, if any, from the server's response to the + last client command. If the most recent response had multiple + lines, this variable has only the final line. These messages + are not standardized and vary in format and content from server + to server. Synonym: \v(ftp_msg). + + FTP file transfers set the regular Kermit transfer status variables: + + \v(cps) Characters per second of most recent transfer. + \v(filespec) File specification used in most recent transfer. + \v(fsize) Size of file most recently transferred. + \v(tfsize) Total size of file group most recently transferred. + \v(xferstatus) Status of most recent transfer (0 = success, 1 = failure). + \v(tftime) Elapsed time of most recent transfer, in seconds. + + During an FTP transfer, the per-file variables are: + + \v(filename) Name of current file. + \v(filenumber) Ordinal file number in group (1, 2, 3, ...) + _________________________________________________________________ + + 3.10.2. Examples + + Let's begin with a simple example showing how to log in, send some + files, and log out: + + define error if fail { ftp bye, stop 1 Error: \%1 } + set transact brief + log t + ftp ftp.xyzcorp.com /anonymous + if fail stop 1 Connection failed + if not \v(ftp_loggedin) stop 1 Login failed + ftp cd incoming + error {ftp cd} + cd upload + error {local cd} + ftp put /delete * + error {put} + ftp bye + + First we define an error handling macro to be used after the + connection is made. Then we set up a brief-format transaction log to + keep a record of our file transfers. Then we make a connection to the + host and log in anonymously. The "if fail" command checks whether the + connection was made. The "if not" command checks whether login was + successful. Obviously the script should not continue unless both tests + succeed. + + Next we change to the server's 'incoming' directory and to our own + 'upload' directory, and send all the files that are in it (they can be + any mixture of text and binary files), deleting each source file + automatically after it is successfully uploaded. Each of these + operations is checked with the ERROR macro, which prevents the script + from continuing past a failure. + + Finally we close the FTP session with the "bye" command. + + Just like any other Kermit script, this one can be used in many ways: + + * It can be stored in a file, and Kermit can be told to TAKE the + file. + * In UNIX, it can be a "[347]kerbang" script and therefore run + directly from the shell prompt or as a cron job. + + We could have used command shortcuts like "rcd", "put", and "bye", but + since they can be ambiguous under certain circumstances, it is better + to avoid them in scripts; they are intended mainly for convenience + during interactive use. However, if you wish to use the shortcuts in a + script, you can do it this way (error handling omitted for brevity): + + local \%t ; Declare a local temporary veriable + assign \%t \v(ftp_getputremote) ; Save current FTP GET-PUT-REMOTE setting + set ftp get-put-remote ftp ; Choose FTP orientation + ftp xyzcorp.com /anonymous ; Open an FTP connection + get oofa.txt ; GET a file + put foo.bar ; PUT a file + rdel yesterday.log ; Delete a file on the server + bye ; Log out and disconnect from server. + set ftp get-put-remote \%t ; Restore previous GET-PUT-REMOTE setting + + Of course, FTP scripts can also be written as macros. This lets you + pass parameters such as hostnames, usernames, and filenames to them: + + define doftpget { + if < \v(argc) 4 end 1 Usage: \%0 host user remotefile [ localfile ] + ftp \%1 /user:\%2 + if fail end 1 FTP OPEN \%1 failed + if not \v(ftp_loggedin) end 1 FTP LOGIN failed + ftp get {\%3} {\%4} + if fail end 1 FTP GET \%3 failed + ftp bye + } + + Add this definition to your Kermit customization file, and it will + always be available when you start Kermit. This macro lets you + download a file with FTP by giving a single command, e.g.: + + doftpget xyzcorp.com anonymous oofa.txt + _________________________________________________________________ + + 3.10.3. Automating Secure FTP Sessions + + Often when making secure connections, you are prompted interactively + for certain information or permission to proceed. These prompts can + stop an automated procedure. To avoid them, you must give the + appropriate commands to disable them, and/or supply the prompted-for + information beforehand. Here are a few hints: + + * Make sure that SET TAKE ERROR and SET MACRO ERROR are both OFF. + This is the default, but in case you have set either one of these + ON in your script or initialization file, this makes the script + halt on any kind of error. Normally you would want to check each + operation for success or failure and take appropriate action. + * On SSL and TLS connections, you may be asked whether it is OK to + proceed with a connection to server that presents a self-signed + certificate. You can use the SET AUTHENTICATION SSL (or TLS) + VERIFY or SET AUTH SSL (or TLS) CERTS-OK commands to avoid this + prompt by not requesting a certificate from the peer. + * (More to be added...) + + [ [348]Top ] [ [349]FTP Top ] [ [350]FTP Script Tutorial ] [ + [351]C-Kermit Home ] [ [352]Kermit Home ] + _________________________________________________________________ + + 3.11. Advanced FTP Protocol Features + + The remainder of the FTP documention (through the end of Section 3) is + new to C-Kermit 8.0.206, but we leave it in black to prevent + headaches. Except for titles. + * [353]TERMINOLOGY + * [354]FEATURE NEGOTIATION + * [355]USING MGET: NLST VERSUS MLSD + * [356]EXAMPLES + * [357]REFERENCES + + The new releases of [358]C-Kermit (8.0.206) and [359]Kermit 95 (2.1) + support new FTP protocol features from RFC 2389 as well as most of + what's in the Elz and Hethmon Extensions to FTP Internet Draft (see + [360]References). Some of these features, such as SIZE (request a + file's size), MDTM (request file's modification time), and REST + (restart interrupted transfer) have been widely implemented in FTP + clients and servers for years (as well as in the initial release of + the Kermit FTP clients). Others such as FEAT and MLSD are rarely seen + and are new to the upcoming Kermit releases. TVFS (Trivial Virtual + File Store) is supported implicitly, and the UTF-8 character-set is + already fully supported at the protocol and data-interchange level. + + For Kermit users, the main benefit of the new FTP protocol extensions + is the ability to do recursive downloads. But the extensions also + introduce complications and tradeoffs that you should be aware of. Of + course Kermit tries to "do the right thing" automatically in every + case for backwards compatibility. But (as noted later) some cases are + inherently ambiguous and/or can result in nasty surprises, and for + those situations new commands and switches are available to give you + precise control over Kermit's behavior, in case the defaults don't + produce the desired results. + _________________________________________________________________ + + 3.11.1. Terminology Command-line FTP clients such as Kermit (as well + as the traditional FTP programs found on Unix, VMS, ..., even Windows) + have commands like PUT, MPUT, GET, MGET, and BYE, which they convert + into zero or more FTP protocol commands, such as NLST, RETR, QUIT. For + clarity, we'll use "command" to refer to commands given by the user to + the FTP client, and "directive" for FTP protocol commands sent by the + FTP client to the FTP server. + _________________________________________________________________ + + 3.11.2. Feature Negotiation New FTP protocol features are negotiated + by the client sending a FEAT directive and the server responding with + a list of (new) features it supports, or else with an error indication + if it does not support the FEAT directive at all, in which case the + client has to guess which new features it supports (Kermit guesses + that it supports SIZE and MDTM but not MLST). Note that the MLST + feature includes MLSD, which is not listed separately as a feature. + + Guessing is nice when it works, but sometimes it doesn't, and some FTP + servers become confused when you send them a directive they don't + understand, or they do something you didn't want, sometimes to the + point of closing the connection. For this reason, Kermit lets you + override default or negotiated features with the following new + commands: + + FTP { ENABLE, DISABLE } FEAT + Enables or disables the automatic sending of a FEAT directive + upon connection to an FTP server. Note that + FTP [ OPEN ] /NOINIT also inhibits sending the FEAT directive + (and several others) for the connection being OPEN'd, but + without necessarily disabling FEAT for subsequent connections + in the same Kermit instance. FEAT is ENABLED by default, in + which case many FTP servers are likely to reply: + +500 'FEAT': command not understood + + which is normally harmless (but you never know). (In C-Kermit + 8.0.208, this error message is suppressed unless you SET FTP + DEBUG ON.) + + FTP ENABLE { MDTM, MLST, SIZE } + Enables the given directive for implicit use by the FTP GET and + MGET commands in case it has been disabled or erroneously + omitted by the server in its FEAT response. Note: MLSD can be + used in the FTP ENABLE and DISABLE commands as a synonym for + MLST. YOU MUST GIVE THIS COMMAND AFTER MAKING THE FTP + CONNECTION. + + FTP DISABLE { MDTM, MLST, SIZE } + Disables implicit use of the given directive by GET or MGET in + case it causes problems; for example, because it makes + multifile downloads take too long or the server announces it + erroneously or misimplements it. Use DISABLE FEAT before making + a connection to prevent Kermit from sending the FEAT directive + as part of its initial sequence. Note that disabling FEAT, + SIZE, or MDTM does not prevent you from executing explicit FTP + FEATURES, FTP SIZE, or FTP MODTIME commands. Also note that + disabling SIZE prevents PUT /RESTART (recovery of interrupted + uploads) from working. YOU MUST GIVE THIS COMMAND AFTER MAKING + THE FTP CONNECTION. + + To enable or disable more than one feature, use multiple FTP ENABLE or + FTP DISABLE commands. The SHOW FTP command shows which features are + currently enabled and disabled. + + FTP FEATURES + This command sends a FEAT directive to the server. In case you + have been disabling and enabling different features, this + resynchronizes Kermit's feature list with the server's. If the + server does not support the FEAT directive, Kermit's feature + list is not changed. + + FTP OPTIONS directive + Informational only: the server tells what options, if any, it + supports for the given directive, e.g. MLST. Fails if the + server does not support the OPTS directive or if the directive + for which options are requested is not valid. The directive is + case-insensitive. + + FTP SIZE filename + Sends a SIZE directive to the server for the given file. The + filename must not contain wildcards. The server responds with + an error if the file can't be found, is not accessible, or the + SIZE directive is not supported, otherwise with the length of + the file in bytes, which Kermit displays and also makes + available to you in its \v(ftp_message) variable. If the + directive is successful, Kermit (re-)enables it for internal + use by the GET and MGET directives on this connection. + + FTP MODTIME filename + Works just like the SIZE directive except it sends an MDTM + directive. Upon success, the server sends modification + date-time string, which Kermit interprets for you and also + makes available in its \v(ftp_message) variable. + + Whenever a SIZE or MDTM directive is sent implicitly and rejected by + the server because it is unknown, Kermit automatically disables it. + _________________________________________________________________ + + 3.11.3. Using MGET: NLST versus MLSD When you give an MGET command to + an FTP client, it sends a request to the FTP server for a list of + files, and then upon successful receipt of the list, goes through it + and issues a RETR (retrieve) directive for each file on the list (or + possibly only for selected files). + + With the new FTP protocol extensions, now there are two ways to get + the list of files: the NLST directive, which has been part of FTP + protocol since the beginning, and the new MLSD directive, which is new + and not yet widely implemented. When NLST is used and you give a + command like "mget *.txt", the FTP client sends: + +NLST *.txt + + and the server sends back a list of the files whose names match, e.g. + +foo.txt +bar.txt +baz.txt + + Then when downloading each file, the client sends SIZE (if it wants + have a percent-done display) and MDTM (if it wants to set the + downloaded file's timestamp to match that of the original), as well as + RETR (to retrieve the file). + + But when MLSD is used, the client is not supposed to send the filename + or wildcard to the server; instead it sends an MLSD directive with no + argument (or the name of a directory), and the server sends back a + list of all the files in the current or given directory; then the + client goes through the list and checks each file to see if it matches + the given pattern, the rationale being that the user knows only the + local conventions for wildcards and not necessarily the server's + conventions. So with NLST the server interprets wildcards; with MLSD + the client does. + + The interpretation of NLST wildcards by the server is not + necessarily required or even envisioned by the FTP protocol + definition (RFC 959), but in practice most clients and servers work + this way. + + The principal advantage of MLSD is that instead of sending back a + simple list of filenames, it sends back a kind of database in which + each entry contains a filename together with information about the + file: type, size, timestamp, and so on; for example: + +size=0;type=dir;perm=el;modify=20020409191530; bin +size=3919312;type=file;perm=r;modify=20000310140400; bar.txt +size=6686176;type=file;perm=r;modify=20001215181000; baz.txt +size=3820092;type=file;perm=r;modify=20000310140300; foo.txt +size=27439;type=file;perm=r;modify=20020923151312; foo.zip +(etc etc...) + + (If the format of the file list were the only difference between NLST + and MLSD, the discussion would be finished: it would always be better + to use MLSD when available, and the MGET user interface would need no + changes. But there's a lot more to MLSD than the file-list format; + read on...) + + The client learns whether the server supports MLSD in FEAT exchange. + But the fact that the server supports MLSD doesn't mean the client + should always use it. It is better to use MLSD: + + * On connections where the server imposes a time penalty for every + command, e.g. the Red Hat Rawhide server. With MLSD, the client + needs to send only one command (RETR) per file, whereas NLST + requires three (SIZE, RETR, and MDTM). Suppose there is a + 30-second delay for each command and 1000 files are to be fetched; + in that case, MLSD saves 60,000 seconds = 1000 minutes = 16 hours + and 40 minutes. + * For recursive downloads since there is no dependable way to + download directory trees with NLST. + + But it is better to use NLST: + + * If you want only a couple short files out of a large directory. In + this case, NLST is the better choice since the server sends a list + of only the files you want, not a list of (say) a million files, + which can make a big difference on slow connections. For example, + suppose your wildcard matches three files of 1K each, but the + million-file listing is 80MB long, and your connection is through + a modem. The overhead of using MLSD is practically infinite. + * If the server supports wildcarding features not known to the + client, but that can be used to achieve desirable effects + otherwise unobtainable, such as "[dir...]*.txt" in VMS or AOS/VS + "except" clauses. + * If you have been given a wildcard string by an FTP site + administrator for fetching a specific group of files out of a + larger directory, e.g. "mget ck[cuw]*.[cwh] makefile", that is + expected to work with any client (an FTP site administrator can't + be expected to know the wildcard syntax of every FTP client). + + But when using MLSD there are complications: + + * MLSD wants either a blank argument (meaning the current directory) + or else the name of a specific directory. The client must not send + it a wildcard or a filename. + * But if the user's command is "mget xxx", how does the client know + whether to send "xxx" in the MLSD directive? It might be the name + of a directory on on the server, in which case it should be sent, + or it might be the name of a file on the server (or a wildcard), + in which case it must not be sent. Since the client knows its own + wildcard syntax, then in most cases it would be right to send + "MLSD" with no argument if xxx is wild, and to send "MLSD xxx" if + it is not. + * But suppose the server's file system allows filename characters + that correspond with the client's wildcard syntax? For example: + "[abc]" could be either a valid VMS directory name or a wildcard + pattern used by the FTP client. What should the client do with + "mget [abc]"? In this case there must be a way for the user to + force sending the MGET argument as the MLSD argument. + * If "xxx" is a regular file in the server's current directory, + "mget xxx" works with NLST but not with MLSD. + + To further complicate matters, NLST can (in theory) work just like + MLSD: if sent with a blank argument or a directory name, it is + supposed to return a complete list of files in the current or given + directory, which the client can match locally against some pattern. It + is not known if any FTP server or client does this but nevertheless, + it should be possible since this behavior can be inferred from RFC + 959. + + In view of these considerations, and given the need to preserve the + traditional FTP client command structure and behavior so the software + will be usable by most people: + + 1. The MGET command should produce the expected result in the common + cases, regardless of whether NLST or MLSD is used underneath. + 2. For anomalous cases, the user needs a way to control whether the + MGET argument is sent to the server or kept for local use. + 3. At the same time, the user might need a way to send a directory + name to the server, independent of any wildcard pattern. + 4. The user needs a way to force NLST or MLSD for a given MGET + command. + + By default, Kermit's MGET command uses MLSD if MLST is reported by the + server in its FEAT list. When MLSD is used, the filespec is sent to + the server if it is not wild (according to Kermit's own definition of + "wild" since it can't possibly know the server's definition). If the + filespec is wild it is held for local use to select files from the + list returned by the server. If MLST is not reported by the server or + is disabled, Kermit sends the MGET filespec with the NLST directive. + + The default behavior can be overridden globally with FTP DISABLE MLST, + which forces Kermit to use NLST to get file lists. And then for + situations in which MLSD is enabled, the following MGET switches can + be used to override the defaults for a specific MGET operation: + + /NLST + Forces the client to send NLST. Example: + +mget /nlst foo.* + + /MLSD + Forces the client to send MLSD (even if MLST is disabled). + Example: + +mget /mlsd foo.* + + /MATCH:pattern + When this switch is given, it forces the client to hold the + pattern for local use against the returned file list. If a + remote filespec is also given (e.g. the "blah" in "mget + /match:*.txt blah"), then it is sent as the NLST or MLSD + argument, presumably to specify the directory whose files are + to be listed. When the /MATCH switch is not given, the MGET + filespec is sent to the server if the directive is NLST or if + the filespec is not wild. Examples: + + Command: With NLST: With MLSD: + mget NLST MLSD + mget *.txt NLST *.txt MLSD + mget foo NLST foo MLSD foo + mget /match:*.txt NLST MLSD + mget /match:*.txt foo NLST foo MLSD foo + + In other words, the pattern is always intepreted locally unless MGET + uses NLST and no /MATCH switch was given. + _________________________________________________________________ + + 3.11.4. Examples + + 3.11.4.1. Downloading a Single File + + There are no choices here, just use the FTP GET command. Kermit always + sends the RETR directive, and possibly SIZE and/or MDTM. The small + advantage of using MLST in this case is outweighed by the risk and + effort of coding a special case. + + 3.11.4.2. Downloading a Group of Files from a Single Directory + + This case presents tradeoffs, especially on slow connections: + + * For downloading all or most of the files in a directory, MLSD is + better because it eliminates the need to send SIZE and MDTM for + each file. No special actions are required in this case; Kermit + uses MLSD automatically if the server supports it (unless you have + disabled it). + * For a small number of files from a large directory, NLST is better + because it bypasses downloading of a potentially huge file list + prior to the files themselves. If you have a connection to a + server that supports MLSD, use the /NLST switch to force NLST: + +mget /nlst t[1234].h + + * If the server supports MLSD but does not support separate SIZE or + MDTM directives, and you need the size and/or timestamp + information, MLSD is better; no special actions required. + * If the server supports MLSD but does not support the "size" and + "modify" facts, but it does support the SIZE or MDTM directives, + and you need the size and/or timestamp information, NLST is + better. + + 3.11.4.3. Downloading a Directory Tree + + MLSD is the only choice for recursive downloads; they rarely, if ever, + work with NLST (the few cases where they do work rely on + extra-protocol "secret" notations for the NLST argument). No special + actions are required to force MLSD when the server supports it, unless + you have disabled it. Examples: + + MGET /RECURSIVE + This tells the server to send all files and directories in the + tree rooted at its current directory. + + MGET /RECURSIVE *.txt + This tells the server to send all *.txt files in the tree + rooted at its current directory. + + MGET /MLSD /RECURSIVE *.txt + Same as the previous example but forces Kermit to send MLSD in + case it was disabled, or in case the server is known to support + it even though it did not announce it in its FEAT listing. + + MGET /RECURSIVE /MATCH:*.zip archives + Tells the server to send all ZIP files in the tree rooted at + its "archives" directory. + + MGET /RECURSIVE /MATCH:* [abc] + The server is running on VMS and you want it to send all the + files in the directory tree rooted at [ABC]. But since "[abc]" + looks just like a wildcard, you have to include a /MATCH: + switch to force Kermit to send "[abc]" as the MLSD argument. + + In all cases in which the /RECURSIVE switch is included, the server's + tree is duplicated locally. + + Although MLSD allows recursion and NLST does not, the MLSD + specification places a heavy burden on the client; the obvious, + straightforward, and elegant implementation (depth-first, the one + that Kermit currently uses) requires as many open temporary files + as the server's directory tree is deep, and therefore client + resource exhaustion -- e.g. exceeding the maximum number of open + files -- is a danger. Unfortunately MLSD was not designed with + recursion in mind. (Breadth-first traversal could be problematic + due to lack of sufficient navigation information.) + + Of course all of Kermit's other MGET switches can be used too, e.g. + for finer-grained file selection (by date, size, etc), for moving or + renaming files as they arrive, to override Kermit's automatic per-file + text/binary mode switching, to pass the incoming files through a + filter, to convert text-file character sets, and so on. + + 3.11.4.4. NLST/MLSD Summary Table + + Here's a table summarizing MGET behavior when the server supports both + NLST and MLSD. /NLST and /MLSD switches are included for clarity to + indicate which protocol is being used, and the expected effects. In + practice you can omit the /NLST and /MLSD switches and the Kermit + client chooses the appropriate or desired protocol as described above. + Sample commands presume a Unix file system on the server, but of + course the server can have any file system or syntax at all. + + User's Command FTP Sends Remarks + mget /nlst NLST Gets a list of all the files in the server's current + and downloads each file. The list includes names only, so Kermit also + must send SIZE and MDTM directives if size and timestamp information + is required (this is always true of NLST). Sending NLST without an + argument is allowed by the RFC959 NLST definition and by the Kermit + FTP client, but might not work with other clients, and also might not + work with every server. + mget /nlst foo NLST foo If "foo" is a directory, this gets a list of + all the files from the server's "foo" directory and downloads each + file; otherwise this downloads the file named "foo" (if any) from the + server's current directory. + mget /nlst *.txt NLST *.txt Gets a list of the files in the server's + current directory whose names match the pattern *.txt, and then + downloads each file from the list. Because we are using NLST, we send + the filespec (*.txt) to the server and the server interprets any + wildcards. + mget /nlst foo/*.txt NLST foo/*.txt Gets a list of the files in the + server's "foo" directory whose names match the pattern *.txt, and then + downloads each file from the list (server interprets wildcards). + mget /nlst /match:*.txt NLST Gets a list of all the files in the + server's current directory and then downloads each one whose name + matches the pattern *.txt (client interprets wildcards). + mget /nlst /match:*.txt foo NLST foo Gets a list of all the files in + the server's "foo" directory and then downloads each one whose name + matches the pattern *.txt (client interprets wildcards). + mget /mlsd MLSD Gets a list of all the files from the server's current + directory and then downloads each one. The list might include size and + timestamp information, in which case Kermit does not need to send SIZE + and MDTM directives for each file (this is always true of MLSD). + mget /mlsd foo MLSD foo Gets a list of all the files from the server's + "foo" directory (where the string "foo" does not contain wildcards) + and then downloads each one. If "foo" is a regular file and not a + directory, this command is supposed to fail, but some servers have + been observed that send the file. + mget /mlsd *.txt MLSD Gets a list of all the files from the server's + current directory and then downloads only the ones whose names match + the pattern "*.txt". Because we are using MLSD and the MGET filespec + is wild, we do not send the filespec to the server, but treat it as + though it had been given in a /MATCH: switch and use it locally to + match the names in the list. + mget /mlsd foo/*.txt MLSD This one won't work because MLSD requires + that the notions of server directory and filename-matching pattern be + separated. However, the client, which can't be expected to know the + server's file-system syntax, winds up sending a request that the + server will (or should) reject. + mget /mlsd /match:*.txt MLSD Gets a list of all the files from the + server's current directory and then downloads only the ones whose + names match the pattern "*.txt" (client interprets wildcards). + mget /mlsd /match:*.txt foo MLSD foo If "foo" is a directory on the + server, this gets a list of all the files from the server's "foo" + directory and then downloads only the ones whose names match the + pattern "*.txt" (client interprets wildcards). This leaves the server + CD'd to the "foo" directory; there's no way the client can restore the + server's original directory because MLSD doesn't give that + information, and since the client can not be expected to know the + server's file-system syntax, it would not be safe to guess. If "foo" + is a regular file, MLSD fails. + mget /mlsd foo bar MLSD This one is problematic. You're supposed to be + able to give MGET a list a filespecs; in this case we name two + directories. The client must change the server's directory to "foo" to + get the list of files, and then the files themselves. But then it has + no way to return to the server's previous directory in order to do the + same for "bar", as explained in the previous example. + mget /mlsd /match:* [abc] MLSD [abc] Including a /MATCH: switch forces + [abc] to be sent to the server even though the client would normally + think it was a wildcard and hold it for local interpretation. In this + example, [abc] might be a VMS directory name. + mget /mlsd /match:* t*.h MLSD t*.h Contrary to the MLSD specification, + some MLSD-capable FTP servers do interpret wildcards. This form of the + MGET command can be used to force a wildcard to be sent to the server + for interpretation. + + When MLSD is used implicitly (that is, without an /MLSD switch given + to force the use of MLSD) and an MGET command such as "mget foo/*.txt" + fails, Kermit automatically falls back to NLST and tries again. + _________________________________________________________________ + + 3.11.5. References + + 1. Postel, J., and J. Reynolds, File Transfer Protocol (FTP), RFC + 959, October 1985: [361]ftp://ftp.isi.edu/in-notes/rfc959.txt. + 2. Hethmon, P, and R. Elz, Feature negotiation mechanism for the File + Transfer Protocol, RFC 2389, August 1998: + [362]ftp://ftp.isi.edu/in-notes/rfc2389.txt. + 3. Elz, R, and P. Hethmon, Extensions to FTP, Internet Draft + draft-ietf-ftpext-mlst-16.txt, September 2002: + [363]http://www.ietf.org/internet-drafts/draft-ietf-ftpext-mlst-16 + .txt. + 4. [364]The Kermit FTP Client (overview). + + [ [365]Top ] [ [366]FTP Top ] [ [367]C-Kermit Home ] [ [368]Kermit + Home ] + __________________________________________________________________________ + +4. FILE SCANNING + + A new feature called file scanning is used in various contexts to + determine if a file is text or binary, and if it is text, what kind of + text. The overhead of file scanning is surprisingly tolerable, usually + about a quarter second per file. File scanning is now used instead of + filename patterns unless you SET FILE SCAN OFF, which restores the + previous behavior. + + The primary benefit of file scanning is in file transfer. For all + practical purposes, now you can stop worrying about whether a file + should be sent in binary or text mode, or about sending mixtures of + text and binary files in a single operation, or configuring and + fine-tuning your lists of binary-file and text-file name patterns: now + it all just works. + + File scanning is done by the file sender, which determines the type of + each file before it sends it and informs the receiver (Kermit or FTP + server) of the type. File scanning is NOT done by the receiver, + because it is the sender's responsibility to determine each file's + type, send the file in the right mode, and inform the receiver of the + mode. If both transfer partners are capable of this (or any other) + form of automatic text/binary mode switching, then files can be sent + in both directions with no worries about corruption due to + inappropriate transfer mode. (As noted in [369]Section 3, FTP servers + don't do this, so this discussion does not apply when using Kermit to + download from an FTP server.) + + The rest of this section is mainly for the curious. If you don't read + it and simply accept all defaults, every file you send should go in + the appropriate mode automatically. As always, however, for + character-set translation to work for 7- and 8-bit character-set + files, the appropriate SET FILE CHARACTER-SET command(s) must have + been executed to identify their encoding (Kermit's default file + character-set is neutral ASCII except on platforms like HP-UX or + DG/UX, where the default file character-set is known). And of course, + receiving is another matter -- obviously the other Kermit must also + send each file in the appropriate mode. + + Scanning is more reliable than filename patterns simply because + filenames are not reliable indicators of the file's contents. Classic + examples include ".doc" files, which are binary if Microsoft Word + documents but text on most other platforms, and ".com" files, which + are binary on DOS and Windows but text on VMS. Anyway, nobody knows + the naming conventions (if any) of all the applications (and persons!) + on your computer. Scanning, on the other hand, determines each file's + type by inspecting its contents rather than just looking at its name. + + Also, file patterns -- even when they work as intended -- categorize + each file only as text or binary, whereas file scanning can make finer + distinctions: + + BINARY + Binary data, not to be converted in any way. Examples include + binary machine code (executable programs), graphics images + (GIF, JPG, etc), compressed files (Z, GZ, etc), archives and + packages (ZIP, TAR, RPM, etc), object files and libraries (OBJ, + DLL, etc). + + 7-BIT TEXT + Text encoded in a 7-bit character set such as ASCII or one of + the ISO 646 national versions. Kermit has no way to tell which + character is used, only that it's 7-bit text. Typical examples + include program source code, README files, Perl or Kermit + scripts, plain-text email, HTML, TeX, and various textual + encodings of binary files: Hex, Base64, etc. When sending such + files, the FILE DEFAULT 7BIT-CHARACTER-SET is used as the file + character-set, and then the appropriate transfer character set + is chosen from the associations list (ASSOCIATE, SHOW + ASSOCIATIONS). + + 8-BIT TEXT + Text encoded in an 8-bit character set such as Latin-1, + Latin-2, Latin/Hebrew, Latin/Cyrillic, KOI8, HP-Roman8, JIS X + 0208, Code Page 437, or Code Page 1252. Again, Kermit has no + way of knowing which particular set is in use, only that it's + 8-bit text. When sending such files, the FILE DEFAULT + 8BIT-CHARACTER-SET is used as the file character-set, and then + the appropriate transfer character set is chosen from the + associations list. + + UCS2 TEXT + Unicode in its basic form, 16 bits (2 octets) per character. + When sending such files, UCS2 is the file character-set and the + byte order is identified automatically; the appropriate + transfer character set is chosen from the associations list. + Normally this would be UTF8. UTF-16 is not supported yet; + Kermit's Unicode translations are restricted to Plane 0, the + Base Multilingual Plane (BMP). + + UTF8 TEXT + Unicode in its 8-bit transformation format. When sending such + files, UTF8 is the file character-set; the appropriate transfer + character set is chosen from the associations list, normally + UCS2 or UTF8. + + File scanning is available in UNIX C-Kermit, in K-95, and to a limited + extent, in VMS C-Kermit (full scanning is problematic in VMS because + even plain-text files might contain binary record-format information). + The relevant commands are: + + SET TRANSFER MODE { AUTOMATIC, MANUAL } + Tells whether the file-transfer mode (text or binary) should be + set by automatic or "manual" means. AUTOMATIC is the default, + which allows any of the automatic methods that are enabled to + do their jobs: FILE SCAN, FILE PATTERNS, peer recognition, etc. + MANUAL lets you control the transfer mode with the SET FILE + TYPE commands. As always, /TEXT and /BINARY switches on your + file-transfer commands override all other methods; if you give + one of these switches, scanning is not done. SHOW TRANSFER + displays the current TRANSFER MODE setting. + + SET FILE SCAN { ON [ number ], OFF } + Turns this feature on and off. It's ON by default. When OFF, + the previous rules apply (SET FILE PATTERNS, etc). When ON is + given, you can also specify a number of bytes to be scanned. + The default is 49152 (= 48K). If a negative number is given, + the entire file is scanned, no matter how big, for maximum + certainty (for example, a PostScript file that appears to be + plain text might include an embedded graphic past the normal + scanning limit). SHOW FILE displays the current FILE SCAN + setting. + + SET FILE DEFAULT 7BIT-CHARACTER-SET name + Tells the 7-bit character-set to use if scanning identifies a + 7-bit text file, e.g. GERMAN. SHOW FILE displays the current + SET FILE DEFAULT settings. So does SHOW CHARACTER-SETS. + + SET FILE DEFAULT 8BIT-CHARACTER-SET name + Tells the 8-bit character-set to use if scanning identifies an + 8-bit text file, e.g. LATIN1. SHOW FILE and SHOW CHARACTER-SET + display this. + + ASSOCIATE FILE-CHARACTER-SET fcs tcs + When sending files and a file character-set (fcs) is identified + by scanning, this tells C-Kermit which transfer character-set + (tcs) to translate it to. It also allows C-Kermit to set the + appropriate transfer character-set automatically whenever you + give a SET FILE CHARACTER-SET command. + + ASSOCIATE TRANSFER-CHARACTER-SET tcs fcs + When receivinging files and a file arrives whose transfer + character-set (tcs) is announced by the sender, this command + tells C-Kermit which file character-set (fcs) to translate it + to. It also allows C-Kermit to set the appropriate file + character-set whenever you give a SET TRANSFER CHARACTER-SET + command. + + SET FILE CHARACTER-SET name + When given for a 7-bit set, also sets FILE DEFAULT + 7BIT-CHARACTER-SET to the same set. When given for an 8-bit + set, also sets FILE DEFAULT 8BIT-CHARACTER-SET to the same set. + If an ASSOCIATE FILE-CHARACTER-SET command has been given for + this set, also sets the corresponding transfer character-set. + + DIRECTORY /XFERMODE [ filespec ] + Performs a file scan of the given files, listing the result for + each file. If FILE SCAN is OFF but PATTERNS are ON, the result + shown according to the current FILE TEXT-PATTERNS and + BINARY-PATTERNS, and are restricted to (B) and (T). When FILE + SCAN is ON, the results are: + + (B) Binary + (T)(7BIT) Text: 7-bit + (T)(8BIT) Text: 8-bit + (T)(UTF8) Text: Unicode UTF8 + (T)(UCS2BE) Text: Unicode UCS2 Big Endian + (T)(UCS2LE) Text: Unicode UCS2 Little Endian + + So you can use DIR /XFER to get a preview of how each file in a + selected group will be transferred. Everything to the right of + the (B) or (T) is new. If FILE SCAN is OFF, you only get the + (B) or (T) as before. + + Note: Big and Little Endian refer to the ordering of bytes + within a computer word. Big Endian architecture is standard and + is used on most non-PC computers. Little Endian architecture is + used on PCs. + + To illustrate file-transfer with scanning, suppose you have a + directory containing a mixture of text and binary files, and each text + file can be 7-bit German ISO 646, 8-bit Latin-1, or Unicode in any of + the following forms: UCS2 Little Endian, UCS2 Big Endian, or UTF8 + ([370]UTF-16 is not supported yet). Assuming all the built-in defaults + are in effect, the following three commands do the job: + + set file char german ; This sets the default for 7-bit text files + set file char latin1 ; This sets the default for 8-bit text files + send * + + Each file is sent in the appropriate mode (text or binary), with text + files converted to the appropriate transfer character-set and labeled + so the receiver can convert them according to its own local + conventions. + + By the way, what if you want to inhibit character-set translation but + still allow automatic text/binary mode switching? Previously, you + could simply SET TRANSFER CHARACTER-SET TRANSPARENT. But now with file + scanning, the file and transfer character-sets are set automatically + per file. A new command was added for this purpose: + + SET TRANSFER TRANSLATION { ON, OFF } + Enables and disables file-transfer character-set translation. + It is enabled by default. + + When TRANSFER TRANSLATION is OFF but FILE SCAN is ON, files are still + scanned to see if they are text or binary, but no character-set + translation is done when they text: only the normal record-format + conversion. + + Like all SET commands, SET TRANSFER TRANSLATION is global and + persistent. You can also force a particular file-transfer command + (SEND, MSEND, GET, RECEIVE, TRANSMIT, etc) to not translate without + affecting the global translation settings by including the new + /TRANSPARENT switch, e.g. + + send /transparent oofa.txt + + As of C-Kermit 8.0.206, SET TRANSFER CHARACTER-SET TRANSPARENT implies + SET TRANSFER TRANSLATION OFF. + + File scanning is also used in the TYPE command. The source file type + and character set are determined as above, and then the file is + automatically converted to your display character-set, line by line. + In Kermit 95, the display character-set is Unicode, perhaps converted + to your current console code page; in other versions of C-Kermit, it + is your current file character-set. Thus if you have the following set + appriately: + + SET FILE CHARACTER-SET (necessary in Unix but not K95) + SET FILE DEFAULT 7BIT CHARACTER-SET + SET FILE DEFAULT 8BIT CHARACTER-SET + + then you should be able to TYPE any text file and see something + reasonable. For example, in Unix, if your DEFAULT 7BIT-CHARACTER-SET + is ITALIAN and your DEFAULT 8BIT-CHARACTER-SET is LATIN1, and your + FILE CHARACTER-SET is LATIN1, you can TYPE an Italian ISO 646 file, a + Latin-1 file, or any kind of Unicode file, and have it translated + automatically to Latin-1 for your display. + + In the GUI version of Kermit 95, you can see mixtures of many + different scripts if the file is UTF8 or UCS2: Roman, Cyrillic, + Hebrew, Greek, Armenian, Georgian, etc, all on the same screen at + once. + + File scanning also adds a new criterion for file selection, i.e. to + select only text (or binary) files. Several commands now include a new + switch, /TYPE:{BINARY,TEXT,ALL}. BINARY means select only binary + regular files (not directories). TEXT means select only text files. + ALL means don't scan; select all files. Examples: + + SEND /TYPE:BINARY *.* + Sends only binary files, skipping over text files. + + NOTE: File scanning is NOT done when using external protocols (because + the external protocol programs, such as sz, are processing each file, + not Kermit). + + DIRECTORY /TYPE:TEXT + Lists only text files but not binary files. + + DELETE /TYPE:BINARY foo.* + Deletes all foo.* files that are regular binary files but does + not delete any text files. + + CHMOD /TYPE:BINARY 775 * + (UNIX) Changes the permissions of all binary files to 775. + + When FILE SCAN is OFF and FILE PATTERNS are ON, behavior is as before + with PATTERNS ON, but with some improvements: + + * Pathnames are now stripped prior to pattern matching. + * Backup suffixes (like .~3~) are stripped prior to pattern + matching. + + [ [371]Top ] [ [372]Contents ] [ [373]C-Kermit Home ] [ [374]Kermit + Home ] + __________________________________________________________________________ + +5. FILE AND DIRECTORY NAMES CONTAINING SPACES + + Prior to the introduction of the graphical user interface (GUI), it + was inconceivable that file or directory names could contain spaces, + because space is a field delimiter in all command languages. GUIs, + however, use dialog boxes for filenames, so there is never any + question of distinguishing a filename from adjacent fields -- because + there are no adjacent fields -- and therefore it has become quite + common on computers that have GUIs to have file and directory names + composed of multiple words. Of course this poses problems for command + shells and other text-oriented programs. + + Most command shells address these problems by allowing such names to + be enclosed in doublequotes, e.g.: + + cd "c:\Program Files" + + C-Kermit previously used braces for this: + + cd {c:\Program Files} + + which was not what most people expected. And even when braces were + used, Kermit had difficulties with completion, file menus, and so + forth, within braced fields. + + C-Kermit 8.0 allows either doublequotes or braces to be used for + grouping: + + send "this file" + send {this file} + rename "this file" "that file" + rename {this file} "that file" + rename "this file" {that file} + cd {Program Files} + cd "Program Files" + + Note that the doublequotes or brackets must enclose the whole file or + directory specification: + + "c:\My Directory" + + not: + + c:\"My Directory" + + In C-Kermit 8.0, you can also use completion on these filenames, in + which case Kermit supplies the quotes (or braces) automatically. + Example (in which the current directory contains only one file whose + name starts with "th" and its full name is "this file" (without the + quotes, but with the space)): + + cat th + + Kermit repaints the filename field like this: + + cat "this file" + + That is, it backspaces over the original "th" and then writes the + filename in doublequotes. + + If completion is only partial, Kermit still supplies the quotes, but + in this case also beeps. To continue the filename, you must first + backspace over the closing quote. The closing quote is supplied in + this case to make sure that you can see the spaces, especially if they + are trailing. For example, if the current directory contains two files + whose names start with "th", and their fill names are "this file" and + "this other file": + + cat th + + Kermit prints: + + cat "this " + + If it didn't print the closing quote, you would probably wonder why it + was beeping. + + Also, if you begin a filename field with a doublequote or opening + brace, now you can use completion or get ?-help; this was never + possible before. + + C-Kermit>type "thi? Input file specification, one of the following: + this file this other file + C-Kermit>type "thi_ + + [ [375]Top ] [ [376]Contents ] [ [377]C-Kermit Home ] [ [378]Kermit + Home ] + __________________________________________________________________________ + +6. OTHER COMMAND PARSING IMPROVEMENTS + + 6.1. Grouping Macro Arguments + + Doublequotes now can be used in macro invocations to group arguments + containing spaces, where previously only braces could be used: + + define xx show args + xx one "this is two" three + + Result: + + Macro arguments at level 0 (\v(argc) = 4): + \%0 = xx + \%1 = one + \%2 = this is two + \%3 = three + + Also, you can now quote braces and quotes in macro args (this didn't + work before). Examples: + + xx "{" ; The argument is a single left brace + xx {"} ; The argument is a doublequote character + + In case this new behavior interferes with your scripts, you can + restore the previous behavior with: + + SET COMMAND DOUBLEQUOTING OFF + + 6.2. Directory and File Name Completion + + C-Kermit 8.0 also includes better completion for directory names, e.g. + in the CD command. If the name typed so far uniquely matches a + directory name, it is completed (as before), but now if the directory + contains any subdirectories, completion is partial (allowing you to + supply additional path segments without backspacing); otherwise it is + complete. + + Completion has also been improved for file and directory names that + contain not only spaces (as described above) but also "metacharacters" + such as asterisk (*) and tilde (~): now the field is repainted if + necessary. For example, if the current directory contains only one + file whose name contains "blah", then in: + + type *blah + + "*blah" is replaced by the filename. In earlier releases, the part + typed so far was left on the command line (and in the history buffer), + so even when the original command worked, the recalled version would + not. Similarly for ~ (the nearly-universal Unix notation for + username): + + type ~olga/x + + is repainted as (e.g.): + + type /users/home/olga/x(Beep) + + Speaking of command history, the new SHOW HISTORY command shows your + command history and recall buffer. SAVE COMMAND HISTORY saves it into + a file of your choice. + + 6.3. Passing Arguments to Command Files + + The method for passing arguments to command files has been improved. + Prior to C-Kermit 7.0 there was no provision for doing this. In + C-Kermit 7.0, the TAKE command was changed to allow arguments to be + given after the filename: + + take commandfile arg1 arg2 ... + + This was accomplished by replacing the current \%1, \%2, etc, with the + given arguments, since a new set of macro argument variables is + created only when a macro is executed, not a command file. It is much + more intuitive, however, if arguments to command files worked like + those to macros: the command file sees the arguments as its own \%1, + \%2, etc, but the caller's variables are not disturbed. C-Kermit 8.0 + accomplishes this by automatically creating an intermediate temporary + macro to start the command file (if any arguments were given), thus + creating a new level of arguments as expected. + + 6.4. More-Prompting + + The familiar --more?-- prompt that appears at the end of each + screenful of command-response output now accepts a new answer: G (Go) + meaning "show all the rest without pausing and asking me any more + questions". P (Proceed) is a synonym for G. + + 6.5. Commas in Macro Definitions + + As noted in the [379]C-Kermit manual, comma is used to separate + commands in a macro definition. Even when the macro is defined on + multiple lines using curly-brace block-structure notation without + commas, the definition is still stored internally as a comma-separated + list of commands. Therefore special tricks are needed to include a + comma in a command. The classic example is: + + define foo { + (some command) + if fail echo Sorry, blah failed... + } + + This would result in Kermit trying to execute a "blah" command. This + could always be handled by enclosing the text in braces: + + define foo { + (some command) + if fail echo {Sorry, blah failed...} + } + + but doublequotes (more intuitive) should have worked too. Now they do: + + define foo { + (some command) + if fail echo "Sorry, blah failed..." + } + + 6.6. Arrow Keys + + As of version 8.0.201, C-Kermit on most platforms lets you access the + command history buffer with arrow keys, just as you always could with + control characters. The restrictions are: + + 1. Only Up and Down arrow keys are accepted. + 2. Only 7-bit ANSI arrow-key sequences are understood (ESC followed + by [ or uppercase letter O, followed by uppercase letter A or (up) + B (down). + + This change was made to facilitate command recall in Linux-based PDAs + that don't have a Control key, or at least not one that's easily (or + always) accessible, such as the Sharp Zaurus SL5500. + + [ [380]Top ] [ [381]Contents ] [ [382]C-Kermit Home ] [ [383]Kermit + Home ] + __________________________________________________________________________ + +7. NEW COMMANDS AND SWITCHES + + See [384]Section 4 for more about file scanning and the /TYPE: switch. + + ASK[Q] [ /TIMEOUT:number /QUIET /DEFAULT:text ] variable [ prompt ] + The new optional /TIMEOUT: switch for ASK and ASKQ causes the + command to time out and and fail if no response is given within + the specified number of seconds, 1 or greater (0 or less means + no timeout, wait forever). This works just like SET ASK-TIMER, + except its effect is local to the ASK command with which it is + given and it does not disturb the global ask timer setting. The + new /QUIET switch tells Kermit not to print an error message if + the ASK or ASKQ command times out waiting for a response. + + Version 8.0.211 adds the /DEFAULT:text switch for ASK-Class + commands (ASK, ASKQ, and GETOK). This lets you supply a default + answer in case the user supplies an empty answer or the + /TIMEOUT: switch was included and the time limit expired + without an answer. In both these cases, the command succeeds. + + CAT filename + Equivalent to TYPE /NOPAGE. + + CDUP + Changes Kermit's local working directory to the parent of the + current one. Equivalent to "cd .." in UNIX or Windows, "cd [-]" + in VMS, "cd ^" in AOS/VS, etc; in other words, it's a + platform-independent way of moving one level up in a directory + tree. + + CHMOD [ switches ] permission files + UNIX only. Sets file permissions for one or more files or + directories. The permission must be given as an octal number, + e.g. 664, 755. Switches: /DIRECTORIES, /FILES, /NOLIST, /PAGE, + /DOTFILES, /LIST, /NOPAGE, /RECURSIVE, /TYPE:{TEXT,BINARY,ALL}, + /SIMULATE. The /TYPE: switch allows selection of only text or + binary files. For example, if you have a mixture of source + files and executables, you can use "chmod /files /type:text + 664" to give owner/group read/write and world read permission + to the text files, and "chmod /files /type:binary 775" to give + the same plus execute permission to the executables. Use + /SIMULATE to see which files would be affected, without + actually changing their permissions. + + CLEAR KEYBOARD-BUFFER + Flushes any as-yet unread characters from the keyboard input + buffer. Useful for flushing typeahead in scripts. + + CONTINUE + When given at an interactive command prompt that was reached by + issuing a PROMPT command (described in this section) from a + script, this command returns to the script, continuing its + execution at the command after the PROMPT command. In this + context, CONTINUE is simply a more-intuitive synonym for END. + + COPY, RENAME, and TRANSLATE + These commands now work on file groups if the target filename + is a directory, e.g. "copy oofa.* ..", "rename * ~olga/tmp/" + + COPY /APPEND source destination + The source file specification can now include wildcards, in + which case all of the source files that match will go into the + destination file in alphabetical order by name. + + DELETE /ASK + Asks permission to delete each file before deleting it. In + C-Kermit 7.0, the answers were "yes" (or "ok") and "no". + C-Kermit 8.0 adds "go" (meaning, delete all the rest without + asking) and "quit" (cancel the DELETE command and return to the + prompt). + + DELETE /DIRECTORIES + Deletes not only files but also directories. + + DELETE /RECURSIVE + Deletes all files that match the given file specification in + the current (or given) directory and all directories beneath + it. + + DELETE /SUMMARY + Prints only the number of files deleted and total size freed, + without listing each file. + + DELETE /TREE + Shorthand for DELETE /RECURSIVE /DIRECTORIES /DOTFILES/. + Equivalent to Windows DELTREE or Unix "rm -Rf". If no file + specification is given, the contents of the current directory, + plus all of its subdirectories and their contents, are deleted. + + DELETE /TYPE:BINARY + Delete only regular binary files (requires FILE SCAN ON). + + DELETE /TYPE:TEXT + Delete only regular text files (requires FILE SCAN ON). + + DIRECTORY [ switches ] [ filespec [ filespec [ filespec ... ] ] ] + The DIRECTORY command now accepts more than one file + specification; e.g. "directory moon.txt sun.doc stars.*". + + DIRECTORY /NORECURSIVE xxx + If xxx is a directory name, forces listing of the directory + itself rather than its contents. + + DIRECTORY /FOLLOWLINKS xxx + (UNIX only) Tells the DIRECTORY command to follow symbolic + links. This not the default because it can cause endless loops. + + DIRECTORY /NOFOLLOWLINKS xxx + (UNIX only) Tells the DIRECTORY command not to follow symbolic + links, but rather, merely to list them. This is the default. + + DIRECTORY /OUTPUT:filename + Sends the results of the DIRECTORY command to the given file. + + DIRECTORY /SUMMARY + Prints only the number of directories and files and the total + size, without listing each file. + + DIRECTORY /TYPE:{TEXT,BINARY} + Shows only files of the selected type, based on file scan. + + DIRECTORY /XFERMODE + Now shows results of file scan (see [385]Section 4). + + FOPEN [ switches ] channel filename + + As of version 8.0.211, FOPEN allows /dev/tty as a filename in + Unix-based operating systems. + + FREAD /TRIM + (8.0.211) Trims any trailing blanks or tabs from the item (such + as a line of text) that it has read. + + FREAD /UNTABIFY + (8.0.211) Converts Horizontal Tab characters to the appropriate + number of spaces, based on VT100-like tab stops + (1,9,17,25,...). + + GREP [ switches ] pattern files + Similar to Unix grep command: displays file lines that match + the given [386]pattern. Switches: + + /COUNT[:variable] + Don't show the matching lines, just tell how many lines + match. If a variable name is specified, the count is + stored in the given variable. + + /DOTFILES + Include files whose names begin with dot. + + /LINENUMBERS + Show line numbers of matching lines. + + /NAMEONLY + only list the names of files that contain matching lines, + but not the lines themselves. + + /NOBACKUP + Skip backup files. + + /NOCASE + Ignore alphabetic case while pattern matching. + + /NODOTFILES + skip files whose names start with dot (period). + + /NOLIST + Suppress output but set SUCCESS or FAILURE according to + search result. + + /NOMATCH + Look for lines that do not match the pattern. + + /NOPAGE + Don't pause between screens of output. + + /OUTPUT:filename + Write results into the given file. + + /PAGE + Pause between screens of output. + + /RECURSIVE + Search files in subdirectories too. + + /TYPE:{TEXT,BINARY} + Search only files of the specified type. + + Synonyms: FIND, SEARCH. + + GETOK /TIMEOUT:n /QUIET /DEFAULT:text + The new /QUIET switch instructs GETOK, when given a timeout, + not to print an error message if it times out. As of 8.0.211, a + default answer can be supplied (see ASK). + + HEAD [ switches ] filename + Equivalent to TYPE /HEAD [ other-switches ] filename. + + HELP DATE + Explains date-time formats, including timezone notation and + delta times. + + HELP FIREWALLS + Explains the firewall negotiation capabilities of your version + of Kermit. + + KCD [ symbolic-directory-name ] + Changes Kermit's working directory to the named symbolic + directory, such as such as exedir, inidir, startup, download, + or and home. Type "kcd ?" for a list of symbolic directory + names known to your copy of Kermit, or give the new ORIENTATION + command for a more detailed explanation. If you give a KCD + command without a directory name, Kermit returns to its "home" + directory, which is determined in some way that depends on the + underlying operating system, but which you can redefine with + the (new) SET CD HOME command. Your home directory is shown by + SHOW CD and it's also the value of the \v(home) variable. + + LICENSE + Displays the C-Kermit license. + + L-commands + When Kermit has a connection to a Kermit or FTP server, file + managment commands such as CD, DIRECTORY, and DELETE might be + intended for the local computer or the remote server. C-Kermit + 8.0.200 and earlier always executes these commands on the local + computer. If you want them executed by the remote server, you + have to prefix them with REMOTE (e.g. REMOTE CD) or use special + R-command aliases (e.g. RCD = REMOTE CD, RDIR = REMOTE DIR, + etc). But this feels unnatural to FTP users, who expect + unprefixed file management commands to be executed by the + remote server, rather than locally. C-Kermit 8.0.201 adds + automatic locus switching to present an FTP-like interface for + FTP connections and the normal Kermit interface for Kermit + connections, and a SET LOCUS command (described below) to + control whether or how this is done. For when LOCUS is REMOTE, + a new set of commands was added for local management: LCD + (Local CD), LDIR (Local DIR), etc. These are described below + under SET LOCUS. + + MORE filename + Equivalent to TYPE /PAGE. + + ORIENTATION + Displays symbolic directory names and the corresponding + variable names and values. The symbolic names, such as exedir, + inidir, startup, download, and home, can be used as arguments + to the new KCD command. + + PROMPT [ text ] + For use in a macro or command file: enters interactive command + mode within the current context ([387]Section 8.1). If the + optional text is included, the prompt is set to it. The text + can include variables, functions, etc, as in the SET PROMPT + command. They are evaluated each time the prompt is printed. + Unlike the SET PROMPT command, the text argument applies only + to the current command level. Thus you can have different + prompts at different levels. + + REMOTE SET MATCH { DOTIFILE, FIFO } { ON, OFF } + Allows the client to tell the server whether wildcards sent to + the server should match dot files (files whose names begin with + period) or FIFOs (named pipes). See SET MATCH. + + SET ATTRIBUTE RECORD-FORMAT { ON, OFF } + Allows control of the Kermit's Record-Format attribute. Set + this to OFF in case incoming file are refused due to unknown or + invalid record formats if you want to accept the file anyway + (and, perhaps, postprocess it to fix its record format). + + SET CD HOME [ directory ] + Specifies the target directory for the CD and KCD commands, + when they are given without an argument, and also sets the + value of the \v(home) variable. + + SET EXIT HANGUP { OFF, ON } + Normally ON, meaning that when Kermit exits, it also explicitly + hangs up the current SET LINE / SET PORT serial port according + to the current SET MODEM TYPE and SET MODEM HANGUP METHOD, and + closes the port device if it was opened by Kermit in the first + place (as opposed to inherited). SET EXIT HANGUP OFF tells + Kermit not to do this. This can't prevent the operating system + from closing the device when Kermit exits (and it's a "last + close") but if the port or modem have been conditioned to + somehow ignore the close and keep the connection open, at least + Kermit itself won't do anything explicit to hang it up or close + it. + + SET FILE EOF { CTRL-Z, LENGTH } + Specifies the end-of-file detection method to be used by + C-Kermit when sending and receiving text files, and in the TYPE + and similar text-file oriented commands. The normal and default + method is LENGTH. You can specify CTRL-Z when handling CP/M or + MS-DOS format text files, in which a Ctrl-Z (ASCII 26) + character within the file marks the end of the file. + + SET FILE LISTSIZE number + Allocates space for the given number of filenames to be filled + in by the wildcard expander. The current number is shown by + SHOW FILE. If you give a command that includes a filename + containing a wildcard (such as "*") that matches more files + that Kermit's list has room for, you can adjust the list size + with this command. + + SET FILE STRINGSPACE number + Allocates space for the given amount of filename strings for + use by the wildcard expander. The current number is shown by + SHOW FILE. The number is the total number of bytes of all the + file specifications that match the given wildcard. + + If you need to process a bigger list of files than your computer + has memory for, you might be able use an external file list. The + Kermit SEND and the FTP PUT and GET commands accept a /LISTFILE: + switch, which gives the name of a file that contains the list of + files to be transferred. Example for UNIX: + + !find . -print | grep / > /tmp/names + ftp put /update /recursive /listfile:/tmp/names + + SET LOCUS { AUTO, LOCAL, REMOTE } + Added in C-Kermit 8.0.201. Sets the locus for unprefixed file + management commands such as CD, DIRECTORY, MKDIR, etc. When + LOCUS is LOCAL these commands act locally and a REMOTE (or R) + prefix (e.g. REMOTE CD, RCD, RDIR) is required to send file + management commands to a remote server. When LOCUS is REMOTE, + an L prefix is required to issue local file management commands + (e.g. LCD, LDIR). The word LOCAL can't be used as a prefix + since it is already used for declaring local variables. LOCUS + applies to all types of connections, and thus is orthogonal to + SET GET-PUT-REMOTE, which selects between Kermit and FTP for + remote file-transfer and management commands. The default LOCUS + is AUTO, which means we switch to REMOTE whenever an FTP + connection is made, and to LOCAL whenever a non-FTP connection + is made, and switch back accordingly whenever a connnection is + closed. So by default, Kermit behaves in its traditional manner + unless you make an FTP connection, in which case it acts like a + regular FTP client (but better :-) LOCUS applies to the + following commands: + + Unprefixed Remote Local Description + CD (CWD) RCD LCD Change (Working) Directory + CDUP RCDUP LCDUP CD Up + PWD RPWD LPWD Print Working Directory + DIRECTORY RDIR LDIR Request a directory listinga + DELETE RDEL LDEL Delete (a) file(s) + RENEME RREN LREN Rename a file + MKDIR RMKDIR LMKDIR Create a directory + RMDIR RRMDIR LRMDIR Remove a directory + + SET MATCH { DOTIFILE, FIFO } { ON, OFF } + Whether C-Kermit filename patterns (wildcards) should match + filenames that start with dot (period), or (Unix only) FIFOs + (named pipes). The defaults are to skip dotfiles in Unix but + match them elsewhere, and to skip FIFOs. Applies to both + interactive use and to server mode, when the server receives + wildcards, e.g. in a GET command. Also see REMOTE SET MATCH. + + SET OPTIONS DIRECTORY /DOTFILES + Now works for server listings too (UNIX only). Give this + command prior to having Kermit enter server mode, and then it + will show files whose names begin with dot (period) when sent a + REMOTE DIRECTORY command. + + SET QUIET ON + (as well as the -q command-line option) Now applies also to: + + + SET HOST connection progress messages. + + "Press the X or E key to cancel" file-transfer message. + + REMOTE CD response. + + REMOTE LOGIN response. + + SET RECEIVE PERMISSIONS { ON, OFF } + Tells C-Kermit whether to set the permissions of incoming files + (received with Kermit protocol) from the permissions supplied + in the file's Attribute packet (if any). Normally ON. Also see + SET SEND PERMISSIONS. + + SET ROOT directory + Like UNIX chroot, without requiring privilege. Sets the root + for file access, does not allow reference to or creation of + files outside the root, and can't be undone. + + SET SEND PERMISSIONS { ON, OFF } + Tells C-Kermit whether to include file permissions in the + attributes it includes with each file when sending with Kermit + protocol. Also see SET RECEIVE PERMISSIONS. + + SET TCP { HTTP-PROXY, SOCKS-SERVER } /USER:name /PASSWORD:text + These commands now allow specification of username and + password. + + SET TERMINAL . . . + (See [388]Section 12.) + + SET TRANSFER MESSAGE [ text ] + Sets an initial text message to be displayed in the + file-transfer display. The transfer message is automatically + deleted once used, so must be set each time a message a + desired. Any variables in the message are evaluated at the time + the SET command is given. If the optional text is omitted, any + transfer message that is currently set is removed. Synonym: SET + XFER MSG. SHOW TRANSFER displays it if it has been set but not + yet used. + + SHOW COMMUNICATIONS + In C-Kermit 8.0, SHOW COMMUNICATIONS, when given in remote mode + (i.e. before any connection has been established), tells the + typical dialout device name for the particular platform on + which it's running (e.g. TXA0: for VMS, or /dev/cua0p0 for + HP-UX). On Unix platforms, it also tells the name of the + lockfile directory. This way, you have an idea of what the SET + LINE device name should look like, and if the SET LINE command + fails, you know the name of the directory or device that is + protected against you. + + SHOW VARIABLES [ name [ name [ ... ] ] ] + In C-Kermit 8.0.201 you can request values of a list of + built-in (\v(xxx)) variables. Each name is a pattern, as + before, but now it a free pattern rather than an anchored one + (explained in [389]Section 8.12) so now "show var date time" + shows the values of all variables whose names include the + strings "date" or "time". + + TAIL [ switches ] filename + Equivalent to TYPE /TAIL [ other-switches ] filename. + + TRANSMIT /NOECHO [ other switches ] filename + The /NOECHO switch is equivalent to giving the command SET + TRANSMIT ECHO OFF prior to the TRANSMIT command, except the + switch affects only the command with which it was given and + does not affect the prevailing global setting. + + TRANSMIT /NOWAIT [ other switches ] filename + The /NOWAIT switch is equivalent to giving the command SET + TRANSMIT PROMPT 0 prior to the TRANSMIT command, except the + switch affects only the command with which it was given and + does not affect the prevailing global setting. + + TRANSMIT /NOWAIT /NOECHO /BINARY [ other switches ] filename + When the TRANSMIT command is given with the /NOWAIT, /NOECHO, + and /BINARY switches, this activates a special "blast the whole + file out the communications connection all at once" mode that + Kermit didn't have prior to version 8.0. There has been + increasing demand for this type of transmission with the advent + of devices that expect image (e.g. .JPG) or sound (e.g. .MP3) + files as raw input. The obvious question is: how does the + receiving device know when it has the whole file? This depends + on the device, of course; usually after a certain amount of + time elapses with nothing arriving, or else when Kermit hangs + up or closes the connection. + + TYPE /CHARACTER-SET:name + Allows you to specify the character set in which the file to be + typed is encoded. + + TYPE /NUMBER + Adds line numbers. + + TYPE /OUTPUT:filename + Sends the results of the TYPE command to the given file. + + TYPE /TRANSLATE-TO:name + Used in conjunction with TYPE /CHARACTER-SET:xxx; allows you to + specify the character set in which the file is to be displayed. + + TYPE /TRANSPARENT + Used to disable character-set translation in the TYPE command, + which otherwise can take place automatically based on file + scanning, even when /CHARACTER-SET and /TRANSLATE-TO switches + are not given. + + VOID text + Parses the text, evaluating any backslash items in it (such as + function calls) but doesn't do anything further, except + possibly printing error messages. Useful for invoking functions + that have side effects without using or printing their direct + results, e.g. "void \fsplit(\%a,&a)". + + Symbolic Links in UNIX + + The UNIX versions of C-Kermit have had /FOLLOWLINKS and /NOFOLLOWLINKS + switches added to several commands to control the treatment of + symbolic links. Different commands deal differently with symbolic + links: + + Kermit SEND, FTP MPUT + /NOFOLLOWLINKS is the default, which means symbolic links are + skipped entirely. The alternative, /FOLLOWLINKS, should be used + with caution, since an innocent link might point to a whole + file system, or it might cause a loop. There is no way in + Kermit or FTP protocol to send the link itself. We either skip + them or follow them; we can't duplicate them. + + DIRECTORY + /NOFOLLOWLINKS is the default, which means the DIRECTORY + command lists symbolic links in a way that shows they are + links, but it does not follow them. The alternative, + /FOLLOWLINKS, follows links and gives information about the + linked-to directories and files. + + DELETE, RMDIR + The DELETE command does not have link-specific switches. DELETE + never follows links. If you tell Kermit to delete a symbolic + link, it deletes the link itself, not the linked-to file. Ditto + for RMDIR. + + COPY + The COPY command behaves just like the UNIX cp command; it + always follows links. + + RENAME + The RENAME command behaves just like the UNIX mv command; it + operates on links directly rather than following. + + [ [390]Top ] [ [391]Contents ] [ [392]C-Kermit Home ] [ [393]Kermit + Home ] + __________________________________________________________________________ + +8. OTHER SCRIPTING IMPROVEMENTS + + 8.1. Performance and Debugging + + A command cache for frequently used commands plus some related + optimizations increases the speed of compute-bound scripts by anywhere + from 50% to 1000%. + + The new PROMPT command can be used to set breakpoints for debugging + scripts. If executed in a command file or macro, it gives you an + interactive command prompt in the current context of the script, with + all its variables, arguments, command stack, etc, available for + examination or change, and the ability to resume the script at any + point (END resumes it, Ctrl-C or STOP cancels it and returns to top + level). + + The new Ctrl-C trapping feature ([394]Section 8.14) lets you intercept + interruption of scripts. This can be used in combination with the + PROMPT command to debug scripts. Example: + +define ON_CTRLC { + echo INTERRUPTED BY CTRL-C... + echo The command stack has not yet been rolled back: + show stack + echo Type Ctrl-C again or use the END command to return to top level. + prompt Debug> +} + + Adding this ON_CTRL definition to your script lets you interrupt it at + any point and get prompt that is issued at the current command level, + so you can query local variables, etc. + + [ [395]Top ] [ [396]Contents ] [ [397]C-Kermit Home ] [ [398]Kermit + Home ] + _________________________________________________________________ + + 8.2. Using Macros as Numeric Variables + + A macro is a way to assign a value to a name, and then use the name to + refer to the value. Macros are used in two ways in Kermit: as + "subroutines" or functions composed of Kermit commands, which are + executed, or as variables to hold arbitrary values -- text, numbers, + filenames, etc. + + When a macro is to be executed, its name is given as if it were a + C-Kermit command, optionally preceded by the word "do". When a macro + is used as a variable, it must be "escaped" with \m(xxx) (or + equivalent function, e.g. \s(xxx), \:(xxx), \fdefinition(xxx)), where + xxx is the macro name, for example: + + define filename /usr/olga/oofa.txt + send \m(filename) + + Of course variables can also hold numbers: + + define size 17 + declare \&a[\m(size)] + ... + define index 3 + if ( == \m(index) 3 ) echo The third value is: \&a[\m(index)] + evaluate index (\m(index) * 4) + if ( > \m(index) \m(size) ) echo Out of range! + + But these are contexts in which only numbers are valid. C-Kermit 8.0 + has been changed to treat non-escaped non-numeric items in strictly + numeric contexts as macro names. So it is now possible (but not + required) to omit the \m(...) notation and just use the macro name in + these contexts: + + define size 17 + declare \&a[size] + ... + define index 3 + if ( == index 3 ) echo The third value is: \&a[index] + evaluate index (index * 4) + if ( > index size ) echo Out of range! + + This is especially nice for loops that deal with arrays. Here, for + example, is a loop that reverses the order of the elements in an + array. Whereas formerly it was necessary to write: + + .\%n ::= \fdim(&a) + for \%i 1 \%n/2 1 { + .tmp := \&a[\%n-\%i+1] + .\&a[\%n-\%i+1] := \&a[\%i] + .\&a[\%i] := \m(tmp) + } + + Recoding this to use macro names "i" and "n" instead of the backslash + variables \%i and \%n, we have: + + .n ::= \fdim(&a) + for i 1 n/2 1 { + .tmp := \&a[n-i+1] + .\&a[n-i+1] := \&a[i] + .\&a[i] := \m(tmp) + } + + which reduces the backslash count to less than half. The final + statement in the loop could be written ".\&a[i] ::= tmp" if the array + contained only numbers (since ::= indicates arithmetic expression + evaluation). + + Also, now you can use floating-point numbers in integer contexts (such + as array subscripts), in which case they are truncated to an integer + value (i.e. the fractional part is discarded). + + Examples of numeric contexts include: + + * Array subscripts. + * Any numeric function argument. + * Right-hand side of ::= assignments. + * EVALUATE command or \fevaluate() function expression. + * The INCREMENT or DECREMENT by-value. + * IF =, >, <, !=, >=, and <= comparands. + * The IF number construct. + * FOR-loop variables. + * STOP, END, and EXIT status codes. + * The INPUT timeout value. + * PAUSE, WAIT, SLEEP, MSLEEP intervals. + * The SHIFT argument. + * Numeric switch arguments, e.g. TYPE /WIDTH:number, SEND + /LARGER:number. + * SCREEN MOVE-TO row and column number. + * Various SET DIAL parameters (timeout, retry limit, etc). + * Various SET SEND or RECEIVE parameters (packet length, window + size, etc). + * Various other SET parameters. + + and: + + * S-Expressions (explained in [399]Section 9). + + Macro names used in numeric contexts must not include mathematical + operators. Although it is legal to create a macro called "foo+bar", in + a numeric context this would be taken as the sum of the values of + "foo" and "bar". Any such conflict can be avoided, of course, by + enclosing the macro name in \m(...). + + [ [400]Top ] [ [401]Contents ] [ [402]C-Kermit Home ] [ [403]Kermit + Home ] + _________________________________________________________________ + + 8.3. New IF Conditions + + Several new IF conditions are available: + + IF DECLARED arrayname + Explained in [404]Section 8.6. + + IF KBHIT + Allows a script to test whether a key was pressed without + actually trying to read it. + + IF KERBANG (Unix only) + True if Kermit was started from a Kerbang script. This is + useful for knowing how to interpret the \&@[] and \&_[] + argument vector arrays, and under what conditions to exit. + + IF INTEGER n + This is just a synonym for IF NUMERIC, which is true if n + contains only digits (or, if n is a variable, its value + contains only digits). + + By contrast, IF FLOAT n succeeds if n is a floating-point number OR an + integer (or a variable with floating-point or integer value). + Therefore, IF FLOAT should be used whenever any kind of number is + acceptable, whereas IF INTEGER (or IF NUMERIC) when only an integer + can be used. + + [ [405]Top ] [ [406]Contents ] [ [407]C-Kermit Home ] [ [408]Kermit + Home ] + _________________________________________________________________ + + 8.4. The ON_UNKNOWN_COMMAND Macro + + The new ON_UNKNOWN_COMMAND macro, if defined, is executed whenever you + give a command that is not known to C-Kermit; any operands are passed + as arguments. Here are some sample definitions: + + DEF ON_UNKNOWN_COMMAND telnet \%1 ; Treat unknown commands as hostnames + DEF ON_UNKNOWN_COMMAND dial \%1 ; Treat unknown commands phone numbers + DEF ON_UNKNOWN_COMMAND take \%1 ; Treat unknown commands as filenames + DEF ON_UNKNOWN_COMMAND !\%* ; Treat unknown commands as shell commands + + The ON_CD macro, if defined, is executed whenever Kermit is given a CD + (change directory) command (8.0.211). Upon entry to this macro, the + directory has already changed and the new directory string is + available in the \v(directory) variable, and also as the first + argument (\%1). + + [ [409]Top ] [ [410]Contents ] [ [411]C-Kermit Home ] [ [412]Kermit + Home ] + _________________________________________________________________ + + 8.5. The SHOW MACRO Command + + The SHOW MACRO command has been changed to accept more than one macro + name: + + (setq a 1 b 2 c 3) + show mac a b c + a = 1 + b = 2 + c = 3 + + An exact match is required for each name (except that case doesn't + matter). If you include wildcard characters, however, a pattern match + is performed: + + show mac [a-c]*x + + shows all macros whose names start with a, b, or c, and end with x. + + [ [413]Top ] [ [414]Contents ] [ [415]C-Kermit Home ] [ [416]Kermit + Home ] + _________________________________________________________________ + + 8.6. Arrays + + A clarification regarding references to array names (as opposed to + array elements): You can use array-name "abbreviations" like &a only + in contexts that expect array names, like ARRAY commands or array-name + function arguments such as the second argument of \fsplit(). In a + LOCAL statement, however, you have to write \&a[], since "local &a" + might refer to a macro named "&a". + + In function arguments, however, you MUST use the abbreviated form: + \fsplit(\%a,&a) or \fsplit(\%a,&a[]). If you include the backslash (as + in "\fsplit(\%a,\&a[])") a parse error occurs. + + Here are the new array-related commands: + + IF DECLARED arrayname + Allows a script to test whether an array has been declared. The + arrayname can be a non-array backslash variable such as \%1 or + \m(name), in which case it is evaluated first, and the result + is treated as the array name. Otherwise, arrayname is treated + as in the ARRAY commands: it can be a, &a, &a[], \&a, \&a[], + \&a[3], \&a[3:9], etc, with the appropriate results in each + case. Synonym: IF DCL. + + UNDECLARE arrayname + UNDECLARE is a new top-level command to undeclare an array. + Previously this could only be done with "declare \&a[0]" (i.e. + re-declare the array with a dimension of 0). + + ARRAY LINK linkname arrayname + Creates a symbolic link from the array named by linkname (which + must be the name of an array that is not yet declared in the + current context) to the array named by arrayname (which must + the name of a currently declared array that is not itself a + link, or a variable containing the name of such an array). The + two names indicate the same array: if you change an array + element, the change is reflected in the link too, and vice + versa. If you undeclare the link, the real array is unaffected. + If you undeclare the real array, all links to it disappear. If + you resize an array (directly or through a link), all links to + it are updated automatically. + + Array links let you pass array names as arguments to macros. For + example, suppose you had a program that needed to uppercase all the + elements of different arrays at different times. You could write a + macro to do this, with the array name as an argument. But without + array links, there would be no way to refer to the argument array + within the macro. Array links make it easy: + + define arrayupper { + local \&e[] \%i + array link \&e[] \%1 + for i 1 \fdim(&e) 1 { .\&e[i] := \fupper(\&e[i]) } + } + declare \&a[] = these are some words + arrayupper &a + show array &a + + The macro declares the array link LOCAL, which means it doesn't + conflict with any array of the same name that might exist outside the + macro, and that the link is destroyed automatically when the macro + exits. This works, by the way, even if the link name and the macro + argument name are the same, as long as the link is declared LOCAL. + + As noted, you can't make a link to a nonexistent array. So when + writing a macro whose job is to create an array whose name is passed + as an argument, you must declare the array first (the size doesn't + matter as long as it's greater than 0). Example: + + define tryme { ; Demonstration macro + local \&e[] ; We only need this inside the macro + array link \&e[] \%1 ; Make local link + shift ; Shift argument list + void \fsplit(\%*,&e) ; Split remainder of arg list into array + } + declare \&a[1] ; Declare target array in advance + tryme &a here are some words ; Invoke the macro with array name and words + show array a ; See the results + + One final improvement allows the macro itself to declare the array + (this was not possible in earlier Kermit releases): if the array name + in the DECLARE command is a variable (and not an array name), or + includes variables, the resulting value is used as the array name. So: + + define tryme { ; Demonstration macro + declare \%1[1] ; Preliminary declaration for target array + local \&e[] ; We only need this inside the macro + array link \&e[] \%1 ; Make local link + shift ; Shift argument list + void \fsplit(\%*,&e) ; Split remainder of arg list into array + } + tryme &a here are some words ; Invoke the macro with array name and words + show array a ; See the results + + The SHOW ARRAY command now indicates whether an array name is a link. + + Also see the descriptions of [417]\fjoin() and [418]\fsplit(), plus + [419]Section 8.10 on the MINPUT command, which shows how an entire + array (or segment of it) can be used as the MINPUT target list. + + [ [420]Top ] [ [421]Contents ] [ [422]C-Kermit Home ] [ [423]Kermit + Home ] + _________________________________________________________________ + + 8.7. New or Improved Built-in Variables and Functions + + The following new built-in variables are available: + + \v(buildid) A date string like "20000808" indicating when C-Kermit was +built. + \v(ftime) Current time, secs since midnight, including fraction of se +cond. + \v(iprompt) The current SET PROMPT value + \v(sexp) The most recent S-Expression (see [424]Section 9) + \v(sdepth) The current S-Expression invocation depth ([425]Section 9) + \v(svalue) The value of the most recent S-Expression ([426]Section 9) + + \v(ftp_code) Most recent FTP response code ([427]Section 3) + \v(ftp_connected) FTP connection status ([428]Section 3) + \v(ftp_cpl) FTP Command Protection Level ([429]Section 3.2) + \v(ftp_dpl) FTP Data Protection Level ([430]Section 3.2) + \v(ftp_getputremote) The current SET GET-PUT-REMOTE setting ([431]Section 3.8 +) + \v(ftp_host) Name or IP address of FTP server ([432]Section 3) + \v(ftp_loggedin) FTP login status ([433]Section 3) + \v(ftp_message) Most recent FTP response message ([434]Section 3) + \v(ftp_security) FTP Security method ([435]Section 3.2) + \v(ftp_server) OS type of FTP server ([436]Section 3) + + \v(http_code) Most recent HTTP response code + \v(http_connected) HTTP connection status + \v(http_host) Name or IP address of HTTP server + \v(http_message) Most recent HTTP response message + \v(http_security) TLS cipher used to secure the HTTP session + + \v(hour) Hour of the day, 0 to 23. + \v(timestamp) Equivalent to "\v(ndate) \v(time)". + + \v(log_debug) Current debug log file, if any. + \v(log_packet) Current packet log file, if any. + \v(log_session) Current session log file, if any. + \v(log_transaction) Current transaction log file, if any. + \v(log_connection) Current connection log file, if any. + + The following new or improved built-in functions are available: + + \fcmdstack() Allows programmatic access to the command stack. + \fcvtdate() [437]Section 8.13, format options added + \fdelta2secs() [438]Section 8.13 + \fdostounixpath(s1) Converts a DOS filename to Unix format. + \fsplit() Now allows grouping/nesting in source string. + \fword() Allows the same grouping and nesting. + \fjoin(&a,s1,n1,n2) Copies an array into a single string. + \fsubstitute(s1,s2,s3) Substitutes characters within a string. + \freplace() Has new 4th "occurrence" argument. + \fsexpression() Evaluates an S-Expression (explained in [439]Section +9). + \ftrim(), \fltrim() Now trim CR and LF by default, as well as SP and Tab. + \funixtodospath(s1) Converts a Unix filename to DOS format. + \fkeywordval(s1,c1) Assigns values to keywords (macros) (explained below) +. + + Most functions that have "2" in their names to stand for the word "to" + can now also be written with "to", e.g. "\fdelta2secs()," + \fdeltatosecs()." + + \funtabify(string) + (New to 8.0.211) Replaces Horizontal Tab characters in the + given string with spaces based on VT100-like tab stops. + + \fverify(s1,s2,n) + As of version 8.0.211, returns -1 if s2 is an empty string. + Previously it returned 0, making \fverify(abc,\%a) look as if + \%a was a string combosed of a's, b's, and/or c's when in fact + it contained nothing. + + \fcode(string) + As of version 8.0.211, returns 0 if string is empty or missing. + Previously it returned the empty string, which made it unsafe + to use in arithmetic or boolean expressions. + + \v(inscale) + New to version 8.0.211, its value is the INPUT SCALE-FACTOR + ([440]Section 8.10), default 1.0. + + 8.7.1. The \fkeywordval() Function + + \fkeywordval(s1,c1) is new to C-Kermit 8.0. Given a string s1 of the + form "name=value", it creates a macro with the given name and assigns + it the given value. If no value appears after the equal sign, any + existing macro of the given name is undefined. Blanks are + automatically trimmed from around the name and value. The optional c1 + parameter is the assignment operator character, equal sign (=) by + default. This function is handy for processing keyword parameters or + any other form of parameter-value pair. Suppose, for example, you want + to write a macro that accepts keyword parameters rather than + positional ones: + + define MYDIAL { + local \%i modem hangup method device speed number + def number 5551234 ; Assign default parameter values + def speed 57600 + def modem usrobotics + def hangup rs232 + def method tone + def country 1 + for \%i 1 \v(argc)-1 1 { ; Parse any keyword parameters... + if not \fkeywordval(\&_[\%i]) end 1 Bad parameter: "\&_[\%i]" + } + set dial country \m(country) + set modem type \m(modem) + set modem hang \m(hangup) + set dial method \m(tone) + set line \m(device) + if fail stop 1 + set speed \m(speed) + if fail stop 1 + show comm + set dial display on + dial \m(number) + if success connect + } + + In this example, all the defaults are set up inside the macro, and + therefore it can be invoked with no parameters at all. But if you want + to have the macro dial a different number, you can supply it as + follows: + + mydial number=7654321 + + You can supply any number of keyword parameters, and you can give them + in any order: + + mydial number=7654321 hangup=modem speed=115200 + + 8.7.2. The \fsplit(), \fjoin(), and \fword() Functions + + \fjoin(&a,s1,n1,n2) is also new; it creates a string from an array (or + a piece of one). &a is the name of the array (a range specifier can be + included); s1 is a character or string to separate each element in the + result string (can be omitted, in which case the elements are not + separated at all), and n1 is a grouping mask, explained below. If s1 + is empty or not specified, the array elements are separated with + spaces. If you want the elements concatenated with no separator, + include a nonzero n2 argument. Given the array: + + declare \&a[] = 0 1 2 3 4 5 6 7 8 9 + + you can get effects like this: + + \fjoin(&a) 0 1 2 3 4 5 6 7 8 9 + \fjoin(&a,:) 0:1:2:3:4:5:6:7:8:9 + \fjoin(&a,{,}) 0,1,2,3,4,5,6,7,8,9 + \fjoin(&a,...) 0...1...2...3...4...5...6...7...8...9 + \fjoin(&a,,,1) 0123456789 + + \fsplit(), \fword(), \fstripb(), and \fjoin() accept a "grouping mask" + argument, n1, which is a number from 0 to 63, in which: + + 1 = "" doublequotes + 2 = {} braces + 4 = '' singlequotes + 8 = () parentheses + 16 = [] square brackets + 32 = <> angle brackets + + These can be OR'd (added) together to make any number 0-63 (-1 is + treated the same as 63, 0 means no grouping). If a bit is on, the + corresponding kind of grouping is selected. (If more than 1 bit is set + for \fjoin(), only the lowest-order one is used.) + + If you include the same character in the grouping mask and the include + list, the grouping mask takes precedence. Example: + + def \%a a "b c d" e + \fsplit(\%a,&a[],,,-1) = 3 <-- doublequote used for grouping + \fsplit(\%a,&a[],,",-1) = 3 <-- doublequote still used for grouping + + Nesting of matched left and right grouping characters (parentheses, + braces, and brackets, but not quotes) is recognized. Example: + + def \%a a (b c n o) p + \fsplit(\%a,&a,,,0) = 16 (no grouping) + \fsplit(\%a,&a,,,2) = 15 (braces only) + \fsplit(\%a,&a,,,16) = 11 (square brackets only) + \fsplit(\%a,&a,,,32) = 7 (angle brackets only) + \fsplit(\%a,&a,,,63) = 3 (all) + \fsplit(\%a,&a,,,-1) = 3 (all) + + \fsplit() and \fjoin() are "reciprocal" functions. You can split a + string up into an array and join it back into a new string that is + equivalent, as long as \fsplit() and \fjoin() are given equivalent + grouping masks, except that the type of braces might change. Example: + + def \%a a {b c [d e] f g} "h i" j m + echo STRING=[\%a] + echo WORDS=\fsplit(\%a,&a,,,-1) + show array a + asg \%b \fjoin(&a,{ },2) + echo JOIN =[\%b] + echo WORDS=\fsplit(\%b,&b,,,-1) + show array b + + The arrays a and b are identical. The strings a and b are as follows: + + \%a: a {b c [d e] f g} "h i" j m + \%b: a {b c [d e] f g} {h i} j {k l} m + + It is possible to quote separator grouping characters with backslash + to override their grouping function. And of course to include + backslash itself in the string, it must be quoted too. Furthermore, + each backslash must be doubled, so the command parser will still pass + one backslash to \fsplit() for each two that it sees. Here are some + examples using \fsplit() with a grouping mask of 8 (treat parentheses + as grouping characters). + + String Result + a b c d e f 6 + a b\\ c d e f 5 + a b (c d e) f 4 + a b \\(c d e\\) f 6 + a b \\\\(c d e\\\\) f 7 + + \fsplit() has also been changed to create its array (if one is given) + each time it is called, so now it can be conveniently called in a loop + without having to redeclare the array each time. + + Incidentally... Sometimes you might want to invoke \fsplit() in a + situation where you don't care about its return value, e.g. when you + just want to fill the array. Now you can "call" \fsplit() or any other + function with the new [441]VOID command: + + void \fsplit(\%a,&a) + + \fsplit() and \fjoin() also accept a new, optional 6th argument, an + options flag, a number that can specify a number of options. So far + there is just one option, whose value is 1: + + separator-flag + Normally separators are collapsed. So, for example, + + \fword(Three little words,2) + + returns "little" (the second word). Space is a separator, but + there are multiple spaces between each word. If the value 1 is + included in the option flag, however, each separator counts. If + two separators are adjacent, an empty word is produced between + them. This is useful for parsing (e.g.) comma-separated lists + exported from databases or spreadsheets. + + 8.7.3. The \fcmdstack() Function + + The new \fcmdstack() function gives access to the command stack: + + \fcmdstack(n1,n2) + Arguments: n1 is the command stack level. If omitted, the + current level, \v(cmdlevel), is used. n2 is a function code + specifying the desired type of information: + + 0 (default) = name of object at level n1. + 1 (nonzero) = object type (0 = prompt; 1 = command file; 2 = macro). + + The default for n2 is 0. + + The name associated with prompt is "(prompt)". Here's a loop that can + be included in a macro or command file to show the stack (similar to + what the SHOW STACK command does): + + for \%i \v(cmdlevel) 0 -1 { + echo \%i. [\fcmdstack(\%i,1)] \fcmdstack(\%i,0) + } + + In this connection, note that \v(cmdfile) always indicates the most + recently invoked active command file (if any), even if that file is + executing a macro. Similarly, \v(macro) indicates the most recently + invoked macro (if any), even if the current command source is not a + macro. The name of the "caller" of the currently executing object + (command file or macro) is: + + \fcmdstack(\v(cmdlevel)-1) + + and its type is: + + \fcmdstack(\v(cmdlevel)-1,1) + + To find the name of the macro that invoked the currently executing + object, even if one or more intermediate command files (or prompting + levels) are involved, use a loop like this: + + for \%i \v(cmdlevel)-1 0 -1 { + if = \fcmdstack(\%i,1) 2 echo CALLER = \fcmdstack(\%i,0) + } + + Of course if you make a macro to do this, the macro must account for + its own additional level: + + define CALLER { + for \%i \v(cmdlevel)-2 0 -1 { + if = \fcmdstack(\%i,1) 2 return \fcmdstack(\%i,0) + } + return "(none)" + } + + The built-in variable \v(cmdsource) gives the current command source + as a word ("prompt", "file", or "macro"). + + 8.7.4. The VOID Command + + VOID is like ECHO in that all functions and variables in its argument + text are evaluated. but it doesn't print anything (except possibly an + error message if a function was invocation contained or resulted in + any errors). VOID sets FAILURE if it encounters any errors, SUCCESS + otherwise. + + [ [442]Top ] [ [443]Contents ] [ [444]C-Kermit Home ] [ [445]Kermit + Home ] + _________________________________________________________________ + + 8.8. The RETURN and END Commands + + The execution of a macro is terminated in any of the following ways: + + * With an END [ number [ message ] ] command. If a number is given, + the macro succeeds if the number is 0, and fails if it is not + zero; if a number is not given, the macro succeeds. + * With a STOP command, which works just like END except it peels + back the command stack all the way to top level. + * With a RETURN [ text ] command, in which case the macro always + succeeds. + * By running out of commands to execute, in which case the macro + succeeds or fails according the most recently executed command + that sets success or failure. + + The same considerations apply to command files invoked by the TAKE + command. + + If a macro does not execute any commands that set success or failure, + then invoking the macro does not change the current SUCCESS/FAILURE + status. It follows, then, that the mere invocation of a macro does not + change the SUCCESS/FAILURE status either. This makes it possible to + write macros to react to the status of other commands (or macros), for + example: + + define CHKLINE { + if success end 0 + stop 1 SET LINE failed - please try another device. + } + set modem type usrobotics + set line /dev/cua0 + chkline + set speed 57600 + dial 7654321 + + By the way, none of this is news. But it was not explicitly documented + before, and C-Kermit 7.0 and earlier did not always handle the RETURN + statement as it should have. + + [ [446]Top ] [ [447]Contents ] [ [448]C-Kermit Home ] [ [449]Kermit + Home ] + _________________________________________________________________ + + 8.9. UNDEFINing Groups of Variables + + The UNDEFINE command, which previously accepted one variable name, now + accepts a list of them, and also accepts wildcard notation to allow + deletion of variables that match a given pattern. + + UNDEFINE [ switches ] name [ name [ name [ ... ] ] ] + Undefines the variables whose names are given. Up to 64 names + may be given in one UNDEFINE command. + + If you omit the switches and include only one name, the UNDEFINE + command works as before. + + Switches include: + + /MATCHING + Specifies that the names given are to treated as patterns + rather than literal variable names. Note: pattern matching + can't be used with array references; use the ARRAY command to + manipulate arrays and subarrays. + + /LIST + List the name of each variable to be undefined, and whether it + was undefined successfully ("ok" or "error"), plus a summary + count at the end. + + /SIMULATE + List the names of the variables that would be deleted without + actually deleting them. Implies /LIST. + + The UNDEFINE command fails if there were any errors and succeeds + otherwise. + + The new _UNDEFINE command is like UNDEFINE, except the names are + assumed to be variable names themselves, which contain the names (or + parts of them) of the variables to be undefined. For example, if you + have the following definitions: + + define \%a foo + define foo This is some text + + then: + + undef \%a + + undefines the variable \%a, but: + + _undef \%a + + undefines the macro foo. + + Normal Kermit patterns are used for matching; metacharacters include + asterisk, question mark, braces, and square brackets. Thus, when using + the /MATCHING switch, if the names of the macros you want to undefine + contain any of these characters, you must quote them with backslash to + force them to be taken literally. Also note that \%* is not the name + of a variable; it is a special notation used within a macro for "all + my arguments". The command "undef /match \%*" deletes all \%x + variables, where x is 0..9 and a..z. Use "undef /match \%[0-9]" to + delete macro argument variables or "undef /match \%[i-n]" to delete a + range of \%x variables. + + [ [450]Top ] [ [451]Contents ] [ [452]C-Kermit Home ] [ [453]Kermit + Home ] + _________________________________________________________________ + + 8.10. The INPUT and MINPUT Commands + + As of C-Kermit 8.0.211, the INPUT and MINPUT commands accept a switch: + + [M]INPUT /NOMATCH timeout + The /NOMATCH switch allows INPUT or MINPUT to read incoming + material for the specified amount of time, without attempting + to match it with any text or patterns. When this switch is + included, the [M]INPUT command succeeds when the timeout + interval expires, with \v(instatus) set to 1, meaning "timed + out", or fails upon interruption or i/o error. + + Also in version 8.0.211, there is a new way to apply a scale factor to + [M]INPUT timeouts: + + SET INPUT SCALE-FACTOR floating-point-number + This scales all [M]INPUT timeouts by the given factor, allowing + time-sensitive scripts to be adjusted to changing conditions + such as congested networks or different-speed modems without + having to change each INPUT-class command. This affects only + those timeouts that are given in seconds, not as wall-clock + times. Although the scale factor can have a fractional part, + the INPUT timeout is still an integer. The new built-in + variable \v(inscale) tells the current INPUT SCALE-FACTOR. + + The MINPUT command can be used to search the incoming data stream for + several targets simultaneously. For example: + + MINPUT 8 one two three + + waits up to 8 seconds for one of the words "one", "two", or "three" to + arrive. Words can be grouped to indicate targets that contain spaces: + + MINPUT 8 nineteeen twenty "twenty one" + + And of course you can also use variables in place of (or as part of) + the target names: + + MINPUT 8 \%a \&x[3] \m(foo) + + Until now you had to know the number of targets in advance when + writing the MINPUT statement. Each of the examples above has exactly + three targets. + + But suppose your script needs to look for a variable number of + targets. For this you can use arrays and \fjoin(), described in + [454]Section 8.7. Any number of \fjoin() invocations can be included + in the MINPUT target list, and each one is expanded into the + appropriate number of separate targets each time the MINPUT command is + executed. Example: + + declare \&a[10] = one two three + minput 10 foo \fjoin(&a) bar + + This declares an array of ten elements, and assigns values to the + first three of them. The MINPUT command looks for these three (as well + as the words "foo" and "bar"). Later, if you assign additional + elements to the array, the same MINPUT command also looks for the new + elements. + + If an array element contains spaces, each word becomes a separate + target. To create one target per array element, use \fjoin()'s + grouping feature: + + dcl \&a[] = {aaa bbb} {ccc ddd} {xxx yyy zzz} + + minput 10 \fjoin(&a) <-- 7 targets + minput 10 \fjoin(&a,,2) <-- 3 targets + + [ [455]Top ] [ [456]Contents ] [ [457]C-Kermit Home ] [ [458]Kermit + Home ] + _________________________________________________________________ + + 8.11. Learned Scripts + + C-Kermit now includes a simple script recorder that monitors your + commands, plus your actions during CONNECT mode, and automatically + generates a script program that mimics what it observed. You should + think of this feature as a script-writing ASSISTANT since, as you will + see [459]later in this section, the result generally needs some + editing to make it both secure and flexible. The script recorder is + controlled by the new LEARN command: + + LEARN [ /ON /OFF /CLOSE ] [ filename ] + If you give a filename, the file is opened for subsequent + recording. The /ON switch enables recording to the current file + (if any); /OFF disables recording. /CLOSE closes the current + script recording file (if any). If you give a filename without + any switches, /ON is assumed. + + The /OFF and /ON switches let you turn recording off and on during a + session without closing the file. + + When recording: + + * All commands that you type (or recall) at the prompt are recorded + in the file except: + + LEARN commands are not recorded. + + The CONNECT command is not recorded. + + The TELNET command is converted to SET HOST /NETWORK:TCP. + * Commands obtained from macros or command files are not recorded. + * During CONNECT: + + Every line you type is converted to an OUTPUT command. + + The last prompt before any line you type becomes an INPUT + command. + + Timeouts are calculated automatically for each INPUT command. + + A PAUSE command is inserted before each OUTPUT command just + to be safe. + + Thus the script recorder is inherently line-oriented. It can't be used + to script character-oriented interactions like typing Space to a + "More?" prompt or editing a text file with VI or EMACS. + + But it has advantages too; for example it takes control characters + into account that might not be visible to you otherwise, and it + automatically converts control characters in both the input and output + streams to the appropriate notation. It can tell, for example that the + "$ " prompt on the left margin in UNIX is really {\{13}\{10}$ }, + whereas in VMS it might be {\{13}\{10}\{13}$ }. These sequences are + detected and recorded automatically. + + A learned script should execute correctly when you give a TAKE command + for it. However, it is usually appropriate to edit the script a bit. + The most important change would be to remove any passwords from it. + For example, if the script contains: + + INPUT 9 {\{13}\{10}Password: } + IF FAIL STOP 1 INPUT timeout + PAUSE 1 + OUTPUT bigsecret\{13} + + you should replace this by something like: + + INPUT 9 {\{13}\{10}Password: } + IF FAIL STOP 1 INPUT timeout + ASKQ pswd Please type your password: + PAUSE 1 + OUTPUT \m(pswd)\{13} + + The LEARN command can't do this for you since it knows nothing about + "content"; it only knows about lines and can't be expected to parse or + understand them -- after all, the Password prompt might be in some + other language. So remember: if you use the LEARN command to record a + login script, be sure edit the resulting file to remove any passwords. + Also be sure to delete any backup copies your editor or OS might have + made of the file. + + Other manual adjustments might also be appropriate: + + * If the target of an INPUT command can vary, you can replace the + INPUT command with MINPUT and the appropriate target list, and/or + the target with a \fpattern(). For example, suppose you are + dialing a number that can be answered by any one of 100 terminal + servers, whose prompts are ts-00>, ts-01>, ts-02>, ... ts-99>. The + script records a particular one of these, but you want it to work + for all of them, so change (e.g.): + INPUT 10 ts-23> ; or whatever + to: + INPUT 10 \fpattern(ts-[0-9][0-9]>) + * The INPUT timeout values are conservative, but they are based only + on a single observation; you might need to tune them. + * The PAUSE commands might not be necessary, or the PAUSE interval + might need adjustment. + * In case you made typographical errors during recording, they are + incorporated in your script; you can edit them out if you want to. + + Here is a sample script generated by Kermit ("learn vms.ksc") in which + a Telnet connection is made to a VMS computer, the user logs in, + starts Kermit on VMS, sends it a file, and then logs out: + + ; Scriptfile: vms.ksc + ; Directory: /usr/olga + ; Recorded: 20001124 15:21:23 + + SET HOST /NETWORK:TCP vms.xyzcorp.com + IF FAIL STOP 1 Connection failed + + INPUT 7 {\{13}\{10}\{13}Username: } + IF FAIL STOP 1 INPUT timeout + PAUSE 1 + OUTPUT olga\{13} + INPUT 3 {\{13}\{10}\{13}Password: } + IF FAIL STOP 1 INPUT timeout + PAUSE 1 + OUTPUT secret\{13} + INPUT 18 {\{13}\{10}\{13}$ } + IF FAIL STOP 1 INPUT timeout + PAUSE 1 + OUTPUT set default [.incoming]\{13} + INPUT 12 {\{13}\{10}\{13}$ } + IF FAIL STOP 1 INPUT timeout + PAUSE 1 + OUTPUT kermit\{13} + INPUT 15 {\{13}\{10}\{13}ALTO:[OLGA.INCOMING] C-Kermit>} + IF FAIL STOP 1 INPUT timeout + PAUSE 1 + OUTPUT receive\{13} + send myfile.txt + + INPUT 18 {\{13}\{10}\{13}ALTO:[OLGA.INCOMING] C-Kermit>} + IF FAIL STOP 1 INPUT timeout + PAUSE 1 + OUTPUT exit\{13} + INPUT 6 {\{13}\{10}\{13}$ } + IF FAIL STOP 1 INPUT timeout + PAUSE 1 + OUTPUT logout\{13} + close + exit + + The commands generated by Kermit during CONNECT (INPUT, IF FAIL, + PAUSE, and OUTPUT) have uppercase keywords; the commands typed by the + user are in whatever form the user typed them (in this case, + lowercase). + + [ [460]Top ] [ [461]Contents ] [ [462]C-Kermit Home ] [ [463]Kermit + Home ] + _________________________________________________________________ + + 8.12. Pattern Matching + + A pattern is a character string that is used to match other strings. + Patterns can contain metacharacters that represent special actions + like "match any single character", "match zero or more characters", + "match any single character from a list", and so on. The best known + application of patterns is in file specifications that contain + wildcards, as in "send *.txt", meaning "send all files whose names end + with .txt". + + Patterns are also used in increasingly many other ways, to the extent + it is useful to point out certain important distinctions in the ways + in which they are used: + + Anchored Patterns + If an anchored pattern does not begin with "*", it must match + the beginning of the string, and if it does not end with "*", + it must match the end of the string. For example, the anchored + pattern "abc" matches only the string "abc", not "abcde" or + "xyzabc" or "abcabc". The anchored pattern "abc*" matches any + string that starts with "abc"; the anchored pattern "*abc" + matches any string that ends with "abc"; the anchored pattern + "*abc*" matches any string that contains "abc" (including any + that start and/or end with it). + + Floating Patterns + A floating pattern matches any string that contains a substring + that matches the pattern. In other words, a floating pattern + has an implied "*" at the beginning and end. You can anchor a + floating pattern to the beginning by starting it with "^", and + you can anchor it to the end by ending it with "$" (see + examples below). + + Wildcards + A wildcard is an anchored pattern that has the additional + property that "*" does not match directory separators. + + This terminology lets us describe Kermit's commands with a bit more + precision. When a pattern is used for matching filenames, it is a + wildcard, except in the TEXT-PATTERNS and BINARY-PATTERNS lists and + /EXCEPT: clauses, in which case directory separators are not + significant (for example, a BINARY-PATTERN of "*.exe" matches any file + whose name ends in .exe, no matter how deeply it might be buried in + subdirectories). When Kermit parses a file specification directly, + however, it uses the strict wildcard definition. For example, "send + a*b" sends all files whose names start with "a" and end with "b" in + the current directory, and not any files whose names end with "b" that + happen to be in subdirectories whose names start with "a". And as + noted, wildcards are anchored, so "delete foo" deletes the file named + "foo", and not all files whose names happen to contain "foo". + + Most other patterns are anchored. For example: + + if match abc bc ... + + does not succeed (and you would be surprised if it did!). In fact, the + only floating patterns are the ones used by commands or functions that + search for patterns in files, arrays, or strings. These include: + + * The GREP and TYPE /MATCH commands. + * The \fsearch(), \frsearch(), and \farraylook() functions. + + Thus these are the only contexts in which explicit anchors ("^" and + "$") may be used: + + grep abc *.txt + Prints all lines containing "abc" in all files whose names end + with ".txt". + + grep ^abc *.txt + Prints all lines that start with "abc" in all ".txt" files. + + grep abc$ *.txt + Prints all lines that end with "abc" in all ".txt" files. + + grep ^a*z$ *.txt + Prints all lines that start with "a" and end with "z" in all + ".txt" files. + + Similarly for TYPE /PAGE, /fsearch(), /frsearch(), and \farraylook(). + + Here is a brief summary of anchored and floating pattern equivalences: + + Anchored Floating + abc ^abc$ + *abc abc$ + abc* ^abc + *abc* abc + + [ [464]Top ] [ [465]Contents ] [ [466]C-Kermit Home ] [ [467]Kermit + Home ] + _________________________________________________________________ + + 8.13. Dates and Times + + C-Kermit's comprehension of date-time formats is considerably expanded + in version 8.0. Any command that reads dates, including the DATE + command itself, or any switch, such as the /BEFORE: and /AFTER: + switches, or any function such as \fcvtdate(), now can understand + dates and times expressed in any ISO 8601 format, in Unix "asctime" + format, in FTP MDTM format, and in practically any format used in RFC + 822 or RFC 2822 electronic mail, with or without timezones, and in a + great many other formats as well. HELP DATE briefly summarizes the + acceptable date-time formats. + + Furthermore, C-Kermit 8.0 includes a new and easy-to-use form of + date-time arithmetic, in which any date or time can be combined with a + "delta time", to add or subtract the desired time interval (years, + months, weeks, days, hours, minutes, seconds) to/from the given date. + And new functions are available to compare dates and to compute their + differences. + + As you can imagine, all this requires quite a bit of "syntax". The + basic format is: + + [ date ] [ time ] [ delta ] + + Each field is optional, but in most cases (depending on the context) + there must be at least one field. If a date is given, it must come + first. If no date is given, the current date is assumed. If no time is + given, an appropriate time is supplied depending on whether a date was + supplied. If no delta is given, no arithmetic is done. If a delta is + given without a date or time, the current date and time are used as + the base. + + Date-time-delta fields are likely to contain spaces (although they + need not; space-free forms are always available). Therefore, in most + contexts -- and notably as switch arguments -- date-time information + must be enclosed in braces or doublequotes, for example: + + send /after:"8-Aug-2001 12:00 UTC" *.txt + + Kermit's standard internal format for dates and times is: + + yyyymmdd hh:mm:ss + + for example: + + 20010208 10:28:01 + + Date-times can always be given in this format. yyyy is the 4-digit + year, mm is the two-digit month (1-12; supply leading zero for + Jan-Sep), dd is the 2-digit day (leading zero for 1-9), hh is the hour + (0-23), mm the minute (0-59), ss the second (0-59), each with leading + zero if less than the field width. The date and time can be separated + by a space, an underscore, a colon, or the letter T. The time is in + 24-hour format. Thus the various quantites are at the following fixed + positions: + +Position Contents + 1-4 Year (4 digits, 0000-9999) + 5-6 Month (2 digits, 1-12) + 7-8 Day (2 digits, 1-31) + 9 Date-Time Separator (space, :, _, or the letter T) + 10-11 Hour (2 digits, 0-23) + 12 Hour-Minute Separator (colon) + 13-14 Minute (2 digits, 0-59) + 15 Minute-Second Separator (colon) + 16-17 Second (2 digits, 0-59) + + Example: + + 19800526 13:07:12 26 May 1980, 13:07:12 (1:07:12PM) + + This is the format produced by the DATE command and by any function + that returns a date-time. It is suitable for lexical comparison and + sorting, and for use as a date-time in any Kermit command. When this + format is given as input to a command or function, various date-time + separators (as noted) are accepted: + + 19800526 13:07:12 26 May 1980, 13:07:12 (1:07:12PM) + 20010208_10:28:35 2 February 2001, 10:28:35 AM + 18580101:12:00:00 1 January 1858, noon + 20110208T00:00:00 2 February 2011, midnight + + Certain other special date-time formats that are encountered on + computer networks are recognized: + + Asctime Format + This is a fixed format used by Unix, named after Unix's + asctime() ("ASCII time") function. It is always exactly 24 + characters long. Example: Fri Aug 10 16:38:01 2001 + + Asctime with Timezone + This is like Asctime format, but includes a 3-character + timezone between the time and year. It is exactly 28 characters + long. Example: Fri Aug 10 16:38:01 GMT 2001 + + E-Mail Format + E-mail date-time formats are defined in [468]RFC 2822 with a + fair amount of flexibility and options. The following examples + are typical of e-mails and HTTP (web-page) headers: + + Sat, 14 Jul 2001 11:49:29 (No timezone) + Fri, 24 Mar 2000 14:19:59 EST (Symbolic timezone) + Tue, 26 Jun 2001 10:19:45 -0400 (EDT) (GMT Offset + comment) + + FTP MDTM Format + This is the date-time format supplied by FTP servers that + support the (not yet standard but widely used nevertheless) + MDTM command, by which the FTP client asks for a file's + modification time: + + yyyymmddhhmmss[.ffff] + + where yyyy is the 4-digit year, mm is the 2-digit month, and so + on, exactly 14 digits long. An optional fractional part + (fraction of second) may also be included, separated by a + decimal point (period). Kermit rounds to the nearest second. + Example: + + 20020208102835.515 (8 February 2002 10:28:36 AM) + + 8.13.1. The Date + + The date, if given, must precede the time and/or delta, and can be in + many, many formats. For starters, you can use several symbolic date + names in place of actual dates: + + NOW + This is replaced by the current date and time. The time can not + be overriden (if you want to supply a specific time, use TODAY + rather than NOW). + + TODAY + This is replaced by the current date and a default time of + 00:00:00 is supplied, but can be overridden by a specific time; + for example, if today is 8 February 2002, then "TODAY" is + "20020802 00:00:00" but "TODAY 10:28" is "20020802 10:28:00". + + TOMORROW + Like TODAY, but one day later (if today is 8 February 2002, + then "TOMORROW" is "20020803 00:00:00" but "TOMORROW 16:30" is + "20020803 16:30:00"). + + YESTERDAY + Like TODAY, but one day earlier. + + MONDAY, TUESDAY, WEDNESDAY, ..., SUNDAY + The date on the given day of the week, today or later. A + default time of 00:00:00 is supplied but can be overridden. + Example: "SATURDAY 12:00" means next Saturday (or today, if + today is Saturday) at noon. + + You can give an explicit date in almost any conceivable format, but + there are some rules: + + * If a date is given, it must have three fields: day, month, and + year; the order can vary (except that the month can not be last). + * If names are used for days, months, etc, they must be English. + * The year must lie between 0000 and 9999, inclusive. + * All calendar calculations use Gregorian dating, so calculated + dates for years prior to 1582 (or later, depending on the country) + will not agree with historical dates. Other forms of dating (e.g. + Hebrew, Chinese) are not supported. + + Various date-field separators are accepted: hyphen, slash, space, + underscore, period. The same field separator (if any) must be used in + both places; for example 18-Sep-2001 but not 18-Sep/2001. Months can + be numeric (1-12) or English names or abbreviations. Month name + abbreviations are normally three letters, e.g. Apr, May, Jun, Jul. + Capitalization doesn't matter. + + Here are a few examples: + + 18 Sep 2001 (English month, abbreviated) + 18 September 2001 (English month, spelled out) + 2001 Sept 18 (Year, month, day) + 18-Sep-2001 (With hyphens) + 18/09/2001 (All numeric with slashes) + 18.09.2001 (Ditto, with periods) + 18_09_2001 (Ditto, with underscores) + 09/18/2001 (See below) + 2001/09/18 (See below) + September 18, 2001 (Correspondence style) + Sep-18-2001 (Month-day-year) + 20010918 (Numeric, no separators) + + You can also include the day of the week with a specific date, in + which case it is accepted (if it is a valid day name), but not + verified to agree with the given date: + + Tue, 18 Sep 2001 (Abbreviated, with comma) + Tue,18 Sep 2001 (Comma but no space) + Tue 18 Sep 2001 (Abbreviated, no comma) + Tuesday 18 Sep 2001 (Spelled out) + Tuesday, 18 Sep 2001 (etc) + Friday, 18 Sep 2001 (Accepted even if not Friday) + + In all-numeric dates with the year last, such as 18/09/2001, Kermit + identifies the year because it's 4 digits, then decides which of the + other two numbers is the month or day based on its value. If both are + 12 or less and are unequal, the date is ambiguous and is rejected. In + all-numeric dates with the year first, the second field is always the + month and the third is the day. The month never comes last. A date + with no separators is accepted only if it is all numeric and has + exactly eight digits, and is assumed to be in yyyymmdd format. + + 20010918 (18-Sep-2001 00:00:00) + + or 14 digits (as in FTP MDTM format): + + 20010918123456 (18-Sep-2001 12:34:56) + + You can always avoid ambiguity by putting the year first, or by using + an English, rather than numeric, month. A date such as 09/08/2001 + would be ambiguous but 2001/09/08 is not, nor is 09-Aug-2001. + + Until the late 1990s, it was common to encounter 2-digit years, and + these are found to this day in old e-mails and other documents. Kermit + accepts these dates if they have English months, and interprets them + according to the windowing rules of [469]RFC 2822: "If a two digit + year is encountered whose value is between 00 and 49, the year is + interpreted by adding 2000, ending up with a value between 2000 and + 2049. If a two digit year is encountered with a value between 50 and + 99, or any three digit year is encountered, the year is interpreted by + adding 1900." + + If you need to specify a year prior to 1000, use leading zeros to + ensure it is not misinterpreted as a "non-Y2K-compliant" modern year: + + 7-Oct-77 (19771007 00:00:00) + 7-Oct-0077 (00771007 00:00:00) + + 8.13.2. The Time + + The basic time format is hh:mm:dd; that is hours, minutes, seconds, + separated by colons, perhaps with an optional fractional second + separated by a decimal point (period). The hours are in 24-hour + format; 12 is noon, 13 is 1pm, and so on. Fields omitted from the + right default to zero. Fields can be omitted from the left or middle + by including the field's terminating colon. Examples: + + 11:59:59 (11:59:59 AM) + 11:59 (11:59:00 AM) + 11 (11:00:00 AM) + 11:59:59.33 (11:59:59 AM) + 11:59:59.66 (Noon) + 03:21:00 (3:21:00 AM) + 3:21:00 (3:21:00 AM) + 15:21:00 (3:21:00 PM) + :21:00 (00:21:00 AM) + ::01 (00:00:01 AM) + 11::59 (11:00:59 AM) + + Leading zeros can be omitted, but it is customary and more readable to + keep them in the minute and second fields: + + 03:02:01 (03:02:01 AM) + 3:02:01 (03:02:01 AM) + 3:2:1 (03:02:01 AM) + + AM/PM notation is accepted if you wish to use it: + + 11:59:59 (11:59:59 AM) + 11:59:59AM (11:59:59 AM) + 11:59:59A.M. (11:59:59 AM) + 11:59:59am (11:59:59 AM) + 11:59:59a.m. (11:59:59 AM) + 11:59:59PM (11:59:59 PM = 23:59:59) + 11:59:59P.M. (11:59:59 PM = 23:59:59) + 11:59:59pm (11:59:59 PM = 23:59:59) + 11:59:59p.m. (11:59:59 PM = 23:59:59) + + You can omit the colons if you wish, in which case Kermit uses the + following rules to interpret the time: + + 1. 6 digits is hh:mm:ss, e.g. 123456 is 12:34:56. + 2. 5 digits is h:mm:ss, e.g. 12345 is 1:23:45. + 3. 4 digits is hh:mm, e.g. 1234 is 12:34. + 4. 3 digits is h:mm, e.g. 123 is 1:23. + 5. 2 digits is hh, e.g. 12 is 12:00. + 6. 1 digit is h (the hour), e.g. 1 is 1:00. + + Examples: + + 1 (01:00:00 AM) + 10 (10:00:00 AM) + 230 (02:30:00 AM) + 230pm (02:30:00 PM = 14:30:00) + 1115 (11:15:00 AM) + 2315 (11:15:00 PM = 23:15:00 PM) + 23150 (02:31:50 AM) + 231500 (23:15:00 PM) + + 8.13.3. Time Zones + + If a time is given, it can (but need not) be followed by a time zone + designator. If no time zone is included, the time is treated as local + time and no timezone conversions are performed. + + The preferred time zone designator is the UTC Offset, as specified in + [470]RFC 2822: a plus sign or minus sign immediately followed by + exactly four decimal digits, signifying the difference in hh (hours) + and mm (minutes) from Universal Coordinated Time (UTC, also known as + Greenwich Mean Time, or GMT), with negative numbers to the West and + positive numbers to the East. For example: + + Fri, 13 Jul 2001 12:54:29 -0700 + + indicates a local time of 12:54:29 that is 07 hours and 00 minutes + behind (less than, East of) Universal Time. The space is optional, so + the example could also be written as: + + Fri, 13 Jul 2001 12:54:29-0700 + + The following symbolic time zones are also accepted, as specified by + [471]RFC 2822 and/or in ISO 8601: + + GMT = +0000 Greenwich Mean Time + Z = +0000 Zulu (Zero Meridian) Time + UTC = +0000 Universal Coordinated Time + UT = +0000 Universal Time + EDT = -0400 Eastern (USA) Daylight Time + EST = -0500 Eastern (USA) Standard Time + CDT = -0500 Central (USA) Daylight Time + CST = -0600 Central (USA) Standard Time + MDT = -0600 Mountain (USA) Daylight Time + MST = -0700 Mountain (USA) Standard Time + PDT = -0700 Pacific (USA) Daylight Time + PST = -0800 Pacific (USA) Standard Time + + Note that GMT, Z, UTC, and UT all express the same concept: standard + (not daylight) time at the Zero Meridian. UTC, by the way, is an + international standard symbol and does not correspond to the order of + the English words, Universal Coordinated Time, but it happens to have + the same initial letters as these words. Of course hundreds of other + symbolic timezones and variations exist, but they are not + standardized, and are therefore not supported by Kermit. + + When a time zone is included with a time, the time is converted to + local time. In case the conversion crosses a midnight boundary, the + date is adjusted accordingly. Examples converting to EST (Eastern USA + Standard Time = -0500): + + 11:30:00 = 11:30:00 + 11:30:00 EST = 11:30:00 + 11:30:00 GMT = 06:30:00 + 11:30:00 PST = 14:30:00 + 11:30:00Z = 06:30:00 + 11:30PM GMT = 18:30:00 + 11:30 -0500 = 11:30:00 + 11:30 -0800 = 08:30:00 + 11:30 +0200 = 04:30:00 + + Unlike most of Kermit's other date-time conversions, timezone + knowledge (specifically, the offset of local time from UTC) is + embodied in the underlying operating system, not in Kermit itself, and + any conversion errors in this department are the fault of the OS. For + example, most UNIX platforms do not perform conversions for years + prior to 1970. + + 8.13.4. Delta Time + + Date/time expressions can be composed of a date and/or time and a + delta time, or a delta time by itself. When a delta time is given by + itself, it is relative to the current local date and time. Delta times + have the following general format: + + {+,-}[number units][hh[:mm[:ss]]] + + In other words, a delta time always starts with a plus or minus sign, + which is followed by a "part1", a "part2", or both. The "part1", if + given, specifies a number of days, weeks, months, or years; "part2" + specifies a time in hh:mm:ss notation. In arithmetic terms, these + represents some number of days or other big time units, and then a + fraction of a day expressed as hours, minutes, and seconds; these are + to be added to or subtracted from the given (or implied) date and + time. The syntax is somewhat flexible, as shown by the following + examples: + + +1 day (Plus one day) + +1day (Ditto) + +1d (Ditto) + + 1 day (Ditto) + + 1 day 3:00 (Plus one day and 3 hours) + +1d3:00 (Ditto) + +1d3 (Ditto) + +3:00:00 (Plus 3 hours) + +3:00 (Ditto) + +3 (Ditto) + +2 days (Plus 2 days) + -12 days 7:14:22 (Minus 12 days, 7 hours, 14 minutes, and 22 seconds) + + The words "week", "month", and "year" can be used like "day" in the + examples above. A week is exactly equivalent to 7 days. When months + are specified, the numeric month number of the date is incremented or + decremented by the given number, and the year and day adjusted + accordingly if necessary (for example, 31-Jan-2001 +1month = + 03-Mar-2001 because February does not have 31 days). When years are + specified, they are added or subtracted to the base year. Examples + (assuming the current date is 10-Aug-2001 and the current time is + 19:21:11): + + 18-Sep-2001 +1day (20010918 00:00:00) + today +1day (20010811 00:00:00) + now+1d (20010811 19:21:11) + + 1 day (20010811 19:21:11) + + 1 day 3:14:42 (20010811 22:35:54) + + 7 weeks (20010928 19:21:11) + +1d3:14:42 (20010811 22:35:54) + +1w3:14:42 (20010817 22:35:54) + +1m3:14:42 (20010910 22:35:54) + +1y3:14:42 (20020810 22:35:54) + 2 feb 2001 + 10 years (20110208 00:00:00) + 2001-02-08 +10y12 (20110208 12:00:00) + 31-dec-1999 23:59:59+00:00:01 (20000101 00:00:00) + 28-feb-1996 +1day (19960229 00:00:00) (leap year) + 28-feb-1997 +1day (19970301 00:00:00) (nonleap year) + 28-feb-1997 +1month (19970328 00:00:00) + 28-feb-1997 +1month 11:59:59 (19970328 11:59:59) + 28-feb-1997 +20years (20170228 00:00:00) + 28-feb-1997 +8000years (99970228 00:00:00) + + For compatibility with VMS, the following special delta-time format is + also accepted: + + +number-hh:mm:ss + -number-hh:mm:ss + + (no spaces). The hyphen after the number indicates days. It + corresponds exactly to the Kermit notation: + + +numberdhh:mm:ss + -numberdhh:mm:ss + + The following forms all indicate exactly the same date and time: + + 18-Sep-2001 12:34:56 +1-3:23:01 + 18-Sep-2001 12:34:56 +1d3:23:01 + 18-Sep-2001 12:34:56 +1 day 3:23:01 + + and mean "add a day plus 3 hours, 23 minutes, and 1 second" to the + given date. + + Note that delta times are not at all the same as UTC offsets; the + former specifies an adjustment to the given date/time and the latter + specifies that the local time is a particular distance from Universal + Time, for example: + + 11-Aug-2001 12:34:56 -0800 (20010811 16:34:56 -- UTC Offset) + 11-Aug-2001 12:34:56 -08:00 (20010811 04:34:56 -- Delta time) + + If you give a time followed by a modifer that starts with a + or - + sign, how does Kermit know whether it's a UTC offset or a delta time? + It is treated as a UTC offset if the sign is followed by exactly four + decimal digits; otherwise it is a delta time. Examples (for USA + Eastern Daylight Time): + + 11-Aug-2001 12:34:56 -0800 (20010811 16:34:56 -- UTC Offset) + 11-Aug-2001 12:34:56 -08:00 (20010811 04:34:56 -- Delta time) + 11-Aug-2001 12:34:56 -800 (20010811 04:34:56 -- Delta time) + 11-Aug-2001 12:34:56 -8 (20010811 04:34:56 -- Delta time) + + The first example says that at some unknown place which is 8 hours + ahead of Universal Time, the time is 12:34:56, and this corresponds to + 16:34:56 in Eastern Daylight time. The second example says to subtract + 8 hours from the local time. The third and fourth are delta times + because, even though a colon is not included, the time does not + consist of exactly 4 digits. + + When a delta time is written after a timezone, however, there is no + ambiguity and no syntax distinction is required: + + 11-Aug-2001 12:34:56 -0800 -0800 (20010811 08:34:56) + 11-Aug-2001 12:34:56 -0800 -08:00 (Ditto) + 11-Aug-2001 12:34:56 -08:00 -08:00 (Illegal) + + 8.13.5. The DATE Command + + Obviously a great many combinations of date, time, time zone, and + delta time are possible, as well as many formatting options. The + purpose of all this flexibility is to comply with as many standards as + possible -- Internet RFCs, ISO standards, and proven corporate + standards -- as well as with notations commonly used by real people, + in order that dates and times from the widest variety of sources can + be assigned to a variable and used in any date-time field in any + Kermit command. + + You can test any date-and/or-time format with the DATE command, which + converts it to standard yyyymmdd hh:mm:ss format if it is understood, + or else gives an explicit error message (rather than just "BAD DATE" + as in previous C-Kermit releases) to indicate what is wrong with it. + Examples (on Tuesday, 31 July 2001 in New York City, Eastern Daylight + Time, UTC -0400): + + DATE command argument Result + 12:30 20010731 12:30:00 + 12:30:01 20010731 12:30:01 + 12:30:01.5 20010731 12:30:02 + 1230 20010731 12:30:00 + 230 20010731 02:30:00 + 230+1d 20010801 02:30:00 + 230+1d3:00 20010801 05:30:00 + 20010718 19:21:15 20010718 19:21:15 + 20010718_192115 20010718 19:21:15 + 20010718T192115 20010718 19:21:15 + 18 Jul 2001 +0400 20010717 23:59:59 + 18 Jul 2001 192115 20010718 19:21:15 + 18 Jul 2001 192115.8 20010718 19:21:16 + 18-Jul-2001T1921 20010718 19:21:00 + 18-Jul-2001 1921Z 20010718 15:21:00 + 18-Jul-2001 1921 GMT 20010718 15:21:00 + 18-Jul-2001 1921 UTC 20010718 15:21:00 + 18-Jul-2001 1921 Z 20010718 15:21:00 + 18-Jul-2001 1921Z 20010718 15:21:00 + 18-Jul-2001 1921 -04:00:00 20010718 19:21:00 + 21-Jul-2001_08:20:00am 20010721 08:20:00 + 21-Jul-2001_8:20:00P.M. 20010721 20:20:00 + Fri Jul 20 11:26:25 2001 20010720 11:26:25 + Fri Jul 20 11:26:25 GMT 2001 20010720 07:26:25 + Sun, 9 Apr 2000 06:46:46 +0100 20000409 01:46:46 + Sunday, 9 Apr 2000 06:46:46 +0100 20000409 01:46:46 + now 20010731 19:41:12 + today 20010731 00:00:00 + today 09:00 20010731 09:00:00 + tomorrow 20010801 00:00:00 + tomorrow 09:00 20010801 09:00:00 + tomorrow 09:00 GMT 20010801 05:00:00 + yesterday 20010730 00:00:00 + yesterday 09:00 20010730 09:00:00 + + 3 days 20010803 00:00:00 + +3 days 20010803 00:00:00 + +3days 20010803 00:00:00 + + 3days 20010803 00:00:00 + + 3 days 09:00 20010803 09:00:00 + + 2 weeks 20010814 00:00:00 + + 1 month 20010831 00:00:00 + - 7 months 20001231 00:00:00 + + 10 years 20110731 00:00:00 + friday 20010803 00:00:00 + saturday 20010804 00:00:00 + sunday 20010805 00:00:00 + monday 20010806 00:00:00 + tuesday 20010731 00:00:00 + wednesday 20010801 00:00:00 + thursday 20010802 00:00:00 + friday 07:00 20010803 07:00:00 + thursday 1:00pm 20010802 13:00:00 + thursday 1:00pm GMT 20010802 09:00:00 + Thu, 10 Nov 94 10:50:47 EST 19941110 10:50:47 + Fri, 20 Oct 1995 18:35:15 -0400 (EDT) 19951020 18:35:15 + 31/12/2001 20011231 00:00:00 + 12/31/2001 20011231 00:00:00 + 2001-July-20 20010720 00:00:00 + 2001-September-30 20010930 00:00:00 + 30-September-2001 20010930 00:00:00 + Sep 30, 2001 12:34:56 20010930 12:34:56 + September 30, 2001 20010930 00:00:00 + September 30, 2001 630 20010930 06:30:00 + September 30 2001 630 20010930 06:30:00 + Sep-30-2001 12:34:59 20010930 12:34:59 + 20010807113542.014 20010807 11:35.42 + 20010807113542.014Z 20010807 07:35:42 + + 8.13.6. New Date-Time Functions + + In the following descriptions, date-time function arguments are the + same free-format date-time strings discussed above, with the same + defaults for missing fields. They are automatically converted to + standard format internally prior to processing. + + \fcvtdate(d1) + Converts the date-time d1 to standard format and local time. + This function is not new, but now it accepts a wider range of + argument formats that can include timezones and/or delta times. + If the first argument is omitted, the current date and time are + assumed. The optional second argument is a format code for the + result: + + n1 = 1: yyyy-mmm-dd hh:mm:ss (mmm = English 3-letter month + abbreviation) + n1 = 2: dd-mmm-yyyy hh:mm:ss (ditto) + n1 = 3: yyyymmddhhmmss (all numeric) + + \futcdate(d1) + Converts the date-time d1 to Universal Coordinated Time (UTC), + also known as GMT or Zulu or Zero-Meridian time. The default d1 + is NOW. If d1 is a valid date-time, the UTC result is returned + in standard format, yyyymmdd hh:ss:mm. + + \fcmpdates(d1,d2) + Compares two free-format date-times, d1 and d2, and, if both + arguments are valid, returns a number: -1 if d1 is earlier than + (before) d2; 0 if d1 is the same as d2; 1 if d1 is later than + (after) d2. + + \fdiffdates(d1,d2) + Computes the difference between two free-format date-times, d1 + and d2. If both arguments are valid, returns a delta time which + is negative if d1 is earlier than (before) d2 and positive + otherwise. If d1 and d2 are equal, the result is "+0:00". + Otherwise, the result consists of the number of days, hours, + minutes, and seconds that separate the two date-times. If the + number of days is zero, it is omitted. If the number of days is + nonzero but the hours, minutes, and seconds are all zero, the + time is omitted. if the seconds are zero, they are omitted. + + \fdelta2secs(dt) + Converts a delta time to seconds. For example, "+1d00:00:01" to + 86401. Valid delta times must start with a + or - sign. Days + are accepted as time units, but not years, months, or weeks. If + the result would overflow a computer long word (as would happen + with 32-bit long words when the number of days is greater than + 24854), the function fails. + + HINT: Although Kermit has a number of built-in date and time + variables, it doesn't have a single one suitable for writing a + timestamp. For this you would normally use something like "\v(ndate) + \v(time)". But \fcvtdate() (with no arguments) is equivalent: it + returns the current date and time in yyyymmdd hh:mm:ss format, + suitable for time stamping. + + 8.13.7. Date-Time Programming Examples + + Here's a macro that converts any date-time to UTC, which you might use + if C-Kermit didn't already have a \futcdate() function: + + define utcdate { + .local := \fcvtdate(\%*) ; 1. + .tmp := \fcvtdate(\m(local)UTC) ; 2. + .offset := \fdiffdate(\m(local),\m(tmp)) ; 3. + .utc := \fcvtdate(\m(local)\m(offset)) ; 4. + sho mac utc ; 5. + } + + Brief explanation: Line 1 converts the macro argument, a free-format + date-time, to standard-format local time. Line 2 appends the "UTC" + timezone to the local time and converts the result to local time. In + other words, we take the same time as the local time, but pretend it's + UTC time, and convert it to local time. For example, if New York time + is 4 hours ahead of UTC, then 6:00pm New York time is 2:00pm UTC. Line + 3 gets the difference of the two results (e.g. "+04:00"). Line 4 + appends the difference (delta time) to the local time, and converts it + again, which adds (or subtracts) the UTC offset to the given time. + Line 5 displays the result. + + Here's a script that opens a web page, gets its headers into an array, + scans the array for the "Last-Modified:" header, and inteprets it: + http open www.columbia.edu + if fail stop 1 HTTP OPEN failed + http /array:a head index.html /dev/null + if fail stop 1 HTTP GET failed + show array a + for \%i 1 \fdim(&a) 1 { + .\%x := \findex(:,\&a[\%i]) + if not \%x continue + .tag := \fleft(\&a[\%i],\%x-1) + .val := \fltrim(\fsubstr(\&a[\%i],\%x+1)) + if ( eq "\m(tag)" "Last-Modified" ) { + echo HTTP Date: \m(val) + .rdate := \fcvtdate(\m(val)) + echo {Standard Date (local): \m(rdate)} + echo {Standard Date (UTC): \futcdate(\m(rdate))} + break + } + } + http close + + The result: + + HTTP Date: Mon, 13 Aug 2001 20:05:42 GMT + Standard Date (local): 20010813 16:05:42 + Standard Date (UTC): 20010813 20:05:42 + + As you can see, Kermit had no trouble decoding the date-time-string + from the website, converting to local time, and converting back to UTC + with no conflicts or loss of information. If it had been in any other + known format, the result would have been the same. + + Now suppose we want to download the web page only if it is newer than + our local copy. The \fdate(filename) function (which returns the + modification date-time of the given file) and the new \fcmpdates() + function make it easy. Insert the following just before the BREAK + statement: + + if ( < 0 \fcmpdates(\m(rdate),\fdate(index.html)) ) { + echo GETTING index.html... + http get index.html index.html + if success echo HTTP GET OK + } else { + echo index.html: no update needed + } + http close + exit + + This says, "if 0 is less than the comparison of the remote file date + and the local file date, get the remote file, otherwise skip it." And + it automatically reconciles the time-zone difference (if any). + + It would be nice to be able to extend this script into a + general-purpose website updater, but unfortunately HTTP protocol + doesn't provide any mechanism for the client to ask the server for a + list of files, recursive or otherwise. + + [ [472]Top ] [ [473]Contents ] [ [474]C-Kermit Home ] [ [475]Kermit + Home ] + _________________________________________________________________ + + 8.14. Trapping Keyboard Interruption + + Normally when you type Ctrl-C and Kermit is in command mode (as + opposed to CONNECT mode) with COMMAND INTERRUPTION ON (as it is unless + you have set it OFF), Kermit interrupts any command that is currently + in progress, and if a command file or macro is executing, rolls the + command stack back to top level, closing all open command files, + deactivating all macros, deallocating all local variables and arrays, + and leaving you at the command prompt. + + Suppose, however, you want certain actions to occur when a script is + interrupted; for example, closing open files, writing log entries, or + displaying summary results. You can do this by defining a macro named + ON_CTRLC. When Ctrl-C is detected, and a macro with this name is + defined, Kermit executes it from the current command level, thus + giving it full access to the environment in which the interruption + occurred, including local variables and open files. Only when the + ON_CTRLC macro completes execution is the command stack rolled back to + top level. + + Once the ON_CTRLC macro is defined, it can be executed only once. This + is to prevent recursion if the user types Ctrl-C while the ON_CTRLC + macro is executing. If you type Ctrl-C while the Ctrl-C macro is + active, this does not start a new copy of ON_CTRLC; rather, it returns + to the top-level command prompt. After the ON_CTRLC macro returns, it + has been removed from the macro table so if you want to use it again + or install a different Ctrl-C trap, you must execute a new DEFINE + ON_CTRLC command. In any case, as always when you interrupt a script + with Ctrl-C, its completion status is FAILURE. + + Normally the ON_CTRLC macro would be defined in the command file or + macro to which it applies, and should be declared LOCAL. This way, if + the command file or macro completes successfully without being + interrupted, the ON_CTRLC definition disappears automatically. + Otherwise the definition would still be valid and the macro would be + executed, probably out of context, the next time you typed Ctrl-C. + + Here's a simple example of a command file that sets a Ctrl-C trap for + itself: + + local on_ctrlc ; Make Ctrl-C trap local to this command file. + define on_ctrlc { ; Define the ON_CTRLC macro. + echo Interrupted at \v(time). + echo Iterations: \%n + } + xecho Type Ctrl-C to quit + for \%n 1 999 1 { ; Prints a dot every second until interrupted. + sleep 1 + xecho . + } + echo Finished normally at \v(time) ; Get here only if not interrupted. + decrement \%n + echo Iterations: \%n + + This prints a summary no matter whether it completes normally or is + interrupted from the keyboard. In both cases the trap is automatically + removed afterwards. + + For an example of how to use ON_CTRLC to debug scripts, see + [476]Section 8.1. + + [ [477]Top ] [ [478]Contents ] [ [479]C-Kermit Home ] [ [480]Kermit + Home ] + __________________________________________________________________________ + +9. S-EXPRESSIONS + + This section is primarily for those who want to write + calculation-intensive scripts, especially if they require + floating-point arithmetic, and/or for those who are familiar with the + LISP programming language. + + Ever since C-Kermit version 5 was released in 1988, scripting has been + one of its major attractions, and arithmetic is a key part of it. + Versions 5 and 6 included integer arithmetic only, using traditional + algebraic notation, e.g.: + + echo \fevaluate(3*(2+7)/2) + 13 + + C-Kermit 7.0 added support for floating-point arithmetic, but only + through function calls: + + echo \ffpdivide(\ffpmultiply(3.0,\ffpadd(2.0,7.0)),2.0) + 13.5 + + C-Kermit 8.0 introduces a third form of arithmetic that treats + integers and floating-point numbers uniformly, is easier to read and + write, and executes very quickly: + + (/ (* 3 (+ 2 7)) 2) + 13.5 + + But first some background. + + The Kermit command and scripting language differs from true + programming languages (such as C or Fortran) in many ways; one of the + most prominent differences is the way in which variables are + distinguished from constants. In a command language, words are taken + literally; for example, the Unix shell: + + cat foo.bar + + displays the file named foo.bar. Whereas in a programming language + like C, words are assumed to be variables: + + s = foo.bar; /* Assigns the value of foo.bar to the variable s */ + + To make a programming language take words literally, you have to quote + or "escape" them: + + s = "foo.bar"; /* Assigns a pointer to the string "foo.bar" to the variable +s */ + + The opposite holds for command languages: to get them to treat a word + as a variable rather than a constant, you have to escape them. For + example, in the Unix shell: + + foo=123 ; Assign value 123 to variable foo. + echo foo ; Prints "foo" + echo $foo ; Prints "123" + + And in Kermit: + + define foo 123 ; Assign value 123 to variable foo. + echo 123 ; This prints "123". + echo foo ; This prints "foo". + echo \m(foo) ; This prints "123". + + In other words, character strings (such as "foo" above) are + interpreted as literal strings, rather than variable names, except in + special commands like DEFINE that deal specifically with variable + names (or in numeric contexts as explained in [481]Section 8.2). The + special "escape" character (dollar sign ($) for the shell, backslash + (\) for Kermit) indicates that a variable is to be replaced by its + value. + + The requirement to escape variable names in command languages normally + does not impose any special hardship, but can add a considerable + notational burden to arithmetic expressions, which are typically full + of variables. Especially in Kermit when floating point numbers are + involved, where you must use special \ffpxxx() functions, e.g. + "\ffpadd(\m(a),\m(b))" rather than the simple "+" operator to add two + floating-point numbers together, because the original arithmetic + handler doesn't support floating point (this might change in the + future). To illustrate, the general formula for the area of a triangle + is: + + sqrt(s * (s - a) * (s - b) * (s - c)) + + where a, b, and c are the lengths of the triangle's three sides and: + + s = (a + b + c) / 2 + + Except in special cases (e.g. a = 3, b = 4, c = 5), the result has a + fractional part so the computation must be done using floating-point + arithmetic. We can create a Kermit 7.0 function for this as follows: + + def area { + local s t1 t2 t3 + assign s \ffpdiv(\ffpadd(\ffpadd(\%1,\%2),\%3),2.0) + assign t1 \ffpsub(\m(s),\%1) + assign t2 \ffpsub(\m(s),\%2) + assign t3 \ffpsub(\m(s),\%3) + return \ffpsqrt(\ffpmul(\m(s),\ffpmul(\m(t1),\ffpmul(\m(t2),\m(t3))))) + } + + But as you can see, this is rather cumbersome. Note, in particular, + that arithmetic functions like \ffpadd(), \ffpmul(), etc, take exactly + two operands (like their symbolic counterparts + and *), so obtaining + the product of three or more numbers (as we do in this case) is + awkward. + + Using the alternative S-Expression notation, we can reduce this to a + form that is both easier to read and executes faster (the details are + explained later): + + def newarea { + (let s (/ (+ \%1 \%2 \%3) 2.0)) + (sqrt (* s (- s \%1) (- s \%2) (- s \%3))) + } + + In both examples, the \%1..3 variables are the normal Kermit macro + arguments, referenced by the normal escaping mechanism. For increased + readability, we can also assign the macro arguments \%1, \%2, and \%3 + to the letters a, b, and c corresponding to our formula: + +def newarea { + (let a \%1 b \%2 c \%3) + (let s (/ (+ a b c) 2.0)) + (sqrt (* s (- s a) (- s b) (- s c))) +} + + And now the Kermit function reads almost like the original formula. + Here Kermit behaves more like a regular programming language. In an + S-Expression, macro names need not be escaped when they are used as + the names of numeric variables. + + [ [482]Top ] [ [483]Contents ] [ [484]C-Kermit Home ] [ [485]Kermit + Home ] + _________________________________________________________________ + + 9.1. What is an S-Expression? + + The S-Expression concept is borrowed from the Lisp programming + language. "S-Expression" is short for Symbolic Expression (itself + sometimes shortened to SEXP). S-Expressions provide a kind of + Alternative Mini-Universe within the Kermit command language when the + regular rules don't apply, a universe enclosed in parentheses. + + C-Kermit does not pretend to be a full Lisp interpreter; only the + arithmetic parts of Lisp have been incorporated: S-Expressions that + operate on numbers and return numeric values (plus extensibility + features described in [486]Section 9.8, which allow some degree of + string processing). + + An S-Expression is a list of zero or more items, separated by spaces, + within parentheses. Examples: + + () + (1) + (a) + (+ a 1) + (* 2 a b) + + If the S-Expression is empty, it has the NIL (empty) value. If it is + not empty and the first item is an operator (such as + or *), there + can be zero or more subsequent items, called the operands: + + (+ 1 2) + + Here the operator is "+" and the operands are "1" and "2", and the + value of the S-Expression is the value of the operation (in this case + 3). The operator always comes first, which is different from the + familiar algebraic notation; this because S-Expression operators can + have different numbers of operands: + + (+ 1) + (+ 1 2) + (+ 1 2 3 4 5 6 7 8 9) + + If the first item in the S-Expression is not an operator, then it must + be a variable or a number (or a macro; see [487]Section 9.8), and the + S-Expression can only contain one item; in this case, the + S-Expression's value is the value of the variable or number: + + (a) + (3) + + Operands can be numbers, variables that have numeric values, functions + that return numbers, or other S-Expressions. To illustrate an + S-Expression within an S-Expression, observe that: + + (+ 1 2) + + is equivalent to any of the following (plus an infinite number of + others): + + (+ 1 (+ 1 1)) + (+ (- 3 2) (/ 14 (+ 3 4))) + + S-Expressions can be nested to any reasonable level; for example, the + value of the following S-Expression is 64: + + (- (* (+ 2 (* 3 4)) (- 9 (* 2 2))) 6) + + Operators have no precedence, implied or otherwise, since they can't + be mixed. The only exceptions are unary + and -, which simply indicate + the sign of a number: + + (* 3 -1) + + Order of evaluation is specified entirely by parentheses, which are + required around each operator and its operands: (+ a (* b c)) instead + of (a + b * c). + + S-Expressions provide a simple and isolated environment in which + Kermit's macro names can be used without the \m(...) escaping that is + normally required. Given: + + define a 1 + define b 2 + define c 3 + + Then: + + (+ \m(a) \m(b) \m(c)) + + is equivalent to: + + (+ a b c) + + Within an S-Expression, as in other strictly numeric contexts + ([488]Section 8.2), any operand that starts with a letter is treated + as a Kermit macro name. In this context, abbreviations are not + accepted; variable names must be spelled out in full. Alphabetic case + is not significant; "a" and "A" are the same variable, but both are + different from "area". + + Of course, regular Kermit variables and functions can be used in + S-Expressions in the normal ways: + + (* \v(math_pi) (^ \%r 2)) ; Area of a circle with radius \%r + (+ \fjoin(&a)) ; Sum of all elements of array \&a[] + + [ [489]Top ] [ [490]Contents ] [ [491]C-Kermit Home ] [ [492]Kermit + Home ] + _________________________________________________________________ + + 9.2. Integer and Floating-Point-Arithmetic + + Normally, if all numbers in an S-Expression are integers, the result + is an integer: + + (+ 1 1) ; Result is 2 + (/ 9 3) ; Result is 3 + + If any of the operands is floating point, however, the result is also + floating point: + + (+ 1 1.0) ; Result is 2.0 + (/ 9.0 3) ; Result is 3.0 + + If all the operands are integers but the result has a fractional part, + the result is floating point: + + (/ 10 3) ; Result is 3.333333333333333 + + To force an integer result in such cases, use the TRUNCATE operator: + + (truncate (/ 10 3)) ; Result is 3 + + Similarly, to force a computation to occur in floating point, you can + coerce one of its operands to FLOAT: + + (+ 1 (float 1)) ; Result is 2.0 + + The result is also floating point if the magnitude of any integer + operand, intermediate result, or the result itself, is larger than the + maximum for the underlying machine architecture: + + (^ 100 100) + + If the result is too large even for floating-point representation, + "Infinity" is printed; if it is too small to be distinguished from 0, + 0.0 is returned. + + Large numbers can be used and large results generated, but they are + accurate only to the precision of the underlying machine. For example, + the result of: + + (+ 111111111111111111111 222222222222222222222) + + should be 333333333333333333333, but 333333333333333300000.0 is + produced instead if the machine is accurate to only about 16 decimal + digits, even with coercion to floating-point. The order of magnitude + is correct but the least significant digits are wrong. The imprecise + nature of the result is indicated by the ".0" at the end. Contrast + with: + + (+ 111111111 222222222) + + which produces an exact integer result. + + [ [493]Top ] [ [494]Contents ] [ [495]C-Kermit Home ] [ [496]Kermit + Home ] + _________________________________________________________________ + + 9.3. How to Use S-Expressions + + S-Expressions may be given as commands to C-Kermit. Any command whose + first character is "(" (left parenthesis) is interpreted as an + S-Expression. + + If you enter an S-Expression at the C-Kermit> prompt, its result is + printed: + + C-Kermit>(/ 10.0 3) + 3.333333333333333 + C-Kermit> + + If an S-Expression is executed within a macro or command file, its + value is not printed. However, you can control the printing action + with: + + SET SEXPRESSION ECHO { AUTO, ON, OFF } + AUTO is the default, meaning print the value at top level only; + ON means always print the value; OFF means never print it. + + In any case, the value of the most recent S-Expression (and the + S-Expression itself) may be accessed programmatically through the + following variables: + + \v(sexpression) + The S-Expression most recently executed. + + \v(svalue) + The value of the S-Expression most recently executed. + + Besides issuing S-Expressions as commands in themselves, you can also + execute them anywhere within a Kermit command, but in this case they + must be enclosed in a function call (otherwise they are taken + literally): + + \fsexpression(s) + The argument "s" is an S-Expression; the outer parentheses may + be omitted. The value of the S-Expression is returned. Note + that since S-Expressions usually contain spaces, some form of + grouping or quoting might be needed in some contexts: + + echo \fsexpression((+ 1 1)) ; Outer parentheses may be included + echo \fsexpr(+ 1 1) ; Outer parentheses may be omitted + echo Value = "\fsexp(+ 1 a)" ; Can be embedded in strings + echo Value = \&a[\fsexp(/ b 2)] ; Can be used in array subscripts + if = {\fsexp(+ 1 1)} 2 { ; Braces needed here for grouping + echo One plus one still equals two + } + + The IF statement illustrates how to use S-Expressions as (or in) IF or + WHILE conditions: + + * Although S-Expressions and IF conditions are similar in + appearance, they are not interchangeable. Therefore you must use + \fsexpr() to let Kermit know it's an S-Expression rather than a + regular IF condition, or a boolean or algebraic expression within + an IF condition. + * In contexts where a single "word" is expected, you must enclose + the \fsexp() invocation in braces if the S-Expression contains + spaces (and most of them do). + + If an S-Expression is the last command executed in a macro, its value + becomes the return value of the macro; no RETURN command is needed. + Example: + + def newarea { + (let s (/ (+ \%1 \%2 \%3) 2.0)) + (sqrt (* s (- s \%1) (- s \%2) (- s \%3))) + } + + This is equivalent to (but more efficient than): + + def newarea { + (let s (/ (+ \%1 \%2 \%3) 2.0)) + return \fsexp(sqrt (* s (- s \%1) (- s \%2) (- s \%3))) + } + + When an S-Expression is entered as a command -- that is, the first + nonblank character of the command is a left parenthesis -- then it is + allowed to span multiple lines, as many as you like, until the first + left parenthesis is matched: + + (let s (/ + (+ + \%1 + \%2 + \%3 + ) + 2.0 + ) + ) + (sqrt (* + s + (- s \%1) + (- s \%2) + (- s \%3) + ) + ) + + The S-Expression concept lends itself easily to embedding and + recursion, but the depth to which recursion can occur is limited by + the resources of the computer (memory size, address space, swap space + on disk) and other factors. There is no way that C-Kermit can know + what this limit is, since it varies not only from computer to + computer, but also from moment to moment. If resources are exhausted + by recursion, C-Kermit simply crashes; there's no way to trap this + error. However, you can set a depth limit on S-Expressions: + + SET SEXPRESSION DEPTH-LIMIT number + Limits the number of times the S-Expression reader can invoke + itself without returning to the given number. The default limit + is 1000. This limit applies to S-Expressions embedded within + other S-Expressions as well as to S-Expressions that invoke + recursive macros. If the limit is exceeded, Kermit prints + "?S-Expression depth limit exceeded" and returns to its prompt. + More about recursion in [497]Section 9.8. + + You can also test the depth programmatically: + + \v(sdepth) + The current S-Expression invocation depth. The depth includes + both nesting level and recursion. For example, in: + (foo (foo (foo (foo (foo))))), the innermost (foo) is at depth + 5. + + Help, completion, and syntax checking are not available within an + S-Expression. If you type ? within an S-Expression, it says: + + C-Kermit>(? S-Expression ("help sexp" for details) + + As it says, typing "help sexp" will display a brief help text. + + The SHOW SEXPRESSION command displays current SET SEXPRESSION settings + and related information. + + [ [498]Top ] [ [499]Contents ] [ [500]C-Kermit Home ] [ [501]Kermit + Home ] + _________________________________________________________________ + + 9.4. Summary of Built-in Constants and Operators + + Three constants are built in: + + * PI, whose value is the value of pi (the quotient of circumference + of any circle and its diameter, 3.141592653...) to the underlying + machine's precision; + * T, which always has the value 1, which signifies truth in Kermit + logical expressions or S-Expressions; + * NIL, which always has the empty value, and can serve as a False + truth value. + + These constants are specific to S-Expressions and are not visible + outside them. They may not be used as the target of an assignment. So, + for example: + + (setq t 0) Fails + assign t 0 Succeeds but this is not the same T! + + E (the base of natural logarithms, 2.7182818184...) is not built in + since it is not intrinsic in most Lisp dialects. If you want E to be + the base of natural logarithms you can: + + (setq e (exp 1)) + + Operators are either symbols (such as "+") or words. Words must be + spelled out in full, not abbreviated. Differences of alphabetic case + are ignored. + + The most basic operation in S-Expressions is evaluation: + + EVAL [ s-expression or variable or number [ another [ another ... ] ] + ] + Evaluates its operands and returns the value of the last one + evaluated. Examples: + + (eval) 0 + (eval 1) 1 + (eval a) value of a + (eval (+ 1 a)) value of a+1 + (eval (setq a 1) (setq b (+ a 0.5))) value of b (= a+0.5) + + You can use "." as a shorthand for EVAL: + + (.) + (. 1) + (. a) + (. (+ 1 a)) + (. (setq a 1) (setq b (+ a 0.5))) + + Opposite of EVAL is the operator that suppresses evaluation of its + operand: + + QUOTE item + The value (quote item) is "item". If the item is itself an + S-Expression, the result is the S-Expression with the outer + parentheses stripped. Examples: + + (quote) (illegal) + (quote a) a + (quote hello) hello + (quote (this is a string)) this is a string + (quote this is a string) (illegal) + + A shorthand notation is also accepted for quoting: + 'a is equivalent to (quote a). And therefore: + '(a b c) is equivalent to (quote (a b c)). + More about quoting in [502]Section 9.8. + + STRING item + Is a combination of EVAL and QUOTE. It evaluates the item as an + S-Expression, and then puts quotes around the result (more + about this in [503]Section 9.8). + + The following operators assign values to variables: + + SETQ [ variable [ value [ variable [ value [ ... ] ] ] ] ] + Applies to global variables. For each variable given: if a + value is not given, the variable is undefined. If a value is + given, assigns the value to the variable. The value may be a + number, a variable, or anything that resolves to a number + including an S-Expression. Returns the value of the last + assignment. Examples: + + (setq) Does nothing, returns NIL. + (setq a) Undefines a, returns NIL. + (setq a 1) Assigns 1 to a, returns 1. + (setq a 1 b 2) Assigns 1 to a, 2 to b, returns 2. + (setq a 1 b 2 c) Assigns 1 to a, 2 to b, undefines c, returns NIL. + + To undefine a variable that is not the final one in the list, give it + a value of "()" or NIL: + + (setq a () b 2) Undefines a, assigns 2 to b, returns 2. + (setq a nil b 2) Ditto. + + Note that a variable can be used right away once it has a value: + + (setq a 1 b a) Assigns 1 to a, the value of a (1) to b, returns 1. + + The results of SETQ (when used with macro names) can be checked + conveniently with SHOW MACRO, e.g: + + show mac a b c + + LET [ variable [ value [ variable [ value [ ... ] ] ] ] ] + Like SETQ, but applies to local variables. Note that "local" is + used in the Kermit sense, not the Lisp sense; it applies to the + current Kermit command level, not to the current S-Expression. + + If you want to use SETQ or LET to assign a value to a backslash + variable such as \%a or \&a[2], you must double the backslash: + + (setq \\%a 3) + (setq \\%b (+ \%a 1)) + (setq \\&a[2] (setq (\\%c (+ \%a \%b)))) + + In other words: + + * Double the backslash when you want to indicate the variable's + NAME; + * Don't double the backslash when you want its VALUE. + + See [504]Section 9.6 for a fuller explanation of variable syntax and + scope. + + Here's a summary table of arithmetic operators; in the examples, a is + 2 and b is -1.3: + + Operator Description Example Result + + Adds all operands (0 or more) (+ a b) 0.7 + - Subtracts all operands (0 or more) (- 9 5 2 1) 1 + * Multiplies all operands (0 or more) (* a (+ b 1) 3) -1.80 + / Divides all operands (2 or more) (/ b a 2) -0.325 + ^ Raise given number to given power (^ 3 2) 9 + ++ Increments variables (++ a 1.2) 3.2 + -- Decrements variables (-- a) 1 + ABS Absolute value of 1 operand (abs (* a b 3)) 7.8 + MAX Maximum of all operands (1 or more) (max 1 2 3 4) 4 + MIN Minimum of all operands (1 or more) (min 1 2 3 4) 1 + MOD (%) Modulus of all operands (1 or more) (mod 7 4 2) 1 + FLOAT Convert an integer to floating-point (float 1) 1.0 + TRUNCATE Integer part of floating-point operand (truncate 3.333) 3 + CEILING Ceiling of floating-point operand (ceiling 1.25) 2 + FLOOR Floor of floating-point operand (floor 1.25) 1 + ROUND Operand rounded to nearest integer (round 1.75) 2 + SQRT Square root of 1 operand (sqrt 2) 1.414.. + EXP e (2.71828..) to the given power (exp -1) 0.367.. + SIN Sine of angle-in-radians (sin (/ pi 2)) 1.0 + COS Cosine of angle-in-radians (cos pi) -1.0 + TAN Tangent of angle-in-radians (tan pi) 0.0 + LOG Natural log (base e) of given number (log 2.7183) 1.000.. + LOG10 Log base 10 of given number (log10 1000) 3.0 + + The ++ and -- operators are also assignment operators and work just + like SETQ and LET in their interpretations of operators and operands, + but: + + * Each target variable must already be defined and have a numeric + value; + * The assignment value is the amount by which to increment or + decrement the variable. + * If an assignment value is not given, 1 is used. + + If you include more than one variable-value pair in a ++ or -- + expression, every variable (except, optionally, the last) must be + followed by a value. Examples: + + (++ a) Equivalent to (setq a (+ a 1)) and to (++ a 1) + (++ a 2) Equivalent to (setq a (+ a 2)) + (-- a (* 2 pi)) Equivalent to (setq a (- a (* 2 pi))) + (++ a 1 b 1 c 1 d) Equivalent to four SETQs incrementing a,b,c,d by 1. + + Another group of operators forms the predicates. These return a "truth + value", in which 0 (or NIL) is false, and 1 or any other nonzero + number is true. + + Operator Description Example Result + = (or ==) Operands are equal (= 1 1.0) 1 + != Operands are not equal (!= 1 1.0) 0 + < Operands in strictly ascending order (< 1 2 3) 1 + <= Operands in ascending order (<= 1 1 2 3) 1 + > Operands in strictly descending order (> 3 2 1) 1 + >= Operands in descending order (<= 3 3 2 1) 1 + AND (&&) Operands are all true (and 1 1 1 1 0) 0 + OR (||) At least one operand is true (or 1 1 1 1 0) 1 + XOR Logical Exclusive OR (xor 3 1) 0 + NOT (!) Reverses truth value of operand (not 3) 0 + + The Exclusive OR of two values is true if one value is true and the + other value is false. + + And another group operates on bits within an integer word: + + Operator Description Example Result + & Bitwise AND (& 7 2) 2 + | Bitwise OR (| 1 2 3 4) 7 + # Bitwise Exclusive OR (# 3 1) 2 + ~ Reverses all bits (~ 3) -4 + + These operators coerce their operands to integer by truncation if + necessary. The result of bit reversal is hardware dependent. + + The final category of operator works on truth values: + + Operator Description Example Result + IF Conditional evaluation (if (1) 2 3) 2 + + IF (predicate) (s1) [ (s2) ] + The IF operator is similar to Kermit's IF command. If the + predicate is true (i.e. evaluates to a nonzero number), the + first S-Expression (s1) is evaluated and its value is returned. + Otherwise, if (s2) is given, it is evaluated and its value + returned; if (s2) is not given, nothing happens and the NIL + (empty) value is returned. + + You can group multiple expressions in the s1 and s2 expressions using + EVAL (or "."): + + (if (< a 0) (eval (setq x 0) (setq y 0)) (eval (setq x a) (setq y b))) + + or equivalently: + + (if (< a 0) (. (setq x 0) (setq y 0)) (. (setq x a) (setq y b))) + + Each operator has its own requirement as to number and type of + operands. In the following table, "number" means any kind of number -- + integer or floating-point -- or a variable, function, macro, or + S-Expression that returns a number; "vname" means variable name, + "fpnumber" means a floating-point number (or anything that resolves to + one), and "integer" means integer (or anything that resolves to one). + "truthvalue" means anything that resolves to a value of zero or an + empty value (which indicates false) or a nonzero value (which + indicates true). "any" means any kind of value, including none at all. + + Operator Number of operands Type of operands Returns + EVAL (.) 0 or more S-Expression Last value (default NIL) + STRING 1 S-Expression string + QUOTE (') 1 word string + SETQ 0 or more vname value pairs Last value (default NIL) + LET 0 or more vname value pairs Last value (default NIL) + + 0 or more number number (default 0) + - 0 or more number number (default 0) + * 0 or more number number (see note (1)) + / 2 or more number number + ^ 2 or more number number + ++ 1 or more vname value pairs Result of last increment + -- 1 or more vname value pairs Result of last decrement + ABS 1 number number + MAX 1 or more number number + MIN 1 or more number number + MOD (%) 2 number number + FLOAT 1 number fpnumber + TRUNCATE 1 number integer + CEILING 1 number integer + FLOOR 1 number integer + ROUND 1 number integer + SQRT 1 number fpnumber + EXP 1 number fpnumber + SIN 1 number fpnumber + COS 1 number fpnumber + TAN 1 number fpnumber + LOG 1 number fpnumber + LOG10 1 number fpnumber + = (==) 1 or more number truthvalue + != 1 or more number truthvalue + < 1 or more number truthvalue + <= 1 or more number truthvalue + > 1 or more number truthvalue + >= 1 or more number truthvalue + AND (&&) 1 or more truthvalue truthvalue + OR (||) 1 or more truthvalue truthvalue + XOR 2 truthvalue truthvalue + NOT (!) 1 truthvalue truthvalue + & 1 or more number (see note 2) integer + | 1 or more number (see note 2) integer + # 2 number (see note 2) integer + ~ 1 number (see note 2) integer + IF 2 or 3 truthvalue,any,any any + + Operators that don't require any arguments return the default values + shown. + + 1. The value of "*", when used as an operator, is initially "1" and + the value of the most recent S-Expression thereafter, as in Franz + Lisp. This is handy when doing a series of calculations by hand: + C-Kermit>(* 13272.42 0.40) + 5308.968 + C-Kermit>(/ * 2) + 2654.4840 + C-Kermit> + 2. The bitwise operators coerce their operands to integer by + truncation. + + [ [505]Top ] [ [506]Contents ] [ [507]C-Kermit Home ] [ [508]Kermit + Home ] + _________________________________________________________________ + + 9.5. Variables + + As noted elsewhere in this discussion, all backslash items (variables + such as \%a, macro parameters such as \%1, array elements such as + \&a[\%i], built-in variables such as \v(ndate), built-in functions + such as \fjoin(), macro names enclosed in \m(), \s(), or \:(), etc) + are evaluated at "top level" before the S-Expression is sent to the + S-Expression reader. To use a backslash variable as the target of an + assignment (e.g. by SETQ, LET, ++, or --), you must double the + backslash, e.g. (setq \\%r 1234). This is discussed at greater length + in the next section. + + Thus S-Expression reader generally deals only with macro names (not + backslash items) as variables. It is important to understand how the + reader handles macro names. There are fundamentally two kinds of + S-Expressions: those that contain a single element, such as: + + (foo) + + and those that contain more than one element: + + (foo a b c) + + If an S-Expression contains only one element, and it is the name of a + macro, the macro's definition is examined. If the definition is a + number (integer or floating-point, positive or negative), then this + becomes the value of the expression. If the definition starts with ' + (apostrophe), then the quoted word or string is the value of the + expression (explained in [509]Section 9.8). Otherwise, the macro is + assumed to be composed of Kermit commands (possibly including + S-Expressions), which are executed. If the macro has a RETURN value, + or it executes an S-Expression as its last command, the result becomes + the value of the S-Expression; otherwise the result is empty. + + For S-Expressions that contain more than one element, and the first + element is the name of a macro, then this macro is executed with the + arguments that are given, after the arguments are evaluated by the + S-Expression reader. Likewise, If the first element is a built-in + operator, then it is applied to the operands after they are evaluated. + In both cases, each operand is fed to the S-Expression reader + recursively for evaluation. If an operand is a number or a quoted + string, it is used as-is. But if it's a macro name, this degenerates + into the first case, and the previous paragraph applies. + + Examples: + + define foo 123 + (foo) Result: 123 + define foo 'abc + (foo) Result: abc + define foo '(one two three) + (foo) Result: one two three + define foo return \frandom(1000) + (foo) Result: 713 (or other number) + define foo (+ a b) + (foo) Result: The sum of a and b + + A more difficult example: + + define foo abc + (foo) Result: ??? + + The result in the last example depends on the definition of abc: + + * If it has no definition, an error occurs; otherwise: + * If the definition is an S-Expression, the result is the + S-Expression's value; otherwise: + * If the definition consists of Kermit commands, they are executed. + But in this case "(foo)" produces the empty result, because it + doesn't RETURN anything. + + The use of macros as S-Expression operators is described in + [510]Section 9.8. + + [ [511]Top ] [ [512]Contents ] [ [513]C-Kermit Home ] [ [514]Kermit + Home ] + _________________________________________________________________ + + 9.6. Assignments and Scope + + The assignment operators SETQ and LET apply to global and local + variables, respectively. SETQ and LET are standard Lisp operators + adapted to Kermit scoping rules. When the operands are numeric or + arithmetic, SETQ is equivalent to Kermit's EVALUATE command: + + (setq a (+ 1 2)) + evaluate a 1 + 2 + + When the operand is a string, SETQ is equivalent to DEFINE: + + (setq a '(this is a string)) + define a this is a string + + In the first case, both statements create a macro named "a" with a + value of 3. But in neither case is the macro "a" necessarily global. + If either of these commands executes in an environment (i.e. macro + invocation level) where a "local a" command has been given, the "a" + macro is global to that environment, but is not visible outside it. + + LET is equivalent to the Kermit LOCAL command, followed by the + corresponding EVALUATE: + + (let a (+ 1 2)) + + is equivalent to: + + local a + evaluate a 1 + 2 + + Again, "local" in this context applies to the Kermit macro invocation + stack, not to the S-Expression nesting level. To illustrate, recall + our "newarea" macro: + +def newarea { + (let a \%1 b \%2 c \%3) + (let s (/ (+ a b c) 2.0)) + (sqrt (* s (- s a) (- s b) (- s c))) +} + + Because SETQ and LET expressions return a value, they can be placed + within a larger S-Expression. In this case we can replace the first + reference to the "s" variable by its defining expression: + +def newarea { + (let a \%1 b \%2 c \%3) + (sqrt (* (let s (/ (+ a b c) 2.0)) (- s a) (- s b) (- s c))) +} + + This would not work if LET were local to the S-Expression, but it + works nicely in the context of Kermit macros. The previous definition + is equivalent to: + +def newarea { + local a b c s + (setq a \%1 b \%2 c \%3) + (sqrt (* (setq s (/ (+ a b c) 2.0)) (- s a) (- s b) (- s c))) +} + + In both cases, the variables a, b, c, and s are local to the "newarea" + macro, and global within it. + + Multiple assignments can be handled in several ways. Here is the + obvious way to initialize a series of variables to the same value: + + (setq a 0) + (setq b 0) + (setq c 0) + (setq s 0) + + Here is a more compact and efficient way of doing the same thing: + + (setq a 0 b 0 c 0 s 0) + + However, in case the value was more complex, it's better to put only + one copy of it in the S-Expression; in this case we rely on the fact + that SETQ returns the value of its last assignment: + + (setq a (setq b (setq c (setq s (* x (^ y 2)))))) + + Similarly, to set a series of variables to x, x+1, x+2, ... + + (setq c (+ (setq b (+ (setq a (+ (setq s x) 1)) 1)) 1)) + + In the last example, you can see why "last" does not always correspond + to "rightmost" (the leftmost variable "c" is assigned last). + + If you are working with backslash variables like \%a or array elements + like \&a[1], remember two rules: + 1. Don't put spaces inside array brackets. + 2. You must double the backslash when using SETQ, LET, ++, or -- to + assign a value to a backslash variable. + + Examples of assigning to a backslash variable: + + (setq x 1) + (setq \\%a 0) + (setq \\&a[x+1] 1) + (++ \\%x) + (-- \\&a[x+2]) + + Examples of referring to a backslash variable's value: + + (setq a (+ \%a 1)) + (setq b (+ \%a \&a[1])) + (++ a \%x) + (-- b \&a[1]) + + The special notation is required because all backslashed items (\%x + variables, array elements, built-in \v(xxx) variables, and \fxxx() + function invocations) are evaluated in a single pass BEFORE the + S-Expression is executed; any other approach would result in + unacceptable performance. So, for example, in: + + declare \&a[] = 1 2 3 + define \%x 4 + define \%y 0 + (setq \\%y (+ \%x \&a[1])) + + the S-Expression becomes: + + (setq \%y (+ 4 1)) + + before it is sent to the S-Expression evaluator. If the backslash had + not been doubled on the assignment target, the result would have been: + + (setq 0 (+ 4 1)) + + which is illegal because you can't assign a value to a number. + Conversely, if backslashes were doubled on right-hand-side values: + + (setq \\%y (+ \\%x \\&a[1]) + + this too, would give an error (not numeric - "\%x"). + + If you omit the double backslash in the assignment target, the result + depends on whether the variable already has a value: + + (setq \%a (* 3 3)) + + If \%a has a non-numeric single-word value, then this becomes the name + of the variable that is assigned by SETQ. To illustrate: + + define \%a foo + echo \%a + foo + (setq \%a (* 3 3)) + echo \%a + foo + show macro foo + foo = 9 + + If \%a has no value, a numeric value, or a multiword value, an + "invalid assignment" error occurs. + + [ [515]Top ] [ [516]Contents ] [ [517]C-Kermit Home ] [ [518]Kermit + Home ] + _________________________________________________________________ + + 9.7. Conditional Expressions + + The IF operator provides a compact form of decision-making within + S-Expressions. An IF expression can stand wherever a number might + stand, as long is it returns a number. Here's a quick way to obtain + the average value of all the elements in an array that contains only + numbers: + + (/ (+ \fjoin(&a)) (float \fdim(&a))) + + This results in a "Divide by zero" error if the array is empty. If you + want to define the average value of an empty array to be 0 instead of + getting an error, you can use IF to check the array size: + + (if \fdim(&a) (/ (+ \fjoin(&a)) (float \fdim(&a))) 0) + + or equivalently: + + (if (not \fdim(&a)) 0 (/ (+ \fjoin(&a)) (float \fdim(&a)))) + + Of course, IF can fit anywhere else into an S-Expression: + + (setq a (+ b (if (< c 0) 0 c))) + + and the IF expression can be as complex as you like: + + (setq a (+ b (if (and (or (> x 0) (> y 0)) (< c 0) (> d 1) (!= e 0)) 1 0))) + + and the "then" and "else" parts can contain multiple S-Expressions + enclosed within (EVAL ...): + + (if x (eval (...) (...) (...)) (eval (...) (...) (...))) + + AND and OR operators are guaranteed to "short circuit". If any operand + of AND is false, none of the subsequent operands is evaluated; + likewise, if an OR operand is true, no further operands are evaluated. + + Bear in mind that the S-Expression IF is not the same as Kermit IF; + the condition is only allowed to be an S-Expression or a variable or + number, not the whole list of possibilities you see when you type "if + ?" at the C-Kermit> prompt. But keep reading... + + [ [519]Top ] [ [520]Contents ] [ [521]C-Kermit Home ] [ [522]Kermit + Home ] + _________________________________________________________________ + + 9.8. Extensibility + + To extend the capabilities of S-Expressions, you can use Kermit macro + names as operators, with the following limitations: + + * The macro must not have the same name as a built-in operator. + * You must use the full macro name, not an abbreviation. + + And with the following enhancement: + + * If the last statement executed by the macro is an S-Expression, + its value is returned automatically. In other words: + + define bump (++ \%1) + + is equivalent to: + + define bump return \fsexpression(++ \%1) + + Here's an example in which we define a FIBONACCI operator that returns + the nth element, n >= 0, of the Fibonacci series, 0 1 1 2 3 5 8 13 21 + 34 55, . . ., in which the first element is 0, the second is 1, and + each subsequent element is the sum of the two before it. This series + was devised by Leonardo Pisano, Filius Bonacci (Fibonacci for short) + in 1202 to describe how fast rabbits can breed, and also forms the + basis for the Golden Mean, the branching behavior of plants, the + spiral of a nautilus shell, etc. (Thanks to [523]Dat Thuc Nguyen for + December 2003 corrections to this section!) + + We can write a FIBONACCI function as a macro easily with + S-Expressions: + + define FIBONACCI { + (if (== \%1 0) 0 + (if (== \%1 1) 1 (+ (fibonacci (- \%1 2)) (fibonacci (- \%1 1))))) + } + + You can read this as: + + If the argument (\%1) is 0, return a result of 0; if it is 1, + return 1; otherwise: + return the sum of fibonacci(argument - 2) and fibonacci(argument - + 1) + + Note that a RETURN statement is not needed, since S-Expressions + automatically set the return value of their containing macros. + + For comparison, here's how it would be coded without S-Expressions: + + define FIBONACCI { + if == \%1 0 { + return 0 + } else if == \%1 1 { + return 1 + } else { + return \feval(\fexec(fibonacci \feval(\%1-2)) - + + \fexec(fibonacci \feval(\%1-1))) + } + } + + Now we can use the FIBONACCI function (whichever way you write it) + just as if it were a built-in operator: + + (fibonacci 6) + + Or: + + (setq a 10) + (fibonacci a) + + Within S-Expressions only (not outside them), S-Expressions themselves + can be used as macro arguments: + + (setq a 2 b 4) + (setq x (fibonacci (* a b ))) + + The value of the S-Expression (in this case "8"), and not the + S-Expression itself, is sent to the macro. + + Your macro is responsible for argument validation and error handling. + A robust Fibonacci macro would be more like this: + + define FIBONACCI { + if < \v(argc) 2 end 1 ?\%0: Missing argument + if > \v(argc) 2 end 1 ?\%0: Too many arguments + if not integer \%1 end 1 ?\%0: Integers only + if < \%1 1 end 1 ?\%0: Argument out of range + (if (== \%1 0) 0 + (if (== \%1 1) 1 (+ (fibonacci (- \%1 2)) (fibonacci (- \%1 1))))) + } + + Recall that "END nonzero-number [ message ]" causes a macro invocation + to fail. When the macro is the operator in an S-Expression, this makes + the S-Expression fail too. Also note that our Fibonacci macro is just + an illustration, not a practical example. Since it is recursive (calls + itself), it won't work for large arguments because the call stack can + exceed available memory. See [524]Section 9.9.2 for a practical + alternative. + + Kermit macros, when used as S-Expression operators, can do anything at + all except initiate file transfers: they can print messages on the + screen, read and write files, interact with the user, and so on. For + example, here's a macro ASKME that asks you to enter a number, makes + sure that you did, and then returns its value for use in the + S-Expression: + + define ASKME { + local \%n + while true { + ask \%n { Number: } + if not def \%n continue + if not numeric \%n { + echo Not numeric - "\%n" + continue + } + break + } + return \%n + } + (setq a (* 2 (askme))) ; Get number from user, double it, assign result to a. + + Here's a macro you can use to validate that a number is in a given + range: + + define inrange { + if != \v(argc) 4 end 1 ?\%0: Wrong number of arguments + if ( < \%1 \%2 || > \%1 \%3 ) return 0 + return 1 + } + + The first argument is the number to be checked, the second is the + minimum acceptable value, the third is the maximum. You can use this + (for example) in IF conditions: + + define yes echo \%1 IS OK + define no echo \%1 IS NOT OK + + (setq a -1 b 999) + (if (inrange a 0 100) (yes a) (no a)) + (if (inrange b -1000 +1000) (yes b) (no b)) + + This is just an illustration, of course; there's already a built-in + operator to let you do range checking without help from macros: + + (if (<= 0 a 100) (yes a) (no a)) + (if (<= -1000 b +1000) (yes b) (no b)) + + To send string parameters to a macro, some kind of quoting is required + to tell the S-Expression parser to take a given "word" literally + rather than replacing it by its value. For this we use the Lisp QUOTE + operator: + + define length return \flength(\%1) + (length (quote abcdefghijklmnopqrstuvwxyz)) + 26 + + This causes the string "abcdefghijklmnopqrstuvwxyz" to be sent + literally to the LENGTH macro. Kermit, like Lisp, also offers a + shortcut for QUOTE, that lets us quote a word by prefixing it with a + single quote (') character, also called apostophe (ASCII 39): + + (length 'abcdefghijklmnopqrstuvwxyz) + 26 + + The two forms are equivalent. + + How the macro treats its arguments is up to the macro. In the example + above, the argument is treated as a literal string. However, it can + also be treated as a variable name: + + define string This is a string + define length return \flength(\m(\%1)) + (length 'string) + 16 + + Note the construct \m(\%1). This means "the value of the macro whose + name is the value of + \%1". The value of \%1 in this case is the word "string", and the + value of the macro whose name is "string" is "This is a string". + + What if the macro takes multiple arguments, or a variable number of + them? Here's a simple macro that prints a phrase that includes its + arguments: + + define complain echo It's too \%*! + + (Recall that \%* means "all arguments".) + + It can be called in the traditional way: + + complain hot Result: "It's too hot!" + complain cold and wet Result: "It's too cold and wet!" + + Or from an S-Expression if you quote the arguments: + + (complain 'hot) Result: "It's too hot!" + (complain 'cold 'and 'wet) Result: "It's too cold and wet!" + + To group multiple words into a single argument, use parentheses: + + (complain (quote (cold and wet))) Result: "It's too cold and wet!" + (complain '(cold and wet)) Result: "It's too cold and wet!" + + Note the difference: + + (complain 'cold 'and 'wet) Three arguments + (complain '(cold and wet)) One argument + + Since the COMPLAIN macro uses \%* to refer to all its arguments, no + matter how many, it doesn't care which form you use. But it makes a + difference in cases where the macro refers to its arguments + individually. + + To illustrate, let's consider a macro that receives the name of a + macro and its argument list and executes it with its arguments, + without knowing how many arguments there are. The following LOOP macro + is used to execute the given macro with the given argument list the + requested number of times: + + def loop { local i, for i 1 \%1 1 do \%2 \%3 } + + Within the LOOP macro, the first argument (\%1) is the loop count, \%2 + is the macro name, and \%3 is the argument list. When the LOOP macro + is invoked traditionally like this: + + loop 3 complain hot + + it prints "It's too hot!" three times. To invoke it from an + S-Expression, you must quote both the macro name as well as the + argument, since in this case the macro name itself is an argument: + + (loop 3 'complain 'hot) + + Now what if you need to send different or variable numbers of + arguments to the LOOP macro? The LOOP macro can handle it already, + provided you group the arguments into LOOP's third argument (\%3). In + Kermit syntax, without grouping: + + loop 3 complain cold and wet + + prints "It's too cold!" three times ("and wet" is lost); but with + grouping (either of the following two forms): + + loop 3 complain {cold and wet} + loop 3 complain "cold and wet" + + the LOOP macro prints "It's too cold and wet!" three times as desired. + + To do the same thing in an S-Expression, just use the Lisp forms of + quoting instead of the Kermit forms; the following two are equivalent: + + (loop 3 'complain (quote (cold and wet))) + (loop 3 'complain '(cold and wet)) + + Here's a similar example in which we write a macro that shows both the + name and the value of one or more other macros, whose names are given + as arguments (similar to "show macro"): + + define display { + local \%i + for \%i 1 \v(argc)-1 1 { + echo \&_[\%i] = \m(\&_[\%i]) + } + } + + (Recall that \&_[] is the macro's argument vector array, equivalent to + \%1, \%2, ...) The DISPLAY macro can be used in S-Expressions like + this: + + (setq a 1 b 2 c 3) + (display 'a 'b 'c 'd) + + which prints: + + a = 1 + b = 2 + c = 3 + d = + + The names must be quoted to prevent their evaluation before they are + sent to the macro. This ability to pass variables "by name" to macros, + rather than by value, lets you write macros that change the values of + argument variables. For example, here's a macro that doubles the value + of its argument variable: + + define double (++ \%1 \%1) + + which you can call like this: + + (setq a 12) + (double 'a) + + In the macro, \%1 is replace by the variable name "a"; "(++ a a)" adds + "a" to itself, and sets the value of "a" to the result. + + There are no built-in operators other than QUOTE, ', and STRING for + handling strings in S-Expressions, but using just these, plus macros + that use Kermit's regular string-handling features, you can easily + extend S-Expressions to do string manipulation: + + define len return \flen(\%1) Returns length of argument string + define cap return \fupper(\%1) Uppercase argument string + define rev return \freverse(\%1) Reverses argument string + define sub return \fsubstr(\%1,\%2,\%3) Returns substring of arg string + + (len '(this is a string)) Result: 16 + (rev '(this is a string)) Result: gnirts a si siht + (rev (cap '(this is a string))) Result: GNIRTS A SI SIHT + (sub (rev (cap '(this is a string))) 5 9) Result: TS A SI S + + You can assign a string to a macro name as follows: + + (setq foo '(this is a string)) + (setq foo (quote (this is a string))) + + The two are exactly equivalent. In both cases, the macro "foo" has the + value: + + '(this is a string) + + so when it is retrieved it can be identified as a string rather than a + number or commands to be executed. Thus: + + (setq foo (quote (this is a string))) + show macro foo + foo = '(this is a string) + (foo) + this is a string + + Note the different results for "show macro foo" and "(foo)". The + former shows the internal definition; the latter evaluates the + variable, which removes the quoting. And perhaps more important, note + that if the apostrophe and surrounding parentheses were not stored as + part of the definition, (foo) would try to execute "this is a string" + as a command. + + Given the assignment above, the following work as expected: + + (len foo) Result: 16 + (rev foo) Result: gnirts a si siht + (rev (cap foo)) Result: GNIRTS A SI SIHT + (sub (rev (cap foo)) 5 8) Result: TS A SI S + + Note that, unlike built-in S-Expression operators that return numbers + or truth values, these operators return strings. If you want to assign + their return values to other variables, you can do so: + + (setq bar (rev (cap foo))) Result: GNIRTS A SI SIHT + + But now the S-Expression processor doesn't know the value of "bar" is + supposed to be a string, rather than a macro to execute. For this you + need one final special operator, STRING. The STRING operator takes an + S-Expression as an operand, evaluates it, and then returns its value + enclosed in '(), so you can use the value as a string is subsequent + S-Expressions. Use STRING for referencing macros that return strings: + + (setq bar (string (rev (cap foo)))) Result: '(GNIRTS A SI SIHT) + + STRING is like QUOTE, except that it evaluates its operand before + applying the quoting, rather than taking the operand literally. + + To reference backslash variables or functions that return string + values, you must use the regular quoting mechanisms: + + (setq time '(\v(time))) + (setq date '(\v(date))) + assign \%r this is a string + (setq s1 '(\%r)) + + That's because backslash items are evaluated BEFORE the S-Expression + parser ever sees them, and the values of \v(time) and so on are not + valid S-Expressions, so STRING won't like them. + + Finally a brief word on the touchy topic of quoting. Suppose you want + to include (say) literal parentheses in a string that will later be + processed by the S-Expression reader (or \fsplit() or \fword()). + Normally, you can't do this because parentheses are meaningful in + these contexts. To defeat the normal parsing rules, you can quote the + parentheses with backslash. However, due to the many levels of string + processing involved, a surprisingly large amount of backslashes might + be required, for example: + + (setq s '(a b (c d) \\\\\\\\\\\\\\\\(e f (g h) x\\\\\\\\\\\\\\\\) j k)) + + This is nearly impossible to explain(*). Instead, just remember two + points: + + * In situations like this, it's better to use DEFINE to create the + string, rather than SETQ. The example above requires only double + backslashes when DEFINE is used: + define s '(a b (c d) \\(e f (g h) x\\) j k) + * The level of quoting depends on how many levels of evaluation the + string must pass through, which is not always obvious. However, + the number of backslashes required in any given situation is + always a power of 2. So if 1 doesn't work, try 2; if 2 doesn't + work, try 4; if 4 doesn't work, try 8, 16, 32, and so on. + + Considerations like this apply in any scripting language (shell, Tcl, + Perl, Python, etc). The situation is known as "Quoting Hell". + + (*) If you really want an explanation, here it is: + + * Every SEXP has its backslash items evaluated in a single pass at + top level before being passed to the SEXP reader, so \%1, + \v(ftime), etc, can be evaluated up front, freeing the SEXP reader + of having to know about such things, which in turn makes it much + more efficient. Therefore one level of quoting is lost right away, + and therefore you must double each backslash that is to be used as + a quote. + * When the SEXP reader sees '\', it treats it as a quote; discards + it and keeps the next character. Thus '\\' becomes '\'. This would + be the end of it, except that: + * The SEXP reader must call itself recursively on its operands, so + we must double any quotes in the operands: 2^2 = 4. + * If the result is to be passed as an argument to a macro, the + backslashes must again be doubled, because the macro processor + evaluates the arguments before sending them to the macro: 2^3 = 8. + * If the macro itself is to see the quotes, rather than just the + result of the quoting, the quotes must be doubled again: 2^4 = 16. + + Moral: To create string constants in which grouping characters must be + quoted, use DEFINE rather than SETQ. + + [ [525]Top ] [ [526]Contents ] [ [527]C-Kermit Home ] [ [528]Kermit + Home ] + _________________________________________________________________ + + 9.9. Examples + + 9.9.1. Statistics + + The following program computes statistics -- means, maxima, mimima, + variance, standard deviation, and correlation -- from data stored in + parallel arrays, \&x[] and \&y[], which can contain any mixture of + integer and floating-point numbers: positive, negative, or zero. Array + setup and validation are not shown. Except for the traditional FOR + loop and printing the results at the end, the entire computation is + done with S-Expressions: + +; Initialize sums, maxima, minima, and number of elements + + (setq xsum 0 ysum 0 xsum2 0 ysum2 0 xysum 0) + (setq xmin (setq xmax \&x[1]) ymin (setq ymax \&y[1])) + (setq n \fdim(&x)) + +; Loop through elements and accumulate sums, maxima, and minima + + for i 1 n 1 { + (setq x \&x[i] y \&y[i]) ; Notational convenience + (setq xmax (max xmax x) ymax (max ymax y)) ; X and Y maxima + (setq xmin (min xmin x) ymin (min ymin y)) ; X and Y minima + (++ xsum x ysum y) ; X and Y sums + (++ xsum2 (^ x 2) ysum2 (^ y 2)) ; Sum of X and Y squares + (++ xysum (* x y)) ; Sum of XY products + } + +; Calculate results + + (setq xmean (/ xsum n) ymean (/ ysum n)) ; Mean X and Y + (setq xss (- xsum2 (/ (^ xsum 2) n))) ; Intermediate values + (setq yss (- ysum2 (/ (^ ysum 2) n))) + (setq xyss (- xysum (/ (* xsum ysum) n))) + (setq xvar (/ xss n) yvar (/ yss n)) ; X and Y variance + (setq sdx (sqrt xvar) sdy (sqrt yvar)) ; Std deviation in X and Y + (setq tmp (* xss yss)) + (setq cc (if tmp (/ xyss (sqrt tmp)) 1.0)) ; Correlation coefficient + show macro xmean ymean xvar yvar sdx sdy cc ; Print the results + + The final "if tmp" check accounts for the possibility that both arrays + contain all 0's. Results can also be printed with "echo CC = \m(cc)", + or any other desired way. Interestingly, if we had not needed the sum + of the squares and products, we could have obtained the sums, maxima, + and minima of the X's and Y's without a loop like this: + + (setq xsum (+ \fjoin(&x)) ysum (+ \fjoin(&y))) + (setq xmax (max \fjoin(&x)) ymax (max \fjoin(&y))) + (setq xmin (min \fjoin(&x)) ymin (min \fjoin(&y))) + + Any Kermit function that returns numbers or lists of numbers can be + included in an S-Expression as an operand. + _________________________________________________________________ + + 9.9.2. Practical Fibonacci Series + + The recursive Fibonacci example given previously is simple and + elegant, but not very useful since it causes memory occupation to grow + each time it calls itself, until eventually both physical memory and + disk swap space are filled and the program crashes. Even for small + arguments, like 17, execution time can be prohibitive: + + (setq t1 \v(ftime)) + (setq result (fibonacci 17)) + (setq t2 (- \v(ftime) t1)) + echo FIBONACCI(17) = \m(result): TIME = \ffpround(t2,3) + + prints (on a certain rather slow computer): + + FIBONACCI(17) = 1597: TIME = 5.861 + + Any recursive function can be recoded iteratively. The result is not + as pretty, but execution is far less expensive: + + define FIBITER { + (if (== \%3 0) (\%2) (fibiter (+ \%1 \%2) \%1 (- \%3 1))) + } + define FIBONACCI { + (fibiter 1 0 \%1) + } + + Here's the result on the same computer for the same argument of 17: + + FIBONACCI(17) = 1597: TIME = 0.015 + + (47 times faster.) Execution time increases proportionally to the size + of the argument in the iterative case, whereas in the recursive case + it goes up geometrically, quickly reaching infinity. + + [ [529]Top ] [ [530]Contents ] [ [531]C-Kermit Home ] [ [532]Kermit + Home ] + _________________________________________________________________ + + 9.10. Differences from Algebraic Notation + + In C-Kermit: + + * Algebraic notation uses infix operators and normal rules of + operator precedence, with parentheses used to force exceptions to + the rules; many operations can be included in an expression. + S-Expressions use prefix operators with no intrinsic precedence; + each operation is enclosed in parentheses, and the arrangement of + parentheses determines precedence. + * Algebraic infix operators require two operands; S-Expression + prefix operators can accept a variable number of operands. + * You can use algebraic notation anywhere that C-Kermit accepts a + number, e.g. "echo \&a[((1+1)*2-1]", but you can use S-Expressions + only as top-level commands. You can, however, use either algebraic + or S-Expressions anywhere at all by enclosing them in \fevaluate() + or \fsexpression(), respectively. + * You can use any mixture of integer and floating-point numbers in + S-Expressions, but only integers are permitted in algebraic + expressions. Outside of S-Expressions, floating point arithmetic + is supported only by \ffp...() function calls. + * Operators and operands in S-Expressions must be separated by + spaces, e.g. "(+ a b)". Spaces are not required in algebraic + expressions: "((a+b)*c)". + * When assigning values to backslash variables (such as \%x or + \&a[2]) using SETQ or LET, you must double the backslash. + + [ [533]Top ] [ [534]Contents ] [ [535]C-Kermit Home ] [ [536]Kermit + Home ] + _________________________________________________________________ + + 9.11. Differences from Lisp + + * Kermit has a lot of built-in operators not found in Lisp: ++, ^, + etc. + * Most dialects of real Lisp do not allow S-Expressions that don't + start with an operator, for example: + (a) + This expression can cause an error in Lisp (even if "a" has a + value), but is acceptable in Kermit, where it returns the value of + the variable "a". Similarly, (1) returns the value "1". + * In real Lisp, EVAL requires exactly one operand. In Kermit, it can + have 0, 1, 2, or more operands. It returns the value of the last + operand evaluated. + * Real Lisp SETQ and LET usually require an even number of operands. + Kermit allows an odd number, in which case the last (or only) + variable is undefined (i.e. deleted, destroyed). + * Kermit does not support ratios such as "7/8". Some Lisp dialects + accept ratios as numbers, and generate ratios when told to divide + two integers whose quotient is not a whole number; e.g. in Common + Lisp: + [13] USER(37): (/ (+ 1 2 3 4) 3) + 10/3 + [13] USER(38): + * The result of (/ 10 3) is 3.333.... Some Lisp dialects truncate + the result to 3 since both operands are integers, some don't; some + give the result as a ratio. C-Kermit always gives a floating point + result when there is a fractional part. If you want an integer + result, you can use TRUNCATE, FLOOR, or CEILING, e.g. (truncate (/ + 10 3)). + * There is currently no "bignum" support. Large numbers can be used + and large results generated, but (as noted in [537]Section 9.2) + they are accurate only to the precision of the underlying machine. + \v(math_precision) gives the machine precision as a number of + decimal digits, e.g. 16. + * Scientific notation for floating-point numbers is not supported. + If the magnitude of a number is greater than the precision of the + underlying hardware, the less-significant digits are shown but + their values are meaningless. If it the number is too small to be + represented internally, it is shown as "0.0". + * Many Lisp features are omitted: List processing (CAR, CDR, etc), + DEFUN, Lisp-specific control structures, and so on. + + [ [538]Top ] [ [539]Contents ] [ [540]C-Kermit Home ] [ [541]Kermit + Home ] + __________________________________________________________________________ + +10. FILE TRANSFER + + New commands and switches: + + SET TRANSFER REPORT { OFF, ON } + Enables or disables the (new) one-line message printed by + Kermit after a remote-mode file transfer to indicate the source + and destination file, complete with path, to let you know where + the file went. + + SEND /TYPE:{TEXT,BINARY} + Sends only files of the given type (see [542]Section 4). + + SEND /NOFOLLOWLINKS: + (UNIX only) Skip over symbolic links rather than following them + (default). This applies to wildcard and/or recursive SENDs; if + a single filename is given, and it happens to be a symbolic + link, the file it points to is sent. + + SEND /FOLLOWLINKS: + (UNIX only) Follow (resolve) symbolic links. Watch out for + circular links, endless loops, etc. + + SET SEND I-PACKETS { OFF, ON } + When sending commands to a Kermit server, this tells whether + command packets should be preceded by an I (information) + packet, which is used to synchronize parameters prior to + executing the command. Normally ON. The only reason to set this + OFF is for communicating with buggy Kermit servers that + misbehave when an I packet is sent to them. There is also a SET + RECEIVE I-PACKETS command, but presently it has no effect. + + SET TRANSFER MESSAGE [ text ] + Sets an initial message to be shown in the Last Message field + of the fullscreen file-transfer display. + + SET TRANSFER TRANSLATION { ON, OFF } + Inhibits or re-enables text-file transfer character-set + translation globally. + + { SEND, MSEND, GET, RECEIVE } /TRANSPARENT + Inhibits character-set translation for this transfer only. + + { GET, RECEIVE } /PIPES:{ON,OFF} + Overrides global TRANSFER PIPES setting for this transfer only; + ON allows incoming files with names like "!tar xf -" to be + opened as pipelines rather than regular files. + + The following new "hot keys" are available when Kermit's file-transfer + display is visible: + + D: Turn on debugging, open "debug.log" if not already open. + d: Turn off debugging but leave log open (if it was open). + T: Turn on debug-log timestamps. + t: Turn off debug-log timestamps. + + Other improvements: + * SET FILE DOWNLOAD-DIRECTORY now works for external protocols (e.g. + sz/rz) too. + * Improved automatic per-file text/binary switching, described in + [543]Section 4. + * When sending a file group (e.g. "send *.*"), failure to open a + file is no longer fatal; now C-Kermit simply goes ahead to the + next file. + * Transaction log entries are now made for external protocols too. + + [ [544]Top ] [ [545]Contents ] [ [546]C-Kermit Home ] [ [547]Kermit + Home ] + __________________________________________________________________________ + +11. MODEMS AND DIALING + + In C-Kermit 8.0, the default modem type for dialing has changed from + NONE (= DIRECT, meaning no modem) to GENERIC. This change should have + no impact on direct connections. For dialing, it means that, unless + you SET MODEM TYPE to a specific type, such as USROBOTICS or CONEXANT, + Kermit assumes: + + 1. The modem uses the Hayes AT command set. + 2. The modem supports error correction, data compression, and + hardware flow control and is already configured to use them. + + In fact, Kermit assumes the modem is completely configured, and + therefore does not send it an initialization string or any + configuration commands. Instead, it sends only the simplest and most + portable commands: + + ATQ0V1 Give dial result codes. + ATDTnumber Dial the number. + + (or ATD or ATDP, as appropriate). + + The new defaults work for direct connections and for most modern + modems on most platforms, and they work much faster than + "full-treatment" dialing. If the new defaults don't work for you, or + if you need to perform explicit modem configuations or interactions, + then set a specific modem type and use the SET MODEM and SET DIAL + commands as documented in Using C-Kermit. + + WARNING: Don't use the generic modem on hosts that do not support + RTS/CTS flow control. If Xon/Xoff is in use on the serial port, + you'll need to select a particular modem type so Kermit knows what + command to give it to enable Xon/Xoff flow control between itself + and your serial port. + + The following new modem types were added in C-Kermit 8.0: + + lucent: Lucent Venus chipset + pctel: PCTel V.90 chipset + conexant: Conexant (ex-Rockwell) modem family + zoom-v32bis: New name for "Zoom" + zoom-v34 Zoom V.34 + zoom-v90 Zoom V.90 56K + zoom-v92: Zoom V.92 with V.44 data compression + zoltrix-v34: New name for "zoltrix" + zoltrix-hsp-v90: Synonym for PCTel + zoltrix-hcf-v90: Synonym for ITU-T-V250 + smartlink-v90: Synonym for usrobotics (same chipset) + acer-v90: Synonym for Rockwell-v90 + + New DIAL-related variables: + + \v(dm_hf): Dial modifier: Wait for Hook-Flash. + \v(dm_wb): Dial modifier: Wait for Bong. + + Finally, if dialing fails, Kermit now prints a context-sensitive hint + suggesting possible reasons and remedies. + + Added in C-Kermit 8.0.201: Rudimentary support for Caller ID, for + use with the ANSWER command. If the modem reports Caller ID + information, Kermit stores it in variables that you can access after + the call is answered: + + \v(callid_date) The date of the call + \v(callid_time) The time of the call + \v(callid_name) The name of the caller + \v(callid_nmbr) The telephone number of the caller + \v(callid_mesg) A message + + The format of these items depends on the originating and answering + phone companies and the modems and their configuration. + + Not very many modems support Caller ID, and those that do (a) tend to + have it disabled by default, and (b) use different commands to enable + it. A quick survey shows of some current models shows: + + - USR V.90: No + - ITU-T V.250: No + - Lucent Venus: No + - Diamond Supra: #CID=1 + - Rockwell 56K: #CID=1 + - PCTEL: #CID=1 + - Zoltrix: +VCID=1 + - Conexant: +VCID=1 + + To use Kermit's Caller ID feature, you have to set the modem to wait + for at least two rings before answering, and you have to give the + command to enable Caller ID; for example (after choosing a modem with + SET MODEM TYPE): + + set modem command autoanswer on ATS0=2#CID=1\{13} + set modem command autoanswer on ATS0=2+VCID=1\{13} + + These commands can be undone with: + + set modem command autoanswer on ATS0=1#CID=0\{13} + set modem command autoanswer on ATS0=1+VCID=0\{13} + + Kermit presently has no built-in knowledge of the Caller ID + capabilities or commands of the modems in its database. + + Since the variables can be accessed only after the call is answered, + the only way to refuse a call is to answer it, inspect the variables, + and then hang it up if desired. + + [ [548]Top ] [ [549]Contents ] [ [550]C-Kermit Home ] [ [551]Kermit + Home ] + __________________________________________________________________________ + +12. TERMINAL CONNECTION + + Now that 7-bit connections are no longer the norm, the default + terminal bytesize (also called "data size" or "word size") in C-Kermit + 8.0 is 8 bits, rather than 7 bits as it was in C-Kermit 7.0 and + earlier: + + SET ESCAPE character + This command, which specifies your CONNECT-mode escape + character, allows you to specify any ASCII control character in + a variety of formats. C-Kermit 8.0.201 now also lets you + specify any 8-bit value, 128-255, as the escape character. In + the SET ESCAPE command, you can type the 8-bit character + literally or you can enter its numeric code. Here are examples + that you can enter from a terminal or console that uses the ISO + Latin-1 character set: + + C-Kermit> set escape à + C-Kermit> set escape 195 + C-Kermit> show escape + Escape character: Code 195 (Ã): enabled + C-Kermit> + + Both of these commands set the escape character value to 195 + (decimal), which happens to be uppercase letter A with Tilde in + Latin-1. SHOW ESCAPE and SHOW TERMINAL show the value, as does + the CONNECT message. + + SET TERMINAL AUTODOWNLOAD ERROR { STOP, CONTINUE } + When Kermit has a terminal connection to another computer, and + a file transfer is initiated automatically because a Kermit + packet was received in CONNECT mode (i.e. in the terminal + screen), this command tells what Kermit should do if the + transfer fails. The default is to STOP, which leaves Kermit in + command mode with its file-transfer display showing, so you can + see that the transfer failed and why. If you SET TERMINAL + AUTODOWNLOAD ERROR CONTINUE, this causes Kermit to return + automatically to its terminal screen (i.e. resume its CONNECT + session) as if the transfer had succeeded; this can be + desirable if the entire session is under control of a + host-based script. + + SET TERMINAL BYTESIZE { 7, 8 } + The byte size to use during CONNECT and INPUT command + execution, which can be more restrictive than the bytesize + implied by the current PARITY setting, but not less + restrictive. In C-Kermit 7.0 and earlier, the terminal bytesize + was 7 by default to protect against the likelihood that parity + was in use on the connection without the user's knowledge. When + the terminal bytesize is 8 (as it is in C-Kermit 8.0 and + later), the user will see garbage in this (increasingly + unlikely) situation. Note that 8 data bits are required for + most character sets other than ASCII: Latin-1, UTF-8, and so + on. + + A new command has been added to produce timestamped session logs: + + SET TERMINAL SESSION-LOG TIMESTAMPED-TEXT + Records the terminal session in text mode (like SET TERMINAL + SESSION-LOG TEXT) but adds a timestamp at the beginning of each + line. The timestamp format is hh:mm:ss.nnn, and indicates the + time at which the first character of the line appeared. + + In most UNIX versions (those built with the select()-capable CONNECT + module -- pretty much all the ones that have or could have TELNET + included), an idle timeout feature has been added: + + SET TERMINAL IDLE-TIMEOUT number + If the number is not 0, then Kermit is to take an action when + the given amount of time passes with no activity during CONNECT + mode. If the number is positive it is the maximum number of + idle seconds; if number is negative it represents milliseconds + (thousandths of seconds). If 0 is given as the number, there + are no idle timeouts. Synonym: SET TERMINAL IDLE-LIMIT. + + SET TERMINAL IDLE-ACTION { RETURN, HANGUP, EXIT, OUTPUT [ string ] } + The action to be taken upon an idle timeout in CONNECT mode. + RETURN to the prompt, HANGUP the connection, EXIT from Kermit, + or OUTPUT the given string (if no string is given, a NUL (ASCII + 0) character is sent). + + SET TERMINAL IDLE-ACTION { TELNET-NOP, TELNET-AYT } + Actions that can be selected on Telnet connections only, that + might be useful if idle limits are enforced by the Telnet + server or in the TCP/IP protocol: TELNET-NOP sends a "NO + Operation" (do-nothing) command, which causes no response from + the server; TELNET-AYT sends an "Are You There" message to the + server, which should make the server send back a message. + Neither of these actions interferes with your remote session. + + SET TERMINAL IDLE-ACTION is useful for connections to hosts or + services that automatically log you out after a certain amount of idle + time, e.g.: + + set term idle-timeout 300 + set term idle-action output \32 + + sends a space (as if you had pressed the space bar) every 300 seconds + (five minutes) while there is no activity (32 is the ASCII code for + space). + + When C-Kermit returns from CONNECT to command mode, the reason for the + transition is given in a new variable, \v(cx_status): + + 0 No CONNECT command given yet. + 1 User escaped back manually. + 2 A trigger string was encountered. + 3 IKSD entered server mode. + 4 Application Program Command received from host. + 5 Idle timeout. + 6 Telnet protocol error. + 7 Keystroke macro. + 8 Time limit exceeded. + 100 Internal error. + 101 Carrier required by not detected. + 102 I/O error on connection. + 103 Disconnected by host. + 104 Disconnected by user. + 105 Session limit exceeded. + 106 Rejected due to Telnet policy. + 107 Received kill signal. + + Values 100 and above indicate there is no connection. + + [ [552]Top ] [ [553]Contents ] [ [554]C-Kermit Home ] [ [555]Kermit + Home ] + __________________________________________________________________________ + +13. CHARACTER SETS + + See the section on [556]file scanning above, and the section on + character-set conversion in [557]FTP. Also: + + * True support for CP1252 (rather than treating it as Latin-1). + * Proper handling of C1 values when converting ISO 8-bit text to + UTF-8. + * TYPE /CHARACTER-SET: /TRANSLATE-TO: allows specific translations. + * The TRANSLATE command now works on multiple files. + * K_CHARSET environment variable to set the file character-set. + * SET TRANSFER TRANSLATION OFF. + * FTP client character-set translation ([558]Section 3.7). + + [ [559]Top ] [ [560]Contents ] [ [561]C-Kermit Home ] [ [562]Kermit + Home ] + __________________________________________________________________________ + +14. DIALOUT FROM TELNET TERMINAL SERVERS + + For years, C-Kermit has supported dialing out from Telnet modem + servers (also called reverse terminal servers or access servers), but + until now there was no way for Kermit to control the communication + parameters (speed, parity, etc) on the serial port of the terminal + server; it had to use whatever was there. + + But now, if you make a connection to a server that supports the Telnet + Com Port Control Option, [563]RFC 2217, you have the same degree of + control as you would have over a serial port on the computer where + Kermit is running: SET SPEED, SET FLOW, SET PARITY, SET STOP-BITS, + SHOW COMM, WAIT, SET CARRIER-WATCH, the modem-signal variables, + sending Break, and so on, apply to the connection between the terminal + server and the modem. + + For example, using a Cisco Access Server 2509, where specifying a TCP + port in the 6000's selects a serial port that can be used for dialing + out: + + set host xxx 6001 ; xxx is the IP hostname or address of the server + (log in if necessary) ; With a script or by hand + set modem type usr ; Tell Kermit what kind of modem it has + set speed 57600 ; This affects the server's port + set flow rts/cts ; Ditto + dial 7654321 + + The modem server might or might not require a login sequence. It might + also allow for automatic authentication, e.g. via Kerberos tickets. + NOTE: If the modem server requires a login sequence, then REDIAL might + not work as expected. + + When you have a Telnet Com Port connection, your SET SPEED and SET + FLOW options change automatically to reflect the capabilities of the + server, rather than those of your local computer. + + See the configuration manual for your server for additional + information. For example, how to set up the server to drop the Telnet + connection automatically when the telephone call is hung up (e.g. + "autohangup" on Cisco models). + + For a Linux-based Telnet Com-Port server, click the Srdird link: + + [ [564]Top ] [ [565]Contents ] [ [566]Sredird ] [ [567]C-Kermit Home ] + [ [568]Kermit Home ] + __________________________________________________________________________ + +15. COPING WITH BROKEN KERMIT PARTNERS + + There are lots of faulty Kermit protocol implementations out there, + found mainly in 3rd-party products ranging from communications + software packages to file-transfer functions imbedded within devices. + This topic is covered [569]HERE for C-Kermit 7.0, but C-Kermit 8.0 + adds some additional tricks. + + SET ATTRIBUTE RECORD-FORMAT { ON, OFF } + Allows control of the Kermit's Record-Format attribute. Set + this to OFF in case incoming file are refused due to unknown or + invalid record formats if you want to accept the file anyway. + + SET SEND I-PACKETS { ON, OFF } + A Kermit server is supposed to accept I-packets; this is how + the client lets the server know its capabilities and + preferences before sending a command. Apparently there is at + least one Kermit server implementation that does not accept + I-packets, and does not properly respond with an Error packet + if it gets one. To get around such situations in C-Kermit 8.0, + you can use SET SEND I-PACKETS OFF to inhibit the sending of I + packets. In this case, the client must be able to adjust to the + server's configuration, rather than the other way around as we + are used to. + + SET PROTOCOL KERMIT {} {} {} + C-Kermit 6.0 and later automatically send "autoupload" and + "autodownload" commands when in local mode and you give a file + transfer command. For example, if you tell kermit to "send + oofa.txt", Kermit sends "kermit -r" and a carriage return, in + case you had forgotten to start Kermit on the far end and told + it to receive a file. If a Kermit program had already been + started on the far end, it should harmlessly absorb this + string. However, some Kermit programs violate the Kermit + protocol definition and treat such strings as Kermit packets + even though they are not. In such cases, give this command to + set the Kermit protocol autoupload and download strings to + nothing, which tells Kermit not to send them. (This is not a + new feature, but it was not previously included in the "Coping" + section of the documentation.) + + [ [570]Top ] [ [571]Contents ] [ [572]C-Kermit Home ] [ [573]Kermit + Home ] + __________________________________________________________________________ + +16. NEW COMMAND-LINE OPTIONS + + kermit -h Now prints a complete listing of its command-line options, + rather than an abbreviated list squeezed into a 24x80 space. + + -dd Debug, like -d but adds timestamps + --version Shows C-Kermit version number. + --noperms Equivalent to SET ATTRIBUTE PROTECTION OFF. + + Kermit now accepts a selection of URLs (Universal Resource Locators) + as its first command-line argument. These are: + + telnet:hostname + Makes a Telnet connection to the given host (IP hostname or + address). + + ftp://[user[:password]@]hostname[/path...] + Makes an FTP connection to the given host (IP hostname or + address). If a username is given, Kermit tries to log you in; + if a password is given, it is used; if not, you are prompted + for one. If no username is given, an anonymous login is + performed. If a pathname is included, Kermit tries to GET the + given file. See [574]Section 3.1.3 for details. + + ftps://[user[:password]@]hostname[/path...] + Makes a secure FTP connection over SSL. + + telnets://[user[:password]@]hostname + Makes a secure Telnet connection over SSL. + + kermit://[user[:password]@]hostname[/path...] + Makes a connection to an [575]Internet Kermit Server. + + http://[user[:password]@]hostname[/path...] + Makes a connection to Web server. + + https://[user[:password]@]hostname[/path...] + Makes a connection to secure Web server. + + [ [576]Top ] [ [577]Contents ] [ [578]C-Kermit Home ] [ [579]Kermit + Home ] + __________________________________________________________________________ + +17. LOGS + + In C-Kermit 8.0, we make an effort to keep passwords out of the debug + log. This can never be 100% effective, but it's better than before, + when there were no precautions at all. Whenever Kermit knows it's + prompting for, parsing, or transmitting a password, it temporarily + turns off logging and then turns it back on afterwards. This keeps the + debug log password-free in most common cases, but there can be no + guarantees. + + As noted elsewhere, the new "-dd" command-line option selects a + timestamped debug log (equivalent to "set debug timestamps on", "log + debug debug.log"). + + C-Kermit 8.0 also supports a new timestamped session log via "set + session-log timestamped-text", "log session". + + There have been requests for other kinds of logs, for example a + command log. These might be added at some point. One person wanted to + be able to log commands with timestamps, but only commands issued at + the prompt, not commands from files or macros, and also wanted a + header line at the beginning showing the date, user, and host. This + can be done as follows: + + .filename := \v(home)commands.log ; (for example) + fopen /write \%c \m(filename) + if success { + fwrite /line \%c \v(date): User=\v(user) Host=\v(host) + fclose \%c + set debug timestamps on + log debug {| grep "CMD(P)" >> \m(filename)} append + } + + [ [580]Top ] [ [581]Contents ] [ [582]C-Kermit Home ] [ [583]Kermit + Home ] + _________________________________________________________________ + + C-Kermit 8.0 Update Notes / [584]The Kermit Project / Columbia + University / 15 Dec 2003 + +References + + 1. http://www.columbia.edu/kermit/ckermit80.html#contents + 2. http://www.columbia.edu/kermit/ckermit.html + 3. http://www.columbia.edu/kermit/index.html + 4. http://www.columbia.edu/kermit/ckermit80.html + 5. mailto:kermit-support@columbia.edu + 6. http://www.columbia.edu/kermit/ + 7. http://www.kermit-project.org/ + 8. http://www.columbia.nyc.ny.us/kermit/ + 9. ftp://kermit.columbia.edu/kermit/f/COPYING.TXT + 10. ftp://kermit.columbia.edu/kermit/f/ckcmai.c + 11. http://www.columbia.edu/kermit/ckermit80.html#xv + 12. http://www.columbia.edu/kermit/ck60manual.html + 13. http://www.columbia.edu/kermit/ckermi70.html + 14. ftp://kermit.columbia.edu/kermit/f/ckermit70.txt + 15. http://www.columbia.edu/kermit/ckututor.html + 16. ftp://kermit.columbia.edu/kermit/f/ckuker.nr + 17. http://www.columbia.edu/kermit/security.htm + 18. http://www.columbia.edu/kermit/telnet.htm + 19. http://www.columbia.edu/kermit/ftpscripts.html + 20. http://www.columbia.edu/kermit/ckcbwr.html + 21. ftp://kermit.columbia.edu/kermit/f/ckcbwr.txt + 22. http://www.columbia.edu/kermit/ckubwr.html + 23. ftp://kermit.columbia.edu/kermit/f/ckubwr.txt + 24. http://www.columbia.edu/kermit/ckvbwr.html + 25. ftp://kermit.columbia.edu/kermit/f/ckvbwr.txt + 26. http://www.columbia.edu/kermit/ckuins.html + 27. ftp://kermit.columbia.edu/kermit/f/ckuins.txt + 28. http://www.columbia.edu/kermit/ckvins.html + 29. ftp://kermit.columbia.edu/kermit/f/ckvins.txt + 30. http://www.columbia.edu/kermit/ckccfg.html + 31. ftp://kermit.columbia.edu/kermit/f/ckccfg.txt + 32. http://www.columbia.edu/kermit/ckcplm.html + 33. ftp://kermit.columbia.edu/kermit/f/ckcplm.txt + 34. http://www.columbia.edu/kermit/iksd.html + 35. http://www.columbia.edu/kermit/skermit.html + 36. http://www.columbia.edu/kermit/ckermit80.html#top + 37. http://www.columbia.edu/kermit/ckermit.html + 38. http://www.columbia.edu/kermit/index.html + 39. http://www.columbia.edu/kermit/ckermit80.html#x0 + 40. http://www.columbia.edu/kermit/ckermit80.html#x1 + 41. http://www.columbia.edu/kermit/ckermit80.html#x2 + 42. http://www.columbia.edu/kermit/ckermit80.html#x2.1 + 43. http://www.columbia.edu/kermit/ckermit80.html#x2.2 + 44. http://www.columbia.edu/kermit/ckermit80.html#x2.2.1 + 45. http://www.columbia.edu/kermit/ckermit80.html#x2.2.2 + 46. http://www.columbia.edu/kermit/ckermit80.html#x2.2.3 + 47. http://www.columbia.edu/kermit/ckermit80.html#x2.2.4 + 48. http://www.columbia.edu/kermit/ckermit80.html#x2.2.5 + 49. http://www.columbia.edu/kermit/ckermit80.html#x2.2.6 + 50. http://www.columbia.edu/kermit/ckermit80.html#x3 + 51. http://www.columbia.edu/kermit/ckermit80.html#x3.1 + 52. http://www.columbia.edu/kermit/ckermit80.html#x3.1.1 + 53. http://www.columbia.edu/kermit/ckermit80.html#x3.1.2 + 54. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3 + 55. http://www.columbia.edu/kermit/ckermit80.html#x3.1.4 + 56. http://www.columbia.edu/kermit/ckermit80.html#x3.2 + 57. http://www.columbia.edu/kermit/ckermit80.html#x3.3 + 58. http://www.columbia.edu/kermit/ckermit80.html#x3.4 + 59. http://www.columbia.edu/kermit/ckermit80.html#x3.5 + 60. http://www.columbia.edu/kermit/ckermit80.html#x3.5.1 + 61. http://www.columbia.edu/kermit/ckermit80.html#x3.5.2 + 62. http://www.columbia.edu/kermit/ckermit80.html#x3.5.3 + 63. http://www.columbia.edu/kermit/ckermit80.html#x3.6 + 64. http://www.columbia.edu/kermit/ckermit80.html#x3.6.1 + 65. http://www.columbia.edu/kermit/ckermit80.html#x3.6.2 + 66. http://www.columbia.edu/kermit/ckermit80.html#x3.6.3 + 67. http://www.columbia.edu/kermit/ckermit80.html#x3.7 + 68. http://www.columbia.edu/kermit/ckermit80.html#x3.7.1 + 69. http://www.columbia.edu/kermit/ckermit80.html#x3.7.2 + 70. http://www.columbia.edu/kermit/ckermit80.html#x3.8 + 71. http://www.columbia.edu/kermit/ckermit80.html#x3.9 + 72. http://www.columbia.edu/kermit/ckermit80.html#x3.10 + 73. http://www.columbia.edu/kermit/ckermit80.html#x3.10.1 + 74. http://www.columbia.edu/kermit/ckermit80.html#x3.10.2 + 75. http://www.columbia.edu/kermit/ckermit80.html#x3.10.3 + 76. http://www.columbia.edu/kermit/ckermit80.html#x3.11 + 77. http://www.columbia.edu/kermit/ckermit80.html#x4 + 78. http://www.columbia.edu/kermit/ckermit80.html#x5 + 79. http://www.columbia.edu/kermit/ckermit80.html#x6 + 80. http://www.columbia.edu/kermit/ckermit80.html#x6.1 + 81. http://www.columbia.edu/kermit/ckermit80.html#x6.2 + 82. http://www.columbia.edu/kermit/ckermit80.html#x6.3 + 83. http://www.columbia.edu/kermit/ckermit80.html#x6.4 + 84. http://www.columbia.edu/kermit/ckermit80.html#x6.5 + 85. http://www.columbia.edu/kermit/ckermit80.html#x6.6 + 86. http://www.columbia.edu/kermit/ckermit80.html#x7 + 87. http://www.columbia.edu/kermit/ckermit80.html#x8 + 88. http://www.columbia.edu/kermit/ckermit80.html#x8.1 + 89. http://www.columbia.edu/kermit/ckermit80.html#x8.2 + 90. http://www.columbia.edu/kermit/ckermit80.html#x8.3 + 91. http://www.columbia.edu/kermit/ckermit80.html#x8.4 + 92. http://www.columbia.edu/kermit/ckermit80.html#x8.5 + 93. http://www.columbia.edu/kermit/ckermit80.html#x8.6 + 94. http://www.columbia.edu/kermit/ckermit80.html#x8.7 + 95. http://www.columbia.edu/kermit/ckermit80.html#x8.8 + 96. http://www.columbia.edu/kermit/ckermit80.html#x8.9 + 97. http://www.columbia.edu/kermit/ckermit80.html#x8.10 + 98. http://www.columbia.edu/kermit/ckermit80.html#x8.11 + 99. http://www.columbia.edu/kermit/ckermit80.html#x8.12 + 100. http://www.columbia.edu/kermit/ckermit80.html#x8.13 + 101. http://www.columbia.edu/kermit/ckermit80.html#x8.14 + 102. http://www.columbia.edu/kermit/ckermit80.html#x9 + 103. http://www.columbia.edu/kermit/ckermit80.html#x9.1 + 104. http://www.columbia.edu/kermit/ckermit80.html#x9.2 + 105. http://www.columbia.edu/kermit/ckermit80.html#x9.3 + 106. http://www.columbia.edu/kermit/ckermit80.html#x9.4 + 107. http://www.columbia.edu/kermit/ckermit80.html#x9.5 + 108. http://www.columbia.edu/kermit/ckermit80.html#x9.6 + 109. http://www.columbia.edu/kermit/ckermit80.html#x9.7 + 110. http://www.columbia.edu/kermit/ckermit80.html#x9.8 + 111. http://www.columbia.edu/kermit/ckermit80.html#x9.9 + 112. http://www.columbia.edu/kermit/ckermit80.html#x9.10 + 113. http://www.columbia.edu/kermit/ckermit80.html#x9.11 + 114. http://www.columbia.edu/kermit/ckermit80.html#x10 + 115. http://www.columbia.edu/kermit/ckermit80.html#x11 + 116. http://www.columbia.edu/kermit/ckermit80.html#x12 + 117. http://www.columbia.edu/kermit/ckermit80.html#x13 + 118. http://www.columbia.edu/kermit/ckermit80.html#x14 + 119. http://www.columbia.edu/kermit/ckermit80.html#x15 + 120. http://www.columbia.edu/kermit/ckermit80.html#x16 + 121. http://www.columbia.edu/kermit/ckermit80.html#x17 + 122. http://www.columbia.edu/kermit/ckermit80.html#top + 123. http://www.columbia.edu/kermit/ckermit.html + 124. http://www.columbia.edu/kermit/index.html + 125. http://www.columbia.edu/kermit/ckuins.html#x5 + 126. http://www.columbia.edu/kermit/ckuins.html + 127. http://www.columbia.edu/kermit/ckermit80.html#x5 + 128. http://www.columbia.edu/kermit/ckermit80.html#x2.2 + 129. http://www.columbia.edu/kermit/ckermit80.html#contents + 130. http://www.columbia.edu/kermit/ckermit80.html#x15 + 131. http://www.columbia.edu/kermit/ckermit80.html#x3.7 + 132. http://www.columbia.edu/kermit/ckermit80.html#ftpdates + 133. http://www.columbia.edu/kermit/ckermit80.html#ftpcheck + 134. http://www.columbia.edu/kermit/ckermit80.html#ftpnamelist + 135. http://www.columbia.edu/kermit/ckermit80.html#srvrename + 136. http://www.columbia.edu/kermit/ckermit80.html#ftpvdir + 137. http://www.columbia.edu/kermit/ckermit80.html#setftptype + 138. http://www.columbia.edu/kermit/ckermit80.html#x3.6 + 139. http://www.columbia.edu/kermit/ckermit80.html#x15 + 140. http://www.columbia.edu/kermit/ckermit80.html#x8.7 + 141. http://www.columbia.edu/kermit/ckermit80.html#x2.1 + 142. http://www.columbia.edu/kermit/ckermit80.html#x2.2 + 143. http://www.columbia.edu/kermit/ckermit80.html#x8.14 + 144. http://www.columbia.edu/kermit/ckermit80.html#x8.13 + 145. http://www.columbia.edu/kermit/ckermit80.html#x8.13 + 146. http://www.columbia.edu/kermit/ckututor.html + 147. http://www.columbia.edu/kermit/ckuins.html + 148. http://www.columbia.edu/kermit/skermit.html + 149. http://www.columbia.edu/kermit/ckermit80.html#setlocus + 150. http://www.columbia.edu/kermit/ckermit80.html#lcommands + 151. http://www.columbia.edu/kermit/ckermit80.html#ftpuser + 152. http://www.columbia.edu/kermit/ckermit80.html#showvar + 153. http://www.columbia.edu/kermit/ckermit80.html#callerid + 154. http://www.columbia.edu/kermit/ckermit80.html#x6.6 + 155. http://www.columbia.edu/kermit/ckermit80.html#x0 + 156. http://www.columbia.edu/kermit/ckermit80.html#x3.11 + 157. http://www.columbia.edu/kermit/ckermit80.html#top + 158. http://www.columbia.edu/kermit/ckermit80.html#contents + 159. http://www.columbia.edu/kermit/ckermit.html + 160. http://www.columbia.edu/kermit/index.html + 161. http://www.columbia.edu/kermit/ckermit80.html#x0 + 162. http://www.columbia.edu/kermit/ckermit80.html#top + 163. http://www.columbia.edu/kermit/ckermit80.html#contents + 164. http://www.columbia.edu/kermit/ckermit.html + 165. http://www.columbia.edu/kermit/index.html + 166. http://www.columbia.edu/kermit/k95.html + 167. http://www.columbia.edu/kermit/sshclient.html + 168. http://www.columbia.edu/kermit/skermit.html + 169. http://www.columbia.edu/kermit/skermit.html + 170. http://www.columbia.edu/kermit/sshclien.htm + 171. http://www.columbia.edu/kermit/ckermit80.html#x3 + 172. ftp://ftp.isi.edu/in-notes/rfc1738.txt + 173. http://www.columbia.edu/kermit/ckermit80.html#x2.2.2 + 174. http://www.columbia.edu/kermit/ckermit80.html#x2.2.1 + 175. ftp://ftp.isi.edu/in-notes/rfc2396.txt + 176. ftp://ftp.isi.edu/in-notes/rfc2616.txt + 177. http://www.columbia.edu/kermit/ckermit80.html#x2.2.3 + 178. ftp://ftp.isi.edu/in-notes/rfc2616.txt + 179. http://www.columbia.edu/kermit/ckermit80.html#x8.13.7 + 180. http://www.columbia.edu/kermit/security.htm#x5.4 + 181. http://www.columbia.edu/kermit/security.htm#x15 + 182. http://www.columbia.edu/kermit/security.htm#x6.2 + 183. http://www.columbia.edu/kermit/security.html + 184. http://www.columbia.edu/kermit/ckermit80.html#x16 + 185. http://www.columbia.edu/kermit/ckermit80.html#top + 186. http://www.columbia.edu/kermit/ckermit80.html#contents + 187. http://www.columbia.edu/kermit/ckermit.html + 188. http://www.columbia.edu/kermit/index.html + 189. http://www.columbia.edu/kermit/ckermit80.html#x3.1 + 190. http://www.columbia.edu/kermit/ckermit80.html#x3.2 + 191. http://www.columbia.edu/kermit/ckermit80.html#x3.3 + 192. http://www.columbia.edu/kermit/ckermit80.html#x3.4 + 193. http://www.columbia.edu/kermit/ckermit80.html#x3.5 + 194. http://www.columbia.edu/kermit/ckermit80.html#x3.6 + 195. http://www.columbia.edu/kermit/ckermit80.html#x3.7 + 196. http://www.columbia.edu/kermit/ckermit80.html#x3.8 + 197. http://www.columbia.edu/kermit/ckermit80.html#x3.9 + 198. http://www.columbia.edu/kermit/ckermit80.html#x3.10 + 199. http://www.columbia.edu/kermit/ckermit80.html#x3.11 + 200. http://www.columbia.edu/kermit/security.htm + 201. http://www.columbia.edu/kermit/security.htm#servers + 202. http://www.columbia.edu/kermit/ckcsets.html + 203. http://www.columbia.edu/kermit/unicode.html + 204. http://www.columbia.edu/kermit/ckermi70.htm#x1.5.4 + 205. http://www.columbia.edu/kermit/case10.html + 206. http://www.columbia.edu/kermit/ckermit80.html#x4 + 207. http://www.columbia.edu/kermit/ckermit80.html#x3.11 + 208. http://www.columbia.edu/kermit/ftpscripts.html + 209. http://www.columbia.edu/kermit/ckermit80.html#top + 210. http://www.columbia.edu/kermit/ckermit80.html#ftp + 211. http://www.columbia.edu/kermit/ftpclient.html + 212. http://www.columbia.edu/kermit/ftpscripts.html + 213. http://www.columbia.edu/kermit/ckermit.html + 214. http://www.columbia.edu/kermit/index.html + 215. http://www.columbia.edu/kermit/ckermit80.html#x3.1.1 + 216. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3 + 217. http://www.columbia.edu/kermit/ckermit80.html#x3.1.4 + 218. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3 + 219. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3 + 220. http://www.columbia.edu/kermit/ckermit80.html#x3.2 + 221. http://www.columbia.edu/kermit/ckermit80.html#x3.5 + 222. http://www.columbia.edu/kermit/ckermit80.html#x3.6 + 223. http://www.columbia.edu/kermit/ftpscripts.html + 224. http://www.columbia.edu/kermit/ckb2.htm + 225. http://www.columbia.edu/kermit/ckermit80.html#ftpautolog + 226. http://www.columbia.edu/kermit/ckermit80.html#ftpuser + 227. http://www.columbia.edu/kermit/ckermit80.html#x3.8 + 228. http://www.columbia.edu/kermit/ckermit80.html#x3.8 + 229. http://www.columbia.edu/kermit/ckermit80.html#top + 230. http://www.columbia.edu/kermit/ckermit80.html#ftp + 231. http://www.columbia.edu/kermit/ckermit.html + 232. http://www.columbia.edu/kermit/index.html + 233. http://www.columbia.edu/kermit/ibm_ie.html + 234. http://www.columbia.edu/kermit/ckermit80.html#x3.10 + 235. http://www.columbia.edu/kermit/ckermit80.html#top + 236. http://www.columbia.edu/kermit/ckermit80.html#ftp + 237. http://www.columbia.edu/kermit/ckermit.html + 238. http://www.columbia.edu/kermit/index.html + 239. http://www.columbia.edu/kermit/ck60manual.html + 240. http://www.columbia.edu/kermit/ckermit70.html#x4.17 + 241. http://www.columbia.edu/kermit/ckermit70.html + 242. http://www.columbia.edu/kermit/ckermit80.html#x3.6 + 243. http://www.columbia.edu/kermit/ckermit80.html#x3.11 + 244. http://www.columbia.edu/kermit/ckermit80.html#x3.1.4 + 245. http://www.columbia.edu/kermit/security.html + 246. http://www.columbia.edu/kermit/ckermit80.html#x3.7 + 247. http://www.columbia.edu/kermit/ckermit80.html#x3.7 + 248. http://www.columbia.edu/kermit/ckermit80.html#x8.13.4 + 249. http://www.columbia.edu/kermit/ckermit80.html#permswitch + 250. http://www.columbia.edu/kermit/ckermit80.html#ftpchmod + 251. http://www.columbia.edu/kermit/ckermit80.html#x3.6.2 + 252. http://www.columbia.edu/kermit/ckermit80.html#x4 + 253. http://www.columbia.edu/kermit/ckermit80.html#top + 254. http://www.columbia.edu/kermit/ckermit80.html#ftp + 255. http://www.columbia.edu/kermit/ckermit.html + 256. http://www.columbia.edu/kermit/index.html + 257. http://www.columbia.edu/kermit/ckermit80.html#x7 + 258. http://www.columbia.edu/kermit/ckermit80.html#x3.8 + 259. http://www.columbia.edu/kermit/ckermit80.html#x3.8 + 260. http://www.columbia.edu/kermit/ckb2.htm + 261. http://www.columbia.edu/kermit/ckermit80.html#x3.10 + 262. http://www.columbia.edu/kermit/ckermit80.html#x3.10 + 263. http://www.columbia.edu/kermit/ckermit80.html#x3.6 + 264. http://www.columbia.edu/kermit/ckermit80.html#setftptype + 265. http://www.columbia.edu/kermit/ckermit80.html#top + 266. http://www.columbia.edu/kermit/ckermit80.html#ftp + 267. http://www.columbia.edu/kermit/ckermit.html + 268. http://www.columbia.edu/kermit/index.html + 269. http://www.columbia.edu/kermit/ckermit70.html#x4.9 + 270. http://www.columbia.edu/kermit/ckermit80.html#x3.5.1 + 271. http://www.columbia.edu/kermit/ckermit80.html#erroraction + 272. http://www.columbia.edu/kermit/ckermit70.html#x1.5 + 273. http://www.columbia.edu/kermit/ckermit70.html#x4.7 + 274. http://www.columbia.edu/kermit/ckermit70.html#x1.6 + 275. http://www.columbia.edu/kermit/ckermit80.html#x8.13 + 276. http://www.columbia.edu/kermit/ckermi70.htm#x1.5.4 + 277. http://www.columbia.edu/kermit/ckermi70.htm + 278. http://www.columbia.edu/kermit/ckermit80.html#x4 + 279. http://www.columbia.edu/kermit/ckermit80.html#x3.7 + 280. http://www.columbia.edu/kermit/ckermit80.html#x3.5.2 + 281. http://www.columbia.edu/kermit/ckermit80.html#x3.7 + 282. http://www.columbia.edu/kermit/ckermit80.html#erroraction + 283. http://www.columbia.edu/kermit/ckermit80.html#x3.5.2 + 284. http://www.columbia.edu/kermit/ckermit80.html#erroraction + 285. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames + 286. http://www.columbia.edu/kermit/ckermit80.html#ftpperms + 287. http://www.columbia.edu/kermit/ckermit80.html#ftpunique + 288. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames + 289. http://www.columbia.edu/kermit/ckermit80.html#note_utc + 290. http://www.columbia.edu/kermit/ckermit80.html#note_date + 291. http://www.columbia.edu/kermit/ckermit80.html#x3.6 + 292. http://www.boulder.nist.gov/timefreq/faq/faq.htm#10: + 293. http://www.columbia.edu/kermit/ckermit80.html#x3.7 + 294. http://www.columbia.edu/kermit/ckermit80.html#top + 295. http://www.columbia.edu/kermit/ckermit80.html#ftp + 296. http://www.columbia.edu/kermit/ckermit.html + 297. http://www.columbia.edu/kermit/index.html + 298. http://www.columbia.edu/kermit/ckermit80.html#x3.11 + 299. http://www.columbia.edu/kermit/ckermi70.htm#x4.3 + 300. http://www.columbia.edu/kermit/ckermit70.html + 301. http://www.columbia.edu/kermit/ckermit80.html#x5 + 302. http://www.columbia.edu/kermit/ckermit80.html#x3.6.3 + 303. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames + 304. http://www.columbia.edu/kermit/ckermi70.htm#x4.1 + 305. http://www.columbia.edu/kermit/ckermi70.htm#x4.2.2 + 306. http://www.columbia.edu/kermit/ckermi70.htm#x1.5.4 + 307. http://www.columbia.edu/kermit/ckermit80.html#x3.6.2 + 308. http://www.columbia.edu/kermit/ckermit80.html#x3.11 + 309. http://www.columbia.edu/kermit/ckermit80.html#x3.11 + 310. http://www.columbia.edu/kermit/ckermit80.html#srvrename + 311. http://www.columbia.edu/kermit/ckermi70.htm#x4.1 + 312. http://www.columbia.edu/kermit/ckermi70.htm + 313. http://www.columbia.edu/kermit/ckb2.htm + 314. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames + 315. http://www.columbia.edu/kermit/ckermit80.html#x3.5.3 + 316. http://www.proftpd.net/ + 317. http://www.columbia.edu/kermit/ckermit80.html#top + 318. http://www.columbia.edu/kermit/ckermit80.html#ftp + 319. http://www.columbia.edu/kermit/ckermit.html + 320. http://www.columbia.edu/kermit/index.html + 321. http://www.columbia.edu/kermit/ckb2.htm + 322. http://www.columbia.edu/kermit/ckcsets.html + 323. http://www.columbia.edu/kermit/unicode.html + 324. http://www.columbia.edu/kermit/ckcsets.html + 325. http://www.columbia.edu/kermit/ckcsets.html + 326. http://www.columbia.edu/kermit/ckermit80.html#x4 + 327. http://www.columbia.edu/kermit/utf8.html + 328. http://www.columbia.edu/kermit/ckcsets.html + 329. http://www.columbia.edu/kermit/ckermit80.html#x4 + 330. ftp://ftp.isi.edu/in-notes/rfc2640.txt + 331. http://www.columbia.edu/kermit/ckermit80.html#top + 332. http://www.columbia.edu/kermit/ckermit80.html#ftp + 333. http://www.columbia.edu/kermit/ckermit.html + 334. http://www.columbia.edu/kermit/index.html + 335. http://www.columbia.edu/kermit/ckermit80.html#top + 336. http://www.columbia.edu/kermit/ckermit80.html#ftp + 337. http://www.columbia.edu/kermit/ckermit.html + 338. http://www.columbia.edu/kermit/index.html + 339. http://www.columbia.edu/kermit/ckermit80.html#top + 340. http://www.columbia.edu/kermit/ckermit80.html#ftp + 341. http://www.columbia.edu/kermit/ckermit.html + 342. http://www.columbia.edu/kermit/index.html + 343. http://www.columbia.edu/kermit/ftpscripts.html + 344. http://www.columbia.edu/kermit/ckermit80.html#x3.2 + 345. http://www.columbia.edu/kermit/ckermit80.html#x3.2 + 346. ftp://ftp.isi.edu/in-notes/rfc959.txt + 347. http://www.columbia.edu/kermit/ckscripts.html + 348. http://www.columbia.edu/kermit/ckermit80.html#top + 349. http://www.columbia.edu/kermit/ckermit80.html#ftp + 350. http://www.columbia.edu/kermit/ftpscript.html + 351. http://www.columbia.edu/kermit/ckermit.html + 352. http://www.columbia.edu/kermit/index.html + 353. http://www.columbia.edu/kermit/ckermit80.html#x3.11.1 + 354. http://www.columbia.edu/kermit/ckermit80.html#x3.11.2 + 355. http://www.columbia.edu/kermit/ckermit80.html#x3.11.3 + 356. http://www.columbia.edu/kermit/ckermit80.html#x3.11.4 + 357. http://www.columbia.edu/kermit/ckermit80.html#x3.11.5 + 358. http://www.columbia.edu/kermit/ckermit.html + 359. http://www.columbia.edu/kermit/k95.html + 360. http://www.columbia.edu/kermit/ckermit80.html#x3.11.5 + 361. ftp://ftp.isi.edu/in-notes/rfc959.txt + 362. ftp://ftp.isi.edu/in-notes/rfc2389.txt + 363. http://www.ietf.org/internet-drafts/draft-ietf-ftpext-mlst-16.txt + 364. http://www.columbia.edu/kermit/ftpclient.html + 365. http://www.columbia.edu/kermit/ckermit80.html#top + 366. http://www.columbia.edu/kermit/ckermit80.html#ftp + 367. http://www.columbia.edu/kermit/ckermit.html + 368. http://www.columbia.edu/kermit/index.html + 369. http://www.columbia.edu/kermit/ckermit80.html#x3 + 370. http://www.columbia.edu/kermit/ckermit80.html#ucs2 + 371. http://www.columbia.edu/kermit/ckermit80.html#top + 372. http://www.columbia.edu/kermit/ckermit80.html#contents + 373. http://www.columbia.edu/kermit/ckermit.html + 374. http://www.columbia.edu/kermit/index.html + 375. http://www.columbia.edu/kermit/ckermit80.html#top + 376. http://www.columbia.edu/kermit/ckermit80.html#contents + 377. http://www.columbia.edu/kermit/ckermit.html + 378. http://www.columbia.edu/kermit/index.html + 379. http://www.columbia.edu/kermit/ckb2.htm + 380. http://www.columbia.edu/kermit/ckermit80.html#top + 381. http://www.columbia.edu/kermit/ckermit80.html#contents + 382. http://www.columbia.edu/kermit/ckermit.html + 383. http://www.columbia.edu/kermit/index.html + 384. http://www.columbia.edu/kermit/ckermit80.html#x4 + 385. http://www.columbia.edu/kermit/ckermit80.html#x4 + 386. http://www.columbia.edu/kermit/ckermit80.html#x8.12 + 387. http://www.columbia.edu/kermit/ckermit80.html#x8.1 + 388. http://www.columbia.edu/kermit/ckermit80.html#x12 + 389. http://www.columbia.edu/kermit/ckermit80.html#x8.12 + 390. http://www.columbia.edu/kermit/ckermit80.html#top + 391. http://www.columbia.edu/kermit/ckermit80.html#contents + 392. http://www.columbia.edu/kermit/ckermit.html + 393. http://www.columbia.edu/kermit/index.html + 394. http://www.columbia.edu/kermit/ckermit80.html#x8.14 + 395. http://www.columbia.edu/kermit/ckermit80.html#top + 396. http://www.columbia.edu/kermit/ckermit80.html#contents + 397. http://www.columbia.edu/kermit/ckermit.html + 398. http://www.columbia.edu/kermit/index.html + 399. http://www.columbia.edu/kermit/ckermit80.html#x9 + 400. http://www.columbia.edu/kermit/ckermit80.html#top + 401. http://www.columbia.edu/kermit/ckermit80.html#contents + 402. http://www.columbia.edu/kermit/ckermit.html + 403. http://www.columbia.edu/kermit/index.html + 404. http://www.columbia.edu/kermit/ckermit80.html#x8.6 + 405. http://www.columbia.edu/kermit/ckermit80.html#top + 406. http://www.columbia.edu/kermit/ckermit80.html#contents + 407. http://www.columbia.edu/kermit/ckermit.html + 408. http://www.columbia.edu/kermit/index.html + 409. http://www.columbia.edu/kermit/ckermit80.html#top + 410. http://www.columbia.edu/kermit/ckermit80.html#contents + 411. http://www.columbia.edu/kermit/ckermit.html + 412. http://www.columbia.edu/kermit/index.html + 413. http://www.columbia.edu/kermit/ckermit80.html#top + 414. http://www.columbia.edu/kermit/ckermit80.html#contents + 415. http://www.columbia.edu/kermit/ckermit.html + 416. http://www.columbia.edu/kermit/index.html + 417. http://www.columbia.edu/kermit/ckermit80.html#fjoin + 418. http://www.columbia.edu/kermit/ckermit80.html#fsplit + 419. http://www.columbia.edu/kermit/ckermit80.html#x8.10 + 420. http://www.columbia.edu/kermit/ckermit80.html#top + 421. http://www.columbia.edu/kermit/ckermit80.html#contents + 422. http://www.columbia.edu/kermit/ckermit.html + 423. http://www.columbia.edu/kermit/index.html + 424. http://www.columbia.edu/kermit/ckermit80.html#x9 + 425. http://www.columbia.edu/kermit/ckermit80.html#x9 + 426. http://www.columbia.edu/kermit/ckermit80.html#x9 + 427. http://www.columbia.edu/kermit/ckermit80.html#x3 + 428. http://www.columbia.edu/kermit/ckermit80.html#x3 + 429. http://www.columbia.edu/kermit/ckermit80.html#x3.2 + 430. http://www.columbia.edu/kermit/ckermit80.html#x3.2 + 431. http://www.columbia.edu/kermit/ckermit80.html#x3.8 + 432. http://www.columbia.edu/kermit/ckermit80.html#x3 + 433. http://www.columbia.edu/kermit/ckermit80.html#x3 + 434. http://www.columbia.edu/kermit/ckermit80.html#x3 + 435. http://www.columbia.edu/kermit/ckermit80.html#x3.2 + 436. http://www.columbia.edu/kermit/ckermit80.html#x3 + 437. http://www.columbia.edu/kermit/ckermit80.html#x8.13 + 438. http://www.columbia.edu/kermit/ckermit80.html#x8.13 + 439. http://www.columbia.edu/kermit/ckermit80.html#x9 + 440. http://www.columbia.edu/kermit/ckermit80.html#x8.10 + 441. http://www.columbia.edu/kermit/ckermit80.html#x8.7.4 + 442. http://www.columbia.edu/kermit/ckermit80.html#top + 443. http://www.columbia.edu/kermit/ckermit80.html#contents + 444. http://www.columbia.edu/kermit/ckermit.html + 445. http://www.columbia.edu/kermit/index.html + 446. http://www.columbia.edu/kermit/ckermit80.html#top + 447. http://www.columbia.edu/kermit/ckermit80.html#contents + 448. http://www.columbia.edu/kermit/ckermit.html + 449. http://www.columbia.edu/kermit/index.html + 450. http://www.columbia.edu/kermit/ckermit80.html#top + 451. http://www.columbia.edu/kermit/ckermit80.html#contents + 452. http://www.columbia.edu/kermit/ckermit.html + 453. http://www.columbia.edu/kermit/index.html + 454. http://www.columbia.edu/kermit/ckermit80.html#x8.7 + 455. http://www.columbia.edu/kermit/ckermit80.html#top + 456. http://www.columbia.edu/kermit/ckermit80.html#contents + 457. http://www.columbia.edu/kermit/ckermit.html + 458. http://www.columbia.edu/kermit/index.html + 459. http://www.columbia.edu/kermit/ckermit80.html#scriptedit + 460. http://www.columbia.edu/kermit/ckermit80.html#top + 461. http://www.columbia.edu/kermit/ckermit80.html#contents + 462. http://www.columbia.edu/kermit/ckermit.html + 463. http://www.columbia.edu/kermit/index.html + 464. http://www.columbia.edu/kermit/ckermit80.html#top + 465. http://www.columbia.edu/kermit/ckermit80.html#contents + 466. http://www.columbia.edu/kermit/ckermit.html + 467. http://www.columbia.edu/kermit/index.html + 468. ftp://ftp.isi.edu/in-notes/rfc2822.txt + 469. ftp://ftp.isi.edu/in-notes/rfc2822.txt + 470. ftp://ftp.isi.edu/in-notes/rfc2822.txt + 471. ftp://ftp.isi.edu/in-notes/rfc2822.txt + 472. http://www.columbia.edu/kermit/ckermit80.html#top + 473. http://www.columbia.edu/kermit/ckermit80.html#contents + 474. http://www.columbia.edu/kermit/ckermit.html + 475. http://www.columbia.edu/kermit/index.html + 476. http://www.columbia.edu/kermit/ckermit80.html#x8.1 + 477. http://www.columbia.edu/kermit/ckermit80.html#top + 478. http://www.columbia.edu/kermit/ckermit80.html#contents + 479. http://www.columbia.edu/kermit/ckermit.html + 480. http://www.columbia.edu/kermit/index.html + 481. http://www.columbia.edu/kermit/ckermit80.html#x8.2 + 482. http://www.columbia.edu/kermit/ckermit80.html#top + 483. http://www.columbia.edu/kermit/ckermit80.html#contents + 484. http://www.columbia.edu/kermit/ckermit.html + 485. http://www.columbia.edu/kermit/index.html + 486. http://www.columbia.edu/kermit/ckermit80.html#x9.8 + 487. http://www.columbia.edu/kermit/ckermit80.html#x9.8 + 488. http://www.columbia.edu/kermit/ckermit80.html#x8.2 + 489. http://www.columbia.edu/kermit/ckermit80.html#top + 490. http://www.columbia.edu/kermit/ckermit80.html#contents + 491. http://www.columbia.edu/kermit/ckermit.html + 492. http://www.columbia.edu/kermit/index.html + 493. http://www.columbia.edu/kermit/ckermit80.html#top + 494. http://www.columbia.edu/kermit/ckermit80.html#contents + 495. http://www.columbia.edu/kermit/ckermit.html + 496. http://www.columbia.edu/kermit/index.html + 497. http://www.columbia.edu/kermit/ckermit80.html#x9.8 + 498. http://www.columbia.edu/kermit/ckermit80.html#top + 499. http://www.columbia.edu/kermit/ckermit80.html#contents + 500. http://www.columbia.edu/kermit/ckermit.html + 501. http://www.columbia.edu/kermit/index.html + 502. http://www.columbia.edu/kermit/ckermit80.html#x9.8 + 503. http://www.columbia.edu/kermit/ckermit80.html#x9.8 + 504. http://www.columbia.edu/kermit/ckermit80.html#x9.6 + 505. http://www.columbia.edu/kermit/ckermit80.html#top + 506. http://www.columbia.edu/kermit/ckermit80.html#contents + 507. http://www.columbia.edu/kermit/ckermit.html + 508. http://www.columbia.edu/kermit/index.html + 509. http://www.columbia.edu/kermit/ckermit80.html#x9.8 + 510. http://www.columbia.edu/kermit/ckermit80.html#x9.8 + 511. http://www.columbia.edu/kermit/ckermit80.html#top + 512. http://www.columbia.edu/kermit/ckermit80.html#contents + 513. http://www.columbia.edu/kermit/ckermit.html + 514. http://www.columbia.edu/kermit/index.html + 515. http://www.columbia.edu/kermit/ckermit80.html#top + 516. http://www.columbia.edu/kermit/ckermit80.html#contents + 517. http://www.columbia.edu/kermit/ckermit.html + 518. http://www.columbia.edu/kermit/index.html + 519. http://www.columbia.edu/kermit/ckermit80.html#top + 520. http://www.columbia.edu/kermit/ckermit80.html#contents + 521. http://www.columbia.edu/kermit/ckermit.html + 522. http://www.columbia.edu/kermit/index.html + 523. mailto:thucdat@hotmail.com + 524. http://www.columbia.edu/kermit/ckermit80.html#x9.9.2 + 525. http://www.columbia.edu/kermit/ckermit80.html#top + 526. http://www.columbia.edu/kermit/ckermit80.html#contents + 527. http://www.columbia.edu/kermit/ckermit.html + 528. http://www.columbia.edu/kermit/index.html + 529. http://www.columbia.edu/kermit/ckermit80.html#top + 530. http://www.columbia.edu/kermit/ckermit80.html#contents + 531. http://www.columbia.edu/kermit/ckermit.html + 532. http://www.columbia.edu/kermit/index.html + 533. http://www.columbia.edu/kermit/ckermit80.html#top + 534. http://www.columbia.edu/kermit/ckermit80.html#contents + 535. http://www.columbia.edu/kermit/ckermit.html + 536. http://www.columbia.edu/kermit/index.html + 537. http://www.columbia.edu/kermit/ckermit80.html#x9.2 + 538. http://www.columbia.edu/kermit/ckermit80.html#top + 539. http://www.columbia.edu/kermit/ckermit80.html#contents + 540. http://www.columbia.edu/kermit/ckermit.html + 541. http://www.columbia.edu/kermit/index.html + 542. http://www.columbia.edu/kermit/ckermit80.html#x4 + 543. http://www.columbia.edu/kermit/ckermit80.html#x4 + 544. http://www.columbia.edu/kermit/ckermit80.html#top + 545. http://www.columbia.edu/kermit/ckermit80.html#contents + 546. http://www.columbia.edu/kermit/ckermit.html + 547. http://www.columbia.edu/kermit/index.html + 548. http://www.columbia.edu/kermit/ckermit80.html#top + 549. http://www.columbia.edu/kermit/ckermit80.html#contents + 550. http://www.columbia.edu/kermit/ckermit.html + 551. http://www.columbia.edu/kermit/index.html + 552. http://www.columbia.edu/kermit/ckermit80.html#top + 553. http://www.columbia.edu/kermit/ckermit80.html#contents + 554. http://www.columbia.edu/kermit/ckermit.html + 555. http://www.columbia.edu/kermit/index.html + 556. http://www.columbia.edu/kermit/ckermit80.html#x4 + 557. http://www.columbia.edu/kermit/ckermit80.html#x3.7 + 558. http://www.columbia.edu/kermit/ckermit80.html#x3.7 + 559. http://www.columbia.edu/kermit/ckermit80.html#top + 560. http://www.columbia.edu/kermit/ckermit80.html#contents + 561. http://www.columbia.edu/kermit/ckermit.html + 562. http://www.columbia.edu/kermit/index.html + 563. ftp://ftp.isi.edu/in-notes/rfc2217.txt + 564. http://www.columbia.edu/kermit/ckermit80.html#top + 565. http://www.columbia.edu/kermit/ckermit80.html#contents + 566. ftp://kermit.columbia.edu/kermit/sredird/ + 567. http://www.columbia.edu/kermit/ckermit.html + 568. http://www.columbia.edu/kermit/index.html + 569. http://www.columbia.edu/kermit/ckermi70.htm#x4.22 + 570. http://www.columbia.edu/kermit/ckermit80.html#top + 571. http://www.columbia.edu/kermit/ckermit80.html#contents + 572. http://www.columbia.edu/kermit/ckermit.html + 573. http://www.columbia.edu/kermit/index.html + 574. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3 + 575. http://www.columbia.edu/kermit/cuiksd.html + 576. http://www.columbia.edu/kermit/ckermit80.html#top + 577. http://www.columbia.edu/kermit/ckermit80.html#contents + 578. http://www.columbia.edu/kermit/ckermit.html + 579. http://www.columbia.edu/kermit/index.html + 580. http://www.columbia.edu/kermit/ckermit80.html#top + 581. http://www.columbia.edu/kermit/ckermit80.html#contents + 582. http://www.columbia.edu/kermit/ckermit.html + 583. http://www.columbia.edu/kermit/index.html + 584. http://www.columbia.edu/kermit/index.html diff --git a/ckermit80.txt b/ckermit80.txt index 493338a..d444545 100644 --- a/ckermit80.txt +++ b/ckermit80.txt @@ -3435,7 +3435,7 @@ C-Kermit>ftp put ? Filename, or switch, one of the following: If this switch is given, then instead of actually retrieving the selected files, the GET command retrieves a list of the names of the files that would be retrieved, and places it in - the specifed file. The resulting file is an ordinary text file, + the specified file. The resulting file is an ordinary text file, with one filename per line, suitable for reading by a person, or processing by a computer program, including Kermit itself (FOPEN / FREAD / FWRITE / FCLOSE), and as /FILELIST: file. If diff --git a/ckuus2.c b/ckuus2.c index 4ef6b75..d837337 100644 --- a/ckuus2.c +++ b/ckuus2.c @@ -5558,7 +5558,7 @@ static char * hxxf_op[] = { " ", "/WRITE", " Open the file for writing. If /READ was not also specified, this creates", -" a new file. If /READ was specifed, the existing file is preserved, but", +" a new file. If /READ was specified, the existing file is preserved, but", " writing is allowed. In both cases, the read/write pointer is initially", " at the beginning of the file.", " ", diff --git a/debian/patches/060_speeling.patch b/debian/patches/060_speeling.patch index bacde1e..a57b0fd 100644 --- a/debian/patches/060_speeling.patch +++ b/debian/patches/060_speeling.patch @@ -15,7 +15,7 @@ Index: ckermit/ckcftp.c Index: ckermit/ckuus2.c =================================================================== --- ckermit.orig/ckuus2.c 2010-05-12 01:33:56.000000000 +0100 -+++ ckermit/ckuus2.c 2010-05-12 01:36:39.000000000 +0100 ++++ ckermit/ckuus2.c 2010-05-12 01:38:07.000000000 +0100 @@ -3660,7 +3660,7 @@ " ", "SET DIAL RETRIES ", @@ -25,6 +25,15 @@ Index: ckermit/ckuus2.c " because automatic redialing is illegal in some countries.", " ", "SET DIAL INTERVAL ", +@@ -5558,7 +5558,7 @@ + " ", + "/WRITE", + " Open the file for writing. If /READ was not also specified, this creates", +-" a new file. If /READ was specifed, the existing file is preserved, but", ++" a new file. If /READ was specified, the existing file is preserved, but", + " writing is allowed. In both cases, the read/write pointer is initially", + " at the beginning of the file.", + " ", @@ -9012,7 +9012,7 @@ "" }; @@ -104,3 +113,16 @@ Index: ckermit/ckuusr.h #define XYMSGS 66 /* MESSAGEs ON/OFF */ #ifdef TNCODE #define XYTEL 67 /* SET TELNET parameters */ +Index: ckermit/ckermit80.txt +=================================================================== +--- ckermit.orig/ckermit80.txt 2010-05-12 01:37:40.000000000 +0100 ++++ ckermit/ckermit80.txt 2010-05-12 01:38:24.000000000 +0100 +@@ -3435,7 +3435,7 @@ + If this switch is given, then instead of actually retrieving + the selected files, the GET command retrieves a list of the + names of the files that would be retrieved, and places it in +- the specifed file. The resulting file is an ordinary text file, ++ the specified file. The resulting file is an ordinary text file, + with one filename per line, suitable for reading by a person, + or processing by a computer program, including Kermit itself + (FOPEN / FREAD / FWRITE / FCLOSE), and as /FILELIST: file. If -- 2.11.0