home *** CD-ROM | disk | FTP | other *** search
/ Columbia Kermit / kermit.zip / c-kermit / ckermit3.txt < prev    next >
Text File  |  2020-01-01  |  465KB  |  10,287 lines
  1.  
  2.    [1]The Columbia Crown The Kermit Project | Columbia University
  3.    612 West 115th Street, New York NY 10025 USA o [2]kermit@columbia.edu
  4.    ...since 1981
  5.    [3]Home [4]Kermit 95 [5]C-Kermit [6]Scripts [7]Current [8]New [9]FAQ
  6.    [10]Support
  7.  
  8. C-Kermit 8.0 Update Notes
  9.  
  10.    [ [11]Contents ] [ [12]C-Kermit ] [ [13]Kermit Home ]
  11.  
  12. Second Supplement to [14]Using C-Kermit, 2nd Edition
  13.  
  14. For C-Kermit 8.0
  15.  
  16.    As of C-Kermit version: 8.0.211
  17.    Date of C-Kermit release: 10 April 2003
  18.    This file last updated: Mon Sep 13 08:52:36 2010
  19.  
  20.      * IF YOU ARE READING A PLAIN-TEXT version of this document, note that
  21.        it is a plain-text dump of a Web page. You can visit the original
  22.        (and possibly more up-to-date) Web page here:
  23.   [15]http://www.columbia.edu/kermit/ckermit80.html
  24.  
  25.      * If you are reading the HTML version of this file with a GUI Web
  26.        browser, the features added since C-Kermit 8.0.201 are shown in red
  27.        if your browser and monitor permit. Features that were new to
  28.        versions 8.0.200 and 201 are in black.
  29.  
  30. Authors: Frank da Cruz and Christine M. Gianone
  31. Address: The Kermit Project
  32.          Columbia University
  33.          612 West 115th Street
  34.          New York NY 10025-7799
  35.          USA
  36. Fax:     +1 (212) 662-6442
  37. E-Mail:  [16]kermit-support@columbia.edu
  38. Web:     [17]http://www.columbia.edu/kermit/
  39. Or:      [18]http://www.kermit-project.org/
  40. Or:      [19]http://www.columbia.nyc.ny.us/kermit/
  41.  
  42. NOTICES
  43.  
  44.    This document:
  45.           Copyright ⌐ 1997, 2002, Frank da Cruz and Christine M. Gianone.
  46.           All rights reserved.
  47.  
  48.    Kermit 95:
  49.           Copyright ⌐ 1995, 2002, Trustees of Columbia University in the
  50.           City of New York. All rights reserved.
  51.  
  52.    C-Kermit:
  53.           Copyright ⌐ 1985, 2002,
  54.           Trustees of Columbia University in the City of New York. All
  55.           rights reserved. See the C-Kermit [20]COPYING.TXT file or the
  56.           copyright text in the [21]ckcmai.c module for disclaimer and
  57.           permissions.
  58.  
  59.    When Kerberos(TM) and/or SRP(TM) (Secure Remote Password) and/or
  60.           SSL/TLS protocol are included:
  61.           Portions Copyright ⌐ 1990, Massachusetts Institute of
  62.           Technology.
  63.           Portions Copyright ⌐ 1991, 1993 Regents of the University of
  64.           California.
  65.           Portions Copyright ⌐ 1991, 1992, 1993, 1994, 1995 by AT&T.
  66.           Portions Copyright ⌐ 1997, Stanford University.
  67.           Portions Copyright ⌐ 1995-1997, Eric Young <eay@cryptosoft.com>.
  68.  
  69.    For the full text of the third-party copyright notices, see
  70.    [22]Appendix V.
  71.  
  72. WHAT IS IN THIS FILE
  73.  
  74.    This file lists changes made to C-Kermit since version 7.0 was released
  75.    in January 2000. Use this file as a supplement to:
  76.  
  77.      * The second edition of [23]Using C-Kermit; and:
  78.      * The [24]C-Kermit 7.0 Update Notes. Also available in plain-text
  79.        form as [25]ckermit70.txt.
  80.  
  81.    until the third edition of Using C-Kermit is published. We apologize
  82.    for the scattered documentation and will consolidate it when we are
  83.    able.
  84.  
  85. ADDITIONAL FILES
  86.  
  87.    Several other files accompany this new Kermit release:
  88.  
  89.    [26]ckututor.html
  90.           C-Kermit Tutorial (for Unix). Also distributed in Nroff form as
  91.           [27]ckuker.nr, the Unix C-Kermit manual page.
  92.  
  93.    [28]security.htm
  94.           Discussion of Kermit's new authentication and encryption
  95.           features, updated for C-Kermit 8.0.
  96.  
  97.    [29]telnet.htm
  98.           Detailed documentation of Kermit's Telnet client, updated for
  99.           C-Kermit 8.0.
  100.  
  101.    [30]ftpscripts.html
  102.           Tutorial: Writing FTP automation scripts
  103.  
  104.    [31]ckcbwr.html
  105.           Platform-independent C-Kermit hints and tips. Also distributed
  106.           in plain text form as [32]ckcbwr.txt
  107.  
  108.    [33]ckubwr.html
  109.           Unix-specific C-Kermit hints and tips. Also distributed in plain
  110.           text form as [34]ckubwr.txt.
  111.  
  112.    [35]ckvbwr.html
  113.           VMS-specific C-Kermit hints and tips. Also distributed in plain
  114.           text form as [36]ckvbwr.txt.
  115.  
  116.    [37]ckuins.html
  117.           Unix C-Kermit installation instructions. Also distributed in
  118.           plain text form as [38]ckuins.txt.
  119.  
  120.    [39]ckvins.html
  121.           VMS C-Kermit installation instructions. Also distributed in
  122.           plain text form as [40]ckvins.txt.
  123.  
  124.    [41]ckccfg.html
  125.           Compile-time configuration options. Also distributed in plain
  126.           text form as [42]ckccfg.txt.
  127.  
  128.    [43]ckcplm.html
  129.           C-Kermit Program Logic Manual. Also distributed in plain text
  130.           form as [44]ckcplm.txt.
  131.  
  132.    [45]iksd.html
  133.           Internet Kermit Service Administrators Guide for Unix.
  134.  
  135.    [46]skermit.html
  136.           C-Kermit as an SSH Subsystem (SFTP server replacement).
  137.  
  138.    [ [47]Top ] [ [48]C-Kermit ] [ [49]Kermit Home ]
  139.  
  140. CONTENTS
  141.  
  142.      [50]0. WHAT'S NEW
  143.      [51]1. FIXES SINCE VERSION 7.0.196
  144.      [52]2. SSH AND HTTP
  145.          [53]2.1. SSH Connections
  146.          [54]2.2. HTTP Connections
  147.             [55]2.2.1. HTTP Command Switches
  148.             [56]2.2.2. HTTP Action Commands
  149.             [57]2.2.3. HTTP Headers
  150.             [58]2.2.4. Secure HTTP Connections
  151.             [59]2.2.5. HTTP Variables
  152.             [60]2.2.6. The HTTP Command-Line Personality
  153.      [61]3. THE BUILT-IN FTP CLIENT
  154.          [62]3.1. Making and Managing FTP Connections
  155.             [63]3.1.1. Kermit Command-Line Options for FTP
  156.             [64]3.1.2. The FTP Command-Line Personality
  157.             [65]3.1.3. The FTP URL Interpreter
  158.             [66]3.1.4. Interactive FTP Session Establishment
  159.          [67]3.2. Making Secure FTP Connections
  160.          [68]3.3. Setting FTP Preferences
  161.          [69]3.4. Managing Directories and Files
  162.          [70]3.5. Uploading Files With FTP
  163.             [71]3.5.1. FTP PUT Switches
  164.             [72]3.5.2. Update Mode
  165.             [73]3.5.3. Recovery
  166.          [74]3.6. Downloading Files With FTP
  167.             [75]3.6.1. FTP GET Switches
  168.             [76]3.6.2. Filename Collisions
  169.             [77]3.6.3. Recovery
  170.          [78]3.7. Translating Character Sets
  171.             [79]3.7.1. Character Sets and Uploading
  172.             [80]3.7.2. Character Sets and Downloading
  173.          [81]3.8. FTP Command Shortcuts
  174.          [82]3.9. Dual Sessions
  175.          [83]3.10. Automating FTP Sessions
  176.             [84]3.10.1. FTP-Specific Variables and Functions
  177.             [85]3.10.2. Examples
  178.             [86]3.10.3. Automating Secure FTP Connections
  179.          [87]3.11. Advanced FTP Protocol Features  [88]4. FILE SCANNING
  180.     [89]5. FILE AND DIRECTORY NAMES CONTAINING SPACES
  181.     [90]6. OTHER COMMAND PARSING IMPROVEMENTS
  182.          [91]6.1. Grouping Macro Arguments
  183.          [92]6.2. Directory and File Name Completion
  184.          [93]6.3. Passing Arguments to Command Files
  185.          [94]6.4. More-Prompting
  186.          [95]6.5. Commas in Macro Definitions
  187.          [96]6.6. Arrow Keys
  188.     [97]7. NEW COMMANDS AND SWITCHES
  189.     [98]8. SCRIPTING IMPROVEMENTS
  190.          [99]8.1. Performance and Debugging
  191.          [100]8.2. Using Macros as Numeric Variables
  192.          [101]8.3. New IF Conditions
  193.          [102]8.4. The ON_UNKNOWN_COMMAND and ON_CD Macros
  194.          [103]8.5. The SHOW MACRO Command
  195.          [104]8.6. Arrays
  196.          [105]8.7. New or Improved Built-in Variables and Functions
  197.          [106]8.8. The RETURN and END Commands
  198.          [107]8.9. UNDEFINing Groups of Variables
  199.          [108]8.10. The INPUT and MINPUT Commands
  200.          [109]8.11. Learned Scripts
  201.          [110]8.12. Pattern Matching
  202.          [111]8.13. Dates and Times
  203.          [112]8.14. Trapping Keyboard Interruption
  204.     [113]9. S-EXPRESSIONS
  205.          [114]9.1. What is an S-Expression?
  206.          [115]9.2. Integer and Floating-Point-Arithmetic
  207.          [116]9.3. How to Use S-Expressions
  208.          [117]9.4. Summary of Built-in Constants and Operators
  209.          [118]9.5. Variables
  210.          [119]9.6. Assignments and Scope
  211.          [120]9.7. Conditional Expressions
  212.          [121]9.8. Extensibility
  213.          [122]9.9. Examples
  214.          [123]9.10. Differences from Algebraic Notation
  215.          [124]9.11.Differences from Lisp
  216.     [125]10. FILE TRANSFER
  217.     [126]11. MODEMS AND DIALING
  218.     [127]12. TERMINAL CONNECTION
  219.     [128]13. CHARACTER SETS
  220.     [129]14. DIALOUT FROM TELNET TERMINAL SERVERS
  221.     [130]15. COPING WITH BROKEN KERMIT PARTNERS
  222.     [131]16. NEW COMMAND-LINE OPTIONS
  223.     [132]17. LOGS
  224.  
  225.    [ [133]Top ] [ [134]C-Kermit ] [ [135]Kermit Home ]
  226.  
  227. 0. WHAT'S NEW
  228.  
  229.    The Initialization and Customization Files
  230.           C-Kermit 8.0 now supports specification of the initialization
  231.           file name (path) in an environment variable, CKERMIT_INI. It
  232.           also relies far less than before on the initialization for
  233.           functioning. See [136]Section 5 of the Unix C-Kermit
  234.           [137]installation instructions for details. As of version
  235.           8.0.201, C-Kermit also executes your customization file (if you
  236.           have one) even if the initialization file was not found.
  237.           Previously, the customization file was executed by a TAKE
  238.           command in the initialization file (and it still is, if an
  239.           initialization is found).
  240.  
  241.    Incompatible Changes
  242.           As always, we do our best to avoid changes that break existing
  243.           scripts. However, C-Kermit 8.0 does include a rather pervasive
  244.           syntax change that might alter the behavior of scripts that
  245.           depend on the previous behavior. As described in [138]Section 5,
  246.           C-Kermit now accepts doublequotes in most contexts where you
  247.           previously had to use braces to group multiple words into a
  248.           single field, or to force inclusion of leading or trailing
  249.           blanks. Most noticeably, in C-Kermit 7.0 and earlier:
  250.  
  251.   echo {this is a string}
  252.  
  253.           would print:
  254.  
  255.   this is a string
  256.  
  257.           whereas:
  258.  
  259.   echo "this is a string"
  260.  
  261.           printed:
  262.  
  263.   "this is a string"
  264.  
  265.           In C-Kermit 8.0, both print:
  266.  
  267.   this is a string
  268.  
  269.           To force the doublequotes to be treated as part of the string,
  270.           use either of the following forms:
  271.  
  272.   echo {"this is a string"}
  273.   echo ""this is a string""
  274.  
  275.           Similarly, to force braces to be treated as part of the string:
  276.  
  277.   echo "{this is a string}"
  278.   echo {{this is a string}}
  279.  
  280.           Other incompatibilities:
  281.  
  282.          1. Using the SET HOST command to make HTTP connections is no
  283.             longer supported. Instead, use the new HTTP OPEN command,
  284.             described in [139]Section 2.2.
  285.  
  286.    C-Kermit 7.1 Alpha.01 (8 December 2000)
  287.  
  288.      Its major new features are those listed in the [140]Table of
  289.           Contents: the FTP client, file scanning, command parsing and
  290.           scripting improvements, S-Expressions, and support for the
  291.           Telnet Com Port Option, plus wider availability of the Kerberos,
  292.           SSL/TLS, and SRP security options for secure Internet
  293.           connections.
  294.  
  295.    C-Kermit 7.1.199 Alpha.02 (4 January 2001)
  296.  
  297.           + C-Kermit now accepts [141]FTP, TELNET, and IKSD URLs as its
  298.             first command-line argument.
  299.           + Character-set translation added to the FTP client for
  300.             [142]filenames.
  301.           + Optional [143]setting of date of incoming files by FTP [M]GET
  302.             from the server date.
  303.           + [144]FTP CHECK filename added to let FTP client check the
  304.             existence of a file on the server.
  305.           + [145]FTP GET /NAMELIST:filename added to get list of server
  306.             filenames into a local file.
  307.           + [146]FTP [M]PUT /SERVER-RENAME:template added to make server
  308.             rename a file as indicated by the template after it has
  309.             arrived completely.
  310.           + FTP [M]GET /SERVER-RENAME:template added to make server rename
  311.             a file as indicated by the template after it has been sent
  312.             completely.
  313.           + FTP [147]VDIRECTORY added for getting verbose directory
  314.             listings from TOPS-20.
  315.           + [148]FTP TYPE TENEX added for transferring 8-bit binary files
  316.             with PDP-10s.
  317.           + Added [149]automatic text/binary mode switching for FTP
  318.             [M]GET, based on filename patterns (e.g. *.zip, *.gz, *.exe
  319.             are binary; *.txt, *.c are text).
  320.           + [150]SET SEND I-PACKETS OFF added for coping with Kermit
  321.             servers that do not support I packets.
  322.           + A new option was added to [151]\fword() and \fsplit() for
  323.             parsing comma-separated lists that might contain empty
  324.             elements.
  325.           + Bug fixes including:
  326.                o {} or "" could not be used as expected to represent the
  327.                  empty string.
  328.                o ,- on a line by itself in a macro definition caused
  329.                  subsequent statements to be skipped.
  330.                o FTP [M]GET didn't work right if path segments were
  331.                  included in the filespec.
  332.                o FTP MGET, if interrupted, did not clear its file list.
  333.                o Various problems with FTP PUT /AS-NAME that nobody
  334.                  noticed.
  335.                o Some FTP messages and displays interfered with each
  336.                  other.
  337.                o Parsing of YESTERDAY, TODAY, and TOMORROW in date-time
  338.                  fields was broken.
  339.                o Automatic old-to-new dialing directory format conversion
  340.                  was broken on VMS.
  341.                o Various source-code portability problems fixed.
  342.           + Improvement of various HELP and SHOW messages.
  343.  
  344.    C-Kermit 7.1.199 Alpha.04 (1 April 2001)
  345.  
  346.           + Big changes:
  347.                o Changed default modem type from NONE to GENERIC.
  348.                o Generic dialing now sends no init string at all.
  349.                o Changed default terminal bytesize from 7 to 8.
  350.           + New features:
  351.                o SET SESSION-LOG TIMESTAMPED-TEXT for timestamped session
  352.                  log.
  353.           + New modem types:
  354.                o Conexant modem family
  355.                o Lucent VENUS chipset
  356.                o PCTel V.90 chipset
  357.                o Zoom V.90
  358.                o Zoom V.92
  359.           + FTP client:
  360.                o FTP OPEN /PASSIVE and /ACTIVE switches added.
  361.                o Now works with servers that that don't include path in
  362.                  NLST response.
  363.                o Fixed SEND /RECURSIVE not to follow symlinks (UNIX).
  364.                o SET FTP VERBOSE-MODE default is now OFF instead of ON.
  365.           + Kermit protocol:
  366.                o Fixed what I hope is the last "Receive window full"
  367.                  error.
  368.                o SET PREFIXING or SET CONTROL PREFIX now automatically
  369.                  sets CLEARCHANNEL OFF.
  370.                o Fixed incorrect report of number of files transferred at
  371.                  end of transfer.
  372.                o Fixed SEND /RECURSIVE not to follow symlinks (UNIX).
  373.           + UNIX:
  374.                o HTTP and shadow passwords enabled for SCO 5.0.6.
  375.                o Even with SET FILENAMES CONVERTED, spaces were still
  376.                  accepted in incoming filenames; now they are converted to
  377.                  underscores.
  378.                o Added support for compile-time mktemp()/mkstemp()
  379.                  selection.
  380.           + VMS:
  381.                o Session-log format for scripted sessions fixed.
  382.           + Scripting:
  383.                o Fixed \frdir() not to follow symlinks (UNIX).
  384.                o Fixed \fday() not to dump core for dates prior to 17 Mar
  385.                  1858.
  386.           + General:
  387.                o "Closing blah..." message upon exit could not be
  388.                  suppressed.
  389.                o Added /PAGE and /NOPAGE to DELETE switches.
  390.                o Added GO response for DELETE /ASK (delete all the rest
  391.                  without asking).
  392.                o Added GO response to "more?" prompt (for multi-page
  393.                  screen output).
  394.                o Updated HELP texts.
  395.  
  396.    C-Kermit 7.1.199 Beta.01 (10 May 2001)
  397.  
  398.           + FTP client verbosity adjustments.
  399.           + Bug with generic modem dialing pausing several secs fixed.
  400.           + SET HOST /USER:, SET LOGIN USERID, etc, fixed when given no
  401.             user ID.
  402.           + A couple \v(dm_blah) dial modifier variables added.
  403.           + "--version" command-line switch added.
  404.           + Fixed NetBSD serial-port DTR handling.
  405.           + Lots of syntax cleanups for Flexelint and gcc -Wall.
  406.           + Fixed modem-type aliases to not take precedence over real
  407.             names.
  408.           + Fixed funny treatment of doublequotes by ECHO command.
  409.           + Enabled SET SESSION-LOG for VMS and other non-UNIX platforms.
  410.           + Fixed changing direction in command history buffer.
  411.           + Fixed handling of IKSD URLs.
  412.           + Made sure DELETE prints a message if it got any errors.
  413.  
  414.    C-Kermit 8.0.200 Beta.02 (28 June 2001)
  415.  
  416.           + Major version number increased from 7 to 8.
  417.           + [152]SSH command.
  418.           + More-consistent Kermit protocol defaults.
  419.           + CONNECT idle timeout and action selection.
  420.           + CONNECT status variable.
  421.           + A way to allocate more space for filename lists.
  422.           + Pseudoterminal handler fixed for late-model Linuxes.
  423.           + Command-line option -dd for timestamped debug log.
  424.           + Download directory now works for external protocols too.
  425.           + GREP /COUNT:variable.
  426.           + SET ATTRIBUTE RECORD-FORMAT { OFF, ON }.
  427.           + Bug fixes.
  428.  
  429.    C-Kermit 8.0.200 Beta.03 (9 Sep 2001)
  430.  
  431.           + [153]HTTP 1.1 connections and scripting
  432.           + [154]ON_CTRLC macro for trapping Ctrl-C in scripts
  433.           + [155]Date-time parsing improvements, timezones, comparison,
  434.             arithmetic
  435.           + [156]Pattern-matching improvements
  436.           + FTP improvements
  437.           + SET EXIT HANGUP { ON, OFF }
  438.           + SET FILE EOF { CTRL-Z, LENGTH }
  439.           + ASK[Q] /TIMEOUT
  440.           + Bug fixes
  441.           + New platforms
  442.  
  443.    C-Kermit 8.0.200 Beta.04 (16 Nov 2001)
  444.  
  445.           + [157]New Unix man page
  446.           + [158]New Unix installation instructions
  447.           + SET TELOPT policies are now enforced on non-Telnet ports if
  448.             the server begins Telnet negotiations.
  449.           + SET TERMINAL IDLE-ACTION { TELNET-NOP, TELNET-AYT }.
  450.           + UUCP lockfile creation race condition fixed.
  451.           + Dialout, modem signals, hangup, hardware flow control, etc,
  452.             tested extensively on many platforms, numerous problems fixed.
  453.           + Improved hints when dialing fails.
  454.           + SET STOP-BITS 2 can now be given without SET FLOW HARDWARE.
  455.           + Major improvements in RFC 2217 Telnet Com-Port Control.
  456.           + Improved ability to REDIAL a modem server port.
  457.           + kermit -h now shows the command name in the usage usage
  458.             string.
  459.           + kermit -h now shows ALL command-line options.
  460.           + kermit -s blah, where blah is a symlink, now works.
  461.           + --noperms command-line option = SET ATTRIBUTE PERMISSIONS OFF.
  462.           + HTTP and HTTPS URLs now supported on the command line.
  463.           + An http command-line personality is now available.
  464.           + Initialization file streamlined to load faster, anachronisms
  465.             removed.
  466.           + Updated NEWS, INTRO, HELP text, SHOW commands. In particular,
  467.             see SHOW COMM, HELP SET LINE, HELP WAIT.
  468.           + Date/time arithmetic routines converted from floating-point to
  469.             integer arithmetic (internally) for greater accuracy and
  470.             portability.
  471.           + Quoted strings containing commas no longer break macro
  472.             execution.
  473.           + Dynamic Kermit file-transfer timeouts are now much more
  474.             aggressive.
  475.           + New "hot keys" to turn debug.log on/off during file transfer.
  476.           + Improved hints when file transfer fails.
  477.           + FTP CD orientation messages are now printed.
  478.           + -R now accepted on the FTP command line to request Recursion.
  479.           + -m allows Active or Passive mode to be chosen on the FTP
  480.             command line.
  481.           + -dd on the FTP command line creates a timestamped debug.log.
  482.           + FTP command-line security options filled in.
  483.           + Improved automatic text/binary mode switching for MGET.
  484.           + Removed spurious error messages that sometimes occur during
  485.             MGET.
  486.           + DIRECTORY, GREP, TYPE, HEAD, and TAIL now have a /OUTPUT:file
  487.             option.
  488.           + TYPE /NUMBER adds line numbers.
  489.           + CAT = TYPE /NOPAGE; MORE = TYPE /PAGE.
  490.           + GETOK ?-help fixed.
  491.           + \v(timestamp) (= "\v(ndate) \v(time)")
  492.           + \v(hour) (hour of the day, 0-23)
  493.           + \funix2dospath() converts a UNIX path (/) to a DOS one (\).
  494.           + \fdos2unixpath() converts a DOS (Windows, OS/2) path to a UNIX
  495.             one.
  496.           + \fkeywordval() parses name=value pair, allows macro keyword
  497.             parameters.
  498.           + We now make every attempt to not write passwords to the
  499.             debug.log.
  500.           + New Certificate Authority certificates file, includes the
  501.             Kermit Project at Columbia University so you can access our
  502.             IKSD securely.
  503.           + Secure targets improved and better documented in Unix
  504.             makefile.
  505.           + All Linux (libc and glibc) builds consolidated under "make
  506.             linux".
  507.           + HP-UX makefile targets now have consistent names.
  508.           + New aix50 and aix51 targets added.
  509.  
  510.    C-Kermit 8.0.200 Final (12 Dec 2001)
  511.  
  512.           + Remote/local-mode confusion on some platforms introduced in
  513.             Beta.04, fixed.
  514.           + Many of the makefile targets adjusted, new ones added.
  515.           + New "make install" target should please most people.
  516.           + New command: SHOW IKSD.
  517.           + FTP over TLS.
  518.           + Last-minute touchups to text messages, HELP text, etc.
  519.           + Enable modem-signal reading for SCO OSR5 and Unixware 7.
  520.           + Special superfast TRANSMIT /BINARY /NOECHO /NOWAIT mode added.
  521.           + Fixed PBX dialing in unmarked-area-code case.
  522.           + Improved SHOW COMMUNICATIONS tells lockfile directory, typical
  523.             dialout device name.
  524.           + Some FTP OPEN command parsing problems fixed.
  525.           + Some errors in date arithmetic fixed.
  526.           + New command: SET TERMINAL AUTODOWNLOAD { ..., ERROR { STOP,
  527.             CONTINUE } }
  528.           + New command: HELP FIREWALL.
  529.           + SET MODEM HANGUP-METHOD DTR added as synonym for RS232-SIGNAL
  530.           + Support for secure URL protocols added: telnets:, ftps:,
  531.             https:.
  532.  
  533.    C-Kermit 8.0.201 (8 Feb 2002)
  534.  
  535.           + Installability as an [159]SSH v2 Subsystem.
  536.           + [160]SET LOCUS command.
  537.           + [161]L-versions of CD, DIR, DELETE, MKDIR, etc, to force local
  538.             execution.
  539.           + [162]USER and ACCOUNT added as synonyms for FTP USER and FTP
  540.             ACCOUNT.
  541.           + [163]SHOW VARIABLES now accepts a list of variables.
  542.           + Rudimentary support for [164]Caller ID when receiving phone
  543.             calls.
  544.           + Up/Down [165]Arrow-key navigation of command history buffer.
  545.           + [166]Automatic execution of customization file if init file is
  546.             missing.
  547.  
  548.    C-Kermit 8.0.206 Beta.01 (11 Oct 2002)
  549.  
  550.         New commands:
  551.  
  552.                o ORIENTATION lists location-related variables and their
  553.                  values.
  554.                o KCD changes to special directories by their symbolic
  555.                  names ("kcd ?" for a list).
  556.                o SET CD HOME path to specify home directory for CD and KCD
  557.                  commands.
  558.                o CONTINUE given at top level is equivalent to END -- handy
  559.                  when PROMPT'ed out of a script, to continue the script.
  560.  
  561.         New switches or operands for existing commands:
  562.  
  563.                o GETOK /TIMEOUT
  564.                o ASK, ASKQ, GETOK /QUIET (suppresses error message on
  565.                  timeout)
  566.                o COPY /APPEND now allows concatenating multiple source
  567.                  files into one dest file.
  568.                o SET TCP { HTTP-PROXY, SOCKS-SERVER } /USER, /PASSWORD.
  569.                o DIRECTORY command now accepts multiple filespecs, e.g.
  570.                  "dir a b c".
  571.  
  572.         SET QUIET ON now also applies to:
  573.  
  574.                o SET HOST connection progress messages.
  575.                o "Press the X or E key to cancel" file-transfer message.
  576.                o REMOTE CD response.
  577.                o REMOTE LOGIN response.
  578.  
  579.         Improvements and new features:
  580.  
  581.                o Numerous FTP client fixes and new features, listed below.
  582.                o C-Kermit, when in remote mode at the end of a file
  583.                  transfer, now prints a one-line "where" message. Control
  584.                  with SET TRANSFER REPORT.
  585.                o Unix makefile "install" target now creates an UNINSTALL
  586.                  script.
  587.                o Improved operation and performance on RFC 2217 Telnet
  588.                  connections.
  589.                o Improved CONNECT (interactive terminal connection)
  590.                  performance.
  591.                o HELP text updated for many commands.
  592.  
  593.         New or fixed makefile targets:
  594.  
  595.                o Solaris 9 (several variations)
  596.                o Concurrent PowerMAX
  597.                o Mac OS X 10.2
  598.                o FreeBSD 1.0
  599.                o FreeBSD 4.6, 5.0
  600.                o AIX 5.2, 5.3
  601.  
  602.         Bugs fixed (general):
  603.  
  604.                o Failure to run in VMS Batch fixed.
  605.                o LDIRECTORY fixed to run Kermit's built-in DIRECTORY
  606.                  command rather than an external one.
  607.                o Fixed Solaris and other SVORPOSIX builds to find out
  608.                  their full hostnames rather than just the "uname -n"
  609.                  name.
  610.                o Fixed some problems matching strings that start with ".".
  611.                o Fixed some problems matching pattern that contain {a,b,c}
  612.                  lists.
  613.                o Fixed erroneous reporting of text-mode reception as
  614.                  binary when sender did not report the file size (cosmetic
  615.                  only).
  616.                o Many problems with SWITCH statements fixed.
  617.                o Fixed SET OPTIONS DIRECTORY /DOTFILES to work for server
  618.                  too.
  619.                o Fixed DELETE to print an error message if the file was
  620.                  not found.
  621.                o Fixed SET CONTROL UNPREFIX ALL and SET PREFIXING NONE to
  622.                  do the same thing.
  623.                o Fixed bugs executing macros from within the ON_EXIT
  624.                  macro.
  625.                o \fday() and \fnday() fixed for dates prior to 17 Nov
  626.                  1858.
  627.                o Serial speed-changing bug in Linux fixed.
  628.                o "Unbalanced braces" script parsing errors when using
  629.                  \{number} fixed.
  630.                o "if defined \v(name)" fixed to behave as described in the
  631.                  book.
  632.                o Fixed Problems caused by LOCAL variables whose names are
  633.                  left substrings of macro names.
  634.                o The INPUT command was fixed to honor the PARITY setting.
  635.                o Fixed bug with COPY to existing file that is longer than
  636.                  source file.
  637.                o REINPUT command failed to strip braces/quotes around its
  638.                  target string.
  639.                o Network directory lookups didn't work for SSH
  640.                  connections.
  641.                o REMOTE SET { FILE, TRANSFER } CHARACTER-SET fixed.
  642.                o Closed some holes whereby an incompletely received file
  643.                  was not deleted when SET FILE INCOMPLETE is DISCARD, e.g.
  644.                  when the Kermit is hung up upon.
  645.                o SET XFER CHARACTER-SET TRANSPARENT fixed to do the same
  646.                  as SET XFER TRANSLATION OFF.
  647.                o SET HOST PTY (e.g. SSH) connection fixed to pass along
  648.                  window-size changes.
  649.                o C-Kermit search path for TAKE files was accidentally
  650.                  disabled.
  651.  
  652.         FTP client bugs fixed:
  653.  
  654.                o Character set translation was broken on little-endian
  655.                  (e.g. PC) architectures.
  656.                o FTP PUT /SERVER-RENAME:, /RENAME-TO:, /MOVE-TO: switches
  657.                  were sticky.
  658.                o Make SET TRANSFER MODE MANUAL apply to FTP.
  659.                o Make SET FILE INCOMPLETE { KEEP, DISCARD } apply to FTP.
  660.                o FTP MGET /UPDATE handled equal times incorrectly.
  661.                o FTP MGET /RECOVER fixed to ignore file dates, use only
  662.                  size.
  663.                o FTP MGET /RECOVER sometimes downloaded files it didn't
  664.                  need to.
  665.                o FTP downloads with TRANSFER DISPLAY BRIEF could give
  666.                  misleading error messages.
  667.                o FTP MGET temp file not deleted if FTP DEBUG set to OFF
  668.                  after it was ON.
  669.                o LOCUS not switched back when FTP connection is lost.
  670.                o Set incoming file date even if it was not completely
  671.                  received.
  672.                o FTP MGET sent SIZE and MDTM commands even when it didn't
  673.                  have to.
  674.                o FTP MGET sent SIZE and MDTM commands even when it knew
  675.                  they wouldn't work.
  676.                o FTP MGET failed if no files were selected for download.
  677.                o FTP MGET a* b* c* would fail to get any c*'s if no b*'s
  678.                  existed.
  679.                o Big problems canceling MGET with Ctrl-C.
  680.                o Some extraneous LOCUS dialogs squelched.
  681.                o Some inconsistencies in SET FTP FILENAMES AUTO fixed.
  682.                o Fixed file-descriptor pileup after multiple MGETs when
  683.                  using mkstemp().
  684.                o Fixed "mget foo", where foo is a directory name.
  685.  
  686.         FTP improvements:
  687.  
  688.                o New [167]FTP protocol features added (FEAT, MLSD).
  689.                o FTP MGET /RECURSIVE now works as expected if server
  690.                  supports MLSD.
  691.                o FTP MGET /DATES-DIFFER to download if local and remote
  692.                  file dates differ.
  693.                o FTP DATES default changed to ON.
  694.                o FTP MPUT, MGET /EXCEPT now allows up to 64 patterns (up
  695.                  from 8).
  696.                o Top-level SITE and PASSIVE commands added for
  697.                  convenience.
  698.                o MGET /COLLISION:APPEND /AS-NAME:newfile *.* puts all
  699.                  remote files into one local file.
  700.                o SET FTP SERVER-TIME-OFFSET for when server has wrong
  701.                  timezone set.
  702.                o Allow for alternative server interpretations of [M]MPUT
  703.                  /UNIQUE.
  704.                o SET FTP ANONYMOUS-PASSWORD lets you specify the default
  705.                  anonymous password.
  706.                o Allow "GET /RECURSIVE path/file" to force local
  707.                  subdirectory creation.
  708.                o SET FTP DISPLAY is like SET TRANSFER DISPLAY but applies
  709.                  only to FTP.
  710.                o FTP { ENABLE, DISABLE } new-protocol-feature-name.
  711.                o FTP MGET /NODOTFILES.
  712.                o Debug log now records FTP commands and responses in
  713.                  grep-able format.
  714.  
  715.    [ [168]Top ] [ [169]Contents ] [ [170]C-Kermit ] [ [171]Kermit Home ]
  716.  
  717. 1. FIXES SINCE VERSION 7.0.196 First, the changes from 7.0.196 to 7.0.197...
  718. Source and makefile tweaks to get successful builds on platforms that were
  719. not available in time for the 7.0 release:
  720.  
  721.      * 4.2BSD
  722.      * 4.3BSD
  723.      * AIX 4.3
  724.      * AT&T 3B2 and 3B20
  725.      * BeOS 4.5
  726.      * CLIX
  727.      * Interactive UNIX System V/386 R3.2 V4.1.1
  728.      * OS-9/68000
  729.      * OSF/1 1.3.
  730.      * PS/2 AIX 1.2.1
  731.      * SCO OSR5.0.x
  732.      * SCO Xenix 2.3.4
  733.      * SINIX 5.41/Intel
  734.      * Stratus FTX
  735.      * Stratus VOS
  736.      * SunOS 4.1 with X.25
  737.      * Ultrix 4.2
  738.      * Unixware 2.0
  739.  
  740.    There were no functional changes from 196 to 197.
  741.  
  742.    Fixes applied after C-Kermit 7.0.197 was released:
  743.  
  744.    Source code: Big flexelint and "gcc -Wall" audit and cleanup.
  745.  
  746.    Configuration:
  747.      * Solaris RTS/CTS (hardware flow control) didn't work.
  748.      * BSDI RTS/CTS worked only in one direction.
  749.      * FreeBSD 4.0 with ncurses 5.0 broke interactive command parsing.
  750.      * QNX-32 build lacked -DBIGBUFOK so couldn't execute big macros.
  751.  
  752.    Connections:
  753.      * SET HOST /PTY didn't work on some platforms.
  754.      * Broken SET HOST /USER:xxx /PASSWORD:yyy /ACCOUNT:zzz switches
  755.        fixed.
  756.      * Transparent printing was broken in Unix.
  757.      * ANSWER 0 (wait forever) didn't work.
  758.      * Some problems in Multitech modem command strings.
  759.      * Spurious "?Sorry, can't condition console terminal" errors.
  760.      * Disabling modem command strings by setting them to nothing broke
  761.        dialing.
  762.      * SET DIAL TIMEOUT value was usually ignored.
  763.      * SET DIAL METHOD PULSE didn't work.
  764.      * Certain modem commands, if changed, not refreshed if modem type
  765.        changed.
  766.      * SET SESSION-LOG command was missing from VMS.
  767.      * VMS session log format fixed for scripts.
  768.      * HANGUP by dropping DTR didn't work in NetBSD.
  769.      * SET FLOW /AUTO versus SET FLOW confusion fixed.
  770.      * Spurious secondary Solaris lockfile removed.
  771.      * SCO OSR5 DTR On/Off hangup.
  772.      * UUCP lockfile race condition.
  773.  
  774.    Commands and scripts:
  775.      * Missing CAUTIOUS and FAST commands restored.
  776.      * Broken PTY command in late-model Linuxes fixed (API changed).
  777.      * Fixed off-by-one error in command recall when switching direction.
  778.      * Fixed recall of commands that contain '?'.
  779.      * COPY /SWAP-BYTES didn't work on some architectures.
  780.      * Various combinations of COPY switches didn't work.
  781.      * Various problems with COPY or RENAME with a directory name as
  782.        target.
  783.      * SHIFT didn't decrement \v(argc) if used within IF, ELSE, or SWITCH
  784.        block.
  785.      * SHIFT didn't affect the \%* variable.
  786.      * Divide by zero improperly handled in some \function()s.
  787.      * Problems with RETURN from right-recursive functions.
  788.      * FSEEK /LINE \%c LAST didn't work if already at end.
  789.      * Some buffer vulnerabilities and potential memory leaks were
  790.        discovered and fixed.
  791.      * \frdirectory() fixed not to follow symbolic links.
  792.      * SET EXIT WARNING OFF fixed to work when EXIT given in a script.
  793.      * Missing DELETE and MKDIR error message fixed.
  794.      * \fday() core dump for ancient dates fixed.
  795.  
  796.    File transfer:
  797.      * SEND /COMMAND was broken.
  798.      * CRECEIVE was broken (but RECEIVE /COMMAND was OK).
  799.      * Quoting wildcard chars in filenames didn't work.
  800.      * Problems canceling streaming file transfers with X or Z.
  801.      * Problems shifting between streaming and windowing file transfer.
  802.      * Non-FULL file-transfer displays erroneously said STREAMING when
  803.        not.
  804.      * An active SEND-LIST prevented GET from working.
  805.      * SET SERVER GET-PATH interpretation of relative names like "." was
  806.        wrong.
  807.      * The MAIL command was broken.
  808.      * "kermit -s *" might have skipped some files.
  809.      * Transaction log entries were not made for external protocol
  810.        transfers.
  811.      * File count report fixed to show number of files actually
  812.        transferred.
  813.      * Fixed filename conversion to convert spaces to underscores.
  814.      * Made SET PREFIXING / SET CONTROL PREFIX also adjust CLEARCHANNEL.
  815.      * More "Receive window full" errors fixed.
  816.      * Broken terminal buffering after curses display in Solaris fixed.
  817.      * SET FILE INCOMPLETE DISCARD did not work in all cases.
  818.      * Packet log changed to reformat the start-of-packet character
  819.        printably.
  820.      * Dynamic timeouts could grow ridiculously large.
  821.  
  822.    Character sets:
  823.      * Hebrew-7 translations missed the letter Tav.
  824.      * C1 area of CP1252 was ignored.
  825.      * SET TRANSFER CHARACTER-SET TRANSPARENT could give garbage
  826.        translations.
  827.      * TRANSLATE might not work on Little Endian architectures.
  828.      * Insufficient range checking in certain TRANSLATE operations.
  829.  
  830.    The following bugs in C-Kermit 8.0.200 were fixed in 8.0.201:
  831.  
  832.      * An obscure path through the code could cause the Unix version of
  833.        C-Kermit to dump core during its startup sequence. This happened to
  834.        only one person, but now it's fixed.
  835.      * When C-Kermit 8.0 is in Kermit server mode and the client says "get
  836.        blah", where blah (on the server) is a symlink rather than a real
  837.        file, the server unreasonably refused to send the linked-to file.
  838.      * When C-Kermit is an FTP client and says "get foo/bar" (i.e. a
  839.        filename that includes one or more path segments), it failed to
  840.        accept the incoming file (this happened only with GET, not MGET).
  841.      * Array references should be case insensitive but only lowercase
  842.        array letters were accepted.
  843.      * SHOW VARIABLES dumped core on \v(sexpression) and \v(svalue).
  844.      * Spurious refusals of remote directory listings if the remote
  845.        server's date was set in the past.
  846.      * In AIX, and maybe elsewhere too, Kermit's COPY command always
  847.        failed with "Source and destination are the same file" when the
  848.        destination file didn't exist.
  849.      * The VMS version of C-Kermit did not work in Batch or when SPAWN'd.
  850.        To compound the problem, it also pretty much ignored the -B and -z
  851.        command-line options, whose purpose is to work around such
  852.        problems.
  853.      * C-Kermit 8.0 could not be built on IRIX 5.x.
  854.      * The C-Kermit 8.0 build for QNX6 said it was an "(unknown version)".
  855.  
  856.    Other fixes are listed in the [172]previous section.
  857.  
  858.    [ [173]Top ] [ [174]Contents ] [ [175]C-Kermit ] [ [176]Kermit Home ]
  859.  
  860. 2. SSH AND HTTP
  861.  
  862. 2.1. SSH Connections
  863.  
  864.      This section does not apply to [177]Kermit 95 2.0, which has its own
  865.      built-in SSH client, which is documented [178]SEPARATELY.
  866.  
  867.    On most UNIX platforms, C-Kermit can make SSH (Secure SHell) connection
  868.    by running the external SSH command or program through its
  869.    pseudoterminal interface. The command is:
  870.  
  871.    SSH text
  872.           Tells Kermit to start the external SSH client, passing the given
  873.           text to it on the command line. Normally the text is just the
  874.           hostname, but it can be anything else that is acceptable to the
  875.           ssh client. If the command succeeds, the connection is made and
  876.           Kermit automatically enters CONNECT (terminal) mode. You can use
  877.           the SSH command to make a connection to any host that has an SSH
  878.           server.
  879.  
  880.    Kermit's SSH command gives you all the features of Kermit on an SSH
  881.    connection: command language, file transfer, character-set translation,
  882.    scripting, and all the rest. By default, C-Kermit invokes SSH with "-e
  883.    none", which disables the ssh escape character and makes the connection
  884.    transparent for purposes of file transfer. You can, however, change the
  885.    SSH invocation to whatever else you might need (an explicit path,
  886.    additional command-line arguments, etc) with:
  887.  
  888.    SET SSH COMMAND text
  889.           Specifies the system command that Kermit's SSH command should
  890.           use to invoke the external SSH client. Use this command to
  891.           supply a specific path or alternative name, or to include
  892.           different or more command-line options.
  893.  
  894.    In most cases, these connections work quite well. They can be scripted
  895.    like any other connection, and file transfer goes as fast as, or faster
  896.    than, on a regular Telnet connection. In some cases, however, the
  897.    underlying pseudoterminal driver is a limiting factor, resulting in
  898.    slow or failed file transfers. Sometimes you can work around such
  899.    problems by reducing the Kermit packet length. Note that Kermit does
  900.    not consider SSH connections to be reliable, so it does not offer to
  901.    use streaming in Kermit protocol transfers (but you can force it with
  902.    SET RELIABLE or SET STREAMING if you wish).
  903.  
  904.    The SSH command is like the TELNET command: it enters CONNECT mode
  905.    automatically when the connection is made. Therefore, to script an SSH
  906.    connection, use:
  907.  
  908.   set host /pty ssh -e none [ other-options ] host
  909.   if fail ...
  910.  
  911.    to make the connection.
  912.  
  913.    Here's a sequence that can be used to make a connection to a given host
  914.    using Telnet if the host accepts it, otherwise SSH:
  915.  
  916.   if not defined \%1 exit 1 Usage: \%0 host
  917.   set quiet on
  918.   set host \%1 23 /telnet
  919.   if fail {
  920.       set host /pty ssh -l \m(user) -e none \%1
  921.       if fail exit 1 \%1: Telnet and SSH both fail
  922.       echo SSH connection to \%1 successful
  923.   } else {
  924.       echo Telnet connection to \%1 successful
  925.   }
  926.  
  927.    In SSH v2, it is possible to make an SSH connection direct to a Kermit
  928.    server system if the host administrator has configured the SSH server
  929.    to allow this; [179]CLICK HERE for details.
  930.  
  931.    Since Kermit uses external ssh client software, and since there are
  932.    different ssh clients (and different releases of each one), the exact
  933.    command to be used to make an SSH/Kermit connection can vary. Here is
  934.    the command for the OpenSSH 3.0.2p1 client:
  935.  
  936. set host /pipe ssh -e none [ -l username ] -T -s hostname kermit
  937.  
  938.    Example:
  939.  
  940. set host /pipe ssh -e none -l olga -T -s hq.xyzcorp.com kermit
  941.  
  942.    The SSH client might or might not prompt you for a password or other
  943.    information before it makes the connection; this depends on your SSH
  944.    configuration (your public and private keys, your authorized hosts
  945.    file, etc). Here's a brief synopsis of the OpenSSH client command
  946.    syntax ("man ssh" for details):
  947.  
  948.    -e none
  949.           This tells the SSH client to use no escape character. Since we
  950.           will be transferring files across the connection, we don't want
  951.           the connection to suddenly block because some character in the
  952.           data.
  953.  
  954.    -l username
  955.           This is the username on the remote host. You can omit the -l
  956.           option and its argument if your local and remote usernames are
  957.           the same. If they are different, you must supply the remote
  958.           username.
  959.  
  960.    -T
  961.           This tells the SSH client to tell the SSH server not to allocate
  962.           a pseudoterminal. We are not making a terminal connection, we
  963.           don't need a terminal, and in fact if a terminal were allocated
  964.           on the remote end, the connection would not work.
  965.  
  966.    -s ... kermit
  967.           This tells the SSH client to tell the SSH server to start the
  968.           specified subsystem ("kermit") once the connection is made. The
  969.           subsystem name comes after the hostname.
  970.  
  971.    hostname
  972.           The IP host name or address of the desired host.
  973.  
  974.    You might want to include other or additional ssh command-line options;
  975.    "man ssh" explains what they are. Here are some examples for the
  976.    OpenSSH 3.0.2p1 client:
  977.  
  978.    -oClearAllForwardings yes
  979.    -oForwardAgent no
  980.    -oForwardX11 no
  981.    -oFallbackToRsh no
  982.           These ensure that a secure connection is used and that the
  983.           connection used for file transfer is not also used for
  984.           forwarding other things that might be specified in the
  985.           ssh_config file.
  986.  
  987.    -oProtocol 2
  988.           (i.e. SSH v2) Ensures that the negotiated protocol supports
  989.           subsystems.
  990.  
  991.    Once you have an SSH connection to a Kermit server, it's just like any
  992.    other connection to a Kermit server (and very similar to a connection
  993.    to an FTP server). You give the client file transfer and management
  994.    commands for the server, and the server executes them. Of course you
  995.    can also give the client any other commands you wish.
  996.  
  997.    [ [180]SSH Kermit Server Subsystem ] [ [181]Kermit 95 Built-in SSH
  998.    Client ]
  999.  
  1000. 2.2. HTTP Connections
  1001.  
  1002.    Hypertext Transfer Protocol, or HTTP, is the application protocol of
  1003.    the World Wide Web (WWW), used between Web browsers (clients) and Web
  1004.    servers. It allows a client to get files from websites, upload files to
  1005.    websites, delete files from websites, get information about website
  1006.    directories and files, and interact with server-side CGI scripts.
  1007.    C-Kermit includes an HTTP client capable of both clear-text and secure
  1008.    HTTP connections, that can do all these tasks and can be automated
  1009.    through the Kermit scripting language.
  1010.  
  1011.    Although C-Kermit 7.0 could make HTTP connections to Web servers, it
  1012.    could do so only when no other connection was open, and the procedure
  1013.    was somewhat awkward. C-Kermit 8.0 improves matters by:
  1014.  
  1015.      * Allowing an HTTP connection to be open at the same time as a
  1016.        regular SET LINE or SET HOST connection, and also at the same time
  1017.        as an FTP connection ([182]Section 3);
  1018.      * Upgrading the HTTP protocol level from 1.0 to 1.1, thus allowing
  1019.        for persistent connections, in which a series of commands can be
  1020.        sent on the same connection, rather than only one as in HTTP 1.0
  1021.        (and C-Kermit 7.0);
  1022.      * Providing for "one-shot" URL-driven HTTP operations such as GET or
  1023.        PUT.
  1024.      * Providing a distinct HTTP command-line personality.
  1025.  
  1026.    Persistent HTTP connections are managed with the following commands:
  1027.  
  1028.    HTTP [ switches ] OPEN [ security-options ] host-or-url [ port ]
  1029.           Opens a persistent connection to the specified host (IP host
  1030.           name or address) on the specified port. If any switches
  1031.           (options, listed in the next section) are included, their values
  1032.           are saved and used for all subsequent HTTP action commands on
  1033.           the same connection. If no port is specified, HTTP (80) is used.
  1034.           A Uniform Resource Locator (URL, [183]RFC 1738) can be given
  1035.           instead of a hostname (or address) and port (but the URL can not
  1036.           include a directory/file path). The security options are
  1037.           explained [184]below. The HTTP OPEN command replaces the
  1038.           C-Kermit 7.0 SET HOST hostname HTTP command, which no longer
  1039.           works with HTTP GET and related commands.
  1040.  
  1041.    HTTP CLOSE
  1042.           Closes any open HTTP connection and clears any saved switch
  1043.           values.
  1044.  
  1045.    A URL starts with a protocol name, which must be http or https in this
  1046.    case; optionally includes a username and password; and must contain a
  1047.    host name or address:
  1048.  
  1049.   protocol://[user[.password]]@host[:port][URI]
  1050.  
  1051.    HTTP is Hypertext Transfer Protocol. HTTPS is the secure (SSL/TLS)
  1052.    version of HTTP. The TCP service port is derived from the protocol
  1053.    prefix (so normally the ":port" field is omitted). Thus the URL
  1054.    protocol name specifies a default TCP service port and the URL user and
  1055.    password fields can take the place of the /USER and /PASSWORD switches
  1056.    ([185]Section 2.2.1). The optional URI is a "compact string of
  1057.    characters for identifying an abstract or physical resource" ([186]RFC
  1058.    2396), such as a file. It must begin with a slash (/); if the URI is
  1059.    omitted, "/" is supplied. Examples:
  1060.  
  1061.    http open http://www.columbia.edu/
  1062.           Equivalent to http open www.columbia.edu or http open
  1063.           www.columbia.edu http.
  1064.  
  1065.    http open https://olga.secret@www1.xyzcorp.com/
  1066.           Equivalent to http /user:olga /pass:secret open www1.xyzcorp.com
  1067.           https.
  1068.  
  1069.    Persistence is accomplished unilaterally by C-Kermit 8.0. An HTTP 1.0
  1070.    server closes the connection after each action. Although HTTP 1.1
  1071.    allows multiple actions on the same connection, an HTTP 1.1 server
  1072.    tends to close the connection if it is idle for more than a few
  1073.    seconds, to defend itself against denial-of-service attacks. But when
  1074.    you use Kermit's HTTP OPEN command to create a connection, Kermit
  1075.    reopens it automatically (if necessary) for each HTTP action until you
  1076.    close it with HTTP CLOSE, regardless of the server's HTTP protocol
  1077.    version, or how many times it closes the connection.
  1078.  
  1079.    Firewalls can be negotiated through proxies with the following
  1080.    commands:
  1081.  
  1082.    SET TCP HTTP-PROXY [ host[:port] ]
  1083.           If a host (by hostname or IP address) is specified, Kermit uses
  1084.           it as a proxy server when attempting outgoing TCP connections --
  1085.           not only HTTP connections, but all TCP/IP connections, Telnet
  1086.           and FTP included. This allows Kermit to adapt to the HTTP
  1087.           firewall penetration method (as opposed to other methods such as
  1088.           SOCKS4). If no hostname or ip-address is specified, any
  1089.           previously specified Proxy server is removed. If no port number
  1090.           is specified, the "http" service is used. This command must be
  1091.           given before the HTTP OPEN command if a proxy is to be used or
  1092.           canceled.
  1093.  
  1094.    HTTP [ switches ] CONNECT host[:port]
  1095.           Instructs the HTTP server to act as a proxy, establishing a
  1096.           connection to the specified host (IP hostname or address) on the
  1097.           given port (80 = HTTP by default) and to redirect all data
  1098.           transmitted between Kermit and itself to the given host for the
  1099.           life of the connection. This command is to be used only for
  1100.           debugging HTTP proxy connections. If a proxy connection is
  1101.           required, instruct Kermit to use the proxy with the SET TCP
  1102.           HTTP-PROXY command.
  1103.  
  1104. 2.2.1. HTTP Command Switches
  1105.  
  1106.    HTTP switches, like all other switches, are optional. When HTTP
  1107.    switches are included with the HTTP OPEN command, they apply
  1108.    automatically to this and all subsequent HTTP actions (GET, PUT, ...)
  1109.    on the same connection until an HTTP CLOSE command is given. So if you
  1110.    include switches (or the equivalent URL fields, such as user and
  1111.    password) in the HTTP OPEN command, you can omit them from subsequent
  1112.    commands on the same connection. If the connection has closed since
  1113.    your last command, it is automatically reopened with the same options.
  1114.  
  1115.    If you include switches with an HTTP action command (such as GET or
  1116.    PUT), they apply only to that command.
  1117.  
  1118.    /USER:name
  1119.           To be used in case a page requires a username for access. The
  1120.           username is sent with page requests. If it is given with the
  1121.           OPEN command it is saved until needed. If a username is included
  1122.           in a URL, it overrides the username given in the switch.
  1123.           CAUTION: Username and password (and all other information,
  1124.           including credit card numbers and other material that you might
  1125.           prefer to protect from public view) are sent across the network
  1126.           in clear text on regular HTTP connections, but authentication is
  1127.           performed securely on HTTPS connections.
  1128.  
  1129.    /PASSWORD:text
  1130.           To be used in case a web page requires a password for access.
  1131.           The password is sent with page requests. If it is given with the
  1132.           OPEN command it is saved until needed. If a password is given in
  1133.           a URL, it overrides the one given here. CAUTION: (same as for
  1134.           /USER:).
  1135.  
  1136.    /AGENT:user-agent
  1137.           Identifies the client to the server. Overrides the default agent
  1138.           string, which is "C-Kermit" (for C-Kermit) or "Kermit-95" (for
  1139.           Kermit 95).
  1140.  
  1141.    /ARRAY:array-designator
  1142.           Tells Kermit to store the response headers in the given array,
  1143.           one line per element. The array need not be declared in advance.
  1144.           Example: /array:&a.
  1145.  
  1146.    /TOSCREEN
  1147.           Tells Kermit to display any response text on the screen. It
  1148.           applies independently of the output file specification; thus it
  1149.           is possible to have the server response go to the screen, a
  1150.           file, both, or neither.
  1151.  
  1152.    /HEADER:header-item(s)
  1153.           Used for specifying any optional headers to be sent with HTTP
  1154.           requests.
  1155.  
  1156.   /HEADER:tag:value
  1157.  
  1158.           To send more than one header, use braces for grouping:
  1159.  
  1160.   /HEADER:{{tag:value}{tag:value}...}
  1161.  
  1162.           For a list of valid tags and value formats see [187]RFC 2616,
  1163.           "Hypertext Transfer Protocol -- HTTP/1.1". A maximum of eight
  1164.           headers may be specified.
  1165.  
  1166. 2.2.2. HTTP Action Commands
  1167.  
  1168.    HTTP actions can occur within a persistent connection, or they can be
  1169.    self-contained ("connectionless"). A persistent HTTP connection begins
  1170.    with an HTTP OPEN command, followed by zero or more HTTP action
  1171.    commands, and is terminated with an HTTP CLOSE command:
  1172.  
  1173.   http open www.columbia.edu
  1174.   if failure stop 1 HTTP OPEN failed: \v(http_message)
  1175.   http get kermit/index.html
  1176.   if failure stop 1 HTTP GET failed: \v(http_message)
  1177.   (more actions possible here...)
  1178.   http close
  1179.  
  1180.    A self-contained HTTP action occurs when a URL is given instead of a
  1181.    remote file name to an HTTP action command. In this case, Kermit makes
  1182.    the HTTP connection, takes the action, and then closes the connection.
  1183.    If an HTTP connection was already open, it is closed silently and
  1184.    automatically.
  1185.  
  1186.   http get http://www.columbia.edu/kermit/index.html
  1187.  
  1188.    Kermit's HTTP action commands are as follows. Switches may be included
  1189.    with any of these to override switch (or default) values given in the
  1190.    HTTP OPEN command.
  1191.  
  1192.    HTTP [ switches ] GET remote-filename [ local-filename ]
  1193.           Retrieves the named file from the server specified in the most
  1194.           recent HTTP OPEN command for which a corresponding HTTP CLOSE
  1195.           command has not been given. The filename may not include
  1196.           wildcards (HTTP protocol does not support them). If no HTTP OPEN
  1197.           command is in effect, this form of the HTTP GET command fails.
  1198.           The default local filename is the same as the remote name, but
  1199.           with any pathname stripped. For example, the command http get
  1200.           kermit/index.html stores the file in the current local directory
  1201.           as index.html. If the /HEADERS: switch is included, information
  1202.           about the file is also stored in the specified array (explained
  1203.           in [188]Section 2.2.3). All files are transferred in binary
  1204.           mode. HTTP does not provide for record-format or character-set
  1205.           conversion.
  1206.  
  1207.    HTTP [ switches ] GET url [ local-filename ]
  1208.           When HTTP GET is given a URL rather than a filename, Kermit
  1209.           opens a connection to the designated server (closing any
  1210.           previously open HTTP connection), gets the file, and then closes
  1211.           the connection. If the URL does not include a filename,
  1212.           index.html is supplied. This is the self-contained one-step
  1213.           "connectionless" method for getting a file from a Web server.
  1214.           The data is not interpreted; HTTP GET is like "lynx -source"
  1215.           rather than "lynx -dump".
  1216.  
  1217.    In the remaining HTTP action commands, the distinction between a remote
  1218.    filename and a URL are the same as in the HTTP GET command.
  1219.  
  1220.    HTTP [ switches ] HEAD remote-filename-or-url [ local-filename ]
  1221.           Like GET except without actually getting the file; instead it
  1222.           retrieves only the headers. If the /ARRAY: or /TOSCREEN switch
  1223.           is included, there is no default local output filename but you
  1224.           can still specify one. If neither of these switches is included,
  1225.           the default local filename is the same as the remote filename,
  1226.           but with any path stripped and with ".head" appended. The HEAD
  1227.           command can be used in a script with the /ARRAY: switch to
  1228.           retrieve information about the requested resource to determine
  1229.           whether the resource should actually be retrieved with a
  1230.           subsequent GET request.
  1231.  
  1232.    HTTP [ switches ] INDEX remote-directory-or-url [ local-filename ]
  1233.           Asks the server to send a listing of the files in the given
  1234.           server directory. This command is not supported by most Web
  1235.           servers. Even when it is supported, there is no standard format
  1236.           for the listing.
  1237.  
  1238.    HTTP [ switches ] POST [ /MIME-TYPE:type ] source-file
  1239.           remote-path-or-url [ result-file ]
  1240.           Sends data to a process running on the remote host; the result
  1241.           is usually an HTML file but could be anything. The data to be
  1242.           posted must be read from a local file (the source-file). If a
  1243.           result file is specified, Kermit stores the server's response in
  1244.           it.
  1245.  
  1246.    HTTP [ switches ] PUT [ MIME-TYPE:type ] local-file [
  1247.           remote-file-or-url [ result-file ] ]
  1248.           Uploads a local file to the server. Only the name of a single
  1249.           file can be given; wildcards (and group transfers) are not
  1250.           supported by HTTP protocol. If no remote filename is given, the
  1251.           file is sent with the same name as the local file, but with any
  1252.           pathname stripped.
  1253.  
  1254.    HTTP [ switches ] DELETE remote-file-or-url [ local-result-file ]
  1255.           Asks the server to delete the specified single file. If a result
  1256.           file is specified, it will contain any response data returned by
  1257.           the server.
  1258.  
  1259.    Note the limitations of HTTP protocol compared to (say) FTP or Kermit.
  1260.    There is no command for changing directories, no standard way to get
  1261.    file or directory lists, no way to transfer file groups by using
  1262.    wildcard notation, etc, and therefore no good way to (say) fetch all
  1263.    pages, descend through subdirectories, perform automatic updates, etc.
  1264.    There is no assurance a connection will stay open and, as noted, there
  1265.    is no provision for data conversion between unlike platforms. The
  1266.    data's MIME headers can be used for postprocessing.
  1267.  
  1268. 2.2.3. HTTP Headers
  1269.  
  1270.    Each HTTP request and response contains a set of name/value pairs
  1271.    called headers. HTTP headers are specified in [189]RFC 2616. For
  1272.    example, an HTTP GET request for /index.html on www.columbia.edu
  1273.    contains the following headers:
  1274.  
  1275.   GET /index.html HTTP/1.1
  1276.   Host: www.columbia.edu:80
  1277.   User-agent: C-Kermit 8.0
  1278.   Authorization: Basic base64-encoded-username-password
  1279.  
  1280.    These might be followed by any others specified with a /HEADERS:
  1281.    switch:
  1282.  
  1283.   Accept: image/gif, image/x-xbitmap, image/jpeg, *.*
  1284.   Accept-Encoding: gzip
  1285.   Accept-Language: en
  1286.   Accept-Charset: iso-8859-1,utf-8
  1287.   Cookie: cookie-data
  1288.  
  1289.    The server sends back a short report about the file prior to sending
  1290.    the file contents. Example:
  1291.  
  1292.   HTTP/1.1 200 OK
  1293.   Date: Fri, 24 Aug 2001 21:09:39 GMT
  1294.   Server: Apache/1.3.4 (Unix)
  1295.   Last-Modified: Mon, 06 Aug 2001 21:16:13 GMT
  1296.   ETag: "1fa137-10d7-3b6f091d"
  1297.   Accept-Ranges: bytes
  1298.   Content-Length: 4311
  1299.   Content-Type: text/html
  1300.  
  1301.    If you want to have this information available to a Kermit script you
  1302.    can use the /ARRAY switch to have Kermit put it in array, one line per
  1303.    array element. Example:
  1304.  
  1305.   set exit warning off
  1306.   http open www.columbia.edu
  1307.   if fail exit 1 Can't reach server
  1308.   http /array:&a get /index.html
  1309.   if fail exit 1 Can't get file
  1310.   echo Header lines: \fdim(&a)
  1311.   for \%i 1 \fdim(&a) 1 {
  1312.       echo \%i. \&a[\%i]
  1313.   }
  1314.  
  1315.    Note that the "Date:" item is the current date and time; the
  1316.    "Last-Modified:" item is the file's modification date and time. An
  1317.    example showing how to use this information is presented in
  1318.    [190]Section 8.13.7.
  1319.  
  1320. 2.2.4. Secure HTTP Connections
  1321.  
  1322.    SSL/TLS (Secure Sockets Layer / Transport Layer Security) is the
  1323.    protocol used to secure HTTP, SMTP, and other Internet applications.
  1324.    See the [191]C-Kermit Reference Section 5.4 for an introduction to
  1325.    SSL/TLS. To make a secure HTTP connection, you need:
  1326.  
  1327.     1. A secure client (a version of C-Kermit or Kermit 95 with SSL/TLS
  1328.        security built in). Type "check ssl" at the Kermit prompt to make
  1329.        sure you have it.
  1330.     2. A secure server to connect to.
  1331.     3. The CA Root Certificate used to authenticate the server to the
  1332.        client. (see [192]Section 15 of the security reference for an
  1333.        introduction to certificates).
  1334.  
  1335.    And you must make a connection to the secure HTTP port: service name
  1336.    HTTPS, port number 443 (as opposed to service HTTP, port 80). You can
  1337.    also make secure connections to other ports by including the /TLS or
  1338.    /SSL switch with the HTTP OPEN command, if the host supports SSL/TLS on
  1339.    the given port:
  1340.  
  1341.    The quality of the SSL/TLS connection depends on the cipher suite.
  1342.    There are several possibilities:
  1343.  
  1344.    Anonymous cipher suite:
  1345.           If an anonymous cipher suite is negotiated, the connection is
  1346.           encrypted but there is no authentication. This connection is
  1347.           subject to a Man-In-The-Middle (MITM) attack.
  1348.  
  1349.    X.509 certificate on the server:
  1350.           When you connect to certain secure servers, an X.509 certificate
  1351.           is returned. This certificate is issued to a special hostname,
  1352.           something like www1.xyzcorp.com or wwws.xyzcorp.com (rather than
  1353.           the normal www.xyzcorp.com). It is signed by the host's
  1354.           Certificate Authority (CA). If the host certificate is
  1355.           configured on the client, it can be used to verify the
  1356.           certificate received from the server. If the certificate it
  1357.           verified as authentic, a check is made to ensure it has not
  1358.           expired and it was issued to the host you were attempting to
  1359.           connect to. If you had asked to connect to (say) www.xyzcorp.com
  1360.           but were given a certificate for www1.xyzcorp.com, you would be
  1361.           prompted for permission to continue.
  1362.  
  1363.           If the verification succeeded, the connection would be encrypted
  1364.           with one-way (server-to-client) authentication. This connection
  1365.           is not subject to a MITM attack.
  1366.  
  1367.           If a username and password are transmitted over this connection,
  1368.           they are not subject to interception. However, the standard
  1369.           risks associated with passing the password to the host for
  1370.           verification apply; for example, if the host has been
  1371.           compromised, the password will be compromised.
  1372.  
  1373.    X.509 client certificate:
  1374.           If a connection has been established with an X.509 server
  1375.           certificate, the server can ask the client to send a certificate
  1376.           of its own. This certificate must be verified against a CA Root
  1377.           certificate. The certificate itself (or subject info from the
  1378.           certificate) is used to determine the authorization for the
  1379.           client, and if successful, the username and password need not be
  1380.           sent to the server.
  1381.  
  1382.    Kerberos 5:
  1383.           Instead of using X.509 certificates, Kerberos 5 can be used to
  1384.           perform the authentication and key exchange. In this situation,
  1385.           there is mutual authentication between the client and server.
  1386.           The Kerberos 5 principal is used by the server to look up the
  1387.           appropriate authorization data. There is no need to send
  1388.           username and password.
  1389.  
  1390.    An HTTP connection is made with the HTTP OPEN command:
  1391.  
  1392.    HTTP [ switches ] OPEN [ { /SSL, /TLS } ] host [ port ]
  1393.           If /SSL or /TLS switches are included (these are synonyms), or
  1394.           if the service is HTTPS or the port is 443, a secure connection
  1395.           is attempted using the current authentication settings; see HELP
  1396.           SET AUTHENTICATION for details ([193]Section 6.2 of the security
  1397.           reference). If the no /SSL or /TLS switch is included but the
  1398.           port is 443 or the service is HTTPS, a secure connection is
  1399.           attempted. If an /SSL or /TLS switch is included but a port is
  1400.           not specified, an SSL/TLS connection is attempted on the default
  1401.           port (80).
  1402.  
  1403.    Certificates are covered in the separate [194]Kermit Security Reference
  1404.    for C-Kermit 8.0. You should let Kermit know to verify certificates
  1405.    with the SET AUTHENTICATION TLS command. For example:
  1406.  
  1407.    SET AUTHENTICATION TLS CRL-DIR directory
  1408.           Specifies a directory that contains certificate revocation files
  1409.           where each file is named by the hash of the certificate that has
  1410.           been revoked.
  1411.  
  1412.    SET AUTHENTICATION TLS CRL-FILE filename
  1413.           Specifies a file that contains a list of certificate
  1414.           revocations.
  1415.  
  1416.    SET AUTHENTICATION TLS VERIFY-DIR directory
  1417.           Specifies a directory that contains root CA certificate files
  1418.           used to verify the certificate chains presented by the peer.
  1419.           Each file is named by a hash of the certificate.
  1420.  
  1421.    SET AUTHENTICATION TLS VERIFY-FILE filename
  1422.           Specifies a file that contains root CA certificates to be used
  1423.           for verifying certificate chains.
  1424.  
  1425.    SET AUTHENTICATION TLS VERIFY OFF
  1426.           Tells Kermit not to require a certificate and accept any
  1427.           certificate that is presented regardless of whether it is valid.
  1428.  
  1429.    There are many other options; see the security document for details.
  1430.  
  1431.    Now suppose you need need to fetch the file denoted by the following
  1432.    URL:
  1433.  
  1434.   https://myuserid:mypassword@wwws.xyzcorp.com/clients/info/secret.html
  1435.  
  1436.    Once you have set up the handling of certificates as desired, you can
  1437.    use the following Kermit commands:
  1438.  
  1439.   http /user:myuserid /password:mypassword open www1.xyzcorp.com https
  1440.   if success {
  1441.       http get /clients/info/secret.html
  1442.       http close
  1443.   }
  1444.  
  1445.    As another example, let's say that you have a web form you need to
  1446.    populate with three fields: red,white and blue.
  1447.  
  1448.   <FORM ACTION="http://www.xyzcorp.com/cgi-bin/form.cgi" METHOD="POST">
  1449.   <INPUT NAME="Red">
  1450.   <INPUT NAME="White">
  1451.   <INPUT NAME="Blue">
  1452.   </FORM>
  1453.  
  1454.    You can handle this with the HTTP POST command. The data to be posted
  1455.    is stored in the local file data.txt.
  1456.  
  1457.   Red=seven stripes&White=six stripes&Blue=fifty stars
  1458.  
  1459.    and the response from the server will be stored into response.txt.
  1460.  
  1461.   http open www.xyzcorp.com http
  1462.   if success {
  1463.     http /array:c post data.txt /cgi-bin/form.cgi response.txt
  1464.     http close
  1465.   }
  1466.  
  1467.    In this scenario, the Common Gateway Interface (CGI) sends a response
  1468.    whether it succeeds or fails in a script-dependent manner. The script
  1469.    can either report success and enclose the response data; or it might
  1470.    send a 302 Found error which indicates that the "Location:" header
  1471.    should be used to determine the URL at which the data can be found.
  1472.  
  1473. 2.2.5. HTTP Variables
  1474.  
  1475.    \v(http_code)
  1476.           The HTTP protocol code number of the most recent server reply,
  1477.           e.g. 404 for "not found".
  1478.  
  1479.    \v(http_connected)
  1480.           1 when an HTTP connection is open, 0 when there is no HTTP
  1481.           connection.
  1482.  
  1483.    \v(http_host)
  1484.           If an HTTP connection is open, the hostname:port, e.g.
  1485.           www.columbia.edu:80; otherwise, empty.
  1486.  
  1487.    \v(http_message)
  1488.           Server error message, if any, from most recent HTTP command.
  1489.  
  1490.    \v(http_security)
  1491.           A list of the security parameters and values for the current
  1492.           connection, if any. Empty if the connection is not to a secure
  1493.           server, or there is no connection.
  1494.  
  1495.    To display all the HTTP variables at once, type SHOW VAR HTTP:
  1496.  
  1497.   C-Kermit> http open www.columbia.edu
  1498.   C-Kermit> http get lkjlkjlkjlkj
  1499.   C-Kermit> sho var http
  1500.    \v(http_code) = 404
  1501.    \v(http_connected) = 1
  1502.    \v(http_host) = www.columbia.edu:80
  1503.    \v(http_message) = Not Found
  1504.    \v(http_security) = NULL
  1505.   C-Kermit>
  1506.  
  1507. 2.2.6. The HTTP Command-Line Personality
  1508.  
  1509.    If you invoke C-Kermit with the name "http" or "https", you can use a
  1510.    special set of HTTP-specific command-line options. You can do this by
  1511.    creating a symbolic linke "http" or "https" to the C-Kermit 8.0
  1512.    executable, or by having a separate copy of it called "http" or
  1513.    "https". Here's the usage message ("http -h"):
  1514.  
  1515.   Usage: ./http host [ options... ]
  1516.    -h             This message.
  1517.    -d             Debug to debug.log.
  1518.    -S             Stay (issue command prompt when done).
  1519.    -Y             Do not execute Kermit initialization file.
  1520.    -q             Quiet (suppress most messages).
  1521.    -u name        Username.
  1522.    -P password    Password.
  1523.    -g pathname    Get remote pathname.
  1524.    -p pathname    Put remote pathname.
  1525.    -H pathname    Head remote pathname.
  1526.    -l pathname    Local path for -g, -p, and -H.
  1527.    -z opt[=value] Security options...
  1528.       cert=file   Client certificate file
  1529.       certsok     Accept all certificates
  1530.       key=file    Client private key file
  1531.       secure      Use SSL
  1532.       verify=n    0 = none, 1 = peer , 2 = certificate required
  1533.  
  1534.    The "host" argument is the name of a Web host, e.g. www.columbia.edu.
  1535.    The action options are -p, -g, and -H. If you give an action option,
  1536.    Kermit does the action and then exits. If you give a host without an
  1537.    action option, Kermit makes an HTTP connection to the host and then
  1538.    gives you the C-Kermit prompt. Here's a simple example that fetches a
  1539.    publicly readable Web page:
  1540.  
  1541.   http www.columbia.edu -g kermit/index.html
  1542.  
  1543.    If you need to access a website for which a username and password are
  1544.    required, you can supply them on the command line with -u and -P. If
  1545.    you include a username but omit the password, Kermit prompts you for
  1546.    it:
  1547.  
  1548.   http www.columbia.edu -u olga -p kermit/index.html -l index.html
  1549.   Password:
  1550.  
  1551.    Note that when PUT'ing files to websites, you have to supply both the
  1552.    -p (remote pathname) and -l (local path) options.
  1553.  
  1554.    If your version of Kermit is built with SSL/TLS security, you can also
  1555.    use the -z option to make secure HTTP (https) connections.
  1556.  
  1557.    Finally, as noted in [195]Section 16, you can also give a URL instead
  1558.    of a host name and options.
  1559.  
  1560.    [ [196]Top ] [ [197]Contents ] [ [198]C-Kermit Home ] [ [199]Kermit
  1561.    Home ]
  1562.  
  1563. 3. KERMIT'S BUILT-IN FTP CLIENT
  1564.  
  1565.      3.1.  [200]Making and Managing FTP Connections
  1566.      3.2.  [201]Making Secure FTP Connections
  1567.      3.3.  [202]Setting FTP Preferences
  1568.      3.4.  [203]Managing Directories and Files
  1569.      3.5.  [204]Uploading Files With FTP
  1570.      3.6.  [205]Downloading Files With FTP
  1571.      3.7.  [206]Translating Character Sets
  1572.      3.8.  [207]FTP Command Shortcuts
  1573.      3.9.  [208]Dual Sessions
  1574.      3.10. [209]Automating FTP Sessions
  1575.      3.11. [210]Advanced FTP Protocol Features
  1576.  
  1577.    Earlier versions of C-Kermit and K95 included an FTP command, but it
  1578.    simply invoked an external FTP client. Now, by popular demand, Kermit
  1579.    includes its own built-in FTP client that offers the following
  1580.    advantages over traditional FTP clients (and its previous interface to
  1581.    them):
  1582.  
  1583.      * Any of Kermit's built-in [211]security methods can be used to
  1584.        establish and conduct secure FTP sessions with [212]FTP servers
  1585.        that support these methods. (Security modules can be subject to
  1586.        export restrictions.)
  1587.      * Kermit's FTP client uses "passive mode" by default to avoid
  1588.        blockage by firewalls and network address translators. Of course
  1589.        active mode can be chosen too when needed.
  1590.      * [213]Character sets can be translated as part of the transfer
  1591.        process even when the FTP server does not support character-set
  1592.        translation, including to/from the new Internet standard
  1593.        international character set, [214]Unicode UTF-8. This includes both
  1594.        the file's name and (for text files only) its contents.
  1595.      * All of C-Kermit's [215]file-selection mechanisms are available:
  1596.        size, date, name patterns and lists, exception lists, etc.
  1597.      * [216]Atomic file movement capabilities are provided (delete, move,
  1598.        or rename files automatically after successful transfer).
  1599.      * The correct file type, "ascii" (i.e. text) or binary, is chosen
  1600.        automatically for each file (explained in [217]Section 4), and any
  1601.        mixture of text and binary files can be sent in a single operation,
  1602.        even across platforms.
  1603.      * Update mode ("don't bother transferring files that didn't change
  1604.        since last time") and recovery (resumption of an interrupted
  1605.        transfer from the point of failure) are available in both
  1606.        directions.
  1607.      * When uploading files from UNIX to UNIX, the file's permissions can
  1608.        be preserved if desired.
  1609.      * Recursive directory-tree PUTs are supported between any two
  1610.        platforms that have tree-structured file systems. Recursive GETs
  1611.        are supported between like platforms if the server cooperates and
  1612.        between like or unlike platforms if the server supports MLSD
  1613.        ([218]Section 3.11).
  1614.      * When receiving files, all of Kermit's file collision actions are
  1615.        available: backup, update, refuse, rename, etc.
  1616.      * Multi-file transfers can be interrupted on a per-file basis,
  1617.        automatically skipping to the next file.
  1618.      * FTP sessions are [219]fully scriptable.
  1619.      * An entire FTP session (connect, login, CD, upload or download,
  1620.        logout) can be specified on the command line without using a
  1621.        script.
  1622.      * All of Kermit's logging options and formats are available to keep
  1623.        an accurate and complete record of each connection and file
  1624.        transfer, and to aid in troubleshooting.
  1625.      * All of Kermit's file-transfer display options are available
  1626.        (fullscreen, brief, CRT, serial, none).
  1627.  
  1628.    And best of all:
  1629.      * Kermit doesn't give you those annoying per-file prompts every time
  1630.        you start a multi-file transfer without remembering to give a
  1631.        "prompt" command first :-).
  1632.  
  1633.    [ [220]Top ] [ [221]FTP Top ] [ [222]FTP Client Overview ] [ [223]FTP
  1634.    Script Tutorial ] [ [224]C-Kermit Home ] [ [225]Kermit Home ]
  1635.  
  1636. 3.1. Making and Managing FTP Connections
  1637.  
  1638.    Each copy of Kermit can have one FTP connection open at a time. FTP
  1639.    connections are independent of regular terminal connections; a terminal
  1640.    connection (serial or network via SET LINE, DIAL, SET HOST, TELNET,
  1641.    etc) may be, but need not be, open at the same time as an FTP
  1642.    connection, and terminal connections can also be closed, and new
  1643.    connections opened, without interfering with the FTP connection (and
  1644.    vice versa). Thus, for example, Kermit can have an FTP connection and a
  1645.    TELNET connection open to the same host simultaneously, using the
  1646.    TELNET connection (e.g.) to send mail or take other desired actions as
  1647.    various FTP actions complete. Of course, each copy of Kermit can do
  1648.    only one thing at a time, so it can't (for example) transfer a file
  1649.    with FTP and another file with Kermit protocol simultaneously.
  1650.  
  1651.    A Kermit FTP session can be established by [226]command-line options,
  1652.    by [227]URL, or by [228]interactive commands.
  1653.  
  1654. 3.1.1. Kermit Command-Line Options for FTP
  1655.  
  1656.    The new command-line option '-9' (sorry, we're out of letters) can be
  1657.    used when starting C-Kermit, telling it to make an FTP connection:
  1658.  
  1659.   kermit -9 hostname
  1660.  
  1661.    or if a non-default FTP port is needed:
  1662.  
  1663.   kermit -9 hostname:port
  1664.  
  1665.    You can also specify the username on the command line with the -M ("My
  1666.    User ID") option that was already there for other connection types:
  1667.  
  1668.   kermit -9 hostname -M olga
  1669.  
  1670.    If you specify the username on the command line, Kermit uses it when
  1671.    making the connection and does not prompt you for it (but it does
  1672.    prompt you for the password if one is required).
  1673.  
  1674.    Once the connection is made, you get the regular Kermit prompt, and can
  1675.    give interactive commands such as the ones described below. When you
  1676.    give a BYE command, Kermit closes the session and exits, just as a
  1677.    regular FTP client would do. If you don't want Kermit to exit when you
  1678.    give a BYE command, include the -S ("Stay") option on the command line.
  1679.  
  1680.    Other Kermit command-line options that are not specific to non-FTP
  1681.    connections should affect the FTP session in the expected ways; for
  1682.    example, -i and -T force binary and text mode transfers, respectively.
  1683.  
  1684.    File transfers can not be initiated on the "kermit -9" command line;
  1685.    for that you need to use Kermit's FTP personality (next section) or you
  1686.    can use URLs ([229]Section 3.1.3).
  1687.  
  1688. 3.1.2. The FTP Command-Line Personality
  1689.  
  1690.    If you want to replace your regular FTP client with C-Kermit, you can
  1691.    make a link called "ftp" to the C-Kermit binary (or you can store a
  1692.    copy of the C-Kermit binary under the name "ftp"). When C-Kermit is
  1693.    invoked with a program name of "ftp" (or "FTP", case doesn't matter),
  1694.    it assumes the command-line personality of the regular FTP client:
  1695.  
  1696.   ftp [ options ] hostname [ port ]
  1697.  
  1698.    In this case the options are like those of a regular FTP client:
  1699.  
  1700.   -d  Debug: enables debug messages and creates a debug.log file.
  1701.   -n  No autologin: Kermit should not send your user ID automatically.
  1702.   -t  Packet trace: accepted but is treated the same as -d.
  1703.   -v  Verbose: accepted but ignored (operation is verbose by default).
  1704.   -i  Not interactive: accepted but ignored.
  1705.  
  1706.    and the hostname can also be a URL (explained in [230]Section 3.1.3).
  1707.    To specify a non-default TCP port for the FTP server, include the port
  1708.    number or name after the hostname.
  1709.  
  1710.    There are also some bonus options that allow you to execute an entire
  1711.    FTP session from the shell command line, as long as you don't include
  1712.    the -n option. These are not available with regular FTP clients, and at
  1713.    least one of these options (-g) conflicts with UNIX ftp (where -g means
  1714.    "no globbing", which does not apply to Kermit), and some of them (like
  1715.    the options above) also conflict with regular Kermit command-line
  1716.    options:
  1717.  
  1718.   -m mode      = "passive" (default) or "active"
  1719.   -Y            Don't execute the Kermit initialization file [1]
  1720.   -q            Quiet, suppresses all but error messages [1]
  1721.   -S            Stay, don't exit automatically [1]
  1722.   -A            Autologin anonymously [2]
  1723.   -u name       Username for autologin [2] (synonym: -M [1])
  1724.   -P password   Password for autologin (see cautions below) [2]
  1725.   -D directory  cd after autologin [2]
  1726.   -b            Binary mode [2]
  1727.   -a            Text ("ascii") mode [2] (synonym: -T [1])
  1728.   -R            Recursive (works with -p) [4]
  1729.   -p files      Files to put (upload) after autologin [2] (synonym: -s [1])
  1730.   -g files      Files to get (download) after autologin [3]
  1731.  
  1732.    [1] Same as Kermit, not available in regular FTP clients.
  1733.    [2] Conflicts with Kermit, not available in regular FTP clients.
  1734.    [3] Same as Kermit, conflicts with regular FTP clients.
  1735.    [4] Conflicts with Kermit, available in some FTP clients.
  1736.  
  1737.    Fancier options such as restart, character-set translation, filename
  1738.    collision selection, automatic move/rename/delete, etc, are not
  1739.    available from the command line; for these you can use the commands
  1740.    described in the following sections. The -R option might also work with
  1741.    -g (GET) but that depends on the server.
  1742.  
  1743.    The following security options are also available, explained in
  1744.    [231]Section 3.2:
  1745.  
  1746.   -k realm      Kerberos 4 realm [4]
  1747.   -f            Kerberos 5 credentials forwarding [4]
  1748.   -x            autoencryption mode [4]
  1749.   -c cipher     SRP cipher type [4]
  1750.   -H hash       SRP encryption hash [4]
  1751.   -z option     Security options [4]
  1752.  
  1753.    If you include -A or specify a name of "anonymous" or "ftp", you are
  1754.    logged in anonymously and, in the absence of -P, Kermit automatically
  1755.    supplies a password of "user@host", where "user" is your local user ID,
  1756.    and "host" is the hostname of the computer where Kermit is running. If
  1757.    you do not include -p or -g, Kermit enters command mode so you can type
  1758.    commands or execute them from a script.
  1759.  
  1760.    If you include -p or -g, Kermit attempts to transfer the specified
  1761.    files and then exits automatically at the end of the transfer unless
  1762.    you also included -S (Stay). It uses the "brief" file transfer display
  1763.    (one line per file) unless you include the -q option to suppress it.
  1764.  
  1765.    When uploading files with -p, Kermit switches automatically between
  1766.    text and binary mode for each file.
  1767.  
  1768.    When downloading, you can either specify a particular mode (text or
  1769.    binary) to be used for all the files, or you can let Kermit select the
  1770.    type for each file automatically, based on its name (see [232]Sections
  1771.    3.5 and [233]3.6 for greater detail). In UNIX be sure to quote any
  1772.    wildcard characters to prevent the shell from expanding them, as shown
  1773.    in the examples just below. Filename collisions are handled according
  1774.    Kermit's FILE COLLISION setting (if specified in your Kermit
  1775.    customization file; otherwise the default, which is BACKUP).
  1776.  
  1777.    It should go without saying that the -P option should be used with
  1778.    caution. In addition to the well-known risks of transmitting plaintext
  1779.    passwords over the Internet, in this case the password also echos to
  1780.    the screen if you type it, and can be seen in ps and w listings that
  1781.    show the user's currently active command and command-line arguments.
  1782.    Thus command-line FTP sessions are most appropriate for secure or
  1783.    anonymous connections (those that do not require passwords).
  1784.  
  1785.    Here's an example in which you download the latest C-Kermit "tarball"
  1786.    from the Columbia University FTP archive:
  1787.  
  1788.   ftp -A kermit.columbia.edu -bg kermit/archives/ckermit.tar.gz
  1789.  
  1790.    This assumes that "ftp" is a symbolic link to C-Kermit. It logs you in
  1791.    anonymously and gets the ckermit.tar.gz file in binary mode from the
  1792.    kermit/archives directory.
  1793.  
  1794.    Here's a slightly more ambitious example that illustrates CD'ing to the
  1795.    desired server directory to get a group of files in text mode (in this
  1796.    case the C-Kermit source files):
  1797.  
  1798.   ftp -A kermit.columbia.edu -D kermit/f -ag "ck[cuw]*.[cwh]" makefile
  1799.  
  1800.    In this case we CD to the kermit/f directory so we don't have to
  1801.    include it in each file specification, and we quote the ck[cuw]*.[cwh]
  1802.    specification so the shell doesn't expand it, since we have to pass it
  1803.    as-is to the server. Note also that the quotes don't go around the
  1804.    entire file list; only around each file specification that needs to be
  1805.    quoted.
  1806.  
  1807.    Here's one more example, that uploads a debug log file in binary mode
  1808.    to the Kermit incoming directory (as we might ask you to do when
  1809.    following up on a problem report):
  1810.  
  1811.   ftp -A kermit.columbia.edu -D kermit/incoming -bp debug.log
  1812.  
  1813.    In this case the -D option is required to tell the server where to put
  1814.    the incoming file.
  1815.  
  1816.    Unless the -Y option is included, your Kermit initialization file
  1817.    (.mykermrc in UNIX, K95.INI in Windows) is executed before the command
  1818.    line options, so you can set any FTP-related preferences there, as
  1819.    described in the subsequent sections.
  1820.  
  1821. 3.1.3. The FTP URL Interpreter
  1822.  
  1823.    If Kermit is invoked with either its regular personality (as "kermit")
  1824.           or its FTP personality (as "ftp"), you can also give a URL
  1825.           (Universal Resource Locator) instead of a hostname and options,
  1826.           with or without a username and password:
  1827.           ftp ftp://user:password@host/path
  1828.           ftp ftp://user@host/path
  1829.           ftp ftp://@host/path   (or ftp://:@host/path)
  1830.           ftp ftp://host/path
  1831.           kermit ftp://host/path
  1832.  
  1833.    If the FTP personality is used, the service must be "ftp". In all
  1834.    cases, a hostname or address must be included. If a user is included
  1835.    but no password, you are prompted for the password. If a path
  1836.    (filename) is included:
  1837.      * If "@" is included without a user, Kermit prompts for the username
  1838.        and password.
  1839.      * If no user and no "@" are included, "anonymous" is used.
  1840.      * GET is assumed.
  1841.  
  1842.    If no path (and no action options) are included, an interactive FTP
  1843.           session is started, as in this example:
  1844.           ftp ftp://kermit.columbia.edu
  1845.  
  1846.    If a path is included, but a username is not included, "anonymous" is
  1847.    used and an appropriate user@host password is supplied automatically.
  1848.    If authentication is successful, Kermit attempts to GET the file
  1849.    indicated by the path or, if the path is the name of a directory, it
  1850.    asks the server for a directory listing. In both cases, Kermit
  1851.    disconnects from the server and exits after the operation is complete
  1852.    (unless you have included the -S option on the command line).
  1853.  
  1854.    Here's an example that gets a listing of the Kermit directory at the
  1855.           Kermit ftp site:
  1856.           ftp ftp://kermit.columbia.edu/kermit/
  1857.  
  1858.    This example gets the top-level READ.ME file from the same directory:
  1859.           ftp ftp://kermit.columbia.edu/kermit/READ.ME
  1860.  
  1861.    Here's the same example, but requesting a text-mode transfer:
  1862.           ftp -T ftp://kermit.columbia.edu/kermit/READ.ME
  1863.           This illustrates that you can mix command-line options and URLs
  1864.           if you desire.
  1865.  
  1866.    Here's an example that logs in as a (fictitious) real user to get a
  1867.           file:
  1868.           ftp ftp://olga@ftp.xyzcorp.com/resume.txt
  1869.           The password is not included, so Kermit prompts for it.
  1870.  
  1871.    This scheme allows Kermit to be used as the FTP helper of other
  1872.    applications, such as Web browsers, with all its advantages over other
  1873.    FTP clients (especially the ones that are built in to most Web
  1874.    browsers), e.g. that it can be given wildcards, and it can pick text
  1875.    and binary mode automatically for each file.
  1876.  
  1877.    HINT: suppose somebody sends you an FTP URL in email, or you see it in
  1878.    some text. If your terminal screen supports copy/paste, copy the url,
  1879.    and then at the shell prompt type "kermit", a space, and then paste the
  1880.    URL, e.g.:
  1881.  
  1882.   $ kermit ftp://alpha.greenie.net/pub/mgetty/source/1.1/mgetty1.1.27-O
  1883.  
  1884.    "$ is the shell prompt; the part you type is underlined, the rest is
  1885.    pasted in. Kermit does the rest.
  1886.  
  1887. 3.1.4. Interactive FTP Session Establishment
  1888.  
  1889.    As you read this and the following sections, bear in mind that any
  1890.    command that can be given at the prompt can also be used in a script
  1891.    program. Kermit's script programming language is the same as its
  1892.    interactive command language. [234]CLICK HERE if you would like to
  1893.    learn a bit more about script writing.
  1894.  
  1895.    An FTP session is established with the FTP OPEN command:
  1896.  
  1897.    FTP [ OPEN ] [ { /SSL, /TLS } ] hostname [ switches ] [ port ]
  1898.           Opens an FTP connection to the given host on the given port and,
  1899.           if FTP AUTOLOGIN is ON, also logs you in to the server,
  1900.           prompting for username and password if necessary. If no port is
  1901.           specified, the regular FTP protocol port (21) is used. The OPEN
  1902.           keyword is optional (unless the hostname conflicts with one of
  1903.           the FTP command keywords, which you can list by typing "ftp ?").
  1904.  
  1905.    The hostname can be an IP host name, numeric IP address, or if you have
  1906.    a network directory active (SET NETWORK DIRECTORY; see Chapter 6 of
  1907.    [235]Using C-Kermit), an entry name in the directory. In the latter
  1908.    case, if the given hostname matches exactly one entry, the associated
  1909.    name or address is used; if it matches more than one, Kermit cycles
  1910.    through them until one is found that can be opened; if it matches none,
  1911.    then the hostname is used as-is. If a directory is active but you want
  1912.    to bypass directory lookup, include an "=" sign at the beginning of the
  1913.    hostname, and/or use a numeric IP address.
  1914.  
  1915.    When an FTP connection is opened, the default file-transfer mode is set
  1916.    to binary if the client and server platforms are alike (e.g. both of
  1917.    them are some kind of UNIX), and to text ("ascii") if they are not
  1918.    alike. This has no particular effect for uploading since Kermit
  1919.    automatically switches between text and binary mode for each file, but
  1920.    might be important for downloading. The connection is also set to
  1921.    Stream mode and File structure. Record- or page-oriented file transfers
  1922.    are not supported by C-Kermit's FTP client.
  1923.  
  1924.    The optional FTP OPEN switches are:
  1925.  
  1926.    /ANONYMOUS
  1927.           Logs you in anonymously, automatically supplying username
  1928.           "anonymous" and user@host as the password, based on your local
  1929.           user and host names.
  1930.  
  1931.    /NOLOGIN
  1932.  
  1933.           Overrides SET FTP AUTOLOGIN ON for this connection only.
  1934.  
  1935.    /USER:name
  1936.           Uses the given username to log you in, thus avoiding the Name:
  1937.           prompt.
  1938.           Overrides SET FTP AUTOLOGIN OFF for this connection only.
  1939.  
  1940.    /PASSWORD:text
  1941.           Uses the given text as your password, thus avoiding the
  1942.           Password: prompt. This switch is not recommended for use in
  1943.           script files, which would be a security risk.
  1944.  
  1945.    /ACCOUNT:text
  1946.           Uses the given text as your account (or secondary password,
  1947.           depending on the requirements of the server; most servers do not
  1948.           require or accept an account name). If an account is not
  1949.           supplied, you are not prompted for one.
  1950.  
  1951.    /PASSIVE
  1952.           Opens the connection in passive mode. Passive mode is the
  1953.           default in Kermit's FTP client, unlike in most others, since it
  1954.           works better through firewalls. The /PASSIVE and /ACTIVE
  1955.           switches apply only to the connection that is being opened, and
  1956.           do not affect the global FTP PASSIVE-MODE setting.
  1957.  
  1958.    /ACTIVE
  1959.           Opens the connection in active mode. Use this switch if the
  1960.           server does not support passive mode, or use the command SET FTP
  1961.           PASSIVE-MODE OFF.
  1962.  
  1963.    /NOINIT
  1964.           Added in C-Kermit 8.0.201.   Tells C-Kermit not to send REST,
  1965.           STRU, FEAT, and MODE commands to the server when the connection
  1966.           is opened, since these have been reported to cause confusion in
  1967.           certain servers.
  1968.  
  1969.    When a username or password is missing, a prompt is issued at the
  1970.    controlling terminal and you must type the response; the response can
  1971.    not be scripted. Use the switches to avoid prompts, or one of the
  1972.    secure authentication methods described in the next section, or see
  1973.    [236]SET FTP AUTOLOGIN and the [237]FTP USER and similar commands
  1974.    described later in this section.
  1975.  
  1976.    Examples:
  1977.  
  1978.   ftp open kermit.columbia.edu /anonymous  ; Open and log in anonymously
  1979.   ftp kermit.columbia.edu /anonymous       ; The OPEN keyword can be omitted
  1980.   ftp xyzcorp.com                          ; Open and maybe prompt for username
  1981.   ftp xyzcorp.com /user:olga               ; Open and log in as olga
  1982.   ftp testing.abccorp.com 449              ; Specify a special TCP port number
  1983.   ftp testing.abccorp.com /user:olaf /password:secret 449
  1984.  
  1985.    The FTP OPEN command succeeds if a connection was opened to the server
  1986.    (even if the given username and password were not valid) and fails
  1987.    otherwise (see [238]Section 3.8 for details).
  1988.  
  1989.    When your FTP session is complete, you can terminate it as follows:
  1990.  
  1991.    FTP BYE
  1992.           Closes the FTP connection if one was open. The FTP prefix can be
  1993.           omitted if no other connection is open at the same time (see
  1994.           [239]Section 3.8 for details). If a connection log is active, an
  1995.           FTP record is written to it. If Kermit was started with the -9
  1996.           command-line option or with its FTP command-line personality,
  1997.           and the -S (Stay) option was not given, AND there is no other
  1998.           active connection, the FTP BYE command also exits, just as it
  1999.           does on a regular FTP client. Synonyms: FTP CLOSE, FTP QUIT (but
  2000.           if the FTP prefix is omitted from QUIT, this becomes the regular
  2001.           Kermit QUIT command, which is equivalent to EXIT; i.e. it closes
  2002.           the connection and exits from Kermit).
  2003.  
  2004.    The following commands can be used to achieve greater control over the
  2005.    connection and login process:
  2006.  
  2007.    SET FTP ANONYMOUS-PASSWORD text
  2008.           Allows you to choose the password text to be sent automatically
  2009.           by Kermit when you open an FTP connection with the /ANONYMOUS
  2010.           switch.
  2011.  
  2012.    SET FTP AUTOLOGIN { ON, OFF }
  2013.           If you give this command prior to opening an FTP connection, it
  2014.           controls whether Kermit tries to log you in automatically as
  2015.           part of the connection process. Normally ON, which means the
  2016.           username and password are sent automatically (and prompted for
  2017.           if they are not yet known). When OFF, FTP OPEN connects to the
  2018.           server without logging in. OFF is equivalent to the -n
  2019.           command-line option when using Kermit's FTP command-line
  2020.           personality.
  2021.  
  2022.    FTP USER name [ password [ account ] ]
  2023.           Used to log in to an FTP server to which a connection has been
  2024.           made without autologin, or when autologin failed. If the
  2025.           password is furnished on the command line, it is used; otherwise
  2026.           you are prompted for a password. An account may also be
  2027.           furnished if required by the server; it is not required by
  2028.           Kermit and is not prompted for if omitted. Synonyms: USER, FTP
  2029.           LOGIN.
  2030.  
  2031.    FTP ACCOUNT text
  2032.           Sends an account name to a server that supports accounts. If the
  2033.           server does not support accounts, an error response occurs. If
  2034.           the server does support accounts, the account is accepted if it
  2035.           is valid and rejected if it is not. The account might be used
  2036.           for charging purposes or it might be a secondary password, or it
  2037.           might be used for any other purpose, such as an access password
  2038.           for a particular disk. Servers that support accounts might or
  2039.           might not allow or require the account to be sent prior to
  2040.           login; usually it is sent after login, if at all. Synonym:
  2041.           ACCOUNT.
  2042.  
  2043.    Example:
  2044.  
  2045. set ftp autologin off                  ; One thing at a time please
  2046. ftp xyzcorp.com                        ; Try to make the connection
  2047. if fail exit 1 FTP connection failed   ; Check that it was made
  2048. ftp user olga secret                   ; Now log in to the server
  2049. if fail exit 1 FTP login failed        ; Check that it worked
  2050. ftp account 103896854                  ; Login OK - send account
  2051. if fail echo WARNING - FTP ACCT failed ; Warn if problem
  2052. ...                                    ; (have session here)
  2053. bye                                    ; Log out and disconnect
  2054.  
  2055.    The following commands are used to control or get information about the
  2056.    FTP connection. Any particular FTP server does not necessarily support
  2057.    all of them.
  2058.  
  2059.    FTP RESET
  2060.           Terminates a user session but leaves the connection open,
  2061.           allowing a new login via FTP USER.
  2062.  
  2063.    FTP IDLE [ number ]
  2064.           Most FTP servers automatically log you out and and disconnect
  2065.           your session if there has been no activity for a certain amount
  2066.           of time. Use this command to ask the server to set its idle
  2067.           limit to the given number of seconds. Omit the number to ask the
  2068.           server to inform you of its current idle limit.
  2069.  
  2070.    FTP STATUS [ filename ]
  2071.           Asks the FTP server to send information about the current
  2072.           session. The result is a free-format report that might include
  2073.           server identification, username and login time, FTP protocol
  2074.           settings, and file-transfer statistics. If a filename is given,
  2075.           the server is supposed to send detailed information about the
  2076.           file.
  2077.  
  2078.    FTP SYSTEM
  2079.           Asks the FTP server to identify its operating system (Listed in
  2080.           Internet Assigned Numbers, Operating System Names). Examples:
  2081.           UNIX, VMS, VM/CMS, WINDOWS-NT. Unfortunately many variations are
  2082.           allowed (e.g. LINUX-2.0, LINUX-2.2, FREEBSD, ULTRIX, etc,
  2083.           instead of UNIX; WINDOWS-NT-3, WINDOWS-NT-3.5, WINDOWS-NT-3.51,
  2084.           WINDOWS-NT-4, etc). The report might also include other
  2085.           information like "Type L8", "Type I", or "Type A", indicating
  2086.           the file-transfer mode.
  2087.  
  2088.    FTP HELP [ keyword [ keyword [ ... ] ]
  2089.           Asks the server to list the commands it supports. The response
  2090.           is usually cryptic, listing FTP command mnemonics, not the
  2091.           commands used by the client (since the server has no way of
  2092.           knowing anything about the client's user interface). For
  2093.           example, the PUT command is STOR in FTP protocol. If a keyword
  2094.           is given, which should be an FTP protocol command,
  2095.           slightly-more- detailed help is given about the corresponding
  2096.           command (if the FTP server supports this feature). Examples:
  2097.           "ftp help", "ftp help stor".
  2098.  
  2099.    FTP SITE text
  2100.           (Advanced) Sends an FTP SITE (site-specific) command. Usually
  2101.           this means that the FTP server is asked to run an external
  2102.           command with the given arguments. You might be able to find out
  2103.           what SITE commands are available by sending "ftp help site" to
  2104.           the server, but in general the availability of and response to
  2105.           SITE commands is (not surprisingly) site specific.
  2106.  
  2107.    FTP QUOTE text
  2108.           (Advanced) Sends an FTP command in FTP protocol format. Use this
  2109.           command to send commands to the server that the FTP client might
  2110.           not know about.
  2111.  
  2112.    SHOW FTP
  2113.           Lists client (Kermit) FTP settings and information. Also SHOW
  2114.           CONNECTION, SHOW COMMUNICATIONS.
  2115.  
  2116.    HELP FTP [ keyword ]
  2117.           Asks Kermit to list and describe its built-in FTP commands.
  2118.  
  2119.    HELP SET FTP [ keyword ]
  2120.           Asks Kermit to list and describe its built-in SET FTP commands.
  2121.  
  2122.    [ [240]Top ] [ [241]FTP Top ] [ [242]C-Kermit Home ] [ [243]Kermit Home
  2123.    ]
  2124.  
  2125. 3.1.5. Making Proxy Connections
  2126.  
  2127.    The simplist form of firewall traversal is the HTTP CONNECT command.
  2128.    The CONNECT command was implemented to allow a public web server which
  2129.    usually resides on the boundary between the public and private networks
  2130.    to forward HTTP requests from clients on the private network to public
  2131.    web sites. In order to allow secure web connections to be established,
  2132.    the CONNECT command works by authenticating the client with a
  2133.    username/password and then establishing a tunnel to the desired host.
  2134.  
  2135.    Many web servers support the CONNECT command and it can be configured
  2136.    to allow outgoing connections to authenticated user to any TCP/IP
  2137.    hostname/port combination accessible to the web server. The limitations
  2138.    of HTTP CONNECT is that it can only be used for outgoing connections
  2139.    for protocols that are implemented using TCP/IP. Protocols such as
  2140.    Kerberos authentication that use UDP/IP cannot be tunneled using HTTP
  2141.    CONNECT.
  2142.  
  2143.    Kermit provides support for the use of HTTP CONNECT proxy services with
  2144.    the command:
  2145.  
  2146.   SET TCP HTTP-PROXY [/USER:username /PASSWORD:password] hostname/ip-address[:po
  2147. rt]
  2148.  
  2149.    When a port is not specified the default port configured on the HTTP
  2150.    server is used. This is frequently port 443. When a hostname is
  2151.    specified, it is resolved using the DNS available to the web server.
  2152.  
  2153. 3.2. Making Secure FTP Connections
  2154.  
  2155.    Also see: [244]Accessing IBM Information Exchange with Kermit.
  2156.  
  2157.    In the previous section, you can see several examples of traditional
  2158.    insecure authentication: username and password sent across the network
  2159.    in clear text. Of course this is bad practice on at least two counts:
  2160.    (1) storing passwords in files (such as script files) gives access to
  2161.    the target systems to anybody who can obtain read access to your
  2162.    scripts; and (2) sending this information over the network leaves it
  2163.    open to interception by network sniffers or compromised hosts.
  2164.  
  2165.    Because of the increasing need for security on the Internet, FTP
  2166.    servers are beginning to appear that offer secure forms of
  2167.    authentication, in which no information is sent over the network that
  2168.    would allow anyone who intercepts it to usurp your identity and gain
  2169.    your access rights.
  2170.  
  2171.    Kermit provides an equivalent form of FTP security for each type of
  2172.    IETF standard security implemented in Telnet. These include
  2173.    GSSAPI-KERBEROS5, KERBEROS4, Secure Remote Password (SRP), and
  2174.    Transport Layer Security (SSL and TLS). It does not presently include
  2175.    SSL tunneling nor any form of SSH v1 or v2. When Kermit is built with
  2176.    the necessary libraries, secure FTP connections are attempted by
  2177.    default, in which all connections are authenticated and the command and
  2178.    data channels are private.
  2179.  
  2180.    The use of authentication and encryption for FTP connections can be
  2181.    adjusted with the commands listed below, which are available only if
  2182.    your version of Kermit was built with the corresponding security
  2183.    options and libraries:
  2184.  
  2185.    SET FTP AUTHTYPE { AUTOMATIC, GSSAPI-KRB5, KERBEROS4, SRP, SSL, TLS }
  2186.           Specifies an ordered list of authentication methods to be
  2187.           attempted when AUTOAUTHENTICATION is ON. The default list is:
  2188.           GSSAPI-KRB5, SRP, KERBEROS_V4, TLS, SSL. If none of the selected
  2189.           methods are supported by the server, an insecure login is used
  2190.           as a fallback. Note, by the way, that SSL or TLS can be used to
  2191.           secure an anonymous connection.
  2192.  
  2193.    SET FTP AUTOAUTHENTICATION { ON, OFF }
  2194.           Tells whether authentication should be negotiated by the FTP
  2195.           OPEN command. Default is ON. Use SET FTP AUTOAUTHENTICATION OFF
  2196.           to force a clear-text, unencrypted connection to FTP servers
  2197.           (such as the one at the Kermit FTP site) that normally would try
  2198.           to negotiate secure authentication and encryption.
  2199.  
  2200.    SET FTP AUTOENCRYPTION { ON, OFF }
  2201.           Tells whether encryption (privacy) should be negotiated by the
  2202.           FTP OPEN command, which can happen only if secure authentication
  2203.           is also negotiated. Default is ON.
  2204.  
  2205.    SET FTP AUTOLOGIN { ON, OFF }
  2206.           Tells Kermit whether to try logging in automatically when you
  2207.           make an FTP connection, as opposed to letting you do it "by
  2208.           hand" with the FTP USER command.
  2209.  
  2210.    SET FTP COMMAND-PROTECTION-LEVEL { CLEAR, CONFIDENTIAL, PRIVATE, SAFE }
  2211.           Determines the level of protection applied to the command
  2212.           channel:
  2213.  
  2214.   CLEAR         Data is sent in plaintext and not protected against tampering.
  2215.   CONFIDENTIAL  Data is encrypted but not protected against tampering.
  2216.   PRIVATE       Data is encrypted and is protected against tampering.
  2217.   SAFE          Data is sent in plaintext but protected against tampering.
  2218.  
  2219.           The default is PRIVATE.
  2220.  
  2221.    SET FTP CREDENTIAL-FORWARDING { ON, OFF }
  2222.           Tells whether end-user credentials are to be forwarded to the
  2223.           server if supported by the authentication method (GSSAPI-KRB5
  2224.           only). This is often required to allow access to distributed
  2225.           file systems (e.g. AFS.)
  2226.  
  2227.    SET FTP DATA-PROTECTION-LEVEL { CLEAR, CONFIDENTIAL, PRIVATE, SAFE }
  2228.           Tells what level of protection is applied to subsequent data
  2229.           channels. The meanings of the protection-level keywords are the
  2230.           same as for SET FTP COMMAND-PROTECTION-LEVEL. The default is
  2231.           PRIVATE.
  2232.  
  2233.    SET FTP SRP CIPHER name
  2234.           Specifies the cipher to be used for encryption when SRP
  2235.           authentication is in use. The list of possible choices is
  2236.           computed based on the capabilities of the local SRP library and
  2237.           includes NONE plus zero or more of the following:
  2238.  
  2239.   BLOWFISH_ECB        CAST5_ECB          DES_ECB          DES3_ECB
  2240.   BLOWFISH_CBC        CAST5_CBC          DES_CBC          DES3_CBC
  2241.   BLOWFISH_CFB64      CAST5_CFB64        DES_CFB64        DES3_CFB64
  2242.   BLOWFISH_OFB64      CAST5_OFB64        DES_OFB64        DES3_OFB64
  2243.  
  2244.           The default is DES3_ECB.
  2245.  
  2246.    SET FTP SRP HASH name
  2247.           Specifies the hash to be used for data protection when SRP
  2248.           authentication is in use. The choices are MD5 and SHA. The
  2249.           default is SHA.
  2250.  
  2251.    Command-line options:
  2252.  
  2253.    -k name
  2254.           Specifies the realm to be used with Kerberos 4 authentication (=
  2255.           SET AUTH K4 REALM name).
  2256.  
  2257.    -f
  2258.           Enables forwarding of Kerberos 5 credentials to the host when
  2259.           using GSSAPI authentication (= SET AUTH K5 FORWARDABLE ON).
  2260.  
  2261.    -x
  2262.           Enables autoencryption (= SET FTP AUTOENCRYPTION ON).
  2263.  
  2264.    -c cipher
  2265.           Specifies the kind of cipher to be used for encryption with SRP
  2266.           authentication. Equivalent to SET FTP SRP CIPHER, with the same
  2267.           choices. If this option is not given, CAST5_CBC is used.
  2268.  
  2269.    -H hash
  2270.           Specifies the hash to be used for encryption with SRP
  2271.           authentication. Equivalent to SET FTP SRP HASH, with the same
  2272.           choices. If this option is not given, SHA is used.
  2273.  
  2274.    -z debug
  2275.           Turns on SSL/TLS debugging.
  2276.  
  2277.    -z secure
  2278.           Requires secure connection.
  2279.  
  2280.    -z certsok
  2281.           Says to accept all certificates without checking validity.
  2282.  
  2283.    -z verify=n
  2284.           Sets certificate verification mode to the given number, n:
  2285.             0 = no verification
  2286.             1 = verify certificate if presented
  2287.             2 = require verification of certificate
  2288.  
  2289.    -z cert=filename
  2290.           Specifies a file containing a client certificate to be presented
  2291.           to the FTP server.
  2292.  
  2293.    -z key=filename
  2294.           Specifies a file containing a private key matching the client
  2295.           certificate.
  2296.  
  2297.    -z !krb4
  2298.           (nokrb4) Disables the use of Kerberos 4.
  2299.  
  2300.    -z !gss
  2301.    -z nogss
  2302.           Disables the use of GSSAPI - Kerberos 5.
  2303.  
  2304.    -z !srp
  2305.    -z nosrp
  2306.           Disables use of SRP.
  2307.  
  2308.    -z !ssl
  2309.    -z nossl
  2310.           Disables the use of SSL.
  2311.  
  2312.    -z !tls
  2313.    -z notls
  2314.           Disables the use of TLS.
  2315.  
  2316.    Caution: If your FTP connection is secured via AUTH TLS, it is not
  2317.    possible to interrupt a file transfer. This is a limitation of all
  2318.    known FTP servers that support AUTH TLS.
  2319.  
  2320.    Note that when using certain security methods, such as SSL or TLS, you
  2321.    may be prompted to confirm or verify certain actions or conditions, for
  2322.    example, whether to accept self-signed certificates. This can interfere
  2323.    with unattended operation of scripts; see [245]Section 3.10.
  2324.  
  2325.    [ [246]Top ] [ [247]FTP Top ] [ [248]C-Kermit Home ] [ [249]Kermit Home
  2326.    ]
  2327.  
  2328. 3.3. Setting FTP Preferences
  2329.  
  2330.    FTP preferences can be set globally and persistently with the commands
  2331.    in the following sections; many of these can also be overridden on a
  2332.    per-command basis with switches that have the same name.
  2333.  
  2334. 3.3.1. Logs, Messages, and Other Feedback
  2335.  
  2336.    You can control the amount of feedback received from your FTP session
  2337.    with the commands in this section. First, you can create a log of your
  2338.    FTP transfers with the following commands:
  2339.  
  2340.    SET TRANSACTION-LOG { VERBOSE, FTP, BRIEF }
  2341.           Selects the log format. VERBOSE is the default, and is described
  2342.           in [250]the manual. FTP chooses a WU-FTPD format, the same as is
  2343.           used by the popular FTP server. BRIEF creates per-file records
  2344.           in comma-separated-list format. For greater detail, see
  2345.           [251]Section 4.17 of the [252]C-Kermit 7.0 Update Notes.
  2346.  
  2347.    LOG TRANSACTIONS filename
  2348.           Records FTP (or Kermit, or any other protocol) uploads and
  2349.           downloads in the given file using the format selected by the
  2350.           most recent SET TRANSACTION-LOG command, if any, or else the
  2351.           default format.
  2352.  
  2353.    FTP screen messages and displays are controlled by the following
  2354.    commands:
  2355.  
  2356.    SET TRANSFER DISPLAY { FULLSCREEN, CRT, SERIAL, BRIEF, NONE, OFF }
  2357.           FTP transfers use Kermit's normal file-transfer display styles.
  2358.           Use this command to choose the desired format; the default on
  2359.           most platforms is FULLSCREEN. The display is automatically
  2360.           disabled if Kermit is running in the background or in batch.
  2361.           BRIEF is always used for command-line initiated transfers
  2362.           (unless suppressed by -q). While a file-transfer is in progress,
  2363.           you can interrupt it in the normal Kermit way by typing one of
  2364.           the following keys or key combinations:
  2365.             X - Cancel current file but go on to the next one (if any).
  2366.             Z - Cancel the entire transfer.   Ctrl-L or Ctrl-W - Refresh
  2367.           the file-transfer display (if any).
  2368.  
  2369.    SET FTP DISPLAY { FULLSCREEN, CRT, SERIAL, BRIEF, NONE, OFF }
  2370.           Like SET TRANSFER DISPLAY, but applies only to FTP connections,
  2371.           and does not affect Kermit- or other protocol file transfers.
  2372.  
  2373.    SET QUIET { ON, OFF }
  2374.           This command applies to Kermit in general, not just FTP. OFF by
  2375.           default; when ON, it suppresses most messages from most commands
  2376.           as well as the file-transfer display.
  2377.  
  2378.    SET FTP PROGRESS-MESSAGES { ON, OFF }
  2379.           Tells whether Kermit should print locally-generated feedback
  2380.           messages for each non-file-transfer command. ON by default.
  2381.  
  2382.    SET FTP VERBOSE-MODE { ON, OFF }
  2383.           Tells whether to display all responses from the FTP server. OFF
  2384.           by default. This shows all responses to all commands, except
  2385.           when the file-transfer display is active, and unless you have
  2386.           SET QUIET ON. When OFF, responses are shown only for commands
  2387.           such as FTP PWD whose purpose is to display a response.
  2388.  
  2389.    SET FTP DEBUG { ON, OFF }
  2390.           Tells whether local client debugging information should be
  2391.           displayed. OFF by default. When ON, the commands that are sent
  2392.           to the server are shown, as well as its responses (even if
  2393.           VERBOSE-MODE is OFF), plus additional informational messages are
  2394.           printed regarding the progress of secure operations. Also, the
  2395.           temporary file created by the [253]MGET command is not deleted
  2396.           so you can see what's in it.
  2397.  
  2398.    Set all of these to OFF when silent running is desired.
  2399.  
  2400. 3.3.2. Operational Preferences
  2401.  
  2402.    FTP DISABLE new-protocol-feature-name
  2403.    FTP ENABLE new-protocol-feature-name
  2404.           Explained in [254]Section 3.11.
  2405.  
  2406.    SET FTP AUTOLOGIN { ON, OFF }
  2407.           If you give this command prior to opening an FTP connection, it
  2408.           controls whether Kermit tries to log you in automatically as
  2409.           part of the connection process. Normally ON, which means the
  2410.           username and password are sent automatically (and prompted for
  2411.           if they are not yet known). When OFF, FTP OPEN connects to the
  2412.           server without logging in. OFF is equivalent to the -n
  2413.           command-line option when using Kermit's FTP command-line
  2414.           personality. See [255]Section 3.1.4 for usage.
  2415.  
  2416.    SET FTP PASSIVE-MODE { ON, OFF }
  2417.           ON by default, to avoid random TCP port assignment for data
  2418.           connections, which can prevent FTP protocol from working through
  2419.           firewalls and network address translators (for more on these
  2420.           topics, see the [256]Kermit security reference. Set to OFF in
  2421.           case the FTP server does not support passive mode, or in case
  2422.           the client has problems with it (it has been observed, for
  2423.           example, that when using passive mode, the SCO XENIX 2.3.4
  2424.           TCP/IP stack hangs in the connect() call forever). Synonyms:
  2425.           PASSIVE [ ON ], PASSIVE OFF, PASV [ ON ], PASV OFF.
  2426.  
  2427.    SET FTP SEND-PORT-COMMANDS { ON, OFF }
  2428.           This command determines whether the FTP client sends a new PORT
  2429.           command to the server when accepting incoming data connections
  2430.           (as when not using passive mode.) When PASSIVE-MODE is OFF and
  2431.           SET SEND-PORT is OFF, the port that was originally specified is
  2432.           reused. This is the default behavior for normal FTP clients but
  2433.           it is not compatible with many firewalls.
  2434.  
  2435.    SET FTP CHARACTER-SET-TRANSLATION { ON, OFF }
  2436.           Whether to translate character sets when transferring files with
  2437.           FTP (explained in [257]Section 3.7). OFF by default.
  2438.  
  2439.    SET FTP SERVER-CHARACTER-SET name
  2440.           Tells Kermit the character set used by the FTP server, UTF-8 by
  2441.           default ([258]Section 3.7).
  2442.  
  2443.    SET FTP SERVER-TIME-OFFSET delta-time
  2444.           Tells Kermit to apply the given [259]delta time to file
  2445.           timestamps provided by the server for its files; for use when
  2446.           (for example) the server does not have its timezone set
  2447.           correctly.
  2448.  
  2449.    SET FTP ERROR-ACTION { PROCEED, QUIT }
  2450.           When transferring a group of files with FTP, and an error occurs
  2451.           with one of the files, Kermit normally goes on the next file.
  2452.           Use SET FTP ERROR-ACTION to QUIT to make Kermit stop the
  2453.           transfer immediately and fail if an error occurs with any single
  2454.           file in the group. Example: you have given Kermit a list of
  2455.           files to send, and one of the files can not be found, or read
  2456.           permission is denied. Note that canceling a file by typing 'X'
  2457.           during transfer is not considered an error (if you want to
  2458.           cancel the entire transfer, type 'Z' or Ctrl-C).
  2459.  
  2460.    SET FTP PERMISSIONS { AUTO, ON, OFF }
  2461.           When uploading files with PUT or MPUT, this tells whether Kermit
  2462.           should send each file's permissions. The default is OFF, which
  2463.           means not to send permissions, in which case the uploaded file's
  2464.           permissions are set by the FTP server according to its own
  2465.           criteria. ON means to send them, AUTO means to send them only if
  2466.           the client (Kermit) and server are on like platforms (e.g. both
  2467.           UNIX). This command has no effect when downloading, since the
  2468.           FTP protocol does not include a way for the server to inform the
  2469.           client of a file's permissions. Also see [260]FTP PUT
  2470.           /PERMISSIONS. Note that setting permissions after uploading is
  2471.           likely to work (correctly or at all) only when the client and
  2472.           server platforms are alike (e.g. both of them are some form of
  2473.           UNIX). Also note that Windows files don't have permissions. Also
  2474.           see [261]FTP CHMOD.
  2475.  
  2476.    SET FTP DATES { ON, OFF }
  2477.           When downloading files with GET or MGET, this tells whether
  2478.           Kermit should try to set the received file's date from the
  2479.           server's date. FTP DATES is ON by default. Note, however, that
  2480.           FTP protocol does not allow date preservation when uploading. So
  2481.           at best, SET FTP DATES ON can work only when downloading, and
  2482.           then only when the server agrees to furnish file dates.
  2483.  
  2484.    SET FTP FILENAMES { AUTO, CONVERTED, LITERAL }
  2485.           When uploading (sending) files, this tells whether to convert
  2486.           outbound filenames to "common form". This means allowing only
  2487.           one period in a name, uppercasing any lowercase letters,
  2488.           replacing spaces by underscores, etc. AUTOMATIC is the default,
  2489.           meaning LITERAL when client and server are the same type of
  2490.           system (e.g. UNIX) and CONVERTED otherwise. Special case: if the
  2491.           setting is AUTOMATIC and the client is not UNIX and the server
  2492.           identifies itself as UNIX, Kermit uses a less-strict form of
  2493.           conversion, in which lowercase letters are not uppercased and
  2494.           the filename can contain any number of periods, but spaces are
  2495.           still converted to underscore. When receiving, conversion
  2496.           generally means to change all-uppercase names to lowercase and
  2497.           spaces to underscore.
  2498.  
  2499.    SET FTP UNIQUE-SERVER-NAMES { ON, OFF }
  2500.           Applies only to uploads. Tells the server to create new, unique
  2501.           names for incoming files that have the same names as existing
  2502.           files. OFF by default, in which case the server overwrites
  2503.           existing files with new files of the same name. When ON, the
  2504.           server uses its own built-in method for creating new names for
  2505.           incoming files; for example, appending a period (.) and a number
  2506.           to the name. CAUTION: Use this option only if you do not need to
  2507.           refer to the file after it is uploaded, since FTP protocol
  2508.           provides no mechanism for the client to find out what name was
  2509.           assigned by the server.
  2510.  
  2511.    SET FTP COLLISION { ... }
  2512.           When downloading, what to do if an incoming file has the same
  2513.           name as an existing file. Options are the same as for SET FILE
  2514.           COLLISION. If this command is not given, Kermit's regular FILE
  2515.           COLLISION setting is used. If this command is given, it
  2516.           overrides the FILE COLLISION setting for FTP transfers only. See
  2517.           [262]Section 3.6.2 for details.
  2518.  
  2519.    SET FTP TYPE { TEXT, BINARY, TENEX }
  2520.           Changes the default transfer mode. When sending (uploading)
  2521.           files, this command has no effect unless you disable automatic
  2522.           text/binary mode switching ([263]Section 4) with SET FILE SCAN
  2523.           OFF or SET TRANSFER MODE MANUAL. When receiving (downloading)
  2524.           files, this command establishes the transfer mode to be used
  2525.           when a filename does not match any of Kermit's text or binary
  2526.           filename patterns, unless you use SET FTP GET-FILETYPE-SWITCHING
  2527.           or SET TRANSFER MODE MANUAL to disable automatic switching, in
  2528.           which case, this command establishes the transfer mode for all
  2529.           downloaded files. In all cases, however, the FTP TYPE can be
  2530.           overridden in any GET or PUT command by including a /TEXT
  2531.           (/ASCII), /BINARY, or /TENEX switch. The FTP TYPE is independent
  2532.           of the Kermit FILE TYPE setting. TENEX is used for sending 8-bit
  2533.           binary files to 36-bit platforms such as TOPS-10, TOPS-20, and
  2534.           TENEX, and getting them back again. Synonym: ASCII = TEXT. Note:
  2535.           there is also an FTP TYPE command, which does what SET FTP TYPE
  2536.           does but also sends a TYPE command to the server immediately if
  2537.           the given type is different from the current one.
  2538.  
  2539.    If you want want specific FTP preference settings to be in effect for
  2540.    all your Kermit FTP sessions, put the desired SET FTP commands in your
  2541.    Kermit customization file (~/.mykermrc in UNIX, K95CUSTOM.INI in
  2542.    Windows).
  2543.  
  2544.    [ [264]Top ] [ [265]FTP Top ] [ [266]C-Kermit Home ] [ [267]Kermit Home
  2545.    ]
  2546.  
  2547. 3.4. Managing Directories and Files
  2548.  
  2549.    In Kermit, commands for directory and file management can refer to:
  2550.  
  2551.      * The local computer
  2552.      * A remote computer when you have a connection to a Kermit server or
  2553.        IKSD.
  2554.      * A remote computer when you have a connection to an FTP server.
  2555.  
  2556.    (There can also be an HTTP connection, but the commands in this section
  2557.    don't apply to HTTP connections.)
  2558.  
  2559.    Thus in general, each such command comes in three forms:
  2560.  
  2561.     1. With no prefix in C-Kermit 8.0.200, it refers to the local computer
  2562.        (CD, DIR, etc). In C-Kermit 8.0.201 and later, however, the "locus"
  2563.        switches to automatically to the remote FTP server when you make an
  2564.        FTP connection (see the SET LOCUS description [268]Section 7); thus
  2565.        C-Kermit 8.0.201 acts almost exactly like a regular FTP client when
  2566.        it has an FTP connection, yet still acts like itself on other kinds
  2567.        of connections.
  2568.     2. With the REMOTE prefix, it is for a Kermit server (REMOTE CD,
  2569.        REMOTE DIR).
  2570.     3. With the FTP prefix, it's for an FTP server (FTP CD, FTP DIR).
  2571.     4. Also see [269]Section 3.8, which explains "R-commands" and
  2572.        "L-commands".
  2573.  
  2574.    Kermit's FTP file and directory management commands are as follows.
  2575.    When an R-command is included in the Synonyms list, be sure to read
  2576.    [270]Section 3.8 about rules for use of R-commands.
  2577.  
  2578.    FTP CD [ directory ]
  2579.           Tells the FTP server to change its default (working) directory
  2580.           to the one given, which usually must be expressed in the syntax
  2581.           of the server platform (UNIX, VMS, etc). If the directory is not
  2582.           specified, the result depends on the FTP server -- it might
  2583.           complain that the command is illegal, or it might change to your
  2584.           original login directory. Synonyms: FTP CWD (Change Wording
  2585.           Directory); RCD.
  2586.  
  2587.    FTP CDUP
  2588.           Tells the FTP server to change its default (working) directory
  2589.           to the parent directory of its current one (equivalent to
  2590.           "cd .." in UNIX, or "cd [-]" in VMS). Synonyms: RCDUP, FTP UP.
  2591.  
  2592.    FTP PWD
  2593.           Asks the FTP server to report ("print") its current working
  2594.           directory. Synonym: RPWD.
  2595.  
  2596.    FTP MKDIR directory
  2597.           Asks the FTP server to create the directory whose name is given.
  2598.           In general, the name must be in the syntax of the server's file
  2599.           system, and it must be either absolute (a full pathname) or
  2600.           relative to the server's current (working) directory. This
  2601.           command fails if the directory can't be created for any reason,
  2602.           including that it exists already. Synonym: RMKDIR.
  2603.  
  2604.    FTP RMDIR directory
  2605.           Asks the FTP server to remove the directory whose name is given.
  2606.           The rules are the same as for MKDIR, plus in most cases, the
  2607.           server will not remove any directory unless it is empty.
  2608.           Synonym: RRMDIR.
  2609.  
  2610.    FTP DIRECTORY [ filespec ] [ redirectors ]
  2611.           Tells the FTP server to send a directory listing of the
  2612.           specified files. If no filespec is given, the server lists all
  2613.           files in its current working directory. The results are in
  2614.           whatever format the server chooses to send them. You can use
  2615.           UNIX-like redirectors to send the listing to a file or a
  2616.           pipeline, exactly as with the regular Kermit client/server
  2617.           REMOTE DIRECTORY command ([271]Using C-Kermit, Chapter 11).
  2618.           Synonym: RDIRECTORY. Examples:
  2619.  
  2620.     ftp dir                           ; Show listing of all files on screen
  2621.     ftp dir *.txt                     ; List *.txt files on screen
  2622.     ftp dir *.txt > somefile          ; Put listing in somefile
  2623.     ftp dir *.txt >> somefile         ; Append listing to somefile
  2624.     ftp dir *.txt | sort > somefile   ; Put sorted listing in somefile
  2625.     ftp dir | more                    ; Runs list through "more"
  2626.     ftp dir | sort | more             ; Runs list through "sort" and "more"
  2627.  
  2628.    FTP VDIRECTORY [ filespec ] [ redirectors ]
  2629.           "Verbose" directory. This is an alternative FTP DIRECTORY
  2630.           command primarily for use with DECSYSTEM-20 (TOPS-20) FTP
  2631.           servers, which send only filenames when given a DIRECTORY
  2632.           command; the VDIRECTORY command makes them also send file sizes,
  2633.           dates, and attributes.
  2634.  
  2635.    FTP CHECK filespec
  2636.           Asks the FTP server whether the given file exists or, if the
  2637.           filespec contains wildcards, if any files match, and this
  2638.           command succeeds or fails accordingly.
  2639.  
  2640.    FTP MODTIME filename
  2641.           Asks the FTP server, via the not-yet-standard FTP MDTM command,
  2642.           to send the modification date and time of the given file. The
  2643.           response should be a numeric string in the format:
  2644.           yyyymmddhhmmssxxxxx... where yyyy is the year, mm is the month,
  2645.           dd is the day, hh is the hour (0-23), mm is the minute, ss is
  2646.           the second, and xxx... is the optional fraction of the second (0
  2647.           or more digits). The date and time is expressed in UTC (GMT,
  2648.           Zulu, Zero-Meridian). The result is available programmatically
  2649.           in the [272]\v(ftp_message) variable, and is understandable by
  2650.           Kermit's date-time switches and functions. For example, suppose
  2651.           we want to upload all local files that are newer than a
  2652.           particular file on the server:
  2653.  
  2654.   C-Kermit> ftp modtime signpost
  2655.   C-Kermit> echo \v(ftp_message)
  2656.   20010807113542.014
  2657.   C-Kermit> ftp mput /after:\v(ftp_message)GMT *
  2658.  
  2659.           Note that we must append "GMT" to the date-time string to let
  2660.           the /AFTER switch know the time is GMT rather than local.
  2661.  
  2662.    FTP SIZE filename
  2663.           Asks the FTP server to send the size (in bytes) of the given
  2664.           file. The result might vary depending on whether the current FTP
  2665.           TYPE is binary or text ("ascii"). For a reliable byte count, do
  2666.           FTP TYPE BINARY first. The result is available programmatically
  2667.           in the [273]\v(ftp_message) variable.
  2668.  
  2669.    FTP CHMOD permissions filename
  2670.           Tells the FTP server to set the permissions (protection) of the
  2671.           given file to the ones given. The permissions and filename must
  2672.           be given in whatever syntax is required by the server. Example
  2673.           (for a UNIX-based FTP server):
  2674.  
  2675.   ftp chmod 664 oofa.txt
  2676.  
  2677.           Not all servers support this command. For non-UNIX-based
  2678.           servers, you might need to use FTP QUOTE or FTP SITE and the
  2679.           appropriate platform-specific FTP server command.
  2680.  
  2681.    FTP UMASK [ number ]
  2682.           This command is probably specific to UNIX-based servers; it sets
  2683.           the UNIX "umask", which is the default permissions mask for new
  2684.           (in this case, incoming) files. Crudely put, the UNIX umask is
  2685.           an octal representation of a binary number in in which a 1 bit
  2686.           stands for a permission bit that must be 0, and a 0 bit stands
  2687.           for a permission bit that can be 0 or 1 depending on other
  2688.           factors, such as the permissions of the parent directory.
  2689.           Example: "umask 007" requires that new files are created without
  2690.           read/write/execute world permission. If the number is not
  2691.           specified, the server's current umask is reported.
  2692.  
  2693.    FTP RENAME filename newname
  2694.           Asks the FTP server to rename the file whose name is "filename"
  2695.           to "newname". Works only for one file; can not be used with
  2696.           wildcards. The server's interpretation of "newname" can vary (in
  2697.           some cases it must be a filename, in others perhaps it can also
  2698.           be a directory name, in which case if the filename denote a
  2699.           regular file, the file might be moved to the given directory).
  2700.           Some servers might allow files to be renamed ("moved") between
  2701.           physical disks or partitions, others might not. Synonym:
  2702.           RRENAME.
  2703.  
  2704.    FTP DELETE [ switches ] filespec [ filespec [ ... ] ]
  2705.           Tells the FTP server to delete the file or files listed. Each
  2706.           file specification may, but need not, contain wildcard
  2707.           characters to match multiple files. File specifications and
  2708.           wildcard syntax must be those of the server. Any file
  2709.           specifications that contain spaces must be enclosed in braces or
  2710.           doublequotes. FTP DELETE switches are:
  2711.  
  2712.  /ERROR-ACTION:  /FILENAMES:     /NOBACKUPFILES  /QUIET
  2713.  /EXCEPT:        /LARGER-THAN:   /NODOTFILES     /NOPAGE
  2714.  /PAGE           /RECURSIVE      /SMALLER-THAN:
  2715.  
  2716.           When used with FTP DELETE, the /RECURSIVE switch deletes files
  2717.           but not directories, and furthermore depends on the server
  2718.           providing recursive file lists, which is not the normal
  2719.           behavior. For further details, see the descriptions of these
  2720.           switches in [274]Section 3.6. Synonyms: FTP MDELETE (Kermit
  2721.           makes no distinction between DELETE and MDELETE); RDELETE.
  2722.  
  2723.    FTP TYPE { TEXT, BINARY, TENEX }
  2724.           Tells the FTP server to change its file-transfer type to the one
  2725.           given, immediately. See [275]SET FTP TYPE for details.
  2726.  
  2727.    [ [276]Top ] [ [277]FTP Top ] [ [278]C-Kermit Home ] [ [279]Kermit Home
  2728.    ]
  2729.  
  2730. 3.5. Uploading Files With FTP
  2731.  
  2732.    Uploading means sending files from the client (Kermit) to the FTP
  2733.    server. The basic command for uploading files with FTP is PUT:
  2734.  
  2735.    FTP PUT [ switches ] [ filespec [ as-name ] ]
  2736.           Uploads (sends) the file or files that match the file
  2737.           specification, which may include wildcards, to the server. If no
  2738.           filespec is given, the names of files to send are taken from the
  2739.           /LISTFILE: file, if any, otherwise from the SEND-LIST, if any.
  2740.           Unless you go out of your way to prevent it, Kermit determines
  2741.           the transfer mode (text or binary) for each file automatically,
  2742.           and switches automatically on a per-file basis. If an as-name is
  2743.           given, the file is sent under that name instead of its own (if
  2744.           an as-name is given with a wildcard filespec, the result is a
  2745.           bit more complicated, and is explained later in this section).
  2746.  
  2747.    Unlike normal FTP clients, Kermit does not prompt you by default (or at
  2748.    all) for each file; it just sends them, just as it does with Kermit
  2749.    protocol. The filespec can be a literal filename or a Kermit pattern,
  2750.    described in:
  2751.  
  2752.   [280]http://www.columbia.edu/kermit/ckermit70.html#x4.9
  2753.  
  2754.    Kermit patterns are equivalent to C-Shell patterns and provide a fair
  2755.    amount of flexibility in selecting which files to send, which is
  2756.    augmented by the file-selection switches presented in [281]Section
  2757.    3.5.1.
  2758.  
  2759.    FTP MPUT [ switches ] filespec [ filespec [ ... ] ]
  2760.           FTP MPUT is just like FTP PUT except it allows you to give more
  2761.           than one file specification, and it does not allow an as-name in
  2762.           the file list. However, as-names can be given to either PUT or
  2763.           MPUT with the /AS-NAME: switch.
  2764.  
  2765.    If a PUT or MPUT command results in one file being uploaded, it
  2766.    succeeds if the file is uploaded completely and fails otherwise. If
  2767.    more than one file is selected for upload, success or failure depends
  2768.    on the [282]FTP ERROR-ACTION setting; if it is PROCEED (the default
  2769.    setting), then the [M]PUT command succeeds if at least one of the files
  2770.    was completely uploaded, and fails otherwise, If FTP ERROR-ACTION is
  2771.    QUIT, the [M]PUT command succeeds if all selected files were uploaded
  2772.    successfully, and fails if any file failed.
  2773.  
  2774.    FTP uploads may be interrupted just like Kermit uploads. While the
  2775.    transfer is in progress, type:
  2776.  
  2777.   X to interrupt the current file and go on to the next file.
  2778.   Z to cancel the current file and all remaining files.
  2779.   ^C (Control-C): Like Z, but might act more quickly.
  2780.  
  2781.    MPUT may be used as in regular FTP clients, but it is not required to
  2782.    send multiple files; in Kermit it is required only if you want to give
  2783.    multiple file specifications. Examples:
  2784.  
  2785.   ftp put oofa.txt               ; Send a single file oofa.txt
  2786.   ftp put oofa.txt budget.txt    ; Send single file oofa.txt as budget.txt
  2787.   ftp put *.txt                  ; Send all *.txt files
  2788.   ftp mput *.txt                 ; Send all *.txt files (same as "put *.txt")
  2789.   ftp mput *.txt foo.bar         ; Send all *.txt files plus foo.bar
  2790.  
  2791.    The distinction between PUT and MPUT is important only when more than
  2792.    one filespec is given, just like the distinction between Kermit SEND
  2793.    and MSEND:
  2794.  
  2795.   ftp put oofa.txt budget.txt    ; Send oofa.txt AS budget.txt
  2796.   ftp mput oofa.txt budget.txt   ; Send oofa.txt AND budget.txt
  2797.  
  2798.    If the source file specification includes any path segments, for
  2799.    example:
  2800.  
  2801.   put /tmp/oofa.txt
  2802.   put subdir/another/andanother/oofa.txt
  2803.  
  2804.    the path portion is stripped from the filename that is sent to the
  2805.    server. However, if an as-name contains a path, it is retained.
  2806.    Examples:
  2807.  
  2808.   ftp put /usr/doc/oofa.txt      ; Send as "oofa.txt".
  2809.   ftp put oofa.txt /tmp/oofa.txt ; Send as "/tmp/oofa.txt"
  2810.  
  2811.    The latter example sends the file oofa.txt from your current local
  2812.    directory to the server's /tmp directory. This works only if the server
  2813.    uses the same directory notation that you used in the as-name AND the
  2814.    given directory already exists on the server AND if you have write
  2815.    access to it.
  2816.  
  2817.    Use caution when uploading from a case-sensitive file system, such as
  2818.    UNIX, to a file system that is not case sensitive, such as Windows or
  2819.    VMS. If you have two files in UNIX, AA and aa and upload both of them,
  2820.    the second one will overwrite the first. The only way around this
  2821.    provided by FTP protocol is its "unique server names" feature (SET FTP
  2822.    UNIQUE-SERVER-NAMES or the /UNIQUE switch described below).
  2823.  
  2824. 3.5.1. FTP PUT Switches
  2825.  
  2826.    FTP PUT and MPUT are similar in format and behavior to the regular
  2827.    Kermit SEND and MSEND commands, and they allow most of the same
  2828.    optional switches:
  2829.  
  2830. C-Kermit>ftp put ? Filename, or switch, one of the following:
  2831.  /after:                 /larger-than:           /rename-to:
  2832.  /array:                 /listfile:              /server-character-set:
  2833.  /as-name:               /local-character-set:   /server-rename-to:
  2834.  /before:                /move-to:               /simulate
  2835.  /binary                 /nobackupfiles          /smaller-than:
  2836.  /command                /nodotfiles             /tenex
  2837.  /delete                 /nofollowlinks          /text
  2838.  /dotfiles               /not-after:             /transparent
  2839.  /error-action:          /not-before:            /type:
  2840.  /except:                /permissions:           /update
  2841.  /filenames:             /quiet                  /unique-server-names
  2842.  /filter:                /recover
  2843.  /followlinks            /recursive
  2844.  
  2845.    Since most of these switches are common to Kermit's SEND and MSEND
  2846.    commands, they described only briefly here. For greater detail see:
  2847.  
  2848.      [283]http://www.columbia.edu/kermit/ckermit70.html#x1.5 (explanation
  2849.    of switches)
  2850.      [284]http://www.columbia.edu/kermit/ckermit70.html#x4.7
  2851.    (file-transfer switches)
  2852.  
  2853.    First the file-selection switches:
  2854.  
  2855.    /AFTER:date-time
  2856.    /BEFORE:date-time
  2857.    /NOT-AFTER:date-time
  2858.    /NOT-BEFORE:date-time
  2859.           Only send those files modified on or after or before the given
  2860.           date and time. These switches can be combined to select files
  2861.           modified between two date/times. Various date-time formats are
  2862.           accepted; if the date-time contains spaces, it must be enclosed
  2863.           in braces or doublequotes. See
  2864.           [285]http://www.columbia.edu/kermit/ckermit70.html#x1.6 and
  2865.           [286]Section 8.13 of this document for details about date-time
  2866.           formats. Examples:
  2867.  
  2868.   ftp put /after:{1 jan 2000 0:00:00} *
  2869.   ftp put /after:-5days *
  2870.  
  2871.    /LARGER-THAN:number
  2872.    /SMALLER-THAN:number
  2873.           Only send files larger (smaller) than the given number of bytes
  2874.           (octets). These switches can be combined to select files in a
  2875.           certain size range.
  2876.  
  2877.    /TYPE:{TEXT,BINARY}
  2878.           Only send files that are the given type, which is determined for
  2879.           each file just before sending it by file scanning. BINARY
  2880.           includes TENEX; if you have included a /TENEX switch, or
  2881.           previously given a [SET] FTP TYPE TENEX command, binary files
  2882.           are sent in TENEX, rather than BINARY mode.
  2883.  
  2884.    /[NO]DOTFILES
  2885.           [Don't] include files whose names begin with dot (.). By
  2886.           default, such files are not included unless your filespec
  2887.           explicitly mentions them.
  2888.  
  2889.    /NOBACKUPFILES
  2890.           Don't include files whose names end with .~nnn~, where nnn is a
  2891.           number, e.g. oofa.txt.~27~. These are backup files created by
  2892.           Kermit, EMACS, and other applications. By default, backup files
  2893.           are included.
  2894.  
  2895.    /NOFOLLOWLINKS
  2896.           (UNIX only) Skip over symbolic links rather than following them
  2897.           (default). This applies to wildcard and/or recursive [M]PUTs; if
  2898.           a single filename is given, and it happens to be a symbolic
  2899.           link, the file it points to is sent.
  2900.  
  2901.    /FOLLOWLINKS
  2902.           (UNIX only) Always follow (resolve) symbolic links, even in
  2903.           wildcard or recursive [M]PUTs. Use with caution. Watch out for
  2904.           circular links, endless loops, etc.
  2905.  
  2906.    /EXCEPT:pattern
  2907.           Exception list -- don't send files whose names match the given
  2908.           pattern. See [287]Section 1.5.4 of the [288]C-Kermit 7.0 Update
  2909.           Notes for details. If you want to exclude a directory from a
  2910.           recursive [M]PUT, use /EXCEPT:{dirname/*}.
  2911.  
  2912.    /RECURSIVE
  2913.           Sends the desired files from the current (or given) directory,
  2914.           plus all directories beneath it, including empty directories,
  2915.           replicating the directory structure on the server. No special
  2916.           capabilities are required in the server, but of course your
  2917.           login ID on the server must have the appropriate access and
  2918.           permission to create directories. Recursive PUTs work not only
  2919.           between like platforms (e.g. UNIX to UNIX) but also between
  2920.           unlike ones (e.g. UNIX to VMS or Windows), in which case
  2921.           text-file format differences are handled by Kermit's automatic
  2922.           text/binary mode switching ([289]Section 4) and character-set
  2923.           translation ([290]Section 3.7). Synonym: /SUBDIRECTORIES.
  2924.  
  2925.    /UPDATE
  2926.           Send only files that have changed since last time ([291]Section
  2927.           3.5.2).
  2928.  
  2929.    /ARRAY:arrayname
  2930.           The "file" to be sent is an array, or a segment of one, rather
  2931.           than a real file. In this case the other selection switches
  2932.           don't apply. The array contents are sent in text mode, and each
  2933.           array element is treated as a line. Example:
  2934.  
  2935.   ftp put /as-name:array.txt /array:&a
  2936.  
  2937.           (or, to send a segment of the array, /array:&a[100:199]). If you
  2938.           don't include an /AS-NAME, a name of "_array_x_" is used (where
  2939.           x is the array letter). If you include this switch, most other
  2940.           switches are meaningless and ignored.
  2941.  
  2942.    /COMMAND
  2943.           The "file" to be sent is the standard output of a command,
  2944.           rather than a real file. It is sent in text or binary mode
  2945.           according to the prevailing FTP TYPE, which can be overridden
  2946.           with a /TEXT or /BINARY switch. Example: Example:
  2947.  
  2948.   ftp put /command /as-name:{userlist} {finger | sort -r}
  2949.  
  2950.    /LISTFILE:filename
  2951.           Tells Kermit to obtain the list of files to be sent from the
  2952.           file whose name is given. This file must contain one file
  2953.           specification (which may be wild) per line. If the list includes
  2954.           files from different directories, such as a recursive listing of
  2955.           a directory tree, the paths are recreated on the server (if
  2956.           possible) if you include the /RECURSIVE switch; otherwise all
  2957.           the files are sent to the current directory on the server.
  2958.  
  2959.    Now the other switches:
  2960.  
  2961.    /AS-NAME:text
  2962.           If a single file is being sent, send it with the given text as
  2963.           its name. If multiple files are being sent, the text must be a
  2964.           template that includes variables such as \v(filename),
  2965.           \v(filenumber), \v(ntime), to allow dynamic creation of each
  2966.           name. The same applies to the as-name field of the FTP PUT
  2967.           command. If this switch is not included (and an as-name is not
  2968.           included as the second filename to PUT), each file is sent with
  2969.           its own name.
  2970.  
  2971.    /BINARY
  2972.    /TEXT
  2973.    /TENEX
  2974.           Forces this upload to take place in the given mode, regardless
  2975.           of the current FTP TYPE setting, and without automatic
  2976.           text/binary switching. /ASCII is a synonym for /TEXT.
  2977.  
  2978.    /FILTER:command
  2979.           Specifies that the file(s) is/are to be passed through the given
  2980.           command or pipeline on their way to the server. Example:
  2981.  
  2982.   ftp put /binary /filter:{gzip -c \v(filename)} /as-name:\v(filename).gz *
  2983.  
  2984.    /TRANSPARENT
  2985.    /LOCAL-CHARACTER-SET:name
  2986.    /SERVER-CHARACTER-SET:name
  2987.           Character-set translation for text files, explained in
  2988.           [292]Section 3.7.
  2989.  
  2990.    /ERROR-ACTION:{PROCEED,QUIT}
  2991.           Overrides the prevailing [293]FTP ERROR-ACTION for the duration
  2992.           of this PUT or MPUT command only.
  2993.  
  2994.    /RECOVER
  2995.           Resume an interrupted transfer where from the point of
  2996.           interruption (explained in [294]Section 3.5.2). Synonym:
  2997.           /RESTART.
  2998.  
  2999.    /DELETE
  3000.           Tells Kermit to delete each source file immediately after, and
  3001.           only if, it has been uploaded completely and successfully. This,
  3002.           in effect, moves the file from the client to the server.
  3003.  
  3004.    /MOVE-TO:directory
  3005.           Tells Kermit to move each source file to the named local
  3006.           directory after, and only if, it has been uploaded completely
  3007.           and successfully.
  3008.  
  3009.    /RENAME-TO:template
  3010.           Tells Kermit to rename each (local) source file according to the
  3011.           given template after, and only if, it has been uploaded
  3012.           completely and successfully. The template works as in /AS-NAME.
  3013.  
  3014.    /SERVER-RENAME-TO:template
  3015.           Tells Kermit to ask the server to rename each file according to
  3016.           the given template as soon as, and only if, it has been received
  3017.           completely and successfully. The template works as in /AS-NAME.
  3018.           Requires write and rename access on the server, so doesn't
  3019.           usually work with (e.g.) anonymous uploads to public incoming
  3020.           areas where the permissions don't allow renaming. Examples:
  3021.  
  3022.         ftp mput /server-rename:\v(filename).ok *
  3023.                 Appends ".ok" to each filename on the server when it's
  3024.                 finished uploading.
  3025.  
  3026.         ftp mput /as-name:\v(filename).tmp /server-rename:\v(filename) *
  3027.                 This is the reverse of the previous example; it uses a
  3028.                 temporary name while uploading is in progress and reverts
  3029.                 the file to its real name when uploading is complete.
  3030.  
  3031.         ftp mput /as-name:\v(filename)
  3032.                 /server-rename:../final/\v(filename) *
  3033.                 Moves the file from the working directory to a final
  3034.                 directory when the upload is complete, but in this case
  3035.                 you have to know the pathname syntax of the server. If the
  3036.                 rename fails, the [M]PUT command fails according to the
  3037.                 [295]FTP ERROR-ACTION selection.
  3038.  
  3039.    /FILENAMES:{AUTOMATIC,CONVERTED,LITERAL}
  3040.           Overrides the [296]FTP FILENAMES setting for this upload only.
  3041.  
  3042.    /PERMISSIONS:{ON,OFF}
  3043.           Overrides the [297]FTP PERMISSIONS setting for this upload only.
  3044.  
  3045.    /UNIQUE
  3046.           Tells Kermit to tell the server to give [298]unique names to
  3047.           incoming files that would otherwise overwrite existing files
  3048.           that have the same name. This switch conflicts with /UPDATE,
  3049.           /RECOVER, /PERMISSIONS, and /SERVER-RENAME since the client has
  3050.           no way of knowing the name assigned by the server.
  3051.  
  3052.    /QUIET
  3053.           Don't display file-transfer progress or statistics.
  3054.  
  3055.    /SIMULATE
  3056.           Shows which files would be sent without actually sending them.
  3057.           Useful (for example) with /UPDATE (next section). The results
  3058.           are shown in the file-transfer display (if it is not disabled)
  3059.           and in the transaction log (if one is active). Hint: use SET
  3060.           TRANSFER DISPLAY BRIEF.
  3061.  
  3062. 3.5.2. Update Mode
  3063.  
  3064.    When you include the /UPDATE switch, this means to skip sending any
  3065.    file that already exists on the server if the local file's modification
  3066.    date/time is not later than that of the corresponding file on the
  3067.    server. Here is a typical application for update mode: Suppose that on
  3068.    Computer A, you maintain a large set of files (say, a collection of Web
  3069.    pages and graphics images, or the source files for a software
  3070.    application), and you need to keep a parallel copy on another Computer,
  3071.    B. Of course you could upload the entire collection every day:
  3072.  
  3073.   cd source-directory
  3074.   ftp computerb.xyzcorp.com
  3075.   ( authentication details... )
  3076.   ftp cd target-directory
  3077.   ftp put [ switches ] *
  3078.  
  3079.    But if the total size is large or the network slow, this would be
  3080.    unnecessarily time-consuming. Worse, if other users or sites had to
  3081.    update whenever new files appeared in B's directory, this would cause
  3082.    them unnecessary work. By including the /UPDATE switch:
  3083.  
  3084.   ftp put /update [ other-switches ] *
  3085.  
  3086.    only those files that changed since last time are uploaded. Here's how
  3087.    it works. For each local file that is selected for uploading:
  3088.  
  3089.      * The remote filename is determined in the normal way, according to
  3090.        the [299]FTP FILENAMES setting, /FILENAMES switch, or the as-name,
  3091.        if any.
  3092.      * Kermit sends an MDTM (modification time) command for the
  3093.        corresponding remote filename to the server.
  3094.      * If the server does not understand the MDTM command, the file is
  3095.        sent.
  3096.      * If the server can't find a file with the given name, the file is
  3097.        sent.
  3098.      * If the local file's modification time is later than that of the
  3099.        remote file, the file is sent.
  3100.      * Otherwise -- the remote file exists but its modification time is
  3101.        equal to or earlier than that of the local file -- the file is
  3102.        skipped.
  3103.  
  3104.    All time comparisons take place in Coordinated Universal Time
  3105.    (UTC)([300]1), also known as GMT or Zulu time: Timezone 0; standard
  3106.    time, without daylight savings.
  3107.  
  3108.      WARNING: Some FTP servers, such as Novell NWFTPD.NLM, ignore or
  3109.      misimplement the FTP specification and send local time rather than
  3110.      UTC.
  3111.  
  3112.    Update mode is useful only when always used in the same direction. When
  3113.    you upload (PUT) a file with FTP, the destination file receives the
  3114.    current timestamp on the server's computer, not the original file's
  3115.    timestamp ([301]2). If you try to FTP PUT /UPDATE the same file again,
  3116.    it will be skipped (as expected) since the remote copy is newer.
  3117.    However, if you try to FTP GET /UPDATE the same file ([302]Section
  3118.    3.6), it will be transferred for the same reason.
  3119.  
  3120.    To check the availability of PUT /UPDATE on a particular connection,
  3121.    issue an FTP MODTIME command for a file that is known to exist on the
  3122.    server. If it succeeds, PUT /UPDATE should work and in that case, you
  3123.    can run a procedure like the one above every day: the first time, it
  3124.    sends all the files; after that, it sends only the ones that changed.
  3125.    If a transaction log is active, a notation is included for any files
  3126.    that are skipped.
  3127.  
  3128.    Notes:
  3129.     1. Why is Coordinated Universal Time abbreviated UTC? From the
  3130.        [303]National Institute of Standards and Technology FAQ: "In 1970
  3131.        the Coordinated Universal Time system was devised by an
  3132.        international advisory group of technical experts within the
  3133.        International Telecommunication Union (ITU). The ITU felt it was
  3134.        best to designate a single abbreviation for use in all languages in
  3135.        order to minimize confusion. Since unanimous agreement could not be
  3136.        achieved on using either the English word order, CUT, or the French
  3137.        word order, TUC, the acronym UTC was chosen as a compromise."
  3138.     2. The Kermit FTP client is unusual in that, when downloading only, it
  3139.        can set the received file's date from the file's date on the
  3140.        server, but this should not affect the update feature. When
  3141.        uploading to an FTP server, however, there is no mechanism for the
  3142.        client to set the date of the uploaded file on the server.
  3143.  
  3144. 3.5.3 Recovery
  3145.  
  3146.    Suppose that while you are uploading a large file over a slow
  3147.    connection, the connection is lost before the entire file is
  3148.    transferred. With most FTP clients, you would have to start over, thus
  3149.    resending the portion of the file that was sent already, and that is
  3150.    already on the server. But Kermit's /RECOVER switch (Synonym: /RESTART)
  3151.    lets you continue an interrupted transfer from the point of failure,
  3152.    thus transferring only the part that wasn't sent already. The
  3153.    prerequisites for recovery are:
  3154.  
  3155.      * The transfer must be in BINARY mode, or else the client and server
  3156.        must reside on like systems (e.g. both on some form of UNIX).
  3157.      * The FTP server must support the SIZE command.
  3158.  
  3159.    Here's how it works. When you include the /RECOVER switch:
  3160.  
  3161.      * Kermit checks for conflicting switches, such as /UPDATE and
  3162.        /UNIQUE; if /RECOVER is given with these switches an error occurs.
  3163.        If /RECOVER is given in other circumstances where it could serve no
  3164.        useful purpose (e.g. with arrays, pipes, or filters), it is
  3165.        ignored.
  3166.  
  3167.    If the switch is accepted, then for each selected file:
  3168.  
  3169.      * If it is not binary (determined by scanning) and the client and
  3170.        server are not on like platforms, recovery is canceled (the entire
  3171.        file is sent). Otherwise:
  3172.      * A SIZE command is sent for the file (using its remote name). If the
  3173.        reply indicates the file was not found, or the SIZE command was not
  3174.        understood, or any other kind of error, recovery is canceled.
  3175.        Otherwise:
  3176.      * A MDTM (modification time) command is sent for the file. If a valid
  3177.        reply is received, and the modification time of the local file is
  3178.        later than that of the remote file, recovery is canceled.
  3179.        Otherwise:
  3180.      * If the sizes of the two files are identical, the file is not sent.
  3181.        Otherwise:
  3182.      * Kermit seeks to the recovery spot in the local file, tells the
  3183.        server to APPEND the data which is about to arrive to the remote
  3184.        file, and then sends the data starting at the recovery point.
  3185.  
  3186.    To safeguard file integrity, recovery is not attempted unless all the
  3187.    preconditions are met. For the widest possible usefulness, APPEND is
  3188.    used rather than RESTART. For stream transfers (the only kind that
  3189.    Kermit supports) the results are the same.
  3190.  
  3191.    By design, the /RECOVER switch can be included with any FTP PUT or MPUT
  3192.    command, even if it specifies a group of files. This allows you to
  3193.    resume an interrupted batch transfer from where it left off. The files
  3194.    that were already completely sent are skipped, the file that was
  3195.    interrupted is recovered, and the remaining files are uploaded.
  3196.  
  3197.    By the way, it doesn't matter how the original partial file was
  3198.    uploaded -- FTP, Kermit, Zmodem, etc: as long as the preconditions are
  3199.    met, it can be recovered with FTP PUT /RECOVER, or for that matter also
  3200.    using Kermit protocol and SEND /RECOVER.
  3201.  
  3202.    A word of caution, however, when the original upload was in text mode
  3203.    with character-set translation ([304]Section 3.7):
  3204.  
  3205.      * If the original upload involved a translation from one single-byte
  3206.        character set to another (e.g. Code Page 850 to Latin-1), recovery
  3207.        is safe if you specify the same translations for the recovery. If
  3208.        you don't, the resulting file will contain a mixture of character
  3209.        sets.
  3210.      * If the original upload involved a translation that changed the size
  3211.        of the file (e.g. from an alphabetic Code Page or Latin Alphabet to
  3212.        Unicode, or vice versa), recovery is NOT safe, even if you specify
  3213.        the same translations.
  3214.  
  3215.    Kermit has no way of knowing anything about the previous upload. As a
  3216.    safeguard, an error occurs if you include /RECOVER and also specify a
  3217.    character-set of UCS2 or UTF8, since recovery can't possibly work in
  3218.    that situation. Otherwise, it's up to you to avoid unsafe recovery
  3219.    operations.
  3220.  
  3221.    [ [305]Top ] [ [306]FTP Top ] [ [307]C-Kermit Home ] [ [308]Kermit Home
  3222.    ]
  3223.  
  3224. 3.6. Downloading Files With FTP
  3225.  
  3226.    Although uploading files with Kermit's FTP client is just as easy and
  3227.    flexible as sending files with Kermit protocol, the same is not always
  3228.    true for downloading because FTP servers lack some of the capabilities
  3229.    of a Kermit server:
  3230.  
  3231.      * If you want to get more than one file, you have to use MGET, not
  3232.        GET, since the underlying FTP protocol is different in the two
  3233.        cases. Kermit can't "autodetect" which one you mean, as it can with
  3234.        PUT and MPUT, since it can't be expected to know the wildcard
  3235.        syntax of the remote platform and/or FTP server (the same is true
  3236.        for all other FTP clients). To complicate matters, FTP protocol now
  3237.        includes two underlying mechanisms (NLST and MLSD) for
  3238.        accomplishing MGET operations and, as explained in [309]Section
  3239.        3.11, the two behave differently.
  3240.      * Automatic text-binary mode switching is not done by the server. It
  3241.        can be done by the client (Kermit), but in this case it is not
  3242.        based on a file scan (since there is no way for Kermit prescan a
  3243.        server file), but rather on the filename, using C-Kermit 7.0
  3244.        [310]filename patterns.
  3245.      * Some options that are available with FTP PUT can not be used with
  3246.        FTP [M]GET or don't work the same way:
  3247.          /PERMISSIONS (FTP protocol has no mechanism for this).
  3248.          /[NOT-]BEFORE, /[NOT-]AFTER (because of the timezone problem).
  3249.          /RECOVER works only in binary mode.   /RECURSIVE has limited
  3250.        utility.
  3251.  
  3252.    The commands for downloading are:
  3253.  
  3254.    SET FILE DOWNLOAD-DIRECTORY [ directory ]
  3255.           As with Kermit transfers, this command, if given, tells C-Kermit
  3256.           where to store incoming files in the absence of a specific
  3257.           as-name. If not given, incoming files are stored as indicated by
  3258.           the as-name, if any, otherwise in the current directory, just as
  3259.           with Kermit transfers. The more verbose transfer display formats
  3260.           give the full pathname of each received file, and, in case you
  3261.           have trouble finding a downloaded file afterwards, its full path
  3262.           is also listed in the transaction log (if you kept one), and you
  3263.           can also ask Kermit where it went with the [311]WHERE command.
  3264.  
  3265.    SET FTP GET-FILETYPE-SWITCHING { ON, OFF }
  3266.           ON by default, causing Kermit to switch automatically into text
  3267.           or binary mode for each file based on whether its name matches a
  3268.           text pattern or binary pattern. Set this OFF, or use a /TEXT,
  3269.           /BINARY, or /TENEX switch to defeat this feature. Use SHOW
  3270.           PATTERNS to see the current pattern list.
  3271.  
  3272.    [ FTP ] GET [ switches ] filename [ as-name ]
  3273.           Asks the server to send the given file, and if it comes, stores
  3274.           it locally under the given as-name, if any, otherwise under its
  3275.           original name (modified according to the selected filename
  3276.           conversion option), in your download directory, if you have
  3277.           specified one, otherwise in the directory indicated in the
  3278.           as-name, if any, otherwise in your current directory. If you
  3279.           accidentally use a wildcard in the filename ("get *.txt") the
  3280.           server will reply with a message like "File not found" (unless
  3281.           there is a file whose name actually is "*.txt"). If FTP
  3282.           GET-FILETYPE-SWITCHING is ON, and in the absence of any GET
  3283.           switches to override it, the file is transferred in binary mode
  3284.           if it matches any of Kermit's binary name patterns, and in text
  3285.           mode if it matches any of Kermit's text name patterns, and in
  3286.           the prevailing FTP TYPE if it matches none of these patterns.
  3287.  
  3288.    [ FTP ] MGET [ switches ] filespec [ filespec [ filespec [ ... ] ] ]
  3289.           Like GET, but for multiple files. One or more file
  3290.           specifications can be given, and any or all (or none) of them
  3291.           can contain wildcards or can be directory names. The file list
  3292.           may not include an as-name, but you can still give one with the
  3293.           /AS-NAME: switch.
  3294.  
  3295.    In both the FTP GET and MGET commands, any filenames that contain
  3296.    spaces must be enclosed in braces or doublequotes (see [312]Section 5
  3297.    for details).
  3298.  
  3299.    FTP downloads may be interrupted just like Kermit transfers. While the
  3300.    transfer is in progress, type:
  3301.  
  3302.      * X to interrupt the current file and go on to the next file.
  3303.      * Z (or Control-C) to cancel the current file and all remaining
  3304.        files.
  3305.  
  3306.    Before proceeding, a brief word about temporary files. In FTP protocol,
  3307.    the MGET command works by requesting a file list from the server, and
  3308.    then (internally) issuing a GET command (FTP RETR protocol directive)
  3309.    for each file. The file list returned by the server can be any size at
  3310.    all, so in case it is huge, we don't store it in memory; instead we put
  3311.    it in a temporary file. For troubleshooting purposes, you should be
  3312.    aware of two points:
  3313.  
  3314.     1. The location of the temporary file is chosen according the TMP or
  3315.        TEMP environment variables. If neither of these variables is
  3316.        defined, you might need to define it. In case there is not enough
  3317.        space on the indicated disk or partition for the server's file
  3318.        list, you might need to either clean up the temporary area, or
  3319.        redefine the environment variable to indicate a different area that
  3320.        has sufficient space.
  3321.     2. If you want to look at the list yourself, use SET FTP DEBUG ON.
  3322.        This tells Kermit to (a) give you the full pathname of the
  3323.        temporary file at the end of each MGET command, and (b) not to
  3324.        delete it, as it normally does.
  3325.  
  3326. 3.6.1. FTP GET Switches
  3327.  
  3328.    The following switches are available with FTP GET and MGET:
  3329.  
  3330.    /TEXT
  3331.           Specifies a text-mode transfer. Overrides the global FTP TYPE
  3332.           setting and filename pattern-matching for the duration of the
  3333.           current command only, All files are downloaded in text mode.
  3334.           Synonym: /ASCII.
  3335.  
  3336.    /BINARY
  3337.           Specifies a binary-mode transfer. Overrides the global FTP TYPE
  3338.           setting and filename pattern-matching for the duration of the
  3339.           current command only. All files are downloaded in binary mode.
  3340.  
  3341.    /TENEX
  3342.           Like /BINARY but specifies a special binary transfer mode to be
  3343.           used when getting 8-bit binary files from a 36-bit platform such
  3344.           as TOPS-10, TOPS-20, or TENEX. All files are downloaded in the
  3345.           special binary mode.
  3346.  
  3347.    /RECOVER
  3348.           This instructs Kermit to try to recover an incomplete download
  3349.           from the point of failure. Works only in binary mode, and only
  3350.           if the server supports the (not-yet-standard) FTP "REST"
  3351.           directive. See [313]Section 3.6.3 for details. Synonym:
  3352.           /RESTART.
  3353.  
  3354.    /FILENAMES:{CONVERTED,LITERAL}
  3355.           Overrides the [314]FTP FILENAMES (filename conversion) setting
  3356.           for this download only, forcing incoming filenames to be either
  3357.           converted or taken literally.
  3358.  
  3359.    /AS-NAME:text
  3360.           For GET, this is equivalent to giving an as-name after the
  3361.           filename. For MGET, this is the only way to specify alternative
  3362.           names for the incoming files. With MGET, the /AS-NAME text
  3363.           should (must) contain a Kermit variable, usually \v(filename) or
  3364.           \v(filenumber). Example:
  3365.  
  3366.   mget /text /as-name:\v(filename).new *.c
  3367.  
  3368.           This gets all ".c" files and stores them with "
  3369.  
  3370.           .new" appended to their names. See the [315]C-Kermit 7.0 Update
  3371.           Notes for details.
  3372.  
  3373.    /COMMAND
  3374.           This specifies that the incoming file is to be written to the
  3375.           standard input of a command, rather than to a file. The command
  3376.           name is the as-name from the GET command or the /AS-NAME
  3377.           argument. If you need to refer to the incoming file's name in
  3378.           the command, use \v(filename). See the description of the
  3379.           regular Kermit [316]GET /COMMAND command for details and
  3380.           examples.
  3381.  
  3382.    /QUIET
  3383.           Transfers the files quietly; don't put up a file-transfer
  3384.           display.
  3385.  
  3386.    /ERROR-ACTION:{QUIT,PROCEED}
  3387.           This switch affects only MGET. If an error occurs with a
  3388.           particular file, this tells whether to go on to the next file
  3389.           (PROCEED) or to stop right away and fail (QUIT). The default is
  3390.           PROCEED.
  3391.  
  3392.    The file selection switches are:
  3393.  
  3394.    /EXCEPT:{pattern} or /EXCEPT:{{pattern}{pattern}{...}}
  3395.           Exception list for MGET; skip downloading any file whose name
  3396.           matches any of the given patterns (when using the second format,
  3397.           up to 64 patterns may be specified). [317]CLICK HERE for syntax
  3398.           details.
  3399.  
  3400.    /SMALLER-THAN:number
  3401.           Download only files whose size is smaller than the given number
  3402.           of bytes (octets). Requires that the FTP server support the SIZE
  3403.           or MLSD directive.
  3404.  
  3405.    /LARGER-THAN:number
  3406.           Download only files whose size is greater than the given number
  3407.           of bytes. Requires that the FTP server support the SIZE or MLSD
  3408.           directive.
  3409.  
  3410.    /NOBACKUPFILES
  3411.           During MGET, don't download any files whose names end with
  3412.           backup suffixes (.~n~ where n is a number).
  3413.  
  3414.    /NODOTFILES
  3415.           During MGET, don't download any files whose names begin with
  3416.           period (.). Equivalent to /EXCEPT:{.*}.
  3417.  
  3418.    /LISTFILE:local-filename
  3419.           The given file contains a list of files to GET, one per line.
  3420.           Filenames in the listfile can contain wildcard characters in the
  3421.           syntax of the server. There is no limit on the number of lines
  3422.           in the listfile.
  3423.  
  3424.    /NAMELIST:local-filename
  3425.           If this switch is given, then instead of actually retrieving the
  3426.           selected files, the GET command retrieves a list of the names of
  3427.           the files that would be retrieved, and places it in the
  3428.           specified file. The resulting file is an ordinary text file,
  3429.           with one filename per line, suitable for reading by a person, or
  3430.           processing by a computer program, including Kermit itself (FOPEN
  3431.           / FREAD / FWRITE / FCLOSE), and as /FILELIST: file. If the
  3432.           filename is omitted or given as "-" (dash, hyphen), the list
  3433.           goes to the screen. NOTE: if you want a copy of the complete
  3434.           list sent by the server, use SET FTP DEBUG ON, perform an MGET,
  3435.           and the temporary file containing the list will be kept rather
  3436.           than deleted (and Kermit tells you its name).
  3437.  
  3438.    /UPDATE, /COLLISION:keyword
  3439.           Explained in [318]Section 3.6.2.
  3440.  
  3441.    /RECURSIVE
  3442.           This means to try to download an entire directory tree, rather
  3443.           than just files from a particular directory. In fact, FTP
  3444.           protocol does not provide a method to request a recursive
  3445.           download (unless the server supports MLSD; see [319]Section
  3446.           3.11), so this works only if the FTP server does it anyway,
  3447.           without being asked, as some do. In this case, Kermit detects
  3448.           that names in the returned file list contain directory
  3449.           separators, and therefore attempts to create the needed
  3450.           directories as the files arrive. But this can work only if the
  3451.           server is on the same kind of platform as the client, so the
  3452.           pathname syntax can be recognized, and also because the server
  3453.           does not switch between text and binary mode, which would be
  3454.           vital for cross-platform transfers. Use with caution. Synonym:
  3455.           /SUBDIRECTORIES.
  3456.  
  3457.           Even when the server does not provide recursive file lists,
  3458.           [M]GET /RECURSIVE forces Kermit to replicate any directory
  3459.           structure implied or expressed by the server's file list. For
  3460.           example:
  3461.  
  3462.   get somepath/somefile
  3463.  
  3464.           Gets the file named somefile from the server's somepath
  3465.           directory and puts it Kermit's current (or download) directory,
  3466.           whereas:
  3467.  
  3468.   get /recursive somepath/somefile
  3469.  
  3470.           creates the path locally and then puts the file in it. Similarly
  3471.           for MGET:
  3472.  
  3473.   mget */data/*
  3474.  
  3475.           downloads all the files in all the data subdirectories of all
  3476.           the subdirectories of the server's current directory and stores
  3477.           them locally in Kermit's current (or download) directory,
  3478.           whereas:
  3479.  
  3480.   mget /recursive */data/*
  3481.  
  3482.           re-creates the server's directory structure locally.
  3483.  
  3484.    The FTP protocol does not include explicit mechanisms for recursion, so
  3485.    Kermit builds upon what is available. Although an Internet draft
  3486.    describes a mechanism ("MLSD") that would allow protocol-driven
  3487.    recursion, similar to Kermit's File Attribute packets (circa 1984), it
  3488.    has not yet attained RFC or standard status, and servers are not yet
  3489.    widely available that offer this feature. In the meantime, the
  3490.    effectiveness of MGET /RECURSIVE depends on the FTP server
  3491.    implementation. If the server returns a recursive list in response to
  3492.    the standard NLST command (whose behavior is ill-defined), Kermit's FTP
  3493.    MGET /RECURSIVE command uses it to re-create the remote directory tree
  3494.    locally. If the server supports MLSD, C-Kermit 8.0.206 and Kermit 95
  3495.    2.1 and later are able to sense it automatically and use it, as
  3496.    described below in [320]Section 3.11.
  3497.  
  3498.    The /BEFORE:, /AFTER:, /NOT-BEFORE:, and /NOT-AFTER: switches are not
  3499.    available for downloading because of the confusion with timezones.
  3500.    Would the given times be in the local timezone, the server's timezone,
  3501.    or GMT? The FTP server's directory listings show its own local times
  3502.    but since we don't know what timezone the server is in, there's no way
  3503.    to reconcile our local times with the server's. Similarly, /PERMISSIONS
  3504.    can't be preserved in downloads because FTP protocol provides no means
  3505.    of querying the server for a file's permission.
  3506.  
  3507.    Source-file disposition switches:
  3508.  
  3509.    /DELETE
  3510.           Each file that is downloaded successfully is to be deleted from
  3511.           the server. Requires the appropriate file access rights on the
  3512.           server.
  3513.  
  3514.    /SERVER-RENAME-TO:template
  3515.           Asks the server to rename each (remote) source file immediately
  3516.           after, and only if, it is sent correctly. See [321]PUT
  3517.           /SERVER-RENAME-TO: for details.
  3518.  
  3519.    Destination-file disposition switches:
  3520.  
  3521.    /TO-SCREEN
  3522.           Displays the incoming file on the screen rather than storing it
  3523.           on disk. If this switch is given, the /RENAME-TO and /MOVE-TO
  3524.           switches are ignored, the file-transfer display is suppressed,
  3525.           and the given file(s) is/are shown on the screen. Can be used
  3526.           with /FILTER, e.g.
  3527.  
  3528.   get /text /to-screen /filter:more oofa.txt
  3529.  
  3530.           In fact, you should always use /TO-SCREEN with /FILTER or
  3531.           /COMMAND when the command would result in displaying the
  3532.           incoming file on the screen; otherwise C-Kermit would have no
  3533.           way of knowing to suppress its file transfer display (since it
  3534.           can't be expected to know what the command or filter does).
  3535.  
  3536.    /RENAME-TO:template
  3537.           Each file that is downloaded is to be renamed as indicated if
  3538.           and only if it was received completely and without error. The
  3539.           template can be literal text or can contain variables that are
  3540.           evaluated for each file. For MGET, the text must contain
  3541.           variables; for GET it can be a literal string. The \v(filename)
  3542.           variable contains the name of the current file, so:
  3543.  
  3544.   ftp mget /rename-to:\v(filename).ok *
  3545.  
  3546.           causes each file that is successfully downloaded to have ".ok"
  3547.           appended to its name. For details see [322]Section 4.1 of the
  3548.           [323]C-Kermit 7.0 Update Notes.
  3549.  
  3550.    /MOVE-TO:text
  3551.           Just like /RENAME-TO:, except the text denotes the name of a
  3552.           directory to which successfully downloaded files are to be
  3553.           moved. If the directory does not exist, it is created.
  3554.  
  3555.    The file transfer display does not show the /MOVE-TO or /RENAME-TO
  3556.    value, since the incoming file has not yet been moved or renamed.
  3557.  
  3558. 3.6.2. Filename Collisions
  3559.  
  3560.    What should happen if an incoming file has the same name as an existing
  3561.    file in the same directory? By default, Kermit's FILE COLLISION setting
  3562.    applies: BACKUP, RENAME, UPDATE, DISCARD, etc, as described in
  3563.    [324]Using C-Kermit. Kermit's default FILE COLLISION setting is BACKUP
  3564.    (rename the existing file and store the incoming file under its own
  3565.    name) and therefore this is also the default FTP collision action.
  3566.  
  3567.    The name under which an incoming file is to be stored is determined as
  3568.    follows:
  3569.  
  3570.      * If an as-name was given, the as-name is used. Otherwise:
  3571.      * If the client and server platforms are alike or [325]FTP FILENAMES
  3572.        is set to LITERAL (or the /FILENAMES:LITERAL switch was given for
  3573.        this download), the incoming filename is used literally. Otherwise:
  3574.      * The incoming filename is converted to a form that is friendly to
  3575.        the local platform. For UNIX, for example, incoming filenames that
  3576.        are all uppercase (as they might be from, say, VMS or an IBM
  3577.        mainframe) are converted to lowercase.
  3578.  
  3579.    If the resulting name coincides with the name of a local file that
  3580.    already exists, we have a filename collision. Collisions are handled
  3581.    according to the currently selected collision action:
  3582.  
  3583.    SET FTP COLLISION { BACKUP, RENAME, UPDATE, DISCARD, APPEND, OVERWRITE
  3584.           }
  3585.           This establishes a filename collision for FTP, separate from the
  3586.           Kermit one. The initial FTP collision setting is inherited from
  3587.           Kermit's FILE COLLISION setting when the first FTP command is
  3588.           given, but subsequent changes to Kermit's FILE COLLISION setting
  3589.           do not affect the FTP COLLISION setting. SHOW FTP tells the
  3590.           current FTP COLLISION setting.
  3591.  
  3592.    FTP GET /COLLISION:{BACKUP,RENAME,UPDATE,DISCARD,APPEND,OVERWRITE}
  3593.           Overrides the current FTP COLLISION action for this download
  3594.           only.
  3595.  
  3596.    FTP GET /UPDATE
  3597.           This is equivalent to GET /COLLISION:UPDATE, and is included for
  3598.           symmetry with PUT /UPDATE
  3599.  
  3600.    FTP GET /UPDATE and /COLLISION:UPDATE mean to download only those files
  3601.    whose modification dates on the server are later than those on the
  3602.    client. Date-time comparisons are done in Coordinated Universal Time
  3603.    (UTC, GMT, ZULU). The command:
  3604.  
  3605.      FTP MGET /COLLISION:APPEND /AS-NAME:newfilename *.*
  3606.  
  3607.    Downloads all matching remote files into a single local file (in
  3608.    whatever order the server sends them).
  3609.  
  3610. 3.6.3. Recovery
  3611.  
  3612.    Recovery is available for downloads too, but there are some differences
  3613.    from the uploading case described in [326]Section 3.5.3:
  3614.  
  3615.      * The transfer must be in BINARY mode. It can not be in text mode,
  3616.        even if the FTP server is on the same kind of platform as Kermit,
  3617.        and even if there is no character-set translation. The original
  3618.        download must also have been in binary mode.
  3619.      * The FTP server must support the REST ("restart") directive.
  3620.        Unfortunately, this is not a standard command; at this writing, it
  3621.        is described only in an Internet Draft, not an RFC or Internet
  3622.        Standard, but nevertheless it is found in several popular FTP
  3623.        servers, such as [327]ProFTPD.
  3624.  
  3625.    Here's how download recovery works:
  3626.  
  3627.      * Kermit checks for conflicting switches, such as /UPDATE, /COMMAND,
  3628.        or /FILTER. If /RECOVER is given with these switches an error
  3629.        occurs.
  3630.      * The prevailing transfer mode (SET FTP TYPE) must be BINARY. If it
  3631.        is not, the /BINARY switch must have been included with the FTP
  3632.        [M]GET command.
  3633.  
  3634.    If the /RECOVER switch is accepted, then for each selected file:
  3635.  
  3636.      * A SIZE command is sent for the file (using its remote name). If the
  3637.        reply indicates the file was not found, or the SIZE command was not
  3638.        understood, or any other kind of error, recovery is canceled (i.e.
  3639.        the entire file is downloaded).
  3640.      * If the sizes of the two files are identical, the file is not sent.
  3641.        Otherwise:
  3642.      * Kermit sends the REST directive to the server, indicating the size
  3643.        of the local file. If the server responds affirmatively, Kermit
  3644.        opens the local file in append mode and appends the incoming data
  3645.        to it. Otherwise, recovery is canceled and the entire file is
  3646.        downloaded.
  3647.  
  3648.    The /RECOVER switch can be included with any FTP GET or MGET command,
  3649.    even if it specifies a group of files. This lets you resume an
  3650.    interrupted batch transfer from where it left off. The files that were
  3651.    already completely sent are skipped, the file that was interrupted is
  3652.    recovered, and the remaining files are uploaded. BUT... unlike with
  3653.    uploading, where this can be done with any mixture of text and binary
  3654.    files, when downloading, it can only be done if all the files are
  3655.    binary.
  3656.  
  3657.    It doesn't matter how the original partial file was downloaded -- FTP,
  3658.    Kermit, HTTP, Zmodem, etc: as long as the preconditions are met, it can
  3659.    be recovered with FTP [M]GET /RECOVER, or for that matter also with GET
  3660.    /RECOVER (using Kermit protocol).
  3661.  
  3662.    [ [328]Top ] [ [329]FTP Top ] [ [330]C-Kermit Home ] [ [331]Kermit Home
  3663.    ]
  3664.  
  3665. 3.7. Translating Character Sets
  3666.  
  3667.    A possibly unique feature of Kermit's FTP client is its ability to
  3668.    convert character sets when transferring files in text mode,
  3669.    independent of the capabilities of the FTP server, as well as to
  3670.    translate the character sets of filenames regardless of transfer mode.
  3671.    For compatibility with existing FTP clients, and because there is a
  3672.    certain performance penalty, Kermit won't do this unless you ask for
  3673.    it. If you enable this feature, you need to inform Kermit of the
  3674.    character set (to be) used on the server and in some cases (explained
  3675.    below) also the local file character set. This discussion assumes you
  3676.    know a bit about character sets (as you must if you have to use them);
  3677.    see Chapter 16 of [332]Using C-Kermit for a detailed treatment. The
  3678.    Kermit commands for FTP character-set conversion are:
  3679.  
  3680.    SET FTP CHARACTER-SET-TRANSLATION { ON, OFF }
  3681.           Whether to translate character sets when transferring text files
  3682.           with FTP. OFF by default. Set this to ON to enable character-set
  3683.           translation for subsequent FTP uploads and downloads.
  3684.  
  3685.    SET FTP SERVER-CHARACTER-SET [333]name
  3686.           Text character set (to be) used by the server. Most FTP servers
  3687.           are ignorant of character sets, so all translations are done
  3688.           unilaterally by Kermit's FTP client. This means that when
  3689.           downloading files, you must know in advance the character-set
  3690.           used in the files you are downloading (and in their names). When
  3691.           uploading, you must specify the character-set to which local
  3692.           filenames and text-file contents are to be translated for
  3693.           transmission to the server. If you SET FTP
  3694.           CHARACTER-SET-TRANSLATION ON but do not specify an FTP
  3695.           SERVER-CHARACTER-SET, [334]UTF8 is used, since this is the new
  3696.           Internet standard international character set; it is upwards
  3697.           compatible with ASCII and it encompasses most written languages
  3698.           and therefore does not favor any particular group of people, as
  3699.           any other default would do. If you SET FTP SERVER-CHARACTER-SET
  3700.           to something (anything) when FTP CHARACTER-SET TRANSLATION is
  3701.           OFF, this also sets the latter ON.
  3702.  
  3703.    SET FILE CHARACTER-SET [335]name
  3704.           This is the regular Kermit (non-FTP-specific) command for
  3705.           identifying the character set (to be) used in local text files
  3706.           and filenames.
  3707.  
  3708.    TO REITERATE: If you SET FTP CHARACTER-SET TRANSLATION ON but do not
  3709.    specify an FTP SERVER-CHARACTER-SET, outbound text files are converted
  3710.    to UTF-8 and inbound text files are assumed to be UTF-8. If this is not
  3711.    appropriate, be sure to also specify the desired FTP
  3712.    SERVER-CHARACTER-SET.
  3713.  
  3714.    You can use "special" (non-ASCII) characters in filenames in all the
  3715.    client / server file management commands (FTP MKDIR, RMDIR, DIRECTORY,
  3716.    VDIRECTORY, DELETE, etc), and also in file-transfer commands. When
  3717.    giving commands such as FTP DIR (RDIR) and FTP PWD (RPWD), the reply is
  3718.    translated too, so you can read it. In this example, the client and
  3719.    server use entirely different codes to represent the special characters
  3720.    of German:
  3721.  
  3722.   C-Kermit> ftp xyzcorp.de /anonymous
  3723.   C-Kermit> set ftp server-character-set latin1
  3724.   C-Kermit> set file character-set german
  3725.   C-Kermit> rcd StΣdte
  3726.   C-Kermit> rpwd
  3727.   "/pub/ftp/StΣdte is current directory"
  3728.   C-Kermit> rdir
  3729.   -rw-rw----  1 olaf     54018 Jan  6 17:58 Adenbⁿttel.txt
  3730.   -rw-rw----  1 ursula     373 Jan  5 15:19 A▀lar.txt
  3731.   -rw-rw----  1 gisbert    482 Jan  5 15:20 Blowatz.txt
  3732.   -rw-rw----  1 gudrun     124 Jan  5 15:19 B÷blingen.txt
  3733.   -rw-rw----  1 olga     14348 Jan  7 14:23 K÷ln.txt
  3734.  
  3735.    When the client and server file systems use different character sets,
  3736.    you should take care to use only those characters that the two sets
  3737.    share in common when creating filenames or text-file contents. For
  3738.    example, PC code pages contain a lot line- and box-drawing characters,
  3739.    and sometimes "smart quotes", etc, that are not found in ISO standard
  3740.    8-bit character sets. You should be especially careful to avoid using
  3741.    such characters in filenames.
  3742.  
  3743.    [ [336]C-Kermit Character Sets ]
  3744.  
  3745. 3.7.1. Character Sets and Uploading
  3746.  
  3747.    Kermit's PUT and MPUT commands include full file-scanning capabilities,
  3748.    as described in [337]Section 4. Thus if FTP CHARACTER-SET-TRANSLATION
  3749.    is ON and your character-set associations are set up appropriately,
  3750.    Kermit automatically switches on a per-file basis between text and
  3751.    binary mode, and for each text file between your chosen 7-bit text
  3752.    character set (e.g. ASCII or ISO 646 German), 8-bit text (e.g. Latin-1
  3753.    or Japanese EUC), UCS-2, and UTF-8, and converts each of these
  3754.    automatically to the server character-set, and furthermore
  3755.    automatically differentiates between the Little and Big Endian forms of
  3756.    UCS-2, always sending in Big Endian form.
  3757.  
  3758.      WARNING: It is not advisable to use UCS-2 (or any Unicode
  3759.      transformation other than UTF-8) "on the wire", i.e. as a server
  3760.      character set. Most FTP servers are not able to cope with it, since
  3761.      it contains lots of 0 (NUL) characters. If you do use it, Kermit
  3762.      does not translate filenames to or from UCS-2, for reasons well
  3763.      known to C programmers (for example, UNIX APIs assume filename
  3764.      strings are NUL-terminated). [338]UTF-8 is the preferred (and
  3765.      standard) Unicode format for the Internet.
  3766.  
  3767.    FTP character-set translations differ from the regular Kermit ones by
  3768.    not restricting translations to a file-character-set /
  3769.    transfer-character-set pair. You can have Kermit's FTP client translate
  3770.    between any pair of character sets it knows about. You can see the list
  3771.    of supported character sets by typing either of the following:
  3772.  
  3773.   set ftp server-character-set ?
  3774.   set file character-set ?
  3775.  
  3776.    A typical list looks like this ([339]CLICK HERE for an explanation of
  3777.    the names):
  3778.  
  3779.   C-Kermit>set file char ? One of the following:
  3780.    ascii            cp869-greek       hebrew-7         mazovia-pc
  3781.    british          cyrillic-iso      hebrew-iso       next-multinational
  3782.    bulgaria-pc      danish            hp-roman8        norwegian
  3783.    canadian-french  dec-kanji         hungarian        portuguese
  3784.    cp1250           dec-multinational iso2022jp-kanji  shift-jis-kanji
  3785.    cp1251-cyrillic  dg-international  italian          short-koi
  3786.    cp1252           dutch             jis7-kanji       spanish
  3787.    cp437            elot927-greek     koi8             swedish
  3788.    cp850            elot928-greek     koi8r            swiss
  3789.    cp852            euc-jp            koi8u            ucs2
  3790.    cp855-cyrillic   finnish           latin1-iso       utf8
  3791.    cp858            french            latin2-iso
  3792.    cp862-hebrew     german            latin9-iso
  3793.    cp866-cyrillic   greek-iso         macintosh-latin
  3794.   C-Kermit>
  3795.  
  3796.    Thus you can translate not only between private sets (like PC code
  3797.    pages) and standard ones (like Latin-1) as in Kermit protocol, but also
  3798.    between any given pair of private sets (e.g. CP852 and Mazovia). All
  3799.    conversions go through Unicode as the intermediate character set,
  3800.    resulting in a minimum of character loss, since Unicode is a superset
  3801.    of all other character sets known to Kermit.
  3802.  
  3803.    In addition to the SET commands listed above, the FTP PUT and MPUT
  3804.    commands include switches that apply only to the current command:
  3805.  
  3806.    /LOCAL-CHARACTER-SET:name
  3807.    /SERVER-CHARACTER-SET:name
  3808.           Use these switches to force a particular translation. These
  3809.           switches override the global FTP CHARACTER-SET-TRANSLATION and
  3810.           SERVER-CHARACTER-SET settings and also character-set
  3811.           differentiation by file scanning for the duration of the PUT or
  3812.           MPUT command. The file scan is still performed, however, to
  3813.           determine whether the file is text or binary; thus these
  3814.           switches do not affect binary files unless you also include the
  3815.           /TEXT switch to force all files to be treated as text.
  3816.  
  3817.    In other words, if you include one or both of these switches with a PUT
  3818.    or MPUT command, they are used. Similarly, the /TRANSPARENT switch
  3819.    disables character-set translation for the PUT or MPUT command despite
  3820.    the prevailing FTP CHARACTER-SET-TRANSLATION and SERVER-CHARACTER-SET
  3821.    settings.
  3822.  
  3823.    When uploading, the FILE CHARACTER-SET setting is ignored unless you
  3824.    have forced Kermit not to [340]scan local files by including a /TEXT or
  3825.    /BINARY switch with your [M]PUT command, or by disabling automatic
  3826.    text/binary switching in some other way.
  3827.  
  3828.    Examples:
  3829.  
  3830.     1. Suppose you have a CP852 (East European) text file that you want to
  3831.        upload and store in ISO Latin Alphabet 2 encoding:
  3832.   ftp put /local-char:cp852 /server-char:latin2 magyar.txt
  3833.  
  3834.     2. Suppose you always want your text files converted to Latin-2 when
  3835.        uploading with FTP. Then put:
  3836.   set ftp server-character-set latin2
  3837.  
  3838.        in your Kermit customization file, and then you can omit the
  3839.        /SERVER-CHARACTER-SET: switch from your FTP PUT commands:
  3840.   ftp put /local-char:cp852 magyar.txt
  3841.  
  3842.     3. Now suppose that all the text files on your PC are written in
  3843.        Hungarian, but they have a variety of encodings, and you don't want
  3844.        to have to include the /LOCAL-CHARACTER-SET: switch on every FTP
  3845.        PUT command, or (more to the point) you want to be able to send a
  3846.        mixture of these files all at once. Put these commands in your
  3847.        Kermit customization file:
  3848.   set ftp server-character-set latin2            ; ISO 8859-2
  3849.   set file default 7-bit-character-set hungarian ; ISO 646 Hungarian
  3850.   set file default 8-bit-character-set cp852     ; PC East European Code Page
  3851.  
  3852.        and now PUT and MPUT will automatically detect and switch among ISO
  3853.        646 Hungarian, Code Page 852, UTF-8, and UCS-2 encodings,
  3854.        translating each one to Latin-2 for uploading:
  3855.   ftp put *.txt
  3856.  
  3857.    And since binary files are also detected automatically, the latter can
  3858.    be simplified to:
  3859.  
  3860.   ftp put *
  3861.  
  3862.    even when "*" matches a diverse collection of binary and text files,
  3863.    because translations are skipped automatically for binary files.
  3864.  
  3865. 3.7.2. Character Sets and Downloading
  3866.  
  3867.    The commands and switches are the same as for uploading, but automatic
  3868.    character-set switching works differently, since Kermit can't scan the
  3869.    server files in advance. Instead, the transfer mode (text or binary) is
  3870.    based on the filenames; each name is compared with Kermit's list of
  3871.    text name patterns and binary name patterns. If the name matches a
  3872.    binary pattern (for example, if the filename is oofa.tar.gz and one of
  3873.    the filename patterns is "*.gz"), the file is downloaded in binary
  3874.    mode; otherwise if it matches a text pattern (e.g. oofa.txt matches
  3875.    "*.txt"), it is transferred in text ("ascii") mode. Otherwise, it is
  3876.    transferred in the prevailing FTP TYPE.
  3877.  
  3878.    In C-Kermit 8.0, the pattern lists used with FTP GET are not the same
  3879.    lists used with Kermit transfers, and can not be viewed with SHOW
  3880.    PATTERNS, nor adjusted with ADD and REMOVE TEXT-PATTERNS and
  3881.    BINARY-PATTERNS, or SET FILE TEXT-PATTERNS and BINARY-PATTERNS.
  3882.    Configuration of the FTP patterns list will be added in a future
  3883.    release.
  3884.  
  3885.    Examples:
  3886.  
  3887.    get /server-char:latin1 /local-char:cp850 Grⁿ▀e.txt
  3888.           In this command, the filename contains special characters, which
  3889.           you enter using whatever character set your local computer uses,
  3890.           in this case PC Code Page 850 (cp850). The command tells Kermit
  3891.           (in case it didn't know already from its FILE CHARACTER-SET
  3892.           setting) that the local character set is cp850 and the server's
  3893.           character-set is ISO 8859-1 Latin Alphabet 1 (latin1). Kermit
  3894.           translates the filename from cp850 to latin1 and sends the
  3895.           latin1 name to the server. Since it's a text file (matches
  3896.           "*.txt"), its contents are translated to cp850 on arrival, and
  3897.           it is saved with a cp850 name.
  3898.  
  3899.    mget /text /server:latin1 /local:utf8 *.txt
  3900.           This command:
  3901.  
  3902.           + Tells C-Kermit that the server's files are encoded in ISO
  3903.             8859-1 Latin Alphabet 1.
  3904.           + Tells C-Kermit to translate the incoming files into Unicode
  3905.             UTF-8 for storage.
  3906.           + Asks the server to send all ".txt" files in text mode.
  3907.  
  3908.    mget /server:latin1 /local:utf8 *
  3909.           Tells Kermit to get all files from the server's directory,
  3910.           switching between text and binary mode based on the filename.
  3911.           The names of all the files are translated (to UTF-8 in this
  3912.           case), but contents are translated (also to UTF-8) only for text
  3913.           files.
  3914.  
  3915.    Note that any pair of 8-bit character sets is likely to have some
  3916.    incompatibilities. Any characters in the source file that do not have
  3917.    equivalents in the destination file's character set are converted to
  3918.    question marks. This applies to both filenames and to text file
  3919.    contents.
  3920.  
  3921.    Also note that the server's ability to accept special characters in
  3922.    filenames depends on the particular server. For example:
  3923.  
  3924.   get Grⁿ▀e.txt
  3925.  
  3926.    works with WU-FTPD, but:
  3927.  
  3928.   mget Grⁿ▀*.txt
  3929.  
  3930.    does not.
  3931.  
  3932. 3.7.3. RFC2640
  3933.  
  3934.    [341]RFC2640, July 1999, specifies a method by which the FTP client and
  3935.    server can negotiate the use of UTF8. However, RFC2640-capable servers
  3936.    are rare to nonexistent at this writing, and in any case you don't need
  3937.    them to be able to transfer text in UTF8. C-Kermit lets you upload and
  3938.    download text files in any character set it knows about, converting to
  3939.    or from any other character set it knows about, without the knowledge,
  3940.    permission, or cooperation of the server, and regardless of its
  3941.    capabilities.
  3942.  
  3943.    [ [342]Top ] [ [343]FTP Top ] [ [344]C-Kermit Home ] [ [345]Kermit Home
  3944.    ]
  3945.  
  3946. 3.8. FTP Command Shortcuts
  3947.  
  3948.    C-Kermit's FTP client coexists with other C-Kermit functions by
  3949.    requiring the "ftp" prefix for each FTP-related command: FTP OPEN, FTP
  3950.    GET, FTP BYE, and so on. For interactive use, however, this can be
  3951.    rather awkward and sometimes surprising, for example when a GET command
  3952.    starts a Kermit GET rather than an FTP GET. In fact, many Kermit
  3953.    commands might just as easily apply to an FTP connection: GET, PUT
  3954.    (SEND), BYE, and CLOSE. The following command lets you choose how these
  3955.    commands are interpreted:
  3956.  
  3957.    SET GET-PUT-REMOTE { AUTO, KERMIT, FTP }
  3958.           Controls the orientation of GET, PUT, REMOTE and other
  3959.           file-transfer and client/server commands that might apply to
  3960.           either Kermit or FTP. The default setting is AUTO, meaning that
  3961.           these commands apply to FTP if an FTP connection is open, and to
  3962.           Kermit otherwise. KERMIT means they always apply to Kermit, FTP
  3963.           means they always apply to FTP.
  3964.  
  3965.    Here is a complete list of affected commands:
  3966.  
  3967.  Kermit Command               FTP Equivalent
  3968.   (none)                       FTP [ OPEN ]
  3969.   LOGIN                        FTP USER
  3970.   LOGOUT                       FTP RESET
  3971.   BYE                          FTP BYE
  3972.   FINISH                       FTP BYE
  3973.   CLOSE                        FTP BYE
  3974.   HANGUP                       FTP BYE
  3975.   BINARY                       FTP TYPE BINARY
  3976.   TEXT (or ASCII)              FTP TYPE ASCII
  3977.   SEND (or PUT)                FTP PUT
  3978.   MSEND (or MPUT)              FTP MPUT
  3979.   RESEND                       FTP PUT /RECOVER
  3980.   CSEND                        FTP PUT /COMMAND
  3981.   GET                          FTP GET
  3982.   MGET                         FTP MGET
  3983.   REGET                        FTP GET /RECOVER
  3984.   REMOTE HELP      (RHELP)     FTP HELP
  3985.   REMOTE CD        (RCD)       FTP CD (CWD)
  3986.   REMOTE PWD       (RPWD)      FTP PWD
  3987.   REMOTE DIRECTORY (RDIR)      FTP DIRECTORY
  3988.   REMOTE DELETE    (RDEL)      FTP DELETE
  3989.   REMOTE MKDIR     (RMKDIR)    FTP MKDIR
  3990.   REMOTE RMDIR     (RRMDIR)    FTP RMDIR
  3991.   REMOTE RENAME    (RRENAME)   FTP RENAME
  3992.   REMOTE TYPE      (RTYPE)     FTP TYPE
  3993.   REMOTE EXIT      (REXIT)     FTP BYE
  3994.  
  3995.    The commands in the right-hand column always access FTP. The commands
  3996.    in the left column can access either Kermit protocol or FTP:
  3997.  
  3998.      * When GET-PUT-REMOTE is set to KERMIT, or to AUTO when there is no
  3999.        FTP connection, the commands in the left-hand column access Kermit
  4000.        protocol, and those right-hand column are required for FTP.
  4001.      * When GET-PUT-REMOTE is set to FTP, or to AUTO when there is an
  4002.        active FTP connection, the commands in the left-hand column access
  4003.        the FTP connection and can not be used to access Kermit protocol.
  4004.        In this case, if you want to be able to use both Kermit protocol
  4005.        and the FTP connection, you must SET GET-PUT-REMOTE KERMIT, and
  4006.        then use the FTP commands in the right-hand column to access the
  4007.        FTP connection.
  4008.  
  4009.    Note that file-management commands such as DIRECTORY, DELETE, CD, PWD,
  4010.    MKDIR, RMDIR, HELP, RENAME, COPY, TYPE, and so on, always apply
  4011.    locally, no matter what kind of connection you have. This is the
  4012.    opposite of most FTP clients, where these commands are intended for the
  4013.    server, and require an "L" prefix for local execution (e.g. "dir" gets
  4014.    a directory listing from the server, "ldir" gets a local directory
  4015.    listing). To illustrate with the CD command and a typical UNIX FTP
  4016.    client:
  4017.  
  4018.  Client   Server      Change Local Directory     Change Remote Directory
  4019.   FTP      FTP         lcd                        cd (cwd)
  4020.   Kermit   Kermit      cd                         rcd, remote cd
  4021.   Kermit   FTP         cd                         ftp cd, rcd, remote cd
  4022.  
  4023.    Also note that not all REMOTE commands are useful with FTP, since FTP
  4024.    servers do not offer the corresponding functions. These include:
  4025.  
  4026.      * REMOTE ASSIGN  - FTP servers don't have variables
  4027.      * REMOTE COPY    - FTP servers don't copy files
  4028.      * REMOTE HOST    - FTP servers don't execute host (shell) commands
  4029.      * REMOTE KERMIT  - FTP servers don't execute Kermit commands
  4030.      * REMOTE PRINT   - FTP servers don't print files
  4031.      * REMOTE QUERY   - FTP servers don't have variables
  4032.      * REMOTE SET     - FTP servers don't have Kermit settings
  4033.      * REMOTE WHO     - FTP servers don't send user lists
  4034.  
  4035.    Finally note that command shortcuts do not apply to the HELP command.
  4036.    For help about an FTP command, use (for example) "help ftp delete", not
  4037.    "help delete" or "help rdelete".
  4038.  
  4039.    [ [346]Top ] [ [347]FTP Top ] [ [348]C-Kermit Home ] [ [349]Kermit Home
  4040.    ]
  4041.  
  4042. 3.9. Dual Sessions
  4043.  
  4044.    You can have an FTP session open at the same time as a regular Kermit
  4045.    SET LINE or SET HOST (terminal) session. In this case, the default SET
  4046.    GET-PUT-REMOTE AUTO setting should ensure that all "two-faced" commands
  4047.    like GET, PUT, REMOTE, HANGUP, BYE, etc, apply to the Kermit session,
  4048.    and all commands for the FTP session must include the FTP prefix. To be
  4049.    absolutely certain, you can use SET GET-PUT-REMOTE KERMIT.
  4050.  
  4051.   ftp foo.bar.baz.com
  4052.   if fail ...
  4053.   (log in)
  4054.   set host foo.bar.baz.com
  4055.   if fail ...
  4056.   (log in)
  4057.  
  4058.    Now you have both an FTP and Telnet connection to the same host (of
  4059.    course they could also be to different hosts, and you could also have a
  4060.    direct or dialed serial connection instead of a Telnet connection). Now
  4061.    assuming you have a Kermit server on the far end of the Kermit
  4062.    connection:
  4063.  
  4064.   rcd incoming      ; Changes Kermit server's directory (= REMOTE CD)
  4065.   ftp cd incoming   ; Changes FTP server's directory
  4066.   put oofa.txt      ; Sends a file on the Kermit connection
  4067.   ftp put oofa.txt  ; Sends a file on the FTP connection
  4068.   bye               ; Shuts down the Kermit connection
  4069.   ftp bye           ; Shuts down the FTP connection
  4070.  
  4071.    Note that PUT and SEND are synonyms for both FTP and Kermit
  4072.    connections.
  4073.  
  4074.    You can also establish dual sessions on the Kermit command line:
  4075.  
  4076.   kermit -j host1 -9 host2
  4077.  
  4078.    This makes a Telnet connection to host1 and an FTP connection to host2.
  4079.  
  4080.    [ [350]Top ] [ [351]FTP Top ] [ [352]C-Kermit Home ] [ [353]Kermit Home
  4081.    ]
  4082.  
  4083. 3.10. Automating FTP Sessions
  4084.  
  4085.    Most of Kermit's scripting features can be used to make and control FTP
  4086.    sessions: FOR and WHILE loops, IF-ELSE and SWITCH constructions,
  4087.    variables, arrays, built-in functions, and all the rest. You can't use
  4088.    INPUT, MINPUT, OUTPUT, CLEAR, or SCRIPT on an FTP session, but these
  4089.    are not needed since the FTP protocol is well defined.
  4090.  
  4091.    [354]CLICK HERE for an FTP scripting tutorial.
  4092.  
  4093. 3.10.1. FTP-Specific Variables and Functions
  4094.  
  4095.    The following variable tells whether an FTP connection is open:
  4096.  
  4097.    \v(ftp_connected)
  4098.           1 if there is an active FTP connection, 0 if there isn't.
  4099.  
  4100.    The FTP OPEN command sets:
  4101.  
  4102.    \v(ftp_host)
  4103.           The host to which the most recent FTP connection was made.
  4104.  
  4105.    \v(ftp_security)
  4106.           The security method negotiated for the current FTP session. The
  4107.           value is "NULL" when no security is used. Other possibilities
  4108.           are GSSAPI, KERBEROS_V4, SSL, TLS, and SRP. Also see
  4109.           \v(authname), \v(authstate), and \v(authtype). See [355]3.2.
  4110.           Making Secure FTP Connections.
  4111.  
  4112.    \v(ftp_server)
  4113.           The OS type (UNIX, VMS, etc) of the FTP server host.
  4114.  
  4115.    The FTP USER command (or FTP OPEN /USER:, or FTP with automatic login)
  4116.    sets:
  4117.  
  4118.    \v(ftp_loggedin)
  4119.           1 if you are logged in to an FTP server, 0 if you are not.
  4120.  
  4121.    The current COMMAND-PROTECTION-LEVEL and DATA-PROTECTION-LEVEL values
  4122.    are reflected in:
  4123.  
  4124.    \v(ftp_cpl)
  4125.    \v(ftp_dpl)
  4126.           The values are "clear", "confidential", "safe" or "private". See
  4127.           [356]3.2. Making Secure FTP Connections.
  4128.  
  4129.    The FTP GET-PUT-REMOTE setting is reflected in:
  4130.  
  4131.    \v(ftp_getputremote)
  4132.           The values are "auto", "ftp", or "kermit".
  4133.  
  4134.    Every FTP command sets the \v(success) variable, as well as the
  4135.    following two FTP-specific variables:
  4136.  
  4137.    \v(ftp_code)
  4138.           The standardized numeric FTP protocol code from the server's
  4139.           response to the last client command, a 3-digit decimal number
  4140.           defined in [357]RFC959. Briefly:
  4141.  
  4142.           1xx = Positive Preliminary Reply
  4143.           2xx = Positive Completion Reply
  4144.           3xx = Positive Intermediate Reply
  4145.           4xx = Transient Negative Completion Reply
  4146.           5xx = Permanent Negative Completion Reply
  4147.  
  4148.    \v(ftp_message)
  4149.           The text message, if any, from the server's response to the last
  4150.           client command. If the most recent response had multiple lines,
  4151.           this variable has only the final line. These messages are not
  4152.           standardized and vary in format and content from server to
  4153.           server. Synonym: \v(ftp_msg).
  4154.  
  4155.    FTP file transfers set the regular Kermit transfer status variables:
  4156.  
  4157.   \v(cps)         Characters per second of most recent transfer.
  4158.   \v(filespec)    File specification used in most recent transfer.
  4159.   \v(fsize)       Size of file most recently transferred.
  4160.   \v(tfsize)      Total size of file group most recently transferred.
  4161.   \v(xferstatus)  Status of most recent transfer (0 = success, 1 = failure).
  4162.   \v(tftime)      Elapsed time of most recent transfer, in seconds.
  4163.  
  4164.    During an FTP transfer, the per-file variables are:
  4165.  
  4166.   \v(filename)    Name of current file.
  4167.   \v(filenumber)  Ordinal file number in group (1, 2, 3, ...)
  4168.  
  4169. 3.10.2. Examples
  4170.  
  4171.    Let's begin with a simple example showing how to log in, send some
  4172.    files, and log out:
  4173.  
  4174.   define error if fail { ftp bye, stop 1 Error: \%1 }
  4175.   set transact brief
  4176.   log t
  4177.   ftp ftp.xyzcorp.com /anonymous
  4178.   if fail stop 1 Connection failed
  4179.   if not \v(ftp_loggedin) stop 1 Login failed
  4180.   ftp cd incoming
  4181.   error {ftp cd}
  4182.   cd upload
  4183.   error {local cd}
  4184.   ftp put /delete *
  4185.   error {put}
  4186.   ftp bye
  4187.  
  4188.    First we define an error handling macro to be used after the connection
  4189.    is made. Then we set up a brief-format transaction log to keep a record
  4190.    of our file transfers. Then we make a connection to the host and log in
  4191.    anonymously. The "if fail" command checks whether the connection was
  4192.    made. The "if not" command checks whether login was successful.
  4193.    Obviously the script should not continue unless both tests succeed.
  4194.  
  4195.    Next we change to the server's 'incoming' directory and to our own
  4196.    'upload' directory, and send all the files that are in it (they can be
  4197.    any mixture of text and binary files), deleting each source file
  4198.    automatically after it is successfully uploaded. Each of these
  4199.    operations is checked with the ERROR macro, which prevents the script
  4200.    from continuing past a failure.
  4201.  
  4202.    Finally we close the FTP session with the "bye" command.
  4203.  
  4204.    Just like any other Kermit script, this one can be used in many ways:
  4205.  
  4206.      * It can be stored in a file, and Kermit can be told to TAKE the
  4207.        file.
  4208.      * In UNIX, it can be a "[358]kerbang" script and therefore run
  4209.        directly from the shell prompt or as a cron job.
  4210.  
  4211.    We could have used command shortcuts like "rcd", "put", and "bye", but
  4212.    since they can be ambiguous under certain circumstances, it is better
  4213.    to avoid them in scripts; they are intended mainly for convenience
  4214.    during interactive use. However, if you wish to use the shortcuts in a
  4215.    script, you can do it this way (error handling omitted for brevity):
  4216.  
  4217.   local \%t                       ; Declare a local temporary variable
  4218.   assign \%t \v(ftp_getputremote) ; Save current FTP GET-PUT-REMOTE setting
  4219.   set ftp get-put-remote ftp      ; Choose FTP orientation
  4220.   ftp xyzcorp.com /anonymous      ; Open an FTP connection
  4221.   get oofa.txt                    ; GET a file
  4222.   put foo.bar                     ; PUT a file
  4223.   rdel yesterday.log              ; Delete a file on the server
  4224.   bye                             ; Log out and disconnect from server.
  4225.   set ftp get-put-remote \%t      ; Restore previous GET-PUT-REMOTE setting
  4226.  
  4227.    Of course, FTP scripts can also be written as macros. This lets you
  4228.    pass parameters such as hostnames, usernames, and filenames to them:
  4229.  
  4230.   define doftpget {
  4231.       if < \v(argc) 4 end 1 Usage: \%0 host user remotefile [ localfile ]
  4232.       ftp \%1 /user:\%2
  4233.       if fail end 1 FTP OPEN \%1 failed
  4234.       if not \v(ftp_loggedin) end 1 FTP LOGIN failed
  4235.       ftp get {\%3} {\%4}
  4236.       if fail end 1 FTP GET \%3 failed
  4237.       ftp bye
  4238.   }
  4239.  
  4240.    Add this definition to your Kermit customization file, and it will
  4241.    always be available when you start Kermit. This macro lets you download
  4242.    a file with FTP by giving a single command, e.g.:
  4243.  
  4244.   doftpget xyzcorp.com anonymous oofa.txt
  4245.  
  4246. 3.10.3. Automating Secure FTP Sessions
  4247.  
  4248.    Often when making secure connections, you are prompted interactively
  4249.    for certain information or permission to proceed. These prompts can
  4250.    stop an automated procedure. To avoid them, you must give the
  4251.    appropriate commands to disable them, and/or supply the prompted-for
  4252.    information beforehand. Here are a few hints:
  4253.  
  4254.      * Make sure that SET TAKE ERROR and SET MACRO ERROR are both OFF.
  4255.        This is the default, but in case you have set either one of these
  4256.        ON in your script or initialization file, this makes the script
  4257.        halt on any kind of error. Normally you would want to check each
  4258.        operation for success or failure and take appropriate action.
  4259.      * On SSL and TLS connections, you may be asked whether it is OK to
  4260.        proceed with a connection to server that presents a self-signed
  4261.        certificate. You can use the SET AUTHENTICATION SSL (or TLS) VERIFY
  4262.        or SET AUTH SSL (or TLS) CERTS-OK commands to avoid this prompt by
  4263.        not requesting a certificate from the peer.
  4264.      * (More to be added...)
  4265.  
  4266.    [ [359]Top ] [ [360]FTP Top ] [ [361]FTP Script Tutorial ] [
  4267.    [362]C-Kermit Home ] [ [363]Kermit Home ]
  4268.  
  4269. 3.11. Advanced FTP Protocol Features
  4270.  
  4271.    The remainder of the FTP documentation (through the end of Section 3)
  4272.    is new to C-Kermit 8.0.206, but we leave it in black to prevent
  4273.    headaches. Except for titles.
  4274.      * [364]TERMINOLOGY
  4275.      * [365]FEATURE NEGOTIATION
  4276.      * [366]USING MGET: NLST VERSUS MLSD
  4277.      * [367]EXAMPLES
  4278.      * [368]REFERENCES
  4279.  
  4280.    The new releases of [369]C-Kermit (8.0.206) and [370]Kermit 95 (2.1)
  4281.    support new FTP protocol features from RFC 2389 as well as most of
  4282.    what's in the Elz and Hethmon Extensions to FTP Internet Draft (see
  4283.    [371]References). Some of these features, such as SIZE (request a
  4284.    file's size), MDTM (request file's modification time), and REST
  4285.    (restart interrupted transfer) have been widely implemented in FTP
  4286.    clients and servers for years (as well as in the initial release of the
  4287.    Kermit FTP clients). Others such as FEAT and MLSD are rarely seen and
  4288.    are new to the upcoming Kermit releases. TVFS (Trivial Virtual File
  4289.    Store) is supported implicitly, and the UTF-8 character-set is already
  4290.    fully supported at the protocol and data-interchange level.
  4291.  
  4292.    For Kermit users, the main benefit of the new FTP protocol extensions
  4293.    is the ability to do recursive downloads. But the extensions also
  4294.    introduce complications and tradeoffs that you should be aware of. Of
  4295.    course Kermit tries to "do the right thing" automatically in every case
  4296.    for backwards compatibility. But (as noted later) some cases are
  4297.    inherently ambiguous and/or can result in nasty surprises, and for
  4298.    those situations new commands and switches are available to give you
  4299.    precise control over Kermit's behavior, in case the defaults don't
  4300.    produce the desired results.
  4301.  
  4302. 3.11.1. Terminology
  4303.  
  4304.    Command-line FTP clients such as Kermit (as well as the traditional FTP
  4305.    programs found on Unix, VMS, ..., even Windows) have commands like PUT,
  4306.    MPUT, GET, MGET, and BYE, which they convert into zero or more FTP
  4307.    protocol commands, such as NLST, RETR, QUIT. For clarity, we'll use
  4308.    "command" to refer to commands given by the user to the FTP client, and
  4309.    "directive" for FTP protocol commands sent by the FTP client to the FTP
  4310.    server.
  4311.  
  4312. 3.11.2. Feature Negotiation
  4313.  
  4314.    New FTP protocol features are negotiated by the client sending a FEAT
  4315.    directive and the server responding with a list of (new) features it
  4316.    supports, or else with an error indication if it does not support the
  4317.    FEAT directive at all, in which case the client has to guess which new
  4318.    features it supports (Kermit guesses that it supports SIZE and MDTM but
  4319.    not MLST). Note that the MLST feature includes MLSD, which is not
  4320.    listed separately as a feature.
  4321.  
  4322.    Guessing is nice when it works, but sometimes it doesn't, and some FTP
  4323.    servers become confused when you send them a directive they don't
  4324.    understand, or they do something you didn't want, sometimes to the
  4325.    point of closing the connection. For this reason, Kermit lets you
  4326.    override default or negotiated features with the following new
  4327.    commands:
  4328.  
  4329.    FTP { ENABLE, DISABLE } FEAT
  4330.           Enables or disables the automatic sending of a FEAT directive
  4331.           upon connection to an FTP server. Note that FTP [ OPEN ] /NOINIT
  4332.             also inhibits sending the FEAT directive (and several others)
  4333.           for the connection being OPEN'd, but without necessarily
  4334.           disabling FEAT for subsequent connections in the same Kermit
  4335.           instance. FEAT is ENABLED by default, in which case many FTP
  4336.           servers are likely to reply:
  4337.  
  4338. 500 'FEAT': command not understood
  4339.  
  4340.           which is normally harmless (but you never know). (In C-Kermit
  4341.           8.0.208, this error message is suppressed unless you SET FTP
  4342.           DEBUG ON.)
  4343.  
  4344.    FTP ENABLE { MDTM, MLST, SIZE }
  4345.           Enables the given directive for implicit use by the FTP GET and
  4346.           MGET commands in case it has been disabled or erroneously
  4347.           omitted by the server in its FEAT response. Note: MLSD can be
  4348.           used in the FTP ENABLE and DISABLE commands as a synonym for
  4349.           MLST. YOU MUST GIVE THIS COMMAND AFTER MAKING THE FTP
  4350.           CONNECTION.
  4351.  
  4352.    FTP DISABLE { MDTM, MLST, SIZE }
  4353.           Disables implicit use of the given directive by GET or MGET in
  4354.           case it causes problems; for example, because it makes multifile
  4355.           downloads take too long or the server announces it erroneously
  4356.           or misimplements it. Use DISABLE FEAT before making a connection
  4357.           to prevent Kermit from sending the FEAT directive as part of its
  4358.           initial sequence. Note that disabling FEAT, SIZE, or MDTM does
  4359.           not prevent you from executing explicit FTP FEATURES, FTP SIZE,
  4360.           or FTP MODTIME commands. Also note that disabling SIZE prevents
  4361.           PUT /RESTART (recovery of interrupted uploads) from working. YOU
  4362.           MUST GIVE THIS COMMAND AFTER MAKING THE FTP CONNECTION.
  4363.  
  4364.    To enable or disable more than one feature, use multiple FTP ENABLE or
  4365.    FTP DISABLE commands. The SHOW FTP command shows which features are
  4366.    currently enabled and disabled.
  4367.  
  4368.    FTP FEATURES
  4369.           This command sends a FEAT directive to the server. In case you
  4370.           have been disabling and enabling different features, this
  4371.           resynchronizes Kermit's feature list with the server's. If the
  4372.           server does not support the FEAT directive, Kermit's feature
  4373.           list is not changed.
  4374.  
  4375.    FTP OPTIONS directive
  4376.           Informational only: the server tells what options, if any, it
  4377.           supports for the given directive, e.g. MLST. Fails if the server
  4378.           does not support the OPTS directive or if the directive for
  4379.           which options are requested is not valid. The directive is
  4380.           case-insensitive.
  4381.  
  4382.    FTP SIZE filename
  4383.           Sends a SIZE directive to the server for the given file. The
  4384.           filename must not contain wildcards. The server responds with an
  4385.           error if the file can't be found, is not accessible, or the SIZE
  4386.           directive is not supported, otherwise with the length of the
  4387.           file in bytes, which Kermit displays and also makes available to
  4388.           you in its \v(ftp_message) variable. If the directive is
  4389.           successful, Kermit (re-)enables it for internal use by the GET
  4390.           and MGET directives on this connection.
  4391.  
  4392.    FTP MODTIME filename
  4393.           Works just like the SIZE directive except it sends an MDTM
  4394.           directive. Upon success, the server sends modification date-time
  4395.           string, which Kermit interprets for you and also makes available
  4396.           in its \v(ftp_message) variable.
  4397.  
  4398.    Whenever a SIZE or MDTM directive is sent implicitly and rejected by
  4399.    the server because it is unknown, Kermit automatically disables it.
  4400.  
  4401. 3.11.3. Using MGET: NLST versus MLSD
  4402.  
  4403.    When you give an MGET command to an FTP client, it sends a request to
  4404.    the FTP server for a list of files, and then upon successful receipt of
  4405.    the list, goes through it and issues a RETR (retrieve) directive for
  4406.    each file on the list (or possibly only for selected files).
  4407.  
  4408.    With the new FTP protocol extensions, now there are two ways to get the
  4409.    list of files: the NLST directive, which has been part of FTP protocol
  4410.    since the beginning, and the new MLSD directive, which is new and not
  4411.    yet widely implemented. When NLST is used and you give a command like
  4412.    "mget *.txt", the FTP client sends:
  4413.  
  4414. NLST *.txt
  4415.  
  4416.    and the server sends back a list of the files whose names match, e.g.
  4417.  
  4418. foo.txt
  4419. bar.txt
  4420. baz.txt
  4421.  
  4422.    Then when downloading each file, the client sends SIZE (if it wants
  4423.    have a percent-done display) and MDTM (if it wants to set the
  4424.    downloaded file's timestamp to match that of the original), as well as
  4425.    RETR (to retrieve the file).
  4426.  
  4427.    But when MLSD is used, the client is not supposed to send the filename
  4428.    or wildcard to the server; instead it sends an MLSD directive with no
  4429.    argument (or the name of a directory), and the server sends back a list
  4430.    of all the files in the current or given directory; then the client
  4431.    goes through the list and checks each file to see if it matches the
  4432.    given pattern, the rationale being that the user knows only the local
  4433.    conventions for wildcards and not necessarily the server's conventions.
  4434.    So with NLST the server interprets wildcards; with MLSD the client
  4435.    does.
  4436.  
  4437.      The interpretation of NLST wildcards by the server is not
  4438.      necessarily required or even envisioned by the FTP protocol
  4439.      definition (RFC 959), but in practice most clients and servers work
  4440.      this way.
  4441.  
  4442.    The principal advantage of MLSD is that instead of sending back a
  4443.    simple list of filenames, it sends back a kind of database in which
  4444.    each entry contains a filename together with information about the
  4445.    file: type, size, timestamp, and so on; for example:
  4446.  
  4447. size=0;type=dir;perm=el;modify=20020409191530; bin
  4448. size=3919312;type=file;perm=r;modify=20000310140400; bar.txt
  4449. size=6686176;type=file;perm=r;modify=20001215181000; baz.txt
  4450. size=3820092;type=file;perm=r;modify=20000310140300; foo.txt
  4451. size=27439;type=file;perm=r;modify=20020923151312; foo.zip
  4452. (etc etc...)
  4453.  
  4454.    (If the format of the file list were the only difference between NLST
  4455.    and MLSD, the discussion would be finished: it would always be better
  4456.    to use MLSD when available, and the MGET user interface would need no
  4457.    changes. But there's a lot more to MLSD than the file-list format; read
  4458.    on...)
  4459.  
  4460.    The client learns whether the server supports MLSD in FEAT exchange.
  4461.    But the fact that the server supports MLSD doesn't mean the client
  4462.    should always use it. It is better to use MLSD:
  4463.  
  4464.      * On connections where the server imposes a time penalty for every
  4465.        command, e.g. the Red Hat Rawhide server. With MLSD, the client
  4466.        needs to send only one command (RETR) per file, whereas NLST
  4467.        requires three (SIZE, RETR, and MDTM). Suppose there is a 30-second
  4468.        delay for each command and 1000 files are to be fetched; in that
  4469.        case, MLSD saves 60,000 seconds = 1000 minutes = 16 hours and 40
  4470.        minutes.
  4471.      * For recursive downloads since there is no dependable way to
  4472.        download directory trees with NLST.
  4473.  
  4474.    But it is better to use NLST:
  4475.  
  4476.      * If you want only a couple short files out of a large directory. In
  4477.        this case, NLST is the better choice since the server sends a list
  4478.        of only the files you want, not a list of (say) a million files,
  4479.        which can make a big difference on slow connections. For example,
  4480.        suppose your wildcard matches three files of 1K each, but the
  4481.        million-file listing is 80MB long, and your connection is through a
  4482.        modem. The overhead of using MLSD is practically infinite.
  4483.      * If the server supports wildcarding features not known to the
  4484.        client, but that can be used to achieve desirable effects otherwise
  4485.        unobtainable, such as "[dir...]*.txt" in VMS or AOS/VS "except"
  4486.        clauses.
  4487.      * If you have been given a wildcard string by an FTP site
  4488.        administrator for fetching a specific group of files out of a
  4489.        larger directory, e.g. "mget ck[cuw]*.[cwh] makefile", that is
  4490.        expected to work with any client (an FTP site administrator can't
  4491.        be expected to know the wildcard syntax of every FTP client).
  4492.  
  4493.    But when using MLSD there are complications:
  4494.  
  4495.      * MLSD wants either a blank argument (meaning the current directory)
  4496.        or else the name of a specific directory. The client must not send
  4497.        it a wildcard or a filename.
  4498.      * But if the user's command is "mget xxx", how does the client know
  4499.        whether to send "xxx" in the MLSD directive? It might be the name
  4500.        of a directory on on the server, in which case it should be sent,
  4501.        or it might be the name of a file on the server (or a wildcard), in
  4502.        which case it must not be sent. Since the client knows its own
  4503.        wildcard syntax, then in most cases it would be right to send
  4504.        "MLSD" with no argument if xxx is wild, and to send "MLSD xxx" if
  4505.        it is not.
  4506.      * But suppose the server's file system allows filename characters
  4507.        that correspond with the client's wildcard syntax? For example:
  4508.        "[abc]" could be either a valid VMS directory name or a wildcard
  4509.        pattern used by the FTP client. What should the client do with
  4510.        "mget [abc]"? In this case there must be a way for the user to
  4511.        force sending the MGET argument as the MLSD argument.
  4512.      * If "xxx" is a regular file in the server's current directory, "mget
  4513.        xxx" works with NLST but not with MLSD.
  4514.  
  4515.    To further complicate matters, NLST can (in theory) work just like
  4516.    MLSD: if sent with a blank argument or a directory name, it is supposed
  4517.    to return a complete list of files in the current or given directory,
  4518.    which the client can match locally against some pattern. It is not
  4519.    known if any FTP server or client does this but nevertheless, it should
  4520.    be possible since this behavior can be inferred from RFC 959.
  4521.  
  4522.    In view of these considerations, and given the need to preserve the
  4523.    traditional FTP client command structure and behavior so the software
  4524.    will be usable by most people:
  4525.  
  4526.     1. The MGET command should produce the expected result in the common
  4527.        cases, regardless of whether NLST or MLSD is used underneath.
  4528.     2. For anomalous cases, the user needs a way to control whether the
  4529.        MGET argument is sent to the server or kept for local use.
  4530.     3. At the same time, the user might need a way to send a directory
  4531.        name to the server, independent of any wildcard pattern.
  4532.     4. The user needs a way to force NLST or MLSD for a given MGET
  4533.        command.
  4534.  
  4535.    By default, Kermit's MGET command uses MLSD if MLST is reported by the
  4536.    server in its FEAT list. When MLSD is used, the filespec is sent to the
  4537.    server if it is not wild (according to Kermit's own definition of
  4538.    "wild" since it can't possibly know the server's definition). If the
  4539.    filespec is wild it is held for local use to select files from the list
  4540.    returned by the server. If MLST is not reported by the server or is
  4541.    disabled, Kermit sends the MGET filespec with the NLST directive.
  4542.  
  4543.    The default behavior can be overridden globally with FTP DISABLE MLST,
  4544.    which forces Kermit to use NLST to get file lists. And then for
  4545.    situations in which MLSD is enabled, the following MGET switches can be
  4546.    used to override the defaults for a specific MGET operation:
  4547.  
  4548.    /NLST
  4549.           Forces the client to send NLST. Example:
  4550.  
  4551. mget /nlst foo.*
  4552.  
  4553.    /MLSD
  4554.           Forces the client to send MLSD (even if MLST is disabled).
  4555.           Example:
  4556.  
  4557. mget /mlsd foo.*
  4558.  
  4559.    /MATCH:pattern
  4560.           When this switch is given, it forces the client to hold the
  4561.           pattern for local use against the returned file list. If a
  4562.           remote filespec is also given (e.g. the "blah" in "mget
  4563.           /match:*.txt blah"), then it is sent as the NLST or MLSD
  4564.           argument, presumably to specify the directory whose files are to
  4565.           be listed. When the /MATCH switch is not given, the MGET
  4566.           filespec is sent to the server if the directive is NLST or if
  4567.           the filespec is not wild. Examples:
  4568.  
  4569.   Command:                   With NLST:     With MLSD:
  4570.     mget                      NLST           MLSD
  4571.     mget *.txt                NLST *.txt     MLSD
  4572.     mget foo                  NLST foo       MLSD foo
  4573.     mget /match:*.txt         NLST           MLSD
  4574.     mget /match:*.txt foo     NLST foo       MLSD foo
  4575.  
  4576.    In other words, the pattern is always interpreted locally unless MGET
  4577.    uses NLST and no /MATCH switch was given.
  4578.  
  4579. 3.11.4. Examples
  4580.  
  4581. 3.11.4.1. Downloading a Single File
  4582.  
  4583.    There are no choices here, just use the FTP GET command. Kermit always
  4584.    sends the RETR directive, and possibly SIZE and/or MDTM. The small
  4585.    advantage of using MLST in this case is outweighed by the risk and
  4586.    effort of coding a special case.
  4587.  
  4588. 3.11.4.2. Downloading a Group of Files from a Single Directory
  4589.  
  4590.    This case presents tradeoffs, especially on slow connections:
  4591.  
  4592.      * For downloading all or most of the files in a directory, MLSD is
  4593.        better because it eliminates the need to send SIZE and MDTM for
  4594.        each file. No special actions are required in this case; Kermit
  4595.        uses MLSD automatically if the server supports it (unless you have
  4596.        disabled it).
  4597.      * For a small number of files from a large directory, NLST is better
  4598.        because it bypasses downloading of a potentially huge file list
  4599.        prior to the files themselves. If you have a connection to a server
  4600.        that supports MLSD, use the /NLST switch to force NLST:
  4601.  
  4602. mget /nlst t[1234].h
  4603.  
  4604.      * If the server supports MLSD but does not support separate SIZE or
  4605.        MDTM directives, and you need the size and/or timestamp
  4606.        information, MLSD is better; no special actions required.
  4607.      * If the server supports MLSD but does not support the "size" and
  4608.        "modify" facts, but it does support the SIZE or MDTM directives,
  4609.        and you need the size and/or timestamp information, NLST is better.
  4610.  
  4611. 3.11.4.3. Downloading a Directory Tree
  4612.  
  4613.    MLSD is the only choice for recursive downloads; they rarely, if ever,
  4614.    work with NLST (the few cases where they do work rely on extra-protocol
  4615.    "secret" notations for the NLST argument). No special actions are
  4616.    required to force MLSD when the server supports it, unless you have
  4617.    disabled it. Examples:
  4618.  
  4619.    MGET /RECURSIVE
  4620.           This tells the server to send all files and directories in the
  4621.           tree rooted at its current directory.
  4622.  
  4623.    MGET /RECURSIVE *.txt
  4624.           This tells the server to send all *.txt files in the tree rooted
  4625.           at its current directory.
  4626.  
  4627.    MGET /MLSD /RECURSIVE *.txt
  4628.           Same as the previous example but forces Kermit to send MLSD in
  4629.           case it was disabled, or in case the server is known to support
  4630.           it even though it did not announce it in its FEAT listing.
  4631.  
  4632.    MGET /RECURSIVE /MATCH:*.zip archives
  4633.           Tells the server to send all ZIP files in the tree rooted at its
  4634.           "archives" directory.
  4635.  
  4636.    MGET /RECURSIVE /MATCH:* [abc]
  4637.           The server is running on VMS and you want it to send all the
  4638.           files in the directory tree rooted at [ABC]. But since "[abc]"
  4639.           looks just like a wildcard, you have to include a /MATCH: switch
  4640.           to force Kermit to send "[abc]" as the MLSD argument.
  4641.  
  4642.    In all cases in which the /RECURSIVE switch is included, the server's
  4643.    tree is duplicated locally.
  4644.  
  4645.      Although MLSD allows recursion and NLST does not, the MLSD
  4646.      specification places a heavy burden on the client; the obvious,
  4647.      straightforward, and elegant implementation (depth-first, the one
  4648.      that Kermit currently uses) requires as many open temporary files as
  4649.      the server's directory tree is deep, and therefore client resource
  4650.      exhaustion -- e.g. exceeding the maximum number of open files -- is
  4651.      a danger. Unfortunately MLSD was not designed with recursion in
  4652.      mind. (Breadth-first traversal could be problematic due to lack of
  4653.      sufficient navigation information.)
  4654.  
  4655.    Of course all of Kermit's other MGET switches can be used too, e.g. for
  4656.    finer-grained file selection (by date, size, etc), for moving or
  4657.    renaming files as they arrive, to override Kermit's automatic per-file
  4658.    text/binary mode switching, to pass the incoming files through a
  4659.    filter, to convert text-file character sets, and so on.
  4660.  
  4661. 3.11.4.4. NLST/MLSD Summary Table
  4662.  
  4663.    Here's a table summarizing MGET behavior when the server supports both
  4664.    NLST and MLSD. /NLST and /MLSD switches are included for clarity to
  4665.    indicate which protocol is being used, and the expected effects. In
  4666.    practice you can omit the /NLST and /MLSD switches and the Kermit
  4667.    client chooses the appropriate or desired protocol as described above.
  4668.    Sample commands presume a Unix file system on the server, but of course
  4669.    the server can have any file system or syntax at all.
  4670.  
  4671.    User's Command FTP Sends Remarks
  4672.    mget /nlst NLST Gets a list of all the files in the server's current
  4673.    and downloads each file. The list includes names only, so Kermit also
  4674.    must send SIZE and MDTM directives if size and timestamp information is
  4675.    required (this is always true of NLST). Sending NLST without an
  4676.    argument is allowed by the RFC959 NLST definition and by the Kermit FTP
  4677.    client, but might not work with other clients, and also might not work
  4678.    with every server.
  4679.    mget /nlst foo NLST foo If "foo" is a directory, this gets a list of
  4680.    all the files from the server's "foo" directory and downloads each
  4681.    file; otherwise this downloads the file named "foo" (if any) from the
  4682.    server's current directory.
  4683.    mget /nlst *.txt NLST *.txt Gets a list of the files in the server's
  4684.    current directory whose names match the pattern *.txt, and then
  4685.    downloads each file from the list. Because we are using NLST, we send
  4686.    the filespec (*.txt) to the server and the server interprets any
  4687.    wildcards.
  4688.    mget /nlst foo/*.txt NLST foo/*.txt  Gets a list of the files in the
  4689.    server's "foo" directory whose names match the pattern *.txt, and then
  4690.    downloads each file from the list (server interprets wildcards).
  4691.    mget /nlst /match:*.txt NLST Gets a list of all the files in the
  4692.    server's current directory and then downloads each one whose name
  4693.    matches the pattern *.txt (client interprets wildcards).
  4694.    mget /nlst /match:*.txt foo  NLST foo Gets a list of all the files in
  4695.    the server's "foo" directory and then downloads each one whose name
  4696.    matches the pattern *.txt (client interprets wildcards).
  4697.    mget /mlsd MLSD Gets a list of all the files from the server's current
  4698.    directory and then downloads each one. The list might include size and
  4699.    timestamp information, in which case Kermit does not need to send SIZE
  4700.    and MDTM directives for each file (this is always true of MLSD).
  4701.    mget /mlsd foo MLSD foo Gets a list of all the files from the server's
  4702.    "foo" directory (where the string "foo" does not contain wildcards) and
  4703.    then downloads each one. If "foo" is a regular file and not a
  4704.    directory, this command is supposed to fail, but some servers have been
  4705.    observed that send the file.
  4706.    mget /mlsd *.txt MLSD Gets a list of all the files from the server's
  4707.    current directory and then downloads only the ones whose names match
  4708.    the pattern "*.txt". Because we are using MLSD and the MGET filespec is
  4709.    wild, we do not send the filespec to the server, but treat it as though
  4710.    it had been given in a /MATCH: switch and use it locally to match the
  4711.    names in the list.
  4712.    mget /mlsd foo/*.txt MLSD This one won't work because MLSD requires
  4713.    that the notions of server directory and filename-matching pattern be
  4714.    separated. However, the client, which can't be expected to know the
  4715.    server's file-system syntax, winds up sending a request that the server
  4716.    will (or should) reject.
  4717.    mget /mlsd /match:*.txt MLSD Gets a list of all the files from the
  4718.    server's current directory and then downloads only the ones whose names
  4719.    match the pattern "*.txt" (client interprets wildcards).
  4720.    mget /mlsd /match:*.txt foo MLSD foo If "foo" is a directory on the
  4721.    server, this gets a list of all the files from the server's "foo"
  4722.    directory and then downloads only the ones whose names match the
  4723.    pattern "*.txt" (client interprets wildcards). This leaves the server
  4724.    CD'd to the "foo" directory; there's no way the client can restore the
  4725.    server's original directory because MLSD doesn't give that information,
  4726.    and since the client can not be expected to know the server's
  4727.    file-system syntax, it would not be safe to guess. If "foo" is a
  4728.    regular file, MLSD fails.
  4729.    mget /mlsd foo bar MLSD This one is problematic. You're supposed to be
  4730.    able to give MGET a list a filespecs; in this case we name two
  4731.    directories. The client must change the server's directory to "foo" to
  4732.    get the list of files, and then the files themselves. But then it has
  4733.    no way to return to the server's previous directory in order to do the
  4734.    same for "bar", as explained in the previous example.
  4735.    mget /mlsd /match:* [abc] MLSD [abc] Including a /MATCH: switch forces
  4736.    [abc] to be sent to the server even though the client would normally
  4737.    think it was a wildcard and hold it for local interpretation. In this
  4738.    example, [abc] might be a VMS directory name.
  4739.    mget /mlsd /match:* t*.h MLSD t*.h Contrary to the MLSD specification,
  4740.    some MLSD-capable FTP servers do interpret wildcards. This form of the
  4741.    MGET command can be used to force a wildcard to be sent to the server
  4742.    for interpretation.
  4743.  
  4744.    When MLSD is used implicitly (that is, without an /MLSD switch given to
  4745.    force the use of MLSD) and an MGET command such as "mget foo/*.txt"
  4746.    fails, Kermit automatically falls back to NLST and tries again.
  4747.  
  4748. 3.11.5. References
  4749.  
  4750.     1. Postel, J., and J. Reynolds, File Transfer Protocol (FTP), RFC 959,
  4751.        October 1985: [372]ftp://ftp.isi.edu/in-notes/rfc959.txt.
  4752.     2. Hethmon, P, and R. Elz, Feature negotiation mechanism for the File
  4753.        Transfer Protocol, RFC 2389, August 1998:
  4754.        [373]ftp://ftp.isi.edu/in-notes/rfc2389.txt.
  4755.     3. Elz, R, and P. Hethmon, Extensions to FTP, Internet Draft
  4756.        draft-ietf-ftpext-mlst-16.txt, September 2002:
  4757.        [374]http://www.ietf.org/internet-drafts/draft-ietf-ftpext-mlst-16.
  4758.        txt.
  4759.     4. [375]The Kermit FTP Client (overview).
  4760.  
  4761.    [ [376]Top ] [ [377]FTP Top ] [ [378]C-Kermit Home ] [ [379]Kermit Home
  4762.    ]
  4763.  
  4764. 4. FILE SCANNING
  4765.  
  4766.    A new feature called file scanning is used in various contexts to
  4767.    determine if a file is text or binary, and if it is text, what kind of
  4768.    text. The overhead of file scanning is surprisingly tolerable, usually
  4769.    about a quarter second per file. File scanning is now used instead of
  4770.    filename patterns unless you SET FILE SCAN OFF, which restores the
  4771.    previous behavior.
  4772.  
  4773.    The primary benefit of file scanning is in file transfer. For all
  4774.    practical purposes, now you can stop worrying about whether a file
  4775.    should be sent in binary or text mode, or about sending mixtures of
  4776.    text and binary files in a single operation, or configuring and
  4777.    fine-tuning your lists of binary-file and text-file name patterns: now
  4778.    it all just works.
  4779.  
  4780.    File scanning is done by the file sender, which determines the type of
  4781.    each file before it sends it and informs the receiver (Kermit or FTP
  4782.    server) of the type. File scanning is NOT done by the receiver, because
  4783.    it is the sender's responsibility to determine each file's type, send
  4784.    the file in the right mode, and inform the receiver of the mode. If
  4785.    both transfer partners are capable of this (or any other) form of
  4786.    automatic text/binary mode switching, then files can be sent in both
  4787.    directions with no worries about corruption due to inappropriate
  4788.    transfer mode. (As noted in [380]Section 3, FTP servers don't do this,
  4789.    so this discussion does not apply when using Kermit to download from an
  4790.    FTP server.)
  4791.  
  4792.    The rest of this section is mainly for the curious. If you don't read
  4793.    it and simply accept all defaults, every file you send should go in the
  4794.    appropriate mode automatically. As always, however, for character-set
  4795.    translation to work for 7- and 8-bit character-set files, the
  4796.    appropriate SET FILE CHARACTER-SET command(s) must have been executed
  4797.    to identify their encoding (Kermit's default file character-set is
  4798.    neutral ASCII except on platforms like HP-UX or DG/UX, where the
  4799.    default file character-set is known). And of course, receiving is
  4800.    another matter -- obviously the other Kermit must also send each file
  4801.    in the appropriate mode.
  4802.  
  4803.    Scanning is more reliable than filename patterns simply because
  4804.    filenames are not reliable indicators of the file's contents. Classic
  4805.    examples include ".doc" files, which are binary if Microsoft Word
  4806.    documents but text on most other platforms, and ".com" files, which are
  4807.    binary on DOS and Windows but text on VMS. Anyway, nobody knows the
  4808.    naming conventions (if any) of all the applications (and persons!) on
  4809.    your computer. Scanning, on the other hand, determines each file's type
  4810.    by inspecting its contents rather than just looking at its name.
  4811.  
  4812.    Also, file patterns -- even when they work as intended -- categorize
  4813.    each file only as text or binary, whereas file scanning can make finer
  4814.    distinctions:
  4815.  
  4816.    BINARY
  4817.           Binary data, not to be converted in any way. Examples include
  4818.           binary machine code (executable programs), graphics images (GIF,
  4819.           JPG, etc), compressed files (Z, GZ, etc), archives and packages
  4820.           (ZIP, TAR, RPM, etc), object files and libraries (OBJ, DLL,
  4821.           etc).
  4822.  
  4823.    7-BIT TEXT
  4824.           Text encoded in a 7-bit character set such as ASCII or one of
  4825.           the ISO 646 national versions. Kermit has no way to tell which
  4826.           character is used, only that it's 7-bit text. Typical examples
  4827.           include program source code, README files, Perl or Kermit
  4828.           scripts, plain-text email, HTML, TeX, and various textual
  4829.           encodings of binary files: Hex, Base64, etc. When sending such
  4830.           files, the FILE DEFAULT 7BIT-CHARACTER-SET is used as the file
  4831.           character-set, and then the appropriate transfer character set
  4832.           is chosen from the associations list (ASSOCIATE, SHOW
  4833.           ASSOCIATIONS).
  4834.  
  4835.    8-BIT TEXT
  4836.           Text encoded in an 8-bit character set such as Latin-1, Latin-2,
  4837.           Latin/Hebrew, Latin/Cyrillic, KOI8, HP-Roman8, JIS X 0208, Code
  4838.           Page 437, or Code Page 1252. Again, Kermit has no way of knowing
  4839.           which particular set is in use, only that it's 8-bit text. When
  4840.           sending such files, the FILE DEFAULT 8BIT-CHARACTER-SET is used
  4841.           as the file character-set, and then the appropriate transfer
  4842.           character set is chosen from the associations list.
  4843.  
  4844.    UCS2 TEXT
  4845.           Unicode in its basic form, 16 bits (2 octets) per character.
  4846.           When sending such files, UCS2 is the file character-set and the
  4847.           byte order is identified automatically; the appropriate transfer
  4848.           character set is chosen from the associations list. Normally
  4849.           this would be UTF8. UTF-16 is not supported yet; Kermit's
  4850.           Unicode translations are restricted to Plane 0, the Base
  4851.           Multilingual Plane (BMP).
  4852.  
  4853.    UTF8 TEXT
  4854.           Unicode in its 8-bit transformation format. When sending such
  4855.           files, UTF8 is the file character-set; the appropriate transfer
  4856.           character set is chosen from the associations list, normally
  4857.           UCS2 or UTF8.
  4858.  
  4859.    File scanning is available in UNIX C-Kermit, in K-95, and to a limited
  4860.    extent, in VMS C-Kermit (full scanning is problematic in VMS because
  4861.    even plain-text files might contain binary record-format information).
  4862.    The relevant commands are:
  4863.  
  4864.    SET TRANSFER MODE { AUTOMATIC, MANUAL }
  4865.           Tells whether the file-transfer mode (text or binary) should be
  4866.           set by automatic or "manual" means. AUTOMATIC is the default,
  4867.           which allows any of the automatic methods that are enabled to do
  4868.           their jobs: FILE SCAN, FILE PATTERNS, peer recognition, etc.
  4869.           MANUAL lets you control the transfer mode with the SET FILE TYPE
  4870.           commands. As always, /TEXT and /BINARY switches on your
  4871.           file-transfer commands override all other methods; if you give
  4872.           one of these switches, scanning is not done. SHOW TRANSFER
  4873.           displays the current TRANSFER MODE setting.
  4874.  
  4875.    SET FILE SCAN { ON [ number ], OFF }
  4876.           Turns this feature on and off. It's ON by default. When OFF, the
  4877.           previous rules apply (SET FILE PATTERNS, etc). When ON is given,
  4878.           you can also specify a number of bytes to be scanned. The
  4879.           default is 49152 (= 48K). If a negative number is given, the
  4880.           entire file is scanned, no matter how big, for maximum certainty
  4881.           (for example, a PostScript file that appears to be plain text
  4882.           might include an embedded graphic past the normal scanning
  4883.           limit). SHOW FILE displays the current FILE SCAN setting.
  4884.  
  4885.    SET FILE DEFAULT 7BIT-CHARACTER-SET name
  4886.           Tells the 7-bit character-set to use if scanning identifies a
  4887.           7-bit text file, e.g. GERMAN. SHOW FILE displays the current SET
  4888.           FILE DEFAULT settings. So does SHOW CHARACTER-SETS.
  4889.  
  4890.    SET FILE DEFAULT 8BIT-CHARACTER-SET name
  4891.           Tells the 8-bit character-set to use if scanning identifies an
  4892.           8-bit text file, e.g. LATIN1. SHOW FILE and SHOW CHARACTER-SET
  4893.           display this.
  4894.  
  4895.    ASSOCIATE FILE-CHARACTER-SET fcs tcs
  4896.           When sending files and a file character-set (fcs) is identified
  4897.           by scanning, this tells C-Kermit which transfer character-set
  4898.           (tcs) to translate it to. It also allows C-Kermit to set the
  4899.           appropriate transfer character-set automatically whenever you
  4900.           give a SET FILE CHARACTER-SET command.
  4901.  
  4902.    ASSOCIATE TRANSFER-CHARACTER-SET tcs fcs
  4903.           When receiving files and a file arrives whose transfer
  4904.           character-set (tcs) is announced by the sender, this command
  4905.           tells C-Kermit which file character-set (fcs) to translate it
  4906.           to. It also allows C-Kermit to set the appropriate file
  4907.           character-set whenever you give a SET TRANSFER CHARACTER-SET
  4908.           command.
  4909.  
  4910.    SET FILE CHARACTER-SET name
  4911.           When given for a 7-bit set, also sets FILE DEFAULT
  4912.           7BIT-CHARACTER-SET to the same set. When given for an 8-bit set,
  4913.           also sets FILE DEFAULT 8BIT-CHARACTER-SET to the same set. If an
  4914.           ASSOCIATE FILE-CHARACTER-SET command has been given for this
  4915.           set, also sets the corresponding transfer character-set.
  4916.  
  4917.    DIRECTORY /XFERMODE [ filespec ]
  4918.           Performs a file scan of the given files, listing the result for
  4919.           each file. If FILE SCAN is OFF but PATTERNS are ON, the result
  4920.           shown according to the current FILE TEXT-PATTERNS and
  4921.           BINARY-PATTERNS, and are restricted to (B) and (T). When FILE
  4922.           SCAN is ON, the results are:
  4923.  
  4924.   (B)          Binary
  4925.   (T)(7BIT)    Text: 7-bit
  4926.   (T)(8BIT)    Text: 8-bit
  4927.   (T)(UTF8)    Text: Unicode UTF8
  4928.   (T)(UCS2BE)  Text: Unicode UCS2 Big Endian
  4929.   (T)(UCS2LE)  Text: Unicode UCS2 Little Endian
  4930.  
  4931.           So you can use DIR /XFER to get a preview of how each file in a
  4932.           selected group will be transferred. Everything to the right of
  4933.           the (B) or (T) is new. If FILE SCAN is OFF, you only get the (B)
  4934.           or (T) as before.
  4935.  
  4936.           Note: Big and Little Endian refer to the ordering of bytes
  4937.           within a computer word. Big Endian architecture is standard and
  4938.           is used on most non-PC computers. Little Endian architecture is
  4939.           used on PCs.
  4940.  
  4941.    To illustrate file-transfer with scanning, suppose you have a directory
  4942.    containing a mixture of text and binary files, and each text file can
  4943.    be 7-bit German ISO 646, 8-bit Latin-1, or Unicode in any of the
  4944.    following forms: UCS2 Little Endian, UCS2 Big Endian, or UTF8
  4945.    ([381]UTF-16 is not supported yet). Assuming all the built-in defaults
  4946.    are in effect, the following three commands do the job:
  4947.  
  4948.   set file char german   ; This sets the default for 7-bit text files
  4949.   set file char latin1   ; This sets the default for 8-bit text files
  4950.   send *
  4951.  
  4952.    Each file is sent in the appropriate mode (text or binary), with text
  4953.    files converted to the appropriate transfer character-set and labeled
  4954.    so the receiver can convert them according to its own local
  4955.    conventions.
  4956.  
  4957.    By the way, what if you want to inhibit character-set translation but
  4958.    still allow automatic text/binary mode switching? Previously, you could
  4959.    simply SET TRANSFER CHARACTER-SET TRANSPARENT. But now with file
  4960.    scanning, the file and transfer character-sets are set automatically
  4961.    per file. A new command was added for this purpose:
  4962.  
  4963.    SET TRANSFER TRANSLATION { ON, OFF }
  4964.           Enables and disables file-transfer character-set translation. It
  4965.           is enabled by default.
  4966.  
  4967.    When TRANSFER TRANSLATION is OFF but FILE SCAN is ON, files are still
  4968.    scanned to see if they are text or binary, but no character-set
  4969.    translation is done when they text: only the normal record-format
  4970.    conversion.
  4971.  
  4972.    Like all SET commands, SET TRANSFER TRANSLATION is global and
  4973.    persistent. You can also force a particular file-transfer command
  4974.    (SEND, MSEND, GET, RECEIVE, TRANSMIT, etc) to not translate without
  4975.    affecting the global translation settings by including the new
  4976.    /TRANSPARENT switch, e.g.
  4977.  
  4978.   send /transparent oofa.txt
  4979.  
  4980.    As of C-Kermit 8.0.206, SET TRANSFER CHARACTER-SET TRANSPARENT implies
  4981.    SET TRANSFER TRANSLATION OFF.
  4982.  
  4983.    File scanning is also used in the TYPE command. The source file type
  4984.    and character set are determined as above, and then the file is
  4985.    automatically converted to your display character-set, line by line. In
  4986.    Kermit 95, the display character-set is Unicode, perhaps converted to
  4987.    your current console code page; in other versions of C-Kermit, it is
  4988.    your current file character-set. Thus if you have the following set
  4989.    appropriately:
  4990.  
  4991.   SET FILE CHARACTER-SET (necessary in Unix but not K95)
  4992.   SET FILE DEFAULT 7BIT CHARACTER-SET
  4993.   SET FILE DEFAULT 8BIT CHARACTER-SET
  4994.  
  4995.    then you should be able to TYPE any text file and see something
  4996.    reasonable. For example, in Unix, if your DEFAULT 7BIT-CHARACTER-SET is
  4997.    ITALIAN and your DEFAULT 8BIT-CHARACTER-SET is LATIN1, and your FILE
  4998.    CHARACTER-SET is LATIN1, you can TYPE an Italian ISO 646 file, a
  4999.    Latin-1 file, or any kind of Unicode file, and have it translated
  5000.    automatically to Latin-1 for your display.
  5001.  
  5002.    In the GUI version of Kermit 95, you can see mixtures of many different
  5003.    scripts if the file is UTF8 or UCS2: Roman, Cyrillic, Hebrew, Greek,
  5004.    Armenian, Georgian, etc, all on the same screen at once.
  5005.  
  5006.    File scanning also adds a new criterion for file selection, i.e. to
  5007.    select only text (or binary) files. Several commands now include a new
  5008.    switch, /TYPE:{BINARY,TEXT,ALL}. BINARY means select only binary
  5009.    regular files (not directories). TEXT means select only text files. ALL
  5010.    means don't scan; select all files. Examples:
  5011.  
  5012.    SEND /TYPE:BINARY *.*
  5013.           Sends only binary files, skipping over text files.
  5014.  
  5015.    NOTE: File scanning is NOT done when using external protocols (because
  5016.    the external protocol programs, such as sz, are processing each file,
  5017.    not Kermit).
  5018.  
  5019.    DIRECTORY /TYPE:TEXT
  5020.           Lists only text files but not binary files.
  5021.  
  5022.    DELETE /TYPE:BINARY foo.*
  5023.           Deletes all foo.* files that are regular binary files but does
  5024.           not delete any text files.
  5025.  
  5026.    CHMOD /TYPE:BINARY 775 *
  5027.           (UNIX) Changes the permissions of all binary files to 775.
  5028.  
  5029.    When FILE SCAN is OFF and FILE PATTERNS are ON, behavior is as before
  5030.    with PATTERNS ON, but with some improvements:
  5031.  
  5032.      * Pathnames are now stripped prior to pattern matching.
  5033.      * Backup suffixes (like .~3~) are stripped prior to pattern matching.
  5034.  
  5035.    [ [382]Top ] [ [383]Contents ] [ [384]C-Kermit Home ] [ [385]Kermit
  5036.    Home ]
  5037.  
  5038. 5. FILE AND DIRECTORY NAMES CONTAINING SPACES
  5039.  
  5040.    Prior to the introduction of the graphical user interface (GUI), it was
  5041.    inconceivable that file or directory names could contain spaces,
  5042.    because space is a field delimiter in all command languages. GUIs,
  5043.    however, use dialog boxes for filenames, so there is never any question
  5044.    of distinguishing a filename from adjacent fields -- because there are
  5045.    no adjacent fields -- and therefore it has become quite common on
  5046.    computers that have GUIs to have file and directory names composed of
  5047.    multiple words. Of course this poses problems for command shells and
  5048.    other text-oriented programs.
  5049.  
  5050.    Most command shells address these problems by allowing such names to be
  5051.    enclosed in doublequotes, e.g.:
  5052.  
  5053.   cd "c:\Program Files"
  5054.  
  5055.    C-Kermit previously used braces for this:
  5056.  
  5057.   cd {c:\Program Files}
  5058.  
  5059.    which was not what most people expected. And even when braces were
  5060.    used, Kermit had difficulties with completion, file menus, and so
  5061.    forth, within braced fields.
  5062.  
  5063.    C-Kermit 8.0 allows either doublequotes or braces to be used for
  5064.    grouping:
  5065.  
  5066.   send "this file"
  5067.   send {this file}
  5068.   rename "this file" "that file"
  5069.   rename {this file} "that file"
  5070.   rename "this file" {that file}
  5071.   cd {Program Files}
  5072.   cd "Program Files"
  5073.  
  5074.    Note that the doublequotes or brackets must enclose the whole file or
  5075.    directory specification:
  5076.  
  5077.   "c:\My Directory"
  5078.  
  5079.    not:
  5080.  
  5081.   c:\"My Directory"
  5082.  
  5083.    In C-Kermit 8.0, you can also use completion on these filenames, in
  5084.    which case Kermit supplies the quotes (or braces) automatically.
  5085.    Example (in which the current directory contains only one file whose
  5086.    name starts with "th" and its full name is "this file" (without the
  5087.    quotes, but with the space)):
  5088.  
  5089.   cat th<Tab>
  5090.  
  5091.    Kermit repaints the filename field like this:
  5092.  
  5093.   cat "this file"
  5094.  
  5095.    That is, it backspaces over the original "th" and then writes the
  5096.    filename in doublequotes.
  5097.  
  5098.    If completion is only partial, Kermit still supplies the quotes, but in
  5099.    this case also beeps. To continue the filename, you must first
  5100.    backspace over the closing quote. The closing quote is supplied in this
  5101.    case to make sure that you can see the spaces, especially if they are
  5102.    trailing. For example, if the current directory contains two files
  5103.    whose names start with "th", and their fill names are "this file" and
  5104.    "this other file":
  5105.  
  5106.   cat th<Tab>
  5107.  
  5108.    Kermit prints:
  5109.  
  5110.   cat "this "<Beep>
  5111.  
  5112.    If it didn't print the closing quote, you would probably wonder why it
  5113.    was beeping.
  5114.  
  5115.    Also, if you begin a filename field with a doublequote or opening
  5116.    brace, now you can use completion or get ?-help; this was never
  5117.    possible before.
  5118.  
  5119.  C-Kermit>type "thi? Input file specification, one of the following:
  5120.    this file        this other file
  5121.  C-Kermit>type "thi_
  5122.  
  5123.    [ [386]Top ] [ [387]Contents ] [ [388]C-Kermit Home ] [ [389]Kermit
  5124.    Home ]
  5125.  
  5126. 6. OTHER COMMAND PARSING IMPROVEMENTS
  5127.  
  5128. 6.1. Grouping Macro Arguments
  5129.  
  5130.    Doublequotes now can be used in macro invocations to group arguments
  5131.    containing spaces, where previously only braces could be used:
  5132.  
  5133.   define xx show args
  5134.   xx one "this is two" three
  5135.  
  5136.    Result:
  5137.  
  5138.   Macro arguments at level 0 (\v(argc) = 4):
  5139.    \%0 = xx
  5140.    \%1 = one
  5141.    \%2 = this is two
  5142.    \%3 = three
  5143.  
  5144.    Also, you can now quote braces and quotes in macro args (this didn't
  5145.    work before). Examples:
  5146.  
  5147.   xx "{"  ; The argument is a single left brace
  5148.   xx {"}  ; The argument is a doublequote character
  5149.  
  5150.    In case this new behavior interferes with your scripts, you can restore
  5151.    the previous behavior with:
  5152.  
  5153.   SET COMMAND DOUBLEQUOTING OFF
  5154.  
  5155. 6.2. Directory and File Name Completion
  5156.  
  5157.    C-Kermit 8.0 also includes better completion for directory names, e.g.
  5158.    in the CD command. If the name typed so far uniquely matches a
  5159.    directory name, it is completed (as before), but now if the directory
  5160.    contains any subdirectories, completion is partial (allowing you to
  5161.    supply additional path segments without backspacing); otherwise it is
  5162.    complete.
  5163.  
  5164.    Completion has also been improved for file and directory names that
  5165.    contain not only spaces (as described above) but also "metacharacters"
  5166.    such as asterisk (*) and tilde (~): now the field is repainted if
  5167.    necessary. For example, if the current directory contains only one file
  5168.    whose name contains "blah", then in:
  5169.  
  5170.   type *blah<Tab>
  5171.  
  5172.    "*blah" is replaced by the filename. In earlier releases, the part
  5173.    typed so far was left on the command line (and in the history buffer),
  5174.    so even when the original command worked, the recalled version would
  5175.    not. Similarly for ~ (the nearly-universal Unix notation for username):
  5176.  
  5177.   type ~olga/x<Tab>
  5178.  
  5179.    is repainted as (e.g.):
  5180.  
  5181.   type /users/home/olga/x(Beep)
  5182.  
  5183.    Speaking of command history, the new SHOW HISTORY command shows your
  5184.    command history and recall buffer. SAVE COMMAND HISTORY saves it into a
  5185.    file of your choice.
  5186.  
  5187. 6.3. Passing Arguments to Command Files
  5188.  
  5189.    The method for passing arguments to command files has been improved.
  5190.    Prior to C-Kermit 7.0 there was no provision for doing this. In
  5191.    C-Kermit 7.0, the TAKE command was changed to allow arguments to be
  5192.    given after the filename:
  5193.  
  5194.   take commandfile arg1 arg2 ...
  5195.  
  5196.    This was accomplished by replacing the current \%1, \%2, etc, with the
  5197.    given arguments, since a new set of macro argument variables is created
  5198.    only when a macro is executed, not a command file. It is much more
  5199.    intuitive, however, if arguments to command files worked like those to
  5200.    macros: the command file sees the arguments as its own \%1, \%2, etc,
  5201.    but the caller's variables are not disturbed. C-Kermit 8.0 accomplishes
  5202.    this by automatically creating an intermediate temporary macro to start
  5203.    the command file (if any arguments were given), thus creating a new
  5204.    level of arguments as expected.
  5205.  
  5206. 6.4. More-Prompting
  5207.  
  5208.    The familiar --more?-- prompt that appears at the end of each screenful
  5209.    of command-response output now accepts a new answer: G (Go) meaning
  5210.    "show all the rest without pausing and asking me any more questions". P
  5211.    (Proceed) is a synonym for G.
  5212.  
  5213. 6.5. Commas in Macro Definitions
  5214.  
  5215.    As noted in the [390]C-Kermit manual, comma is used to separate
  5216.    commands in a macro definition. Even when the macro is defined on
  5217.    multiple lines using curly-brace block-structure notation without
  5218.    commas, the definition is still stored internally as a comma-separated
  5219.    list of commands. Therefore special tricks are needed to include a
  5220.    comma in a command. The classic example is:
  5221.  
  5222.   define foo {
  5223.       (some command)
  5224.       if fail echo Sorry, blah failed...
  5225.   }
  5226.  
  5227.    This would result in Kermit trying to execute a "blah" command. This
  5228.    could always be handled by enclosing the text in braces:
  5229.  
  5230.   define foo {
  5231.       (some command)
  5232.       if fail echo {Sorry, blah failed...}
  5233.   }
  5234.  
  5235.    but doublequotes (more intuitive) should have worked too. Now they do:
  5236.  
  5237.   define foo {
  5238.       (some command)
  5239.       if fail echo "Sorry, blah failed..."
  5240.   }
  5241.  
  5242. 6.6. Arrow Keys
  5243.  
  5244.    As of version 8.0.201, C-Kermit on most platforms lets you access the
  5245.    command history buffer with arrow keys, just as you always could with
  5246.    control characters. The restrictions are:
  5247.  
  5248.     1. Only Up and Down arrow keys are accepted.
  5249.     2. Only 7-bit ANSI arrow-key sequences are understood (ESC followed by
  5250.        [ or uppercase letter O, followed by uppercase letter A or (up) B
  5251.        (down).
  5252.  
  5253.    This change was made to facilitate command recall in Linux-based PDAs
  5254.    that don't have a Control key, or at least not one that's easily (or
  5255.    always) accessible, such as the Sharp Zaurus SL5500.
  5256.  
  5257.    [ [391]Top ] [ [392]Contents ] [ [393]C-Kermit Home ] [ [394]Kermit
  5258.    Home ]
  5259.  
  5260. 7. NEW COMMANDS AND SWITCHES
  5261.  
  5262.    See [395]Section 4 for more about file scanning and the /TYPE: switch.
  5263.  
  5264.    ASK[Q] [ /TIMEOUT:number /QUIET /DEFAULT:text ] variable [ prompt ]
  5265.           The new optional /TIMEOUT: switch for ASK and ASKQ causes the
  5266.           command to time out and and fail if no response is given within
  5267.           the specified number of seconds, 1 or greater (0 or less means
  5268.           no timeout, wait forever). This works just like SET ASK-TIMER,
  5269.           except its effect is local to the ASK command with which it is
  5270.           given and it does not disturb the global ask timer setting. The
  5271.           new /QUIET switch tells Kermit not to print an error message if
  5272.           the ASK or ASKQ command times out waiting for a response.
  5273.  
  5274.           Version 8.0.211 adds the /DEFAULT:text switch for ASK-Class
  5275.           commands (ASK, ASKQ, and GETOK). This lets you supply a default
  5276.           answer in case the user supplies an empty answer or the
  5277.           /TIMEOUT: switch was included and the time limit expired without
  5278.           an answer. In both these cases, the command succeeds.
  5279.  
  5280.    CAT filename
  5281.           Equivalent to TYPE /NOPAGE.
  5282.  
  5283.    CDUP
  5284.           Changes Kermit's local working directory to the parent of the
  5285.           current one. Equivalent to "cd .." in UNIX or Windows, "cd [-]"
  5286.           in VMS, "cd ^" in AOS/VS, etc; in other words, it's a
  5287.           platform-independent way of moving one level up in a directory
  5288.           tree.
  5289.  
  5290.    CHMOD [ switches ] permission files
  5291.           UNIX only. Sets file permissions for one or more files or
  5292.           directories. The permission must be given as an octal number,
  5293.           e.g. 664, 755. Switches: /DIRECTORIES, /FILES, /NOLIST, /PAGE,
  5294.           /DOTFILES, /LIST, /NOPAGE, /RECURSIVE, /TYPE:{TEXT,BINARY,ALL},
  5295.           /SIMULATE. The /TYPE: switch allows selection of only text or
  5296.           binary files. For example, if you have a mixture of source files
  5297.           and executables, you can use "chmod /files /type:text 664" to
  5298.           give owner/group read/write and world read permission to the
  5299.           text files, and "chmod /files /type:binary 775" to give the same
  5300.           plus execute permission to the executables. Use /SIMULATE to see
  5301.           which files would be affected, without actually changing their
  5302.           permissions.
  5303.  
  5304.    CLEAR KEYBOARD-BUFFER
  5305.           Flushes any as-yet unread characters from the keyboard input
  5306.           buffer. Useful for flushing typeahead in scripts.
  5307.  
  5308.    CONTINUE
  5309.           When given at an interactive command prompt that was reached by
  5310.           issuing a PROMPT command (described in this section) from a
  5311.           script, this command returns to the script, continuing its
  5312.           execution at the command after the PROMPT command. In this
  5313.           context, CONTINUE is simply a more-intuitive synonym for END.
  5314.  
  5315.    COPY, RENAME, and TRANSLATE
  5316.           These commands now work on file groups if the target filename is
  5317.           a directory, e.g. "copy oofa.* ..", "rename * ~olga/tmp/"
  5318.  
  5319.    COPY /APPEND source destination
  5320.           The source file specification can now include wildcards, in
  5321.           which case all of the source files that match will go into the
  5322.           destination file in alphabetical order by name.
  5323.  
  5324.    DELETE /ASK
  5325.           Asks permission to delete each file before deleting it. In
  5326.           C-Kermit 7.0, the answers were "yes" (or "ok") and "no".
  5327.           C-Kermit 8.0 adds "go" (meaning, delete all the rest without
  5328.           asking) and "quit" (cancel the DELETE command and return to the
  5329.           prompt).
  5330.  
  5331.    DELETE /DIRECTORIES
  5332.           Deletes not only files but also directories.
  5333.  
  5334.    DELETE /RECURSIVE
  5335.           Deletes all files that match the given file specification in the
  5336.           current (or given) directory and all directories beneath it.
  5337.  
  5338.    DELETE /SUMMARY
  5339.           Prints only the number of files deleted and total size freed,
  5340.           without listing each file.
  5341.  
  5342.    DELETE /TREE
  5343.           Shorthand for DELETE /RECURSIVE /DIRECTORIES /DOTFILES/.
  5344.           Equivalent to Windows DELTREE or Unix "rm -Rf". If no file
  5345.           specification is given, the contents of the current directory,
  5346.           plus all of its subdirectories and their contents, are deleted.
  5347.  
  5348.    DELETE /TYPE:BINARY
  5349.           Delete only regular binary files (requires FILE SCAN ON).
  5350.  
  5351.    DELETE /TYPE:TEXT
  5352.           Delete only regular text files (requires FILE SCAN ON).
  5353.  
  5354.    DIRECTORY [ switches ] [ filespec [ filespec [ filespec ... ] ] ]
  5355.           The DIRECTORY command now accepts more than one file
  5356.           specification; e.g. "directory moon.txt sun.doc stars.*".
  5357.  
  5358.    DIRECTORY /NORECURSIVE xxx
  5359.           If xxx is a directory name, forces listing of the directory
  5360.           itself rather than its contents.
  5361.  
  5362.    DIRECTORY /FOLLOWLINKS xxx
  5363.           (UNIX only) Tells the DIRECTORY command to follow symbolic
  5364.           links. This not the default because it can cause endless loops.
  5365.  
  5366.    DIRECTORY /NOFOLLOWLINKS xxx
  5367.           (UNIX only) Tells the DIRECTORY command not to follow symbolic
  5368.           links, but rather, merely to list them. This is the default.
  5369.  
  5370.    DIRECTORY /OUTPUT:filename
  5371.           Sends the results of the DIRECTORY command to the given file.
  5372.  
  5373.    DIRECTORY /SUMMARY
  5374.           Prints only the number of directories and files and the total
  5375.           size, without listing each file.
  5376.  
  5377.    DIRECTORY /TYPE:{TEXT,BINARY}
  5378.           Shows only files of the selected type, based on file scan.
  5379.  
  5380.    DIRECTORY /XFERMODE
  5381.           Now shows results of file scan (see [396]Section 4).
  5382.  
  5383.    FOPEN [ switches ] channel filename
  5384.  
  5385.           As of version 8.0.211, FOPEN allows /dev/tty as a filename in
  5386.           Unix-based operating systems.
  5387.  
  5388.    FREAD /TRIM
  5389.           (8.0.211) Trims any trailing blanks or tabs from the item (such
  5390.           as a line of text) that it has read.
  5391.  
  5392.    FREAD /UNTABIFY
  5393.           (8.0.211) Converts Horizontal Tab characters to the appropriate
  5394.           number of spaces, based on VT100-like tab stops (1,9,17,25,...).
  5395.  
  5396.    GREP [ switches ] pattern files
  5397.           Similar to Unix grep command: displays file lines that match the
  5398.           given [397]pattern. Switches:
  5399.  
  5400.         /COUNT[:variable]
  5401.                 Don't show the matching lines, just tell how many lines
  5402.                 match. If a variable name is specified, the count is
  5403.                 stored in the given variable.
  5404.  
  5405.         /DOTFILES
  5406.                 Include files whose names begin with dot.
  5407.  
  5408.         /LINENUMBERS
  5409.                 Show line numbers of matching lines.
  5410.  
  5411.         /NAMEONLY
  5412.                 only list the names of files that contain matching lines,
  5413.                 but not the lines themselves.
  5414.  
  5415.         /NOBACKUP
  5416.                 Skip backup files.
  5417.  
  5418.         /NOCASE
  5419.                 Ignore alphabetic case while pattern matching.
  5420.  
  5421.         /NODOTFILES
  5422.                 skip files whose names start with dot (period).
  5423.  
  5424.         /NOLIST
  5425.                 Suppress output but set SUCCESS or FAILURE according to
  5426.                 search result.
  5427.  
  5428.         /NOMATCH
  5429.                 Look for lines that do not match the pattern.
  5430.  
  5431.         /NOPAGE
  5432.                 Don't pause between screens of output.
  5433.  
  5434.         /OUTPUT:filename
  5435.                 Write results into the given file.
  5436.  
  5437.         /PAGE
  5438.                 Pause between screens of output.
  5439.  
  5440.         /RECURSIVE
  5441.                 Search files in subdirectories too.
  5442.  
  5443.         /TYPE:{TEXT,BINARY}
  5444.                 Search only files of the specified type.
  5445.  
  5446.           Synonyms: FIND, SEARCH.
  5447.  
  5448.    GETOK /TIMEOUT:n /QUIET /DEFAULT:text
  5449.           The new /QUIET switch instructs GETOK, when given a timeout, not
  5450.           to print an error message if it times out. As of 8.0.211, a
  5451.           default answer can be supplied (see ASK).
  5452.  
  5453.    HEAD [ switches ] filename
  5454.           Equivalent to TYPE /HEAD [ other-switches ] filename.
  5455.  
  5456.    HELP DATE
  5457.           Explains date-time formats, including timezone notation and
  5458.           delta times.
  5459.  
  5460.    HELP FIREWALLS
  5461.           Explains the firewall negotiation capabilities of your version
  5462.           of Kermit.
  5463.  
  5464.    KCD [ symbolic-directory-name ]
  5465.           Changes Kermit's working directory to the named symbolic
  5466.           directory, such as such as exedir, inidir, startup, download, or
  5467.           and home. Type "kcd ?" for a list of symbolic directory names
  5468.           known to your copy of Kermit, or give the new ORIENTATION
  5469.           command for a more detailed explanation. If you give a KCD
  5470.           command without a directory name, Kermit returns to its "home"
  5471.           directory, which is determined in some way that depends on the
  5472.           underlying operating system, but which you can redefine with the
  5473.           (new) SET CD HOME command. Your home directory is shown by SHOW
  5474.           CD and it's also the value of the \v(home) variable.
  5475.  
  5476.    LICENSE
  5477.           Displays the C-Kermit license.
  5478.  
  5479.    L-commands
  5480.           When Kermit has a connection to a Kermit or FTP server, file
  5481.           management commands such as CD, DIRECTORY, and DELETE might be
  5482.           intended for the local computer or the remote server. C-Kermit
  5483.           8.0.200 and earlier always executes these commands on the local
  5484.           computer. If you want them executed by the remote server, you
  5485.           have to prefix them with REMOTE (e.g. REMOTE CD) or use special
  5486.           R-command aliases (e.g. RCD = REMOTE CD, RDIR = REMOTE DIR,
  5487.           etc). But this feels unnatural to FTP users, who expect
  5488.           unprefixed file management commands to be executed by the remote
  5489.           server, rather than locally. C-Kermit 8.0.201 adds automatic
  5490.           locus switching to present an FTP-like interface for FTP
  5491.           connections and the normal Kermit interface for Kermit
  5492.           connections, and a SET LOCUS command (described below) to
  5493.           control whether or how this is done. For when LOCUS is REMOTE, a
  5494.           new set of commands was added for local management: LCD (Local
  5495.           CD), LDIR (Local DIR), etc. These are described below under SET
  5496.           LOCUS.
  5497.  
  5498.    MORE filename
  5499.           Equivalent to TYPE /PAGE.
  5500.  
  5501.    ORIENTATION
  5502.           Displays symbolic directory names and the corresponding variable
  5503.           names and values. The symbolic names, such as exedir, inidir,
  5504.           startup, download, and home, can be used as arguments to the new
  5505.           KCD command.
  5506.  
  5507.    PROMPT [ text ]
  5508.           For use in a macro or command file: enters interactive command
  5509.           mode within the current context ([398]Section 8.1). If the
  5510.           optional text is included, the prompt is set to it. The text can
  5511.           include variables, functions, etc, as in the SET PROMPT command.
  5512.           They are evaluated each time the prompt is printed. Unlike the
  5513.           SET PROMPT command, the text argument applies only to the
  5514.           current command level. Thus you can have different prompts at
  5515.           different levels.
  5516.  
  5517.    REMOTE SET MATCH { DOTFILE, FIFO } { ON, OFF }
  5518.           Allows the client to tell the server whether wildcards sent to
  5519.           the server should match dot files (files whose names begin with
  5520.           period) or FIFOs (named pipes). See SET MATCH.
  5521.  
  5522.    SET ATTRIBUTE RECORD-FORMAT { ON, OFF }
  5523.           Allows control of the Kermit's Record-Format attribute. Set this
  5524.           to OFF in case incoming file are refused due to unknown or
  5525.           invalid record formats if you want to accept the file anyway
  5526.           (and, perhaps, postprocess it to fix its record format).
  5527.  
  5528.    SET CD HOME [ directory ]
  5529.           Specifies the target directory for the CD and KCD commands, when
  5530.           they are given without an argument, and also sets the value of
  5531.           the \v(home) variable.
  5532.  
  5533.    SET EXIT HANGUP { OFF, ON }
  5534.           Normally ON, meaning that when Kermit exits, it also explicitly
  5535.           hangs up the current SET LINE / SET PORT serial port according
  5536.           to the current SET MODEM TYPE and SET MODEM HANGUP METHOD, and
  5537.           closes the port device if it was opened by Kermit in the first
  5538.           place (as opposed to inherited). SET EXIT HANGUP OFF tells
  5539.           Kermit not to do this. This can't prevent the operating system
  5540.           from closing the device when Kermit exits (and it's a "last
  5541.           close") but if the port or modem have been conditioned to
  5542.           somehow ignore the close and keep the connection open, at least
  5543.           Kermit itself won't do anything explicit to hang it up or close
  5544.           it.
  5545.  
  5546.    SET FILE EOF { CTRL-Z, LENGTH }
  5547.           Specifies the end-of-file detection method to be used by
  5548.           C-Kermit when sending and receiving text files, and in the TYPE
  5549.           and similar text-file oriented commands. The normal and default
  5550.           method is LENGTH. You can specify CTRL-Z when handling CP/M or
  5551.           MS-DOS format text files, in which a Ctrl-Z (ASCII 26) character
  5552.           within the file marks the end of the file.
  5553.  
  5554.    SET FILE LISTSIZE number
  5555.           Allocates space for the given number of filenames to be filled
  5556.           in by the wildcard expander. The current number is shown by SHOW
  5557.           FILE. If you give a command that includes a filename containing
  5558.           a wildcard (such as "*") that matches more files that Kermit's
  5559.           list has room for, you can adjust the list size with this
  5560.           command.
  5561.  
  5562.    SET FILE STRINGSPACE number
  5563.           Allocates space for the given amount of filename strings for use
  5564.           by the wildcard expander. The current number is shown by SHOW
  5565.           FILE. The number is the total number of bytes of all the file
  5566.           specifications that match the given wildcard.
  5567.  
  5568.      If you need to process a bigger list of files than your computer has
  5569.      memory for, you might be able use an external file list. The Kermit
  5570.      SEND and the FTP PUT and GET commands accept a /LISTFILE: switch,
  5571.      which gives the name of a file that contains the list of files to be
  5572.      transferred. Example for UNIX:
  5573.  
  5574.   !find . -print | grep / > /tmp/names
  5575.   ftp put /update /recursive /listfile:/tmp/names
  5576.  
  5577.    SET LOCUS { AUTO, LOCAL, REMOTE }
  5578.           Added in C-Kermit 8.0.201.   Sets the locus for unprefixed file
  5579.           management commands such as CD, DIRECTORY, MKDIR, etc. When
  5580.           LOCUS is LOCAL these commands act locally and a REMOTE (or R)
  5581.           prefix (e.g. REMOTE CD, RCD, RDIR) is required to send file
  5582.           management commands to a remote server. When LOCUS is REMOTE, an
  5583.           L prefix is required to issue local file management commands
  5584.           (e.g. LCD, LDIR). The word LOCAL can't be used as a prefix since
  5585.           it is already used for declaring local variables. LOCUS applies
  5586.           to all types of connections, and thus is orthogonal to SET
  5587.           GET-PUT-REMOTE, which selects between Kermit and FTP for remote
  5588.           file-transfer and management commands. The default LOCUS is
  5589.           AUTO, which means we switch to REMOTE whenever an FTP connection
  5590.           is made, and to LOCAL whenever a non-FTP connection is made, and
  5591.           switch back accordingly whenever a connection is closed. So by
  5592.           default, Kermit behaves in its traditional manner unless you
  5593.           make an FTP connection, in which case it acts like a regular FTP
  5594.           client (but better :-)   LOCUS applies to the following
  5595.           commands:
  5596.  
  5597.   Unprefixed    Remote       Local        Description
  5598.    CD (CWD)      RCD          LCD          Change (Working) Directory
  5599.    CDUP          RCDUP        LCDUP        CD Up
  5600.    PWD           RPWD         LPWD         Print Working Directory
  5601.    DIRECTORY     RDIR         LDIR         Request a directory listing
  5602.    DELETE        RDEL         LDEL         Delete (a) file(s)
  5603.    RENAME        RREN         LREN         Rename a file
  5604.    MKDIR         RMKDIR       LMKDIR       Create a directory
  5605.    RMDIR         RRMDIR       LRMDIR       Remove a directory
  5606.  
  5607.    SET MATCH { DOTFILE, FIFO } { ON, OFF }
  5608.           Whether C-Kermit filename patterns (wildcards) should match
  5609.           filenames that start with dot (period), or (Unix only) FIFOs
  5610.           (named pipes). The defaults are to skip dotfiles in Unix but
  5611.           match them elsewhere, and to skip FIFOs. Applies to both
  5612.           interactive use and to server mode, when the server receives
  5613.           wildcards, e.g. in a GET command. Also see REMOTE SET MATCH.
  5614.  
  5615.    SET OPTIONS DIRECTORY /DOTFILES
  5616.           Now works for server listings too (UNIX only). Give this command
  5617.           prior to having Kermit enter server mode, and then it will show
  5618.           files whose names begin with dot (period) when sent a REMOTE
  5619.           DIRECTORY command.
  5620.  
  5621.    SET QUIET ON
  5622.           (as well as the -q command-line option) Now applies also to:
  5623.  
  5624.           + SET HOST connection progress messages.
  5625.           + "Press the X or E key to cancel" file-transfer message.
  5626.           + REMOTE CD response.
  5627.           + REMOTE LOGIN response.
  5628.  
  5629.    SET RECEIVE PERMISSIONS { ON, OFF }
  5630.           Tells C-Kermit whether to set the permissions of incoming files
  5631.           (received with Kermit protocol) from the permissions supplied in
  5632.           the file's Attribute packet (if any). Normally ON. Also see SET
  5633.           SEND PERMISSIONS.
  5634.  
  5635.    SET ROOT directory
  5636.           Like UNIX chroot, without requiring privilege. Sets the root for
  5637.           file access, does not allow reference to or creation of files
  5638.           outside the root, and can't be undone.
  5639.  
  5640.    SET SEND PERMISSIONS { ON, OFF }
  5641.           Tells C-Kermit whether to include file permissions in the
  5642.           attributes it includes with each file when sending with Kermit
  5643.           protocol. Also see SET RECEIVE PERMISSIONS.
  5644.  
  5645.    SET TCP { HTTP-PROXY, SOCKS-SERVER } /USER:name /PASSWORD:text
  5646.           These commands now allow specification of username and password.
  5647.  
  5648.    SET TERMINAL . . .
  5649.           (See [399]Section 12.)
  5650.  
  5651.    SET TRANSFER MESSAGE [ text ]
  5652.           Sets an initial text message to be displayed in the
  5653.           file-transfer display. The transfer message is automatically
  5654.           deleted once used, so must be set each time a message a desired.
  5655.           Any variables in the message are evaluated at the time the SET
  5656.           command is given. If the optional text is omitted, any transfer
  5657.           message that is currently set is removed. Synonym: SET XFER MSG.
  5658.           SHOW TRANSFER displays it if it has been set but not yet used.
  5659.  
  5660.    SHOW COMMUNICATIONS
  5661.           In C-Kermit 8.0, SHOW COMMUNICATIONS, when given in remote mode
  5662.           (i.e. before any connection has been established), tells the
  5663.           typical dialout device name for the particular platform on which
  5664.           it's running (e.g. TXA0: for VMS, or /dev/cua0p0 for HP-UX). On
  5665.           Unix platforms, it also tells the name of the lockfile
  5666.           directory. This way, you have an idea of what the SET LINE
  5667.           device name should look like, and if the SET LINE command fails,
  5668.           you know the name of the directory or device that is protected
  5669.           against you.
  5670.  
  5671.    SHOW VARIABLES [ name [ name [ ... ] ] ]
  5672.           In C-Kermit 8.0.201 you can request values of a list of built-in
  5673.           (\v(xxx)) variables. Each name is a pattern, as before, but now
  5674.           it a free pattern rather than an anchored one (explained in
  5675.           [400]Section 8.12) so now "show var date time" shows the values
  5676.           of all variables whose names include the strings "date" or
  5677.           "time".
  5678.  
  5679.    TAIL [ switches ] filename
  5680.           Equivalent to TYPE /TAIL [ other-switches ] filename.
  5681.  
  5682.    TRANSMIT /NOECHO [ other switches ] filename
  5683.           The /NOECHO switch is equivalent to giving the command SET
  5684.           TRANSMIT ECHO OFF prior to the TRANSMIT command, except the
  5685.           switch affects only the command with which it was given and does
  5686.           not affect the prevailing global setting.
  5687.  
  5688.    TRANSMIT /NOWAIT [ other switches ] filename
  5689.           The /NOWAIT switch is equivalent to giving the command SET
  5690.           TRANSMIT PROMPT 0 prior to the TRANSMIT command, except the
  5691.           switch affects only the command with which it was given and does
  5692.           not affect the prevailing global setting.
  5693.  
  5694.    TRANSMIT /NOWAIT /NOECHO /BINARY [ other switches ] filename
  5695.           When the TRANSMIT command is given with the /NOWAIT, /NOECHO,
  5696.           and /BINARY switches, this activates a special "blast the whole
  5697.           file out the communications connection all at once" mode that
  5698.           Kermit didn't have prior to version 8.0. There has been
  5699.           increasing demand for this type of transmission with the advent
  5700.           of devices that expect image (e.g. .JPG) or sound (e.g. .MP3)
  5701.           files as raw input. The obvious question is: how does the
  5702.           receiving device know when it has the whole file? This depends
  5703.           on the device, of course; usually after a certain amount of time
  5704.           elapses with nothing arriving, or else when Kermit hangs up or
  5705.           closes the connection.
  5706.  
  5707.    TYPE /CHARACTER-SET:name
  5708.           Allows you to specify the character set in which the file to be
  5709.           typed is encoded.
  5710.  
  5711.    TYPE /NUMBER
  5712.           Adds line numbers.
  5713.  
  5714.    TYPE /OUTPUT:filename
  5715.           Sends the results of the TYPE command to the given file.
  5716.  
  5717.    TYPE /TRANSLATE-TO:name
  5718.           Used in conjunction with TYPE /CHARACTER-SET:xxx; allows you to
  5719.           specify the character set in which the file is to be displayed.
  5720.  
  5721.    TYPE /TRANSPARENT
  5722.           Used to disable character-set translation in the TYPE command,
  5723.           which otherwise can take place automatically based on file
  5724.           scanning, even when /CHARACTER-SET and /TRANSLATE-TO switches
  5725.           are not given.
  5726.  
  5727.    VOID text
  5728.           Parses the text, evaluating any backslash items in it (such as
  5729.           function calls) but doesn't do anything further, except possibly
  5730.           printing error messages. Useful for invoking functions that have
  5731.           side effects without using or printing their direct results,
  5732.           e.g. "void \fsplit(\%a,&a)".
  5733.  
  5734. Symbolic Links in UNIX
  5735.  
  5736.    The UNIX versions of C-Kermit have had /FOLLOWLINKS and /NOFOLLOWLINKS
  5737.    switches added to several commands to control the treatment of symbolic
  5738.    links. Different commands deal differently with symbolic links:
  5739.  
  5740.    Kermit SEND, FTP MPUT
  5741.           /NOFOLLOWLINKS is the default, which means symbolic links are
  5742.           skipped entirely. The alternative, /FOLLOWLINKS, should be used
  5743.           with caution, since an innocent link might point to a whole file
  5744.           system, or it might cause a loop. There is no way in Kermit or
  5745.           FTP protocol to send the link itself. We either skip them or
  5746.           follow them; we can't duplicate them.
  5747.  
  5748.    DIRECTORY
  5749.           /NOFOLLOWLINKS is the default, which means the DIRECTORY command
  5750.           lists symbolic links in a way that shows they are links, but it
  5751.           does not follow them. The alternative, /FOLLOWLINKS, follows
  5752.           links and gives information about the linked-to directories and
  5753.           files.
  5754.  
  5755.    DELETE, RMDIR
  5756.           The DELETE command does not have link-specific switches. DELETE
  5757.           never follows links. If you tell Kermit to delete a symbolic
  5758.           link, it deletes the link itself, not the linked-to file. Ditto
  5759.           for RMDIR.
  5760.  
  5761.    COPY
  5762.           The COPY command behaves just like the UNIX cp command; it
  5763.           always follows links.
  5764.  
  5765.    RENAME
  5766.           The RENAME command behaves just like the UNIX mv command; it
  5767.           operates on links directly rather than following.
  5768.  
  5769.    [ [401]Top ] [ [402]Contents ] [ [403]C-Kermit Home ] [ [404]Kermit
  5770.    Home ]
  5771.  
  5772. 8. OTHER SCRIPTING IMPROVEMENTS
  5773.  
  5774. 8.1. Performance and Debugging
  5775.  
  5776.    A command cache for frequently used commands plus some related
  5777.    optimizations increases the speed of compute-bound scripts by anywhere
  5778.    from 50% to 1000%.
  5779.  
  5780.    The new PROMPT command can be used to set breakpoints for debugging
  5781.    scripts. If executed in a command file or macro, it gives you an
  5782.    interactive command prompt in the current context of the script, with
  5783.    all its variables, arguments, command stack, etc, available for
  5784.    examination or change, and the ability to resume the script at any
  5785.    point (END resumes it, Ctrl-C or STOP cancels it and returns to top
  5786.    level).
  5787.  
  5788.    The new Ctrl-C trapping feature ([405]Section 8.14) lets you intercept
  5789.    interruption of scripts. This can be used in combination with the
  5790.    PROMPT command to debug scripts. Example:
  5791.  
  5792. define ON_CTRLC {
  5793.     echo INTERRUPTED BY CTRL-C...
  5794.     echo The command stack has not yet been rolled back:
  5795.     show stack
  5796.     echo Type Ctrl-C again or use the END command to return to top level.
  5797.     prompt Debug>
  5798. }
  5799.  
  5800.    Adding this ON_CTRL definition to your script lets you interrupt it at
  5801.    any point and get prompt that is issued at the current command level,
  5802.    so you can query local variables, etc.
  5803.  
  5804.    [ [406]Top ] [ [407]Contents ] [ [408]C-Kermit Home ] [ [409]Kermit
  5805.    Home ]
  5806.  
  5807. 8.2. Using Macros as Numeric Variables
  5808.  
  5809.    A macro is a way to assign a value to a name, and then use the name to
  5810.    refer to the value. Macros are used in two ways in Kermit: as
  5811.    "subroutines" or functions composed of Kermit commands, which are
  5812.    executed, or as variables to hold arbitrary values -- text, numbers,
  5813.    filenames, etc.
  5814.  
  5815.    When a macro is to be executed, its name is given as if it were a
  5816.    C-Kermit command, optionally preceded by the word "do". When a macro is
  5817.    used as a variable, it must be "escaped" with \m(xxx) (or equivalent
  5818.    function, e.g. \s(xxx), \:(xxx), \fdefinition(xxx)), where xxx is the
  5819.    macro name, for example:
  5820.  
  5821.   define filename /usr/olga/oofa.txt
  5822.   send \m(filename)
  5823.  
  5824.    Of course variables can also hold numbers:
  5825.  
  5826.   define size 17
  5827.   declare \&a[\m(size)]
  5828.   ...
  5829.   define index 3
  5830.   if ( == \m(index) 3 ) echo The third value is: \&a[\m(index)]
  5831.   evaluate index (\m(index) * 4)
  5832.   if ( > \m(index) \m(size) ) echo Out of range!
  5833.  
  5834.    But these are contexts in which only numbers are valid. C-Kermit 8.0
  5835.    has been changed to treat non-escaped non-numeric items in strictly
  5836.    numeric contexts as macro names. So it is now possible (but not
  5837.    required) to omit the \m(...) notation and just use the macro name in
  5838.    these contexts:
  5839.  
  5840.   define size 17
  5841.   declare \&a[size]
  5842.   ...
  5843.   define index 3
  5844.   if ( == index 3 ) echo The third value is: \&a[index]
  5845.   evaluate index (index * 4)
  5846.   if ( > index size ) echo Out of range!
  5847.  
  5848.    This is especially nice for loops that deal with arrays. Here, for
  5849.    example, is a loop that reverses the order of the elements in an array.
  5850.    Whereas formerly it was necessary to write:
  5851.  
  5852.   .\%n ::= \fdim(&a)
  5853.   for \%i 1 \%n/2 1 {
  5854.       .tmp := \&a[\%n-\%i+1]
  5855.       .\&a[\%n-\%i+1] := \&a[\%i]
  5856.       .\&a[\%i] := \m(tmp)
  5857.   }
  5858.  
  5859.    Recoding this to use macro names "i" and "n" instead of the backslash
  5860.    variables \%i and \%n, we have:
  5861.  
  5862.   .n ::= \fdim(&a)
  5863.   for i 1 n/2 1 {
  5864.       .tmp := \&a[n-i+1]
  5865.       .\&a[n-i+1] := \&a[i]
  5866.       .\&a[i] := \m(tmp)
  5867.   }
  5868.  
  5869.    which reduces the backslash count to less than half. The final
  5870.    statement in the loop could be written ".\&a[i] ::= tmp" if the array
  5871.    contained only numbers (since ::= indicates arithmetic expression
  5872.    evaluation).
  5873.  
  5874.    Also, now you can use floating-point numbers in integer contexts (such
  5875.    as array subscripts), in which case they are truncated to an integer
  5876.    value (i.e. the fractional part is discarded).
  5877.  
  5878.    Examples of numeric contexts include:
  5879.  
  5880.      * Array subscripts.
  5881.      * Any numeric function argument.
  5882.      * Right-hand side of ::= assignments.
  5883.      * EVALUATE command or \fevaluate() function expression.
  5884.      * The INCREMENT or DECREMENT by-value.
  5885.      * IF =, >, <, !=, >=, and <= comparands.
  5886.      * The IF number construct.
  5887.      * FOR-loop variables.
  5888.      * STOP, END, and EXIT status codes.
  5889.      * The INPUT timeout value.
  5890.      * PAUSE, WAIT, SLEEP, MSLEEP intervals.
  5891.      * The SHIFT argument.
  5892.      * Numeric switch arguments, e.g. TYPE /WIDTH:number, SEND
  5893.        /LARGER:number.
  5894.      * SCREEN MOVE-TO row and column number.
  5895.      * Various SET DIAL parameters (timeout, retry limit, etc).
  5896.      * Various SET SEND or RECEIVE parameters (packet length, window size,
  5897.        etc).
  5898.      * Various other SET parameters.
  5899.  
  5900.    and:
  5901.  
  5902.      * S-Expressions (explained in [410]Section 9).
  5903.  
  5904.    Macro names used in numeric contexts must not include mathematical
  5905.    operators. Although it is legal to create a macro called "foo+bar", in
  5906.    a numeric context this would be taken as the sum of the values of "foo"
  5907.    and "bar". Any such conflict can be avoided, of course, by enclosing
  5908.    the macro name in \m(...).
  5909.  
  5910.    [ [411]Top ] [ [412]Contents ] [ [413]C-Kermit Home ] [ [414]Kermit
  5911.    Home ]
  5912.  
  5913. 8.3. New IF Conditions
  5914.  
  5915.    Several new IF conditions are available:
  5916.  
  5917.    IF DECLARED arrayname
  5918.           Explained in [415]Section 8.6.
  5919.  
  5920.    IF KBHIT
  5921.           Allows a script to test whether a key was pressed without
  5922.           actually trying to read it.
  5923.  
  5924.    IF KERBANG (Unix only)
  5925.           True if Kermit was started from a Kerbang script. This is useful
  5926.           for knowing how to interpret the \&@[] and \&_[] argument vector
  5927.           arrays, and under what conditions to exit.
  5928.  
  5929.    IF INTEGER n
  5930.           This is just a synonym for IF NUMERIC, which is true if n
  5931.           contains only digits (or, if n is a variable, its value contains
  5932.           only digits).
  5933.  
  5934.    By contrast, IF FLOAT n succeeds if n is a floating-point number OR an
  5935.    integer (or a variable with floating-point or integer value).
  5936.    Therefore, IF FLOAT should be used whenever any kind of number is
  5937.    acceptable, whereas IF INTEGER (or IF NUMERIC) when only an integer can
  5938.    be used.
  5939.  
  5940.    [ [416]Top ] [ [417]Contents ] [ [418]C-Kermit Home ] [ [419]Kermit
  5941.    Home ]
  5942.  
  5943. 8.4. The ON_UNKNOWN_COMMAND Macro
  5944.  
  5945.    The new ON_UNKNOWN_COMMAND macro, if defined, is executed whenever you
  5946.    give a command that is not known to C-Kermit; any operands are passed
  5947.    as arguments. Here are some sample definitions:
  5948.  
  5949.   DEF ON_UNKNOWN_COMMAND telnet \%1 ; Treat unknown commands as hostnames
  5950.   DEF ON_UNKNOWN_COMMAND dial \%1   ; Treat unknown commands phone numbers
  5951.   DEF ON_UNKNOWN_COMMAND take \%1   ; Treat unknown commands as filenames
  5952.   DEF ON_UNKNOWN_COMMAND !\%*       ; Treat unknown commands as shell commands
  5953.  
  5954.    The ON_CD macro, if defined, is executed whenever Kermit is given a CD
  5955.    (change directory) command (8.0.211). Upon entry to this macro, the
  5956.    directory has already changed and the new directory string is available
  5957.    in the \v(directory) variable, and also as the first argument (\%1).
  5958.  
  5959.    [ [420]Top ] [ [421]Contents ] [ [422]C-Kermit Home ] [ [423]Kermit
  5960.    Home ]
  5961.  
  5962. 8.5. The SHOW MACRO Command
  5963.  
  5964.    The SHOW MACRO command has been changed to accept more than one macro
  5965.    name:
  5966.  
  5967.   (setq a 1 b 2 c 3)
  5968.   show mac a b c
  5969.   a = 1
  5970.   b = 2
  5971.   c = 3
  5972.  
  5973.    An exact match is required for each name (except that case doesn't
  5974.    matter). If you include wildcard characters, however, a pattern match
  5975.    is performed:
  5976.  
  5977.   show mac [a-c]*x
  5978.  
  5979.    shows all macros whose names start with a, b, or c, and end with x.
  5980.  
  5981.    [ [424]Top ] [ [425]Contents ] [ [426]C-Kermit Home ] [ [427]Kermit
  5982.    Home ]
  5983.  
  5984. 8.6. Arrays
  5985.  
  5986.    A clarification regarding references to array names (as opposed to
  5987.    array elements): You can use array-name "abbreviations" like &a only in
  5988.    contexts that expect array names, like ARRAY commands or array-name
  5989.    function arguments such as the second argument of \fsplit(). In a LOCAL
  5990.    statement, however, you have to write \&a[], since "local &a" might
  5991.    refer to a macro named "&a".
  5992.  
  5993.    In function arguments, however, you MUST use the abbreviated form:
  5994.    \fsplit(\%a,&a) or \fsplit(\%a,&a[]). If you include the backslash (as
  5995.    in "\fsplit(\%a,\&a[])") a parse error occurs.
  5996.  
  5997.    Here are the new array-related commands:
  5998.  
  5999.    IF DECLARED arrayname
  6000.           Allows a script to test whether an array has been declared. The
  6001.           arrayname can be a non-array backslash variable such as \%1 or
  6002.           \m(name), in which case it is evaluated first, and the result is
  6003.           treated as the array name. Otherwise, arrayname is treated as in
  6004.           the ARRAY commands: it can be a, &a, &a[], \&a, \&a[], \&a[3],
  6005.           \&a[3:9], etc, with the appropriate results in each case.
  6006.           Synonym: IF DCL.
  6007.  
  6008.    UNDECLARE arrayname
  6009.           UNDECLARE is a new top-level command to undeclare an array.
  6010.           Previously this could only be done with "declare \&a[0]" (i.e.
  6011.           re-declare the array with a dimension of 0).
  6012.  
  6013.    ARRAY LINK linkname arrayname
  6014.           Creates a symbolic link from the array named by linkname (which
  6015.           must be the name of an array that is not yet declared in the
  6016.           current context) to the array named by arrayname (which must the
  6017.           name of a currently declared array that is not itself a link, or
  6018.           a variable containing the name of such an array). The two names
  6019.           indicate the same array: if you change an array element, the
  6020.           change is reflected in the link too, and vice versa. If you
  6021.           undeclare the link, the real array is unaffected. If you
  6022.           undeclare the real array, all links to it disappear. If you
  6023.           resize an array (directly or through a link), all links to it
  6024.           are updated automatically.
  6025.  
  6026.    Array links let you pass array names as arguments to macros. For
  6027.    example, suppose you had a program that needed to uppercase all the
  6028.    elements of different arrays at different times. You could write a
  6029.    macro to do this, with the array name as an argument. But without array
  6030.    links, there would be no way to refer to the argument array within the
  6031.    macro. Array links make it easy:
  6032.  
  6033.   define arrayupper {
  6034.       local \&e[] \%i
  6035.       array link \&e[] \%1
  6036.       for i 1 \fdim(&e) 1 { .\&e[i] := \fupper(\&e[i]) }
  6037.   }
  6038.   declare \&a[] = these are some words
  6039.   arrayupper &a
  6040.   show array &a
  6041.  
  6042.    The macro declares the array link LOCAL, which means it doesn't
  6043.    conflict with any array of the same name that might exist outside the
  6044.    macro, and that the link is destroyed automatically when the macro
  6045.    exits. This works, by the way, even if the link name and the macro
  6046.    argument name are the same, as long as the link is declared LOCAL.
  6047.  
  6048.    As noted, you can't make a link to a nonexistent array. So when writing
  6049.    a macro whose job is to create an array whose name is passed as an
  6050.    argument, you must declare the array first (the size doesn't matter as
  6051.    long as it's greater than 0). Example:
  6052.  
  6053.   define tryme {                ; Demonstration macro
  6054.       local \&e[]               ; We only need this inside the macro
  6055.       array link \&e[] \%1      ; Make local link
  6056.       shift                     ; Shift argument list
  6057.       void \fsplit(\%*,&e)      ; Split remainder of arg list into array
  6058.   }
  6059.   declare \&a[1]                ; Declare target array in advance
  6060.   tryme &a here are some words  ; Invoke the macro with array name and words
  6061.   show array a                  ; See the results
  6062.  
  6063.    One final improvement allows the macro itself to declare the array
  6064.    (this was not possible in earlier Kermit releases): if the array name
  6065.    in the DECLARE command is a variable (and not an array name), or
  6066.    includes variables, the resulting value is used as the array name. So:
  6067.  
  6068.   define tryme {                ; Demonstration macro
  6069.       declare \%1[1]            ; Preliminary declaration for target array
  6070.       local \&e[]               ; We only need this inside the macro
  6071.       array link \&e[] \%1      ; Make local link
  6072.       shift                     ; Shift argument list
  6073.       void \fsplit(\%*,&e)      ; Split remainder of arg list into array
  6074.   }
  6075.   tryme &a here are some words  ; Invoke the macro with array name and words
  6076.   show array a                  ; See the results
  6077.  
  6078.    The SHOW ARRAY command now indicates whether an array name is a link.
  6079.  
  6080.    Also see the descriptions of [428]\fjoin() and [429]\fsplit(), plus
  6081.    [430]Section 8.10 on the MINPUT command, which shows how an entire
  6082.    array (or segment of it) can be used as the MINPUT target list.
  6083.  
  6084.    [ [431]Top ] [ [432]Contents ] [ [433]C-Kermit Home ] [ [434]Kermit
  6085.    Home ]
  6086.  
  6087. 8.7. New or Improved Built-in Variables and Functions
  6088.  
  6089.    The following new built-in variables are available:
  6090.  
  6091.   \v(buildid)       A date string like "20000808" indicating when C-Kermit was b
  6092. uilt.
  6093.   \v(ftime)         Current time, secs since midnight, including fraction of sec
  6094. ond.
  6095.   \v(iprompt)       The current SET PROMPT value
  6096.   \v(sexp)          The most recent S-Expression (see [435]Section 9)
  6097.   \v(sdepth)        The current S-Expression invocation depth ([436]Section 9)
  6098.   \v(svalue)        The value of the most recent S-Expression ([437]Section 9)
  6099.  
  6100.   \v(ftp_code)      Most recent FTP response code ([438]Section 3)
  6101.   \v(ftp_connected) FTP connection status ([439]Section 3)
  6102.   \v(ftp_cpl)       FTP Command Protection Level ([440]Section 3.2)
  6103.   \v(ftp_dpl)       FTP Data Protection Level ([441]Section 3.2)
  6104.   \v(ftp_getputremote) The current SET GET-PUT-REMOTE setting ([442]Section 3.8)
  6105.  
  6106.   \v(ftp_host)      Name or IP address of FTP server ([443]Section 3)
  6107.   \v(ftp_loggedin)  FTP login status ([444]Section 3)
  6108.   \v(ftp_message)   Most recent FTP response message ([445]Section 3)
  6109.   \v(ftp_security)  FTP Security method ([446]Section 3.2)
  6110.   \v(ftp_server)    OS type of FTP server ([447]Section 3)
  6111.  
  6112.   \v(http_code)       Most recent HTTP response code
  6113.   \v(http_connected)  HTTP connection status
  6114.   \v(http_host)       Name or IP address of HTTP server
  6115.   \v(http_message)    Most recent HTTP response message
  6116.   \v(http_security)   TLS cipher used to secure the HTTP session
  6117.  
  6118.   \v(hour)            Hour of the day, 0 to 23.
  6119.   \v(timestamp)       Equivalent to "\v(ndate) \v(time)".
  6120.  
  6121.   \v(log_debug)       Current debug log file, if any.
  6122.   \v(log_packet)      Current packet log file, if any.
  6123.   \v(log_session)     Current session log file, if any.
  6124.   \v(log_transaction) Current transaction log file, if any.
  6125.   \v(log_connection)  Current connection log file, if any.
  6126.  
  6127.    The following new or improved built-in functions are available:
  6128.  
  6129.   \fcmdstack()            Allows programmatic access to the command stack.
  6130.   \fcvtdate()             [448]Section 8.13, format options added
  6131.   \fdelta2secs()          [449]Section 8.13
  6132.   \fdostounixpath(s1)     Converts a DOS filename to Unix format.
  6133.   \fsplit()               Now allows grouping/nesting in source string.
  6134.   \fword()                Allows the same grouping and nesting.
  6135.   \fjoin(&a,s1,n1,n2)     Copies an array into a single string.
  6136.   \fsubstitute(s1,s2,s3)  Substitutes characters within a string.
  6137.   \freplace()             Has new 4th "occurrence" argument.
  6138.   \fsexpression()         Evaluates an S-Expression (explained in [450]Section 9
  6139. ).
  6140.   \ftrim(), \fltrim()     Now trim CR and LF by default, as well as SP and Tab.
  6141.   \funixtodospath(s1)     Converts a Unix filename to DOS format.
  6142.   \fkeywordval(s1,c1)     Assigns values to keywords (macros) (explained below).
  6143.  
  6144.    Most functions that have "2" in their names to stand for the word "to"
  6145.    can now also be written with "to", e.g. "\fdelta2secs(),"
  6146.    \fdeltatosecs()."
  6147.  
  6148.    \funtabify(string)
  6149.           (New to 8.0.211) Replaces Horizontal Tab characters in the given
  6150.           string with spaces based on VT100-like tab stops.
  6151.  
  6152.    \fverify(s1,s2,n)
  6153.           As of version 8.0.211, returns -1 if s2 is an empty string.
  6154.           Previously it returned 0, making \fverify(abc,\%a) look as if
  6155.           \%a was a string composed of a's, b's, and/or c's when in fact
  6156.           it contained nothing.
  6157.  
  6158.    \fcode(string)
  6159.           As of version 8.0.211, returns 0 if string is empty or missing.
  6160.           Previously it returned the empty string, which made it unsafe to
  6161.           use in arithmetic or boolean expressions.
  6162.  
  6163.    \v(inscale)
  6164.           New to version 8.0.211, its value is the INPUT SCALE-FACTOR
  6165.           ([451]Section 8.10), default 1.0.
  6166.  
  6167. 8.7.1. The \fkeywordval() Function
  6168.  
  6169.    \fkeywordval(s1,c1) is new to C-Kermit 8.0. Given a string s1 of the
  6170.    form "name=value", it creates a macro with the given name and assigns
  6171.    it the given value. If no value appears after the equal sign, any
  6172.    existing macro of the given name is undefined. Blanks are automatically
  6173.    trimmed from around the name and value. The optional c1 parameter is
  6174.    the assignment operator character, equal sign (=) by default. This
  6175.    function is handy for processing keyword parameters or any other form
  6176.    of parameter-value pair. Suppose, for example, you want to write a
  6177.    macro that accepts keyword parameters rather than positional ones:
  6178.  
  6179.   define MYDIAL {
  6180.       local \%i modem hangup method device speed number
  6181.       def number 5551234          ; Assign default parameter values
  6182.       def speed 57600
  6183.       def modem usrobotics
  6184.       def hangup rs232
  6185.       def method tone
  6186.       def country 1
  6187.       for \%i 1 \v(argc)-1 1 {    ; Parse any keyword parameters...
  6188.           if not \fkeywordval(\&_[\%i]) end 1 Bad parameter: "\&_[\%i]"
  6189.       }
  6190.       set dial country \m(country)
  6191.       set modem type \m(modem)
  6192.       set modem hang \m(hangup)
  6193.       set dial method \m(tone)
  6194.       set line \m(device)
  6195.       if fail stop 1
  6196.       set speed \m(speed)
  6197.       if fail stop 1
  6198.       show comm
  6199.       set dial display on
  6200.       dial \m(number)
  6201.       if success connect
  6202.   }
  6203.  
  6204.    In this example, all the defaults are set up inside the macro, and
  6205.    therefore it can be invoked with no parameters at all. But if you want
  6206.    to have the macro dial a different number, you can supply it as
  6207.    follows:
  6208.  
  6209.   mydial number=7654321
  6210.  
  6211.    You can supply any number of keyword parameters, and you can give them
  6212.    in any order:
  6213.  
  6214.   mydial number=7654321 hangup=modem speed=115200
  6215.  
  6216. 8.7.2. The \fsplit(), \fjoin(), and \fword() Functions
  6217.  
  6218.    \fjoin(&a,s1,n1,n2) is also new; it creates a string from an array (or
  6219.    a piece of one). &a is the name of the array (a range specifier can be
  6220.    included); s1 is a character or string to separate each element in the
  6221.    result string (can be omitted, in which case the elements are not
  6222.    separated at all), and n1 is a grouping mask, explained below. If s1 is
  6223.    empty or not specified, the array elements are separated with spaces.
  6224.    If you want the elements concatenated with no separator, include a
  6225.    nonzero n2 argument. Given the array:
  6226.  
  6227.   declare \&a[] = 0 1 2 3 4 5 6 7 8 9
  6228.  
  6229.    you can get effects like this:
  6230.  
  6231.   \fjoin(&a)      0 1 2 3 4 5 6 7 8 9
  6232.   \fjoin(&a,:)    0:1:2:3:4:5:6:7:8:9
  6233.   \fjoin(&a,{,})  0,1,2,3,4,5,6,7,8,9
  6234.   \fjoin(&a,...)  0...1...2...3...4...5...6...7...8...9
  6235.   \fjoin(&a,,,1)  0123456789
  6236.  
  6237.    \fsplit(), \fword(), \fstripb(), and \fjoin() accept a "grouping mask"
  6238.    argument, n1, which is a number from 0 to 63, in which:
  6239.  
  6240.    1 = "" doublequotes
  6241.    2 = {} braces
  6242.    4 = '' singlequotes
  6243.    8 = () parentheses
  6244.   16 = [] square brackets
  6245.   32 = <> angle brackets
  6246.  
  6247.    These can be OR'd (added) together to make any number 0-63 (-1 is
  6248.    treated the same as 63, 0 means no grouping). If a bit is on, the
  6249.    corresponding kind of grouping is selected. (If more than 1 bit is set
  6250.    for \fjoin(), only the lowest-order one is used.)
  6251.  
  6252.    If you include the same character in the grouping mask and the include
  6253.    list, the grouping mask takes precedence. Example:
  6254.  
  6255.   def \%a  a "b c d" e
  6256.   \fsplit(\%a,&a[],,,-1)  = 3  <-- doublequote used for grouping
  6257.   \fsplit(\%a,&a[],,",-1) = 3  <-- doublequote still used for grouping
  6258.  
  6259.    Nesting of matched left and right grouping characters (parentheses,
  6260.    braces, and brackets, but not quotes) is recognized. Example:
  6261.  
  6262.   def \%a a (b c <d e [f g {h i} j k] l m> n o) p
  6263.   \fsplit(\%a,&a,,,0)  = 16 (no grouping)
  6264.   \fsplit(\%a,&a,,,2)  = 15 (braces only)
  6265.   \fsplit(\%a,&a,,,16) = 11 (square brackets only)
  6266.   \fsplit(\%a,&a,,,32) =  7 (angle brackets only)
  6267.   \fsplit(\%a,&a,,,63) =  3 (all)
  6268.   \fsplit(\%a,&a,,,-1) =  3 (all)
  6269.  
  6270.    \fsplit() and \fjoin() are "reciprocal" functions. You can split a
  6271.    string up into an array and join it back into a new string that is
  6272.    equivalent, as long as \fsplit() and \fjoin() are given equivalent
  6273.    grouping masks, except that the type of braces might change. Example:
  6274.  
  6275.   def \%a a {b c [d e] f g} "h i" j <k l> m
  6276.   echo STRING=[\%a]
  6277.   echo WORDS=\fsplit(\%a,&a,,,-1)
  6278.   show array a
  6279.   asg \%b \fjoin(&a,{ },2)
  6280.   echo JOIN  =[\%b]
  6281.   echo WORDS=\fsplit(\%b,&b,,,-1)
  6282.   show array b
  6283.  
  6284.    The arrays a and b are identical. The strings a and b are as follows:
  6285.  
  6286.   \%a: a {b c [d e] f g} "h i" j <k l> m
  6287.   \%b: a {b c [d e] f g} {h i} j {k l} m
  6288.  
  6289.    It is possible to quote separator grouping characters with backslash to
  6290.    override their grouping function. And of course to include backslash
  6291.    itself in the string, it must be quoted too. Furthermore, each
  6292.    backslash must be doubled, so the command parser will still pass one
  6293.    backslash to \fsplit() for each two that it sees. Here are some
  6294.    examples using \fsplit() with a grouping mask of 8 (treat parentheses
  6295.    as grouping characters).
  6296.  
  6297.   String                  Result
  6298.     a b c d e f             6
  6299.     a b\\ c d e f           5
  6300.     a b (c d e) f           4
  6301.     a b \\(c d e\\) f       6
  6302.     a b \\\\(c d e\\\\) f   7
  6303.  
  6304.    \fsplit() has also been changed to create its array (if one is given)
  6305.    each time it is called, so now it can be conveniently called in a loop
  6306.    without having to redeclare the array each time.
  6307.  
  6308.    Incidentally... Sometimes you might want to invoke \fsplit() in a
  6309.    situation where you don't care about its return value, e.g. when you
  6310.    just want to fill the array. Now you can "call" \fsplit() or any other
  6311.    function with the new [452]VOID command:
  6312.  
  6313.   void \fsplit(\%a,&a)
  6314.  
  6315.    \fsplit() and \fjoin() also accept a new, optional 6th argument, an
  6316.    options flag, a number that can specify a number of options. So far
  6317.    there is just one option, whose value is 1:
  6318.  
  6319.    separator-flag
  6320.           Normally separators are collapsed. So, for example,
  6321.  
  6322.   \fword(Three        little          words,2)
  6323.  
  6324.           returns "little" (the second word). Space is a separator, but
  6325.           there are multiple spaces between each word. If the value 1 is
  6326.           included in the option flag, however, each separator counts. If
  6327.           two separators are adjacent, an empty word is produced between
  6328.           them. This is useful for parsing (e.g.) comma-separated lists
  6329.           exported from databases or spreadsheets.
  6330.  
  6331. 8.7.3. The \fcmdstack() Function
  6332.  
  6333.    The new \fcmdstack() function gives access to the command stack:
  6334.  
  6335.    \fcmdstack(n1,n2)
  6336.           Arguments: n1 is the command stack level. If omitted, the
  6337.           current level, \v(cmdlevel), is used. n2 is a function code
  6338.           specifying the desired type of information:
  6339.  
  6340.   0 (default) = name of object at level n1.
  6341.   1 (nonzero) = object type (0 = prompt; 1 = command file; 2 = macro).
  6342.  
  6343.           The default for n2 is 0.
  6344.  
  6345.    The name associated with prompt is "(prompt)". Here's a loop that can
  6346.    be included in a macro or command file to show the stack (similar to
  6347.    what the SHOW STACK command does):
  6348.  
  6349.   for \%i \v(cmdlevel) 0 -1 {
  6350.       echo \%i. [\fcmdstack(\%i,1)] \fcmdstack(\%i,0)
  6351.   }
  6352.  
  6353.    In this connection, note that \v(cmdfile) always indicates the most
  6354.    recently invoked active command file (if any), even if that file is
  6355.    executing a macro. Similarly, \v(macro) indicates the most recently
  6356.    invoked macro (if any), even if the current command source is not a
  6357.    macro. The name of the "caller" of the currently executing object
  6358.    (command file or macro) is:
  6359.  
  6360.   \fcmdstack(\v(cmdlevel)-1)
  6361.  
  6362.    and its type is:
  6363.  
  6364.   \fcmdstack(\v(cmdlevel)-1,1)
  6365.  
  6366.    To find the name of the macro that invoked the currently executing
  6367.    object, even if one or more intermediate command files (or prompting
  6368.    levels) are involved, use a loop like this:
  6369.  
  6370.   for \%i \v(cmdlevel)-1 0 -1 {
  6371.       if = \fcmdstack(\%i,1) 2 echo CALLER = \fcmdstack(\%i,0)
  6372.   }
  6373.  
  6374.    Of course if you make a macro to do this, the macro must account for
  6375.    its own additional level:
  6376.  
  6377.   define CALLER {
  6378.       for \%i \v(cmdlevel)-2 0 -1 {
  6379.           if = \fcmdstack(\%i,1) 2 return \fcmdstack(\%i,0)
  6380.       }
  6381.       return "(none)"
  6382.   }
  6383.  
  6384.    The built-in variable \v(cmdsource) gives the current command source as
  6385.    a word ("prompt", "file", or "macro").
  6386.  
  6387. 8.7.4. The VOID Command
  6388.  
  6389.    VOID is like ECHO in that all functions and variables in its argument
  6390.    text are evaluated. but it doesn't print anything (except possibly an
  6391.    error message if a function was invocation contained or resulted in any
  6392.    errors). VOID sets FAILURE if it encounters any errors, SUCCESS
  6393.    otherwise.
  6394.  
  6395.    [ [453]Top ] [ [454]Contents ] [ [455]C-Kermit Home ] [ [456]Kermit
  6396.    Home ]
  6397.  
  6398. 8.8. The RETURN and END Commands
  6399.  
  6400.    The execution of a macro is terminated in any of the following ways:
  6401.  
  6402.      * With an END [ number [ message ] ] command. If a number is given,
  6403.        the macro succeeds if the number is 0, and fails if it is not zero;
  6404.        if a number is not given, the macro succeeds.
  6405.      * With a STOP command, which works just like END except it peels back
  6406.        the command stack all the way to top level.
  6407.      * With a RETURN [ text ] command, in which case the macro always
  6408.        succeeds.
  6409.      * By running out of commands to execute, in which case the macro
  6410.        succeeds or fails according the most recently executed command that
  6411.        sets success or failure.
  6412.  
  6413.    The same considerations apply to command files invoked by the TAKE
  6414.    command.
  6415.  
  6416.    If a macro does not execute any commands that set success or failure,
  6417.    then invoking the macro does not change the current SUCCESS/FAILURE
  6418.    status. It follows, then, that the mere invocation of a macro does not
  6419.    change the SUCCESS/FAILURE status either. This makes it possible to
  6420.    write macros to react to the status of other commands (or macros), for
  6421.    example:
  6422.  
  6423.   define CHKLINE {
  6424.       if success end 0
  6425.       stop 1 SET LINE failed - please try another device.
  6426.   }
  6427.   set modem type usrobotics
  6428.   set line /dev/cua0
  6429.   chkline
  6430.   set speed 57600
  6431.   dial 7654321
  6432.  
  6433.    By the way, none of this is news. But it was not explicitly documented
  6434.    before, and C-Kermit 7.0 and earlier did not always handle the RETURN
  6435.    statement as it should have.
  6436.  
  6437.    [ [457]Top ] [ [458]Contents ] [ [459]C-Kermit Home ] [ [460]Kermit
  6438.    Home ]
  6439.  
  6440. 8.9. UNDEFINing Groups of Variables
  6441.  
  6442.    The UNDEFINE command, which previously accepted one variable name, now
  6443.    accepts a list of them, and also accepts wildcard notation to allow
  6444.    deletion of variables that match a given pattern.
  6445.  
  6446.    UNDEFINE [ switches ] name [ name [ name [ ... ] ] ]
  6447.           Undefines the variables whose names are given. Up to 64 names
  6448.           may be given in one UNDEFINE command.
  6449.  
  6450.    If you omit the switches and include only one name, the UNDEFINE
  6451.    command works as before.
  6452.  
  6453.    Switches include:
  6454.  
  6455.    /MATCHING
  6456.           Specifies that the names given are to treated as patterns rather
  6457.           than literal variable names. Note: pattern matching can't be
  6458.           used with array references; use the ARRAY command to manipulate
  6459.           arrays and subarrays.
  6460.  
  6461.    /LIST
  6462.           List the name of each variable to be undefined, and whether it
  6463.           was undefined successfully ("ok" or "error"), plus a summary
  6464.           count at the end.
  6465.  
  6466.    /SIMULATE
  6467.           List the names of the variables that would be deleted without
  6468.           actually deleting them. Implies /LIST.
  6469.  
  6470.    The UNDEFINE command fails if there were any errors and succeeds
  6471.    otherwise.
  6472.  
  6473.    The new _UNDEFINE command is like UNDEFINE, except the names are
  6474.    assumed to be variable names themselves, which contain the names (or
  6475.    parts of them) of the variables to be undefined. For example, if you
  6476.    have the following definitions:
  6477.  
  6478.   define \%a foo
  6479.   define foo This is some text
  6480.  
  6481.    then:
  6482.  
  6483.   undef \%a
  6484.  
  6485.    undefines the variable \%a, but:
  6486.  
  6487.   _undef \%a
  6488.  
  6489.    undefines the macro foo.
  6490.  
  6491.    Normal Kermit patterns are used for matching; metacharacters include
  6492.    asterisk, question mark, braces, and square brackets. Thus, when using
  6493.    the /MATCHING switch, if the names of the macros you want to undefine
  6494.    contain any of these characters, you must quote them with backslash to
  6495.    force them to be taken literally. Also note that \%* is not the name of
  6496.    a variable; it is a special notation used within a macro for "all my
  6497.    arguments". The command "undef /match \%*" deletes all \%x variables,
  6498.    where x is 0..9 and a..z. Use "undef /match \%[0-9]" to delete macro
  6499.    argument variables or "undef /match \%[i-n]" to delete a range of \%x
  6500.    variables.
  6501.  
  6502.    [ [461]Top ] [ [462]Contents ] [ [463]C-Kermit Home ] [ [464]Kermit
  6503.    Home ]
  6504.  
  6505. 8.10. The INPUT and MINPUT Commands
  6506.  
  6507.    As of C-Kermit 8.0.211, the INPUT and MINPUT commands accept a switch:
  6508.  
  6509.    [M]INPUT /NOMATCH timeout
  6510.           The /NOMATCH switch allows INPUT or MINPUT to read incoming
  6511.           material for the specified amount of time, without attempting to
  6512.           match it with any text or patterns. When this switch is
  6513.           included, the [M]INPUT command succeeds when the timeout
  6514.           interval expires, with \v(instatus) set to 1, meaning "timed
  6515.           out", or fails upon interruption or i/o error.
  6516.  
  6517.    Also in version 8.0.211, there is a new way to apply a scale factor to
  6518.    [M]INPUT timeouts:
  6519.  
  6520.    SET INPUT SCALE-FACTOR floating-point-number
  6521.           This scales all [M]INPUT timeouts by the given factor, allowing
  6522.           time-sensitive scripts to be adjusted to changing conditions
  6523.           such as congested networks or different-speed modems without
  6524.           having to change each INPUT-class command. This affects only
  6525.           those timeouts that are given in seconds, not as wall-clock
  6526.           times. Although the scale factor can have a fractional part, the
  6527.           INPUT timeout is still an integer. The new built-in variable
  6528.           \v(inscale) tells the current INPUT SCALE-FACTOR.
  6529.  
  6530.    The MINPUT command can be used to search the incoming data stream for
  6531.    several targets simultaneously. For example:
  6532.  
  6533.   MINPUT 8 one two three
  6534.  
  6535.    waits up to 8 seconds for one of the words "one", "two", or "three" to
  6536.    arrive. Words can be grouped to indicate targets that contain spaces:
  6537.  
  6538.   MINPUT 8 nineteen twenty "twenty one"
  6539.  
  6540.    And of course you can also use variables in place of (or as part of)
  6541.    the target names:
  6542.  
  6543.   MINPUT 8 \%a \&x[3] \m(foo)
  6544.  
  6545.    Until now you had to know the number of targets in advance when writing
  6546.    the MINPUT statement. Each of the examples above has exactly three
  6547.    targets.
  6548.  
  6549.    But suppose your script needs to look for a variable number of targets.
  6550.    For this you can use arrays and \fjoin(), described in [465]Section
  6551.    8.7. Any number of \fjoin() invocations can be included in the MINPUT
  6552.    target list, and each one is expanded into the appropriate number of
  6553.    separate targets each time the MINPUT command is executed. Example:
  6554.  
  6555.   declare \&a[10] = one two three
  6556.   minput 10 foo \fjoin(&a) bar
  6557.  
  6558.    This declares an array of ten elements, and assigns values to the first
  6559.    three of them. The MINPUT command looks for these three (as well as the
  6560.    words "foo" and "bar"). Later, if you assign additional elements to the
  6561.    array, the same MINPUT command also looks for the new elements.
  6562.  
  6563.    If an array element contains spaces, each word becomes a separate
  6564.    target. To create one target per array element, use \fjoin()'s grouping
  6565.    feature:
  6566.  
  6567.   dcl \&a[] = {aaa bbb} {ccc ddd} {xxx yyy zzz}
  6568.  
  6569.   minput 10 \fjoin(&a)     <-- 7 targets
  6570.   minput 10 \fjoin(&a,,2)  <-- 3 targets
  6571.  
  6572.    [ [466]Top ] [ [467]Contents ] [ [468]C-Kermit Home ] [ [469]Kermit
  6573.    Home ]
  6574.  
  6575. 8.11. Learned Scripts
  6576.  
  6577.    C-Kermit now includes a simple script recorder that monitors your
  6578.    commands, plus your actions during CONNECT mode, and automatically
  6579.    generates a script program that mimics what it observed. You should
  6580.    think of this feature as a script-writing ASSISTANT since, as you will
  6581.    see [470]later in this section, the result generally needs some editing
  6582.    to make it both secure and flexible. The script recorder is controlled
  6583.    by the new LEARN command:
  6584.  
  6585.    LEARN [ /ON /OFF /CLOSE ] [ filename ]
  6586.           If you give a filename, the file is opened for subsequent
  6587.           recording. The /ON switch enables recording to the current file
  6588.           (if any); /OFF disables recording. /CLOSE closes the current
  6589.           script recording file (if any). If you give a filename without
  6590.           any switches, /ON is assumed.
  6591.  
  6592.    The /OFF and /ON switches let you turn recording off and on during a
  6593.    session without closing the file.
  6594.  
  6595.    When recording:
  6596.  
  6597.      * All commands that you type (or recall) at the prompt are recorded
  6598.        in the file except:
  6599.           + LEARN commands are not recorded.
  6600.           + The CONNECT command is not recorded.
  6601.           + The TELNET command is converted to SET HOST /NETWORK:TCP.
  6602.      * Commands obtained from macros or command files are not recorded.
  6603.      * During CONNECT:
  6604.           + Every line you type is converted to an OUTPUT command.
  6605.           + The last prompt before any line you type becomes an INPUT
  6606.             command.
  6607.           + Timeouts are calculated automatically for each INPUT command.
  6608.           + A PAUSE command is inserted before each OUTPUT command just to
  6609.             be safe.
  6610.  
  6611.    Thus the script recorder is inherently line-oriented. It can't be used
  6612.    to script character-oriented interactions like typing Space to a
  6613.    "More?" prompt or editing a text file with VI or EMACS.
  6614.  
  6615.    But it has advantages too; for example it takes control characters into
  6616.    account that might not be visible to you otherwise, and it
  6617.    automatically converts control characters in both the input and output
  6618.    streams to the appropriate notation. It can tell, for example that the
  6619.    "$ " prompt on the left margin in UNIX is really {\{13}\{10}$ },
  6620.    whereas in VMS it might be {\{13}\{10}\{13}$ }. These sequences are
  6621.    detected and recorded automatically.
  6622.  
  6623.    A learned script should execute correctly when you give a TAKE command
  6624.    for it. However, it is usually appropriate to edit the script a bit.
  6625.    The most important change would be to remove any passwords from it. For
  6626.    example, if the script contains:
  6627.  
  6628.   INPUT 9 {\{13}\{10}Password: }
  6629.   IF FAIL STOP 1 INPUT timeout
  6630.   PAUSE 1
  6631.   OUTPUT bigsecret\{13}
  6632.  
  6633.    you should replace this by something like:
  6634.  
  6635.   INPUT 9 {\{13}\{10}Password: }
  6636.   IF FAIL STOP 1 INPUT timeout
  6637.   ASKQ pswd Please type your password:
  6638.   PAUSE 1
  6639.   OUTPUT \m(pswd)\{13}
  6640.  
  6641.    The LEARN command can't do this for you since it knows nothing about
  6642.    "content"; it only knows about lines and can't be expected to parse or
  6643.    understand them -- after all, the Password prompt might be in some
  6644.    other language. So remember: if you use the LEARN command to record a
  6645.    login script, be sure edit the resulting file to remove any passwords.
  6646.    Also be sure to delete any backup copies your editor or OS might have
  6647.    made of the file.
  6648.  
  6649.    Other manual adjustments might also be appropriate:
  6650.  
  6651.      * If the target of an INPUT command can vary, you can replace the
  6652.        INPUT command with MINPUT and the appropriate target list, and/or
  6653.        the target with a \fpattern(). For example, suppose you are dialing
  6654.        a number that can be answered by any one of 100 terminal servers,
  6655.        whose prompts are ts-00>, ts-01>, ts-02>, ... ts-99>. The script
  6656.        records a particular one of these, but you want it to work for all
  6657.        of them, so change (e.g.):
  6658.   INPUT 10 ts-23>  ; or whatever
  6659.  
  6660.        to:
  6661.   INPUT 10 \fpattern(ts-[0-9][0-9]>)
  6662.  
  6663.      * The INPUT timeout values are conservative, but they are based only
  6664.        on a single observation; you might need to tune them.
  6665.      * The PAUSE commands might not be necessary, or the PAUSE interval
  6666.        might need adjustment.
  6667.      * In case you made typographical errors during recording, they are
  6668.        incorporated in your script; you can edit them out if you want to.
  6669.  
  6670.    Here is a sample script generated by Kermit ("learn vms.ksc") in which
  6671.    a Telnet connection is made to a VMS computer, the user logs in, starts
  6672.    Kermit on VMS, sends it a file, and then logs out:
  6673.  
  6674.   ; Scriptfile: vms.ksc
  6675.   ; Directory:  /usr/olga
  6676.   ; Recorded:   20001124 15:21:23
  6677.  
  6678.   SET HOST /NETWORK:TCP vms.xyzcorp.com
  6679.   IF FAIL STOP 1 Connection failed
  6680.  
  6681.   INPUT 7 {\{13}\{10}\{13}Username: }
  6682.   IF FAIL STOP 1 INPUT timeout
  6683.   PAUSE 1
  6684.   OUTPUT olga\{13}
  6685.   INPUT 3 {\{13}\{10}\{13}Password: }
  6686.   IF FAIL STOP 1 INPUT timeout
  6687.   PAUSE 1
  6688.   OUTPUT secret\{13}
  6689.   INPUT 18 {\{13}\{10}\{13}$ }
  6690.   IF FAIL STOP 1 INPUT timeout
  6691.   PAUSE 1
  6692.   OUTPUT set default [.incoming]\{13}
  6693.   INPUT 12 {\{13}\{10}\{13}$ }
  6694.   IF FAIL STOP 1 INPUT timeout
  6695.   PAUSE 1
  6696.   OUTPUT kermit\{13}
  6697.   INPUT 15 {\{13}\{10}\{13}ALTO:[OLGA.INCOMING] C-Kermit>}
  6698.   IF FAIL STOP 1 INPUT timeout
  6699.   PAUSE 1
  6700.   OUTPUT receive\{13}
  6701.   send myfile.txt
  6702.  
  6703.   INPUT 18 {\{13}\{10}\{13}ALTO:[OLGA.INCOMING] C-Kermit>}
  6704.   IF FAIL STOP 1 INPUT timeout
  6705.   PAUSE 1
  6706.   OUTPUT exit\{13}
  6707.   INPUT 6 {\{13}\{10}\{13}$ }
  6708.   IF FAIL STOP 1 INPUT timeout
  6709.   PAUSE 1
  6710.   OUTPUT logout\{13}
  6711.   close
  6712.   exit
  6713.  
  6714.    The commands generated by Kermit during CONNECT (INPUT, IF FAIL, PAUSE,
  6715.    and OUTPUT) have uppercase keywords; the commands typed by the user are
  6716.    in whatever form the user typed them (in this case, lowercase).
  6717.  
  6718.    [ [471]Top ] [ [472]Contents ] [ [473]C-Kermit Home ] [ [474]Kermit
  6719.    Home ]
  6720.  
  6721. 8.12. Pattern Matching
  6722.  
  6723.    A pattern is a character string that is used to match other strings.
  6724.    Patterns can contain metacharacters that represent special actions like
  6725.    "match any single character", "match zero or more characters", "match
  6726.    any single character from a list", and so on. The best known
  6727.    application of patterns is in file specifications that contain
  6728.    wildcards, as in "send *.txt", meaning "send all files whose names end
  6729.    with .txt".
  6730.  
  6731.    Patterns are also used in increasingly many other ways, to the extent
  6732.    it is useful to point out certain important distinctions in the ways in
  6733.    which they are used:
  6734.  
  6735.    Anchored Patterns
  6736.           If an anchored pattern does not begin with "*", it must match
  6737.           the beginning of the string, and if it does not end with "*", it
  6738.           must match the end of the string. For example, the anchored
  6739.           pattern "abc" matches only the string "abc", not "abcde" or
  6740.           "xyzabc" or "abcabc". The anchored pattern "abc*" matches any
  6741.           string that starts with "abc"; the anchored pattern "*abc"
  6742.           matches any string that ends with "abc"; the anchored pattern
  6743.           "*abc*" matches any string that contains "abc" (including any
  6744.           that start and/or end with it).
  6745.  
  6746.    Floating Patterns
  6747.           A floating pattern matches any string that contains a substring
  6748.           that matches the pattern. In other words, a floating pattern has
  6749.           an implied "*" at the beginning and end. You can anchor a
  6750.           floating pattern to the beginning by starting it with "^", and
  6751.           you can anchor it to the end by ending it with "$" (see examples
  6752.           below).
  6753.  
  6754.    Wildcards
  6755.           A wildcard is an anchored pattern that has the additional
  6756.           property that "*" does not match directory separators.
  6757.  
  6758.    This terminology lets us describe Kermit's commands with a bit more
  6759.    precision. When a pattern is used for matching filenames, it is a
  6760.    wildcard, except in the TEXT-PATTERNS and BINARY-PATTERNS lists and
  6761.    /EXCEPT: clauses, in which case directory separators are not
  6762.    significant (for example, a BINARY-PATTERN of "*.exe" matches any file
  6763.    whose name ends in .exe, no matter how deeply it might be buried in
  6764.    subdirectories). When Kermit parses a file specification directly,
  6765.    however, it uses the strict wildcard definition. For example, "send
  6766.    a*b" sends all files whose names start with "a" and end with "b" in the
  6767.    current directory, and not any files whose names end with "b" that
  6768.    happen to be in subdirectories whose names start with "a". And as
  6769.    noted, wildcards are anchored, so "delete foo" deletes the file named
  6770.    "foo", and not all files whose names happen to contain "foo".
  6771.  
  6772.    Most other patterns are anchored. For example:
  6773.  
  6774.   if match abc bc ...
  6775.  
  6776.    does not succeed (and you would be surprised if it did!). In fact, the
  6777.    only floating patterns are the ones used by commands or functions that
  6778.    search for patterns in files, arrays, or strings. These include:
  6779.  
  6780.      * The GREP and TYPE /MATCH commands.
  6781.      * The \fsearch(), \frsearch(), and \farraylook() functions.
  6782.  
  6783.    Thus these are the only contexts in which explicit anchors ("^" and
  6784.    "$") may be used:
  6785.  
  6786.    grep abc *.txt
  6787.           Prints all lines containing "abc" in all files whose names end
  6788.           with ".txt".
  6789.  
  6790.    grep ^abc *.txt
  6791.           Prints all lines that start with "abc" in all ".txt" files.
  6792.  
  6793.    grep abc$ *.txt
  6794.           Prints all lines that end with "abc" in all ".txt" files.
  6795.  
  6796.    grep ^a*z$ *.txt
  6797.           Prints all lines that start with "a" and end with "z" in all
  6798.           ".txt" files.
  6799.  
  6800.    Similarly for TYPE /PAGE, /fsearch(), /frsearch(), and \farraylook().
  6801.  
  6802.    Here is a brief summary of anchored and floating pattern equivalences:
  6803.  
  6804.   Anchored   Floating
  6805.     abc       ^abc$
  6806.     *abc      abc$
  6807.     abc*      ^abc
  6808.     *abc*     abc
  6809.  
  6810.    [ [475]Top ] [ [476]Contents ] [ [477]C-Kermit Home ] [ [478]Kermit
  6811.    Home ]
  6812.  
  6813. 8.13. Dates and Times
  6814.  
  6815.    C-Kermit's comprehension of date-time formats is considerably expanded
  6816.    in version 8.0. Any command that reads dates, including the DATE
  6817.    command itself, or any switch, such as the /BEFORE: and /AFTER:
  6818.    switches, or any function such as \fcvtdate(), now can understand dates
  6819.    and times expressed in any ISO 8601 format, in Unix "asctime" format,
  6820.    in FTP MDTM format, and in practically any format used in RFC 822 or
  6821.    RFC 2822 electronic mail, with or without timezones, and in a great
  6822.    many other formats as well. HELP DATE briefly summarizes the acceptable
  6823.    date-time formats.
  6824.  
  6825.    Furthermore, C-Kermit 8.0 includes a new and easy-to-use form of
  6826.    date-time arithmetic, in which any date or time can be combined with a
  6827.    "delta time", to add or subtract the desired time interval (years,
  6828.    months, weeks, days, hours, minutes, seconds) to/from the given date.
  6829.    And new functions are available to compare dates and to compute their
  6830.    differences.
  6831.  
  6832.    As you can imagine, all this requires quite a bit of "syntax". The
  6833.    basic format is:
  6834.  
  6835.   [ date ] [ time ] [ delta ]
  6836.  
  6837.    Each field is optional, but in most cases (depending on the context)
  6838.    there must be at least one field. If a date is given, it must come
  6839.    first. If no date is given, the current date is assumed. If no time is
  6840.    given, an appropriate time is supplied depending on whether a date was
  6841.    supplied. If no delta is given, no arithmetic is done. If a delta is
  6842.    given without a date or time, the current date and time are used as the
  6843.    base.
  6844.  
  6845.    Date-time-delta fields are likely to contain spaces (although they need
  6846.    not; space-free forms are always available). Therefore, in most
  6847.    contexts -- and notably as switch arguments -- date-time information
  6848.    must be enclosed in braces or doublequotes, for example:
  6849.  
  6850.   send /after:"8-Aug-2001 12:00 UTC" *.txt
  6851.  
  6852.    Kermit's standard internal format for dates and times is:
  6853.  
  6854.   yyyymmdd hh:mm:ss
  6855.  
  6856.    for example:
  6857.  
  6858.   20010208 10:28:01
  6859.  
  6860.    Date-times can always be given in this format. yyyy is the 4-digit
  6861.    year, mm is the two-digit month (1-12; supply leading zero for
  6862.    Jan-Sep), dd is the 2-digit day (leading zero for 1-9), hh is the hour
  6863.    (0-23), mm the minute (0-59), ss the second (0-59), each with leading
  6864.    zero if less than the field width. The date and time can be separated
  6865.    by a space, an underscore, a colon, or the letter T. The time is in
  6866.    24-hour format. Thus the various quantities are at the following fixed
  6867.    positions:
  6868.  
  6869. Position  Contents
  6870.    1-4    Year   (4 digits, 0000-9999)
  6871.    5-6    Month  (2 digits, 1-12)
  6872.    7-8    Day    (2 digits, 1-31)
  6873.    9      Date-Time Separator (space, :, _, or the letter T)
  6874.   10-11   Hour   (2 digits, 0-23)
  6875.   12      Hour-Minute Separator (colon)
  6876.   13-14   Minute (2 digits, 0-59)
  6877.   15      Minute-Second Separator (colon)
  6878.   16-17   Second (2 digits, 0-59)
  6879.  
  6880.    Example:
  6881.  
  6882.   19800526 13:07:12  26 May 1980, 13:07:12 (1:07:12PM)
  6883.  
  6884.    This is the format produced by the DATE command and by any function
  6885.    that returns a date-time. It is suitable for lexical comparison and
  6886.    sorting, and for use as a date-time in any Kermit command. When this
  6887.    format is given as input to a command or function, various date-time
  6888.    separators (as noted) are accepted:
  6889.  
  6890.   19800526 13:07:12  26 May 1980, 13:07:12 (1:07:12PM)
  6891.   20010208_10:28:35  2 February 2001, 10:28:35 AM
  6892.   18580101:12:00:00  1 January 1858, noon
  6893.   20110208T00:00:00  2 February 2011, midnight
  6894.  
  6895.    Certain other special date-time formats that are encountered on
  6896.    computer networks are recognized:
  6897.  
  6898.    Asctime Format
  6899.           This is a fixed format used by Unix, named after Unix's
  6900.           asctime() ("ASCII time") function. It is always exactly 24
  6901.           characters long. Example: Fri Aug 10 16:38:01 2001
  6902.  
  6903.    Asctime with Timezone
  6904.           This is like Asctime format, but includes a 3-character timezone
  6905.           between the time and year. It is exactly 28 characters long.
  6906.           Example: Fri Aug 10 16:38:01 GMT 2001
  6907.  
  6908.    E-Mail Format
  6909.           E-mail date-time formats are defined in [479]RFC 2822 with a
  6910.           fair amount of flexibility and options. The following examples
  6911.           are typical of e-mails and HTTP (web-page) headers:
  6912.  
  6913.   Sat, 14 Jul 2001 11:49:29                (No timezone)
  6914.   Fri, 24 Mar 2000 14:19:59 EST            (Symbolic timezone)
  6915.   Tue, 26 Jun 2001 10:19:45 -0400 (EDT)    (GMT Offset + comment)
  6916.  
  6917.    FTP MDTM Format
  6918.           This is the date-time format supplied by FTP servers that
  6919.           support the (not yet standard but widely used nevertheless) MDTM
  6920.           command, by which the FTP client asks for a file's modification
  6921.           time:
  6922.  
  6923.   yyyymmddhhmmss[.ffff]
  6924.  
  6925.           where yyyy is the 4-digit year, mm is the 2-digit month, and so
  6926.           on, exactly 14 digits long. An optional fractional part
  6927.           (fraction of second) may also be included, separated by a
  6928.           decimal point (period). Kermit rounds to the nearest second.
  6929.           Example:
  6930.  
  6931.   20020208102835.515                       (8 February 2002 10:28:36 AM)
  6932.  
  6933. 8.13.1. The Date
  6934.  
  6935.    The date, if given, must precede the time and/or delta, and can be in
  6936.    many, many formats. For starters, you can use several symbolic date
  6937.    names in place of actual dates:
  6938.  
  6939.    NOW
  6940.           This is replaced by the current date and time. The time can not
  6941.           be overridden (if you want to supply a specific time, use TODAY
  6942.           rather than NOW).
  6943.  
  6944.    TODAY
  6945.           This is replaced by the current date and a default time of
  6946.           00:00:00 is supplied, but can be overridden by a specific time;
  6947.           for example, if today is 8 February 2002, then "TODAY" is
  6948.           "20020802 00:00:00" but "TODAY 10:28" is "20020802 10:28:00".
  6949.  
  6950.    TOMORROW
  6951.           Like TODAY, but one day later (if today is 8 February 2002, then
  6952.           "TOMORROW" is "20020803 00:00:00" but "TOMORROW 16:30" is
  6953.           "20020803 16:30:00").
  6954.  
  6955.    YESTERDAY
  6956.           Like TODAY, but one day earlier.
  6957.  
  6958.    MONDAY, TUESDAY, WEDNESDAY, ..., SUNDAY
  6959.           The date on the given day of the week, today or later. A default
  6960.           time of 00:00:00 is supplied but can be overridden. Example:
  6961.           "SATURDAY 12:00" means next Saturday (or today, if today is
  6962.           Saturday) at noon.
  6963.  
  6964.    You can give an explicit date in almost any conceivable format, but
  6965.    there are some rules:
  6966.  
  6967.      * If a date is given, it must have three fields: day, month, and
  6968.        year; the order can vary (except that the month can not be last).
  6969.      * If names are used for days, months, etc, they must be English.
  6970.      * The year must lie between 0000 and 9999, inclusive.
  6971.      * All calendar calculations use Gregorian dating, so calculated dates
  6972.        for years prior to 1582 (or later, depending on the country) will
  6973.        not agree with historical dates. Other forms of dating (e.g.
  6974.        Hebrew, Chinese) are not supported.
  6975.  
  6976.    Various date-field separators are accepted: hyphen, slash, space,
  6977.    underscore, period. The same field separator (if any) must be used in
  6978.    both places; for example 18-Sep-2001 but not 18-Sep/2001. Months can be
  6979.    numeric (1-12) or English names or abbreviations. Month name
  6980.    abbreviations are normally three letters, e.g. Apr, May, Jun, Jul.
  6981.    Capitalization doesn't matter.
  6982.  
  6983.    Here are a few examples:
  6984.  
  6985.   18 Sep 2001                              (English month, abbreviated)
  6986.   18 September 2001                        (English month, spelled out)
  6987.   2001 Sept 18                             (Year, month, day)
  6988.   18-Sep-2001                              (With hyphens)
  6989.   18/09/2001                               (All numeric with slashes)
  6990.   18.09.2001                               (Ditto, with periods)
  6991.   18_09_2001                               (Ditto, with underscores)
  6992.   09/18/2001                               (See below)
  6993.   2001/09/18                               (See below)
  6994.   September 18, 2001                       (Correspondence style)
  6995.   Sep-18-2001                              (Month-day-year)
  6996.   20010918                                 (Numeric, no separators)
  6997.  
  6998.    You can also include the day of the week with a specific date, in which
  6999.    case it is accepted (if it is a valid day name), but not verified to
  7000.    agree with the given date:
  7001.  
  7002.   Tue, 18 Sep 2001                         (Abbreviated, with comma)
  7003.   Tue,18 Sep 2001                          (Comma but no space)
  7004.   Tue 18 Sep 2001                          (Abbreviated, no comma)
  7005.   Tuesday 18 Sep 2001                      (Spelled out)
  7006.   Tuesday, 18 Sep 2001                     (etc)
  7007.   Friday, 18 Sep 2001                      (Accepted even if not Friday)
  7008.  
  7009.    In all-numeric dates with the year last, such as 18/09/2001, Kermit
  7010.    identifies the year because it's 4 digits, then decides which of the
  7011.    other two numbers is the month or day based on its value. If both are
  7012.    12 or less and are unequal, the date is ambiguous and is rejected. In
  7013.    all-numeric dates with the year first, the second field is always the
  7014.    month and the third is the day. The month never comes last. A date with
  7015.    no separators is accepted only if it is all numeric and has exactly
  7016.    eight digits, and is assumed to be in yyyymmdd format.
  7017.  
  7018.   20010918                                 (18-Sep-2001 00:00:00)
  7019.  
  7020.    or 14 digits (as in FTP MDTM format):
  7021.  
  7022.   20010918123456                           (18-Sep-2001 12:34:56)
  7023.  
  7024.    You can always avoid ambiguity by putting the year first, or by using
  7025.    an English, rather than numeric, month. A date such as 09/08/2001 would
  7026.    be ambiguous but 2001/09/08 is not, nor is 09-Aug-2001.
  7027.  
  7028.    Until the late 1990s, it was common to encounter 2-digit years, and
  7029.    these are found to this day in old e-mails and other documents. Kermit
  7030.    accepts these dates if they have English months, and interprets them
  7031.    according to the windowing rules of [480]RFC 2822: "If a two digit year
  7032.    is encountered whose value is between 00 and 49, the year is
  7033.    interpreted by adding 2000, ending up with a value between 2000 and
  7034.    2049. If a two digit year is encountered with a value between 50 and
  7035.    99, or any three digit year is encountered, the year is interpreted by
  7036.    adding 1900."
  7037.  
  7038.    If you need to specify a year prior to 1000, use leading zeros to
  7039.    ensure it is not misinterpreted as a "non-Y2K-compliant" modern year:
  7040.  
  7041.   7-Oct-77                                 (19771007 00:00:00)
  7042.   7-Oct-0077                               (00771007 00:00:00)
  7043.  
  7044. 8.13.2. The Time
  7045.  
  7046.    The basic time format is hh:mm:dd; that is hours, minutes, seconds,
  7047.    separated by colons, perhaps with an optional fractional second
  7048.    separated by a decimal point (period). The hours are in 24-hour format;
  7049.    12 is noon, 13 is 1pm, and so on. Fields omitted from the right default
  7050.    to zero. Fields can be omitted from the left or middle by including the
  7051.    field's terminating colon. Examples:
  7052.  
  7053.   11:59:59                                 (11:59:59 AM)
  7054.   11:59                                    (11:59:00 AM)
  7055.   11                                       (11:00:00 AM)
  7056.   11:59:59.33                              (11:59:59 AM)
  7057.   11:59:59.66                              (Noon)
  7058.   03:21:00                                 (3:21:00 AM)
  7059.   3:21:00                                  (3:21:00 AM)
  7060.   15:21:00                                 (3:21:00 PM)
  7061.   :21:00                                   (00:21:00 AM)
  7062.   ::01                                     (00:00:01 AM)
  7063.   11::59                                   (11:00:59 AM)
  7064.  
  7065.    Leading zeros can be omitted, but it is customary and more readable to
  7066.    keep them in the minute and second fields:
  7067.  
  7068.   03:02:01                                 (03:02:01 AM)
  7069.   3:02:01                                  (03:02:01 AM)
  7070.   3:2:1                                    (03:02:01 AM)
  7071.  
  7072.    AM/PM notation is accepted if you wish to use it:
  7073.  
  7074.   11:59:59                                 (11:59:59 AM)
  7075.   11:59:59AM                               (11:59:59 AM)
  7076.   11:59:59A.M.                             (11:59:59 AM)
  7077.   11:59:59am                               (11:59:59 AM)
  7078.   11:59:59a.m.                             (11:59:59 AM)
  7079.   11:59:59PM                               (11:59:59 PM = 23:59:59)
  7080.   11:59:59P.M.                             (11:59:59 PM = 23:59:59)
  7081.   11:59:59pm                               (11:59:59 PM = 23:59:59)
  7082.   11:59:59p.m.                             (11:59:59 PM = 23:59:59)
  7083.  
  7084.    You can omit the colons if you wish, in which case Kermit uses the
  7085.    following rules to interpret the time:
  7086.  
  7087.     1. 6 digits is hh:mm:ss, e.g. 123456 is 12:34:56.
  7088.     2. 5 digits is h:mm:ss, e.g. 12345 is 1:23:45.
  7089.     3. 4 digits is hh:mm, e.g. 1234 is 12:34.
  7090.     4. 3 digits is h:mm, e.g. 123 is 1:23.
  7091.     5. 2 digits is hh, e.g. 12 is 12:00.
  7092.     6. 1 digit is h (the hour), e.g. 1 is 1:00.
  7093.  
  7094.    Examples:
  7095.  
  7096.   1                                        (01:00:00 AM)
  7097.   10                                       (10:00:00 AM)
  7098.   230                                      (02:30:00 AM)
  7099.   230pm                                    (02:30:00 PM = 14:30:00)
  7100.   1115                                     (11:15:00 AM)
  7101.   2315                                     (11:15:00 PM = 23:15:00 PM)
  7102.   23150                                    (02:31:50 AM)
  7103.   231500                                   (23:15:00 PM)
  7104.  
  7105. 8.13.3. Time Zones
  7106.  
  7107.    If a time is given, it can (but need not) be followed by a time zone
  7108.    designator. If no time zone is included, the time is treated as local
  7109.    time and no timezone conversions are performed.
  7110.  
  7111.    The preferred time zone designator is the UTC Offset, as specified in
  7112.    [481]RFC 2822: a plus sign or minus sign immediately followed by
  7113.    exactly four decimal digits, signifying the difference in hh (hours)
  7114.    and mm (minutes) from Universal Coordinated Time (UTC, also known as
  7115.    Greenwich Mean Time, or GMT), with negative numbers to the West and
  7116.    positive numbers to the East. For example:
  7117.  
  7118.   Fri, 13 Jul 2001 12:54:29 -0700
  7119.  
  7120.    indicates a local time of 12:54:29 that is 07 hours and 00 minutes
  7121.    behind (less than, East of) Universal Time. The space is optional, so
  7122.    the example could also be written as:
  7123.  
  7124.   Fri, 13 Jul 2001 12:54:29-0700
  7125.  
  7126.    The following symbolic time zones are also accepted, as specified by
  7127.    [482]RFC 2822 and/or in ISO 8601:
  7128.  
  7129.   GMT  =  +0000       Greenwich Mean Time
  7130.   Z    =  +0000       Zulu (Zero Meridian) Time
  7131.   UTC  =  +0000       Universal Coordinated Time
  7132.   UT   =  +0000       Universal Time
  7133.   EDT  =  -0400       Eastern (USA) Daylight Time
  7134.   EST  =  -0500       Eastern (USA) Standard Time
  7135.   CDT  =  -0500       Central (USA) Daylight Time
  7136.   CST  =  -0600       Central (USA) Standard Time
  7137.   MDT  =  -0600       Mountain (USA) Daylight Time
  7138.   MST  =  -0700       Mountain (USA) Standard Time
  7139.   PDT  =  -0700       Pacific (USA) Daylight Time
  7140.   PST  =  -0800       Pacific (USA) Standard Time
  7141.  
  7142.    Note that GMT, Z, UTC, and UT all express the same concept: standard
  7143.    (not daylight) time at the Zero Meridian. UTC, by the way, is an
  7144.    international standard symbol and does not correspond to the order of
  7145.    the English words, Universal Coordinated Time, but it happens to have
  7146.    the same initial letters as these words. Of course hundreds of other
  7147.    symbolic timezones and variations exist, but they are not standardized,
  7148.    and are therefore not supported by Kermit.
  7149.  
  7150.    When a time zone is included with a time, the time is converted to
  7151.    local time. In case the conversion crosses a midnight boundary, the
  7152.    date is adjusted accordingly. Examples converting to EST (Eastern USA
  7153.    Standard Time = -0500):
  7154.  
  7155.  11:30:00      =  11:30:00
  7156.  11:30:00 EST  =  11:30:00
  7157.  11:30:00 GMT  =  06:30:00
  7158.  11:30:00 PST  =  14:30:00
  7159.  11:30:00Z     =  06:30:00
  7160.  11:30PM GMT   =  18:30:00
  7161.  11:30 -0500   =  11:30:00
  7162.  11:30 -0800   =  08:30:00
  7163.  11:30 +0200   =  04:30:00
  7164.  
  7165.    Unlike most of Kermit's other date-time conversions, timezone knowledge
  7166.    (specifically, the offset of local time from UTC) is embodied in the
  7167.    underlying operating system, not in Kermit itself, and any conversion
  7168.    errors in this department are the fault of the OS. For example, most
  7169.    UNIX platforms do not perform conversions for years prior to 1970.
  7170.  
  7171. 8.13.4. Delta Time
  7172.  
  7173.    Date/time expressions can be composed of a date and/or time and a delta
  7174.    time, or a delta time by itself. When a delta time is given by itself,
  7175.    it is relative to the current local date and time. Delta times have the
  7176.    following general format:
  7177.  
  7178.   {+,-}[number units][hh[:mm[:ss]]]
  7179.  
  7180.    In other words, a delta time always starts with a plus or minus sign,
  7181.    which is followed by a "part1", a "part2", or both. The "part1", if
  7182.    given, specifies a number of days, weeks, months, or years; "part2"
  7183.    specifies a time in hh:mm:ss notation. In arithmetic terms, these
  7184.    represents some number of days or other big time units, and then a
  7185.    fraction of a day expressed as hours, minutes, and seconds; these are
  7186.    to be added to or subtracted from the given (or implied) date and time.
  7187.    The syntax is somewhat flexible, as shown by the following examples:
  7188.  
  7189.   +1 day                (Plus one day)
  7190.   +1day                 (Ditto)
  7191.   +1d                   (Ditto)
  7192.   + 1 day               (Ditto)
  7193.   + 1 day 3:00          (Plus one day and 3 hours)
  7194.   +1d3:00               (Ditto)
  7195.   +1d3                  (Ditto)
  7196.   +3:00:00              (Plus 3 hours)
  7197.   +3:00                 (Ditto)
  7198.   +3                    (Ditto)
  7199.   +2 days               (Plus 2 days)
  7200.   -12 days 7:14:22      (Minus 12 days, 7 hours, 14 minutes, and 22 seconds)
  7201.  
  7202.    The words "week", "month", and "year" can be used like "day" in the
  7203.    examples above. A week is exactly equivalent to 7 days. When months are
  7204.    specified, the numeric month number of the date is incremented or
  7205.    decremented by the given number, and the year and day adjusted
  7206.    accordingly if necessary (for example, 31-Jan-2001 +1month =
  7207.    03-Mar-2001 because February does not have 31 days). When years are
  7208.    specified, they are added or subtracted to the base year. Examples
  7209.    (assuming the current date is 10-Aug-2001 and the current time is
  7210.    19:21:11):
  7211.  
  7212.   18-Sep-2001 +1day              (20010918 00:00:00)
  7213.   today +1day                    (20010811 00:00:00)
  7214.   now+1d                         (20010811 19:21:11)
  7215.   + 1 day                        (20010811 19:21:11)
  7216.   + 1 day 3:14:42                (20010811 22:35:54)
  7217.   + 7 weeks                      (20010928 19:21:11)
  7218.   +1d3:14:42                     (20010811 22:35:54)
  7219.   +1w3:14:42                     (20010817 22:35:54)
  7220.   +1m3:14:42                     (20010910 22:35:54)
  7221.   +1y3:14:42                     (20020810 22:35:54)
  7222.   2 feb 2001 + 10 years          (20110208 00:00:00)
  7223.   2001-02-08 +10y12              (20110208 12:00:00)
  7224.   31-dec-1999 23:59:59+00:00:01  (20000101 00:00:00)
  7225.   28-feb-1996 +1day              (19960229 00:00:00) (leap year)
  7226.   28-feb-1997 +1day              (19970301 00:00:00) (nonleap year)
  7227.   28-feb-1997 +1month            (19970328 00:00:00)
  7228.   28-feb-1997 +1month 11:59:59   (19970328 11:59:59)
  7229.   28-feb-1997 +20years           (20170228 00:00:00)
  7230.   28-feb-1997 +8000years         (99970228 00:00:00)
  7231.  
  7232.    For compatibility with VMS, the following special delta-time format is
  7233.    also accepted:
  7234.  
  7235.   +number-hh:mm:ss
  7236.   -number-hh:mm:ss
  7237.  
  7238.    (no spaces). The hyphen after the number indicates days. It corresponds
  7239.    exactly to the Kermit notation:
  7240.  
  7241.   +numberdhh:mm:ss
  7242.   -numberdhh:mm:ss
  7243.  
  7244.    The following forms all indicate exactly the same date and time:
  7245.  
  7246.   18-Sep-2001 12:34:56 +1-3:23:01
  7247.   18-Sep-2001 12:34:56 +1d3:23:01
  7248.   18-Sep-2001 12:34:56 +1 day 3:23:01
  7249.  
  7250.    and mean "add a day plus 3 hours, 23 minutes, and 1 second" to the
  7251.    given date.
  7252.  
  7253.    Note that delta times are not at all the same as UTC offsets; the
  7254.    former specifies an adjustment to the given date/time and the latter
  7255.    specifies that the local time is a particular distance from Universal
  7256.    Time, for example:
  7257.  
  7258.   11-Aug-2001 12:34:56 -0800          (20010811 16:34:56 -- UTC Offset)
  7259.   11-Aug-2001 12:34:56 -08:00         (20010811 04:34:56 -- Delta time)
  7260.  
  7261.    If you give a time followed by a modifier that starts with a + or -
  7262.    sign, how does Kermit know whether it's a UTC offset or a delta time?
  7263.    It is treated as a UTC offset if the sign is followed by exactly four
  7264.    decimal digits; otherwise it is a delta time. Examples (for USA Eastern
  7265.    Daylight Time):
  7266.  
  7267.   11-Aug-2001 12:34:56 -0800          (20010811 16:34:56 -- UTC Offset)
  7268.   11-Aug-2001 12:34:56 -08:00         (20010811 04:34:56 -- Delta time)
  7269.   11-Aug-2001 12:34:56 -800           (20010811 04:34:56 -- Delta time)
  7270.   11-Aug-2001 12:34:56 -8             (20010811 04:34:56 -- Delta time)
  7271.  
  7272.    The first example says that at some unknown place which is 8 hours
  7273.    ahead of Universal Time, the time is 12:34:56, and this corresponds to
  7274.    16:34:56 in Eastern Daylight time. The second example says to subtract
  7275.    8 hours from the local time. The third and fourth are delta times
  7276.    because, even though a colon is not included, the time does not consist
  7277.    of exactly 4 digits.
  7278.  
  7279.    When a delta time is written after a timezone, however, there is no
  7280.    ambiguity and no syntax distinction is required:
  7281.  
  7282.   11-Aug-2001 12:34:56 -0800 -0800    (20010811 08:34:56)
  7283.   11-Aug-2001 12:34:56 -0800 -08:00   (Ditto)
  7284.   11-Aug-2001 12:34:56 -08:00 -08:00  (Illegal)
  7285.  
  7286. 8.13.5. The DATE Command
  7287.  
  7288.    Obviously a great many combinations of date, time, time zone, and delta
  7289.    time are possible, as well as many formatting options. The purpose of
  7290.    all this flexibility is to comply with as many standards as possible --
  7291.    Internet RFCs, ISO standards, and proven corporate standards -- as well
  7292.    as with notations commonly used by real people, in order that dates and
  7293.    times from the widest variety of sources can be assigned to a variable
  7294.    and used in any date-time field in any Kermit command.
  7295.  
  7296.    You can test any date-and/or-time format with the DATE command, which
  7297.    converts it to standard yyyymmdd hh:mm:ss format if it is understood,
  7298.    or else gives an explicit error message (rather than just "BAD DATE" as
  7299.    in previous C-Kermit releases) to indicate what is wrong with it.
  7300.    Examples (on Tuesday, 31 July 2001 in New York City, Eastern Daylight
  7301.    Time, UTC -0400):
  7302.  
  7303.   DATE command argument                   Result
  7304.   12:30                                   20010731 12:30:00
  7305.   12:30:01                                20010731 12:30:01
  7306.   12:30:01.5                              20010731 12:30:02
  7307.   1230                                    20010731 12:30:00
  7308.   230                                     20010731 02:30:00
  7309.   230+1d                                  20010801 02:30:00
  7310.   230+1d3:00                              20010801 05:30:00
  7311.   20010718 19:21:15                       20010718 19:21:15
  7312.   20010718_192115                         20010718 19:21:15
  7313.   20010718T192115                         20010718 19:21:15
  7314.   18 Jul 2001 +0400                       20010717 23:59:59
  7315.   18 Jul 2001 192115                      20010718 19:21:15
  7316.   18 Jul 2001 192115.8                    20010718 19:21:16
  7317.   18-Jul-2001T1921                        20010718 19:21:00
  7318.   18-Jul-2001 1921Z                       20010718 15:21:00
  7319.   18-Jul-2001 1921 GMT                    20010718 15:21:00
  7320.   18-Jul-2001 1921 UTC                    20010718 15:21:00
  7321.   18-Jul-2001 1921 Z                      20010718 15:21:00
  7322.   18-Jul-2001 1921Z                       20010718 15:21:00
  7323.   18-Jul-2001 1921 -04:00:00              20010718 19:21:00
  7324.   21-Jul-2001_08:20:00am                  20010721 08:20:00
  7325.   21-Jul-2001_8:20:00P.M.                 20010721 20:20:00
  7326.   Fri Jul 20 11:26:25 2001                20010720 11:26:25
  7327.   Fri Jul 20 11:26:25 GMT 2001            20010720 07:26:25
  7328.   Sun, 9 Apr 2000 06:46:46 +0100          20000409 01:46:46
  7329.   Sunday, 9 Apr 2000 06:46:46 +0100       20000409 01:46:46
  7330.   now                                     20010731 19:41:12
  7331.   today                                   20010731 00:00:00
  7332.   today 09:00                             20010731 09:00:00
  7333.   tomorrow                                20010801 00:00:00
  7334.   tomorrow 09:00                          20010801 09:00:00
  7335.   tomorrow 09:00 GMT                      20010801 05:00:00
  7336.   yesterday                               20010730 00:00:00
  7337.   yesterday 09:00                         20010730 09:00:00
  7338.   + 3 days                                20010803 00:00:00
  7339.   +3 days                                 20010803 00:00:00
  7340.   +3days                                  20010803 00:00:00
  7341.   + 3days                                 20010803 00:00:00
  7342.   + 3 days 09:00                          20010803 09:00:00
  7343.   + 2 weeks                               20010814 00:00:00
  7344.   + 1 month                               20010831 00:00:00
  7345.   - 7 months                              20001231 00:00:00
  7346.   + 10 years                              20110731 00:00:00
  7347.   friday                                  20010803 00:00:00
  7348.   saturday                                20010804 00:00:00
  7349.   sunday                                  20010805 00:00:00
  7350.   monday                                  20010806 00:00:00
  7351.   tuesday                                 20010731 00:00:00
  7352.   wednesday                               20010801 00:00:00
  7353.   thursday                                20010802 00:00:00
  7354.   friday 07:00                            20010803 07:00:00
  7355.   thursday 1:00pm                         20010802 13:00:00
  7356.   thursday 1:00pm GMT                     20010802 09:00:00
  7357.   Thu, 10 Nov 94 10:50:47 EST             19941110 10:50:47
  7358.   Fri, 20 Oct 1995 18:35:15 -0400 (EDT)   19951020 18:35:15
  7359.   31/12/2001                              20011231 00:00:00
  7360.   12/31/2001                              20011231 00:00:00
  7361.   2001-July-20                            20010720 00:00:00
  7362.   2001-September-30                       20010930 00:00:00
  7363.   30-September-2001                       20010930 00:00:00
  7364.   Sep 30, 2001 12:34:56                   20010930 12:34:56
  7365.   September 30, 2001                      20010930 00:00:00
  7366.   September 30, 2001 630                  20010930 06:30:00
  7367.   September 30 2001 630                   20010930 06:30:00
  7368.   Sep-30-2001 12:34:59                    20010930 12:34:59
  7369.   20010807113542.014                      20010807 11:35.42
  7370.   20010807113542.014Z                     20010807 07:35:42
  7371.  
  7372. 8.13.6. New Date-Time Functions
  7373.  
  7374.    In the following descriptions, date-time function arguments are the
  7375.    same free-format date-time strings discussed above, with the same
  7376.    defaults for missing fields. They are automatically converted to
  7377.    standard format internally prior to processing.
  7378.  
  7379.    \fcvtdate(d1)
  7380.           Converts the date-time d1 to standard format and local time.
  7381.           This function is not new, but now it accepts a wider range of
  7382.           argument formats that can include timezones and/or delta times.
  7383.           If the first argument is omitted, the current date and time are
  7384.           assumed. The optional second argument is a format code for the
  7385.           result:
  7386.  
  7387.      n1 = 1: yyyy-mmm-dd hh:mm:ss (mmm = English 3-letter month
  7388.      abbreviation)
  7389.      n1 = 2: dd-mmm-yyyy hh:mm:ss (ditto)
  7390.      n1 = 3: yyyymmddhhmmss (all numeric)
  7391.  
  7392.    \futcdate(d1)
  7393.           Converts the date-time d1 to Universal Coordinated Time (UTC),
  7394.           also known as GMT or Zulu or Zero-Meridian time. The default d1
  7395.           is NOW. If d1 is a valid date-time, the UTC result is returned
  7396.           in standard format, yyyymmdd hh:ss:mm.
  7397.  
  7398.    \fcmpdates(d1,d2)
  7399.           Compares two free-format date-times, d1 and d2, and, if both
  7400.           arguments are valid, returns a number: -1 if d1 is earlier than
  7401.           (before) d2; 0 if d1 is the same as d2; 1 if d1 is later than
  7402.           (after) d2.
  7403.  
  7404.    \fdiffdates(d1,d2)
  7405.           Computes the difference between two free-format date-times, d1
  7406.           and d2. If both arguments are valid, returns a delta time which
  7407.           is negative if d1 is earlier than (before) d2 and positive
  7408.           otherwise. If d1 and d2 are equal, the result is "+0:00".
  7409.           Otherwise, the result consists of the number of days, hours,
  7410.           minutes, and seconds that separate the two date-times. If the
  7411.           number of days is zero, it is omitted. If the number of days is
  7412.           nonzero but the hours, minutes, and seconds are all zero, the
  7413.           time is omitted. if the seconds are zero, they are omitted.
  7414.  
  7415.    \fdelta2secs(dt)
  7416.           Converts a delta time to seconds. For example, "+1d00:00:01" to
  7417.           86401. Valid delta times must start with a + or - sign. Days are
  7418.           accepted as time units, but not years, months, or weeks. If the
  7419.           result would overflow a computer long word (as would happen with
  7420.           32-bit long words when the number of days is greater than
  7421.           24854), the function fails.
  7422.  
  7423.    HINT: Although Kermit has a number of built-in date and time variables,
  7424.    it doesn't have a single one suitable for writing a timestamp. For this
  7425.    you would normally use something like "\v(ndate) \v(time)". But
  7426.    \fcvtdate() (with no arguments) is equivalent: it returns the current
  7427.    date and time in yyyymmdd hh:mm:ss format, suitable for time stamping.
  7428.  
  7429. 8.13.7. Date-Time Programming Examples
  7430.  
  7431.    Here's a macro that converts any date-time to UTC, which you might use
  7432.    if C-Kermit didn't already have a \futcdate() function:
  7433.  
  7434.   define utcdate {
  7435.       .local := \fcvtdate(\%*)                 ; 1.
  7436.       .tmp := \fcvtdate(\m(local)UTC)          ; 2.
  7437.       .offset := \fdiffdate(\m(local),\m(tmp)) ; 3.
  7438.       .utc := \fcvtdate(\m(local)\m(offset))   ; 4.
  7439.       sho mac utc                              ; 5.
  7440.   }
  7441.  
  7442.    Brief explanation: Line 1 converts the macro argument, a free-format
  7443.    date-time, to standard-format local time. Line 2 appends the "UTC"
  7444.    timezone to the local time and converts the result to local time. In
  7445.    other words, we take the same time as the local time, but pretend it's
  7446.    UTC time, and convert it to local time. For example, if New York time
  7447.    is 4 hours ahead of UTC, then 6:00pm New York time is 2:00pm UTC. Line
  7448.    3 gets the difference of the two results (e.g. "+04:00"). Line 4
  7449.    appends the difference (delta time) to the local time, and converts it
  7450.    again, which adds (or subtracts) the UTC offset to the given time. Line
  7451.    5 displays the result.
  7452.  
  7453.    Here's a script that opens a web page, gets its headers into an array,
  7454.    scans the array for the "Last-Modified:" header, and interprets it:
  7455.   http open www.columbia.edu
  7456.   if fail stop 1 HTTP OPEN failed
  7457.   http /array:a head index.html /dev/null
  7458.   if fail stop 1 HTTP GET failed
  7459.   show array a
  7460.   for \%i 1 \fdim(&a) 1 {
  7461.       .\%x := \findex(:,\&a[\%i])
  7462.       if not \%x continue
  7463.       .tag := \fleft(\&a[\%i],\%x-1)
  7464.       .val := \fltrim(\fsubstr(\&a[\%i],\%x+1))
  7465.       if ( eq "\m(tag)" "Last-Modified" ) {
  7466.           echo HTTP Date: \m(val)
  7467.           .rdate := \fcvtdate(\m(val))
  7468.           echo {Standard Date (local): \m(rdate)}
  7469.           echo {Standard Date (UTC):   \futcdate(\m(rdate))}
  7470.           break
  7471.       }
  7472.   }
  7473.   http close
  7474.  
  7475.    The result:
  7476.  
  7477.   HTTP Date: Mon, 13 Aug 2001 20:05:42 GMT
  7478.   Standard Date (local): 20010813 16:05:42
  7479.   Standard Date (UTC):   20010813 20:05:42
  7480.  
  7481.    As you can see, Kermit had no trouble decoding the date-time-string
  7482.    from the website, converting to local time, and converting back to UTC
  7483.    with no conflicts or loss of information. If it had been in any other
  7484.    known format, the result would have been the same.
  7485.  
  7486.    Now suppose we want to download the web page only if it is newer than
  7487.    our local copy. The \fdate(filename) function (which returns the
  7488.    modification date-time of the given file) and the new \fcmpdates()
  7489.    function make it easy. Insert the following just before the BREAK
  7490.    statement:
  7491.  
  7492.   if ( < 0 \fcmpdates(\m(rdate),\fdate(index.html)) ) {
  7493.      echo GETTING index.html...
  7494.      http get index.html index.html
  7495.      if success echo HTTP GET OK
  7496.   } else {
  7497.      echo index.html: no update needed
  7498.   }
  7499.   http close
  7500.   exit
  7501.  
  7502.    This says, "if 0 is less than the comparison of the remote file date
  7503.    and the local file date, get the remote file, otherwise skip it." And
  7504.    it automatically reconciles the time-zone difference (if any).
  7505.  
  7506.    It would be nice to be able to extend this script into a
  7507.    general-purpose website updater, but unfortunately HTTP protocol
  7508.    doesn't provide any mechanism for the client to ask the server for a
  7509.    list of files, recursive or otherwise.
  7510.  
  7511.    [ [483]Top ] [ [484]Contents ] [ [485]C-Kermit Home ] [ [486]Kermit
  7512.    Home ]
  7513.  
  7514. 8.14. Trapping Keyboard Interruption
  7515.  
  7516.    Normally when you type Ctrl-C and Kermit is in command mode (as opposed
  7517.    to CONNECT mode) with COMMAND INTERRUPTION ON (as it is unless you have
  7518.    set it OFF), Kermit interrupts any command that is currently in
  7519.    progress, and if a command file or macro is executing, rolls the
  7520.    command stack back to top level, closing all open command files,
  7521.    deactivating all macros, deallocating all local variables and arrays,
  7522.    and leaving you at the command prompt.
  7523.  
  7524.    Suppose, however, you want certain actions to occur when a script is
  7525.    interrupted; for example, closing open files, writing log entries, or
  7526.    displaying summary results. You can do this by defining a macro named
  7527.    ON_CTRLC. When Ctrl-C is detected, and a macro with this name is
  7528.    defined, Kermit executes it from the current command level, thus giving
  7529.    it full access to the environment in which the interruption occurred,
  7530.    including local variables and open files. Only when the ON_CTRLC macro
  7531.    completes execution is the command stack rolled back to top level.
  7532.  
  7533.    Once the ON_CTRLC macro is defined, it can be executed only once. This
  7534.    is to prevent recursion if the user types Ctrl-C while the ON_CTRLC
  7535.    macro is executing. If you type Ctrl-C while the Ctrl-C macro is
  7536.    active, this does not start a new copy of ON_CTRLC; rather, it returns
  7537.    to the top-level command prompt. After the ON_CTRLC macro returns, it
  7538.    has been removed from the macro table so if you want to use it again or
  7539.    install a different Ctrl-C trap, you must execute a new DEFINE ON_CTRLC
  7540.    command. In any case, as always when you interrupt a script with
  7541.    Ctrl-C, its completion status is FAILURE.
  7542.  
  7543.    Normally the ON_CTRLC macro would be defined in the command file or
  7544.    macro to which it applies, and should be declared LOCAL. This way, if
  7545.    the command file or macro completes successfully without being
  7546.    interrupted, the ON_CTRLC definition disappears automatically.
  7547.    Otherwise the definition would still be valid and the macro would be
  7548.    executed, probably out of context, the next time you typed Ctrl-C.
  7549.  
  7550.    Here's a simple example of a command file that sets a Ctrl-C trap for
  7551.    itself:
  7552.  
  7553.   local on_ctrlc              ; Make Ctrl-C trap local to this command file.
  7554.   define on_ctrlc {           ; Define the ON_CTRLC macro.
  7555.       echo Interrupted at \v(time).
  7556.       echo Iterations: \%n
  7557.   }
  7558.   xecho Type Ctrl-C to quit
  7559.   for \%n 1 999 1 {           ; Prints a dot every second until interrupted.
  7560.       sleep 1
  7561.       xecho .
  7562.   }
  7563.   echo Finished normally at \v(time) ; Get here only if not interrupted.
  7564.   decrement \%n
  7565.   echo Iterations: \%n
  7566.  
  7567.    This prints a summary no matter whether it completes normally or is
  7568.    interrupted from the keyboard. In both cases the trap is automatically
  7569.    removed afterwards.
  7570.  
  7571.    For an example of how to use ON_CTRLC to debug scripts, see
  7572.    [487]Section 8.1.
  7573.  
  7574.    [ [488]Top ] [ [489]Contents ] [ [490]C-Kermit Home ] [ [491]Kermit
  7575.    Home ]
  7576.  
  7577. 9. S-EXPRESSIONS
  7578.  
  7579.    This section is primarily for those who want to write
  7580.    calculation-intensive scripts, especially if they require
  7581.    floating-point arithmetic, and/or for those who are familiar with the
  7582.    LISP programming language.
  7583.  
  7584.    Ever since C-Kermit version 5 was released in 1988, scripting has been
  7585.    one of its major attractions, and arithmetic is a key part of it.
  7586.    Versions 5 and 6 included integer arithmetic only, using traditional
  7587.    algebraic notation, e.g.:
  7588.  
  7589.   echo \fevaluate(3*(2+7)/2)
  7590.   13
  7591.  
  7592.    C-Kermit 7.0 added support for floating-point arithmetic, but only
  7593.    through function calls:
  7594.  
  7595.   echo \ffpdivide(\ffpmultiply(3.0,\ffpadd(2.0,7.0)),2.0)
  7596.   13.5
  7597.  
  7598.    C-Kermit 8.0 introduces a third form of arithmetic that treats integers
  7599.    and floating-point numbers uniformly, is easier to read and write, and
  7600.    executes very quickly:
  7601.  
  7602.   (/ (* 3 (+ 2 7)) 2)
  7603.   13.5
  7604.  
  7605.    But first some background.
  7606.  
  7607.    The Kermit command and scripting language differs from true programming
  7608.    languages (such as C or Fortran) in many ways; one of the most
  7609.    prominent differences is the way in which variables are distinguished
  7610.    from constants. In a command language, words are taken literally; for
  7611.    example, the Unix shell:
  7612.  
  7613.   cat foo.bar
  7614.  
  7615.    displays the file named foo.bar. Whereas in a programming language like
  7616.    C, words are assumed to be variables:
  7617.  
  7618.   s = foo.bar;    /* Assigns the value of foo.bar to the variable s */
  7619.  
  7620.    To make a programming language take words literally, you have to quote
  7621.    or "escape" them:
  7622.  
  7623.   s = "foo.bar";  /* Assigns a pointer to the string "foo.bar" to the variable s
  7624.  */
  7625.  
  7626.    The opposite holds for command languages: to get them to treat a word
  7627.    as a variable rather than a constant, you have to escape them. For
  7628.    example, in the Unix shell:
  7629.  
  7630.   foo=123         ; Assign value 123 to variable foo.
  7631.   echo foo        ; Prints "foo"
  7632.   echo $foo       ; Prints "123"
  7633.  
  7634.    And in Kermit:
  7635.  
  7636.   define foo 123  ; Assign value 123 to variable foo.
  7637.   echo 123        ; This prints "123".
  7638.   echo foo        ; This prints "foo".
  7639.   echo \m(foo)    ; This prints "123".
  7640.  
  7641.    In other words, character strings (such as "foo" above) are interpreted
  7642.    as literal strings, rather than variable names, except in special
  7643.    commands like DEFINE that deal specifically with variable names (or in
  7644.    numeric contexts as explained in [492]Section 8.2). The special
  7645.    "escape" character (dollar sign ($) for the shell, backslash (\) for
  7646.    Kermit) indicates that a variable is to be replaced by its value.
  7647.  
  7648.    The requirement to escape variable names in command languages normally
  7649.    does not impose any special hardship, but can add a considerable
  7650.    notational burden to arithmetic expressions, which are typically full
  7651.    of variables. Especially in Kermit when floating point numbers are
  7652.    involved, where you must use special \ffpxxx() functions, e.g.
  7653.    "\ffpadd(\m(a),\m(b))" rather than the simple "+" operator to add two
  7654.    floating-point numbers together, because the original arithmetic
  7655.    handler doesn't support floating point (this might change in the
  7656.    future). To illustrate, the general formula for the area of a triangle
  7657.    is:
  7658.  
  7659.   sqrt(s * (s - a) * (s - b) * (s - c))
  7660.  
  7661.    where a, b, and c are the lengths of the triangle's three sides and:
  7662.  
  7663.   s = (a + b + c) / 2
  7664.  
  7665.    Except in special cases (e.g. a = 3, b = 4, c = 5), the result has a
  7666.    fractional part so the computation must be done using floating-point
  7667.    arithmetic. We can create a Kermit 7.0 function for this as follows:
  7668.  
  7669.   def area {
  7670.       local s t1 t2 t3
  7671.       assign s \ffpdiv(\ffpadd(\ffpadd(\%1,\%2),\%3),2.0)
  7672.       assign t1 \ffpsub(\m(s),\%1)
  7673.       assign t2 \ffpsub(\m(s),\%2)
  7674.       assign t3 \ffpsub(\m(s),\%3)
  7675.       return \ffpsqrt(\ffpmul(\m(s),\ffpmul(\m(t1),\ffpmul(\m(t2),\m(t3)))))
  7676.   }
  7677.  
  7678.    But as you can see, this is rather cumbersome. Note, in particular,
  7679.    that arithmetic functions like \ffpadd(), \ffpmul(), etc, take exactly
  7680.    two operands (like their symbolic counterparts + and *), so obtaining
  7681.    the product of three or more numbers (as we do in this case) is
  7682.    awkward.
  7683.  
  7684.    Using the alternative S-Expression notation, we can reduce this to a
  7685.    form that is both easier to read and executes faster (the details are
  7686.    explained later):
  7687.  
  7688.   def newarea {
  7689.       (let s (/ (+ \%1 \%2 \%3) 2.0))
  7690.       (sqrt (* s (- s \%1) (- s \%2) (- s \%3)))
  7691.   }
  7692.  
  7693.    In both examples, the \%1..3 variables are the normal Kermit macro
  7694.    arguments, referenced by the normal escaping mechanism. For increased
  7695.    readability, we can also assign the macro arguments \%1, \%2, and \%3
  7696.    to the letters a, b, and c corresponding to our formula:
  7697.  
  7698. def newarea {
  7699.     (let a \%1 b \%2 c \%3)
  7700.     (let s (/ (+ a b c) 2.0))
  7701.     (sqrt (* s (- s a) (- s b) (- s c)))
  7702. }
  7703.  
  7704.    And now the Kermit function reads almost like the original formula.
  7705.    Here Kermit behaves more like a regular programming language. In an
  7706.    S-Expression, macro names need not be escaped when they are used as the
  7707.    names of numeric variables.
  7708.  
  7709.    [ [493]Top ] [ [494]Contents ] [ [495]C-Kermit Home ] [ [496]Kermit
  7710.    Home ]
  7711.  
  7712. 9.1. What is an S-Expression?
  7713.  
  7714.    The S-Expression concept is borrowed from the Lisp programming
  7715.    language. "S-Expression" is short for Symbolic Expression (itself
  7716.    sometimes shortened to SEXP). S-Expressions provide a kind of
  7717.    Alternative Mini-Universe within the Kermit command language when the
  7718.    regular rules don't apply, a universe enclosed in parentheses.
  7719.  
  7720.    C-Kermit does not pretend to be a full Lisp interpreter; only the
  7721.    arithmetic parts of Lisp have been incorporated: S-Expressions that
  7722.    operate on numbers and return numeric values (plus extensibility
  7723.    features described in [497]Section 9.8, which allow some degree of
  7724.    string processing).
  7725.  
  7726.    An S-Expression is a list of zero or more items, separated by spaces,
  7727.    within parentheses. Examples:
  7728.  
  7729.   ()
  7730.   (1)
  7731.   (a)
  7732.   (+ a 1)
  7733.   (* 2 a b)
  7734.  
  7735.    If the S-Expression is empty, it has the NIL (empty) value. If it is
  7736.    not empty and the first item is an operator (such as + or *), there can
  7737.    be zero or more subsequent items, called the operands:
  7738.  
  7739.   (+ 1 2)
  7740.  
  7741.    Here the operator is "+" and the operands are "1" and "2", and the
  7742.    value of the S-Expression is the value of the operation (in this case
  7743.    3). The operator always comes first, which is different from the
  7744.    familiar algebraic notation; this because S-Expression operators can
  7745.    have different numbers of operands:
  7746.  
  7747.   (+ 1)
  7748.   (+ 1 2)
  7749.   (+ 1 2 3 4 5 6 7 8 9)
  7750.  
  7751.    If the first item in the S-Expression is not an operator, then it must
  7752.    be a variable or a number (or a macro; see [498]Section 9.8), and the
  7753.    S-Expression can only contain one item; in this case, the
  7754.    S-Expression's value is the value of the variable or number:
  7755.  
  7756.   (a)
  7757.   (3)
  7758.  
  7759.    Operands can be numbers, variables that have numeric values, functions
  7760.    that return numbers, or other S-Expressions. To illustrate an
  7761.    S-Expression within an S-Expression, observe that:
  7762.  
  7763.   (+ 1 2)
  7764.  
  7765.    is equivalent to any of the following (plus an infinite number of
  7766.    others):
  7767.  
  7768.   (+ 1 (+ 1 1))
  7769.   (+ (- 3 2) (/ 14 (+ 3 4)))
  7770.  
  7771.    S-Expressions can be nested to any reasonable level; for example, the
  7772.    value of the following S-Expression is 64:
  7773.  
  7774.   (- (* (+ 2 (* 3 4)) (- 9 (* 2 2))) 6)
  7775.  
  7776.    Operators have no precedence, implied or otherwise, since they can't be
  7777.    mixed. The only exceptions are unary + and -, which simply indicate the
  7778.    sign of a number:
  7779.  
  7780.   (* 3 -1)
  7781.  
  7782.    Order of evaluation is specified entirely by parentheses, which are
  7783.    required around each operator and its operands: (+ a (* b c)) instead
  7784.    of (a + b * c).
  7785.  
  7786.    S-Expressions provide a simple and isolated environment in which
  7787.    Kermit's macro names can be used without the \m(...) escaping that is
  7788.    normally required. Given:
  7789.  
  7790.   define a 1
  7791.   define b 2
  7792.   define c 3
  7793.  
  7794.    Then:
  7795.  
  7796.   (+ \m(a) \m(b) \m(c))
  7797.  
  7798.    is equivalent to:
  7799.  
  7800.   (+ a b c)
  7801.  
  7802.    Within an S-Expression, as in other strictly numeric contexts
  7803.    ([499]Section 8.2), any operand that starts with a letter is treated as
  7804.    a Kermit macro name. In this context, abbreviations are not accepted;
  7805.    variable names must be spelled out in full. Alphabetic case is not
  7806.    significant; "a" and "A" are the same variable, but both are different
  7807.    from "area".
  7808.  
  7809.    Of course, regular Kermit variables and functions can be used in
  7810.    S-Expressions in the normal ways:
  7811.  
  7812.   (* \v(math_pi) (^ \%r 2))             ; Area of a circle with radius \%r
  7813.   (+ \fjoin(&a))                        ; Sum of all elements of array \&a[]
  7814.  
  7815.    [ [500]Top ] [ [501]Contents ] [ [502]C-Kermit Home ] [ [503]Kermit
  7816.    Home ]
  7817.  
  7818. 9.2. Integer and Floating-Point-Arithmetic
  7819.  
  7820.    Normally, if all numbers in an S-Expression are integers, the result is
  7821.    an integer:
  7822.  
  7823.   (+ 1 1)                               ; Result is 2
  7824.   (/ 9 3)                               ; Result is 3
  7825.  
  7826.    If any of the operands is floating point, however, the result is also
  7827.    floating point:
  7828.  
  7829.   (+ 1 1.0)                             ; Result is 2.0
  7830.   (/ 9.0 3)                             ; Result is 3.0
  7831.  
  7832.    If all the operands are integers but the result has a fractional part,
  7833.    the result is floating point:
  7834.  
  7835.   (/ 10 3)                              ; Result is 3.333333333333333
  7836.  
  7837.    To force an integer result in such cases, use the TRUNCATE operator:
  7838.  
  7839.   (truncate (/ 10 3))                   ; Result is 3
  7840.  
  7841.    Similarly, to force a computation to occur in floating point, you can
  7842.    coerce one of its operands to FLOAT:
  7843.  
  7844.   (+ 1 (float 1))                       ; Result is 2.0
  7845.  
  7846.    The result is also floating point if the magnitude of any integer
  7847.    operand, intermediate result, or the result itself, is larger than the
  7848.    maximum for the underlying machine architecture:
  7849.  
  7850.   (^ 100 100)
  7851.  
  7852.    If the result is too large even for floating-point representation,
  7853.    "Infinity" is printed; if it is too small to be distinguished from 0,
  7854.    0.0 is returned.
  7855.  
  7856.    Large numbers can be used and large results generated, but they are
  7857.    accurate only to the precision of the underlying machine. For example,
  7858.    the result of:
  7859.  
  7860.  (+ 111111111111111111111 222222222222222222222)
  7861.  
  7862.    should be 333333333333333333333, but 333333333333333300000.0 is
  7863.    produced instead if the machine is accurate to only about 16 decimal
  7864.    digits, even with coercion to floating-point. The order of magnitude is
  7865.    correct but the least significant digits are wrong. The imprecise
  7866.    nature of the result is indicated by the ".0" at the end. Contrast
  7867.    with:
  7868.  
  7869.  (+ 111111111 222222222)
  7870.  
  7871.    which produces an exact integer result.
  7872.  
  7873.    [ [504]Top ] [ [505]Contents ] [ [506]C-Kermit Home ] [ [507]Kermit
  7874.    Home ]
  7875.  
  7876. 9.3. How to Use S-Expressions
  7877.  
  7878.    S-Expressions may be given as commands to C-Kermit. Any command whose
  7879.    first character is "(" (left parenthesis) is interpreted as an
  7880.    S-Expression.
  7881.  
  7882.    If you enter an S-Expression at the C-Kermit> prompt, its result is
  7883.    printed:
  7884.  
  7885.   C-Kermit>(/ 10.0 3)
  7886.    3.333333333333333
  7887.   C-Kermit>
  7888.  
  7889.    If an S-Expression is executed within a macro or command file, its
  7890.    value is not printed. However, you can control the printing action
  7891.    with:
  7892.  
  7893.    SET SEXPRESSION ECHO { AUTO, ON, OFF }
  7894.           AUTO is the default, meaning print the value at top level only;
  7895.           ON means always print the value; OFF means never print it.
  7896.  
  7897.    In any case, the value of the most recent S-Expression (and the
  7898.    S-Expression itself) may be accessed programmatically through the
  7899.    following variables:
  7900.  
  7901.    \v(sexpression)
  7902.           The S-Expression most recently executed.
  7903.  
  7904.    \v(svalue)
  7905.           The value of the S-Expression most recently executed.
  7906.  
  7907.    Besides issuing S-Expressions as commands in themselves, you can also
  7908.    execute them anywhere within a Kermit command, but in this case they
  7909.    must be enclosed in a function call (otherwise they are taken
  7910.    literally):
  7911.  
  7912.    \fsexpression(s)
  7913.           The argument "s" is an S-Expression; the outer parentheses may
  7914.           be omitted. The value of the S-Expression is returned. Note that
  7915.           since S-Expressions usually contain spaces, some form of
  7916.           grouping or quoting might be needed in some contexts:
  7917.  
  7918.   echo \fsexpression((+ 1 1))            ; Outer parentheses may be included
  7919.   echo \fsexpr(+ 1 1)                    ; Outer parentheses may be omitted
  7920.   echo Value = "\fsexp(+ 1 a)"           ; Can be embedded in strings
  7921.   echo Value = \&a[\fsexp(/ b 2)]        ; Can be used in array subscripts
  7922.   if = {\fsexp(+ 1 1)} 2 {               ; Braces needed here for grouping
  7923.       echo One plus one still equals two
  7924.   }
  7925.  
  7926.    The IF statement illustrates how to use S-Expressions as (or in) IF or
  7927.    WHILE conditions:
  7928.  
  7929.      * Although S-Expressions and IF conditions are similar in appearance,
  7930.        they are not interchangeable. Therefore you must use \fsexpr() to
  7931.        let Kermit know it's an S-Expression rather than a regular IF
  7932.        condition, or a boolean or algebraic expression within an IF
  7933.        condition.
  7934.      * In contexts where a single "word" is expected, you must enclose the
  7935.        \fsexp() invocation in braces if the S-Expression contains spaces
  7936.        (and most of them do).
  7937.  
  7938.    If an S-Expression is the last command executed in a macro, its value
  7939.    becomes the return value of the macro; no RETURN command is needed.
  7940.    Example:
  7941.  
  7942.   def newarea {
  7943.       (let s (/ (+ \%1 \%2 \%3) 2.0))
  7944.       (sqrt (* s (- s \%1) (- s \%2) (- s \%3)))
  7945.   }
  7946.  
  7947.    This is equivalent to (but more efficient than):
  7948.  
  7949.   def newarea {
  7950.       (let s (/ (+ \%1 \%2 \%3) 2.0))
  7951.       return \fsexp(sqrt (* s (- s \%1) (- s \%2) (- s \%3)))
  7952.   }
  7953.  
  7954.    When an S-Expression is entered as a command -- that is, the first
  7955.    nonblank character of the command is a left parenthesis -- then it is
  7956.    allowed to span multiple lines, as many as you like, until the first
  7957.    left parenthesis is matched:
  7958.  
  7959.   (let s (/
  7960.           (+
  7961.            \%1
  7962.            \%2
  7963.            \%3
  7964.            )
  7965.           2.0
  7966.           )
  7967.        )
  7968.   (sqrt (*
  7969.          s
  7970.          (- s \%1)
  7971.          (- s \%2)
  7972.          (- s \%3)
  7973.          )
  7974.         )
  7975.  
  7976.    The S-Expression concept lends itself easily to embedding and
  7977.    recursion, but the depth to which recursion can occur is limited by the
  7978.    resources of the computer (memory size, address space, swap space on
  7979.    disk) and other factors. There is no way that C-Kermit can know what
  7980.    this limit is, since it varies not only from computer to computer, but
  7981.    also from moment to moment. If resources are exhausted by recursion,
  7982.    C-Kermit simply crashes; there's no way to trap this error. However,
  7983.    you can set a depth limit on S-Expressions:
  7984.  
  7985.    SET SEXPRESSION DEPTH-LIMIT number
  7986.           Limits the number of times the S-Expression reader can invoke
  7987.           itself without returning to the given number. The default limit
  7988.           is 1000. This limit applies to S-Expressions embedded within
  7989.           other S-Expressions as well as to S-Expressions that invoke
  7990.           recursive macros. If the limit is exceeded, Kermit prints
  7991.           "?S-Expression depth limit exceeded" and returns to its prompt.
  7992.           More about recursion in [508]Section 9.8.
  7993.  
  7994.    You can also test the depth programmatically:
  7995.  
  7996.    \v(sdepth)
  7997.           The current S-Expression invocation depth. The depth includes
  7998.           both nesting level and recursion. For example, in:
  7999.           (foo (foo (foo (foo (foo))))), the innermost (foo) is at depth
  8000.           5.
  8001.  
  8002.    Help, completion, and syntax checking are not available within an
  8003.    S-Expression. If you type ? within an S-Expression, it says:
  8004.  
  8005.   C-Kermit>(? S-Expression ("help sexp" for details)
  8006.  
  8007.    As it says, typing "help sexp" will display a brief help text.
  8008.  
  8009.    The SHOW SEXPRESSION command displays current SET SEXPRESSION settings
  8010.    and related information.
  8011.  
  8012.    [ [509]Top ] [ [510]Contents ] [ [511]C-Kermit Home ] [ [512]Kermit
  8013.    Home ]
  8014.  
  8015. 9.4. Summary of Built-in Constants and Operators
  8016.  
  8017.    Three constants are built in:
  8018.  
  8019.      * PI, whose value is the value of pi (the quotient of circumference
  8020.        of any circle and its diameter, 3.141592653...) to the underlying
  8021.        machine's precision;
  8022.      * T, which always has the value 1, which signifies truth in Kermit
  8023.        logical expressions or S-Expressions;
  8024.      * NIL, which always has the empty value, and can serve as a False
  8025.        truth value.
  8026.  
  8027.    These constants are specific to S-Expressions and are not visible
  8028.    outside them. They may not be used as the target of an assignment. So,
  8029.    for example:
  8030.  
  8031.   (setq t 0)   Fails
  8032.   assign t 0   Succeeds but this is not the same T!
  8033.  
  8034.    E (the base of natural logarithms, 2.7182818184...) is not built in
  8035.    since it is not intrinsic in most Lisp dialects. If you want E to be
  8036.    the base of natural logarithms you can:
  8037.  
  8038.   (setq e (exp 1))
  8039.  
  8040.    Operators are either symbols (such as "+") or words. Words must be
  8041.    spelled out in full, not abbreviated. Differences of alphabetic case
  8042.    are ignored.
  8043.  
  8044.    The most basic operation in S-Expressions is evaluation:
  8045.  
  8046.    EVAL [ s-expression or variable or number [ another [ another ... ] ] ]
  8047.           Evaluates its operands and returns the value of the last one
  8048.           evaluated. Examples:
  8049.  
  8050.   (eval)                                0
  8051.   (eval 1)                              1
  8052.   (eval a)                              value of a
  8053.   (eval (+ 1 a))                        value of a+1
  8054.   (eval (setq a 1) (setq b (+ a 0.5)))  value of b (= a+0.5)
  8055.  
  8056.           You can use "." as a shorthand for EVAL:
  8057.  
  8058.   (.)
  8059.   (. 1)
  8060.   (. a)
  8061.   (. (+ 1 a))
  8062.   (. (setq a 1) (setq b (+ a 0.5)))
  8063.  
  8064.    Opposite of EVAL is the operator that suppresses evaluation of its
  8065.    operand:
  8066.  
  8067.    QUOTE item
  8068.           The value (quote item) is "item". If the item is itself an
  8069.           S-Expression, the result is the S-Expression with the outer
  8070.           parentheses stripped. Examples:
  8071.  
  8072.   (quote)                               (illegal)
  8073.   (quote a)                             a
  8074.   (quote hello)                         hello
  8075.   (quote (this is a string))            this is a string
  8076.   (quote this is a string)              (illegal)
  8077.  
  8078.           A shorthand notation is also accepted for quoting:
  8079.           'a is equivalent to (quote a). And therefore:
  8080.           '(a b c) is equivalent to (quote (a b c)).
  8081.           More about quoting in [513]Section 9.8.
  8082.  
  8083.    STRING item
  8084.           Is a combination of EVAL and QUOTE. It evaluates the item as an
  8085.           S-Expression, and then puts quotes around the result (more about
  8086.           this in [514]Section 9.8).
  8087.  
  8088.    The following operators assign values to variables:
  8089.  
  8090.    SETQ [ variable [ value [ variable [ value [ ... ] ] ] ] ]
  8091.           Applies to global variables. For each variable given: if a value
  8092.           is not given, the variable is undefined. If a value is given,
  8093.           assigns the value to the variable. The value may be a number, a
  8094.           variable, or anything that resolves to a number including an
  8095.           S-Expression. Returns the value of the last assignment.
  8096.           Examples:
  8097.  
  8098.   (setq)             Does nothing, returns NIL.
  8099.   (setq a)           Undefines a, returns NIL.
  8100.   (setq a 1)         Assigns 1 to a, returns 1.
  8101.   (setq a 1 b 2)     Assigns 1 to a, 2 to b, returns 2.
  8102.   (setq a 1 b 2 c)   Assigns 1 to a, 2 to b, undefines c, returns NIL.
  8103.  
  8104.    To undefine a variable that is not the final one in the list, give it a
  8105.    value of "()" or NIL:
  8106.  
  8107.   (setq a () b 2)    Undefines a, assigns 2 to b, returns 2.
  8108.   (setq a nil b 2)   Ditto.
  8109.  
  8110.    Note that a variable can be used right away once it has a value:
  8111.  
  8112.   (setq a 1 b a)     Assigns 1 to a, the value of a (1) to b, returns 1.
  8113.  
  8114.    The results of SETQ (when used with macro names) can be checked
  8115.    conveniently with SHOW MACRO, e.g:
  8116.  
  8117.   show mac a b c
  8118.  
  8119.    LET [ variable [ value [ variable [ value [ ... ] ] ] ] ]
  8120.           Like SETQ, but applies to local variables. Note that "local" is
  8121.           used in the Kermit sense, not the Lisp sense; it applies to the
  8122.           current Kermit command level, not to the current S-Expression.
  8123.  
  8124.    If you want to use SETQ or LET to assign a value to a backslash
  8125.    variable such as \%a or \&a[2], you must double the backslash:
  8126.  
  8127.   (setq \\%a 3)
  8128.   (setq \\%b (+ \%a 1))
  8129.   (setq \\&a[2] (setq (\\%c (+ \%a \%b))))
  8130.  
  8131.    In other words:
  8132.  
  8133.      * Double the backslash when you want to indicate the variable's NAME;
  8134.      * Don't double the backslash when you want its VALUE.
  8135.  
  8136.    See [515]Section 9.6 for a fuller explanation of variable syntax and
  8137.    scope.
  8138.  
  8139.    Here's a summary table of arithmetic operators; in the examples, a is 2
  8140.    and b is -1.3:
  8141.  
  8142.   Operator  Description                            Example           Result
  8143.   +         Adds all operands (0 or more)          (+ a b)           0.7
  8144.   -         Subtracts all operands (0 or more)     (- 9 5 2 1)       1
  8145.   *         Multiplies all operands (0 or more)    (* a (+ b 1) 3)  -1.80
  8146.   /         Divides all operands (2 or more)       (/ b a 2)        -0.325
  8147.   ^         Raise given number to given power      (^ 3 2)           9
  8148.   ++        Increments variables                   (++ a 1.2)        3.2
  8149.   --        Decrements variables                   (-- a)            1
  8150.   ABS       Absolute value of 1 operand            (abs (* a b 3))   7.8
  8151.   MAX       Maximum of all operands (1 or more)    (max 1 2 3 4)     4
  8152.   MIN       Minimum of all operands (1 or more)    (min 1 2 3 4)     1
  8153.   MOD (%)   Modulus of all operands (1 or more)    (mod 7 4 2)       1
  8154.   FLOAT     Convert an integer to floating-point   (float 1)         1.0
  8155.   TRUNCATE  Integer part of floating-point operand (truncate 3.333)  3
  8156.   CEILING   Ceiling of floating-point operand      (ceiling 1.25)    2
  8157.   FLOOR     Floor of floating-point operand        (floor 1.25)      1
  8158.   ROUND     Operand rounded to nearest integer     (round 1.75)      2
  8159.   SQRT      Square root of 1 operand               (sqrt 2)          1.414..
  8160.   EXP       e (2.71828..) to the given power       (exp -1)          0.367..
  8161.   SIN       Sine of angle-in-radians               (sin (/ pi 2))    1.0
  8162.   COS       Cosine of angle-in-radians             (cos pi)         -1.0
  8163.   TAN       Tangent of angle-in-radians            (tan pi)          0.0
  8164.   LOG       Natural log (base e) of given number   (log 2.7183)      1.000..
  8165.   LOG10     Log base 10 of given number            (log10 1000)      3.0
  8166.  
  8167.    The ++ and -- operators are also assignment operators and work just
  8168.    like SETQ and LET in their interpretations of operators and operands,
  8169.    but:
  8170.  
  8171.      * Each target variable must already be defined and have a numeric
  8172.        value;
  8173.      * The assignment value is the amount by which to increment or
  8174.        decrement the variable.
  8175.      * If an assignment value is not given, 1 is used.
  8176.  
  8177.    If you include more than one variable-value pair in a ++ or --
  8178.    expression, every variable (except, optionally, the last) must be
  8179.    followed by a value. Examples:
  8180.  
  8181.   (++ a)                Equivalent to (setq a (+ a 1)) and to (++ a 1)
  8182.   (++ a 2)              Equivalent to (setq a (+ a 2))
  8183.   (-- a (* 2 pi))       Equivalent to (setq a (- a (* 2 pi)))
  8184.   (++ a 1 b 1 c 1 d)    Equivalent to four SETQs incrementing a,b,c,d by 1.
  8185.  
  8186.    Another group of operators forms the predicates. These return a "truth
  8187.    value", in which 0 (or NIL) is false, and 1 or any other nonzero number
  8188.    is true.
  8189.  
  8190.   Operator  Description                            Example           Result
  8191.   = (or ==) Operands are equal                     (= 1 1.0)         1
  8192.   !=        Operands are not equal                 (!= 1 1.0)        0
  8193.   <         Operands in strictly ascending order   (< 1 2 3)         1
  8194.   <=        Operands in ascending order            (<= 1 1 2 3)      1
  8195.   >         Operands in strictly descending order  (> 3 2 1)         1
  8196.   >=        Operands in descending order           (<= 3 3 2 1)      1
  8197.   AND (&&)  Operands are all true                  (and 1 1 1 1 0)   0
  8198.   OR  (||)  At least one operand is true           (or 1 1 1 1 0)    1
  8199.   XOR       Logical Exclusive OR                   (xor 3 1)         0
  8200.   NOT (!)   Reverses truth value of operand        (not 3)           0
  8201.  
  8202.    The Exclusive OR of two values is true if one value is true and the
  8203.    other value is false.
  8204.  
  8205.    And another group operates on bits within an integer word:
  8206.  
  8207.   Operator  Description                            Example           Result
  8208.   &         Bitwise AND                            (& 7 2)           2
  8209.   |         Bitwise OR                             (| 1 2 3 4)       7
  8210.   #         Bitwise Exclusive OR                   (# 3 1)           2
  8211.   ~         Reverses all bits                      (~ 3)            -4
  8212.  
  8213.    These operators coerce their operands to integer by truncation if
  8214.    necessary. The result of bit reversal is hardware dependent.
  8215.  
  8216.    The final category of operator works on truth values:
  8217.  
  8218.   Operator  Description                            Example           Result
  8219.   IF        Conditional evaluation                 (if (1) 2 3)      2
  8220.  
  8221.    IF (predicate) (s1) [ (s2) ]
  8222.           The IF operator is similar to Kermit's IF command. If the
  8223.           predicate is true (i.e. evaluates to a nonzero number), the
  8224.           first S-Expression (s1) is evaluated and its value is returned.
  8225.           Otherwise, if (s2) is given, it is evaluated and its value
  8226.           returned; if (s2) is not given, nothing happens and the NIL
  8227.           (empty) value is returned.
  8228.  
  8229.    You can group multiple expressions in the s1 and s2 expressions using
  8230.    EVAL (or "."):
  8231.  
  8232.   (if (< a 0) (eval (setq x 0) (setq y 0)) (eval (setq x a) (setq y b)))
  8233.  
  8234.    or equivalently:
  8235.  
  8236.   (if (< a 0) (. (setq x 0) (setq y 0)) (. (setq x a) (setq y b)))
  8237.  
  8238.    Each operator has its own requirement as to number and type of
  8239.    operands. In the following table, "number" means any kind of number --
  8240.    integer or floating-point -- or a variable, function, macro, or
  8241.    S-Expression that returns a number; "vname" means variable name,
  8242.    "fpnumber" means a floating-point number (or anything that resolves to
  8243.    one), and "integer" means integer (or anything that resolves to one).
  8244.    "truthvalue" means anything that resolves to a value of zero or an
  8245.    empty value (which indicates false) or a nonzero value (which indicates
  8246.    true). "any" means any kind of value, including none at all.
  8247.  
  8248.   Operator  Number of operands   Type of operands    Returns
  8249.   EVAL  (.) 0 or more            S-Expression        Last value (default NIL)
  8250.   STRING    1                    S-Expression        string
  8251.   QUOTE (') 1                    word                string
  8252.   SETQ      0 or more            vname value pairs   Last value (default NIL)
  8253.   LET       0 or more            vname value pairs   Last value (default NIL)
  8254.   +         0 or more            number              number     (default 0)
  8255.   -         0 or more            number              number     (default 0)
  8256.   *         0 or more            number              number     (see note (1))
  8257.   /         2 or more            number              number
  8258.   ^         2 or more            number              number
  8259.   ++        1 or more            vname value pairs   Result of last increment
  8260.   --        1 or more            vname value pairs   Result of last decrement
  8261.   ABS       1                    number              number
  8262.   MAX       1 or more            number              number
  8263.   MIN       1 or more            number              number
  8264.   MOD (%)   2                    number              number
  8265.   FLOAT     1                    number              fpnumber
  8266.   TRUNCATE  1                    number              integer
  8267.   CEILING   1                    number              integer
  8268.   FLOOR     1                    number              integer
  8269.   ROUND     1                    number              integer
  8270.   SQRT      1                    number              fpnumber
  8271.   EXP       1                    number              fpnumber
  8272.   SIN       1                    number              fpnumber
  8273.   COS       1                    number              fpnumber
  8274.   TAN       1                    number              fpnumber
  8275.   LOG       1                    number              fpnumber
  8276.   LOG10     1                    number              fpnumber
  8277.   = (==)    1 or more            number              truthvalue
  8278.   !=        1 or more            number              truthvalue
  8279.   <         1 or more            number              truthvalue
  8280.   <=        1 or more            number              truthvalue
  8281.   >         1 or more            number              truthvalue
  8282.   >=        1 or more            number              truthvalue
  8283.   AND (&&)  1 or more            truthvalue          truthvalue
  8284.   OR  (||)  1 or more            truthvalue          truthvalue
  8285.   XOR       2                    truthvalue          truthvalue
  8286.   NOT (!)   1                    truthvalue          truthvalue
  8287.   &         1 or more            number (see note 2) integer
  8288.   |         1 or more            number (see note 2) integer
  8289.   #         2                    number (see note 2) integer
  8290.   ~         1                    number (see note 2) integer
  8291.   IF        2 or 3               truthvalue,any,any  any
  8292.  
  8293.    Operators that don't require any arguments return the default values
  8294.    shown.
  8295.  
  8296.     1. The value of "*", when used as an operand, is initially "1" and the
  8297.        value of the most recent S-Expression thereafter, as in Franz Lisp.
  8298.        This is handy when doing a series of calculations by hand:
  8299.   C-Kermit>(* 13272.42 0.40)
  8300.    5308.968
  8301.   C-Kermit>(/ * 2)
  8302.    2654.4840
  8303.   C-Kermit>
  8304.  
  8305.     2. The bitwise operators coerce their operands to integer by
  8306.        truncation.
  8307.  
  8308.    [ [516]Top ] [ [517]Contents ] [ [518]C-Kermit Home ] [ [519]Kermit
  8309.    Home ]
  8310.  
  8311. 9.5. Variables
  8312.  
  8313.    As noted elsewhere in this discussion, all backslash items (variables
  8314.    such as \%a, macro parameters such as \%1, array elements such as
  8315.    \&a[\%i], built-in variables such as \v(ndate), built-in functions such
  8316.    as \fjoin(), macro names enclosed in \m(), \s(), or \:(), etc) are
  8317.    evaluated at "top level" before the S-Expression is sent to the
  8318.    S-Expression reader. To use a backslash variable as the target of an
  8319.    assignment (e.g. by SETQ, LET, ++, or --), you must double the
  8320.    backslash, e.g. (setq \\%r 1234). This is discussed at greater length
  8321.    in the next section.
  8322.  
  8323.    Thus S-Expression reader generally deals only with macro names (not
  8324.    backslash items) as variables. It is important to understand how the
  8325.    reader handles macro names. There are fundamentally two kinds of
  8326.    S-Expressions: those that contain a single element, such as:
  8327.  
  8328.   (foo)
  8329.  
  8330.    and those that contain more than one element:
  8331.  
  8332.   (foo a b c)
  8333.  
  8334.    If an S-Expression contains only one element, and it is the name of a
  8335.    macro, the macro's definition is examined. If the definition is a
  8336.    number (integer or floating-point, positive or negative), then this
  8337.    becomes the value of the expression. If the definition starts with '
  8338.    (apostrophe), then the quoted word or string is the value of the
  8339.    expression (explained in [520]Section 9.8). Otherwise, the macro is
  8340.    assumed to be composed of Kermit commands (possibly including
  8341.    S-Expressions), which are executed. If the macro has a RETURN value, or
  8342.    it executes an S-Expression as its last command, the result becomes the
  8343.    value of the S-Expression; otherwise the result is empty.
  8344.  
  8345.    For S-Expressions that contain more than one element, and the first
  8346.    element is the name of a macro, then this macro is executed with the
  8347.    arguments that are given, after the arguments are evaluated by the
  8348.    S-Expression reader. Likewise, If the first element is a built-in
  8349.    operator, then it is applied to the operands after they are evaluated.
  8350.    In both cases, each operand is fed to the S-Expression reader
  8351.    recursively for evaluation. If an operand is a number or a quoted
  8352.    string, it is used as-is. But if it's a macro name, this degenerates
  8353.    into the first case, and the previous paragraph applies.
  8354.  
  8355.    Examples:
  8356.  
  8357.   define foo 123
  8358.   (foo)                                Result: 123
  8359.   define foo 'abc
  8360.   (foo)                                Result: abc
  8361.   define foo '(one two three)
  8362.   (foo)                                Result: one two three
  8363.   define foo return \frandom(1000)
  8364.   (foo)                                Result: 713 (or other number)
  8365.   define foo (+ a b)
  8366.   (foo)                                Result: The sum of a and b
  8367.  
  8368.    A more difficult example:
  8369.  
  8370.   define foo abc
  8371.   (foo)                                Result: ???
  8372.  
  8373.    The result in the last example depends on the definition of abc:
  8374.  
  8375.      * If it has no definition, an error occurs; otherwise:
  8376.      * If the definition is an S-Expression, the result is the
  8377.        S-Expression's value; otherwise:
  8378.      * If the definition consists of Kermit commands, they are executed.
  8379.        But in this case "(foo)" produces the empty result, because it
  8380.        doesn't RETURN anything.
  8381.  
  8382.    The use of macros as S-Expression operators is described in
  8383.    [521]Section 9.8.
  8384.  
  8385.    [ [522]Top ] [ [523]Contents ] [ [524]C-Kermit Home ] [ [525]Kermit
  8386.    Home ]
  8387.  
  8388. 9.6. Assignments and Scope
  8389.  
  8390.    The assignment operators SETQ and LET apply to global and local
  8391.    variables, respectively. SETQ and LET are standard Lisp operators
  8392.    adapted to Kermit scoping rules. When the operands are numeric or
  8393.    arithmetic, SETQ is equivalent to Kermit's EVALUATE command:
  8394.  
  8395.   (setq a (+ 1 2))
  8396.   evaluate a 1 + 2
  8397.  
  8398.    When the operand is a string, SETQ is equivalent to DEFINE:
  8399.  
  8400.   (setq a '(this is a string))
  8401.   define a this is a string
  8402.  
  8403.    In the first case, both statements create a macro named "a" with a
  8404.    value of 3. But in neither case is the macro "a" necessarily global. If
  8405.    either of these commands executes in an environment (i.e. macro
  8406.    invocation level) where a "local a" command has been given, the "a"
  8407.    macro is global to that environment, but is not visible outside it.
  8408.  
  8409.    LET is equivalent to the Kermit LOCAL command, followed by the
  8410.    corresponding EVALUATE:
  8411.  
  8412.   (let a (+ 1 2))
  8413.  
  8414.    is equivalent to:
  8415.  
  8416.   local a
  8417.   evaluate a 1 + 2
  8418.  
  8419.    Again, "local" in this context applies to the Kermit macro invocation
  8420.    stack, not to the S-Expression nesting level. To illustrate, recall our
  8421.    "newarea" macro:
  8422.  
  8423. def newarea {
  8424.     (let a \%1 b \%2 c \%3)
  8425.     (let s (/ (+ a b c) 2.0))
  8426.     (sqrt (* s (- s a) (- s b) (- s c)))
  8427. }
  8428.  
  8429.    Because SETQ and LET expressions return a value, they can be placed
  8430.    within a larger S-Expression. In this case we can replace the first
  8431.    reference to the "s" variable by its defining expression:
  8432.  
  8433. def newarea {
  8434.     (let a \%1 b \%2 c \%3)
  8435.     (sqrt (* (let s (/ (+ a b c) 2.0)) (- s a) (- s b) (- s c)))
  8436. }
  8437.  
  8438.    This would not work if LET were local to the S-Expression, but it works
  8439.    nicely in the context of Kermit macros. The previous definition is
  8440.    equivalent to:
  8441.  
  8442. def newarea {
  8443.     local a b c s
  8444.     (setq a \%1 b \%2 c \%3)
  8445.     (sqrt (* (setq s (/ (+ a b c) 2.0)) (- s a) (- s b) (- s c)))
  8446. }
  8447.  
  8448.    In both cases, the variables a, b, c, and s are local to the "newarea"
  8449.    macro, and global within it.
  8450.  
  8451.    Multiple assignments can be handled in several ways. Here is the
  8452.    obvious way to initialize a series of variables to the same value:
  8453.  
  8454.   (setq a 0)
  8455.   (setq b 0)
  8456.   (setq c 0)
  8457.   (setq s 0)
  8458.  
  8459.    Here is a more compact and efficient way of doing the same thing:
  8460.  
  8461.   (setq a 0 b 0 c 0 s 0)
  8462.  
  8463.    However, in case the value was more complex, it's better to put only
  8464.    one copy of it in the S-Expression; in this case we rely on the fact
  8465.    that SETQ returns the value of its last assignment:
  8466.  
  8467.   (setq a (setq b (setq c (setq s (* x (^ y 2))))))
  8468.  
  8469.    Similarly, to set a series of variables to x, x+1, x+2, ...
  8470.  
  8471.   (setq c (+ (setq b (+ (setq a (+ (setq s x) 1)) 1)) 1))
  8472.  
  8473.    In the last example, you can see why "last" does not always correspond
  8474.    to "rightmost" (the leftmost variable "c" is assigned last).
  8475.  
  8476.    If you are working with backslash variables like \%a or array elements
  8477.    like \&a[1], remember two rules:
  8478.     1. Don't put spaces inside array brackets.
  8479.     2. You must double the backslash when using SETQ, LET, ++, or -- to
  8480.        assign a value to a backslash variable.
  8481.  
  8482.    Examples of assigning to a backslash variable:
  8483.  
  8484.   (setq x 1)
  8485.   (setq \\%a 0)
  8486.   (setq \\&a[x+1] 1)
  8487.   (++ \\%x)
  8488.   (-- \\&a[x+2])
  8489.  
  8490.    Examples of referring to a backslash variable's value:
  8491.  
  8492.   (setq a (+ \%a 1))
  8493.   (setq b (+ \%a \&a[1]))
  8494.   (++ a \%x)
  8495.   (-- b \&a[1])
  8496.  
  8497.    The special notation is required because all backslashed items (\%x
  8498.    variables, array elements, built-in \v(xxx) variables, and \fxxx()
  8499.    function invocations) are evaluated in a single pass BEFORE the
  8500.    S-Expression is executed; any other approach would result in
  8501.    unacceptable performance. So, for example, in:
  8502.  
  8503.   declare \&a[] = 1 2 3
  8504.   define \%x 4
  8505.   define \%y 0
  8506.   (setq \\%y (+ \%x \&a[1]))
  8507.  
  8508.    the S-Expression becomes:
  8509.  
  8510.   (setq \%y (+ 4 1))
  8511.  
  8512.    before it is sent to the S-Expression evaluator. If the backslash had
  8513.    not been doubled on the assignment target, the result would have been:
  8514.  
  8515.   (setq 0 (+ 4 1))
  8516.  
  8517.    which is illegal because you can't assign a value to a number.
  8518.    Conversely, if backslashes were doubled on right-hand-side values:
  8519.  
  8520.   (setq \\%y (+ \\%x \\&a[1])
  8521.  
  8522.    this too, would give an error (not numeric - "\%x").
  8523.  
  8524.    If you omit the double backslash in the assignment target, the result
  8525.    depends on whether the variable already has a value:
  8526.  
  8527.   (setq \%a (* 3 3))
  8528.  
  8529.    If \%a has a non-numeric single-word value, then this becomes the name
  8530.    of the variable that is assigned by SETQ. To illustrate:
  8531.  
  8532.   define \%a foo
  8533.   echo \%a
  8534.   foo
  8535.   (setq \%a (* 3 3))
  8536.   echo \%a
  8537.   foo
  8538.   show macro foo
  8539.   foo = 9
  8540.  
  8541.    If \%a has no value, a numeric value, or a multiword value, an "invalid
  8542.    assignment" error occurs.
  8543.  
  8544.    [ [526]Top ] [ [527]Contents ] [ [528]C-Kermit Home ] [ [529]Kermit
  8545.    Home ]
  8546.  
  8547. 9.7. Conditional Expressions
  8548.  
  8549.    The IF operator provides a compact form of decision-making within
  8550.    S-Expressions. An IF expression can stand wherever a number might
  8551.    stand, as long is it returns a number. Here's a quick way to obtain the
  8552.    average value of all the elements in an array that contains only
  8553.    numbers:
  8554.  
  8555.   (/ (+ \fjoin(&a)) (float \fdim(&a)))
  8556.  
  8557.    This results in a "Divide by zero" error if the array is empty. If you
  8558.    want to define the average value of an empty array to be 0 instead of
  8559.    getting an error, you can use IF to check the array size:
  8560.  
  8561.   (if \fdim(&a) (/ (+ \fjoin(&a)) (float \fdim(&a))) 0)
  8562.  
  8563.    or equivalently:
  8564.  
  8565.   (if (not \fdim(&a)) 0 (/ (+ \fjoin(&a)) (float \fdim(&a))))
  8566.  
  8567.    Of course, IF can fit anywhere else into an S-Expression:
  8568.  
  8569.   (setq a (+ b (if (< c 0) 0 c)))
  8570.  
  8571.    and the IF expression can be as complex as you like:
  8572.  
  8573.   (setq a (+ b (if (and (or (> x 0) (> y 0)) (< c 0) (> d 1) (!= e 0)) 1 0)))
  8574.  
  8575.    and the "then" and "else" parts can contain multiple S-Expressions
  8576.    enclosed within (EVAL ...):
  8577.  
  8578.   (if x (eval (...) (...) (...)) (eval (...) (...) (...)))
  8579.  
  8580.    AND and OR operators are guaranteed to "short circuit". If any operand
  8581.    of AND is false, none of the subsequent operands is evaluated;
  8582.    likewise, if an OR operand is true, no further operands are evaluated.
  8583.  
  8584.    Bear in mind that the S-Expression IF is not the same as Kermit IF; the
  8585.    condition is only allowed to be an S-Expression or a variable or
  8586.    number, not the whole list of possibilities you see when you type "if
  8587.    ?" at the C-Kermit> prompt. But keep reading...
  8588.  
  8589.    [ [530]Top ] [ [531]Contents ] [ [532]C-Kermit Home ] [ [533]Kermit
  8590.    Home ]
  8591.  
  8592. 9.8. Extensibility
  8593.  
  8594.    To extend the capabilities of S-Expressions, you can use Kermit macro
  8595.    names as operators, with the following limitations:
  8596.  
  8597.      * The macro must not have the same name as a built-in operator.
  8598.      * You must use the full macro name, not an abbreviation.
  8599.  
  8600.    And with the following enhancement:
  8601.  
  8602.      * If the last statement executed by the macro is an S-Expression, its
  8603.        value is returned automatically. In other words:
  8604.  
  8605.   define bump (++ \%1)
  8606.  
  8607.    is equivalent to:
  8608.  
  8609.   define bump return \fsexpression(++ \%1)
  8610.  
  8611.    Here's an example in which we define a FIBONACCI operator that returns
  8612.    the nth element, n >= 0, of the Fibonacci series, 0 1 1 2 3 5 8 13 21
  8613.    34 55, . . ., in which the first element is 0, the second is 1, and
  8614.    each subsequent element is the sum of the two before it. This series
  8615.    was devised by Leonardo Pisano, Filius Bonacci (Fibonacci for short) in
  8616.    1202 to describe how fast rabbits can breed, and also forms the basis
  8617.    for the Golden Mean, the branching behavior of plants, the spiral of a
  8618.    nautilus shell, etc. (Thanks to [534]Dat Thuc Nguyen for December 2003
  8619.    corrections to this section!)
  8620.  
  8621.    We can write a FIBONACCI function as a macro easily with S-Expressions:
  8622.  
  8623.   define FIBONACCI {
  8624.     (if (== \%1 0) 0
  8625.         (if (== \%1 1) 1 (+ (fibonacci (- \%1 2)) (fibonacci (- \%1 1)))))
  8626.   }
  8627.  
  8628.    You can read this as:
  8629.  
  8630.      If the argument (\%1) is 0, return a result of 0; if it is 1,
  8631.      return 1; otherwise:
  8632.      return the sum of fibonacci(argument - 2) and fibonacci(argument -
  8633.      1)
  8634.  
  8635.    Note that a RETURN statement is not needed, since S-Expressions
  8636.    automatically set the return value of their containing macros.
  8637.  
  8638.    For comparison, here's how it would be coded without S-Expressions:
  8639.  
  8640.   define FIBONACCI {
  8641.       if == \%1 0 {
  8642.           return 0
  8643.       } else if == \%1 1 {
  8644.           return 1
  8645.       } else {
  8646.           return \feval(\fexec(fibonacci \feval(\%1-2)) -
  8647.                + \fexec(fibonacci \feval(\%1-1)))
  8648.       }
  8649.   }
  8650.  
  8651.    Now we can use the FIBONACCI function (whichever way you write it) just
  8652.    as if it were a built-in operator:
  8653.  
  8654.   (fibonacci 6)
  8655.  
  8656.    Or:
  8657.  
  8658.   (setq a 10)
  8659.   (fibonacci a)
  8660.  
  8661.    Within S-Expressions only (not outside them), S-Expressions themselves
  8662.    can be used as macro arguments:
  8663.  
  8664.   (setq a 2 b 4)
  8665.   (setq x (fibonacci (* a b )))
  8666.  
  8667.    The value of the S-Expression (in this case "8"), and not the
  8668.    S-Expression itself, is sent to the macro.
  8669.  
  8670.    Your macro is responsible for argument validation and error handling. A
  8671.    robust Fibonacci macro would be more like this:
  8672.  
  8673.   define FIBONACCI {
  8674.       if < \v(argc) 2 end 1 ?\%0: Missing argument
  8675.       if > \v(argc) 2 end 1 ?\%0: Too many arguments
  8676.       if not integer \%1 end 1 ?\%0: Integers only
  8677.       if < \%1 1 end 1 ?\%0: Argument out of range
  8678.       (if (== \%1 0) 0
  8679.          (if (== \%1 1) 1 (+ (fibonacci (- \%1 2)) (fibonacci (- \%1 1)))))
  8680.   }
  8681.  
  8682.    Recall that "END nonzero-number [ message ]" causes a macro invocation
  8683.    to fail. When the macro is the operator in an S-Expression, this makes
  8684.    the S-Expression fail too. Also note that our Fibonacci macro is just
  8685.    an illustration, not a practical example. Since it is recursive (calls
  8686.    itself), it won't work for large arguments because the call stack can
  8687.    exceed available memory. See [535]Section 9.9.2 for a practical
  8688.    alternative.
  8689.  
  8690.    Kermit macros, when used as S-Expression operators, can do anything at
  8691.    all except initiate file transfers: they can print messages on the
  8692.    screen, read and write files, interact with the user, and so on. For
  8693.    example, here's a macro ASKME that asks you to enter a number, makes
  8694.    sure that you did, and then returns its value for use in the
  8695.    S-Expression:
  8696.  
  8697.   define ASKME {
  8698.       local \%n
  8699.       while true {
  8700.           ask \%n { Number: }
  8701.           if not def \%n continue
  8702.           if not numeric \%n {
  8703.               echo Not numeric - "\%n"
  8704.               continue
  8705.           }
  8706.           break
  8707.       }
  8708.       return \%n
  8709.   }
  8710.   (setq a (* 2 (askme))) ; Get number from user, double it, assign result to a.
  8711.  
  8712.    Here's a macro you can use to validate that a number is in a given
  8713.    range:
  8714.  
  8715.   define inrange {
  8716.       if != \v(argc) 4 end 1 ?\%0: Wrong number of arguments
  8717.       if ( < \%1 \%2 || > \%1 \%3 ) return 0
  8718.       return 1
  8719.   }
  8720.  
  8721.    The first argument is the number to be checked, the second is the
  8722.    minimum acceptable value, the third is the maximum. You can use this
  8723.    (for example) in IF conditions:
  8724.  
  8725.   define yes echo \%1 IS OK
  8726.   define no echo \%1 IS NOT OK
  8727.  
  8728.   (setq a -1 b 999)
  8729.   (if (inrange a 0 100) (yes a) (no a))
  8730.   (if (inrange b -1000 +1000) (yes b) (no b))
  8731.  
  8732.    This is just an illustration, of course; there's already a built-in
  8733.    operator to let you do range checking without help from macros:
  8734.  
  8735.   (if (<= 0 a 100) (yes a) (no a))
  8736.   (if (<= -1000 b +1000) (yes b) (no b))
  8737.  
  8738.    To send string parameters to a macro, some kind of quoting is required
  8739.    to tell the S-Expression parser to take a given "word" literally rather
  8740.    than replacing it by its value. For this we use the Lisp QUOTE
  8741.    operator:
  8742.  
  8743.   define length return \flength(\%1)
  8744.   (length (quote abcdefghijklmnopqrstuvwxyz))
  8745.   26
  8746.  
  8747.    This causes the string "abcdefghijklmnopqrstuvwxyz" to be sent
  8748.    literally to the LENGTH macro. Kermit, like Lisp, also offers a
  8749.    shortcut for QUOTE, that lets us quote a word by prefixing it with a
  8750.    single quote (') character, also called apostrophe (ASCII 39):
  8751.  
  8752.   (length 'abcdefghijklmnopqrstuvwxyz)
  8753.   26
  8754.  
  8755.    The two forms are equivalent.
  8756.  
  8757.    How the macro treats its arguments is up to the macro. In the example
  8758.    above, the argument is treated as a literal string. However, it can
  8759.    also be treated as a variable name:
  8760.  
  8761.   define string This is a string
  8762.   define length return \flength(\m(\%1))
  8763.   (length 'string)
  8764.   16
  8765.  
  8766.    Note the construct \m(\%1). This means "the value of the macro whose
  8767.    name is the value of
  8768.    \%1". The value of \%1 in this case is the word "string", and the value
  8769.    of the macro whose name is "string" is "This is a string".
  8770.  
  8771.    What if the macro takes multiple arguments, or a variable number of
  8772.    them? Here's a simple macro that prints a phrase that includes its
  8773.    arguments:
  8774.  
  8775.   define complain echo It's too \%*!
  8776.  
  8777.    (Recall that \%* means "all arguments".)
  8778.  
  8779.    It can be called in the traditional way:
  8780.  
  8781.   complain hot                       Result: "It's too hot!"
  8782.   complain cold and wet              Result: "It's too cold and wet!"
  8783.  
  8784.    Or from an S-Expression if you quote the arguments:
  8785.  
  8786.   (complain 'hot)                    Result: "It's too hot!"
  8787.   (complain 'cold 'and 'wet)         Result: "It's too cold and wet!"
  8788.  
  8789.    To group multiple words into a single argument, use parentheses:
  8790.  
  8791.   (complain (quote (cold and wet)))  Result: "It's too cold and wet!"
  8792.   (complain '(cold and wet))         Result: "It's too cold and wet!"
  8793.  
  8794.    Note the difference:
  8795.  
  8796.   (complain 'cold 'and 'wet)         Three arguments
  8797.   (complain '(cold and wet))         One argument
  8798.  
  8799.    Since the COMPLAIN macro uses \%* to refer to all its arguments, no
  8800.    matter how many, it doesn't care which form you use. But it makes a
  8801.    difference in cases where the macro refers to its arguments
  8802.    individually.
  8803.  
  8804.    To illustrate, let's consider a macro that receives the name of a macro
  8805.    and its argument list and executes it with its arguments, without
  8806.    knowing how many arguments there are. The following LOOP macro is used
  8807.    to execute the given macro with the given argument list the requested
  8808.    number of times:
  8809.  
  8810.   def loop { local i, for i 1 \%1 1 do \%2 \%3 }
  8811.  
  8812.    Within the LOOP macro, the first argument (\%1) is the loop count, \%2
  8813.    is the macro name, and \%3 is the argument list. When the LOOP macro is
  8814.    invoked traditionally like this:
  8815.  
  8816.   loop 3 complain hot
  8817.  
  8818.    it prints "It's too hot!" three times. To invoke it from an
  8819.    S-Expression, you must quote both the macro name as well as the
  8820.    argument, since in this case the macro name itself is an argument:
  8821.  
  8822.   (loop 3 'complain 'hot)
  8823.  
  8824.    Now what if you need to send different or variable numbers of arguments
  8825.    to the LOOP macro? The LOOP macro can handle it already, provided you
  8826.    group the arguments into LOOP's third argument (\%3). In Kermit syntax,
  8827.    without grouping:
  8828.  
  8829.   loop 3 complain cold and wet
  8830.  
  8831.    prints "It's too cold!" three times ("and wet" is lost); but with
  8832.    grouping (either of the following two forms):
  8833.  
  8834.   loop 3 complain {cold and wet}
  8835.   loop 3 complain "cold and wet"
  8836.  
  8837.    the LOOP macro prints "It's too cold and wet!" three times as desired.
  8838.  
  8839.    To do the same thing in an S-Expression, just use the Lisp forms of
  8840.    quoting instead of the Kermit forms; the following two are equivalent:
  8841.  
  8842.   (loop 3 'complain (quote (cold and wet)))
  8843.   (loop 3 'complain '(cold and wet))
  8844.  
  8845.    Here's a similar example in which we write a macro that shows both the
  8846.    name and the value of one or more other macros, whose names are given
  8847.    as arguments (similar to "show macro"):
  8848.  
  8849.   define display {
  8850.       local \%i
  8851.       for \%i 1 \v(argc)-1 1 {
  8852.           echo \&_[\%i] = \m(\&_[\%i])
  8853.       }
  8854.   }
  8855.  
  8856.    (Recall that \&_[] is the macro's argument vector array, equivalent to
  8857.    \%1, \%2, ...) The DISPLAY macro can be used in S-Expressions like
  8858.    this:
  8859.  
  8860.   (setq a 1 b 2 c 3)
  8861.   (display 'a 'b 'c 'd)
  8862.  
  8863.    which prints:
  8864.  
  8865.   a = 1
  8866.   b = 2
  8867.   c = 3
  8868.   d =
  8869.  
  8870.    The names must be quoted to prevent their evaluation before they are
  8871.    sent to the macro. This ability to pass variables "by name" to macros,
  8872.    rather than by value, lets you write macros that change the values of
  8873.    argument variables. For example, here's a macro that doubles the value
  8874.    of its argument variable:
  8875.  
  8876.   define double (++ \%1 \%1)
  8877.  
  8878.    which you can call like this:
  8879.  
  8880.   (setq a 12)
  8881.   (double 'a)
  8882.  
  8883.    In the macro, \%1 is replace by the variable name "a"; "(++ a a)" adds
  8884.    "a" to itself, and sets the value of "a" to the result.
  8885.  
  8886.    There are no built-in operators other than QUOTE, ', and STRING for
  8887.    handling strings in S-Expressions, but using just these, plus macros
  8888.    that use Kermit's regular string-handling features, you can easily
  8889.    extend S-Expressions to do string manipulation:
  8890.  
  8891.   define len return \flen(\%1)               Returns length of argument string
  8892.   define cap return \fupper(\%1)             Uppercase argument string
  8893.   define rev return \freverse(\%1)           Reverses argument string
  8894.   define sub return \fsubstr(\%1,\%2,\%3)    Returns substring of arg string
  8895.  
  8896.   (len '(this is a string))                  Result: 16
  8897.   (rev '(this is a string))                  Result: gnirts a si siht
  8898.   (rev (cap '(this is a string)))            Result: GNIRTS A SI SIHT
  8899.   (sub (rev (cap '(this is a string))) 5 9)  Result: TS A SI S
  8900.  
  8901.    You can assign a string to a macro name as follows:
  8902.  
  8903.   (setq foo '(this is a string))
  8904.   (setq foo (quote (this is a string)))
  8905.  
  8906.    The two are exactly equivalent. In both cases, the macro "foo" has the
  8907.    value:
  8908.  
  8909.   '(this is a string)
  8910.  
  8911.    so when it is retrieved it can be identified as a string rather than a
  8912.    number or commands to be executed. Thus:
  8913.  
  8914.   (setq foo (quote (this is a string)))
  8915.   show macro foo
  8916.   foo = '(this is a string)
  8917.   (foo)
  8918.   this is a string
  8919.  
  8920.    Note the different results for "show macro foo" and "(foo)". The former
  8921.    shows the internal definition; the latter evaluates the variable, which
  8922.    removes the quoting. And perhaps more important, note that if the
  8923.    apostrophe and surrounding parentheses were not stored as part of the
  8924.    definition, (foo) would try to execute "this is a string" as a command.
  8925.  
  8926.    Given the assignment above, the following work as expected:
  8927.  
  8928.   (len foo)                                  Result: 16
  8929.   (rev foo)                                  Result: gnirts a si siht
  8930.   (rev (cap foo))                            Result: GNIRTS A SI SIHT
  8931.   (sub (rev (cap foo)) 5 8)                  Result: TS A SI S
  8932.  
  8933.    Note that, unlike built-in S-Expression operators that return numbers
  8934.    or truth values, these operators return strings. If you want to assign
  8935.    their return values to other variables, you can do so:
  8936.  
  8937.   (setq bar (rev (cap foo)))                 Result: GNIRTS A SI SIHT
  8938.  
  8939.    But now the S-Expression processor doesn't know the value of "bar" is
  8940.    supposed to be a string, rather than a macro to execute. For this you
  8941.    need one final special operator, STRING. The STRING operator takes an
  8942.    S-Expression as an operand, evaluates it, and then returns its value
  8943.    enclosed in '(), so you can use the value as a string is subsequent
  8944.    S-Expressions. Use STRING for referencing macros that return strings:
  8945.  
  8946.   (setq bar (string (rev (cap foo))))        Result: '(GNIRTS A SI SIHT)
  8947.  
  8948.    STRING is like QUOTE, except that it evaluates its operand before
  8949.    applying the quoting, rather than taking the operand literally.
  8950.  
  8951.    To reference backslash variables or functions that return string
  8952.    values, you must use the regular quoting mechanisms:
  8953.  
  8954.   (setq time '(\v(time)))
  8955.   (setq date '(\v(date)))
  8956.   assign \%r this is a string
  8957.   (setq s1 '(\%r))
  8958.  
  8959.    That's because backslash items are evaluated BEFORE the S-Expression
  8960.    parser ever sees them, and the values of \v(time) and so on are not
  8961.    valid S-Expressions, so STRING won't like them.
  8962.  
  8963.    Finally a brief word on the touchy topic of quoting. Suppose you want
  8964.    to include (say) literal parentheses in a string that will later be
  8965.    processed by the S-Expression reader (or \fsplit() or \fword()).
  8966.    Normally, you can't do this because parentheses are meaningful in these
  8967.    contexts. To defeat the normal parsing rules, you can quote the
  8968.    parentheses with backslash. However, due to the many levels of string
  8969.    processing involved, a surprisingly large amount of backslashes might
  8970.    be required, for example:
  8971.  
  8972.   (setq s '(a b (c d) \\\\\\\\\\\\\\\\(e f (g h) x\\\\\\\\\\\\\\\\) j k))
  8973.  
  8974.    This is nearly impossible to explain(*). Instead, just remember two
  8975.    points:
  8976.  
  8977.      * In situations like this, it's better to use DEFINE to create the
  8978.        string, rather than SETQ. The example above requires only double
  8979.        backslashes when DEFINE is used:
  8980.   define s '(a b (c d) \\(e f (g h) x\\) j k)
  8981.  
  8982.      * The level of quoting depends on how many levels of evaluation the
  8983.        string must pass through, which is not always obvious. However, the
  8984.        number of backslashes required in any given situation is always a
  8985.        power of 2. So if 1 doesn't work, try 2; if 2 doesn't work, try 4;
  8986.        if 4 doesn't work, try 8, 16, 32, and so on.
  8987.  
  8988.    Considerations like this apply in any scripting language (shell, Tcl,
  8989.    Perl, Python, etc). The situation is known as "Quoting Hell".
  8990.  
  8991.    (*) If you really want an explanation, here it is:
  8992.  
  8993.      * Every SEXP has its backslash items evaluated in a single pass at
  8994.        top level before being passed to the SEXP reader, so \%1,
  8995.        \v(ftime), etc, can be evaluated up front, freeing the SEXP reader
  8996.        of having to know about such things, which in turn makes it much
  8997.        more efficient. Therefore one level of quoting is lost right away,
  8998.        and therefore you must double each backslash that is to be used as
  8999.        a quote.
  9000.      * When the SEXP reader sees '\', it treats it as a quote; discards it
  9001.        and keeps the next character. Thus '\\' becomes '\'. This would be
  9002.        the end of it, except that:
  9003.      * The SEXP reader must call itself recursively on its operands, so we
  9004.        must double any quotes in the operands: 2^2 = 4.
  9005.      * If the result is to be passed as an argument to a macro, the
  9006.        backslashes must again be doubled, because the macro processor
  9007.        evaluates the arguments before sending them to the macro: 2^3 = 8.
  9008.      * If the macro itself is to see the quotes, rather than just the
  9009.        result of the quoting, the quotes must be doubled again: 2^4 = 16.
  9010.  
  9011.    Moral: To create string constants in which grouping characters must be
  9012.    quoted, use DEFINE rather than SETQ.
  9013.  
  9014.    [ [536]Top ] [ [537]Contents ] [ [538]C-Kermit Home ] [ [539]Kermit
  9015.    Home ]
  9016.  
  9017. 9.9. Examples
  9018.  
  9019. 9.9.1. Statistics
  9020.  
  9021.    The following program computes statistics -- means, maxima, minima,
  9022.    variance, standard deviation, and correlation -- from data stored in
  9023.    parallel arrays, \&x[] and \&y[], which can contain any mixture of
  9024.    integer and floating-point numbers: positive, negative, or zero. Array
  9025.    setup and validation are not shown. Except for the traditional FOR loop
  9026.    and printing the results at the end, the entire computation is done
  9027.    with S-Expressions:
  9028.  
  9029. ; Initialize sums, maxima, minima, and number of elements
  9030.  
  9031.   (setq xsum 0 ysum 0 xsum2 0 ysum2 0 xysum 0)
  9032.   (setq xmin (setq xmax \&x[1]) ymin (setq ymax \&y[1]))
  9033.   (setq n \fdim(&x))
  9034.  
  9035. ; Loop through elements and accumulate sums, maxima, and minima
  9036.  
  9037.   for i 1 n 1 {
  9038.       (setq x \&x[i] y \&y[i])                    ; Notational convenience
  9039.       (setq xmax (max xmax x) ymax (max ymax y))  ; X and Y maxima
  9040.       (setq xmin (min xmin x) ymin (min ymin y))  ; X and Y minima
  9041.       (++ xsum x ysum y)                          ; X and Y sums
  9042.       (++ xsum2 (^ x 2) ysum2 (^ y 2))            ; Sum of X and Y squares
  9043.       (++ xysum (* x y))                          ; Sum of XY products
  9044.   }
  9045.  
  9046. ; Calculate results
  9047.  
  9048.   (setq xmean (/ xsum n) ymean (/ ysum n))        ; Mean X and Y
  9049.   (setq xss (- xsum2 (/ (^ xsum 2) n)))           ; Intermediate values
  9050.   (setq yss (- ysum2 (/ (^ ysum 2) n)))
  9051.   (setq xyss (- xysum (/ (* xsum ysum) n)))
  9052.   (setq xvar (/ xss n) yvar (/ yss n))            ; X and Y variance
  9053.   (setq sdx (sqrt xvar) sdy (sqrt yvar))          ; Std deviation in X and Y
  9054.   (setq tmp (* xss yss))
  9055.   (setq cc (if tmp (/ xyss (sqrt tmp)) 1.0))      ; Correlation coefficient
  9056.   show macro xmean ymean xvar yvar sdx sdy cc     ; Print the results
  9057.  
  9058.    The final "if tmp" check accounts for the possibility that both arrays
  9059.    contain all 0's. Results can also be printed with "echo CC = \m(cc)",
  9060.    or any other desired way. Interestingly, if we had not needed the sum
  9061.    of the squares and products, we could have obtained the sums, maxima,
  9062.    and minima of the X's and Y's without a loop like this:
  9063.  
  9064.   (setq xsum (+ \fjoin(&x)) ysum (+ \fjoin(&y)))
  9065.   (setq xmax (max \fjoin(&x)) ymax (max \fjoin(&y)))
  9066.   (setq xmin (min \fjoin(&x)) ymin (min \fjoin(&y)))
  9067.  
  9068.    Any Kermit function that returns numbers or lists of numbers can be
  9069.    included in an S-Expression as an operand.
  9070.  
  9071. 9.9.2. Practical Fibonacci Series
  9072.  
  9073.    The recursive Fibonacci example given previously is simple and elegant,
  9074.    but not very useful since it causes memory occupation to grow each time
  9075.    it calls itself, until eventually both physical memory and disk swap
  9076.    space are filled and the program crashes. Even for small arguments,
  9077.    like 17, execution time can be prohibitive:
  9078.  
  9079.   (setq t1 \v(ftime))
  9080.   (setq result (fibonacci 17))
  9081.   (setq t2 (- \v(ftime) t1))
  9082.   echo FIBONACCI(17) = \m(result): TIME = \ffpround(t2,3)
  9083.  
  9084.    prints (on a certain rather slow computer):
  9085.  
  9086.   FIBONACCI(17) = 1597: TIME = 5.861
  9087.  
  9088.    Any recursive function can be recoded iteratively. The result is not as
  9089.    pretty, but execution is far less expensive:
  9090.  
  9091.     define FIBITER {
  9092.         (if (== \%3 0) (\%2) (fibiter (+ \%1 \%2) \%1 (- \%3 1)))
  9093.     }
  9094.     define FIBONACCI {
  9095.         (fibiter 1 0 \%1)
  9096.     }
  9097.  
  9098.    Here's the result on the same computer for the same argument of 17:
  9099.  
  9100.   FIBONACCI(17) = 1597: TIME = 0.015
  9101.  
  9102.    (47 times faster.) Execution time increases proportionally to the size
  9103.    of the argument in the iterative case, whereas in the recursive case it
  9104.    goes up geometrically, quickly reaching infinity.
  9105.  
  9106.    [ [540]Top ] [ [541]Contents ] [ [542]C-Kermit Home ] [ [543]Kermit
  9107.    Home ]
  9108.  
  9109. 9.10. Differences from Algebraic Notation
  9110.  
  9111.    In C-Kermit:
  9112.  
  9113.      * Algebraic notation uses infix operators and normal rules of
  9114.        operator precedence, with parentheses used to force exceptions to
  9115.        the rules; many operations can be included in an expression.
  9116.        S-Expressions use prefix operators with no intrinsic precedence;
  9117.        each operation is enclosed in parentheses, and the arrangement of
  9118.        parentheses determines precedence.
  9119.      * Algebraic infix operators require two operands; S-Expression prefix
  9120.        operators can accept a variable number of operands.
  9121.      * You can use algebraic notation anywhere that C-Kermit accepts a
  9122.        number, e.g. "echo \&a[((1+1)*2-1]", but you can use S-Expressions
  9123.        only as top-level commands. You can, however, use either algebraic
  9124.        or S-Expressions anywhere at all by enclosing them in \fevaluate()
  9125.        or \fsexpression(), respectively.
  9126.      * You can use any mixture of integer and floating-point numbers in
  9127.        S-Expressions, but only integers are permitted in algebraic
  9128.        expressions. Outside of S-Expressions, floating point arithmetic is
  9129.        supported only by \ffp...() function calls.
  9130.      * Operators and operands in S-Expressions must be separated by
  9131.        spaces, e.g. "(+ a b)". Spaces are not required in algebraic
  9132.        expressions: "((a+b)*c)".
  9133.      * When assigning values to backslash variables (such as \%x or
  9134.        \&a[2]) using SETQ or LET, you must double the backslash.
  9135.  
  9136.    [ [544]Top ] [ [545]Contents ] [ [546]C-Kermit Home ] [ [547]Kermit
  9137.    Home ]
  9138.  
  9139. 9.11. Differences from Lisp
  9140.  
  9141.      * Kermit has a lot of built-in operators not found in Lisp: ++, ^,
  9142.        etc.
  9143.      * Most dialects of real Lisp do not allow S-Expressions that don't
  9144.        start with an operator, for example:
  9145.   (a)
  9146.  
  9147.        This expression can cause an error in Lisp (even if "a" has a
  9148.        value), but is acceptable in Kermit, where it returns the value of
  9149.        the variable "a". Similarly, (1) returns the value "1".
  9150.      * In real Lisp, EVAL requires exactly one operand. In Kermit, it can
  9151.        have 0, 1, 2, or more operands. It returns the value of the last
  9152.        operand evaluated.
  9153.      * Real Lisp SETQ and LET usually require an even number of operands.
  9154.        Kermit allows an odd number, in which case the last (or only)
  9155.        variable is undefined (i.e. deleted, destroyed).
  9156.      * Kermit does not support ratios such as "7/8". Some Lisp dialects
  9157.        accept ratios as numbers, and generate ratios when told to divide
  9158.        two integers whose quotient is not a whole number; e.g. in Common
  9159.        Lisp:
  9160.   [13] USER(37): (/ (+ 1 2 3 4) 3)
  9161.   10/3
  9162.   [13] USER(38):
  9163.  
  9164.      * The result of (/ 10 3) is 3.333.... Some Lisp dialects truncate the
  9165.        result to 3 since both operands are integers, some don't; some give
  9166.        the result as a ratio. C-Kermit always gives a floating point
  9167.        result when there is a fractional part. If you want an integer
  9168.        result, you can use TRUNCATE, FLOOR, or CEILING, e.g. (truncate (/
  9169.        10 3)).
  9170.      * There is currently no "bignum" support. Large numbers can be used
  9171.        and large results generated, but (as noted in [548]Section 9.2)
  9172.        they are accurate only to the precision of the underlying machine.
  9173.        \v(math_precision) gives the machine precision as a number of
  9174.        decimal digits, e.g. 16.
  9175.      * Scientific notation for floating-point numbers is not supported. If
  9176.        the magnitude of a number is greater than the precision of the
  9177.        underlying hardware, the less-significant digits are shown but
  9178.        their values are meaningless. If it the number is too small to be
  9179.        represented internally, it is shown as "0.0".
  9180.      * Many Lisp features are omitted: List processing (CAR, CDR, etc),
  9181.        DEFUN, Lisp-specific control structures, and so on.
  9182.  
  9183.    [ [549]Top ] [ [550]Contents ] [ [551]C-Kermit Home ] [ [552]Kermit
  9184.    Home ]
  9185.  
  9186. 10. FILE TRANSFER
  9187.  
  9188.    New commands and switches:
  9189.  
  9190.    SET TRANSFER REPORT { OFF, ON }
  9191.           Enables or disables the (new) one-line message printed by Kermit
  9192.           after a remote-mode file transfer to indicate the source and
  9193.           destination file, complete with path, to let you know where the
  9194.           file went.
  9195.  
  9196.    SEND /TYPE:{TEXT,BINARY}
  9197.           Sends only files of the given type (see [553]Section 4).
  9198.  
  9199.    SEND /NOFOLLOWLINKS:
  9200.           (UNIX only) Skip over symbolic links rather than following them
  9201.           (default). This applies to wildcard and/or recursive SENDs; if a
  9202.           single filename is given, and it happens to be a symbolic link,
  9203.           the file it points to is sent.
  9204.  
  9205.    SEND /FOLLOWLINKS:
  9206.           (UNIX only) Follow (resolve) symbolic links. Watch out for
  9207.           circular links, endless loops, etc.
  9208.  
  9209.    SET SEND I-PACKETS { OFF, ON }
  9210.           When sending commands to a Kermit server, this tells whether
  9211.           command packets should be preceded by an I (information) packet,
  9212.           which is used to synchronize parameters prior to executing the
  9213.           command. Normally ON. The only reason to set this OFF is for
  9214.           communicating with buggy Kermit servers that misbehave when an I
  9215.           packet is sent to them. There is also a SET RECEIVE I-PACKETS
  9216.           command, but presently it has no effect.
  9217.  
  9218.    SET TRANSFER MESSAGE [ text ]
  9219.           Sets an initial message to be shown in the Last Message field of
  9220.           the fullscreen file-transfer display.
  9221.  
  9222.    SET TRANSFER TRANSLATION { ON, OFF }
  9223.           Inhibits or re-enables text-file transfer character-set
  9224.           translation globally.
  9225.  
  9226.    { SEND, MSEND, GET, RECEIVE } /TRANSPARENT
  9227.           Inhibits character-set translation for this transfer only.
  9228.  
  9229.    { GET, RECEIVE } /PIPES:{ON,OFF}
  9230.           Overrides global TRANSFER PIPES setting for this transfer only;
  9231.           ON allows incoming files with names like "!tar xf -" to be
  9232.           opened as pipelines rather than regular files.
  9233.  
  9234.    The following new "hot keys" are available when Kermit's file-transfer
  9235.    display is visible:
  9236.  
  9237.      D: Turn on debugging, open "debug.log" if not already open.
  9238.      d: Turn off debugging but leave log open (if it was open).
  9239.      T: Turn on debug-log timestamps.
  9240.      t: Turn off debug-log timestamps.
  9241.  
  9242.    Other improvements:
  9243.      * SET FILE DOWNLOAD-DIRECTORY now works for external protocols (e.g.
  9244.        sz/rz) too.
  9245.      * Improved automatic per-file text/binary switching, described in
  9246.        [554]Section 4.
  9247.      * When sending a file group (e.g. "send *.*"), failure to open a file
  9248.        is no longer fatal; now C-Kermit simply goes ahead to the next
  9249.        file.
  9250.      * Transaction log entries are now made for external protocols too.
  9251.  
  9252.    [ [555]Top ] [ [556]Contents ] [ [557]C-Kermit Home ] [ [558]Kermit
  9253.    Home ]
  9254.  
  9255. 11. MODEMS AND DIALING
  9256.  
  9257.    In C-Kermit 8.0, the default modem type for dialing has changed from
  9258.    NONE (= DIRECT, meaning no modem) to GENERIC. This change should have
  9259.    no impact on direct connections. For dialing, it means that, unless you
  9260.    SET MODEM TYPE to a specific type, such as USROBOTICS or CONEXANT,
  9261.    Kermit assumes:
  9262.  
  9263.     1. The modem uses the Hayes AT command set.
  9264.     2. The modem supports error correction, data compression, and hardware
  9265.        flow control and is already configured to use them.
  9266.  
  9267.    In fact, Kermit assumes the modem is completely configured, and
  9268.    therefore does not send it an initialization string or any
  9269.    configuration commands. Instead, it sends only the simplest and most
  9270.    portable commands:
  9271.  
  9272.      ATQ0V1          Give dial result codes.
  9273.      ATDTnumber      Dial the number.
  9274.  
  9275.    (or ATD or ATDP, as appropriate).
  9276.  
  9277.    The new defaults work for direct connections and for most modern modems
  9278.    on most platforms, and they work much faster than "full-treatment"
  9279.    dialing. If the new defaults don't work for you, or if you need to
  9280.    perform explicit modem configurations or interactions, then set a
  9281.    specific modem type and use the SET MODEM and SET DIAL commands as
  9282.    documented in Using C-Kermit.
  9283.  
  9284.      WARNING: Don't use the generic modem on hosts that do not support
  9285.      RTS/CTS flow control. If Xon/Xoff is in use on the serial port,
  9286.      you'll need to select a particular modem type so Kermit knows what
  9287.      command to give it to enable Xon/Xoff flow control between itself
  9288.      and your serial port.
  9289.  
  9290.    The following new modem types were added in C-Kermit 8.0:
  9291.  
  9292.      lucent:          Lucent Venus chipset
  9293.      pctel:           PCTel V.90 chipset
  9294.      conexant:        Conexant (ex-Rockwell) modem family
  9295.      zoom-v32bis:     New name for "Zoom"
  9296.      zoom-v34         Zoom V.34
  9297.      zoom-v90         Zoom V.90 56K
  9298.      zoom-v92:        Zoom V.92 with V.44 data compression
  9299.      zoltrix-v34:     New name for "zoltrix"
  9300.      zoltrix-hsp-v90: Synonym for PCTel
  9301.      zoltrix-hcf-v90: Synonym for ITU-T-V250
  9302.      smartlink-v90:   Synonym for usrobotics (same chipset)
  9303.      acer-v90:        Synonym for Rockwell-v90
  9304.  
  9305.    New DIAL-related variables:
  9306.  
  9307.      \v(dm_hf):  Dial modifier: Wait for Hook-Flash.
  9308.      \v(dm_wb):  Dial modifier: Wait for Bong.
  9309.  
  9310.    Finally, if dialing fails, Kermit now prints a context-sensitive hint
  9311.    suggesting possible reasons and remedies.
  9312.  
  9313.    Added in C-Kermit 8.0.201:   Rudimentary support for Caller ID, for use
  9314.    with the ANSWER command. If the modem reports Caller ID information,
  9315.    Kermit stores it in variables that you can access after the call is
  9316.    answered:
  9317.  
  9318.   \v(callid_date)   The date of the call
  9319.   \v(callid_time)   The time of the call
  9320.   \v(callid_name)   The name of the caller
  9321.   \v(callid_nmbr)   The telephone number of the caller
  9322.   \v(callid_mesg)   A message
  9323.  
  9324.    The format of these items depends on the originating and answering
  9325.    phone companies and the modems and their configuration.
  9326.  
  9327.    Not very many modems support Caller ID, and those that do (a) tend to
  9328.    have it disabled by default, and (b) use different commands to enable
  9329.    it. A quick survey shows of some current models shows:
  9330.  
  9331.    - USR V.90:      No
  9332.    - ITU-T V.250:   No
  9333.    - Lucent Venus:  No
  9334.    - Diamond Supra: #CID=1
  9335.    - Rockwell 56K:  #CID=1
  9336.    - PCTEL:         #CID=1
  9337.    - Zoltrix:       +VCID=1
  9338.    - Conexant:      +VCID=1
  9339.  
  9340.    To use Kermit's Caller ID feature, you have to set the modem to wait
  9341.    for at least two rings before answering, and you have to give the
  9342.    command to enable Caller ID; for example (after choosing a modem with
  9343.    SET MODEM TYPE):
  9344.  
  9345.   set modem command autoanswer on ATS0=2#CID=1\{13}
  9346.   set modem command autoanswer on ATS0=2+VCID=1\{13}
  9347.  
  9348.    These commands can be undone with:
  9349.  
  9350.   set modem command autoanswer on ATS0=1#CID=0\{13}
  9351.   set modem command autoanswer on ATS0=1+VCID=0\{13}
  9352.  
  9353.    Kermit presently has no built-in knowledge of the Caller ID
  9354.    capabilities or commands of the modems in its database.
  9355.  
  9356.    Since the variables can be accessed only after the call is answered,
  9357.    the only way to refuse a call is to answer it, inspect the variables,
  9358.    and then hang it up if desired.
  9359.  
  9360.    [ [559]Top ] [ [560]Contents ] [ [561]C-Kermit Home ] [ [562]Kermit
  9361.    Home ]
  9362.  
  9363. 12. TERMINAL CONNECTION
  9364.  
  9365.    Now that 7-bit connections are no longer the norm, the default terminal
  9366.    bytesize (also called "data size" or "word size") in C-Kermit 8.0 is 8
  9367.    bits, rather than 7 bits as it was in C-Kermit 7.0 and earlier:
  9368.  
  9369.    SET ESCAPE character
  9370.           This command, which specifies your CONNECT-mode escape
  9371.           character, allows you to specify any ASCII control character in
  9372.           a variety of formats. C-Kermit 8.0.201 now also lets you specify
  9373.           any 8-bit value, 128-255, as the escape character. In the SET
  9374.           ESCAPE command, you can type the 8-bit character literally or
  9375.           you can enter its numeric code. Here are examples that you can
  9376.           enter from a terminal or console that uses the ISO Latin-1
  9377.           character set:
  9378.  
  9379.   C-Kermit> set escape ├
  9380.   C-Kermit> set escape 195
  9381.   C-Kermit> show escape
  9382.    Escape character: Code 195 (├): enabled
  9383.   C-Kermit>
  9384.  
  9385.           Both of these commands set the escape character value to 195
  9386.           (decimal), which happens to be uppercase letter A with Tilde in
  9387.           Latin-1. SHOW ESCAPE and SHOW TERMINAL show the value, as does
  9388.           the CONNECT message.
  9389.  
  9390.    SET TERMINAL AUTODOWNLOAD ERROR { STOP, CONTINUE }
  9391.           When Kermit has a terminal connection to another computer, and a
  9392.           file transfer is initiated automatically because a Kermit packet
  9393.           was received in CONNECT mode (i.e. in the terminal screen), this
  9394.           command tells what Kermit should do if the transfer fails. The
  9395.           default is to STOP, which leaves Kermit in command mode with its
  9396.           file-transfer display showing, so you can see that the transfer
  9397.           failed and why. If you SET TERMINAL AUTODOWNLOAD ERROR CONTINUE,
  9398.           this causes Kermit to return automatically to its terminal
  9399.           screen (i.e. resume its CONNECT session) as if the transfer had
  9400.           succeeded; this can be desirable if the entire session is under
  9401.           control of a host-based script.
  9402.  
  9403.    SET TERMINAL BYTESIZE { 7, 8 }
  9404.           The byte size to use during CONNECT and INPUT command execution,
  9405.           which can be more restrictive than the bytesize implied by the
  9406.           current PARITY setting, but not less restrictive. In C-Kermit
  9407.           7.0 and earlier, the terminal bytesize was 7 by default to
  9408.           protect against the likelihood that parity was in use on the
  9409.           connection without the user's knowledge. When the terminal
  9410.           bytesize is 8 (as it is in C-Kermit 8.0 and later), the user
  9411.           will see garbage in this (increasingly unlikely) situation. Note
  9412.           that 8 data bits are required for most character sets other than
  9413.           ASCII: Latin-1, UTF-8, and so on.
  9414.  
  9415.    A new command has been added to produce timestamped session logs:
  9416.  
  9417.    SET TERMINAL SESSION-LOG TIMESTAMPED-TEXT
  9418.           Records the terminal session in text mode (like SET TERMINAL
  9419.           SESSION-LOG TEXT) but adds a timestamp at the beginning of each
  9420.           line. The timestamp format is hh:mm:ss.nnn, and indicates the
  9421.           time at which the first character of the line appeared.
  9422.  
  9423.    In most UNIX versions (those built with the select()-capable CONNECT
  9424.    module -- pretty much all the ones that have or could have TELNET
  9425.    included), an idle timeout feature has been added:
  9426.  
  9427.    SET TERMINAL IDLE-TIMEOUT number
  9428.           If the number is not 0, then Kermit is to take an action when
  9429.           the given amount of time passes with no activity during CONNECT
  9430.           mode. If the number is positive it is the maximum number of idle
  9431.           seconds; if number is negative it represents milliseconds
  9432.           (thousandths of seconds). If 0 is given as the number, there are
  9433.           no idle timeouts. Synonym: SET TERMINAL IDLE-LIMIT.
  9434.  
  9435.    SET TERMINAL IDLE-ACTION { RETURN, HANGUP, EXIT, OUTPUT [ string ] }
  9436.           The action to be taken upon an idle timeout in CONNECT mode.
  9437.           RETURN to the prompt, HANGUP the connection, EXIT from Kermit,
  9438.           or OUTPUT the given string (if no string is given, a NUL (ASCII
  9439.           0) character is sent).
  9440.  
  9441.    SET TERMINAL IDLE-ACTION { TELNET-NOP, TELNET-AYT }
  9442.           Actions that can be selected on Telnet connections only, that
  9443.           might be useful if idle limits are enforced by the Telnet server
  9444.           or in the TCP/IP protocol: TELNET-NOP sends a "NO Operation"
  9445.           (do-nothing) command, which causes no response from the server;
  9446.           TELNET-AYT sends an "Are You There" message to the server, which
  9447.           should make the server send back a message. Neither of these
  9448.           actions interferes with your remote session.
  9449.  
  9450.    SET TERMINAL IDLE-ACTION is useful for connections to hosts or services
  9451.    that automatically log you out after a certain amount of idle time,
  9452.    e.g.:
  9453.  
  9454.   set term idle-timeout 300
  9455.   set term idle-action output \32
  9456.  
  9457.    sends a space (as if you had pressed the space bar) every 300 seconds
  9458.    (five minutes) while there is no activity (32 is the ASCII code for
  9459.    space).
  9460.  
  9461.    When C-Kermit returns from CONNECT to command mode, the reason for the
  9462.    transition is given in a new variable, \v(cx_status):
  9463.  
  9464.       0  No CONNECT command given yet.
  9465.       1  User escaped back manually.
  9466.       2  A trigger string was encountered.
  9467.       3  IKSD entered server mode.
  9468.       4  Application Program Command received from host.
  9469.       5  Idle timeout.
  9470.       6  Telnet protocol error.
  9471.       7  Keystroke macro.
  9472.       8  Time limit exceeded.
  9473.     100  Internal error.
  9474.     101  Carrier required by not detected.
  9475.     102  I/O error on connection.
  9476.     103  Disconnected by host.
  9477.     104  Disconnected by user.
  9478.     105  Session limit exceeded.
  9479.     106  Rejected due to Telnet policy.
  9480.     107  Received kill signal.
  9481.  
  9482.    Values 100 and above indicate there is no connection.
  9483.  
  9484.    [ [563]Top ] [ [564]Contents ] [ [565]C-Kermit Home ] [ [566]Kermit
  9485.    Home ]
  9486.  
  9487. 13. CHARACTER SETS
  9488.  
  9489.    See the section on [567]file scanning above, and the section on
  9490.    character-set conversion in [568]FTP. Also:
  9491.  
  9492.      * True support for CP1252 (rather than treating it as Latin-1).
  9493.      * Proper handling of C1 values when converting ISO 8-bit text to
  9494.        UTF-8.
  9495.      * TYPE /CHARACTER-SET: /TRANSLATE-TO: allows specific translations.
  9496.      * The TRANSLATE command now works on multiple files.
  9497.      * K_CHARSET environment variable to set the file character-set.
  9498.      * SET TRANSFER TRANSLATION OFF.
  9499.      * FTP client character-set translation ([569]Section 3.7).
  9500.  
  9501.    [ [570]Top ] [ [571]Contents ] [ [572]C-Kermit Home ] [ [573]Kermit
  9502.    Home ]
  9503.  
  9504. 14. DIALOUT FROM TELNET TERMINAL SERVERS
  9505.  
  9506.    For years, C-Kermit has supported dialing out from Telnet modem servers
  9507.    (also called reverse terminal servers or access servers), but until now
  9508.    there was no way for Kermit to control the communication parameters
  9509.    (speed, parity, etc) on the serial port of the terminal server; it had
  9510.    to use whatever was there.
  9511.  
  9512.    But now, if you make a connection to a server that supports the Telnet
  9513.    Com Port Control Option, [574]RFC 2217, you have the same degree of
  9514.    control as you would have over a serial port on the computer where
  9515.    Kermit is running: SET SPEED, SET FLOW, SET PARITY, SET STOP-BITS, SHOW
  9516.    COMM, WAIT, SET CARRIER-WATCH, the modem-signal variables, sending
  9517.    Break, and so on, apply to the connection between the terminal server
  9518.    and the modem.
  9519.  
  9520.    For example, using a Cisco Access Server 2509, where specifying a TCP
  9521.    port in the 6000's selects a serial port that can be used for dialing
  9522.    out:
  9523.  
  9524.   set host xxx 6001      ; xxx is the IP hostname or address of the server
  9525.   (log in if necessary)  ; With a script or by hand
  9526.   set modem type usr     ; Tell Kermit what kind of modem it has
  9527.   set speed 57600        ; This affects the server's port
  9528.   set flow rts/cts       ; Ditto
  9529.   dial 7654321
  9530.  
  9531.    The modem server might or might not require a login sequence. It might
  9532.    also allow for automatic authentication, e.g. via Kerberos tickets.
  9533.    NOTE: If the modem server requires a login sequence, then REDIAL might
  9534.    not work as expected.
  9535.  
  9536.    When you have a Telnet Com Port connection, your SET SPEED and SET FLOW
  9537.    options change automatically to reflect the capabilities of the server,
  9538.    rather than those of your local computer.
  9539.  
  9540.    See the configuration manual for your server for additional
  9541.    information. For example, how to set up the server to drop the Telnet
  9542.    connection automatically when the telephone call is hung up (e.g.
  9543.    "autohangup" on Cisco models).
  9544.  
  9545.    For a Linux-based Telnet Com-Port server, click the Sredird link:
  9546.  
  9547.    [ [575]Top ] [ [576]Contents ] [ [577]Sredird ] [ [578]C-Kermit Home ]
  9548.    [ [579]Kermit Home ]
  9549.  
  9550. 15. COPING WITH BROKEN KERMIT PARTNERS
  9551.  
  9552.    There are lots of faulty Kermit protocol implementations out there,
  9553.    found mainly in 3rd-party products ranging from communications software
  9554.    packages to file-transfer functions embedded within devices. This topic
  9555.    is covered [580]HERE for C-Kermit 7.0, but C-Kermit 8.0 adds some
  9556.    additional tricks.
  9557.  
  9558.    SET ATTRIBUTE RECORD-FORMAT { ON, OFF }
  9559.           Allows control of the Kermit's Record-Format attribute. Set this
  9560.           to OFF in case incoming file are refused due to unknown or
  9561.           invalid record formats if you want to accept the file anyway.
  9562.  
  9563.    SET ATTRIBUTES OFF
  9564.           This is not a new trick, but it was recently discovered that the
  9565.           Kermit implementation embedded within a certain kind of
  9566.           punching/bending machine (Salvagnini if you must know) hangs
  9567.           upon reception of standard format Kermit attributes when
  9568.           receiving files. When sending files, it sends attributes of its
  9569.           own, one per A-packet, which is slightly unusual but legal. When
  9570.           receiving files from C-Kermit, K95, MS-DOS Kermit, Kermit-370,
  9571.           etc, it simply exits upon reception of the first A-packet;
  9572.           apparently it was not coded according to the protocol
  9573.           specification, which allows multiple attributes per A-packet.
  9574.           Solution: tell the file sender to SET ATTRIBUTES OFF.
  9575.  
  9576.    SET SEND I-PACKETS { ON, OFF }
  9577.           A Kermit server is supposed to accept I-packets; this is how the
  9578.           client lets the server know its capabilities and preferences
  9579.           before sending a command. Apparently there is at least one
  9580.           Kermit server implementation that does not accept I-packets, and
  9581.           does not properly respond with an Error packet if it gets one.
  9582.           To get around such situations in C-Kermit 8.0, you can use SET
  9583.           SEND I-PACKETS OFF to inhibit the sending of I packets. In this
  9584.           case, the client must be able to adjust to the server's
  9585.           configuration, rather than the other way around as we are used
  9586.           to.
  9587.  
  9588.    SET PROTOCOL KERMIT {} {} {}
  9589.           C-Kermit 6.0 and later automatically send "autoupload" and
  9590.           "autodownload" commands when in local mode and you give a file
  9591.           transfer command. For example, if you tell kermit to "send
  9592.           oofa.txt", Kermit sends "kermit -r" and a carriage return, in
  9593.           case you had forgotten to start Kermit on the far end and told
  9594.           it to receive a file. If a Kermit program had already been
  9595.           started on the far end, it should harmlessly absorb this string.
  9596.           However, some Kermit programs violate the Kermit protocol
  9597.           definition and treat such strings as Kermit packets even though
  9598.           they are not. In such cases, give this command to set the Kermit
  9599.           protocol autoupload and download strings to nothing, which tells
  9600.           Kermit not to send them. (This is not a new feature, but it was
  9601.           not previously included in the "Coping" section of the
  9602.           documentation.)
  9603.  
  9604.    [ [581]Top ] [ [582]Contents ] [ [583]C-Kermit Home ] [ [584]Kermit
  9605.    Home ]
  9606.  
  9607. 16. NEW COMMAND-LINE OPTIONS
  9608.  
  9609.    kermit -h Now prints a complete listing of its command-line options,
  9610.    rather than an abbreviated list squeezed into a 24x80 space.
  9611.  
  9612.    -dd              Debug, like -d but adds timestamps
  9613.    --version  Shows C-Kermit version number.
  9614.    --noperms  Equivalent to SET ATTRIBUTE PROTECTION OFF.
  9615.  
  9616.    Kermit now accepts a selection of URLs (Universal Resource Locators) as
  9617.    its first command-line argument. These are:
  9618.  
  9619.    telnet:hostname
  9620.           Makes a Telnet connection to the given host (IP hostname or
  9621.           address).
  9622.  
  9623.    ftp://[user[:password]@]hostname[/path...]
  9624.           Makes an FTP connection to the given host (IP hostname or
  9625.           address). If a username is given, Kermit tries to log you in; if
  9626.           a password is given, it is used; if not, you are prompted for
  9627.           one. If no username is given, an anonymous login is performed.
  9628.           If a pathname is included, Kermit tries to GET the given file.
  9629.           See [585]Section 3.1.3 for details.
  9630.  
  9631.    ftps://[user[:password]@]hostname[/path...]
  9632.           Makes a secure FTP connection over SSL.
  9633.  
  9634.    telnets://[user[:password]@]hostname
  9635.           Makes a secure Telnet connection over SSL.
  9636.  
  9637.    kermit://[user[:password]@]hostname[/path...]
  9638.           Makes a connection to an [586]Internet Kermit Server.
  9639.  
  9640.    http://[user[:password]@]hostname[/path...]
  9641.           Makes a connection to Web server.
  9642.  
  9643.    https://[user[:password]@]hostname[/path...]
  9644.           Makes a connection to secure Web server.
  9645.  
  9646.    [ [587]Top ] [ [588]Contents ] [ [589]C-Kermit Home ] [ [590]Kermit
  9647.    Home ]
  9648.  
  9649. 17. LOGS
  9650.  
  9651.    In C-Kermit 8.0, we make an effort to keep passwords out of the debug
  9652.    log. This can never be 100% effective, but it's better than before,
  9653.    when there were no precautions at all. Whenever Kermit knows it's
  9654.    prompting for, parsing, or transmitting a password, it temporarily
  9655.    turns off logging and then turns it back on afterwards. This keeps the
  9656.    debug log password-free in most common cases, but there can be no
  9657.    guarantees.
  9658.  
  9659.    As noted elsewhere, the new "-dd" command-line option selects a
  9660.    timestamped debug log (equivalent to "set debug timestamps on", "log
  9661.    debug debug.log").
  9662.  
  9663.    C-Kermit 8.0 also supports a new timestamped session log via "set
  9664.    session-log timestamped-text", "log session".
  9665.  
  9666.    There have been requests for other kinds of logs, for example a command
  9667.    log. These might be added at some point. One person wanted to be able
  9668.    to log commands with timestamps, but only commands issued at the
  9669.    prompt, not commands from files or macros, and also wanted a header
  9670.    line at the beginning showing the date, user, and host. This can be
  9671.    done as follows:
  9672.  
  9673.   .filename := \v(home)commands.log  ; (for example)
  9674.   fopen /write \%c \m(filename)
  9675.   if success {
  9676.       fwrite /line \%c \v(date): User=\v(user) Host=\v(host)
  9677.       fclose \%c
  9678.       set debug timestamps on
  9679.       log debug {| grep "CMD(P)" >> \m(filename)} append
  9680.   }
  9681.  
  9682.    [ [591]Top ] [ [592]Contents ] [ [593]C-Kermit Home ] [ [594]Kermit
  9683.    Home ]
  9684.      __________________________________________________________________
  9685.  
  9686.  
  9687.     C-Kermit 8.0 Update Notes / [595]The Kermit Project / Columbia
  9688.     University / 15 Dec 2003 - 13 Sep 2010
  9689.  
  9690. References
  9691.  
  9692.    1. http://www.columbia.edu/
  9693.    2. mailto:kermit@columbia.edu
  9694.    3. http://www.columbia.edu/kermit/index.html
  9695.    4. http://www.columbia.edu/kermit/k95.html
  9696.    5. http://www.columbia.edu/kermit/ckermit.html
  9697.    6. http://www.columbia.edu/kermit/ckscripts.html
  9698.    7. http://www.columbia.edu/kermit/current.html
  9699.    8. http://www.columbia.edu/kermit/whatsnew.html
  9700.    9. http://www.columbia.edu/kermit/faq.html
  9701.   10. http://www.columbia.edu/kermit/support.html
  9702.   11. http://www.columbia.edu/kermit/ckermit80.html#contents
  9703.   12. http://www.columbia.edu/kermit/ckermit.html
  9704.   13. http://www.columbia.edu/kermit/index.html
  9705.   14. http://www.amazon.com/gp/product/1555581641?ie=UTF8&tag=aleidmoreldom-20&linkCode=as2&camp=1789&creative=9325&creativeASIN=1555581641
  9706.   15. http://www.columbia.edu/kermit/ckermit80.html
  9707.   16. mailto:kermit-support@columbia.edu
  9708.   17. http://www.columbia.edu/kermit/
  9709.   18. http://www.kermit-project.org/
  9710.   19. http://www.columbia.nyc.ny.us/kermit/
  9711.   20. ftp://kermit.columbia.edu/kermit/f/COPYING.TXT
  9712.   21. ftp://kermit.columbia.edu/kermit/f/ckcmai.c
  9713.   22. http://www.columbia.edu/kermit/ckermit80.html#xv
  9714.   23. http://www.columbia.edu/kermit/ck60manual.html
  9715.   24. http://www.columbia.edu/kermit/ckermi70.html
  9716.   25. ftp://kermit.columbia.edu/kermit/f/ckermit70.txt
  9717.   26. http://www.columbia.edu/kermit/ckututor.html
  9718.   27. ftp://kermit.columbia.edu/kermit/f/ckuker.nr
  9719.   28. http://www.columbia.edu/kermit/security.htm
  9720.   29. http://www.columbia.edu/kermit/telnet.htm
  9721.   30. http://www.columbia.edu/kermit/ftpscripts.html
  9722.   31. http://www.columbia.edu/kermit/ckcbwr.html
  9723.   32. ftp://kermit.columbia.edu/kermit/f/ckcbwr.txt
  9724.   33. http://www.columbia.edu/kermit/ckubwr.html
  9725.   34. ftp://kermit.columbia.edu/kermit/f/ckubwr.txt
  9726.   35. http://www.columbia.edu/kermit/ckvbwr.html
  9727.   36. ftp://kermit.columbia.edu/kermit/f/ckvbwr.txt
  9728.   37. http://www.columbia.edu/kermit/ckuins.html
  9729.   38. ftp://kermit.columbia.edu/kermit/f/ckuins.txt
  9730.   39. http://www.columbia.edu/kermit/ckvins.html
  9731.   40. ftp://kermit.columbia.edu/kermit/f/ckvins.txt
  9732.   41. http://www.columbia.edu/kermit/ckccfg.html
  9733.   42. ftp://kermit.columbia.edu/kermit/f/ckccfg.txt
  9734.   43. http://www.columbia.edu/kermit/ckcplm.html
  9735.   44. ftp://kermit.columbia.edu/kermit/f/ckcplm.txt
  9736.   45. http://www.columbia.edu/kermit/iksd.html
  9737.   46. http://www.columbia.edu/kermit/skermit.html
  9738.   47. http://www.columbia.edu/kermit/ckermit80.html#top
  9739.   48. http://www.columbia.edu/kermit/ckermit.html
  9740.   49. http://www.columbia.edu/kermit/index.html
  9741.   50. http://www.columbia.edu/kermit/ckermit80.html#x0
  9742.   51. http://www.columbia.edu/kermit/ckermit80.html#x1
  9743.   52. http://www.columbia.edu/kermit/ckermit80.html#x2
  9744.   53. http://www.columbia.edu/kermit/ckermit80.html#x2.1
  9745.   54. http://www.columbia.edu/kermit/ckermit80.html#x2.2
  9746.   55. http://www.columbia.edu/kermit/ckermit80.html#x2.2.1
  9747.   56. http://www.columbia.edu/kermit/ckermit80.html#x2.2.2
  9748.   57. http://www.columbia.edu/kermit/ckermit80.html#x2.2.3
  9749.   58. http://www.columbia.edu/kermit/ckermit80.html#x2.2.4
  9750.   59. http://www.columbia.edu/kermit/ckermit80.html#x2.2.5
  9751.   60. http://www.columbia.edu/kermit/ckermit80.html#x2.2.6
  9752.   61. http://www.columbia.edu/kermit/ckermit80.html#x3
  9753.   62. http://www.columbia.edu/kermit/ckermit80.html#x3.1
  9754.   63. http://www.columbia.edu/kermit/ckermit80.html#x3.1.1
  9755.   64. http://www.columbia.edu/kermit/ckermit80.html#x3.1.2
  9756.   65. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
  9757.   66. http://www.columbia.edu/kermit/ckermit80.html#x3.1.4
  9758.   67. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  9759.   68. http://www.columbia.edu/kermit/ckermit80.html#x3.3
  9760.   69. http://www.columbia.edu/kermit/ckermit80.html#x3.4
  9761.   70. http://www.columbia.edu/kermit/ckermit80.html#x3.5
  9762.   71. http://www.columbia.edu/kermit/ckermit80.html#x3.5.1
  9763.   72. http://www.columbia.edu/kermit/ckermit80.html#x3.5.2
  9764.   73. http://www.columbia.edu/kermit/ckermit80.html#x3.5.3
  9765.   74. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9766.   75. http://www.columbia.edu/kermit/ckermit80.html#x3.6.1
  9767.   76. http://www.columbia.edu/kermit/ckermit80.html#x3.6.2
  9768.   77. http://www.columbia.edu/kermit/ckermit80.html#x3.6.3
  9769.   78. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9770.   79. http://www.columbia.edu/kermit/ckermit80.html#x3.7.1
  9771.   80. http://www.columbia.edu/kermit/ckermit80.html#x3.7.2
  9772.   81. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  9773.   82. http://www.columbia.edu/kermit/ckermit80.html#x3.9
  9774.   83. http://www.columbia.edu/kermit/ckermit80.html#x3.10
  9775.   84. http://www.columbia.edu/kermit/ckermit80.html#x3.10.1
  9776.   85. http://www.columbia.edu/kermit/ckermit80.html#x3.10.2
  9777.   86. http://www.columbia.edu/kermit/ckermit80.html#x3.10.3
  9778.   87. http://www.columbia.edu/kermit/ckermit80.html#x3.11
  9779.   88. http://www.columbia.edu/kermit/ckermit80.html#x4
  9780.   89. http://www.columbia.edu/kermit/ckermit80.html#x5
  9781.   90. http://www.columbia.edu/kermit/ckermit80.html#x6
  9782.   91. http://www.columbia.edu/kermit/ckermit80.html#x6.1
  9783.   92. http://www.columbia.edu/kermit/ckermit80.html#x6.2
  9784.   93. http://www.columbia.edu/kermit/ckermit80.html#x6.3
  9785.   94. http://www.columbia.edu/kermit/ckermit80.html#x6.4
  9786.   95. http://www.columbia.edu/kermit/ckermit80.html#x6.5
  9787.   96. http://www.columbia.edu/kermit/ckermit80.html#x6.6
  9788.   97. http://www.columbia.edu/kermit/ckermit80.html#x7
  9789.   98. http://www.columbia.edu/kermit/ckermit80.html#x8
  9790.   99. http://www.columbia.edu/kermit/ckermit80.html#x8.1
  9791.  100. http://www.columbia.edu/kermit/ckermit80.html#x8.2
  9792.  101. http://www.columbia.edu/kermit/ckermit80.html#x8.3
  9793.  102. http://www.columbia.edu/kermit/ckermit80.html#x8.4
  9794.  103. http://www.columbia.edu/kermit/ckermit80.html#x8.5
  9795.  104. http://www.columbia.edu/kermit/ckermit80.html#x8.6
  9796.  105. http://www.columbia.edu/kermit/ckermit80.html#x8.7
  9797.  106. http://www.columbia.edu/kermit/ckermit80.html#x8.8
  9798.  107. http://www.columbia.edu/kermit/ckermit80.html#x8.9
  9799.  108. http://www.columbia.edu/kermit/ckermit80.html#x8.10
  9800.  109. http://www.columbia.edu/kermit/ckermit80.html#x8.11
  9801.  110. http://www.columbia.edu/kermit/ckermit80.html#x8.12
  9802.  111. http://www.columbia.edu/kermit/ckermit80.html#x8.13
  9803.  112. http://www.columbia.edu/kermit/ckermit80.html#x8.14
  9804.  113. http://www.columbia.edu/kermit/ckermit80.html#x9
  9805.  114. http://www.columbia.edu/kermit/ckermit80.html#x9.1
  9806.  115. http://www.columbia.edu/kermit/ckermit80.html#x9.2
  9807.  116. http://www.columbia.edu/kermit/ckermit80.html#x9.3
  9808.  117. http://www.columbia.edu/kermit/ckermit80.html#x9.4
  9809.  118. http://www.columbia.edu/kermit/ckermit80.html#x9.5
  9810.  119. http://www.columbia.edu/kermit/ckermit80.html#x9.6
  9811.  120. http://www.columbia.edu/kermit/ckermit80.html#x9.7
  9812.  121. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  9813.  122. http://www.columbia.edu/kermit/ckermit80.html#x9.9
  9814.  123. http://www.columbia.edu/kermit/ckermit80.html#x9.10
  9815.  124. http://www.columbia.edu/kermit/ckermit80.html#x9.11
  9816.  125. http://www.columbia.edu/kermit/ckermit80.html#x10
  9817.  126. http://www.columbia.edu/kermit/ckermit80.html#x11
  9818.  127. http://www.columbia.edu/kermit/ckermit80.html#x12
  9819.  128. http://www.columbia.edu/kermit/ckermit80.html#x13
  9820.  129. http://www.columbia.edu/kermit/ckermit80.html#x14
  9821.  130. http://www.columbia.edu/kermit/ckermit80.html#x15
  9822.  131. http://www.columbia.edu/kermit/ckermit80.html#x16
  9823.  132. http://www.columbia.edu/kermit/ckermit80.html#x17
  9824.  133. http://www.columbia.edu/kermit/ckermit80.html#top
  9825.  134. http://www.columbia.edu/kermit/ckermit.html
  9826.  135. http://www.columbia.edu/kermit/index.html
  9827.  136. http://www.columbia.edu/kermit/ckuins.html#x5
  9828.  137. http://www.columbia.edu/kermit/ckuins.html
  9829.  138. http://www.columbia.edu/kermit/ckermit80.html#x5
  9830.  139. http://www.columbia.edu/kermit/ckermit80.html#x2.2
  9831.  140. http://www.columbia.edu/kermit/ckermit80.html#contents
  9832.  141. http://www.columbia.edu/kermit/ckermit80.html#x15
  9833.  142. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9834.  143. http://www.columbia.edu/kermit/ckermit80.html#ftpdates
  9835.  144. http://www.columbia.edu/kermit/ckermit80.html#ftpcheck
  9836.  145. http://www.columbia.edu/kermit/ckermit80.html#ftpnamelist
  9837.  146. http://www.columbia.edu/kermit/ckermit80.html#srvrename
  9838.  147. http://www.columbia.edu/kermit/ckermit80.html#ftpvdir
  9839.  148. http://www.columbia.edu/kermit/ckermit80.html#setftptype
  9840.  149. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9841.  150. http://www.columbia.edu/kermit/ckermit80.html#x15
  9842.  151. http://www.columbia.edu/kermit/ckermit80.html#x8.7
  9843.  152. http://www.columbia.edu/kermit/ckermit80.html#x2.1
  9844.  153. http://www.columbia.edu/kermit/ckermit80.html#x2.2
  9845.  154. http://www.columbia.edu/kermit/ckermit80.html#x8.14
  9846.  155. http://www.columbia.edu/kermit/ckermit80.html#x8.13
  9847.  156. http://www.columbia.edu/kermit/ckermit80.html#x8.13
  9848.  157. http://www.columbia.edu/kermit/ckututor.html
  9849.  158. http://www.columbia.edu/kermit/ckuins.html
  9850.  159. http://www.columbia.edu/kermit/skermit.html
  9851.  160. http://www.columbia.edu/kermit/ckermit80.html#setlocus
  9852.  161. http://www.columbia.edu/kermit/ckermit80.html#lcommands
  9853.  162. http://www.columbia.edu/kermit/ckermit80.html#ftpuser
  9854.  163. http://www.columbia.edu/kermit/ckermit80.html#showvar
  9855.  164. http://www.columbia.edu/kermit/ckermit80.html#callerid
  9856.  165. http://www.columbia.edu/kermit/ckermit80.html#x6.6
  9857.  166. http://www.columbia.edu/kermit/ckermit80.html#x0
  9858.  167. http://www.columbia.edu/kermit/ckermit80.html#x3.11
  9859.  168. http://www.columbia.edu/kermit/ckermit80.html#top
  9860.  169. http://www.columbia.edu/kermit/ckermit80.html#contents
  9861.  170. http://www.columbia.edu/kermit/ckermit.html
  9862.  171. http://www.columbia.edu/kermit/index.html
  9863.  172. http://www.columbia.edu/kermit/ckermit80.html#x0
  9864.  173. http://www.columbia.edu/kermit/ckermit80.html#top
  9865.  174. http://www.columbia.edu/kermit/ckermit80.html#contents
  9866.  175. http://www.columbia.edu/kermit/ckermit.html
  9867.  176. http://www.columbia.edu/kermit/index.html
  9868.  177. http://www.columbia.edu/kermit/k95.html
  9869.  178. http://www.columbia.edu/kermit/sshclient.html
  9870.  179. http://www.columbia.edu/kermit/skermit.html
  9871.  180. http://www.columbia.edu/kermit/skermit.html
  9872.  181. http://www.columbia.edu/kermit/sshclien.htm
  9873.  182. http://www.columbia.edu/kermit/ckermit80.html#x3
  9874.  183. ftp://ftp.isi.edu/in-notes/rfc1738.txt
  9875.  184. http://www.columbia.edu/kermit/ckermit80.html#x2.2.2
  9876.  185. http://www.columbia.edu/kermit/ckermit80.html#x2.2.1
  9877.  186. ftp://ftp.isi.edu/in-notes/rfc2396.txt
  9878.  187. ftp://ftp.isi.edu/in-notes/rfc2616.txt
  9879.  188. http://www.columbia.edu/kermit/ckermit80.html#x2.2.3
  9880.  189. ftp://ftp.isi.edu/in-notes/rfc2616.txt
  9881.  190. http://www.columbia.edu/kermit/ckermit80.html#x8.13.7
  9882.  191. http://www.columbia.edu/kermit/security.htm#x5.4
  9883.  192. http://www.columbia.edu/kermit/security.htm#x15
  9884.  193. http://www.columbia.edu/kermit/security.htm#x6.2
  9885.  194. http://www.columbia.edu/kermit/security.html
  9886.  195. http://www.columbia.edu/kermit/ckermit80.html#x16
  9887.  196. http://www.columbia.edu/kermit/ckermit80.html#top
  9888.  197. http://www.columbia.edu/kermit/ckermit80.html#contents
  9889.  198. http://www.columbia.edu/kermit/ckermit.html
  9890.  199. http://www.columbia.edu/kermit/index.html
  9891.  200. http://www.columbia.edu/kermit/ckermit80.html#x3.1
  9892.  201. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  9893.  202. http://www.columbia.edu/kermit/ckermit80.html#x3.3
  9894.  203. http://www.columbia.edu/kermit/ckermit80.html#x3.4
  9895.  204. http://www.columbia.edu/kermit/ckermit80.html#x3.5
  9896.  205. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9897.  206. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9898.  207. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  9899.  208. http://www.columbia.edu/kermit/ckermit80.html#x3.9
  9900.  209. http://www.columbia.edu/kermit/ckermit80.html#x3.10
  9901.  210. http://www.columbia.edu/kermit/ckermit80.html#x3.11
  9902.  211. http://www.columbia.edu/kermit/security.htm
  9903.  212. http://www.columbia.edu/kermit/security.htm#servers
  9904.  213. http://www.columbia.edu/kermit/ckcsets.html
  9905.  214. http://www.columbia.edu/kermit/unicode.html
  9906.  215. http://www.columbia.edu/kermit/ckermi70.htm#x1.5.4
  9907.  216. http://www.columbia.edu/kermit/case10.html
  9908.  217. http://www.columbia.edu/kermit/ckermit80.html#x4
  9909.  218. http://www.columbia.edu/kermit/ckermit80.html#x3.11
  9910.  219. http://www.columbia.edu/kermit/ftpscripts.html
  9911.  220. http://www.columbia.edu/kermit/ckermit80.html#top
  9912.  221. http://www.columbia.edu/kermit/ckermit80.html#ftp
  9913.  222. http://www.columbia.edu/kermit/ftpclient.html
  9914.  223. http://www.columbia.edu/kermit/ftpscripts.html
  9915.  224. http://www.columbia.edu/kermit/ckermit.html
  9916.  225. http://www.columbia.edu/kermit/index.html
  9917.  226. http://www.columbia.edu/kermit/ckermit80.html#x3.1.1
  9918.  227. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
  9919.  228. http://www.columbia.edu/kermit/ckermit80.html#x3.1.4
  9920.  229. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
  9921.  230. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
  9922.  231. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  9923.  232. http://www.columbia.edu/kermit/ckermit80.html#x3.5
  9924.  233. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9925.  234. http://www.columbia.edu/kermit/ftpscripts.html
  9926.  235. http://www.columbia.edu/kermit/ckb2.htm
  9927.  236. http://www.columbia.edu/kermit/ckermit80.html#ftpautolog
  9928.  237. http://www.columbia.edu/kermit/ckermit80.html#ftpuser
  9929.  238. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  9930.  239. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  9931.  240. http://www.columbia.edu/kermit/ckermit80.html#top
  9932.  241. http://www.columbia.edu/kermit/ckermit80.html#ftp
  9933.  242. http://www.columbia.edu/kermit/ckermit.html
  9934.  243. http://www.columbia.edu/kermit/index.html
  9935.  244. http://www.columbia.edu/kermit/ibm_ie.html
  9936.  245. http://www.columbia.edu/kermit/ckermit80.html#x3.10
  9937.  246. http://www.columbia.edu/kermit/ckermit80.html#top
  9938.  247. http://www.columbia.edu/kermit/ckermit80.html#ftp
  9939.  248. http://www.columbia.edu/kermit/ckermit.html
  9940.  249. http://www.columbia.edu/kermit/index.html
  9941.  250. http://www.columbia.edu/kermit/ck60manual.html
  9942.  251. http://www.columbia.edu/kermit/ckermit70.html#x4.17
  9943.  252. http://www.columbia.edu/kermit/ckermit70.html
  9944.  253. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9945.  254. http://www.columbia.edu/kermit/ckermit80.html#x3.11
  9946.  255. http://www.columbia.edu/kermit/ckermit80.html#x3.1.4
  9947.  256. http://www.columbia.edu/kermit/security.html
  9948.  257. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9949.  258. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9950.  259. http://www.columbia.edu/kermit/ckermit80.html#x8.13.4
  9951.  260. http://www.columbia.edu/kermit/ckermit80.html#permswitch
  9952.  261. http://www.columbia.edu/kermit/ckermit80.html#ftpchmod
  9953.  262. http://www.columbia.edu/kermit/ckermit80.html#x3.6.2
  9954.  263. http://www.columbia.edu/kermit/ckermit80.html#x4
  9955.  264. http://www.columbia.edu/kermit/ckermit80.html#top
  9956.  265. http://www.columbia.edu/kermit/ckermit80.html#ftp
  9957.  266. http://www.columbia.edu/kermit/ckermit.html
  9958.  267. http://www.columbia.edu/kermit/index.html
  9959.  268. http://www.columbia.edu/kermit/ckermit80.html#x7
  9960.  269. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  9961.  270. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  9962.  271. http://www.columbia.edu/kermit/ckb2.htm
  9963.  272. http://www.columbia.edu/kermit/ckermit80.html#x3.10
  9964.  273. http://www.columbia.edu/kermit/ckermit80.html#x3.10
  9965.  274. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9966.  275. http://www.columbia.edu/kermit/ckermit80.html#setftptype
  9967.  276. http://www.columbia.edu/kermit/ckermit80.html#top
  9968.  277. http://www.columbia.edu/kermit/ckermit80.html#ftp
  9969.  278. http://www.columbia.edu/kermit/ckermit.html
  9970.  279. http://www.columbia.edu/kermit/index.html
  9971.  280. http://www.columbia.edu/kermit/ckermit70.html#x4.9
  9972.  281. http://www.columbia.edu/kermit/ckermit80.html#x3.5.1
  9973.  282. http://www.columbia.edu/kermit/ckermit80.html#erroraction
  9974.  283. http://www.columbia.edu/kermit/ckermit70.html#x1.5
  9975.  284. http://www.columbia.edu/kermit/ckermit70.html#x4.7
  9976.  285. http://www.columbia.edu/kermit/ckermit70.html#x1.6
  9977.  286. http://www.columbia.edu/kermit/ckermit80.html#x8.13
  9978.  287. http://www.columbia.edu/kermit/ckermi70.htm#x1.5.4
  9979.  288. http://www.columbia.edu/kermit/ckermi70.htm
  9980.  289. http://www.columbia.edu/kermit/ckermit80.html#x4
  9981.  290. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9982.  291. http://www.columbia.edu/kermit/ckermit80.html#x3.5.2
  9983.  292. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9984.  293. http://www.columbia.edu/kermit/ckermit80.html#erroraction
  9985.  294. http://www.columbia.edu/kermit/ckermit80.html#x3.5.2
  9986.  295. http://www.columbia.edu/kermit/ckermit80.html#erroraction
  9987.  296. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames
  9988.  297. http://www.columbia.edu/kermit/ckermit80.html#ftpperms
  9989.  298. http://www.columbia.edu/kermit/ckermit80.html#ftpunique
  9990.  299. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames
  9991.  300. http://www.columbia.edu/kermit/ckermit80.html#note_utc
  9992.  301. http://www.columbia.edu/kermit/ckermit80.html#note_date
  9993.  302. http://www.columbia.edu/kermit/ckermit80.html#x3.6
  9994.  303. http://www.boulder.nist.gov/timefreq/faq/faq.htm#10:
  9995.  304. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  9996.  305. http://www.columbia.edu/kermit/ckermit80.html#top
  9997.  306. http://www.columbia.edu/kermit/ckermit80.html#ftp
  9998.  307. http://www.columbia.edu/kermit/ckermit.html
  9999.  308. http://www.columbia.edu/kermit/index.html
  10000.  309. http://www.columbia.edu/kermit/ckermit80.html#x3.11
  10001.  310. http://www.columbia.edu/kermit/ckermi70.htm#x4.3
  10002.  311. http://www.columbia.edu/kermit/ckermit70.html
  10003.  312. http://www.columbia.edu/kermit/ckermit80.html#x5
  10004.  313. http://www.columbia.edu/kermit/ckermit80.html#x3.6.3
  10005.  314. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames
  10006.  315. http://www.columbia.edu/kermit/ckermi70.htm#x4.1
  10007.  316. http://www.columbia.edu/kermit/ckermi70.htm#x4.2.2
  10008.  317. http://www.columbia.edu/kermit/ckermi70.htm#x1.5.4
  10009.  318. http://www.columbia.edu/kermit/ckermit80.html#x3.6.2
  10010.  319. http://www.columbia.edu/kermit/ckermit80.html#x3.11
  10011.  320. http://www.columbia.edu/kermit/ckermit80.html#x3.11
  10012.  321. http://www.columbia.edu/kermit/ckermit80.html#srvrename
  10013.  322. http://www.columbia.edu/kermit/ckermi70.htm#x4.1
  10014.  323. http://www.columbia.edu/kermit/ckermi70.htm
  10015.  324. http://www.columbia.edu/kermit/ckb2.htm
  10016.  325. http://www.columbia.edu/kermit/ckermit80.html#ftpfilenames
  10017.  326. http://www.columbia.edu/kermit/ckermit80.html#x3.5.3
  10018.  327. http://www.proftpd.net/
  10019.  328. http://www.columbia.edu/kermit/ckermit80.html#top
  10020.  329. http://www.columbia.edu/kermit/ckermit80.html#ftp
  10021.  330. http://www.columbia.edu/kermit/ckermit.html
  10022.  331. http://www.columbia.edu/kermit/index.html
  10023.  332. http://www.columbia.edu/kermit/ckb2.htm
  10024.  333. http://www.columbia.edu/kermit/ckcsets.html
  10025.  334. http://www.columbia.edu/kermit/unicode.html
  10026.  335. http://www.columbia.edu/kermit/ckcsets.html
  10027.  336. http://www.columbia.edu/kermit/ckcsets.html
  10028.  337. http://www.columbia.edu/kermit/ckermit80.html#x4
  10029.  338. http://www.columbia.edu/kermit/utf8.html
  10030.  339. http://www.columbia.edu/kermit/ckcsets.html
  10031.  340. http://www.columbia.edu/kermit/ckermit80.html#x4
  10032.  341. ftp://ftp.isi.edu/in-notes/rfc2640.txt
  10033.  342. http://www.columbia.edu/kermit/ckermit80.html#top
  10034.  343. http://www.columbia.edu/kermit/ckermit80.html#ftp
  10035.  344. http://www.columbia.edu/kermit/ckermit.html
  10036.  345. http://www.columbia.edu/kermit/index.html
  10037.  346. http://www.columbia.edu/kermit/ckermit80.html#top
  10038.  347. http://www.columbia.edu/kermit/ckermit80.html#ftp
  10039.  348. http://www.columbia.edu/kermit/ckermit.html
  10040.  349. http://www.columbia.edu/kermit/index.html
  10041.  350. http://www.columbia.edu/kermit/ckermit80.html#top
  10042.  351. http://www.columbia.edu/kermit/ckermit80.html#ftp
  10043.  352. http://www.columbia.edu/kermit/ckermit.html
  10044.  353. http://www.columbia.edu/kermit/index.html
  10045.  354. http://www.columbia.edu/kermit/ftpscripts.html
  10046.  355. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  10047.  356. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  10048.  357. ftp://ftp.isi.edu/in-notes/rfc959.txt
  10049.  358. http://www.columbia.edu/kermit/ckscripts.html
  10050.  359. http://www.columbia.edu/kermit/ckermit80.html#top
  10051.  360. http://www.columbia.edu/kermit/ckermit80.html#ftp
  10052.  361. http://www.columbia.edu/kermit/ftpscript.html
  10053.  362. http://www.columbia.edu/kermit/ckermit.html
  10054.  363. http://www.columbia.edu/kermit/index.html
  10055.  364. http://www.columbia.edu/kermit/ckermit80.html#x3.11.1
  10056.  365. http://www.columbia.edu/kermit/ckermit80.html#x3.11.2
  10057.  366. http://www.columbia.edu/kermit/ckermit80.html#x3.11.3
  10058.  367. http://www.columbia.edu/kermit/ckermit80.html#x3.11.4
  10059.  368. http://www.columbia.edu/kermit/ckermit80.html#x3.11.5
  10060.  369. http://www.columbia.edu/kermit/ckermit.html
  10061.  370. http://www.columbia.edu/kermit/k95.html
  10062.  371. http://www.columbia.edu/kermit/ckermit80.html#x3.11.5
  10063.  372. ftp://ftp.isi.edu/in-notes/rfc959.txt
  10064.  373. ftp://ftp.isi.edu/in-notes/rfc2389.txt
  10065.  374. http://www.ietf.org/internet-drafts/draft-ietf-ftpext-mlst-16.txt
  10066.  375. http://www.columbia.edu/kermit/ftpclient.html
  10067.  376. http://www.columbia.edu/kermit/ckermit80.html#top
  10068.  377. http://www.columbia.edu/kermit/ckermit80.html#ftp
  10069.  378. http://www.columbia.edu/kermit/ckermit.html
  10070.  379. http://www.columbia.edu/kermit/index.html
  10071.  380. http://www.columbia.edu/kermit/ckermit80.html#x3
  10072.  381. http://www.columbia.edu/kermit/ckermit80.html#ucs2
  10073.  382. http://www.columbia.edu/kermit/ckermit80.html#top
  10074.  383. http://www.columbia.edu/kermit/ckermit80.html#contents
  10075.  384. http://www.columbia.edu/kermit/ckermit.html
  10076.  385. http://www.columbia.edu/kermit/index.html
  10077.  386. http://www.columbia.edu/kermit/ckermit80.html#top
  10078.  387. http://www.columbia.edu/kermit/ckermit80.html#contents
  10079.  388. http://www.columbia.edu/kermit/ckermit.html
  10080.  389. http://www.columbia.edu/kermit/index.html
  10081.  390. http://www.columbia.edu/kermit/ckb2.htm
  10082.  391. http://www.columbia.edu/kermit/ckermit80.html#top
  10083.  392. http://www.columbia.edu/kermit/ckermit80.html#contents
  10084.  393. http://www.columbia.edu/kermit/ckermit.html
  10085.  394. http://www.columbia.edu/kermit/index.html
  10086.  395. http://www.columbia.edu/kermit/ckermit80.html#x4
  10087.  396. http://www.columbia.edu/kermit/ckermit80.html#x4
  10088.  397. http://www.columbia.edu/kermit/ckermit80.html#x8.12
  10089.  398. http://www.columbia.edu/kermit/ckermit80.html#x8.1
  10090.  399. http://www.columbia.edu/kermit/ckermit80.html#x12
  10091.  400. http://www.columbia.edu/kermit/ckermit80.html#x8.12
  10092.  401. http://www.columbia.edu/kermit/ckermit80.html#top
  10093.  402. http://www.columbia.edu/kermit/ckermit80.html#contents
  10094.  403. http://www.columbia.edu/kermit/ckermit.html
  10095.  404. http://www.columbia.edu/kermit/index.html
  10096.  405. http://www.columbia.edu/kermit/ckermit80.html#x8.14
  10097.  406. http://www.columbia.edu/kermit/ckermit80.html#top
  10098.  407. http://www.columbia.edu/kermit/ckermit80.html#contents
  10099.  408. http://www.columbia.edu/kermit/ckermit.html
  10100.  409. http://www.columbia.edu/kermit/index.html
  10101.  410. http://www.columbia.edu/kermit/ckermit80.html#x9
  10102.  411. http://www.columbia.edu/kermit/ckermit80.html#top
  10103.  412. http://www.columbia.edu/kermit/ckermit80.html#contents
  10104.  413. http://www.columbia.edu/kermit/ckermit.html
  10105.  414. http://www.columbia.edu/kermit/index.html
  10106.  415. http://www.columbia.edu/kermit/ckermit80.html#x8.6
  10107.  416. http://www.columbia.edu/kermit/ckermit80.html#top
  10108.  417. http://www.columbia.edu/kermit/ckermit80.html#contents
  10109.  418. http://www.columbia.edu/kermit/ckermit.html
  10110.  419. http://www.columbia.edu/kermit/index.html
  10111.  420. http://www.columbia.edu/kermit/ckermit80.html#top
  10112.  421. http://www.columbia.edu/kermit/ckermit80.html#contents
  10113.  422. http://www.columbia.edu/kermit/ckermit.html
  10114.  423. http://www.columbia.edu/kermit/index.html
  10115.  424. http://www.columbia.edu/kermit/ckermit80.html#top
  10116.  425. http://www.columbia.edu/kermit/ckermit80.html#contents
  10117.  426. http://www.columbia.edu/kermit/ckermit.html
  10118.  427. http://www.columbia.edu/kermit/index.html
  10119.  428. http://www.columbia.edu/kermit/ckermit80.html#fjoin
  10120.  429. http://www.columbia.edu/kermit/ckermit80.html#fsplit
  10121.  430. http://www.columbia.edu/kermit/ckermit80.html#x8.10
  10122.  431. http://www.columbia.edu/kermit/ckermit80.html#top
  10123.  432. http://www.columbia.edu/kermit/ckermit80.html#contents
  10124.  433. http://www.columbia.edu/kermit/ckermit.html
  10125.  434. http://www.columbia.edu/kermit/index.html
  10126.  435. http://www.columbia.edu/kermit/ckermit80.html#x9
  10127.  436. http://www.columbia.edu/kermit/ckermit80.html#x9
  10128.  437. http://www.columbia.edu/kermit/ckermit80.html#x9
  10129.  438. http://www.columbia.edu/kermit/ckermit80.html#x3
  10130.  439. http://www.columbia.edu/kermit/ckermit80.html#x3
  10131.  440. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  10132.  441. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  10133.  442. http://www.columbia.edu/kermit/ckermit80.html#x3.8
  10134.  443. http://www.columbia.edu/kermit/ckermit80.html#x3
  10135.  444. http://www.columbia.edu/kermit/ckermit80.html#x3
  10136.  445. http://www.columbia.edu/kermit/ckermit80.html#x3
  10137.  446. http://www.columbia.edu/kermit/ckermit80.html#x3.2
  10138.  447. http://www.columbia.edu/kermit/ckermit80.html#x3
  10139.  448. http://www.columbia.edu/kermit/ckermit80.html#x8.13
  10140.  449. http://www.columbia.edu/kermit/ckermit80.html#x8.13
  10141.  450. http://www.columbia.edu/kermit/ckermit80.html#x9
  10142.  451. http://www.columbia.edu/kermit/ckermit80.html#x8.10
  10143.  452. http://www.columbia.edu/kermit/ckermit80.html#x8.7.4
  10144.  453. http://www.columbia.edu/kermit/ckermit80.html#top
  10145.  454. http://www.columbia.edu/kermit/ckermit80.html#contents
  10146.  455. http://www.columbia.edu/kermit/ckermit.html
  10147.  456. http://www.columbia.edu/kermit/index.html
  10148.  457. http://www.columbia.edu/kermit/ckermit80.html#top
  10149.  458. http://www.columbia.edu/kermit/ckermit80.html#contents
  10150.  459. http://www.columbia.edu/kermit/ckermit.html
  10151.  460. http://www.columbia.edu/kermit/index.html
  10152.  461. http://www.columbia.edu/kermit/ckermit80.html#top
  10153.  462. http://www.columbia.edu/kermit/ckermit80.html#contents
  10154.  463. http://www.columbia.edu/kermit/ckermit.html
  10155.  464. http://www.columbia.edu/kermit/index.html
  10156.  465. http://www.columbia.edu/kermit/ckermit80.html#x8.7
  10157.  466. http://www.columbia.edu/kermit/ckermit80.html#top
  10158.  467. http://www.columbia.edu/kermit/ckermit80.html#contents
  10159.  468. http://www.columbia.edu/kermit/ckermit.html
  10160.  469. http://www.columbia.edu/kermit/index.html
  10161.  470. http://www.columbia.edu/kermit/ckermit80.html#scriptedit
  10162.  471. http://www.columbia.edu/kermit/ckermit80.html#top
  10163.  472. http://www.columbia.edu/kermit/ckermit80.html#contents
  10164.  473. http://www.columbia.edu/kermit/ckermit.html
  10165.  474. http://www.columbia.edu/kermit/index.html
  10166.  475. http://www.columbia.edu/kermit/ckermit80.html#top
  10167.  476. http://www.columbia.edu/kermit/ckermit80.html#contents
  10168.  477. http://www.columbia.edu/kermit/ckermit.html
  10169.  478. http://www.columbia.edu/kermit/index.html
  10170.  479. ftp://ftp.isi.edu/in-notes/rfc2822.txt
  10171.  480. ftp://ftp.isi.edu/in-notes/rfc2822.txt
  10172.  481. ftp://ftp.isi.edu/in-notes/rfc2822.txt
  10173.  482. ftp://ftp.isi.edu/in-notes/rfc2822.txt
  10174.  483. http://www.columbia.edu/kermit/ckermit80.html#top
  10175.  484. http://www.columbia.edu/kermit/ckermit80.html#contents
  10176.  485. http://www.columbia.edu/kermit/ckermit.html
  10177.  486. http://www.columbia.edu/kermit/index.html
  10178.  487. http://www.columbia.edu/kermit/ckermit80.html#x8.1
  10179.  488. http://www.columbia.edu/kermit/ckermit80.html#top
  10180.  489. http://www.columbia.edu/kermit/ckermit80.html#contents
  10181.  490. http://www.columbia.edu/kermit/ckermit.html
  10182.  491. http://www.columbia.edu/kermit/index.html
  10183.  492. http://www.columbia.edu/kermit/ckermit80.html#x8.2
  10184.  493. http://www.columbia.edu/kermit/ckermit80.html#top
  10185.  494. http://www.columbia.edu/kermit/ckermit80.html#contents
  10186.  495. http://www.columbia.edu/kermit/ckermit.html
  10187.  496. http://www.columbia.edu/kermit/index.html
  10188.  497. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  10189.  498. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  10190.  499. http://www.columbia.edu/kermit/ckermit80.html#x8.2
  10191.  500. http://www.columbia.edu/kermit/ckermit80.html#top
  10192.  501. http://www.columbia.edu/kermit/ckermit80.html#contents
  10193.  502. http://www.columbia.edu/kermit/ckermit.html
  10194.  503. http://www.columbia.edu/kermit/index.html
  10195.  504. http://www.columbia.edu/kermit/ckermit80.html#top
  10196.  505. http://www.columbia.edu/kermit/ckermit80.html#contents
  10197.  506. http://www.columbia.edu/kermit/ckermit.html
  10198.  507. http://www.columbia.edu/kermit/index.html
  10199.  508. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  10200.  509. http://www.columbia.edu/kermit/ckermit80.html#top
  10201.  510. http://www.columbia.edu/kermit/ckermit80.html#contents
  10202.  511. http://www.columbia.edu/kermit/ckermit.html
  10203.  512. http://www.columbia.edu/kermit/index.html
  10204.  513. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  10205.  514. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  10206.  515. http://www.columbia.edu/kermit/ckermit80.html#x9.6
  10207.  516. http://www.columbia.edu/kermit/ckermit80.html#top
  10208.  517. http://www.columbia.edu/kermit/ckermit80.html#contents
  10209.  518. http://www.columbia.edu/kermit/ckermit.html
  10210.  519. http://www.columbia.edu/kermit/index.html
  10211.  520. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  10212.  521. http://www.columbia.edu/kermit/ckermit80.html#x9.8
  10213.  522. http://www.columbia.edu/kermit/ckermit80.html#top
  10214.  523. http://www.columbia.edu/kermit/ckermit80.html#contents
  10215.  524. http://www.columbia.edu/kermit/ckermit.html
  10216.  525. http://www.columbia.edu/kermit/index.html
  10217.  526. http://www.columbia.edu/kermit/ckermit80.html#top
  10218.  527. http://www.columbia.edu/kermit/ckermit80.html#contents
  10219.  528. http://www.columbia.edu/kermit/ckermit.html
  10220.  529. http://www.columbia.edu/kermit/index.html
  10221.  530. http://www.columbia.edu/kermit/ckermit80.html#top
  10222.  531. http://www.columbia.edu/kermit/ckermit80.html#contents
  10223.  532. http://www.columbia.edu/kermit/ckermit.html
  10224.  533. http://www.columbia.edu/kermit/index.html
  10225.  534. mailto:thucdat@hotmail.com
  10226.  535. http://www.columbia.edu/kermit/ckermit80.html#x9.9.2
  10227.  536. http://www.columbia.edu/kermit/ckermit80.html#top
  10228.  537. http://www.columbia.edu/kermit/ckermit80.html#contents
  10229.  538. http://www.columbia.edu/kermit/ckermit.html
  10230.  539. http://www.columbia.edu/kermit/index.html
  10231.  540. http://www.columbia.edu/kermit/ckermit80.html#top
  10232.  541. http://www.columbia.edu/kermit/ckermit80.html#contents
  10233.  542. http://www.columbia.edu/kermit/ckermit.html
  10234.  543. http://www.columbia.edu/kermit/index.html
  10235.  544. http://www.columbia.edu/kermit/ckermit80.html#top
  10236.  545. http://www.columbia.edu/kermit/ckermit80.html#contents
  10237.  546. http://www.columbia.edu/kermit/ckermit.html
  10238.  547. http://www.columbia.edu/kermit/index.html
  10239.  548. http://www.columbia.edu/kermit/ckermit80.html#x9.2
  10240.  549. http://www.columbia.edu/kermit/ckermit80.html#top
  10241.  550. http://www.columbia.edu/kermit/ckermit80.html#contents
  10242.  551. http://www.columbia.edu/kermit/ckermit.html
  10243.  552. http://www.columbia.edu/kermit/index.html
  10244.  553. http://www.columbia.edu/kermit/ckermit80.html#x4
  10245.  554. http://www.columbia.edu/kermit/ckermit80.html#x4
  10246.  555. http://www.columbia.edu/kermit/ckermit80.html#top
  10247.  556. http://www.columbia.edu/kermit/ckermit80.html#contents
  10248.  557. http://www.columbia.edu/kermit/ckermit.html
  10249.  558. http://www.columbia.edu/kermit/index.html
  10250.  559. http://www.columbia.edu/kermit/ckermit80.html#top
  10251.  560. http://www.columbia.edu/kermit/ckermit80.html#contents
  10252.  561. http://www.columbia.edu/kermit/ckermit.html
  10253.  562. http://www.columbia.edu/kermit/index.html
  10254.  563. http://www.columbia.edu/kermit/ckermit80.html#top
  10255.  564. http://www.columbia.edu/kermit/ckermit80.html#contents
  10256.  565. http://www.columbia.edu/kermit/ckermit.html
  10257.  566. http://www.columbia.edu/kermit/index.html
  10258.  567. http://www.columbia.edu/kermit/ckermit80.html#x4
  10259.  568. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  10260.  569. http://www.columbia.edu/kermit/ckermit80.html#x3.7
  10261.  570. http://www.columbia.edu/kermit/ckermit80.html#top
  10262.  571. http://www.columbia.edu/kermit/ckermit80.html#contents
  10263.  572. http://www.columbia.edu/kermit/ckermit.html
  10264.  573. http://www.columbia.edu/kermit/index.html
  10265.  574. ftp://ftp.isi.edu/in-notes/rfc2217.txt
  10266.  575. http://www.columbia.edu/kermit/ckermit80.html#top
  10267.  576. http://www.columbia.edu/kermit/ckermit80.html#contents
  10268.  577. ftp://kermit.columbia.edu/kermit/sredird/
  10269.  578. http://www.columbia.edu/kermit/ckermit.html
  10270.  579. http://www.columbia.edu/kermit/index.html
  10271.  580. http://www.columbia.edu/kermit/ckermi70.htm#x4.22
  10272.  581. http://www.columbia.edu/kermit/ckermit80.html#top
  10273.  582. http://www.columbia.edu/kermit/ckermit80.html#contents
  10274.  583. http://www.columbia.edu/kermit/ckermit.html
  10275.  584. http://www.columbia.edu/kermit/index.html
  10276.  585. http://www.columbia.edu/kermit/ckermit80.html#x3.1.3
  10277.  586. http://www.columbia.edu/kermit/cuiksd.html
  10278.  587. http://www.columbia.edu/kermit/ckermit80.html#top
  10279.  588. http://www.columbia.edu/kermit/ckermit80.html#contents
  10280.  589. http://www.columbia.edu/kermit/ckermit.html
  10281.  590. http://www.columbia.edu/kermit/index.html
  10282.  591. http://www.columbia.edu/kermit/ckermit80.html#top
  10283.  592. http://www.columbia.edu/kermit/ckermit80.html#contents
  10284.  593. http://www.columbia.edu/kermit/ckermit.html
  10285.  594. http://www.columbia.edu/kermit/index.html
  10286.  595. http://www.columbia.edu/kermit/index.html
  10287.